mirror of
https://github.com/etlegacy/etlegacy-libs.git
synced 2024-11-10 14:51:58 +00:00
285 lines
9 KiB
HTML
285 lines
9 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html>
|
|
<head>
|
|
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
|
|
<title>Ogg Vorbis Documentation</title>
|
|
|
|
<style type="text/css">
|
|
body {
|
|
margin: 0 18px 0 18px;
|
|
padding-bottom: 30px;
|
|
font-family: Verdana, Arial, Helvetica, sans-serif;
|
|
color: #333333;
|
|
font-size: .8em;
|
|
}
|
|
|
|
a {
|
|
color: #3366cc;
|
|
}
|
|
|
|
img {
|
|
border: 0;
|
|
}
|
|
|
|
#xiphlogo {
|
|
margin: 30px 0 16px 0;
|
|
}
|
|
|
|
#content p {
|
|
line-height: 1.4;
|
|
}
|
|
|
|
h1, h1 a, h2, h2 a, h3, h3 a {
|
|
font-weight: bold;
|
|
color: #ff9900;
|
|
margin: 1.3em 0 8px 0;
|
|
}
|
|
|
|
h1 {
|
|
font-size: 1.3em;
|
|
}
|
|
|
|
h2 {
|
|
font-size: 1.2em;
|
|
}
|
|
|
|
h3 {
|
|
font-size: 1.1em;
|
|
}
|
|
|
|
li {
|
|
line-height: 1.4;
|
|
}
|
|
|
|
#copyright {
|
|
margin-top: 30px;
|
|
line-height: 1.5em;
|
|
text-align: center;
|
|
font-size: .8em;
|
|
color: #888888;
|
|
clear: both;
|
|
}
|
|
</style>
|
|
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<div id="xiphlogo">
|
|
<a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.Org"/></a>
|
|
</div>
|
|
|
|
<h1>Ogg Vorbis I format specification: comment field and header specification</h1>
|
|
|
|
<h1 id="overview">Overview</h1>
|
|
|
|
<p>The Vorbis text comment header is the second (of three) header
|
|
packets that begin a Vorbis bitstream. It is meant for short, text
|
|
comments, not arbitrary metadata; arbitrary metadata belongs in a
|
|
separate logical bitstream (usually an XML stream type) that provides
|
|
greater structure and machine parseability.</p>
|
|
|
|
<p>The comment field is meant to be used much like someone jotting a
|
|
quick note on the bottom of a CDR. It should be a little information to
|
|
remember the disc by and explain it to others; a short, to-the-point
|
|
text note that need not only be a couple words, but isn't going to be
|
|
more than a short paragraph. The essentials, in other words, whatever
|
|
they turn out to be, eg:</p>
|
|
|
|
<blockquote><p>
|
|
"Honest Bob and the Factory-to-Dealer-Incentives, _I'm Still Around_,
|
|
opening for Moxy Früvous, 1997"
|
|
</p></blockquote>
|
|
|
|
<h1 id="commentencoding">Comment encoding</h1>
|
|
|
|
<h2 id="structure">Structure</h2>
|
|
|
|
<p>The comment header logically is a list of eight-bit-clean vectors; the
|
|
number of vectors is bounded to 2^32-1 and the length of each vector
|
|
is limited to 2^32-1 bytes. The vector length is encoded; the vector
|
|
contents themselves are not null terminated. In addition to the vector
|
|
list, there is a single vector for vendor name (also 8 bit clean,
|
|
length encoded in 32 bits). For example, the 1.0 release of libvorbis
|
|
set the vendor string to "Xiph.Org libVorbis I 20020717".</p>
|
|
|
|
<p>The comment header is decoded as follows:</p>
|
|
|
|
<pre>
|
|
1) [vendor_length] = read an unsigned integer of 32 bits
|
|
2) [vendor_string] = read a UTF-8 vector as [vendor_length] octets
|
|
3) [user_comment_list_length] = read an unsigned integer of 32 bits
|
|
4) iterate [user_comment_list_length] times {
|
|
|
|
5) [length] = read an unsigned integer of 32 bits
|
|
6) this iteration's user comment = read a UTF-8 vector as [length] octets
|
|
|
|
}
|
|
|
|
7) [framing_bit] = read a single bit as boolean
|
|
8) if ( [framing_bit] unset or end of packet ) then ERROR
|
|
9) done.
|
|
</pre>
|
|
|
|
<h2 id="vectorformat">Content vector format</h2>
|
|
|
|
<p>The comment vectors are structured similarly to a UNIX environment variable.
|
|
That is, comment fields consist of a field name and a corresponding value and
|
|
look like:</p>
|
|
|
|
<pre>
|
|
comment[0]="ARTIST=me";
|
|
comment[1]="TITLE=the sound of Vorbis";
|
|
</pre>
|
|
|
|
<ul>
|
|
<li>A case-insensitive field name that may consist of ASCII 0x20 through
|
|
0x7D, 0x3D ('=') excluded. ASCII 0x41 through 0x5A inclusive (A-Z) is
|
|
to be considered equivalent to ASCII 0x61 through 0x7A inclusive
|
|
(a-z).</li>
|
|
<li>The field name is immediately followed by ASCII 0x3D ('=');
|
|
this equals sign is used to terminate the field name.</li>
|
|
<li>0x3D is followed by the 8 bit clean UTF-8 encoded value of the
|
|
field contents to the end of the field.</li>
|
|
</ul>
|
|
|
|
<h3 id="fieldnames">Field names</h3>
|
|
|
|
<p>Below is a proposed, minimal list of standard field names with a
|
|
description of intended use. No single or group of field names is
|
|
mandatory; a comment header may contain one, all or none of the names
|
|
in this list.</p>
|
|
|
|
<dl>
|
|
|
|
<dt>TITLE</dt>
|
|
<dd>Track/Work name</dd>
|
|
|
|
<dt>VERSION</dt>
|
|
<dd>The version field may be used to differentiate multiple
|
|
versions of the same track title in a single collection.
|
|
(e.g. remix info)</dd>
|
|
|
|
<dt>ALBUM</dt>
|
|
<dd>The collection name to which this track belongs</dd>
|
|
|
|
<dt>TRACKNUMBER</dt>
|
|
<dd>The track number of this piece if part of a specific larger collection or album</dd>
|
|
|
|
<dt>ARTIST</dt>
|
|
<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.</dd>
|
|
|
|
<dt>PERFORMER</dt>
|
|
<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.</dd>
|
|
|
|
<dt>COPYRIGHT</dt>
|
|
<dd>Copyright attribution, e.g., '2001 Nobody's Band' or '1999 Jack Moffitt'</dd>
|
|
|
|
<dt>LICENSE</dt>
|
|
<dd>License information, eg, 'All Rights Reserved', 'Any
|
|
Use Permitted', a URL to a license such as a Creative Commons license
|
|
("www.creativecommons.org/blahblah/license.html") or the EFF Open
|
|
Audio License ('distributed under the terms of the Open Audio
|
|
License. see http://www.eff.org/IP/Open_licenses/eff_oal.html for
|
|
details'), etc.</dd>
|
|
|
|
<dt>ORGANIZATION</dt>
|
|
<dd>Name of the organization producing the track (i.e.
|
|
the 'record label')</dd>
|
|
|
|
<dt>DESCRIPTION</dt>
|
|
<dd>A short text description of the contents</dd>
|
|
|
|
<dt>GENRE</dt>
|
|
<dd>A short text indication of music genre</dd>
|
|
|
|
<dt>DATE</dt>
|
|
<dd>Date the track was recorded</dd>
|
|
|
|
<dt>LOCATION</dt>
|
|
<dd>Location where track was recorded</dd>
|
|
|
|
<dt>CONTACT</dt>
|
|
<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.</dd>
|
|
|
|
<dt>ISRC</dt>
|
|
<dd>ISRC number for the track; see <a href="http://www.ifpi.org/isrc/">the
|
|
ISRC intro page</a> for more information on ISRC numbers.</dd>
|
|
|
|
</dl>
|
|
|
|
<h3 id="implications">Implications</h3>
|
|
|
|
<ul>
|
|
<li>Field names should not be 'internationalized'; this is a
|
|
concession to simplicity not an attempt to exclude the majority of
|
|
the world that doesn't speak English. Field <emph>contents</emph>,
|
|
however, use the UTF-8 character encoding to allow easy representation
|
|
of any language.</li>
|
|
<li>We have the length of the entirety of the field and restrictions on
|
|
the field name so that the field name is bounded in a known way. Thus
|
|
we also have the length of the field contents.</li>
|
|
<li>Individual 'vendors' may use non-standard field names within
|
|
reason. The proper use of comment fields should be clear through
|
|
context at this point. Abuse will be discouraged.</li>
|
|
<li>There is no vendor-specific prefix to 'nonstandard' field names.
|
|
Vendors should make some effort to avoid arbitrarily polluting the
|
|
common namespace. We will generally collect the more useful tags
|
|
here to help with standardization.</li>
|
|
<li>Field names are not required to be unique (occur once) within a
|
|
comment header. As an example, assume a track was recorded by three
|
|
well know artists; the following is permissible, and encouraged:
|
|
<pre>
|
|
ARTIST=Dizzy Gillespie
|
|
ARTIST=Sonny Rollins
|
|
ARTIST=Sonny Stitt
|
|
</pre></li>
|
|
</ul>
|
|
|
|
<h2 id="encoding">Encoding</h2>
|
|
|
|
<p>The comment header comprises the entirety of the second bitstream
|
|
header packet. Unlike the first bitstream header packet, it is not
|
|
generally the only packet on the second page and may not be restricted
|
|
to within the second bitstream page. The length of the comment header
|
|
packet is (practically) unbounded. The comment header packet is not
|
|
optional; it must be present in the bitstream even if it is
|
|
effectively empty.</p>
|
|
|
|
<p>The comment header is encoded as follows (as per Ogg's standard
|
|
bitstream mapping which renders least-significant-bit of the word to be
|
|
coded into the least significant available bit of the current
|
|
bitstream octet first):</p>
|
|
|
|
<ol>
|
|
<li>Vendor string length (32 bit unsigned quantity specifying number of octets)</li>
|
|
<li>Vendor string ([vendor string length] octets coded from beginning of string
|
|
to end of string, not null terminated)</li>
|
|
<li>Number of comment fields (32 bit unsigned quantity specifying number of fields)</li>
|
|
<li>Comment field 0 length (if [Number of comment fields]>0; 32 bit unsigned
|
|
quantity specifying number of octets)</li>
|
|
<li>Comment field 0 ([Comment field 0 length] octets coded from beginning of
|
|
string to end of string, not null terminated)</li>
|
|
<li>Comment field 1 length (if [Number of comment fields]>1...)...</li>
|
|
</ol>
|
|
|
|
<p>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()</p>
|
|
|
|
<div id="copyright">
|
|
The Xiph Fish Logo is a
|
|
trademark (™) of Xiph.Org.<br/>
|
|
|
|
These pages © 1994 - 2005 Xiph.Org. All rights reserved.
|
|
</div>
|
|
|
|
</body>
|
|
</html>
|