云
云中女孩
Unregistered / Unconfirmed
GUEST, unregistred user!
Ogg Vorbis I format specification: comment field and header specification
Last update to thisdo
cument: July 16, 2002
Overview
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.
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:
"Honest Bob and the Factory-to-Dealer-Incentives, _I'm Still Around_, opening
for Moxy Fruvous, 1997"
Comment encoding
Structure
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). Libvorbis currently sets the
vendor string to "Xiph.Org libVorbis I 20020717".
The comment header is decoded as follows:
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)do
ne.
Content vector format
The comment vectors are structured similarly to a UNIX environment variable.
That is, comment fields consist of a field name and a field value and look like:
comment[0]="ARTIST=me";
comment[1]="TITLE=the sound of Vorbis";
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).
The field name is immediately followed by ASCII 0x3D ('=');
this equals sign
is used to terminate the field name.
0x3D is followed by 8 bit clean UTF-8 encoded field contents to the end of the
field.
Field names
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.
TITLE
Track/Work name
VERSION
The version field may be used to differentiate multiple versions of the same
track title in a single collection. (e.g. remix info)
ALBUM
The collection name to which this track belongs
TRACKNUMBER
The track number of this piece if part of a specific larger collection or
album
ARTIST
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.
PERFORMER
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.
COPYRIGHT
Copyright attribution, e.g., '2001 Nobody's Band' or '1999 Jack Moffitt'
LICENSE
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.
ORGANIZATION
Name of the organization producing the track (i.e. the 'record label')
DESCRIPTION
A short text description of the contents
GENRE
A short text indication of music genre
DATE
Date the track was recorded
LOCATION
Location where track was recorded
CONTACT
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.
ISRC
ISRC number for the track;
see the ISRC intro page for more information on
ISRC numbers.
Implications
Field names should not be 'internationalized';
this is a concession to
simplicity not an attempt to exclude the majority of the world thatdo
esn't
speak English. Field *contents*, however, are represented in UTF-8 to allow
easy representation of any language.
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.
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.
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.
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:
ARTIST=Dizzy Gillespie
ARTIST=Sonny Rollins
ARTIST=Sonny Stitt
Encoding
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.
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):
Vendor string length (32 bit unsigned quantity specifying number of octets)
Vendor string ([vendor string length] octets coded from begin
ning of string to
end of string, not null terminated)
Number of comment fields (32 bit unsigned quantity specifying number of
fields)
Comment field 0 length (if [Number of comment fields]>0;
32 bit unsigned
quantity specifying number of octets)
Comment field 0 ([Comment field 0 length] octets coded from begin
ning of
string to end of string, not null terminated)
Comment field 1 length (if [Number of comment fields]>1...)...
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()
Ogg is a Xiph.org Foundation 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 About the Xiph.org Foundation for details.
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, the Xiph.org Foundation and the Ogg project (xiph.org)
reserve the right to set the Ogg Vorbis specification and certify specification
compliance.
Xiph.org's Vorbis software CODEC implementation is distributed under a BSD-like
license. Thisdo
es not restrict third parties from distributing independent
implementations of Vorbis software under other licenses.
Ogg, Vorbis, Xiph.org Foundation and their logos are trademarks (tm) of the
Xiph.org Foundation. These pages are copyright (C) 1994-2002 Xiph.org
Foundation. All rights reserved.
Last update to thisdo
cument: July 16, 2002
Overview
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.
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:
"Honest Bob and the Factory-to-Dealer-Incentives, _I'm Still Around_, opening
for Moxy Fruvous, 1997"
Comment encoding
Structure
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). Libvorbis currently sets the
vendor string to "Xiph.Org libVorbis I 20020717".
The comment header is decoded as follows:
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)do
ne.
Content vector format
The comment vectors are structured similarly to a UNIX environment variable.
That is, comment fields consist of a field name and a field value and look like:
comment[0]="ARTIST=me";
comment[1]="TITLE=the sound of Vorbis";
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).
The field name is immediately followed by ASCII 0x3D ('=');
this equals sign
is used to terminate the field name.
0x3D is followed by 8 bit clean UTF-8 encoded field contents to the end of the
field.
Field names
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.
TITLE
Track/Work name
VERSION
The version field may be used to differentiate multiple versions of the same
track title in a single collection. (e.g. remix info)
ALBUM
The collection name to which this track belongs
TRACKNUMBER
The track number of this piece if part of a specific larger collection or
album
ARTIST
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.
PERFORMER
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.
COPYRIGHT
Copyright attribution, e.g., '2001 Nobody's Band' or '1999 Jack Moffitt'
LICENSE
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.
ORGANIZATION
Name of the organization producing the track (i.e. the 'record label')
DESCRIPTION
A short text description of the contents
GENRE
A short text indication of music genre
DATE
Date the track was recorded
LOCATION
Location where track was recorded
CONTACT
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.
ISRC
ISRC number for the track;
see the ISRC intro page for more information on
ISRC numbers.
Implications
Field names should not be 'internationalized';
this is a concession to
simplicity not an attempt to exclude the majority of the world thatdo
esn't
speak English. Field *contents*, however, are represented in UTF-8 to allow
easy representation of any language.
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.
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.
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.
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:
ARTIST=Dizzy Gillespie
ARTIST=Sonny Rollins
ARTIST=Sonny Stitt
Encoding
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.
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):
Vendor string length (32 bit unsigned quantity specifying number of octets)
Vendor string ([vendor string length] octets coded from begin
ning of string to
end of string, not null terminated)
Number of comment fields (32 bit unsigned quantity specifying number of
fields)
Comment field 0 length (if [Number of comment fields]>0;
32 bit unsigned
quantity specifying number of octets)
Comment field 0 ([Comment field 0 length] octets coded from begin
ning of
string to end of string, not null terminated)
Comment field 1 length (if [Number of comment fields]>1...)...
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()
Ogg is a Xiph.org Foundation 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 About the Xiph.org Foundation for details.
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, the Xiph.org Foundation and the Ogg project (xiph.org)
reserve the right to set the Ogg Vorbis specification and certify specification
compliance.
Xiph.org's Vorbis software CODEC implementation is distributed under a BSD-like
license. Thisdo
es not restrict third parties from distributing independent
implementations of Vorbis software under other licenses.
Ogg, Vorbis, Xiph.org Foundation and their logos are trademarks (tm) of the
Xiph.org Foundation. These pages are copyright (C) 1994-2002 Xiph.org
Foundation. All rights reserved.