opusfile: Stream Information

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

Stream Information

## 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 data source 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 data source being read is seekable.

This is true if

1. The `seek()` and `tell()` callbacks are both non-`NULL`,
2. The `seek()` callback was successfully executed at least once, and
3. 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 sources, this returns the total number of links in the whole stream, which will be at least 1. For partially-open or unseekable sources, 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 source 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 source 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 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.

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

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

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