1 <?xml version="1.0" standalone="no"?>
2 <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4 <!ENTITY % isolat1 SYSTEM "http://www.oasis-open.org/docbook/xml/4.2/ent/iso-lat1.ent">
8 <section id="vorbis-spec-comment">
14 <title>comment field and header specification</title>
17 <section><title>Overview</title>
19 <para>The Vorbis text comment header is the second (of three) header
20 packets that begin a Vorbis bitstream. It is meant for short text
21 comments, not arbitrary metadata; arbitrary metadata belongs in a
22 separate logical bitstream (usually an XML stream type) that provides
23 greater structure and machine parseability.</para>
25 <para>The comment field is meant to be used much like someone jotting a
26 quick note on the bottom of a CDR. It should be a little information to
27 remember the disc by and explain it to others; a short, to-the-point
28 text note that need not only be a couple words, but isn't going to be
29 more than a short paragraph. The essentials, in other words, whatever
30 they turn out to be, eg:
33 <simpara>Honest Bob and the Factory-to-Dealer-Incentives, <citetitle>I'm Still
34 Around</citetitle>, opening for Moxy Früvous, 1997.</simpara>
40 <section><title>Comment encoding</title>
42 <section><title>Structure</title>
45 The comment header is logically a list of eight-bit-clean vectors; the
46 number of vectors is bounded to 2^32-1 and the length of each vector
47 is limited to 2^32-1 bytes. The vector length is encoded; the vector
48 contents themselves are not null terminated. In addition to the vector
49 list, there is a single vector for vendor name (also 8 bit clean,
50 length encoded in 32 bits). For example, the 1.0 release of libvorbis
51 set the vendor string to "Xiph.Org libVorbis I 20020717".</para>
53 <para>The comment header is decoded as follows:
56 1) [vendor_length] = read an unsigned integer of 32 bits
57 2) [vendor_string] = read a UTF-8 vector as [vendor_length] octets
58 3) [user_comment_list_length] = read an unsigned integer of 32 bits
59 4) iterate [user_comment_list_length] times {
60 5) [length] = read an unsigned integer of 32 bits
61 6) this iteration's user comment = read a UTF-8 vector as [length] octets
63 7) [framing_bit] = read a single bit as boolean
64 8) if ( [framing_bit] unset or end-of-packet ) then ERROR
71 <section><title>Content vector format</title>
74 The comment vectors are structured similarly to a UNIX environment variable.
75 That is, comment fields consist of a field name and a corresponding value and
78 <blockquote><programlisting>
79 comment[0]="ARTIST=me";
80 comment[1]="TITLE=the sound of Vorbis";
81 </programlisting></blockquote>
84 The field name is case-insensitive and may consist of ASCII 0x20
85 through 0x7D, 0x3D ('=') excluded. ASCII 0x41 through 0x5A inclusive
86 (characters A-Z) is to be considered equivalent to ASCII 0x61 through
87 0x7A inclusive (characters a-z).
91 The field name is immediately followed by ASCII 0x3D ('=');
92 this equals sign is used to terminate the field name.
96 0x3D is followed by 8 bit clean UTF-8 encoded value of the
97 field contents to the end of the field.
100 <section><title>Field names</title>
102 <para>Below is a proposed, minimal list of standard field names with a
103 description of intended use. No single or group of field names is
104 mandatory; a comment header may contain one, all or none of the names
111 <simpara>Track/Work name</simpara>
117 <simpara>The version field may be used to
118 differentiate multiple
119 versions of the same track title in a single collection. (e.g. remix
121 </simpara></listitem>
124 <varlistentry><term>ALBUM</term><listitem><simpara>The collection name to which this track belongs
125 </simpara></listitem>
128 <varlistentry><term>TRACKNUMBER</term>
129 <listitem><simpara>The track number of this piece if part of a specific larger collection or album
130 </simpara></listitem>
133 <varlistentry><term>ARTIST</term>
134 <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.
135 </simpara></listitem>
138 <varlistentry><term>PERFORMER</term>
139 <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.
140 </simpara></listitem>
143 <varlistentry><term>COPYRIGHT</term>
144 <listitem><simpara>Copyright attribution, e.g., '2001 Nobody's Band' or '1999 Jack Moffitt'
145 </simpara></listitem>
148 <varlistentry><term>LICENSE</term>
149 <listitem><simpara>License information, eg, 'All Rights Reserved', 'Any
150 Use Permitted', a URL to a license such as a Creative Commons license
151 ("www.creativecommons.org/blahblah/license.html") or the EFF Open
152 Audio License ('distributed under the terms of the Open Audio
153 License. see http://www.eff.org/IP/Open_licenses/eff_oal.html for
155 </simpara></listitem>
158 <varlistentry><term>ORGANIZATION</term>
159 <listitem><simpara>Name of the organization producing the track (i.e.
161 </simpara></listitem>
164 <varlistentry><term>DESCRIPTION</term>
165 <listitem><simpara>A short text description of the contents
166 </simpara></listitem>
169 <varlistentry><term>GENRE</term>
170 <listitem><simpara>A short text indication of music genre
171 </simpara></listitem>
174 <varlistentry><term>DATE</term>
175 <listitem><simpara>Date the track was recorded
176 </simpara></listitem>
179 <varlistentry><term>LOCATION</term>
180 <listitem><simpara>Location where track was recorded
181 </simpara></listitem>
184 <varlistentry><term>CONTACT</term>
185 <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.
186 </simpara></listitem>
189 <varlistentry><term>ISRC</term>
190 <listitem><simpara>International Standard Recording Code for the
192 url="http://www.ifpi.org/site-content/online/isrc_intro.html">the ISRC
193 intro page</ulink> for more information on ISRC numbers.
194 </simpara></listitem>
201 <section><title>Implications</title>
203 <para>Field names should not be 'internationalized'; this is a
204 concession to simplicity not an attempt to exclude the majority of
205 the world that doesn't speak English. Field <emphasis>contents</emphasis>,
206 however, use the UTF-8 character encoding to allow easy representation
207 of any language.</para>
209 <para>We have the length of the entirety of the field and restrictions on
210 the field name so that the field name is bounded in a known way. Thus
211 we also have the length of the field contents.</para>
213 <para>Individual 'vendors' may use non-standard field names within
214 reason. The proper use of comment fields should be clear through
215 context at this point. Abuse will be discouraged.</para>
217 <para>There is no vendor-specific prefix to 'nonstandard' field names.
218 Vendors should make some effort to avoid arbitrarily polluting the
219 common namespace. We will generally collect the more useful tags
220 here to help with standardization.</para>
222 <para>Field names are not required to be unique (occur once) within a
223 comment header. As an example, assume a track was recorded by three
224 well know artists; the following is permissible, and encouraged:
226 <blockquote><programlisting>
227 ARTIST=Dizzy Gillespie
230 </programlisting></blockquote>
238 <section><title>Encoding</title>
241 The comment header comprises the entirety of the second bitstream
242 header packet. Unlike the first bitstream header packet, it is not
243 generally the only packet on the second page and may not be restricted
244 to within the second bitstream page. The length of the comment header
245 packet is (practically) unbounded. The comment header packet is not
246 optional; it must be present in the bitstream even if it is
247 effectively empty.</para>
250 The comment header is encoded as follows (as per Ogg's standard
251 bitstream mapping which renders least-significant-bit of the word to be
252 coded into the least significant available bit of the current
253 bitstream octet first):
257 Vendor string length (32 bit unsigned quantity specifying number of octets)
258 </simpara></listitem>
260 Vendor string ([vendor string length] octets coded from beginning of string to end of string, not null terminated)
261 </simpara></listitem>
263 Number of comment fields (32 bit unsigned quantity specifying number of fields)
264 </simpara></listitem>
266 Comment field 0 length (if [Number of comment fields]>0; 32 bit unsigned quantity specifying number of octets)
267 </simpara></listitem>
269 Comment field 0 ([Comment field 0 length] octets coded from beginning of string to end of string, not null terminated)
270 </simpara></listitem>
272 Comment field 1 length (if [Number of comment fields]>1...)...
273 </simpara></listitem>
278 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>.