xiph
/
vorbis
mirror of https://git.xiph.org/vorbis.git


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195
							<HTML><HEAD><TITLE>xiph.org: Ogg Vorbis documentation</TITLE>
<BODY bgcolor="#ffffff" text="#202020" link="#006666" vlink="#000000">
<nobr><img src="white-ogg.png"><img src="vorbisword2.png"></nobr><p>


<h1><font color=#000070>
Ogg Vorbis comment field specification
</font></h1>

<em>Last update to this document: June 16, 2000</em><p>

The 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
metadata stream (usually an XML stream type).<p>

<h2>Comment use rationale</h2>


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:

<blockquote>
"Honest Bob and the Factory-to-Dealer-Incentives, _I'm Still Around_,
opening for Moxy Fruvous, 1997"
</blockquote>

<h2>Structure</h2>

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
is 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). Libvorbis currently sets the vendor string to "Xiphophorus
libVorbis I 20000508".<p>

The comment vectors are structured similarly to a UNIX environment.
That is, comment fields consist of a field name and a field value and
look like:

<pre>
comment[0]="ARTIST=me"; 
comment[1]="TITLE=the sound of vorbis"; 
</pre>

<h2>Content vector format</h2>

<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>The field name is immediately followed by ASCII 0x3D ('='); this
equals sign is used to terminate the field name.

<li>0x3D is followed by 8 bit clean UTF-8 field contents to the end of
the field.
</ul>

<h3>Field names</h3>

Below is a proposed, minimal list of standard filed 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.
<dl>
<dt>TITLE<dd>Track name

<dt>VERSION<dd>The version field may be used to differentiate multiple version of the same track title in a single collection.

<dt>ALBUM<dd>The collection name to which this track belongs

<dt>ARTIST<dd>Track performer

<dt>ORGANIZATION<dd>Name of the organization producing the track (ie,
the 'record label')

<dt>DESCRIPTION<dd>A short text description of the contents

<dt>GENRE<dd>A short text indication of music genre

<dt>DATE<dd>Date the track was recorded

<dt>LOCATION<dd>Location where track was recorded

<dt>COPYRIGHT<dd>Copyright information
</dl>

<h3>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 *contents*, however,
are represented in UTF-8 to allow easy representation of any language.
<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>
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>
There is no vendor-specific prefix to 'nonstandard' field names.
Vendors should make some effort to avoid arbitrarily polluting the
common namespace.
<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:
<pre>
              ARTIST=Dizzy Gillespie 
              ARTIST=Sonny Rollins 
              ARTIST=Sonny Stitt 
</pre>

</ul>

<h2>Encoding</h2> 

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>

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):

<ol>
<li>
Vendor string length (32 bit unsigned quantity specifying number of octets)

<li>
Vendor string ([vendor string length] octets coded from beginning of string to end of string, not null terminated)

<li>Number of comment fields (32 bit unsigned quantity specifying number of fields)

<li>Comment field 0 length (if [Number of comment fields]>0; 32 bit unsigned quantity specifying number of octets)

<li>
Comment field 0 ([Comment field 0 length] octets coded from beginning of string to end of string, not null terminated)
 
<li>Comment field 1 length (if [Number of comment fields]>1...)...
</ol>

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()

<hr>
<a href="http://www.xiph.org/">
<img src="white-xifish.png" align=left border=0>
</a>
<font size=-2 color=#505050>

Ogg is a <a href="http://www.xiph.org">Xiphophorus</a> effort to
protect essential tenets of Internet multimedia from corporate
hostage-taking; Open Source is the net's greatest tool to keep
everyone honest. See <a href="http://www.xiph.org/about.html">About
Xiphophorus</a> for details.
<p>

Ogg Vorbis is the first Ogg audio CODEC.  Anyone may
freely use and distribute the Ogg and Vorbis specification,
whether in a private, public or corporate capacity.  However,
Xiphophorus and the Ogg project (xiph.org) reserve the right to set
the Ogg/Vorbis specification and certify specification compliance.<p>

Xiphophorus's Vorbis software CODEC implementation is distributed
under the Lesser/Library GNU Public License.  This does not restrict
third parties from distributing independent implementations of Vorbis
software under other licenses.<p>

OggSquish, Vorbis, Xiphophorus and their logos are trademarks (tm) of
<a href="http://www.xiph.org/">Xiphophorus</a>.  These pages are
copyright (C) 1994-2000 Xiphophorus. All rights reserved.<p>

</body>