mpg123 advanced parameter API

Collaboration diagram for mpg123 advanced parameter API:

Modules
	mpg123 low level I/O

Typedefs
typedef struct mpg123_pars_struct	mpg123_pars

Functions
MPG123_EXPORT mpg123_handle *	mpg123_parnew (mpg123_pars *mp, const char *decoder, int *error)
MPG123_EXPORT mpg123_pars *	mpg123_new_pars (int *error)
MPG123_EXPORT void	mpg123_delete_pars (mpg123_pars *mp)
MPG123_EXPORT int	mpg123_fmt_none (mpg123_pars *mp)
MPG123_EXPORT int	mpg123_fmt_all (mpg123_pars *mp)
MPG123_EXPORT int	mpg123_fmt (mpg123_pars *mp, long rate, int channels, int encodings)
MPG123_EXPORT int	mpg123_fmt2 (mpg123_pars *mp, long rate, int channels, int encodings)
MPG123_EXPORT int	mpg123_fmt_support (mpg123_pars *mp, long rate, int encoding)
MPG123_EXPORT int	mpg123_par (mpg123_pars *mp, enum mpg123_parms type, long value, double fvalue)
MPG123_EXPORT int	mpg123_getpar (mpg123_pars *mp, enum mpg123_parms type, long *value, double *fvalue)

Detailed Description

Direct access to a parameter set without full handle around it. Possible uses:

• Influence behaviour of library during initialization of handle (MPG123_VERBOSE).
• Use one set of parameters for multiple handles.

The functions for handling mpg123_pars (mpg123_par() and mpg123_fmt() family) directly return a fully qualified mpg123 error code, the ones operating on full handles normally MPG123_OK or MPG123_ERR, storing the specific error code itseld inside the handle.

Typedef Documentation

mpg123_pars

typedef struct mpg123_pars_struct mpg123_pars

Opaque structure for the libmpg123 decoder parameters.

Definition at line 1538 of file mpg123.h.

Function Documentation

mpg123_delete_pars()

MPG123_EXPORT void mpg123_delete_pars

(

mpg123_pars *

mp

)

Delete and free up memory used by a mpg123_pars data structure

Parameters

mp	parameter handle

Definition at line 167 of file frame.c.

{
    if(mp != NULL) free(mp);
}

mpg123_fmt()

MPG123_EXPORT int mpg123_fmt	(	mpg123_pars *	mp,
		long	rate,
		int	channels,
		int	encodings
	)

Set the audio format support of a mpg123_pars in detail:

Parameters

mp	parameter handle
rate	The sample rate value (in Hertz).
channels	A combination of MPG123_STEREO and MPG123_MONO.
encodings	A combination of accepted encodings for rate and channels, p.ex MPG123_ENC_SIGNED16|MPG123_ENC_ULAW_8 (or 0 for no support).

Returns

MPG123_OK on success

Definition at line 524 of file format.c.

{
    return (rate == 0)
    ?   MPG123_BAD_RATE
    :   mpg123_fmt2(mp, rate, channels, encodings);
}

mpg123_fmt2()

MPG123_EXPORT int mpg123_fmt2	(	mpg123_pars *	mp,
		long	rate,
		int	channels,
		int	encodings
	)

Set the audio format support of a mpg123_pars in detail:

Parameters

mp	parameter handle
rate	The sample rate value (in Hertz). Special value 0 means all rates (reason for this variant of mpg123_fmt).
channels	A combination of MPG123_STEREO and MPG123_MONO.
encodings	A combination of accepted encodings for rate and channels, p.ex MPG123_ENC_SIGNED16|MPG123_ENC_ULAW_8 (or 0 for no support).

Returns

MPG123_OK on success

Definition at line 485 of file format.c.

{
    int ie, ic, ratei, r1, r2;
    int ch[2] = {0, 1};
    if(mp == NULL) return MPG123_BAD_PARS;
    if(!(channels & (MPG123_MONO|MPG123_STEREO))) return MPG123_BAD_CHANNEL;
 
    if(PVERB(mp,3)) fprintf(stderr, "Note: Want to enable format %li/%i for encodings 0x%x.\n", rate, channels, encodings);
 
    if(!(channels & MPG123_STEREO)) ch[1] = 0;     /* {0,0} */
    else if(!(channels & MPG123_MONO)) ch[0] = 1; /* {1,1} */
    if(rate)
    {
        r1 = rate2num(mp, rate);
        r2 = r1+1;
    }
    else
    {
        r1 = 0;
        r2 = MPG123_RATES+1; /* including forced rate */
    }
 
    if(r1 < 0) return MPG123_BAD_RATE;
 
    /* now match the encodings */
    for(ratei = r1; ratei < r2; ++ratei)
    for(ic = 0; ic < 2; ++ic)
    {
        for(ie = 0; ie < MPG123_ENCODINGS; ++ie)
        if(good_enc(my_encodings[ie]) && ((my_encodings[ie] & encodings) == my_encodings[ie]))
        mp->audio_caps[ch[ic]][ratei][ie] = 1;
 
        if(ch[0] == ch[1]) break; /* no need to do it again */
    }
 
    return MPG123_OK;
}

Referenced by mpg123_fmt(), and mpg123_format2().

mpg123_fmt_all()

MPG123_EXPORT int mpg123_fmt_all

(

mpg123_pars *

mp

)

Configure mpg123 parameters to accept all formats (also any custom rate you may set) – this is default.

Parameters

mp	parameter handle

Returns

MPG123_OK on success

Definition at line 449 of file format.c.

{
    size_t rate, ch, enc;
    if(mp == NULL) return MPG123_BAD_PARS;
 
    if(PVERB(mp,3)) fprintf(stderr, "Note: Enabling all formats.\n");
 
    for(ch=0;   ch   < NUM_CHANNELS;     ++ch)
    for(rate=0; rate < MPG123_RATES+1;   ++rate)
    for(enc=0;  enc  < MPG123_ENCODINGS; ++enc)
    mp->audio_caps[ch][rate][enc] = good_enc(my_encodings[enc]) ? 1 : 0;
 
    return MPG123_OK;
}

Referenced by frame_default_pars(), and mpg123_format_all().

mpg123_fmt_none()

MPG123_EXPORT int mpg123_fmt_none

(

mpg123_pars *

mp

)

Configure mpg123 parameters to accept no output format at all, use before specifying supported formats with mpg123_format

Parameters

mp	parameter handle

Returns

MPG123_OK on success

Definition at line 428 of file format.c.

{
    if(mp == NULL) return MPG123_BAD_PARS;
 
    if(PVERB(mp,3)) fprintf(stderr, "Note: Disabling all formats.\n");
 
    memset(mp->audio_caps,0,sizeof(mp->audio_caps));
    return MPG123_OK;
}

Referenced by mpg123_format_none().

mpg123_fmt_support()

MPG123_EXPORT int mpg123_fmt_support	(	mpg123_pars *	mp,
		long	rate,
		int	encoding
	)

Check to see if a specific format at a specific rate is supported by mpg123_pars.

Parameters

mp	parameter handle
rate	sampling rate
encoding	encoding

Returns

0 for no support (that includes invalid parameters), MPG123_STEREO, MPG123_MONO or MPG123_STEREO|MPG123_MONO.

Definition at line 537 of file format.c.

{
    int ch = 0;
    int ratei, enci;
    ratei = rate2num(mp, rate);
    enci  = enc2num(encoding);
    if(mp == NULL || ratei < 0 || enci < 0) return 0;
    if(mp->audio_caps[0][ratei][enci]) ch |= MPG123_MONO;
    if(mp->audio_caps[1][ratei][enci]) ch |= MPG123_STEREO;
    return ch;
}

Referenced by mpg123_format_support().

mpg123_getpar()

MPG123_EXPORT int mpg123_getpar	(	mpg123_pars *	mp,
		enum mpg123_parms	type,
		long *	value,
		double *	fvalue
	)

Get a specific parameter, for a specific mpg123_pars. See the mpg123_parms enumeration for a list of available parameters.

Parameters

mp	parameter handle
type	parameter choice
value	integer value return address
fvalue	floating point value return address

Returns

MPG123_OK on success

Definition at line 278 of file libmpg123.c.

{
    int ret = 0;
 
    if(mp == NULL) return MPG123_BAD_PARS;
    switch(key)
    {
        case MPG123_VERBOSE:
            if(val) *val = mp->verbose;
        break;
        case MPG123_FLAGS:
        case MPG123_ADD_FLAGS:
            if(val) *val = mp->flags;
        break;
        case MPG123_FORCE_RATE:
            if(val)
#ifdef NO_NTOM
            *val = 0;
#else
            *val = mp->force_rate;
#endif
        break;
        case MPG123_DOWN_SAMPLE:
            if(val) *val = mp->down_sample;
        break;
        case MPG123_RVA:
            if(val) *val = mp->rva;
        break;
        case MPG123_DOWNSPEED:
            if(val) *val = mp->halfspeed;
        break;
        case MPG123_UPSPEED:
            if(val) *val = mp->doublespeed;
        break;
        case MPG123_ICY_INTERVAL:
#ifndef NO_ICY
            if(val) *val = (long)mp->icy_interval;
#else
            if(val) *val = 0;
#endif
        break;
        case MPG123_OUTSCALE:
            if(fval) *fval = mp->outscale;
            if(val) *val = (long)(mp->outscale*SHORT_SCALE);
        break;
        case MPG123_RESYNC_LIMIT:
            if(val) *val = mp->resync_limit;
        break;
        case MPG123_INDEX_SIZE:
            if(val)
#ifdef FRAME_INDEX
            *val = mp->index_size;
#else
            *val = 0; /* graceful fallback: no index is index of zero size */
#endif
        break;
        case MPG123_PREFRAMES:
            *val = mp->preframes;
        break;
        case MPG123_FEEDPOOL:
#ifndef NO_FEEDER
            *val = mp->feedpool;
#else
            ret = MPG123_MISSING_FEATURE;
#endif
        break;
        case MPG123_FEEDBUFFER:
#ifndef NO_FEEDER
            *val = mp->feedbuffer;
#else
            ret = MPG123_MISSING_FEATURE;
#endif
        break;
        case MPG123_FREEFORMAT_SIZE:
            *val = mp->freeformat_framesize;
        break;
        default:
            ret = MPG123_BAD_PARAM;
    }
    return ret;
}

Referenced by mpg123_getparam().

mpg123_new_pars()

MPG123_EXPORT mpg123_pars * mpg123_new_pars

(

int *

error

)

Allocate memory for and return a pointer to a new mpg123_pars

Parameters

error

error code return address

Returns

new parameter handle

Definition at line 159 of file frame.c.

{
    mpg123_pars *mp = malloc(sizeof(struct mpg123_pars_struct));
    if(mp != NULL){ frame_default_pars(mp); if(error != NULL) *error = MPG123_OK; }
    else if(error != NULL) *error = MPG123_OUT_OF_MEM;
    return mp;
}

mpg123_par()

MPG123_EXPORT int mpg123_par	(	mpg123_pars *	mp,
		enum mpg123_parms	type,
		long	value,
		double	fvalue
	)

Set a specific parameter, for a specific mpg123_pars, using a parameter type key chosen from the mpg123_parms enumeration, to the specified value.

Parameters

mp	parameter handle
type	parameter choice
value	integer value
fvalue	floating point value

Returns

MPG123_OK on success

Definition at line 152 of file libmpg123.c.

{
    int ret = MPG123_OK;
 
    if(mp == NULL) return MPG123_BAD_PARS;
    switch(key)
    {
        case MPG123_VERBOSE:
            mp->verbose = val;
        break;
        case MPG123_FLAGS:
#ifndef GAPLESS
            if(val & MPG123_GAPLESS) ret = MPG123_NO_GAPLESS;
#endif
            if(ret == MPG123_OK) mp->flags = val;
            debug1("set flags to 0x%lx", (unsigned long) mp->flags);
        break;
        case MPG123_ADD_FLAGS:
#ifndef GAPLESS
            /* Enabling of gapless mode doesn't work when it's not there, but disabling (below) is no problem. */
            if(val & MPG123_GAPLESS) ret = MPG123_NO_GAPLESS;
            else
#endif
            mp->flags |= val;
            debug1("set flags to 0x%lx", (unsigned long) mp->flags);
        break;
        case MPG123_REMOVE_FLAGS:
            mp->flags &= ~val;
            debug1("set flags to 0x%lx", (unsigned long) mp->flags);
        break;
        case MPG123_FORCE_RATE: /* should this trigger something? */
#ifdef NO_NTOM
            if(val > 0)
            ret = MPG123_BAD_RATE;
#else
            if(val > 96000) ret = MPG123_BAD_RATE;
            else mp->force_rate = val < 0 ? 0 : val; /* >0 means enable, 0 disable */
#endif
        break;
        case MPG123_DOWN_SAMPLE:
#ifdef NO_DOWNSAMPLE
            if(val != 0) ret = MPG123_BAD_RATE;
#else
            if(val < 0 || val > 2) ret = MPG123_BAD_RATE;
            else mp->down_sample = (int)val;
#endif
        break;
        case MPG123_RVA:
            if(val < 0 || val > MPG123_RVA_MAX) ret = MPG123_BAD_RVA;
            else mp->rva = (int)val;
        break;
        case MPG123_DOWNSPEED:
            mp->halfspeed = val < 0 ? 0 : val;
        break;
        case MPG123_UPSPEED:
            mp->doublespeed = val < 0 ? 0 : val;
        break;
        case MPG123_ICY_INTERVAL:
#ifndef NO_ICY
            mp->icy_interval = val > 0 ? val : 0;
#else
            if(val > 0) ret = MPG123_BAD_PARAM;
#endif
        break;
        case MPG123_OUTSCALE:
            /* Choose the value that is non-zero, if any.
               Downscaling integers to 1.0 . */
            mp->outscale = val == 0 ? fval : (double)val/SHORT_SCALE;
        break;
        case MPG123_TIMEOUT:
#ifdef TIMEOUT_READ
            mp->timeout = val >= 0 ? val : 0;
#else
            if(val > 0) ret = MPG123_NO_TIMEOUT;
#endif
        break;
        case MPG123_RESYNC_LIMIT:
            mp->resync_limit = val;
        break;
        case MPG123_INDEX_SIZE:
#ifdef FRAME_INDEX
            mp->index_size = val;
#else
            if(val) // It is only an eror if you want to enable the index.
                ret = MPG123_NO_INDEX;
#endif
        break;
        case MPG123_PREFRAMES:
            if(val >= 0) mp->preframes = val;
            else ret = MPG123_BAD_VALUE;
        break;
        case MPG123_FEEDPOOL:
#ifndef NO_FEEDER
            if(val >= 0) mp->feedpool = val;
            else ret = MPG123_BAD_VALUE;
#else
            ret = MPG123_MISSING_FEATURE;
#endif
        break;
        case MPG123_FEEDBUFFER:
#ifndef NO_FEEDER
            if(val > 0) mp->feedbuffer = val;
            else ret = MPG123_BAD_VALUE;
#else
            ret = MPG123_MISSING_FEATURE;
#endif
        break;
        case MPG123_FREEFORMAT_SIZE:
            mp->freeformat_framesize = val;
        break;
        default:
            ret = MPG123_BAD_PARAM;
    }
    return ret;
}

Referenced by mpg123_param().

mpg123_parnew()

MPG123_EXPORT mpg123_handle * mpg123_parnew	(	mpg123_pars *	mp,
		const char *	decoder,
		int *	error
	)

Create a handle with preset parameters.

Parameters

mp	parameter handle
decoder	decoder choice
error	error code return address

Returns

mpg123 handle

Definition at line 63 of file libmpg123.c.

{
    mpg123_handle *fr = NULL;
    int err = MPG123_OK;
 
    if(initialized) fr = (mpg123_handle*) malloc(sizeof(mpg123_handle));
    else err = MPG123_NOT_INITIALIZED;
    if(fr != NULL)
    {
        frame_init_par(fr, mp);
        debug("cpu opt setting");
        if(frame_cpu_opt(fr, decoder) != 1)
        {
            err = MPG123_BAD_DECODER;
            frame_exit(fr);
            free(fr);
            fr = NULL;
        }
    }
    if(fr != NULL)
    {
        fr->decoder_change = 1;
    }
    else if(err == MPG123_OK) err = MPG123_OUT_OF_MEM;
 
    if(error != NULL) *error = err;
    return fr;
}

Referenced by mpg123_new().