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