liboggz: Oggz Seek API

# 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.
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.
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.
oggz_off_t | oggz_tell (OGGZ *oggz)
| Query the file offset in bytes corresponding to the data read.
oggz_off_t | oggz_seek (OGGZ *oggz, oggz_off_t offset, int whence)
| Seek to a specific byte offset.

## 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