An Opus stream in Ogg starts with two header packets, described in RFC 7845. Every other packet is audio. All numbers are little-endian.
OpusHead
The identification header is alone on the stream’s first page. It is 19 bytes, or more when a mapping table follows.
| Offset | Size | Name | Description |
|---|---|---|---|
| 0 | 8 | magic | the ASCII characters OpusHead |
| 8 | 1 | version | high 4 bits the major version, which must be 0; low 4 bits the minor version. Readers accept any minor version |
| 9 | 1 | channel count | the number of output channels, from 1 upwards |
| 10 | 2 | pre-skip | samples at 48 kHz to drop from the start of the decoded audio |
| 12 | 4 | input sample rate | the rate of the source, for information only; decoders output 48 kHz |
| 16 | 2 | output gain | a gain in Q7.8 dB (signed), applied at the output |
| 18 | 1 | mapping family | how channels are carried: see below |
| 19 | 1 | stream count | family ≠ 0: the number of Opus streams in each packet |
| 20 | 1 | coupled count | family ≠ 0: how many of those are stereo pairs |
| 21 | C | channel mapping | family ≠ 0 (except family 3): for each output channel, the decoded channel number, or 255 for silence |
Channel mapping families
| Family | Meaning |
|---|---|
| 0 | one stream, mono or stereo. No table |
| 1 | 1 to 8 channels in the Vorbis channel order, with a mapping table |
| 2 | ambisonics (RFC 8486): (order + 1)² channels, plus 2 when a non-diegetic stereo pair is added, with a mapping table in ACN order and SN3D normalisation |
| 3 | ambisonics with a demixing matrix (RFC 8486): the table is a matrix of (streams + coupled) × channels 16-bit values instead |
| 255 | discrete channels with no defined layout |
| others | reserved; a reader may not attempt to play them |
A stream count of N and coupled count of M give N + M decoded channels. Decoded channel numbers below 2M are the coupled pairs’ left and right; the rest are the mono streams.
Time and trimming
Granule positions count 48 kHz samples. The first page carrying audio must have a granule position no
greater than the samples it completes; a smaller value means extra samples at the start
have been dropped. The audio time of a granule position is
(granule − pre-skip) / 48000 seconds. The stream’s last page may give a granule position
smaller than the samples decoded: the excess at the end is discarded, which is how Opus
files are cut to the exact sample count.
Decoders output 48 kHz at the header’s gain, and multistream packets use self-delimited framing for every stream but the last.