Format:Ogg Opus
| Uses | Library:Libopus |
|---|---|
| Magic | 'OpusHead' (first packet), 'OpusTags' (second packet) |
| Extensions | .opus, .ogg |
| Endianness | little |
| On this wiki | Facts · Code · Notes · Topics |
Opus audio in an Ogg container (RFC 7845, .opus): an OpusHead identification header packet (version 1, channels, pre-skip, mapping family and table) and an OpusTags comment packet, then audio packets; the decoder always runs at 48 kHz.
Overview
The container is Format:Ogg; this page covers what is specific to the Opus mapping. A logical stream has exactly two header packets (OpusHead on its own page, OpusTags) followed by audio packets (RFC 7845 section 5). The basic OpusHead layout is the fact Fact:Ogg/struct/OpusHead; the granule position rules are in Fact:Ogg/behavior/Ogg Opus granule position and pre-skip.
Channel mapping table
The table follows the 19-byte fixed part of OpusHead unless the mapping family is 0: u8 stream count N (not 0), u8 coupled stream count M (not more than N; the first M streams are decoded as stereo, so M+N decoded channels, at most 255), then one u8 per output channel. A mapping value below 2M selects stream value/2 (left channel when even, right when odd); a value from 2M to 254 selects mono stream (value - M); 255 is silence. Family 0 (mono or stereo only) omits the table and implies N=1, M=C-1 and mapping 0, 1.
Mapping families
0: 1 or 2 channels (RTP order). 1: 1 to 8 channels in Vorbis surround order (not the WAVE/FLAC order, so permute when converting). 255: 1 to 255 unidentified channels; general players should not play them. 2 to 254 are reserved and should be treated as 255. Families 2 and 3 (ambisonics) are not in RFC 7845 but are defined by RFC 8486 (Ambisonics in an Ogg Opus Container, sections 3.1 and 3.2): a decoder that meets family 2 or 3 must interpret the channels as ambisonic, and a demuxer that does not know them should act as for 255 (RFC 8486 text read at https://www.rfc-editor.org/rfc/rfc8486.txt). Experimental numbers 254 (for family 2) and 253 (for family 3) are noted there for pre-standard use.
OpusTags
After the 8-byte magic 'OpusTags': u32 vendor string length, the UTF-8 vendor string, u32 comment count, then for each comment a u32 length and a UTF-8 NAME=value string. This is the Vorbis comment layout without the final framing bit. Two extra tags exist: R128_TRACK_GAIN and R128_ALBUM_GAIN, ASCII decimal integers from -32768 to 32767 (at most 6 characters) in Q7.8 dB, applied in addition to the header output gain. A parser may reject a comment header larger than 125,829,120 octets and may ignore comments not fully inside the first 61,440 octets.
Playback details
Output gain scale: sample *= pow(10, output_gain / (20.0 * 256)). Input sample rate is informational (0 = unspecified); decode at 48 kHz or another rate Opus supports (8, 12, 16, 24, 48 kHz). Pre-roll when seeking: decode at least 3840 samples (80 ms) before the target and discard them.
Code & repositories
- RFC 7845 (https://www.rfc-editor.org/rfc/rfc7845) and the xiph/opus repository, see Library:Libopus.