00001 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
00002 <html>
00003 <head>
00004
00005 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
00006 <title>Ogg Vorbis Documentation</title>
00007
00008 <style type="text/css">
00009 body {
00010 margin: 0 18px 0 18px;
00011 padding-bottom: 30px;
00012 font-family: Verdana, Arial, Helvetica, sans-serif;
00013 color: #333333;
00014 font-size: .8em;
00015 }
00016
00017 a {
00018 color: #3366cc;
00019 }
00020
00021 img {
00022 border: 0;
00023 }
00024
00025 #xiphlogo {
00026 margin: 30px 0 16px 0;
00027 }
00028
00029 #content p {
00030 line-height: 1.4;
00031 }
00032
00033 h1, h1 a, h2, h2 a, h3, h3 a {
00034 font-weight: bold;
00035 color: #ff9900;
00036 margin: 1.3em 0 8px 0;
00037 }
00038
00039 h1 {
00040 font-size: 1.3em;
00041 }
00042
00043 h2 {
00044 font-size: 1.2em;
00045 }
00046
00047 h3 {
00048 font-size: 1.1em;
00049 }
00050
00051 li {
00052 line-height: 1.4;
00053 }
00054
00055 #copyright {
00056 margin-top: 30px;
00057 line-height: 1.5em;
00058 text-align: center;
00059 font-size: .8em;
00060 color: #888888;
00061 clear: both;
00062 }
00063 </style>
00064
00065 </head>
00066
00067 <body>
00068
00069 <div id="xiphlogo">
00070 <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.org"/></a>
00071 </div>
00072
00073 <h1>Ogg Vorbis I format specification: comment field and header specification</h1>
00074
00075 <h1>Overview</h1>
00076
00077 <p>The Vorbis text comment header is the second (of three) header
00078 packets that begin a Vorbis bitstream. It is meant for short, text
00079 comments, not arbitrary metadata; arbitrary metadata belongs in a
00080 separate logical bitstream (usually an XML stream type) that provides
00081 greater structure and machine parseability.</p>
00082
00083 <p>The comment field is meant to be used much like someone jotting a
00084 quick note on the bottom of a CDR. It should be a little information to
00085 remember the disc by and explain it to others; a short, to-the-point
00086 text note that need not only be a couple words, but isn't going to be
00087 more than a short paragraph. The essentials, in other words, whatever
00088 they turn out to be, eg:</p>
00089
00090 <blockquote><p>
00091 "Honest Bob and the Factory-to-Dealer-Incentives, _I'm Still Around_,
00092 opening for Moxy Früvous, 1997"
00093 </p></blockquote>
00094
00095 <h1>Comment encoding</h1>
00096
00097 <h2>Structure</h2>
00098
00099 <p>The comment header logically is a list of eight-bit-clean vectors; the
00100 number of vectors is bounded to 2^32-1 and the length of each vector
00101 is limited to 2^32-1 bytes. The vector length is encoded; the vector
00102 contents themselves are not null terminated. In addition to the vector
00103 list, there is a single vector for vendor name (also 8 bit clean,
00104 length encoded in 32 bits). For example, the 1.0 release of libvorbis
00105 set the vendor string to "Xiph.Org libVorbis I 20020717".</p>
00106
00107 <p>The comment header is decoded as follows:</p>
00108
00109 <pre>
00110 1) [vendor_length] = read an unsigned integer of 32 bits
00111 2) [vendor_string] = read a UTF-8 vector as [vendor_length] octets
00112 3) [user_comment_list_length] = read an unsigned integer of 32 bits
00113 4) iterate [user_comment_list_length] times {
00114
00115 5) [length] = read an unsigned integer of 32 bits
00116 6) this iteration's user comment = read a UTF-8 vector as [length] octets
00117
00118 }
00119
00120 7) [framing_bit] = read a single bit as boolean
00121 8) if ( [framing_bit] unset or end of packet ) then ERROR
00122 9) done.
00123 </pre>
00124
00125 <h2>Content vector format</h2>
00126
00127 <p>The comment vectors are structured similarly to a UNIX environment variable.
00128 That is, comment fields consist of a field name and a corresponding value and
00129 look like:</p>
00130
00131 <pre>
00132 comment[0]="ARTIST=me";
00133 comment[1]="TITLE=the sound of Vorbis";
00134 </pre>
00135
00136 <ul>
00137 <li>A case-insensitive field name that may consist of ASCII 0x20 through
00138 0x7D, 0x3D ('=') excluded. ASCII 0x41 through 0x5A inclusive (A-Z) is
00139 to be considered equivalent to ASCII 0x61 through 0x7A inclusive
00140 (a-z).</li>
00141 <li>The field name is immediately followed by ASCII 0x3D ('=');
00142 this equals sign is used to terminate the field name.</li>
00143 <li>0x3D is followed by the 8 bit clean UTF-8 encoded value of the
00144 field contents to the end of the field.</li>
00145 </ul>
00146
00147 <h3>Field names</h3>
00148
00149 <p>Below is a proposed, minimal list of standard field names with a
00150 description of intended use. No single or group of field names is
00151 mandatory; a comment header may contain one, all or none of the names
00152 in this list.</p>
00153
00154 <dl>
00155
00156 <dt>TITLE</dt>
00157 <dd>Track/Work name</dd>
00158
00159 <dt>VERSION</dt>
00160 <dd>The version field may be used to differentiate multiple
00161 versions of the same track title in a single collection.
00162 (e.g. remix info)</dd>
00163
00164 <dt>ALBUM</dt>
00165 <dd>The collection name to which this track belongs</dd>
00166
00167 <dt>TRACKNUMBER</dt>
00168 <dd>The track number of this piece if part of a specific larger collection or album</dd>
00169
00170 <dt>ARTIST</dt>
00171 <dd>The artist generally considered responsible for the work. In popular music
00172 this is usually the performing band or singer. For classical music it would be
00173 the composer. For an audio book it would be the author of the original text.</dd>
00174
00175 <dt>PERFORMER</dt>
00176 <dd>The artist(s) who performed the work. In classical music this would be the
00177 conductor, orchestra, soloists. In an audio book it would be the actor who did
00178 the reading. In popular music this is typically the same as the ARTIST and
00179 is omitted.</dd>
00180
00181 <dt>COPYRIGHT</dt>
00182 <dd>Copyright attribution, e.g., '2001 Nobody's Band' or '1999 Jack Moffitt'</dd>
00183
00184 <dt>LICENSE</dt>
00185 <dd>License information, eg, 'All Rights Reserved', 'Any
00186 Use Permitted', a URL to a license such as a Creative Commons license
00187 ("www.creativecommons.org/blahblah/license.html") or the EFF Open
00188 Audio License ('distributed under the terms of the Open Audio
00189 License. see http://www.eff.org/IP/Open_licenses/eff_oal.html for
00190 details'), etc.</dd>
00191
00192 <dt>ORGANIZATION</dt>
00193 <dd>Name of the organization producing the track (i.e.
00194 the 'record label')</dd>
00195
00196 <dt>DESCRIPTION</dt>
00197 <dd>A short text description of the contents</dd>
00198
00199 <dt>GENRE</dt>
00200 <dd>A short text indication of music genre</dd>
00201
00202 <dt>DATE</dt>
00203 <dd>Date the track was recorded</dd>
00204
00205 <dt>LOCATION</dt>
00206 <dd>Location where track was recorded</dd>
00207
00208 <dt>CONTACT</dt>
00209 <dd>Contact information for the creators or distributors of the track.
00210 This could be a URL, an email address, the physical address of
00211 the producing label.</dd>
00212
00213 <dt>ISRC</dt>
00214 <dd>ISRC number for the track; see <a href="http:
00215 ISRC intro page</a> for more information on ISRC numbers.</dd>
00216
00217 </dl>
00218
00219 <h3>Implications</h3>
00220
00221 <ul>
00222 <li>Field names should not be 'internationalized'; this is a
00223 concession to simplicity not an attempt to exclude the majority of
00224 the world that doesn't speak English. Field <emph>contents</emph>,
00225 however, use the UTF-8 character encoding to allow easy representation
00226 of any language.</li>
00227 <li>We have the length of the entirety of the field and restrictions on
00228 the field name so that the field name is bounded in a known way. Thus
00229 we also have the length of the field contents.</li>
00230 <li>Individual 'vendors' may use non-standard field names within
00231 reason. The proper use of comment fields should be clear through
00232 context at this point. Abuse will be discouraged.</li>
00233 <li>There is no vendor-specific prefix to 'nonstandard' field names.
00234 Vendors should make some effort to avoid arbitrarily polluting the
00235 common namespace. We will generally collect the more useful tags
00236 here to help with standardization.</li>
00237 <li>Field names are not required to be unique (occur once) within a
00238 comment header. As an example, assume a track was recorded by three
00239 well know artists; the following is permissible, and encouraged:
00240 <pre>
00241 ARTIST=Dizzy Gillespie
00242 ARTIST=Sonny Rollins
00243 ARTIST=Sonny Stitt
00244 </pre></li>
00245 </ul>
00246
00247 <h2>Encoding</h2>
00248
00249 <p>The comment header comprises the entirety of the second bitstream
00250 header packet. Unlike the first bitstream header packet, it is not
00251 generally the only packet on the second page and may not be restricted
00252 to within the second bitstream page. The length of the comment header
00253 packet is (practically) unbounded. The comment header packet is not
00254 optional; it must be present in the bitstream even if it is
00255 effectively empty.</p>
00256
00257 <p>The comment header is encoded as follows (as per Ogg's standard
00258 bitstream mapping which renders least-significant-bit of the word to be
00259 coded into the least significant available bit of the current
00260 bitstream octet first):</p>
00261
00262 <ol>
00263 <li>Vendor string length (32 bit unsigned quantity specifying number of octets)</li>
00264 <li>Vendor string ([vendor string length] octets coded from beginning of string
00265 to end of string, not null terminated)</li>
00266 <li>Number of comment fields (32 bit unsigned quantity specifying number of fields)</li>
00267 <li>Comment field 0 length (if [Number of comment fields]>0; 32 bit unsigned
00268 quantity specifying number of octets)</li>
00269 <li>Comment field 0 ([Comment field 0 length] octets coded from beginning of
00270 string to end of string, not null terminated)</li>
00271 <li>Comment field 1 length (if [Number of comment fields]>1...)...</li>
00272 </ol>
00273
00274 <p>This is actually somewhat easier to describe in code; implementation of the above
00275 can be found in vorbis/lib/info.c:_vorbis_pack_comment(),_vorbis_unpack_comment()</p>
00276
00277 <div id="copyright">
00278 The Xiph Fish Logo is a
00279 trademark (™) of Xiph.Org.<br/>
00280
00281 These pages © 1994 - 2005 Xiph.Org. All rights reserved.
00282 </div>
00283
00284 </body>
00285 </html>
