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

Detailed Description

Function Documentation

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. 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_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.

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.