00001 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
00002 <html>
00003 <head>
00004
00005 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
00006 <title>Ogg Vorbis Documentation</title>
00007
00008 <style type="text/css">
00009 body {
00010 margin: 0 18px 0 18px;
00011 padding-bottom: 30px;
00012 font-family: Verdana, Arial, Helvetica, sans-serif;
00013 color: #333333;
00014 font-size: .8em;
00015 }
00016
00017 a {
00018 color: #3366cc;
00019 }
00020
00021 img {
00022 border: 0;
00023 }
00024
00025 #xiphlogo {
00026 margin: 30px 0 16px 0;
00027 }
00028
00029 #content p {
00030 line-height: 1.4;
00031 }
00032
00033 h1, h1 a, h2, h2 a, h3, h3 a {
00034 font-weight: bold;
00035 color: #ff9900;
00036 margin: 1.3em 0 8px 0;
00037 }
00038
00039 h1 {
00040 font-size: 1.3em;
00041 }
00042
00043 h2 {
00044 font-size: 1.2em;
00045 }
00046
00047 h3 {
00048 font-size: 1.1em;
00049 }
00050
00051 li {
00052 line-height: 1.4;
00053 }
00054
00055 #copyright {
00056 margin-top: 30px;
00057 line-height: 1.5em;
00058 text-align: center;
00059 font-size: .8em;
00060 color: #888888;
00061 clear: both;
00062 }
00063 </style>
00064
00065 </head>
00066
00067 <body>
00068
00069 <div id="xiphlogo">
00070 <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.org"/></a>
00071 </div>
00072
00073 <h1>Programming with Xiph.org <tt>libvorbis</tt></h1>
00074
00075 <h2>Description</h2>
00076
00077 <p>Libvorbis is the Xiph.org Foundation's portable Ogg Vorbis CODEC
00078 implemented as a programmatic library. Libvorbis provides primitives
00079 to handle framing and manipulation of Ogg bitstreams (used by the
00080 Vorbis for streaming), a full analysis (encoding) interface as well as
00081 packet decoding and synthesis for playback.</p>
00082
00083 <p>The libvorbis library does not provide any system interface; a
00084 full-featured demonstration player included with the library
00085 distribtion provides example code for a variety of system interfaces
00086 as well as a working example of using libvorbis in production code.</p>
00087
00088 <h2>Encoding Overview</h2>
00089
00090 <h2>Decoding Overview</h2>
00091
00092 <p>Decoding a bitstream with libvorbis follows roughly the following
00093 steps:</p>
00094
00095 <ol>
00096 <li>Frame the incoming bitstream into pages</li>
00097 <li>Sort the pages by logical bitstream and buffer then into logical streams</li>
00098 <li>Decompose the logical streams into raw packets</li>
00099 <li>Reconstruct segments of the original data from each packet</li>
00100 <li>Glue the reconstructed segments back into a decoded stream</li>
00101 </ol>
00102
00103 <h3>Framing</h3>
00104
00105 <p>An Ogg bitstream is logically arranged into pages, but to decode
00106 the pages, we have to find them first. The raw bitstream is first fed
00107 into an <tt>ogg_sync_state</tt> buffer using <tt>ogg_sync_buffer()</tt>
00108 and <tt>ogg_sync_wrote()</tt>. After each block we submit to the sync
00109 buffer, we should check to see if we can frame and extract a complete
00110 page or pages using <tt>ogg_sync_pageout()</tt>. Extra pages are
00111 buffered; allowing them to build up in the <tt>ogg_sync_state</tt>
00112 buffer will eventually exhaust memory.</p>
00113
00114 <p>The Ogg pages returned from <tt>ogg_sync_pageout</tt> need not be
00115 decoded further to be used as landmarks in seeking; seeking can be
00116 either a rough process of simply jumping to approximately intuited
00117 portions of the bitstream, or it can be a precise bisection process
00118 that captures pages and inspects data position. When seeking,
00119 however, sequential multiplexing (chaining) must be accounted for;
00120 beginning play in a new logical bitstream requires initializing a
00121 synthesis engine with the headers from that bitstream. Vorbis
00122 bitstreams do not make use of concurent multiplexing (grouping).</p>
00123
00124 <h3>Sorting</h3>
00125
00126 <p>The pages produced by <tt>ogg_sync_pageout</tt> are then sorted by
00127 serial number to seperate logical bitstreams. Initialize logical
00128 bitstream buffers (<tt>og_stream_state</tt>) using
00129 <tt>ogg_stream_init()</tt>. Pages are submitted to the matching
00130 logical bitstream buffer using <tt>ogg_stream_pagein</tt>; the serial
00131 number of the page and the stream buffer must match, or the page will
00132 be rejected. A page submitted out of sequence will simply be noted,
00133 and in the course of outputting packets, the hole will be flagged
00134 (<tt>ogg_sync_pageout</tt> and <tt>ogg_stream_packetout</tt> will
00135 return a negative value at positions where they had to recapture the
00136 stream).</p>
00137
00138 <h3>Extracting packets</h3>
00139
00140 <p>After submitting page[s] to a logical stream, read available packets
00141 using <tt>ogg_stream_packetout</tt>.</p>
00142
00143 <h3>Decoding packets</h3>
00144
00145 <h3>Reassembling data segments</h3>
00146
00147 <h2>Ogg Bitstream Manipulation Structures</h2>
00148
00149 <p>Two of the Ogg bitstream data structures are intended to be
00150 transparent to the developer; the fields should be used directly.</p>
00151
00152 <h3>ogg_packet</h3>
00153
00154 <pre>
00155 typedef struct {
00156 unsigned char *packet;
00157 long bytes;
00158 long b_o_s;
00159 long e_o_s;
00160
00161 size64 granulepos;
00162
00163 } ogg_packet;
00164 </pre>
00165
00166 <dl>
00167 <dt>packet:</dt>
00168 <dd>a pointer to the byte data of the raw packet</dd>
00169 <dt>bytes:</dt>
00170 <dd>the size of the packet' raw data</dd>
00171 <dt>b_o_s:</dt>
00172 <dd>beginning of stream; nonzero if this is the first packet of
00173 the logical bitstream</dd>
00174 <dt>e_o_s:</dt>
00175 <dd>end of stream; nonzero if this is the last packet of the
00176 logical bitstream</dd>
00177 <dt>granulepos:</dt>
00178 <dd>the absolute position of this packet in the original
00179 uncompressed data stream.</dd>
00180 </dl>
00181
00182 <h4>encoding notes</h4>
00183
00184 <p>The encoder is responsible for setting all of
00185 the fields of the packet to appropriate values before submission to
00186 <tt>ogg_stream_packetin()</tt>; however, it is noted that the value in
00187 <tt>b_o_s</tt> is ignored; the first page produced from a given
00188 <tt>ogg_stream_state</tt> structure will be stamped as the initial
00189 page. <tt>e_o_s</tt>, however, must be set; this is the means by
00190 which the stream encoding primitives handle end of stream and cleanup.</p>
00191
00192 <h4>decoding notes</h4>
00193
00194 <p><tt>ogg_stream_packetout()</tt> sets the fields
00195 to appropriate values. Note that granulepos will be >= 0 only in the
00196 case that the given packet actually represents that position (ie, only
00197 the last packet completed on any page will have a meaningful
00198 <tt>granulepos</tt>). Intervening frames will see <tt>granulepos</tt> set
00199 to -1.</p>
00200
00201 <h3>ogg_page</h3>
00202
00203 <pre>
00204 typedef struct {
00205 unsigned char *header;
00206 long header_len;
00207 unsigned char *body;
00208 long body_len;
00209 } ogg_page;
00210 </pre>
00211
00212 <dl>
00213 <dt>header:</dt>
00214 <dd>pointer to the page header data</dd>
00215 <dt>header_len:</dt>
00216 <dd>length of the page header in bytes</dd>
00217 <dt>body:</dt>
00218 <dd>pointer to the page body</dd>
00219 <dt>body_len:</dt>
00220 <dd>length of the page body</dd>
00221 </dl>
00222
00223 <p>Note that although the <tt>header</tt> and <tt>body</tt> pointers do
00224 not necessarily point into a single contiguous page vector, the page
00225 body must immediately follow the header in the bitstream.</p>
00226
00227 <h2>Ogg Bitstream Manipulation Functions</h2>
00228
00229 <h3>
00230 int ogg_page_bos(ogg_page *og);
00231 </h3>
00232
00233 <p>Returns the 'beginning of stream' flag for the given Ogg page. The
00234 beginning of stream flag is set on the initial page of a logical
00235 bitstream.</p>
00236
00237 <p>Zero indicates the flag is cleared (this is not the initial page of a
00238 logical bitstream). Nonzero indicates the flag is set (this is the
00239 initial page of a logical bitstream).</p>
00240
00241 <h3>
00242 int ogg_page_continued(ogg_page *og);
00243 </h3>
00244
00245 <p>Returns the 'packet continued' flag for the given Ogg page. The packet
00246 continued flag indicates whether or not the body data of this page
00247 begins with packet continued from a preceeding page.</p>
00248
00249 <p>Zero (unset) indicates that the body data begins with a new packet.
00250 Nonzero (set) indicates that the first packet data on the page is a
00251 continuation from the preceeding page.</p>
00252
00253 <h3>
00254 int ogg_page_eos(ogg_page *og);
00255 </h3>
00256
00257 <p>Returns the 'end of stream' flag for a give Ogg page. The end of page
00258 flag is set on the last (terminal) page of a logical bitstream.</p>
00259
00260 <p>Zero (unset) indicates that this is not the last page of a logical
00261 bitstream. Nonzero (set) indicates that this is the last page of a
00262 logical bitstream and that no addiitonal pages belonging to this
00263 bitstream may follow.</p>
00264
00265 <h3>
00266 size64 ogg_page_granulepos(ogg_page *og);
00267 </h3>
00268
00269 <p>Returns the position of this page as an absolute position within the
00270 original uncompressed data. The position, as returned, is 'frames
00271 encoded to date up to and including the last whole packet on this
00272 page'. Partial packets begun on this page but continued to the
00273 following page are not included. If no packet ends on this page, the
00274 frame position value will be equal to the frame position value of the
00275 preceeding page. If none of the original uncompressed data is yet
00276 represented in the logical bitstream (for example, the first page of a
00277 bitstream consists only of a header packet; this packet encodes only
00278 metadata), the value shall be zero.</p>
00279
00280 <p>The units of the framenumber are determined by media mapping. A
00281 vorbis audio bitstream, for example, defines one frame to be the
00282 channel values from a single sampling period (eg, a 16 bit stereo
00283 bitstream consists of two samples of two bytes for a total of four
00284 bytes, thus a frame would be four bytes). A video stream defines one
00285 frame to be a single frame of video.</p>
00286
00287 <h3>
00288 int ogg_page_pageno(ogg_page *og);
00289 </h3>
00290
00291 <p>Returns the sequential page number of the given Ogg page. The first
00292 page in a logical bitstream is numbered zero; following pages are
00293 numbered in increasing monotonic order.</p>
00294
00295 <h3>
00296 int ogg_page_serialno(ogg_page *og);
00297 </h3>
00298
00299 <p>Returns the serial number of the given Ogg page. The serial number is
00300 used as a handle to distinguish various logical bitstreams in a
00301 physical Ogg bitstresm. Every logical bitstream within a
00302 physical bitstream must use a unique (within the scope of the physical
00303 bitstream) serial number, which is stamped on all bitstream pages.</p>
00304
00305 <h3>
00306 int ogg_page_version(ogg_page *og);
00307 </h3>
00308
00309 <p>Returns the revision of the Ogg bitstream structure of the given page.
00310 Currently, the only permitted number is zero. Later revisions of the
00311 bitstream spec will increment this version should any changes be
00312 incompatable.</p>
00313
00314 <h3>
00315 int ogg_stream_clear(ogg_stream_state *os);
00316 </h3>
00317
00318 <p>Clears and deallocates the internal storage of the given Ogg stream.
00319 After clearing, the stream structure is not initialized for use;
00320 <tt>ogg_stream_init</tt> must be called to reinitialize for use.
00321 Use <tt>ogg_stream_reset</tt> to reset the stream state
00322 to a fresh, intiialized state.</p>
00323
00324 <p><tt>ogg_stream_clear</tt> does not call <tt>free()</tt> on the pointer
00325 <tt>os</tt>, allowing use of this call on stream structures in static
00326 or automatic storage. <tt>ogg_stream_destroy</tt>is a complimentary
00327 function that frees the pointer as well.</p>
00328
00329 <p>Returns zero on success and non-zero on failure. This function always
00330 succeeds.</p>
00331
00332 <h3>
00333 int ogg_stream_destroy(ogg_stream_state *os);
00334 </h3>
00335
00336 <p>Clears and deallocates the internal storage of the given Ogg stream,
00337 then frees the storage associated with the pointer <tt>os</tt>.</p>
00338
00339 <p><tt>ogg_stream_clear</tt> does not call <tt>free()</tt> on the pointer
00340 <tt>os</tt>, allowing use of that call on stream structures in static
00341 or automatic storage.</p>
00342
00343 <p>Returns zero on success and non-zero on failure. This function always
00344 succeeds.</p>
00345
00346 <h3>
00347 int ogg_stream_init(ogg_stream_state *os,int serialno);
00348 </h3>
00349
00350 <p>Initialize the storage associated with <tt>os</tt> for use as an Ogg
00351 stream. This call is used to initialize a stream for both encode and
00352 decode. The given serial number is the serial number that will be
00353 stamped on pages of the produced bitstream (during encode), or used as
00354 a check that pages match (during decode).</p>
00355
00356 <p>Returns zero on success, nonzero on failure.</p>
00357
00358 <h3>
00359 int ogg_stream_packetin(ogg_stream_state *os, ogg_packet *op);
00360 </h3>
00361
00362 <p>Used during encoding to add the given raw packet to the given Ogg
00363 bitstream. The contents of <tt>op</tt> are copied;
00364 <tt>ogg_stream_packetin</tt> does not retain any pointers into
00365 <tt>op</tt>'s storage. The encoding proccess buffers incoming packets
00366 until enough packets have been assembled to form an entire page;
00367 <tt>ogg_stream_pageout</tt> is used to read complete pages.</p>
00368
00369 <p>Returns zero on success, nonzero on failure.</p>
00370
00371 <h3>
00372 int ogg_stream_packetout(ogg_stream_state *os,ogg_packet *op);
00373 </h3>
00374
00375 <p>Used during decoding to read raw packets from the given logical
00376 bitstream. <tt>ogg_stream_packetout</tt> will only return complete
00377 packets for which checksumming indicates no corruption. The size and
00378 contents of the packet exactly match those given in the encoding
00379 process. </p>
00380
00381 <p>Returns zero if the next packet is not ready to be read (not buffered
00382 or incomplete), positive if it returned a complete packet in
00383 <tt>op</tt> and negative if there is a gap, extra bytes or corruption
00384 at this position in the bitstream (essentially that the bitstream had
00385 to be recaptured). A negative value is not necessarily an error. It
00386 would be a common occurence when seeking, for example, which requires
00387 recapture of the bitstream at the position decoding continued.</p>
00388
00389 <p>If the return value is positive, <tt>ogg_stream_packetout</tt> placed
00390 a packet in <tt>op</tt>. The data in <tt>op</tt> points to static
00391 storage that is valid until the next call to
00392 <tt>ogg_stream_pagein</tt>, <tt>ogg_stream_clear</tt>,
00393 <tt>ogg_stream_reset</tt>, or <tt>ogg_stream_destroy</tt>. The
00394 pointers are not invalidated by more calls to
00395 <tt>ogg_stream_packetout</tt>.</p>
00396
00397 <h3>
00398 int ogg_stream_pagein(ogg_stream_state *os, ogg_page *og);
00399 </h3>
00400
00401 <p>Used during decoding to buffer the given complete, pre-verified page
00402 for decoding into raw Ogg packets. The given page must be framed,
00403 normally produced by <tt>ogg_sync_pageout</tt>, and from the logical
00404 bitstream associated with <tt>os</tt> (the serial numbers must match).
00405 The contents of the given page are copied; <tt>ogg_stream_pagein</tt>
00406 retains no pointers into <tt>og</tt> storage.</p>
00407
00408 <p>Returns zero on success and non-zero on failure.</p>
00409
00410 <h3>
00411 int ogg_stream_pageout(ogg_stream_state *os, ogg_page *og);
00412 </h3>
00413
00414 <p>Used during encode to read complete pages from the stream buffer. The
00415 returned page is ready for sending out to the real world.</p>
00416
00417 <p>Returns zero if there is no complete page ready for reading. Returns
00418 nonzero when it has placed data for a complete page into
00419 <tt>og</tt>. Note that the storage returned in og points into internal
00420 storage; the pointers in <tt>og</tt> are valid until the next call to
00421 <tt>ogg_stream_pageout</tt>, <tt>ogg_stream_packetin</tt>,
00422 <tt>ogg_stream_reset</tt>, <tt>ogg_stream_clear</tt> or
00423 <tt>ogg_stream_destroy</tt>.</p>
00424
00425 <h3>
00426 int ogg_stream_reset(ogg_stream_state *os);
00427 </h3>
00428
00429 <p>Resets the given stream's state to that of a blank, unused stream;
00430 this may be used during encode or decode.</p>
00431
00432 <p>Note that if used during encode, it does not alter the stream's serial
00433 number. In addition, the next page produced during encoding will be
00434 marked as the 'initial' page of the logical bitstream.</p>
00435
00436 <p>When used during decode, this simply clears the data buffer of any
00437 pending pages. Beginning and end of stream cues are read from the
00438 bitstream and are unaffected by reset.</p>
00439
00440 <p>Returns zero on success and non-zero on failure. This function always
00441 succeeds.</p>
00442
00443 <h3>
00444 char *ogg_sync_buffer(ogg_sync_state *oy, long size);
00445 </h3>
00446
00447 <p>This call is used to buffer a raw bitstream for framing and
00448 verification. <tt>ogg_sync_buffer</tt> handles stream capture and
00449 recapture, checksumming, and division into Ogg pages (as required by
00450 <tt>ogg_stream_pagein</tt>).</p>
00451
00452 <p><tt>ogg_sync_buffer</tt> exposes a buffer area into which the decoder
00453 copies the next (up to) <tt>size</tt> bytes. We expose the buffer
00454 (rather than taking a buffer) in order to avoid an extra copy many
00455 uses; this way, for example, <tt>read()</tt> can transfer data
00456 directly into the stream buffer without first needing to place it in
00457 temporary storage.</p>
00458
00459 <p>Returns a pointer into <tt>oy</tt>'s internal bitstream sync buffer;
00460 the remaining space in the sync buffer is at least <tt>size</tt>
00461 bytes. The decoder need not write all of <tt>size</tt> bytes;
00462 <tt>ogg_sync_wrote</tt> is used to inform the engine how many bytes
00463 were actually written. Use of <tt>ogg_sync_wrote</tt> after writing
00464 into the exposed buffer is mandantory.</p>
00465
00466 <h3>
00467 int ogg_sync_clear(ogg_sync_state *oy);
00468 </h3>
00469
00470 <p><tt>ogg_sync_clear</tt>
00471 clears and deallocates the internal storage of the given Ogg sync
00472 buffer. After clearing, the sync structure is not initialized for
00473 use; <tt>ogg_sync_init</tt> must be called to reinitialize for use.
00474 Use <tt>ogg_sync_reset</tt> to reset the sync state and buffer to a
00475 fresh, intiialized state.</p>
00476
00477 <p><tt>ogg_sync_clear</tt> does not call <tt>free()</tt> on the pointer
00478 <tt>oy</tt>, allowing use of this call on sync structures in static
00479 or automatic storage. <tt>ogg_sync_destroy</tt>is a complimentary
00480 function that frees the pointer as well.</p>
00481
00482 <p>Returns zero on success and non-zero on failure. This function always
00483 succeeds.</p>
00484
00485 <h3>
00486 int ogg_sync_destroy(ogg_sync_state *oy);
00487 </h3>
00488
00489 <p>Clears and deallocates the internal storage of the given Ogg sync
00490 buffer, then frees the storage associated with the pointer
00491 <tt>oy</tt>.</p>
00492
00493 <p><tt>ogg_sync_clear</tt> does not call <tt>free()</tt> on the pointer
00494 <tt>oy</tt>, allowing use of that call on stream structures in static
00495 or automatic storage.</p>
00496
00497 <p>Returns zero on success and non-zero on failure. This function always
00498 succeeds.</p>
00499
00500 <h3>
00501 int ogg_sync_init(ogg_sync_state *oy);
00502 </h3>
00503
00504 <p>Initializes the sync buffer <tt>oy</tt> for use.</p>
00505
00506 <p>Returns zero on success and non-zero on failure. This function always
00507 succeeds.</p>
00508
00509 <h3>
00510 int ogg_sync_pageout(ogg_sync_state *oy, ogg_page *og);
00511 </h3>
00512
00513 <p>Reads complete, framed, verified Ogg pages from the sync buffer,
00514 placing the page data in <tt>og</tt>.</p>
00515
00516 <p>Returns zero when there's no complete pages buffered for
00517 retrieval. Returns negative when a loss of sync or recapture occurred
00518 (this is not necessarily an error; recapture would be required after
00519 seeking, for example). Returns positive when a page is returned in
00520 <tt>og</tt>. Note that the data in <tt>og</tt> points into the sync
00521 buffer storage; the pointers are valid until the next call to
00522 <tt>ogg_sync_buffer</tt>, <tt>ogg_sync_clear</tt>,
00523 <tt>ogg_sync_destroy</tt> or <tt>ogg_sync_reset</tt>.</p>
00524
00525 <h3>
00526 int ogg_sync_reset(ogg_sync_state *oy);
00527 </h3>
00528
00529 <p><tt>ogg_sync_reset</tt> resets the sync state in <tt>oy</tt> to a
00530 clean, empty state. This is useful, for example, when seeking to a
00531 new location in a bitstream.</p>
00532
00533 <p>Returns zero on success, nonzero on failure.</p>
00534
00535 <h3>
00536 int ogg_sync_wrote(ogg_sync_state *oy, long bytes);
00537 </h3>
00538
00539 <p>Used to inform the sync state as to how many bytes were actually
00540 written into the exposed sync buffer. It must be equal to or less
00541 than the size of the buffer requested.</p>
00542
00543 <p>Returns zero on success and non-zero on failure; failure occurs only
00544 when the number of bytes written were larger than the buffer.</p>
00545
00546 <div id="copyright">
00547 The Xiph Fish Logo is a
00548 trademark (™) of Xiph.Org.<br/>
00549
00550 These pages © 1994 - 2005 Xiph.Org. All rights reserved.
00551 </div>
00552
00553 </body>
00554 </html>
