moved docs to doc

svn path=/branches/branch_jackoggsvorbis/vorbis/; revision=663
author: Jack Moffitt <jack@xiph.org> 2000-09-07 06:19:23 +0000
committer: Jack Moffitt <jack@xiph.org> 2000-09-07 06:19:23 +0000
commit: 959736d94ce5bc55fc0513c5fd78b24cb631f8e6 (patch)
tree: 2e45e87cd7240f1db4c0ab438a93b8b05e6dd6f0
parent: e20b7009217c52621c830128a0cdcf07a6e161ef (diff)
download: libvorbis-git-959736d94ce5bc55fc0513c5fd78b24cb631f8e6.tar.gz
7 files changed, 897 insertions, 0 deletions
diff --git a/doc/programming.html b/doc/programming.html
new file mode 100644
index 00000000..7f6e62fe
--- /dev/null
+++ b/doc/programming.html
@@ -0,0 +1,507 @@
+<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>
+Programming with Xiphophorus <tt>libvorbis</tt>
+</font></h1>
+
+<em>Last update to this document: July 22, 1999</em><br> 
+
+<h2>Description</h2> 
+
+Libvorbis is Xiphophorus's portable Ogg Vorbis CODEC implemented as a
+programmatic library.  Libvorbis provides primitives to handle framing
+and manipulation of Ogg bitstreams (used by the Vorbis for
+streaming), a full analysis (encoding) interface as well as packet
+decoding and synthesis for playback. <p>
+
+The libvorbis library does not provide any system interface; a
+full-featured demonstration player included with the library
+distribtion provides example code for a variety of system interfaces
+as well as a working example of using libvorbis in production code.
+
+<h2>Encoding Overview</h2>
+
+
+
+<h2>Decoding Overview</h2>
+
+Decoding a bitstream with libvorbis follows roughly the following
+steps:
+
+<ol>
+<li>Frame the incoming bitstream into pages
+<li>Sort the pages by logical bitstream and buffer then into logical streams
+<li>Decompose the logical streams into raw packets
+<li>Reconstruct segments of the original data from each packet
+<li>Glue the reconstructed segments back into a decoded stream
+</ol>
+
+<h3>Framing</h3>
+
+An Ogg bitstream is logically arranged into pages, but to decode
+the pages, we have to find them first.  The raw bitstream is first fed
+into an <tt>ogg_sync_state</tt> buffer using <tt>ogg_sync_buffer()</tt>
+and <tt>ogg_sync_wrote()</tt>.  After each block we submit to the sync
+buffer, we should check to see if we can frame and extract a complete
+page or pages using <tt>ogg_sync_pageout()</tt>.  Extra pages are
+buffered; allowing them to build up in the <tt>ogg_sync_state</tt>
+buffer will eventually exhaust memory.<p>
+
+The Ogg pages returned from <tt>ogg_sync_pageout</tt> need not be
+decoded further to be used as landmarks in seeking; seeking can be
+either a rough process of simply jumping to approximately intuited
+portions of the bitstream, or it can be a precise bisection process
+that captures pages and inspects data position.  When seeking,
+however, sequential multiplexing (chaining) must be accounted for;
+beginning play in a new logical bitstream requires initializing a
+synthesis engine with the headers from that bitstream.  Vorbis
+bitstreams do not make use of concurent multiplexing (grouping).<p>
+
+<h3>Sorting</h3>
+
+The pages produced by <tt>ogg_sync_pageout</tt> are then sorted by
+serial number to seperate logical bitstreams.  Initialize logical
+bitstream buffers (<tt>og_stream_state</tt>) using
+<tt>ogg_stream_init()</tt>. Pages are submitted to the matching
+logical bitstream buffer using <tt>ogg_stream_pagein</tt>; the serial
+number of the page and the stream buffer must match, or the page will
+be rejected.  A page submitted out of sequence will simply be noted,
+and in the course of outputting packets, the hole will be flagged
+(<tt>ogg_sync_pageout</tt> and <tt>ogg_stream_packetout</tt> will
+return a negative value at positions where they had to recapture the
+stream).
+
+<h3>Extracting packets</h3>
+
+After submitting page[s] to a logical stream, read available packets
+using <tt>ogg_stream_packetout</tt>.
+
+<h3>Decoding packets</h3>
+
+<h3>Reassembling data segments</h3>
+
+
+<h2>Ogg Bitstream Manipulation Structures</h3>
+
+Two of the Ogg bitstream data structures are intended to be
+transparent to the developer; the fields should be used directly.<p>
+
+<h3>ogg_packet</h3>
+
+<pre>
+typedef struct {
+  unsigned char *packet;
+  long  bytes;
+  long  b_o_s;
+  long  e_o_s;
+
+  size64 frameno;
+
+} ogg_packet;
+</pre>
+
+<dl>
+<dt>packet: <dd>a pointer to the byte data of the raw packet
+<dt>bytes: <dd>the size of the packet' raw data
+<dt>b_o_s: <dd>beginning of stream; nonzero if this is the first packet of 
+              the logical bitstream
+<dt>e_o_s: <dd>end of stream; nonzero if this is the last packet of the 
+              logical bitstream
+<dt>frameno: <dd>the absolute position of this packet in the original 
+             uncompressed data stream.
+</dl>
+
+<h4>encoding notes</h4> The encoder is responsible for setting all of
+the fields of the packet to appropriate values before submission to
+<tt>ogg_stream_packetin()</tt>; however, it is noted that the value in
+<tt>b_o_s</tt> is ignored; the first page produced from a given
+<tt>ogg_stream_state</tt> structure will be stamped as the initial
+page.  <tt>e_o_s</tt>, however, must be set; this is the means by
+which the stream encoding primitives handle end of stream and cleanup.
+
+<h4>decoding notes</h4><tt>ogg_stream_packetout()</tt> sets the fields
+to appropriate values.  Note that frameno will be >= 0 only in the
+case that the given packet actually represents that position (ie, only
+the last packet completed on any page will have a meaningful
+<tt>frameno</tt>).  Intervening frames will see <tt>frameno</tt> set
+to -1.
+
+<h3>ogg_page</h3>
+
+<pre>
+typedef struct {
+  unsigned char *header;
+  long header_len;
+  unsigned char *body;
+  long body_len;
+} ogg_page;
+</pre>
+
+<dl>
+<dt>header: <dd>pointer to the page header data
+<dt>header_len: <dd>length of the page header in bytes
+<dt>body: <dd>pointer to the page body
+<dt>body_len: <dd>length of the page body
+</dl>
+
+Note that although the <tt>header</tt> and <tt>body</tt> pointers do
+not necessarily point into a single contiguous page vector, the page
+body must immediately follow the header in the bitstream.<p>
+
+<h2>Ogg Bitstream Manipulation Functions</h3>
+
+<h3>
+int    ogg_page_bos(ogg_page *og);
+</h3>
+
+Returns the 'beginning of stream' flag for the given Ogg page.  The
+beginning of stream flag is set on the initial page of a logical
+bitstream.<P>
+
+Zero indicates the flag is cleared (this is not the initial page of a
+logical bitstream).  Nonzero indicates the flag is set (this is the
+initial page of a logical bitstream).<p>
+
+<h3>
+int    ogg_page_continued(ogg_page *og);
+</h3>
+
+Returns the 'packet continued' flag for the given Ogg page. The packet
+continued flag indicates whether or not the body data of this page
+begins with packet continued from a preceeding page.<p>
+Zero (unset) indicates that the body data begins with a new packet.
+Nonzero (set) indicates that the first packet data on the page is a
+continuation from the preceeding page.
+
+<h3>
+int    ogg_page_eos(ogg_page *og);
+</h3>
+
+Returns the 'end of stream' flag for a give Ogg page.  The end of page
+flag is set on the last (terminal) page of a logical bitstream.<p>
+
+Zero (unset) indicates that this is not the last page of a logical
+bitstream.  Nonzero (set) indicates that this is the last page of a
+logical bitstream and that no addiitonal pages belonging to this
+bitstream may follow.<p>
+
+<h3>
+size64 ogg_page_frameno(ogg_page *og);
+</h3>
+
+Returns the position of this page as an absolute position within the
+original uncompressed data.  The position, as returned, is 'frames
+encoded to date up to and including the last whole packet on this
+page'.  Partial packets begun on this page but continued to the
+following page are not included.  If no packet ends on this page, the
+frame position value will be equal to the frame position value of the
+preceeding page.  If none of the original uncompressed data is yet
+represented in the logical bitstream (for example, the first page of a
+bitstream consists only of a header packet; this packet encodes only
+metadata), the value shall be zero.<p>
+
+The units of the framenumber are determined by media mapping.  A
+vorbis audio bitstream, for example, defines one frame to be the
+channel values from a single sampling period (eg, a 16 bit stereo
+bitstream consists of two samples of two bytes for a total of four
+bytes, thus a frame would be four bytes).  A video stream defines one
+frame to be a single frame of video.<p>
+
+<h3>
+int    ogg_page_pageno(ogg_page *og);
+</h3>
+
+Returns the sequential page number of the given Ogg page.  The first
+page in a logical bitstream is numbered zero; following pages are
+numbered in increasing monotonic order.<p>
+
+<h3>
+int    ogg_page_serialno(ogg_page *og);
+</h3>
+
+Returns the serial number of the given Ogg page.  The serial number is
+used as a handle to distinguish various logical bitstreams in a
+physical Ogg bitstresm. Every logical bitstream within a
+physical bitstream must use a unique (within the scope of the physical
+bitstream) serial number, which is stamped on all bitstream pages.<p>
+
+<h3>
+int    ogg_page_version(ogg_page *og);
+</h3>
+
+Returns the revision of the Ogg bitstream structure of the given page.
+Currently, the only permitted number is zero.  Later revisions of the
+bitstream spec will increment this version should any changes be
+incompatable.</p>
+
+<h3>
+int    ogg_stream_clear(ogg_stream_state *os);
+</h3>
+
+Clears and deallocates the internal storage of the given Ogg stream.
+After clearing, the stream structure is not initialized for use;
+<tt>ogg_stream_init</tt> must be called to reinitialize for use.
+Use <tt>ogg_stream_reset</tt> to reset the stream state
+to a fresh, intiialized state.<p>
+
+<tt>ogg_stream_clear</tt> does not call <tt>free()</tt> on the pointer
+<tt>os</tt>, allowing use of this call on stream structures in static
+or automatic storage.  <tt>ogg_stream_destroy</tt>is a complimentary
+function that frees the pointer as well.<p>
+
+Returns zero on success and non-zero on failure. This function always
+succeeds.<p>
+
+<h3>
+int    ogg_stream_destroy(ogg_stream_state *os);
+</h3>
+
+Clears and deallocates the internal storage of the given Ogg stream,
+then frees the storage associated with the pointer <tt>os</tt>.<p>
+
+<tt>ogg_stream_clear</tt> does not call <tt>free()</tt> on the pointer
+<tt>os</tt>, allowing use of that call on stream structures in static
+or automatic storage.<p>
+
+Returns zero on success and non-zero on failure. This function always
+succeeds.<p>
+
+<h3>
+int    ogg_stream_init(ogg_stream_state *os,int serialno);
+</h3>
+
+Initialize the storage associated with <tt>os</tt> for use as an Ogg
+stream.  This call is used to initialize a stream for both encode and
+decode.  The given serial number is the serial number that will be
+stamped on pages of the produced bitstream (during encode), or used as
+a check that pages match (during decode).<p>
+
+Returns zero on success, nonzero on failure.<p>
+
+<h3>
+int    ogg_stream_packetin(ogg_stream_state *os, ogg_packet *op);
+</h3>
+
+Used during encoding to add the given raw packet to the given Ogg
+bitstream.  The contents of <tt>op</tt> are copied;
+<tt>ogg_stream_packetin</tt> does not retain any pointers into
+<tt>op</tt>'s storage. The encoding proccess buffers incoming packets
+until enough packets have been assembled to form an entire page;
+<tt>ogg_stream_pageout</tt> is used to read complete pages.<p>
+
+Returns zero on success, nonzero on failure.<p>
+
+<h3>
+int    ogg_stream_packetout(ogg_stream_state *os,ogg_packet *op);
+</h3>
+
+Used during decoding to read raw packets from the given logical
+bitstream.  <tt>ogg_stream_packetout</tt> will only return complete
+packets for which checksumming indicates no corruption.  The size and
+contents of the packet exactly match those given in the encoding
+process.  <p>
+
+Returns zero if the next packet is not ready to be read (not buffered
+or incomplete), positive if it returned a complete packet in
+<tt>op</tt> and negative if there is a gap, extra bytes or corruption
+at this position in the bitstream (essentially that the bitstream had
+to be recaptured).  A negative value is not necessarily an error.  It
+would be a common occurence when seeking, for example, which requires
+recapture of the bitstream at the position decoding continued.<p>
+
+Iff the return value is positive, <tt>ogg_stream_packetout</tt> placed
+a packet in <tt>op</tt>.  The data in <t>op</tt> points to static
+storage that is valid until the next call to
+<tt>ogg_stream_pagein</tt>, <tt>ogg_stream_clear</tt>,
+<tt>ogg_stream_reset</tt>, or <tt>ogg_stream_destroy</tt>.  The
+pointers are not invalidated by more calls to
+<tt>ogg_stream_packetout</tt>.<p>
+
+<h3>
+int    ogg_stream_pagein(ogg_stream_state *os, ogg_page *og);
+</h3>
+
+Used during decoding to buffer the given complete, pre-verified page
+for decoding into raw Ogg packets. The given page must be framed,
+normally produced by <tt>ogg_sync_pageout</tt>, and from the logical
+bitstream associated with <tt>os</tt> (the serial numbers must match).
+The contents of the given page are copied; <tt>ogg_stream_pagein</tt>
+retains no pointers into <tt>og</tt> storage.<p>
+
+Returns zero on success and non-zero on failure.<p>
+
+<h3>
+int    ogg_stream_pageout(ogg_stream_state *os, ogg_page *og);
+</h3>
+
+Used during encode to read complete pages from the stream buffer.  The
+returned page is ready for sending out to the real world.<p>
+
+Returns zero if there is no complete page ready for reading.  Returns
+nonzero when it has placed data for a complete page into
+<tt>og</tt>. Note that the storage returned in og points into internal
+storage; the pointers in <tt>og</tt> are valid until the next call to
+<tt>ogg_stream_pageout</tt>, <tt>ogg_stream_packetin</tt>,
+<tt>ogg_stream_reset</tt>, <tt>ogg_stream_clear</tt> or
+<tt>ogg_stream_destroy</tt>.
+
+<h3>
+int    ogg_stream_reset(ogg_stream_state *os);
+</h3>
+
+Resets the given stream's state to that of a blank, unused stream;
+this may be used during encode or decode. <p>
+
+Note that if used during encode, it does not alter the stream's serial
+number.  In addition, the next page produced during encoding will be
+marked as the 'initial' page of the logical bitstream.<p>
+
+When used during decode, this simply clears the data buffer of any
+pending pages.  Beginning and end of stream cues are read from the
+bitstream and are unaffected by reset.<p>
+
+Returns zero on success and non-zero on failure. This function always
+succeeds.<p>
+
+<h3>
+char  *ogg_sync_buffer(ogg_sync_state *oy, long size);
+</h3>
+
+This call is used to buffer a raw bitstream for framing and
+verification. <tt>ogg_sync_buffer</tt> handles stream capture and
+recapture, checksumming, and division into Ogg pages (as required by
+<tt>ogg_stream_pagein</tt>).<p>
+
+<tt>ogg_sync_buffer</tt> exposes a buffer area into which the decoder
+copies the next (up to) <tt>size</tt> bytes.  We expose the buffer
+(rather than taking a buffer) in order to avoid an extra copy many
+uses; this way, for example, <tt>read()</tt> can transfer data
+directly into the stream buffer without first needing to place it in
+temporary storage.<p>
+
+Returns a pointer into <tt>oy</tt>'s internal bitstream sync buffer;
+the remaining space in the sync buffer is at least <tt>size</tt>
+bytes.  The decoder need not write all of <tt>size</tt> bytes;
+<tt>ogg_sync_wrote</tt> is used to inform the engine how many bytes
+were actually written. Use of <tt>ogg_sync_wrote</tt> after writing
+into the exposed buffer is mandantory.<p>
+
+<h3>
+int    ogg_sync_clear(ogg_sync_state *oy);
+</h3>
+
+<tt>ogg_sync_clear</tt>
+
+Clears and deallocates the internal storage of the given Ogg sync
+buffer.  After clearing, the sync structure is not initialized for
+use; <tt>ogg_sync_init</tt> must be called to reinitialize for use.
+Use <tt>ogg_sync_reset</tt> to reset the sync state and buffer to a
+fresh, intiialized state.<p>
+
+<tt>ogg_sync_clear</tt> does not call <tt>free()</tt> on the pointer
+<tt>oy</tt>, allowing use of this call on sync structures in static
+or automatic storage.  <tt>ogg_sync_destroy</tt>is a complimentary
+function that frees the pointer as well.<p>
+
+Returns zero on success and non-zero on failure. This function always
+succeeds.<p>
+
+<h3>
+int    ogg_sync_destroy(ogg_sync_state *oy);
+</h3>
+
+Clears and deallocates the internal storage of the given Ogg sync
+buffer, then frees the storage associated with the pointer
+<tt>oy</tt>.<p>
+
+<tt>ogg_sync_clear</tt> does not call <tt>free()</tt> on the pointer
+<tt>oy</tt>, allowing use of that call on stream structures in static
+or automatic storage.<p>
+
+Returns zero on success and non-zero on failure. This function always
+succeeds.<p>
+
+<h3>
+int    ogg_sync_init(ogg_sync_state *oy);
+</h3>
+
+Initializes the sync buffer <tt>oy</tt> for use.<p>
+Returns zero on success and non-zero on failure. This function always
+succeeds.<p>
+
+<h3>
+int    ogg_sync_pageout(ogg_sync_state *oy, ogg_page *og);
+</h3>
+
+Reads complete, framed, verified Ogg pages from the sync buffer,
+placing the page data in <tt>og</tt>.<p>
+
+Returns zero when there's no complete pages buffered for
+retrieval. Returns negative when a loss of sync or recapture occurred
+(this is not necessarily an error; recapture would be required after
+seeking, for example).  Returns positive when a page is returned in
+<tt>og</tt>. Note that the data in <tt>og</tt> points into the sync
+buffer storage; the pointers are valid until the next call to
+<tt>ogg_sync_buffer</tt>, <tt>ogg_sync_clear</tt>,
+<tt>ogg_sync_destroy</tt> or <tt>ogg_sync_reset</tt>.
+
+
+<h3>
+int    ogg_sync_reset(ogg_sync_state *oy);
+</h3>
+
+<tt>ogg_sync_reset</tt> resets the sync state in <tt>oy</tt> to a
+clean, empty state.  This is useful, for example, when seeking to a
+new location in a bitstream.<p>
+
+Returns zero on success, nonzero on failure.<p>
+
+<h3>
+int    ogg_sync_wrote(ogg_sync_state *oy, long bytes);
+</h3>
+
+Used to inform the sync state as to how many bytes were actually
+written into the exposed sync buffer.  It must be equal to or less
+than the size of the buffer requested.<p>
+
+Returns zero on success and non-zero on failure; failure occurs only
+when the number of bytes written were larger than the buffer.<p>
+
+<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>
+
+
+
+
+
+
diff --git a/doc/v-comment.html b/doc/v-comment.html
new file mode 100644
index 00000000..a425eb03
--- /dev/null
+++ b/doc/v-comment.html
@@ -0,0 +1,194 @@
+<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>
+
+
+
+
+
+
diff --git a/doc/vorbis.html b/doc/vorbis.html
new file mode 100644
index 00000000..27e3a5b0
--- /dev/null
+++ b/doc/vorbis.html
@@ -0,0 +1,196 @@
+<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 encoding format documentation
+</font></h1>
+
+<em>Last update to this document: July 15, 1999</em><br> 
+<em>Last update to Vorbis documentation: July 21, 1999</em><p> 
+
+<table><tr><td>
+<img src=wait.png>
+</td><td valign=center>
+As of writing, not all the below document
+links are live.  They will be populated as we complete the
+documents.
+</td></tr></table>
+
+<p>
+<h2>Documents</h2>
+<ul>
+<li><a href="packet.html">Vorbis packet structure</a>
+<li><a href="envelope.html">Temporal envelope shaping and blocksize</a>
+<li><a href="mdct.html">Time domain segmentation and MDCT transform</a>
+<li><a href="resolution.html">The resolution floor</a>
+<li><a href="residuals.html">MDCT-domain fine structure</a><p>
+
+<li><a href="probmodel.html">The Vorbis probability model</a>
+
+<li><a href="bitpack.html">The Vorbis bitpacker</a><p>
+
+<li><a href="oggstream.html">Ogg bitstream overview</a>
+<li><a href="framing.html">Ogg logical bitstream and framing spec</a>
+<li><a href="vorbis-stream.html">Vorbis packet->Ogg bitstream 
+       mapping</a><p>
+
+<li><a href="programming.html">Programming with libvorbis</a><p>
+</ul>
+
+<h2>Description</h2>
+Ogg Vorbis is a general purpose compressed audio format
+for high quality (44.1-48.0kHz, 16+ bit, polyphonic) audio and music
+at moderate fixed and variable bitrates (40-80 kb/s/channel).  This
+places Vorbis in the same class as audio representations including
+MPEG-1 audio layer 3, MPEG-4 audio (AAC and TwinVQ), and PAC.<p>
+
+Vorbis is the first of a planned family of Ogg multimedia coding
+formats being developed as part of Xiphophorus's Ogg multimedia
+project.  See <a href="http://www.xiph.org/">http://www.xiph.org/</a>
+for more information.
+
+<h2>Vorbis technical documents</h2>
+
+A Vorbis encoder takes in overlapping (but contiguous) short-time
+segments of audio data. The encoder analyzes the content of the audio
+to determine an optimal compact representation; this phase of encoding
+is known as <em>analysis</em>.  For each short-time block of sound,
+the encoder then packs an efficient representation of the signal, as
+determined by analysis, into a raw packet much smaller than the size
+required by the original signal; this phase is <em>coding</em>.
+Lastly, in a streaming environment, the raw packets are then
+structured into a continuous stream of octets; this last phase is
+<em>streaming</em>. Note that the stream of octets is referred to both
+as a 'byte-' and 'bit-'stream; the latter usage is acceptible as the
+stream of octets is a physical representation of a true logical
+bit-by-bit stream.<p>
+
+A Vorbis decoder performs a mirror image process of extracting the
+original sequence of raw packets from an Ogg stream (<em>stream
+decomposition</em>), reconstructing the signal representation from the
+raw data in the packet (<em>decoding</em>) and them reconstituting an
+audio signal from the decoded representation (<em>synthesis</em>).<p>
+
+The <a href="programming.html">Programming with libvorbis</a>
+documents discuss use of the reference Vorbis codec library
+(libvorbis) produced by Xiphophorus.<p>
+
+The data representations and algorithms necessary at each step to
+encode and decode Ogg Vorbis bitstreams are described by the below
+documents in sufficient detail to construct a complete Vorbis codec.
+Note that at the time of writing, Vorbis is still in a 'Request For
+Comments' stage of development; despite being in advanced stages of
+development, input from the multimedia community is welcome.<p>
+
+<h3>Vorbis analysis and synthesis</h3>
+
+Analysis begins by seperating an input audio stream into individual,
+overlapping short-time segments of audio data.  These segments are
+then transformed into an alternate representation, seeking to
+represent the original signal in a more efficient form that codes into
+a smaller number of bytes.  The analysis and transformation stage is
+the most complex element of producing a Vorbis bitstream.<p>
+
+The corresponding synthesis step in the decoder is simpler; there is
+no analysis to perform, merely a mechanical, deterministic
+reconstruction of the original audio data from the transform-domain
+representation.<p>
+
+<ul>
+<li><a href="packet.html">Vorbis packet structure</a>: Describes the basic analysis components necessary to produce Vorbis packets and the structure of the packet itself.
+<li><a href="envelope.html">Temporal envelope shaping and blocksize</a>: Use of temporal envelope shaping and variable blocksize to minimize time-domain energy leakage during wide dynamic range and spectral energy swings.  Also discusses time-related principles of psychoacoustics.
+<li><a href="mdct.html">Time domain segmentation and MDCT transform</a>: Division of time domain data into individual overlapped, windowed short-time vectors and transformation using the MDCT
+<li><a href="resolution.html">The resolution floor</a>: Use of frequency doamin psychoacoustics, and the MDCT-domain noise, masking and resolution floors
+<li><a href="residuals.html">MDCT-domain fine structure</a>: Production, quantization and massaging of MDCT-spectrum fine structure
+</ul>
+
+<h3>Vorbis coding and decoding</h3>
+
+Coding and decoding converts the transform-domain representation of
+the original audio produced by analysis to and from a bitwise packed
+raw data packet.  Coding and decoding consist of two logically
+orthogonal concepts, <em>back-end coding</em> and <em>bitpacking</em>.<p>
+
+<em>Back-end coding</em> uses a probability model to represent the raw numbers
+of the audio representation in as few physical bits as possible;
+familiar examples of back-end coding include Huffman coding and Vector
+Quantization.<p>
+
+<em>Bitpacking</em> arranges the variable sized words of the back-end
+coding into a vector of octets without wasting space.  The octets
+produced by coding a single short-time audio segment is one raw Vorbis
+packet.<p>
+
+<ul>
+
+<li><a href="probmodel.html">The Vorbis probability model</a>
+
+<li><a href="bitpack.html">The Vorbis bitpacker</a>: Arrangement of 
+variable bit-length words into an octet-aligned packet.
+
+</ul>
+
+<h3>Vorbis streaming and stream decomposition</h3>
+
+Vorbis packets contain the raw, bitwise-compressed representation of a
+snippet of audio.  These packets contain no structure and cannot be
+strung together directly into a stream; for streamed transmission and
+storage, Vorbis packets are encoded into an Ogg bitstream.<p>
+
+<ul>
+
+<li><a href="oggstream.html">Ogg bitstream overview</a>: High-level
+description of Ogg logical bitstreams, how logical bitstreams
+(of mixed media types) can be combined into physical bitstreams, and
+restrictions on logical-to-physical mapping.  Note that this document is
+not specific only to Ogg Vorbis.
+
+<li><a href="framing.html">Ogg logical bitstream and framing
+spec</a>: Low level, complete specification of Ogg logical
+bitstream pages.  Note that this document is not specific only to Ogg
+Vorbis.
+
+<li><a href="vorbis-stream.html">Vorbis bitstream mapping</a>:
+Specifically describes mapping Vorbis data into an
+Ogg physical bitstream.  
+
+</ul>
+
+
+<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>
+
+
+
+
+
+
diff --git a/doc/vorbisword2.png b/doc/vorbisword2.png
new file mode 100644
index 00000000..12e3d316
--- /dev/null
+++ b/doc/vorbisword2.png
diff --git a/doc/wait.png b/doc/wait.png
new file mode 100644
index 00000000..2d10af60
--- /dev/null
+++ b/doc/wait.png
diff --git a/doc/white-ogg.png b/doc/white-ogg.png
new file mode 100644
index 00000000..45dc0acd
--- /dev/null
+++ b/doc/white-ogg.png
diff --git a/doc/white-xifish.png b/doc/white-xifish.png
new file mode 100644
index 00000000..ab25cc8f
--- /dev/null
+++ b/doc/white-xifish.png
author	Jack Moffitt <jack@xiph.org>	2000-09-07 06:19:23 +0000
committer	Jack Moffitt <jack@xiph.org>	2000-09-07 06:19:23 +0000
commit	959736d94ce5bc55fc0513c5fd78b24cb631f8e6 (patch)
tree	2e45e87cd7240f1db4c0ab438a93b8b05e6dd6f0
parent	e20b7009217c52621c830128a0cdcf07a6e161ef (diff)
download	libvorbis-git-959736d94ce5bc55fc0513c5fd78b24cb631f8e6.tar.gz