# 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;-).
Classes | Enumerations | Functions
mpg123 status and information

## Classes
struct | mpg123_frameinfo
struct | mpg123_frameinfo2
struct | mpg123_moreinfo

## Enumerations
enum | mpg123_vbr { MPG123_CBR =0, MPG123_VBR, MPG123_ABR }
enum | mpg123_version { MPG123_1_0 =0, MPG123_2_0, MPG123_2_5 }
enum | mpg123_mode { MPG123_M_STEREO =0, MPG123_M_JOINT, MPG123_M_DUAL, MPG123_M_MONO }
enum | mpg123_flags { MPG123_CRC =0x1, MPG123_COPYRIGHT =0x2, MPG123_PRIVATE =0x4, MPG123_ORIGINAL =0x8 }
enum | mpg123_state { MPG123_ACCURATE = 1, MPG123_BUFFERFILL, MPG123_FRANKENSTEIN, MPG123_FRESH_DECODER, MPG123_ENC_DELAY, MPG123_ENC_PADDING, MPG123_DEC_DELAY }

## Functions
MPG123_EXPORT int | mpg123_info (mpg123_handle *mh, struct mpg123_frameinfo *mi)
MPG123_EXPORT int | mpg123_info2 (mpg123_handle *mh, struct mpg123_frameinfo2 *mi)
MPG123_EXPORT int | mpg123_set_moreinfo (mpg123_handle *mh, struct mpg123_moreinfo *mi)
MPG123_EXPORT size_t | mpg123_safe_buffer (void)
MPG123_EXPORT int | mpg123_scan (mpg123_handle *mh)
MPG123_EXPORT off_t | mpg123_framelength (mpg123_handle *mh)
MPG123_EXPORT off_t | mpg123_length (mpg123_handle *mh)
MPG123_EXPORT int | mpg123_set_filesize (mpg123_handle *mh, off_t size)
MPG123_EXPORT int64_t | mpg123_framelength64 (mpg123_handle *mh)
MPG123_EXPORT int64_t | mpg123_length64 (mpg123_handle *mh)
MPG123_EXPORT int | mpg123_set_filesize64 (mpg123_handle *mh, int64_t size)
MPG123_EXPORT double | mpg123_tpf (mpg123_handle *mh)
MPG123_EXPORT int | mpg123_spf (mpg123_handle *mh)
MPG123_EXPORT long | mpg123_clip (mpg123_handle *mh)
MPG123_EXPORT int | mpg123_getstate (mpg123_handle *mh, enum mpg123_state key, long *val, double *fval)
MPG123_EXPORT int | mpg123_getstate2 (mpg123_handle *mh, int key, long *val, double *fval)

## Detailed Description

## Enumeration Type Documentation

## ◆ mpg123_vbr

enum mpg123_vbr

Enumeration of the mode types of Variable Bitrate

Enumerator
MPG123_CBR | Constant Bitrate Mode (default)
MPG123_VBR | Variable Bitrate Mode
MPG123_ABR | Average Bitrate Mode

Definition at line 1468 of file mpg123.h.

## ◆ mpg123_version

enum mpg123_version

Enumeration of the MPEG Versions

Enumerator
MPG123_1_0 | MPEG Version 1.0
MPG123_2_0 | MPEG Version 2.0
MPG123_2_5 | MPEG Version 2.5

Definition at line 1475 of file mpg123.h.

## ◆ mpg123_mode

enum mpg123_mode

Enumeration of the MPEG Audio mode. Only the mono mode has 1 channel, the others have 2 channels.

Enumerator
MPG123_M_STEREO | Standard Stereo.
MPG123_M_JOINT | Joint Stereo.
MPG123_M_DUAL | Dual Channel.
MPG123_M_MONO | Single Channel.

Definition at line 1484 of file mpg123.h.

## ◆ mpg123_flags

enum mpg123_flags

Enumeration of the MPEG Audio flag bits

Enumerator
MPG123_CRC | The bitstream is error protected using 16-bit CRC.
MPG123_COPYRIGHT | The bitstream is copyrighted.
MPG123_PRIVATE | The private bit has been set.
MPG123_ORIGINAL | The bitstream is an original, not a copy.

Definition at line 1493 of file mpg123.h.

## ◆ mpg123_state

enum mpg123_state

The key values for state information from mpg123_getstate().

Enumerator
MPG123_ACCURATE | Query if positons are currently accurate (integer value, 0 if false, 1 if true).
MPG123_BUFFERFILL | Get fill of internal (feed) input buffer as integer byte count returned as long and as double. An error is returned on integer overflow while converting to (signed) long, but the returned floating point value shold still be fine.
MPG123_FRANKENSTEIN | Stream consists of carelessly stitched together files. Seeking may yield unexpected results (also with MPG123_ACCURATE, it may be confused).
MPG123_FRESH_DECODER | Decoder structure has been updated, possibly indicating changed stream (integer value, 0 if false, 1 if true). Flag is cleared after retrieval.
MPG123_ENC_DELAY | Encoder delay read from Info tag (layer III, -1 if unknown).
MPG123_ENC_PADDING | Encoder padding read from Info tag (layer III, -1 if unknown).
MPG123_DEC_DELAY | Decoder delay (for layer III only, -1 otherwise).

Definition at line 1688 of file mpg123.h.

## Function Documentation

## ◆ mpg123_info()

MPG123_EXPORT int mpg123_info | ( | mpg123_handle * | mh,
|  | struct mpg123_frameinfo * | mi
| ) |  |

Get frame information about the MPEG audio bitstream and store it in a mpg123_frameinfo structure.

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

Parameters

  mh | handle
  mi | address of existing frameinfo structure to write to

Returns
  MPG123_OK on success

## ◆ mpg123_info2()

MPG123_EXPORT int mpg123_info2 | ( | mpg123_handle * | mh,
|  | struct mpg123_frameinfo2 * | mi
| ) |  |

Get frame information about the MPEG audio bitstream and store it in a mpg123_frameinfo2 structure.

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

Parameters

  mh | handle
  mi | address of existing frameinfo structure to write to

Returns
  MPG123_OK on success

## ◆ mpg123_set_moreinfo()

MPG123_EXPORT int mpg123_set_moreinfo | ( | mpg123_handle * | mh,
|  | struct mpg123_moreinfo * | mi
| ) |  |

Trigger collection of additional decoder information while decoding.

Parameters

  mh | handle
  mi | pointer to data storage (NULL to disable collection)

Returns
  MPG123_OK if the collection was enabled/disabled as desired, MPG123_ERR otherwise (e.g. if the feature is disabled)

## ◆ mpg123_safe_buffer()

MPG123_EXPORT size_t mpg123_safe_buffer | ( | void |  | ) |

Get the safe output buffer size for all cases (when you want to replace the internal buffer)

Returns
  safe buffer size

## ◆ mpg123_scan()

MPG123_EXPORT int mpg123_scan | ( | mpg123_handle * | mh | ) |

Make a full parsing scan of each frame in the file. ID3 tags are found. An accurate length value is stored. Seek index will be filled. A seek back to current position is performed. At all, this function refuses work when stream is not seekable.

Parameters

  mh | handle

Returns
  MPG123_OK on success

## ◆ mpg123_framelength()

MPG123_EXPORT off_t mpg123_framelength | ( | mpg123_handle * | mh | ) |

Return, if possible, the full (expected) length of current track in MPEG frames.

Parameters

  mh | handle

Returns
  length >= 0 or MPG123_ERR if there is no length guess possible.

## ◆ mpg123_length()

MPG123_EXPORT off_t mpg123_length | ( | mpg123_handle * | mh | ) |

Return, if possible, the full (expected) length of current track in samples (PCM frames).

This relies either on an Info frame at the beginning or a previous call to mpg123_scan() to get the real number of MPEG frames in a file. It will guess based on file size if neither Info frame nor scan data are present. In any case, there is no guarantee that the decoder will not give you more data, for example in case the open file gets appended to during decoding.

Parameters

  mh | handle

Returns
  length >= 0 or MPG123_ERR if there is no length guess possible.

## ◆ mpg123_set_filesize()

MPG123_EXPORT int mpg123_set_filesize | ( | mpg123_handle * | mh,
|  | off_t | size
| ) |  |

Override the value for file size in bytes. Useful for getting sensible track length values in feed mode or for HTTP streams.

Parameters

  mh | handle
  size | file size in bytes

Returns
  MPG123_OK on success

## ◆ mpg123_framelength64()

MPG123_EXPORT int64_t mpg123_framelength64 | ( | mpg123_handle * | mh | ) |

Return, if possible, the full (expected) length of current track in MPEG frames as 64 bit number.

Parameters

  mh | handle

Returns
  length >= 0 or MPG123_ERR if there is no length guess possible.

## ◆ mpg123_length64()

MPG123_EXPORT int64_t mpg123_length64 | ( | mpg123_handle * | mh | ) |

Return, if possible, the full (expected) length of current track in samples (PCM frames) as 64 bit value.

This relies either on an Info frame at the beginning or a previous call to mpg123_scan() to get the real number of MPEG frames in a file. It will guess based on file size if neither Info frame nor scan data are present. In any case, there is no guarantee that the decoder will not give you more data, for example in case the open file gets appended to during decoding.

Parameters

  mh | handle

Returns
  length >= 0 or MPG123_ERR if there is no length guess possible.

## ◆ mpg123_set_filesize64()

MPG123_EXPORT int mpg123_set_filesize64 | ( | mpg123_handle * | mh,
|  | int64_t | size
| ) |  |

Override the 64 bit value for file size in bytes. Useful for getting sensible track length values in feed mode or for HTTP streams.

Parameters

  mh | handle
  size | file size in bytes

Returns
  MPG123_OK on success

## ◆ mpg123_tpf()

MPG123_EXPORT double mpg123_tpf | ( | mpg123_handle * | mh | ) |

Get MPEG frame duration in seconds.

Parameters

  mh | handle

Returns
  frame duration in seconds, <0 on error

## ◆ mpg123_spf()

MPG123_EXPORT int mpg123_spf | ( | mpg123_handle * | mh | ) |

Get MPEG frame duration in samples.

Parameters

  mh | handle

Returns
  samples per frame for the most recently parsed frame; <0 on errors

## ◆ mpg123_clip()

MPG123_EXPORT long mpg123_clip | ( | mpg123_handle * | mh | ) |

Get and reset the clip count.

Parameters

  mh | handle

Returns
  count of clipped samples

## ◆ mpg123_getstate()

MPG123_EXPORT int mpg123_getstate | ( | mpg123_handle * | mh,
|  | enum mpg123_state | key,
|  | long * | val,
|  | double * | fval
| ) |  |

Get various current decoder/stream state information.

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

Parameters

  mh | handle
  key | the key to identify the information to give.
  val | the address to return (long) integer values to
  fval | the address to return floating point values to

Returns
  MPG123_OK on success

## ◆ mpg123_getstate2()

MPG123_EXPORT int mpg123_getstate2 | ( | mpg123_handle * | mh,
|  | int | key,
|  | long * | val,
|  | double * | fval
| ) |  |

Get various current decoder/stream state information. No enums.

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

Parameters

  mh | handle
  key | the key to identify the information to give (enum mpg123_state)
  val | the address to return (long) integer values to
  fval | the address to return floating point values to

Returns
  MPG123_OK on success