79fd9e9df254d410369bc4a09be737d6329a107a
[platform/upstream/libvorbis.git] / doc / 05-comment.tex
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
8 The Vorbis text comment header is the second (of three) header
9 packets that begin a Vorbis bitstream. It is meant for short text
10 comments, not arbitrary metadata; arbitrary metadata belongs in a
11 separate logical bitstream (usually an XML stream type) that provides
12 greater structure and machine parseability.
13
14 The comment field is meant to be used much like someone jotting a
15 quick note on the bottom of a CDR. It should be a little information to
16 remember the disc by and explain it to others; a short, to-the-point
17 text note that need not only be a couple words, but isn't going to be
18 more than a short paragraph.  The essentials, in other words, whatever
19 they turn out to be, eg:
20
21 \begin{quote}
22 Honest Bob and the Factory-to-Dealer-Incentives, \textit{``I'm Still
23 Around''}, opening for Moxy Fr\"{u}vous, 1997.
24 \end{quote}
25
26
27
28
29 \subsection{Comment encoding}
30
31 \subsubsection{Structure}
32
33 The comment header is logically 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 contents themselves are not null terminated. In addition to the vector
37 list, there is a single vector for vendor name (also 8 bit clean,
38 length encoded in 32 bits). For example, the 1.0 release of libvorbis
39 set the vendor string to ``Xiph.Org libVorbis I 20020717''.
40
41 The vector lengths and number of vectors are stored lsb first, according
42 to the bit packing conventions of the vorbis codec. However, since data
43 in the comment header is octet-aligned, they can simply be read as
44 unaligned 32 bit little endian unsigned integers.
45
46 The 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
66 The comment vectors are structured similarly to a UNIX environment variable.
67 That is, comment fields consist of a field name and a corresponding value and
68 look like:
69
70 \begin{quote}
71 \begin{programlisting}
72 comment[0]="ARTIST=me";
73 comment[1]="TITLE=the sound of Vorbis";
74 \end{programlisting}
75 \end{quote}
76
77 The field name is case-insensitive and may consist of ASCII 0x20
78 through 0x7D, 0x3D ('=') excluded. ASCII 0x41 through 0x5A inclusive
79 (characters A-Z) is to be considered equivalent to ASCII 0x61 through
80 0x7A inclusive (characters a-z).
81
82
83 The field name is immediately followed by ASCII 0x3D ('=');
84 this equals sign is used to terminate the field name.
85
86
87 0x3D is followed by 8 bit clean UTF-8 encoded value of the
88 field contents to the end of the field.
89
90
91 \paragraph{Field names}
92
93 Below is a proposed, minimal list of standard field names with a
94 description of intended use.  No single or group of field names is
95 mandatory; a comment header may contain one, all or none of the names
96 in 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
104 versions of the same track title in a single collection. (e.g. remix
105 info)
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
124 Use Permitted', a URL to a license such as a Creative Commons license
125 ("www.creativecommons.org/blahblah/license.html") or the EFF Open
126 Audio License ('distributed under the terms of the Open Audio
127 License. see http://www.eff.org/IP/Open_licenses/eff_oal.html for
128 details'), etc.
129
130 \item[ORGANIZATION]
131         Name of the organization producing the track (i.e.
132 the '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
151 track; see \href{http://www.ifpi.org/isrc/}{the ISRC
152 intro page} for more information on ISRC numbers.
153
154 \end{description}
155
156
157
158 \paragraph{Implications}
159
160 Field names should not be 'internationalized'; this is a
161 concession to simplicity not an attempt to exclude the majority of
162 the world that doesn't speak English. Field \emph{contents},
163 however, use the UTF-8 character encoding to allow easy representation
164 of any language.
165
166 We have the length of the entirety of the field and restrictions on
167 the field name so that the field name is bounded in a known way. Thus
168 we also have the length of the field contents.
169
170 Individual 'vendors' may use non-standard field names within
171 reason. The proper use of comment fields should be clear through
172 context at this point.  Abuse will be discouraged.
173
174 There is no vendor-specific prefix to 'nonstandard' field names.
175 Vendors should make some effort to avoid arbitrarily polluting the
176 common namespace. We will generally collect the more useful tags
177 here to help with standardization.
178
179 Field names are not required to be unique (occur once) within a
180 comment header.  As an example, assume a track was recorded by three
181 well know artists; the following is permissible, and encouraged:
182
183 \begin{quote}
184 \begin{programlisting}
185 ARTIST=Dizzy Gillespie
186 ARTIST=Sonny Rollins
187 ARTIST=Sonny Stitt
188 \end{programlisting}
189 \end{quote}
190
191
192
193
194
195
196
197 \subsubsection{Encoding}
198
199 The comment header comprises the entirety of the second bitstream
200 header packet.  Unlike the first bitstream header packet, it is not
201 generally the only packet on the second page and may not be restricted
202 to within the second bitstream page.  The length of the comment header
203 packet is (practically) unbounded.  The comment header packet is not
204 optional; it must be present in the bitstream even if it is
205 effectively empty.
206
207 The comment header is encoded as follows (as per Ogg's standard
208 bitstream mapping which renders least-significant-bit of the word to be
209 coded into the least significant available bit of the current
210 bitstream 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
234 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()}.
235
236
237
238
239
240