X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=doc%2Fv-comment.html;h=4b64d27d2b2b4d730ef071a8f8d1b953c2998543;hb=33d292c235daba602245740f0f0f29e331d91c0e;hp=eebffb09a4474e3916a384fff5ac3d29dbcc8ad3;hpb=6ff75aa0afc00e28324277531bd2a23d26499543;p=platform%2Fupstream%2Flibvorbis.git diff --git a/doc/v-comment.html b/doc/v-comment.html index eebffb0..4b64d27 100644 --- a/doc/v-comment.html +++ b/doc/v-comment.html @@ -1,202 +1,285 @@ -xiph.org: Ogg Vorbis documentation - -

- - -

-Ogg Vorbis comment field specification -

- -Last update to this document: October 2, 2001

- -

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 separate -logical bitream (usually an XML stream type) that provides greater -structure and machine parseability.

- -

Comment use rationale

- -The comment field is meant to be used much like someone jotting a + + + + + +Ogg Vorbis Documentation + + + + + + + +

+ +

Ogg Vorbis I format specification: comment field and header specification

+ +

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: +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" -
+opening for Moxy Früvous, 1997" +

+ +

Comment encoding

Structure

-The comment header logically is a list of eight-bit-clean vectors; the +

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 20010910".

+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".

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

The comment header is decoded as follows:

-comment[0]="ARTIST=me"; 
-comment[1]="TITLE=the sound of vorbis"; 
+  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.

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 corresponding 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. +(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 the 8 bit clean UTF-8 encoded value of the +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 +

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. +in this list.

TITLE: Track 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) +
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 +
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 +
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. +
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 ommitted. +
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.
ORGANIZATION: Name of the organization producing the track (i.e. -the 'record label') +
COPYRIGHT: Copyright attribution, e.g., '2001 Nobody's Band' or '1999 Jack Moffitt'
DESCRIPTION: A short text description of the contents +
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.
GENRE: A short text indication of music genre +
ORGANIZATION: Name of the organization producing the track (i.e. +the 'record label')
DATE: Date the track was recorded +
DESCRIPTION: A short text description of the contents
LOCATION: Location where track was recorded +
GENRE: A short text indication of music genre
COPYRIGHT: Copyright and license information (e.g. '(c) 2001 Nobody's Band. All rights reserved' or '(c) 1999 Jack Moffit, distributed under the terms of the Open Audio License. see http://www.eff.org/IP/Open_licenses/eff_oal.html for details') +
DATE: Date the 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. +
LOCATION: Location where track was recorded
ISRC: ISRC number for the track; see the ISRC intro page for more information on ISRC numbers. +
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.
DISCID: Table of contents hash from an associated disc, generally used to index the track in published music databases. See http://freedb.org/ for and example of such a hash. +
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 +
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. -
-We have the length of the entirety of the field and restrictions on +the world that doesn't speak English. Field contents, +however, use the UTF-8 character encoding 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 +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. +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 +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 +

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 +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.

+effectively empty.

-The comment header is encoded as follows (as per Ogg's standard +

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): +bitstream octet first):

-Vendor string length (32 bit unsigned quantity specifying number of octets) - -
-Vendor string ([vendor string length] octets coded from beginning 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 beginning of string to end of string, not null terminated) - -
Comment field 1 length (if [Number of comment fields]>1...)... +
Vendor string length (32 bit unsigned quantity specifying number of octets)
Vendor string ([vendor string length] octets coded from beginning 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 beginning 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() - -

- -

- - +

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 Xiphophorus 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 -Xiphophorus for details. -

+ The Xiph Fish Logo is a + trademark (™) of Xiph.Org.
-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.

- -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.

- +