download : svn :: features :: sf.net project - bug tracker :: news archive

libmpg123 API :: testing :: benchmarking :: faq :: links :: contact

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 and the overall NEWS file on libmpg123 versions and important changes between them.
Let me emphasize that the policy for libmpg123 is to always stay backwards compatible -- only additions are planned (and it's not yet planned to change the plans;-).

mpg123 output audio format

Enumerations
enum	mpg123_enc_enum {   MPG123_ENC_8 = 0x00f, MPG123_ENC_16 = 0x040,   MPG123_ENC_32 = 0x100, MPG123_ENC_SIGNED = 0x080,   MPG123_ENC_FLOAT = 0xe00, MPG123_ENC_SIGNED_16 = (MPG123_ENC_16|MPG123_ENC_SIGNED|0x10),   MPG123_ENC_UNSIGNED_16 = (MPG123_ENC_16|0x20), MPG123_ENC_UNSIGNED_8 = 0x01,   MPG123_ENC_SIGNED_8 = (MPG123_ENC_SIGNED|0x02), MPG123_ENC_ULAW_8 = 0x04,   MPG123_ENC_ALAW_8 = 0x08, MPG123_ENC_SIGNED_32 = MPG123_ENC_32|MPG123_ENC_SIGNED|0x1000,   MPG123_ENC_UNSIGNED_32 = MPG123_ENC_32|0x2000, MPG123_ENC_FLOAT_32 = 0x200,   MPG123_ENC_FLOAT_64 = 0x400, MPG123_ENC_ANY }
enum	mpg123_channelcount { MPG123_MONO = 1, MPG123_STEREO = 2 }
Functions
void	mpg123_rates (const long **list, size_t *number)
void	mpg123_encodings (const int **list, size_t *number)
int	mpg123_format_none (mpg123_handle *mh)
int	mpg123_format_all (mpg123_handle *mh)
int	mpg123_format (mpg123_handle *mh, long rate, int channels, int encodings)
int	mpg123_format_support (mpg123_handle *mh, long rate, int encoding)
int	mpg123_getformat (mpg123_handle *mh, long *rate, int *channels, int *encoding)

---

Detailed Description

Functions to get and select the format of the decoded audio.

---

Enumeration Type Documentation

enum mpg123_enc_enum

An enum over all sample types possibly known to mpg123. The values are designed as bit flags to allow bitmasking for encoding families.

Note that (your build of) libmpg123 does not necessarily support all these. Usually, you can expect the 8bit encodings and signed 16 bit. Also 32bit float will be usual beginning with mpg123-1.7.0 . What you should bear in mind is that (SSE, etc) optimized routines are just for signed 16bit (and 8bit derived from that). Other formats use plain C code.

All formats are in native byte order. On a little endian machine this should mean that you can just feed the MPG123_ENC_SIGNED_32 data to common 24bit hardware that ignores the lowest byte (or you could choose to do rounding with these lower bits).

Enumerator:

MPG123_ENC_8	0000 0000 1111 Some 8 bit integer encoding.
MPG123_ENC_16	0000 0100 0000 Some 16 bit integer encoding.
MPG123_ENC_32	0001 0000 0000 Some 32 bit integer encoding.
MPG123_ENC_SIGNED	0000 1000 0000 Some signed integer encoding.
MPG123_ENC_FLOAT	1110 0000 0000 Some float encoding.
MPG123_ENC_SIGNED_16	1101 0000 signed 16 bit
MPG123_ENC_UNSIGNED_16	0110 0000 unsigned 16 bit
MPG123_ENC_UNSIGNED_8	0000 0001 unsigned 8 bit
MPG123_ENC_SIGNED_8	1000 0010 signed 8 bit
MPG123_ENC_ULAW_8	0000 0100 ulaw 8 bit
MPG123_ENC_ALAW_8	0000 1000 alaw 8 bit
MPG123_ENC_SIGNED_32	0001 0001 1000 0000 signed 32 bit
MPG123_ENC_UNSIGNED_32	0010 0001 0000 0000 unsigned 32 bit
MPG123_ENC_FLOAT_32	0010 0000 0000 32bit float
MPG123_ENC_FLOAT_64	0100 0000 0000 64bit float
MPG123_ENC_ANY	any encoding

Definition at line 284 of file mpg123.h.

enum mpg123_channelcount

They can be combined into one number (3) to indicate mono and stereo...

Definition at line 308 of file mpg123.h.

---

Function Documentation

void mpg123_rates	(	const long **	list,
		size_t *	number
	)

An array of supported standard sample rates These are possible native sample rates of MPEG audio files. You can still force mpg123 to resample to a different one, but by default you will only get audio in one of these samplings.

Parameters:

	list	Store a pointer to the sample rates array there.
	number	Store the number of sample rates there.

void mpg123_encodings	(	const int **	list,
		size_t *	number
	)

An array of supported audio encodings. An audio encoding is one of the fully qualified members of mpg123_enc_enum (MPG123_ENC_SIGNED_16, not MPG123_SIGNED).

Parameters:

	list	Store a pointer to the encodings array there.
	number	Store the number of encodings there.

int mpg123_format_none

(

mpg123_handle *

mh

)

Configure a mpg123 handle to accept no output format at all, use before specifying supported formats with mpg123_format

int mpg123_format_all

(

mpg123_handle *

mh

)

Configure mpg123 handle to accept all formats (also any custom rate you may set) -- this is default.

int mpg123_format	(	mpg123_handle *	mh,
		long	rate,
		int	channels,
		int	encodings
	)

Set the audio format support of a mpg123_handle in detail:

Parameters:

	mh	audio decoder handle
	rate	The sample rate value (in Hertz).
	channels	A combination of MPG123_STEREO and MPG123_MONO.
	encodings	A combination of accepted encodings for rate and channels, p.ex MPG123_ENC_SIGNED16 | MPG123_ENC_ULAW_8 (or 0 for no support). Please note that some encodings may not be supported in the library build and thus will be ignored here.

Returns:

MPG123_OK on success, MPG123_ERR if there was an error.

int mpg123_format_support	(	mpg123_handle *	mh,
		long	rate,
		int	encoding
	)

Check to see if a specific format at a specific rate is supported by mpg123_handle.

Returns:

0 for no support (that includes invalid parameters), MPG123_STEREO, MPG123_MONO or MPG123_STEREO|MPG123_MONO.

int mpg123_getformat	(	mpg123_handle *	mh,
		long *	rate,
		int *	channels,
		int *	encoding
	)

Get the current output format written to the addresses givenr.

---