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;-).
out123 library API


#define out123_param_int(ao, code, value)   out123_param((ao), (code), (value), 0., NULL)
#define out123_param_float(ao, code, value)   out123_param((ao), (code), 0, (value), NULL)
#define out123_param_string(ao, code, value)   out123_param((ao), (code), 0, 0., (value))
#define out123_getparam_int(ao, code, value)   out123_getparam((ao), (code), (value), NULL, NULL)
#define out123_getparam_float(ao, code, value)   out123_getparam((ao), (code), NULL, (value), NULL)
#define out123_getparam_string(ao, code, value)   out123_getparam((ao), (code), NULL, NULL, (value))


typedef struct out123_struct out123_handle


enum  out123_parms {
enum  out123_flags {
  OUT123_LINE_OUT = 0x04, OUT123_QUIET = 0x08,
  OUT123_KEEP_PLAYING = 0x10, OUT123_MUTE = 0x20
enum  out123_propflags { OUT123_PROP_LIVE = 0x01, OUT123_PROP_PERSISTENT = 0x02 }
enum  out123_error {
  OUT123_ERR = -1, OUT123_OK = 0,


MPG123_EXPORT out123_handleout123_new (void)
MPG123_EXPORT void out123_del (out123_handle *ao)
MPG123_EXPORT void out123_free (void *ptr)
MPG123_EXPORT const char * out123_strerror (out123_handle *ao)
MPG123_EXPORT int out123_errcode (out123_handle *ao)
MPG123_EXPORT const char * out123_plain_strerror (int errcode)
MPG123_EXPORT int out123_set_buffer (out123_handle *ao, size_t buffer_bytes)
MPG123_EXPORT int out123_param (out123_handle *ao, enum out123_parms code, long value, double fvalue, const char *svalue)
MPG123_EXPORT int out123_getparam (out123_handle *ao, enum out123_parms code, long *ret_value, double *ret_fvalue, char **ret_svalue)
MPG123_EXPORT int out123_param_from (out123_handle *ao, out123_handle *from_ao)
MPG123_EXPORT int out123_drivers (out123_handle *ao, char ***names, char ***descr)
MPG123_EXPORT int out123_open (out123_handle *ao, const char *driver, const char *device)
MPG123_EXPORT int out123_driver_info (out123_handle *ao, char **driver, char **device)
MPG123_EXPORT void out123_close (out123_handle *ao)
MPG123_EXPORT int out123_encodings (out123_handle *ao, long rate, int channels)
MPG123_EXPORT int out123_encsize (int encoding)
MPG123_EXPORT int out123_formats (out123_handle *ao, const long *rates, int ratecount, int minchannels, int maxchannels, struct mpg123_fmt **fmtlist)
MPG123_EXPORT int out123_enc_list (int **enclist)
MPG123_EXPORT int out123_enc_byname (const char *name)
MPG123_EXPORT const char * out123_enc_name (int encoding)
MPG123_EXPORT const char * out123_enc_longname (int encoding)
MPG123_EXPORT int out123_start (out123_handle *ao, long rate, int channels, int encoding)
MPG123_EXPORT void out123_pause (out123_handle *ao)
MPG123_EXPORT void out123_continue (out123_handle *ao)
MPG123_EXPORT void out123_stop (out123_handle *ao)
MPG123_EXPORT size_t out123_play (out123_handle *ao, void *buffer, size_t bytes)
MPG123_EXPORT void out123_drop (out123_handle *ao)
MPG123_EXPORT void out123_drain (out123_handle *ao)
MPG123_EXPORT void out123_ndrain (out123_handle *ao, size_t bytes)
MPG123_EXPORT size_t out123_buffered (out123_handle *ao)
MPG123_EXPORT int out123_getformat (out123_handle *ao, long *rate, int *channels, int *encoding, int *framesize)

Detailed Description

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.

The basic idea is to create a handle with out123_new() and open a certain output device (using a certain driver module, possibly build-time defaults) with out123_open(). Now, you can query the output device for supported encodings for given rate and channel count with out123_get_encodings() and decide what to use for actually starting playback with out123_start().

Then, you just need to provide (interleaved pcm) data for playback with out123_play(), which will block when the device's buffers are full. You get your timing from that (instead of callbacks). If your program does the production of the audio data just a little bit faster than the playback, causing out123_play() to block ever so briefly, you're fine.

You stop playback with out123_stop(), or just close the device and driver via out123_close(), or even just decide to drop it all and do out123_del() right away when you're done.

There are other functions for specific needs, but the basic idea should be covered by the above.

Typedef Documentation

◆ out123_handle

typedef struct out123_struct out123_handle

Typedef shortcut as preferrend name for the handle type.

Definition at line 93 of file out123.h.

Enumeration Type Documentation

◆ out123_parms

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


integer, various flags, see enum out123_flags


float, fraction of buffer to fill before playback


integer, output device gain (module-specific)


integer, verbosity to stderr, >= 0


float, length of device buffer in seconds; This might be ignored, might have only a loose relation to actual buffer sizes and latency, depending on output driver. Try to tune this before opening a device if you want to influcence latency or reduce dropouts. Value <= 0 uses some default, usually favouring stable playback over low latency. Values above 0.5 are probably too much.


integer, query driver/device property flags (r/o)


string, name of this instance (NULL restores default); The value returned by out123_getparam() might be different if the audio backend changed it (to be unique among clients, p.ex.). TODO: The name provided here is used as prefix in diagnostic messages.


string, path to a program binary directory to use as starting point in the search for the output module directory (e.g. ../lib/mpg123 or ./plugins). The environment variable MPG123_MODDIR is always tried first and the in-built installation path last.


enable given flags


disable diven flags

Definition at line 96 of file out123.h.

◆ out123_flags

Flags to tune out123 behaviour


output to headphones (if supported)


output to speaker (if supported)


output to line out (if supported)


no printouts to standard error


When this is set (default), playback continues in a loop when the device does not consume all given data at once. This happens when encountering signals (like SIGSTOP, SIGCONT) that cause interruption of the underlying functions. Note that this flag is meaningless when the optional buffer is employed, There, your program will always block until the buffer completely took over the data given to it via out123_play(), unless a communication error arises.


software mute (play silent audio)

Definition at line 125 of file out123.h.

◆ out123_propflags

Read-only output driver/device property flags (OUT123_PROPFLAGS).


This is a live output, meaning that special care might be needed for pauses in playback (p.ex. stream of silence instead of interruption), as opposed to files on disk.


This (live) output does not need special care for pauses (continues with silence itself), out123_pause() does nothing to the device.

Definition at line 145 of file out123.h.

◆ out123_error

Error code enumeration API calls return a useful (positve) value or zero (OUT123_OK) on simple success. A negative value (-1 == OUT123_ERR) usually indicates that some error occured. Which one, that can be queried using out123_errcode() and friends.


generic alias for verbosity, always == -1


just a name for zero, not going to change


dazzled, out of memory


bad driver name given


unspecified issue loading a driver


no driver loaded


no active audio device


some device playback error


error opening device


Some (really unexpected) error in buffer infrastructure.


basic failure in module loading


some bad function arguments supplied


unknown parameter code


attempt to set read-only parameter


bad handle pointer (NULL, usually)


placeholder for shaping arrays

Definition at line 184 of file out123.h.

Function Documentation

◆ out123_new()

MPG123_EXPORT out123_handle* out123_new ( void  )

Create a new output handle. This only allocates and initializes memory, so the only possible error condition is running out of memory.

pointer to new handle or NULL on error

◆ out123_del()

MPG123_EXPORT void out123_del ( out123_handle ao)

Delete output handle. This implies out123_close().

◆ out123_free()

MPG123_EXPORT void out123_free ( void *  ptr)

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

◆ out123_strerror()

MPG123_EXPORT const char* out123_strerror ( out123_handle ao)

Get string representation of last encountered error in the context of given handle.

error string

◆ out123_errcode()

MPG123_EXPORT int out123_errcode ( out123_handle ao)

Get the plain errcode intead of a string. Note that this used to return OUT123_ERR instead of OUT123_BAD_HANDLE in case of ao==NULL before mpg123-1.23.5 .

error code recorded in handle or OUT123_BAD_HANDLE

◆ out123_plain_strerror()

MPG123_EXPORT const char* out123_plain_strerror ( int  errcode)

Return the error string for a given error code.

errcodethe integer error code
error string

◆ out123_set_buffer()

MPG123_EXPORT int out123_set_buffer ( out123_handle ao,
size_t  buffer_bytes 

Set a desired output buffer size. This starts a separate process that handles the audio output, decoupling the latter from the main process with a memory buffer and saving you the burden to ensure sparing CPU cycles for actual playback. This is for applicatons that prefer continuous playback over small latency. In other words: The kind of applications that out123 is designed for. This routine always kills off any currently active audio output module / device, even if you just disable the buffer when there is no buffer.

Keep this in mind for memory-constrainted systems: Activating the buffer causes a fork of the calling process, doubling the virtual memory use. Depending on your operating system kernel's behaviour regarding memory overcommit, it might be wise to call out123_set_buffer() very early in your program before allocating lots of memory.

There might be a change to threads in future, but for now this is classic fork with shared memory, working without any threading library. If your platform or build does not support that, you will always get an error on trying to set up a non-zero buffer (but the API call will be present).

Also, if you do intend to use this from a multithreaded program, think twice and make sure that your setup is happy with forking full-blown processes off threaded programs. Probably you are better off spawning a buffer thread yourself.

buffer_bytessize (bytes) of a memory buffer for decoded audio, a value of zero disables the buffer.
0 on success, OUT123_ERR on error

◆ out123_param()

MPG123_EXPORT int out123_param ( out123_handle ao,
enum out123_parms  code,
long  value,
double  fvalue,
const char *  svalue 

Set a specific parameter, for a specific out123_handle, using a parameter code chosen from the out123_parms enumeration, to the specified value. The parameters usually only change what happens on next out123_open, not incfluencing running operation.

codeparameter code
valueinput value for integer parameters
fvalueinput value for floating point parameters
svalueinput value for string parameters (contens are copied)
0 on success, OUT123_ERR on error.

◆ out123_getparam()

MPG123_EXPORT int out123_getparam ( out123_handle ao,
enum out123_parms  code,
long *  ret_value,
double *  ret_fvalue,
char **  ret_svalue 

Get a specific parameter, for a specific out123_handle, using a parameter code chosen from the out123_parms enumeration, to the specified value.

codeparameter code
ret_valueoutput address for integer parameters
ret_fvalueoutput address for floating point parameters
ret_svalueoutput address for string parameters (pointer to internal memory, so no messing around, please)
0 on success, OUT123_ERR on error (bad parameter name or bad handle).

◆ out123_param_from()

MPG123_EXPORT int out123_param_from ( out123_handle ao,
out123_handle from_ao 

Copy parameters from another out123_handle.

from_aothe handle to copy parameters from
0 in success, -1 on error

◆ out123_drivers()

MPG123_EXPORT int out123_drivers ( out123_handle ao,
char ***  names,
char ***  descr 

Get list of driver modules reachable in system in C argv-style format. The client is responsible for freeing the memory of both the individual strings and the lists themselves. A module that is not loadable because of missing libraries is simply skipped. You will get stderr messages about that unless OUT123_QUIET was was set, though. Failure to open the module directory is a serious error, resulting in negative return value.

namesaddress for storing list of names
descraddress for storing list of descriptions
number of drivers found, -1 on error

◆ out123_open()

MPG123_EXPORT int out123_open ( out123_handle ao,
const char *  driver,
const char *  device 

Open an output device with a certain driver Note: Opening means that the driver code is loaded and the desired device name recorded, possibly tested for availability or tentatively opened. After out123_open(), you can ask for supported encodings and then really open the device for playback with out123_start().

driver(comma-separated list of) output driver name(s to try), NULL for default (stdout for file-based drivers)
devicedevice name to open, NULL for default
0 on success, -1 on error.

◆ out123_driver_info()

MPG123_EXPORT int out123_driver_info ( out123_handle ao,
char **  driver,
char **  device 

Give info about currently loaded driver and device Any of the return addresses can be NULL if you are not interested in everything. You get pointers to internal storage. They are valid as long as the driver/device combination is opened. The device may be NULL indicating some unnamed default. TODO: Make the driver modules return names for such defaults.

driverreturn address for driver name
devicereturn address for device name
0 on success, -1 on error (i.e. no driver loaded)

◆ out123_close()

MPG123_EXPORT void out123_close ( out123_handle ao)

Close the current output device and driver. This implies out123_drain() to ensure no data is lost. With a buffer, that might cause considerable delay during which your main application is blocked waiting. Call out123_drop() beforehand if you want to end things quickly.


◆ out123_encodings()

MPG123_EXPORT int out123_encodings ( out123_handle ao,
long  rate,
int  channels 

Get supported audio encodings for given rate and channel count, for the currently openend audio device. TODO: Reopening the underlying audio device for each query is dumb, at least when dealing with JACK. It takes a long time and is just a waste. Reconsider that. Make sure that all output modules are fine with it, though! Usually, a wider range of rates is supported, but the number of sample encodings is limited, as is the number of channels. So you can call this with some standard rate and hope that the returned encodings work also for others, with the tested channel count. The return value of -1 on some encountered error conveniently also does not match any defined format (only 15 bits used for encodings, so this would even work with 16 bit integers). This implies out123_stop() to enter query mode.

ratesampling rate
channelsnumber of channels
supported encodings combined with bitwise or, to be checked against your favourite bitmask, -1 on error

◆ out123_encsize()

MPG123_EXPORT int out123_encsize ( int  encoding)

Return the size (in bytes) of one mono sample of the named encoding.

encodingThe encoding value to analyze.
positive size of encoding in bytes, 0 on invalid encoding.

◆ out123_formats()

MPG123_EXPORT int out123_formats ( out123_handle ao,
const long *  rates,
int  ratecount,
int  minchannels,
int  maxchannels,
struct mpg123_fmt **  fmtlist 

Get list of supported formats for currently opened audio device. Given a list of sampling rates and minimal/maximal channel count, this quickly checks what formats are supported with these constraints. The first entry is always reserved for a default format for the output device. If there is no such default, all values of the format are -1. For each requested combination of rate and channels, a format entry is created, possible with encoding value 0 to indicate that this combination has been tested and rejected. So, when there is no basic error, the number of returned format entries should be (ratecount*(maxchannels-minchannels+1)+1) . But instead of forcing you to guess, this will be allocated by successful run. For the first entry, the encoding member is supposed to be a definite encoding, for the others it is a bitwise combination of all possible encodings. This function is more efficient than many calls to out123_encodings().

ratespointer to an array of sampling rates, may be NULL for none
ratecountnumber of provided sampling rates
minchannelsminimal channel count
maxchannelsmaximal channel count
fmtlistreturn address for array of supported formats the encoding field of each entry is a combination of all supported encodings at this rate and channel count; Memory shall be freed by user.
number of returned format enries, -1 on error

◆ out123_enc_list()

MPG123_EXPORT int out123_enc_list ( int **  enclist)

Get list of encodings known to the library. You are responsible for freeing the allocated array.

enclistreturn address for allocated array of encoding codes
number of encodings, -1 on error

◆ out123_enc_byname()

MPG123_EXPORT int out123_enc_byname ( const char *  name)

Find encoding code by name.

nameshort or long name to find encoding code for
encoding if found (enum mpg123_enc_enum), else 0

◆ out123_enc_name()

MPG123_EXPORT const char* out123_enc_name ( int  encoding)

Get name of encoding.

encodingcode (enum mpg123_enc_enum)
short name for valid encodings, NULL otherwise

◆ out123_enc_longname()

MPG123_EXPORT const char* out123_enc_longname ( int  encoding)

Get long name of encoding.

encodingcode (enum mpg123_enc_enum)
long name for valid encodings, NULL otherwise

◆ out123_start()

MPG123_EXPORT int out123_start ( out123_handle ao,
long  rate,
int  channels,
int  encoding 

Start playback with a certain output format It might be a good idea to have audio data handy to feed after this returns with success. Rationale for not taking a pointer to struct mpg123_fmt: This would always force you to deal with that type and needlessly enlarge the shortest possible program.

encodingsample encoding (values matching libmpg123 API)
channelsnumber of channels (1 or 2, usually)
ratesampling rate
0 on success, negative on error (bad format, usually)

◆ out123_pause()

MPG123_EXPORT void out123_pause ( out123_handle ao)

Pause playback Interrupt playback, holding any data in the optional buffer.

This closes the audio device if it is a live sink, ready to be re-opened by out123_continue() or out123_play() with the existing parameters.


◆ out123_continue()

MPG123_EXPORT void out123_continue ( out123_handle ao)

Continue playback The counterpart to out123_pause(). Announce to the driver that playback shall continue.

Playback might not resume immediately if the optional buffer is configured to wait for a minimum fill and close to being empty. You can force playback of the last scrap with out123_drain(), or just by feeding more data with out123_play(), which will trigger out123_continue() for you, too.


◆ out123_stop()

MPG123_EXPORT void out123_stop ( out123_handle ao)

Stop playback. This waits for pending audio data to drain to the speakers. You might want to call out123_drop() before stopping if you want to end things right away.


◆ out123_play()

MPG123_EXPORT size_t out123_play ( out123_handle ao,
void *  buffer,
size_t  bytes 

Hand over data for playback and wait in case audio device is busy. This survives non-fatal signals like SIGSTOP/SIGCONT and keeps on playing until the buffer is done with if the flag OUT123_KEEP_PLAYING ist set (default). So, per default, if you provided a byte count divisible by the PCM frame size, it is an error when less bytes than given are played. To be sure if an error occured, check out123_errcode(). Also note that it is no accident that the buffer parameter is not marked as constant. Some output drivers might need to do things like swap byte order. This is done in-place instead of wasting memory on yet another copy. Software muting also overwrites the data.

bufferpointer to raw audio data to be played
bytesnumber of bytes to read from the buffer
number of bytes played (might be less than given, even zero)

◆ out123_drop()

MPG123_EXPORT void out123_drop ( out123_handle ao)

Drop any buffered data, making next provided data play right away. This does not imply an actual pause in playback. You are expected to play something, unless you called out123_pause(). Feel free to call out123_stop() afterwards instead for a quicker exit than the implied out123_drain(). For live sinks, this may include dropping data from their buffers. For others (files), this only concerns data in the optional buffer.


◆ out123_drain()

MPG123_EXPORT void out123_drain ( out123_handle ao)

Drain the output, waiting until all data went to the hardware. This does imply out123_continue() before and out123_pause() after draining. This might involve only the optional buffer process, or the buffers on the audio driver side, too.


◆ out123_ndrain()

MPG123_EXPORT void out123_ndrain ( out123_handle ao,
size_t  bytes 

Drain the output, but only partially up to the given number of bytes. This gives you the opportunity to do something while the optional buffer is writing remaining data instead of having one atomic API call for it all.

It is wholly expected that the return value of out123_buffered() before and after calling this has a bigger difference than the provided limit, as the buffer is writing all the time in the background.

This is just a plain out123_drain() if the optional buffer is not in use. Also triggers out123_continue(), but only out123_pause() if there is no buffered data anymore.

byteslimit of buffered bytes to drain
number of bytes drained from buffer

◆ out123_buffered()

MPG123_EXPORT size_t out123_buffered ( out123_handle ao)

Get an indication of how many bytes reside in the optional buffer. This might get extended to tell the number of bytes queued up in the audio backend, too.

number of bytes in out123 library buffer

◆ out123_getformat()

MPG123_EXPORT int out123_getformat ( out123_handle ao,
long *  rate,
int *  channels,
int *  encoding,
int *  framesize 

Extract currently used audio format from handle. matching mpg123_getformat(). Given return addresses may be NULL to indicate no interest.

rateaddress for sample rate
channelsaddress for channel count
encodingaddress for encoding
framesizesize of a full PCM frame (for convenience)
0 on success, -1 on error
Hopefully valid HTML! Valid CSS!