OGGZ Seek API
Detailed Description
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).
liboggz provides two abstractions for seeking at an arbitrary level of precision, as well as allowing seeking to a direct byte offset.
To seek across non-metric spaces for which a partial order exists (ie. data that is not synchronised by a measure such as time, but is nevertheless somehow seekably structured), use an OggzOrder.
For most purposes, such as media data, use an OggzMetric instead. For common codecs you can ask Oggz to do 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().
- See the Using OggzMetrics section for details on setting up and seeking with metrics.
|
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_set_metric_linear (OGGZ *oggz, long serialno, ogg_int64_t granule_rate_numerator, ogg_int64_t granule_rate_denominator) |
| Specify that a logical bitstream has a linear metric.
|
int | oggz_set_metric (OGGZ *oggz, long serialno, OggzMetric metric, void *user_data) |
| Set the OggzMetric to use for an OGGZ handle.
|
ogg_int64_t | oggz_seek_units (OGGZ *oggz, ogg_int64_t units, int whence) |
| Seek to a number of units corresponding to the Metric function.
|
int | oggz_data_begins_here (OGGZ *oggz) |
| Tell OGGZ that we're past the headers, to remember the current packet as the start of data.
|
off_t | oggz_tell (OGGZ *oggz) |
| Provide the file offset in bytes corresponding to the data read.
|
off_t | oggz_seek (OGGZ *oggz, off_t offset, int whence) |
| Seek to a specific bytes offset.
|
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_data_begins_here |
( |
OGGZ * |
oggz |
) |
|
|
|
Tell OGGZ that we're past the headers, to remember the current packet as the start of data.
This informs the seeking mechanism that when seeking back to unit 0, go to the packet we're on now, not to the start of the file, which is usually codec headers. - Parameters:
-
oggz | An OGGZ handle previously opened for reading |
- Returns:
- 0 on success, -1 on failure.
|
off_t oggz_seek |
( |
OGGZ * |
oggz, |
|
|
off_t |
offset, |
|
|
int |
whence |
|
) |
|
|
|
Seek to a specific bytes offset.
- Parameters:
-
oggz | An OGGZ handle |
offset | a byte offset |
whence | As defined in <stdio.h>: SEEK_SET, SEEK_CUR or SEEK_END |
- Returns:
- the new file offset, or -1 on failure.
|
ogg_int64_t oggz_seek_units |
( |
OGGZ * |
oggz, |
|
|
ogg_int64_t |
units, |
|
|
int |
whence |
|
) |
|
|
|
Seek to a number of units corresponding to the Metric function.
- Parameters:
-
oggz | An OGGZ handle |
units | A number of units |
whence | As defined in <stdio.h>: SEEK_SET, SEEK_CUR or SEEK_END |
- Returns:
- the new file offset, or -1 on failure.
|
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_metric_linear |
( |
OGGZ * |
oggz, |
|
|
long |
serialno, |
|
|
ogg_int64_t |
granule_rate_numerator, |
|
|
ogg_int64_t |
granule_rate_denominator |
|
) |
|
|
|
Specify that a logical bitstream has a linear metric.
- 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 |
|
off_t oggz_tell |
( |
OGGZ * |
oggz |
) |
|
|
|
Provide the file offset in bytes corresponding to the data read.
- Parameters:
-
- Returns:
- The current offset of oggz.
- Note:
- When reading, the value returned by oggz_tell() reflects the data offset of the start of the most recent packet processed, so that when called from an OggzReadPacket callback it reflects the byte offset of the start of the packet. As OGGZ may have internally read ahead, this may differ from the current offset of the associated file descriptor.
|
Generated on Thu Dec 11 09:42:28 2003 for liboggz by
1.3.4