doc/v-comment.html

   1 <HTML><HEAD><TITLE>xiph.org: Ogg Vorbis documentation</TITLE>
   2 <BODY bgcolor="#ffffff" text="#202020" link="#006666" vlink="#000000">
   3 <nobr><img src="white-ogg.png"><img src="vorbisword2.png"></nobr><p>
   4
   5
   6 <h1><font color=#000070>
   7 Ogg Vorbis I format specification: comment field and header specification
   8 </font></h1>
   9
  10 <em>Last update to this document: July 16, 2002</em><p>
  11
  12 <h1>Overview</h1>
  13
  14 <p>The Vorbis text comment header is the second (of three) header
  15 packets that begin a Vorbis bitstream. It is meant for short, text
  16 comments, not arbitrary metadata; arbitrary metadata belongs in a
  17 separate logical bitstream (usually an XML stream type) that provides
  18 greater structure and machine parseability.
  19
  20 <p>The comment field is meant to be used much like someone jotting a
  21 quick note on the bottom of a CDR. It should be a little information to
  22 remember the disc by and explain it to others; a short, to-the-point
  23 text note that need not only be a couple words, but isn't going to be
  24 more than a short paragraph.  The essentials, in other words, whatever
  25 they turn out to be, eg:
  26
  27 <blockquote>
  28 "Honest Bob and the Factory-to-Dealer-Incentives, _I'm Still Around_,
  29 opening for Moxy Fruvous, 1997"
  30 </blockquote>
  31
  32 <h1>Comment encoding</h1>
  33
  34
  35 <h2>Structure</h2>
  36
  37 The comment header logically is a list of eight-bit-clean vectors; the
  38 number of vectors is bounded to 2^32-1 and the length of each vector
  39 is limited to 2^32-1 bytes. The vector length is encoded; the vector
  40 contents themselves are not null terminated. In addition to the vector
  41 list, there is a single vector for vendor name (also 8 bit clean,
  42 length encoded in 32 bits). Libvorbis currently sets the vendor string
  43 to "Xiph.Org libVorbis I 20020717".<p>
  44
  45 The comment header is decoded as follows:<p>
  46
  47 <pre>
  48   1) [vendor_length] = read an unsigned integer of 32 bits
  49   2) [vendor_string] = read a UTF-8 vector as [vendor_length] octets
  50   3) [user_comment_list_length] = read an unsigned integer of 32 bits
  51   4) iterate [user_comment_list_length] times {
  52
  53        5) [length] = read an unsigned integer of 32 bits
  54        6) this iteration's user comment = read a UTF-8 vector as [length] octets
  55
  56      }
  57
  58   7) [framing_bit] = read a single bit as boolean
  59   8) if ( [framing_bit]  unset or end of packet ) then ERROR
  60   9) done.
  61 </pre>
  62
  63
  64 <h2>Content vector format</h2>
  65
  66 The comment vectors are structured similarly to a UNIX environment variable.
  67 That is, comment fields consist of a field name and a field value and
  68 look like:
  69
  70 <pre>
  71 comment[0]="ARTIST=me";
  72 comment[1]="TITLE=the sound of Vorbis";
  73 </pre>
  74
  75 <ul>
  76 <li>A case-insensitive field name that may consist of ASCII 0x20 through
  77 0x7D, 0x3D ('=') excluded. ASCII 0x41 through 0x5A inclusive (A-Z) is
  78 to be considered equivalent to ASCII 0x61 through 0x7A inclusive
  79 (a-z).
  80
  81 <li>The field name is immediately followed by ASCII 0x3D ('='); this
  82 equals sign is used to terminate the field name.
  83
  84 <li>0x3D is followed by 8 bit clean UTF-8 encoded field contents
  85 to the end of the field.
  86 </ul>
  87
  88 <h3>Field names</h3>
  89
  90 Below is a proposed, minimal list of standard field names with a
  91 description of intended use.  No single or group of field names is
  92 mandatory; a comment header may contain one, all or none of the names
  93 in this list.<p>
  94
  95 <dl>
  96 <dt>TITLE<dd>Track/Work name
  97
  98 <dt>VERSION<dd>The version field may be used to differentiate multiple
  99 versions of the same track title in a single collection. (e.g. remix info)
 100
 101 <dt>ALBUM<dd>The collection name to which this track belongs
 102
 103 <dt>TRACKNUMBER<dd>The track number of this piece if part of a specific larger collection or album
 104
 105 <dt>ARTIST<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.
 106
 107 <dt>PERFORMER<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.
 108
 109 <dt>COPYRIGHT<dd>Copyright attribution, e.g., '2001 Nobody's Band' or '1999 Jack Moffitt'
 110
 111 <dt>LICENSE<dd>License information, eg, 'All Rights Reserved', 'Any
 112 Use Permitted', a URL to a license such as a Creative Commons license
 113 ("www.creativecommons.org/blahblah/license.html") or the EFF Open
 114 Audio License ('distributed under the terms of the Open Audio
 115 License. see http://www.eff.org/IP/Open_licenses/eff_oal.html for
 116 details'), etc.
 117
 118 <dt>ORGANIZATION<dd>Name of the organization producing the track (i.e.
 119 the 'record label')
 120
 121 <dt>DESCRIPTION<dd>A short text description of the contents
 122
 123 <dt>GENRE<dd>A short text indication of music genre
 124
 125 <dt>DATE<dd>Date the track was recorded
 126
 127 <dt>LOCATION<dd>Location where track was recorded
 128
 129 <dt>CONTACT<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.
 130
 131 <dt>ISRC<dd>ISRC number for the track; see <a href="http://www.ifpi.org/site-content/online/isrc_intro.html">the ISRC intro page</a> for more information on ISRC numbers.
 132
 133 </dl>
 134
 135 <h3>Implications</h3>
 136 <ul>
 137 <li>
 138 Field names should not be 'internationalized'; this is a
 139 concession to simplicity not an attempt to exclude the majority of
 140 the world that doesn't speak English. Field *contents*, however,
 141 are represented in UTF-8 to allow easy representation of any language.
 142 <li>
 143 We have the length of the entirety of the field and restrictions on
 144 the field name so that the field name is bounded in a known way. Thus
 145 we also have the length of the field contents.
 146 <li>
 147 Individual 'vendors' may use non-standard field names within
 148 reason. The proper use of comment fields should be clear through
 149 context at this point.  Abuse will be discouraged.
 150 <li>
 151 There is no vendor-specific prefix to 'nonstandard' field names.
 152 Vendors should make some effort to avoid arbitrarily polluting the
 153 common namespace. We will generally collect the more useful tags
 154 here to help with standardization.
 155 <li>
 156 Field names are not required to be unique (occur once) within a
 157 comment header.  As an example, assume a track was recorded by three
 158 well know artists; the following is permissible, and encouraged:
 159 <pre>
 160               ARTIST=Dizzy Gillespie
 161               ARTIST=Sonny Rollins
 162               ARTIST=Sonny Stitt
 163 </pre>
 164
 165 </ul>
 166
 167 <h2>Encoding</h2>
 168
 169 The comment header comprises the entirety of the second bitstream
 170 header packet.  Unlike the first bitstream header packet, it is not
 171 generally the only packet on the second page and may not be restricted
 172 to within the second bitstream page.  The length of the comment header
 173 packet is [practically] unbounded.  The comment header packet is not
 174 optional; it must be present in the bitstream even if it is
 175 effectively empty.<p>
 176
 177 The comment header is encoded as follows (as per Ogg's standard
 178 bitstream mapping which renders least-significant-bit of the word to be
 179 coded into the least significant available bit of the current
 180 bitstream octet first):
 181
 182 <ol>
 183 <li>
 184 Vendor string length (32 bit unsigned quantity specifying number of octets)
 185
 186 <li>
 187 Vendor string ([vendor string length] octets coded from beginning of string to end of string, not null terminated)
 188
 189 <li>Number of comment fields (32 bit unsigned quantity specifying number of fields)
 190
 191 <li>Comment field 0 length (if [Number of comment fields]>0; 32 bit unsigned quantity specifying number of octets)
 192
 193 <li>
 194 Comment field 0 ([Comment field 0 length] octets coded from beginning of string to end of string, not null terminated)
 195
 196 <li>Comment field 1 length (if [Number of comment fields]>1...)...
 197 </ol>
 198
 199 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()
 200
 201 <hr>
 202 <a href="http://www.xiph.org/">
 203 <img src="white-xifish.png" align=left border=0>
 204 </a>
 205 <font size=-2 color=#505050>
 206
 207 Ogg is a <a href="http://www.xiph.org">Xiph.org Foundation</a> effort
 208 to protect essential tenets of Internet multimedia from corporate
 209 hostage-taking; Open Source is the net's greatest tool to keep
 210 everyone honest. See <a href="http://www.xiph.org/about.html">About
 211 the Xiph.org Foundation</a> for details.
 212 <p>
 213
 214 Ogg Vorbis is the first Ogg audio CODEC.  Anyone may freely use and
 215 distribute the Ogg and Vorbis specification, whether in a private,
 216 public or corporate capacity.  However, the Xiph.org Foundation and
 217 the Ogg project (xiph.org) reserve the right to set the Ogg Vorbis
 218 specification and certify specification compliance.<p>
 219
 220 Xiph.org's Vorbis software CODEC implementation is distributed under a
 221 BSD-like license.  This does not restrict third parties from
 222 distributing independent implementations of Vorbis software under
 223 other licenses.<p>
 224
 225 Ogg, Vorbis, Xiph.org Foundation and their logos are trademarks (tm)
 226 of the <a href="http://www.xiph.org/">Xiph.org Foundation</a>.  These
 227 pages are copyright (C) 1994-2002 Xiph.org Foundation. All rights
 228 reserved.<p>
 229
 230 </body>
 231