# API documentation for libmpg123, libout123, and libsyn123

Note: This API doc is automatically generated from the current development version that you can get via Subversion or as a daily snapshot from http://mpg123.org/snapshot. There may be differences (additions) compared to the latest stable release. See NEWS.libmpg123, NEWS.libout123, NEWS.libsyn123, and the overall NEWS file on libmpg123 versions and important changes between them.
Let me emphasize that the policy for the lib*123 family is to always stay backwards compatible -- only additions are planned (and it's not yet planned to change the plans;-).
Typedefs | Enumerations | Functions
mpg123 library and handle setup

Functions to initialise and shutdown the mpg123 library and handles. The parameters of handles have workable defaults, you only have to tune them when you want to tune something;-) Tip: Use a RVA setting... More...

## Typedefs
typedef struct mpg123_handle_struct | mpg123_handle

## Enumerations
enum | mpg123_parms { MPG123_VERBOSE = 0, MPG123_FLAGS, MPG123_ADD_FLAGS, MPG123_FORCE_RATE, MPG123_DOWN_SAMPLE, MPG123_RVA, MPG123_DOWNSPEED, MPG123_UPSPEED, MPG123_START_FRAME, MPG123_DECODE_FRAMES, MPG123_ICY_INTERVAL, MPG123_OUTSCALE, MPG123_TIMEOUT, MPG123_REMOVE_FLAGS, MPG123_RESYNC_LIMIT, MPG123_INDEX_SIZE, MPG123_PREFRAMES, MPG123_FEEDPOOL, MPG123_FEEDBUFFER, MPG123_FREEFORMAT_SIZE }
enum | mpg123_param_flags { MPG123_FORCE_MONO = 0x7, MPG123_MONO_LEFT = 0x1, MPG123_MONO_RIGHT = 0x2, MPG123_MONO_MIX = 0x4, MPG123_FORCE_STEREO = 0x8, MPG123_FORCE_8BIT = 0x10, MPG123_QUIET = 0x20, MPG123_GAPLESS = 0x40, MPG123_NO_RESYNC = 0x80, MPG123_SEEKBUFFER = 0x100, MPG123_FUZZY = 0x200, MPG123_FORCE_FLOAT = 0x400, MPG123_PLAIN_ID3TEXT = 0x800, MPG123_IGNORE_STREAMLENGTH = 0x1000, MPG123_SKIP_ID3V2 = 0x2000, MPG123_IGNORE_INFOFRAME = 0x4000, MPG123_AUTO_RESAMPLE = 0x8000, MPG123_PICTURE = 0x10000, MPG123_NO_PEEK_END = 0x20000, MPG123_FORCE_SEEKABLE = 0x40000, MPG123_STORE_RAW_ID3 = 0x80000, MPG123_FORCE_ENDIAN = 0x100000, MPG123_BIG_ENDIAN = 0x200000, MPG123_NO_READAHEAD = 0x400000, MPG123_FLOAT_FALLBACK = 0x800000, MPG123_NO_FRANKENSTEIN = 0x1000000 }
enum | mpg123_param_rva { MPG123_RVA_OFF = 0, MPG123_RVA_MIX = 1, MPG123_RVA_ALBUM = 2, MPG123_RVA_MAX = MPG123_RVA_ALBUM }
enum | mpg123_feature_set { MPG123_FEATURE_ABI_UTF8OPEN = 0, MPG123_FEATURE_OUTPUT_8BIT, MPG123_FEATURE_OUTPUT_16BIT, MPG123_FEATURE_OUTPUT_32BIT, MPG123_FEATURE_INDEX, MPG123_FEATURE_PARSE_ID3V2, MPG123_FEATURE_DECODE_LAYER1, MPG123_FEATURE_DECODE_LAYER2, MPG123_FEATURE_DECODE_LAYER3, MPG123_FEATURE_DECODE_ACCURATE, MPG123_FEATURE_DECODE_DOWNSAMPLE, MPG123_FEATURE_DECODE_NTOM, MPG123_FEATURE_PARSE_ICY, MPG123_FEATURE_TIMEOUT_READ, MPG123_FEATURE_EQUALIZER, MPG123_FEATURE_MOREINFO, MPG123_FEATURE_OUTPUT_FLOAT32, MPG123_FEATURE_OUTPUT_FLOAT64 }

## Functions
const char * | mpg123_distversion (unsigned int *major, unsigned int *minor, unsigned int *patch)
unsigned int | mpg123_libversion (unsigned int *patch)
MPG123_EXPORT int | mpg123_init (void)
MPG123_EXPORT void | mpg123_exit (void)
MPG123_EXPORT mpg123_handle * | mpg123_new (const char *decoder, int *error)
MPG123_EXPORT void | mpg123_delete (mpg123_handle *mh)
MPG123_EXPORT void | mpg123_free (void *ptr)
MPG123_EXPORT int | mpg123_param (mpg123_handle *mh, enum mpg123_parms type, long value, double fvalue)
MPG123_EXPORT int | mpg123_param2 (mpg123_handle *mh, int type, long value, double fvalue)
MPG123_EXPORT int | mpg123_getparam (mpg123_handle *mh, enum mpg123_parms type, long *value, double *fvalue)
MPG123_EXPORT int | mpg123_getparam2 (mpg123_handle *mh, int type, long *value, double *fvalue)
MPG123_EXPORT int | mpg123_feature (const enum mpg123_feature_set key)
MPG123_EXPORT int | mpg123_feature2 (int key)

## Detailed Description

Functions to initialise and shutdown the mpg123 library and handles. The parameters of handles have workable defaults, you only have to tune them when you want to tune something;-) Tip: Use a RVA setting...

## Typedef Documentation

## ◆ mpg123_handle

typedef struct mpg123_handle_struct mpg123_handle

Opaque structure for the libmpg123 decoder handle. Most functions take a pointer to a mpg123_handle as first argument and operate on its data in an object-oriented manner.

Definition at line 222 of file mpg123.h.

## Enumeration Type Documentation

## ◆ mpg123_parms

enum mpg123_parms

Enumeration of the parameters types that it is possible to set/get.

Enumerator
MPG123_VERBOSE | set verbosity value for enabling messages to stderr, >= 0 makes sense (integer)
MPG123_FLAGS | set all flags, p.ex val = MPG123_GAPLESS|MPG123_MONO_MIX (integer)
MPG123_ADD_FLAGS | add some flags (integer)
MPG123_FORCE_RATE | when value > 0, force output rate to that value (integer)
MPG123_DOWN_SAMPLE | 0=native rate, 1=half rate, 2=quarter rate (integer)
MPG123_RVA | one of the RVA choices above (integer)
MPG123_DOWNSPEED | play a frame N times (integer)
MPG123_UPSPEED | play every Nth frame (integer)
MPG123_START_FRAME | start with this frame (skip frames before that, integer)
MPG123_DECODE_FRAMES | decode only this number of frames (integer)
MPG123_ICY_INTERVAL | Stream contains ICY metadata with this interval (integer). Make sure to set this before opening a stream.
MPG123_OUTSCALE | the scale for output samples (amplitude - integer or float according to mpg123 output format, normally integer)
MPG123_TIMEOUT | timeout for reading from a stream (not supported on win32, integer)
MPG123_REMOVE_FLAGS | remove some flags (inverse of MPG123_ADD_FLAGS, integer)
MPG123_RESYNC_LIMIT | Try resync on frame parsing for that many bytes or until end of stream (<0 ... integer). This can enlarge the limit for skipping junk on beginning, too (but not reduce it).
MPG123_INDEX_SIZE | Set the frame index size (if supported). Values <0 mean that the index is allowed to grow dynamically in these steps (in positive direction, of course) – Use this when you really want a full index with every individual frame.
MPG123_PREFRAMES | Decode/ignore that many frames in advance for layer 3. This is needed to fill bit reservoir after seeking, for example (but also at least one frame in advance is needed to have all "normal" data for layer 3). Give a positive integer value, please.
MPG123_FEEDPOOL | For feeder mode, keep that many buffers in a pool to avoid frequent malloc/free. The pool is allocated on mpg123_open_feed(). If you change this parameter afterwards, you can trigger growth and shrinkage during decoding. The default value could change any time. If you care about this, then set it. (integer)
MPG123_FEEDBUFFER | Minimal size of one internal feeder buffer, again, the default value is subject to change. (integer)
MPG123_FREEFORMAT_SIZE | Tell the parser a free-format frame size to avoid read-ahead to get it. A value of -1 (default) means that the parser will determine it. The parameter value is applied during decoder setup for a freshly opened stream only.

Definition at line 284 of file mpg123.h.

## ◆ mpg123_param_flags

enum mpg123_param_flags

Flag bits for MPG123_FLAGS, use the usual binary or to combine.

Enumerator
MPG123_FORCE_MONO | 0111 Force some mono mode: This is a test bitmask for seeing if any mono forcing is active.
MPG123_MONO_LEFT | 0001 Force playback of left channel only.
MPG123_MONO_RIGHT | 0010 Force playback of right channel only.
MPG123_MONO_MIX | 0100 Force playback of mixed mono.
MPG123_FORCE_STEREO | 1000 Force stereo output.
MPG123_FORCE_8BIT | 00010000 Force 8bit formats.
MPG123_QUIET | 00100000 Suppress any printouts (overrules verbose).
MPG123_GAPLESS | 01000000 Enable gapless decoding (default on if libmpg123 has support).
MPG123_NO_RESYNC | 10000000 Disable resync stream after error.
MPG123_SEEKBUFFER | 000100000000 Enable small buffer on non-seekable streams to allow some peek-ahead (for better MPEG sync).
MPG123_FUZZY | 001000000000 Enable fuzzy seeks (guessing byte offsets or using approximate seek points from Xing TOC)
MPG123_FORCE_FLOAT | 010000000000 Force floating point output (32 or 64 bits depends on mpg123 internal precision).
MPG123_PLAIN_ID3TEXT | 100000000000 Do not translate ID3 text data to UTF-8. ID3 strings will contain the raw text data, with the first byte containing the ID3 encoding code.
MPG123_IGNORE_STREAMLENGTH | 1000000000000 Ignore any stream length information contained in the stream, which can be contained in a 'TLEN' frame of an ID3v2 tag or a Xing tag
MPG123_SKIP_ID3V2 | 10 0000 0000 0000 Do not parse ID3v2 tags, just skip them.
MPG123_IGNORE_INFOFRAME | 100 0000 0000 0000 Do not parse the LAME/Xing info frame, treat it as normal MPEG data.
MPG123_AUTO_RESAMPLE | 1000 0000 0000 0000 Allow automatic internal resampling of any kind (default on if supported). Especially when going lowlevel with replacing output buffer, you might want to unset this flag. Setting MPG123_DOWNSAMPLE or MPG123_FORCE_RATE will override this.
MPG123_PICTURE | 17th bit: Enable storage of pictures from tags (ID3v2 APIC).
MPG123_NO_PEEK_END | 18th bit: Do not seek to the end of the stream in order to probe the stream length and search for the id3v1 field. This also means the file size is unknown unless set using mpg123_set_filesize() and the stream is assumed as non-seekable unless overridden.
MPG123_FORCE_SEEKABLE | 19th bit: Force the stream to be seekable.
MPG123_STORE_RAW_ID3 | Store raw ID3 data (even if skipping). Before mpg123 1.33.2 (libmpg123 API 49, patchlevel 4), this has to be combined with MPG123_SKIP_ID3 to avoid getting corrupted data due to the ID3 parser inserting encoding bytes for its own convenience.
MPG123_FORCE_ENDIAN | Enforce endianess of output samples. This is not reflected in the format codes. If this flag is set along with MPG123_BIG_ENDIAN, MPG123_ENC_SIGNED16 means s16be, without MPG123_BIG_ENDIAN, it means s16le. Normal operation without MPG123_FORCE_ENDIAN produces output in native byte order.
MPG123_BIG_ENDIAN | Choose big endian instead of little.
MPG123_NO_READAHEAD | Disable read-ahead in parser. If you know you provide full frames to the feeder API, this enables decoder output from the first one on, instead of having to wait for the next frame to confirm that the stream is healthy. It also disables free format support unless you provide a frame size using MPG123_FREEFORMAT_SIZE.
MPG123_FLOAT_FALLBACK | Consider floating point output encoding only after trying other (possibly downsampled) rates and encodings first. This is to support efficient playback where floating point output is only configured for an external resampler, bypassing that resampler when the desired rate can be produced directly. This is enabled by default to be closer to older versions of libmpg123 which did not enable float automatically at all. If disabled, float is considered after the 16 bit default and higher-bit integer encodings for any rate.
MPG123_NO_FRANKENSTEIN | Disable support for Frankenstein streams (different MPEG streams stiched together). Do not accept serious change of MPEG header inside a single stream. With this flag, the audio output format cannot change during decoding unless you open a new stream. This also stops decoding after an announced end of stream (Info header contained a number of frames and this number has been reached). This makes your MP3 files behave more like ordinary media files with defined structure, rather than stream dumps with some sugar.

Definition at line 314 of file mpg123.h.

## ◆ mpg123_param_rva

enum mpg123_param_rva

choices for MPG123_RVA

Enumerator
MPG123_RVA_OFF | RVA disabled (default).
MPG123_RVA_MIX | Use mix/track/radio gain.
MPG123_RVA_ALBUM | Use album/audiophile gain
MPG123_RVA_MAX | The maximum RVA code, may increase in future.

Definition at line 379 of file mpg123.h.

## ◆ mpg123_feature_set

enum mpg123_feature_set

Feature set available for query with mpg123_feature.

Enumerator
MPG123_FEATURE_ABI_UTF8OPEN | mpg123 expects path names to be given in UTF-8 encoding instead of plain native.
MPG123_FEATURE_OUTPUT_8BIT | 8bit output
MPG123_FEATURE_OUTPUT_16BIT | 16bit output
MPG123_FEATURE_OUTPUT_32BIT | 32bit output
MPG123_FEATURE_INDEX | support for building a frame index for accurate seeking
MPG123_FEATURE_PARSE_ID3V2 | id3v2 parsing
MPG123_FEATURE_DECODE_LAYER1 | mpeg layer-1 decoder enabled
MPG123_FEATURE_DECODE_LAYER2 | mpeg layer-2 decoder enabled
MPG123_FEATURE_DECODE_LAYER3 | mpeg layer-3 decoder enabled
MPG123_FEATURE_DECODE_ACCURATE | accurate decoder rounding
MPG123_FEATURE_DECODE_DOWNSAMPLE | downsample (sample omit)
MPG123_FEATURE_DECODE_NTOM | flexible rate decoding
MPG123_FEATURE_PARSE_ICY | ICY support
MPG123_FEATURE_TIMEOUT_READ | Reader with timeout (network).
MPG123_FEATURE_EQUALIZER | tunable equalizer
MPG123_FEATURE_MOREINFO | more info extraction (for frame analyzer)
MPG123_FEATURE_OUTPUT_FLOAT32 | 32 bit float output
MPG123_FEATURE_OUTPUT_FLOAT64 | 64 bit float output (as of now: never!)

Definition at line 448 of file mpg123.h.

## Function Documentation

## ◆ mpg123_distversion()

const char* mpg123_distversion | ( | unsigned int * | major,
|  | unsigned int * | minor,
|  | unsigned int * | patch
| ) |  |

Get version of the mpg123 distribution this library build came with. (optional means non-NULL)

Parameters

  major | optional address to store major version number
  minor | optional address to store minor version number
  patch | optional address to store patchlevel version number

Returns
  full version string (like "1.2.3-beta4 (experimental)")

## ◆ mpg123_libversion()

unsigned int mpg123_libversion | ( | unsigned int * | patch | ) |

Get API version of library build.

Parameters

  patch | optional address to store patchlevel

Returns
  API version of library

## ◆ mpg123_init()

MPG123_EXPORT int mpg123_init | ( | void |  | ) |

Useless no-op that used to do initialization work.

For API version before 46 (mpg123 1.27.0), you had to ensure to have this called once before creating a handle. To be pure, this had to happen in a single-threaded context, too (while in practice, there was no harm done possibly racing to compute the same numbers again).

Now this function really does nothing anymore. The only reason to call it is to be compatible with old versions of the library that still require it.

Returns
  MPG123_OK if successful, otherwise an error number.

## ◆ mpg123_exit()

MPG123_EXPORT void mpg123_exit | ( | void |  | ) |

Superfluous Function to close down the mpg123 library. This was created with the thought that there sometime will be cleanup code to be run after library use. This never materialized. You can forget about this function and it is only here for old programs that do call it.

## ◆ mpg123_new()

MPG123_EXPORT mpg123_handle* mpg123_new | ( | const char * | decoder,
|  | int * | error
| ) |  |

Create a handle with optional choice of decoder (named by a string, see mpg123_decoders() or mpg123_supported_decoders()). and optional retrieval of an error code to feed to mpg123_plain_strerror(). Optional means: Any of or both the parameters may be NULL.

Parameters

  decoder | optional choice of decoder variant (NULL for default)
  error | optional address to store error codes

Returns
  Non-NULL pointer to fresh handle when successful.

## ◆ mpg123_delete()

MPG123_EXPORT void mpg123_delete | ( | mpg123_handle * | mh | ) |

Delete handle, mh is either a valid mpg123 handle or NULL.

Parameters

  mh | handle

## ◆ mpg123_free()

MPG123_EXPORT void mpg123_free | ( | void * | ptr | ) |

Free plain memory allocated within libmpg123. This is for library users that are not sure to use the same underlying memory allocator as libmpg123. It is just a wrapper over free() in the underlying C library.

## ◆ mpg123_param()

MPG123_EXPORT int mpg123_param | ( | mpg123_handle * | mh,
|  | enum mpg123_parms | type,
|  | long | value,
|  | double | fvalue
| ) |  |

Set a specific parameter on a handle.

Note that this name is mapped to mpg123_param2() instead unless MPG123_ENUM_API is defined.

Parameters

  mh | handle
  type | parameter choice
  value | integer value
  fvalue | floating point value

Returns
  MPG123_OK on success

## ◆ mpg123_param2()

MPG123_EXPORT int mpg123_param2 | ( | mpg123_handle * | mh,
|  | int | type,
|  | long | value,
|  | double | fvalue
| ) |  |

Set a specific parameter on a handle. No enums.

This is actually called instead of mpg123_param() unless MPG123_ENUM_API is defined.

Parameters

  mh | handle
  type | parameter choice (from enum mpg123_parms)
  value | integer value
  fvalue | floating point value

Returns
  MPG123_OK on success

## ◆ mpg123_getparam()

MPG123_EXPORT int mpg123_getparam | ( | mpg123_handle * | mh,
|  | enum mpg123_parms | type,
|  | long * | value,
|  | double * | fvalue
| ) |  |

Get a specific parameter from a handle.

Note that this name is mapped to mpg123_getparam2() instead unless MPG123_ENUM_API is defined.

Parameters

  mh | handle
  type | parameter choice
  value | integer value return address
  fvalue | floating point value return address

Returns
  MPG123_OK on success

## ◆ mpg123_getparam2()

MPG123_EXPORT int mpg123_getparam2 | ( | mpg123_handle * | mh,
|  | int | type,
|  | long * | value,
|  | double * | fvalue
| ) |  |

Get a specific parameter from a handle. No enums.

This is actually called instead of mpg123_getparam() unless MPG123_ENUM_API is defined.

Parameters

  mh | handle
  type | parameter choice (from enum mpg123_parms)
  value | integer value return address
  fvalue | floating point value return address

Returns
  MPG123_OK on success

## ◆ mpg123_feature()

MPG123_EXPORT int mpg123_feature | ( | const enum mpg123_feature_set | key | ) |

Query libmpg123 features.

Note that this name is mapped to mpg123_feature2() instead unless MPG123_ENUM_API is defined.

Parameters

  key | feature selection

Returns
  1 for success, 0 for unimplemented functions

## ◆ mpg123_feature2()

MPG123_EXPORT int mpg123_feature2 | ( | int | key | ) |

Query libmpg123 features. No enums.

This is actually called instead of mpg123_feature() unless MPG123_ENUM_API is defined.

Parameters

  key | feature selection (from enum mpg123_feature_set)

Returns
  1 for success, 0 for unimplemented functions