mpg123 logo
download : svn :: features :: sf.net project - bug tracker :: news archive
libmpg123 API :: hacking :: testing :: benchmarking :: FAQ :: links :: contact
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 and the overall NEWS file on libmpg123 versions and important changes between them.
Let me emphasize that the policy for libmpg123 is to always stay backwards compatible -- only additions are planned (and it's not yet planned to change the plans;-).

mpg123 metadata handling


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)
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 941 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 942 of file mpg123.h.

#define MPG123_ICY   0xc

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

Definition at line 943 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 944 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 846 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 866 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.

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

Generated on Mon Feb 6 01:07:21 2012 for libmpg123 by  doxygen 1.5.6