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;-).
mpg123 file input and decoding

Functions

MPG123_EXPORT int mpg123_open_fixed (mpg123_handle *mh, const char *path, int channels, int encoding)
 
MPG123_EXPORT int mpg123_open (mpg123_handle *mh, const char *path)
 
MPG123_EXPORT int mpg123_open_fd (mpg123_handle *mh, int fd)
 
MPG123_EXPORT int mpg123_open_handle (mpg123_handle *mh, void *iohandle)
 
MPG123_EXPORT int mpg123_open_feed (mpg123_handle *mh)
 
MPG123_EXPORT int mpg123_close (mpg123_handle *mh)
 
MPG123_EXPORT int mpg123_read (mpg123_handle *mh, void *outmemory, size_t outmemsize, size_t *done)
 
MPG123_EXPORT int mpg123_feed (mpg123_handle *mh, const unsigned char *in, size_t size)
 
MPG123_EXPORT int mpg123_decode (mpg123_handle *mh, const unsigned char *inmemory, size_t inmemsize, void *outmemory, size_t outmemsize, size_t *done)
 
MPG123_EXPORT int mpg123_decode_frame (mpg123_handle *mh, off_t *num, unsigned char **audio, size_t *bytes)
 
MPG123_EXPORT int mpg123_framebyframe_decode (mpg123_handle *mh, off_t *num, unsigned char **audio, size_t *bytes)
 
MPG123_EXPORT int mpg123_decode_frame64 (mpg123_handle *mh, int64_t *num, unsigned char **audio, size_t *bytes)
 
MPG123_EXPORT int mpg123_framebyframe_decode64 (mpg123_handle *mh, int64_t *num, unsigned char **audio, size_t *bytes)
 
MPG123_EXPORT int mpg123_framebyframe_next (mpg123_handle *mh)
 
MPG123_EXPORT int mpg123_framedata (mpg123_handle *mh, unsigned long *header, unsigned char **bodydata, size_t *bodybytes)
 
MPG123_EXPORT off_t mpg123_framepos (mpg123_handle *mh)
 
MPG123_EXPORT int64_t mpg123_framepos64 (mpg123_handle *mh)
 

Detailed Description

Functions for input bitstream and decoding operations. Decoding/seek functions may also return message codes MPG123_DONE, MPG123_NEW_FORMAT and MPG123_NEED_MORE (please read up on these on how to react!).

Function Documentation

◆ mpg123_open_fixed()

MPG123_EXPORT int mpg123_open_fixed ( mpg123_handle mh,
const char *  path,
int  channels,
int  encoding 
)

Open a simple MPEG file with fixed properties.

This function shall simplify the common use case of a plain MPEG file on disk that you want to decode, with one fixed sample rate and channel count, and usually a length defined by a Lame/Info/Xing tag. It will:

  • set the MPG123_NO_FRANKENSTEIN flag
  • set up format support according to given parameters,
  • open the file,
  • query audio format,
  • fix the audio format support table to ensure the format stays the same,
  • call mpg123_scan() if there is no header frame to tell the track length.

From that on, you can call mpg123_getformat() for querying the sample rate (and channel count in case you allowed both) and mpg123_length() to get a pretty safe number for the duration. Only the sample rate is left open as that indeed is a fixed property of MPEG files. You could set MPG123_FORCE_RATE beforehand, but that may trigger low-quality resampling in the decoder, only do so if in dire need. The library will convert mono files to stereo for you, and vice versa. If any constraint cannot be satisified (most likely because of a non-default build of libmpg123), you get MPG123_ERR returned and can query the detailed cause from the handle. Only on MPG123_OK there will an open file that you then close using mpg123_close(), or implicitly on mpg123_delete() or the next call to open another file.

So, for your usual CD rip collection, you could use

mpg123_open_fixed(mh, path, MPG123_STEREO, MPG123_ENC_SIGNED_16)

and be happy calling mpg123_getformat() to verify 44100 Hz rate, then just playing away with mpg123_read(). The occasional mono file, or MP2 file, will also be decoded without you really noticing. Just the speed could be wrong if you do not care about sample rate at all.

Parameters
mhhandle
pathfilesystem path (see mpg123_open())
channelsallowed channel count, either 1 (MPG123_MONO) or 2 (MPG123_STEREO), or bitwise or of them, but then you're halfway back to calling mpg123_format() again;-)
encodinga definite encoding from enum mpg123_enc_enum or a bitmask like for mpg123_format(), defeating the purpose somewhat

◆ mpg123_open()

MPG123_EXPORT int mpg123_open ( mpg123_handle mh,
const char *  path 
)

Open and prepare to decode the specified file by filesystem path. This does not open HTTP urls; libmpg123 contains no networking code. If you want to decode internet streams, use mpg123_open_fd() or mpg123_open_feed().

The path parameter usually is just a string that is handed to the underlying OS routine for opening, treated as a blob of binary data. On platforms where encoding needs to be involved, something like _wopen() is called underneath and the path argument to libmpg123 is assumed to be encoded in UTF-8. So, if you have to ask yourself which encoding is needed, the answer is UTF-8, which also fits any sane modern install of Unix-like systems.

Parameters
mhhandle
pathfilesystem
Returns
MPG123_OK on success

◆ mpg123_open_fd()

MPG123_EXPORT int mpg123_open_fd ( mpg123_handle mh,
int  fd 
)

Use an already opened file descriptor as the bitstream input mpg123_close() will not close the file descriptor.

Parameters
mhhandle
fdfile descriptor
Returns
MPG123_OK on success

◆ mpg123_open_handle()

MPG123_EXPORT int mpg123_open_handle ( mpg123_handle mh,
void *  iohandle 
)

Use an opaque handle as bitstream input. This works only with the replaced I/O from mpg123_replace_reader_handle() or mpg123_reader64()! mpg123_close() will call the cleanup callback for your non-NULL handle (if you gave one).

Parameters
mhhandle
iohandleyour handle
Returns
MPG123_OK on success

◆ mpg123_open_feed()

MPG123_EXPORT int mpg123_open_feed ( mpg123_handle mh)

Open a new bitstream and prepare for direct feeding This works together with mpg123_decode(); you are responsible for reading and feeding the input bitstream. Also, you are expected to handle ICY metadata extraction yourself. This input method does not handle MPG123_ICY_INTERVAL. It does parse ID3 frames, though.

Parameters
mhhandle
Returns
MPG123_OK on success

◆ mpg123_close()

MPG123_EXPORT int mpg123_close ( mpg123_handle mh)

Closes the source, if libmpg123 opened it.

Parameters
mhhandle
Returns
MPG123_OK on success

◆ mpg123_read()

MPG123_EXPORT int mpg123_read ( mpg123_handle mh,
void *  outmemory,
size_t  outmemsize,
size_t *  done 
)

Read from stream and decode up to outmemsize bytes.

Note: The type of outmemory changed to a void pointer in mpg123 1.26.0 (API version 45).

Parameters
mhhandle
outmemoryaddress of output buffer to write to
outmemsizemaximum number of bytes to write
doneaddress to store the number of actually decoded bytes to
Returns
MPG123_OK or error/message code

◆ mpg123_feed()

MPG123_EXPORT int mpg123_feed ( mpg123_handle mh,
const unsigned char *  in,
size_t  size 
)

Feed data for a stream that has been opened with mpg123_open_feed(). It's give and take: You provide the bytestream, mpg123 gives you the decoded samples.

Parameters
mhhandle
ininput buffer
sizenumber of input bytes
Returns
MPG123_OK or error/message code.

◆ mpg123_decode()

MPG123_EXPORT int mpg123_decode ( mpg123_handle mh,
const unsigned char *  inmemory,
size_t  inmemsize,
void *  outmemory,
size_t  outmemsize,
size_t *  done 
)

Decode MPEG Audio from inmemory to outmemory. This is very close to a drop-in replacement for old mpglib. When you give zero-sized output buffer the input will be parsed until decoded data is available. This enables you to get MPG123_NEW_FORMAT (and query it) without taking decoded data. Think of this function being the union of mpg123_read() and mpg123_feed() (which it actually is, sort of;-). You can actually always decide if you want those specialized functions in separate steps or one call this one here.

Note: The type of outmemory changed to a void pointer in mpg123 1.26.0 (API version 45).

Parameters
mhhandle
inmemoryinput buffer
inmemsizenumber of input bytes
outmemoryoutput buffer
outmemsizemaximum number of output bytes
doneaddress to store the number of actually decoded bytes to
Returns
error/message code (watch out especially for MPG123_NEED_MORE)

◆ mpg123_decode_frame()

MPG123_EXPORT int mpg123_decode_frame ( mpg123_handle mh,
off_t *  num,
unsigned char **  audio,
size_t *  bytes 
)

Decode next MPEG frame to internal buffer or read a frame and return after setting a new format.

Parameters
mhhandle
numcurrent frame offset gets stored there
audioThis pointer is set to the internal buffer to read the decoded audio from.
bytesnumber of output bytes ready in the buffer
Returns
MPG123_OK or error/message code

◆ mpg123_framebyframe_decode()

MPG123_EXPORT int mpg123_framebyframe_decode ( mpg123_handle mh,
off_t *  num,
unsigned char **  audio,
size_t *  bytes 
)

Decode current MPEG frame to internal buffer. Warning: This is experimental API that might change in future releases! Please watch mpg123 development closely when using it.

Parameters
mhhandle
numlast frame offset gets stored there
audiothis pointer is set to the internal buffer to read the decoded audio from.
bytesnumber of output bytes ready in the buffer
Returns
MPG123_OK or error/message code

◆ mpg123_decode_frame64()

MPG123_EXPORT int mpg123_decode_frame64 ( mpg123_handle mh,
int64_t *  num,
unsigned char **  audio,
size_t *  bytes 
)

Decode next MPEG frame to internal buffer or read a frame and return after setting a new format.

Parameters
mhhandle
numcurrent frame offset gets stored there
audioThis pointer is set to the internal buffer to read the decoded audio from.
bytesnumber of output bytes ready in the buffer
Returns
MPG123_OK or error/message code

◆ mpg123_framebyframe_decode64()

MPG123_EXPORT int mpg123_framebyframe_decode64 ( mpg123_handle mh,
int64_t *  num,
unsigned char **  audio,
size_t *  bytes 
)

Decode current MPEG frame to internal buffer. Warning: This is experimental API that might change in future releases! Please watch mpg123 development closely when using it.

Parameters
mhhandle
numlast frame offset gets stored there
audiothis pointer is set to the internal buffer to read the decoded audio from.
bytesnumber of output bytes ready in the buffer
Returns
MPG123_OK or error/message code

◆ mpg123_framebyframe_next()

MPG123_EXPORT int mpg123_framebyframe_next ( mpg123_handle mh)

Find, read and parse the next mp3 frame Warning: This is experimental API that might change in future releases! Please watch mpg123 development closely when using it.

Parameters
mhhandle
Returns
MPG123_OK or error/message code

◆ mpg123_framedata()

MPG123_EXPORT int mpg123_framedata ( mpg123_handle mh,
unsigned long *  header,
unsigned char **  bodydata,
size_t *  bodybytes 
)

Get access to the raw input data for the last parsed frame. This gives you a direct look (and write access) to the frame body data. Together with the raw header, you can reconstruct the whole raw MPEG stream without junk and meta data, or play games by actually modifying the frame body data before decoding this frame (mpg123_framebyframe_decode()). A more sane use would be to use this for CRC checking (see mpg123_info() and MPG123_CRC), the first two bytes of the body make up the CRC16 checksum, if present. You can provide NULL for a parameter pointer when you are not interested in the value.

Parameters
mhhandle
headerthe 4-byte MPEG header
bodydatapointer to the frame body stored in the handle (without the header)
bodybytessize of frame body in bytes (without the header)
Returns
MPG123_OK if there was a yet un-decoded frame to get the data from, MPG123_BAD_HANDLE or MPG123_ERR otherwise (without further explanation, the error state of the mpg123_handle is not modified by this function).

◆ mpg123_framepos()

MPG123_EXPORT off_t mpg123_framepos ( mpg123_handle mh)

Get the input position (byte offset in stream) of the last parsed frame. This can be used for external seek index building, for example. It just returns the internally stored offset, regardless of validity – you ensure that a valid frame has been parsed before!

Parameters
mhhandle
Returns
byte offset in stream

◆ mpg123_framepos64()

MPG123_EXPORT int64_t mpg123_framepos64 ( mpg123_handle mh)

Get the 64 bit input position (byte offset in stream) of the last parsed frame. This can be used for external seek index building, for example. It just returns the internally stored offset, regardless of validity – you ensure that a valid frame has been parsed before!

Parameters
mhhandle
Returns
byte offset in stream
Hopefully valid HTML! Valid CSS!