Mercurial > hg > sv-dependency-builds

annotate src/libvorbis-1.3.3/doc/v-comment.html @ 127:7867fa7e1b6b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Current fftw source
author Chris Cannam <cannam@all-day-breakfast.com>
date Tue, 18 Oct 2016 13:40:26 +0100
parents 98c1576536ae
children
rev   line source
cannam@86 1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
cannam@86 2 <html>
cannam@86 3 <head>
cannam@86 4
cannam@86 5 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
cannam@86 6 <title>Ogg Vorbis Documentation</title>
cannam@86 7
cannam@86 8 <style type="text/css">
cannam@86 9 body {
cannam@86 10 margin: 0 18px 0 18px;
cannam@86 11 padding-bottom: 30px;
cannam@86 12 font-family: Verdana, Arial, Helvetica, sans-serif;
cannam@86 13 color: #333333;
cannam@86 14 font-size: .8em;
cannam@86 15 }
cannam@86 16
cannam@86 17 a {
cannam@86 18 color: #3366cc;
cannam@86 19 }
cannam@86 20
cannam@86 21 img {
cannam@86 22 border: 0;
cannam@86 23 }
cannam@86 24
cannam@86 25 #xiphlogo {
cannam@86 26 margin: 30px 0 16px 0;
cannam@86 27 }
cannam@86 28
cannam@86 29 #content p {
cannam@86 30 line-height: 1.4;
cannam@86 31 }
cannam@86 32
cannam@86 33 h1, h1 a, h2, h2 a, h3, h3 a {
cannam@86 34 font-weight: bold;
cannam@86 35 color: #ff9900;
cannam@86 36 margin: 1.3em 0 8px 0;
cannam@86 37 }
cannam@86 38
cannam@86 39 h1 {
cannam@86 40 font-size: 1.3em;
cannam@86 41 }
cannam@86 42
cannam@86 43 h2 {
cannam@86 44 font-size: 1.2em;
cannam@86 45 }
cannam@86 46
cannam@86 47 h3 {
cannam@86 48 font-size: 1.1em;
cannam@86 49 }
cannam@86 50
cannam@86 51 li {
cannam@86 52 line-height: 1.4;
cannam@86 53 }
cannam@86 54
cannam@86 55 #copyright {
cannam@86 56 margin-top: 30px;
cannam@86 57 line-height: 1.5em;
cannam@86 58 text-align: center;
cannam@86 59 font-size: .8em;
cannam@86 60 color: #888888;
cannam@86 61 clear: both;
cannam@86 62 }
cannam@86 63 </style>
cannam@86 64
cannam@86 65 </head>
cannam@86 66
cannam@86 67 <body>
cannam@86 68
cannam@86 69 <div id="xiphlogo">
cannam@86 70 <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.Org"/></a>
cannam@86 71 </div>
cannam@86 72
cannam@86 73 <h1>Ogg Vorbis I format specification: comment field and header specification</h1>
cannam@86 74
cannam@86 75 <h1>Overview</h1>
cannam@86 76
cannam@86 77 <p>The Vorbis text comment header is the second (of three) header
cannam@86 78 packets that begin a Vorbis bitstream. It is meant for short, text
cannam@86 79 comments, not arbitrary metadata; arbitrary metadata belongs in a
cannam@86 80 separate logical bitstream (usually an XML stream type) that provides
cannam@86 81 greater structure and machine parseability.</p>
cannam@86 82
cannam@86 83 <p>The comment field is meant to be used much like someone jotting a
cannam@86 84 quick note on the bottom of a CDR. It should be a little information to
cannam@86 85 remember the disc by and explain it to others; a short, to-the-point
cannam@86 86 text note that need not only be a couple words, but isn't going to be
cannam@86 87 more than a short paragraph. The essentials, in other words, whatever
cannam@86 88 they turn out to be, eg:</p>
cannam@86 89
cannam@86 90 <blockquote><p>
cannam@86 91 "Honest Bob and the Factory-to-Dealer-Incentives, _I'm Still Around_,
cannam@86 92 opening for Moxy Fr&uuml;vous, 1997"
cannam@86 93 </p></blockquote>
cannam@86 94
cannam@86 95 <h1>Comment encoding</h1>
cannam@86 96
cannam@86 97 <h2>Structure</h2>
cannam@86 98
cannam@86 99 <p>The comment header logically is a list of eight-bit-clean vectors; the
cannam@86 100 number of vectors is bounded to 2^32-1 and the length of each vector
cannam@86 101 is limited to 2^32-1 bytes. The vector length is encoded; the vector
cannam@86 102 contents themselves are not null terminated. In addition to the vector
cannam@86 103 list, there is a single vector for vendor name (also 8 bit clean,
cannam@86 104 length encoded in 32 bits). For example, the 1.0 release of libvorbis
cannam@86 105 set the vendor string to "Xiph.Org libVorbis I 20020717".</p>
cannam@86 106
cannam@86 107 <p>The comment header is decoded as follows:</p>
cannam@86 108
cannam@86 109 <pre>
cannam@86 110 1) [vendor_length] = read an unsigned integer of 32 bits
cannam@86 111 2) [vendor_string] = read a UTF-8 vector as [vendor_length] octets
cannam@86 112 3) [user_comment_list_length] = read an unsigned integer of 32 bits
cannam@86 113 4) iterate [user_comment_list_length] times {
cannam@86 114
cannam@86 115 5) [length] = read an unsigned integer of 32 bits
cannam@86 116 6) this iteration's user comment = read a UTF-8 vector as [length] octets
cannam@86 117
cannam@86 118 }
cannam@86 119
cannam@86 120 7) [framing_bit] = read a single bit as boolean
cannam@86 121 8) if ( [framing_bit] unset or end of packet ) then ERROR
cannam@86 122 9) done.
cannam@86 123 </pre>
cannam@86 124
cannam@86 125 <h2>Content vector format</h2>
cannam@86 126
cannam@86 127 <p>The comment vectors are structured similarly to a UNIX environment variable.
cannam@86 128 That is, comment fields consist of a field name and a corresponding value and
cannam@86 129 look like:</p>
cannam@86 130
cannam@86 131 <pre>
cannam@86 132 comment[0]="ARTIST=me";
cannam@86 133 comment[1]="TITLE=the sound of Vorbis";
cannam@86 134 </pre>
cannam@86 135
cannam@86 136 <ul>
cannam@86 137 <li>A case-insensitive field name that may consist of ASCII 0x20 through
cannam@86 138 0x7D, 0x3D ('=') excluded. ASCII 0x41 through 0x5A inclusive (A-Z) is
cannam@86 139 to be considered equivalent to ASCII 0x61 through 0x7A inclusive
cannam@86 140 (a-z).</li>
cannam@86 141 <li>The field name is immediately followed by ASCII 0x3D ('=');
cannam@86 142 this equals sign is used to terminate the field name.</li>
cannam@86 143 <li>0x3D is followed by the 8 bit clean UTF-8 encoded value of the
cannam@86 144 field contents to the end of the field.</li>
cannam@86 145 </ul>
cannam@86 146
cannam@86 147 <h3>Field names</h3>
cannam@86 148
cannam@86 149 <p>Below is a proposed, minimal list of standard field names with a
cannam@86 150 description of intended use. No single or group of field names is
cannam@86 151 mandatory; a comment header may contain one, all or none of the names
cannam@86 152 in this list.</p>
cannam@86 153
cannam@86 154 <dl>
cannam@86 155
cannam@86 156 <dt>TITLE</dt>
cannam@86 157 <dd>Track/Work name</dd>
cannam@86 158
cannam@86 159 <dt>VERSION</dt>
cannam@86 160 <dd>The version field may be used to differentiate multiple
cannam@86 161 versions of the same track title in a single collection.
cannam@86 162 (e.g. remix info)</dd>
cannam@86 163
cannam@86 164 <dt>ALBUM</dt>
cannam@86 165 <dd>The collection name to which this track belongs</dd>
cannam@86 166
cannam@86 167 <dt>TRACKNUMBER</dt>
cannam@86 168 <dd>The track number of this piece if part of a specific larger collection or album</dd>
cannam@86 169
cannam@86 170 <dt>ARTIST</dt>
cannam@86 171 <dd>The artist generally considered responsible for the work. In popular music
cannam@86 172 this is usually the performing band or singer. For classical music it would be
cannam@86 173 the composer. For an audio book it would be the author of the original text.</dd>
cannam@86 174
cannam@86 175 <dt>PERFORMER</dt>
cannam@86 176 <dd>The artist(s) who performed the work. In classical music this would be the
cannam@86 177 conductor, orchestra, soloists. In an audio book it would be the actor who did
cannam@86 178 the reading. In popular music this is typically the same as the ARTIST and
cannam@86 179 is omitted.</dd>
cannam@86 180
cannam@86 181 <dt>COPYRIGHT</dt>
cannam@86 182 <dd>Copyright attribution, e.g., '2001 Nobody's Band' or '1999 Jack Moffitt'</dd>
cannam@86 183
cannam@86 184 <dt>LICENSE</dt>
cannam@86 185 <dd>License information, eg, 'All Rights Reserved', 'Any
cannam@86 186 Use Permitted', a URL to a license such as a Creative Commons license
cannam@86 187 ("www.creativecommons.org/blahblah/license.html") or the EFF Open
cannam@86 188 Audio License ('distributed under the terms of the Open Audio
cannam@86 189 License. see http://www.eff.org/IP/Open_licenses/eff_oal.html for
cannam@86 190 details'), etc.</dd>
cannam@86 191
cannam@86 192 <dt>ORGANIZATION</dt>
cannam@86 193 <dd>Name of the organization producing the track (i.e.
cannam@86 194 the 'record label')</dd>
cannam@86 195
cannam@86 196 <dt>DESCRIPTION</dt>
cannam@86 197 <dd>A short text description of the contents</dd>
cannam@86 198
cannam@86 199 <dt>GENRE</dt>
cannam@86 200 <dd>A short text indication of music genre</dd>
cannam@86 201
cannam@86 202 <dt>DATE</dt>
cannam@86 203 <dd>Date the track was recorded</dd>
cannam@86 204
cannam@86 205 <dt>LOCATION</dt>
cannam@86 206 <dd>Location where track was recorded</dd>
cannam@86 207
cannam@86 208 <dt>CONTACT</dt>
cannam@86 209 <dd>Contact information for the creators or distributors of the track.
cannam@86 210 This could be a URL, an email address, the physical address of
cannam@86 211 the producing label.</dd>
cannam@86 212
cannam@86 213 <dt>ISRC</dt>
cannam@86 214 <dd>ISRC number for the track; see <a href="http://www.ifpi.org/isrc/">the
cannam@86 215 ISRC intro page</a> for more information on ISRC numbers.</dd>
cannam@86 216
cannam@86 217 </dl>
cannam@86 218
cannam@86 219 <h3>Implications</h3>
cannam@86 220
cannam@86 221 <ul>
cannam@86 222 <li>Field names should not be 'internationalized'; this is a
cannam@86 223 concession to simplicity not an attempt to exclude the majority of
cannam@86 224 the world that doesn't speak English. Field <emph>contents</emph>,
cannam@86 225 however, use the UTF-8 character encoding to allow easy representation
cannam@86 226 of any language.</li>
cannam@86 227 <li>We have the length of the entirety of the field and restrictions on
cannam@86 228 the field name so that the field name is bounded in a known way. Thus
cannam@86 229 we also have the length of the field contents.</li>
cannam@86 230 <li>Individual 'vendors' may use non-standard field names within
cannam@86 231 reason. The proper use of comment fields should be clear through
cannam@86 232 context at this point. Abuse will be discouraged.</li>
cannam@86 233 <li>There is no vendor-specific prefix to 'nonstandard' field names.
cannam@86 234 Vendors should make some effort to avoid arbitrarily polluting the
cannam@86 235 common namespace. We will generally collect the more useful tags
cannam@86 236 here to help with standardization.</li>
cannam@86 237 <li>Field names are not required to be unique (occur once) within a
cannam@86 238 comment header. As an example, assume a track was recorded by three
cannam@86 239 well know artists; the following is permissible, and encouraged:
cannam@86 240 <pre>
cannam@86 241 ARTIST=Dizzy Gillespie
cannam@86 242 ARTIST=Sonny Rollins
cannam@86 243 ARTIST=Sonny Stitt
cannam@86 244 </pre></li>
cannam@86 245 </ul>
cannam@86 246
cannam@86 247 <h2>Encoding</h2>
cannam@86 248
cannam@86 249 <p>The comment header comprises the entirety of the second bitstream
cannam@86 250 header packet. Unlike the first bitstream header packet, it is not
cannam@86 251 generally the only packet on the second page and may not be restricted
cannam@86 252 to within the second bitstream page. The length of the comment header
cannam@86 253 packet is (practically) unbounded. The comment header packet is not
cannam@86 254 optional; it must be present in the bitstream even if it is
cannam@86 255 effectively empty.</p>
cannam@86 256
cannam@86 257 <p>The comment header is encoded as follows (as per Ogg's standard
cannam@86 258 bitstream mapping which renders least-significant-bit of the word to be
cannam@86 259 coded into the least significant available bit of the current
cannam@86 260 bitstream octet first):</p>
cannam@86 261
cannam@86 262 <ol>
cannam@86 263 <li>Vendor string length (32 bit unsigned quantity specifying number of octets)</li>
cannam@86 264 <li>Vendor string ([vendor string length] octets coded from beginning of string
cannam@86 265 to end of string, not null terminated)</li>
cannam@86 266 <li>Number of comment fields (32 bit unsigned quantity specifying number of fields)</li>
cannam@86 267 <li>Comment field 0 length (if [Number of comment fields]>0; 32 bit unsigned
cannam@86 268 quantity specifying number of octets)</li>
cannam@86 269 <li>Comment field 0 ([Comment field 0 length] octets coded from beginning of
cannam@86 270 string to end of string, not null terminated)</li>
cannam@86 271 <li>Comment field 1 length (if [Number of comment fields]>1...)...</li>
cannam@86 272 </ol>
cannam@86 273
cannam@86 274 <p>This is actually somewhat easier to describe in code; implementation of the above
cannam@86 275 can be found in vorbis/lib/info.c:_vorbis_pack_comment(),_vorbis_unpack_comment()</p>
cannam@86 276
cannam@86 277 <div id="copyright">
cannam@86 278 The Xiph Fish Logo is a
cannam@86 279 trademark (&trade;) of Xiph.Org.<br/>
cannam@86 280
cannam@86 281 These pages &copy; 1994 - 2005 Xiph.Org. All rights reserved.
cannam@86 282 </div>
cannam@86 283
cannam@86 284 </body>
cannam@86 285 </html>