doc/v-comment.html - platform/external/libvorbis - Git at Google

 <!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>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:</p>

 <blockquote><p>
 "Honest Bob and the Factory-to-Dealer-Incentives, _I'm Still Around_,
 opening for Moxy Fr&uuml;vous, 1997"
 </p></blockquote>

 <h1>Comment encoding</h1>

 <h2>Structure</h2>

 <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
 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>

 <p>The comment header is decoded as follows:</p>

 <pre>
   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>

 <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>
 <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>

 <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.</p>

 <dl>

 <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>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>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>COPYRIGHT</dt>
 <dd>Copyright attribution, e.g., '2001 Nobody's Band' or '1999 Jack Moffitt'</dd>

 <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>ORGANIZATION</dt>
 <dd>Name of the organization producing the track (i.e.
 the 'record label')</dd>

 <dt>DESCRIPTION</dt>
 <dd>A short text description of the contents</dd>

 <dt>GENRE</dt>
 <dd>A short text indication of music genre</dd>

 <dt>DATE</dt>
 <dd>Date the track was recorded</dd>

 <dt>LOCATION</dt>
 <dd>Location where track was recorded</dd>

 <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="http://www.ifpi.org/isrc/">the
 ISRC intro page</a> for more information on ISRC numbers.</dd>

 </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 <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>
 <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>
 <li>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.</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></li>
 </ul>

 <h2>Encoding</h2>

 <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
 optional; it must be present in the bitstream even if it is
 effectively empty.</p>

 <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):</p>

 <ol>
 <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>

 <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>

 <div id="copyright">
   The Xiph Fish Logo is a
   trademark (&trade;) of Xiph.Org.<br/>

   These pages &copy; 1994 - 2005 Xiph.Org. All rights reserved.
 </div>

 </body>
 </html>
	<!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>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:</p>

	<blockquote><p>
	"Honest Bob and the Factory-to-Dealer-Incentives, _I'm Still Around_,
	opening for Moxy Früvous, 1997"
	</p></blockquote>

	<h1>Comment encoding</h1>

	<h2>Structure</h2>

	<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
	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>

	<p>The comment header is decoded as follows:</p>

	<pre>
	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>

	<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>
	<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>

	<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.</p>

	<dl>

	<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>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>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>COPYRIGHT</dt>
	<dd>Copyright attribution, e.g., '2001 Nobody's Band' or '1999 Jack Moffitt'</dd>

	<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>ORGANIZATION</dt>
	<dd>Name of the organization producing the track (i.e.
	the 'record label')</dd>

	<dt>DESCRIPTION</dt>
	<dd>A short text description of the contents</dd>

	<dt>GENRE</dt>
	<dd>A short text indication of music genre</dd>

	<dt>DATE</dt>
	<dd>Date the track was recorded</dd>

	<dt>LOCATION</dt>
	<dd>Location where track was recorded</dd>

	<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="http://www.ifpi.org/isrc/">the
	ISRC intro page</a> for more information on ISRC numbers.</dd>

	</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 <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>
	<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>
	<li>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.</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></li>
	</ul>

	<h2>Encoding</h2>

	<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
	optional; it must be present in the bitstream even if it is
	effectively empty.</p>

	<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):</p>

	<ol>
	<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>

	<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>

	<div id="copyright">
	The Xiph Fish Logo is a
	trademark (™) of Xiph.Org.<br/>

	These pages © 1994 - 2005 Xiph.Org. All rights reserved.
	</div>

	</body>
	</html>