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 low level I/O

Functions

MPG123_EXPORT int mpg123_replace_buffer (mpg123_handle *mh, void *data, size_t size)
 
MPG123_EXPORT size_t mpg123_outblock (mpg123_handle *mh)
 
MPG123_EXPORT int mpg123_replace_reader (mpg123_handle *mh, mpg123_ssize_t(*r_read)(int, void *, size_t), off_t(*r_lseek)(int, off_t, int))
 
MPG123_EXPORT int mpg123_replace_reader_handle (mpg123_handle *mh, mpg123_ssize_t(*r_read)(void *, void *, size_t), off_t(*r_lseek)(void *, off_t, int), void(*cleanup)(void *))
 
MPG123_EXPORT int mpg123_reader64 (mpg123_handle *mh, int(*r_read)(void *, void *, size_t, size_t *), int64_t(*r_lseek)(void *, int64_t, int), void(*cleanup)(void *))
 

Detailed Description

You may want to do tricky stuff with I/O that does not work with mpg123's default file access or you want to make it decode into your own pocket...

Function Documentation

◆ mpg123_replace_buffer()

MPG123_EXPORT int mpg123_replace_buffer ( mpg123_handle mh,
void *  data,
size_t  size 
)

Replace default internal buffer with user-supplied buffer. Instead of working on it's own private buffer, mpg123 will directly use the one you provide for storing decoded audio. Note that the required buffer size could be bigger than expected from output encoding if libmpg123 has to convert from primary decoder output (p.ex. 32 bit storage for 24 bit output).

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

Parameters
mhhandle
datapointer to user buffer
sizeof buffer in bytes
Returns
MPG123_OK on success

◆ mpg123_outblock()

MPG123_EXPORT size_t mpg123_outblock ( mpg123_handle mh)

The max size of one frame's decoded output with current settings. Use that to determine an appropriate minimum buffer size for decoding one frame.

Parameters
mhhandle
Returns
maximum decoded data size in bytes

◆ mpg123_replace_reader()

MPG123_EXPORT int mpg123_replace_reader ( mpg123_handle mh,
mpg123_ssize_t(*)(int, void *, size_t)  r_read,
off_t(*)(int, off_t, int)  r_lseek 
)

Replace low-level stream access functions; read and lseek as known in POSIX. You can use this to make any fancy file opening/closing yourself, using mpg123_open_fd() to set the file descriptor for your read/lseek (doesn't need to be a "real" file descriptor...). Setting a function to NULL means that just a call to POSIX read/lseek is done (without handling signals). Note: As it would be troublesome to mess with this while having a file open, this implies mpg123_close().

Parameters
mhhandle
r_readcallback for reading (behaviour like POSIX read)
r_lseekcallback for seeking (like POSIX lseek)
Returns
MPG123_OK on success

◆ mpg123_replace_reader_handle()

MPG123_EXPORT int mpg123_replace_reader_handle ( mpg123_handle mh,
mpg123_ssize_t(*)(void *, void *, size_t)  r_read,
off_t(*)(void *, off_t, int)  r_lseek,
void(*)(void *)  cleanup 
)

Replace I/O functions with your own ones operating on some kind of handle instead of integer descriptors. The handle is a void pointer, so you can pass any data you want... mpg123_open_handle() is the call you make to use the I/O defined here. There is no fallback to internal read/seek here. Note: As it would be troublesome to mess with this while having a file open, this mpg123_close() is implied here.

Parameters
mhhandle
r_readcallback for reading (behaviour like POSIX read)
r_lseekcallback for seeking (like POSIX lseek)
cleanupA callback to clean up a non-NULL I/O handle on mpg123_close, can be NULL for none (you take care of cleaning your handles).
Returns
MPG123_OK on success

◆ mpg123_reader64()

MPG123_EXPORT int mpg123_reader64 ( mpg123_handle mh,
int(*)(void *, void *, size_t, size_t *)  r_read,
int64_t(*)(void *, int64_t, int)  r_lseek,
void(*)(void *)  cleanup 
)

Set up portable read functions on an opaque handle. The handle is a void pointer, so you can pass any data you want... mpg123_open_handle() is the call you make to use the I/O defined here. There is no fallback to internal read/seek here. Note: As it would be troublesome to mess with this while having a file open, this mpg123_close() is implied here.

Parameters
mhhandle
r_readcallback for reading The parameters are the handle, the buffer to read into, a byte count to read, address to store the returned byte count. Return value is zero for no issue, non-zero for some error. Recoverable signal handling has to happen inside the callback.
r_lseekcallback for seeking (like POSIX lseek), maybe NULL for non-seekable streams
cleanupA callback to clean up a non-NULL I/O handle on mpg123_close, maybe NULL for none
Returns
MPG123_OK on success
Hopefully valid HTML! Valid CSS!