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 (OggOpusFile *_of) OP_ARG_NONNULL(1)
	Returns whether or not the data source being read is seekable.
int	op_link_count (OggOpusFile *_of) OP_ARG_NONNULL(1)
	Returns the number of links in this chained stream.
opus_uint32	op_serialno (OggOpusFile *_of, int _li) OP_ARG_NONNULL(1)
	Get the serial number of the given link in a (possibly-chained) Ogg Opus stream.
int	op_channel_count (OggOpusFile *_of, int _li) OP_ARG_NONNULL(1)
	Get the channel count of the given link in a (possibly-chained) Ogg Opus stream.
opus_int64	op_raw_total (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.
ogg_int64_t	op_pcm_total (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.
const OpusHead *	op_head (OggOpusFile *_of, int _li) OP_ARG_NONNULL(1)
	Get the ID header information for the given link in a (possibly chained) Ogg Opus stream.
const OpusTags *	op_tags (OggOpusFile *_of, int _li) OP_ARG_NONNULL(1)
	Get the comment header information for the given link in a (possibly chained) Ogg Opus stream.
int	op_current_link (OggOpusFile *_of) OP_ARG_NONNULL(1)
	Retrieve the index of the current link.
opus_int32	op_bitrate (OggOpusFile *_of, int _li) OP_ARG_NONNULL(1)
	Computes the bitrate for a given link in a (possibly chained) Ogg Opus stream.
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.
opus_int64	op_raw_tell (OggOpusFile *_of) OP_ARG_NONNULL(1)
	Obtain the current value of the position indicator for _of.
ogg_int64_t	op_pcm_tell (OggOpusFile *_of) OP_ARG_NONNULL(1)
	Obtain the PCM offset of the next sample to be read.

Detailed Description

Function Documentation

int op_seekable ( OggOpusFile * _of )

Returns whether or not the data source 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.

int op_link_count ( 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 sources, this returns the total number of links in the whole stream. For partially-open or unseekable sources, this always returns 1.

opus_uint32 op_serialno	(	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 source is not seekable, this always returns the serial number of the current link.

int op_channel_count	(	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 source is not seekable, this always returns the channel count of the current link.

opus_int64 op_raw_total	(	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.

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 source if trailing garbage was detected in the file.

Return values:

OP_EINVAL The source 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.

ogg_int64_t op_pcm_total	(	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 source 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.

const OpusHead* op_head	(	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.

const OpusTags* op_tags	(	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.

int op_current_link ( 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 and the value returned by op_link_count(). 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.

opus_int32 op_bitrate	(	OggOpusFile *	_of,
		int	_li
	)

Computes the bitrate for a given 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.

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.

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.

opus_int64 op_raw_tell ( 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.

ogg_int64_t op_pcm_tell ( 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