"Fossies" - the Fresh Open Source Software Archive

Member "quicktime4linux-2.3/thirdparty/libvorbis-1.1.1/doc/xml/05-comment.xml" (31 May 2008, 10070 Bytes) of package /linux/privat/old/quicktime4linux-2.3-src.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) XML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 <?xml version="1.0" standalone="no"?>
    2 <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
    3                 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
    4 <!ENTITY % isolat1 SYSTEM "http://www.oasis-open.org/docbook/xml/4.2/ent/iso-lat1.ent">
    5 %isolat1;
    6 ]>
    7 
    8 <section id="vorbis-spec-comment">
    9 <sectioninfo>
   10  <releaseinfo>
   11  $Id: 05-comment.xml 7186 2004-07-20 07:19:25Z xiphmont $
   12 </releaseinfo>
   13 </sectioninfo>
   14 <title>comment field and header specification</title>
   15 
   16 
   17 <section><title>Overview</title>
   18 
   19 <para>The Vorbis text comment header is the second (of three) header
   20 packets that begin a Vorbis bitstream. It is meant for short text
   21 comments, not arbitrary metadata; arbitrary metadata belongs in a
   22 separate logical bitstream (usually an XML stream type) that provides
   23 greater structure and machine parseability.</para>
   24 
   25 <para>The comment field is meant to be used much like someone jotting a
   26 quick note on the bottom of a CDR. It should be a little information to
   27 remember the disc by and explain it to others; a short, to-the-point
   28 text note that need not only be a couple words, but isn't going to be
   29 more than a short paragraph.  The essentials, in other words, whatever
   30 they turn out to be, eg:
   31 
   32 <blockquote>
   33 <simpara>Honest Bob and the Factory-to-Dealer-Incentives, <citetitle>I'm Still
   34 Around</citetitle>, opening for Moxy Fr&uuml;vous, 1997.</simpara>
   35 </blockquote>
   36 </para>
   37 
   38 </section>
   39 
   40 <section><title>Comment encoding</title>
   41 
   42 <section><title>Structure</title>
   43 
   44 <para>
   45 The comment header is logically a list of eight-bit-clean vectors; the
   46 number of vectors is bounded to 2^32-1 and the length of each vector
   47 is limited to 2^32-1 bytes. The vector length is encoded; the vector
   48 contents themselves are not null terminated. In addition to the vector
   49 list, there is a single vector for vendor name (also 8 bit clean,
   50 length encoded in 32 bits). The 1.0 release of libvorbis sets the 
   51 vendor string to "Xiph.Org libVorbis I 20020717".</para>
   52 
   53 <para>The comment header is decoded as follows:
   54 
   55 <programlisting>
   56   1) [vendor_length] = read an unsigned integer of 32 bits
   57   2) [vendor_string] = read a UTF-8 vector as [vendor_length] octets
   58   3) [user_comment_list_length] = read an unsigned integer of 32 bits
   59   4) iterate [user_comment_list_length] times {
   60        5) [length] = read an unsigned integer of 32 bits
   61        6) this iteration's user comment = read a UTF-8 vector as [length] octets
   62      }
   63   7) [framing_bit] = read a single bit as boolean
   64   8) if ( [framing_bit] unset or end-of-packet ) then ERROR
   65   9) done.
   66 </programlisting>
   67 </para>
   68 
   69 </section>
   70 
   71 <section><title>Content vector format</title>
   72 
   73 <para>
   74 The comment vectors are structured similarly to a UNIX environment variable.
   75 That is, comment fields consist of a field name and a corresponding value and
   76 look like:</para>
   77 
   78 <blockquote><programlisting>
   79 comment[0]="ARTIST=me"; 
   80 comment[1]="TITLE=the sound of Vorbis"; 
   81 </programlisting></blockquote>
   82 
   83 <para>
   84 The field name is case-insensitive and may consist of ASCII 0x20
   85 through 0x7D, 0x3D ('=') excluded. ASCII 0x41 through 0x5A inclusive
   86 (characters A-Z) is to be considered equivalent to ASCII 0x61 through 
   87 0x7A inclusive (characters a-z).
   88 </para>
   89 
   90 <para>
   91 The field name is immediately followed by ASCII 0x3D ('=');
   92 this equals sign is used to terminate the field name.
   93 </para>
   94 
   95 <para>
   96 0x3D is followed by 8 bit clean UTF-8 encoded value of the
   97 field contents to the end of the field.
   98 </para>
   99 
  100 <section><title>Field names</title>
  101 
  102 <para>Below is a proposed, minimal list of standard field names with a
  103 description of intended use.  No single or group of field names is
  104 mandatory; a comment header may contain one, all or none of the names
  105 in this list.</para>
  106 
  107 <variablelist>
  108 <varlistentry>
  109 <term>TITLE</term>
  110 <listitem>
  111 <simpara>Track/Work name</simpara>
  112 </listitem>
  113 </varlistentry>
  114 <varlistentry>
  115  <term>VERSION</term>
  116 <listitem>
  117  <simpara>The version field may be used to
  118 differentiate multiple
  119 versions of the same track title in a single collection. (e.g. remix
  120 info)
  121 </simpara></listitem>
  122 </varlistentry>
  123 
  124 <varlistentry><term>ALBUM</term><listitem><simpara>The collection name to which this track belongs
  125 </simpara></listitem>
  126 </varlistentry>
  127 
  128 <varlistentry><term>TRACKNUMBER</term>
  129 <listitem><simpara>The track number of this piece if part of a specific larger collection or album
  130 </simpara></listitem>
  131 </varlistentry>
  132 
  133 <varlistentry><term>ARTIST</term>
  134 <listitem><simpara>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.
  135 </simpara></listitem>
  136 </varlistentry>
  137 
  138 <varlistentry><term>PERFORMER</term>
  139 <listitem><simpara>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.
  140 </simpara></listitem>
  141 </varlistentry>
  142 
  143 <varlistentry><term>COPYRIGHT</term>
  144 <listitem><simpara>Copyright attribution, e.g., '2001 Nobody's Band' or '1999 Jack Moffitt'
  145 </simpara></listitem>
  146 </varlistentry>
  147 
  148 <varlistentry><term>LICENSE</term>
  149 <listitem><simpara>License information, eg, 'All Rights Reserved', 'Any
  150 Use Permitted', a URL to a license such as a Creative Commons license
  151 ("www.creativecommons.org/blahblah/license.html") or the EFF Open
  152 Audio License ('distributed under the terms of the Open Audio
  153 License. see http://www.eff.org/IP/Open_licenses/eff_oal.html for
  154 details'), etc.
  155 </simpara></listitem>
  156 </varlistentry>
  157 
  158 <varlistentry><term>ORGANIZATION</term>
  159 <listitem><simpara>Name of the organization producing the track (i.e.
  160 the 'record label')
  161 </simpara></listitem>
  162 </varlistentry>
  163 
  164 <varlistentry><term>DESCRIPTION</term>
  165 <listitem><simpara>A short text description of the contents
  166 </simpara></listitem>
  167 </varlistentry>
  168 
  169 <varlistentry><term>GENRE</term>
  170 <listitem><simpara>A short text indication of music genre
  171 </simpara></listitem>
  172 </varlistentry>
  173 
  174 <varlistentry><term>DATE</term>
  175 <listitem><simpara>Date the track was recorded
  176 </simpara></listitem>
  177 </varlistentry>
  178 
  179 <varlistentry><term>LOCATION</term>
  180 <listitem><simpara>Location where track was recorded
  181 </simpara></listitem>
  182 </varlistentry>
  183 
  184 <varlistentry><term>CONTACT</term>
  185 <listitem><simpara>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.
  186 </simpara></listitem>
  187 </varlistentry>
  188 
  189 <varlistentry><term>ISRC</term>
  190 <listitem><simpara>International Standard Recording Code for the
  191 track; see <ulink
  192 url="http://www.ifpi.org/site-content/online/isrc_intro.html">the ISRC
  193 intro page</ulink> for more information on ISRC numbers.
  194 </simpara></listitem>
  195 </varlistentry>
  196 
  197 </variablelist>
  198 
  199 </section>
  200 
  201 <section><title>Implications</title>
  202 
  203 <para>Field names should not be 'internationalized'; this is a
  204 concession to simplicity not an attempt to exclude the majority of
  205 the world that doesn't speak English. Field <emphasis>contents</emphasis>
  206 however, use the UTF-8 character encoding to allow easy representation of any
  207 language.</para>
  208 
  209 <para>We have the length of the entirety of the field and restrictions on
  210 the field name so that the field name is bounded in a known way. Thus
  211 we also have the length of the field contents.</para>
  212 
  213 <para>Individual 'vendors' may use non-standard field names within
  214 reason. The proper use of comment fields should be clear through
  215 context at this point.  Abuse will be discouraged.</para>
  216 
  217 <para>There is no vendor-specific prefix to 'nonstandard' field names.
  218 Vendors should make some effort to avoid arbitrarily polluting the
  219 common namespace. We will generally collect the more useful tags
  220 here to help with standardization.</para>
  221 
  222 <para>Field names are not required to be unique (occur once) within a
  223 comment header.  As an example, assume a track was recorded by three
  224 well know artists; the following is permissible, and encouraged:
  225 
  226 <blockquote><programlisting>
  227 ARTIST=Dizzy Gillespie 
  228 ARTIST=Sonny Rollins 
  229 ARTIST=Sonny Stitt 
  230 </programlisting></blockquote>
  231 
  232 </para>
  233 
  234 </section>
  235 
  236 </section>
  237 
  238 <section><title>Encoding</title> 
  239 
  240 <para>
  241 The comment header comprises the entirety of the second bitstream
  242 header packet.  Unlike the first bitstream header packet, it is not
  243 generally the only packet on the second page and may not be restricted
  244 to within the second bitstream page.  The length of the comment header
  245 packet is (practically) unbounded.  The comment header packet is not
  246 optional; it must be present in the bitstream even if it is
  247 effectively empty.</para>
  248 
  249 <para>
  250 The comment header is encoded as follows (as per Ogg's standard
  251 bitstream mapping which renders least-significant-bit of the word to be
  252 coded into the least significant available bit of the current
  253 bitstream octet first):
  254 
  255 <orderedlist>
  256  <listitem><simpara>
  257   Vendor string length (32 bit unsigned quantity specifying number of octets)
  258  </simpara></listitem>
  259  <listitem><simpara>
  260   Vendor string ([vendor string length] octets coded from beginning of string to end of string, not null terminated)
  261  </simpara></listitem>
  262  <listitem><simpara>
  263   Number of comment fields (32 bit unsigned quantity specifying number of fields)
  264  </simpara></listitem>
  265  <listitem><simpara>
  266   Comment field 0 length (if [Number of comment fields]>0; 32 bit unsigned quantity specifying number of octets)
  267  </simpara></listitem>
  268  <listitem><simpara>
  269   Comment field 0 ([Comment field 0 length] octets coded from beginning of string to end of string, not null terminated)
  270  </simpara></listitem>
  271  <listitem><simpara>
  272   Comment field 1 length (if [Number of comment fields]>1...)...
  273  </simpara></listitem>
  274 </orderedlist>
  275 </para>
  276 
  277 <para>
  278 This is actually somewhat easier to describe in code; implementation of the above can be found in <filename>vorbis/lib/info.c</filename>, <function>_vorbis_pack_comment()</function> and <function>_vorbis_unpack_comment()</function>.
  279 </para>
  280 
  281 </section>
  282 </section>
  283 
  284 </section>