Data Structures
struct	mpg123_string
struct	mpg123_text
struct	mpg123_id3v2
struct	mpg123_id3v1
Defines
#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 }
Functions
void	mpg123_init_string (mpg123_string *sb)
void	mpg123_free_string (mpg123_string *sb)
int	mpg123_resize_string (mpg123_string *sb, size_t news)
int	mpg123_grow_string (mpg123_string *sb, size_t news)
int	mpg123_copy_string (mpg123_string from, mpg123_string to)
int	mpg123_add_string (mpg123_string sb, const char stuff)
int	mpg123_add_substring (mpg123_string sb, const char stuff, size_t from, size_t count)
int	mpg123_set_string (mpg123_string sb, const char stuff)
int	mpg123_set_substring (mpg123_string sb, const char stuff, size_t from, size_t count)
size_t	mpg123_strlen (mpg123_string *sb, int utf8)
enum mpg123_text_encoding	mpg123_enc_from_id3 (unsigned char id3_enc_byte)
int	mpg123_store_utf8 (mpg123_string sb, enum mpg123_text_encoding enc, const unsigned char source, size_t source_size)
int	mpg123_meta_check (mpg123_handle *mh)
void	mpg123_meta_free (mpg123_handle *mh)
int	mpg123_id3 (mpg123_handle mh, mpg123_id3v1 v1, mpg123_id3v2 *v2)
int	mpg123_icy (mpg123_handle mh, char *icy_meta)
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.

Define Documentation

#define MPG123_ID3 0x3

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

Definition at line 942 of file mpg123.h.

#define MPG123_NEW_ID3 0x1

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

Definition at line 943 of file mpg123.h.

#define MPG123_ICY 0xc

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

Definition at line 944 of file mpg123.h.

#define MPG123_NEW_ICY 0x4

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

Definition at line 945 of file mpg123.h.

Enumeration Type Documentation

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 847 of file mpg123.h.

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 867 of file mpg123.h.

Function Documentation

void mpg123_init_string ( mpg123_string * sb )

Create and allocate memory for a new mpg123_string

void mpg123_free_string ( mpg123_string * sb )

Free-up mempory for an existing mpg123_string

int mpg123_resize_string	(	mpg123_string *	sb,
		size_t	news
	)

Change the size of a mpg123_string

Returns:: 0 on error, 1 on success

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.

Returns:: 0 on error, 1 on success

int mpg123_copy_string	(	mpg123_string *	from,
		mpg123_string *	to
	)

Copy the contents of one mpg123_string string to another.

Returns:: 0 on error, 1 on success

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

Append a C-String to an mpg123_string

Returns:: 0 on error, 1 on success

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

Append a C-substring to an mpg123 string

Returns:: 0 on error, 1 on success

Parameters:

	from	offset to copy from
	count	number of characters to copy (a null-byte is always appended)

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

Set the conents of a mpg123_string to a C-string

Returns:: 0 on error, 1 on success

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

Set the contents of a mpg123_string to a C-substring

Returns:: 0 on error, 1 on success

Parameters:

	from	offset to copy from
	count	number of characters to copy (a null-byte is always appended)

size_t mpg123_strlen	(	mpg123_string *	sb,
		int	utf8
	)

Count characters in a mpg123 string (non-null bytes or UTF-8 characters).

Returns:: character count

Parameters:

	sb	the string
	utf8	a flag to tell if the string is in utf8 encoding Even with the fill property, the character count is not obvious as there could be multiple trailing null bytes.

enum mpg123_text_encoding mpg123_enc_from_id3 ( unsigned char id3_enc_byte )

Convert ID3 encoding byte to mpg123 encoding index.

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

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

Parameters:

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

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

int mpg123_meta_check ( mpg123_handle * mh )

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.

void mpg123_meta_free ( mpg123_handle * mh )

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

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:: Return value is MPG123_OK or MPG123_ERR,

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.

Returns:: Return value is MPG123_OK or MPG123_ERR,

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

mpg123 metadata handling

Data Structures

Defines

Enumerations

Functions

Detailed Description

Define Documentation

Enumeration Type Documentation

Function Documentation