1 files changed, 194 insertions, 0 deletions
diff --git a/doc/vorbis/v-comment.html b/doc/vorbis/v-comment.html
new file mode 100755
index 0000000..4089d81
--- /dev/null
+++ b/doc/vorbis/v-comment.html
@@ -0,0 +1,194 @@
+<HTML><HEAD><TITLE>xiph.org: Ogg Vorbis documentation</TITLE>
+<BODY bgcolor="#ffffff" text="#202020" link="#006666" vlink="#000000">
+<nobr><img src="white-ogg.png"><img src="vorbisword2.png"></nobr><p>
+
+
+<h1><font color=#000070>
+Ogg Vorbis comment field specification
+</font></h1>
+
+<em>Last update to this document: January 19, 2001</em><p>
+
+The 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
+metadata stream (usually an XML stream type).<p>
+
+<h2>Comment use rationale</h2>
+
+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>
+"Honest Bob and the Factory-to-Dealer-Incentives, _I'm Still Around_,
+opening for Moxy Fruvous, 1997"
+</blockquote>
+
+<h2>Structure</h2>
+
+The comment header logically is 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
+is 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). Libvorbis currently sets the vendor string to "Xiphophorus
+libVorbis I 20010119".<p>
+
+The comment vectors are structured similarly to a UNIX environment.
+That is, comment fields consist of a field name and a field value and
+look like:
+
+<pre>
+comment[0]="ARTIST=me"; 
+comment[1]="TITLE=the sound of vorbis"; 
+</pre>
+
+<h2>Content vector format</h2>
+
+<ul>
+<li>A case-insensitive field name that may consist of ASCII 0x20 through
+0x7D, 0x3D ('=') excluded. ASCII 0x41 through 0x5A inclusive (A-Z) is
+to be considered equivalent to ASCII 0x61 through 0x7A inclusive
+(a-z).
+
+<li>The field name is immediately followed by ASCII 0x3D ('='); this
+equals sign is used to terminate the field name.
+
+<li>0x3D is followed by 8 bit clean UTF-8 field contents to the end of
+the field.
+</ul>
+
+<h3>Field names</h3>
+
+Below is a proposed, minimal list of standard filed 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.
+<dl>
+<dt>TITLE<dd>Track name
+
+<dt>VERSION<dd>The version field may be used to differentiate multiple
+version of the same track title in a single collection. (e.g. remix info)
+
+<dt>ALBUM<dd>The collection name to which this track belongs
+
+<dt>TRACKNUMBER<dd>The track number of this piece if part of a specific larger collection or album
+
+<dt>ARTIST<dd>Track performer
+
+<dt>ORGANIZATION<dd>Name of the organization producing the track (i.e.
+the 'record label')
+
+<dt>DESCRIPTION<dd>A short text description of the contents
+
+<dt>GENRE<dd>A short text indication of music genre
+
+<dt>DATE<dd>Date the track was recorded
+
+<dt>LOCATION<dd>Location where track was recorded
+
+<dt>COPYRIGHT<dd>Copyright information
+
+<dt>ISRC<dd>ISRC number for the track; see <a href="http://www.ifpi.org/online/isrc_intro.html">the ISRC intro page</a> for more information on ISRC numbers.
+
+</dl>
+
+<h3>Implications</h3>
+<ul>
+<li>
+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 *contents*, however,
+are represented in UTF-8 to allow easy representation of any language.
+<li>
+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.
+<li>
+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.
+<li>
+There is no vendor-specific prefix to 'nonstandard' field names.
+Vendors should make some effort to avoid arbitrarily polluting the
+common namespace.
+<li>
+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:
+<pre>
+              ARTIST=Dizzy Gillespie 
+              ARTIST=Sonny Rollins 
+              ARTIST=Sonny Stitt 
+</pre>
+
+</ul>
+
+<h2>Encoding</h2> 
+
+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.<p>
+
+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):
+
+<ol>
+<li>
+Vendor string length (32 bit unsigned quantity specifying number of octets)
+
+<li>
+Vendor string ([vendor string length] octets coded from beginning of string to end of string, not null terminated)
+
+<li>Number of comment fields (32 bit unsigned quantity specifying number of fields)
+
+<li>Comment field 0 length (if [Number of comment fields]>0; 32 bit unsigned quantity specifying number of octets)
+
+<li>
+Comment field 0 ([Comment field 0 length] octets coded from beginning of string to end of string, not null terminated)
+ 
+<li>Comment field 1 length (if [Number of comment fields]>1...)...
+</ol>
+
+This is actually somewhat easier to describe in code; implementation of the above can be found in vorbis/lib/info.c:_vorbis_pack_comment(),_vorbis_unpack_comment()
+
+<hr>
+<a href="http://www.xiph.org/">
+<img src="white-xifish.png" align=left border=0>
+</a>
+<font size=-2 color=#505050>
+
+Ogg is a <a href="http://www.xiph.org">Xiphophorus</a> effort to
+protect essential tenets of Internet multimedia from corporate
+hostage-taking; Open Source is the net's greatest tool to keep
+everyone honest. See <a href="http://www.xiph.org/about.html">About
+Xiphophorus</a> for details.
+<p>
+
+Ogg Vorbis is the first Ogg audio CODEC.  Anyone may
+freely use and distribute the Ogg and Vorbis specification,
+whether in a private, public or corporate capacity.  However,
+Xiphophorus and the Ogg project (xiph.org) reserve the right to set
+the Ogg/Vorbis specification and certify specification compliance.<p>
+
+Xiphophorus's Vorbis software CODEC implementation is distributed
+under the Lesser/Library GNU Public License.  This does not restrict
+third parties from distributing independent implementations of Vorbis
+software under other licenses.<p>
+
+OggSquish, Vorbis, Xiphophorus and their logos are trademarks (tm) of
+<a href="http://www.xiph.org/">Xiphophorus</a>.  These pages are
+copyright (C) 1994-2000 Xiphophorus. All rights reserved.<p>
+
+</body>
+