gosu 0.7.15 → 0.7.16

data/dependencies/libvorbis/doc/xml/05-comment.xml

@@ -0,0 +1,284 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+<!ENTITY % isolat1 SYSTEM "http://www.oasis-open.org/docbook/xml/4.2/ent/iso-lat1.ent">
+%isolat1;
+]>
+
+<section id="vorbis-spec-comment">
+<sectioninfo>
+ <releaseinfo>
+ $Id: 05-comment.xml 11703 2006-07-17 16:33:17Z giles $
+</releaseinfo>
+</sectioninfo>
+<title>comment field and header specification</title>
+
+
+<section><title>Overview</title>
+
+<para>The Vorbis text comment header is the second (of three) header
+packets that begin a Vorbis bitstream. It is meant for short text
+comments, not arbitrary metadata; arbitrary metadata belongs in a
+separate logical bitstream (usually an XML stream type) that provides
+greater structure and machine parseability.</para>
+
+<para>The comment field is meant to be used much like someone jotting a
+quick note on the bottom of a CDR. It should be a little information to
+remember the disc by and explain it to others; a short, to-the-point
+text note that need not only be a couple words, but isn't going to be
+more than a short paragraph.  The essentials, in other words, whatever
+they turn out to be, eg:
+
+<blockquote>
+<simpara>Honest Bob and the Factory-to-Dealer-Incentives, <citetitle>I'm Still
+Around</citetitle>, opening for Moxy Fr&uuml;vous, 1997.</simpara>
+</blockquote>
+</para>
+
+</section>
+
+<section><title>Comment encoding</title>
+
+<section><title>Structure</title>
+
+<para>
+The comment header is logically a list of eight-bit-clean vectors; the
+number of vectors is bounded to 2^32-1 and the length of each vector
+is limited to 2^32-1 bytes. The vector length is encoded; the vector
+contents themselves are not null terminated. In addition to the vector
+list, there is a single vector for vendor name (also 8 bit clean,
+length encoded in 32 bits). For example, the 1.0 release of libvorbis 
+set the vendor string to "Xiph.Org libVorbis I 20020717".</para>
+
+<para>The comment header is decoded as follows:
+
+<programlisting>
+  1) [vendor_length] = read an unsigned integer of 32 bits
+  2) [vendor_string] = read a UTF-8 vector as [vendor_length] octets
+  3) [user_comment_list_length] = read an unsigned integer of 32 bits
+  4) iterate [user_comment_list_length] times {
+       5) [length] = read an unsigned integer of 32 bits
+       6) this iteration's user comment = read a UTF-8 vector as [length] octets
+     }
+  7) [framing_bit] = read a single bit as boolean
+  8) if ( [framing_bit] unset or end-of-packet ) then ERROR
+  9) done.
+</programlisting>
+</para>
+
+</section>
+
+<section><title>Content vector format</title>
+
+<para>
+The comment vectors are structured similarly to a UNIX environment variable.
+That is, comment fields consist of a field name and a corresponding value and
+look like:</para>
+
+<blockquote><programlisting>
+comment[0]="ARTIST=me"; 
+comment[1]="TITLE=the sound of Vorbis"; 
+</programlisting></blockquote>
+
+<para>
+The field name is case-insensitive and may consist of ASCII 0x20
+through 0x7D, 0x3D ('=') excluded. ASCII 0x41 through 0x5A inclusive
+(characters A-Z) is to be considered equivalent to ASCII 0x61 through 
+0x7A inclusive (characters a-z).
+</para>
+
+<para>
+The field name is immediately followed by ASCII 0x3D ('=');
+this equals sign is used to terminate the field name.
+</para>
+
+<para>
+0x3D is followed by 8 bit clean UTF-8 encoded value of the
+field contents to the end of the field.
+</para>
+
+<section><title>Field names</title>
+
+<para>Below is a proposed, minimal list of standard field names with a
+description of intended use.  No single or group of field names is
+mandatory; a comment header may contain one, all or none of the names
+in this list.</para>
+
+<variablelist>
+<varlistentry>
+<term>TITLE</term>
+<listitem>
+<simpara>Track/Work name</simpara>
+</listitem>
+</varlistentry>
+<varlistentry>
+ <term>VERSION</term>
+<listitem>
+ <simpara>The version field may be used to
+differentiate multiple
+versions of the same track title in a single collection. (e.g. remix
+info)
+</simpara></listitem>
+</varlistentry>
+
+<varlistentry><term>ALBUM</term><listitem><simpara>The collection name to which this track belongs
+</simpara></listitem>
+</varlistentry>
+
+<varlistentry><term>TRACKNUMBER</term>
+<listitem><simpara>The track number of this piece if part of a specific larger collection or album
+</simpara></listitem>
+</varlistentry>
+
+<varlistentry><term>ARTIST</term>
+<listitem><simpara>The artist generally considered responsible for the work. In popular music this is usually the performing band or singer. For classical music it would be the composer. For an audio book it would be the author of the original text.
+</simpara></listitem>
+</varlistentry>
+
+<varlistentry><term>PERFORMER</term>
+<listitem><simpara>The artist(s) who performed the work. In classical music this would be the conductor, orchestra, soloists. In an audio book it would be the actor who did the reading. In popular music this is typically the same as the ARTIST and is omitted.
+</simpara></listitem>
+</varlistentry>
+
+<varlistentry><term>COPYRIGHT</term>
+<listitem><simpara>Copyright attribution, e.g., '2001 Nobody's Band' or '1999 Jack Moffitt'
+</simpara></listitem>
+</varlistentry>
+
+<varlistentry><term>LICENSE</term>
+<listitem><simpara>License information, eg, 'All Rights Reserved', 'Any
+Use Permitted', a URL to a license such as a Creative Commons license
+("www.creativecommons.org/blahblah/license.html") or the EFF Open
+Audio License ('distributed under the terms of the Open Audio
+License. see http://www.eff.org/IP/Open_licenses/eff_oal.html for
+details'), etc.
+</simpara></listitem>
+</varlistentry>
+
+<varlistentry><term>ORGANIZATION</term>
+<listitem><simpara>Name of the organization producing the track (i.e.
+the 'record label')
+</simpara></listitem>
+</varlistentry>
+
+<varlistentry><term>DESCRIPTION</term>
+<listitem><simpara>A short text description of the contents
+</simpara></listitem>
+</varlistentry>
+
+<varlistentry><term>GENRE</term>
+<listitem><simpara>A short text indication of music genre
+</simpara></listitem>
+</varlistentry>
+
+<varlistentry><term>DATE</term>
+<listitem><simpara>Date the track was recorded
+</simpara></listitem>
+</varlistentry>
+
+<varlistentry><term>LOCATION</term>
+<listitem><simpara>Location where track was recorded
+</simpara></listitem>
+</varlistentry>
+
+<varlistentry><term>CONTACT</term>
+<listitem><simpara>Contact information for the creators or distributors of the track. This could be a URL, an email address, the physical address of the producing label.
+</simpara></listitem>
+</varlistentry>
+
+<varlistentry><term>ISRC</term>
+<listitem><simpara>International Standard Recording Code for the
+track; see <ulink
+url="http://www.ifpi.org/isrc/">the ISRC
+intro page</ulink> for more information on ISRC numbers.
+</simpara></listitem>
+</varlistentry>
+
+</variablelist>
+
+</section>
+
+<section><title>Implications</title>
+
+<para>Field names should not be 'internationalized'; this is a
+concession to simplicity not an attempt to exclude the majority of
+the world that doesn't speak English. Field <emphasis>contents</emphasis>,
+however, use the UTF-8 character encoding to allow easy representation 
+of any language.</para>
+
+<para>We have the length of the entirety of the field and restrictions on
+the field name so that the field name is bounded in a known way. Thus
+we also have the length of the field contents.</para>
+
+<para>Individual 'vendors' may use non-standard field names within
+reason. The proper use of comment fields should be clear through
+context at this point.  Abuse will be discouraged.</para>
+
+<para>There is no vendor-specific prefix to 'nonstandard' field names.
+Vendors should make some effort to avoid arbitrarily polluting the
+common namespace. We will generally collect the more useful tags
+here to help with standardization.</para>
+
+<para>Field names are not required to be unique (occur once) within a
+comment header.  As an example, assume a track was recorded by three
+well know artists; the following is permissible, and encouraged:
+
+<blockquote><programlisting>
+ARTIST=Dizzy Gillespie 
+ARTIST=Sonny Rollins 
+ARTIST=Sonny Stitt 
+</programlisting></blockquote>
+
+</para>
+
+</section>
+
+</section>
+
+<section><title>Encoding</title> 
+
+<para>
+The comment header comprises the entirety of the second bitstream
+header packet.  Unlike the first bitstream header packet, it is not
+generally the only packet on the second page and may not be restricted
+to within the second bitstream page.  The length of the comment header
+packet is (practically) unbounded.  The comment header packet is not
+optional; it must be present in the bitstream even if it is
+effectively empty.</para>
+
+<para>
+The comment header is encoded as follows (as per Ogg's standard
+bitstream mapping which renders least-significant-bit of the word to be
+coded into the least significant available bit of the current
+bitstream octet first):
+
+<orderedlist>
+ <listitem><simpara>
+  Vendor string length (32 bit unsigned quantity specifying number of octets)
+ </simpara></listitem>
+ <listitem><simpara>
+  Vendor string ([vendor string length] octets coded from beginning of string to end of string, not null terminated)
+ </simpara></listitem>
+ <listitem><simpara>
+  Number of comment fields (32 bit unsigned quantity specifying number of fields)
+ </simpara></listitem>
+ <listitem><simpara>
+  Comment field 0 length (if [Number of comment fields]>0; 32 bit unsigned quantity specifying number of octets)
+ </simpara></listitem>
+ <listitem><simpara>
+  Comment field 0 ([Comment field 0 length] octets coded from beginning of string to end of string, not null terminated)
+ </simpara></listitem>
+ <listitem><simpara>
+  Comment field 1 length (if [Number of comment fields]>1...)...
+ </simpara></listitem>
+</orderedlist>
+</para>
+
+<para>
+This is actually somewhat easier to describe in code; implementation of the above can be found in <filename>vorbis/lib/info.c</filename>, <function>_vorbis_pack_comment()</function> and <function>_vorbis_unpack_comment()</function>.
+</para>
+
+</section>
+</section>
+
+</section>

data/dependencies/libvorbis/doc/xml/06-floor0.xml

@@ -0,0 +1,257 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+
+]>
+
+<section id="vorbis-spec-floor0">
+<sectioninfo>
+<releaseinfo>
+  $Id: 06-floor0.xml 10424 2005-11-23 08:44:18Z xiphmont $
+</releaseinfo>
+</sectioninfo>  
+<title>Floor type 0 setup and decode</title>
+
+
+<section>
+<title>Overview</title>
+
+<para>
+Vorbis floor type zero uses Line Spectral Pair (LSP, also alternately
+known as Line Spectral Frequency or LSF) representation to encode a
+smooth spectral envelope curve as the frequency response of the LSP
+filter.  This representation is equivalent to a traditional all-pole
+infinite impulse response filter as would be used in linear predictive
+coding; LSP representation may be converted to LPC representation and
+vice-versa.</para>
+
+</section>
+
+<section>
+<title>Floor 0 format</title>
+
+<para>
+Floor zero configuration consists of six integer fields and a list of
+VQ codebooks for use in coding/decoding the LSP filter coefficient
+values used by each frame. </para>
+
+<section><title>header decode</title>
+
+<para>
+Configuration information for instances of floor zero decodes from the
+codec setup header (third packet).  configuration decode proceeds as
+follows:</para>
+
+<screen>
+  1) [floor0_order] = read an unsigned integer of 8 bits
+  2) [floor0_rate] = read an unsigned integer of 16 bits
+  3) [floor0_bark_map_size] = read an unsigned integer of 16 bits
+  4) [floor0_amplitude_bits] = read an unsigned integer of six bits
+  5) [floor0_amplitude_offset] = read an unsigned integer of eight bits
+  6) [floor0_number_of_books] = read an unsigned integer of four bits and add 1
+  7) if any of [floor0_order], [floor0_rate], [floor0_bark_map_size], [floor0_amplitude_bits],
+     [floor0_amplitude_offset] or [floor0_number_of_books] are less than zero, the stream is not decodable
+  8) array [floor0_book_list] = read a list of [floor0_number_of_books] unsigned integers of eight bits each;
+</screen>
+
+<para>
+An end-of-packet condition during any of these bitstream reads renders
+this stream undecodable.  In addition, any element of the array
+<varname>[floor0_book_list]</varname> that is greater than the maximum codebook
+number for this bitstream is an error condition that also renders the
+stream undecodable.</para>
+
+</section>
+
+<section id="vorbis-spec-floor0-decode">
+<title>packet decode</title>
+
+<para>
+Extracting a floor0 curve from an audio packet consists of first
+decoding the curve amplitude and <varname>[floor0_order]</varname> LSP
+coefficient values from the bitstream, and then computing the floor
+curve, which is defined as the frequency response of the decoded LSP
+filter.</para>
+
+<para>
+Packet decode proceeds as follows:</para>
+<screen>
+  1) [amplitude] = read an unsigned integer of [floor0_amplitude_bits] bits
+  2) if ( [amplitude] is greater than zero ) {
+       3) [coefficients] is an empty, zero length vector
+       4) [booknumber] = read an unsigned integer of <link linkend="vorbis-spec-ilog">ilog</link>( [floor0_number_of_books] ) bits
+       5) if ( [booknumber] is greater than the highest number decode codebook ) then packet is undecodable
+       6) [last] = zero;
+       7) vector [temp_vector] = read vector from bitstream using codebook number [floor0_book_list] element [booknumber] in VQ context.
+       8) add the scalar value [last] to each scalar in vector [temp_vector]
+       9) [last] = the value of the last scalar in vector [temp_vector]
+      10) concatenate [temp_vector] onto the end of the [coefficients] vector
+      11) if (length of vector [coefficients] is less than [floor0_order], continue at step 6
+
+     }
+
+ 12) done.
+ 
+</screen>
+
+<para>
+Take note of the following properties of decode:
+<itemizedlist>
+ <listitem><simpara>An <varname>[amplitude]</varname> 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.</simpara></listitem>
+ <listitem><simpara>An end-of-packet condition during decode should be considered a
+nominal occruence; if end-of-packet is reached during any read
+operation above, floor decode is to return 'unused' status as if the
+<varname>[amplitude]</varname> value had read zero at the beginning of decode.</simpara></listitem>
+
+ <listitem><simpara>The book number used for decode
+can, in fact, be stored in the bitstream in <link linkend="vorbis-spec-ilog">ilog</link>( <varname>[floor0_number_of_books]</varname> -
+1 ) bits.  Nevertheless, the above specification is correct and values
+greater than the maximum possible book value are reserved.</simpara></listitem>
+
+ <listitem><simpara>The number of scalars read into the vector <varname>[coefficients]</varname>
+may be greater than <varname>[floor0_order]</varname>, the number actually
+required for curve computation.  For example, if the VQ codebook used
+for the floor currently being decoded has a
+<varname>[codebook_dimensions]</varname> value of three and
+<varname>[floor0_order]</varname> is ten, the only way to fill all the needed
+scalars in <varname>[coefficients]</varname> is to to read a total of twelve
+scalars as four vectors of three scalars each.  This is not an error
+condition, and care must be taken not to allow a buffer overflow in
+decode. The extra values are not used and may be ignored or discarded.</simpara></listitem>
+</itemizedlist>
+</para>
+
+</section>
+
+<section id="vorbis-spec-floor0-synth">
+<title>curve computation</title>
+
+<para>
+Given an <varname>[amplitude]</varname> integer and <varname>[coefficients]</varname>
+vector from packet decode as well as the [floor0_order],
+[floor0_rate], [floor0_bark_map_size], [floor0_amplitude_bits] and
+[floor0_amplitude_offset] values from floor setup, and an output
+vector size <varname>[n]</varname> specified by the decode process, we compute a
+floor output vector.</para>
+
+<para>
+If the value <varname>[amplitude]</varname> is zero, the return value is a
+length <varname>[n]</varname> vector with all-zero scalars.  Otherwise, begin by
+assuming the following definitions for the given vector to be
+synthesized:</para>
+
+<informalequation>
+ <mediaobject>
+  <textobject><phrase>[lsp map equation]</phrase></textobject>
+  <textobject role="tex"><phrase>
+   <![CDATA[
+   \begin{math}
+     \mathrm{map}_i = \left\{
+       \begin{array}{ll}
+          \min (  
+            \mathtt{floor0\_bark\_map\_size} - 1,
+            foobar
+          ) & \textrm{for } i \in [0,n-1] \\
+          -1 & \textrm{for } i = n
+        \end{array}
+      \right.
+    \end {math}
+    
+    where
+    
+    \begin{math}
+    foobar = 
+      \left\lfloor
+        \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})} 
+      \right\rfloor
+    \end{math}
+                  
+    and
+                
+    \begin{math}
+      \mathrm{bark}(x) = 13.1 \arctan (.00074x) + 2.24 \arctan (.0000000185x^2 + .0001x)
+    \end{math}
+    ]]>
+   </phrase></textobject>
+  <imageobject><imagedata  fileref="lspmap.png"/></imageobject>
+ </mediaobject>
+</informalequation>
+
+<para>
+The above is used to synthesize the LSP curve on a Bark-scale frequency
+axis, then map the result to a linear-scale frequency axis.
+Similarly, the below calculation synthesizes the output LSP curve <varname>[output]</varname> on a log
+(dB) amplitude scale, mapping it to linear amplitude in the last step:</para>
+
+<orderedlist>
+ <listitem><simpara> <varname>[i]</varname> = 0 </simpara></listitem>
+ <listitem><para>if ( <varname>[floor0_order]</varname> is odd ) {
+  <orderedlist>
+   <listitem><para>calculate <varname>[p]</varname> and <varname>[q]</varname> according to:
+        <informalequation>
+         <mediaobject>
+          <textobject><phrase>[equation for odd lsp]</phrase></textobject>
+	  <textobject role="tex"><phrase>
+	   <![CDATA[
+           \begin{eqnarray*}
+             p & = & (1 - \cos^2\omega)\prod_{j=0}^{(\mathtt{order}-3)/2} 4 (\cos c_{2j+1} - \cos \omega)^2 \\
+             q & = & \frac{1}{4} \prod_{j=0}^{(\mathtt{order}-1)/2} 4 (\cos c_{2j+1} - \cos \omega)^2
+           \end{eqnarray*}
+	   ]]>
+          </phrase></textobject>
+	  <imageobject><imagedata fileref="oddlsp.png"/></imageobject>
+	 </mediaobject>
+        </informalequation>
+   </para></listitem>
+  </orderedlist>
+  } else <varname>[floor0_order]</varname> is even {
+  <orderedlist>
+   <listitem><para>calculate <varname>[p]</varname> and <varname>[q]</varname> according to:
+        <informalequation>
+         <mediaobject>
+	  <textobject><phrase>[equation for even lsp]</phrase></textobject>
+	  <textobject role="tex"><phrase>
+	   <![CDATA[
+           \begin{eqnarray*}
+             p & = & \frac{(1 - \cos^2\omega)}{2} \prod_{j=0}^{(\mathtt{order}-2)/2} 4 (\cos c_{2j} - \cos \omega)^2 \\
+             q & = & \frac{(1 + \cos^2\omega)}{2} \prod_{j=0}^{(\mathtt{order}-2)/2} 4 (\cos c_{2j} - \cos \omega)^2
+           \end{eqnarray*}
+	   ]]>
+          </phrase></textobject>
+	  <imageobject><imagedata fileref="evenlsp.png"/></imageobject>
+	 </mediaobject>
+        </informalequation>
+   </para></listitem>
+  </orderedlist> 
+  }
+ </para></listitem>
+ <listitem><para>calculate <varname>[linear_floor_value]</varname> according to:
+     <informalequation>
+      <mediaobject>
+       <textobject><phrase>[expression for floorval]</phrase></textobject>
+       <textobject role="tex"><phrase>
+	 <![CDATA[
+         \begin{math}
+           \exp \left( .11512925 \left(\frac{\mathtt{amplitude} \cdot \mathtt{floor0\_amplitute\_offset}}{(2^{\mathtt{floor0\_amplitude\_bits}}-1)\sqrt{p+q}}
+                  - \mathtt{floor0\_amplitude\_offset} \right) \right)
+         \end{math}
+	 ]]>
+       </phrase></textobject>
+       <imageobject><imagedata fileref="floorval.png"/></imageobject>
+      </mediaobject>
+     </informalequation>
+ </para></listitem>
+ <listitem><simpara><varname>[iteration_condition]</varname> = map element <varname>[i]</varname></simpara></listitem>
+ <listitem><simpara><varname>[output]</varname> element <varname>[i]</varname> = <varname>[linear_floor_value]</varname></simpara></listitem>
+ <listitem><simpara>increment <varname>[i]</varname></simpara></listitem>
+ <listitem><simpara>if ( map element <varname>[i]</varname> is equal to <varname>[iteration_condition]</varname> ) continue at step 5</simpara></listitem>
+ <listitem><simpara>if ( <varname>[i]</varname> is less than <varname>[n]</varname> ) continue at step 2</simpara></listitem>
+ <listitem><simpara>done</simpara></listitem>
+</orderedlist>
+
+</section>
+
+</section>
+
+</section>
+