download : svn :: features :: sf.net project - bug tracker :: news archive

libmpg123 API :: 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
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)
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 751 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 752 of file mpg123.h.

#define MPG123_ICY   0xc

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

Definition at line 753 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 754 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)

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.

Parameters:

icy_text

The input data in ICY encoding

Returns:

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

---