Append a C-String to an mpg123_string \param sb string handle \param stuff to append \return 0 on error, 1 on success
Append a C-substring to an mpg123 string \param sb string handle \param stuff content to copy \param from offset to copy from \param count number of characters to copy (a null-byte is always appended) \return 0 on error, 1 on success
Remove trailing \\r and \\n, if present. \param sb string handle \return 0 on error, 1 on success
Get and reset the clip count. \param mh handle \return count of clipped samples
Closes the source, if libmpg123 opened it. \param mh handle \return MPG123_OK on success
Copy the contents of one mpg123_string string to another. Yes the order of arguments is reversed compated to memcpy(). \param from string handle \param to string handle \return 0 on error, 1 on success
Get the currently active decoder name. The active decoder engine can vary depening on output constraints, mostly non-resampling, integer output is accelerated via 3DNow & Co. but for other modes a fallback engine kicks in. Note that this can return a decoder that is only active in the hidden and not available as decoder choice from the outside. \param mh handle \return The decoder name or NULL on error.
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. \param mh handle \param inmemory input buffer \param inmemsize number of input bytes \param outmemory output buffer \param outmemsize maximum number of output bytes \param done address to store the number of actually decoded bytes to \return error/message code (watch out especially for MPG123_NEED_MORE)
Decode next MPEG frame to internal buffer or read a frame and return after setting a new format. \param mh handle \param num current frame offset gets stored there \param audio This pointer is set to the internal buffer to read the decoded audio from. \param bytes number of output bytes ready in the buffer \return MPG123_OK or error/message code
Set the active decoder. \param mh handle \param decoder_name name of decoder \return MPG123_OK on success
Get available decoder list. \return NULL-terminated array of generally available decoder names (plain 8bit ASCII)
Delete handle, mh is either a valid mpg123 handle or NULL. \param mh handle
Delete and free up memory used by a mpg123_pars data structure \param mp parameter handle
Convert ID3 encoding byte to mpg123 encoding index. \param id3_enc_byte the ID3 encoding code \return the mpg123 encoding index
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). * \param list Store a pointer to the encodings array there. * \param number Store the number of encodings there.
Return the size (in bytes) of one mono sample of the named encoding. * \param encoding The encoding value to analyze. * \return positive size of encoding in bytes, 0 on invalid encoding.
Set the 32 Band Audio Equalizer settings. \param mh handle \param channel Can be MPG123_LEFT, MPG123_RIGHT or MPG123_LEFT|MPG123_RIGHT for both. \param band The equaliser band to change (from 0 to 31) \param val The (linear) adjustment factor. \return MPG123_OK on success
Return the plain errcode intead of a string. \param mh handle \return error code recorded in handle or MPG123_BAD_HANDLE
Function to close down the mpg123 library. * This function is not thread-safe. Call it exactly once per process, before any other (possibly threaded) work with the library.
Query libmpg123 features. \param key feature selection \return 1 for success, 0 for unimplemented functions
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. \param mh handle \param in input buffer \param size number of input bytes \return MPG123_OK or error/message code.
Seek to a desired sample offset in data feeding mode. * This just prepares things to be right only if you ensure that the next chunk of input data will be from input_offset byte position. * \param mh handle * \param sampleoff offset in PCM samples * \param whence one of SEEK_SET, SEEK_CUR or SEEK_END * \param input_offset The position it expects to be at the * next time data is fed to mpg123_decode(). * \return The resulting offset >= 0 or error/message code
Set the audio format support of a mpg123_pars in detail: \param mp parameter handle \param rate The sample rate value (in Hertz). \param channels A combination of MPG123_STEREO and MPG123_MONO. \param encodings A combination of accepted encodings for rate and channels, p.ex MPG123_ENC_SIGNED16|MPG123_ENC_ULAW_8 (or 0 for no support). \return MPG123_OK on success
Configure mpg123 parameters to accept all formats (also any custom rate you may set) -- this is default. \param mp parameter handle \return MPG123_OK on success
Configure mpg123 parameters to accept no output format at all, use before specifying supported formats with mpg123_format \param mp parameter handle \return MPG123_OK on success
Check to see if a specific format at a specific rate is supported * by mpg123_pars. * \param mp parameter handle * \param rate sampling rate * \param encoding encoding * \return 0 for no support (that includes invalid parameters), MPG123_STEREO, * MPG123_MONO or MPG123_STEREO|MPG123_MONO.
Set the audio format support of a mpg123_handle in detail: * \param mh handle * \param rate The sample rate value (in Hertz). * \param channels A combination of MPG123_STEREO and MPG123_MONO. * \param 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. * \return MPG123_OK on success, MPG123_ERR if there was an error.
Configure mpg123 handle to accept all formats (also any custom rate you may set) -- this is default. \param mh handle \return MPG123_OK on success
Configure a mpg123 handle to accept no output format at all, use before specifying supported formats with mpg123_format \param mh handle \return MPG123_OK on success
Check to see if a specific format at a specific rate is supported * by mpg123_handle. * \param mh handle * \param rate sampling rate * \param encoding encoding * \return 0 for no support (that includes invalid parameters), MPG123_STEREO, * MPG123_MONO or MPG123_STEREO|MPG123_MONO.
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. \param mh handle \param num last frame offset gets stored there \param audio this pointer is set to the internal buffer to read the decoded audio from. \param bytes number of output bytes ready in the buffer \return MPG123_OK or error/message code
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. \param mh handle \return MPG123_OK or error/message code
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.
Return, if possible, the full (expected) length of current track in frames. \param mh handle \return length >= 0 or MPG123_ERR if there is no length guess possible.
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! \param mh handle \return byte offset in stream
Free-up mempory for an existing mpg123_string \param sb string handle
Get the 32 Band Audio Equalizer settings. * \param mh handle * \param channel Can be MPG123_LEFT, MPG123_RIGHT or MPG123_LEFT|MPG123_RIGHT for (arithmetic mean of) both. * \param band The equaliser band to change (from 0 to 31) * \return The (linear) adjustment factor (zero for pad parameters)
Get the current output format written to the addresses given. \param mh handle \param rate sampling rate return address \param channels channel count return address \param encoding encoding return address \return MPG123_OK on success
Get a specific parameter, for a specific mpg123_pars. See the mpg123_parms enumeration for a list of available parameters. \param mp parameter handle \param type parameter choice \param value integer value return address \param fvalue floating point value return address \return MPG123_OK on success
Get a specific parameter, for a specific mpg123_handle. See the mpg123_parms enumeration for a list of available parameters. \param mh handle \param type parameter choice \param value integer value return address \param fvalue floating point value return address \return MPG123_OK on success
Get various current decoder/stream state information. \param mh handle \param key the key to identify the information to give. \param val the address to return (long) integer values to \param fval the address to return floating point values to \return MPG123_OK on success
Return current volume setting, the actual value due to RVA, and the RVA adjustment itself. It's all as double float value to abstract the sample format. The volume values are linear factors / amplitudes (not percent) and the RVA value is in decibels. \param mh handle \param base return address for base volume (linear factor) \param really return address for actual volume (linear factor) \param rva_db return address for RVA value (decibels) \return MPG123_OK on success
Increase size of a mpg123_string if necessary (it may stay larger). Note that the functions for adding and setting in current libmpg123 use this instead of mpg123_resize_string(). That way, you can preallocate memory and safely work afterwards with pieces. \param sb string handle \param news new minimum size \return 0 on error, 1 on success
Point icy_meta to existing data structure wich may change on any next read/decode function call. \param mh handle \param icy_meta return address for ICY meta string (set to NULL if nothing there) \return MPG123_OK on success
Decode from windows-1252 (the encoding ICY metainfo used) to UTF-8. * Note that this is very similar to mpg123_store_utf8(&sb, mpg123_text_icy, icy_text, strlen(icy_text+1)) . * \param icy_text The input data in ICY encoding * \return pointer to newly allocated buffer with UTF-8 data (You free() it!)
Point v1 and v2 to existing data structures wich may change on any next read/decode function call. v1 and/or v2 can be set to NULL when there is no corresponding data. \return MPG123_OK on success
Give access to the frame index table that is managed for seeking. You are asked not to modify the values... Use mpg123_set_index to set the seek index \param mh handle \param offsets pointer to the index array \param step one index byte offset advances this many MPEG frames \param fill number of recorded index offsets; size of the array \return MPG123_OK on success
Get frame information about the MPEG audio bitstream and store it in a mpg123_frameinfo structure. \param mh handle \param mi address of existing frameinfo structure to write to \return MPG123_OK on success
Function to initialise the mpg123 library. * This function is not thread-safe. Call it exactly once per process, before any other (possibly threaded) work with the library.
Create and allocate memory for a new mpg123_string \param sb string handle (address of existing structure on your side)
Return, if possible, the full (expected) length of current track in samples. \param mh handle \return length >= 0 or MPG123_ERR if there is no length guess possible.
Query if there is (new) meta info, be it ID3 or ICY (or something new in future). \param mh handle \return combination of flags, 0 on error (same as "nothing new")
Clean up meta data storage (ID3v2 and ICY), freeing memory. \param mh handle
Create a handle with optional choice of decoder (named by a string, see mpg123_decoders() or mpg123_supported_decoders()). and optional retrieval of an error code to feed to mpg123_plain_strerror(). Optional means: Any of or both the parameters may be NULL.
Allocate memory for and return a pointer to a new mpg123_pars \param error error code return address \return new parameter handle
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(). \param mh handle \param path filesystem path \return MPG123_OK on success
Use an already opened file descriptor as the bitstream input mpg123_close() will _not_ close the file descriptor. \param mh handle \param fd file descriptor \return MPG123_OK on success
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. \param mh handle \return MPG123_OK on success
Use an opaque handle as bitstream input. This works only with the replaced I/O from mpg123_replace_reader_handle()! mpg123_close() will call the cleanup callback for your handle (if you gave one). \param mh handle \param iohandle your handle \return MPG123_OK on success
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. \param mh handle \return maximum decoded data size in bytes
Set a specific parameter, for a specific mpg123_pars, using a parameter type key chosen from the mpg123_parms enumeration, to the specified value. \param mp parameter handle \param type parameter choice \param value integer value \param fvalue floating point value \return MPG123_OK on success
Set a specific parameter, for a specific mpg123_handle, using a parameter type key chosen from the mpg123_parms enumeration, to the specified value. \param mh handle \param type parameter choice \param value integer value \param fvalue floating point value \return MPG123_OK on success
Create a handle with preset parameters. \param mp parameter handle \param decoder decoder choice \param error error code return address \return mpg123 handle
Look up error strings given integer code. \param errcode integer error code \return string describing what that error error code means
An old crutch to keep old mpg123 binaries happy. WARNING: This function is there only to avoid runtime linking errors with standalone mpg123 before version 1.23.0 (if you strangely update the library but not the end-user program) and actually is broken for various cases (p.ex. 24 bit output). Do never use. It might eventually be purged from the library.
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. * \param list Store a pointer to the sample rates array there. * \param number Store the number of sample rates there.
Read from stream and decode up to outmemsize bytes. \param mh handle \param outmemory address of output buffer to write to \param outmemsize maximum number of bytes to write \param done address to store the number of actually decoded bytes to \return MPG123_OK or error/message code
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). \param mh handle \param data pointer to user buffer \param size of buffer in bytes \return MPG123_OK on success
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 the default internal read is used (active from next mpg123_open call on). Note: As it would be troublesome to mess with this while having a file open, this implies mpg123_close(). \param mh handle \param r_read callback for reading (behaviour like POSIX read) \param r_lseek callback for seeking (like POSIX lseek) \return MPG123_OK on success
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. \param mh handle \param r_read callback for reading (behaviour like POSIX read) \param r_lseek callback for seeking (like POSIX lseek) \param cleanup A callback to clean up an I/O handle on mpg123_close, can be NULL for none (you take care of cleaning your handles). \return MPG123_OK on success
Reset the 32 Band Audio Equalizer settings to flat \param mh handle \return MPG123_OK on success
Change the size of a mpg123_string \param sb string handle \param news new size in bytes \return 0 on error, 1 on success
Get the safe output buffer size for all cases (when you want to replace the internal buffer) \return safe buffer size
Make a full parsing scan of each frame in the file. ID3 tags are found. An accurate length value is stored. Seek index will be filled. A seek back to current position is performed. At all, this function refuses work when stream is not seekable. \param mh handle \return MPG123_OK on success
Seek to a desired sample offset. Usage is modelled afer the standard lseek(). \param mh handle \param sampleoff offset in PCM samples \param whence one of SEEK_SET, SEEK_CUR or SEEK_END \return The resulting offset >= 0 or error/message code
Seek to a desired MPEG frame offset. * Usage is modelled afer the standard lseek(). * \param mh handle * \param frameoff offset in MPEG frames * \param whence one of SEEK_SET, SEEK_CUR or SEEK_END * \return The resulting offset >= 0 or error/message code
Override the value for file size in bytes. Useful for getting sensible track length values in feed mode or for HTTP streams. \param mh handle \param size file size in bytes \return MPG123_OK on success
Set the frame index table Setting offsets to NULL and fill > 0 will allocate fill entries. Setting offsets to NULL and fill to 0 will clear the index and free the allocated memory used by the index. \param mh handle \param offsets pointer to the index array \param step one index byte offset advances this many MPEG frames \param fill number of recorded index offsets; size of the array \return MPG123_OK on success
Set the content of a mpg123_string to a C-string \param sb string handle \param stuff content to copy \return 0 on error, 1 on success
Set the content of a mpg123_string to a C-substring \param sb string handle \param stuff the future content \param from offset to copy from \param count number of characters to copy (a null-byte is always appended) \return 0 on error, 1 on success
Get MPEG frame duration in samples. \param mh handle \return samples per frame for the most recently parsed frame; <0 on errors
Store text data in string, after converting to UTF-8 from indicated encoding A prominent error can be that you provided an unknown encoding value, or this build of libmpg123 lacks support for certain encodings (ID3 or ICY stuff missing). Also, you might want to take a bit of care with preparing the data; for example, strip leading zeroes (I have seen that). \param sb target string \param enc mpg123 text encoding value \param source source buffer with plain unsigned bytes (you might need to cast from signed char) \param source_size number of bytes in the source buffer \return 0 on error, 1 on success (on error, mpg123_free_string is called on sb)
Give string describing what error has occured in the context of handle mh. When a function operating on an mpg123 handle returns MPG123_ERR, you should check for the actual reason via char *errmsg = mpg123_strerror(mh) This function will catch mh == NULL and return the message for MPG123_BAD_HANDLE. \param mh handle \return error message
Count characters in a mpg123 string (non-null bytes or UTF-8 characters). Even with the fill property, the character count is not obvious as there could be multiple trailing null bytes. \param sb string handle \param utf8 a flag to tell if the string is in utf8 encoding \return character count
Get supported decoder list. \return NULL-terminated array of the decoders supported by the CPU (plain 8bit ASCII)
Returns the current position in samples. On the next successful read, you'd get that sample. \param mh handle \return sample offset or MPG123_ERR (null handle)
Returns the current byte offset in the input stream. \param mh handle \return byte offset or MPG123_ERR (null handle)
Returns the frame number that the next read will give you data from. \param mh handle \return frame offset or MPG123_ERR (null handle)
Return a MPEG frame offset corresponding to an offset in seconds. * This assumes that the samples per frame do not change in the file/stream, which is a good assumption for any sane file/stream only. * \return frame offset >= 0 or error/message code
Get MPEG frame duration in seconds. \param mh handle \return frame duration in seconds, <0 on error
Set the absolute output volume including the RVA setting, vol<0 just applies (a possibly changed) RVA setting. \param mh handle \param vol volume value (linear factor) \return MPG123_OK on success
Adjust output volume including the RVA setting by chosen amount \param mh handle \param change volume value (linear factor increment) \return MPG123_OK on success
Enumeration of the message and error codes and returned by libmpg123 functions.
They can be combined into one number (3) to indicate mono and stereo...
another channel enumeration, for left/right choice
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.
Feature set available for query with mpg123_feature.
Enumeration of the MPEG Audio flag bits
The encoding byte values from ID3v2.
The picture type values from ID3v2.
Enumeration of the MPEG Audio mode. * Only the mono mode has 1 channel, the others have 2 channels.
Flag bits for MPG123_FLAGS, use the usual binary or to combine.
choices for MPG123_RVA
Enumeration of the parameters types that it is possible to set/get.
The key values for state information from mpg123_getstate().
The mpg123 text encodings. This contains encodings we encounter in ID3 tags or ICY meta info.
Enumeration of the mode types of Variable Bitrate
Enumeration of the MPEG Versions
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. \param enc the encoding (mpg123_enc_enum value) \return size of one sample in bytes
A macro to check at compile time which set of API functions to expect. This should be incremented at least each time a new symbol is added to the header.
< 0001 There is ID3 info that changed since last call to mpg123_id3.
< 1100 There is some ICY info. Also matches 0100 or NEW_ICY.
< 0011 There is some ID3 info. Also matches 0010 or NEW_ID3.
Structure defining an audio format. Providing the members as individual function arguments to define a certain output format is easy enough. This struct makes is more comfortable to deal with a list of formats. Negative values for the members might be used to communicate use of default values.
Data structure for storing information about a frame of MPEG Audio
Opaque structure for the libmpg123 decoder handle.
Data structure for ID3v1 tags (the last 128 bytes of a file). * Don't take anything for granted (like string termination)! * Also note the change ID3v1.1 did: comment[28] = 0; comment[29] = track_number * It is your task to support ID3v1 only or ID3v1.1 ...
Data structure for storing IDV3v2 tags. * This structure is not a direct binary mapping with the file contents. * The ID3v2 text frames are allowed to contain multiple strings. * So check for null bytes until you reach the mpg123_string fill. * All text is encoded in UTF-8.
Opaque structure for the libmpg123 decoder parameters.
Sub data structure for ID3v2, for storing picture data including comment. * This is for the ID3v2 APIC field. You should consult the ID3v2 specification * for the use of the APIC field ("frames" in ID3v2 documentation, I use "fields" * here to separate from MPEG frames).
Data structure for storing strings in a safer way than a standard C-String. * Can also hold a number of null-terminated strings.
Sub data structure for ID3v2, for storing various text fields (including comments). * This is for ID3v2 COMM, TXXX and all the other text fields. * Only COMM and TXXX have a description, only COMM and USLT have a language. * You should consult the ID3v2 specification for the use of the various text fields ("frames" in ID3v2 documentation, I use "fields" here to separate from MPEG frames).