-<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
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<head>
+
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
+<title>Ogg Vorbis Documentation</title>
+
+<style type="text/css">
+body {
+ margin: 0 18px 0 18px;
+ padding-bottom: 30px;
+ font-family: Verdana, Arial, Helvetica, sans-serif;
+ color: #333333;
+ font-size: .8em;
+}
+
+a {
+ color: #3366cc;
+}
+
+img {
+ border: 0;
+}
+
+#xiphlogo {
+ margin: 30px 0 16px 0;
+}
+
+#content p {
+ line-height: 1.4;
+}
+
+h1, h1 a, h2, h2 a, h3, h3 a {
+ font-weight: bold;
+ color: #ff9900;
+ margin: 1.3em 0 8px 0;
+}
+
+h1 {
+ font-size: 1.3em;
+}
+
+h2 {
+ font-size: 1.2em;
+}
+
+h3 {
+ font-size: 1.1em;
+}
+
+li {
+ line-height: 1.4;
+}
+
+#copyright {
+ margin-top: 30px;
+ line-height: 1.5em;
+ text-align: center;
+ font-size: .8em;
+ color: #888888;
+ clear: both;
+}
+</style>
+
+</head>
+
+<body>
+
+<div id="xiphlogo">
+ <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.Org"/></a>
+</div>
+
+<h1>Ogg Vorbis I format specification: comment field and header specification</h1>
+
+<h1 id="overview">Overview</h1>
+
+<p>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.</p>
+
+<p>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:
+more than a short paragraph. The essentials, in other words, whatever
+they turn out to be, eg:</p>
-<blockquote>
+<blockquote><p>
"Honest Bob and the Factory-to-Dealer-Incentives, _I'm Still Around_,
-opening for Moxy Fruvous, 1997"
-</blockquote>
+opening for Moxy Früvous, 1997"
+</p></blockquote>
+
+<h1 id="commentencoding">Comment encoding</h1>
-<h2>Structure</h2>
+<h2 id="structure">Structure</h2>
-The comment header logically is a list of eight-bit-clean vectors; the
+<p>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>
+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".</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:
+<p>The comment header is decoded as follows:</p>
<pre>
-comment[0]="ARTIST=me";
-comment[1]="TITLE=the sound of vorbis";
+ 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.
</pre>
-<h2>Content vector format</h2>
+<h2 id="vectorformat">Content vector format</h2>
+
+<p>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:</p>
+
+<pre>
+comment[0]="ARTIST=me";
+comment[1]="TITLE=the sound of Vorbis";
+</pre>
<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.
+(a-z).</li>
+<li>The field name is immediately followed by ASCII 0x3D ('=');
+this equals sign is used to terminate the field name.</li>
+<li>0x3D is followed by the 8 bit clean UTF-8 encoded value of the
+field contents to the end of the field.</li>
</ul>
-<h3>Field names</h3>
+<h3 id="fieldnames">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
+<p>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.
+in this list.</p>
+
<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>TITLE</dt>
+<dd>Track/Work name</dd>
+
+<dt>VERSION</dt>
+<dd>The version field may be used to differentiate multiple
+versions of the same track title in a single collection.
+(e.g. remix info)</dd>
+
+<dt>ALBUM</dt>
+<dd>The collection name to which this track belongs</dd>
+
+<dt>TRACKNUMBER</dt>
+<dd>The track number of this piece if part of a specific larger collection or album</dd>
-<dt>ALBUM<dd>The collection name to which this track belongs
+<dt>ARTIST</dt>
+<dd>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.</dd>
-<dt>TRACKNUMBER<dd>The track number of this piece if part of a specific larger collection or album
+<dt>PERFORMER</dt>
+<dd>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.</dd>
-<dt>ARTIST<dd>Track performer
+<dt>COPYRIGHT</dt>
+<dd>Copyright attribution, e.g., '2001 Nobody's Band' or '1999 Jack Moffitt'</dd>
-<dt>ORGANIZATION<dd>Name of the organization producing the track (i.e.
-the 'record label')
+<dt>LICENSE</dt>
+<dd>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.</dd>
-<dt>DESCRIPTION<dd>A short text description of the contents
+<dt>ORGANIZATION</dt>
+<dd>Name of the organization producing the track (i.e.
+the 'record label')</dd>
-<dt>GENRE<dd>A short text indication of music genre
+<dt>DESCRIPTION</dt>
+<dd>A short text description of the contents</dd>
-<dt>DATE<dd>Date the track was recorded
+<dt>GENRE</dt>
+<dd>A short text indication of music genre</dd>
-<dt>LOCATION<dd>Location where track was recorded
+<dt>DATE</dt>
+<dd>Date the track was recorded</dd>
-<dt>COPYRIGHT<dd>Copyright information
+<dt>LOCATION</dt>
+<dd>Location where track was recorded</dd>
-<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.
+<dt>CONTACT</dt>
+<dd>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.</dd>
+
+<dt>ISRC</dt>
+<dd>ISRC number for the track; see <a href="https://isrc.ifpi.org/">the
+ISRC intro page</a> for more information on ISRC numbers.</dd>
</dl>
-<h3>Implications</h3>
+<h3 id="implications">Implications</h3>
+
<ul>
-<li>
-Field names should not be 'internationalized'; this is a
+<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 world that doesn't speak English. Field <emph>contents</emph>,
+however, use the UTF-8 character encoding to allow easy representation
+of any language.</li>
+<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
+we also have the length of the field contents.</li>
+<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.
+context at this point. Abuse will be discouraged.</li>
+<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
+common namespace. We will generally collect the more useful tags
+here to help with standardization.</li>
+<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>
-
+</pre></li>
</ul>
-<h2>Encoding</h2>
+<h2 id="encoding">Encoding</h2>
-The comment header comprises the entirety of the second bitstream
-header packet. Unlike the first bitstream header packet, it is not
+<p>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
+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>
+effectively empty.</p>
-The comment header is encoded as follows (as per Ogg's standard
+<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):
+bitstream octet first):</p>
<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...)...
+<li>Vendor string length (32 bit unsigned quantity specifying number of octets)</li>
+<li>Vendor string ([vendor string length] octets coded from beginning of string
+to end of string, not null terminated)</li>
+<li>Number of comment fields (32 bit unsigned quantity specifying number of fields)</li>
+<li>Comment field 0 length (if [Number of comment fields]>0; 32 bit unsigned
+quantity specifying number of octets)</li>
+<li>Comment field 0 ([Comment field 0 length] octets coded from beginning of
+string to end of string, not null terminated)</li>
+<li>Comment field 1 length (if [Number of comment fields]>1...)...</li>
</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()
+<p>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()</p>
-<hr>
-<a href="http://www.xiph.org/">
-<img src="white-xifish.png" align=left border=0>
-</a>
-<font size=-2 color=#505050>
+<div id="copyright">
+ The Xiph Fish Logo is a
+ trademark (™) of Xiph.Org.<br/>
-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>
+ These pages © 1994 - 2005 Xiph.Org. All rights reserved.
+</div>
</body>
-
+</html>
projects / platform / upstream / libvorbis.git / blobdiff