Permalink
Browse files

Add weblog post text

  • Loading branch information...
1 parent 35fa07c commit ed37c56cbea006fedf2aefa92b0cdb95c11e9186 @doublec committed Jun 24, 2009
Showing with 206 additions and 0 deletions.
  1. +206 −0 part1.html
View
@@ -0,0 +1,206 @@
+<p>
+ Reading data from an Ogg file is relatively simple. The file format
+ is well documented
+ in <a href="http://www.ietf.org/rfc/rfc3533.txt">RFC 3533</a>. I
+ showed how to read the format using
+ JavaScript <a href="http://www.bluishcoder.co.nz/2009/06/reading-ogg-files-with-javascript.html">
+ in a previous post</a>.
+</p>
+<p>For C and C++ programs it's easier to use
+ the <a href="http://xiph.org">xiph.org</a> libraries. There are
+ libraries for decoding specific formats (libvorbis, libtheora) and
+ there is a library for reading data from Ogg files (libogg).
+</p>
+<p>I'm prototyping some approaches to improve the performance of the
+ Firefox Ogg video playback and while I'm at it I'll write some posts
+ on using these libraries to decode/play Ogg files. Hopefully it'll
+ prove useful to others using them and I can get some feedback on
+ usage.
+</p>
+<p>All the code for this is in
+ the <a href="http://github.com/doublec/plogg/tree">plogg</a> git
+ repository on github. The 'master' branch contains the work in
+ progress player that I'll describe in a series of posts, and there
+ are branches specific to the examples in each post.
+</p>
+<p>The <a href="http://www.xiph.org/ogg/doc/libogg/">libogg
+ documentation</a> describes the API that I'll be using in this
+ post. All that this example will do is read an Ogg file, read each
+ stream in the file and count the number of packets for that
+ stream. It prints the number of packets. It doesn't decode the
+ data or do anything really useful. That'll come later.
+</p>
+<p>You can think of an Ogg file as containing logical streams of
+ data. Each stream has a serial number that is unique within the file
+ to identify it. A file containing Vorbis and Theora data will have
+ two streams. A Vorbis stream and a Theora stream.</p>
+<p>Each stream is split up into packets. The packets
+ contain the raw data for the stream. The process of decoding a
+ stream involves getting a packet from it, decoding that data, doing
+ something with it, and repeating.</p>
+<p>That describes the logical format. The physical format of the Ogg
+ file is split into pages of data. Each physical page contains some
+ part of the data for one stream. </p>
+<p>The process of reading and decoding an Ogg file is to read pages
+ from the file, associating them with the streams they belong to. At
+ some point we then go through the pages held in the stream and
+ obtain the packets from it. This is the process the code in this
+ example follows.</p>
+<p>The first thing we need to do when reading an Ogg file is find the
+first page of data. We use
+ a <a href="http://www.xiph.org/ogg/doc/libogg/ogg_sync_state.html">ogg_sync_state</a>
+ structure to keep track of search for the page data. This needs to
+ be initialized
+ with <a href="http://www.xiph.org/ogg/doc/libogg/ogg_sync_init.html">ogg_sync_init</a>
+ and later cleaned up
+ with <a href="http://www.xiph.org/ogg/doc/libogg/ogg_sync_clear.html">ogg_sync_clear</a>:
+<pre>ifstream file("foo.ogg", ios::in | ios::binary);
+ogg_sync_state state;
+int ret = ogg_sync_init(&state);
+assert(ret==0);
+...look for page...
+</pre>
+<p>Note that the libogg functions return an error code which should be
+ checked, A result of '0' generally indicates success. We want to
+ obtain a complete page of Ogg data. This is held in
+ an <a href="http://www.xiph.org/ogg/doc/libogg/ogg_page.html">ogg_page</a>
+ structure. The process of obtaining this structure is to do the
+ following steps:
+<ol>
+ <li>Call <a href="http://www.xiph.org/ogg/doc/libogg/ogg_sync_pageout.html">ogg_sync_pageout</a>. This
+ will take any data current stored in the ogg_sync_state object and
+ store it in the ogg_page. It will return a result indicating when
+ the entire pages data has been read and the ogg_page can be used. It
+ needs to be called first to initialize buffers. It gets called
+ repeatedly as we read data from the file.</li>
+ <li>Call <a href="http://www.xiph.org/ogg/doc/libogg/ogg_sync_buffer.html">ogg_sync_buffer</a>
+ to obtain an area of memory we can reading data from the file
+ into. We pass the size of the buffer. This buffer is reused
+ on each call and will be resized if needed if a larger buffer size
+ is asked for later.</li>
+ <li>Read data from the file into the buffer obtained above.</li>
+ <li>Call <a href="http://www.xiph.org/ogg/doc/libogg/ogg_sync_wrote.html">ogg_sync_wrote</a>
+ to tell libogg how much data we copied into the buffer.</li>
+ <li>Resume from the first step, calling ogg_sync_buffer. This will
+ copy the data from the buffer into the page, and return '1' if a
+ full page of data is available.</li>
+</ol>
+<p>Here's the code following these steps:</p>
+<pre>ogg_page page;
+while(ogg_sync_pageout(&amp;state, &amp;page) != 1) {
+ char* buffer = ogg_sync_buffer(oy, 4096);
+ assert(buffer);
+
+ file.read(buffer, 4096);
+ int bytes = stream.gcount();
+ if (bytes == 0) {
+ // End of file
+ break;
+ }
+
+ int ret = ogg_sync_wrote(&state, bytes);
+ assert(ret == 0);
+}
+</pre>
+<p>We need to keep track of the logical streams within the file. These
+ are identified by serial number and this number is obtained from the
+ page. I create a C++ map to associate the serial number with an
+ OggStream object which holds information I want associated with the
+ stream. In later examples this will hold data needed for the Theora
+ and Vorbis decoding process.
+</p>
+<pre>class OggStream
+{
+ ...
+ int mSerial;
+ ogg_stream_state mState;
+ int mPacketCount;
+ ...
+};
+
+typedef map<int, OggStream*> StreamMap;
+</pre>
+<p>Each stream has
+ an <a href="http://www.xiph.org/ogg/doc/libogg/ogg_stream_state.html">ogg_stream_state</a>
+ object that is used to keep track of the data read that belongs to
+ the stream. We're storing this in the OggStream object that we
+ associated with the stream serial number. Once we've read a page as
+ described above we need to tell libogg to add this page of data to
+ the stream.
+</p>
+<pre>
+StreamMap streams;
+ogg_page page = ...obtained previously...;
+int serial = ogg_page_serialno(&page);
+OggStream* stream = 0;
+if (ogg_page_bos(&page) {
+ stream = new OggStream(serial);
+ int ret = ogg_stream_init(&stream->mState, serial);
+ assert(ret == 0);
+ streams[serial] = stream;
+}
+else
+ stream = streams[serial];
+
+int ret = ogg_stream_pagein(&stream->mState, &page);
+assert(ret == 0);
+</pre>
+
+<p>This code
+ uses <a href="http://www.xiph.org/ogg/doc/libogg/ogg_page_serialno.html">ogg_page_serialno</a>
+ to get the serial number of the page we just read. If it is the
+ beginning of the stream
+ (<a href="http://www.xiph.org/ogg/doc/libogg/ogg_page_bos.html">ogg_page_bos</a>)
+ then we create a new OggStream object, initialize the stream's state
+ with <a href="http://www.xiph.org/ogg/doc/libogg/ogg_stream_init.html">ogg_stream_init</a>,
+ and store it in out streams map. If it's not the beginning of the
+ stream we just get our existing entry in the map. The final call to
+ <a href="http://www.xiph.org/ogg/doc/libogg/ogg_stream_pagein.html">ogg_stream_pagein</a>
+ inserts the page of data into the streams state object. Once this is
+ done we can start looking for completed packets of data and decode them.
+</p>
+<p>To decode the data from a stream we need to retrieve a packet from
+ it. The steps for doing this are:<p>
+<ul>
+ <li>Call <a href="http://www.xiph.org/ogg/doc/libogg/ogg_stream_packetout.html">ogg_stream_packetout</a>. This
+ will return a value indicating if a packet of data is available in
+ the stream. If it is not then we need to read another page
+ (following the same steps previously) and add it to the stream,
+ calling ogg_stream_packetout again until it tells us a packet is
+ available. The packet's data is stored in
+ an <a href="http://www.xiph.org/ogg/doc/libogg/ogg_packet.html">ogg_packet</a>
+ object.</li>
+ <li>Do something with the packet data. This usually involves calling
+ libvorbis or libtheora routines to decode the data. In this example
+ we're just counting the packets.</li>
+ <li>Repeat until all packets in all streams are consumed.</li>
+</ul>
+<pre>while (..read a page...) {
+ ...put page in stream...
+ ogg_packet packet;
+ int ret = ogg_stream_packetout(&stream->mState, &packet);
+ if (ret == 0) {
+ // Need more data to be able to complete the packet
+ continue;
+ }
+ else if (ret == -1) {
+ // We are out of sync and there is a gap in the data.
+ // We lost a page somewhere.
+ break;
+ }
+
+ // A packet is available, this is what we pass to the vorbis or
+ // theora libraries to decode.
+ stream->mPacketCount++;
+}
+</pre>
+<p>That's all there is to reading an Ogg file. There are more libogg
+ functions to get data out of the stream, identify end of stream, and
+ various other useful functions but this covers the basics. Try out
+ the example program in the github repository for more information.
+</p>
+<p>Note that the libogg functions don't require reading from a
+ file. You can use these routines with any data you've obtained. From
+ a socket, from memory, etc.</p>
+<p>In the next post about reading Ogg files I'll go through using
+ libtheora to decode the video data and display it.</p>

0 comments on commit ed37c56

Please sign in to comment.