mpg123 status and information

Collaboration diagram for mpg123 status and information:

Modules
	mpg123 metadata handling

Classes
struct	mpg123_frameinfo
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_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 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)

Detailed Description

Enumeration Type Documentation

mpg123_flags

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

                  {
    MPG123_CRC=0x1,         
    MPG123_COPYRIGHT=0x2,   
    MPG123_PRIVATE=0x4,     
    MPG123_ORIGINAL=0x8 
};

mpg123_mode

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

                 {
    MPG123_M_STEREO=0,  
    MPG123_M_JOINT,     
    MPG123_M_DUAL,      
    MPG123_M_MONO       
};

mpg123_state

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

{
     MPG123_ACCURATE = 1 
    ,MPG123_BUFFERFILL   
    ,MPG123_FRANKENSTEIN 
    ,MPG123_FRESH_DECODER 
    ,MPG123_ENC_DELAY 
    ,MPG123_ENC_PADDING 
    ,MPG123_DEC_DELAY 
};

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

                {
    MPG123_CBR=0,   
    MPG123_VBR,     
    MPG123_ABR      
};

mpg123_version

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

                    {
    MPG123_1_0=0,   
    MPG123_2_0,     
    MPG123_2_5      
};

Function Documentation

mpg123_clip()

MPG123_EXPORT long mpg123_clip

(

mpg123_handle *

mh

)

Get and reset the clip count.

Parameters

mh

handle

Returns

count of clipped samples

Definition at line 1061 of file libmpg123.c.

{
    long ret = 0;
 
    if(mh != NULL)
    {
        ret = mh->clip;
        mh->clip = 0;
    }
    return ret;
}

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

mh

handle

Returns

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

Definition at line 208 of file lfs_alias.c.

{
    return NATIVE_NAME(mpg123_framelength)(mh);
}

Referenced by mpg123_framelength().

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.

Parameters

mh	handle
key	the key to identify the information to give.
val	the address to return (long) integer values to
fval	the address to return floating point values to

Returns

MPG123_OK on success

Definition at line 360 of file libmpg123.c.

{
    int ret = MPG123_OK;
    long theval = 0;
    double thefval = 0.;
 
    if(mh == NULL) return MPG123_BAD_HANDLE;
 
    switch(key)
    {
        case MPG123_ACCURATE:
            theval = mh->state_flags & FRAME_ACCURATE;
        break;
        case MPG123_FRANKENSTEIN:
            theval = mh->state_flags & FRAME_FRANKENSTEIN;
        break;
        case MPG123_BUFFERFILL:
#ifndef NO_FEEDER
        {
            size_t sval = bc_fill(&mh->rdat.buffer);
            theval = (long)sval;
            if(theval < 0 || (size_t)theval != sval)
            {
                mh->err = MPG123_INT_OVERFLOW;
                ret = MPG123_ERR;
            }
        }
#else
            mh->err = MPG123_MISSING_FEATURE;
            ret = MPG123_ERR;
#endif
        break;
        case MPG123_FRESH_DECODER:
            theval = mh->state_flags & FRAME_FRESH_DECODER;
            mh->state_flags &= ~FRAME_FRESH_DECODER;
        break;
        case MPG123_ENC_DELAY:
            theval = mh->enc_delay;
        break;
        case MPG123_ENC_PADDING:
            theval = mh->enc_padding;
        break;
        case MPG123_DEC_DELAY:
            theval = mh->lay == 3 ? GAPLESS_DELAY : -1;
        break;
        default:
            mh->err = MPG123_BAD_KEY;
            ret = MPG123_ERR;
    }
 
    if(val  != NULL) *val  = theval;
    if(fval != NULL) *fval = thefval;
 
    return ret;
}

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.

Parameters

mh	handle
mi	address of existing frameinfo structure to write to

Returns

MPG123_OK on success

Definition at line 1087 of file libmpg123.c.

{
    int b;
 
    if(mh == NULL) return MPG123_BAD_HANDLE;
    if(mi == NULL)
    {
        mh->err = MPG123_ERR_NULL;
        return MPG123_ERR;
    }
    b = init_track(mh);
    if(b < 0) return b;
 
    mi->version = mh->mpeg25 ? MPG123_2_5 : (mh->lsf ? MPG123_2_0 : MPG123_1_0);
    mi->layer = mh->lay;
    mi->rate = frame_freq(mh);
    switch(mh->mode)
    {
        case 0: mi->mode = MPG123_M_STEREO; break;
        case 1: mi->mode = MPG123_M_JOINT;  break;
        case 2: mi->mode = MPG123_M_DUAL;   break;
        case 3: mi->mode = MPG123_M_MONO;   break;
        default: mi->mode = 0; // Nothing good to do here.
    }
    mi->mode_ext = mh->mode_ext;
    mi->framesize = mh->framesize+4; /* Include header. */
    mi->flags = 0;
    if(mh->error_protection) mi->flags |= MPG123_CRC;
    if(mh->copyright)        mi->flags |= MPG123_COPYRIGHT;
    if(mh->extension)        mi->flags |= MPG123_PRIVATE;
    if(mh->original)         mi->flags |= MPG123_ORIGINAL;
    mi->emphasis = mh->emphasis;
    mi->bitrate  = frame_bitrate(mh);
    mi->abr_rate = mh->abr_rate;
    mi->vbr = mh->vbr;
    return MPG123_OK;
}

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

mh

handle

Returns

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

Definition at line 214 of file lfs_alias.c.

{
    return NATIVE_NAME(mpg123_length)(mh);
}

Referenced by mpg123_length().

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

Definition at line 647 of file libmpg123.c.

{
    /* real is the largest possible output (it's 32bit float, 32bit int or 64bit double). */
    return sizeof(real)*2*1152*NTOM_MAX;
}

Referenced by mpg123_outblock().

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

mh

handle

Returns

MPG123_OK on success

Definition at line 1461 of file libmpg123.c.

{
    int b;
    off_t oldpos;
    off_t track_frames = 0;
    off_t track_samples = 0;
 
    if(mh == NULL) return MPG123_BAD_HANDLE;
    if(!(mh->rdat.flags & READER_SEEKABLE)){ mh->err = MPG123_NO_SEEK; return MPG123_ERR; }
    /* Scan through the _whole_ file, since the current position is no count but computed assuming constant samples per frame. */
    /* Also, we can just keep the current buffer and seek settings. Just operate on input frames here. */
    debug("issuing scan");
    b = init_track(mh); /* mh->num >= 0 !! */
    if(b<0)
    {
        if(b == MPG123_DONE) return MPG123_OK;
        else return MPG123_ERR; /* Must be error here, NEED_MORE is not for seekable streams. */
    }
    oldpos = mpg123_tell(mh);
    b = mh->rd->seek_frame(mh, 0);
    if(b<0 || mh->num != 0) return MPG123_ERR;
    /* One frame must be there now. */
    track_frames = 1;
    track_samples = mh->spf; /* Internal samples. */
    debug("TODO: We should disable gapless code when encountering inconsistent mh->spf!");
    debug("      ... at least unset MPG123_ACCURATE.");
    /* Do not increment mh->track_frames in the loop as tha would confuse Frankenstein detection. */
    while(read_frame(mh) == 1)
    {
        ++track_frames;
        track_samples += mh->spf;
    }
    mh->track_frames = track_frames;
    mh->track_samples = track_samples;
    debug2("Scanning yielded %"OFF_P" track samples, %"OFF_P" frames.", (off_p)mh->track_samples, (off_p)mh->track_frames);
#ifdef GAPLESS
    /* Also, think about usefulness of that extra value track_samples ... it could be used for consistency checking. */
    if(mh->p.flags & MPG123_GAPLESS) frame_gapless_update(mh, mh->track_samples);
#endif
    return mpg123_seek(mh, oldpos, SEEK_SET) >= 0 ? MPG123_OK : MPG123_ERR;
}

Referenced by mpg123_seek(), and open_fixed_post().

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

mh	handle
size	file size in bytes

Returns

MPG123_OK on success

Definition at line 507 of file lfs_wrap.c.

{
    return MPG123_LARGENAME(mpg123_set_filesize)(mh, size);
}

Referenced by mpg123_set_filesize().

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

mh	handle
mi	pointer 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)

Definition at line 638 of file frame.c.

{
#ifndef NO_MOREINFO
    mh->pinfo = mi;
    return MPG123_OK;
#else
    mh->err = MPG123_MISSING_FEATURE;
    return MPG123_ERR;
#endif
}

mpg123_spf()

MPG123_EXPORT int mpg123_spf

(

mpg123_handle *

mh

)

Get MPEG frame duration in samples.

Parameters

mh

handle

Returns

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

Definition at line 973 of file parse.c.

{
    if(mh == NULL) return MPG123_ERR;
 
    return mh->firsthead ? mh->spf : MPG123_ERR;
}

mpg123_tpf()

MPG123_EXPORT double mpg123_tpf

(

mpg123_handle *

mh

)

Get MPEG frame duration in seconds.

Parameters

mh

handle

Returns

frame duration in seconds, <0 on error

Definition at line 980 of file parse.c.

{
    static int bs[4] = { 0,384,1152,1152 };
    double tpf;
    if(fr == NULL || !fr->firsthead) return MPG123_ERR;
 
    tpf = (double) bs[fr->lay];
    tpf /= freqs[fr->sampling_frequency] << (fr->lsf);
    return tpf;
}

Referenced by get_songlen(), mpg123_position(), and mpg123_timeframe().