libmpg123: mpg123 file input and decoding

Note: This API doc is automatically generated from the current development version that you can get via Subversion or as a daily snapshot from http://mpg123.org/snapshot. There may be differences (additions) compared to the latest stable release. See NEWS.libmpg123 and the overall NEWS file on libmpg123 versions and important changes between them.
Let me emphasize that the policy for libmpg123 is to always stay backwards compatible -- only additions are planned (and it's not yet planned to change the plans;-).

mpg123 file input and decoding

Detailed Description

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.


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)

mpg123 file input and decoding

Functions

Detailed Description

Function Documentation