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 position and seeking

Functions
off_t	mpg123_tell (mpg123_handle *mh)
off_t	mpg123_tellframe (mpg123_handle *mh)
off_t	mpg123_tell_stream (mpg123_handle *mh)
off_t	mpg123_seek (mpg123_handle *mh, off_t sampleoff, int whence)
off_t	mpg123_feedseek (mpg123_handle *mh, off_t sampleoff, int whence, off_t *input_offset)
off_t	mpg123_seek_frame (mpg123_handle *mh, off_t frameoff, int whence)
off_t	mpg123_timeframe (mpg123_handle *mh, double sec)
int	mpg123_index (mpg123_handle *mh, off_t **offsets, off_t *step, size_t *fill)
int	mpg123_position (mpg123_handle *mh, off_t frame_offset, off_t buffered_bytes, off_t *current_frame, off_t *frames_left, double *current_seconds, double *seconds_left)

---

Detailed Description

Functions querying and manipulating position in the decoded audio bitstream. The position is measured in decoded audio samples, or MPEG frame offset for the specific functions. If gapless code is in effect, the positions are adjusted to compensate the skipped padding/delay - meaning, you should not care about that at all and just use the position defined for the samples you get out of the decoder;-) The general usage is modelled after stdlib's ftell() and fseek(). Especially, the whence parameter for the seek functions has the same meaning as the one for fseek() and needs the same constants from stdlib.h:

• SEEK_SET: set position to (or near to) specified offset
• SEEK_CUR: change position by offset from now
• SEEK_END: set position to offset from end

Note that sample-accurate seek only works when gapless support has been enabled at compile time; seek is frame-accurate otherwise. Also, seeking is not guaranteed to work for all streams (underlying stream may not support it).

---

Function Documentation

off_t mpg123_tell

(

mpg123_handle *

mh

)

Returns the current position in samples. On the next read, you'd get that sample.

off_t mpg123_tellframe

(

mpg123_handle *

mh

)

Returns the frame number that the next read will give you data from.

off_t mpg123_tell_stream

(

mpg123_handle *

mh

)

Returns the current byte offset in the input stream.

off_t mpg123_seek	(	mpg123_handle *	mh,
		off_t	sampleoff,
		int	whence
	)

Seek to a desired sample offset. Set whence to SEEK_SET, SEEK_CUR or SEEK_END.

Returns:

The resulting offset >= 0 or error/message code

off_t mpg123_feedseek	(	mpg123_handle *	mh,
		off_t	sampleoff,
		int	whence,
		off_t *	input_offset
	)

Seek to a desired sample offset in data feeding mode. This just prepares things to be right only if you ensure that the next chunk of input data will be from input_offset byte position.

Parameters:

input_offset

The position it expects to be at the next time data is fed to mpg123_decode().

Returns:

The resulting offset >= 0 or error/message code

off_t mpg123_seek_frame	(	mpg123_handle *	mh,
		off_t	frameoff,
		int	whence
	)

Seek to a desired MPEG frame index. Set whence to SEEK_SET, SEEK_CUR or SEEK_END.

Returns:

The resulting offset >= 0 or error/message code

off_t mpg123_timeframe	(	mpg123_handle *	mh,
		double	sec
	)

Return a MPEG frame offset corresponding to an offset in seconds. This assumes that the samples per frame do not change in the file/stream, which is a good assumption for any sane file/stream only.

Returns:

frame offset >= 0 or error/message code

int mpg123_index	(	mpg123_handle *	mh,
		off_t **	offsets,
		off_t *	step,
		size_t *	fill
	)

Give access to the frame index table that is managed for seeking. You are asked not to modify the values... unless you are really aware of what you are doing.

Parameters:

	offsets	pointer to the index array
	step	one index byte offset advances this many MPEG frames
	fill	number of recorded index offsets; size of the array

int mpg123_position	(	mpg123_handle *	mh,
		off_t	frame_offset,
		off_t	buffered_bytes,
		off_t *	current_frame,
		off_t *	frames_left,
		double *	current_seconds,
		double *	seconds_left
	)

Get information about current and remaining frames/seconds. WARNING: This function is there because of special usage by standalone mpg123 and may be removed in the final version of libmpg123! You provide an offset (in frames) from now and a number of output bytes served by libmpg123 but not yet played. You get the projected current frame and seconds, as well as the remaining frames/seconds. This does _not_ care about skipped samples due to gapless playback.

---