opusfile: Seeking

| opusfile 0.8 Stand-alone decoder library for .opus files.

Seeking

## Functions for seeking in Opus streams
These functions let you seek in Opus streams, if the underlying source support it. Seeking is implemented for all built-in stream I/O routines, though some individual sources may not be seekable (pipes, live HTTP streams, or HTTP streams from a server that does not support `Range` requests). op_raw_seek() is the fastest: it is guaranteed to perform at most one physical seek, but, since the target is a byte position, makes no guarantee how close to a given time it will come. op_pcm_seek() provides sample-accurate seeking. The number of physical seeks it requires is still quite small (often 1 or 2, even in highly variable bitrate streams). Seeking in Opus requires decoding some pre-roll amount before playback to allow the internal state to converge (as if recovering from packet loss). This is handled internally by `libopusfile`, but means there is little extra overhead for decoding up to the exact position requested (since it must decode some amount of audio anyway). It also means that decoding after seeking may not return exactly the same values as would be obtained by decoding the stream straight through. However, such differences are expected to be smaller than the loss introduced by Opus's lossy compression.
int | op_raw_seek (OggOpusFile *_of, opus_int64 _byte_offset) OP_ARG_NONNULL(1)
| Seek to a byte offset relative to the compressed data. More...
int | op_pcm_seek (OggOpusFile *_of, ogg_int64_t _pcm_offset) OP_ARG_NONNULL(1)
| Seek to the specified PCM offset, such that decoding will begin at exactly the requested position. More...

## Detailed Description

## Function Documentation

## § op_raw_seek()

int op_raw_seek | ( | OggOpusFile * | _of,
|  | opus_int64 | _byte_offset
| ) |  |

Seek to a byte offset relative to the compressed data.

This also scans packets to update the PCM cursor. It will cross a logical bitstream boundary, but only if it can't get any packets out of the tail of the link to which it seeks.

Parameters

  _of | The `OggOpusFile` in which to seek.
  _byte_offset | The byte position to seek to.

Returns
  0 on success, or a negative error code on failure.

Return values

  OP_EREAD | The underlying seek operation failed.
  OP_EINVAL | The stream was only partially open, or the target was outside the valid range for the stream.
  OP_ENOSEEK | This stream is not seekable.
  OP_EBADLINK | Failed to initialize a decoder for a stream for an unknown reason.

## § op_pcm_seek()

int op_pcm_seek | ( | OggOpusFile * | _of,
|  | ogg_int64_t | _pcm_offset
| ) |  |

Seek to the specified PCM offset, such that decoding will begin at exactly the requested position.

Parameters

  _of | The `OggOpusFile` in which to seek.
  _pcm_offset | The PCM offset to seek to. This is in samples at 48 kHz relative to the start of the stream.

Returns
  0 on success, or a negative value on error.

Return values

  OP_EREAD | An underlying read or seek operation failed.
  OP_EINVAL | The stream was only partially open, or the target was outside the valid range for the stream.
  OP_ENOSEEK | This stream is not seekable.
  OP_EBADLINK | We failed to find data we had seen before, or the bitstream structure was sufficiently malformed that seeking to the target destination was impossible.