The setup header holds everything a decoder needs: the codebooks, then descriptions of the
floors, residues, mappings and modes that the audio packets refer to. After the common
header (packet_type 5 and vorbis), every field is packed bit
by bit, the first field in the lowest bits of each byte. The header ends with a framing bit,
which must be 1. Sizes below are in bits.
In order
| Size | Name | Description |
|---|---|---|
| 8 | vorbis_codebook_count | the number of codebooks, minus one |
| codebooks | see Codebooks | |
| 6 | vorbis_time_count | the number of time-domain transforms, minus one |
| 16 each | time transforms | placeholders; each must be 0 |
| 6 | vorbis_floor_count | the number of floors, minus one |
| floors | see Floors | |
| 6 | vorbis_residue_count | the number of residues, minus one |
| residues | see Residues | |
| 6 | vorbis_mapping_count | the number of mappings, minus one |
| mappings | see Mappings | |
| 6 | vorbis_mode_count | the number of modes, minus one |
| modes | see Modes | |
| 1 | framing_flag | must be 1 |
Codebooks
A codebook turns bits into entry numbers with a canonical Huffman code, and turns entries into vectors for vector quantisation.
| Size | Name | Description |
|---|---|---|
| 24 | sync | the value 0x564342 (BCV) |
| 16 | codebook_dimensions | values in each vector |
| 24 | codebook_entries | the number of entries |
| 1 | ordered | set when the codeword lengths are sorted and run-length coded |
| 1 | sparse | when not ordered: set when entries may be unused |
| 1 | used | when sparse, one bit for each entry: 0 means it has no codeword |
| 5 | codeword length | when not ordered, each entry’s codeword length, minus one |
| 5 | first length | when ordered: the first length, minus one; then a count, in as many bits as ilog(remaining entries), for each length |
| 4 | codebook_lookup_type | 0 no vector lookup, 1 lattice, 2 explicit |
| 32 | minimum_value | when the lookup type is 1 or 2: a Vorbis float, see below |
| 32 | delta_value | likewise: the step between values, a Vorbis float |
| 4 | value_bits | the bits per multiplicand, minus one |
| 1 | sequence_p | set when each vector value builds on the one before it |
| value_bits | multiplicands | lookup1_values(entries, dimensions) of them for type 1, or entries × dimensions for type 2 |
The entropy code gives each entry the lowest codeword of its length still free,
in entry order. lookup1_values is the largest integer r such that
r to the power of dimensions is at most entries.
A Vorbis float is a 32-bit field: 21 bits of mantissa, 10 of exponent and one of sign,
from the least significant end. Its value is
mantissa × 2^(exponent − 788), negated if the sign bit is set.
For lookup type 1, a vector value for dimension d comes from the entry number written in
base lookup_values; for type 2 the multiplicands are listed in full. In both
cases each value is multiplicand × delta + minimum, with the previous value added
when sequence_p is set.
Floors
Each floor starts with a 16-bit type: 0 or 1.
Floor type 0
| Size | Name | Description |
|---|---|---|
| 8 | floor0_order | the order of the LSP filter |
| 16 | floor0_rate | the sample rate the floor was designed for |
| 16 | floor0_bark_map_size | the number of steps on the Bark scale |
| 6 | floor0_amplitude_bits | the width of the amplitude in an audio packet |
| 8 | floor0_amplitude_offset | the amplitude’s scale in dB |
| 4 | floor0_number_of_books | how many codebooks, minus one |
| 8 each | floor0_book_list | the codebook numbers |
Floor type 1
| Size | Name | Description |
|---|---|---|
| 5 | floor1_partitions | the number of partitions |
| 4 each | floor1_partition_class_list | each partition’s class |
| 3 | class dimension | for each class: posts it holds, minus one |
| 2 | class subclasses | for each class: log2 of the number of subclasses |
| 8 | class masterbook | when there are subclasses: the codebook that selects one |
| 8 each | subclass books | for each subclass (2 to the power of subclasses): codebook number plus one, or 0 for none |
| 2 | floor1_multiplier | the amplitude multiplier, minus one, so 1 to 4 |
| 4 | rangebits | the width of each post’s X position |
| rangebits each | floor1_X_list | X positions of the posts, by partition and class dimension (0 and 2 to the power of rangebits are implicit first entries) |
The multiplier selects the amplitude range: 256, 128, 86 or 64 steps for multipliers 1 to 4.
Residues
| Size | Name | Description |
|---|---|---|
| 16 | residue type | 0, 1 or 2: see decoding |
| 24 | residue_begin | the first position coded |
| 24 | residue_end | one past the last position coded |
| 24 | residue_partition_size | the partition size, minus one |
| 6 | residue_classifications | the number of classes, minus one |
| 8 | residue_classbook | the codebook that classifies partitions |
| 3 + 1 + 5 | cascade | for each class, a pattern of up to 8 passes: 3 low bits, a flag, and 5 more high bits when the flag is set |
| 8 each | residue_books | for each set bit in the cascade: a codebook number |
Mappings
| Size | Name | Description |
|---|---|---|
| 16 | mapping type | must be 0 |
| 1 | submaps flag | when set, a submap count follows |
| 4 | vorbis_mapping_submaps | the number of submaps, minus one; otherwise one submap |
| 1 | coupling flag | when set, coupling steps follow |
| 8 | vorbis_mapping_coupling_steps | the number of coupling steps, minus one |
| ilog(channels − 1) each | magnitude, angle | for each step, the channels coupled together |
| 2 | reserved | must be 0 |
| 4 each | vorbis_mapping_mux | when more than one submap: the submap for each channel |
| 8 | discard | for each submap: an unused time-domain field |
| 8 | submap floor | for each submap: the floor number |
| 8 | submap residue | for each submap: the residue number |
Modes
| Size | Name | Description |
|---|---|---|
| 1 | vorbis_mode_blockflag | 0 short block, 1 long block |
| 16 | vorbis_mode_windowtype | must be 0 |
| 16 | vorbis_mode_transformtype | must be 0 |
| 8 | vorbis_mode_mapping | the mapping number |
Links
- Vorbis I specification – the Xiph.Org Foundation’s description of the codec