<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>liboggz: Ogg basics</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.6.3 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
</div>
<div class="contents">
<h1>Ogg basics</h1><table border="0" cellpadding="0" cellspacing="0">
</table>
<h2><a class="anchor" id="Scope">
Scope</a></h2>
<p>This section provides a minimal introduction to Ogg concepts, covering only that which is required to use liboggz.</p>
<p>For more detailed information, see the <a href="http://www.xiph.org/ogg/">Ogg</a> homepage or IETF <a href="http://www.ietf.org/rfc/rfc3533.txt">RFC 3533</a> <em>The Ogg File Format version 0</em>.</p>
<h2><a class="anchor" id="Terminology">
Terminology</a></h2>
<p>The monospace text below is quoted directly from RFC 3533. For each concept introduced, tips related to liboggz are provided in bullet points.</p>
<h3><a class="anchor" id="bitstreams">
Physical and Logical Bitstreams</a></h3>
<p>The raw data of an Ogg stream, as read directly from a file or network socket, is called a <em>physical bitstream</em>.</p>
<pre>
The result of an Ogg encapsulation is called the "Physical (Ogg)
Bitstream". It encapsulates one or several encoder-created
bitstreams, which are called "Logical Bitstreams". A logical
bitstream, provided to the Ogg encapsulation process, has a
structure, i.e., it is split up into a sequence of so-called
"Packets". The packets are created by the encoder of that logical
bitstream and represent meaningful entities for that encoder only
(e.g., an uncompressed stream may use video frames as packets).
</pre><h3><a class="anchor" id="pages">
Packets and Pages</a></h3>
<p>Within the Ogg format, packets are written into <em>pages</em>. You can think of pages like pages in a book, and packets as items of the actual text. Consider, for example, individual poems or short stories as the packets. Pages are of course all the same size, and a few very short packets could be written into a single page. On the other hand, a very long packet will use many pages.</p>
<ul>
<li>liboggz handles the details of writing packets into pages, and of reading packets from pages; your application deals only with <code>ogg_packet</code> structures.</li>
<li>Each <code>ogg_packet</code> structure contains a block of data and its length in bytes, plus other information related to the stream structure as explained below.</li>
</ul>
<h3><a class="anchor" id="serialno">
serialno</a></h3>
<p>Each logical bitstream is uniquely identified by a serial number or <em>serialno</em>.</p>
<ul>
<li>Packets are always associated with a <em>serialno</em>. This is not actually part of the <code>ogg_packet</code> structure, so wherever you see an <code>ogg_packet</code> in the liboggz API, you will see an accompanying <em>serialno</em>.</li>
</ul>
<pre>
This unique serial number is created randomly and does not have any
connection to the content or encoder of the logical bitstream it
represents.
</pre><ul>
<li>Use <a class="el" href="oggz_8h.html#aaf89877e3e89408387d422f487bcf094" title="Request a new serialno, as required for a new stream, ensuring the serialno is not...">oggz_serialno_new()</a> to generate a new serial number for each logical bitstream you write.</li>
<li>Use an <a class="el" href="oggz__table_8h.html">OggzTable </a>, keyed by <em>serialno</em>, to store and retrieve data related to each logical bitstream.</li>
</ul>
<h3><a class="anchor" id="boseos">
b_o_s and e_o_s</a></h3>
<pre>
bos page: The initial page (beginning of stream) of a logical
bitstream which contains information to identify the codec type
and other decoding-relevant information.</pre><pre> eos page: The final page (end of stream) of a logical bitstream.
</pre><ul>
<li>Every <code>ogg_packet</code> contains <em>b_o_s</em> and <em>e_o_s</em> flags. Of course each of these will be set only once per logical bitstream. See the Structuring section below for rules on setting <em>b_o_s</em> and <em>e_o_s</em> when interleaving logical bitstreams.</li>
<li>This documentation will refer to <em>bos</em> and <em>eos</em> <em>packets</em> (not <em>pages</em>) as that is more closely represented by the API. The <em>bos</em> packet is the only packet on the <em>bos</em> page, and the <em>eos</em> packet is the last packet on the <em>eos</em> page.</li>
</ul>
<h3><a class="anchor" id="granulepos">
granulepos</a></h3>
<pre>
granule position: An increasing position number for a specific
logical bitstream stored in the page header. Its meaning is
dependent on the codec for that logical bitstream
</pre><ul>
<li>Every <code>ogg_packet</code> contains a <em>granulepos</em>. The <em>granulepos</em> of each packet is used mostly for <a class="el" href="group__seek__api.html">seeking. </a></li>
</ul>
<h2><a class="anchor" id="Structuring">
Structuring</a></h2>
<p>The general structure of an Ogg stream is governed by various rules.</p>
<h3><a class="anchor" id="secondaries">
Secondary header packets</a></h3>
<p>Some data sources require initial setup information such as comments and codebooks to be present near the beginning of the stream (directly following the b_o_s packets.</p>
<pre>
Ogg also allows but does not require secondary header packets after
the bos page for logical bitstreams and these must also precede any
data packets in any logical bitstream. These subsequent header
packets are framed into an integral number of pages, which will not
contain any data packets. So, a physical bitstream begins with the
bos pages of all logical bitstreams containing one initial header
packet per page, followed by the subsidiary header packets of all
streams, followed by pages containing data packets.
</pre><ul>
<li>liboggz handles the framing of <em>packets</em> into low-level <em>pages</em>. To ensure that the pages used by secondary headers contain no data packets, set the <em>flush</em> parameter of <a class="el" href="group__write__api.html#ga6ccaceb107db1fd2eae047dbdbaa5889" title="Add a packet to oggz's packet queue.">oggz_write_feed()</a> to <em>OGGZ_FLUSH_AFTER</em> when queueing the last of the secondary headers.</li>
<li>or, equivalently, set <em>flush</em> to <em>OGGZ_FLUSH_BEFORE</em> when queueing the first of the data packets.</li>
</ul>
<h3><a class="anchor" id="boseosseq">
Sequencing b_o_s and e_o_s packets</a></h3>
<p>The following rules apply for sequencing <em>bos</em> and <em>eos</em> packets in a physical bitstream: </p>
<pre>
... All bos pages of all logical bitstreams MUST appear together at
the beginning of the Ogg bitstream.</pre><pre> ... eos pages for the logical bitstreams need not all occur
contiguously. Eos pages may be 'nil' pages, that is, pages
containing no content but simply a page header with position
information and the eos flag set in the page header.
</pre><ul>
<li><a class="el" href="group__write__api.html#ga6ccaceb107db1fd2eae047dbdbaa5889" title="Add a packet to oggz's packet queue.">oggz_write_feed()</a> will fail with a return value of <em>OGGZ_ERR_BOS</em> if an attempt is made to queue a late <em>bos</em> packet</li>
</ul>
<h3><a class="anchor" id="interleaving">
Interleaving logical bitstreams</a></h3>
<pre>
It is possible to consecutively chain groups of concurrently
multiplexed bitstreams. The groups, when unchained, MUST stand on
their own as a valid concurrently multiplexed bitstream. The
following diagram shows a schematic example of such a physical
bitstream that obeys all the rules of both grouped and chained
multiplexed bitstreams.</pre><pre> physical bitstream with pages of
different logical bitstreams grouped and chained
-------------------------------------------------------------
|*A*|*B*|*C*|A|A|C|B|A|B|A#|C|...|B|C|B#|C#|*D*|D|...|D#|
-------------------------------------------------------------
bos bos bos eos eos eos bos eos</pre><pre> In this example, there are two chained physical bitstreams, the first
of which is a grouped stream of three logical bitstreams A, B, and C.
The second physical bitstream is chained after the end of the grouped
bitstream, which ends after the last eos page of all its grouped
logical bitstreams. As can be seen, grouped bitstreams begin
together - all of the bos pages MUST appear before any data pages.
It can also be seen that pages of concurrently multiplexed bitstreams
need not conform to a regular order. And it can be seen that a
grouped bitstream can end long before the other bitstreams in the
group end.
</pre><ul>
<li><a class="el" href="group__write__api.html#ga6ccaceb107db1fd2eae047dbdbaa5889" title="Add a packet to oggz's packet queue.">oggz_write_feed()</a> will fail, returning an explicit error value, if an attempt is made to queue a packet in violation of these rules.</li>
</ul>
<h2><a class="anchor" id="References">
References</a></h2>
<p>This introduction to the Ogg format is derived from IETF <a href="http://www.ietf.org/rfc/rfc3533.txt">RFC 3533</a> <em>The Ogg File Format version 0</em> in accordance with the following copyright statement pertaining to the text of RFC 3533:</p>
<pre>
Copyright (C) The Internet Society (2003). All Rights Reserved.</pre><pre> This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.</pre><pre> The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.</pre><pre> This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
</pre> </div>
<hr class="footer"/><address style="text-align: right;"><small>Generated on Sat Apr 24 09:13:55 2010 for liboggz by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.3 </small></address>
</body>
</html>