doc/programming.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   2 <html>
   3 <head>
   4
   5 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
   6 <title>Ogg Vorbis Documentation</title>
   7
   8 <style type="text/css">
   9 body {
  10   margin: 0 18px 0 18px;
  11   padding-bottom: 30px;
  12   font-family: Verdana, Arial, Helvetica, sans-serif;
  13   color: #333333;
  14   font-size: .8em;
  15 }
  16
  17 a {
  18   color: #3366cc;
  19 }
  20
  21 img {
  22   border: 0;
  23 }
  24
  25 #xiphlogo {
  26   margin: 30px 0 16px 0;
  27 }
  28
  29 #content p {
  30   line-height: 1.4;
  31 }
  32
  33 h1, h1 a, h2, h2 a, h3, h3 a {
  34   font-weight: bold;
  35   color: #ff9900;
  36   margin: 1.3em 0 8px 0;
  37 }
  38
  39 h1 {
  40   font-size: 1.3em;
  41 }
  42
  43 h2 {
  44   font-size: 1.2em;
  45 }
  46
  47 h3 {
  48   font-size: 1.1em;
  49 }
  50
  51 li {
  52   line-height: 1.4;
  53 }
  54
  55 #copyright {
  56   margin-top: 30px;
  57   line-height: 1.5em;
  58   text-align: center;
  59   font-size: .8em;
  60   color: #888888;
  61   clear: both;
  62 }
  63 </style>
  64
  65 </head>
  66
  67 <body>
  68
  69 <div id="xiphlogo">
  70   <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.Org"/></a>
  71 </div>
  72
  73 <h1>Programming with Xiph.Org <tt>libvorbis</tt></h1>
  74
  75 <h2>Description</h2>
  76
  77 <p>Libvorbis is the Xiph.Org Foundation's portable Ogg Vorbis CODEC
  78 implemented as a programmatic library. Libvorbis provides primitives
  79 to handle framing and manipulation of Ogg bitstreams (used by the
  80 Vorbis for streaming), a full analysis (encoding) interface as well as
  81 packet decoding and synthesis for playback.</p>
  82
  83 <p>The libvorbis library does not provide any system interface; a
  84 full-featured demonstration player included with the library
  85 distribtion provides example code for a variety of system interfaces
  86 as well as a working example of using libvorbis in production code.</p>
  87
  88 <h2>Encoding Overview</h2>
  89
  90 <h2>Decoding Overview</h2>
  91
  92 <p>Decoding a bitstream with libvorbis follows roughly the following
  93 steps:</p>
  94
  95 <ol>
  96 <li>Frame the incoming bitstream into pages</li>
  97 <li>Sort the pages by logical bitstream and buffer then into logical streams</li>
  98 <li>Decompose the logical streams into raw packets</li>
  99 <li>Reconstruct segments of the original data from each packet</li>
 100 <li>Glue the reconstructed segments back into a decoded stream</li>
 101 </ol>
 102
 103 <h3>Framing</h3>
 104
 105 <p>An Ogg bitstream is logically arranged into pages, but to decode
 106 the pages, we have to find them first. The raw bitstream is first fed
 107 into an <tt>ogg_sync_state</tt> buffer using <tt>ogg_sync_buffer()</tt>
 108 and <tt>ogg_sync_wrote()</tt>. After each block we submit to the sync
 109 buffer, we should check to see if we can frame and extract a complete
 110 page or pages using <tt>ogg_sync_pageout()</tt>. Extra pages are
 111 buffered; allowing them to build up in the <tt>ogg_sync_state</tt>
 112 buffer will eventually exhaust memory.</p>
 113
 114 <p>The Ogg pages returned from <tt>ogg_sync_pageout</tt> need not be
 115 decoded further to be used as landmarks in seeking; seeking can be
 116 either a rough process of simply jumping to approximately intuited
 117 portions of the bitstream, or it can be a precise bisection process
 118 that captures pages and inspects data position. When seeking,
 119 however, sequential multiplexing (chaining) must be accounted for;
 120 beginning play in a new logical bitstream requires initializing a
 121 synthesis engine with the headers from that bitstream. Vorbis
 122 bitstreams do not make use of concurent multiplexing (grouping).</p>
 123
 124 <h3>Sorting</h3>
 125
 126 <p>The pages produced by <tt>ogg_sync_pageout</tt> are then sorted by
 127 serial number to seperate logical bitstreams. Initialize logical
 128 bitstream buffers (<tt>og_stream_state</tt>) using
 129 <tt>ogg_stream_init()</tt>. Pages are submitted to the matching
 130 logical bitstream buffer using <tt>ogg_stream_pagein</tt>; the serial
 131 number of the page and the stream buffer must match, or the page will
 132 be rejected. A page submitted out of sequence will simply be noted,
 133 and in the course of outputting packets, the hole will be flagged
 134 (<tt>ogg_sync_pageout</tt> and <tt>ogg_stream_packetout</tt> will
 135 return a negative value at positions where they had to recapture the
 136 stream).</p>
 137
 138 <h3>Extracting packets</h3>
 139
 140 <p>After submitting page[s] to a logical stream, read available packets
 141 using <tt>ogg_stream_packetout</tt>.</p>
 142
 143 <h3>Decoding packets</h3>
 144
 145 <h3>Reassembling data segments</h3>
 146
 147 <h2>Ogg Bitstream Manipulation Structures</h2>
 148
 149 <p>Two of the Ogg bitstream data structures are intended to be
 150 transparent to the developer; the fields should be used directly.</p>
 151
 152 <h3>ogg_packet</h3>
 153
 154 <pre>
 155 typedef struct {
 156   unsigned char *packet;
 157   long  bytes;
 158   long  b_o_s;
 159   long  e_o_s;
 160
 161   size64 granulepos;
 162
 163 } ogg_packet;
 164 </pre>
 165
 166 <dl>
 167 <dt>packet:</dt>
 168 <dd>a pointer to the byte data of the raw packet</dd>
 169 <dt>bytes:</dt>
 170 <dd>the size of the packet' raw data</dd>
 171 <dt>b_o_s:</dt>
 172 <dd>beginning of stream; nonzero if this is the first packet of
 173   the logical bitstream</dd>
 174 <dt>e_o_s:</dt>
 175 <dd>end of stream; nonzero if this is the last packet of the
 176   logical bitstream</dd>
 177 <dt>granulepos:</dt>
 178 <dd>the absolute position of this packet in the original
 179   uncompressed data stream.</dd>
 180 </dl>
 181
 182 <h4>encoding notes</h4>
 183
 184 <p>The encoder is responsible for setting all of
 185 the fields of the packet to appropriate values before submission to
 186 <tt>ogg_stream_packetin()</tt>; however, it is noted that the value in
 187 <tt>b_o_s</tt> is ignored; the first page produced from a given
 188 <tt>ogg_stream_state</tt> structure will be stamped as the initial
 189 page. <tt>e_o_s</tt>, however, must be set; this is the means by
 190 which the stream encoding primitives handle end of stream and cleanup.</p>
 191
 192 <h4>decoding notes</h4>
 193
 194 <p><tt>ogg_stream_packetout()</tt> sets the fields
 195 to appropriate values. Note that granulepos will be >= 0 only in the
 196 case that the given packet actually represents that position (ie, only
 197 the last packet completed on any page will have a meaningful
 198 <tt>granulepos</tt>). Intervening frames will see <tt>granulepos</tt> set
 199 to -1.</p>
 200
 201 <h3>ogg_page</h3>
 202
 203 <pre>
 204 typedef struct {
 205   unsigned char *header;
 206   long header_len;
 207   unsigned char *body;
 208   long body_len;
 209 } ogg_page;
 210 </pre>
 211
 212 <dl>
 213 <dt>header:</dt>
 214 <dd>pointer to the page header data</dd>
 215 <dt>header_len:</dt>
 216 <dd>length of the page header in bytes</dd>
 217 <dt>body:</dt>
 218 <dd>pointer to the page body</dd>
 219 <dt>body_len:</dt>
 220 <dd>length of the page body</dd>
 221 </dl>
 222
 223 <p>Note that although the <tt>header</tt> and <tt>body</tt> pointers do
 224 not necessarily point into a single contiguous page vector, the page
 225 body must immediately follow the header in the bitstream.</p>
 226
 227 <h2>Ogg Bitstream Manipulation Functions</h2>
 228
 229 <h3>
 230 int    ogg_page_bos(ogg_page *og);
 231 </h3>
 232
 233 <p>Returns the 'beginning of stream' flag for the given Ogg page. The
 234 beginning of stream flag is set on the initial page of a logical
 235 bitstream.</p>
 236
 237 <p>Zero indicates the flag is cleared (this is not the initial page of a
 238 logical bitstream). Nonzero indicates the flag is set (this is the
 239 initial page of a logical bitstream).</p>
 240
 241 <h3>
 242 int    ogg_page_continued(ogg_page *og);
 243 </h3>
 244
 245 <p>Returns the 'packet continued' flag for the given Ogg page. The packet
 246 continued flag indicates whether or not the body data of this page
 247 begins with packet continued from a preceeding page.</p>
 248
 249 <p>Zero (unset) indicates that the body data begins with a new packet.
 250 Nonzero (set) indicates that the first packet data on the page is a
 251 continuation from the preceeding page.</p>
 252
 253 <h3>
 254 int    ogg_page_eos(ogg_page *og);
 255 </h3>
 256
 257 <p>Returns the 'end of stream' flag for a give Ogg page. The end of page
 258 flag is set on the last (terminal) page of a logical bitstream.</p>
 259
 260 <p>Zero (unset) indicates that this is not the last page of a logical
 261 bitstream. Nonzero (set) indicates that this is the last page of a
 262 logical bitstream and that no addiitonal pages belonging to this
 263 bitstream may follow.</p>
 264
 265 <h3>
 266 size64 ogg_page_granulepos(ogg_page *og);
 267 </h3>
 268
 269 <p>Returns the position of this page as an absolute position within the
 270 original uncompressed data. The position, as returned, is 'frames
 271 encoded to date up to and including the last whole packet on this
 272 page'. Partial packets begun on this page but continued to the
 273 following page are not included. If no packet ends on this page, the
 274 frame position value will be equal to the frame position value of the
 275 preceeding page. If none of the original uncompressed data is yet
 276 represented in the logical bitstream (for example, the first page of a
 277 bitstream consists only of a header packet; this packet encodes only
 278 metadata), the value shall be zero.</p>
 279
 280 <p>The units of the framenumber are determined by media mapping. A
 281 vorbis audio bitstream, for example, defines one frame to be the
 282 channel values from a single sampling period (eg, a 16 bit stereo
 283 bitstream consists of two samples of two bytes for a total of four
 284 bytes, thus a frame would be four bytes). A video stream defines one
 285 frame to be a single frame of video.</p>
 286
 287 <h3>
 288 int    ogg_page_pageno(ogg_page *og);
 289 </h3>
 290
 291 <p>Returns the sequential page number of the given Ogg page. The first
 292 page in a logical bitstream is numbered zero; following pages are
 293 numbered in increasing monotonic order.</p>
 294
 295 <h3>
 296 int    ogg_page_serialno(ogg_page *og);
 297 </h3>
 298
 299 <p>Returns the serial number of the given Ogg page. The serial number is
 300 used as a handle to distinguish various logical bitstreams in a
 301 physical Ogg bitstresm. Every logical bitstream within a
 302 physical bitstream must use a unique (within the scope of the physical
 303 bitstream) serial number, which is stamped on all bitstream pages.</p>
 304
 305 <h3>
 306 int    ogg_page_version(ogg_page *og);
 307 </h3>
 308
 309 <p>Returns the revision of the Ogg bitstream structure of the given page.
 310 Currently, the only permitted number is zero. Later revisions of the
 311 bitstream spec will increment this version should any changes be
 312 incompatable.</p>
 313
 314 <h3>
 315 int    ogg_stream_clear(ogg_stream_state *os);
 316 </h3>
 317
 318 <p>Clears and deallocates the internal storage of the given Ogg stream.
 319 After clearing, the stream structure is not initialized for use;
 320 <tt>ogg_stream_init</tt> must be called to reinitialize for use.
 321 Use <tt>ogg_stream_reset</tt> to reset the stream state
 322 to a fresh, intiialized state.</p>
 323
 324 <p><tt>ogg_stream_clear</tt> does not call <tt>free()</tt> on the pointer
 325 <tt>os</tt>, allowing use of this call on stream structures in static
 326 or automatic storage. <tt>ogg_stream_destroy</tt>is a complimentary
 327 function that frees the pointer as well.</p>
 328
 329 <p>Returns zero on success and non-zero on failure. This function always
 330 succeeds.</p>
 331
 332 <h3>
 333 int    ogg_stream_destroy(ogg_stream_state *os);
 334 </h3>
 335
 336 <p>Clears and deallocates the internal storage of the given Ogg stream,
 337 then frees the storage associated with the pointer <tt>os</tt>.</p>
 338
 339 <p><tt>ogg_stream_clear</tt> does not call <tt>free()</tt> on the pointer
 340 <tt>os</tt>, allowing use of that call on stream structures in static
 341 or automatic storage.</p>
 342
 343 <p>Returns zero on success and non-zero on failure. This function always
 344 succeeds.</p>
 345
 346 <h3>
 347 int    ogg_stream_init(ogg_stream_state *os,int serialno);
 348 </h3>
 349
 350 <p>Initialize the storage associated with <tt>os</tt> for use as an Ogg
 351 stream. This call is used to initialize a stream for both encode and
 352 decode. The given serial number is the serial number that will be
 353 stamped on pages of the produced bitstream (during encode), or used as
 354 a check that pages match (during decode).</p>
 355
 356 <p>Returns zero on success, nonzero on failure.</p>
 357
 358 <h3>
 359 int    ogg_stream_packetin(ogg_stream_state *os, ogg_packet *op);
 360 </h3>
 361
 362 <p>Used during encoding to add the given raw packet to the given Ogg
 363 bitstream. The contents of <tt>op</tt> are copied;
 364 <tt>ogg_stream_packetin</tt> does not retain any pointers into
 365 <tt>op</tt>'s storage. The encoding proccess buffers incoming packets
 366 until enough packets have been assembled to form an entire page;
 367 <tt>ogg_stream_pageout</tt> is used to read complete pages.</p>
 368
 369 <p>Returns zero on success, nonzero on failure.</p>
 370
 371 <h3>
 372 int    ogg_stream_packetout(ogg_stream_state *os,ogg_packet *op);
 373 </h3>
 374
 375 <p>Used during decoding to read raw packets from the given logical
 376 bitstream. <tt>ogg_stream_packetout</tt> will only return complete
 377 packets for which checksumming indicates no corruption. The size and
 378 contents of the packet exactly match those given in the encoding
 379 process. </p>
 380
 381 <p>Returns zero if the next packet is not ready to be read (not buffered
 382 or incomplete), positive if it returned a complete packet in
 383 <tt>op</tt> and negative if there is a gap, extra bytes or corruption
 384 at this position in the bitstream (essentially that the bitstream had
 385 to be recaptured). A negative value is not necessarily an error. It
 386 would be a common occurence when seeking, for example, which requires
 387 recapture of the bitstream at the position decoding continued.</p>
 388
 389 <p>If the return value is positive, <tt>ogg_stream_packetout</tt> placed
 390 a packet in <tt>op</tt>. The data in <tt>op</tt> points to static
 391 storage that is valid until the next call to
 392 <tt>ogg_stream_pagein</tt>, <tt>ogg_stream_clear</tt>,
 393 <tt>ogg_stream_reset</tt>, or <tt>ogg_stream_destroy</tt>. The
 394 pointers are not invalidated by more calls to
 395 <tt>ogg_stream_packetout</tt>.</p>
 396
 397 <h3>
 398 int    ogg_stream_pagein(ogg_stream_state *os, ogg_page *og);
 399 </h3>
 400
 401 <p>Used during decoding to buffer the given complete, pre-verified page
 402 for decoding into raw Ogg packets. The given page must be framed,
 403 normally produced by <tt>ogg_sync_pageout</tt>, and from the logical
 404 bitstream associated with <tt>os</tt> (the serial numbers must match).
 405 The contents of the given page are copied; <tt>ogg_stream_pagein</tt>
 406 retains no pointers into <tt>og</tt> storage.</p>
 407
 408 <p>Returns zero on success and non-zero on failure.</p>
 409
 410 <h3>
 411 int    ogg_stream_pageout(ogg_stream_state *os, ogg_page *og);
 412 </h3>
 413
 414 <p>Used during encode to read complete pages from the stream buffer. The
 415 returned page is ready for sending out to the real world.</p>
 416
 417 <p>Returns zero if there is no complete page ready for reading. Returns
 418 nonzero when it has placed data for a complete page into
 419 <tt>og</tt>. Note that the storage returned in og points into internal
 420 storage; the pointers in <tt>og</tt> are valid until the next call to
 421 <tt>ogg_stream_pageout</tt>, <tt>ogg_stream_packetin</tt>,
 422 <tt>ogg_stream_reset</tt>, <tt>ogg_stream_clear</tt> or
 423 <tt>ogg_stream_destroy</tt>.</p>
 424
 425 <h3>
 426 int    ogg_stream_reset(ogg_stream_state *os);
 427 </h3>
 428
 429 <p>Resets the given stream's state to that of a blank, unused stream;
 430 this may be used during encode or decode.</p>
 431
 432 <p>Note that if used during encode, it does not alter the stream's serial
 433 number. In addition, the next page produced during encoding will be
 434 marked as the 'initial' page of the logical bitstream.</p>
 435
 436 <p>When used during decode, this simply clears the data buffer of any
 437 pending pages. Beginning and end of stream cues are read from the
 438 bitstream and are unaffected by reset.</p>
 439
 440 <p>Returns zero on success and non-zero on failure. This function always
 441 succeeds.</p>
 442
 443 <h3>
 444 char  *ogg_sync_buffer(ogg_sync_state *oy, long size);
 445 </h3>
 446
 447 <p>This call is used to buffer a raw bitstream for framing and
 448 verification. <tt>ogg_sync_buffer</tt> handles stream capture and
 449 recapture, checksumming, and division into Ogg pages (as required by
 450 <tt>ogg_stream_pagein</tt>).</p>
 451
 452 <p><tt>ogg_sync_buffer</tt> exposes a buffer area into which the decoder
 453 copies the next (up to) <tt>size</tt> bytes. We expose the buffer
 454 (rather than taking a buffer) in order to avoid an extra copy many
 455 uses; this way, for example, <tt>read()</tt> can transfer data
 456 directly into the stream buffer without first needing to place it in
 457 temporary storage.</p>
 458
 459 <p>Returns a pointer into <tt>oy</tt>'s internal bitstream sync buffer;
 460 the remaining space in the sync buffer is at least <tt>size</tt>
 461 bytes. The decoder need not write all of <tt>size</tt> bytes;
 462 <tt>ogg_sync_wrote</tt> is used to inform the engine how many bytes
 463 were actually written. Use of <tt>ogg_sync_wrote</tt> after writing
 464 into the exposed buffer is mandantory.</p>
 465
 466 <h3>
 467 int    ogg_sync_clear(ogg_sync_state *oy);
 468 </h3>
 469
 470 <p><tt>ogg_sync_clear</tt>
 471 clears and deallocates the internal storage of the given Ogg sync
 472 buffer. After clearing, the sync structure is not initialized for
 473 use; <tt>ogg_sync_init</tt> must be called to reinitialize for use.
 474 Use <tt>ogg_sync_reset</tt> to reset the sync state and buffer to a
 475 fresh, intiialized state.</p>
 476
 477 <p><tt>ogg_sync_clear</tt> does not call <tt>free()</tt> on the pointer
 478 <tt>oy</tt>, allowing use of this call on sync structures in static
 479 or automatic storage. <tt>ogg_sync_destroy</tt>is a complimentary
 480 function that frees the pointer as well.</p>
 481
 482 <p>Returns zero on success and non-zero on failure. This function always
 483 succeeds.</p>
 484
 485 <h3>
 486 int    ogg_sync_destroy(ogg_sync_state *oy);
 487 </h3>
 488
 489 <p>Clears and deallocates the internal storage of the given Ogg sync
 490 buffer, then frees the storage associated with the pointer
 491 <tt>oy</tt>.</p>
 492
 493 <p>An alternative function,<tt>ogg_sync_clear</tt>, does not call
 494 <tt>free()</tt> on the pointer <tt>oy</tt>, allowing use of that call on
 495 stream structures in static or automatic storage.</p>
 496
 497 <p>Returns zero on success and non-zero on failure. This function always
 498 succeeds.</p>
 499
 500 <h3>
 501 int    ogg_sync_init(ogg_sync_state *oy);
 502 </h3>
 503
 504 <p>Initializes the sync buffer <tt>oy</tt> for use.</p>
 505
 506 <p>Returns zero on success and non-zero on failure. This function always
 507 succeeds.</p>
 508
 509 <h3>
 510 int    ogg_sync_pageout(ogg_sync_state *oy, ogg_page *og);
 511 </h3>
 512
 513 <p>Reads complete, framed, verified Ogg pages from the sync buffer,
 514 placing the page data in <tt>og</tt>.</p>
 515
 516 <p>Returns zero when there's no complete pages buffered for
 517 retrieval. Returns negative when a loss of sync or recapture occurred
 518 (this is not necessarily an error; recapture would be required after
 519 seeking, for example). Returns positive when a page is returned in
 520 <tt>og</tt>. Note that the data in <tt>og</tt> points into the sync
 521 buffer storage; the pointers are valid until the next call to
 522 <tt>ogg_sync_buffer</tt>, <tt>ogg_sync_clear</tt>,
 523 <tt>ogg_sync_destroy</tt> or <tt>ogg_sync_reset</tt>.</p>
 524
 525 <h3>
 526 int    ogg_sync_reset(ogg_sync_state *oy);
 527 </h3>
 528
 529 <p><tt>ogg_sync_reset</tt> resets the sync state in <tt>oy</tt> to a
 530 clean, empty state. This is useful, for example, when seeking to a
 531 new location in a bitstream.</p>
 532
 533 <p>Returns zero on success, nonzero on failure.</p>
 534
 535 <h3>
 536 int    ogg_sync_wrote(ogg_sync_state *oy, long bytes);
 537 </h3>
 538
 539 <p>Used to inform the sync state as to how many bytes were actually
 540 written into the exposed sync buffer. It must be equal to or less
 541 than the size of the buffer requested.</p>
 542
 543 <p>Returns zero on success and non-zero on failure; failure occurs only
 544 when the number of bytes written were larger than the buffer.</p>
 545
 546 <div id="copyright">
 547   The Xiph Fish Logo is a
 548   trademark (&trade;) of Xiph.Org.<br/>
 549
 550   These pages &copy; 1994 - 2005 Xiph.Org. All rights reserved.
 551 </div>
 552
 553 </body>
 554 </html>