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:

• Create an OGGZ handle for reading with flags = OGGZ_READ | OGGZ_AUTO
• Read data, ensuring that you have received all b_o_s pages before attempting to seek.

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

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 an offset in milliseconds, or custom units as specified by a Metric function you have provided.

Parameters

oggz	An OGGZ handle
units	A number of milliseconds, or custom units
whence	As 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

oggz	An 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

oggz	An 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

oggz	An OGGZ handle

Returns

the offset in milliseconds, or custom units

Return values

OGGZ_ERR_BAD_OGGZ	oggz does not refer to an existing OGGZ
OGGZ_ERR_INVALID	Operation not suitable for this OGGZ