doc/xml/04-codec.xml

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