--- /dev/null
+<HTML><HEAD><TITLE>xiph.org: OggSquish Vorbis documentation</TITLE>
+<BODY bgcolor="#ffffff" text="#202020" link="#006666" vlink="#000000">
+<nobr><img src="white-ogg.gif"><img src="vorbisword2.gif"></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 OggSquish 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>
+
+
+
+<h2>OggSquish Bitstream Manipulation Structures</h3>
+
+Two of the OggSquish 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>OggSquish 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 OggSquish 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 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.gif" align=left border=0>
+</a>
+<font size=-2 color=#505050>
+
+OggSquish 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 OggSquish audio CODEC. Anyone may
+freely use and distribute the OggSquish 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 (libvorbis and the
+vorbis encode/decode/playback utility) are distributed under the 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-1999 Xiphophorus. All rights reserved.<p>
+
+</body>
+
+
+
+
+
+
projects / platform / upstream / libvorbis.git / commitdiff