1% -*- mode: latex; TeX-master: "Vorbis_I_spec"; -*-
2%!TEX root = Vorbis_I_spec.tex
3% $Id$
4\section{Floor type 0 setup and decode} \label{vorbis:spec:floor0}
5
6\subsection{Overview}
7
8Vorbis floor type zero uses Line Spectral Pair (LSP, also alternately
9known as Line Spectral Frequency or LSF) representation to encode a
10smooth spectral envelope curve as the frequency response of the LSP
11filter.  This representation is equivalent to a traditional all-pole
12infinite impulse response filter as would be used in linear predictive
13coding; LSP representation may be converted to LPC representation and
14vice-versa.
15
16
17
18\subsection{Floor 0 format}
19
20Floor zero configuration consists of six integer fields and a list of
21VQ codebooks for use in coding/decoding the LSP filter coefficient
22values used by each frame.
23
24\subsubsection{header decode}
25
26Configuration information for instances of floor zero decodes from the
27codec setup header (third packet).  configuration decode proceeds as
28follows:
29
30\begin{Verbatim}[commandchars=\\\{\}]
31  1) [floor0_order] = read an unsigned integer of 8 bits
32  2) [floor0_rate] = read an unsigned integer of 16 bits
33  3) [floor0_bark_map_size] = read an unsigned integer of 16 bits
34  4) [floor0_amplitude_bits] = read an unsigned integer of six bits
35  5) [floor0_amplitude_offset] = read an unsigned integer of eight bits
36  6) [floor0_number_of_books] = read an unsigned integer of four bits and add 1
37  7) array [floor0_book_list] = read a list of [floor0_number_of_books] unsigned integers of eight bits each;
38\end{Verbatim}
39
40An end-of-packet condition during any of these bitstream reads renders
41this stream undecodable.  In addition, any element of the array
42\varname{[floor0_book_list]} that is greater than the maximum codebook
43number for this bitstream is an error condition that also renders the
44stream undecodable.
45
46
47
48\subsubsection{packet decode} \label{vorbis:spec:floor0-decode}
49
50Extracting a floor0 curve from an audio packet consists of first
51decoding the curve amplitude and \varname{[floor0_order]} LSP
52coefficient values from the bitstream, and then computing the floor
53curve, which is defined as the frequency response of the decoded LSP
54filter.
55
56Packet decode proceeds as follows:
57\begin{Verbatim}[commandchars=\\\{\}]
58  1) [amplitude] = read an unsigned integer of [floor0_amplitude_bits] bits
59  2) if ( [amplitude] is greater than zero ) \{
60       3) [coefficients] is an empty, zero length vector
61       4) [booknumber] = read an unsigned integer of \link{vorbis:spec:ilog}{ilog}( [floor0_number_of_books] ) bits
62       5) if ( [booknumber] is greater than the highest number decode codebook ) then packet is undecodable
63       6) [last] = zero;
64       7) vector [temp_vector] = read vector from bitstream using codebook number [floor0_book_list] element [booknumber] in VQ context.
65       8) add the scalar value [last] to each scalar in vector [temp_vector]
66       9) [last] = the value of the last scalar in vector [temp_vector]
67      10) concatenate [temp_vector] onto the end of the [coefficients] vector
68      11) if (length of vector [coefficients] is less than [floor0_order], continue at step 6
69
70     \}
71
72 12) done.
73
74\end{Verbatim}
75
76Take note of the following properties of decode:
77\begin{itemize}
78 \item An \varname{[amplitude]} value of zero must result in a return code that indicates this channel is unused in this frame (the output of the channel will be all-zeroes in synthesis).  Several later stages of decode don't occur for an unused channel.
79 \item An end-of-packet condition during decode should be considered a
80nominal occruence; if end-of-packet is reached during any read
81operation above, floor decode is to return 'unused' status as if the
82\varname{[amplitude]} value had read zero at the beginning of decode.
83
84 \item The book number used for decode
85can, in fact, be stored in the bitstream in \link{vorbis:spec:ilog}{ilog}( \varname{[floor0_number_of_books]} -
861 ) bits.  Nevertheless, the above specification is correct and values
87greater than the maximum possible book value are reserved.
88
89 \item The number of scalars read into the vector \varname{[coefficients]}
90may be greater than \varname{[floor0_order]}, the number actually
91required for curve computation.  For example, if the VQ codebook used
92for the floor currently being decoded has a
93\varname{[codebook_dimensions]} value of three and
94\varname{[floor0_order]} is ten, the only way to fill all the needed
95scalars in \varname{[coefficients]} is to to read a total of twelve
96scalars as four vectors of three scalars each.  This is not an error
97condition, and care must be taken not to allow a buffer overflow in
98decode. The extra values are not used and may be ignored or discarded.
99\end{itemize}
100
101
102
103
104\subsubsection{curve computation} \label{vorbis:spec:floor0-synth}
105
106Given an \varname{[amplitude]} integer and \varname{[coefficients]}
107vector from packet decode as well as the [floor0_order],
108[floor0_rate], [floor0_bark_map_size], [floor0_amplitude_bits] and
109[floor0_amplitude_offset] values from floor setup, and an output
110vector size \varname{[n]} specified by the decode process, we compute a
111floor output vector.
112
113If the value \varname{[amplitude]} is zero, the return value is a
114length \varname{[n]} vector with all-zero scalars.  Otherwise, begin by
115assuming the following definitions for the given vector to be
116synthesized:
117
118   \begin{displaymath}
119     \mathrm{map}_i = \left\{
120       \begin{array}{ll}
121          \min (
122            \mathtt{floor0\_bark\_map\_size} - 1,
123            foobar
124          ) & \textrm{for } i \in [0,n-1] \\
125          -1 & \textrm{for } i = n
126        \end{array}
127      \right.
128    \end{displaymath}
129
130    where
131
132    \begin{displaymath}
133    foobar =
134      \left\lfloor
135        \mathrm{bark}\left(\frac{\mathtt{floor0\_rate} \cdot i}{2n}\right) \cdot \frac{\mathtt{floor0\_bark\_map\_size}} {\mathrm{bark}(.5 \cdot \mathtt{floor0\_rate})}
136      \right\rfloor
137    \end{displaymath}
138
139    and
140
141    \begin{displaymath}
142      \mathrm{bark}(x) = 13.1 \arctan (.00074x) + 2.24 \arctan (.0000000185x^2 + .0001x)
143    \end{displaymath}
144
145The above is used to synthesize the LSP curve on a Bark-scale frequency
146axis, then map the result to a linear-scale frequency axis.
147Similarly, the below calculation synthesizes the output LSP curve \varname{[output]} on a log
148(dB) amplitude scale, mapping it to linear amplitude in the last step:
149
150\begin{enumerate}
151 \item  \varname{[i]} = 0
152 \item  \varname{[$\omega$]} = $\pi$ * map element \varname{[i]} / \varname{[floor0_bark_map_size]}
153 \item if ( \varname{[floor0_order]} is odd ) {
154  \begin{enumerate}
155   \item calculate \varname{[p]} and \varname{[q]} according to:
156           \begin{eqnarray*}
157             p & = & (1 - \cos^2\omega)\prod_{j=0}^{\frac{\mathtt{floor0\_order}-3}{2}} 4 (\cos([\mathtt{coefficients}]_{2j+1}) - \cos \omega)^2 \\
158             q & = & \frac{1}{4} \prod_{j=0}^{\frac{\mathtt{floor0\_order}-1}{2}} 4 (\cos([\mathtt{coefficients}]_{2j}) - \cos \omega)^2
159           \end{eqnarray*}
160
161  \end{enumerate}
162  } else \varname{[floor0_order]} is even {
163  \begin{enumerate}
164   \item calculate \varname{[p]} and \varname{[q]} according to:
165           \begin{eqnarray*}
166             p & = & \frac{(1 - \cos^2\omega)}{2} \prod_{j=0}^{\frac{\mathtt{floor0\_order}-2}{2}} 4 (\cos([\mathtt{coefficients}]_{2j+1}) - \cos \omega)^2 \\
167             q & = & \frac{(1 + \cos^2\omega)}{2} \prod_{j=0}^{\frac{\mathtt{floor0\_order}-2}{2}} 4 (\cos([\mathtt{coefficients}]_{2j}) - \cos \omega)^2
168           \end{eqnarray*}
169
170  \end{enumerate}
171  }
172
173 \item calculate \varname{[linear_floor_value]} according to:
174         \begin{displaymath}
175           \exp \left( .11512925 \left(\frac{\mathtt{amplitude} \cdot \mathtt{floor0\_amplitute\_offset}}{(2^{\mathtt{floor0\_amplitude\_bits}}-1)\sqrt{p+q}}
176                  - \mathtt{floor0\_amplitude\_offset} \right) \right)
177         \end{displaymath}
178
179 \item \varname{[iteration_condition]} = map element \varname{[i]}
180 \item \varname{[output]} element \varname{[i]} = \varname{[linear_floor_value]}
181 \item increment \varname{[i]}
182 \item if ( map element \varname{[i]} is equal to \varname{[iteration_condition]} ) continue at step 5
183 \item if ( \varname{[i]} is less than \varname{[n]} ) continue at step 2
184 \item done
185\end{enumerate}
186
187
188
189
190
191
192
193