Semantics of seeking in Ogg bitstreams

Introduction

[*** This line works around a bug in doxygen ***]

The seeking semantics of the Ogg file format were outlined by Monty in a post to theora-dev in September 2002. Quoting from that post, we have the following assumptions:

Ogg is not a non-linear format. ... It is a media transport format designed to do nothing more than deliver content, in a stream, and have all the pieces arrive on time and in sync.
The Ogg layer does not know the specifics of the codec data it's multiplexing into a stream. It knows nothing beyond 'Oooo, packets!', that the packets belong to different buckets, that the packets go in order, and that packets have position markers. Ogg does not even have a concept of 'time'; it only knows about the sequentially increasing, unitless position markers. It is up to higher layers which have access to the codec APIs to assign and convert units of framing or time.

(For more details on the structure of Ogg streams, see the Ogg Basics section).

For data such as media, for which it is possible to provide a mapping such as 'time', Oggz can efficiently navigate through an Ogg stream by use of an OggzMetric callback, thus allowing automatic seeking to points in 'time'.

For common codecs you can ask Oggz to set this for you automatically by instantiating the OGGZ handle with the OGGZ_AUTO flag set. For others you can specify a multiplier with oggz_set_metric_linear(), or a generic non-linear metric with oggz_set_metric().