Typedefs
typedef ogg_int64_t(*	OggzMetric )(OGGZ oggz, long serialno, ogg_int64_t granulepos, void user_data)
	This is the signature of a function to correlate Ogg streams. More...

Functions
int	oggz_get_preroll (OGGZ *oggz, long serialno)
	Retrieve the preroll of a logical bitstream. More...

int	oggz_set_preroll (OGGZ *oggz, long serialno, int preroll)
	Specify the preroll of a logical bitstream. More...

int	oggz_get_granuleshift (OGGZ *oggz, long serialno)
	Retrieve the granuleshift of a logical bitstream. More...

int	oggz_set_granuleshift (OGGZ *oggz, long serialno, int granuleshift)
	Specify the granuleshift of a logical bitstream. More...

int	oggz_get_granulerate (OGGZ oggz, long serialno, ogg_int64_t granulerate_n, ogg_int64_t *granulerate_d)
	Retrieve the granulerate of a logical bitstream. More...

int	oggz_set_granulerate (OGGZ *oggz, long serialno, ogg_int64_t granule_rate_numerator, ogg_int64_t granule_rate_denominator)
	Specify the granulerate of a logical bitstream. More...

int	oggz_set_metric (OGGZ oggz, long serialno, OggzMetric metric, void user_data)
	Set the OggzMetric to use for an OGGZ handle. More...

int	oggz_set_data_start (OGGZ *oggz, oggz_off_t offset)
	Tell Oggz to remember the given offset as the start of data. More...

Detailed Description

Introduction

An OggzMetric is a helper function for Oggz's seeking mechanism.

If every position in an Ogg stream can be described by a metric such as time, then it is possible to define a function that, given a serialno and granulepos, returns a measurement in units such as milliseconds. Oggz will use this function repeatedly while seeking in order to navigate through the Ogg stream.

The meaning of the units is arbitrary, but must be consistent across all logical bitstreams. This allows Oggz to seek accurately through Ogg bitstreams containing multiple logical bitstreams such as tracks of media.

How to set metrics

You don't need to set metrics for Speex, Vorbis, FLAC, Theora, CMML or Annodex. These can be handled automatically by Oggz.

For most others it is simply a matter of providing a "granulerate": a frame or sampling rate, if each packet's granulepos represents a sample number.

Set the granule_rate_numerator and granule_rate_denominator appropriately using oggz_set_granulerate()

Some codecs use a "granuleshift" to divide a granulepos into two halves; the first describing a dependency on a previous packet, the second giving the offset since that packet. This is used to mark keyframes and intermediate frames.

Set the granuleshift appropriately using oggz_set_granuleshift()

Custom Metrics

For streams with non-linear granulepos, you need to set a custom metric:

Implement an OggzMetric callback
Set the OggzMetric callback using oggz_set_metric()

Seeking with OggzMetrics

To seek, use oggz_seek_units(). Oggz will perform a ratio search through the Ogg bitstream, using the OggzMetric callback to determine its position relative to the desired unit.

Note

Many data streams begin with headers describing such things as codec setup parameters. One of the assumptions Monty makes is:

Given pre-cached decode headers, a player may seek into a stream at any point and begin decode.

Thus, the first action taken by applications dealing with such data is to read in and cache the decode headers; thereafter the application can safely seek to arbitrary points in the data.

This impacts seeking because the portion of the bitstream containing decode headers should not be considered part of the metric space. To inform Oggz not to seek earlier than the end of the decode headers, use oggz_set_data_start().

Typedef Documentation

typedef ogg_int64_t(* OggzMetric)(OGGZ *oggz, long serialno, ogg_int64_t granulepos, void *user_data)

This is the signature of a function to correlate Ogg streams.

If every position in an Ogg stream can be described by a metric (eg. time) then define this function that returns some arbitrary unit value. This is the normal use of Oggz for media streams. The meaning of units is arbitrary, but must be consistent across all logical bitstreams; for example a conversion of the time offset of a given packet into nanoseconds or a similar stream-specific subdivision may be appropriate.

Parameters

oggz	An OGGZ handle
serialno	Identifies a logical bitstream within oggz
granulepos	A granulepos within the logical bitstream identified by serialno
user_data	Arbitrary data you wish to pass to your callback

Returns: A conversion of the (serialno, granulepos) pair into a measure in units which is consistent across all logical bitstreams within oggz

Function Documentation

int oggz_get_granulerate	(	OGGZ *	oggz,
		long	serialno,
		ogg_int64_t *	granulerate_n,
		ogg_int64_t *	granulerate_d
	)

Retrieve the granulerate of a logical bitstream.

Parameters

oggz	An OGGZ handle
serialno	Identify the logical bitstream in oggz
granulerate_n	Return location for the granulerate numerator
granulerate_d	Return location for the granulerate denominator

Returns: 0 Success

Return values

OGGZ_ERR_BAD_SERIALNO	serialno does not identify an existing logical bitstream in oggz.
OGGZ_ERR_BAD_OGGZ	oggz does not refer to an existing OGGZ

int oggz_get_granuleshift	(	OGGZ *	oggz,
		long	serialno
	)

Retrieve the granuleshift of a logical bitstream.

Parameters

oggz	An OGGZ handle
serialno	Identify the logical bitstream in oggz

Returns: The granuleshift of the specified logical bitstream.

Return values

OGGZ_ERR_BAD_SERIALNO	serialno does not identify an existing logical bitstream in oggz.
OGGZ_ERR_BAD_OGGZ	oggz does not refer to an existing OGGZ

int oggz_get_preroll	(	OGGZ *	oggz,
		long	serialno
	)

Retrieve the preroll of a logical bitstream.

Parameters

oggz	An OGGZ handle
serialno	Identify the logical bitstream in oggz

Returns: The preroll of the specified logical bitstream.

Return values

OGGZ_ERR_BAD_SERIALNO	serialno does not identify an existing logical bitstream in oggz.
OGGZ_ERR_BAD_OGGZ	oggz does not refer to an existing OGGZ

int oggz_set_data_start	(	OGGZ *	oggz,
		oggz_off_t	offset
	)

Tell Oggz to remember the given offset as the start of data.

This informs the seeking mechanism that when seeking back to unit 0, go to the given offset, not to the start of the file, which is usually codec headers. The usual usage is:

    oggz_set_data_start (oggz, oggz_tell (oggz));

Parameters

oggz	An OGGZ handle previously opened for reading
offset	The offset of the start of data

Returns: 0 on success, -1 on failure.

int oggz_set_granulerate	(	OGGZ *	oggz,
		long	serialno,
		ogg_int64_t	granule_rate_numerator,
		ogg_int64_t	granule_rate_denominator
	)

Specify the granulerate of a logical bitstream.

Parameters

oggz	An OGGZ handle
serialno	Identify the logical bitstream in oggz to attach this linear metric to. A value of -1 indicates that the metric should be attached to all unattached logical bitstreams in oggz.
granule_rate_numerator	The numerator of the granule rate
granule_rate_denominator	The denominator of the granule rate

Returns: 0 Success

Return values

OGGZ_ERR_BAD_SERIALNO	serialno does not identify an existing logical bitstream in oggz.
OGGZ_ERR_BAD_OGGZ	oggz does not refer to an existing OGGZ

int oggz_set_granuleshift	(	OGGZ *	oggz,
		long	serialno,
		int	granuleshift
	)

Specify the granuleshift of a logical bitstream.

Parameters

oggz	An OGGZ handle
serialno	Identify the logical bitstream in oggz to attach this granuleshift metric to. A value of -1 indicates that the metric should be attached to all unattached logical bitstreams in oggz.
granuleshift	The granuleshift

Returns: 0 Success

Return values

OGGZ_ERR_BAD_SERIALNO	serialno does not identify an existing logical bitstream in oggz.
OGGZ_ERR_BAD_OGGZ	oggz does not refer to an existing OGGZ

int oggz_set_metric	(	OGGZ *	oggz,
		long	serialno,
		OggzMetric	metric,
		void *	user_data
	)

Set the OggzMetric to use for an OGGZ handle.

Parameters

oggz	An OGGZ handle
serialno	Identify the logical bitstream in oggz to attach this metric to. A value of -1 indicates that this metric should be attached to all unattached logical bitstreams in oggz.
metric	An OggzMetric callback
user_data	arbitrary data to pass to the metric callback

Returns: 0 Success

Return values

OGGZ_ERR_BAD_SERIALNO	serialno does not identify an existing logical bitstream in oggz, and is not -1
OGGZ_ERR_BAD_OGGZ	oggz does not refer to an existing OGGZ

Note: Specifying values of serialno other than -1 allows you to pass logical bitstream specific user_data to the same metric.; Alternatively, you may use a different metric for each serialno, but all metrics used must return mutually consistent unit measurements.

int oggz_set_preroll	(	OGGZ *	oggz,
		long	serialno,
		int	preroll
	)

Specify the preroll of a logical bitstream.

Parameters

oggz	An OGGZ handle
serialno	Identify the logical bitstream in oggz to attach this preroll to.
preroll	The preroll

Returns: 0 Success

Return values

OGGZ_ERR_BAD_SERIALNO	serialno does not identify an existing logical bitstream in oggz.
OGGZ_ERR_BAD_OGGZ	oggz does not refer to an existing OGGZ

Typedefs

Functions

Detailed Description

Introduction

How to set metrics

Custom Metrics

Seeking with OggzMetrics

Typedef Documentation

Function Documentation