1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
\r
5 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
\r
6 <title>Ogg Vorbis Documentation</title>
\r
8 <style type="text/css">
\r
10 margin: 0 18px 0 18px;
\r
11 padding-bottom: 30px;
\r
12 font-family: Verdana, Arial, Helvetica, sans-serif;
\r
26 margin: 30px 0 16px 0;
\r
33 h1, h1 a, h2, h2 a, h3, h3 a {
\r
36 margin: 1.3em 0 8px 0;
\r
70 <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.org"/></a>
\r
73 <h1>Programming with Xiph.org <tt>libvorbis</tt></h1>
\r
75 <h2>Description</h2>
\r
77 <p>Libvorbis is the Xiph.org Foundation's portable Ogg Vorbis CODEC
\r
78 implemented as a programmatic library. Libvorbis provides primitives
\r
79 to handle framing and manipulation of Ogg bitstreams (used by the
\r
80 Vorbis for streaming), a full analysis (encoding) interface as well as
\r
81 packet decoding and synthesis for playback.</p>
\r
83 <p>The libvorbis library does not provide any system interface; a
\r
84 full-featured demonstration player included with the library
\r
85 distribtion provides example code for a variety of system interfaces
\r
86 as well as a working example of using libvorbis in production code.</p>
\r
88 <h2>Encoding Overview</h2>
\r
90 <h2>Decoding Overview</h2>
\r
92 <p>Decoding a bitstream with libvorbis follows roughly the following
\r
96 <li>Frame the incoming bitstream into pages</li>
\r
97 <li>Sort the pages by logical bitstream and buffer then into logical streams</li>
\r
98 <li>Decompose the logical streams into raw packets</li>
\r
99 <li>Reconstruct segments of the original data from each packet</li>
\r
100 <li>Glue the reconstructed segments back into a decoded stream</li>
\r
105 <p>An Ogg bitstream is logically arranged into pages, but to decode
\r
106 the pages, we have to find them first. The raw bitstream is first fed
\r
107 into an <tt>ogg_sync_state</tt> buffer using <tt>ogg_sync_buffer()</tt>
\r
108 and <tt>ogg_sync_wrote()</tt>. After each block we submit to the sync
\r
109 buffer, we should check to see if we can frame and extract a complete
\r
110 page or pages using <tt>ogg_sync_pageout()</tt>. Extra pages are
\r
111 buffered; allowing them to build up in the <tt>ogg_sync_state</tt>
\r
112 buffer will eventually exhaust memory.</p>
\r
114 <p>The Ogg pages returned from <tt>ogg_sync_pageout</tt> need not be
\r
115 decoded further to be used as landmarks in seeking; seeking can be
\r
116 either a rough process of simply jumping to approximately intuited
\r
117 portions of the bitstream, or it can be a precise bisection process
\r
118 that captures pages and inspects data position. When seeking,
\r
119 however, sequential multiplexing (chaining) must be accounted for;
\r
120 beginning play in a new logical bitstream requires initializing a
\r
121 synthesis engine with the headers from that bitstream. Vorbis
\r
122 bitstreams do not make use of concurent multiplexing (grouping).</p>
\r
126 <p>The pages produced by <tt>ogg_sync_pageout</tt> are then sorted by
\r
127 serial number to seperate logical bitstreams. Initialize logical
\r
128 bitstream buffers (<tt>og_stream_state</tt>) using
\r
129 <tt>ogg_stream_init()</tt>. Pages are submitted to the matching
\r
130 logical bitstream buffer using <tt>ogg_stream_pagein</tt>; the serial
\r
131 number of the page and the stream buffer must match, or the page will
\r
132 be rejected. A page submitted out of sequence will simply be noted,
\r
133 and in the course of outputting packets, the hole will be flagged
\r
134 (<tt>ogg_sync_pageout</tt> and <tt>ogg_stream_packetout</tt> will
\r
135 return a negative value at positions where they had to recapture the
\r
138 <h3>Extracting packets</h3>
\r
140 <p>After submitting page[s] to a logical stream, read available packets
\r
141 using <tt>ogg_stream_packetout</tt>.</p>
\r
143 <h3>Decoding packets</h3>
\r
145 <h3>Reassembling data segments</h3>
\r
147 <h2>Ogg Bitstream Manipulation Structures</h2>
\r
149 <p>Two of the Ogg bitstream data structures are intended to be
\r
150 transparent to the developer; the fields should be used directly.</p>
\r
152 <h3>ogg_packet</h3>
\r
156 unsigned char *packet;
\r
168 <dd>a pointer to the byte data of the raw packet</dd>
\r
170 <dd>the size of the packet' raw data</dd>
\r
172 <dd>beginning of stream; nonzero if this is the first packet of
\r
173 the logical bitstream</dd>
\r
175 <dd>end of stream; nonzero if this is the last packet of the
\r
176 logical bitstream</dd>
\r
177 <dt>granulepos:</dt>
\r
178 <dd>the absolute position of this packet in the original
\r
179 uncompressed data stream.</dd>
\r
182 <h4>encoding notes</h4>
\r
184 <p>The encoder is responsible for setting all of
\r
185 the fields of the packet to appropriate values before submission to
\r
186 <tt>ogg_stream_packetin()</tt>; however, it is noted that the value in
\r
187 <tt>b_o_s</tt> is ignored; the first page produced from a given
\r
188 <tt>ogg_stream_state</tt> structure will be stamped as the initial
\r
189 page. <tt>e_o_s</tt>, however, must be set; this is the means by
\r
190 which the stream encoding primitives handle end of stream and cleanup.</p>
\r
192 <h4>decoding notes</h4>
\r
194 <p><tt>ogg_stream_packetout()</tt> sets the fields
\r
195 to appropriate values. Note that granulepos will be >= 0 only in the
\r
196 case that the given packet actually represents that position (ie, only
\r
197 the last packet completed on any page will have a meaningful
\r
198 <tt>granulepos</tt>). Intervening frames will see <tt>granulepos</tt> set
\r
205 unsigned char *header;
\r
207 unsigned char *body;
\r
214 <dd>pointer to the page header data</dd>
\r
215 <dt>header_len:</dt>
\r
216 <dd>length of the page header in bytes</dd>
\r
218 <dd>pointer to the page body</dd>
\r
220 <dd>length of the page body</dd>
\r
223 <p>Note that although the <tt>header</tt> and <tt>body</tt> pointers do
\r
224 not necessarily point into a single contiguous page vector, the page
\r
225 body must immediately follow the header in the bitstream.</p>
\r
227 <h2>Ogg Bitstream Manipulation Functions</h2>
\r
230 int ogg_page_bos(ogg_page *og);
\r
233 <p>Returns the 'beginning of stream' flag for the given Ogg page. The
\r
234 beginning of stream flag is set on the initial page of a logical
\r
237 <p>Zero indicates the flag is cleared (this is not the initial page of a
\r
238 logical bitstream). Nonzero indicates the flag is set (this is the
\r
239 initial page of a logical bitstream).</p>
\r
242 int ogg_page_continued(ogg_page *og);
\r
245 <p>Returns the 'packet continued' flag for the given Ogg page. The packet
\r
246 continued flag indicates whether or not the body data of this page
\r
247 begins with packet continued from a preceeding page.</p>
\r
249 <p>Zero (unset) indicates that the body data begins with a new packet.
\r
250 Nonzero (set) indicates that the first packet data on the page is a
\r
251 continuation from the preceeding page.</p>
\r
254 int ogg_page_eos(ogg_page *og);
\r
257 <p>Returns the 'end of stream' flag for a give Ogg page. The end of page
\r
258 flag is set on the last (terminal) page of a logical bitstream.</p>
\r
260 <p>Zero (unset) indicates that this is not the last page of a logical
\r
261 bitstream. Nonzero (set) indicates that this is the last page of a
\r
262 logical bitstream and that no addiitonal pages belonging to this
\r
263 bitstream may follow.</p>
\r
266 size64 ogg_page_granulepos(ogg_page *og);
\r
269 <p>Returns the position of this page as an absolute position within the
\r
270 original uncompressed data. The position, as returned, is 'frames
\r
271 encoded to date up to and including the last whole packet on this
\r
272 page'. Partial packets begun on this page but continued to the
\r
273 following page are not included. If no packet ends on this page, the
\r
274 frame position value will be equal to the frame position value of the
\r
275 preceeding page. If none of the original uncompressed data is yet
\r
276 represented in the logical bitstream (for example, the first page of a
\r
277 bitstream consists only of a header packet; this packet encodes only
\r
278 metadata), the value shall be zero.</p>
\r
280 <p>The units of the framenumber are determined by media mapping. A
\r
281 vorbis audio bitstream, for example, defines one frame to be the
\r
282 channel values from a single sampling period (eg, a 16 bit stereo
\r
283 bitstream consists of two samples of two bytes for a total of four
\r
284 bytes, thus a frame would be four bytes). A video stream defines one
\r
285 frame to be a single frame of video.</p>
\r
288 int ogg_page_pageno(ogg_page *og);
\r
291 <p>Returns the sequential page number of the given Ogg page. The first
\r
292 page in a logical bitstream is numbered zero; following pages are
\r
293 numbered in increasing monotonic order.</p>
\r
296 int ogg_page_serialno(ogg_page *og);
\r
299 <p>Returns the serial number of the given Ogg page. The serial number is
\r
300 used as a handle to distinguish various logical bitstreams in a
\r
301 physical Ogg bitstresm. Every logical bitstream within a
\r
302 physical bitstream must use a unique (within the scope of the physical
\r
303 bitstream) serial number, which is stamped on all bitstream pages.</p>
\r
306 int ogg_page_version(ogg_page *og);
\r
309 <p>Returns the revision of the Ogg bitstream structure of the given page.
\r
310 Currently, the only permitted number is zero. Later revisions of the
\r
311 bitstream spec will increment this version should any changes be
\r
315 int ogg_stream_clear(ogg_stream_state *os);
\r
318 <p>Clears and deallocates the internal storage of the given Ogg stream.
\r
319 After clearing, the stream structure is not initialized for use;
\r
320 <tt>ogg_stream_init</tt> must be called to reinitialize for use.
\r
321 Use <tt>ogg_stream_reset</tt> to reset the stream state
\r
322 to a fresh, intiialized state.</p>
\r
324 <p><tt>ogg_stream_clear</tt> does not call <tt>free()</tt> on the pointer
\r
325 <tt>os</tt>, allowing use of this call on stream structures in static
\r
326 or automatic storage. <tt>ogg_stream_destroy</tt>is a complimentary
\r
327 function that frees the pointer as well.</p>
\r
329 <p>Returns zero on success and non-zero on failure. This function always
\r
333 int ogg_stream_destroy(ogg_stream_state *os);
\r
336 <p>Clears and deallocates the internal storage of the given Ogg stream,
\r
337 then frees the storage associated with the pointer <tt>os</tt>.</p>
\r
339 <p><tt>ogg_stream_clear</tt> does not call <tt>free()</tt> on the pointer
\r
340 <tt>os</tt>, allowing use of that call on stream structures in static
\r
341 or automatic storage.</p>
\r
343 <p>Returns zero on success and non-zero on failure. This function always
\r
347 int ogg_stream_init(ogg_stream_state *os,int serialno);
\r
350 <p>Initialize the storage associated with <tt>os</tt> for use as an Ogg
\r
351 stream. This call is used to initialize a stream for both encode and
\r
352 decode. The given serial number is the serial number that will be
\r
353 stamped on pages of the produced bitstream (during encode), or used as
\r
354 a check that pages match (during decode).</p>
\r
356 <p>Returns zero on success, nonzero on failure.</p>
\r
359 int ogg_stream_packetin(ogg_stream_state *os, ogg_packet *op);
\r
362 <p>Used during encoding to add the given raw packet to the given Ogg
\r
363 bitstream. The contents of <tt>op</tt> are copied;
\r
364 <tt>ogg_stream_packetin</tt> does not retain any pointers into
\r
365 <tt>op</tt>'s storage. The encoding proccess buffers incoming packets
\r
366 until enough packets have been assembled to form an entire page;
\r
367 <tt>ogg_stream_pageout</tt> is used to read complete pages.</p>
\r
369 <p>Returns zero on success, nonzero on failure.</p>
\r
372 int ogg_stream_packetout(ogg_stream_state *os,ogg_packet *op);
\r
375 <p>Used during decoding to read raw packets from the given logical
\r
376 bitstream. <tt>ogg_stream_packetout</tt> will only return complete
\r
377 packets for which checksumming indicates no corruption. The size and
\r
378 contents of the packet exactly match those given in the encoding
\r
381 <p>Returns zero if the next packet is not ready to be read (not buffered
\r
382 or incomplete), positive if it returned a complete packet in
\r
383 <tt>op</tt> and negative if there is a gap, extra bytes or corruption
\r
384 at this position in the bitstream (essentially that the bitstream had
\r
385 to be recaptured). A negative value is not necessarily an error. It
\r
386 would be a common occurence when seeking, for example, which requires
\r
387 recapture of the bitstream at the position decoding continued.</p>
\r
389 <p>If the return value is positive, <tt>ogg_stream_packetout</tt> placed
\r
390 a packet in <tt>op</tt>. The data in <tt>op</tt> points to static
\r
391 storage that is valid until the next call to
\r
392 <tt>ogg_stream_pagein</tt>, <tt>ogg_stream_clear</tt>,
\r
393 <tt>ogg_stream_reset</tt>, or <tt>ogg_stream_destroy</tt>. The
\r
394 pointers are not invalidated by more calls to
\r
395 <tt>ogg_stream_packetout</tt>.</p>
\r
398 int ogg_stream_pagein(ogg_stream_state *os, ogg_page *og);
\r
401 <p>Used during decoding to buffer the given complete, pre-verified page
\r
402 for decoding into raw Ogg packets. The given page must be framed,
\r
403 normally produced by <tt>ogg_sync_pageout</tt>, and from the logical
\r
404 bitstream associated with <tt>os</tt> (the serial numbers must match).
\r
405 The contents of the given page are copied; <tt>ogg_stream_pagein</tt>
\r
406 retains no pointers into <tt>og</tt> storage.</p>
\r
408 <p>Returns zero on success and non-zero on failure.</p>
\r
411 int ogg_stream_pageout(ogg_stream_state *os, ogg_page *og);
\r
414 <p>Used during encode to read complete pages from the stream buffer. The
\r
415 returned page is ready for sending out to the real world.</p>
\r
417 <p>Returns zero if there is no complete page ready for reading. Returns
\r
418 nonzero when it has placed data for a complete page into
\r
419 <tt>og</tt>. Note that the storage returned in og points into internal
\r
420 storage; the pointers in <tt>og</tt> are valid until the next call to
\r
421 <tt>ogg_stream_pageout</tt>, <tt>ogg_stream_packetin</tt>,
\r
422 <tt>ogg_stream_reset</tt>, <tt>ogg_stream_clear</tt> or
\r
423 <tt>ogg_stream_destroy</tt>.</p>
\r
426 int ogg_stream_reset(ogg_stream_state *os);
\r
429 <p>Resets the given stream's state to that of a blank, unused stream;
\r
430 this may be used during encode or decode.</p>
\r
432 <p>Note that if used during encode, it does not alter the stream's serial
\r
433 number. In addition, the next page produced during encoding will be
\r
434 marked as the 'initial' page of the logical bitstream.</p>
\r
436 <p>When used during decode, this simply clears the data buffer of any
\r
437 pending pages. Beginning and end of stream cues are read from the
\r
438 bitstream and are unaffected by reset.</p>
\r
440 <p>Returns zero on success and non-zero on failure. This function always
\r
444 char *ogg_sync_buffer(ogg_sync_state *oy, long size);
\r
447 <p>This call is used to buffer a raw bitstream for framing and
\r
448 verification. <tt>ogg_sync_buffer</tt> handles stream capture and
\r
449 recapture, checksumming, and division into Ogg pages (as required by
\r
450 <tt>ogg_stream_pagein</tt>).</p>
\r
452 <p><tt>ogg_sync_buffer</tt> exposes a buffer area into which the decoder
\r
453 copies the next (up to) <tt>size</tt> bytes. We expose the buffer
\r
454 (rather than taking a buffer) in order to avoid an extra copy many
\r
455 uses; this way, for example, <tt>read()</tt> can transfer data
\r
456 directly into the stream buffer without first needing to place it in
\r
457 temporary storage.</p>
\r
459 <p>Returns a pointer into <tt>oy</tt>'s internal bitstream sync buffer;
\r
460 the remaining space in the sync buffer is at least <tt>size</tt>
\r
461 bytes. The decoder need not write all of <tt>size</tt> bytes;
\r
462 <tt>ogg_sync_wrote</tt> is used to inform the engine how many bytes
\r
463 were actually written. Use of <tt>ogg_sync_wrote</tt> after writing
\r
464 into the exposed buffer is mandantory.</p>
\r
467 int ogg_sync_clear(ogg_sync_state *oy);
\r
470 <p><tt>ogg_sync_clear</tt>
\r
471 clears and deallocates the internal storage of the given Ogg sync
\r
472 buffer. After clearing, the sync structure is not initialized for
\r
473 use; <tt>ogg_sync_init</tt> must be called to reinitialize for use.
\r
474 Use <tt>ogg_sync_reset</tt> to reset the sync state and buffer to a
\r
475 fresh, intiialized state.</p>
\r
477 <p><tt>ogg_sync_clear</tt> does not call <tt>free()</tt> on the pointer
\r
478 <tt>oy</tt>, allowing use of this call on sync structures in static
\r
479 or automatic storage. <tt>ogg_sync_destroy</tt>is a complimentary
\r
480 function that frees the pointer as well.</p>
\r
482 <p>Returns zero on success and non-zero on failure. This function always
\r
486 int ogg_sync_destroy(ogg_sync_state *oy);
\r
489 <p>Clears and deallocates the internal storage of the given Ogg sync
\r
490 buffer, then frees the storage associated with the pointer
\r
493 <p><tt>ogg_sync_clear</tt> does not call <tt>free()</tt> on the pointer
\r
494 <tt>oy</tt>, allowing use of that call on stream structures in static
\r
495 or automatic storage.</p>
\r
497 <p>Returns zero on success and non-zero on failure. This function always
\r
501 int ogg_sync_init(ogg_sync_state *oy);
\r
504 <p>Initializes the sync buffer <tt>oy</tt> for use.</p>
\r
506 <p>Returns zero on success and non-zero on failure. This function always
\r
510 int ogg_sync_pageout(ogg_sync_state *oy, ogg_page *og);
\r
513 <p>Reads complete, framed, verified Ogg pages from the sync buffer,
\r
514 placing the page data in <tt>og</tt>.</p>
\r
516 <p>Returns zero when there's no complete pages buffered for
\r
517 retrieval. Returns negative when a loss of sync or recapture occurred
\r
518 (this is not necessarily an error; recapture would be required after
\r
519 seeking, for example). Returns positive when a page is returned in
\r
520 <tt>og</tt>. Note that the data in <tt>og</tt> points into the sync
\r
521 buffer storage; the pointers are valid until the next call to
\r
522 <tt>ogg_sync_buffer</tt>, <tt>ogg_sync_clear</tt>,
\r
523 <tt>ogg_sync_destroy</tt> or <tt>ogg_sync_reset</tt>.</p>
\r
526 int ogg_sync_reset(ogg_sync_state *oy);
\r
529 <p><tt>ogg_sync_reset</tt> resets the sync state in <tt>oy</tt> to a
\r
530 clean, empty state. This is useful, for example, when seeking to a
\r
531 new location in a bitstream.</p>
\r
533 <p>Returns zero on success, nonzero on failure.</p>
\r
536 int ogg_sync_wrote(ogg_sync_state *oy, long bytes);
\r
539 <p>Used to inform the sync state as to how many bytes were actually
\r
540 written into the exposed sync buffer. It must be equal to or less
\r
541 than the size of the buffer requested.</p>
\r
543 <p>Returns zero on success and non-zero on failure; failure occurs only
\r
544 when the number of bytes written were larger than the buffer.</p>
\r
546 <div id="copyright">
\r
547 The Xiph Fish Logo is a
\r
548 trademark (™) of Xiph.Org.<br/>
\r
550 These pages © 1994 - 2005 Xiph.Org. All rights reserved.
\r
projects / platform / upstream / libvorbis.git / blob