1
2% -*- mode: latex; TeX-master: "Vorbis_I_spec"; -*-
3%!TEX root = Vorbis_I_spec.tex
4% $Id$
5\section{Codec Setup and Packet Decode} \label{vorbis:spec:codec}
6
7\subsection{Overview}
8
9This document serves as the top-level reference document for the
10bit-by-bit decode specification of Vorbis I.  This document assumes a
11high-level understanding of the Vorbis decode process, which is
12provided in \xref{vorbis:spec:intro}.  \xref{vorbis:spec:bitpacking} covers reading and writing bit fields from
13and to bitstream packets.
14
15
16
17\subsection{Header decode and decode setup}
18
19A Vorbis bitstream begins with three header packets. The header
20packets are, in order, the identification header, the comments header,
21and the setup header. All are required for decode compliance.  An
22end-of-packet condition during decoding the first or third header
23packet renders the stream undecodable.  End-of-packet decoding the
24comment header is a non-fatal error condition.
25
26\subsubsection{Common header decode}
27
28Each header packet begins with the same header fields.
29
30
31\begin{Verbatim}[commandchars=\\\{\}]
32  1) [packet_type] : 8 bit value
33  2) 0x76, 0x6f, 0x72, 0x62, 0x69, 0x73: the characters 'v','o','r','b','i','s' as six octets
34\end{Verbatim}
35
36Decode continues according to packet type; the identification header
37is type 1, the comment header type 3 and the setup header type 5
38(these types are all odd as a packet with a leading single bit of '0'
39is an audio packet).  The packets must occur in the order of
40identification, comment, setup.
41
42
43
44\subsubsection{Identification header}
45
46The identification header is a short header of only a few fields used
47to declare the stream definitively as Vorbis, and provide a few externally
48relevant pieces of information about the audio stream. The
49identification header is coded as follows:
50
51\begin{Verbatim}[commandchars=\\\{\}]
52 1) [vorbis_version] = read 32 bits as unsigned integer
53 2) [audio_channels] = read 8 bit integer as unsigned
54 3) [audio_sample_rate] = read 32 bits as unsigned integer
55 4) [bitrate_maximum] = read 32 bits as signed integer
56 5) [bitrate_nominal] = read 32 bits as signed integer
57 6) [bitrate_minimum] = read 32 bits as signed integer
58 7) [blocksize_0] = 2 exponent (read 4 bits as unsigned integer)
59 8) [blocksize_1] = 2 exponent (read 4 bits as unsigned integer)
60 9) [framing_flag] = read one bit
61\end{Verbatim}
62
63\varname{[vorbis_version]} is to read '0' in order to be compatible
64with this document.  Both \varname{[audio_channels]} and
65\varname{[audio_sample_rate]} must read greater than zero.  Allowed final
66blocksize values are 64, 128, 256, 512, 1024, 2048, 4096 and 8192 in
67Vorbis I.  \varname{[blocksize_0]} must be less than or equal to
68\varname{[blocksize_1]}.  The framing bit must be nonzero.  Failure to
69meet any of these conditions renders a stream undecodable.
70
71The bitrate fields above are used only as hints. The nominal bitrate
72field especially may be considerably off in purely VBR streams.  The
73fields are meaningful only when greater than zero.
74
75\begin{itemize}
76  \item All three fields set to the same value implies a fixed rate, or tightly bounded, nearly fixed-rate bitstream
77  \item Only nominal set implies a VBR or ABR stream that averages the nominal bitrate
78  \item Maximum and or minimum set implies a VBR bitstream that obeys the bitrate limits
79  \item None set indicates the encoder does not care to speculate.
80\end{itemize}
81
82
83
84
85\subsubsection{Comment header}
86Comment header decode and data specification is covered in
87\xref{vorbis:spec:comment}.
88
89
90\subsubsection{Setup header}
91
92Vorbis codec setup is configurable to an extreme degree:
93
94\begin{center}
95\includegraphics[width=\textwidth]{components}
96\captionof{figure}{decoder pipeline configuration}
97\end{center}
98
99
100The setup header contains the bulk of the codec setup information
101needed for decode.  The setup header contains, in order, the lists of
102codebook configurations, time-domain transform configurations
103(placeholders in Vorbis I), floor configurations, residue
104configurations, channel mapping configurations and mode
105configurations. It finishes with a framing bit of '1'.  Header decode
106proceeds in the following order:
107
108\paragraph{Codebooks}
109
110\begin{enumerate}
111\item \varname{[vorbis_codebook_count]} = read eight bits as unsigned integer and add one
112\item Decode \varname{[vorbis_codebook_count]} codebooks in order as defined
113in \xref{vorbis:spec:codebook}.  Save each configuration, in
114order, in an array of
115codebook configurations \varname{[vorbis_codebook_configurations]}.
116\end{enumerate}
117
118
119
120\paragraph{Time domain transforms}
121
122These hooks are placeholders in Vorbis I.  Nevertheless, the
123configuration placeholder values must be read to maintain bitstream
124sync.
125
126\begin{enumerate}
127\item \varname{[vorbis_time_count]} = read 6 bits as unsigned integer and add one
128\item read \varname{[vorbis_time_count]} 16 bit values; each value should be zero.  If any value is nonzero, this is an error condition and the stream is undecodable.
129\end{enumerate}
130
131
132
133\paragraph{Floors}
134
135Vorbis uses two floor types; header decode is handed to the decode
136abstraction of the appropriate type.
137
138\begin{enumerate}
139 \item \varname{[vorbis_floor_count]} = read 6 bits as unsigned integer and add one
140 \item For each \varname{[i]} of \varname{[vorbis_floor_count]} floor numbers:
141  \begin{enumerate}
142   \item read the floor type: vector \varname{[vorbis_floor_types]} element \varname{[i]} =
143read 16 bits as unsigned integer
144   \item If the floor type is zero, decode the floor
145configuration as defined in \xref{vorbis:spec:floor0}; save
146this
147configuration in slot \varname{[i]} of the floor configuration array \varname{[vorbis_floor_configurations]}.
148   \item If the floor type is one,
149decode the floor configuration as defined in \xref{vorbis:spec:floor1}; save this configuration in slot \varname{[i]} of the floor configuration array \varname{[vorbis_floor_configurations]}.
150   \item If the the floor type is greater than one, this stream is undecodable; ERROR CONDITION
151  \end{enumerate}
152
153\end{enumerate}
154
155
156
157\paragraph{Residues}
158
159Vorbis uses three residue types; header decode of each type is identical.
160
161
162\begin{enumerate}
163\item \varname{[vorbis_residue_count]} = read 6 bits as unsigned integer and add one
164
165\item For each of \varname{[vorbis_residue_count]} residue numbers:
166 \begin{enumerate}
167  \item read the residue type; vector \varname{[vorbis_residue_types]} element \varname{[i]} = read 16 bits as unsigned integer
168  \item If the residue type is zero,
169one or two, decode the residue configuration as defined in \xref{vorbis:spec:residue}; save this configuration in slot \varname{[i]} of the residue configuration array \varname{[vorbis_residue_configurations]}.
170  \item If the the residue type is greater than two, this stream is undecodable; ERROR CONDITION
171 \end{enumerate}
172
173\end{enumerate}
174
175
176
177\paragraph{Mappings}
178
179Mappings are used to set up specific pipelines for encoding
180multichannel audio with varying channel mapping applications. Vorbis I
181uses a single mapping type (0), with implicit PCM channel mappings.
182
183% FIXME/TODO: LaTeX cannot nest enumerate that deeply, so I have to use
184% itemize at the innermost level. However, it would be much better to 
185% rewrite this pseudocode using listings or algoritmicx or some other
186% package geared towards this.
187\begin{enumerate}
188 \item \varname{[vorbis_mapping_count]} = read 6 bits as unsigned integer and add one
189 \item For each \varname{[i]} of \varname{[vorbis_mapping_count]} mapping numbers:
190  \begin{enumerate}
191   \item read the mapping type: 16 bits as unsigned integer.  There's no reason to save the mapping type in Vorbis I.
192   \item If the mapping type is nonzero, the stream is undecodable
193   \item If the mapping type is zero:
194    \begin{enumerate}
195     \item read 1 bit as a boolean flag
196      \begin{enumerate}
197       \item if set, \varname{[vorbis_mapping_submaps]} = read 4 bits as unsigned integer and add one
198       \item if unset, \varname{[vorbis_mapping_submaps]} = 1
199      \end{enumerate}
200
201
202     \item read 1 bit as a boolean flag
203       \begin{enumerate}
204         \item if set, square polar channel mapping is in use:
205           \begin{itemize}
206             \item \varname{[vorbis_mapping_coupling_steps]} = read 8 bits as unsigned integer and add one
207             \item for \varname{[j]} each of \varname{[vorbis_mapping_coupling_steps]} steps:
208               \begin{itemize}
209                 \item vector \varname{[vorbis_mapping_magnitude]} element \varname{[j]}= read \link{vorbis:spec:ilog}{ilog}(\varname{[audio_channels]} - 1) bits as unsigned integer
210                 \item vector \varname{[vorbis_mapping_angle]} element \varname{[j]}= read \link{vorbis:spec:ilog}{ilog}(\varname{[audio_channels]} - 1) bits as unsigned integer
211                 \item the numbers read in the above two steps are channel numbers representing the channel to treat as magnitude and the channel to treat as angle, respectively.  If for any coupling step the angle channel number equals the magnitude channel number, the magnitude channel number is greater than \varname{[audio_channels]}-1, or the angle channel is greater than \varname{[audio_channels]}-1, the stream is undecodable.
212               \end{itemize}
213
214
215           \end{itemize}
216
217
218         \item if unset, \varname{[vorbis_mapping_coupling_steps]} = 0
219       \end{enumerate}
220
221
222     \item read 2 bits (reserved field); if the value is nonzero, the stream is undecodable
223     \item if \varname{[vorbis_mapping_submaps]} is greater than one, we read channel multiplex settings. For each \varname{[j]} of \varname{[audio_channels]} channels:
224      \begin{enumerate}
225       \item vector \varname{[vorbis_mapping_mux]} element \varname{[j]} = read 4 bits as unsigned integer
226       \item if the value is greater than the highest numbered submap (\varname{[vorbis_mapping_submaps]} - 1), this in an error condition rendering the stream undecodable
227      \end{enumerate}
228
229     \item for each submap \varname{[j]} of \varname{[vorbis_mapping_submaps]} submaps, read the floor and residue numbers for use in decoding that submap:
230      \begin{enumerate}
231       \item read and discard 8 bits (the unused time configuration placeholder)
232       \item read 8 bits as unsigned integer for the floor number; save in vector \varname{[vorbis_mapping_submap_floor]} element \varname{[j]}
233       \item verify the floor number is not greater than the highest number floor configured for the bitstream. If it is, the bitstream is undecodable
234       \item read 8 bits as unsigned integer for the residue number; save in vector \varname{[vorbis_mapping_submap_residue]} element \varname{[j]}
235       \item verify the residue number is not greater than the highest number residue configured for the bitstream.  If it is, the bitstream is undecodable
236      \end{enumerate}
237
238     \item save this mapping configuration in slot \varname{[i]} of the mapping configuration array \varname{[vorbis_mapping_configurations]}.
239    \end{enumerate}
240
241  \end{enumerate}
242
243\end{enumerate}
244
245
246
247\paragraph{Modes}
248
249\begin{enumerate}
250 \item \varname{[vorbis_mode_count]} = read 6 bits as unsigned integer and add one
251 \item For each of \varname{[vorbis_mode_count]} mode numbers:
252  \begin{enumerate}
253  \item \varname{[vorbis_mode_blockflag]} = read 1 bit
254  \item \varname{[vorbis_mode_windowtype]} = read 16 bits as unsigned integer
255  \item \varname{[vorbis_mode_transformtype]} = read 16 bits as unsigned integer
256  \item \varname{[vorbis_mode_mapping]} = read 8 bits as unsigned integer
257  \item verify ranges; zero is the only legal value in Vorbis I for
258\varname{[vorbis_mode_windowtype]}
259and \varname{[vorbis_mode_transformtype]}.  \varname{[vorbis_mode_mapping]} must not be greater than the highest number mapping in use.  Any illegal values render the stream undecodable.
260  \item save this mode configuration in slot \varname{[i]} of the mode configuration array
261\varname{[vorbis_mode_configurations]}.
262 \end{enumerate}
263
264\item read 1 bit as a framing flag.  If unset, a framing error occurred and the stream is not
265decodable.
266\end{enumerate}
267
268After reading mode descriptions, setup header decode is complete.
269
270
271
272
273
274
275
276
277\subsection{Audio packet decode and synthesis}
278
279Following the three header packets, all packets in a Vorbis I stream
280are audio.  The first step of audio packet decode is to read and
281verify the packet type. \emph{A non-audio packet when audio is expected
282indicates stream corruption or a non-compliant stream. The decoder
283must ignore the packet and not attempt decoding it to audio}.
284
285
286\subsubsection{packet type, mode and window decode}
287
288\begin{enumerate}
289 \item read 1 bit \varname{[packet_type]}; check that packet type is 0 (audio)
290 \item read \link{vorbis:spec:ilog}{ilog}([vorbis_mode_count]-1) bits
291\varname{[mode_number]}
292 \item decode blocksize \varname{[n]} is equal to \varname{[blocksize_0]} if
293\varname{[vorbis_mode_blockflag]} is 0, else \varname{[n]} is equal to \varname{[blocksize_1]}.
294 \item perform window selection and setup; this window is used later by the inverse MDCT:
295  \begin{enumerate}
296   \item if this is a long window (the \varname{[vorbis_mode_blockflag]} flag of this mode is
297set):
298    \begin{enumerate}
299     \item read 1 bit for \varname{[previous_window_flag]}
300     \item read 1 bit for \varname{[next_window_flag]}
301     \item if \varname{[previous_window_flag]} is not set, the left half
302         of the window will be a hybrid window for lapping with a
303         short block.  See \xref{vorbis:spec:window} for an illustration of overlapping
304dissimilar
305         windows. Else, the left half window will have normal long
306         shape.
307     \item if \varname{[next_window_flag]} is not set, the right half of
308         the window will be a hybrid window for lapping with a short
309         block.  See \xref{vorbis:spec:window} for an
310illustration of overlapping dissimilar
311         windows. Else, the left right window will have normal long
312         shape.
313    \end{enumerate}
314
315   \item  if this is a short window, the window is always the same
316       short-window shape.
317  \end{enumerate}
318
319\end{enumerate}
320
321Vorbis windows all use the slope function $y=\sin(\frac{\pi}{2} * \sin^2((x+0.5)/n * \pi))$,
322where $n$ is window size and $x$ ranges $0 \ldots n-1$, but dissimilar
323lapping requirements can affect overall shape.  Window generation
324proceeds as follows:
325
326\begin{enumerate}
327 \item  \varname{[window_center]} = \varname{[n]} / 2
328 \item  if (\varname{[vorbis_mode_blockflag]} is set and \varname{[previous_window_flag]} is
329not set) then
330  \begin{enumerate}
331   \item \varname{[left_window_start]} = \varname{[n]}/4 -
332\varname{[blocksize_0]}/4
333   \item \varname{[left_window_end]} = \varname{[n]}/4 + \varname{[blocksize_0]}/4
334   \item \varname{[left_n]} = \varname{[blocksize_0]}/2
335  \end{enumerate}
336 else
337  \begin{enumerate}
338   \item \varname{[left_window_start]} = 0
339   \item \varname{[left_window_end]} = \varname{[window_center]}
340   \item \varname{[left_n]} = \varname{[n]}/2
341  \end{enumerate}
342
343 \item  if (\varname{[vorbis_mode_blockflag]} is set and \varname{[next_window_flag]} is not
344set) then
345  \begin{enumerate}
346   \item \varname{[right_window_start]} = \varname{[n]*3}/4 -
347\varname{[blocksize_0]}/4
348   \item \varname{[right_window_end]} = \varname{[n]*3}/4 +
349\varname{[blocksize_0]}/4
350   \item \varname{[right_n]} = \varname{[blocksize_0]}/2
351  \end{enumerate}
352 else
353  \begin{enumerate}
354   \item \varname{[right_window_start]} = \varname{[window_center]}
355   \item \varname{[right_window_end]} = \varname{[n]}
356   \item \varname{[right_n]} = \varname{[n]}/2
357  \end{enumerate}
358
359 \item  window from range 0 ... \varname{[left_window_start]}-1 inclusive is zero
360 \item  for \varname{[i]} in range \varname{[left_window_start]} ...
361\varname{[left_window_end]}-1, window(\varname{[i]}) = $\sin(\frac{\pi}{2} * \sin^2($ (\varname{[i]}-\varname{[left_window_start]}+0.5) / \varname{[left_n]} $* \frac{\pi}{2})$ )
362 \item  window from range \varname{[left_window_end]} ... \varname{[right_window_start]}-1
363inclusive is one\item  for \varname{[i]} in range \varname{[right_window_start]} ... \varname{[right_window_end]}-1, window(\varname{[i]}) = $\sin(\frac{\pi}{2} * \sin^2($ (\varname{[i]}-\varname{[right_window_start]}+0.5) / \varname{[right_n]} $ * \frac{\pi}{2} + \frac{\pi}{2})$ )
364\item  window from range \varname{[right_window_start]} ... \varname{[n]}-1 is
365zero
366\end{enumerate}
367
368An end-of-packet condition up to this point should be considered an
369error that discards this packet from the stream.  An end of packet
370condition past this point is to be considered a possible nominal
371occurrence.
372
373
374
375\subsubsection{floor curve decode}
376
377From this point on, we assume out decode context is using mode number
378\varname{[mode_number]} from configuration array
379\varname{[vorbis_mode_configurations]} and the map number
380\varname{[vorbis_mode_mapping]} (specified by the current mode) taken
381from the mapping configuration array
382\varname{[vorbis_mapping_configurations]}.
383
384Floor curves are decoded one-by-one in channel order.
385
386For each floor \varname{[i]} of \varname{[audio_channels]}
387 \begin{enumerate}
388  \item \varname{[submap_number]} = element \varname{[i]} of vector [vorbis_mapping_mux]
389  \item \varname{[floor_number]} = element \varname{[submap_number]} of vector
390[vorbis_submap_floor]
391  \item if the floor type of this
392floor (vector \varname{[vorbis_floor_types]} element
393\varname{[floor_number]}) is zero then decode the floor for
394channel \varname{[i]} according to the
395\xref{vorbis:spec:floor0-decode}
396  \item if the type of this floor
397is one then decode the floor for channel \varname{[i]} according
398to the \xref{vorbis:spec:floor1-decode}
399  \item save the needed decoded floor information for channel for later synthesis
400  \item if the decoded floor returned 'unused', set vector \varname{[no_residue]} element
401\varname{[i]} to true, else set vector \varname{[no_residue]} element \varname{[i]} to
402false
403 \end{enumerate}
404
405
406An end-of-packet condition during floor decode shall result in packet
407decode zeroing all channel output vectors and skipping to the
408add/overlap output stage.
409
410
411
412\subsubsection{nonzero vector propagate}
413
414A possible result of floor decode is that a specific vector is marked
415'unused' which indicates that that final output vector is all-zero
416values (and the floor is zero).  The residue for that vector is not
417coded in the stream, save for one complication.  If some vectors are
418used and some are not, channel coupling could result in mixing a
419zeroed and nonzeroed vector to produce two nonzeroed vectors.
420
421for each \varname{[i]} from 0 ... \varname{[vorbis_mapping_coupling_steps]}-1
422
423\begin{enumerate}
424 \item if either \varname{[no_residue]} entry for channel
425(\varname{[vorbis_mapping_magnitude]} element \varname{[i]})
426or channel
427(\varname{[vorbis_mapping_angle]} element \varname{[i]})
428are set to false, then both must be set to false.  Note that an 'unused'
429floor has no decoded floor information; it is important that this is
430remembered at floor curve synthesis time.
431\end{enumerate}
432
433
434
435
436\subsubsection{residue decode}
437
438Unlike floors, which are decoded in channel order, the residue vectors
439are decoded in submap order.
440
441for each submap \varname{[i]} in order from 0 ... \varname{[vorbis_mapping_submaps]}-1
442
443\begin{enumerate}
444 \item \varname{[ch]} = 0
445 \item for each channel \varname{[j]} in order from 0 ... \varname{[audio_channels]} - 1
446  \begin{enumerate}
447   \item if channel \varname{[j]} in submap \varname{[i]} (vector \varname{[vorbis_mapping_mux]} element \varname{[j]} is equal to \varname{[i]})
448    \begin{enumerate}
449     \item if vector \varname{[no_residue]} element \varname{[j]} is true
450      \begin{enumerate}
451       \item vector \varname{[do_not_decode_flag]} element \varname{[ch]} is set
452      \end{enumerate}
453     else
454      \begin{enumerate}
455       \item vector \varname{[do_not_decode_flag]} element \varname{[ch]} is unset
456      \end{enumerate}
457
458     \item increment \varname{[ch]}
459    \end{enumerate}
460
461  \end{enumerate}
462 \item \varname{[residue_number]} = vector \varname{[vorbis_mapping_submap_residue]} element \varname{[i]}
463 \item \varname{[residue_type]} = vector \varname{[vorbis_residue_types]} element \varname{[residue_number]}
464 \item decode \varname{[ch]} vectors using residue \varname{[residue_number]}, according to type \varname{[residue_type]}, also passing vector \varname{[do_not_decode_flag]} to indicate which vectors in the bundle should not be decoded. Correct per-vector decode length is \varname{[n]}/2.
465 \item \varname{[ch]} = 0
466 \item for each channel \varname{[j]} in order from 0 ... \varname{[audio_channels]}
467  \begin{enumerate}
468   \item if channel \varname{[j]} is in submap \varname{[i]} (vector \varname{[vorbis_mapping_mux]} element \varname{[j]} is equal to \varname{[i]})
469    \begin{enumerate}
470     \item residue vector for channel \varname{[j]} is set to decoded residue vector \varname{[ch]}
471     \item increment \varname{[ch]}
472    \end{enumerate}
473
474  \end{enumerate}
475
476\end{enumerate}
477
478
479
480\subsubsection{inverse coupling}
481
482for each \varname{[i]} from \varname{[vorbis_mapping_coupling_steps]}-1 descending to 0
483
484\begin{enumerate}
485 \item \varname{[magnitude_vector]} = the residue vector for channel
486(vector \varname{[vorbis_mapping_magnitude]} element \varname{[i]})
487 \item \varname{[angle_vector]} = the residue vector for channel (vector
488\varname{[vorbis_mapping_angle]} element \varname{[i]})
489 \item for each scalar value \varname{[M]} in vector \varname{[magnitude_vector]} and the corresponding scalar value \varname{[A]} in vector \varname{[angle_vector]}:
490  \begin{enumerate}
491   \item if (\varname{[M]} is greater than zero)
492    \begin{enumerate}
493     \item if (\varname{[A]} is greater than zero)
494      \begin{enumerate}
495       \item \varname{[new_M]} = \varname{[M]}
496       \item \varname{[new_A]} = \varname{[M]}-\varname{[A]}
497      \end{enumerate}
498     else
499      \begin{enumerate}
500       \item \varname{[new_A]} = \varname{[M]}
501       \item \varname{[new_M]} = \varname{[M]}+\varname{[A]}
502      \end{enumerate}
503
504    \end{enumerate}
505   else
506    \begin{enumerate}
507     \item if (\varname{[A]} is greater than zero)
508      \begin{enumerate}
509       \item \varname{[new_M]} = \varname{[M]}
510       \item \varname{[new_A]} = \varname{[M]}+\varname{[A]}
511      \end{enumerate}
512     else
513      \begin{enumerate}
514       \item \varname{[new_A]} = \varname{[M]}
515       \item \varname{[new_M]} = \varname{[M]}-\varname{[A]}
516      \end{enumerate}
517
518    \end{enumerate}
519
520   \item set scalar value \varname{[M]} in vector \varname{[magnitude_vector]} to \varname{[new_M]}
521   \item set scalar value \varname{[A]} in vector \varname{[angle_vector]} to \varname{[new_A]}
522  \end{enumerate}
523
524\end{enumerate}
525
526
527
528
529\subsubsection{dot product}
530
531For each channel, synthesize the floor curve from the decoded floor
532information, according to packet type. Note that the vector synthesis
533length for floor computation is \varname{[n]}/2.
534
535For each channel, multiply each element of the floor curve by each
536element of that channel's residue vector.  The result is the dot
537product of the floor and residue vectors for each channel; the produced
538vectors are the length \varname{[n]}/2 audio spectrum for each
539channel.
540
541% TODO/FIXME: The following two paragraphs have identical twins
542%   in section 1 (under "compute floor/residue dot product")
543One point is worth mentioning about this dot product; a common mistake
544in a fixed point implementation might be to assume that a 32 bit
545fixed-point representation for floor and residue and direct
546multiplication of the vectors is sufficient for acceptable spectral
547depth in all cases because it happens to mostly work with the current
548Xiph.Org reference encoder.
549
550However, floor vector values can span \~140dB (\~24 bits unsigned), and
551the audio spectrum vector should represent a minimum of 120dB (\~21
552bits with sign), even when output is to a 16 bit PCM device.  For the
553residue vector to represent full scale if the floor is nailed to
554$-140$dB, it must be able to span 0 to $+140$dB.  For the residue vector
555to reach full scale if the floor is nailed at 0dB, it must be able to
556represent $-140$dB to $+0$dB.  Thus, in order to handle full range
557dynamics, a residue vector may span $-140$dB to $+140$dB entirely within
558spec.  A 280dB range is approximately 48 bits with sign; thus the
559residue vector must be able to represent a 48 bit range and the dot
560product must be able to handle an effective 48 bit times 24 bit
561multiplication.  This range may be achieved using large (64 bit or
562larger) integers, or implementing a movable binary point
563representation.
564
565
566
567\subsubsection{inverse MDCT}
568
569Convert the audio spectrum vector of each channel back into time
570domain PCM audio via an inverse Modified Discrete Cosine Transform
571(MDCT).  A detailed description of the MDCT is available in \cite{Sporer/Brandenburg/Edler}.  The window
572function used for the MDCT is the function described earlier.
573
574
575
576\subsubsection{overlap_add}
577
578Windowed MDCT output is overlapped and added with the right hand data
579of the previous window such that the 3/4 point of the previous window
580is aligned with the 1/4 point of the current window (as illustrated in
581\xref{vorbis:spec:window}).  The overlapped portion
582produced from overlapping the previous and current frame data is
583finished data to be returned by the decoder.  This data spans from the
584center of the previous window to the center of the current window.  In
585the case of same-sized windows, the amount of data to return is
586one-half block consisting of and only of the overlapped portions. When
587overlapping a short and long window, much of the returned range does not
588actually overlap.  This does not damage transform orthogonality.  Pay
589attention however to returning the correct data range; the amount of
590data to be returned is:
591
592\begin{programlisting}
593window_blocksize(previous_window)/4+window_blocksize(current_window)/4
594\end{programlisting}
595
596from the center (element windowsize/2) of the previous window to the
597center (element windowsize/2-1, inclusive) of the current window.
598
599Data is not returned from the first frame; it must be used to 'prime'
600the decode engine.  The encoder accounts for this priming when
601calculating PCM offsets; after the first frame, the proper PCM output
602offset is '0' (as no data has been returned yet).
603
604
605
606\subsubsection{output channel order}
607
608Vorbis I specifies only a channel mapping type 0.  In mapping type 0,
609channel mapping is implicitly defined as follows for standard audio
610applications. As of revision 16781 (20100113), the specification adds
611defined channel locations for 6.1 and 7.1 surround.  Ordering/location
612for greater-than-eight channels remains 'left to the implementation'.
613
614These channel orderings refer to order within the encoded stream.  It
615is naturally possible for a decoder to produce output with channels in
616any order. Any such decoder should explicitly document channel
617reordering behavior.
618
619\begin{description} %[style=nextline]
620 \item[one channel]
621	the stream is monophonic
622
623\item[two channels]
624	the stream is stereo.  channel order: left, right
625
626\item[three channels]
627	the stream is a 1d-surround encoding.  channel order: left,
628center, right
629
630\item[four channels]
631	the stream is quadraphonic surround.  channel order: front left,
632front right, rear left, rear right
633
634\item[five channels]
635	the stream is five-channel surround.  channel order: front left,
636center, front right, rear left, rear right
637
638\item[six channels]
639	the stream is 5.1 surround.  channel order: front left, center, 
640front right, rear left, rear right, LFE
641
642\item[seven channels]
643        the stream is 6.1 surround.  channel order: front left, center, 
644front right, side left, side right, rear center, LFE
645
646\item[eight channels]
647        the stream is 7.1 surround.  channel order: front left, center, 
648front right, side left, side right, rear left, rear right, 
649LFE
650
651\item[greater than eight channels]
652	channel use and order is defined by the application
653
654\end{description}
655
656Applications using Vorbis for dedicated purposes may define channel
657mapping as seen fit.  Future channel mappings (such as three and four
658channel \href{http://www.ambisonic.net/}{Ambisonics}) will
659make use of channel mappings other than mapping 0.
660
661
662