mpg123 low level I/O

Collaboration diagram for mpg123 low level I/O:

Functions
MPG123_EXPORT int	mpg123_replace_buffer (mpg123_handle *mh, void *data, size_t size)
MPG123_EXPORT size_t	mpg123_outblock (mpg123_handle *mh)
MPG123_EXPORT int	mpg123_replace_reader (mpg123_handle *mh, ssize_t(*r_read)(int, void *, size_t), off_t(*r_lseek)(int, off_t, int))
MPG123_EXPORT int	mpg123_replace_reader_handle (mpg123_handle *mh, ssize_t(*r_read)(void *, void *, size_t), off_t(*r_lseek)(void *, off_t, int), void(*cleanup)(void *))

Variables
enum mpg123_version	mpg123_frameinfo::version
int	mpg123_frameinfo::layer
long	mpg123_frameinfo::rate
enum mpg123_mode	mpg123_frameinfo::mode
int	mpg123_frameinfo::mode_ext
int	mpg123_frameinfo::framesize
enum mpg123_flags	mpg123_frameinfo::flags
int	mpg123_frameinfo::emphasis
int	mpg123_frameinfo::bitrate
int	mpg123_frameinfo::abr_rate
enum mpg123_vbr	mpg123_frameinfo::vbr
double	mpg123_moreinfo::xr [2][2][576]
double	mpg123_moreinfo::sfb [2][2][22]
double	mpg123_moreinfo::sfb_s [2][2][3 *13]
int	mpg123_moreinfo::qss [2][2]
int	mpg123_moreinfo::big_values [2][2]
int	mpg123_moreinfo::sub_gain [2][2][3]
int	mpg123_moreinfo::scalefac_scale [2][2]
int	mpg123_moreinfo::preflag [2][2]
int	mpg123_moreinfo::blocktype [2][2]
int	mpg123_moreinfo::mixed [2][2]
int	mpg123_moreinfo::mainbits [2][2]
int	mpg123_moreinfo::sfbits [2][2]
int	mpg123_moreinfo::scfsi [2]
int	mpg123_moreinfo::maindata
int	mpg123_moreinfo::padding
char *	mpg123_string::p
size_t	mpg123_string::size
size_t	mpg123_string::fill
char	mpg123_text::lang [3]
char	mpg123_text::id [4]
mpg123_string	mpg123_text::description
mpg123_string	mpg123_text::text
char	mpg123_picture::type
mpg123_string	mpg123_picture::description
mpg123_string	mpg123_picture::mime_type
size_t	mpg123_picture::size
unsigned char *	mpg123_picture::data
unsigned char	mpg123_id3v2::version
mpg123_string *	mpg123_id3v2::title
mpg123_string *	mpg123_id3v2::artist
mpg123_string *	mpg123_id3v2::album
mpg123_string *	mpg123_id3v2::year
mpg123_string *	mpg123_id3v2::genre
mpg123_string *	mpg123_id3v2::comment
mpg123_text *	mpg123_id3v2::comment_list
size_t	mpg123_id3v2::comments
mpg123_text *	mpg123_id3v2::text
size_t	mpg123_id3v2::texts
mpg123_text *	mpg123_id3v2::extra
size_t	mpg123_id3v2::extras
mpg123_picture *	mpg123_id3v2::picture
size_t	mpg123_id3v2::pictures
char	mpg123_id3v1::tag [3]
char	mpg123_id3v1::title [30]
char	mpg123_id3v1::artist [30]
char	mpg123_id3v1::album [30]
char	mpg123_id3v1::year [4]
char	mpg123_id3v1::comment [30]
unsigned char	mpg123_id3v1::genre

Detailed Description

You may want to do tricky stuff with I/O that does not work with mpg123's default file access or you want to make it decode into your own pocket...

Function Documentation

mpg123_outblock()

MPG123_EXPORT size_t mpg123_outblock

(

mpg123_handle *

mh

)

The max size of one frame's decoded output with current settings. Use that to determine an appropriate minimum buffer size for decoding one frame.

Parameters

mh

handle

Returns

maximum decoded data size in bytes

Definition at line 653 of file libmpg123.c.

{
    /* Try to be helpful and never return zero output block size. */
    if(mh != NULL && mh->outblock > 0) return mh->outblock;
    else return mpg123_safe_buffer();
}

mpg123_replace_buffer()

MPG123_EXPORT int mpg123_replace_buffer	(	mpg123_handle *	mh,
		void *	data,
		size_t	size
	)

Replace default internal buffer with user-supplied buffer. Instead of working on it's own private buffer, mpg123 will directly use the one you provide for storing decoded audio. Note that the required buffer size could be bigger than expected from output encoding if libmpg123 has to convert from primary decoder output (p.ex. 32 bit storage for 24 bit output).

Note: The type of data changed to a void pointer in mpg123 1.26.0 (API version 45).

Parameters

mh	handle
data	pointer to user buffer
size	of buffer in bytes

Returns

MPG123_OK on success

Definition at line 219 of file frame.c.

{
    debug2("replace buffer with %p size %"SIZE_P, data, (size_p)size);
    if(mh == NULL) return MPG123_BAD_HANDLE;
    /* Will accept any size, the error comes later... */
    if(data == NULL)
    {
        mh->err = MPG123_BAD_BUFFER;
        return MPG123_ERR;
    }
    if(mh->buffer.rdata != NULL) free(mh->buffer.rdata);
    mh->own_buffer = FALSE;
    mh->buffer.rdata = NULL;
    mh->buffer.data = data;
    mh->buffer.size = size;
    mh->buffer.fill = 0;
    return MPG123_OK;
}

mpg123_replace_reader()

MPG123_EXPORT int mpg123_replace_reader	(	mpg123_handle *	mh,
		ssize_t(*)(int, void *, size_t)	r_read,
		off_t(*)(int, off_t, int)	r_lseek
	)

Replace low-level stream access functions; read and lseek as known in POSIX. You can use this to make any fancy file opening/closing yourself, using mpg123_open_fd() to set the file descriptor for your read/lseek (doesn't need to be a "real" file descriptor...). Setting a function to NULL means that the default internal read is used (active from next mpg123_open call on). Note: As it would be troublesome to mess with this while having a file open, this implies mpg123_close().

Parameters

mh	handle
r_read	callback for reading (behaviour like POSIX read)
r_lseek	callback for seeking (like POSIX lseek)

Returns

MPG123_OK on success

Definition at line 601 of file lfs_wrap.c.

{
    struct wrap_data* ioh;
 
    if(mh == NULL) return MPG123_ERR;
 
    mpg123_close(mh);
    ioh = wrap_get(mh);
    if(ioh == NULL) return MPG123_ERR;
 
    /* If both callbacks are NULL, switch totally to internal I/O, else just use fallback for at most half of them. */
    if(r_read == NULL && r_lseek == NULL)
    {
        /* Only the type is actually important to disable the code. */
        ioh->iotype = 0;
        ioh->fd = -1;
        ioh->r_read = NULL;
        ioh->r_lseek = NULL;
    }
    else
    {
        ioh->iotype = IO_FD;
        ioh->fd = -1; /* On next mpg123_open_fd(), this gets a value. */
        ioh->r_read = r_read != NULL ? r_read : fallback_read;
        ioh->r_lseek = r_lseek != NULL ? r_lseek : fallback_lseek;
    }
 
    /* The real reader replacement will happen while opening. */
    return MPG123_OK;
}

mpg123_replace_reader_handle()

MPG123_EXPORT int mpg123_replace_reader_handle	(	mpg123_handle *	mh,
		ssize_t(*)(void *, void *, size_t)	r_read,
		off_t(*)(void *, off_t, int)	r_lseek,
		void(*)(void *)	cleanup
	)

Replace I/O functions with your own ones operating on some kind of handle instead of integer descriptors. The handle is a void pointer, so you can pass any data you want... mpg123_open_handle() is the call you make to use the I/O defined here. There is no fallback to internal read/seek here. Note: As it would be troublesome to mess with this while having a file open, this mpg123_close() is implied here.

Parameters

mh	handle
r_read	callback for reading (behaviour like POSIX read)
r_lseek	callback for seeking (like POSIX lseek)
cleanup	A callback to clean up an I/O handle on mpg123_close, can be NULL for none (you take care of cleaning your handles).

Returns

MPG123_OK on success

Definition at line 632 of file lfs_wrap.c.

{
    struct wrap_data* ioh;
 
    if(mh == NULL) return MPG123_ERR;
 
    mpg123_close(mh);
    ioh = wrap_get(mh);
    if(ioh == NULL) return MPG123_ERR;
 
    ioh->iotype = IO_HANDLE;
    ioh->handle = NULL;
    ioh->r_h_read = r_read;
    ioh->r_h_lseek = r_lseek;
    ioh->h_cleanup = cleanup;
 
    /* The real reader replacement will happen while opening. */
    return MPG123_OK;
}

Referenced by mpg123_open(), mpg123_open_fd(), and mpg123_open_handle().

Variable Documentation

abr_rate

int mpg123_frameinfo::abr_rate

The target average bitrate.

Definition at line 1049 of file mpg123.h.

album [1/2]

mpg123_string* mpg123_id3v2::album

Album string (pointer into text_list).

Definition at line 1432 of file mpg123.h.

Referenced by null_id3_links().

album [2/2]

char mpg123_id3v1::album[30]

Album string.

Definition at line 1458 of file mpg123.h.

artist [1/2]

mpg123_string* mpg123_id3v2::artist

Artist string (pointer into text_list).

Definition at line 1431 of file mpg123.h.

Referenced by null_id3_links().

artist [2/2]

char mpg123_id3v1::artist[30]

Artist string.

Definition at line 1457 of file mpg123.h.

big_values

int mpg123_moreinfo::big_values[2][2]

Definition at line 1064 of file mpg123.h.

bitrate

int mpg123_frameinfo::bitrate

Bitrate of the frame (kbps).

Definition at line 1048 of file mpg123.h.

blocktype

int mpg123_moreinfo::blocktype[2][2]

Definition at line 1068 of file mpg123.h.

comment [1/2]

mpg123_string* mpg123_id3v2::comment

Pointer to last encountered comment text with empty description.

Definition at line 1435 of file mpg123.h.

Referenced by null_id3_links().

comment [2/2]

char mpg123_id3v1::comment[30]

Comment string.

Definition at line 1460 of file mpg123.h.

comment_list

mpg123_text* mpg123_id3v2::comment_list

Array of comments.

Definition at line 1438 of file mpg123.h.

Referenced by init_id3().

comments

size_t mpg123_id3v2::comments

Number of comments.

Definition at line 1439 of file mpg123.h.

Referenced by init_id3().

data

unsigned char* mpg123_picture::data

pointer to the image data

Definition at line 1419 of file mpg123.h.

Referenced by free_mpg123_picture(), and init_mpg123_picture().

description [1/2]

mpg123_string mpg123_text::description

Empty for the generic comment...

Definition at line 1379 of file mpg123.h.

Referenced by free_mpg123_text(), init_mpg123_text(), process_comment(), and process_extra().

description [2/2]

mpg123_string mpg123_picture::description

description string

Definition at line 1416 of file mpg123.h.

Referenced by free_mpg123_picture(), and init_mpg123_picture().

emphasis

int mpg123_frameinfo::emphasis

The emphasis type.

Definition at line 1047 of file mpg123.h.

extra

mpg123_text* mpg123_id3v2::extra

The array of extra (TXXX) fields.

Definition at line 1442 of file mpg123.h.

Referenced by init_id3().

extras

size_t mpg123_id3v2::extras

Number of extra text (TXXX) fields.

Definition at line 1443 of file mpg123.h.

Referenced by init_id3().

fill

size_t mpg123_string::fill

number of used bytes (including closing zero byte)

Definition at line 1195 of file mpg123.h.

Referenced by mpg123_copy_string(), process_comment(), and process_extra().

flags

enum mpg123_flags mpg123_frameinfo::flags

MPEG Audio flag bits. Just now I realize that it should be declared as int, not enum. It's a bitwise combination of the enum values.

Definition at line 1046 of file mpg123.h.

framesize

int mpg123_frameinfo::framesize

The size of the frame (in bytes, including header).

Definition at line 1045 of file mpg123.h.

genre [1/2]

mpg123_string* mpg123_id3v2::genre

Genre String (pointer into text_list). The genre string(s) may very well need postprocessing, esp. for ID3v2.3.

Definition at line 1434 of file mpg123.h.

Referenced by null_id3_links().

genre [2/2]

unsigned char mpg123_id3v1::genre

Genre index.

Definition at line 1461 of file mpg123.h.

id

char mpg123_text::id[4]

The ID3v2 text field id, like TALB, TPE2, ... (4 characters, no string termination).

Definition at line 1378 of file mpg123.h.

Referenced by init_mpg123_text(), process_comment(), and process_extra().

lang

char mpg123_text::lang[3]

Three-letter language code (not terminated).

Definition at line 1377 of file mpg123.h.

Referenced by init_mpg123_text(), and process_comment().

layer

int mpg123_frameinfo::layer

The MPEG Audio Layer (MP1/MP2/MP3).

Definition at line 1041 of file mpg123.h.

mainbits

int mpg123_moreinfo::mainbits[2][2]

Definition at line 1070 of file mpg123.h.

maindata

int mpg123_moreinfo::maindata

Definition at line 1073 of file mpg123.h.

mime_type

mpg123_string mpg123_picture::mime_type

MIME type

Definition at line 1417 of file mpg123.h.

Referenced by free_mpg123_picture(), and init_mpg123_picture().

mixed

int mpg123_moreinfo::mixed[2][2]

Definition at line 1069 of file mpg123.h.

mode

enum mpg123_mode mpg123_frameinfo::mode

The audio mode (Mono, Stereo, Joint-stero, Dual Channel).

Definition at line 1043 of file mpg123.h.

mode_ext

int mpg123_frameinfo::mode_ext

The mode extension bit flag.

Definition at line 1044 of file mpg123.h.

p

char* mpg123_string::p

pointer to the string data

Definition at line 1193 of file mpg123.h.

Referenced by mpg123_copy_string(), process_comment(), and process_extra().

padding

int mpg123_moreinfo::padding

Definition at line 1074 of file mpg123.h.

picture

mpg123_picture* mpg123_id3v2::picture

Array of ID3v2 pictures fields (APIC). Only populated if MPG123_PICTURE flag is set!

Definition at line 1444 of file mpg123.h.

Referenced by init_id3().

pictures

size_t mpg123_id3v2::pictures

Number of picture (APIC) fields.

Definition at line 1446 of file mpg123.h.

Referenced by init_id3().

preflag

int mpg123_moreinfo::preflag[2][2]

Definition at line 1067 of file mpg123.h.

qss

int mpg123_moreinfo::qss[2][2]

Definition at line 1063 of file mpg123.h.

rate

long mpg123_frameinfo::rate

The sampling rate in Hz.

Definition at line 1042 of file mpg123.h.

scalefac_scale

int mpg123_moreinfo::scalefac_scale[2][2]

Definition at line 1066 of file mpg123.h.

scfsi

int mpg123_moreinfo::scfsi[2]

Definition at line 1072 of file mpg123.h.

sfb

double mpg123_moreinfo::sfb[2][2][22]

Definition at line 1061 of file mpg123.h.

sfb_s

double mpg123_moreinfo::sfb_s[2][2][3 *13]

Definition at line 1062 of file mpg123.h.

sfbits

int mpg123_moreinfo::sfbits[2][2]

Definition at line 1071 of file mpg123.h.

size [1/2]

size_t mpg123_string::size

raw number of bytes allocated

Definition at line 1194 of file mpg123.h.

size [2/2]

size_t mpg123_picture::size

size in bytes

Definition at line 1418 of file mpg123.h.

Referenced by init_mpg123_picture().

sub_gain

int mpg123_moreinfo::sub_gain[2][2][3]

Definition at line 1065 of file mpg123.h.

tag

char mpg123_id3v1::tag[3]

Always the string "TAG", the classic intro.

Definition at line 1455 of file mpg123.h.

text [1/2]

mpg123_string mpg123_text::text

...

Definition at line 1380 of file mpg123.h.

Referenced by free_mpg123_text(), init_mpg123_text(), process_comment(), and process_extra().

text [2/2]

mpg123_text* mpg123_id3v2::text

Array of ID3v2 text fields (including USLT)

Definition at line 1440 of file mpg123.h.

Referenced by init_id3().

texts

size_t mpg123_id3v2::texts

Numer of text fields.

Definition at line 1441 of file mpg123.h.

Referenced by init_id3().

title [1/2]

mpg123_string* mpg123_id3v2::title

Title string (pointer into text_list).

Definition at line 1430 of file mpg123.h.

Referenced by null_id3_links().

title [2/2]

char mpg123_id3v1::title[30]

Title string.

Definition at line 1456 of file mpg123.h.

type

char mpg123_picture::type

mpg123_id3_pic_type value

Definition at line 1415 of file mpg123.h.

Referenced by init_mpg123_picture().

vbr

enum mpg123_vbr mpg123_frameinfo::vbr

The VBR mode.

Definition at line 1050 of file mpg123.h.

version [1/2]

enum mpg123_version mpg123_frameinfo::version

The MPEG version (1.0/2.0/2.5).

Definition at line 1040 of file mpg123.h.

version [2/2]

unsigned char mpg123_id3v2::version

3 or 4 for ID3v2.3 or ID3v2.4.

Definition at line 1429 of file mpg123.h.

Referenced by init_id3(), and parse_new_id3().

xr

double mpg123_moreinfo::xr[2][2][576]

Definition at line 1060 of file mpg123.h.

year [1/2]

mpg123_string* mpg123_id3v2::year

The year as a string (pointer into text_list).

Definition at line 1433 of file mpg123.h.

Referenced by null_id3_links().

year [2/2]

char mpg123_id3v1::year[4]

Year string.

Definition at line 1459 of file mpg123.h.