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