mpg123 file input and decoding

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_decode_frame64 (mpg123_handle *mh, int64_t *num, unsigned char **audio, size_t *bytes)
MPG123_EXPORT int	mpg123_framebyframe_decode64 (mpg123_handle *mh, int64_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)
MPG123_EXPORT int64_t	mpg123_framepos64 (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_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 (see mpg123_open())
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

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().

The path parameter usually is just a string that is handed to the underlying OS routine for opening, treated as a blob of binary data. On platforms where encoding needs to be involved, something like _wopen() is called underneath and the path argument to libmpg123 is assumed to be encoded in UTF-8. So, if you have to ask yourself which encoding is needed, the answer is UTF-8, which also fits any sane modern install of Unix-like systems.

Parameters

mh	handle
path	filesystem

Returns

MPG123_OK on success

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

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() or mpg123_reader64()! mpg123_close() will call the cleanup callback for your non-NULL handle (if you gave one).

Parameters

mh	handle
iohandle	your handle

Returns

MPG123_OK on success

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

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

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

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.

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)

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

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

mpg123_decode_frame64()

MPG123_EXPORT int mpg123_decode_frame64	(	mpg123_handle *	mh,
		int64_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

mpg123_framebyframe_decode64()

MPG123_EXPORT int mpg123_framebyframe_decode64	(	mpg123_handle *	mh,
		int64_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

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

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).

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

mpg123_framepos64()

MPG123_EXPORT int64_t mpg123_framepos64

(

mpg123_handle *

mh

)

Get the 64 bit 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