|
Packit |
a38265 |
\section{Ogg basics}
|
|
Packit |
a38265 |
\label{group__basics}\index{Ogg basics@{Ogg basics}}
|
|
Packit |
a38265 |
\subsection{Scope}\label{group__basics_Scope}
|
|
Packit |
a38265 |
This section provides a minimal introduction to Ogg concepts, covering only that which is required to use liboggz.
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
For more detailed information, see the {\tt Ogg} homepage or IETF {\tt RFC 3533} {\itshape The Ogg File Format version 0\/}.\subsection{Terminology}\label{group__basics_Terminology}
|
|
Packit |
a38265 |
The monospace text below is quoted directly from RFC 3533. For each concept introduced, tips related to liboggz are provided in bullet points.\subsubsection{Physical and Logical Bitstreams}\label{group__basics_bitstreams}
|
|
Packit |
a38265 |
The raw data of an Ogg stream, as read directly from a file or network socket, is called a {\itshape physical bitstream\/}.
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
\begin{DoxyPre}
|
|
Packit |
a38265 |
The result of an Ogg encapsulation is called the "Physical (Ogg)
|
|
Packit |
a38265 |
Bitstream". It encapsulates one or several encoder-created
|
|
Packit |
a38265 |
bitstreams, which are called "Logical Bitstreams". A logical
|
|
Packit |
a38265 |
bitstream, provided to the Ogg encapsulation process, has a
|
|
Packit |
a38265 |
structure, i.e., it is split up into a sequence of so-called
|
|
Packit |
a38265 |
"Packets". The packets are created by the encoder of that logical
|
|
Packit |
a38265 |
bitstream and represent meaningful entities for that encoder only
|
|
Packit |
a38265 |
(e.g., an uncompressed stream may use video frames as packets).
|
|
Packit |
a38265 |
\end{DoxyPre}
|
|
Packit |
a38265 |
\subsubsection{Packets and Pages}\label{group__basics_pages}
|
|
Packit |
a38265 |
Within the Ogg format, packets are written into {\itshape pages\/}. 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.
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
\begin{DoxyItemize}
|
|
Packit |
a38265 |
\item liboggz handles the details of writing packets into pages, and of reading packets from pages; your application deals only with {\ttfamily ogg\_\-packet} structures.
|
|
Packit |
a38265 |
\item Each {\ttfamily ogg\_\-packet} structure contains a block of data and its length in bytes, plus other information related to the stream structure as explained below.
|
|
Packit |
a38265 |
\end{DoxyItemize}\subsubsection{serialno}\label{group__basics_serialno}
|
|
Packit |
a38265 |
Each logical bitstream is uniquely identified by a serial number or {\itshape serialno\/}.
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
\begin{DoxyItemize}
|
|
Packit |
a38265 |
\item Packets are always associated with a {\itshape serialno\/}. This is not actually part of the {\ttfamily ogg\_\-packet} structure, so wherever you see an {\ttfamily ogg\_\-packet} in the liboggz API, you will see an accompanying {\itshape serialno\/}.
|
|
Packit |
a38265 |
\end{DoxyItemize}
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
\begin{DoxyPre}
|
|
Packit |
a38265 |
This unique serial number is created randomly and does not have any
|
|
Packit |
a38265 |
connection to the content or encoder of the logical bitstream it
|
|
Packit |
a38265 |
represents.
|
|
Packit |
a38265 |
\end{DoxyPre}
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
\begin{DoxyItemize}
|
|
Packit |
a38265 |
\item Use \doxyref{oggz\_\-serialno\_\-new()}{p.}{oggz_8h_aaf89877e3e89408387d422f487bcf094} to generate a new serial number for each logical bitstream you write.
|
|
Packit |
a38265 |
\item Use an \doxyref{OggzTable }{p.}{oggz__table_8h}, keyed by {\itshape serialno\/}, to store and retrieve data related to each logical bitstream.
|
|
Packit |
a38265 |
\end{DoxyItemize}\subsubsection{b\_\-o\_\-s and e\_\-o\_\-s}\label{group__basics_boseos}
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
\begin{DoxyPre}
|
|
Packit |
a38265 |
bos page: The initial page (beginning of stream) of a logical
|
|
Packit |
a38265 |
bitstream which contains information to identify the codec type
|
|
Packit |
a38265 |
and other decoding-relevant information.\end{DoxyPre}
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
\begin{DoxyPre} eos page: The final page (end of stream) of a logical bitstream.
|
|
Packit |
a38265 |
\end{DoxyPre}
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
\begin{DoxyItemize}
|
|
Packit |
a38265 |
\item Every {\ttfamily ogg\_\-packet} contains {\itshape b\_\-o\_\-s\/} and {\itshape e\_\-o\_\-s\/} flags. Of course each of these will be set only once per logical bitstream. See the Structuring section below for rules on setting {\itshape b\_\-o\_\-s\/} and {\itshape e\_\-o\_\-s\/} when interleaving logical bitstreams.
|
|
Packit |
a38265 |
\item This documentation will refer to {\itshape bos\/} and {\itshape eos\/} {\itshape packets\/} (not {\itshape pages\/}) as that is more closely represented by the API. The {\itshape bos\/} packet is the only packet on the {\itshape bos\/} page, and the {\itshape eos\/} packet is the last packet on the {\itshape eos\/} page.
|
|
Packit |
a38265 |
\end{DoxyItemize}\subsubsection{granulepos}\label{group__basics_granulepos}
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
\begin{DoxyPre}
|
|
Packit |
a38265 |
granule position: An increasing position number for a specific
|
|
Packit |
a38265 |
logical bitstream stored in the page header. Its meaning is
|
|
Packit |
a38265 |
dependent on the codec for that logical bitstream
|
|
Packit |
a38265 |
\end{DoxyPre}
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
\begin{DoxyItemize}
|
|
Packit |
a38265 |
\item Every {\ttfamily ogg\_\-packet} contains a {\itshape granulepos\/}. The {\itshape granulepos\/} of each packet is used mostly for \doxyref{seeking. }{p.}{group__seek__api}
|
|
Packit |
a38265 |
\end{DoxyItemize}\subsection{Structuring}\label{group__basics_Structuring}
|
|
Packit |
a38265 |
The general structure of an Ogg stream is governed by various rules.\subsubsection{Secondary header packets}\label{group__basics_secondaries}
|
|
Packit |
a38265 |
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.
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
\begin{DoxyPre}
|
|
Packit |
a38265 |
Ogg also allows but does not require secondary header packets after
|
|
Packit |
a38265 |
the bos page for logical bitstreams and these must also precede any
|
|
Packit |
a38265 |
data packets in any logical bitstream. These subsequent header
|
|
Packit |
a38265 |
packets are framed into an integral number of pages, which will not
|
|
Packit |
a38265 |
contain any data packets. So, a physical bitstream begins with the
|
|
Packit |
a38265 |
bos pages of all logical bitstreams containing one initial header
|
|
Packit |
a38265 |
packet per page, followed by the subsidiary header packets of all
|
|
Packit |
a38265 |
streams, followed by pages containing data packets.
|
|
Packit |
a38265 |
\end{DoxyPre}
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
\begin{DoxyItemize}
|
|
Packit |
a38265 |
\item liboggz handles the framing of {\itshape packets\/} into low-\/level {\itshape pages\/}. To ensure that the pages used by secondary headers contain no data packets, set the {\itshape flush\/} parameter of \doxyref{oggz\_\-write\_\-feed()}{p.}{group__write__api_ga6ccaceb107db1fd2eae047dbdbaa5889} to {\itshape OGGZ\_\-FLUSH\_\-AFTER\/} when queueing the last of the secondary headers.
|
|
Packit |
a38265 |
\item or, equivalently, set {\itshape flush\/} to {\itshape OGGZ\_\-FLUSH\_\-BEFORE\/} when queueing the first of the data packets.
|
|
Packit |
a38265 |
\end{DoxyItemize}\subsubsection{Sequencing b\_\-o\_\-s and e\_\-o\_\-s packets}\label{group__basics_boseosseq}
|
|
Packit |
a38265 |
The following rules apply for sequencing {\itshape bos\/} and {\itshape eos\/} packets in a physical bitstream:
|
|
Packit |
a38265 |
\begin{DoxyPre}
|
|
Packit |
a38265 |
... All bos pages of all logical bitstreams MUST appear together at
|
|
Packit |
a38265 |
the beginning of the Ogg bitstream.\end{DoxyPre}
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
\begin{DoxyPre} ... eos pages for the logical bitstreams need not all occur
|
|
Packit |
a38265 |
contiguously. Eos pages may be 'nil' pages, that is, pages
|
|
Packit |
a38265 |
containing no content but simply a page header with position
|
|
Packit |
a38265 |
information and the eos flag set in the page header.
|
|
Packit |
a38265 |
\end{DoxyPre}
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
\begin{DoxyItemize}
|
|
Packit |
a38265 |
\item \doxyref{oggz\_\-write\_\-feed()}{p.}{group__write__api_ga6ccaceb107db1fd2eae047dbdbaa5889} will fail with a return value of {\itshape OGGZ\_\-ERR\_\-BOS\/} if an attempt is made to queue a late {\itshape bos\/} packet
|
|
Packit |
a38265 |
\end{DoxyItemize}\subsubsection{Interleaving logical bitstreams}\label{group__basics_interleaving}
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
\begin{DoxyPre}
|
|
Packit |
a38265 |
It is possible to consecutively chain groups of concurrently
|
|
Packit |
a38265 |
multiplexed bitstreams. The groups, when unchained, MUST stand on
|
|
Packit |
a38265 |
their own as a valid concurrently multiplexed bitstream. The
|
|
Packit |
a38265 |
following diagram shows a schematic example of such a physical
|
|
Packit |
a38265 |
bitstream that obeys all the rules of both grouped and chained
|
|
Packit |
a38265 |
multiplexed bitstreams.\end{DoxyPre}
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
\begin{DoxyPre} physical bitstream with pages of
|
|
Packit |
a38265 |
different logical bitstreams grouped and chained
|
|
Packit |
a38265 |
-------------------------------------------------------------
|
|
Packit |
a38265 |
|*A*|*B*|*C*|A|A|C|B|A|B|A\#|C|...|B|C|B\#|C\#|*D*|D|...|D\#|
|
|
Packit |
a38265 |
-------------------------------------------------------------
|
|
Packit |
a38265 |
bos bos bos eos eos eos bos eos\end{DoxyPre}
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
\begin{DoxyPre} In this example, there are two chained physical bitstreams, the first
|
|
Packit |
a38265 |
of which is a grouped stream of three logical bitstreams A, B, and C.
|
|
Packit |
a38265 |
The second physical bitstream is chained after the end of the grouped
|
|
Packit |
a38265 |
bitstream, which ends after the last eos page of all its grouped
|
|
Packit |
a38265 |
logical bitstreams. As can be seen, grouped bitstreams begin
|
|
Packit |
a38265 |
together - all of the bos pages MUST appear before any data pages.
|
|
Packit |
a38265 |
It can also be seen that pages of concurrently multiplexed bitstreams
|
|
Packit |
a38265 |
need not conform to a regular order. And it can be seen that a
|
|
Packit |
a38265 |
grouped bitstream can end long before the other bitstreams in the
|
|
Packit |
a38265 |
group end.
|
|
Packit |
a38265 |
\end{DoxyPre}
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
\begin{DoxyItemize}
|
|
Packit |
a38265 |
\item \doxyref{oggz\_\-write\_\-feed()}{p.}{group__write__api_ga6ccaceb107db1fd2eae047dbdbaa5889} will fail, returning an explicit error value, if an attempt is made to queue a packet in violation of these rules.
|
|
Packit |
a38265 |
\end{DoxyItemize}\subsection{References}\label{group__basics_References}
|
|
Packit |
a38265 |
This introduction to the Ogg format is derived from IETF {\tt RFC 3533} {\itshape The Ogg File Format version 0\/} in accordance with the following copyright statement pertaining to the text of RFC 3533:
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
\begin{DoxyPre}
|
|
Packit |
a38265 |
Copyright (C) The Internet Society (2003). All Rights Reserved.\end{DoxyPre}
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
\begin{DoxyPre} This document and translations of it may be copied and furnished to
|
|
Packit |
a38265 |
others, and derivative works that comment on or otherwise explain it
|
|
Packit |
a38265 |
or assist in its implementation may be prepared, copied, published
|
|
Packit |
a38265 |
and distributed, in whole or in part, without restriction of any
|
|
Packit |
a38265 |
kind, provided that the above copyright notice and this paragraph are
|
|
Packit |
a38265 |
included on all such copies and derivative works. However, this
|
|
Packit |
a38265 |
document itself may not be modified in any way, such as by removing
|
|
Packit |
a38265 |
the copyright notice or references to the Internet Society or other
|
|
Packit |
a38265 |
Internet organizations, except as needed for the purpose of
|
|
Packit |
a38265 |
developing Internet standards in which case the procedures for
|
|
Packit |
a38265 |
copyrights defined in the Internet Standards process must be
|
|
Packit |
a38265 |
followed, or as required to translate it into languages other than
|
|
Packit |
a38265 |
English.\end{DoxyPre}
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
\begin{DoxyPre} The limited permissions granted above are perpetual and will not be
|
|
Packit |
a38265 |
revoked by the Internet Society or its successors or assigns.\end{DoxyPre}
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
\begin{DoxyPre} This document and the information contained herein is provided on an
|
|
Packit |
a38265 |
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
|
|
Packit |
a38265 |
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
|
|
Packit |
a38265 |
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
|
|
Packit |
a38265 |
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
|
|
Packit |
a38265 |
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
|
|
Packit |
a38265 |
\end{DoxyPre}
|
|
Packit |
a38265 |
|