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