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