# 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;-).
Macros | Typedefs | Enumerations | Functions
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. More...

## 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_NOT_SUPPORTED, OUT123_DEV_ENUMERATE, OUT123_ERRCOUNT }

## Functions
const MPG123_EXPORT char * | out123_distversion (unsigned int *major, unsigned int *minor, unsigned int *patch)
MPG123_EXPORT unsigned int | out123_libversion (unsigned int *patch)
MPG123_EXPORT out123_handle * | out123_new (void)
MPG123_EXPORT void | out123_del (out123_handle *ao)
MPG123_EXPORT void | out123_free (void *ptr)
const MPG123_EXPORT char * | out123_strerror (out123_handle *ao)
MPG123_EXPORT int | out123_errcode (out123_handle *ao)
const MPG123_EXPORT 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_param2 (out123_handle *ao, int 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_getparam2 (out123_handle *ao, int 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_devices (out123_handle *ao, const char *driver, char ***names, char ***descr, char **active_driver)
MPG123_EXPORT void | out123_stringlists_free (char **name, char **descr, int count)
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)
const MPG123_EXPORT char * | out123_enc_name (int encoding)
const MPG123_EXPORT 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.

Note that the driver modules that bind to the operating system API for output might impose restrictions on what you can safely do regarding your out123_handle and multiple threads or processes. You should be on the safe side ensuring that you confine usage of a handle to a single thread instead of passing it around.

## Macro Definition Documentation

## ◆ out123_param_int

#define out123_param_int | ( |  | ao,
|  |  | code,
|  |  | value
| ) |  | out123_param((ao), (code), (value), 0., NULL)

Shortcut for out123_param() to set an integer parameter.

Definition at line 355 of file out123.h.

## ◆ out123_param_float

#define out123_param_float | ( |  | ao,
|  |  | code,
|  |  | value
| ) |  | out123_param((ao), (code), 0, (value), NULL)

Shortcut for out123_param() to set a float parameter.

Definition at line 358 of file out123.h.

## ◆ out123_param_string

#define out123_param_string | ( |  | ao,
|  |  | code,
|  |  | value
| ) |  | out123_param((ao), (code), 0, 0., (value))

Shortcut for out123_param() to set an string parameter.

Definition at line 361 of file out123.h.

## ◆ out123_getparam_int

#define out123_getparam_int | ( |  | ao,
|  |  | code,
|  |  | value
| ) |  | out123_getparam((ao), (code), (value), NULL, NULL)

Shortcut for out123_getparam() to get an integer parameter.

Definition at line 401 of file out123.h.

## ◆ out123_getparam_float

#define out123_getparam_float | ( |  | ao,
|  |  | code,
|  |  | value
| ) |  | out123_getparam((ao), (code), NULL, (value), NULL)

Shortcut for out123_getparam() to get a float parameter.

Definition at line 404 of file out123.h.

## ◆ out123_getparam_string

#define out123_getparam_string | ( |  | ao,
|  |  | code,
|  |  | value
| ) |  | out123_getparam((ao), (code), NULL, NULL, (value))

Shortcut for out123_getparam() to get a string parameter.

Definition at line 407 of file out123.h.

## Typedef Documentation

## ◆ out123_handle

typedef struct out123_struct out123_handle

Typedef shortcut as preferrend name for the handle type.

Definition at line 119 of file out123.h.

## Enumeration Type Documentation

## ◆ out123_parms

enum 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 139 of file out123.h.

## ◆ out123_flags

enum 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 168 of file out123.h.

## ◆ out123_propflags

enum 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 188 of file out123.h.

## ◆ out123_error

enum 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_NOT_SUPPORTED | some requested operation is not supported (right now)
OUT123_DEV_ENUMERATE | device enumeration itself failed
OUT123_ERRCOUNT | placeholder for shaping arrays

Definition at line 227 of file out123.h.

## Function Documentation

## ◆ out123_distversion()

const MPG123_EXPORT char* out123_distversion | ( | unsigned int * | major,
|  | unsigned int * | minor,
|  | unsigned int * | patch
| ) |  |

Get version of the mpg123 distribution this library build came with. (optional means non-NULL)

Parameters

  major | optional address to store major version number
  minor | optional address to store minor version number
  patch | optional address to store patchlevel version number

Returns
  full version string (like "1.2.3-beta4 (experimental)")

## ◆ out123_libversion()

MPG123_EXPORT unsigned int out123_libversion | ( | unsigned int * | patch | ) |

Get API version of library build.

Parameters

  patch | optional address to store patchlevel

Returns
  API version of library

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

const MPG123_EXPORT char* out123_strerror | ( | out123_handle * | ao | ) |

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

Parameters

  ao | handle

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

  ao | handle

Returns
  error code recorded in handle or OUT123_BAD_HANDLE

## ◆ out123_plain_strerror()

const MPG123_EXPORT char* out123_plain_strerror | ( | int | errcode | ) |

Return the error string for a given error code.

Parameters

  errcode | the 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

  ao | handle
  buffer_bytes | size (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 parameter on a out123_handle.

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

The parameters usually only change what happens on next out123_open, not incfluencing running operation. There are macros To ease the API a bit: You can call out123_param_int(ao, code, value) for integer (long) values, same with out123_param_float() and out123_param_string().

Parameters

  ao | handle
  code | parameter code
  value | input value for integer parameters
  fvalue | input value for floating point parameters
  svalue | input value for string parameters (contens are copied)

Returns
  0 on success, OUT123_ERR on error.

## ◆ out123_param2()

MPG123_EXPORT int out123_param2 | ( | out123_handle * | ao,
|  | int | code,
|  | long | value,
|  | double | fvalue,
|  | const char * | svalue
| ) |  |

Set a parameter on a out123_handle. No enum.

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

The parameters usually only change what happens on next out123_open, not incfluencing running operation. There are macros To ease the API a bit: You can call out123_param_int(ao, code, value) for integer (long) values, same with out123_param_float() and out123_param_string().

Parameters

  ao | handle
  code | parameter code (from enum out123_parms)
  value | input value for integer parameters
  fvalue | input value for floating point parameters
  svalue | input 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 parameter from an out123_handle.

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

Parameters

  ao | handle
  code | parameter code
  ret_value | output address for integer parameters
  ret_fvalue | output address for floating point parameters
  ret_svalue | output 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_getparam2()

MPG123_EXPORT int out123_getparam2 | ( | out123_handle * | ao,
|  | int | code,
|  | long * | ret_value,
|  | double * | ret_fvalue,
|  | char ** | ret_svalue
| ) |  |

Get a parameter from an out123_handle. No enum.

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

Parameters

  ao | handle
  code | parameter code (from enum out123_parms)
  ret_value | output address for integer parameters
  ret_fvalue | output address for floating point parameters
  ret_svalue | output 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

  ao | handle
  from_ao | the 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. There is out123_stringlists_free() to assist.

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

  ao | handle
  names | address for storing list of names
  descr | address for storing list of descriptions

Returns
  number of drivers found, -1 on error

## ◆ out123_devices()

MPG123_EXPORT int out123_devices | ( | out123_handle * | ao,
|  | const char * | driver,
|  | char *** | names,
|  | char *** | descr,
|  | char ** | active_driver
| ) |  |

Get a list of available output devices for a given driver.

If the driver supports enumeration, you can get a listing of possible output devices. If this list is exhaustive, depends on the driver. Note that this implies out123_close(). When you have a device already open, you don't need to look for one anymore. If you really do, just create another handle.

Your provided pointers are only used for non-negative return values. In this case, you are responsible for freeing the associated memory of the strings and the lists themselves. The format of the lists is an array of char pointers, with the returned count just like the usual C argv and argc. There is out123_stringlists_free() to assist.

Note: Calling this on a handle with a configured buffer process will yield OUT123_NOT_SUPPORTED.

Parameters

  ao | handle
  driver | driver name or comma-separated list of names to try, just like for out123_open(), possibly NULL for some default
  names | address for storing list of names
  descr | address for storing list of descriptions
  active_driver | address for storing a copy of the actually active driver name (in case you gave a list or NULL as driver), can be NULL if not interesting

Returns
  count of devices or OUT123_ERR if some error was encountered, possibly just OUT123_NOT_SUPPORTED if the driver lacks enumeration support

## ◆ out123_stringlists_free()

MPG123_EXPORT void out123_stringlists_free | ( | char ** | name,
|  | char ** | descr,
|  | int | count
| ) |  |

Helper to free string list memory.

This aids in freeing the memory allocated by out123_devices() and out123_drivers().

Any of the given lists can be NULL and nothing will happen to it.

Parameters

  name | first string list
  descr | second string list
  count | count of strings

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

  ao | handle
  driver | (comma-separated list of) output driver name(s to try), NULL for default
  device | device name to open, NULL for default (stdout for file-based drivers)

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

  ao | handle
  driver | return address for driver name
  device | return 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

  ao | handle

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

  ao | handle
  rate | sampling rate
  channels | number 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

  encoding | The 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

  ao | handle
  rates | pointer to an array of sampling rates, may be NULL for none
  ratecount | number of provided sampling rates
  minchannels | minimal channel count
  maxchannels | maximal channel count
  fmtlist | return 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

  enclist | return 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

  name | short or long name to find encoding code for

Returns
  encoding if found (enum mpg123_enc_enum), else 0

## ◆ out123_enc_name()

const MPG123_EXPORT char* out123_enc_name | ( | int | encoding | ) |

Get name of encoding.

Parameters

  encoding | code (enum mpg123_enc_enum)

Returns
  short name for valid encodings, NULL otherwise

## ◆ out123_enc_longname()

const MPG123_EXPORT char* out123_enc_longname | ( | int | encoding | ) |

Get long name of encoding.

Parameters

  encoding | code (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

  ao | handle
  encoding | sample encoding (values matching libmpg123 API)
  channels | number of channels (1 or 2, usually)
  rate | sampling 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

  ao | handle

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

  ao | handle

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

  ao | handle

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

  ao | handle
  buffer | pointer to raw audio data to be played
  bytes | number 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

  ao | handle

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

  ao | handle

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

  ao | handle
  bytes | limit 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

  ao | handle

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

  ao | handle
  rate | address for sample rate
  channels | address for channel count
  encoding | address for encoding
  framesize | size of a full PCM frame (for convenience)

Returns
  0 on success, -1 on error