1 <HTML><HEAD><TITLE>xiph.org: Ogg Vorbis documentation</TITLE>
2 <BODY bgcolor="#ffffff" text="#202020" link="#006666" vlink="#000000">
3 <nobr><img src="white-ogg.png"><img src="vorbisword2.png"></nobr><p>
6 <h1><font color=#000070>
7 Ogg Vorbis comment field specification
10 <em>Last update to this document: October 2, 2001</em><p>
12 <p>The text comment header is the second (of three) header packets that
13 begin a Vorbis bitstream. It is meant for short, text comments,
14 not arbitrary metadata; arbitrary metadata belongs in a separate
15 logical bitream (usually an XML stream type) that provides greater
16 structure and machine parseability.</p>
18 <h2>Comment use rationale</h2>
20 The comment field is meant to be used much like someone jotting a
21 quick note on the bottom of a CDR. It should be a little information to
22 remember the disc by and explain it to others; a short, to-the-point
23 text note that need not only be a couple words, but isn't going to be
24 more than a short paragraph. The essentials, in other words, whatever
25 they turn out to be, eg:
28 "Honest Bob and the Factory-to-Dealer-Incentives, _I'm Still Around_,
29 opening for Moxy Fruvous, 1997"
34 The comment header logically is a list of eight-bit-clean vectors; the
35 number of vectors is bounded to 2^32-1 and the length of each vector
36 is limited to 2^32-1 bytes. The vector length is encoded; the vector
37 is not null terminated. In addition to the vector list, there is a
38 single vector for vendor name (also 8 bit clean, length encoded in 32
39 bits). Libvorbis currently sets the vendor string to "Xiphophorus
40 libVorbis I 20010910".<p>
42 The comment vectors are structured similarly to a UNIX environment variable.
43 That is, comment fields consist of a field name and a field value and
47 comment[0]="ARTIST=me";
48 comment[1]="TITLE=the sound of vorbis";
51 <h2>Content vector format</h2>
54 <li>A case-insensitive field name that may consist of ASCII 0x20 through
55 0x7D, 0x3D ('=') excluded. ASCII 0x41 through 0x5A inclusive (A-Z) is
56 to be considered equivalent to ASCII 0x61 through 0x7A inclusive
59 <li>The field name is immediately followed by ASCII 0x3D ('='); this
60 equals sign is used to terminate the field name.
62 <li>0x3D is followed by 8 bit clean UTF-8 encoded field contents
63 to the end of the field.
68 Below is a proposed, minimal list of standard filed names with a
69 description of intended use. No single or group of field names is
70 mandatory; a comment header may contain one, all or none of the names
73 <dt>TITLE<dd>Track name
75 <dt>VERSION<dd>The version field may be used to differentiate multiple
76 versions of the same track title in a single collection. (e.g. remix info)
78 <dt>ALBUM<dd>The collection name to which this track belongs
80 <dt>TRACKNUMBER<dd>The track number of this piece if part of a specific larger collection or album
82 <dt>ARTIST<dd>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.
84 <dt>PERFORMER<dd>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 ommitted.
86 <dt>ORGANIZATION<dd>Name of the organization producing the track (i.e.
89 <dt>DESCRIPTION<dd>A short text description of the contents
91 <dt>GENRE<dd>A short text indication of music genre
93 <dt>DATE<dd>Date the track was recorded
95 <dt>LOCATION<dd>Location where track was recorded
97 <dt>COPYRIGHT<dd>Copyright and license information (e.g. '(c) 2001 Nobody's Band. All rights reserved' or '(c) 1999 Jack Moffit, distributed under the terms of the Open Audio License. see http://www.eff.org/IP/Open_licenses/eff_oal.html for details')
99 <dt>CONTACT<dd>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.
101 <dt>ISRC<dd>ISRC number for the track; see <a href="http://www.ifpi.org/site-content/online/isrc_intro.html">the ISRC intro page</a> for more information on ISRC numbers.
103 <dt>DISCID<dd>Table of contents hash from an associated disc, generally used to index the track in published music databases. See <a href="http://freedb.org/">http://freedb.org/</a> for and example of such a hash.
107 <h3>Implications</h3>
110 Field names should not be 'internationalized'; this is a
111 concession to simplicity not an attempt to exclude the majority of
112 the world that doesn't speak English. Field *contents*, however,
113 are represented in UTF-8 to allow easy representation of any language.
115 We have the length of the entirety of the field and restrictions on
116 the field name so that the field name is bounded in a known way. Thus
117 we also have the length of the field contents.
119 Individual 'vendors' may use non-standard field names within
120 reason. The proper use of comment fields should be clear through
121 context at this point. Abuse will be discouraged.
123 There is no vendor-specific prefix to 'nonstandard' field names.
124 Vendors should make some effort to avoid arbitrarily polluting the
125 common namespace. We will generally collect the more useful tags
126 here to help with standardization.
128 Field names are not required to be unique (occur once) within a
129 comment header. As an example, assume a track was recorded by three
130 well know artists; the following is permissible, and encouraged:
132 ARTIST=Dizzy Gillespie
141 The comment header comprises the entirety of the second bitstream
142 header packet. Unlike the first bitstream header packet, it is not
143 generally the only packet on the second page and may not be restricted
144 to within the second bitstream page. The length of the comment header
145 packet is [practically] unbounded. The comment header packet is not
146 optional; it must be present in the bitstream even if it is
147 effectively empty.<p>
149 The comment header is encoded as follows (as per Ogg's standard
150 bitstream mapping which renders least-significant-bit of the word to be
151 coded into the least significant available bit of the current
152 bitstream octet first):
156 Vendor string length (32 bit unsigned quantity specifying number of octets)
159 Vendor string ([vendor string length] octets coded from beginning of string to end of string, not null terminated)
161 <li>Number of comment fields (32 bit unsigned quantity specifying number of fields)
163 <li>Comment field 0 length (if [Number of comment fields]>0; 32 bit unsigned quantity specifying number of octets)
166 Comment field 0 ([Comment field 0 length] octets coded from beginning of string to end of string, not null terminated)
168 <li>Comment field 1 length (if [Number of comment fields]>1...)...
171 This is actually somewhat easier to describe in code; implementation of the above can be found in vorbis/lib/info.c:_vorbis_pack_comment(),_vorbis_unpack_comment()
174 <a href="http://www.xiph.org/">
175 <img src="white-xifish.png" align=left border=0>
177 <font size=-2 color=#505050>
179 Ogg is a <a href="http://www.xiph.org">Xiphophorus</a> effort to
180 protect essential tenets of Internet multimedia from corporate
181 hostage-taking; Open Source is the net's greatest tool to keep
182 everyone honest. See <a href="http://www.xiph.org/about.html">About
183 Xiphophorus</a> for details.
186 Ogg Vorbis is the first Ogg audio CODEC. Anyone may
187 freely use and distribute the Ogg and Vorbis specification,
188 whether in a private, public or corporate capacity. However,
189 Xiphophorus and the Ogg project (xiph.org) reserve the right to set
190 the Ogg/Vorbis specification and certify specification compliance.<p>
192 Xiphophorus's Vorbis software CODEC implementation is distributed
193 under the Lesser/Library GNU Public License. This does not restrict
194 third parties from distributing independent implementations of Vorbis
195 software under other licenses.<p>
197 OggSquish, Vorbis, Xiphophorus and their logos are trademarks (tm) of
198 <a href="http://www.xiph.org/">Xiphophorus</a>. These pages are
199 copyright (C) 1994-2001 Xiphophorus. All rights reserved.<p>