liboggz  1.1.1
Functions
Oggz Seek API

Oggz can seek on multitrack, multicodec bitstreams. More...

Functions

ogg_int64_t oggz_tell_units (OGGZ *oggz)
 Query the current offset in milliseconds, or custom units as specified by a Metric function you have provided. More...
 
ogg_int64_t oggz_seek_units (OGGZ *oggz, ogg_int64_t units, int whence)
 Seek to an offset in milliseconds, or custom units as specified by a Metric function you have provided. More...
 
ogg_int64_t oggz_tell_granulepos (OGGZ *oggz)
 Provide the exact stored granulepos (from the page header) if relevant to the current packet, or a constructed granulepos if the stored granulepos does not belong to this packet, or -1 if this codec does not have support for granulepos interpolation. More...
 
oggz_off_t oggz_tell (OGGZ *oggz)
 Query the file offset in bytes corresponding to the data read. More...
 
oggz_off_t oggz_seek (OGGZ *oggz, oggz_off_t offset, int whence)
 Seek to a specific byte offset. More...
 

Detailed Description

Oggz can seek on multitrack, multicodec bitstreams.

Time seeking

Support is built-in for seeking to time positions in CELT, CMML. FLAC, OggPCM, Speex, Theora and Vorbis. Oggz is also compatible with Annodex streams, and supports seeking on all tracks described in an Ogg Skeleton track.

You need to 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
Oggz parses these codec headers internally, and so liboggz is not linked to libspeex, libvorbis, libflac, libtheora, libcmml or libannodex.

For other data streams, you will need to provide a metric function; see the section on Using OggzMetrics for details of setting up and seeking with metrics.

Byte seeking

oggz_seek() provides low-level seeking to byte positions.

More detail

For a full description of the seeking methods possible in Ogg, see Semantics of seeking in Ogg bitstreams .

Function Documentation

oggz_off_t oggz_seek ( OGGZ oggz,
oggz_off_t  offset,
int  whence 
)

Seek to a specific byte offset.

Parameters
oggzAn OGGZ handle
offseta byte offset
whenceAs 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 an offset in milliseconds, or custom units as specified by a Metric function you have provided.

Parameters
oggzAn OGGZ handle
unitsA number of milliseconds, or custom units
whenceAs defined in <stdio.h>: SEEK_SET, SEEK_CUR or SEEK_END
Returns
the new file offset, or -1 on failure.
oggz_off_t oggz_tell ( OGGZ oggz)

Query the file offset in bytes corresponding to the data read.

Parameters
oggzAn OGGZ handle
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.
ogg_int64_t oggz_tell_granulepos ( OGGZ oggz)

Provide the exact stored granulepos (from the page header) if relevant to the current packet, or a constructed granulepos if the stored granulepos does not belong to this packet, or -1 if this codec does not have support for granulepos interpolation.

Parameters
oggzAn OGGZ handle
Returns
the granulepos of the current packet (if available)
ogg_int64_t oggz_tell_units ( OGGZ oggz)

Query the current offset in milliseconds, or custom units as specified by a Metric function you have provided.

Parameters
oggzAn OGGZ handle
Returns
the offset in milliseconds, or custom units
Return values
OGGZ_ERR_BAD_OGGZoggz does not refer to an existing OGGZ
OGGZ_ERR_INVALIDOperation not suitable for this OGGZ