opusfile  0.12-12-gb23e611
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 stream support it.

Seeking is implemented for all built-in stream I/O routines, though some individual streams 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
_ofThe OggOpusFile in which to seek.
_byte_offsetThe byte position to seek to. This must be between 0 and op_raw_total(_of,-1) (inclusive).
Returns
0 on success, or a negative error code on failure.
Return values
OP_EREADThe underlying seek operation failed.
OP_EINVALThe stream was only partially open, or the target was outside the valid range for the stream.
OP_ENOSEEKThis stream is not seekable.
OP_EBADLINKFailed 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
_ofThe OggOpusFile in which to seek.
_pcm_offsetThe 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_EREADAn underlying read or seek operation failed.
OP_EINVALThe stream was only partially open, or the target was outside the valid range for the stream.
OP_ENOSEEKThis stream is not seekable.
OP_EBADLINKWe failed to find data we had seen before, or the bitstream structure was sufficiently malformed that seeking to the target destination was impossible.