doc/v-comment.html

   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&uuml;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 (&trade;) of Xiph.Org.<br/>
 277
 278   These pages &copy; 1994 - 2005 Xiph.Org. All rights reserved.
 279 </div>
 280
 281 </body>
 282 </html>