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;-).
mpg123 status and information

Classes

struct  mpg123_frameinfo
 
struct  mpg123_frameinfo2
 
struct  mpg123_moreinfo
 

Enumerations

enum  mpg123_vbr {
  MPG123_CBR =0 , MPG123_VBR ,
  MPG123_ABR
}
 
enum  mpg123_version {
  MPG123_1_0 =0 , MPG123_2_0 ,
  MPG123_2_5
}
 
enum  mpg123_mode {
  MPG123_M_STEREO =0 , MPG123_M_JOINT ,
  MPG123_M_DUAL , MPG123_M_MONO
}
 
enum  mpg123_flags {
  MPG123_CRC =0x1 , MPG123_COPYRIGHT =0x2 ,
  MPG123_PRIVATE =0x4 , MPG123_ORIGINAL =0x8
}
 
enum  mpg123_state {
  MPG123_ACCURATE = 1 , MPG123_BUFFERFILL ,
  MPG123_FRANKENSTEIN , MPG123_FRESH_DECODER ,
  MPG123_ENC_DELAY , MPG123_ENC_PADDING ,
  MPG123_DEC_DELAY
}
 

Functions

MPG123_EXPORT int mpg123_info (mpg123_handle *mh, struct mpg123_frameinfo *mi)
 
MPG123_EXPORT int mpg123_info2 (mpg123_handle *mh, struct mpg123_frameinfo2 *mi)
 
MPG123_EXPORT int mpg123_set_moreinfo (mpg123_handle *mh, struct mpg123_moreinfo *mi)
 
MPG123_EXPORT size_t mpg123_safe_buffer (void)
 
MPG123_EXPORT int mpg123_scan (mpg123_handle *mh)
 
MPG123_EXPORT off_t mpg123_framelength (mpg123_handle *mh)
 
MPG123_EXPORT off_t mpg123_length (mpg123_handle *mh)
 
MPG123_EXPORT int mpg123_set_filesize (mpg123_handle *mh, off_t size)
 
MPG123_EXPORT int64_t mpg123_framelength64 (mpg123_handle *mh)
 
MPG123_EXPORT int64_t mpg123_length64 (mpg123_handle *mh)
 
MPG123_EXPORT int mpg123_set_filesize64 (mpg123_handle *mh, int64_t size)
 
MPG123_EXPORT double mpg123_tpf (mpg123_handle *mh)
 
MPG123_EXPORT int mpg123_spf (mpg123_handle *mh)
 
MPG123_EXPORT long mpg123_clip (mpg123_handle *mh)
 
MPG123_EXPORT int mpg123_getstate (mpg123_handle *mh, enum mpg123_state key, long *val, double *fval)
 
MPG123_EXPORT int mpg123_getstate2 (mpg123_handle *mh, int key, long *val, double *fval)
 

Detailed Description

Enumeration Type Documentation

◆ mpg123_vbr

enum mpg123_vbr

Enumeration of the mode types of Variable Bitrate

Enumerator
MPG123_CBR 

Constant Bitrate Mode (default)

MPG123_VBR 

Variable Bitrate Mode

MPG123_ABR 

Average Bitrate Mode

Definition at line 1358 of file mpg123.h.

◆ mpg123_version

Enumeration of the MPEG Versions

Enumerator
MPG123_1_0 

MPEG Version 1.0

MPG123_2_0 

MPEG Version 2.0

MPG123_2_5 

MPEG Version 2.5

Definition at line 1365 of file mpg123.h.

◆ mpg123_mode

Enumeration of the MPEG Audio mode. Only the mono mode has 1 channel, the others have 2 channels.

Enumerator
MPG123_M_STEREO 

Standard Stereo.

MPG123_M_JOINT 

Joint Stereo.

MPG123_M_DUAL 

Dual Channel.

MPG123_M_MONO 

Single Channel.

Definition at line 1374 of file mpg123.h.

◆ mpg123_flags

Enumeration of the MPEG Audio flag bits

Enumerator
MPG123_CRC 

The bitstream is error protected using 16-bit CRC.

MPG123_COPYRIGHT 

The bitstream is copyrighted.

MPG123_PRIVATE 

The private bit has been set.

MPG123_ORIGINAL 

The bitstream is an original, not a copy.

Definition at line 1383 of file mpg123.h.

◆ mpg123_state

The key values for state information from mpg123_getstate().

Enumerator
MPG123_ACCURATE 

Query if positons are currently accurate (integer value, 0 if false, 1 if true).

MPG123_BUFFERFILL 

Get fill of internal (feed) input buffer as integer byte count returned as long and as double. An error is returned on integer overflow while converting to (signed) long, but the returned floating point value shold still be fine.

MPG123_FRANKENSTEIN 

Stream consists of carelessly stitched together files. Seeking may yield unexpected results (also with MPG123_ACCURATE, it may be confused).

MPG123_FRESH_DECODER 

Decoder structure has been updated, possibly indicating changed stream (integer value, 0 if false, 1 if true). Flag is cleared after retrieval.

MPG123_ENC_DELAY 

Encoder delay read from Info tag (layer III, -1 if unknown).

MPG123_ENC_PADDING 

Encoder padding read from Info tag (layer III, -1 if unknown).

MPG123_DEC_DELAY 

Decoder delay (for layer III only, -1 otherwise).

Definition at line 1578 of file mpg123.h.

Function Documentation

◆ mpg123_info()

MPG123_EXPORT int mpg123_info ( mpg123_handle mh,
struct mpg123_frameinfo mi 
)

Get frame information about the MPEG audio bitstream and store it in a mpg123_frameinfo structure.

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

Parameters
mhhandle
miaddress of existing frameinfo structure to write to
Returns
MPG123_OK on success

◆ mpg123_info2()

MPG123_EXPORT int mpg123_info2 ( mpg123_handle mh,
struct mpg123_frameinfo2 mi 
)

Get frame information about the MPEG audio bitstream and store it in a mpg123_frameinfo2 structure.

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

Parameters
mhhandle
miaddress of existing frameinfo structure to write to
Returns
MPG123_OK on success

◆ mpg123_set_moreinfo()

MPG123_EXPORT int mpg123_set_moreinfo ( mpg123_handle mh,
struct mpg123_moreinfo mi 
)

Trigger collection of additional decoder information while decoding.

Parameters
mhhandle
mipointer to data storage (NULL to disable collection)
Returns
MPG123_OK if the collection was enabled/disabled as desired, MPG123_ERR otherwise (e.g. if the feature is disabled)

◆ mpg123_safe_buffer()

MPG123_EXPORT size_t mpg123_safe_buffer ( void  )

Get the safe output buffer size for all cases (when you want to replace the internal buffer)

Returns
safe buffer size

◆ mpg123_scan()

MPG123_EXPORT int mpg123_scan ( mpg123_handle mh)

Make a full parsing scan of each frame in the file. ID3 tags are found. An accurate length value is stored. Seek index will be filled. A seek back to current position is performed. At all, this function refuses work when stream is not seekable.

Parameters
mhhandle
Returns
MPG123_OK on success

◆ mpg123_framelength()

MPG123_EXPORT off_t mpg123_framelength ( mpg123_handle mh)

Return, if possible, the full (expected) length of current track in MPEG frames.

Parameters
mhhandle
Returns
length >= 0 or MPG123_ERR if there is no length guess possible.

◆ mpg123_length()

MPG123_EXPORT off_t mpg123_length ( mpg123_handle mh)

Return, if possible, the full (expected) length of current track in samples (PCM frames).

This relies either on an Info frame at the beginning or a previous call to mpg123_scan() to get the real number of MPEG frames in a file. It will guess based on file size if neither Info frame nor scan data are present. In any case, there is no guarantee that the decoder will not give you more data, for example in case the open file gets appended to during decoding.

Parameters
mhhandle
Returns
length >= 0 or MPG123_ERR if there is no length guess possible.

◆ mpg123_set_filesize()

MPG123_EXPORT int mpg123_set_filesize ( mpg123_handle mh,
off_t  size 
)

Override the value for file size in bytes. Useful for getting sensible track length values in feed mode or for HTTP streams.

Parameters
mhhandle
sizefile size in bytes
Returns
MPG123_OK on success

◆ mpg123_framelength64()

MPG123_EXPORT int64_t mpg123_framelength64 ( mpg123_handle mh)

Return, if possible, the full (expected) length of current track in MPEG frames as 64 bit number.

Parameters
mhhandle
Returns
length >= 0 or MPG123_ERR if there is no length guess possible.

◆ mpg123_length64()

MPG123_EXPORT int64_t mpg123_length64 ( mpg123_handle mh)

Return, if possible, the full (expected) length of current track in samples (PCM frames) as 64 bit value.

This relies either on an Info frame at the beginning or a previous call to mpg123_scan() to get the real number of MPEG frames in a file. It will guess based on file size if neither Info frame nor scan data are present. In any case, there is no guarantee that the decoder will not give you more data, for example in case the open file gets appended to during decoding.

Parameters
mhhandle
Returns
length >= 0 or MPG123_ERR if there is no length guess possible.

◆ mpg123_set_filesize64()

MPG123_EXPORT int mpg123_set_filesize64 ( mpg123_handle mh,
int64_t  size 
)

Override the 64 bit value for file size in bytes. Useful for getting sensible track length values in feed mode or for HTTP streams.

Parameters
mhhandle
sizefile size in bytes
Returns
MPG123_OK on success

◆ mpg123_tpf()

MPG123_EXPORT double mpg123_tpf ( mpg123_handle mh)

Get MPEG frame duration in seconds.

Parameters
mhhandle
Returns
frame duration in seconds, <0 on error

◆ mpg123_spf()

MPG123_EXPORT int mpg123_spf ( mpg123_handle mh)

Get MPEG frame duration in samples.

Parameters
mhhandle
Returns
samples per frame for the most recently parsed frame; <0 on errors

◆ mpg123_clip()

MPG123_EXPORT long mpg123_clip ( mpg123_handle mh)

Get and reset the clip count.

Parameters
mhhandle
Returns
count of clipped samples

◆ mpg123_getstate()

MPG123_EXPORT int mpg123_getstate ( mpg123_handle mh,
enum mpg123_state  key,
long *  val,
double *  fval 
)

Get various current decoder/stream state information.

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

Parameters
mhhandle
keythe key to identify the information to give.
valthe address to return (long) integer values to
fvalthe address to return floating point values to
Returns
MPG123_OK on success

◆ mpg123_getstate2()

MPG123_EXPORT int mpg123_getstate2 ( mpg123_handle mh,
int  key,
long *  val,
double *  fval 
)

Get various current decoder/stream state information. No enums.

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

Parameters
mhhandle
keythe key to identify the information to give (enum mpg123_state)
valthe address to return (long) integer values to
fvalthe address to return floating point values to
Returns
MPG123_OK on success
Hopefully valid HTML! Valid CSS!