Functions for obtaining information about streams
These functions allow you to get basic information about a stream, including seekability, the number of links (for chained streams), plus the size, duration, bitrate, header parameters, and meta information for each link (or, where available, the stream as a whole). Some of these (size, duration) are only available for seekable streams. You can also query the current stream position, link, and playback time, and instantaneous bitrate during playback. Some of these functions may be used successfully on the partially open streams returned by op_test_callbacks() or one of the associated convenience functions. Their documention will indicate so explicitly.
int	op_seekable (const OggOpusFile *_of) OP_ARG_NONNULL(1)
	Returns whether or not the stream being read is seekable. More...

int	op_link_count (const OggOpusFile *_of) OP_ARG_NONNULL(1)
	Returns the number of links in this chained stream. More...

opus_uint32	op_serialno (const OggOpusFile *_of, int _li) OP_ARG_NONNULL(1)
	Get the serial number of the given link in a (possibly-chained) Ogg Opus stream. More...

int	op_channel_count (const OggOpusFile *_of, int _li) OP_ARG_NONNULL(1)
	Get the channel count of the given link in a (possibly-chained) Ogg Opus stream. More...

opus_int64	op_raw_total (const OggOpusFile *_of, int _li) OP_ARG_NONNULL(1)
	Get the total (compressed) size of the stream, or of an individual link in a (possibly-chained) Ogg Opus stream, including all headers and Ogg muxing overhead. More...

ogg_int64_t	op_pcm_total (const OggOpusFile *_of, int _li) OP_ARG_NONNULL(1)
	Get the total PCM length (number of samples at 48 kHz) of the stream, or of an individual link in a (possibly-chained) Ogg Opus stream. More...

const OpusHead *	op_head (const OggOpusFile *_of, int _li) OP_ARG_NONNULL(1)
	Get the ID header information for the given link in a (possibly chained) Ogg Opus stream. More...

const OpusTags *	op_tags (const OggOpusFile *_of, int _li) OP_ARG_NONNULL(1)
	Get the comment header information for the given link in a (possibly chained) Ogg Opus stream. More...

int	op_current_link (const OggOpusFile *_of) OP_ARG_NONNULL(1)
	Retrieve the index of the current link. More...

opus_int32	op_bitrate (const OggOpusFile *_of, int _li) OP_ARG_NONNULL(1)
	Computes the bitrate of the stream, or of an individual link in a (possibly-chained) Ogg Opus stream. More...

opus_int32	op_bitrate_instant (OggOpusFile *_of) OP_ARG_NONNULL(1)
	Compute the instantaneous bitrate, measured as the ratio of bits to playable samples decoded since a) the last call to op_bitrate_instant(), b) the last seek, or c) the start of playback, whichever was most recent. More...

opus_int64	op_raw_tell (const OggOpusFile *_of) OP_ARG_NONNULL(1)
	Obtain the current value of the position indicator for _of. More...

ogg_int64_t	op_pcm_tell (const OggOpusFile *_of) OP_ARG_NONNULL(1)
	Obtain the PCM offset of the next sample to be read. More...

Detailed Description

Function Documentation

◆ op_seekable()

int op_seekable ( const OggOpusFile * _of )

Returns whether or not the stream being read is seekable.

This is true if

The seek() and tell() callbacks are both non-NULL,
The seek() callback was successfully executed at least once, and
The tell() callback was successfully able to report the position indicator afterwards.

This function may be called on partially-opened streams.

Parameters

_of	The `OggOpusFile` whose seekable status is to be returned.

Returns: A non-zero value if seekable, and 0 if unseekable.

◆ op_link_count()

int op_link_count ( const OggOpusFile * _of )

Returns the number of links in this chained stream.

This function may be called on partially-opened streams, but it will always return 1. The actual number of links is not known until the stream is fully opened.

Parameters

_of	The `OggOpusFile` from which to retrieve the link count.

Returns: For fully-open seekable streams, this returns the total number of links in the whole stream, which will be at least 1. For partially-open or unseekable streams, this always returns 1.

◆ op_serialno()

opus_uint32 op_serialno	(	const OggOpusFile *	_of,
		int	_li
	)

Get the serial number of the given link in a (possibly-chained) Ogg Opus stream.

This function may be called on partially-opened streams, but it will always return the serial number of the Opus stream in the first link.

Parameters

_of	The `OggOpusFile` from which to retrieve the serial number.
_li	The index of the link whose serial number should be retrieved. Use a negative number to get the serial number of the current link.

Returns: The serial number of the given link. If _li is greater than the total number of links, this returns the serial number of the last link. If the stream is not seekable, this always returns the serial number of the current link.

◆ op_channel_count()

int op_channel_count	(	const OggOpusFile *	_of,
		int	_li
	)

Get the channel count of the given link in a (possibly-chained) Ogg Opus stream.

This is equivalent to op_head(_of,_li)->channel_count, but is provided for convenience. This function may be called on partially-opened streams, but it will always return the channel count of the Opus stream in the first link.

Parameters

_of	The `OggOpusFile` from which to retrieve the channel count.
_li	The index of the link whose channel count should be retrieved. Use a negative number to get the channel count of the current link.

Returns: The channel count of the given link. If _li is greater than the total number of links, this returns the channel count of the last link. If the stream is not seekable, this always returns the channel count of the current link.

◆ op_raw_total()

opus_int64 op_raw_total	(	const OggOpusFile *	_of,
		int	_li
	)

Get the total (compressed) size of the stream, or of an individual link in a (possibly-chained) Ogg Opus stream, including all headers and Ogg muxing overhead.

Warning: If the Opus stream (or link) is concurrently multiplexed with other logical streams (e.g., video), this returns the size of the entire stream (or link), not just the number of bytes in the first logical Opus stream. Returning the latter would require scanning the entire file.

Parameters

_of	The `OggOpusFile` from which to retrieve the compressed size.
_li	The index of the link whose compressed size should be computed. Use a negative number to get the compressed size of the entire stream.

Returns: The compressed size of the entire stream if _li is negative, the compressed size of link _li if it is non-negative, or a negative value on error. The compressed size of the entire stream may be smaller than that of the underlying stream if trailing garbage was detected in the file.

Return values

OP_EINVAL The stream is not seekable (so we can't know the length), _li wasn't less than the total number of links in the stream, or the stream was only partially open.

◆ op_pcm_total()

ogg_int64_t op_pcm_total	(	const OggOpusFile *	_of,
		int	_li
	)

Get the total PCM length (number of samples at 48 kHz) of the stream, or of an individual link in a (possibly-chained) Ogg Opus stream.

Users looking for op_time_total() should use op_pcm_total() instead. Because timestamps in Opus are fixed at 48 kHz, there is no need for a separate function to convert this to seconds (and leaving it out avoids introducing floating point to the API, for those that wish to avoid it).

Parameters

_of	The `OggOpusFile` from which to retrieve the PCM offset.
_li	The index of the link whose PCM length should be computed. Use a negative number to get the PCM length of the entire stream.

Returns: The PCM length of the entire stream if _li is negative, the PCM length of link _li if it is non-negative, or a negative value on error.

Return values

OP_EINVAL The stream is not seekable (so we can't know the length), _li wasn't less than the total number of links in the stream, or the stream was only partially open.

◆ op_head()

const OpusHead* op_head	(	const OggOpusFile *	_of,
		int	_li
	)

Get the ID header information for the given link in a (possibly chained) Ogg Opus stream.

This function may be called on partially-opened streams, but it will always return the ID header information of the Opus stream in the first link.

Parameters

_of	The `OggOpusFile` from which to retrieve the ID header information.
_li	The index of the link whose ID header information should be retrieved. Use a negative number to get the ID header information of the current link. For an unseekable stream, _li is ignored, and the ID header information for the current link is always returned, if available.

Returns: The contents of the ID header for the given link.

◆ op_tags()

const OpusTags* op_tags	(	const OggOpusFile *	_of,
		int	_li
	)

Get the comment header information for the given link in a (possibly chained) Ogg Opus stream.

This function may be called on partially-opened streams, but it will always return the tags from the Opus stream in the first link.

Parameters

_of	The `OggOpusFile` from which to retrieve the comment header information.
_li	The index of the link whose comment header information should be retrieved. Use a negative number to get the comment header information of the current link. For an unseekable stream, _li is ignored, and the comment header information for the current link is always returned, if available.

Returns: The contents of the comment header for the given link, or NULL if this is an unseekable stream that encountered an invalid link.

◆ op_current_link()

int op_current_link ( const OggOpusFile * _of )

Retrieve the index of the current link.

This is the link that produced the data most recently read by op_read_float() or its associated functions, or, after a seek, the link that the seek target landed in. Reading more data may advance the link index (even on the first read after a seek).

Parameters

_of	The `OggOpusFile` from which to retrieve the current link index.

Returns: The index of the current link on success, or a negative value on failure. For seekable streams, this is a number between 0 (inclusive) and the value returned by op_link_count() (exclusive). For unseekable streams, this value starts at 0 and increments by one each time a new link is encountered (even though op_link_count() always returns 1).

Return values

OP_EINVAL The stream was only partially open.

◆ op_bitrate()

opus_int32 op_bitrate	(	const OggOpusFile *	_of,
		int	_li
	)

Computes the bitrate of the stream, or of an individual link in a (possibly-chained) Ogg Opus stream.

The stream must be seekable to compute the bitrate. For unseekable streams, use op_bitrate_instant() to get periodic estimates.

Warning: If the Opus stream (or link) is concurrently multiplexed with other logical streams (e.g., video), this uses the size of the entire stream (or link) to compute the bitrate, not just the number of bytes in the first logical Opus stream. Returning the latter requires scanning the entire file, but this may be done by decoding the whole file and calling op_bitrate_instant() once at the end. Install a trivial decoding callback with op_set_decode_callback() if you wish to skip actual decoding during this process.

Parameters

_of	The `OggOpusFile` from which to retrieve the bitrate.
_li	The index of the link whose bitrate should be computed. Use a negative number to get the bitrate of the whole stream.

Returns: The bitrate on success, or a negative value on error.

Return values

OP_EINVAL The stream was only partially open, the stream was not seekable, or _li was larger than the number of links.

◆ op_bitrate_instant()

opus_int32 op_bitrate_instant ( OggOpusFile * _of )

Compute the instantaneous bitrate, measured as the ratio of bits to playable samples decoded since a) the last call to op_bitrate_instant(), b) the last seek, or c) the start of playback, whichever was most recent.

This will spike somewhat after a seek or at the start/end of a chain boundary, as pre-skip, pre-roll, and end-trimming causes samples to be decoded but not played.

Parameters

_of	The `OggOpusFile` from which to retrieve the bitrate.

Returns: The bitrate, in bits per second, or a negative value on error.

Return values

OP_FALSE	No data has been decoded since any of the events described above.
OP_EINVAL	The stream was only partially open.

◆ op_raw_tell()

opus_int64 op_raw_tell ( const OggOpusFile * _of )

Obtain the current value of the position indicator for _of.

Parameters

_of	The `OggOpusFile` from which to retrieve the position indicator.

Returns: The byte position that is currently being read from.

Return values

OP_EINVAL The stream was only partially open.

◆ op_pcm_tell()

ogg_int64_t op_pcm_tell ( const OggOpusFile * _of )

Obtain the PCM offset of the next sample to be read.

If the stream is not properly timestamped, this might not increment by the proper amount between reads, or even return monotonically increasing values.

Parameters

_of	The `OggOpusFile` from which to retrieve the PCM offset.

Returns: The PCM offset of the next sample to be read.

Return values

OP_EINVAL The stream was only partially open.

Functions for obtaining information about streams

Detailed Description

Function Documentation

◆ op_seekable()

◆ op_link_count()

◆ op_serialno()

◆ op_channel_count()

◆ op_raw_total()

◆ op_pcm_total()

◆ op_head()

◆ op_tags()

◆ op_current_link()

◆ op_bitrate()

◆ op_bitrate_instant()

◆ op_raw_tell()

◆ op_pcm_tell()