doc/xml/04-codec.xml

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