You could access this page securely.

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 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;-).
mpg123 PCM sample encodings


struct  mpg123_fmt


#define MPG123_SAMPLESIZE(enc)
#define MPG123_ZEROSAMPLE(enc, siz, off)


enum  mpg123_enc_enum {
  MPG123_ENC_8 = 0x00f, MPG123_ENC_16 = 0x040,
  MPG123_ENC_24 = 0x4000, 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_SIGNED_24 = MPG123_ENC_24|MPG123_ENC_SIGNED|0x1000, MPG123_ENC_UNSIGNED_24 = MPG123_ENC_24|0x2000,
  MPG123_ENC_FLOAT_32 = 0x200, MPG123_ENC_FLOAT_64 = 0x400,

Detailed Description

These are definitions for audio formats used by libmpg123 and libout123.

Macro Definition Documentation


#define MPG123_SAMPLESIZE (   enc)
( \
(enc) < 1 \
? 0 \
: ( (enc) & MPG123_ENC_8 \
? 1 \
: ( (enc) & MPG123_ENC_16 \
? 2 \
: ( (enc) & MPG123_ENC_24 \
? 3 \
: ( ( (enc) & MPG123_ENC_32 \
|| (enc) == MPG123_ENC_FLOAT_32 ) \
? 4 \
: ( (enc) == MPG123_ENC_FLOAT_64 \
? 8 \
: 0 \
) ) ) ) ) )

Get size of one PCM sample with given encoding. This is included both in libmpg123 and libout123. Both offer an API function to provide the macro results from library compile-time, not that of you application. This most likely does not matter as I do not expect any fresh PCM sample encoding to appear. But who knows? Perhaps the encoding type will be abused for funny things in future, not even plain PCM. And, by the way: Thomas really likes the ?: operator.

encthe encoding (mpg123_enc_enum value)
size of one sample in bytes

Definition at line 101 of file fmt123.h.


#define MPG123_ZEROSAMPLE (   enc,
( \
(enc) == MPG123_ENC_ULAW_8 \
? (off == 0 ? 0xff : 0x00) \
: ( (enc) == MPG123_ENC_ALAW_8 \
? (off == 0 ? 0xd5 : 0x00) \
: ( (((enc) & (MPG123_ENC_SIGNED|MPG123_ENC_FLOAT)) || (siz) != ((off)+1)) \
? 0x00 \
: 0x80 \
) ) )

Representation of zero in differing encodings. This exists to define proper silence in various encodings without having to link to libsyn123 to do actual conversions at runtime. You have to handle big/little endian order yourself, though. This takes the shortcut that any signed encoding has a zero with all-zero bits. Unsigned linear encodings just have the highest bit set (2^(n-1) for n bits), while the nonlinear 8-bit ones are special.

encthe encoding (mpg123_enc_enum value)
sizbytes per sample (return value of MPG123_SAMPLESIZE(enc))
offbyte (octet) offset counted from LSB
unsigned byte value for the designated octet

Definition at line 130 of file fmt123.h.

Enumeration Type Documentation

◆ 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. This is also why the enum is not used as type for actual encoding variables, plain integers (at least 16 bit, 15 bit being used) cover the possible combinations of these flags.

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 may be absent for some formats. We do have SSE for 16, 32 bit and float, though. 24 bit integer is done via postprocessing of 32 bit output – just cutting the last byte, no rounding, even. If you want better, do it yourself.

All formats are in native byte order. If you need different endinaness, you can simply postprocess the output buffers (libmpg123 wouldn't do anything else). The macro MPG123_SAMPLESIZE() can be helpful there.

Definition at line 43 of file fmt123.h.

Hopefully valid HTML! Valid CSS!