Ogg Encapsulation for the Opus Audio Codec
Extracted elements (30)
EBU R128 normalization is preferred over REPLAYGAIN schemes because of its clear definition and industry adoption; peak normalizations are excluded because they are unreliable for lossy codecs due to decoder-dependent excursion height variation.
Opus uses the pre-skip mechanism rather than Vorbis's trimmed granule position approach because the encoder might introduce more than a single packet's worth of latency, and very large packets in streams with many channels might not fit on a single page.
The 61,440-octet audio packet size limit was derived from the maximum reasonable packet size of (7,664*N - 2) octets for 120 ms of 8-channel stereo CELT, rounded up to a multiple of 1,024, ensuring all implementations can process it without excessive memory use.
The version number in the ID header was split into major/minor sub-fields (upper/lower four bits) to allow backwards-compatible extensions without requiring a new codec identifier. The initial version '1' was chosen to prevent implementations from treating the byte as a null terminator for 'OpusHead'.
Channel Mapping Family 1 uses Vorbis speaker ordering (e.g., for 7.1: FL, FC, FR, SL, SR, RL, RR, LFE), which differs from WAVE and FLAC multichannel ordering; correct output requires channel permutation when converting between formats.
A demuxer MUST NOT attempt to decode the data for the first packet on a page with the 'continued packet' flag set if the previous page does not end in a continued packet or the page sequence numbers are not consecutive.
All audio data pages with completed packets after the first MUST have a granule position equal to the number of samples in packets completing on that page plus the granule position of the most recent page with completed packets.
All Opus packets in a single Ogg packet MUST be constrained to have the same duration; implementations SHOULD treat any Opus packet with a different duration from the first as a malformed packet.
An implementation MUST treat any stream as invalid if the granule position of the first audio data page with a completed packet is smaller than the number of samples contained in packets that complete on that page, unless that page has the 'end of stream' flag set.
An Ogg Opus player MUST support any valid channel mapping with family 0 or 1, even if the channel count does not match the hardware, and SHOULD perform channel mixing as needed.
Demuxers SHOULD treat audio data packets as invalid if they are larger than 61,440 octets per Opus stream. Demuxers MUST avoid attempting to allocate excessive amounts of memory when presented with very large packets.
If a player uses R128_TRACK_GAIN or R128_ALBUM_GAIN, it MUST apply those gains in addition to the 'output gain' value from the ID header. If a tool modifies the ID header's 'output gain', it MUST also update or remove the R128 comment tags.
R128_TRACK_GAIN and R128_ALBUM_GAIN tags MUST NOT appear more than once each; their values MUST be integers from -32768 to 32767 in ASCII base-10 with no whitespace and no more than 6 characters.
The first packet in the logical Ogg bitstream MUST contain the identification (ID) header, placed alone on the first page with its 'beginning of stream' flag set.
The granule position MUST be zero for the ID header page and the page where the comment header completes.
The Output Channel Count field MUST NOT be zero, and the Channel Mapping Table MUST be omitted when the channel mapping family is 0 but is REQUIRED otherwise.
The RECOMMENDED MIME type for Ogg Opus files is 'audio/ogg'; the RECOMMENDED filename extension is '.opus'. When multiplexed with other streams, 'audio/ogg', 'video/ogg', or 'application/ogg' SHOULD be used and '.opus' is NOT RECOMMENDED.
The second packet in the logical Ogg bitstream MUST contain the comment header, and the comment header packet MUST finish the page on which it completes.
The Version field in the ID header MUST always be '1' for this version of the encapsulation specification. Implementations SHOULD treat streams with the same upper four bits as backwards compatible, accepting version numbers 15 or less and rejecting 16 or greater.
When seeking within an Ogg Opus stream, an implementation SHOULD start decoding and discarding output at least 3840 samples (80 ms) prior to the seek target to ensure correct audio at the target.
Channel Mapping Family 0 supports 1 or 2 channels (mono or stereo) with the same channel interpretation as RFC 7587 RTP mapping. The channel mapping table is omitted; stream count defaults to 1 and coupled count defaults to (C-1).
Channel Mapping Family 1 supports 1 to 8 channels using Vorbis channel order, defining speaker locations for mono through 7.1 surround. This ordering differs from WAVE and FLAC formats and requires permutation when interfacing with those formats.
The Channel Mapping Table contains Stream Count 'N' (8-bit unsigned), Coupled Stream Count 'M' (8-bit unsigned), and Channel Mapping (8*C bits, one octet per output channel). An index of 255 in the Channel Mapping indicates a silent output channel.
The Output Gain field is a 16-bit signed Q7.8 fixed-point value in dB representing 20*log10 of the factor to scale decoder output. Players and media frameworks SHOULD apply it by default; any additional volume adjustment MUST be applied in addition to this gain.
This document defines the 'Opus Channel Mapping Families' IANA registry (values 0-255) with 'Specification Required' registration policy, with initial assignments: 0 (RFC 7845 §5.1.1.1), 1 (RFC 7845 §5.1.1.2), and 255 (RFC 7845 §5.1.1.3).
Implementations MUST NOT overrun allocated memory nor consume excessive resources when decoding payloads. Comment headers with inflated string length or user comment count fields could trigger integer overflow or excessive memory allocation; implementations should validate sizes before allocating.
Ogg Opus streams SHOULD NOT be used with insecure ciphers or cipher modes vulnerable to known-plaintext attacks, as the Ogg page capture pattern, magic signature fields, and codec data all contain easily predictable values.
Seeking implementations must guard against quadratic-complexity re-scanning caused by invalid data at the end of a stream; algorithms must continue to make progress and terminate even with missing or out-of-order granule positions.
The comment header begins with an 8-octet magic signature 'OpusTags', followed by Vendor String Length (32-bit unsigned little-endian), Vendor String (UTF-8), User Comment List Length (32-bit unsigned little-endian), and per-comment String Length (32-bit) and String (UTF-8) pairs.
The ID header begins with an 8-octet magic signature 'OpusHead', followed by Version (8-bit unsigned), Channel Count (8-bit unsigned), Pre-skip (16-bit unsigned little-endian), Input Sample Rate (32-bit unsigned little-endian), Output Gain (16-bit signed Q7.8 little-endian), Channel Mapping Family (8-bit unsigned), and optional Channel Mapping Table.