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
MPG123_EXPORT const 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)

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

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.

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 1 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()

MPG123_EXPORT const 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()

MPG123_EXPORT const 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()

MPG123_EXPORT const 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()

MPG123_EXPORT const 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()

MPG123_EXPORT const 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

API documentation for libmpg123, libout123, and libsyn123

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ out123_param_int

◆ out123_param_float

◆ out123_param_string

◆ out123_getparam_int

◆ out123_getparam_float

◆ out123_getparam_string

Typedef Documentation

◆ out123_handle

Enumeration Type Documentation

◆ out123_parms

◆ out123_flags

◆ out123_propflags

◆ out123_error

Function Documentation

◆ out123_distversion()

◆ out123_libversion()

◆ out123_new()

◆ out123_del()

◆ out123_free()

◆ out123_strerror()

◆ out123_errcode()

◆ out123_plain_strerror()

◆ out123_set_buffer()

◆ out123_param()

◆ out123_param2()

◆ out123_getparam()

◆ out123_getparam2()

◆ out123_param_from()

◆ out123_drivers()

◆ out123_devices()

◆ out123_stringlists_free()

◆ out123_open()

◆ out123_driver_info()

◆ out123_close()

◆ out123_encodings()

◆ out123_encsize()

◆ out123_formats()

◆ out123_enc_list()

◆ out123_enc_byname()

◆ out123_enc_name()

◆ out123_enc_longname()

◆ out123_start()

◆ out123_pause()

◆ out123_continue()

◆ out123_stop()

◆ out123_play()

◆ out123_drop()

◆ out123_drain()

◆ out123_ndrain()

◆ out123_buffered()

◆ out123_getformat()