# 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;-).
Modules
Here is a list of all modules:

example programs using libmpg123 and libout123 |
mpg123 header general settings and notes |
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..
mpg123 error handling | Functions to get text version of the error numbers and an enumeration of the error codes returned by libmpg123
mpg123 decoder selection | Functions to list and select the available decoders. Perhaps the most prominent feature of mpg123: You have several (optimized) decoders to choose from (on x86 and PPC (MacOS) systems, that is)
mpg123 output audio format | Functions to get and select the format of the decoded audio
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!)
mpg123 position and seeking | Functions querying and manipulating position in the decoded audio bitstream. The position is measured in decoded audio samples or MPEG frame offset for the specific functions. The term sample refers to a group of samples for multiple channels, normally dubbed PCM frames. The latter term is avoided here because frame means something different in the context of MPEG audio. Since all samples of a PCM frame occur at the same time, there is only very limited ambiguity when talking about playback offset, as counting each channel sample individually does not make sense
mpg123 volume and equalizer |
mpg123 status and information |
mpg123 metadata handling | Functions to retrieve the metadata from MPEG Audio files and streams. Also includes string handling functions
mpg123 advanced parameter API | Direct access to a parameter set without full handle around it. Possible uses:
mpg123 low level I/O | You may want to do tricky stuff with I/O that does not work with mpg123's default file access or you want to make it decode into your own pocket..
mpg123 PCM sample encodings | These are definitions for audio formats used by libmpg123 and libout123
out123 library API | This is out123, a library focused on continuous playback of audio streams via various platform-specific output methods. It glosses over details of the native APIs to give an interface close to simply writing data to a file. There might be the option to tune details like buffer (period) sizes and the number of them on the device side in future, but the focus of the library is to ease the use case of just getting that raw audio data out there, without interruptions
syn123 library API | I wanted to create some test signals in different encodings for testing libout123. Also, they shall serve to verify the decoding of libmpg123 in automated testing. Then, the awful drop-sample resampling inside the latter needed replacement. As digital filtering is part of the resampler dance, a chain of those can also be configured and applied. I hope I can avoid adding yet more functionality. It's a little utility library to accompany libmpg123 and libout123, OK?