VirtualBox

source: vbox/trunk/src/libs/libvorbis-1.3.7/doc/05-comment.tex@ 103131

Last change on this file since 103131 was 96468, checked in by vboxsync, 2 years ago

libs/libvorbis-1.3.7: Re-exporting, hopefully this time everything is there. bugref:10275

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 7.9 KB
Line 
1% -*- mode: latex; TeX-master: "Vorbis_I_spec"; -*-
2%!TEX root = Vorbis_I_spec.tex
3\section{comment field and header specification} \label{vorbis:spec:comment}
4
5\subsection{Overview}
6
7The Vorbis text comment header is the second (of three) header
8packets that begin a Vorbis bitstream. It is meant for short text
9comments, not arbitrary metadata; arbitrary metadata belongs in a
10separate logical bitstream (usually an XML stream type) that provides
11greater structure and machine parseability.
12
13The comment field is meant to be used much like someone jotting a
14quick note on the bottom of a CDR. It should be a little information to
15remember the disc by and explain it to others; a short, to-the-point
16text note that need not only be a couple words, but isn't going to be
17more than a short paragraph. The essentials, in other words, whatever
18they turn out to be, eg:
19
20\begin{quote}
21Honest Bob and the Factory-to-Dealer-Incentives, \textit{``I'm Still
22Around''}, opening for Moxy Fr\"{u}vous, 1997.
23\end{quote}
24
25
26
27
28\subsection{Comment encoding}
29
30\subsubsection{Structure}
31
32The comment header is logically a list of eight-bit-clean vectors; the
33number of vectors is bounded to $2^{32}-1$ and the length of each vector
34is limited to $2^{32}-1$ bytes. The vector length is encoded; the vector
35contents themselves are not null terminated. In addition to the vector
36list, there is a single vector for vendor name (also 8 bit clean,
37length encoded in 32 bits). For example, the 1.0 release of libvorbis
38set the vendor string to ``Xiph.Org libVorbis I 20020717''.
39
40The vector lengths and number of vectors are stored lsb first, according
41to the bit packing conventions of the vorbis codec. However, since data
42in the comment header is octet-aligned, they can simply be read as
43unaligned 32 bit little endian unsigned integers.
44
45The comment header is decoded as follows:
46
47\begin{programlisting}
48 1) [vendor\_length] = read an unsigned integer of 32 bits
49 2) [vendor\_string] = read a UTF-8 vector as [vendor\_length] octets
50 3) [user\_comment\_list\_length] = read an unsigned integer of 32 bits
51 4) iterate [user\_comment\_list\_length] times {
52 5) [length] = read an unsigned integer of 32 bits
53 6) this iteration's user comment = read a UTF-8 vector as [length] octets
54 }
55 7) [framing\_bit] = read a single bit as boolean
56 8) if ( [framing\_bit] unset or end-of-packet ) then ERROR
57 9) done.
58\end{programlisting}
59
60
61
62
63\subsubsection{Content vector format}
64
65The comment vectors are structured similarly to a UNIX environment variable.
66That is, comment fields consist of a field name and a corresponding value and
67look like:
68
69\begin{quote}
70\begin{programlisting}
71comment[0]="ARTIST=me";
72comment[1]="TITLE=the sound of Vorbis";
73\end{programlisting}
74\end{quote}
75
76The field name is case-insensitive and may consist of ASCII 0x20
77through 0x7D, 0x3D ('=') excluded. ASCII 0x41 through 0x5A inclusive
78(characters A-Z) is to be considered equivalent to ASCII 0x61 through
790x7A inclusive (characters a-z).
80
81
82The field name is immediately followed by ASCII 0x3D ('=');
83this equals sign is used to terminate the field name.
84
85
860x3D is followed by 8 bit clean UTF-8 encoded value of the
87field contents to the end of the field.
88
89
90\paragraph{Field names}
91
92Below is a proposed, minimal list of standard field names with a
93description of intended use. No single or group of field names is
94mandatory; a comment header may contain one, all or none of the names
95in this list.
96
97\begin{description} %[style=nextline]
98\item[TITLE]
99 Track/Work name
100
101\item[VERSION]
102 The version field may be used to differentiate multiple
103versions of the same track title in a single collection. (e.g. remix
104info)
105
106\item[ALBUM]
107 The collection name to which this track belongs
108
109\item[TRACKNUMBER]
110 The track number of this piece if part of a specific larger collection or album
111
112\item[ARTIST]
113 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.
114
115\item[PERFORMER]
116 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.
117
118\item[COPYRIGHT]
119 Copyright attribution, e.g., '2001 Nobody's Band' or '1999 Jack Moffitt'
120
121\item[LICENSE]
122 License information, for example, 'All Rights Reserved', 'Any
123Use Permitted', a URL to a license such as a Creative Commons license
124(e.g. "creativecommons.org/license/by/4.0/") or similar.
125
126\item[ORGANIZATION]
127 Name of the organization producing the track (i.e.
128the 'record label')
129
130\item[DESCRIPTION]
131 A short text description of the contents
132
133\item[GENRE]
134 A short text indication of music genre
135
136\item[DATE]
137 Date the track was recorded
138
139\item[LOCATION]
140 Location where track was recorded
141
142\item[CONTACT]
143 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.
144
145\item[ISRC]
146 International Standard Recording Code for the
147track; see \href{https://isrc.ifpi.org/}{the ISRC
148intro page} for more information on ISRC numbers.
149
150\end{description}
151
152
153
154\paragraph{Implications}
155
156Field names should not be 'internationalized'; this is a
157concession to simplicity not an attempt to exclude the majority of
158the world that doesn't speak English. Field \emph{contents},
159however, use the UTF-8 character encoding to allow easy representation
160of any language.
161
162We have the length of the entirety of the field and restrictions on
163the field name so that the field name is bounded in a known way. Thus
164we also have the length of the field contents.
165
166Individual 'vendors' may use non-standard field names within
167reason. The proper use of comment fields should be clear through
168context at this point. Abuse will be discouraged.
169
170There is no vendor-specific prefix to 'nonstandard' field names.
171Vendors should make some effort to avoid arbitrarily polluting the
172common namespace. We will generally collect the more useful tags
173here to help with standardization.
174
175Field names are not required to be unique (occur once) within a
176comment header. As an example, assume a track was recorded by three
177well know artists; the following is permissible, and encouraged:
178
179\begin{quote}
180\begin{programlisting}
181ARTIST=Dizzy Gillespie
182ARTIST=Sonny Rollins
183ARTIST=Sonny Stitt
184\end{programlisting}
185\end{quote}
186
187
188
189
190
191
192
193\subsubsection{Encoding}
194
195The comment header comprises the entirety of the second bitstream
196header packet. Unlike the first bitstream header packet, it is not
197generally the only packet on the second page and may not be restricted
198to within the second bitstream page. The length of the comment header
199packet is (practically) unbounded. The comment header packet is not
200optional; it must be present in the bitstream even if it is
201effectively empty.
202
203The comment header is encoded as follows (as per Ogg's standard
204bitstream mapping which renders least-significant-bit of the word to be
205coded into the least significant available bit of the current
206bitstream octet first):
207
208\begin{enumerate}
209 \item
210 Vendor string length (32 bit unsigned quantity specifying number of octets)
211
212 \item
213 Vendor string ([vendor string length] octets coded from beginning of string to end of string, not null terminated)
214
215 \item
216 Number of comment fields (32 bit unsigned quantity specifying number of fields)
217
218 \item
219 Comment field 0 length (if [Number of comment fields] $>0$; 32 bit unsigned quantity specifying number of octets)
220
221 \item
222 Comment field 0 ([Comment field 0 length] octets coded from beginning of string to end of string, not null terminated)
223
224 \item
225 Comment field 1 length (if [Number of comment fields] $>1$...)...
226
227\end{enumerate}
228
229
230This is actually somewhat easier to describe in code; implementation of the above can be found in \filename{vorbis/lib/info.c}, \function{\_vorbis\_pack\_comment()} and \function{\_vorbis\_unpack\_comment()}.
231
232
233
234
235
236
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette