download : svn :: features :: sf.net project - bug tracker :: news archive

libmpg123 API :: testing :: benchmarking :: faq :: links :: contact

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 library and handle setup

Typedefs
typedef struct mpg123_handle_struct	mpg123_handle
Enumerations
enum	mpg123_parms {   MPG123_VERBOSE, MPG123_FLAGS,   MPG123_ADD_FLAGS, MPG123_FORCE_RATE,   MPG123_DOWN_SAMPLE, MPG123_RVA,   MPG123_DOWNSPEED, MPG123_UPSPEED,   MPG123_START_FRAME, MPG123_DECODE_FRAMES,   MPG123_ICY_INTERVAL, MPG123_OUTSCALE,   MPG123_TIMEOUT, MPG123_REMOVE_FLAGS,   MPG123_RESYNC_LIMIT }
enum	mpg123_param_flags {   MPG123_FORCE_MONO = 0x7, MPG123_MONO_LEFT = 0x1,   MPG123_MONO_RIGHT = 0x2, MPG123_MONO_MIX = 0x4,   MPG123_FORCE_STEREO = 0x8, MPG123_FORCE_8BIT = 0x10,   MPG123_QUIET = 0x20, MPG123_GAPLESS = 0x40,   MPG123_NO_RESYNC = 0x80, MPG123_SEEKBUFFER = 0x100 }
enum	mpg123_param_rva {   MPG123_RVA_OFF = 0, MPG123_RVA_MIX = 1,   MPG123_RVA_ALBUM = 2, MPG123_RVA_MAX = MPG123_RVA_ALBUM }
Functions
int	mpg123_init (void)
void	mpg123_exit (void)
mpg123_handle *	mpg123_new (const char *decoder, int *error)
void	mpg123_delete (mpg123_handle *mh)
int	mpg123_param (mpg123_handle *mh, enum mpg123_parms type, long value, double fvalue)
int	mpg123_getparam (mpg123_handle *mh, enum mpg123_parms type, long *val, double *fval)

---

Detailed Description

Functions to initialise and shutdown the mpg123 library and handles. The parameters of handles have workable defaults, you only have to tune them when you want to tune something;-) Tip: Use a RVA setting...

---

Typedef Documentation

typedef struct mpg123_handle_struct mpg123_handle

Opaque structure for the libmpg123 decoder handle. Most functions take a pointer to a mpg123_handle as first argument and operate on its data in an object-oriented manner.

Definition at line 48 of file mpg123.h.

---

Enumeration Type Documentation

enum mpg123_parms

Enumeration of the parameters types that it is possible to set/get.

Enumerator:

MPG123_VERBOSE	set verbosity value for enabling messages to stderr, >= 0 makes sense
MPG123_FLAGS	set all flags, p.ex val = MPG123_GAPLESS|MPG123_MONO_MIX
MPG123_ADD_FLAGS	add some flags
MPG123_FORCE_RATE	when value > 0, force output rate to that value
MPG123_DOWN_SAMPLE	0=native rate, 1=half rate, 2=quarter rate
MPG123_RVA	one of the RVA choices above
MPG123_DOWNSPEED	play a frame N times
MPG123_UPSPEED	play every Nth frame
MPG123_START_FRAME	start with this frame (skip frames before that)
MPG123_DECODE_FRAMES	decode only this number of frames
MPG123_ICY_INTERVAL	stream contains ICY metadata with this interval
MPG123_OUTSCALE	the scale for output samples (amplitude)
MPG123_TIMEOUT	timeout for reading from a stream (not supported on win32)
MPG123_REMOVE_FLAGS	remove some flags (inverse of MPG123_ADD_FLAGS)
MPG123_RESYNC_LIMIT	Try resync on frame parsing for that many bytes or until end of stream (<0).

Definition at line 73 of file mpg123.h.

enum mpg123_param_flags

Flag bits for MPG123_FLAGS, use the usual binary or to combine.

Enumerator:

MPG123_FORCE_MONO	0111 Force some mono mode: This is a test bitmask for seeing if any mono forcing is active.
MPG123_MONO_LEFT	0001 Force playback of left channel only.
MPG123_MONO_RIGHT	0010 Force playback of right channel only.
MPG123_MONO_MIX	0100 Force playback of mixed mono.
MPG123_FORCE_STEREO	1000 Force stereo output.
MPG123_FORCE_8BIT	00010000 Force 8bit formats.
MPG123_QUIET	00100000 Suppress any printouts (overrules verbose).
MPG123_GAPLESS	01000000 Enable gapless decoding (default on if libmpg123 has support).
MPG123_NO_RESYNC	10000000 Disable resync stream after error.
MPG123_SEEKBUFFER	000100000000 Enable small buffer on non-seekable streams to allow some peek-ahead (for better MPEG sync).

Definition at line 93 of file mpg123.h.

enum mpg123_param_rva

choices for MPG123_RVA

Enumerator:

MPG123_RVA_OFF	RVA disabled (default).
MPG123_RVA_MIX	Use mix/track/radio gain.
MPG123_RVA_ALBUM	Use album/audiophile gain
MPG123_RVA_MAX	The maximum RVA code, may increase in future.

Definition at line 108 of file mpg123.h.

---

Function Documentation

int mpg123_init

(

void

)

Function to initialise the mpg123 library. This function is not thread-safe. Call it exactly once per process, before any other (possibly threaded) work with the library.

Returns:

MPG123_OK if successful, otherwise an error number.

void mpg123_exit

(

void

)

Function to close down the mpg123 library. This function is not thread-safe. Call it exactly once per process, before any other (possibly threaded) work with the library.

mpg123_handle* mpg123_new	(	const char *	decoder,
		int *	error
	)

Create a handle with optional choice of decoder (named by a string, see mpg123_decoders() or mpg123_supported_decoders()). and optional retrieval of an error code to feed to mpg123_plain_strerror(). Optional means: Any of or both the parameters may be NULL.

Returns:

Non-NULL pointer when successful.

void mpg123_delete

(

mpg123_handle *

mh

)

Delete handle, mh is either a valid mpg123 handle or NULL.

int mpg123_param	(	mpg123_handle *	mh,
		enum mpg123_parms	type,
		long	value,
		double	fvalue
	)

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

int mpg123_getparam	(	mpg123_handle *	mh,
		enum mpg123_parms	type,
		long *	val,
		double *	fval
	)

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

---