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.
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.
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.
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().
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. | |
Functions | |
int | oggz_get_granuleshift (OGGZ *oggz, long serialno) |
Retrieve the granuleshift of a logical bitstream. | |
int | oggz_set_granuleshift (OGGZ *oggz, long serialno, int granuleshift) |
Specify the granuleshift of a logical bitstream. | |
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. | |
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. | |
int | oggz_set_metric (OGGZ *oggz, long serialno, OggzMetric metric, void *user_data) |
Set the OggzMetric to use for an OGGZ handle. | |
int | oggz_set_data_start (OGGZ *oggz, oggz_off_t offset) |
Tell OGGZ to remember the given offset as the start of data. |
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.
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 |
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.
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 |
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.
oggz | An OGGZ handle | |
serialno | Identify the logical bitstream in oggz |
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));
oggz | An OGGZ handle previously opened for reading | |
offset | The offset of the start of data |
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.
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 |
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.
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 |
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.
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 |
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 |
Alternatively, you may use a different metric for each serialno, but all metrics used must return mutually consistent unit measurements.