doc/05-comment.tex

   1 % -*- mode: latex; TeX-master: "Vorbis_I_spec"; -*-
   2 %!TEX root = Vorbis_I_spec.tex
   3 \section{comment field and header specification} \label{vorbis:spec:comment}
   4
   5 \subsection{Overview}
   6
   7 The Vorbis text comment header is the second (of three) header
   8 packets that begin a Vorbis bitstream. It is meant for short text
   9 comments, not arbitrary metadata; arbitrary metadata belongs in a
  10 separate logical bitstream (usually an XML stream type) that provides
  11 greater structure and machine parseability.
  12
  13 The comment field is meant to be used much like someone jotting a
  14 quick note on the bottom of a CDR. It should be a little information to
  15 remember the disc by and explain it to others; a short, to-the-point
  16 text note that need not only be a couple words, but isn't going to be
  17 more than a short paragraph.  The essentials, in other words, whatever
  18 they turn out to be, eg:
  19
  20 \begin{quote}
  21 Honest Bob and the Factory-to-Dealer-Incentives, \textit{``I'm Still
  22 Around''}, opening for Moxy Fr\"{u}vous, 1997.
  23 \end{quote}
  24
  25
  26
  27
  28 \subsection{Comment encoding}
  29
  30 \subsubsection{Structure}
  31
  32 The comment header is logically a list of eight-bit-clean vectors; the
  33 number of vectors is bounded to $2^{32}-1$ and the length of each vector
  34 is limited to $2^{32}-1$ bytes. The vector length is encoded; the vector
  35 contents themselves are not null terminated. In addition to the vector
  36 list, there is a single vector for vendor name (also 8 bit clean,
  37 length encoded in 32 bits). For example, the 1.0 release of libvorbis
  38 set the vendor string to ``Xiph.Org libVorbis I 20020717''.
  39
  40 The vector lengths and number of vectors are stored lsb first, according
  41 to the bit packing conventions of the vorbis codec. However, since data
  42 in the comment header is octet-aligned, they can simply be read as
  43 unaligned 32 bit little endian unsigned integers.
  44
  45 The comment header is decoded as follows:
  46
  47 \begin{programlisting}
  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        5) [length] = read an unsigned integer of 32 bits
  53        6) this iteration's user comment = read a UTF-8 vector as [length] octets
  54      }
  55   7) [framing\_bit] = read a single bit as boolean
  56   8) if ( [framing\_bit] unset or end-of-packet ) then ERROR
  57   9) done.
  58 \end{programlisting}
  59
  60
  61
  62
  63 \subsubsection{Content vector format}
  64
  65 The comment vectors are structured similarly to a UNIX environment variable.
  66 That is, comment fields consist of a field name and a corresponding value and
  67 look like:
  68
  69 \begin{quote}
  70 \begin{programlisting}
  71 comment[0]="ARTIST=me";
  72 comment[1]="TITLE=the sound of Vorbis";
  73 \end{programlisting}
  74 \end{quote}
  75
  76 The field name is case-insensitive and may consist of ASCII 0x20
  77 through 0x7D, 0x3D ('=') excluded. ASCII 0x41 through 0x5A inclusive
  78 (characters A-Z) is to be considered equivalent to ASCII 0x61 through
  79 0x7A inclusive (characters a-z).
  80
  81
  82 The field name is immediately followed by ASCII 0x3D ('=');
  83 this equals sign is used to terminate the field name.
  84
  85
  86 0x3D is followed by 8 bit clean UTF-8 encoded value of the
  87 field contents to the end of the field.
  88
  89
  90 \paragraph{Field names}
  91
  92 Below is a proposed, minimal list of standard field names with a
  93 description of intended use.  No single or group of field names is
  94 mandatory; a comment header may contain one, all or none of the names
  95 in this list.
  96
  97 \begin{description} %[style=nextline]
  98 \item[TITLE]
  99         Track/Work name
 100
 101 \item[VERSION]
 102         The version field may be used to differentiate multiple
 103 versions of the same track title in a single collection. (e.g. remix
 104 info)
 105
 106 \item[ALBUM]
 107         The collection name to which this track belongs
 108
 109 \item[TRACKNUMBER]
 110         The track number of this piece if part of a specific larger collection or album
 111
 112 \item[ARTIST]
 113         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.
 114
 115 \item[PERFORMER]
 116         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.
 117
 118 \item[COPYRIGHT]
 119         Copyright attribution, e.g., '2001 Nobody's Band' or '1999 Jack Moffitt'
 120
 121 \item[LICENSE]
 122         License information, eg, 'All Rights Reserved', 'Any
 123 Use Permitted', a URL to a license such as a Creative Commons license
 124 ("www.creativecommons.org/blahblah/license.html") or the EFF Open
 125 Audio License ('distributed under the terms of the Open Audio
 126 License. see http://www.eff.org/IP/Open\_licenses/eff\_oal.html for
 127 details'), etc.
 128
 129 \item[ORGANIZATION]
 130         Name of the organization producing the track (i.e.
 131 the 'record label')
 132
 133 \item[DESCRIPTION]
 134         A short text description of the contents
 135
 136 \item[GENRE]
 137         A short text indication of music genre
 138
 139 \item[DATE]
 140         Date the track was recorded
 141
 142 \item[LOCATION]
 143         Location where track was recorded
 144
 145 \item[CONTACT]
 146         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.
 147
 148 \item[ISRC]
 149         International Standard Recording Code for the
 150 track; see \href{https://isrc.ifpi.org/}{the ISRC
 151 intro page} for more information on ISRC numbers.
 152
 153 \end{description}
 154
 155
 156
 157 \paragraph{Implications}
 158
 159 Field names should not be 'internationalized'; this is a
 160 concession to simplicity not an attempt to exclude the majority of
 161 the world that doesn't speak English. Field \emph{contents},
 162 however, use the UTF-8 character encoding to allow easy representation
 163 of any language.
 164
 165 We have the length of the entirety of the field and restrictions on
 166 the field name so that the field name is bounded in a known way. Thus
 167 we also have the length of the field contents.
 168
 169 Individual 'vendors' may use non-standard field names within
 170 reason. The proper use of comment fields should be clear through
 171 context at this point.  Abuse will be discouraged.
 172
 173 There is no vendor-specific prefix to 'nonstandard' field names.
 174 Vendors should make some effort to avoid arbitrarily polluting the
 175 common namespace. We will generally collect the more useful tags
 176 here to help with standardization.
 177
 178 Field names are not required to be unique (occur once) within a
 179 comment header.  As an example, assume a track was recorded by three
 180 well know artists; the following is permissible, and encouraged:
 181
 182 \begin{quote}
 183 \begin{programlisting}
 184 ARTIST=Dizzy Gillespie
 185 ARTIST=Sonny Rollins
 186 ARTIST=Sonny Stitt
 187 \end{programlisting}
 188 \end{quote}
 189
 190
 191
 192
 193
 194
 195
 196 \subsubsection{Encoding}
 197
 198 The comment header comprises the entirety of the second bitstream
 199 header packet.  Unlike the first bitstream header packet, it is not
 200 generally the only packet on the second page and may not be restricted
 201 to within the second bitstream page.  The length of the comment header
 202 packet is (practically) unbounded.  The comment header packet is not
 203 optional; it must be present in the bitstream even if it is
 204 effectively empty.
 205
 206 The comment header is encoded as follows (as per Ogg's standard
 207 bitstream mapping which renders least-significant-bit of the word to be
 208 coded into the least significant available bit of the current
 209 bitstream octet first):
 210
 211 \begin{enumerate}
 212  \item
 213   Vendor string length (32 bit unsigned quantity specifying number of octets)
 214
 215  \item
 216   Vendor string ([vendor string length] octets coded from beginning of string to end of string, not null terminated)
 217
 218  \item
 219   Number of comment fields (32 bit unsigned quantity specifying number of fields)
 220
 221  \item
 222   Comment field 0 length (if [Number of comment fields] $>0$; 32 bit unsigned quantity specifying number of octets)
 223
 224  \item
 225   Comment field 0 ([Comment field 0 length] octets coded from beginning of string to end of string, not null terminated)
 226
 227  \item
 228   Comment field 1 length (if [Number of comment fields] $>1$...)...
 229
 230 \end{enumerate}
 231
 232
 233 This is actually somewhat easier to describe in code; implementation of the above can be found in \filename{vorbis/lib/info.c}, \function{\_vorbis\_pack\_comment()} and \function{\_vorbis\_unpack\_comment()}.
 234
 235
 236
 237
 238
 239