These hooks are placeholders in Vorbis I. Nevertheless, the
configuration placeholder values must be read to maintain bitstream
sync.
\begin{enumerate}
\item\varname{[vorbis\_time\_count]} = read 6 bits as unsigned integer and add one
\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.
\end{enumerate}
\paragraph{Floors}
Vorbis uses two floor types; header decode is handed to the decode
abstraction of the appropriate type.
\begin{enumerate}
\item\varname{[vorbis\_floor\_count]} = read 6 bits as unsigned integer and add one
\item For each \varname{[i]} of \varname{[vorbis\_floor\_count]} floor numbers:
\begin{enumerate}
\item read the floor type: vector \varname{[vorbis\_floor\_types]} element \varname{[i]} =
read 16 bits as unsigned integer
\item If the floor type is zero, decode the floor
configuration as defined in \xref{vorbis:spec:floor0}; save
this
configuration in slot \varname{[i]} of the floor configuration array \varname{[vorbis\_floor\_configurations]}.
\item If the floor type is one,
decode 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]}.
\item If the the floor type is greater than one, this stream is undecodable; ERROR CONDITION
\end{enumerate}
\end{enumerate}
\paragraph{Residues}
Vorbis uses three residue types; header decode of each type is identical.
\begin{enumerate}
\item\varname{[vorbis\_residue\_count]} = read 6 bits as unsigned integer and add one
\item For each of \varname{[vorbis\_residue\_count]} residue numbers:
\begin{enumerate}
\item read the residue type; vector \varname{[vorbis\_residue\_types]} element \varname{[i]} = read 16 bits as unsigned integer
\item If the residue type is zero,
one 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]}.
\item If the the residue type is greater than two, this stream is undecodable; ERROR CONDITION
\end{enumerate}
\end{enumerate}
\paragraph{Mappings}
Mappings are used to set up specific pipelines for encoding
multichannel audio with varying channel mapping applications. Vorbis I
uses a single mapping type (0), with implicit PCM channel mappings.
% FIXME/TODO: LaTeX cannot nest enumerate that deeply, so I have to use
% itemize at the innermost level. However, it would be much better to
% rewrite this pseudocode using listings or algoritmicx or some other
% package geared towards this.
\begin{enumerate}
\item\varname{[vorbis\_mapping\_count]} = read 6 bits as unsigned integer and add one
\item For each \varname{[i]} of \varname{[vorbis\_mapping\_count]} mapping numbers:
\begin{enumerate}
\item read the mapping type: 16 bits as unsigned integer. There's no reason to save the mapping type in Vorbis I.
\item If the mapping type is nonzero, the stream is undecodable
\item If the mapping type is zero:
\begin{enumerate}
\item read 1 bit as a boolean flag
\begin{enumerate}
\item if set, \varname{[vorbis\_mapping\_submaps]} = read 4 bits as unsigned integer and add one
\item if unset, \varname{[vorbis\_mapping\_submaps]} = 1
\end{enumerate}
\item read 1 bit as a boolean flag
\begin{enumerate}
\item if set, square polar channel mapping is in use:
\begin{itemize}
\item\varname{[vorbis\_mapping\_coupling\_steps]} = read 8 bits as unsigned integer and add one
\item for \varname{[j]} each of \varname{[vorbis\_mapping\_coupling\_steps]} steps:
\begin{itemize}
\item vector \varname{[vorbis\_mapping\_magnitude]} element \varname{[j]}= read \link{vorbis:spec:ilog}{ilog}(\varname{[audio\_channels]} - 1) bits as unsigned integer
\item vector \varname{[vorbis\_mapping\_angle]} element \varname{[j]}= read \link{vorbis:spec:ilog}{ilog}(\varname{[audio\_channels]} - 1) bits as unsigned integer
\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.
\end{itemize}
\end{itemize}
\item if unset, \varname{[vorbis\_mapping\_coupling\_steps]} = 0
\end{enumerate}
\item read 2 bits (reserved field); if the value is nonzero, the stream is undecodable
\item if \varname{[vorbis\_mapping\_submaps]} is greater than one, we read channel multiplex settings. For each \varname{[j]} of \varname{[audio\_channels]} channels:
\begin{enumerate}
\item vector \varname{[vorbis\_mapping\_mux]} element \varname{[j]} = read 4 bits as unsigned integer
\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
\end{enumerate}
\item for each submap \varname{[j]} of \varname{[vorbis\_mapping\_submaps]} submaps, read the floor and residue numbers for use in decoding that submap:
\begin{enumerate}
\item read and discard 8 bits (the unused time configuration placeholder)
\item read 8 bits as unsigned integer for the floor number; save in vector \varname{[vorbis\_mapping\_submap\_floor]} element \varname{[j]}
\item verify the floor number is not greater than the highest number floor configured for the bitstream. If it is, the bitstream is undecodable
\item read 8 bits as unsigned integer for the residue number; save in vector \varname{[vorbis\_mapping\_submap\_residue]} element \varname{[j]}
\item verify the residue number is not greater than the highest number residue configured for the bitstream. If it is, the bitstream is undecodable
\end{enumerate}
\item save this mapping configuration in slot \varname{[i]} of the mapping configuration array \varname{[vorbis\_mapping\_configurations]}.
\end{enumerate}
\end{enumerate}
\end{enumerate}
\paragraph{Modes}
\begin{enumerate}
\item\varname{[vorbis\_mode\_count]} = read 6 bits as unsigned integer and add one
\item For each of \varname{[vorbis\_mode\_count]} mode numbers:
\begin{enumerate}
\item\varname{[vorbis\_mode\_blockflag]} = read 1 bit
\item\varname{[vorbis\_mode\_windowtype]} = read 16 bits as unsigned integer
\item\varname{[vorbis\_mode\_transformtype]} = read 16 bits as unsigned integer
\item\varname{[vorbis\_mode\_mapping]} = read 8 bits as unsigned integer
\item verify ranges; zero is the only legal value in Vorbis I for
\varname{[vorbis\_mode\_windowtype]}
and \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.
\item save this mode configuration in slot \varname{[i]} of the mode configuration array
\varname{[vorbis\_mode\_configurations]}.
\end{enumerate}
\item read 1 bit as a framing flag. If unset, a framing error occurred and the stream is not
decodable.
\end{enumerate}
After reading mode descriptions, setup header decode is complete.
\subsection{Audio packet decode and synthesis}
Following the three header packets, all packets in a Vorbis I stream
are audio. The first step of audio packet decode is to read and
verify the packet type. \emph{A non-audio packet when audio is expected
indicates stream corruption or a non-compliant stream. The decoder
must ignore the packet and not attempt decoding it to audio}.
\subsubsection{packet type, mode and window decode}
\begin{enumerate}
\item read 1 bit \varname{[packet\_type]}; check that packet type is 0 (audio)
\item window from range \varname{[left\_window\_end]} ... \varname{[right\_window\_start]}-1
inclusive 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})$ )
\item window from range \varname{[right\_window\_start]} ... \varname{[n]}-1 is
zero
\end{enumerate}
An end-of-packet condition up to this point should be considered an
error that discards this packet from the stream. An end of packet
condition past this point is to be considered a possible nominal
occurrence.
\subsubsection{floor curve decode}
From this point on, we assume out decode context is using mode number
\varname{[mode\_number]} from configuration array
\varname{[vorbis\_mode\_configurations]} and the map number
\varname{[vorbis\_mode\_mapping]} (specified by the current mode) taken
from the mapping configuration array
\varname{[vorbis\_mapping\_configurations]}.
Floor curves are decoded one-by-one in channel order.
For each floor \varname{[i]} of \varname{[audio\_channels]}
\begin{enumerate}
\item\varname{[submap\_number]} = element \varname{[i]} of vector [vorbis\_mapping\_mux]
\item\varname{[floor\_number]} = element \varname{[submap\_number]} of vector
[vorbis\_submap\_floor]
\item if the floor type of this
floor (vector \varname{[vorbis\_floor\_types]} element
\varname{[floor\_number]}) is zero then decode the floor for
channel \varname{[i]} according to the
\xref{vorbis:spec:floor0-decode}
\item if the type of this floor
is one then decode the floor for channel \varname{[i]} according
to the \xref{vorbis:spec:floor1-decode}
\item save the needed decoded floor information for channel for later synthesis
\item if the decoded floor returned 'unused', set vector \varname{[no\_residue]} element
\varname{[i]} to true, else set vector \varname{[no\_residue]} element \varname{[i]} to
false
\end{enumerate}
An end-of-packet condition during floor decode shall result in packet
decode zeroing all channel output vectors and skipping to the
add/overlap output stage.
\subsubsection{nonzero vector propagate}
A possible result of floor decode is that a specific vector is marked
'unused' which indicates that that final output vector is all-zero
values (and the floor is zero). The residue for that vector is not
coded in the stream, save for one complication. If some vectors are
used and some are not, channel coupling could result in mixing a
zeroed and nonzeroed vector to produce two nonzeroed vectors.
for each \varname{[i]} from 0 ... \varname{[vorbis\_mapping\_coupling\_steps]}-1
\begin{enumerate}
\item if either \varname{[no\_residue]} entry for channel
(\varname{[vorbis\_mapping\_magnitude]} element \varname{[i]})
or channel
(\varname{[vorbis\_mapping\_angle]} element \varname{[i]})
are set to false, then both must be set to false. Note that an 'unused'
floor has no decoded floor information; it is important that this is
remembered at floor curve synthesis time.
\end{enumerate}
\subsubsection{residue decode}
Unlike floors, which are decoded in channel order, the residue vectors
are decoded in submap order.
for each submap \varname{[i]} in order from 0 ... \varname{[vorbis\_mapping\_submaps]}-1
\begin{enumerate}
\item\varname{[ch]} = 0
\item for each channel \varname{[j]} in order from 0 ... \varname{[audio\_channels]} - 1
\begin{enumerate}
\item if channel \varname{[j]} in submap \varname{[i]} (vector \varname{[vorbis\_mapping\_mux]} element \varname{[j]} is equal to \varname{[i]})
\begin{enumerate}
\item if vector \varname{[no\_residue]} element \varname{[j]} is true
\begin{enumerate}
\item vector \varname{[do\_not\_decode\_flag]} element \varname{[ch]} is set
\end{enumerate}
else
\begin{enumerate}
\item vector \varname{[do\_not\_decode\_flag]} element \varname{[ch]} is unset
\end{enumerate}
\item increment \varname{[ch]}
\end{enumerate}
\end{enumerate}
\item\varname{[residue\_number]} = vector \varname{[vorbis\_mapping\_submap\_residue]} element \varname{[i]}
\item\varname{[residue\_type]} = vector \varname{[vorbis\_residue\_types]} element \varname{[residue\_number]}
\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.
\item\varname{[ch]} = 0
\item for each channel \varname{[j]} in order from 0 ... \varname{[audio\_channels]}
\begin{enumerate}
\item if channel \varname{[j]} is in submap \varname{[i]} (vector \varname{[vorbis\_mapping\_mux]} element \varname{[j]} is equal to \varname{[i]})
\begin{enumerate}
\item residue vector for channel \varname{[j]} is set to decoded residue vector \varname{[ch]}
\item increment \varname{[ch]}
\end{enumerate}
\end{enumerate}
\end{enumerate}
\subsubsection{inverse coupling}
for each \varname{[i]} from \varname{[vorbis\_mapping\_coupling\_steps]}-1 descending to 0
\begin{enumerate}
\item\varname{[magnitude\_vector]} = the residue vector for channel
(vector \varname{[vorbis\_mapping\_magnitude]} element \varname{[i]})
\item\varname{[angle\_vector]} = the residue vector for channel (vector
\varname{[vorbis\_mapping\_angle]} element \varname{[i]})
\item for each scalar value \varname{[M]} in vector \varname{[magnitude\_vector]} and the corresponding scalar value \varname{[A]} in vector \varname{[angle\_vector]}:
