Main Page | Modules | File List | Globals

Using OggzMetric

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

Some common media codecs can be handled automatically by Oggz. For most others it is simply a matter of providing a linear multiplication factor (such as a sampling rate, if each packet's granulepos represents a sample number). For non-linear data streams, you will need to explicitly provide your own OggzMetric function.

Automatic Metrics

Oggz can automatically provide metrics for the common media codecs Speex, Vorbis, and Theora, as well as all Annodex streams. You need do nothing more than open the file with the OGGZ_AUTO flag set.

Oggz will silently parse known codec headers and associate metrics appropriately; if you attempt to seek before you have received all b_o_s pages, Oggz will not have had a chance to parse the codec headers and associate metrics. It is safe to seek once you have received a packet with b_o_s == 0; see the Ogg basics section for more details.

Note:
This functionality is provided for convenience. Oggz parses these codec headers internally, and so liboggz is not linked to libspeex, libvorbis, libtheora or libannodex.

Linear Metrics

Custom Metrics

For some streams, neither of the above methods are appropriate.

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:

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


Generated on Tue Apr 13 12:27:03 2004 for liboggz by doxygen 1.3.6-20040222