Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/libvorbis-1.2.0/doc/programming.html @ 16

Last change on this file since 16 was 16, checked in by landauf, 17 years ago

added libvorbis
File size: 18.4 KB
Line 
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">
9body {
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
17a {
18  color: #3366cc;
19}
20
21img {
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
33h1, h1 a, h2, h2 a, h3, h3 a {
34  font-weight: bold;
35  color: #ff9900;
36  margin: 1.3em 0 8px 0;
37}
38
39h1 {
40  font-size: 1.3em;
41}
42
43h2 {
44  font-size: 1.2em;
45}
46
47h3 {
48  font-size: 1.1em;
49}
50
51li {
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
78implemented as a programmatic library. Libvorbis provides primitives
79to handle framing and manipulation of Ogg bitstreams (used by the
80Vorbis for streaming), a full analysis (encoding) interface as well as
81packet decoding and synthesis for playback.</p>
82
83<p>The libvorbis library does not provide any system interface; a
84full-featured demonstration player included with the library
85distribtion provides example code for a variety of system interfaces
86as 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
93steps:</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
106the pages, we have to find them first. The raw bitstream is first fed
107into an <tt>ogg_sync_state</tt> buffer using <tt>ogg_sync_buffer()</tt>
108and <tt>ogg_sync_wrote()</tt>. After each block we submit to the sync
109buffer, we should check to see if we can frame and extract a complete
110page or pages using <tt>ogg_sync_pageout()</tt>. Extra pages are
111buffered; allowing them to build up in the <tt>ogg_sync_state</tt>
112buffer will eventually exhaust memory.</p>
113
114<p>The Ogg pages returned from <tt>ogg_sync_pageout</tt> need not be
115decoded further to be used as landmarks in seeking; seeking can be
116either a rough process of simply jumping to approximately intuited
117portions of the bitstream, or it can be a precise bisection process
118that captures pages and inspects data position. When seeking,
119however, sequential multiplexing (chaining) must be accounted for;
120beginning play in a new logical bitstream requires initializing a
121synthesis engine with the headers from that bitstream. Vorbis
122bitstreams 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
127serial number to seperate logical bitstreams. Initialize logical
128bitstream buffers (<tt>og_stream_state</tt>) using
129<tt>ogg_stream_init()</tt>. Pages are submitted to the matching
130logical bitstream buffer using <tt>ogg_stream_pagein</tt>; the serial
131number of the page and the stream buffer must match, or the page will
132be rejected. A page submitted out of sequence will simply be noted,
133and in the course of outputting packets, the hole will be flagged
134(<tt>ogg_sync_pageout</tt> and <tt>ogg_stream_packetout</tt> will
135return a negative value at positions where they had to recapture the
136stream).</p>
137
138<h3>Extracting packets</h3>
139
140<p>After submitting page[s] to a logical stream, read available packets
141using <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
150transparent to the developer; the fields should be used directly.</p>
151
152<h3>ogg_packet</h3>
153
154<pre>
155typedef 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
185the 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
189page. <tt>e_o_s</tt>, however, must be set; this is the means by
190which 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
195to appropriate values. Note that granulepos will be >= 0 only in the
196case that the given packet actually represents that position (ie, only
197the last packet completed on any page will have a meaningful
198<tt>granulepos</tt>). Intervening frames will see <tt>granulepos</tt> set
199to -1.</p>
200
201<h3>ogg_page</h3>
202
203<pre>
204typedef 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
224not necessarily point into a single contiguous page vector, the page
225body must immediately follow the header in the bitstream.</p>
226
227<h2>Ogg Bitstream Manipulation Functions</h2>
228
229<h3>
230int    ogg_page_bos(ogg_page *og);
231</h3>
232
233<p>Returns the 'beginning of stream' flag for the given Ogg page. The
234beginning of stream flag is set on the initial page of a logical
235bitstream.</p>
236
237<p>Zero indicates the flag is cleared (this is not the initial page of a
238logical bitstream). Nonzero indicates the flag is set (this is the
239initial page of a logical bitstream).</p>
240
241<h3>
242int    ogg_page_continued(ogg_page *og);
243</h3>
244
245<p>Returns the 'packet continued' flag for the given Ogg page. The packet
246continued flag indicates whether or not the body data of this page
247begins with packet continued from a preceeding page.</p>
248
249<p>Zero (unset) indicates that the body data begins with a new packet.
250Nonzero (set) indicates that the first packet data on the page is a
251continuation from the preceeding page.</p>
252
253<h3>
254int    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
258flag 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
261bitstream. Nonzero (set) indicates that this is the last page of a
262logical bitstream and that no addiitonal pages belonging to this
263bitstream may follow.</p>
264
265<h3>
266size64 ogg_page_granulepos(ogg_page *og);
267</h3>
268
269<p>Returns the position of this page as an absolute position within the
270original uncompressed data. The position, as returned, is 'frames
271encoded to date up to and including the last whole packet on this
272page'. Partial packets begun on this page but continued to the
273following page are not included. If no packet ends on this page, the
274frame position value will be equal to the frame position value of the
275preceeding page. If none of the original uncompressed data is yet
276represented in the logical bitstream (for example, the first page of a
277bitstream consists only of a header packet; this packet encodes only
278metadata), the value shall be zero.</p>
279
280<p>The units of the framenumber are determined by media mapping. A
281vorbis audio bitstream, for example, defines one frame to be the
282channel values from a single sampling period (eg, a 16 bit stereo
283bitstream consists of two samples of two bytes for a total of four
284bytes, thus a frame would be four bytes). A video stream defines one
285frame to be a single frame of video.</p>
286
287<h3>
288int    ogg_page_pageno(ogg_page *og);
289</h3>
290
291<p>Returns the sequential page number of the given Ogg page. The first
292page in a logical bitstream is numbered zero; following pages are
293numbered in increasing monotonic order.</p>
294
295<h3>
296int    ogg_page_serialno(ogg_page *og);
297</h3>
298
299<p>Returns the serial number of the given Ogg page. The serial number is
300used as a handle to distinguish various logical bitstreams in a
301physical Ogg bitstresm. Every logical bitstream within a
302physical bitstream must use a unique (within the scope of the physical
303bitstream) serial number, which is stamped on all bitstream pages.</p>
304
305<h3>
306int    ogg_page_version(ogg_page *og);
307</h3>
308
309<p>Returns the revision of the Ogg bitstream structure of the given page.
310Currently, the only permitted number is zero. Later revisions of the
311bitstream spec will increment this version should any changes be
312incompatable.</p>
313
314<h3>
315int    ogg_stream_clear(ogg_stream_state *os);
316</h3>
317
318<p>Clears and deallocates the internal storage of the given Ogg stream.
319After clearing, the stream structure is not initialized for use;
320<tt>ogg_stream_init</tt> must be called to reinitialize for use.
321Use <tt>ogg_stream_reset</tt> to reset the stream state
322to 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
326or automatic storage. <tt>ogg_stream_destroy</tt>is a complimentary
327function that frees the pointer as well.</p>
328
329<p>Returns zero on success and non-zero on failure. This function always
330succeeds.</p>
331
332<h3>
333int    ogg_stream_destroy(ogg_stream_state *os);
334</h3>
335
336<p>Clears and deallocates the internal storage of the given Ogg stream,
337then 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
341or automatic storage.</p>
342
343<p>Returns zero on success and non-zero on failure. This function always
344succeeds.</p>
345
346<h3>
347int    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
351stream. This call is used to initialize a stream for both encode and
352decode. The given serial number is the serial number that will be
353stamped on pages of the produced bitstream (during encode), or used as
354a check that pages match (during decode).</p>
355
356<p>Returns zero on success, nonzero on failure.</p>
357
358<h3>
359int    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
363bitstream. 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
366until 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>
372int    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
376bitstream. <tt>ogg_stream_packetout</tt> will only return complete
377packets for which checksumming indicates no corruption. The size and
378contents of the packet exactly match those given in the encoding
379process. </p>
380
381<p>Returns zero if the next packet is not ready to be read (not buffered
382or incomplete), positive if it returned a complete packet in
383<tt>op</tt> and negative if there is a gap, extra bytes or corruption
384at this position in the bitstream (essentially that the bitstream had
385to be recaptured). A negative value is not necessarily an error. It
386would be a common occurence when seeking, for example, which requires
387recapture of the bitstream at the position decoding continued.</p>
388
389<p>If the return value is positive, <tt>ogg_stream_packetout</tt> placed
390a packet in <tt>op</tt>. The data in <tt>op</tt> points to static
391storage 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
394pointers are not invalidated by more calls to
395<tt>ogg_stream_packetout</tt>.</p>
396
397<h3>
398int    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
402for decoding into raw Ogg packets. The given page must be framed,
403normally produced by <tt>ogg_sync_pageout</tt>, and from the logical
404bitstream associated with <tt>os</tt> (the serial numbers must match).
405The contents of the given page are copied; <tt>ogg_stream_pagein</tt>
406retains no pointers into <tt>og</tt> storage.</p>
407
408<p>Returns zero on success and non-zero on failure.</p>
409
410<h3>
411int    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
415returned 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
418nonzero when it has placed data for a complete page into
419<tt>og</tt>. Note that the storage returned in og points into internal
420storage; 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>
426int    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;
430this 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
433number. In addition, the next page produced during encoding will be
434marked as the 'initial' page of the logical bitstream.</p>
435
436<p>When used during decode, this simply clears the data buffer of any
437pending pages. Beginning and end of stream cues are read from the
438bitstream and are unaffected by reset.</p>
439
440<p>Returns zero on success and non-zero on failure. This function always
441succeeds.</p>
442
443<h3>
444char  *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
448verification. <tt>ogg_sync_buffer</tt> handles stream capture and
449recapture, 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
453copies 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
455uses; this way, for example, <tt>read()</tt> can transfer data
456directly into the stream buffer without first needing to place it in
457temporary storage.</p>
458
459<p>Returns a pointer into <tt>oy</tt>'s internal bitstream sync buffer;
460the remaining space in the sync buffer is at least <tt>size</tt>
461bytes. 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
463were actually written. Use of <tt>ogg_sync_wrote</tt> after writing
464into the exposed buffer is mandantory.</p>
465
466<h3>
467int    ogg_sync_clear(ogg_sync_state *oy);
468</h3>
469
470<p><tt>ogg_sync_clear</tt>
471clears and deallocates the internal storage of the given Ogg sync
472buffer. After clearing, the sync structure is not initialized for
473use; <tt>ogg_sync_init</tt> must be called to reinitialize for use.
474Use <tt>ogg_sync_reset</tt> to reset the sync state and buffer to a
475fresh, 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
479or automatic storage. <tt>ogg_sync_destroy</tt>is a complimentary
480function that frees the pointer as well.</p>
481
482<p>Returns zero on success and non-zero on failure. This function always
483succeeds.</p>
484
485<h3>
486int    ogg_sync_destroy(ogg_sync_state *oy);
487</h3>
488
489<p>Clears and deallocates the internal storage of the given Ogg sync
490buffer, then frees the storage associated with the pointer
491<tt>oy</tt>.</p>
492
493<p><tt>ogg_sync_clear</tt> does not call <tt>free()</tt> on the pointer
494<tt>oy</tt>, allowing use of that call on stream structures in static
495or automatic storage.</p>
496
497<p>Returns zero on success and non-zero on failure. This function always
498succeeds.</p>
499
500<h3>
501int    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
507succeeds.</p>
508
509<h3>
510int    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,
514placing the page data in <tt>og</tt>.</p>
515
516<p>Returns zero when there's no complete pages buffered for
517retrieval. Returns negative when a loss of sync or recapture occurred
518(this is not necessarily an error; recapture would be required after
519seeking, 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
521buffer 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>
526int    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
530clean, empty state. This is useful, for example, when seeking to a
531new location in a bitstream.</p>
532
533<p>Returns zero on success, nonzero on failure.</p>
534
535<h3>
536int    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
540written into the exposed sync buffer. It must be equal to or less
541than the size of the buffer requested.</p>
542
543<p>Returns zero on success and non-zero on failure; failure occurs only
544when 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>
Note: See TracBrowser for help on using the repository browser.