[xiph-cvs] cvs commit: vorbis/doc vorbis-spec-ref.html
Monty
xiphmont at xiph.org
Thu Jul 18 21:54:25 PDT 2002
xiphmont 02/07/18 21:54:25
Modified: doc vorbis-spec-ref.html
Log:
Plow changes into CVS
Revision Changes Path
1.2 +166 -9 vorbis/doc/vorbis-spec-ref.html
Index: vorbis-spec-ref.html
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/vorbis-spec-ref.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- vorbis-spec-ref.html 2002/07/19 03:06:26 1.1
+++ vorbis-spec-ref.html 2002/07/19 04:54:24 1.2
@@ -14,7 +14,10 @@
bit-by-bit decode specification of Vorbis I. This document assumes a
high-level understanding of the Vorbis decode process, which is
provided in the document <a href="vorbis-spec-intro.html">Ogg Vorbis I
-format specification: introduction and description</a>.
+format specification: introduction and description</a>. <a
+href="vorbis-spec-bitpack.html">Ogg Vorbis I format specification:
+bitpacking convention</a> covers reading and writing bit fields from
+and to bitstream packets.<p>
<h1>Header decode and decode setup</h1>
@@ -25,18 +28,48 @@
packet renders the stream undecodable. End-of-packet decoding the
comment header is a non-fatal error condition.<p>
+<h2>Common header decode</h2>
+
+Each header packet begins with the same header fields
+
+<pre>
+ 1) [packet_type] : 8 bit value
+ 2) 0x76, 0x6f, 0x72, 0x62, 0x69, 0x73: the characters 'v','o','r','b','i','s' as six octets
+</pre>
+
+Decode continues according to packet type; the identification header
+is type 1, the comment header type 3 and the setup header type 5
+(these types are all odd as a packet with a leading single bit of '0'
+is an audio packet). The packets must occur in the order of
+identification, comment, setup.
+
<h2>Identification Header</h2>
The identification header is a short header of only a few fields used
to declare the stream definitively as Vorbis, and provide a externally
relevant pieces of information about the audio stream. The
identification header is coded as follows:<p>
-
-<ol>
-<li>
+<pre>
+ 1) [vorbis_version] = read 32 bits as unsigned integer
+ 2) [audio_channels] = read 8 bit integer as unsigned
+ 3) [audio_sample_rate] = read 32 bits as unsigned integer
+ 4) [bitrate_maximum] = read 32 bits as unsigned integer
+ 5) [bitrate_nominal] = read 32 bits as unsigned integer
+ 6) [bitrate_lower] = read 32 bits as unsigned integer
+ 7) [blocksize_0] = 2 exponent (read 4 bits as unsigned integer)
+ 8) [blocksize_1] = 2 exponent (read 4 bits as unsigned integer)
+ 9) [framing_flag] = read one bit
+</pre>
+
+<tt>[vorbis_version]</tt> is to read '0' in order to be compatable
+with this docuement. Both <tt>[audio_channels]</tt> and
+<tt>[audio_rate]</tt> must read greater than zero. Allowed final
+blocksize values are 64, 128, 256, 512, 1024, 2048, 4096 and 8192 in
+Vorbis I. <tt>[blocksize_0]</tt> must be less than or equal to
+<tt>[blocksize_1]</tt>. The framing bit must be nonzero. Failure to
+meet any of these conditions renders a stream undecodable.<p>
-
<h2>Comment Header</h2>
Comment header decode and data specification is covered in <a
@@ -45,9 +78,136 @@
<h2>Setup Header</h2>
+Vorbis codec setup is configurable to an extreme degree:<p>
+
+<img src="components.png"><p>
+
+The setup header contains the bulk of the codec setup information
+needed for decode. The setup header contains, in order, the lists of
+codebook configurations, time-domain transform configurations
+(placeholders in Vorbis I), floor configurations, residue
+configurations, channel mappping configurations and mode
+configurations. It finishes with a framing bit of '1'. Header decode
+proceeds in the following order:<p>
+
+<h3>codebooks</h3>
+
+<ol>
+<li><tt>[vorbis_codebook_count]</tt> = read eight bits as unsigned integer and add one
+<li>Decode <tt>[vorbis_codebook_count]</tt> codebooks in order as defined
+in <a href="vorbis-spec-codebook.html">the codebook specification
+document</a>. Save each configuration, in order, in an array of
+codebook configurations <tt>[vorbis_codebook_configurations]</tt>.
+</ol>
+
+<h3>time domain transforms</h3>
+
+These hooks are placeholders in Vorbis I. Nevertheless, the
+configuration placeholder values must be read to maintain bitstream
+sync.<p>
+
+<ol>
+<li><tt>[vorbis_time_count]</tt> = read 6 bits as unsigned integer and add one
+<li>read <tt>[vorbis_time_count]</tt> 16 bit values; each value should be zero. If any othe values is nonzero, this is an error condition and the stream is undecodable.
+</ol>
+
+<h3>floors</h3>
+
+Vorbis uses two floor type; header decode is handed to the decode
+abstraction of the appropriate type.
+
+<ol>
+<li><tt>[vorbis_floor_count]</tt> = read 6 bits as unsigned integer and add one
+<li>For each of <tt>[vorbis_floor_count]</tt> floor numbers:
+ <ol>
+ <li>read the floor type; vector <tt>[vorbis_floor_types]</tt> element <tt>[i]</tt> = read 16 bits as unsigned integer
+ <li>If the floor type is zero, decode the floor configuration as defined in the floor type 0 specification document; save this configuration in slot <tt>[i]</tt> of the floor configuration array <tt>[vorbis_floor_configurations]</tt>.
+ <li>If the floor type is one, decode the floor configuration as defined in the floor type 1 specification document; save this configuration in slot <tt>[i]</tt> of the floor configuration array <tt>[vorbis_floor_configurations]</tt>.
+ <li>If the the floor type is greater than one, this stream is undecodable; ERROR CONDITION
+ </ol>
+</ol>
-<h3>mapping 0</h3>
+<h3>residues</h3>
+Vorbis uses three residue types; header decode of each type is identical.
+
+<ol>
+<li><tt>[vorbis_residue_count]</tt> = read 6 bits as unsigned integer and add one
+<li>For each of <tt>[vorbis_residue_count]</tt> residue numbers:
+ <ol>
+ <li>read the residue type; vector <tt>[vorbis_residue_types]</tt> element <tt>[i]</tt> = read 16 bits as unsigned integer
+ <li>If the residue type is zero, one or two, decode the residue configuration as defined in the residue specification document; save this configuration in slot <tt>[i]</tt> of the residue configuration array <tt>[vorbis_residue_configurations]</tt>.
+ <li>If the the residue type is greater than two, this stream is undecodable; ERROR CONDITION
+ </ol>
+</ol>
+
+<h3>mappings</h3>
+
+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.<p>
+
+<ol>
+<li><tt>[vorbis_mapping_count]</tt> = read 6 bits as unsigned integer and add one<p>
+<li>For each <tt>[i]</tt> of <tt>[vorbis_mapping_count]</tt> mapping numbers:<p>
+ <ol>
+ <li>read the mapping type: 16 bits as unsigned integer. There's no reason to save the mapping type in Vorbis I.<p>
+ <li>If the mapping type is nonzero, the stream is undecodable<p>
+ <li>If the mapping type is zero:<p>
+ <ol> <li>read 1 bit as a boolean flag<p>
+ <ol><li>if set, <tt>[vorbis_mapping_submaps]</tt> = read 4 bits as unsigned integer and add one<p>
+ <li>if unset, <tt>[vorbis_mapping_submaps]</tt> = 1<p>
+ </ol>
+ <li>read 1 bit as a boolean flag; if set, square polar channel mapping is in use:<p>
+ <ol><li><tt>[vorbis_mapping_coupling_steps]</tt>= read 8 bits as unsigned int and add one<p>
+ <li>for <tt>[j]</tt> each of <tt>[vorbis_mapping_coupling_steps]</tt> steps:<p>
+ <ol>
+ <li>vector <tt>[vorbis_mapping_magnitude]</tt> element <tt>[j]</tt>= read ilog([audio_channels]) bits as unsiged integer<p>
+ <li>vector <tt>[vorbis_mapping_angle]</tt> element <tt>[j]</tt>= read ilog([audio_channels]) bits as unsiged integer<p>
+ <li>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 any of angle channel equals magnitud channel, magnitude channel is greater than <tt>[audio_channels]</tt>-1, or angle channel is greater than <tt>[audio_channels]</tt>-1, the stream is undecodable.<p>
+ </ol>
+ </ol>
+ <li>read 2 bits (reserved field); if the value is nonzero, the stream is undecodable<p>
+ <li>if <tt>[vorbis_mapping_submaps]</tt> is greater than one, we read channel multiplex settings. For each <tt>[j]</tt> of <tt>[audio_channels]</tt> channels:<p>
+ <ol><li>vector <tt>[vorbis_mapping_mux]</tt> element <tt>[j]</tt> = read 4 bits as unsigned integer<p>
+ <li>if the value is greater than the highest numbered submap, this in an error condition rendering the stream undecodable<p>
+ </ol>
+ <li>for each submap <tt>[j]</tt> of <tt>[vorbis_mapping_submaps]</tt> submaps, read the floor and residue numbers for use in decoding that submap:
+ <ol><li>read and discard 8 bits (the unused time configuration placeholder)<p>
+ <li>read 8 bits as unsigned integer for the floor number; save in vector <tt>[vorbis_mapping_submap_floor]</tt> element <tt>[j]</tt><p>
+ <li>verify the floor number is not greater than the highest number floor configured for the bitstream. If it is, the bitstream is undecodable<p>
+ <li>read 8 bits as unsigned integer for the residue number; save in vector <tt>[vorbis_mapping_submapping_residue]</tt> element <tt>[j]</tt><p>
+ <li>verify the residue number is not greater than the highest number residue configured for the bitstream. If it is, the bitstream is undecodable<p>
+ </ol>
+
+
+ <li>save this mapping configuration in slot <tt>[i]</tt> of the mapping configuration array <tt>[vorbis_mapping_configurations]</tt>.
+
+ </ol>
+ </ol>
+</ol>
+
+<h3>modes</h3>
+
+<ol>
+<li><tt>[vorbis_mode_count]</tt> = read 6 bits as unsigned integer and add one
+<li>For each of <tt>[vorbis_mode_count]</tt> mode numbers:
+ <ol>
+ <li><tt>[vorbis_mode_blockflag]</tt> = read 1 bit<p>
+ <li><tt>[vorbis_mode_windowtype]</tt> = read 16 bits as unsigned integer<p>
+ <li><tt>[vorbis_mode_transformtype]</tt> = read 16 bits as unsigned integer<p>
+ <li><tt>[vorbis_mode_mapping]</tt> = read 8 bits as unsigned integer<p>
+ <li>verify ranges; zero is the only legal value in Vorbis I for <tt>[vorbis_mode_windowtype]</tt> and <tt>[vorbis_mode_transformtype]</tt>. <tt>[vorbis_mode_mapping]</tt> must not be greater than the highest number mapping in use. Any illegal values render the stream undecodable.<p>
+ </ol>
+ <li>read 1 bit as a framing flag. If unset, a framing error occurred and the stream is not decodable.
+
+</ol><p>
+
+After reading mode descriptions, setup header decode is complete.<p>
+
+<h1>Packet decode</h1>
+
+
<h4>channel order</h4>
In mapping type 0, channel mapping is implicitly defined as follows for standard audio applications:<p>
@@ -66,9 +226,6 @@
mapping as seen fit. Future channel mappings (such as three and four
channel Ambisonics) will make
use of channel mappings other than mapping 0.
-
-<h1>Packet decode</h1>
-
<p><p><p>--- >8 ----
List archives: http://www.xiph.org/archives/
Ogg project homepage: http://www.xiph.org/ogg/
To unsubscribe from this list, send a message to 'cvs-request at xiph.org'
containing only the word 'unsubscribe' in the body. No subject is needed.
Unsubscribe messages sent to the list will be ignored/filtered.
More information about the commits
mailing list