18e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 28e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels% -*- mode: latex; TeX-master: "Vorbis_I_spec"; -*- 38e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels%!TEX root = Vorbis_I_spec.tex 48e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels% $Id$ 58e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\section{Codec Setup and Packet Decode} \label{vorbis:spec:codec} 68e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 78e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\subsection{Overview} 88e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 98e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsThis document serves as the top-level reference document for the 108e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbit-by-bit decode specification of Vorbis I. This document assumes a 118e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelshigh-level understanding of the Vorbis decode process, which is 128e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsprovided in \xref{vorbis:spec:intro}. \xref{vorbis:spec:bitpacking} covers reading and writing bit fields from 138e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsand to bitstream packets. 148e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 158e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 168e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 178e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\subsection{Header decode and decode setup} 188e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 198e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsA Vorbis bitstream begins with three header packets. The header 208e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelspackets are, in order, the identification header, the comments header, 218e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsand the setup header. All are required for decode compliance. An 228e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsend-of-packet condition during decoding the first or third header 238e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelspacket renders the stream undecodable. End-of-packet decoding the 248e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelscomment header is a non-fatal error condition. 258e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 268e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\subsubsection{Common header decode} 278e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 288e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsEach header packet begins with the same header fields. 298e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 308e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 318e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\begin{Verbatim}[commandchars=\\\{\}] 328e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1) [packet_type] : 8 bit value 338e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2) 0x76, 0x6f, 0x72, 0x62, 0x69, 0x73: the characters 'v','o','r','b','i','s' as six octets 348e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\end{Verbatim} 358e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 368e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsDecode continues according to packet type; the identification header 378e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsis type 1, the comment header type 3 and the setup header type 5 388e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels(these types are all odd as a packet with a leading single bit of '0' 398e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsis an audio packet). The packets must occur in the order of 408e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsidentification, comment, setup. 418e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 428e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 438e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 448e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\subsubsection{Identification header} 458e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 468e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsThe identification header is a short header of only a few fields used 478e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsto declare the stream definitively as Vorbis, and provide a few externally 488e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsrelevant pieces of information about the audio stream. The 498e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsidentification header is coded as follows: 508e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 518e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\begin{Verbatim}[commandchars=\\\{\}] 528e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1) [vorbis_version] = read 32 bits as unsigned integer 538e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2) [audio_channels] = read 8 bit integer as unsigned 548e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 3) [audio_sample_rate] = read 32 bits as unsigned integer 558e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 4) [bitrate_maximum] = read 32 bits as signed integer 568e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 5) [bitrate_nominal] = read 32 bits as signed integer 578e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 6) [bitrate_minimum] = read 32 bits as signed integer 588e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 7) [blocksize_0] = 2 exponent (read 4 bits as unsigned integer) 598e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 8) [blocksize_1] = 2 exponent (read 4 bits as unsigned integer) 608e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 9) [framing_flag] = read one bit 618e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\end{Verbatim} 628e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 638e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\varname{[vorbis_version]} is to read '0' in order to be compatible 648e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelswith this document. Both \varname{[audio_channels]} and 658e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\varname{[audio_sample_rate]} must read greater than zero. Allowed final 668e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsblocksize values are 64, 128, 256, 512, 1024, 2048, 4096 and 8192 in 678e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsVorbis I. \varname{[blocksize_0]} must be less than or equal to 688e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\varname{[blocksize_1]}. The framing bit must be nonzero. Failure to 698e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsmeet any of these conditions renders a stream undecodable. 708e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 718e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsThe bitrate fields above are used only as hints. The nominal bitrate 728e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsfield especially may be considerably off in purely VBR streams. The 738e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsfields are meaningful only when greater than zero. 748e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 758e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\begin{itemize} 768e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item All three fields set to the same value implies a fixed rate, or tightly bounded, nearly fixed-rate bitstream 778e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item Only nominal set implies a VBR or ABR stream that averages the nominal bitrate 788e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item Maximum and or minimum set implies a VBR bitstream that obeys the bitrate limits 798e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item None set indicates the encoder does not care to speculate. 808e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\end{itemize} 818e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 828e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 838e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 848e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 858e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\subsubsection{Comment header} 868e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsComment header decode and data specification is covered in 878e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\xref{vorbis:spec:comment}. 888e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 898e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 908e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\subsubsection{Setup header} 918e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 928e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsVorbis codec setup is configurable to an extreme degree: 938e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 948e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\begin{center} 958e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\includegraphics[width=\textwidth]{components} 968e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\captionof{figure}{decoder pipeline configuration} 978e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\end{center} 988e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 998e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1008e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsThe setup header contains the bulk of the codec setup information 1018e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsneeded for decode. The setup header contains, in order, the lists of 1028e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelscodebook configurations, time-domain transform configurations 1038e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels(placeholders in Vorbis I), floor configurations, residue 1048e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsconfigurations, channel mapping configurations and mode 1058e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsconfigurations. It finishes with a framing bit of '1'. Header decode 1068e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsproceeds in the following order: 1078e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1088e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\paragraph{Codebooks} 1098e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1108e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\begin{enumerate} 1118e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\item \varname{[vorbis_codebook_count]} = read eight bits as unsigned integer and add one 1128e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\item Decode \varname{[vorbis_codebook_count]} codebooks in order as defined 1138e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsin \xref{vorbis:spec:codebook}. Save each configuration, in 1148e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsorder, in an array of 1158e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelscodebook configurations \varname{[vorbis_codebook_configurations]}. 1168e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\end{enumerate} 1178e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1188e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1198e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1208e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\paragraph{Time domain transforms} 1218e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1228e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsThese hooks are placeholders in Vorbis I. Nevertheless, the 1238e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsconfiguration placeholder values must be read to maintain bitstream 1248e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelssync. 1258e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1268e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\begin{enumerate} 1278e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\item \varname{[vorbis_time_count]} = read 6 bits as unsigned integer and add one 1288e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\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. 1298e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\end{enumerate} 1308e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1318e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1328e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1338e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\paragraph{Floors} 1348e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1358e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsVorbis uses two floor types; header decode is handed to the decode 1368e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsabstraction of the appropriate type. 1378e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1388e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\begin{enumerate} 1398e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[vorbis_floor_count]} = read 6 bits as unsigned integer and add one 1408e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item For each \varname{[i]} of \varname{[vorbis_floor_count]} floor numbers: 1418e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{enumerate} 1428e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item read the floor type: vector \varname{[vorbis_floor_types]} element \varname{[i]} = 1438e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsread 16 bits as unsigned integer 1448e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item If the floor type is zero, decode the floor 1458e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsconfiguration as defined in \xref{vorbis:spec:floor0}; save 1468e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsthis 1478e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsconfiguration in slot \varname{[i]} of the floor configuration array \varname{[vorbis_floor_configurations]}. 1488e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item If the floor type is one, 1498e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsdecode 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]}. 1508e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item If the the floor type is greater than one, this stream is undecodable; ERROR CONDITION 1518e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{enumerate} 1528e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1538e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\end{enumerate} 1548e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1558e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1568e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1578e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\paragraph{Residues} 1588e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1598e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsVorbis uses three residue types; header decode of each type is identical. 1608e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1618e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1628e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\begin{enumerate} 1638e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\item \varname{[vorbis_residue_count]} = read 6 bits as unsigned integer and add one 1648e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1658e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\item For each of \varname{[vorbis_residue_count]} residue numbers: 1668e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{enumerate} 1678e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item read the residue type; vector \varname{[vorbis_residue_types]} element \varname{[i]} = read 16 bits as unsigned integer 1688e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item If the residue type is zero, 1698e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsone 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]}. 1708e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item If the the residue type is greater than two, this stream is undecodable; ERROR CONDITION 1718e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{enumerate} 1728e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1738e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\end{enumerate} 1748e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1758e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1768e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1778e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\paragraph{Mappings} 1788e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1798e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsMappings are used to set up specific pipelines for encoding 1808e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsmultichannel audio with varying channel mapping applications. Vorbis I 1818e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsuses a single mapping type (0), with implicit PCM channel mappings. 1828e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1838e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels% FIXME/TODO: LaTeX cannot nest enumerate that deeply, so I have to use 1848e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels% itemize at the innermost level. However, it would be much better to 1858e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels% rewrite this pseudocode using listings or algoritmicx or some other 1868e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels% package geared towards this. 1878e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\begin{enumerate} 1888e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[vorbis_mapping_count]} = read 6 bits as unsigned integer and add one 1898e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item For each \varname{[i]} of \varname{[vorbis_mapping_count]} mapping numbers: 1908e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{enumerate} 1918e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item read the mapping type: 16 bits as unsigned integer. There's no reason to save the mapping type in Vorbis I. 1928e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item If the mapping type is nonzero, the stream is undecodable 1938e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item If the mapping type is zero: 1948e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{enumerate} 1958e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item read 1 bit as a boolean flag 1968e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{enumerate} 1978e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item if set, \varname{[vorbis_mapping_submaps]} = read 4 bits as unsigned integer and add one 1988e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item if unset, \varname{[vorbis_mapping_submaps]} = 1 1998e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{enumerate} 2008e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2018e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2028e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item read 1 bit as a boolean flag 2038e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{enumerate} 2048e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item if set, square polar channel mapping is in use: 2058e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{itemize} 2068e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[vorbis_mapping_coupling_steps]} = read 8 bits as unsigned integer and add one 2078e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item for \varname{[j]} each of \varname{[vorbis_mapping_coupling_steps]} steps: 2088e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{itemize} 2098e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item vector \varname{[vorbis_mapping_magnitude]} element \varname{[j]}= read \link{vorbis:spec:ilog}{ilog}(\varname{[audio_channels]} - 1) bits as unsigned integer 2108e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item vector \varname{[vorbis_mapping_angle]} element \varname{[j]}= read \link{vorbis:spec:ilog}{ilog}(\varname{[audio_channels]} - 1) bits as unsigned integer 2118e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \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. 2128e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{itemize} 2138e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2148e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2158e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{itemize} 2168e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2178e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2188e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item if unset, \varname{[vorbis_mapping_coupling_steps]} = 0 2198e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{enumerate} 2208e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2218e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2228e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item read 2 bits (reserved field); if the value is nonzero, the stream is undecodable 2238e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item if \varname{[vorbis_mapping_submaps]} is greater than one, we read channel multiplex settings. For each \varname{[j]} of \varname{[audio_channels]} channels: 2248e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{enumerate} 2258e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item vector \varname{[vorbis_mapping_mux]} element \varname{[j]} = read 4 bits as unsigned integer 2268e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \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 2278e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{enumerate} 2288e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2298e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item for each submap \varname{[j]} of \varname{[vorbis_mapping_submaps]} submaps, read the floor and residue numbers for use in decoding that submap: 2308e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{enumerate} 2318e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item read and discard 8 bits (the unused time configuration placeholder) 2328e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item read 8 bits as unsigned integer for the floor number; save in vector \varname{[vorbis_mapping_submap_floor]} element \varname{[j]} 2338e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item verify the floor number is not greater than the highest number floor configured for the bitstream. If it is, the bitstream is undecodable 2348e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item read 8 bits as unsigned integer for the residue number; save in vector \varname{[vorbis_mapping_submap_residue]} element \varname{[j]} 2358e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item verify the residue number is not greater than the highest number residue configured for the bitstream. If it is, the bitstream is undecodable 2368e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{enumerate} 2378e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2388e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item save this mapping configuration in slot \varname{[i]} of the mapping configuration array \varname{[vorbis_mapping_configurations]}. 2398e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{enumerate} 2408e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2418e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{enumerate} 2428e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2438e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\end{enumerate} 2448e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2458e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2468e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2478e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\paragraph{Modes} 2488e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2498e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\begin{enumerate} 2508e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[vorbis_mode_count]} = read 6 bits as unsigned integer and add one 2518e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item For each of \varname{[vorbis_mode_count]} mode numbers: 2528e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{enumerate} 2538e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[vorbis_mode_blockflag]} = read 1 bit 2548e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[vorbis_mode_windowtype]} = read 16 bits as unsigned integer 2558e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[vorbis_mode_transformtype]} = read 16 bits as unsigned integer 2568e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[vorbis_mode_mapping]} = read 8 bits as unsigned integer 2578e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item verify ranges; zero is the only legal value in Vorbis I for 2588e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\varname{[vorbis_mode_windowtype]} 2598e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsand \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. 2608e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item save this mode configuration in slot \varname{[i]} of the mode configuration array 2618e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\varname{[vorbis_mode_configurations]}. 2628e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{enumerate} 2638e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2648e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\item read 1 bit as a framing flag. If unset, a framing error occurred and the stream is not 2658e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsdecodable. 2668e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\end{enumerate} 2678e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2688e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsAfter reading mode descriptions, setup header decode is complete. 2698e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2708e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2718e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2728e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2738e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2748e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2758e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2768e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2778e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\subsection{Audio packet decode and synthesis} 2788e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2798e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsFollowing the three header packets, all packets in a Vorbis I stream 2808e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsare audio. The first step of audio packet decode is to read and 2818e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsverify the packet type. \emph{A non-audio packet when audio is expected 2828e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsindicates stream corruption or a non-compliant stream. The decoder 2838e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsmust ignore the packet and not attempt decoding it to audio}. 2848e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2858e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2868e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\subsubsection{packet type, mode and window decode} 2878e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2888e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\begin{enumerate} 2898e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item read 1 bit \varname{[packet_type]}; check that packet type is 0 (audio) 2908e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item read \link{vorbis:spec:ilog}{ilog}([vorbis_mode_count]-1) bits 2918e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\varname{[mode_number]} 2928e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item decode blocksize \varname{[n]} is equal to \varname{[blocksize_0]} if 2938e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\varname{[vorbis_mode_blockflag]} is 0, else \varname{[n]} is equal to \varname{[blocksize_1]}. 2948e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item perform window selection and setup; this window is used later by the inverse MDCT: 2958e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{enumerate} 2968e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item if this is a long window (the \varname{[vorbis_mode_blockflag]} flag of this mode is 2978e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsset): 2988e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{enumerate} 2998e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item read 1 bit for \varname{[previous_window_flag]} 3008e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item read 1 bit for \varname{[next_window_flag]} 3018e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item if \varname{[previous_window_flag]} is not set, the left half 3028e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels of the window will be a hybrid window for lapping with a 3038e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels short block. See \xref{vorbis:spec:window} for an illustration of overlapping 3048e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsdissimilar 3058e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels windows. Else, the left half window will have normal long 3068e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels shape. 3078e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item if \varname{[next_window_flag]} is not set, the right half of 3088e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels the window will be a hybrid window for lapping with a short 3098e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels block. See \xref{vorbis:spec:window} for an 3108e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsillustration of overlapping dissimilar 3118e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels windows. Else, the left right window will have normal long 3128e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels shape. 3138e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{enumerate} 3148e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 3158e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item if this is a short window, the window is always the same 3168e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels short-window shape. 3178e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{enumerate} 3188e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 3198e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\end{enumerate} 3208e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 3218e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsVorbis windows all use the slope function $y=\sin(\frac{\pi}{2} * \sin^2((x+0.5)/n * \pi))$, 3228e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelswhere $n$ is window size and $x$ ranges $0 \ldots n-1$, but dissimilar 3238e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelslapping requirements can affect overall shape. Window generation 3248e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsproceeds as follows: 3258e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 3268e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\begin{enumerate} 3278e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[window_center]} = \varname{[n]} / 2 3288e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item if (\varname{[vorbis_mode_blockflag]} is set and \varname{[previous_window_flag]} is 3298e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsnot set) then 3308e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{enumerate} 3318e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[left_window_start]} = \varname{[n]}/4 - 3328e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\varname{[blocksize_0]}/4 3338e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[left_window_end]} = \varname{[n]}/4 + \varname{[blocksize_0]}/4 3348e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[left_n]} = \varname{[blocksize_0]}/2 3358e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{enumerate} 3368e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels else 3378e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{enumerate} 3388e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[left_window_start]} = 0 3398e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[left_window_end]} = \varname{[window_center]} 3408e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[left_n]} = \varname{[n]}/2 3418e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{enumerate} 3428e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 3438e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item if (\varname{[vorbis_mode_blockflag]} is set and \varname{[next_window_flag]} is not 3448e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsset) then 3458e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{enumerate} 3468e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[right_window_start]} = \varname{[n]*3}/4 - 3478e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\varname{[blocksize_0]}/4 3488e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[right_window_end]} = \varname{[n]*3}/4 + 3498e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\varname{[blocksize_0]}/4 3508e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[right_n]} = \varname{[blocksize_0]}/2 3518e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{enumerate} 3528e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels else 3538e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{enumerate} 3548e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[right_window_start]} = \varname{[window_center]} 3558e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[right_window_end]} = \varname{[n]} 3568e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[right_n]} = \varname{[n]}/2 3578e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{enumerate} 3588e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 3598e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item window from range 0 ... \varname{[left_window_start]}-1 inclusive is zero 3608e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item for \varname{[i]} in range \varname{[left_window_start]} ... 3618e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\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})$ ) 3628e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item window from range \varname{[left_window_end]} ... \varname{[right_window_start]}-1 3638e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsinclusive 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})$ ) 3648e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\item window from range \varname{[right_window_start]} ... \varname{[n]}-1 is 3658e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelszero 3668e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\end{enumerate} 3678e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 3688e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsAn end-of-packet condition up to this point should be considered an 3698e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelserror that discards this packet from the stream. An end of packet 3708e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelscondition past this point is to be considered a possible nominal 3718e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsoccurrence. 3728e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 3738e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 3748e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 3758e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\subsubsection{floor curve decode} 3768e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 3778e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsFrom this point on, we assume out decode context is using mode number 3788e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\varname{[mode_number]} from configuration array 3798e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\varname{[vorbis_mode_configurations]} and the map number 3808e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\varname{[vorbis_mode_mapping]} (specified by the current mode) taken 3818e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsfrom the mapping configuration array 3828e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\varname{[vorbis_mapping_configurations]}. 3838e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 3848e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsFloor curves are decoded one-by-one in channel order. 3858e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 3868e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsFor each floor \varname{[i]} of \varname{[audio_channels]} 3878e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{enumerate} 3888e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[submap_number]} = element \varname{[i]} of vector [vorbis_mapping_mux] 3898e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[floor_number]} = element \varname{[submap_number]} of vector 3908e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels[vorbis_submap_floor] 3918e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item if the floor type of this 3928e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsfloor (vector \varname{[vorbis_floor_types]} element 3938e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\varname{[floor_number]}) is zero then decode the floor for 3948e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelschannel \varname{[i]} according to the 3958e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\xref{vorbis:spec:floor0-decode} 3968e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item if the type of this floor 3978e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsis one then decode the floor for channel \varname{[i]} according 3988e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsto the \xref{vorbis:spec:floor1-decode} 3998e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item save the needed decoded floor information for channel for later synthesis 4008e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item if the decoded floor returned 'unused', set vector \varname{[no_residue]} element 4018e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\varname{[i]} to true, else set vector \varname{[no_residue]} element \varname{[i]} to 4028e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsfalse 4038e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{enumerate} 4048e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 4058e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 4068e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsAn end-of-packet condition during floor decode shall result in packet 4078e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsdecode zeroing all channel output vectors and skipping to the 4088e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsadd/overlap output stage. 4098e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 4108e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 4118e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 4128e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\subsubsection{nonzero vector propagate} 4138e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 4148e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsA possible result of floor decode is that a specific vector is marked 4158e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels'unused' which indicates that that final output vector is all-zero 4168e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsvalues (and the floor is zero). The residue for that vector is not 4178e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelscoded in the stream, save for one complication. If some vectors are 4188e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsused and some are not, channel coupling could result in mixing a 4198e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelszeroed and nonzeroed vector to produce two nonzeroed vectors. 4208e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 4218e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsfor each \varname{[i]} from 0 ... \varname{[vorbis_mapping_coupling_steps]}-1 4228e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 4238e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\begin{enumerate} 4248e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item if either \varname{[no_residue]} entry for channel 4258e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels(\varname{[vorbis_mapping_magnitude]} element \varname{[i]}) 4268e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsor channel 4278e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels(\varname{[vorbis_mapping_angle]} element \varname{[i]}) 4288e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsare set to false, then both must be set to false. Note that an 'unused' 4298e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsfloor has no decoded floor information; it is important that this is 4308e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsremembered at floor curve synthesis time. 4318e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\end{enumerate} 4328e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 4338e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 4348e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 4358e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 4368e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\subsubsection{residue decode} 4378e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 4388e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsUnlike floors, which are decoded in channel order, the residue vectors 4398e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsare decoded in submap order. 4408e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 4418e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsfor each submap \varname{[i]} in order from 0 ... \varname{[vorbis_mapping_submaps]}-1 4428e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 4438e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\begin{enumerate} 4448e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[ch]} = 0 4458e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item for each channel \varname{[j]} in order from 0 ... \varname{[audio_channels]} - 1 4468e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{enumerate} 4478e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item if channel \varname{[j]} in submap \varname{[i]} (vector \varname{[vorbis_mapping_mux]} element \varname{[j]} is equal to \varname{[i]}) 4488e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{enumerate} 4498e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item if vector \varname{[no_residue]} element \varname{[j]} is true 4508e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{enumerate} 4518e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item vector \varname{[do_not_decode_flag]} element \varname{[ch]} is set 4528e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{enumerate} 4538e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels else 4548e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{enumerate} 4558e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item vector \varname{[do_not_decode_flag]} element \varname{[ch]} is unset 4568e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{enumerate} 4578e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 4588e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item increment \varname{[ch]} 4598e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{enumerate} 4608e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 4618e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{enumerate} 4628e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[residue_number]} = vector \varname{[vorbis_mapping_submap_residue]} element \varname{[i]} 4638e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[residue_type]} = vector \varname{[vorbis_residue_types]} element \varname{[residue_number]} 4648e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \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. 4658e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[ch]} = 0 4668e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item for each channel \varname{[j]} in order from 0 ... \varname{[audio_channels]} 4678e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{enumerate} 4688e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item if channel \varname{[j]} is in submap \varname{[i]} (vector \varname{[vorbis_mapping_mux]} element \varname{[j]} is equal to \varname{[i]}) 4698e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{enumerate} 4708e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item residue vector for channel \varname{[j]} is set to decoded residue vector \varname{[ch]} 4718e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item increment \varname{[ch]} 4728e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{enumerate} 4738e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 4748e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{enumerate} 4758e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 4768e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\end{enumerate} 4778e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 4788e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 4798e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 4808e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\subsubsection{inverse coupling} 4818e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 4828e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsfor each \varname{[i]} from \varname{[vorbis_mapping_coupling_steps]}-1 descending to 0 4838e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 4848e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\begin{enumerate} 4858e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[magnitude_vector]} = the residue vector for channel 4868e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels(vector \varname{[vorbis_mapping_magnitude]} element \varname{[i]}) 4878e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[angle_vector]} = the residue vector for channel (vector 4888e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\varname{[vorbis_mapping_angle]} element \varname{[i]}) 4898e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item for each scalar value \varname{[M]} in vector \varname{[magnitude_vector]} and the corresponding scalar value \varname{[A]} in vector \varname{[angle_vector]}: 4908e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{enumerate} 4918e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item if (\varname{[M]} is greater than zero) 4928e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{enumerate} 4938e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item if (\varname{[A]} is greater than zero) 4948e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{enumerate} 4958e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[new_M]} = \varname{[M]} 4968e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[new_A]} = \varname{[M]}-\varname{[A]} 4978e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{enumerate} 4988e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels else 4998e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{enumerate} 5008e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[new_A]} = \varname{[M]} 5018e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[new_M]} = \varname{[M]}+\varname{[A]} 5028e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{enumerate} 5038e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 5048e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{enumerate} 5058e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels else 5068e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{enumerate} 5078e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item if (\varname{[A]} is greater than zero) 5088e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{enumerate} 5098e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[new_M]} = \varname{[M]} 5108e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[new_A]} = \varname{[M]}+\varname{[A]} 5118e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{enumerate} 5128e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels else 5138e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \begin{enumerate} 5148e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[new_A]} = \varname{[M]} 5158e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item \varname{[new_M]} = \varname{[M]}-\varname{[A]} 5168e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{enumerate} 5178e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 5188e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{enumerate} 5198e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 5208e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item set scalar value \varname{[M]} in vector \varname{[magnitude_vector]} to \varname{[new_M]} 5218e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item set scalar value \varname{[A]} in vector \varname{[angle_vector]} to \varname{[new_A]} 5228e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \end{enumerate} 5238e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 5248e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\end{enumerate} 5258e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 5268e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 5278e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 5288e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 5298e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\subsubsection{dot product} 5308e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 5318e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsFor each channel, synthesize the floor curve from the decoded floor 5328e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsinformation, according to packet type. Note that the vector synthesis 5338e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelslength for floor computation is \varname{[n]}/2. 5348e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 5358e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsFor each channel, multiply each element of the floor curve by each 5368e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelselement of that channel's residue vector. The result is the dot 5378e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsproduct of the floor and residue vectors for each channel; the produced 5388e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsvectors are the length \varname{[n]}/2 audio spectrum for each 5398e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelschannel. 5408e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 5418e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels% TODO/FIXME: The following two paragraphs have identical twins 5428e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels% in section 1 (under "compute floor/residue dot product") 5438e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsOne point is worth mentioning about this dot product; a common mistake 5448e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsin a fixed point implementation might be to assume that a 32 bit 5458e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsfixed-point representation for floor and residue and direct 5468e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsmultiplication of the vectors is sufficient for acceptable spectral 5478e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsdepth in all cases because it happens to mostly work with the current 5488e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsXiph.Org reference encoder. 5498e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 5508e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsHowever, floor vector values can span \~140dB (\~24 bits unsigned), and 5518e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsthe audio spectrum vector should represent a minimum of 120dB (\~21 5528e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbits with sign), even when output is to a 16 bit PCM device. For the 5538e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsresidue vector to represent full scale if the floor is nailed to 5548e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels$-140$dB, it must be able to span 0 to $+140$dB. For the residue vector 5558e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsto reach full scale if the floor is nailed at 0dB, it must be able to 5568e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsrepresent $-140$dB to $+0$dB. Thus, in order to handle full range 5578e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsdynamics, a residue vector may span $-140$dB to $+140$dB entirely within 5588e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsspec. A 280dB range is approximately 48 bits with sign; thus the 5598e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsresidue vector must be able to represent a 48 bit range and the dot 5608e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsproduct must be able to handle an effective 48 bit times 24 bit 5618e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsmultiplication. This range may be achieved using large (64 bit or 5628e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelslarger) integers, or implementing a movable binary point 5638e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsrepresentation. 5648e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 5658e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 5668e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 5678e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\subsubsection{inverse MDCT} 5688e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 5698e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsConvert the audio spectrum vector of each channel back into time 5708e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsdomain PCM audio via an inverse Modified Discrete Cosine Transform 5718e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels(MDCT). A detailed description of the MDCT is available in \cite{Sporer/Brandenburg/Edler}. The window 5728e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsfunction used for the MDCT is the function described earlier. 5738e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 5748e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 5758e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 5768e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\subsubsection{overlap_add} 5778e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 5788e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsWindowed MDCT output is overlapped and added with the right hand data 5798e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsof the previous window such that the 3/4 point of the previous window 5808e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsis aligned with the 1/4 point of the current window (as illustrated in 5818e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\xref{vorbis:spec:window}). The overlapped portion 5828e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsproduced from overlapping the previous and current frame data is 5838e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsfinished data to be returned by the decoder. This data spans from the 5848e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelscenter of the previous window to the center of the current window. In 5858e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsthe case of same-sized windows, the amount of data to return is 5868e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsone-half block consisting of and only of the overlapped portions. When 5878e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsoverlapping a short and long window, much of the returned range does not 5888e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsactually overlap. This does not damage transform orthogonality. Pay 5898e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsattention however to returning the correct data range; the amount of 5908e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsdata to be returned is: 5918e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 5928e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\begin{programlisting} 5938e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelswindow_blocksize(previous_window)/4+window_blocksize(current_window)/4 5948e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\end{programlisting} 5958e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 5968e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsfrom the center (element windowsize/2) of the previous window to the 5978e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelscenter (element windowsize/2-1, inclusive) of the current window. 5988e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 5998e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsData is not returned from the first frame; it must be used to 'prime' 6008e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsthe decode engine. The encoder accounts for this priming when 6018e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelscalculating PCM offsets; after the first frame, the proper PCM output 6028e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsoffset is '0' (as no data has been returned yet). 6038e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 6048e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 6058e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 6068e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\subsubsection{output channel order} 6078e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 6088e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsVorbis I specifies only a channel mapping type 0. In mapping type 0, 6098e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelschannel mapping is implicitly defined as follows for standard audio 6108e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsapplications. As of revision 16781 (20100113), the specification adds 6118e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsdefined channel locations for 6.1 and 7.1 surround. Ordering/location 6128e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsfor greater-than-eight channels remains 'left to the implementation'. 6138e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 6148e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsThese channel orderings refer to order within the encoded stream. It 6158e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsis naturally possible for a decoder to produce output with channels in 6168e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsany order. Any such decoder should explicitly document channel 6178e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsreordering behavior. 6188e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 6198e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\begin{description} %[style=nextline] 6208e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels \item[one channel] 6218e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels the stream is monophonic 6228e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 6238e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\item[two channels] 6248e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels the stream is stereo. channel order: left, right 6258e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 6268e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\item[three channels] 6278e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels the stream is a 1d-surround encoding. channel order: left, 6288e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelscenter, right 6298e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 6308e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\item[four channels] 6318e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels the stream is quadraphonic surround. channel order: front left, 6328e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsfront right, rear left, rear right 6338e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 6348e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\item[five channels] 6358e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels the stream is five-channel surround. channel order: front left, 6368e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelscenter, front right, rear left, rear right 6378e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 6388e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\item[six channels] 6398e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels the stream is 5.1 surround. channel order: front left, center, 6408e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsfront right, rear left, rear right, LFE 6418e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 6428e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\item[seven channels] 6438e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels the stream is 6.1 surround. channel order: front left, center, 6448e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsfront right, side left, side right, rear center, LFE 6458e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 6468e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\item[eight channels] 6478e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels the stream is 7.1 surround. channel order: front left, center, 6488e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsfront right, side left, side right, rear left, rear right, 6498e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsLFE 6508e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 6518e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\item[greater than eight channels] 6528e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels channel use and order is defined by the application 6538e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 6548e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\end{description} 6558e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 6568e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsApplications using Vorbis for dedicated purposes may define channel 6578e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsmapping as seen fit. Future channel mappings (such as three and four 6588e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelschannel \href{http://www.ambisonic.net/}{Ambisonics}) will 6598e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsmake use of channel mappings other than mapping 0. 6608e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 6618e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 662