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

Macros

#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))
 

Typedefs

typedef struct out123_struct out123_handle
 

Enumerations

enum  out123_parms {
  OUT123_FLAGS = 1, OUT123_PRELOAD,
  OUT123_GAIN, OUT123_VERBOSE,
  OUT123_DEVICEBUFFER, OUT123_PROPFLAGS,
  OUT123_NAME, OUT123_BINDIR,
  OUT123_ADD_FLAGS, OUT123_REMOVE_FLAGS
}
 
enum  out123_flags {
  OUT123_HEADPHONES = 0x01, OUT123_INTERNAL_SPEAKER = 0x02,
  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,
  OUT123_DOOM, OUT123_BAD_DRIVER_NAME,
  OUT123_BAD_DRIVER, OUT123_NO_DRIVER,
  OUT123_NOT_LIVE, OUT123_DEV_PLAY,
  OUT123_DEV_OPEN, OUT123_BUFFER_ERROR,
  OUT123_MODULE_ERROR, OUT123_ARG_ERROR,
  OUT123_BAD_PARAM, OUT123_SET_RO_PARAM,
  OUT123_BAD_HANDLE, OUT123_ERRCOUNT
}
 

Functions

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.

Enumerator
OUT123_FLAGS 

integer, various flags, see enum out123_flags

OUT123_PRELOAD 

float, fraction of buffer to fill before playback

OUT123_GAIN 

integer, output device gain (module-specific)

OUT123_VERBOSE 

integer, verbosity to stderr, >= 0

OUT123_DEVICEBUFFER 

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.

OUT123_PROPFLAGS 

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

OUT123_NAME 

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.

OUT123_BINDIR 

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.

OUT123_ADD_FLAGS 

enable given flags

OUT123_REMOVE_FLAGS 

disable diven flags

Definition at line 96 of file out123.h.

◆ out123_flags

Flags to tune out123 behaviour

Enumerator
OUT123_HEADPHONES 

output to headphones (if supported)

OUT123_INTERNAL_SPEAKER 

output to speaker (if supported)

OUT123_LINE_OUT 

output to line out (if supported)

OUT123_QUIET 

no printouts to standard error

OUT123_KEEP_PLAYING 

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.

OUT123_MUTE 

software mute (play silent audio)

Definition at line 125 of file out123.h.

◆ out123_propflags

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

Enumerator
OUT123_PROP_LIVE 

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.

OUT123_PROP_PERSISTENT 

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.

Enumerator
OUT123_ERR 

generic alias for verbosity, always == -1

OUT123_OK 

just a name for zero, not going to change

OUT123_DOOM 

dazzled, out of memory

OUT123_BAD_DRIVER_NAME 

bad driver name given

OUT123_BAD_DRIVER 

unspecified issue loading a driver

OUT123_NO_DRIVER 

no driver loaded

OUT123_NOT_LIVE 

no active audio device

OUT123_DEV_PLAY 

some device playback error

OUT123_DEV_OPEN 

error opening device

OUT123_BUFFER_ERROR 

Some (really unexpected) error in buffer infrastructure.

OUT123_MODULE_ERROR 

basic failure in module loading

OUT123_ARG_ERROR 

some bad function arguments supplied

OUT123_BAD_PARAM 

unknown parameter code

OUT123_SET_RO_PARAM 

attempt to set read-only parameter

OUT123_BAD_HANDLE 

bad handle pointer (NULL, usually)

OUT123_ERRCOUNT 

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.

Returns
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.

Parameters
aohandle
Returns
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 .

Parameters
aohandle
Returns
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.

Parameters
errcodethe integer error code
Returns
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.

Parameters
aohandle
buffer_bytessize (bytes) of a memory buffer for decoded audio, a value of zero disables the buffer.
Returns
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.

Parameters
aohandle
codeparameter code
valueinput value for integer parameters
fvalueinput value for floating point parameters
svalueinput value for string parameters (contens are copied)
Returns
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.

Parameters
aohandle
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)
Returns
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.

Parameters
aohandle
from_aothe handle to copy parameters from
Returns
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.

Parameters
aohandle
namesaddress for storing list of names
descraddress for storing list of descriptions
Returns
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().

Parameters
aohandle
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
Returns
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.

Parameters
aohandle
driverreturn address for driver name
devicereturn address for device name
Returns
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.

Parameters
aohandle

◆ 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.

Parameters
aohandle
ratesampling rate
channelsnumber of channels
Returns
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.

Parameters
encodingThe encoding value to analyze.
Returns
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().

Parameters
aohandle
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.
Returns
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.

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

◆ out123_enc_byname()

MPG123_EXPORT int out123_enc_byname ( const char *  name)

Find encoding code by name.

Parameters
nameshort or long name to find encoding code for
Returns
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.

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

◆ out123_enc_longname()

MPG123_EXPORT const char* out123_enc_longname ( int  encoding)

Get long name of encoding.

Parameters
encodingcode (enum mpg123_enc_enum)
Returns
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.

Parameters
aohandle
encodingsample encoding (values matching libmpg123 API)
channelsnumber of channels (1 or 2, usually)
ratesampling rate
Returns
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.

Parameters
aohandle

◆ 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.

Parameters
aohandle

◆ 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.

Parameters
aohandle

◆ 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.

Parameters
aohandle
bufferpointer to raw audio data to be played
bytesnumber of bytes to read from the buffer
Returns
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.

Parameters
aohandle

◆ 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.

Parameters
aohandle

◆ 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.

Parameters
aohandle
byteslimit of buffered bytes to drain
Returns
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.

Parameters
aohandle
Returns
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.

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