mpg123 file input and decoding

Functions
int	mpg123_open (mpg123_handle *mh, const char *path)
int	mpg123_open_fd (mpg123_handle *mh, int fd)
int	mpg123_open_handle (mpg123_handle *mh, void *iohandle)
int	mpg123_open_feed (mpg123_handle *mh)
int	mpg123_close (mpg123_handle *mh)
int	mpg123_read (mpg123_handle *mh, unsigned char *outmemory, size_t outmemsize, size_t *done)
int	mpg123_feed (mpg123_handle *mh, const unsigned char *in, size_t size)
int	mpg123_decode (mpg123_handle *mh, const unsigned char *inmemory, size_t inmemsize, unsigned char *outmemory, size_t outmemsize, size_t *done)
int	mpg123_decode_frame (mpg123_handle *mh, off_t *num, unsigned char **audio, size_t *bytes)
int	mpg123_framebyframe_decode (mpg123_handle *mh, off_t *num, unsigned char **audio, size_t *bytes)
int	mpg123_framebyframe_next (mpg123_handle *mh)
int	mpg123_framedata (mpg123_handle *mh, unsigned long *header, unsigned char **bodydata, size_t *bodybytes)
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

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

Enumeration of the error codes returned by libmpg123 functions. 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().

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.

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

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.

int mpg123_close

(

mpg123_handle *

mh

)

Closes the source, if libmpg123 opened it.

int mpg123_read	(	mpg123_handle *	mh,
		unsigned char *	outmemory,
		size_t	outmemsize,
		size_t *	done
	)

Read from stream and decode up to outmemsize bytes.

Parameters:

	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:

error/message code (watch out for MPG123_DONE and friends!)

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:

	in	input buffer
	size	number of input bytes

Returns:

error/message code.

int mpg123_decode	(	mpg123_handle *	mh,
		const unsigned char *	inmemory,
		size_t	inmemsize,
		unsigned char *	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.

Parameters:

	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)

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:

	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

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:

	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

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.

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:

	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_ERR otherwise (without further explanation, the error state of the mpg123_handle is not modified by this function).

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!