doc/xml/05-comment.xml

   1 <section id="vorbis-spec-comment">
   2 <sectioninfo>
   3  <releaseinfo>
   4  $Id: 05-comment.xml,v 1.3 2002/10/25 14:41:44 giles Exp $
   5  <emphasis>Last update to this document: July 16, 2002</emphasis>
   6 </releaseinfo>
   7 </sectioninfo>
   8 <title>comment field and header specification</title>
   9
  10
  11 <section><title>Overview</title>
  12
  13 <para>The Vorbis text comment header is the second (of three) header
  14 packets that begin a Vorbis bitstream. It is meant for short text
  15 comments, not arbitrary metadata; arbitrary metadata belongs in a
  16 separate logical bitstream (usually an XML stream type) that provides
  17 greater structure and machine parseability.</para>
  18
  19 <para>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 <simpara>Honest Bob and the Factory-to-Dealer-Incentives, <citetitle>I'm Still
  28 Around</citetitle>, opening for Moxy Fr&uuml;vous, 1997.</simpara>
  29 </blockquote>
  30 </para>
  31
  32 </section>
  33
  34 <section><title>Comment encoding</title>
  35
  36 <section><title>Structure</title>
  37
  38 <para>
  39 The comment header is logically a list of eight-bit-clean vectors; the
  40 number of vectors is bounded to 2^32-1 and the length of each vector
  41 is limited to 2^32-1 bytes. The vector length is encoded; the vector
  42 contents themselves are not null terminated. In addition to the vector
  43 list, there is a single vector for vendor name (also 8 bit clean,
  44 length encoded in 32 bits). The 1.0 release of libvorbis sets the
  45 vendor string to "Xiph.Org libVorbis I 20020717".</para>
  46
  47 <para>The comment header is decoded as follows:
  48
  49 <programlisting>
  50   1) [vendor_length] = read an unsigned integer of 32 bits
  51   2) [vendor_string] = read a UTF-8 vector as [vendor_length] octets
  52   3) [user_comment_list_length] = read an unsigned integer of 32 bits
  53   4) iterate [user_comment_list_length] times {
  54        5) [length] = read an unsigned integer of 32 bits
  55        6) this iteration's user comment = read a UTF-8 vector as [length] octets
  56      }
  57   7) [framing_bit] = read a single bit as boolean
  58   8) if ( [framing_bit] unset or end-of-packet ) then ERROR
  59   9) done.
  60 </programlisting>
  61 </para>
  62
  63 </section>
  64
  65 <section><title>Content vector format</title>
  66
  67 <para>
  68 The comment vectors are structured similarly to a UNIX environment variable.
  69 That is, comment fields consist of a field name and a corresponding value and
  70 look like:</para>
  71
  72 <blockquote><programlisting>
  73 comment[0]="ARTIST=me";
  74 comment[1]="TITLE=the sound of Vorbis";
  75 </programlisting></blockquote>
  76
  77 <para>
  78 The field name is case-insensitive and may consist of ASCII 0x20
  79 through 0x7D, 0x3D ('=') excluded. ASCII 0x41 through 0x5A inclusive
  80 (characters A-Z) is to be considered equivalent to ASCII 0x61 through
  81 0x7A inclusive (characters a-z).
  82 </para>
  83
  84 <para>
  85 The field name is immediately followed by ASCII 0x3D ('=');
  86 this equals sign is used to terminate the field name.
  87 </para>
  88
  89 <para>
  90 0x3D is followed by 8 bit clean UTF-8 encoded value of the
  91 field contents to the end of the field.
  92 </para>
  93
  94 <section><title>Field names</title>
  95
  96 <para>Below is a proposed, minimal list of standard filed names with a
  97 description of intended use.  No single or group of field names is
  98 mandatory; a comment header may contain one, all or none of the names
  99 in this list.</para>
 100
 101 <variablelist>
 102 <varlistentry>
 103 <term>TITLE</term>
 104 <listitem>
 105 <simpara>Track/Work name</simpara>
 106 </listitem>
 107 </varlistentry>
 108 <varlistentry>
 109  <term>VERSION</term>
 110 <listitem>
 111  <simpara>The version field may be used to
 112 differentiate multiple
 113 versions of the same track title in a single collection. (e.g. remix
 114 info)
 115 </simpara></listitem>
 116 </varlistentry>
 117
 118 <varlistentry><term>ALBUM</term><listitem><simpara>The collection name to which this track belongs
 119 </simpara></listitem>
 120 </varlistentry>
 121
 122 <varlistentry><term>TRACKNUMBER</term>
 123 <listitem><simpara>The track number of this piece if part of a specific larger collection or album
 124 </simpara></listitem>
 125 </varlistentry>
 126
 127 <varlistentry><term>ARTIST</term>
 128 <listitem><simpara>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.
 129 </simpara></listitem>
 130 </varlistentry>
 131
 132 <varlistentry><term>PERFORMER</term>
 133 <listitem><simpara>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.
 134 </simpara></listitem>
 135 </varlistentry>
 136
 137 <varlistentry><term>COPYRIGHT</term>
 138 <listitem><simpara>Copyright attribution, e.g., '2001 Nobody's Band' or '1999 Jack Moffitt'
 139 </simpara></listitem>
 140 </varlistentry>
 141
 142 <varlistentry><term>LICENSE</term>
 143 <listitem><simpara>License information, eg, 'All Rights Reserved', 'Any
 144 Use Permitted', a URL to a license such as a Creative Commons license
 145 ("www.creativecommons.org/blahblah/license.html") or the EFF Open
 146 Audio License ('distributed under the terms of the Open Audio
 147 License. see http://www.eff.org/IP/Open_licenses/eff_oal.html for
 148 details'), etc.
 149 </simpara></listitem>
 150 </varlistentry>
 151
 152 <varlistentry><term>ORGANIZATION</term>
 153 <listitem><simpara>Name of the organization producing the track (i.e.
 154 the 'record label')
 155 </simpara></listitem>
 156 </varlistentry>
 157
 158 <varlistentry><term>DESCRIPTION</term>
 159 <listitem><simpara>A short text description of the contents
 160 </simpara></listitem>
 161 </varlistentry>
 162
 163 <varlistentry><term>GENRE</term>
 164 <listitem><simpara>A short text indication of music genre
 165 </simpara></listitem>
 166 </varlistentry>
 167
 168 <varlistentry><term>DATE</term>
 169 <listitem><simpara>Date the track was recorded
 170 </simpara></listitem>
 171 </varlistentry>
 172
 173 <varlistentry><term>LOCATION</term>
 174 <listitem><simpara>Location where track was recorded
 175 </simpara></listitem>
 176 </varlistentry>
 177
 178 <varlistentry><term>CONTACT</term>
 179 <listitem><simpara>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.
 180 </simpara></listitem>
 181 </varlistentry>
 182
 183 <varlistentry><term>ISRC</term>
 184 <listitem><simpara>International Standard Recording Code for the
 185 track; see <ulink
 186 url="http://www.ifpi.org/site-content/online/isrc_intro.html">the ISRC
 187 intro page</ulink> for more information on ISRC numbers.
 188 </simpara></listitem>
 189 </varlistentry>
 190
 191 </variablelist>
 192
 193 </section>
 194
 195 <section><title>Implications</title>
 196
 197 <para>Field names should not be 'internationalized'; this is a
 198 concession to simplicity not an attempt to exclude the majority of
 199 the world that doesn't speak English. Field <emphasis>contents</emphasis>
 200 however, use the UTF-8 character encoding to allow easy representation of any
 201 language.</para>
 202
 203 <para>We have the length of the entirety of the field and restrictions on
 204 the field name so that the field name is bounded in a known way. Thus
 205 we also have the length of the field contents.</para>
 206
 207 <para>Individual 'vendors' may use non-standard field names within
 208 reason. The proper use of comment fields should be clear through
 209 context at this point.  Abuse will be discouraged.</para>
 210
 211 <para>There is no vendor-specific prefix to 'nonstandard' field names.
 212 Vendors should make some effort to avoid arbitrarily polluting the
 213 common namespace. We will generally collect the more useful tags
 214 here to help with standardization.</para>
 215
 216 <para>Field names are not required to be unique (occur once) within a
 217 comment header.  As an example, assume a track was recorded by three
 218 well know artists; the following is permissible, and encouraged:
 219
 220 <blockquote><programlisting>
 221 ARTIST=Dizzy Gillespie
 222 ARTIST=Sonny Rollins
 223 ARTIST=Sonny Stitt
 224 </programlisting></blockquote>
 225
 226 </para>
 227
 228 </section>
 229
 230 </section>
 231
 232 <section><title>Encoding</title>
 233
 234 <para>
 235 The comment header comprises the entirety of the second bitstream
 236 header packet.  Unlike the first bitstream header packet, it is not
 237 generally the only packet on the second page and may not be restricted
 238 to within the second bitstream page.  The length of the comment header
 239 packet is (practically) unbounded.  The comment header packet is not
 240 optional; it must be present in the bitstream even if it is
 241 effectively empty.</para>
 242
 243 <para>
 244 The comment header is encoded as follows (as per Ogg's standard
 245 bitstream mapping which renders least-significant-bit of the word to be
 246 coded into the least significant available bit of the current
 247 bitstream octet first):
 248
 249 <orderedlist>
 250  <listitem><simpara>
 251   Vendor string length (32 bit unsigned quantity specifying number of octets)
 252  </simpara></listitem>
 253  <listitem><simpara>
 254   Vendor string ([vendor string length] octets coded from beginning of string to end of string, not null terminated)
 255  </simpara></listitem>
 256  <listitem><simpara>
 257   Number of comment fields (32 bit unsigned quantity specifying number of fields)
 258  </simpara></listitem>
 259  <listitem><simpara>
 260   Comment field 0 length (if [Number of comment fields]>0; 32 bit unsigned quantity specifying number of octets)
 261  </simpara></listitem>
 262  <listitem><simpara>
 263   Comment field 0 ([Comment field 0 length] octets coded from beginning of string to end of string, not null terminated)
 264  </simpara></listitem>
 265  <listitem><simpara>
 266   Comment field 1 length (if [Number of comment fields]>1...)...
 267  </simpara></listitem>
 268 </orderedlist>
 269 </para>
 270
 271 <para>
 272 This is actually somewhat easier to describe in code; implementation of the above can be found in <filename>vorbis/lib/info.c</filename>, <function>_vorbis_pack_comment()</function> and <function>_vorbis_unpack_comment()</function>.
 273 </para>
 274
 275 </section>
 276 </section>
 277
 278 </section>