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