opusfile: Header Information

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

Data Structures | Macros
Header Information

## Data Structures
struct | OpusHead
| Ogg Opus bitstream information. More...
struct | OpusTags
| The metadata from an Ogg Opus stream. More...
struct | OpusPictureTag
| The contents of a METADATA_BLOCK_PICTURE tag. More...

## Macros
#define | OPUS_CHANNEL_COUNT_MAX (255)
| The maximum number of channels in an Ogg Opus stream. More...

## Picture tag image formats
#define | OP_PIC_FORMAT_UNKNOWN (-1)
| The MIME type was not recognized, or the image data did not match the declared MIME type. More...
#define | OP_PIC_FORMAT_URL (0)
| The MIME type indicates the image data is really a URL. More...
#define | OP_PIC_FORMAT_JPEG (1)
| The image is a JPEG. More...
#define | OP_PIC_FORMAT_PNG (2)
| The image is a PNG. More...
#define | OP_PIC_FORMAT_GIF (3)
| The image is a GIF. More...

## 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. More...
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. More...
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. More...
int | opus_tags_copy (OpusTags *_dst, const OpusTags *_src) OP_ARG_NONNULL(1)
| Performs a deep copy of an OpusTags structure. More...
void | opus_tags_init (OpusTags *_tags) OP_ARG_NONNULL(1)
| Initializes an OpusTags structure. More...
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. More...
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. More...
int | opus_tags_set_binary_suffix (OpusTags *_tags, const unsigned char *_data, int _len) OP_ARG_NONNULL(1)
| Replace the binary suffix data at the end of the packet (if any). More...
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. More...
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. More...
const unsigned char * | opus_tags_get_binary_suffix (const OpusTags *_tags, int *_len) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2)
| Retrieve the binary suffix data at the end of the packet (if any). More...
int | opus_tags_get_album_gain (const OpusTags *_tags, int *_gain_q8) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2)
| Get the album gain from an R128_ALBUM_GAIN tag, if one was specified. More...
int | opus_tags_get_track_gain (const OpusTags *_tags, int *_gain_q8) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2)
| Get the track gain from an R128_TRACK_GAIN tag, if one was specified. More...
void | opus_tags_clear (OpusTags *_tags) OP_ARG_NONNULL(1)
| Clears the OpusTags structure. More...
int | opus_tagcompare (const char *_tag_name, const char *_comment)
| Check if _comment is an instance of a _tag_name tag. More...
int | opus_tagncompare (const char *_tag_name, int _tag_len, const char *_comment)
| Check if _comment is an instance of a _tag_name tag. More...
OP_WARN_UNUSED_RESULT int | opus_picture_tag_parse (OpusPictureTag *_pic, const char *_tag) OP_ARG_NONNULL(1) OP_ARG_NONNULL(2)
| Parse a single METADATA_BLOCK_PICTURE tag. More...
void | opus_picture_tag_init (OpusPictureTag *_pic) OP_ARG_NONNULL(1)
| Initializes an OpusPictureTag structure. More...
void | opus_picture_tag_clear (OpusPictureTag *_pic) OP_ARG_NONNULL(1)
| Clears the OpusPictureTag structure. More...

## Detailed Description

## Macro Definition Documentation

## § OPUS_CHANNEL_COUNT_MAX

#define OPUS_CHANNEL_COUNT_MAX (255)

The maximum number of channels in an Ogg Opus stream.

## § OP_PIC_FORMAT_UNKNOWN

#define OP_PIC_FORMAT_UNKNOWN (-1)

The MIME type was not recognized, or the image data did not match the declared MIME type.

## § OP_PIC_FORMAT_URL

#define OP_PIC_FORMAT_URL (0)

The MIME type indicates the image data is really a URL.

## § OP_PIC_FORMAT_JPEG

#define OP_PIC_FORMAT_JPEG (1)

The image is a JPEG.

## § OP_PIC_FORMAT_PNG

#define OP_PIC_FORMAT_PNG (2)

The image is a PNG.

## § OP_PIC_FORMAT_GIF

#define OP_PIC_FORMAT_GIF (3)

The image is a GIF.

## Function Documentation

## § opus_head_parse()

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.

## § opus_granule_sample()

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

## § opus_tags_parse()

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.

## § opus_tags_copy()

int opus_tags_copy | ( | OpusTags * | _dst,
|  | const OpusTags * | _src
| ) |  |

Performs a deep copy of an OpusTags structure.

Parameters

  _dst | The OpusTags structure to copy into. If this function fails, the contents of this structure remain untouched.
  _src | The OpusTags structure to copy from.

Return values

  0 | Success.
  OP_EFAULT | If there wasn't enough memory to copy the tags.

## § opus_tags_init()

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.

## § opus_tags_add()

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.

## § opus_tags_add_comment()

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.

## § opus_tags_set_binary_suffix()

int opus_tags_set_binary_suffix | ( | OpusTags * | _tags,
|  | const unsigned char * | _data,
|  | int | _len
| ) |  |

Replace the binary suffix data at the end of the packet (if any).

Parameters

  _tags | An initialized OpusTags structure.
  _data | A buffer of binary data to append after the encoded user comments. The least significant bit of the first byte of this data must be set (to ensure the data is preserved by other editors).
  _len | The number of bytes of binary data to append. This may be zero to remove any existing binary suffix data.

Returns
  0 on success, or a negative value on error.

Return values

  OP_EINVAL | _len was negative, or _len was positive but _data was `NULL` or the least significant bit of the first byte was not set.
  OP_EFAULT | An internal memory allocation failed.

## § opus_tags_query()

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.

## § opus_tags_query_count()

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.

## § opus_tags_get_binary_suffix()

const unsigned char* opus_tags_get_binary_suffix | ( | const OpusTags * | _tags,
|  | int * | _len
| ) |  |

Retrieve the binary suffix data at the end of the packet (if any).

Parameters

  | _tags | An initialized OpusTags structure.
  [out] | _len | Returns the number of bytes of binary suffix data returned.

Returns
  A pointer to the binary suffix data, or `NULL` if none was present.

## § opus_tags_get_album_gain()

int opus_tags_get_album_gain | ( | const OpusTags * | _tags,
|  | int * | _gain_q8
| ) |  |

Get the album gain from an R128_ALBUM_GAIN tag, if one was specified.

This searches for the first R128_ALBUM_GAIN tag with a valid signed, 16-bit decimal integer value and returns the value. This routine is exposed merely for convenience for applications which wish to do something special with the album gain (i.e., display it). If you simply wish to apply the album gain instead of the header gain, you can use op_set_gain_offset() with an OP_ALBUM_GAIN type and no offset.

Parameters

  | _tags | An initialized OpusTags structure.
  [out] | _gain_q8 | The album gain, in 1/256ths of a dB. This will lie in the range [-32768,32767], and should be applied in addition to the header gain. On error, no value is returned, and the previous contents remain unchanged.

Returns
  0 on success, or a negative value on error.

Return values

  OP_FALSE | There was no album gain available in the given tags.

## § opus_tags_get_track_gain()

int opus_tags_get_track_gain | ( | const OpusTags * | _tags,
|  | int * | _gain_q8
| ) |  |

Get the track gain from an R128_TRACK_GAIN tag, if one was specified.

This searches for the first R128_TRACK_GAIN tag with a valid signed, 16-bit decimal integer value and returns the value. This routine is exposed merely for convenience for applications which wish to do something special with the track gain (i.e., display it). If you simply wish to apply the track gain instead of the header gain, you can use op_set_gain_offset() with an OP_TRACK_GAIN type and no offset.

Parameters

  | _tags | An initialized OpusTags structure.
  [out] | _gain_q8 | The track gain, in 1/256ths of a dB. This will lie in the range [-32768,32767], and should be applied in addition to the header gain. On error, no value is returned, and the previous contents remain unchanged.

Returns
  0 on success, or a negative value on error.

Return values

  OP_FALSE | There was no track gain available in the given tags.

## § opus_tags_clear()

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.

## § opus_tagcompare()

int opus_tagcompare | ( | const char * | _tag_name,
|  | const char * | _comment
| ) |  |

Check if _comment is an instance of a _tag_name tag.

See also
  opus_tagncompare

Parameters

  _tag_name | A NUL-terminated, case-insensitive, ASCII string containing the name of the tag to check for (without the terminating '=' character).
  _comment | The comment string to check.

Returns
  An integer less than, equal to, or greater than zero if _comment is found respectively, to be less than, to match, or be greater than a "tag=value" string whose tag matches _tag_name.

## § opus_tagncompare()

int opus_tagncompare | ( | const char * | _tag_name,
|  | int | _tag_len,
|  | const char * | _comment
| ) |  |

Check if _comment is an instance of a _tag_name tag.

This version is slightly more efficient than opus_tagcompare() if the length of the tag name is already known (e.g., because it is a constant).

See also
  opus_tagcompare

Parameters

  _tag_name | A case-insensitive ASCII string containing the name of the tag to check for (without the terminating '=' character).
  _tag_len | The number of characters in the tag name. This must be non-negative.
  _comment | The comment string to check.

Returns
  An integer less than, equal to, or greater than zero if _comment is found respectively, to be less than, to match, or be greater than a "tag=value" string whose tag matches the first _tag_len characters of _tag_name.

## § opus_picture_tag_parse()

OP_WARN_UNUSED_RESULT int opus_picture_tag_parse | ( | OpusPictureTag * | _pic,
|  | const char * | _tag
| ) |  |

Parse a single METADATA_BLOCK_PICTURE tag.

This decodes the BASE64-encoded content of the tag and returns a structure with the MIME type, description, image parameters (if known), and the compressed image data. If the MIME type indicates the presence of an image format we recognize (JPEG, PNG, or GIF) and the actual image data contains the magic signature associated with that format, then the OpusPictureTag::format field will be set to the corresponding format. This is provided as a convenience to avoid requiring applications to parse the MIME type and/or do their own format detection for the commonly used formats. In this case, we also attempt to extract the image parameters directly from the image data (overriding any that were present in the tag, which the specification says applications are not meant to rely on). The application must still provide its own support for actually decoding the image data and, if applicable, retrieving that data from URLs.

Parameters

  [out] | _pic | Returns the parsed picture data. No sanitation is done on the type, MIME type, or description fields, so these might return invalid values. The contents of this structure are left unmodified on failure.
  | _tag | The METADATA_BLOCK_PICTURE tag contents. The leading "METADATA_BLOCK_PICTURE=" portion is optional, to allow the function to be used on either directly on the values in OpusTags::user_comments or on the return value of opus_tags_query().

Returns
  0 on success or a negative value on error.

Return values

  OP_ENOTFORMAT | The METADATA_BLOCK_PICTURE contents were not valid.
  OP_EFAULT | There was not enough memory to store the picture tag contents.

## § opus_picture_tag_init()

void opus_picture_tag_init | ( | OpusPictureTag * | _pic | ) |

Initializes an OpusPictureTag structure.

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

Parameters

  _pic | The OpusPictureTag structure to initialize.

## § opus_picture_tag_clear()

void opus_picture_tag_clear | ( | OpusPictureTag * | _pic | ) |

Clears the OpusPictureTag structure.

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

Parameters

  _pic | The OpusPictureTag structure to clear.