sv-dependency-builds: src/libvorbis-1.3.3/doc/v-comment.html comparison

comparison src/libvorbis-1.3.3/doc/v-comment.html @ 1:05aa0afa9217

Bring in flac, ogg, vorbis

author	Chris Cannam
date	Tue, 19 Mar 2013 17:37:49 +0000
parents
children

comparison

equal deleted inserted replaced

-:c7265573341e
+:05aa0afa9217
+<!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>

Mercurial > hg > sv-dependency-builds

comparison src/libvorbis-1.3.3/doc/v-comment.html @ 1:05aa0afa9217