* Functions to get text version of the error numbers and an enumeration
* of the error codes returned by libmpg123.
*
* Most functions operating on a mpg123_handle simply return MPG123_OK on success and MPG123_ERR on failure (setting the internal error variable of the handle to the specific error code).
* Decoding/seek functions may also return message codes MPG123_DONE, MPG123_NEW_FORMAT and MPG123_NEED_MORE.
* The positive range of return values is used for "useful" values when appropriate.
*
* @{
*/
/** Enumeration of the message and error codes and returned by libmpg123 functions. */
enummpg123_errors
{
MPG123_DONE=-12,/**< Message: Track ended. */
MPG123_NEW_FORMAT=-11,/**< Message: Output format will be different on next call. */
MPG123_NEED_MORE=-10,/**< Message: For feed reader: "Feed me more!" */
MPG123_ERR=-1,/**< Generic Error */
MPG123_OK=0,/**< Success */
MPG123_BAD_OUTFORMAT,/**< Unable to set up output format! */
MPG123_BAD_CHANNEL,/**< Invalid channel number specified. */
/** Configure a mpg123 handle to accept no output format at all,
* use before specifying supported formats with mpg123_format */
EXPORTintmpg123_format_none(mpg123_handle*mh);
/** Configure mpg123 handle to accept all formats
* (also any custom rate you may set) -- this is default. */
EXPORTintmpg123_format_all(mpg123_handle*mh);
/** Set the audio format support of a mpg123_handle in detail:
* \param mh audio decoder 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. */
/** \defgroup mpg123_seek mpg123 position and seeking
*
* Functions querying and manipulating position in the decoded audio bitstream.
* The position is measured in decoded audio samples, or MPEG frame offset for the specific functions.
* If gapless code is in effect, the positions are adjusted to compensate the skipped padding/delay - meaning, you should not care about that at all and just use the position defined for the samples you get out of the decoder;-)
* The general usage is modelled after stdlib's ftell() and fseek().
* Especially, the whence parameter for the seek functions has the same meaning as the one for fseek() and needs the same constants from stdlib.h:
* - SEEK_SET: set position to (or near to) specified offset
* - SEEK_CUR: change position by offset from now
* - SEEK_END: set position to offset from end
*
* Note that sample-afccurate seek only works when gapless support has been enabled at compile time; seek is frame-accurate otherwise.
* Also, seeking is not guaranteed to work for all streams (underlying stream may not support it).
*
* @{
*/
/** Returns the current position in samples.
* On the next read, you'd get that sample. */
EXPORToff_tmpg123_tell(mpg123_handle*mh);
/** Returns the frame number that the next read will give you data from. */
EXPORToff_tmpg123_tellframe(mpg123_handle*mh);
/** Seek to a desired sample offset.
* Set whence to SEEK_SET, SEEK_CUR or SEEK_END.
* \return The resulting offset >= 0 or error/message code */
/** 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 has 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). */
typedefstruct
{
charlang[3];/**< Three-letter language code (not terminated). */
charid[4];/**< The ID3v2 text field id, like TALB, TPE2, ... (4 characters, no string termination). */
mpg123_stringdescription;/**< Empty for the generic comment... */
mpg123_stringtext;/**< ... */
}mpg123_text;
/** 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. */
typedefstruct
{
unsignedcharversion;/**< 3 or 4 for ID3v2.3 or ID3v2.4. */
mpg123_string*title;/**< Title string (pointer into text_list). */
mpg123_string*artist;/**< Artist string (pointer into text_list). */
mpg123_string*album;/**< Album string (pointer into text_list). */
mpg123_string*year;/**< The year as a string (pointer into text_list). */
mpg123_string*genre;/**< Genre String (pointer into text_list). The genre string(s) may very well need postprocessing, esp. for ID3v2.3. */
mpg123_string*comment;/**< Pointer to last encountered comment text with empty description. */
/* Encountered ID3v2 fields are appended to these lists.
There can be multiple occurences, the pointers above always point to the last encountered data. */
mpg123_text*comment_list;/**< Array of comments. */
size_tcomments;/**< Number of comments. */
mpg123_text*text;/**< Array of ID3v2 text fields */
size_ttexts;/**< Numer of text fields. */
mpg123_text*extra;/**< The array of extra (TXXX) fields. */
size_textras;/**< Number of extra text (TXXX) fields. */
}mpg123_id3v2;
/** 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[19] = track_number
* It is your task to support ID3v1 only or ID3v1.1 ...*/
typedefstruct
{
chartag[3];/**< Always the string "TAG", the classic intro. */
chartitle[30];/**< Title string. */
charartist[30];/**< Artist string. */
charalbum[30];/**< Album string. */
charyear[4];/**< Year string. */
charcomment[30];/**< Comment string. */
unsignedchargenre;/**< Genre index. */
}mpg123_id3v1;
#define MPG123_ID3 0x3 /**< 0011 There is some ID3 info. Also matches 0010 or NEW_ID3. */
#define MPG123_NEW_ID3 0x1 /**< 0001 There is ID3 info that changed since last call to mpg123_id3. */
#define MPG123_ICY 0xc /**< 1100 There is some ICY info. Also matches 0100 or NEW_ICY.*/
#define MPG123_NEW_ICY 0x4 /**< 0100 There is ICY info that changed since last call to mpg123_icy. */
/** Query if there is (new) meta info, be it ID3 or ICY (or something new in future).
The check function returns a combination of flags. */
EXPORTintmpg123_meta_check(mpg123_handle*mh);/* On error (no valid handle) just 0 is returned. */
/** 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 Return value is MPG123_OK or MPG123_ERR, */
