# 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;-).
Functions
mpg123 file input and decoding

Functions for input bitstream and decoding operations. Decoding/seek functions may also return message codes MPG123_DONE, MPG123_NEW_FORMAT and MPG123_NEED_MORE (please read up on these on how to react!). More...

## Functions
MPG123_EXPORT int | mpg123_open_fixed (mpg123_handle *mh, const char *path, int channels, int encoding)
MPG123_EXPORT int | mpg123_open (mpg123_handle *mh, const char *path)
MPG123_EXPORT int | mpg123_open_fd (mpg123_handle *mh, int fd)
MPG123_EXPORT int | mpg123_open_handle (mpg123_handle *mh, void *iohandle)
MPG123_EXPORT int | mpg123_open64 (mpg123_handle *mh, const char *path)
MPG123_EXPORT int | mpg123_open_fixed64 (mpg123_handle *mh, const char *path, int channels, int encoding)
MPG123_EXPORT int | mpg123_open_handle64 (mpg123_handle *mh, void *iohandle)
MPG123_EXPORT int | mpg123_open_feed (mpg123_handle *mh)
MPG123_EXPORT int | mpg123_close (mpg123_handle *mh)
MPG123_EXPORT int | mpg123_read (mpg123_handle *mh, void *outmemory, size_t outmemsize, size_t *done)
MPG123_EXPORT int | mpg123_feed (mpg123_handle *mh, const unsigned char *in, size_t size)
MPG123_EXPORT int | mpg123_decode (mpg123_handle *mh, const unsigned char *inmemory, size_t inmemsize, void *outmemory, size_t outmemsize, size_t *done)
MPG123_EXPORT int | mpg123_decode_frame (mpg123_handle *mh, off_t *num, unsigned char **audio, size_t *bytes)
MPG123_EXPORT int | mpg123_framebyframe_decode (mpg123_handle *mh, off_t *num, unsigned char **audio, size_t *bytes)
MPG123_EXPORT int | mpg123_decode_frame64 (mpg123_handle *mh, int64_t *num, unsigned char **audio, size_t *bytes)
MPG123_EXPORT int | mpg123_framebyframe_decode64 (mpg123_handle *mh, int64_t *num, unsigned char **audio, size_t *bytes)
MPG123_EXPORT int | mpg123_framebyframe_next (mpg123_handle *mh)
MPG123_EXPORT int | mpg123_framedata (mpg123_handle *mh, unsigned long *header, unsigned char **bodydata, size_t *bodybytes)
MPG123_EXPORT off_t | mpg123_framepos (mpg123_handle *mh)
MPG123_EXPORT int64_t | mpg123_framepos64 (mpg123_handle *mh)

## Detailed Description

Functions for input bitstream and decoding operations. Decoding/seek functions may also return message codes MPG123_DONE, MPG123_NEW_FORMAT and MPG123_NEED_MORE (please read up on these on how to react!).

## Function Documentation

## ◆ mpg123_open_fixed()

MPG123_EXPORT int mpg123_open_fixed | ( | mpg123_handle * | mh,
|  | const char * | path,
|  | int | channels,
|  | int | encoding
| ) |  |

Open a simple MPEG file with fixed properties.

This function shall simplify the common use case of a plain MPEG file on disk that you want to decode, with one fixed sample rate and channel count, and usually a length defined by a Lame/Info/Xing tag. It will:

- set the MPG123_NO_FRANKENSTEIN flag
- set up format support according to given parameters,
- open the file,
- query audio format,
- fix the audio format support table to ensure the format stays the same,
- call mpg123_scan() if there is no header frame to tell the track length.

From that on, you can call mpg123_getformat() for querying the sample rate (and channel count in case you allowed both) and mpg123_length() to get a pretty safe number for the duration. Only the sample rate is left open as that indeed is a fixed property of MPEG files. You could set MPG123_FORCE_RATE beforehand, but that may trigger low-quality resampling in the decoder, only do so if in dire need. The library will convert mono files to stereo for you, and vice versa. If any constraint cannot be satisified (most likely because of a non-default build of libmpg123), you get MPG123_ERR returned and can query the detailed cause from the handle. Only on MPG123_OK there will an open file that you then close using mpg123_close(), or implicitly on mpg123_delete() or the next call to open another file.

So, for your usual CD rip collection, you could use

mpg123_open_fixed(mh, path, MPG123_STEREO, MPG123_ENC_SIGNED_16)

and be happy calling mpg123_getformat() to verify 44100 Hz rate, then just playing away with mpg123_read(). The occasional mono file, or MP2 file, will also be decoded without you really noticing. Just the speed could be wrong if you do not care about sample rate at all.

Parameters

  mh | handle
  path | filesystem path (see mpg123_open())
  channels | allowed channel count, either 1 (MPG123_MONO) or 2 (MPG123_STEREO), or bitwise or of them, but then you're halfway back to calling mpg123_format() again;-)
  encoding | a definite encoding from enum mpg123_enc_enum or a bitmask like for mpg123_format(), defeating the purpose somewhat

## ◆ mpg123_open()

MPG123_EXPORT int mpg123_open | ( | mpg123_handle * | mh,
|  | const char * | path
| ) |  |

Open and prepare to decode the specified file by filesystem path. This does not open HTTP urls; libmpg123 contains no networking code. If you want to decode internet streams, use mpg123_open_fd() or mpg123_open_feed().

The path parameter usually is just a string that is handed to the underlying OS routine for opening, treated as a blob of binary data. On platforms where encoding needs to be involved, something like _wopen() is called underneath and the path argument to libmpg123 is assumed to be encoded in UTF-8. So, if you have to ask yourself which encoding is needed, the answer is UTF-8, which also fits any sane modern install of Unix-like systems.

Parameters

  mh | handle
  path | filesystem path

Returns
  MPG123_OK on success

## ◆ mpg123_open_fd()

MPG123_EXPORT int mpg123_open_fd | ( | mpg123_handle * | mh,
|  | int | fd
| ) |  |

Use an already opened file descriptor as the bitstream input mpg123_close() will not close the file descriptor.

Parameters

  mh | handle
  fd | file descriptor

Returns
  MPG123_OK on success

## ◆ mpg123_open_handle()

MPG123_EXPORT int mpg123_open_handle | ( | mpg123_handle * | mh,
|  | void * | iohandle
| ) |  |

Use an opaque handle as bitstream input. This works only with the replaced I/O from mpg123_replace_reader_handle() or mpg123_reader64()! mpg123_close() will call the cleanup callback for your non-NULL handle (if you gave one). Note that this used to be usable with MPG123_PORTABLE_API defined in mpg123 1.32.x and was in fact the only entry point for handle I/O. Since mpg123 1.33.0 and API version 49, there is mpg123_open_handle64() for the portable case and has to be used instead of this function here, even if it would work just fine, the inclusion of a largefile-renamed symbol in the portable set was wrong.

Parameters

  mh | handle
  iohandle | your handle

Returns
  MPG123_OK on success

## ◆ mpg123_open64()

MPG123_EXPORT int mpg123_open64 | ( | mpg123_handle * | mh,
|  | const char * | path
| ) |  |

Open and prepare to decode the specified file by filesystem path. This works exactly like mpg123_open() in modern libmpg123, see there for more description. This name is not subject to largefile symbol renaming. You can also use it with MPG123_PORTABLE_API.

Parameters

  mh | handle
  path | filesystem path of your resource

Returns
  MPG123_OK on success

## ◆ mpg123_open_fixed64()

MPG123_EXPORT int mpg123_open_fixed64 | ( | mpg123_handle * | mh,
|  | const char * | path,
|  | int | channels,
|  | int | encoding
| ) |  |

Open a simple MPEG file with fixed properties. This is the same as mpg123_open_fixed(), just with a stable symbol name for int64_t portable API.

Parameters

  mh | handle
  path | filesystem path (see mpg123_open())
  channels | allowed channel count, either 1 (MPG123_MONO) or 2 (MPG123_STEREO), or bitwise or of them, but then you're halfway back to calling mpg123_format() again;-)
  encoding | a definite encoding from enum mpg123_enc_enum or a bitmask like for mpg123_format(), defeating the purpose somewhat

## ◆ mpg123_open_handle64()

MPG123_EXPORT int mpg123_open_handle64 | ( | mpg123_handle * | mh,
|  | void * | iohandle
| ) |  |

Use an opaque handle as bitstream input. This works only with the replaced I/O from mpg123_reader64()! mpg123_close() will call the cleanup callback for your non-NULL handle (if you gave one). This is a simplified variant of mpg123_open_handle() that only supports the int64_t API, available with MPG123_PORTABLE_API.

Parameters

  mh | handle
  iohandle | your handle

Returns
  MPG123_OK on success

## ◆ mpg123_open_feed()

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

Open a new bitstream and prepare for direct feeding This works together with mpg123_decode(); you are responsible for reading and feeding the input bitstream. Also, you are expected to handle ICY metadata extraction yourself. This input method does not handle MPG123_ICY_INTERVAL. It does parse ID3 frames, though.

Parameters

  mh | handle

Returns
  MPG123_OK on success

## ◆ mpg123_close()

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

Closes the source, if libmpg123 opened it.

Parameters

  mh | handle

Returns
  MPG123_OK on success

## ◆ mpg123_read()

MPG123_EXPORT int mpg123_read | ( | mpg123_handle * | mh,
|  | void * | outmemory,
|  | size_t | outmemsize,
|  | size_t * | done
| ) |  |

Read from stream and decode up to outmemsize bytes.

Note: The type of outmemory changed to a void pointer in mpg123 1.26.0 (API version 45).

Parameters

  mh | handle
  outmemory | address of output buffer to write to
  outmemsize | maximum number of bytes to write
  done | address to store the number of actually decoded bytes to

Returns
  MPG123_OK or error/message code

## ◆ mpg123_feed()

MPG123_EXPORT int mpg123_feed | ( | mpg123_handle * | mh,
|  | const unsigned char * | in,
|  | size_t | size
| ) |  |

Feed data for a stream that has been opened with mpg123_open_feed(). It's give and take: You provide the bytestream, mpg123 gives you the decoded samples.

Parameters

  mh | handle
  in | input buffer
  size | number of input bytes

Returns
  MPG123_OK or error/message code.

## ◆ mpg123_decode()

MPG123_EXPORT int mpg123_decode | ( | mpg123_handle * | mh,
|  | const unsigned char * | inmemory,
|  | size_t | inmemsize,
|  | void * | outmemory,
|  | size_t | outmemsize,
|  | size_t * | done
| ) |  |

Decode MPEG Audio from inmemory to outmemory. This is very close to a drop-in replacement for old mpglib. When you give zero-sized output buffer the input will be parsed until decoded data is available. This enables you to get MPG123_NEW_FORMAT (and query it) without taking decoded data. Think of this function being the union of mpg123_read() and mpg123_feed() (which it actually is, sort of;-). You can actually always decide if you want those specialized functions in separate steps or one call this one here.

Note: The type of outmemory changed to a void pointer in mpg123 1.26.0 (API version 45).

Parameters

  mh | handle
  inmemory | input buffer
  inmemsize | number of input bytes
  outmemory | output buffer
  outmemsize | maximum number of output bytes
  done | address to store the number of actually decoded bytes to

Returns
  error/message code (watch out especially for MPG123_NEED_MORE)

## ◆ mpg123_decode_frame()

MPG123_EXPORT int mpg123_decode_frame | ( | mpg123_handle * | mh,
|  | off_t * | num,
|  | unsigned char ** | audio,
|  | size_t * | bytes
| ) |  |

Decode next MPEG frame to internal buffer or read a frame and return after setting a new format.

Parameters

  mh | handle
  num | current frame offset gets stored there
  audio | This pointer is set to the internal buffer to read the decoded audio from.
  bytes | number of output bytes ready in the buffer

Returns
  MPG123_OK or error/message code

## ◆ mpg123_framebyframe_decode()

MPG123_EXPORT int mpg123_framebyframe_decode | ( | mpg123_handle * | mh,
|  | off_t * | num,
|  | unsigned char ** | audio,
|  | size_t * | bytes
| ) |  |

Decode current MPEG frame to internal buffer. Warning: This is experimental API that might change in future releases! Please watch mpg123 development closely when using it.

Parameters

  mh | handle
  num | last frame offset gets stored there
  audio | this pointer is set to the internal buffer to read the decoded audio from.
  bytes | number of output bytes ready in the buffer

Returns
  MPG123_OK or error/message code

## ◆ mpg123_decode_frame64()

MPG123_EXPORT int mpg123_decode_frame64 | ( | mpg123_handle * | mh,
|  | int64_t * | num,
|  | unsigned char ** | audio,
|  | size_t * | bytes
| ) |  |

Decode next MPEG frame to internal buffer or read a frame and return after setting a new format.

Parameters

  mh | handle
  num | current frame offset gets stored there
  audio | This pointer is set to the internal buffer to read the decoded audio from.
  bytes | number of output bytes ready in the buffer

Returns
  MPG123_OK or error/message code

## ◆ mpg123_framebyframe_decode64()

MPG123_EXPORT int mpg123_framebyframe_decode64 | ( | mpg123_handle * | mh,
|  | int64_t * | num,
|  | unsigned char ** | audio,
|  | size_t * | bytes
| ) |  |

Decode current MPEG frame to internal buffer. Warning: This is experimental API that might change in future releases! Please watch mpg123 development closely when using it.

Parameters

  mh | handle
  num | last frame offset gets stored there
  audio | this pointer is set to the internal buffer to read the decoded audio from.
  bytes | number of output bytes ready in the buffer

Returns
  MPG123_OK or error/message code

## ◆ mpg123_framebyframe_next()

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

Find, read and parse the next mp3 frame Warning: This is experimental API that might change in future releases! Please watch mpg123 development closely when using it.

Parameters

  mh | handle

Returns
  MPG123_OK or error/message code

## ◆ mpg123_framedata()

MPG123_EXPORT int mpg123_framedata | ( | mpg123_handle * | mh,
|  | unsigned long * | header,
|  | unsigned char ** | bodydata,
|  | size_t * | bodybytes
| ) |  |

Get access to the raw input data for the last parsed frame. This gives you a direct look (and write access) to the frame body data. Together with the raw header, you can reconstruct the whole raw MPEG stream without junk and meta data, or play games by actually modifying the frame body data before decoding this frame (mpg123_framebyframe_decode()). A more sane use would be to use this for CRC checking (see mpg123_info() and MPG123_CRC), the first two bytes of the body make up the CRC16 checksum, if present. You can provide NULL for a parameter pointer when you are not interested in the value.

Parameters

  mh | handle
  header | the 4-byte MPEG header
  bodydata | pointer to the frame body stored in the handle (without the header)
  bodybytes | size of frame body in bytes (without the header)

Returns
  MPG123_OK if there was a yet un-decoded frame to get the data from, MPG123_BAD_HANDLE or MPG123_ERR otherwise (without further explanation, the error state of the mpg123_handle is not modified by this function).

## ◆ mpg123_framepos()

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

Get the input position (byte offset in stream) of the last parsed frame. This can be used for external seek index building, for example. It just returns the internally stored offset, regardless of validity – you ensure that a valid frame has been parsed before!

Parameters

  mh | handle

Returns
  byte offset in stream

## ◆ mpg123_framepos64()

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

Get the 64 bit input position (byte offset in stream) of the last parsed frame. This can be used for external seek index building, for example. It just returns the internally stored offset, regardless of validity – you ensure that a valid frame has been parsed before!

Parameters

  mh | handle

Returns
  byte offset in stream