# 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;-).
Classes | Macros | Enumerations | Functions
mpg123 metadata handling

Functions to retrieve the metadata from MPEG Audio files and streams. Also includes string handling functions. More...

## Classes
struct | mpg123_string
struct | mpg123_text
struct | mpg123_picture
struct | mpg123_id3v2
struct | mpg123_id3v1

## Macros
#define | MPG123_ID3 0x3
#define | MPG123_NEW_ID3 0x1
#define | MPG123_ICY 0xc
#define | MPG123_NEW_ICY 0x4

## Enumerations
enum | mpg123_text_encoding { mpg123_text_unknown = 0, mpg123_text_utf8 = 1, mpg123_text_latin1 = 2, mpg123_text_icy = 3, mpg123_text_cp1252 = 4, mpg123_text_utf16 = 5, mpg123_text_utf16bom = 6, mpg123_text_utf16be = 7, mpg123_text_max = 7 }
enum | mpg123_id3_enc { mpg123_id3_latin1 = 0, mpg123_id3_utf16bom = 1, mpg123_id3_utf16be = 2, mpg123_id3_utf8 = 3, mpg123_id3_enc_max = 3 }
enum | mpg123_id3_pic_type { mpg123_id3_pic_other = 0, mpg123_id3_pic_icon = 1, mpg123_id3_pic_other_icon = 2, mpg123_id3_pic_front_cover = 3, mpg123_id3_pic_back_cover = 4, mpg123_id3_pic_leaflet = 5, mpg123_id3_pic_media = 6, mpg123_id3_pic_lead = 7, mpg123_id3_pic_artist = 8, mpg123_id3_pic_conductor = 9, mpg123_id3_pic_orchestra = 10, mpg123_id3_pic_composer = 11, mpg123_id3_pic_lyricist = 12, mpg123_id3_pic_location = 13, mpg123_id3_pic_recording = 14, mpg123_id3_pic_performance = 15, mpg123_id3_pic_video = 16, mpg123_id3_pic_fish = 17, mpg123_id3_pic_illustration = 18, mpg123_id3_pic_artist_logo = 19, mpg123_id3_pic_publisher_logo = 20 }

## Functions
MPG123_EXPORT mpg123_string * | mpg123_new_string (const char *val)
MPG123_EXPORT void | mpg123_delete_string (mpg123_string *sb)
MPG123_EXPORT void | mpg123_init_string (mpg123_string *sb)
MPG123_EXPORT void | mpg123_free_string (mpg123_string *sb)
MPG123_EXPORT int | mpg123_resize_string (mpg123_string *sb, size_t news)
MPG123_EXPORT int | mpg123_grow_string (mpg123_string *sb, size_t news)
MPG123_EXPORT int | mpg123_copy_string (mpg123_string *from, mpg123_string *to)
MPG123_EXPORT int | mpg123_move_string (mpg123_string *from, mpg123_string *to)
MPG123_EXPORT int | mpg123_add_string (mpg123_string *sb, const char *stuff)
MPG123_EXPORT int | mpg123_add_substring (mpg123_string *sb, const char *stuff, size_t from, size_t count)
MPG123_EXPORT int | mpg123_set_string (mpg123_string *sb, const char *stuff)
MPG123_EXPORT int | mpg123_set_substring (mpg123_string *sb, const char *stuff, size_t from, size_t count)
MPG123_EXPORT size_t | mpg123_strlen (mpg123_string *sb, int utf8)
MPG123_EXPORT int | mpg123_chomp_string (mpg123_string *sb)
MPG123_EXPORT int | mpg123_same_string (mpg123_string *a, mpg123_string *b)
MPG123_EXPORT enum mpg123_text_encoding | mpg123_enc_from_id3 (unsigned char id3_enc_byte)
MPG123_EXPORT int | mpg123_enc_from_id3_2 (unsigned char id3_enc_byte)
MPG123_EXPORT int | mpg123_store_utf8 (mpg123_string *sb, enum mpg123_text_encoding enc, const unsigned char *source, size_t source_size)
MPG123_EXPORT int | mpg123_store_utf8_2 (mpg123_string *sb, int enc, const unsigned char *source, size_t source_size)
MPG123_EXPORT int | mpg123_meta_check (mpg123_handle *mh)
MPG123_EXPORT void | mpg123_meta_free (mpg123_handle *mh)
MPG123_EXPORT int | mpg123_id3 (mpg123_handle *mh, mpg123_id3v1 **v1, mpg123_id3v2 **v2)
MPG123_EXPORT int | mpg123_id3_raw (mpg123_handle *mh, unsigned char **v1, size_t *v1_size, unsigned char **v2, size_t *v2_size)
MPG123_EXPORT int | mpg123_icy (mpg123_handle *mh, char **icy_meta)
MPG123_EXPORT char * | mpg123_icy2utf8 (const char *icy_text)

## Detailed Description

Functions to retrieve the metadata from MPEG Audio files and streams. Also includes string handling functions.

## Macro Definition Documentation

## ◆ MPG123_ID3

#define MPG123_ID3 0x3

0011 There is some ID3 info. Also matches 0010 or NEW_ID3.

Definition at line 2052 of file mpg123.h.

## ◆ MPG123_NEW_ID3

#define MPG123_NEW_ID3 0x1

0001 There is ID3 info that changed since last call to mpg123_id3.

Definition at line 2053 of file mpg123.h.

## ◆ MPG123_ICY

#define MPG123_ICY 0xc

1100 There is some ICY info. Also matches 0100 or NEW_ICY.

Definition at line 2054 of file mpg123.h.

## ◆ MPG123_NEW_ICY

#define MPG123_NEW_ICY 0x4

0100 There is ICY info that changed since last call to mpg123_icy.

Definition at line 2055 of file mpg123.h.

## Enumeration Type Documentation

## ◆ mpg123_text_encoding

enum mpg123_text_encoding

The mpg123 text encodings. This contains encodings we encounter in ID3 tags or ICY meta info.

Enumerator
mpg123_text_unknown | Unkown encoding... mpg123_id3_encoding can return that on invalid codes.
mpg123_text_utf8 | UTF-8
mpg123_text_latin1 | ISO-8859-1. Note that sometimes latin1 in ID3 is abused for totally different encodings.
mpg123_text_icy | ICY metadata encoding, usually CP-1252 but we take it as UTF-8 if it qualifies as such.
mpg123_text_cp1252 | Really CP-1252 without any guessing.
mpg123_text_utf16 | Some UTF-16 encoding. The last of a set of leading BOMs (byte order mark) rules. When there is no BOM, big endian ordering is used. Note that UCS-2 qualifies as UTF-8 when you don't mess with the reserved code points. If you want to decode little endian data without BOM you need to prepend 0xff 0xfe yourself.
mpg123_text_utf16bom | Just an alias for UTF-16, ID3v2 has this as distinct code.
mpg123_text_utf16be | Another alias for UTF16 from ID3v2. Note, that, because of the mess that is reality, BOMs are used if encountered. There really is not much distinction between the UTF16 types for mpg123 One exception: Since this is seen in ID3v2 tags, leading null bytes are skipped for all other UTF16 types (we expect a BOM before real data there), not so for utf16be!
mpg123_text_max | Placeholder for the maximum encoding value.

Definition at line 1873 of file mpg123.h.

## ◆ mpg123_id3_enc

enum mpg123_id3_enc

The encoding byte values from ID3v2.

Enumerator
mpg123_id3_latin1 | Note: This sometimes can mean anything in practice...
mpg123_id3_utf16bom | UTF16, UCS-2 ... it's all the same for practical purposes.
mpg123_id3_utf16be | Big-endian UTF-16, BOM see note for mpg123_text_utf16be.
mpg123_id3_utf8 | Our lovely overly ASCII-compatible 8 byte encoding for the world.
mpg123_id3_enc_max | Placeholder to check valid range of encoding byte.

Definition at line 1893 of file mpg123.h.

## ◆ mpg123_id3_pic_type

enum mpg123_id3_pic_type

The picture type values from ID3v2.

Enumerator
mpg123_id3_pic_other | see ID3v2 docs
mpg123_id3_pic_icon | see ID3v2 docs
mpg123_id3_pic_other_icon | see ID3v2 docs
mpg123_id3_pic_front_cover | see ID3v2 docs
mpg123_id3_pic_back_cover | see ID3v2 docs
mpg123_id3_pic_leaflet | see ID3v2 docs
mpg123_id3_pic_media | see ID3v2 docs
mpg123_id3_pic_lead | see ID3v2 docs
mpg123_id3_pic_artist | see ID3v2 docs
mpg123_id3_pic_conductor | see ID3v2 docs
mpg123_id3_pic_orchestra | see ID3v2 docs
mpg123_id3_pic_composer | see ID3v2 docs
mpg123_id3_pic_lyricist | see ID3v2 docs
mpg123_id3_pic_location | see ID3v2 docs
mpg123_id3_pic_recording | see ID3v2 docs
mpg123_id3_pic_performance | see ID3v2 docs
mpg123_id3_pic_video | see ID3v2 docs
mpg123_id3_pic_fish | see ID3v2 docs
mpg123_id3_pic_illustration | see ID3v2 docs
mpg123_id3_pic_artist_logo | see ID3v2 docs
mpg123_id3_pic_publisher_logo | see ID3v2 docs

Definition at line 1972 of file mpg123.h.

## Function Documentation

## ◆ mpg123_new_string()

MPG123_EXPORT mpg123_string* mpg123_new_string | ( | const char * | val | ) |

Allocate and intialize a new string.

Parameters

  val | optional initial string value (can be NULL)

## ◆ mpg123_delete_string()

MPG123_EXPORT void mpg123_delete_string | ( | mpg123_string * | sb | ) |

Free memory of contents and the string structure itself.

Parameters

  sb | string handle

## ◆ mpg123_init_string()

MPG123_EXPORT void mpg123_init_string | ( | mpg123_string * | sb | ) |

Initialize an existing mpg123_string structure to {NULL, 0, 0}. If you hand in a NULL pointer here, your program should crash. The other string functions are more forgiving, but this one here is too basic.

Parameters

  sb | string handle (address of existing structure on your side)

## ◆ mpg123_free_string()

MPG123_EXPORT void mpg123_free_string | ( | mpg123_string * | sb | ) |

Free-up memory of the contents of an mpg123_string (not the struct itself). This also calls mpg123_init_string() and hence is safe to be called repeatedly.

Parameters

  sb | string handle

## ◆ mpg123_resize_string()

MPG123_EXPORT int mpg123_resize_string | ( | mpg123_string * | sb,
|  | size_t | news
| ) |  |

Change the size of a mpg123_string

Parameters

  sb | string handle
  news | new size in bytes

Returns
  0 on error, 1 on success

## ◆ mpg123_grow_string()

MPG123_EXPORT int mpg123_grow_string | ( | mpg123_string * | sb,
|  | size_t | news
| ) |  |

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.

Parameters

  sb | string handle
  news | new minimum size

Returns
  0 on error, 1 on success

## ◆ mpg123_copy_string()

MPG123_EXPORT int mpg123_copy_string | ( | mpg123_string * | from,
|  | mpg123_string * | to
| ) |  |

Copy the contents of one mpg123_string string to another. Yes the order of arguments is reversed compated to memcpy().

Parameters

  from | string handle
  to | string handle

Returns
  0 on error, 1 on success

## ◆ mpg123_move_string()

MPG123_EXPORT int mpg123_move_string | ( | mpg123_string * | from,
|  | mpg123_string * | to
| ) |  |

Move the contents of one mpg123_string string to another. This frees any memory associated with the target and moves over the pointers from the source, leaving the source without content after that. The only possible error is that you hand in NULL pointers. If you handed in a valid source, its contents will be gone, even if there was no target to move to. If you hand in a valid target, its original contents will also always be gone, to be replaced with the source's contents if there was some.

Parameters

  from | source string handle
  to | target string handle

Returns
  0 on error, 1 on success

## ◆ mpg123_add_string()

MPG123_EXPORT int mpg123_add_string | ( | mpg123_string * | sb,
|  | const char * | stuff
| ) |  |

Append a C-String to an mpg123_string

Parameters

  sb | string handle
  stuff | to append

Returns
  0 on error, 1 on success

## ◆ mpg123_add_substring()

MPG123_EXPORT int mpg123_add_substring | ( | mpg123_string * | sb,
|  | const char * | stuff,
|  | size_t | from,
|  | size_t | count
| ) |  |

Append a C-substring to an mpg123 string

Parameters

  sb | string handle
  stuff | content to copy
  from | offset to copy from
  count | number of characters to copy (a null-byte is always appended)

Returns
  0 on error, 1 on success

## ◆ mpg123_set_string()

MPG123_EXPORT int mpg123_set_string | ( | mpg123_string * | sb,
|  | const char * | stuff
| ) |  |

Set the content of a mpg123_string to a C-string

Parameters

  sb | string handle
  stuff | content to copy

Returns
  0 on error, 1 on success

## ◆ mpg123_set_substring()

MPG123_EXPORT int mpg123_set_substring | ( | mpg123_string * | sb,
|  | const char * | stuff,
|  | size_t | from,
|  | size_t | count
| ) |  |

Set the content of a mpg123_string to a C-substring

Parameters

  sb | string handle
  stuff | the future content
  from | offset to copy from
  count | number of characters to copy (a null-byte is always appended)

Returns
  0 on error, 1 on success

## ◆ mpg123_strlen()

MPG123_EXPORT size_t mpg123_strlen | ( | mpg123_string * | sb,
|  | int | utf8
| ) |  |

Count characters in a mpg123 string (non-null bytes or Unicode points). This function is of limited use, as it does just count code points encoded in an UTF-8 string, only loosely related to the count of visible characters. Get your full Unicode handling support elsewhere.

Parameters

  sb | string handle
  utf8 | a flag to tell if the string is in utf8 encoding

Returns
  character count

## ◆ mpg123_chomp_string()

MPG123_EXPORT int mpg123_chomp_string | ( | mpg123_string * | sb | ) |

Remove trailing \r and \n, if present.

Parameters

  sb | string handle

Returns
  0 on error, 1 on success

## ◆ mpg123_same_string()

MPG123_EXPORT int mpg123_same_string | ( | mpg123_string * | a,
|  | mpg123_string * | b
| ) |  |

Determine if two strings contain the same data. This only returns 1 if both given handles are non-NULL and if they are filled with the same bytes.

Parameters

  a | first string handle
  b | second string handle

Returns
  0 for different strings, 1 for identical

## ◆ mpg123_enc_from_id3()

MPG123_EXPORT enum mpg123_text_encoding mpg123_enc_from_id3 | ( | unsigned char | id3_enc_byte | ) |

Convert ID3 encoding byte to mpg123 encoding index.

Note that this name is mapped to mpg123_enc_from_id3_2() instead unless MPG123_ENUM_API is defined.

Parameters

  id3_enc_byte | the ID3 encoding code

Returns
  the mpg123 encoding index

## ◆ mpg123_enc_from_id3_2()

MPG123_EXPORT int mpg123_enc_from_id3_2 | ( | unsigned char | id3_enc_byte | ) |

Convert ID3 encoding byte to mpg123 encoding index. No enums.

This is actually called instead of mpg123_enc_from_id3() unless MPG123_ENUM_API is defined.

Parameters

  id3_enc_byte | the ID3 encoding code

Returns
  the mpg123 encoding index

## ◆ mpg123_store_utf8()

MPG123_EXPORT int mpg123_store_utf8 | ( | mpg123_string * | sb,
|  | enum mpg123_text_encoding | enc,
|  | const unsigned char * | source,
|  | size_t | source_size
| ) |  |

Store text data in string, after converting to UTF-8 from indicated encoding.

Note that this name is mapped to mpg123_store_utf8_2() instead unless MPG123_ENUM_API is defined.

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).

Parameters

  sb | target string
  enc | mpg123 text encoding value
  source | source buffer with plain unsigned bytes (you might need to cast from signed char)
  source_size | number of bytes in the source buffer

Returns
  0 on error, 1 on success (on error, mpg123_free_string is called on sb)

## ◆ mpg123_store_utf8_2()

MPG123_EXPORT int mpg123_store_utf8_2 | ( | mpg123_string * | sb,
|  | int | enc,
|  | const unsigned char * | source,
|  | size_t | source_size
| ) |  |

Store text data in string, after converting to UTF-8 from indicated encoding. No enums.

This is actually called instead of mpg123_store_utf8() unless MPG123_ENUM_API is defined.

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).

Parameters

  sb | target string
  enc | mpg123 text encoding value (enum mpg123_text_encoding)
  source | source buffer with plain unsigned bytes (you might need to cast from signed char)
  source_size | number of bytes in the source buffer

Returns
  0 on error, 1 on success (on error, mpg123_free_string is called on sb)

## ◆ mpg123_meta_check()

MPG123_EXPORT int mpg123_meta_check | ( | mpg123_handle * | mh | ) |

Query if there is (new) meta info, be it ID3 or ICY (or something new in future).

Parameters

  mh | handle

Returns
  combination of flags, 0 on error (same as "nothing new")

## ◆ mpg123_meta_free()

MPG123_EXPORT void mpg123_meta_free | ( | mpg123_handle * | mh | ) |

Clean up meta data storage (ID3v2 and ICY), freeing memory.

Parameters

  mh | handle

## ◆ mpg123_id3()

MPG123_EXPORT int mpg123_id3 | ( | mpg123_handle * | mh,
|  | mpg123_id3v1 ** | v1,
|  | mpg123_id3v2 ** | v2
| ) |  |

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.

Returns
  MPG123_OK on success

## ◆ mpg123_id3_raw()

MPG123_EXPORT int mpg123_id3_raw | ( | mpg123_handle * | mh,
|  | unsigned char ** | v1,
|  | size_t * | v1_size,
|  | unsigned char ** | v2,
|  | size_t * | v2_size
| ) |  |

Return pointers to and size of stored raw ID3 data if storage has been configured with MPG123_STORE_RAW_ID3 and stream parsing passed the metadata already. Null value with zero size is a possibility! The storage can change at any next API call.

Parameters

  mh | mpg123 handle
  v1 | address to store pointer to v1 tag
  v1_size | size of v1 data in bytes
  v2 | address to store pointer to v2 tag
  v2_size | size of v2 data in bytes

Returns
  MPG123_OK or MPG123_ERR. Only on MPG123_OK the output values are set.

## ◆ mpg123_icy()

MPG123_EXPORT int mpg123_icy | ( | mpg123_handle * | mh,
|  | char ** | icy_meta
| ) |  |

Point icy_meta to existing data structure wich may change on any next read/decode function call.

Parameters

  mh | handle
  icy_meta | return address for ICY meta string (set to NULL if nothing there)

Returns
  MPG123_OK on success

## ◆ mpg123_icy2utf8()

MPG123_EXPORT char* mpg123_icy2utf8 | ( | const char * | icy_text | ) |

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)) .

Parameters

  icy_text | The input data in ICY encoding

Returns
  pointer to newly allocated buffer with UTF-8 data (You free() it!)