/usr/share/doc/libvorbis-dev/html/programming.html is in libvorbis-dev 1.3.2-1.3ubuntu1.2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
<title>Ogg Vorbis Documentation</title>
<style type="text/css">
body {
margin: 0 18px 0 18px;
padding-bottom: 30px;
font-family: Verdana, Arial, Helvetica, sans-serif;
color: #333333;
font-size: .8em;
}
a {
color: #3366cc;
}
img {
border: 0;
}
#xiphlogo {
margin: 30px 0 16px 0;
}
#content p {
line-height: 1.4;
}
h1, h1 a, h2, h2 a, h3, h3 a {
font-weight: bold;
color: #ff9900;
margin: 1.3em 0 8px 0;
}
h1 {
font-size: 1.3em;
}
h2 {
font-size: 1.2em;
}
h3 {
font-size: 1.1em;
}
li {
line-height: 1.4;
}
#copyright {
margin-top: 30px;
line-height: 1.5em;
text-align: center;
font-size: .8em;
color: #888888;
clear: both;
}
</style>
</head>
<body>
<div id="xiphlogo">
<a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.Org"/></a>
</div>
<h1>Programming with Xiph.Org <tt>libvorbis</tt></h1>
<h2>Description</h2>
<p>Libvorbis is the Xiph.Org Foundation'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>
<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.</p>
<h2>Encoding Overview</h2>
<h2>Decoding Overview</h2>
<p>Decoding a bitstream with libvorbis follows roughly the following
steps:</p>
<ol>
<li>Frame the incoming bitstream into pages</li>
<li>Sort the pages by logical bitstream and buffer then into logical streams</li>
<li>Decompose the logical streams into raw packets</li>
<li>Reconstruct segments of the original data from each packet</li>
<li>Glue the reconstructed segments back into a decoded stream</li>
</ol>
<h3>Framing</h3>
<p>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>
<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>
<p>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).</p>
<h3>Extracting packets</h3>
<p>After submitting page[s] to a logical stream, read available packets
using <tt>ogg_stream_packetout</tt>.</p>
<h3>Decoding packets</h3>
<h3>Reassembling data segments</h3>
<h2>Ogg Bitstream Manipulation Structures</h2>
<p>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 granulepos;
} ogg_packet;
</pre>
<dl>
<dt>packet:</dt>
<dd>a pointer to the byte data of the raw packet</dd>
<dt>bytes:</dt>
<dd>the size of the packet' raw data</dd>
<dt>b_o_s:</dt>
<dd>beginning of stream; nonzero if this is the first packet of
the logical bitstream</dd>
<dt>e_o_s:</dt>
<dd>end of stream; nonzero if this is the last packet of the
logical bitstream</dd>
<dt>granulepos:</dt>
<dd>the absolute position of this packet in the original
uncompressed data stream.</dd>
</dl>
<h4>encoding notes</h4>
<p>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.</p>
<h4>decoding notes</h4>
<p><tt>ogg_stream_packetout()</tt> sets the fields
to appropriate values. Note that granulepos 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>granulepos</tt>). Intervening frames will see <tt>granulepos</tt> set
to -1.</p>
<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:</dt>
<dd>pointer to the page header data</dd>
<dt>header_len:</dt>
<dd>length of the page header in bytes</dd>
<dt>body:</dt>
<dd>pointer to the page body</dd>
<dt>body_len:</dt>
<dd>length of the page body</dd>
</dl>
<p>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</h2>
<h3>
int ogg_page_bos(ogg_page *og);
</h3>
<p>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>
<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>
<p>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>
<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.</p>
<h3>
int ogg_page_eos(ogg_page *og);
</h3>
<p>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>
<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_granulepos(ogg_page *og);
</h3>
<p>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>
<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>
<p>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>
<p>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>
<p>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>
<p>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>
<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>
<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>
<p>Clears and deallocates the internal storage of the given Ogg stream,
then frees the storage associated with the pointer <tt>os</tt>.</p>
<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>
<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>
<p>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>
<p>Returns zero on success, nonzero on failure.</p>
<h3>
int ogg_stream_packetin(ogg_stream_state *os, ogg_packet *op);
</h3>
<p>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>
<p>Returns zero on success, nonzero on failure.</p>
<h3>
int ogg_stream_packetout(ogg_stream_state *os,ogg_packet *op);
</h3>
<p>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>
<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>
<p>If the return value is positive, <tt>ogg_stream_packetout</tt> placed
a packet in <tt>op</tt>. The data in <tt>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>
<p>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>
<p>Returns zero on success and non-zero on failure.</p>
<h3>
int ogg_stream_pageout(ogg_stream_state *os, ogg_page *og);
</h3>
<p>Used during encode to read complete pages from the stream buffer. The
returned page is ready for sending out to the real world.</p>
<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>.</p>
<h3>
int ogg_stream_reset(ogg_stream_state *os);
</h3>
<p>Resets the given stream's state to that of a blank, unused stream;
this may be used during encode or decode.</p>
<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>
<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>
<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>
<p>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>
<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>
<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>
<p><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>
<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>
<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>
<p>Clears and deallocates the internal storage of the given Ogg sync
buffer, then frees the storage associated with the pointer
<tt>oy</tt>.</p>
<p>An alternative function,<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>
<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>
<p>Initializes the sync buffer <tt>oy</tt> for use.</p>
<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>
<p>Reads complete, framed, verified Ogg pages from the sync buffer,
placing the page data in <tt>og</tt>.</p>
<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>.</p>
<h3>
int ogg_sync_reset(ogg_sync_state *oy);
</h3>
<p><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>
<p>Returns zero on success, nonzero on failure.</p>
<h3>
int ogg_sync_wrote(ogg_sync_state *oy, long bytes);
</h3>
<p>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>
<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>
<div id="copyright">
The Xiph Fish Logo is a
trademark (™) of Xiph.Org.<br/>
These pages © 1994 - 2005 Xiph.Org. All rights reserved.
</div>
</body>
</html>
|