]> git.jsancho.org Git - lugaru.git/blob - libvorbis-1.0.1/doc/v-comment.html
Added a couple missing Windows files
[lugaru.git] / libvorbis-1.0.1 / doc / v-comment.html
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>
4
5
6 <h1><font color=#000070>
7 Ogg Vorbis I format specification: comment field and header specification
8 </font></h1>
9
10 <em>Last update to this document: July 16, 2002</em><p>
11
12 <h1>Overview</h1>
13
14 <p>The Vorbis text comment header is the second (of three) header
15 packets that begin a Vorbis bitstream. It is meant for short, text
16 comments, not arbitrary metadata; arbitrary metadata belongs in a
17 separate logical bitstream (usually an XML stream type) that provides
18 greater structure and machine parseability.
19
20 <p>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:
26
27 <blockquote>
28 "Honest Bob and the Factory-to-Dealer-Incentives, _I'm Still Around_,
29 opening for Moxy Fruvous, 1997"
30 </blockquote>
31
32 <h1>Comment encoding</h1>
33
34
35 <h2>Structure</h2>
36
37 The comment header logically is a list of eight-bit-clean vectors; the
38 number of vectors is bounded to 2^32-1 and the length of each vector
39 is limited to 2^32-1 bytes. The vector length is encoded; the vector
40 contents themselves are not null terminated. In addition to the vector
41 list, there is a single vector for vendor name (also 8 bit clean,
42 length encoded in 32 bits). Libvorbis currently sets the vendor string
43 to "Xiph.Org libVorbis I 20020717".<p>
44
45 The comment header is decoded as follows:<p>
46
47 <pre>
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
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      }
57
58   7) [framing_bit] = read a single bit as boolean
59   8) if ( [framing_bit]  unset or end of packet ) then ERROR
60   9) done.
61 </pre>
62
63
64 <h2>Content vector format</h2>
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 field value and
68 look like:
69
70 <pre>
71 comment[0]="ARTIST=me"; 
72 comment[1]="TITLE=the sound of Vorbis"; 
73 </pre>
74
75 <ul>
76 <li>A case-insensitive field name that may consist of ASCII 0x20 through
77 0x7D, 0x3D ('=') excluded. ASCII 0x41 through 0x5A inclusive (A-Z) is
78 to be considered equivalent to ASCII 0x61 through 0x7A inclusive
79 (a-z).
80
81 <li>The field name is immediately followed by ASCII 0x3D ('='); this
82 equals sign is used to terminate the field name.
83
84 <li>0x3D is followed by 8 bit clean UTF-8 encoded field contents
85 to the end of the field.
86 </ul>
87
88 <h3>Field names</h3>
89
90 Below is a proposed, minimal list of standard filed names with a
91 description of intended use.  No single or group of field names is
92 mandatory; a comment header may contain one, all or none of the names
93 in this list.<p>
94
95 <dl>
96 <dt>TITLE<dd>Track/Work name
97
98 <dt>VERSION<dd>The version field may be used to differentiate multiple
99 versions of the same track title in a single collection. (e.g. remix info)
100
101 <dt>ALBUM<dd>The collection name to which this track belongs
102
103 <dt>TRACKNUMBER<dd>The track number of this piece if part of a specific larger collection or album
104
105 <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.
106
107 <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 omitted.
108
109 <dt>COPYRIGHT<dd>Copyright attribution, e.g., '2001 Nobody's Band' or '1999 Jack Moffitt'
110
111 <dt>LICENSE<dd>License information, eg, 'All Rights Reserved', 'Any
112 Use Permitted', a URL to a license such as a Creative Commons license
113 ("www.creativecommons.org/blahblah/license.html") or the EFF Open
114 Audio License ('distributed under the terms of the Open Audio
115 License. see http://www.eff.org/IP/Open_licenses/eff_oal.html for
116 details'), etc.
117
118 <dt>ORGANIZATION<dd>Name of the organization producing the track (i.e.
119 the 'record label')
120
121 <dt>DESCRIPTION<dd>A short text description of the contents
122
123 <dt>GENRE<dd>A short text indication of music genre
124
125 <dt>DATE<dd>Date the track was recorded
126
127 <dt>LOCATION<dd>Location where track was recorded
128
129 <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.
130
131 <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.
132
133 </dl>
134
135 <h3>Implications</h3>
136 <ul>
137 <li>
138 Field names should not be 'internationalized'; this is a
139 concession to simplicity not an attempt to exclude the majority of
140 the world that doesn't speak English. Field *contents*, however,
141 are represented in UTF-8 to allow easy representation of any language.
142 <li>
143 We have the length of the entirety of the field and restrictions on
144 the field name so that the field name is bounded in a known way. Thus
145 we also have the length of the field contents.
146 <li>
147 Individual 'vendors' may use non-standard field names within
148 reason. The proper use of comment fields should be clear through
149 context at this point.  Abuse will be discouraged.
150 <li>
151 There is no vendor-specific prefix to 'nonstandard' field names.
152 Vendors should make some effort to avoid arbitrarily polluting the
153 common namespace. We will generally collect the more useful tags
154 here to help with standardization.
155 <li>
156 Field names are not required to be unique (occur once) within a
157 comment header.  As an example, assume a track was recorded by three
158 well know artists; the following is permissible, and encouraged:
159 <pre>
160               ARTIST=Dizzy Gillespie 
161               ARTIST=Sonny Rollins 
162               ARTIST=Sonny Stitt 
163 </pre>
164
165 </ul>
166
167 <h2>Encoding</h2> 
168
169 The comment header comprises the entirety of the second bitstream
170 header packet.  Unlike the first bitstream header packet, it is not
171 generally the only packet on the second page and may not be restricted
172 to within the second bitstream page.  The length of the comment header
173 packet is [practically] unbounded.  The comment header packet is not
174 optional; it must be present in the bitstream even if it is
175 effectively empty.<p>
176
177 The comment header is encoded as follows (as per Ogg's standard
178 bitstream mapping which renders least-significant-bit of the word to be
179 coded into the least significant available bit of the current
180 bitstream octet first):
181
182 <ol>
183 <li>
184 Vendor string length (32 bit unsigned quantity specifying number of octets)
185
186 <li>
187 Vendor string ([vendor string length] octets coded from beginning of string to end of string, not null terminated)
188
189 <li>Number of comment fields (32 bit unsigned quantity specifying number of fields)
190
191 <li>Comment field 0 length (if [Number of comment fields]>0; 32 bit unsigned quantity specifying number of octets)
192
193 <li>
194 Comment field 0 ([Comment field 0 length] octets coded from beginning of string to end of string, not null terminated)
195  
196 <li>Comment field 1 length (if [Number of comment fields]>1...)...
197 </ol>
198
199 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()
200
201 <hr>
202 <a href="http://www.xiph.org/">
203 <img src="white-xifish.png" align=left border=0>
204 </a>
205 <font size=-2 color=#505050>
206
207 Ogg is a <a href="http://www.xiph.org">Xiph.org Foundation</a> effort
208 to protect essential tenets of Internet multimedia from corporate
209 hostage-taking; Open Source is the net's greatest tool to keep
210 everyone honest. See <a href="http://www.xiph.org/about.html">About
211 the Xiph.org Foundation</a> for details.
212 <p>
213
214 Ogg Vorbis is the first Ogg audio CODEC.  Anyone may freely use and
215 distribute the Ogg and Vorbis specification, whether in a private,
216 public or corporate capacity.  However, the Xiph.org Foundation and
217 the Ogg project (xiph.org) reserve the right to set the Ogg Vorbis
218 specification and certify specification compliance.<p>
219
220 Xiph.org's Vorbis software CODEC implementation is distributed under a
221 BSD-like license.  This does not restrict third parties from
222 distributing independent implementations of Vorbis software under
223 other licenses.<p>
224
225 Ogg, Vorbis, Xiph.org Foundation and their logos are trademarks (tm)
226 of the <a href="http://www.xiph.org/">Xiph.org Foundation</a>.  These
227 pages are copyright (C) 1994-2002 Xiph.org Foundation. All rights
228 reserved.<p>
229
230 </body>
231