doc/programming.html

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