[xiph-commits] r10669 - trunk/ogg/doc

[giles at svn.xiph.org]

Author: giles
Date: 2005-12-20 17:23:01 -0800 (Tue, 20 Dec 2005)
New Revision: 10669

Modified:
   trunk/ogg/doc/framing.html
Log:
Sync with changes to the version distributed with libvorbis.


Modified: trunk/ogg/doc/framing.html
===================================================================
--- trunk/ogg/doc/framing.html	2005-12-21 01:22:23 UTC (rev 10668)
+++ trunk/ogg/doc/framing.html	2005-12-21 01:23:01 UTC (rev 10669)
@@ -30,7 +30,7 @@
   line-height: 1.4;
 }
 
-h1, h1 a, h2, h2 a, h3, h3 a, h4, h4 a {
+h1, h1 a, h2, h2 a, h3, h3 a {
   font-weight: bold;
   color: #ff9900;
   margin: 1.3em 0 8px 0;
@@ -77,14 +77,14 @@
 <p>The Ogg transport bitstream is designed to provide framing, error
 protection and seeking structure for higher-level codec streams that
 consist of raw, unencapsulated data packets, such as the Vorbis audio
-codec or Tarkin video codec.</p>
+codec or Theora video codec.</p>
 
 <h2>Application example: Vorbis</h2>
 
 <p>Vorbis encodes short-time blocks of PCM data into raw packets of
-bit-packed data.  These raw packets may be used directly by transport
+bit-packed data. These raw packets may be used directly by transport
 mechanisms that provide their own framing and packet-separation
-mechanisms (such as UDP datagrams).  For stream based storage (such as
+mechanisms (such as UDP datagrams). For stream based storage (such as
 files) and transport (such as TCP streams or pipes), Vorbis uses the
 Ogg bitstream format to provide framing/sync, sync recapture
 after error, landmarks during seeking, and enough information to
@@ -94,12 +94,14 @@
 <h2>Design constraints for Ogg bitstreams</h2>
 
 <ol>
-<li>True streaming; we must not need to seek to build a 100% complete bitstream.</li>
-<li>Use no more than approximately 1-2% of bitstream bandwidth for packet
-  boundary marking, high-level framing, sync and seeking.</li>
-<li>Specification of absolute position within the original sample stream.</li>
-<li>Simple mechanism to ease limited editing, such as a simplified concatenation
-  mechanism.</li>
+<li>True streaming; we must not need to seek to build a 100%
+  complete bitstream.</li>
+<li>Use no more than approximately 1-2% of bitstream bandwidth for
+  packet boundary marking, high-level framing, sync and seeking.</li>
+<li>Specification of absolute position within the original sample
+  stream.</li>
+<li>Simple mechanism to ease limited editing, such as a simplified
+  concatenation mechanism.</li>
 <li>Detection of corruption, recapture after error and direct, random
   access to data at arbitrary positions in the bitstream.</li>
 </ol>
@@ -107,28 +109,27 @@
 <h2>Logical and Physical Bitstreams</h2>
 
 <p>A <em>logical</em> Ogg bitstream is a contiguous stream of
-sequential pages belonging only to the logical bitstream.  A
+sequential pages belonging only to the logical bitstream. A
 <em>physical</em> Ogg bitstream is constructed from one or more
 than one logical Ogg bitstream (the simplest physical bitstream
-is simply a single logical bitstream).  We describe below the exact
-formatting of an Ogg logical bitstream.  Combining logical
+is simply a single logical bitstream). We describe below the exact
+formatting of an Ogg logical bitstream. Combining logical
 bitstreams into more complex physical bitstreams is described in the
-<a href="oggstream.html">Ogg bitstream overview</a>.  The exact
+<a href="oggstream.html">Ogg bitstream overview</a>. The exact
 mapping of raw Vorbis packets into a valid Ogg Vorbis physical
-bitstream is described in <a href="vorbis-stream.html">Vorbis
-bitstream mapping</a>.</p>
+bitstream is described in the Vorbis I Specification.</p>
 
 <h2>Bitstream structure</h2>
 
 <p>An Ogg stream is structured by dividing incoming packets into
 segments of up to 255 bytes and then wrapping a group of contiguous
 packet segments into a variable length page preceded by a page
-header.  Both the header size and page size are variable; the page
+header. Both the header size and page size are variable; the page
 header contains sizing information and checksum data to determine
 header/page size and data integrity.</p>
 
 <p>The bitstream is captured (or recaptured) by looking for the beginning
-of a page, specifically the capture pattern.  Once the capture pattern
+of a page, specifically the capture pattern. Once the capture pattern
 is found, the decoder verifies page sync and integrity by computing
 and comparing the checksum. At that point, the decoder can extract the
 packets themselves.</p>
@@ -142,9 +143,9 @@
 boundaries.</p>
 
 <p>The raw packet is logically divided into [n] 255 byte segments and a
-last fractional segment of &lt; 255 bytes.  A packet size may well
+last fractional segment of &lt; 255 bytes. A packet size may well
 consist only of the trailing fractional segment, and a fractional
-segment may be zero length.  These values, called "lacing values" are
+segment may be zero length. These values, called "lacing values" are
 then saved and placed into the header segment table.</p>
 
 <p>An example should make the basic concept clear:</p>
@@ -164,7 +165,7 @@
 that this encoding both avoids imposing a maximum packet size as well
 as imposing minimum overhead on small packets (as opposed to, eg,
 simply using two bytes at the head of every packet and having a max
-packet size of 32k.  Small packets (&lt;255, the typical case) are
+packet size of 32k. Small packets (&lt;255, the typical case) are
 penalized with twice the segmentation overhead). Using the lacing
 values as suggested, small packets see the minimum possible
 byte-aligned overheade (1 byte) and large packets, over 512 bytes or
@@ -172,7 +173,7 @@
 
 <p>Note that a lacing value of 255 implies that a second lacing value
 follows in the packet, and a value of &lt; 255 marks the end of the
-packet after that many additional bytes.  A packet of 255 bytes (or a
+packet after that many additional bytes. A packet of 255 bytes (or a
 multiple of 255 bytes) is terminated by a lacing value of 0:</p>
 
 <pre><tt>
@@ -199,7 +200,7 @@
 <p>After segmenting a packet, the encoder may decide not to place all the
 resulting segments into the current page; to do so, the encoder places
 the lacing values of the segments it wishes to belong to the current
-page into the current segment table, then finishes the page.  The next
+page into the current segment table, then finishes the page. The next
 page is begun with the first value in the segment table belonging to
 the next packet segment, thus continuing the packet (data in the
 packet body must also correspond properly to the lacing values in the
@@ -211,21 +212,21 @@
 <p>The last mechanic to spanning a page boundary is to set the header
 flag in the new page to indicate that the first lacing value in the
 segment table continues rather than begins a packet; a header flag of
-0x01 is set to indicate a continued packet.  Although mandatory, it
+0x01 is set to indicate a continued packet. Although mandatory, it
 is not actually algorithmically necessary; one could inspect the
 preceding segment table to determine if the packet is new or
-continued.  Adding the information to the packet_header flag allows a
+continued. Adding the information to the packet_header flag allows a
 simpler design (with no overhead) that needs only inspect the current
-page header after frame capture.  This also allows faster error
+page header after frame capture. This also allows faster error
 recovery in the event that the packet originates in a corrupt
 preceding page, implying that the previous page's segment table
 cannot be trusted.</p>
 
 <p>Note that a packet can span an arbitrary number of pages; the above
-spanning process is repeated for each spanned page boundary.  Also a
+spanning process is repeated for each spanned page boundary. Also a
 'zero termination' on a packet size that is an even multiple of 255
 must appear even if the lacing value appears in the next page as a
-zero-length continuation of the current packet.  The header flag
+zero-length continuation of the current packet. The header flag
 should be set to 0x01 to indicate that the packet spanned, even though
 the span is a nil case as far as data is concerned.</p>
 
@@ -248,7 +249,7 @@
 <p>The headering mechanism is designed to avoid copying and re-assembly
 of the packet data (ie, making the packet segmentation process a
 logical one); the header can be generated directly from incoming
-packet data.  The encoder buffers packet data until it finishes a
+packet data. The encoder buffers packet data until it finishes a
 complete page at which point it writes the header followed by the
 buffered packet segments.</p>
 
@@ -296,16 +297,16 @@
 <h4>absolute granule position</h4>
 
 <p>(This is packed in the same way the rest of Ogg data is packed; LSb
-of LSB first.  Note that the 'position' data specifies a 'sample'
+of LSB first. Note that the 'position' data specifies a 'sample'
 number (eg, in a CD quality sample is four octets, 16 bits for left
 and 16 bits for right; in video it would likely be the frame number.
 It is up to the specific codec in use to define the semantic meaning
-of the granule position value).  The position specified is the total
+of the granule position value). The position specified is the total
 samples encoded after including all packets finished on this page
 (packets begun on this page but continuing on to the next page do not
-count).  The rationale here is that the position specified in the
+count). The rationale here is that the position specified in the
 frame header of the last page tells how long the data coded by the
-bitstream is.  A truncated stream will still return the proper number
+bitstream is. A truncated stream will still return the proper number
 of samples that can be decoded fully.</p>
 
 <p>A special value of '-1' (in two's complement) indicates that no packets
@@ -327,11 +328,11 @@
 <h4>stream serial number</h4>
  
 <p>Ogg allows for separate logical bitstreams to be mixed at page
-granularity in a physical bitstream.  The most common case would be
+granularity in a physical bitstream. The most common case would be
 sequential arrangement, but it is possible to interleave pages for
-two separate bitstreams to be decoded concurrently.  The serial
+two separate bitstreams to be decoded concurrently. The serial
 number is the means by which pages physical pages are associated with
-a particular logical stream.  Each logical stream must have a unique
+a particular logical stream. Each logical stream must have a unique
 serial number within a physical stream:</p>
 
 <pre><tt>
@@ -360,9 +361,9 @@
 <h4>page checksum</h4>
      
 <p>32 bit CRC value (direct algorithm, initial val and final XOR = 0,
-generator polynomial=0x04c11db7).  The value is computed over the
+generator polynomial=0x04c11db7). The value is computed over the
 entire header (with the CRC field in the header set to zero) and then
-continued over the page.  The CRC field is then filled with the
+continued over the page. The CRC field is then filled with the
 computed value.</p>
 
 <p>(A thorough discussion of CRC algorithms can be found in <a
@@ -386,7 +387,7 @@
 maximum number of 255 segments (255 bytes each) sets the maximum
 possible physical page size at 65307 bytes or just under 64kB (thus
 we know that a header corrupted so as destroy sizing/alignment
-information will not cause a runaway bitstream.  We'll read in the
+information will not cause a runaway bitstream. We'll read in the
 page according to the corrupted size information that's guaranteed to
 be a reasonable size regardless, notice the checksum mismatch, drop
 sync and then look for recapture).</p>
@@ -415,7 +416,7 @@
 immediately after the header.</p>
 
 <p>Page headers typically impose a flat .25-.5% space overhead assuming
-nominal ~8k page sizes.  The segmentation table needed for exact
+nominal ~8k page sizes. The segmentation table needed for exact
 packet recovery in the streaming layer adds approximately .5-1%
 nominal assuming expected encoder behavior in the 44.1kHz, 128kbps
 stereo encodings.</p>