diff options
Diffstat (limited to 'vorbis/doc/v-comment.html')
| -rw-r--r-- | vorbis/doc/v-comment.html | 285 |
1 files changed, 0 insertions, 285 deletions
diff --git a/vorbis/doc/v-comment.html b/vorbis/doc/v-comment.html deleted file mode 100644 index aad5e88..0000000 --- a/vorbis/doc/v-comment.html +++ /dev/null @@ -1,285 +0,0 @@ -<!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:</p> - -<blockquote><p> -"Honest Bob and the Factory-to-Dealer-Incentives, _I'm Still Around_, -opening for Moxy Früvous, 1997" -</p></blockquote> - -<h1 id="commentencoding">Comment encoding</h1> - -<h2 id="structure">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 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> -<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 id="fieldnames">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 id="implications">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 id="encoding">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> |