mpg123 file input and decoding

Collaboration diagram for mpg123 file input and decoding:

Modules
	mpg123 position and seeking

Functions
MPG123_EXPORT int	mpg123_open_fixed (mpg123_handle *mh, const char *path, int channels, int encoding)
MPG123_EXPORT int	mpg123_open (mpg123_handle *mh, const char *path)
MPG123_EXPORT int	mpg123_open_fd (mpg123_handle *mh, int fd)
MPG123_EXPORT int	mpg123_open_handle (mpg123_handle *mh, void *iohandle)
MPG123_EXPORT int	mpg123_open_feed (mpg123_handle *mh)
MPG123_EXPORT int	mpg123_close (mpg123_handle *mh)
MPG123_EXPORT int	mpg123_read (mpg123_handle *mh, void *outmemory, size_t outmemsize, size_t *done)
MPG123_EXPORT int	mpg123_feed (mpg123_handle *mh, const unsigned char *in, size_t size)
MPG123_EXPORT int	mpg123_decode (mpg123_handle *mh, const unsigned char *inmemory, size_t inmemsize, void *outmemory, size_t outmemsize, size_t *done)
MPG123_EXPORT int	mpg123_decode_frame (mpg123_handle *mh, off_t *num, unsigned char **audio, size_t *bytes)
MPG123_EXPORT int	mpg123_framebyframe_decode (mpg123_handle *mh, off_t *num, unsigned char **audio, size_t *bytes)
MPG123_EXPORT int	mpg123_framebyframe_next (mpg123_handle *mh)
MPG123_EXPORT int	mpg123_framedata (mpg123_handle *mh, unsigned long *header, unsigned char **bodydata, size_t *bodybytes)
MPG123_EXPORT off_t	mpg123_framepos (mpg123_handle *mh)

Detailed Description

Functions for input bitstream and decoding operations. Decoding/seek functions may also return message codes MPG123_DONE, MPG123_NEW_FORMAT and MPG123_NEED_MORE (please read up on these on how to react!).

Function Documentation

mpg123_close()

MPG123_EXPORT int mpg123_close

(

mpg123_handle *

mh

)

Closes the source, if libmpg123 opened it.

Parameters

mh

handle

Returns

MPG123_OK on success

Definition at line 1694 of file libmpg123.c.

{
    if(mh == NULL) return MPG123_BAD_HANDLE;
 
    /* mh->rd is never NULL! */
    if(mh->rd->close != NULL) mh->rd->close(mh);
 
    if(mh->new_format)
    {
        debug("Hey, we are closing a track before the new format has been queried...");
        invalidate_format(&mh->af);
        mh->new_format = 0;
    }
    /* Always reset the frame buffers on close, so we cannot forget it in funky opening routines (wrappers, even). */
    frame_reset(mh);
    return MPG123_OK;
}

Referenced by mpg123_delete(), mpg123_open(), mpg123_open_fd(), mpg123_open_feed(), mpg123_open_handle(), mpg123_replace_reader(), mpg123_replace_reader_handle(), and open_fixed_post().

mpg123_decode()

MPG123_EXPORT int mpg123_decode	(	mpg123_handle *	mh,
		const unsigned char *	inmemory,
		size_t	inmemsize,
		void *	outmemory,
		size_t	outmemsize,
		size_t *	done
	)

Decode MPEG Audio from inmemory to outmemory. This is very close to a drop-in replacement for old mpglib. When you give zero-sized output buffer the input will be parsed until decoded data is available. This enables you to get MPG123_NEW_FORMAT (and query it) without taking decoded data. Think of this function being the union of mpg123_read() and mpg123_feed() (which it actually is, sort of;-). You can actually always decide if you want those specialized functions in separate steps or one call this one here.

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

Parameters

mh	handle
inmemory	input buffer
inmemsize	number of input bytes
outmemory	output buffer
outmemsize	maximum number of output bytes
done	address to store the number of actually decoded bytes to

Returns

error/message code (watch out especially for MPG123_NEED_MORE)

Definition at line 992 of file libmpg123.c.

{
    int ret = MPG123_OK;
    size_t mdone = 0;
    unsigned char *outmemory = outmem;
 
    if(done != NULL) *done = 0;
    if(mh == NULL) return MPG123_BAD_HANDLE;
    if(inmemsize > 0 && mpg123_feed(mh, inmemory, inmemsize) != MPG123_OK)
    {
        ret = MPG123_ERR;
        goto decodeend;
    }
    if(outmemory == NULL) outmemsize = 0; /* Not just give error, give chance to get a status message. */
 
    while(ret == MPG123_OK)
    {
        debug4("decode loop, fill %i (%li vs. %li); to_decode: %i", (int)mh->buffer.fill, (long)mh->num, (long)mh->firstframe, mh->to_decode);
        /* Decode a frame that has been read before.
           This only happens when buffer is empty! */
        if(mh->to_decode)
        {
            if(mh->new_format)
            {
                debug("notifiying new format");
                mh->new_format = 0;
                ret = MPG123_NEW_FORMAT;
                goto decodeend;
            }
            if(mh->buffer.size - mh->buffer.fill < mh->outblock)
            {
                ret = MPG123_NO_SPACE;
                goto decodeend;
            }
            if(mh->decoder_change && decode_update(mh) < 0)
            {
                ret = MPG123_ERR;
                goto decodeend;
            }
            decode_the_frame(mh);
            mh->to_decode = mh->to_ignore = FALSE;
            mh->buffer.p = mh->buffer.data;
            debug2("decoded frame %li, got %li samples in buffer", (long)mh->num, (long)(mh->buffer.fill / (samples_to_bytes(mh, 1))));
            FRAME_BUFFERCHECK(mh);
        }
        if(mh->buffer.fill) /* Copy (part of) the decoded data to the caller's buffer. */
        {
            /* get what is needed - or just what is there */
            int a = mh->buffer.fill > (outmemsize - mdone) ? outmemsize - mdone : mh->buffer.fill;
            debug4("buffer fill: %i; copying %i (%i - %li)", (int)mh->buffer.fill, a, (int)outmemsize, (long)mdone);
            memcpy(outmemory, mh->buffer.p, a);
            /* less data in frame buffer, less needed, output pointer increase, more data given... */
            mh->buffer.fill -= a;
            outmemory  += a;
            mdone += a;
            mh->buffer.p += a;
            if(!(outmemsize > mdone)) goto decodeend;
        }
        else /* If we didn't have data, get a new frame. */
        {
            int b = get_next_frame(mh);
            if(b < 0){ ret = b; goto decodeend; }
        }
    }
decodeend:
    if(done != NULL) *done = mdone;
    return ret;
}

Referenced by mpg123_read().

mpg123_decode_frame()

MPG123_EXPORT int mpg123_decode_frame	(	mpg123_handle *	mh,
		off_t *	num,
		unsigned char **	audio,
		size_t *	bytes
	)

Decode next MPEG frame to internal buffer or read a frame and return after setting a new format.

Parameters

mh	handle
num	current frame offset gets stored there
audio	This pointer is set to the internal buffer to read the decoded audio from.
bytes	number of output bytes ready in the buffer

Returns

MPG123_OK or error/message code

Definition at line 166 of file lfs_wrap.c.

{
    off_t largenum;
    int err;
 
    err = MPG123_LARGENAME(mpg123_decode_frame)(mh, &largenum, audio, bytes);
    if(err == MPG123_OK && num != NULL)
    {
        *num = largenum;
        if(*num != largenum)
        {
            mh->err = MPG123_LFS_OVERFLOW;
            err = MPG123_ERR;
        }
    }
    return err;
}

Referenced by mpg123_decode_frame().

mpg123_feed()

MPG123_EXPORT int mpg123_feed	(	mpg123_handle *	mh,
		const unsigned char *	in,
		size_t	size
	)

Feed data for a stream that has been opened with mpg123_open_feed(). It's give and take: You provide the bytestream, mpg123 gives you the decoded samples.

Parameters

mh	handle
in	input buffer
size	number of input bytes

Returns

MPG123_OK or error/message code.

Definition at line 947 of file libmpg123.c.

{
    if(mh == NULL) return MPG123_BAD_HANDLE;
#ifndef NO_FEEDER
    if(size > 0)
    {
        if(in != NULL)
        {
            if(feed_more(mh, in, size) != 0) return MPG123_ERR;
            else
            {
                /* The need for more data might have triggered an error.
                   This one is outdated now with the new data. */
                if(mh->err == MPG123_ERR_READER) mh->err = MPG123_OK;
 
                return MPG123_OK;
            }
        }
        else
        {
            mh->err = MPG123_NULL_BUFFER;
            return MPG123_ERR;
        }
    }
    return MPG123_OK;
#else
    mh->err = MPG123_MISSING_FEATURE;
    return MPG123_ERR;
#endif
}

Referenced by mpg123_decode().

mpg123_framebyframe_decode()

MPG123_EXPORT int mpg123_framebyframe_decode	(	mpg123_handle *	mh,
		off_t *	num,
		unsigned char **	audio,
		size_t *	bytes
	)

Decode current MPEG frame to internal buffer. Warning: This is experimental API that might change in future releases! Please watch mpg123 development closely when using it.

Parameters

mh	handle
num	last frame offset gets stored there
audio	this pointer is set to the internal buffer to read the decoded audio from.
bytes	number of output bytes ready in the buffer

Returns

MPG123_OK or error/message code

Definition at line 186 of file lfs_wrap.c.

{
    off_t largenum;
    int err;
 
    err = MPG123_LARGENAME(mpg123_framebyframe_decode)(mh, &largenum, audio, bytes);
    if(err == MPG123_OK && num != NULL)
    {
        *num = largenum;
        if(*num != largenum)
        {
            mh->err = MPG123_LFS_OVERFLOW;
            err = MPG123_ERR;
        }
    }
    return err;
}

Referenced by mpg123_framebyframe_decode().

mpg123_framebyframe_next()

MPG123_EXPORT int mpg123_framebyframe_next

(

mpg123_handle *

mh

)

Find, read and parse the next mp3 frame Warning: This is experimental API that might change in future releases! Please watch mpg123 development closely when using it.

Parameters

mh

handle

Returns

MPG123_OK or error/message code

Definition at line 860 of file libmpg123.c.

{
    int b;
    if(mh == NULL) return MPG123_BAD_HANDLE;
 
    mh->to_decode = mh->to_ignore = FALSE;
    mh->buffer.fill = 0;
 
    b = get_next_frame(mh);
    if(b < 0) return b;
    debug1("got next frame, %i", mh->to_decode);
 
    /* mpg123_framebyframe_decode will return MPG123_OK with 0 bytes decoded if mh->to_decode is 0 */
    if(!mh->to_decode)
        return MPG123_OK;
 
    if(mh->new_format)
    {
        debug("notifiying new format");
        mh->new_format = 0;
        return MPG123_NEW_FORMAT;
    }
 
    return MPG123_OK;
}

mpg123_framedata()

MPG123_EXPORT int mpg123_framedata	(	mpg123_handle *	mh,
		unsigned long *	header,
		unsigned char **	bodydata,
		size_t *	bodybytes
	)

Get access to the raw input data for the last parsed frame. This gives you a direct look (and write access) to the frame body data. Together with the raw header, you can reconstruct the whole raw MPEG stream without junk and meta data, or play games by actually modifying the frame body data before decoding this frame (mpg123_framebyframe_decode()). A more sane use would be to use this for CRC checking (see mpg123_info() and MPG123_CRC), the first two bytes of the body make up the CRC16 checksum, if present. You can provide NULL for a parameter pointer when you are not interested in the value.

Parameters

mh	handle
header	the 4-byte MPEG header
bodydata	pointer to the frame body stored in the handle (without the header)
bodybytes	size of frame body in bytes (without the header)

Returns

MPG123_OK if there was a yet un-decoded frame to get the data from, MPG123_BAD_HANDLE or MPG123_ERR otherwise (without further explanation, the error state of the mpg123_handle is not modified by this function).

Definition at line 626 of file frame.c.

{
    if(mh == NULL)     return MPG123_BAD_HANDLE;
    if(!mh->to_decode) return MPG123_ERR;
 
    if(header    != NULL) *header    = mh->oldhead;
    if(bodydata  != NULL) *bodydata  = mh->bsbuf;
    if(bodybytes != NULL) *bodybytes = mh->framesize;
 
    return MPG123_OK;
}

mpg123_framepos()

MPG123_EXPORT off_t mpg123_framepos

(

mpg123_handle *

mh

)

Get the input position (byte offset in stream) of the last parsed frame. This can be used for external seek index building, for example. It just returns the internally stored offset, regardless of validity – you ensure that a valid frame has been parsed before!

Parameters

mh

handle

Returns

byte offset in stream

Definition at line 1054 of file frame.c.

{
    if(mh == NULL) return MPG123_ERR;
 
    return mh->input_offset;
}

Referenced by mpg123_framepos().

mpg123_open()

MPG123_EXPORT int mpg123_open	(	mpg123_handle *	mh,
		const char *	path
	)

Open and prepare to decode the specified file by filesystem path. This does not open HTTP urls; libmpg123 contains no networking code. If you want to decode internet streams, use mpg123_open_fd() or mpg123_open_feed().

Parameters

mh	handle
path	filesystem path

Returns

MPG123_OK on success

Definition at line 112 of file lfs_alias.c.

{
    return NATIVE_NAME(mpg123_open)(mh, path);
}

Referenced by mpg123_open(), and mpg123_open_fixed().

mpg123_open_fd()

MPG123_EXPORT int mpg123_open_fd	(	mpg123_handle *	mh,
		int	fd
	)

Use an already opened file descriptor as the bitstream input mpg123_close() will not close the file descriptor.

Parameters

mh	handle
fd	file descriptor

Returns

MPG123_OK on success

Definition at line 118 of file lfs_alias.c.

{
    return NATIVE_NAME(mpg123_open_fd)(mh, fd);
}

Referenced by mpg123_open_fd().

mpg123_open_feed()

MPG123_EXPORT int mpg123_open_feed

(

mpg123_handle *

mh

)

Open a new bitstream and prepare for direct feeding This works together with mpg123_decode(); you are responsible for reading and feeding the input bitstream. Also, you are expected to handle ICY metadata extraction yourself. This input method does not handle MPG123_ICY_INTERVAL. It does parse ID3 frames, though.

Parameters

mh

handle

Returns

MPG123_OK on success

Definition at line 535 of file libmpg123.c.

{
    if(mh == NULL) return MPG123_BAD_HANDLE;
 
    mpg123_close(mh);
    return open_feed(mh);
}

mpg123_open_fixed()

MPG123_EXPORT int mpg123_open_fixed	(	mpg123_handle *	mh,
		const char *	path,
		int	channels,
		int	encoding
	)

Open a simple MPEG file with fixed properties.

This function shall simplify the common use case of a plain MPEG file on disk that you want to decode, with one fixed sample rate and channel count, and usually a length defined by a Lame/Info/Xing tag. It will:

• set the MPG123_NO_FRANKENSTEIN flag
• set up format support according to given parameters,
• open the file,
• query audio format,
• fix the audio format support table to ensure the format stays the same,
• call mpg123_scan() if there is no header frame to tell the track length.

From that on, you can call mpg123_getformat() for querying the sample rate (and channel count in case you allowed both) and mpg123_length() to get a pretty safe number for the duration. Only the sample rate is left open as that indeed is a fixed property of MPEG files. You could set MPG123_FORCE_RATE beforehand, but that may trigger low-quality resampling in the decoder, only do so if in dire need. The library will convert mono files to stereo for you, and vice versa. If any constraint cannot be satisified (most likely because of a non-default build of libmpg123), you get MPG123_ERR returned and can query the detailed cause from the handle. Only on MPG123_OK there will an open file that you then close using mpg123_close(), or implicitly on mpg123_delete() or the next call to open another file.

So, for your usual CD rip collection, you could use

mpg123_open_fixed(mh, path, MPG123_STEREO, MPG123_ENC_SIGNED_16)

and be happy calling mpg123_getformat() to verify 44100 Hz rate, then just playing away with mpg123_read(). The occasional mono file, or MP2 file, will also be decoded without you really noticing. Just the speed could be wrong if you do not care about sample rate at all.

Parameters

mh	handle
path	filesystem path
channels	allowed channel count, either 1 (MPG123_MONO) or 2 (MPG123_STEREO), or bitwise or of them, but then you're halfway back to calling mpg123_format() again;-)
encoding	a definite encoding from enum mpg123_enc_enum or a bitmask like for mpg123_format(), defeating the purpose somewhat

Definition at line 105 of file lfs_alias.c.

{
    return NATIVE_NAME(mpg123_open_fixed)(mh, path, channels, encoding);
}

Referenced by mpg123_open_fixed().

mpg123_open_handle()

MPG123_EXPORT int mpg123_open_handle	(	mpg123_handle *	mh,
		void *	iohandle
	)

Use an opaque handle as bitstream input. This works only with the replaced I/O from mpg123_replace_reader_handle()! mpg123_close() will call the cleanup callback for your handle (if you gave one).

Parameters

mh	handle
iohandle	your handle

Returns

MPG123_OK on success

Definition at line 124 of file lfs_alias.c.

{
    return NATIVE_NAME(mpg123_open_handle)(mh, iohandle);
}

Referenced by mpg123_open_handle().

mpg123_read()

MPG123_EXPORT int mpg123_read	(	mpg123_handle *	mh,
		void *	outmemory,
		size_t	outmemsize,
		size_t *	done
	)

Read from stream and decode up to outmemsize bytes.

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

Parameters

mh	handle
outmemory	address of output buffer to write to
outmemsize	maximum number of bytes to write
done	address to store the number of actually decoded bytes to

Returns

MPG123_OK or error/message code

Definition at line 942 of file libmpg123.c.

{
    return mpg123_decode(mh, NULL, 0, out, size, done);
}