Header Information

Data Structures
struct	OpusHead
	Ogg Opus bitstream information. More...
struct	OpusTags
	The metadata from an Ogg Opus stream. More...
Defines
#define	OPUS_CHANNEL_COUNT_MAX   (255)
	The maximum number of channels in an Ogg Opus stream.
Functions for manipulating header data
These functions manipulate the OpusHead and OpusTags structures, which describe the audio parameters and tag-value metadata, respectively. These can be used to query the headers returned by libopusfile, or to parse Opus headers from sources other than an Ogg Opus stream, provided they use the same format.
OP_WARN_UNUSED_RESULT int	opus_head_parse (OpusHead *_head, const unsigned char *_data, size_t _len) OP_ARG_NONNULL(2)
	Parses the contents of the ID header packet of an Ogg Opus stream.
ogg_int64_t	opus_granule_sample (const OpusHead *_head, ogg_int64_t _gp) OP_ARG_NONNULL(1)
	Converts a granule position to a sample offset for a given Ogg Opus stream.
OP_WARN_UNUSED_RESULT int	opus_tags_parse (OpusTags *_tags, const unsigned char *_data, size_t _len) OP_ARG_NONNULL(2)
	Parses the contents of the 'comment' header packet of an Ogg Opus stream.
void	opus_tags_init (OpusTags *_tags) OP_ARG_NONNULL(1)
	Initializes an OpusTags structure.
int	opus_tags_add (OpusTags *_tags, const char *_tag, const char *_value) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2) OP_ARG_NONNULL(3)
	Add a (tag, value) pair to an initialized OpusTags structure.
int	opus_tags_add_comment (OpusTags *_tags, const char *_comment) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2)
	Add a comment to an initialized OpusTags structure.
const char *	opus_tags_query (const OpusTags *_tags, const char *_tag, int _count) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2)
	Look up a comment value by its tag.
int	opus_tags_query_count (const OpusTags *_tags, const char *_tag) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2)
	Look up the number of instances of a tag.
void	opus_tags_clear (OpusTags *_tags) OP_ARG_NONNULL(1)
	Clears the OpusTags structure.

---

Define Documentation

#define OPUS_CHANNEL_COUNT_MAX   (255)

The maximum number of channels in an Ogg Opus stream.

---

Function Documentation

OP_WARN_UNUSED_RESULT int opus_head_parse	(	OpusHead *	_head,
		const unsigned char *	_data,
		size_t	_len
	)

Parses the contents of the ID header packet of an Ogg Opus stream.

Parameters:

[out]	_head	Returns the contents of the parsed packet. The contents of this structure are untouched on error. This may be NULL to merely test the header for validity.
[in]	_data	The contents of the ID header packet.
	_len	The number of bytes of data in the ID header packet.

Returns:

0 on success or a negative value on error.

Return values:

OP_ENOTFORMAT	If the data does not start with the "OpusHead" string.
OP_EVERSION	If the version field signaled a version this library does not know how to parse.
OP_EIMPL	If the channel mapping family was 255, which general purpose players should not attempt to play.
OP_EBADHEADER	If the contents of the packet otherwise violate the Ogg Opus specification: Insufficient data, Too much data for the known minor versions, An unrecognized channel mapping family, Zero channels or too many channels, Zero coded streams, Too many coupled streams, or An invalid channel mapping index.

ogg_int64_t opus_granule_sample	(	const OpusHead *	_head,
		ogg_int64_t	_gp
	)

Converts a granule position to a sample offset for a given Ogg Opus stream.

The sample offset is simply _gp-_head->pre_skip. Granule position values smaller than OpusHead::pre_skip correspond to audio that should never be played, and thus have no associated sample offset. This function returns -1 for such values. This function also correctly handles extremely large granule positions, which may have wrapped around to a negative number when stored in a signed ogg_int64_t value.

Parameters:

_head	The OpusHead information from the ID header of the stream.
_gp	The granule position to convert.

Returns:

The sample offset associated with the given granule position (counting at a 48 kHz sampling rate), or the special value -1 on error (i.e., the granule position was smaller than the pre-skip amount).

OP_WARN_UNUSED_RESULT int opus_tags_parse	(	OpusTags *	_tags,
		const unsigned char *	_data,
		size_t	_len
	)

Parses the contents of the 'comment' header packet of an Ogg Opus stream.

Parameters:

[out]	_tags	An uninitialized OpusTags structure. This returns the contents of the parsed packet. The contents of this structure are untouched on error. This may be NULL to merely test the header for validity.
[in]	_data	The contents of the 'comment' header packet.
	_len	The number of bytes of data in the 'info' header packet.

Return values:

0	Success.
OP_ENOTFORMAT	If the data does not start with the "OpusTags" string.
OP_EBADHEADER	If the contents of the packet otherwise violate the Ogg Opus specification.
OP_EFAULT	If there wasn't enough memory to store the tags.

void opus_tags_init

(

OpusTags *

_tags

)

Initializes an OpusTags structure.

This should be called on a freshly allocated OpusTags structure before attempting to use it.

Parameters:

_tags

The OpusTags structure to initialize.

int opus_tags_add	(	OpusTags *	_tags,
		const char *	_tag,
		const char *	_value
	)

Add a (tag, value) pair to an initialized OpusTags structure.

Note:

Neither opus_tags_add() nor opus_tags_add_comment() support values containing embedded NULs, although the bitstream format does support them. To add such tags, you will need to manipulate the OpusTags structure directly.

Parameters:

_tags	The OpusTags structure to add the (tag, value) pair to.
_tag	A NUL-terminated, case-insensitive, ASCII string containing the tag to add (without an '=' character).
_value	A NUL-terminated UTF-8 containing the corresponding value.

Returns:

0 on success, or a negative value on failure.

Return values:

OP_EFAULT

An internal memory allocation failed.

int opus_tags_add_comment	(	OpusTags *	_tags,
		const char *	_comment
	)

Add a comment to an initialized OpusTags structure.

Note:

Neither opus_tags_add_comment() nor opus_tags_add() support comments containing embedded NULs, although the bitstream format does support them. To add such tags, you will need to manipulate the OpusTags structure directly.

Parameters:

_tags	The OpusTags structure to add the comment to.
_comment	A NUL-terminated UTF-8 string containing the comment in "TAG=value" form.

Returns:

0 on success, or a negative value on failure.

Return values:

OP_EFAULT

An internal memory allocation failed.

const char* opus_tags_query	(	const OpusTags *	_tags,
		const char *	_tag,
		int	_count
	)

Look up a comment value by its tag.

Parameters:

_tags	An initialized OpusTags structure.
_tag	The tag to look up.
_count	The instance of the tag. The same tag can appear multiple times, each with a distinct value, so an index is required to retrieve them all. The order in which these values appear is significant and should be preserved. Use opus_tags_query_count() to get the legal range for the _count parameter.

Returns:

A pointer to the queried tag's value. This points directly to data in the OpusTags structure. It should not be modified or freed by the application, and modifications to the structure may invalidate the pointer.

Return values:

NULL	If no matching tag is found.

int opus_tags_query_count	(	const OpusTags *	_tags,
		const char *	_tag
	)

Look up the number of instances of a tag.

Call this first when querying for a specific tag and then iterate over the number of instances with separate calls to opus_tags_query() to retrieve all the values for that tag in order.

Parameters:

_tags	An initialized OpusTags structure.
_tag	The tag to look up.

Returns:

The number of instances of this particular tag.

void opus_tags_clear

(

OpusTags *

_tags

)

Clears the OpusTags structure.

This should be called on an OpusTags structure after it is no longer needed. It will free all memory used by the structure members.

Parameters:

_tags

The OpusTags structure to clear.