VirtualBox

source: vbox/trunk/src/libs/libvorbis-1.3.7/doc/v-comment.html@ 103131

Last change on this file since 103131 was 96468, checked in by vboxsync, 2 years ago

libs/libvorbis-1.3.7: Re-exporting, hopefully this time everything is there. bugref:10275

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 8.8 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
2<html>
3<head>
4
5<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
6<title>Ogg Vorbis Documentation</title>
7
8<style type="text/css">
9body {
10 margin: 0 18px 0 18px;
11 padding-bottom: 30px;
12 font-family: Verdana, Arial, Helvetica, sans-serif;
13 color: #333333;
14 font-size: .8em;
15}
16
17a {
18 color: #3366cc;
19}
20
21img {
22 border: 0;
23}
24
25#xiphlogo {
26 margin: 30px 0 16px 0;
27}
28
29#content p {
30 line-height: 1.4;
31}
32
33h1, h1 a, h2, h2 a, h3, h3 a {
34 font-weight: bold;
35 color: #ff9900;
36 margin: 1.3em 0 8px 0;
37}
38
39h1 {
40 font-size: 1.3em;
41}
42
43h2 {
44 font-size: 1.2em;
45}
46
47h3 {
48 font-size: 1.1em;
49}
50
51li {
52 line-height: 1.4;
53}
54
55#copyright {
56 margin-top: 30px;
57 line-height: 1.5em;
58 text-align: center;
59 font-size: .8em;
60 color: #888888;
61 clear: both;
62}
63</style>
64
65</head>
66
67<body>
68
69<div id="xiphlogo">
70 <a href="https://xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.Org"/></a>
71</div>
72
73<h1>Ogg Vorbis I format specification: comment field and header specification</h1>
74
75<h1 id="overview">Overview</h1>
76
77<p>The Vorbis text comment header is the second (of three) header
78packets that begin a Vorbis bitstream. It is meant for short, text
79comments, not arbitrary metadata; arbitrary metadata belongs in a
80separate logical bitstream (usually an XML stream type) that provides
81greater structure and machine parseability.</p>
82
83<p>The comment field is meant to be used much like someone jotting a
84quick note on the bottom of a CDR. It should be a little information to
85remember the disc by and explain it to others; a short, to-the-point
86text note that need not only be a couple words, but isn't going to be
87more than a short paragraph. The essentials, in other words, whatever
88they turn out to be, eg:</p>
89
90<blockquote><p>
91"Honest Bob and the Factory-to-Dealer-Incentives, _I'm Still Around_,
92opening for Moxy Fr&uuml;vous, 1997"
93</p></blockquote>
94
95<h1 id="commentencoding">Comment encoding</h1>
96
97<h2 id="structure">Structure</h2>
98
99<p>The comment header logically is a list of eight-bit-clean vectors; the
100number of vectors is bounded to 2^32-1 and the length of each vector
101is limited to 2^32-1 bytes. The vector length is encoded; the vector
102contents themselves are not null terminated. In addition to the vector
103list, there is a single vector for vendor name (also 8 bit clean,
104length encoded in 32 bits). For example, the 1.0 release of libvorbis
105set the vendor string to "Xiph.Org libVorbis I 20020717".</p>
106
107<p>The comment header is decoded as follows:</p>
108
109<pre>
110 1) [vendor_length] = read an unsigned integer of 32 bits
111 2) [vendor_string] = read a UTF-8 vector as [vendor_length] octets
112 3) [user_comment_list_length] = read an unsigned integer of 32 bits
113 4) iterate [user_comment_list_length] times {
114
115 5) [length] = read an unsigned integer of 32 bits
116 6) this iteration's user comment = read a UTF-8 vector as [length] octets
117
118 }
119
120 7) [framing_bit] = read a single bit as boolean
121 8) if ( [framing_bit] unset or end of packet ) then ERROR
122 9) done.
123</pre>
124
125<h2 id="vectorformat">Content vector format</h2>
126
127<p>The comment vectors are structured similarly to a UNIX environment variable.
128That is, comment fields consist of a field name and a corresponding value and
129look like:</p>
130
131<pre>
132comment[0]="ARTIST=me";
133comment[1]="TITLE=the sound of Vorbis";
134</pre>
135
136<ul>
137<li>A case-insensitive field name that may consist of ASCII 0x20 through
1380x7D, 0x3D ('=') excluded. ASCII 0x41 through 0x5A inclusive (A-Z) is
139to be considered equivalent to ASCII 0x61 through 0x7A inclusive
140(a-z).</li>
141<li>The field name is immediately followed by ASCII 0x3D ('=');
142this equals sign is used to terminate the field name.</li>
143<li>0x3D is followed by the 8 bit clean UTF-8 encoded value of the
144field contents to the end of the field.</li>
145</ul>
146
147<h3 id="fieldnames">Field names</h3>
148
149<p>Below is a proposed, minimal list of standard field names with a
150description of intended use. No single or group of field names is
151mandatory; a comment header may contain one, all or none of the names
152in this list.</p>
153
154<dl>
155
156<dt>TITLE</dt>
157<dd>Track/Work name</dd>
158
159<dt>VERSION</dt>
160<dd>The version field may be used to differentiate multiple
161versions of the same track title in a single collection.
162(e.g. remix info)</dd>
163
164<dt>ALBUM</dt>
165<dd>The collection name to which this track belongs</dd>
166
167<dt>TRACKNUMBER</dt>
168<dd>The track number of this piece if part of a specific larger collection or album</dd>
169
170<dt>ARTIST</dt>
171<dd>The artist generally considered responsible for the work. In popular music
172this is usually the performing band or singer. For classical music it would be
173the composer. For an audio book it would be the author of the original text.</dd>
174
175<dt>PERFORMER</dt>
176<dd>The artist(s) who performed the work. In classical music this would be the
177conductor, orchestra, soloists. In an audio book it would be the actor who did
178the reading. In popular music this is typically the same as the ARTIST and
179is omitted.</dd>
180
181<dt>COPYRIGHT</dt>
182<dd>Copyright attribution, e.g., '2001 Nobody's Band' or '1999 Jack Moffitt'</dd>
183
184<dt>LICENSE</dt>
185<dd>License information, for example, 'All Rights Reserved', 'Any
186Use Permitted', a URL to a license such as a Creative Commons license
187(e.g. "creativecommons.org/licenses/by/4.0/"), or similar.</dd>
188
189<dt>ORGANIZATION</dt>
190<dd>Name of the organization producing the track (i.e.
191the 'record label')</dd>
192
193<dt>DESCRIPTION</dt>
194<dd>A short text description of the contents</dd>
195
196<dt>GENRE</dt>
197<dd>A short text indication of music genre</dd>
198
199<dt>DATE</dt>
200<dd>Date the track was recorded</dd>
201
202<dt>LOCATION</dt>
203<dd>Location where track was recorded</dd>
204
205<dt>CONTACT</dt>
206<dd>Contact information for the creators or distributors of the track.
207This could be a URL, an email address, the physical address of
208the producing label.</dd>
209
210<dt>ISRC</dt>
211<dd>ISRC number for the track; see <a href="https://isrc.ifpi.org/">the
212ISRC intro page</a> for more information on ISRC numbers.</dd>
213
214</dl>
215
216<h3 id="implications">Implications</h3>
217
218<ul>
219<li>Field names should not be 'internationalized'; this is a
220concession to simplicity not an attempt to exclude the majority of
221the world that doesn't speak English. Field <emph>contents</emph>,
222however, use the UTF-8 character encoding to allow easy representation
223of any language.</li>
224<li>We have the length of the entirety of the field and restrictions on
225the field name so that the field name is bounded in a known way. Thus
226we also have the length of the field contents.</li>
227<li>Individual 'vendors' may use non-standard field names within
228reason. The proper use of comment fields should be clear through
229context at this point. Abuse will be discouraged.</li>
230<li>There is no vendor-specific prefix to 'nonstandard' field names.
231Vendors should make some effort to avoid arbitrarily polluting the
232common namespace. We will generally collect the more useful tags
233here to help with standardization.</li>
234<li>Field names are not required to be unique (occur once) within a
235comment header. As an example, assume a track was recorded by three
236well know artists; the following is permissible, and encouraged:
237<pre>
238 ARTIST=Dizzy Gillespie
239 ARTIST=Sonny Rollins
240 ARTIST=Sonny Stitt
241</pre></li>
242</ul>
243
244<h2 id="encoding">Encoding</h2>
245
246<p>The comment header comprises the entirety of the second bitstream
247header packet. Unlike the first bitstream header packet, it is not
248generally the only packet on the second page and may not be restricted
249to within the second bitstream page. The length of the comment header
250packet is (practically) unbounded. The comment header packet is not
251optional; it must be present in the bitstream even if it is
252effectively empty.</p>
253
254<p>The comment header is encoded as follows (as per Ogg's standard
255bitstream mapping which renders least-significant-bit of the word to be
256coded into the least significant available bit of the current
257bitstream octet first):</p>
258
259<ol>
260<li>Vendor string length (32 bit unsigned quantity specifying number of octets)</li>
261<li>Vendor string ([vendor string length] octets coded from beginning of string
262to end of string, not null terminated)</li>
263<li>Number of comment fields (32 bit unsigned quantity specifying number of fields)</li>
264<li>Comment field 0 length (if [Number of comment fields]>0; 32 bit unsigned
265quantity specifying number of octets)</li>
266<li>Comment field 0 ([Comment field 0 length] octets coded from beginning of
267string to end of string, not null terminated)</li>
268<li>Comment field 1 length (if [Number of comment fields]>1...)...</li>
269</ol>
270
271<p>This is actually somewhat easier to describe in code; implementation of the above
272can be found in vorbis/lib/info.c:_vorbis_pack_comment(),_vorbis_unpack_comment()</p>
273
274<div id="copyright">
275 The Xiph Fish Logo is a
276 trademark (&trade;) of Xiph.Org.<br/>
277
278 These pages &copy; 1994 - 2005 Xiph.Org. All rights reserved.
279</div>
280
281</body>
282</html>
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette