diff options
Diffstat (limited to 'doc/v-comment.html')
-rw-r--r-- | doc/v-comment.html | 570 |
1 files changed, 285 insertions, 285 deletions
diff --git a/doc/v-comment.html b/doc/v-comment.html index e654004e..a0390a0f 100644 --- a/doc/v-comment.html +++ b/doc/v-comment.html @@ -1,285 +1,285 @@ -<!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/site-content/online/isrc_intro.html">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>
+<!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> |