[xiph-commits] r10667 - trunk/vorbis/doc
giles at svn.xiph.org
giles at svn.xiph.org
Tue Dec 20 17:19:41 PST 2005
Author: giles
Date: 2005-12-20 17:19:37 -0800 (Tue, 20 Dec 2005)
New Revision: 10667
Modified:
trunk/vorbis/doc/Vorbis_I_spec.html
trunk/vorbis/doc/floor1_inverse_dB_table.html
trunk/vorbis/doc/framing.html
trunk/vorbis/doc/helper.html
trunk/vorbis/doc/index.html
trunk/vorbis/doc/oggstream.html
trunk/vorbis/doc/programming.html
trunk/vorbis/doc/stereo.html
trunk/vorbis/doc/v-comment.html
trunk/vorbis/doc/vorbis-fidelity.html
trunk/vorbis/doc/vorbis.html
Log:
Set native eol-style.
Property changes on: trunk/vorbis/doc/Vorbis_I_spec.html
___________________________________________________________________
Name: svn:eol-style
+ native
Modified: trunk/vorbis/doc/floor1_inverse_dB_table.html
===================================================================
--- trunk/vorbis/doc/floor1_inverse_dB_table.html 2005-12-20 20:18:59 UTC (rev 10666)
+++ trunk/vorbis/doc/floor1_inverse_dB_table.html 2005-12-21 01:19:37 UTC (rev 10667)
@@ -1,154 +1,154 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html>
-<head>
-
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
-<title>Ogg Vorbis Documentation</title>
-
-<style type="text/css">
-body {
- margin: 0 18px 0 18px;
- padding-bottom: 30px;
- font-family: Verdana, Arial, Helvetica, sans-serif;
- color: #333333;
- font-size: .8em;
-}
-
-a {
- color: #3366cc;
-}
-
-img {
- border: 0;
-}
-
-#xiphlogo {
- margin: 30px 0 16px 0;
-}
-
-#content p {
- line-height: 1.4;
-}
-
-h1, h1 a, h2, h2 a, h3, h3 a {
- font-weight: bold;
- color: #ff9900;
- margin: 1.3em 0 8px 0;
-}
-
-h1 {
- font-size: 1.3em;
-}
-
-h2 {
- font-size: 1.2em;
-}
-
-h3 {
- font-size: 1.1em;
-}
-
-li {
- line-height: 1.4;
-}
-
-#copyright {
- margin-top: 30px;
- line-height: 1.5em;
- text-align: center;
- font-size: .8em;
- color: #888888;
- clear: both;
-}
-</style>
-
-</head>
-
-<body>
-
-<div id="xiphlogo">
- <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.org"/></a>
-</div>
-
-<h1>Ogg Vorbis I format specification: floor1_inverse_dB_table</h1>
-
-<p>The vector <tt>[floor1_inverse_dB_table]</tt> is a 256 element static
-lookup table consiting of the following values (read left to right
-then top to bottom):</p>
-
-<pre>
- 1.0649863e-07, 1.1341951e-07, 1.2079015e-07, 1.2863978e-07,
- 1.3699951e-07, 1.4590251e-07, 1.5538408e-07, 1.6548181e-07,
- 1.7623575e-07, 1.8768855e-07, 1.9988561e-07, 2.1287530e-07,
- 2.2670913e-07, 2.4144197e-07, 2.5713223e-07, 2.7384213e-07,
- 2.9163793e-07, 3.1059021e-07, 3.3077411e-07, 3.5226968e-07,
- 3.7516214e-07, 3.9954229e-07, 4.2550680e-07, 4.5315863e-07,
- 4.8260743e-07, 5.1396998e-07, 5.4737065e-07, 5.8294187e-07,
- 6.2082472e-07, 6.6116941e-07, 7.0413592e-07, 7.4989464e-07,
- 7.9862701e-07, 8.5052630e-07, 9.0579828e-07, 9.6466216e-07,
- 1.0273513e-06, 1.0941144e-06, 1.1652161e-06, 1.2409384e-06,
- 1.3215816e-06, 1.4074654e-06, 1.4989305e-06, 1.5963394e-06,
- 1.7000785e-06, 1.8105592e-06, 1.9282195e-06, 2.0535261e-06,
- 2.1869758e-06, 2.3290978e-06, 2.4804557e-06, 2.6416497e-06,
- 2.8133190e-06, 2.9961443e-06, 3.1908506e-06, 3.3982101e-06,
- 3.6190449e-06, 3.8542308e-06, 4.1047004e-06, 4.3714470e-06,
- 4.6555282e-06, 4.9580707e-06, 5.2802740e-06, 5.6234160e-06,
- 5.9888572e-06, 6.3780469e-06, 6.7925283e-06, 7.2339451e-06,
- 7.7040476e-06, 8.2047000e-06, 8.7378876e-06, 9.3057248e-06,
- 9.9104632e-06, 1.0554501e-05, 1.1240392e-05, 1.1970856e-05,
- 1.2748789e-05, 1.3577278e-05, 1.4459606e-05, 1.5399272e-05,
- 1.6400004e-05, 1.7465768e-05, 1.8600792e-05, 1.9809576e-05,
- 2.1096914e-05, 2.2467911e-05, 2.3928002e-05, 2.5482978e-05,
- 2.7139006e-05, 2.8902651e-05, 3.0780908e-05, 3.2781225e-05,
- 3.4911534e-05, 3.7180282e-05, 3.9596466e-05, 4.2169667e-05,
- 4.4910090e-05, 4.7828601e-05, 5.0936773e-05, 5.4246931e-05,
- 5.7772202e-05, 6.1526565e-05, 6.5524908e-05, 6.9783085e-05,
- 7.4317983e-05, 7.9147585e-05, 8.4291040e-05, 8.9768747e-05,
- 9.5602426e-05, 0.00010181521, 0.00010843174, 0.00011547824,
- 0.00012298267, 0.00013097477, 0.00013948625, 0.00014855085,
- 0.00015820453, 0.00016848555, 0.00017943469, 0.00019109536,
- 0.00020351382, 0.00021673929, 0.00023082423, 0.00024582449,
- 0.00026179955, 0.00027881276, 0.00029693158, 0.00031622787,
- 0.00033677814, 0.00035866388, 0.00038197188, 0.00040679456,
- 0.00043323036, 0.00046138411, 0.00049136745, 0.00052329927,
- 0.00055730621, 0.00059352311, 0.00063209358, 0.00067317058,
- 0.00071691700, 0.00076350630, 0.00081312324, 0.00086596457,
- 0.00092223983, 0.00098217216, 0.0010459992, 0.0011139742,
- 0.0011863665, 0.0012634633, 0.0013455702, 0.0014330129,
- 0.0015261382, 0.0016253153, 0.0017309374, 0.0018434235,
- 0.0019632195, 0.0020908006, 0.0022266726, 0.0023713743,
- 0.0025254795, 0.0026895994, 0.0028643847, 0.0030505286,
- 0.0032487691, 0.0034598925, 0.0036847358, 0.0039241906,
- 0.0041792066, 0.0044507950, 0.0047400328, 0.0050480668,
- 0.0053761186, 0.0057254891, 0.0060975636, 0.0064938176,
- 0.0069158225, 0.0073652516, 0.0078438871, 0.0083536271,
- 0.0088964928, 0.009474637, 0.010090352, 0.010746080,
- 0.011444421, 0.012188144, 0.012980198, 0.013823725,
- 0.014722068, 0.015678791, 0.016697687, 0.017782797,
- 0.018938423, 0.020169149, 0.021479854, 0.022875735,
- 0.024362330, 0.025945531, 0.027631618, 0.029427276,
- 0.031339626, 0.033376252, 0.035545228, 0.037855157,
- 0.040315199, 0.042935108, 0.045725273, 0.048696758,
- 0.051861348, 0.055231591, 0.058820850, 0.062643361,
- 0.066714279, 0.071049749, 0.075666962, 0.080584227,
- 0.085821044, 0.091398179, 0.097337747, 0.10366330,
- 0.11039993, 0.11757434, 0.12521498, 0.13335215,
- 0.14201813, 0.15124727, 0.16107617, 0.17154380,
- 0.18269168, 0.19456402, 0.20720788, 0.22067342,
- 0.23501402, 0.25028656, 0.26655159, 0.28387361,
- 0.30232132, 0.32196786, 0.34289114, 0.36517414,
- 0.38890521, 0.41417847, 0.44109412, 0.46975890,
- 0.50028648, 0.53279791, 0.56742212, 0.60429640,
- 0.64356699, 0.68538959, 0.72993007, 0.77736504,
- 0.82788260, 0.88168307, 0.9389798, 1.
-</pre>
-
-<div id="copyright">
- The Xiph Fish Logo is a
- trademark (™) of Xiph.Org.<br/>
-
- These pages © 1994 - 2005 Xiph.Org. All rights reserved.
-</div>
-
-</body>
-</html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<head>
+
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
+<title>Ogg Vorbis Documentation</title>
+
+<style type="text/css">
+body {
+ margin: 0 18px 0 18px;
+ padding-bottom: 30px;
+ font-family: Verdana, Arial, Helvetica, sans-serif;
+ color: #333333;
+ font-size: .8em;
+}
+
+a {
+ color: #3366cc;
+}
+
+img {
+ border: 0;
+}
+
+#xiphlogo {
+ margin: 30px 0 16px 0;
+}
+
+#content p {
+ line-height: 1.4;
+}
+
+h1, h1 a, h2, h2 a, h3, h3 a {
+ font-weight: bold;
+ color: #ff9900;
+ margin: 1.3em 0 8px 0;
+}
+
+h1 {
+ font-size: 1.3em;
+}
+
+h2 {
+ font-size: 1.2em;
+}
+
+h3 {
+ font-size: 1.1em;
+}
+
+li {
+ line-height: 1.4;
+}
+
+#copyright {
+ margin-top: 30px;
+ line-height: 1.5em;
+ text-align: center;
+ font-size: .8em;
+ color: #888888;
+ clear: both;
+}
+</style>
+
+</head>
+
+<body>
+
+<div id="xiphlogo">
+ <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.org"/></a>
+</div>
+
+<h1>Ogg Vorbis I format specification: floor1_inverse_dB_table</h1>
+
+<p>The vector <tt>[floor1_inverse_dB_table]</tt> is a 256 element static
+lookup table consiting of the following values (read left to right
+then top to bottom):</p>
+
+<pre>
+ 1.0649863e-07, 1.1341951e-07, 1.2079015e-07, 1.2863978e-07,
+ 1.3699951e-07, 1.4590251e-07, 1.5538408e-07, 1.6548181e-07,
+ 1.7623575e-07, 1.8768855e-07, 1.9988561e-07, 2.1287530e-07,
+ 2.2670913e-07, 2.4144197e-07, 2.5713223e-07, 2.7384213e-07,
+ 2.9163793e-07, 3.1059021e-07, 3.3077411e-07, 3.5226968e-07,
+ 3.7516214e-07, 3.9954229e-07, 4.2550680e-07, 4.5315863e-07,
+ 4.8260743e-07, 5.1396998e-07, 5.4737065e-07, 5.8294187e-07,
+ 6.2082472e-07, 6.6116941e-07, 7.0413592e-07, 7.4989464e-07,
+ 7.9862701e-07, 8.5052630e-07, 9.0579828e-07, 9.6466216e-07,
+ 1.0273513e-06, 1.0941144e-06, 1.1652161e-06, 1.2409384e-06,
+ 1.3215816e-06, 1.4074654e-06, 1.4989305e-06, 1.5963394e-06,
+ 1.7000785e-06, 1.8105592e-06, 1.9282195e-06, 2.0535261e-06,
+ 2.1869758e-06, 2.3290978e-06, 2.4804557e-06, 2.6416497e-06,
+ 2.8133190e-06, 2.9961443e-06, 3.1908506e-06, 3.3982101e-06,
+ 3.6190449e-06, 3.8542308e-06, 4.1047004e-06, 4.3714470e-06,
+ 4.6555282e-06, 4.9580707e-06, 5.2802740e-06, 5.6234160e-06,
+ 5.9888572e-06, 6.3780469e-06, 6.7925283e-06, 7.2339451e-06,
+ 7.7040476e-06, 8.2047000e-06, 8.7378876e-06, 9.3057248e-06,
+ 9.9104632e-06, 1.0554501e-05, 1.1240392e-05, 1.1970856e-05,
+ 1.2748789e-05, 1.3577278e-05, 1.4459606e-05, 1.5399272e-05,
+ 1.6400004e-05, 1.7465768e-05, 1.8600792e-05, 1.9809576e-05,
+ 2.1096914e-05, 2.2467911e-05, 2.3928002e-05, 2.5482978e-05,
+ 2.7139006e-05, 2.8902651e-05, 3.0780908e-05, 3.2781225e-05,
+ 3.4911534e-05, 3.7180282e-05, 3.9596466e-05, 4.2169667e-05,
+ 4.4910090e-05, 4.7828601e-05, 5.0936773e-05, 5.4246931e-05,
+ 5.7772202e-05, 6.1526565e-05, 6.5524908e-05, 6.9783085e-05,
+ 7.4317983e-05, 7.9147585e-05, 8.4291040e-05, 8.9768747e-05,
+ 9.5602426e-05, 0.00010181521, 0.00010843174, 0.00011547824,
+ 0.00012298267, 0.00013097477, 0.00013948625, 0.00014855085,
+ 0.00015820453, 0.00016848555, 0.00017943469, 0.00019109536,
+ 0.00020351382, 0.00021673929, 0.00023082423, 0.00024582449,
+ 0.00026179955, 0.00027881276, 0.00029693158, 0.00031622787,
+ 0.00033677814, 0.00035866388, 0.00038197188, 0.00040679456,
+ 0.00043323036, 0.00046138411, 0.00049136745, 0.00052329927,
+ 0.00055730621, 0.00059352311, 0.00063209358, 0.00067317058,
+ 0.00071691700, 0.00076350630, 0.00081312324, 0.00086596457,
+ 0.00092223983, 0.00098217216, 0.0010459992, 0.0011139742,
+ 0.0011863665, 0.0012634633, 0.0013455702, 0.0014330129,
+ 0.0015261382, 0.0016253153, 0.0017309374, 0.0018434235,
+ 0.0019632195, 0.0020908006, 0.0022266726, 0.0023713743,
+ 0.0025254795, 0.0026895994, 0.0028643847, 0.0030505286,
+ 0.0032487691, 0.0034598925, 0.0036847358, 0.0039241906,
+ 0.0041792066, 0.0044507950, 0.0047400328, 0.0050480668,
+ 0.0053761186, 0.0057254891, 0.0060975636, 0.0064938176,
+ 0.0069158225, 0.0073652516, 0.0078438871, 0.0083536271,
+ 0.0088964928, 0.009474637, 0.010090352, 0.010746080,
+ 0.011444421, 0.012188144, 0.012980198, 0.013823725,
+ 0.014722068, 0.015678791, 0.016697687, 0.017782797,
+ 0.018938423, 0.020169149, 0.021479854, 0.022875735,
+ 0.024362330, 0.025945531, 0.027631618, 0.029427276,
+ 0.031339626, 0.033376252, 0.035545228, 0.037855157,
+ 0.040315199, 0.042935108, 0.045725273, 0.048696758,
+ 0.051861348, 0.055231591, 0.058820850, 0.062643361,
+ 0.066714279, 0.071049749, 0.075666962, 0.080584227,
+ 0.085821044, 0.091398179, 0.097337747, 0.10366330,
+ 0.11039993, 0.11757434, 0.12521498, 0.13335215,
+ 0.14201813, 0.15124727, 0.16107617, 0.17154380,
+ 0.18269168, 0.19456402, 0.20720788, 0.22067342,
+ 0.23501402, 0.25028656, 0.26655159, 0.28387361,
+ 0.30232132, 0.32196786, 0.34289114, 0.36517414,
+ 0.38890521, 0.41417847, 0.44109412, 0.46975890,
+ 0.50028648, 0.53279791, 0.56742212, 0.60429640,
+ 0.64356699, 0.68538959, 0.72993007, 0.77736504,
+ 0.82788260, 0.88168307, 0.9389798, 1.
+</pre>
+
+<div id="copyright">
+ The Xiph Fish Logo is a
+ trademark (™) of Xiph.Org.<br/>
+
+ These pages © 1994 - 2005 Xiph.Org. All rights reserved.
+</div>
+
+</body>
+</html>
Property changes on: trunk/vorbis/doc/floor1_inverse_dB_table.html
___________________________________________________________________
Name: svn:eol-style
+ native
Modified: trunk/vorbis/doc/framing.html
===================================================================
--- trunk/vorbis/doc/framing.html 2005-12-20 20:18:59 UTC (rev 10666)
+++ trunk/vorbis/doc/framing.html 2005-12-21 01:19:37 UTC (rev 10667)
@@ -1,433 +1,433 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html>
-<head>
-
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
-<title>Ogg Vorbis Documentation</title>
-
-<style type="text/css">
-body {
- margin: 0 18px 0 18px;
- padding-bottom: 30px;
- font-family: Verdana, Arial, Helvetica, sans-serif;
- color: #333333;
- font-size: .8em;
-}
-
-a {
- color: #3366cc;
-}
-
-img {
- border: 0;
-}
-
-#xiphlogo {
- margin: 30px 0 16px 0;
-}
-
-#content p {
- line-height: 1.4;
-}
-
-h1, h1 a, h2, h2 a, h3, h3 a {
- font-weight: bold;
- color: #ff9900;
- margin: 1.3em 0 8px 0;
-}
-
-h1 {
- font-size: 1.3em;
-}
-
-h2 {
- font-size: 1.2em;
-}
-
-h3 {
- font-size: 1.1em;
-}
-
-li {
- line-height: 1.4;
-}
-
-#copyright {
- margin-top: 30px;
- line-height: 1.5em;
- text-align: center;
- font-size: .8em;
- color: #888888;
- clear: both;
-}
-</style>
-
-</head>
-
-<body>
-
-<div id="xiphlogo">
- <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.org"/></a>
-</div>
-
-<h1>Ogg logical bitstream framing</h1>
-
-<h2>Ogg bitstreams</h2>
-
-<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>
-
-<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
-mechanisms that provide their own framing and packet-separation
-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
-properly separate data back into packets at the original packet
-boundaries without relying on decoding to find packet boundaries.</p>
-
-<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>Detection of corruption, recapture after error and direct, random
- access to data at arbitrary positions in the bitstream.</li>
-</ol>
-
-<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
-<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
-bitstreams into more complex physical bitstreams is described in the
-<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>
-
-<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 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
-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>
-
-<h3>Packet segmentation</h3>
-
-<p>Packets are logically divided into multiple segments before encoding
-into a page. Note that the segmentation and fragmentation process is a
-logical one; it's used to compute page header values and the original
-page data need not be disturbed, even when a packet spans page
-boundaries.</p>
-
-<p>The raw packet is logically divided into [n] 255 byte segments and a
-last fractional segment of < 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
-then saved and placed into the header segment table.</p>
-
-<p>An example should make the basic concept clear:</p>
-
-<pre>
-<tt>
-raw packet:
- ___________________________________________
- |______________packet data__________________| 753 bytes
-
-lacing values for page header segment table: 255,255,243
-</tt>
-</pre>
-
-<p>We simply add the lacing values for the total size; the last lacing
-value for a packet is always the value that is less than 255. Note
-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 (<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
-so, see a fairly constant ~.5% overhead on encoding space.</p>
-
-<p>Note that a lacing value of 255 implies that a second lacing value
-follows in the packet, and a value of < 255 marks the end of the
-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>
-raw packet:
- _______________________________
- |________packet data____________| 255 bytes
-
-lacing values: 255, 0
-</tt></pre>
-
-<p>Note also that a 'nil' (zero length) packet is not an error; it
-consists of nothing more than a lacing value of zero in the header.</p>
-
-<h3>Packets spanning pages</h3>
-
-<p>Packets are not restricted to beginning and ending within a page,
-although individual segments are, by definition, required to do so.
-Packets are not restricted to a maximum size, although excessively
-large packets in the data stream are discouraged; the Ogg
-bitstream specification strongly recommends nominal page size of
-approximately 4-8kB (large packets are foreseen as being useful for
-initialization data at the beginning of a logical bitstream).</p>
-
-<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 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
-spanned pages. The segment data in the first packet corresponding to
-the lacing values of the first page belong in that page; packet
-segments listed in the segment table of the following page must begin
-the page body of the subsequent page).</p>
-
-<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
-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
-simpler design (with no overhead) that needs only inspect the current
-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
-'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
-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>
-
-<p>The encoding looks odd, but is properly optimized for speed and the
-expected case of the majority of packets being between 50 and 200
-bytes (note that it is designed such that packets of wildly different
-sizes can be handled within the model; placing packet size
-restrictions on the encoder would have only slightly simplified design
-in page generation and increased overall encoder complexity).</p>
-
-<p>The main point behind tracking individual packets (and packet
-segments) is to allow more flexible encoding tricks that requiring
-explicit knowledge of packet size. An example is simple bandwidth
-limiting, implemented by simply truncating packets in the nominal case
-if the packet is arranged so that the least sensitive portion of the
-data comes last.</p>
-
-<h3>Page header</h3>
-
-<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
-complete page at which point it writes the header followed by the
-buffered packet segments.</p>
-
-<h4>capture_pattern</h4>
-
-<p>A header begins with a capture pattern that simplifies identifying
-pages; once the decoder has found the capture pattern it can do a more
-intensive job of verifying that it has in fact found a page boundary
-(as opposed to an inadvertent coincidence in the byte stream).</p>
-
-<pre><tt>
- byte value
-
- 0 0x4f 'O'
- 1 0x67 'g'
- 2 0x67 'g'
- 3 0x53 'S'
-</tt></pre>
-
-<h4>stream_structure_version</h4>
-
-<p>The capture pattern is followed by the stream structure revision:</p>
-
-<pre><tt>
- byte value
-
- 4 0x00
-</tt></pre>
-
-<h4>header_type_flag</h4>
-
-<p>The header type flag identifies this page's context in the bitstream:</p>
-
-<pre><tt>
- byte value
-
- 5 bitflags: 0x01: unset = fresh packet
- set = continued packet
- 0x02: unset = not first page of logical bitstream
- set = first page of logical bitstream (bos)
- 0x04: unset = not last page of logical bitstream
- set = last page of logical bitstream (eos)
-</tt></pre>
-
-<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'
-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
-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
-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
-of samples that can be decoded fully.</p>
-
-<p>A special value of '-1' (in two's complement) indicates that no packets
-finish on this page.</p>
-
-<pre><tt>
- byte value
-
- 6 0xXX LSB
- 7 0xXX
- 8 0xXX
- 9 0xXX
- 10 0xXX
- 11 0xXX
- 12 0xXX
- 13 0xXX MSB
-</tt></pre>
-
-<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
-sequential arrangement, but it is possible to interleave pages for
-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
-serial number within a physical stream:</p>
-
-<pre><tt>
- byte value
-
- 14 0xXX LSB
- 15 0xXX
- 16 0xXX
- 17 0xXX MSB
-</tt></pre>
-
-<h4>page sequence no</h4>
-
-<p>Page counter; lets us know if a page is lost (useful where packets
-span page boundaries).</p>
-
-<pre><tt>
- byte value
-
- 18 0xXX LSB
- 19 0xXX
- 20 0xXX
- 21 0xXX MSB
-</tt></pre>
-
-<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
-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
-computed value.</p>
-
-<p>(A thorough discussion of CRC algorithms can be found in <a
-href="ftp://ftp.rocksoft.com/papers/crc_v3.txt">"A
-Painless Guide to CRC Error Detection Algorithms"</a> by Ross
-Williams <a
-href="mailto:ross at guest.adelaide.edu.au">ross at guest.adelaide.edu.au</a>.)</p>
-
-<pre><tt>
- byte value
-
- 22 0xXX LSB
- 23 0xXX
- 24 0xXX
- 25 0xXX MSB
-</tt></pre>
-
-<h4>page_segments</h4>
-
-<p>The number of segment entries to appear in the segment table. The
-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
-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>
-
-<pre><tt>
- byte value
-
- 26 0x00-0xff (0-255)
-</tt></pre>
-
-<h4>segment_table (containing packet lacing values)</h4>
-
-<p>The lacing values for each packet segment physically appearing in
-this page are listed in contiguous order.</p>
-
-<pre><tt>
- byte value
-
- 27 0x00-0xff (0-255)
- [...]
- n 0x00-0xff (0-255, n=page_segments+26)
-</tt></pre>
-
-<p>Total page size is calculated directly from the known header size and
-lacing values in the segment table. Packet data segments follow
-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
-packet recovery in the streaming layer adds approximately .5-1%
-nominal assuming expected encoder behavior in the 44.1kHz, 128kbps
-stereo encodings.</p>
-
-<div id="copyright">
- The Xiph Fish Logo is a
- trademark (™) of Xiph.Org.<br/>
-
- These pages © 1994 - 2005 Xiph.Org. All rights reserved.
-</div>
-
-</body>
-</html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<head>
+
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
+<title>Ogg Vorbis Documentation</title>
+
+<style type="text/css">
+body {
+ margin: 0 18px 0 18px;
+ padding-bottom: 30px;
+ font-family: Verdana, Arial, Helvetica, sans-serif;
+ color: #333333;
+ font-size: .8em;
+}
+
+a {
+ color: #3366cc;
+}
+
+img {
+ border: 0;
+}
+
+#xiphlogo {
+ margin: 30px 0 16px 0;
+}
+
+#content p {
+ line-height: 1.4;
+}
+
+h1, h1 a, h2, h2 a, h3, h3 a {
+ font-weight: bold;
+ color: #ff9900;
+ margin: 1.3em 0 8px 0;
+}
+
+h1 {
+ font-size: 1.3em;
+}
+
+h2 {
+ font-size: 1.2em;
+}
+
+h3 {
+ font-size: 1.1em;
+}
+
+li {
+ line-height: 1.4;
+}
+
+#copyright {
+ margin-top: 30px;
+ line-height: 1.5em;
+ text-align: center;
+ font-size: .8em;
+ color: #888888;
+ clear: both;
+}
+</style>
+
+</head>
+
+<body>
+
+<div id="xiphlogo">
+ <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.org"/></a>
+</div>
+
+<h1>Ogg logical bitstream framing</h1>
+
+<h2>Ogg bitstreams</h2>
+
+<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>
+
+<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
+mechanisms that provide their own framing and packet-separation
+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
+properly separate data back into packets at the original packet
+boundaries without relying on decoding to find packet boundaries.</p>
+
+<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>Detection of corruption, recapture after error and direct, random
+ access to data at arbitrary positions in the bitstream.</li>
+</ol>
+
+<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
+<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
+bitstreams into more complex physical bitstreams is described in the
+<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>
+
+<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 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
+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>
+
+<h3>Packet segmentation</h3>
+
+<p>Packets are logically divided into multiple segments before encoding
+into a page. Note that the segmentation and fragmentation process is a
+logical one; it's used to compute page header values and the original
+page data need not be disturbed, even when a packet spans page
+boundaries.</p>
+
+<p>The raw packet is logically divided into [n] 255 byte segments and a
+last fractional segment of < 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
+then saved and placed into the header segment table.</p>
+
+<p>An example should make the basic concept clear:</p>
+
+<pre>
+<tt>
+raw packet:
+ ___________________________________________
+ |______________packet data__________________| 753 bytes
+
+lacing values for page header segment table: 255,255,243
+</tt>
+</pre>
+
+<p>We simply add the lacing values for the total size; the last lacing
+value for a packet is always the value that is less than 255. Note
+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 (<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
+so, see a fairly constant ~.5% overhead on encoding space.</p>
+
+<p>Note that a lacing value of 255 implies that a second lacing value
+follows in the packet, and a value of < 255 marks the end of the
+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>
+raw packet:
+ _______________________________
+ |________packet data____________| 255 bytes
+
+lacing values: 255, 0
+</tt></pre>
+
+<p>Note also that a 'nil' (zero length) packet is not an error; it
+consists of nothing more than a lacing value of zero in the header.</p>
+
+<h3>Packets spanning pages</h3>
+
+<p>Packets are not restricted to beginning and ending within a page,
+although individual segments are, by definition, required to do so.
+Packets are not restricted to a maximum size, although excessively
+large packets in the data stream are discouraged; the Ogg
+bitstream specification strongly recommends nominal page size of
+approximately 4-8kB (large packets are foreseen as being useful for
+initialization data at the beginning of a logical bitstream).</p>
+
+<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 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
+spanned pages. The segment data in the first packet corresponding to
+the lacing values of the first page belong in that page; packet
+segments listed in the segment table of the following page must begin
+the page body of the subsequent page).</p>
+
+<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
+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
+simpler design (with no overhead) that needs only inspect the current
+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
+'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
+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>
+
+<p>The encoding looks odd, but is properly optimized for speed and the
+expected case of the majority of packets being between 50 and 200
+bytes (note that it is designed such that packets of wildly different
+sizes can be handled within the model; placing packet size
+restrictions on the encoder would have only slightly simplified design
+in page generation and increased overall encoder complexity).</p>
+
+<p>The main point behind tracking individual packets (and packet
+segments) is to allow more flexible encoding tricks that requiring
+explicit knowledge of packet size. An example is simple bandwidth
+limiting, implemented by simply truncating packets in the nominal case
+if the packet is arranged so that the least sensitive portion of the
+data comes last.</p>
+
+<h3>Page header</h3>
+
+<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
+complete page at which point it writes the header followed by the
+buffered packet segments.</p>
+
+<h4>capture_pattern</h4>
+
+<p>A header begins with a capture pattern that simplifies identifying
+pages; once the decoder has found the capture pattern it can do a more
+intensive job of verifying that it has in fact found a page boundary
+(as opposed to an inadvertent coincidence in the byte stream).</p>
+
+<pre><tt>
+ byte value
+
+ 0 0x4f 'O'
+ 1 0x67 'g'
+ 2 0x67 'g'
+ 3 0x53 'S'
+</tt></pre>
+
+<h4>stream_structure_version</h4>
+
+<p>The capture pattern is followed by the stream structure revision:</p>
+
+<pre><tt>
+ byte value
+
+ 4 0x00
+</tt></pre>
+
+<h4>header_type_flag</h4>
+
+<p>The header type flag identifies this page's context in the bitstream:</p>
+
+<pre><tt>
+ byte value
+
+ 5 bitflags: 0x01: unset = fresh packet
+ set = continued packet
+ 0x02: unset = not first page of logical bitstream
+ set = first page of logical bitstream (bos)
+ 0x04: unset = not last page of logical bitstream
+ set = last page of logical bitstream (eos)
+</tt></pre>
+
+<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'
+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
+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
+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
+of samples that can be decoded fully.</p>
+
+<p>A special value of '-1' (in two's complement) indicates that no packets
+finish on this page.</p>
+
+<pre><tt>
+ byte value
+
+ 6 0xXX LSB
+ 7 0xXX
+ 8 0xXX
+ 9 0xXX
+ 10 0xXX
+ 11 0xXX
+ 12 0xXX
+ 13 0xXX MSB
+</tt></pre>
+
+<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
+sequential arrangement, but it is possible to interleave pages for
+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
+serial number within a physical stream:</p>
+
+<pre><tt>
+ byte value
+
+ 14 0xXX LSB
+ 15 0xXX
+ 16 0xXX
+ 17 0xXX MSB
+</tt></pre>
+
+<h4>page sequence no</h4>
+
+<p>Page counter; lets us know if a page is lost (useful where packets
+span page boundaries).</p>
+
+<pre><tt>
+ byte value
+
+ 18 0xXX LSB
+ 19 0xXX
+ 20 0xXX
+ 21 0xXX MSB
+</tt></pre>
+
+<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
+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
+computed value.</p>
+
+<p>(A thorough discussion of CRC algorithms can be found in <a
+href="ftp://ftp.rocksoft.com/papers/crc_v3.txt">"A
+Painless Guide to CRC Error Detection Algorithms"</a> by Ross
+Williams <a
+href="mailto:ross at guest.adelaide.edu.au">ross at guest.adelaide.edu.au</a>.)</p>
+
+<pre><tt>
+ byte value
+
+ 22 0xXX LSB
+ 23 0xXX
+ 24 0xXX
+ 25 0xXX MSB
+</tt></pre>
+
+<h4>page_segments</h4>
+
+<p>The number of segment entries to appear in the segment table. The
+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
+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>
+
+<pre><tt>
+ byte value
+
+ 26 0x00-0xff (0-255)
+</tt></pre>
+
+<h4>segment_table (containing packet lacing values)</h4>
+
+<p>The lacing values for each packet segment physically appearing in
+this page are listed in contiguous order.</p>
+
+<pre><tt>
+ byte value
+
+ 27 0x00-0xff (0-255)
+ [...]
+ n 0x00-0xff (0-255, n=page_segments+26)
+</tt></pre>
+
+<p>Total page size is calculated directly from the known header size and
+lacing values in the segment table. Packet data segments follow
+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
+packet recovery in the streaming layer adds approximately .5-1%
+nominal assuming expected encoder behavior in the 44.1kHz, 128kbps
+stereo encodings.</p>
+
+<div id="copyright">
+ The Xiph Fish Logo is a
+ trademark (™) of Xiph.Org.<br/>
+
+ These pages © 1994 - 2005 Xiph.Org. All rights reserved.
+</div>
+
+</body>
+</html>
Property changes on: trunk/vorbis/doc/framing.html
___________________________________________________________________
Name: svn:eol-style
+ native
Modified: trunk/vorbis/doc/helper.html
===================================================================
--- trunk/vorbis/doc/helper.html 2005-12-20 20:18:59 UTC (rev 10666)
+++ trunk/vorbis/doc/helper.html 2005-12-21 01:19:37 UTC (rev 10667)
@@ -1,239 +1,239 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html>
-<head>
-
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
-<title>Ogg Vorbis Documentation</title>
-
-<style type="text/css">
-body {
- margin: 0 18px 0 18px;
- padding-bottom: 30px;
- font-family: Verdana, Arial, Helvetica, sans-serif;
- color: #333333;
- font-size: .8em;
-}
-
-a {
- color: #3366cc;
-}
-
-img {
- border: 0;
-}
-
-#xiphlogo {
- margin: 30px 0 16px 0;
-}
-
-#content p {
- line-height: 1.4;
-}
-
-h1, h1 a, h2, h2 a, h3, h3 a {
- font-weight: bold;
- color: #ff9900;
- margin: 1.3em 0 8px 0;
-}
-
-h1 {
- font-size: 1.3em;
-}
-
-h2 {
- font-size: 1.2em;
-}
-
-h3 {
- font-size: 1.1em;
-}
-
-li {
- line-height: 1.4;
-}
-
-#copyright {
- margin-top: 30px;
- line-height: 1.5em;
- text-align: center;
- font-size: .8em;
- color: #888888;
- clear: both;
-}
-</style>
-
-</head>
-
-<body>
-
-<div id="xiphlogo">
- <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.org"/></a>
-</div>
-
-<h1>Ogg Vorbis I format specification: helper equations</h1>
-
-<h1>Overview</h1>
-
-<p>The equations below are used in multiple places by the Vorbis codec
-specification. Rather than cluttering up the main specification
-documents, they are defined here and linked in the main documents
-where appropriate.</p>
-
-<h2><a name="log">ilog</a></h2>
-
-<p>The "ilog(x)" function returns the position number (1 through n) of the
-highest set bit in the two's complement integer value
-<tt>[x]</tt>. Values of <tt>[x]</tt> less than zero are defined to return zero.</p>
-
-<pre>
- 1) [return_value] = 0;
- 2) if ( [x] is greater than zero ){
-
- 3) increment [return_value];
- 4) logical shift [x] one bit to the right, padding the MSb with zero
- 5) repeat at step 2)
-
- }
-
- 6) done
-</pre>
-
-<p>Examples:</p>
-
-<ul>
-<li>ilog(0) = 0;</li>
-<li>ilog(1) = 1;</li>
-<li>ilog(2) = 2;</li>
-<li>ilog(3) = 2;</li>
-<li>ilog(4) = 3;</li>
-<li>ilog(7) = 3;</li>
-<li>ilog(negative number) = 0;</li>
-</ul>
-
-<h2><a name="float32_unpack">float32_unpack</a></h2>
-
-<p>"float32_unpack(x)" is intended to translate the packed binary
-representation of a Vorbis codebook float value into the
-representation used by the decoder for floating point numbers. For
-purposes of this example, we will unpack a Vorbis float32 into a
-host-native floating point number.</p>
-
-<pre>
- 1) [mantissa] = [x] bitwise AND 0x1fffff (unsigned result)
- 2) [sign] = [x] bitwise AND 0x80000000 (unsigned result)
- 3) [exponent] = ( [x] bitwise AND 0x7fe00000) shifted right 21 bits (unsigned result)
- 4) if ( [sign] is nonzero ) then negate [mantissa]
- 5) return [mantissa] * ( 2 ^ ( [exponent] - 788 ) )
-</pre>
-
-<h2><a name="lookup1_values">lookup1_values</a></h2>
-
-<p>"lookup1_values(codebook_entries,codebook_dimensions)" is used to
-compute the correct length of the value index for a codebook VQ lookup
-table of lookup type 1. The values on this list are permuted to
-construct the VQ vector lookup table of size
-<tt>[codebook_entries]</tt>.</p>
-
-<p>The return value for this function is defined to be 'the greatest
-integer value for which <tt>[return_value] to the power of
-[codebook_dimensions] is less than or equal to
-[codebook_entries]</tt>'.</p>
-
-<h2><a name="low_neighbor">low_neighbor</a></h2>
-
-<p>"low_neighbor(v,x)" finds the position <i>n</i> in vector [v] of
-the greatest value scalar element for which <i>n</i> is less than
-<tt>[x]</tt> and <tt>vector [v] element <i>n</i> is less
-than vector [v] element [x]</tt>.</p>
-
-<h2><a name="high_neighbor">high_neighbor</a></h2>
-
-<p>"high_neighbor(v,x)" finds the position <i>n</i> in vector [v] of
-the lowest value scalar element for which <i>n</i> is less than
-<tt>[x]</tt> and <tt>vector [v] element <i>n</i> is greater
-than vector [v] element [x]</tt>.</p>
-
-<h2><a name="render_point">render_point</a></h2>
-
-<p>"render_point(x0,y0,x1,y1,X)" is used to find the Y value at point X
-along the line specified by x0, x1, y0 and y1. This function uses an
-integer algorithm to solve for the point directly without calculating
-intervening values along the line.</p>
-
-<pre>
- 1) [dy] = [y1] - [y0]
- 2) [adx] = [x1] - [x0]
- 3) [ady] = absolute value of [dy]
- 4) [err] = [ady] * ([X] - [x0])
- 5) [off] = [err] / [adx] using integer division
- 6) if ( [dy] is less than zero ) {
-
- 7) [Y] = [y0] - [off]
-
- } else {
-
- 8) [Y] = [y0] + [off]
-
- }
-
- 9) done
-</pre>
-
-<h2><a name="render_line">render_line</a></h2>
-
-<p>Floor decode type one uses the integer line drawing algorithm of
-"render_line(x0, y0, x1, y1, v)" to construct an integer floor
-curve for contiguous piecewise line segments. Note that it has not
-been relevant elsewhere, but here we must define integer division as
-rounding division of both positive and negative numbers toward zero.</p>
-
-<pre>
- 1) [dy] = [y1] - [y0]
- 2) [adx] = [x1] - [x0]
- 3) [ady] = absolute value of [dy]
- 4) [base] = [dy] / [adx] using integer division
- 5) [x] = [x0]
- 6) [y] = [y0]
- 7) [err] = 0
-
- 8) if ( [dy] is less than 0 ) {
-
- 9) [sy] = [base] - 1
-
- } else {
-
- 10) [sy] = [base] + 1
-
- }
-
- 11) [ady] = [ady] - (absolute value of [base]) * [adx]
- 12) vector [v] element [x] = [y]
-
- 13) iterate [x] over the range [x0]+1 ... [x1]-1 {
-
- 14) [err] = [err] + [ady];
- 15) if ( [err] >= [adx] ) {
-
- 15) [err] = [err] - [adx]
- 16) [y] = [y] + [sy]
-
- } else {
-
- 17) [y] = [y] + [base]
-
- }
-
- 18) vector [v] element [x] = [y]
-
- }
-</pre>
-
-<div id="copyright">
- The Xiph Fish Logo is a
- trademark (™) of Xiph.Org.<br/>
-
- These pages © 1994 - 2005 Xiph.Org. All rights reserved.
-</div>
-
-</body>
-</html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<head>
+
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
+<title>Ogg Vorbis Documentation</title>
+
+<style type="text/css">
+body {
+ margin: 0 18px 0 18px;
+ padding-bottom: 30px;
+ font-family: Verdana, Arial, Helvetica, sans-serif;
+ color: #333333;
+ font-size: .8em;
+}
+
+a {
+ color: #3366cc;
+}
+
+img {
+ border: 0;
+}
+
+#xiphlogo {
+ margin: 30px 0 16px 0;
+}
+
+#content p {
+ line-height: 1.4;
+}
+
+h1, h1 a, h2, h2 a, h3, h3 a {
+ font-weight: bold;
+ color: #ff9900;
+ margin: 1.3em 0 8px 0;
+}
+
+h1 {
+ font-size: 1.3em;
+}
+
+h2 {
+ font-size: 1.2em;
+}
+
+h3 {
+ font-size: 1.1em;
+}
+
+li {
+ line-height: 1.4;
+}
+
+#copyright {
+ margin-top: 30px;
+ line-height: 1.5em;
+ text-align: center;
+ font-size: .8em;
+ color: #888888;
+ clear: both;
+}
+</style>
+
+</head>
+
+<body>
+
+<div id="xiphlogo">
+ <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.org"/></a>
+</div>
+
+<h1>Ogg Vorbis I format specification: helper equations</h1>
+
+<h1>Overview</h1>
+
+<p>The equations below are used in multiple places by the Vorbis codec
+specification. Rather than cluttering up the main specification
+documents, they are defined here and linked in the main documents
+where appropriate.</p>
+
+<h2><a name="log">ilog</a></h2>
+
+<p>The "ilog(x)" function returns the position number (1 through n) of the
+highest set bit in the two's complement integer value
+<tt>[x]</tt>. Values of <tt>[x]</tt> less than zero are defined to return zero.</p>
+
+<pre>
+ 1) [return_value] = 0;
+ 2) if ( [x] is greater than zero ){
+
+ 3) increment [return_value];
+ 4) logical shift [x] one bit to the right, padding the MSb with zero
+ 5) repeat at step 2)
+
+ }
+
+ 6) done
+</pre>
+
+<p>Examples:</p>
+
+<ul>
+<li>ilog(0) = 0;</li>
+<li>ilog(1) = 1;</li>
+<li>ilog(2) = 2;</li>
+<li>ilog(3) = 2;</li>
+<li>ilog(4) = 3;</li>
+<li>ilog(7) = 3;</li>
+<li>ilog(negative number) = 0;</li>
+</ul>
+
+<h2><a name="float32_unpack">float32_unpack</a></h2>
+
+<p>"float32_unpack(x)" is intended to translate the packed binary
+representation of a Vorbis codebook float value into the
+representation used by the decoder for floating point numbers. For
+purposes of this example, we will unpack a Vorbis float32 into a
+host-native floating point number.</p>
+
+<pre>
+ 1) [mantissa] = [x] bitwise AND 0x1fffff (unsigned result)
+ 2) [sign] = [x] bitwise AND 0x80000000 (unsigned result)
+ 3) [exponent] = ( [x] bitwise AND 0x7fe00000) shifted right 21 bits (unsigned result)
+ 4) if ( [sign] is nonzero ) then negate [mantissa]
+ 5) return [mantissa] * ( 2 ^ ( [exponent] - 788 ) )
+</pre>
+
+<h2><a name="lookup1_values">lookup1_values</a></h2>
+
+<p>"lookup1_values(codebook_entries,codebook_dimensions)" is used to
+compute the correct length of the value index for a codebook VQ lookup
+table of lookup type 1. The values on this list are permuted to
+construct the VQ vector lookup table of size
+<tt>[codebook_entries]</tt>.</p>
+
+<p>The return value for this function is defined to be 'the greatest
+integer value for which <tt>[return_value] to the power of
+[codebook_dimensions] is less than or equal to
+[codebook_entries]</tt>'.</p>
+
+<h2><a name="low_neighbor">low_neighbor</a></h2>
+
+<p>"low_neighbor(v,x)" finds the position <i>n</i> in vector [v] of
+the greatest value scalar element for which <i>n</i> is less than
+<tt>[x]</tt> and <tt>vector [v] element <i>n</i> is less
+than vector [v] element [x]</tt>.</p>
+
+<h2><a name="high_neighbor">high_neighbor</a></h2>
+
+<p>"high_neighbor(v,x)" finds the position <i>n</i> in vector [v] of
+the lowest value scalar element for which <i>n</i> is less than
+<tt>[x]</tt> and <tt>vector [v] element <i>n</i> is greater
+than vector [v] element [x]</tt>.</p>
+
+<h2><a name="render_point">render_point</a></h2>
+
+<p>"render_point(x0,y0,x1,y1,X)" is used to find the Y value at point X
+along the line specified by x0, x1, y0 and y1. This function uses an
+integer algorithm to solve for the point directly without calculating
+intervening values along the line.</p>
+
+<pre>
+ 1) [dy] = [y1] - [y0]
+ 2) [adx] = [x1] - [x0]
+ 3) [ady] = absolute value of [dy]
+ 4) [err] = [ady] * ([X] - [x0])
+ 5) [off] = [err] / [adx] using integer division
+ 6) if ( [dy] is less than zero ) {
+
+ 7) [Y] = [y0] - [off]
+
+ } else {
+
+ 8) [Y] = [y0] + [off]
+
+ }
+
+ 9) done
+</pre>
+
+<h2><a name="render_line">render_line</a></h2>
+
+<p>Floor decode type one uses the integer line drawing algorithm of
+"render_line(x0, y0, x1, y1, v)" to construct an integer floor
+curve for contiguous piecewise line segments. Note that it has not
+been relevant elsewhere, but here we must define integer division as
+rounding division of both positive and negative numbers toward zero.</p>
+
+<pre>
+ 1) [dy] = [y1] - [y0]
+ 2) [adx] = [x1] - [x0]
+ 3) [ady] = absolute value of [dy]
+ 4) [base] = [dy] / [adx] using integer division
+ 5) [x] = [x0]
+ 6) [y] = [y0]
+ 7) [err] = 0
+
+ 8) if ( [dy] is less than 0 ) {
+
+ 9) [sy] = [base] - 1
+
+ } else {
+
+ 10) [sy] = [base] + 1
+
+ }
+
+ 11) [ady] = [ady] - (absolute value of [base]) * [adx]
+ 12) vector [v] element [x] = [y]
+
+ 13) iterate [x] over the range [x0]+1 ... [x1]-1 {
+
+ 14) [err] = [err] + [ady];
+ 15) if ( [err] >= [adx] ) {
+
+ 15) [err] = [err] - [adx]
+ 16) [y] = [y] + [sy]
+
+ } else {
+
+ 17) [y] = [y] + [base]
+
+ }
+
+ 18) vector [v] element [x] = [y]
+
+ }
+</pre>
+
+<div id="copyright">
+ The Xiph Fish Logo is a
+ trademark (™) of Xiph.Org.<br/>
+
+ These pages © 1994 - 2005 Xiph.Org. All rights reserved.
+</div>
+
+</body>
+</html>
Property changes on: trunk/vorbis/doc/helper.html
___________________________________________________________________
Name: svn:eol-style
+ native
Modified: trunk/vorbis/doc/index.html
===================================================================
--- trunk/vorbis/doc/index.html 2005-12-20 20:18:59 UTC (rev 10666)
+++ trunk/vorbis/doc/index.html 2005-12-21 01:19:37 UTC (rev 10667)
@@ -1,114 +1,114 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html>
-<head>
-
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
-<title>Ogg Vorbis Documentation</title>
-
-<style type="text/css">
-body {
- margin: 0 18px 0 18px;
- padding-bottom: 30px;
- font-family: Verdana, Arial, Helvetica, sans-serif;
- color: #333333;
- font-size: .8em;
-}
-
-a {
- color: #3366cc;
-}
-
-img {
- border: 0;
-}
-
-#xiphlogo {
- margin: 30px 0 16px 0;
-}
-
-#content p {
- line-height: 1.4;
-}
-
-h1, h1 a, h2, h2 a, h3, h3 a {
- font-weight: bold;
- color: #ff9900;
- margin: 1.3em 0 8px 0;
-}
-
-h1 {
- font-size: 1.3em;
-}
-
-h2 {
- font-size: 1.2em;
-}
-
-h3 {
- font-size: 1.1em;
-}
-
-li {
- line-height: 1.4;
-}
-
-#copyright {
- margin-top: 30px;
- line-height: 1.5em;
- text-align: center;
- font-size: .8em;
- color: #888888;
- clear: both;
-}
-</style>
-
-</head>
-
-<body>
-
-<div id="xiphlogo">
- <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.org"/></a>
-</div>
-
-<h1>Ogg Vorbis Documentation</h1>
-
-<h2>Vorbis technical discussion documents</h2>
-<ul>
-<li><a href="vorbis-fidelity.html">Fidelity measurement terminology</a></li>
-<li><a href="stereo.html">Vorbis channel coupling and stereo-specific application</a></li>
-</ul>
-
-<h2>Ogg Vorbis I specification</h2>
-
-<ul>
-<li>Vorbis I specification [<a href="Vorbis_I_spec.html">html</a>]
- [<a href="Vorbis_I_spec.pdf">pdf</a>]</li>
-<li><a href="v-comment.html">Vorbis comment header specification</a></li>
-<li><a href="draft-kerr-avt-vorbis-rtp-03.txt">Embedding Vorbis encoded
-audio in an RTP payload format</a></li>
-</ul>
-
-<h2>Ogg Vorbis programming documents</h2>
-
-<ul>
-<li>Programming with libvorbis</li>
-<li><a href="vorbisfile/index.html">Programming with vorbisfile</a></li>
-<li><a href="vorbisenc/index.html">Programming with vorbisenc</a></li>
-</ul>
-
-<h2>Ogg bitstream documentation</h2>
-
-<ul>
-<li><a href="oggstream.html">Ogg bitstream overview</a></li>
-<li><a href="framing.html">Ogg logical bitstream and framing spec</a></li>
-</ul>
-
-<div id="copyright">
- The Xiph Fish Logo is a
- trademark (™) of Xiph.Org.<br/>
-
- These pages © 1994 - 2005 Xiph.Org. All rights reserved.
-</div>
-
-</body>
-</html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<head>
+
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
+<title>Ogg Vorbis Documentation</title>
+
+<style type="text/css">
+body {
+ margin: 0 18px 0 18px;
+ padding-bottom: 30px;
+ font-family: Verdana, Arial, Helvetica, sans-serif;
+ color: #333333;
+ font-size: .8em;
+}
+
+a {
+ color: #3366cc;
+}
+
+img {
+ border: 0;
+}
+
+#xiphlogo {
+ margin: 30px 0 16px 0;
+}
+
+#content p {
+ line-height: 1.4;
+}
+
+h1, h1 a, h2, h2 a, h3, h3 a {
+ font-weight: bold;
+ color: #ff9900;
+ margin: 1.3em 0 8px 0;
+}
+
+h1 {
+ font-size: 1.3em;
+}
+
+h2 {
+ font-size: 1.2em;
+}
+
+h3 {
+ font-size: 1.1em;
+}
+
+li {
+ line-height: 1.4;
+}
+
+#copyright {
+ margin-top: 30px;
+ line-height: 1.5em;
+ text-align: center;
+ font-size: .8em;
+ color: #888888;
+ clear: both;
+}
+</style>
+
+</head>
+
+<body>
+
+<div id="xiphlogo">
+ <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.org"/></a>
+</div>
+
+<h1>Ogg Vorbis Documentation</h1>
+
+<h2>Vorbis technical discussion documents</h2>
+<ul>
+<li><a href="vorbis-fidelity.html">Fidelity measurement terminology</a></li>
+<li><a href="stereo.html">Vorbis channel coupling and stereo-specific application</a></li>
+</ul>
+
+<h2>Ogg Vorbis I specification</h2>
+
+<ul>
+<li>Vorbis I specification [<a href="Vorbis_I_spec.html">html</a>]
+ [<a href="Vorbis_I_spec.pdf">pdf</a>]</li>
+<li><a href="v-comment.html">Vorbis comment header specification</a></li>
+<li><a href="draft-kerr-avt-vorbis-rtp-03.txt">Embedding Vorbis encoded
+audio in an RTP payload format</a></li>
+</ul>
+
+<h2>Ogg Vorbis programming documents</h2>
+
+<ul>
+<li>Programming with libvorbis</li>
+<li><a href="vorbisfile/index.html">Programming with vorbisfile</a></li>
+<li><a href="vorbisenc/index.html">Programming with vorbisenc</a></li>
+</ul>
+
+<h2>Ogg bitstream documentation</h2>
+
+<ul>
+<li><a href="oggstream.html">Ogg bitstream overview</a></li>
+<li><a href="framing.html">Ogg logical bitstream and framing spec</a></li>
+</ul>
+
+<div id="copyright">
+ The Xiph Fish Logo is a
+ trademark (™) of Xiph.Org.<br/>
+
+ These pages © 1994 - 2005 Xiph.Org. All rights reserved.
+</div>
+
+</body>
+</html>
Property changes on: trunk/vorbis/doc/index.html
___________________________________________________________________
Name: svn:eol-style
+ native
Modified: trunk/vorbis/doc/oggstream.html
===================================================================
--- trunk/vorbis/doc/oggstream.html 2005-12-20 20:18:59 UTC (rev 10666)
+++ trunk/vorbis/doc/oggstream.html 2005-12-21 01:19:37 UTC (rev 10667)
@@ -1,234 +1,234 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html>
-<head>
-
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
-<title>Ogg Vorbis Documentation</title>
-
-<style type="text/css">
-body {
- margin: 0 18px 0 18px;
- padding-bottom: 30px;
- font-family: Verdana, Arial, Helvetica, sans-serif;
- color: #333333;
- font-size: .8em;
-}
-
-a {
- color: #3366cc;
-}
-
-img {
- border: 0;
-}
-
-#xiphlogo {
- margin: 30px 0 16px 0;
-}
-
-#content p {
- line-height: 1.4;
-}
-
-h1, h1 a, h2, h2 a, h3, h3 a {
- font-weight: bold;
- color: #ff9900;
- margin: 1.3em 0 8px 0;
-}
-
-h1 {
- font-size: 1.3em;
-}
-
-h2 {
- font-size: 1.2em;
-}
-
-h3 {
- font-size: 1.1em;
-}
-
-li {
- line-height: 1.4;
-}
-
-#copyright {
- margin-top: 30px;
- line-height: 1.5em;
- text-align: center;
- font-size: .8em;
- color: #888888;
- clear: both;
-}
-</style>
-
-</head>
-
-<body>
-
-<div id="xiphlogo">
- <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.org"/></a>
-</div>
-
-<h1>Ogg logical and physical bitstream overview</h1>
-
-<h2>Ogg bitstreams</h2>
-
-<p>Ogg codecs use octet vectors of raw, compressed data
-(<em>packets</em>). These compressed packets do not have any
-high-level structure or boundary information; strung together, they
-appear to be streams of random bytes with no landmarks.</p>
-
-<p>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 files) and transport
-(such as TCP streams or pipes), Vorbis and other future Ogg codecs use
-the Ogg bitstream format to provide framing/sync, sync recapture
-after error, landmarks during seeking, and enough information to
-properly separate data back into packets at the original packet
-boundaries without relying on decoding to find packet boundaries.</p>
-
-<h2>Logical and physical bitstreams</h2>
-
-<p>Raw packets are grouped and encoded into contiguous pages of
-structured bitstream data called <em>logical bitstreams</em>. A
-logical bitstream consists of pages, in order, belonging to a single
-codec instance. Each page is a self contained entity (although it is
-possible that a packet may be split and encoded across one or more
-pages); that is, the page decode mechanism is designed to recognize,
-verify and handle single pages at a time from the overall bitstream.</p>
-
-<p>Multiple logical bitstreams can be combined (with restrictions) into a
-single <em>physical bitstream</em>. A physical bitstream consists of
-multiple logical bitstreams multiplexed at the page level and may
-include a 'meta-header' at the beginning of the multiplexed logical
-stream that serves as identification magic. Whole pages are taken in
-order from multiple logical bitstreams and combined into a single
-physical stream of pages. The decoder reconstructs the original
-logical bitstreams from the physical bitstream by taking the pages in
-order from the physical bitstream and redirecting them into the
-appropriate logical decoding entity. The simplest physical bitstream
-is a single, unmultiplexed logical bitstream with no meta-header; this
-is referred to as a 'degenerate stream'.</p>
-
-<p><a href="framing.html">Ogg Logical Bitstream Framing</a> discusses
-the page format of an Ogg bitstream, the packet coding process
-and logical bitstreams in detail. The remainder of this document
-specifies requirements for constructing finished, physical Ogg
-bitstreams.</p>
-
-<h2>Mapping Restrictions</h2>
-
-<p>Logical bitstreams may not be mapped/multiplexed into physical
-bitstreams without restriction. Here we discuss design restrictions
-on Ogg physical bitstreams in general, mostly to introduce
-design rationale. Each 'media' format defines its own (generally more
-restrictive) mapping. An 'Ogg Vorbis Audio Bitstream', for example, has a
-specific physical bitstream structure.
-An 'Ogg A/V' bitstream (not currently specified) will also mandate a
-specific, restricted physical bitstream format.</p>
-
-<h3>additional end-to-end structure</h3>
-
-<p>The <a href="framing.html">framing specification</a> defines
-'beginning of stream' and 'end of stream' page markers via a header
-flag (it is possible for a stream to consist of a single page). A
-stream always consists of an integer number of pages, an easy
-requirement given the variable size nature of pages.</p>
-
-<p>In addition to the header flag marking the first and last pages of a
-logical bitstream, the first page of an Ogg bitstream obeys
-additional restrictions. Each individual media mapping specifies its
-own implementation details regarding these restrictions.</p>
-
-<p>The first page of a logical Ogg bitstream consists of a single,
-small 'initial header' packet that includes sufficient information to
-identify the exact CODEC type and media requirements of the logical
-bitstream. The intent of this restriction is to simplify identifying
-the bitstream type and content; for a given media type (or across all
-Ogg media types) we can know that we only need a small, fixed
-amount of data to uniquely identify the bitstream type.</p>
-
-<p>As an example, Ogg Vorbis places the name and revision of the Vorbis
-CODEC, the audio rate and the audio quality into this initial header,
-thus simplifying vastly the certain identification of an Ogg Vorbis
-audio bitstream.</p>
-
-<h3>sequential multiplexing (chaining)</h3>
-
-<p>The simplest form of logical bitstream multiplexing is concatenation
-(<em>chaining</em>). Complete logical bitstreams are strung
-one-after-another in order. The bitstreams do not overlap; the final
-page of a given logical bitstream is immediately followed by the
-initial page of the next. Chaining is the only logical->physical
-mapping allowed by Ogg Vorbis.</p>
-
-<p>Each chained logical bitstream must have a unique serial number within
-the scope of the physical bitstream.</p>
-
-<h3>concurrent multiplexing (grouping)</h3>
-
-<p>Logical bitstreams may also be multiplexed 'in parallel'
-(<em>grouped</em>). An example of grouping would be to allow
-streaming of separate audio and video streams, using different codecs
-and different logical bitstreams, in the same physical bitstream.
-Whole pages from multiple logical bitstreams are mixed together.</p>
-
-<p>The initial pages of each logical bitstream must appear first; the
-media mapping specifies the order of the initial pages. For example,
-Ogg A/V will eventually specify an Ogg video bitstream with
-audio. The mapping may specify that the physical bitstream must begin
-with the initial page of a logical video bitstream, followed by the
-initial page of an audio stream. Unlike initial pages, terminal pages
-for the logical bitstreams need not all occur contiguously (although a
-specific media mapping may require this; it is not mandated by the
-generic Ogg stream spec). Terminal pages may be 'nil' pages,
-that is, pages containing no content but simply a page header with
-position information and the 'last page of bitstream' flag set in the
-page header.</p>
-
-<p>Each grouped bitstream must have a unique serial number within the
-scope of the physical bitstream.</p>
-
-<h3>sequential and concurrent multiplexing</h3>
-
-<p>Groups of concurrently multiplexed bitstreams may be chained
-consecutively. Such a physical bitstream obeys all the rules of both
-grouped and chained multiplexed streams; the groups, when unchained ,
-must stand on their own as a valid concurrently multiplexed
-bitstream.</p>
-
-<h3>multiplexing example</h3>
-
-<p>Below, we present an example of a grouped and chained bitstream:</p>
-
-<p><img src="stream.png" alt="stream"/></p>
-
-<p>In this example, we see pages from five total logical bitstreams
-multiplexed into a physical bitstream. Note the following
-characteristics:</p>
-
-<ol>
-<li>Grouped bitstreams begin together; all of the initial pages
-must appear before any data pages. When concurrently multiplexed
-groups are chained, the new group does not begin until all the
-bitstreams in the previous group have terminated.</li>
-
-<li>The pages of concurrently multiplexed bitstreams need not conform
-to a regular order; the only requirement is that page <tt>n</tt> of a
-logical bitstream follow page <tt>n-1</tt> in the physical bitstream.
-There are no restrictions on intervening pages belonging to other
-logical bitstreams. (Tying page appearance to bitrate demands is one
-logical strategy, ie, the page appears at the chronological point
-where decode requires more information).</li>
-</ol>
-
-<div id="copyright">
- The Xiph Fish Logo is a
- trademark (™) of Xiph.Org.<br/>
-
- These pages © 1994 - 2005 Xiph.Org. All rights reserved.
-</div>
-
-</body>
-</html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<head>
+
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
+<title>Ogg Vorbis Documentation</title>
+
+<style type="text/css">
+body {
+ margin: 0 18px 0 18px;
+ padding-bottom: 30px;
+ font-family: Verdana, Arial, Helvetica, sans-serif;
+ color: #333333;
+ font-size: .8em;
+}
+
+a {
+ color: #3366cc;
+}
+
+img {
+ border: 0;
+}
+
+#xiphlogo {
+ margin: 30px 0 16px 0;
+}
+
+#content p {
+ line-height: 1.4;
+}
+
+h1, h1 a, h2, h2 a, h3, h3 a {
+ font-weight: bold;
+ color: #ff9900;
+ margin: 1.3em 0 8px 0;
+}
+
+h1 {
+ font-size: 1.3em;
+}
+
+h2 {
+ font-size: 1.2em;
+}
+
+h3 {
+ font-size: 1.1em;
+}
+
+li {
+ line-height: 1.4;
+}
+
+#copyright {
+ margin-top: 30px;
+ line-height: 1.5em;
+ text-align: center;
+ font-size: .8em;
+ color: #888888;
+ clear: both;
+}
+</style>
+
+</head>
+
+<body>
+
+<div id="xiphlogo">
+ <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.org"/></a>
+</div>
+
+<h1>Ogg logical and physical bitstream overview</h1>
+
+<h2>Ogg bitstreams</h2>
+
+<p>Ogg codecs use octet vectors of raw, compressed data
+(<em>packets</em>). These compressed packets do not have any
+high-level structure or boundary information; strung together, they
+appear to be streams of random bytes with no landmarks.</p>
+
+<p>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 files) and transport
+(such as TCP streams or pipes), Vorbis and other future Ogg codecs use
+the Ogg bitstream format to provide framing/sync, sync recapture
+after error, landmarks during seeking, and enough information to
+properly separate data back into packets at the original packet
+boundaries without relying on decoding to find packet boundaries.</p>
+
+<h2>Logical and physical bitstreams</h2>
+
+<p>Raw packets are grouped and encoded into contiguous pages of
+structured bitstream data called <em>logical bitstreams</em>. A
+logical bitstream consists of pages, in order, belonging to a single
+codec instance. Each page is a self contained entity (although it is
+possible that a packet may be split and encoded across one or more
+pages); that is, the page decode mechanism is designed to recognize,
+verify and handle single pages at a time from the overall bitstream.</p>
+
+<p>Multiple logical bitstreams can be combined (with restrictions) into a
+single <em>physical bitstream</em>. A physical bitstream consists of
+multiple logical bitstreams multiplexed at the page level and may
+include a 'meta-header' at the beginning of the multiplexed logical
+stream that serves as identification magic. Whole pages are taken in
+order from multiple logical bitstreams and combined into a single
+physical stream of pages. The decoder reconstructs the original
+logical bitstreams from the physical bitstream by taking the pages in
+order from the physical bitstream and redirecting them into the
+appropriate logical decoding entity. The simplest physical bitstream
+is a single, unmultiplexed logical bitstream with no meta-header; this
+is referred to as a 'degenerate stream'.</p>
+
+<p><a href="framing.html">Ogg Logical Bitstream Framing</a> discusses
+the page format of an Ogg bitstream, the packet coding process
+and logical bitstreams in detail. The remainder of this document
+specifies requirements for constructing finished, physical Ogg
+bitstreams.</p>
+
+<h2>Mapping Restrictions</h2>
+
+<p>Logical bitstreams may not be mapped/multiplexed into physical
+bitstreams without restriction. Here we discuss design restrictions
+on Ogg physical bitstreams in general, mostly to introduce
+design rationale. Each 'media' format defines its own (generally more
+restrictive) mapping. An 'Ogg Vorbis Audio Bitstream', for example, has a
+specific physical bitstream structure.
+An 'Ogg A/V' bitstream (not currently specified) will also mandate a
+specific, restricted physical bitstream format.</p>
+
+<h3>additional end-to-end structure</h3>
+
+<p>The <a href="framing.html">framing specification</a> defines
+'beginning of stream' and 'end of stream' page markers via a header
+flag (it is possible for a stream to consist of a single page). A
+stream always consists of an integer number of pages, an easy
+requirement given the variable size nature of pages.</p>
+
+<p>In addition to the header flag marking the first and last pages of a
+logical bitstream, the first page of an Ogg bitstream obeys
+additional restrictions. Each individual media mapping specifies its
+own implementation details regarding these restrictions.</p>
+
+<p>The first page of a logical Ogg bitstream consists of a single,
+small 'initial header' packet that includes sufficient information to
+identify the exact CODEC type and media requirements of the logical
+bitstream. The intent of this restriction is to simplify identifying
+the bitstream type and content; for a given media type (or across all
+Ogg media types) we can know that we only need a small, fixed
+amount of data to uniquely identify the bitstream type.</p>
+
+<p>As an example, Ogg Vorbis places the name and revision of the Vorbis
+CODEC, the audio rate and the audio quality into this initial header,
+thus simplifying vastly the certain identification of an Ogg Vorbis
+audio bitstream.</p>
+
+<h3>sequential multiplexing (chaining)</h3>
+
+<p>The simplest form of logical bitstream multiplexing is concatenation
+(<em>chaining</em>). Complete logical bitstreams are strung
+one-after-another in order. The bitstreams do not overlap; the final
+page of a given logical bitstream is immediately followed by the
+initial page of the next. Chaining is the only logical->physical
+mapping allowed by Ogg Vorbis.</p>
+
+<p>Each chained logical bitstream must have a unique serial number within
+the scope of the physical bitstream.</p>
+
+<h3>concurrent multiplexing (grouping)</h3>
+
+<p>Logical bitstreams may also be multiplexed 'in parallel'
+(<em>grouped</em>). An example of grouping would be to allow
+streaming of separate audio and video streams, using different codecs
+and different logical bitstreams, in the same physical bitstream.
+Whole pages from multiple logical bitstreams are mixed together.</p>
+
+<p>The initial pages of each logical bitstream must appear first; the
+media mapping specifies the order of the initial pages. For example,
+Ogg A/V will eventually specify an Ogg video bitstream with
+audio. The mapping may specify that the physical bitstream must begin
+with the initial page of a logical video bitstream, followed by the
+initial page of an audio stream. Unlike initial pages, terminal pages
+for the logical bitstreams need not all occur contiguously (although a
+specific media mapping may require this; it is not mandated by the
+generic Ogg stream spec). Terminal pages may be 'nil' pages,
+that is, pages containing no content but simply a page header with
+position information and the 'last page of bitstream' flag set in the
+page header.</p>
+
+<p>Each grouped bitstream must have a unique serial number within the
+scope of the physical bitstream.</p>
+
+<h3>sequential and concurrent multiplexing</h3>
+
+<p>Groups of concurrently multiplexed bitstreams may be chained
+consecutively. Such a physical bitstream obeys all the rules of both
+grouped and chained multiplexed streams; the groups, when unchained ,
+must stand on their own as a valid concurrently multiplexed
+bitstream.</p>
+
+<h3>multiplexing example</h3>
+
+<p>Below, we present an example of a grouped and chained bitstream:</p>
+
+<p><img src="stream.png" alt="stream"/></p>
+
+<p>In this example, we see pages from five total logical bitstreams
+multiplexed into a physical bitstream. Note the following
+characteristics:</p>
+
+<ol>
+<li>Grouped bitstreams begin together; all of the initial pages
+must appear before any data pages. When concurrently multiplexed
+groups are chained, the new group does not begin until all the
+bitstreams in the previous group have terminated.</li>
+
+<li>The pages of concurrently multiplexed bitstreams need not conform
+to a regular order; the only requirement is that page <tt>n</tt> of a
+logical bitstream follow page <tt>n-1</tt> in the physical bitstream.
+There are no restrictions on intervening pages belonging to other
+logical bitstreams. (Tying page appearance to bitrate demands is one
+logical strategy, ie, the page appears at the chronological point
+where decode requires more information).</li>
+</ol>
+
+<div id="copyright">
+ The Xiph Fish Logo is a
+ trademark (™) of Xiph.Org.<br/>
+
+ These pages © 1994 - 2005 Xiph.Org. All rights reserved.
+</div>
+
+</body>
+</html>
Property changes on: trunk/vorbis/doc/oggstream.html
___________________________________________________________________
Name: svn:eol-style
+ native
Modified: trunk/vorbis/doc/programming.html
===================================================================
--- trunk/vorbis/doc/programming.html 2005-12-20 20:18:59 UTC (rev 10666)
+++ trunk/vorbis/doc/programming.html 2005-12-21 01:19:37 UTC (rev 10667)
@@ -1,554 +1,554 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html>
-<head>
-
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
-<title>Ogg Vorbis Documentation</title>
-
-<style type="text/css">
-body {
- margin: 0 18px 0 18px;
- padding-bottom: 30px;
- font-family: Verdana, Arial, Helvetica, sans-serif;
- color: #333333;
- font-size: .8em;
-}
-
-a {
- color: #3366cc;
-}
-
-img {
- border: 0;
-}
-
-#xiphlogo {
- margin: 30px 0 16px 0;
-}
-
-#content p {
- line-height: 1.4;
-}
-
-h1, h1 a, h2, h2 a, h3, h3 a {
- font-weight: bold;
- color: #ff9900;
- margin: 1.3em 0 8px 0;
-}
-
-h1 {
- font-size: 1.3em;
-}
-
-h2 {
- font-size: 1.2em;
-}
-
-h3 {
- font-size: 1.1em;
-}
-
-li {
- line-height: 1.4;
-}
-
-#copyright {
- margin-top: 30px;
- line-height: 1.5em;
- text-align: center;
- font-size: .8em;
- color: #888888;
- clear: both;
-}
-</style>
-
-</head>
-
-<body>
-
-<div id="xiphlogo">
- <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.org"/></a>
-</div>
-
-<h1>Programming with Xiph.org <tt>libvorbis</tt></h1>
-
-<h2>Description</h2>
-
-<p>Libvorbis is the Xiph.org Foundation's portable Ogg Vorbis CODEC
-implemented as a programmatic library. Libvorbis provides primitives
-to handle framing and manipulation of Ogg bitstreams (used by the
-Vorbis for streaming), a full analysis (encoding) interface as well as
-packet decoding and synthesis for playback.</p>
-
-<p>The libvorbis library does not provide any system interface; a
-full-featured demonstration player included with the library
-distribtion provides example code for a variety of system interfaces
-as well as a working example of using libvorbis in production code.</p>
-
-<h2>Encoding Overview</h2>
-
-<h2>Decoding Overview</h2>
-
-<p>Decoding a bitstream with libvorbis follows roughly the following
-steps:</p>
-
-<ol>
-<li>Frame the incoming bitstream into pages</li>
-<li>Sort the pages by logical bitstream and buffer then into logical streams</li>
-<li>Decompose the logical streams into raw packets</li>
-<li>Reconstruct segments of the original data from each packet</li>
-<li>Glue the reconstructed segments back into a decoded stream</li>
-</ol>
-
-<h3>Framing</h3>
-
-<p>An Ogg bitstream is logically arranged into pages, but to decode
-the pages, we have to find them first. The raw bitstream is first fed
-into an <tt>ogg_sync_state</tt> buffer using <tt>ogg_sync_buffer()</tt>
-and <tt>ogg_sync_wrote()</tt>. After each block we submit to the sync
-buffer, we should check to see if we can frame and extract a complete
-page or pages using <tt>ogg_sync_pageout()</tt>. Extra pages are
-buffered; allowing them to build up in the <tt>ogg_sync_state</tt>
-buffer will eventually exhaust memory.</p>
-
-<p>The Ogg pages returned from <tt>ogg_sync_pageout</tt> need not be
-decoded further to be used as landmarks in seeking; seeking can be
-either a rough process of simply jumping to approximately intuited
-portions of the bitstream, or it can be a precise bisection process
-that captures pages and inspects data position. When seeking,
-however, sequential multiplexing (chaining) must be accounted for;
-beginning play in a new logical bitstream requires initializing a
-synthesis engine with the headers from that bitstream. Vorbis
-bitstreams do not make use of concurent multiplexing (grouping).</p>
-
-<h3>Sorting</h3>
-
-<p>The pages produced by <tt>ogg_sync_pageout</tt> are then sorted by
-serial number to seperate logical bitstreams. Initialize logical
-bitstream buffers (<tt>og_stream_state</tt>) using
-<tt>ogg_stream_init()</tt>. Pages are submitted to the matching
-logical bitstream buffer using <tt>ogg_stream_pagein</tt>; the serial
-number of the page and the stream buffer must match, or the page will
-be rejected. A page submitted out of sequence will simply be noted,
-and in the course of outputting packets, the hole will be flagged
-(<tt>ogg_sync_pageout</tt> and <tt>ogg_stream_packetout</tt> will
-return a negative value at positions where they had to recapture the
-stream).</p>
-
-<h3>Extracting packets</h3>
-
-<p>After submitting page[s] to a logical stream, read available packets
-using <tt>ogg_stream_packetout</tt>.</p>
-
-<h3>Decoding packets</h3>
-
-<h3>Reassembling data segments</h3>
-
-<h2>Ogg Bitstream Manipulation Structures</h2>
-
-<p>Two of the Ogg bitstream data structures are intended to be
-transparent to the developer; the fields should be used directly.</p>
-
-<h3>ogg_packet</h3>
-
-<pre>
-typedef struct {
- unsigned char *packet;
- long bytes;
- long b_o_s;
- long e_o_s;
-
- size64 granulepos;
-
-} ogg_packet;
-</pre>
-
-<dl>
-<dt>packet:</dt>
-<dd>a pointer to the byte data of the raw packet</dd>
-<dt>bytes:</dt>
-<dd>the size of the packet' raw data</dd>
-<dt>b_o_s:</dt>
-<dd>beginning of stream; nonzero if this is the first packet of
- the logical bitstream</dd>
-<dt>e_o_s:</dt>
-<dd>end of stream; nonzero if this is the last packet of the
- logical bitstream</dd>
-<dt>granulepos:</dt>
-<dd>the absolute position of this packet in the original
- uncompressed data stream.</dd>
-</dl>
-
-<h4>encoding notes</h4>
-
-<p>The encoder is responsible for setting all of
-the fields of the packet to appropriate values before submission to
-<tt>ogg_stream_packetin()</tt>; however, it is noted that the value in
-<tt>b_o_s</tt> is ignored; the first page produced from a given
-<tt>ogg_stream_state</tt> structure will be stamped as the initial
-page. <tt>e_o_s</tt>, however, must be set; this is the means by
-which the stream encoding primitives handle end of stream and cleanup.</p>
-
-<h4>decoding notes</h4>
-
-<p><tt>ogg_stream_packetout()</tt> sets the fields
-to appropriate values. Note that granulepos will be >= 0 only in the
-case that the given packet actually represents that position (ie, only
-the last packet completed on any page will have a meaningful
-<tt>granulepos</tt>). Intervening frames will see <tt>granulepos</tt> set
-to -1.</p>
-
-<h3>ogg_page</h3>
-
-<pre>
-typedef struct {
- unsigned char *header;
- long header_len;
- unsigned char *body;
- long body_len;
-} ogg_page;
-</pre>
-
-<dl>
-<dt>header:</dt>
-<dd>pointer to the page header data</dd>
-<dt>header_len:</dt>
-<dd>length of the page header in bytes</dd>
-<dt>body:</dt>
-<dd>pointer to the page body</dd>
-<dt>body_len:</dt>
-<dd>length of the page body</dd>
-</dl>
-
-<p>Note that although the <tt>header</tt> and <tt>body</tt> pointers do
-not necessarily point into a single contiguous page vector, the page
-body must immediately follow the header in the bitstream.</p>
-
-<h2>Ogg Bitstream Manipulation Functions</h2>
-
-<h3>
-int ogg_page_bos(ogg_page *og);
-</h3>
-
-<p>Returns the 'beginning of stream' flag for the given Ogg page. The
-beginning of stream flag is set on the initial page of a logical
-bitstream.</p>
-
-<p>Zero indicates the flag is cleared (this is not the initial page of a
-logical bitstream). Nonzero indicates the flag is set (this is the
-initial page of a logical bitstream).</p>
-
-<h3>
-int ogg_page_continued(ogg_page *og);
-</h3>
-
-<p>Returns the 'packet continued' flag for the given Ogg page. The packet
-continued flag indicates whether or not the body data of this page
-begins with packet continued from a preceeding page.</p>
-
-<p>Zero (unset) indicates that the body data begins with a new packet.
-Nonzero (set) indicates that the first packet data on the page is a
-continuation from the preceeding page.</p>
-
-<h3>
-int ogg_page_eos(ogg_page *og);
-</h3>
-
-<p>Returns the 'end of stream' flag for a give Ogg page. The end of page
-flag is set on the last (terminal) page of a logical bitstream.</p>
-
-<p>Zero (unset) indicates that this is not the last page of a logical
-bitstream. Nonzero (set) indicates that this is the last page of a
-logical bitstream and that no addiitonal pages belonging to this
-bitstream may follow.</p>
-
-<h3>
-size64 ogg_page_granulepos(ogg_page *og);
-</h3>
-
-<p>Returns the position of this page as an absolute position within the
-original uncompressed data. The position, as returned, is 'frames
-encoded to date up to and including the last whole packet on this
-page'. Partial packets begun on this page but continued to the
-following page are not included. If no packet ends on this page, the
-frame position value will be equal to the frame position value of the
-preceeding page. If none of the original uncompressed data is yet
-represented in the logical bitstream (for example, the first page of a
-bitstream consists only of a header packet; this packet encodes only
-metadata), the value shall be zero.</p>
-
-<p>The units of the framenumber are determined by media mapping. A
-vorbis audio bitstream, for example, defines one frame to be the
-channel values from a single sampling period (eg, a 16 bit stereo
-bitstream consists of two samples of two bytes for a total of four
-bytes, thus a frame would be four bytes). A video stream defines one
-frame to be a single frame of video.</p>
-
-<h3>
-int ogg_page_pageno(ogg_page *og);
-</h3>
-
-<p>Returns the sequential page number of the given Ogg page. The first
-page in a logical bitstream is numbered zero; following pages are
-numbered in increasing monotonic order.</p>
-
-<h3>
-int ogg_page_serialno(ogg_page *og);
-</h3>
-
-<p>Returns the serial number of the given Ogg page. The serial number is
-used as a handle to distinguish various logical bitstreams in a
-physical Ogg bitstresm. Every logical bitstream within a
-physical bitstream must use a unique (within the scope of the physical
-bitstream) serial number, which is stamped on all bitstream pages.</p>
-
-<h3>
-int ogg_page_version(ogg_page *og);
-</h3>
-
-<p>Returns the revision of the Ogg bitstream structure of the given page.
-Currently, the only permitted number is zero. Later revisions of the
-bitstream spec will increment this version should any changes be
-incompatable.</p>
-
-<h3>
-int ogg_stream_clear(ogg_stream_state *os);
-</h3>
-
-<p>Clears and deallocates the internal storage of the given Ogg stream.
-After clearing, the stream structure is not initialized for use;
-<tt>ogg_stream_init</tt> must be called to reinitialize for use.
-Use <tt>ogg_stream_reset</tt> to reset the stream state
-to a fresh, intiialized state.</p>
-
-<p><tt>ogg_stream_clear</tt> does not call <tt>free()</tt> on the pointer
-<tt>os</tt>, allowing use of this call on stream structures in static
-or automatic storage. <tt>ogg_stream_destroy</tt>is a complimentary
-function that frees the pointer as well.</p>
-
-<p>Returns zero on success and non-zero on failure. This function always
-succeeds.</p>
-
-<h3>
-int ogg_stream_destroy(ogg_stream_state *os);
-</h3>
-
-<p>Clears and deallocates the internal storage of the given Ogg stream,
-then frees the storage associated with the pointer <tt>os</tt>.</p>
-
-<p><tt>ogg_stream_clear</tt> does not call <tt>free()</tt> on the pointer
-<tt>os</tt>, allowing use of that call on stream structures in static
-or automatic storage.</p>
-
-<p>Returns zero on success and non-zero on failure. This function always
-succeeds.</p>
-
-<h3>
-int ogg_stream_init(ogg_stream_state *os,int serialno);
-</h3>
-
-<p>Initialize the storage associated with <tt>os</tt> for use as an Ogg
-stream. This call is used to initialize a stream for both encode and
-decode. The given serial number is the serial number that will be
-stamped on pages of the produced bitstream (during encode), or used as
-a check that pages match (during decode).</p>
-
-<p>Returns zero on success, nonzero on failure.</p>
-
-<h3>
-int ogg_stream_packetin(ogg_stream_state *os, ogg_packet *op);
-</h3>
-
-<p>Used during encoding to add the given raw packet to the given Ogg
-bitstream. The contents of <tt>op</tt> are copied;
-<tt>ogg_stream_packetin</tt> does not retain any pointers into
-<tt>op</tt>'s storage. The encoding proccess buffers incoming packets
-until enough packets have been assembled to form an entire page;
-<tt>ogg_stream_pageout</tt> is used to read complete pages.</p>
-
-<p>Returns zero on success, nonzero on failure.</p>
-
-<h3>
-int ogg_stream_packetout(ogg_stream_state *os,ogg_packet *op);
-</h3>
-
-<p>Used during decoding to read raw packets from the given logical
-bitstream. <tt>ogg_stream_packetout</tt> will only return complete
-packets for which checksumming indicates no corruption. The size and
-contents of the packet exactly match those given in the encoding
-process. </p>
-
-<p>Returns zero if the next packet is not ready to be read (not buffered
-or incomplete), positive if it returned a complete packet in
-<tt>op</tt> and negative if there is a gap, extra bytes or corruption
-at this position in the bitstream (essentially that the bitstream had
-to be recaptured). A negative value is not necessarily an error. It
-would be a common occurence when seeking, for example, which requires
-recapture of the bitstream at the position decoding continued.</p>
-
-<p>If the return value is positive, <tt>ogg_stream_packetout</tt> placed
-a packet in <tt>op</tt>. The data in <tt>op</tt> points to static
-storage that is valid until the next call to
-<tt>ogg_stream_pagein</tt>, <tt>ogg_stream_clear</tt>,
-<tt>ogg_stream_reset</tt>, or <tt>ogg_stream_destroy</tt>. The
-pointers are not invalidated by more calls to
-<tt>ogg_stream_packetout</tt>.</p>
-
-<h3>
-int ogg_stream_pagein(ogg_stream_state *os, ogg_page *og);
-</h3>
-
-<p>Used during decoding to buffer the given complete, pre-verified page
-for decoding into raw Ogg packets. The given page must be framed,
-normally produced by <tt>ogg_sync_pageout</tt>, and from the logical
-bitstream associated with <tt>os</tt> (the serial numbers must match).
-The contents of the given page are copied; <tt>ogg_stream_pagein</tt>
-retains no pointers into <tt>og</tt> storage.</p>
-
-<p>Returns zero on success and non-zero on failure.</p>
-
-<h3>
-int ogg_stream_pageout(ogg_stream_state *os, ogg_page *og);
-</h3>
-
-<p>Used during encode to read complete pages from the stream buffer. The
-returned page is ready for sending out to the real world.</p>
-
-<p>Returns zero if there is no complete page ready for reading. Returns
-nonzero when it has placed data for a complete page into
-<tt>og</tt>. Note that the storage returned in og points into internal
-storage; the pointers in <tt>og</tt> are valid until the next call to
-<tt>ogg_stream_pageout</tt>, <tt>ogg_stream_packetin</tt>,
-<tt>ogg_stream_reset</tt>, <tt>ogg_stream_clear</tt> or
-<tt>ogg_stream_destroy</tt>.</p>
-
-<h3>
-int ogg_stream_reset(ogg_stream_state *os);
-</h3>
-
-<p>Resets the given stream's state to that of a blank, unused stream;
-this may be used during encode or decode.</p>
-
-<p>Note that if used during encode, it does not alter the stream's serial
-number. In addition, the next page produced during encoding will be
-marked as the 'initial' page of the logical bitstream.</p>
-
-<p>When used during decode, this simply clears the data buffer of any
-pending pages. Beginning and end of stream cues are read from the
-bitstream and are unaffected by reset.</p>
-
-<p>Returns zero on success and non-zero on failure. This function always
-succeeds.</p>
-
-<h3>
-char *ogg_sync_buffer(ogg_sync_state *oy, long size);
-</h3>
-
-<p>This call is used to buffer a raw bitstream for framing and
-verification. <tt>ogg_sync_buffer</tt> handles stream capture and
-recapture, checksumming, and division into Ogg pages (as required by
-<tt>ogg_stream_pagein</tt>).</p>
-
-<p><tt>ogg_sync_buffer</tt> exposes a buffer area into which the decoder
-copies the next (up to) <tt>size</tt> bytes. We expose the buffer
-(rather than taking a buffer) in order to avoid an extra copy many
-uses; this way, for example, <tt>read()</tt> can transfer data
-directly into the stream buffer without first needing to place it in
-temporary storage.</p>
-
-<p>Returns a pointer into <tt>oy</tt>'s internal bitstream sync buffer;
-the remaining space in the sync buffer is at least <tt>size</tt>
-bytes. The decoder need not write all of <tt>size</tt> bytes;
-<tt>ogg_sync_wrote</tt> is used to inform the engine how many bytes
-were actually written. Use of <tt>ogg_sync_wrote</tt> after writing
-into the exposed buffer is mandantory.</p>
-
-<h3>
-int ogg_sync_clear(ogg_sync_state *oy);
-</h3>
-
-<p><tt>ogg_sync_clear</tt>
-clears and deallocates the internal storage of the given Ogg sync
-buffer. After clearing, the sync structure is not initialized for
-use; <tt>ogg_sync_init</tt> must be called to reinitialize for use.
-Use <tt>ogg_sync_reset</tt> to reset the sync state and buffer to a
-fresh, intiialized state.</p>
-
-<p><tt>ogg_sync_clear</tt> does not call <tt>free()</tt> on the pointer
-<tt>oy</tt>, allowing use of this call on sync structures in static
-or automatic storage. <tt>ogg_sync_destroy</tt>is a complimentary
-function that frees the pointer as well.</p>
-
-<p>Returns zero on success and non-zero on failure. This function always
-succeeds.</p>
-
-<h3>
-int ogg_sync_destroy(ogg_sync_state *oy);
-</h3>
-
-<p>Clears and deallocates the internal storage of the given Ogg sync
-buffer, then frees the storage associated with the pointer
-<tt>oy</tt>.</p>
-
-<p><tt>ogg_sync_clear</tt> does not call <tt>free()</tt> on the pointer
-<tt>oy</tt>, allowing use of that call on stream structures in static
-or automatic storage.</p>
-
-<p>Returns zero on success and non-zero on failure. This function always
-succeeds.</p>
-
-<h3>
-int ogg_sync_init(ogg_sync_state *oy);
-</h3>
-
-<p>Initializes the sync buffer <tt>oy</tt> for use.</p>
-
-<p>Returns zero on success and non-zero on failure. This function always
-succeeds.</p>
-
-<h3>
-int ogg_sync_pageout(ogg_sync_state *oy, ogg_page *og);
-</h3>
-
-<p>Reads complete, framed, verified Ogg pages from the sync buffer,
-placing the page data in <tt>og</tt>.</p>
-
-<p>Returns zero when there's no complete pages buffered for
-retrieval. Returns negative when a loss of sync or recapture occurred
-(this is not necessarily an error; recapture would be required after
-seeking, for example). Returns positive when a page is returned in
-<tt>og</tt>. Note that the data in <tt>og</tt> points into the sync
-buffer storage; the pointers are valid until the next call to
-<tt>ogg_sync_buffer</tt>, <tt>ogg_sync_clear</tt>,
-<tt>ogg_sync_destroy</tt> or <tt>ogg_sync_reset</tt>.</p>
-
-<h3>
-int ogg_sync_reset(ogg_sync_state *oy);
-</h3>
-
-<p><tt>ogg_sync_reset</tt> resets the sync state in <tt>oy</tt> to a
-clean, empty state. This is useful, for example, when seeking to a
-new location in a bitstream.</p>
-
-<p>Returns zero on success, nonzero on failure.</p>
-
-<h3>
-int ogg_sync_wrote(ogg_sync_state *oy, long bytes);
-</h3>
-
-<p>Used to inform the sync state as to how many bytes were actually
-written into the exposed sync buffer. It must be equal to or less
-than the size of the buffer requested.</p>
-
-<p>Returns zero on success and non-zero on failure; failure occurs only
-when the number of bytes written were larger than the buffer.</p>
-
-<div id="copyright">
- The Xiph Fish Logo is a
- trademark (™) of Xiph.Org.<br/>
-
- These pages © 1994 - 2005 Xiph.Org. All rights reserved.
-</div>
-
-</body>
-</html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<head>
+
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
+<title>Ogg Vorbis Documentation</title>
+
+<style type="text/css">
+body {
+ margin: 0 18px 0 18px;
+ padding-bottom: 30px;
+ font-family: Verdana, Arial, Helvetica, sans-serif;
+ color: #333333;
+ font-size: .8em;
+}
+
+a {
+ color: #3366cc;
+}
+
+img {
+ border: 0;
+}
+
+#xiphlogo {
+ margin: 30px 0 16px 0;
+}
+
+#content p {
+ line-height: 1.4;
+}
+
+h1, h1 a, h2, h2 a, h3, h3 a {
+ font-weight: bold;
+ color: #ff9900;
+ margin: 1.3em 0 8px 0;
+}
+
+h1 {
+ font-size: 1.3em;
+}
+
+h2 {
+ font-size: 1.2em;
+}
+
+h3 {
+ font-size: 1.1em;
+}
+
+li {
+ line-height: 1.4;
+}
+
+#copyright {
+ margin-top: 30px;
+ line-height: 1.5em;
+ text-align: center;
+ font-size: .8em;
+ color: #888888;
+ clear: both;
+}
+</style>
+
+</head>
+
+<body>
+
+<div id="xiphlogo">
+ <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.org"/></a>
+</div>
+
+<h1>Programming with Xiph.org <tt>libvorbis</tt></h1>
+
+<h2>Description</h2>
+
+<p>Libvorbis is the Xiph.org Foundation's portable Ogg Vorbis CODEC
+implemented as a programmatic library. Libvorbis provides primitives
+to handle framing and manipulation of Ogg bitstreams (used by the
+Vorbis for streaming), a full analysis (encoding) interface as well as
+packet decoding and synthesis for playback.</p>
+
+<p>The libvorbis library does not provide any system interface; a
+full-featured demonstration player included with the library
+distribtion provides example code for a variety of system interfaces
+as well as a working example of using libvorbis in production code.</p>
+
+<h2>Encoding Overview</h2>
+
+<h2>Decoding Overview</h2>
+
+<p>Decoding a bitstream with libvorbis follows roughly the following
+steps:</p>
+
+<ol>
+<li>Frame the incoming bitstream into pages</li>
+<li>Sort the pages by logical bitstream and buffer then into logical streams</li>
+<li>Decompose the logical streams into raw packets</li>
+<li>Reconstruct segments of the original data from each packet</li>
+<li>Glue the reconstructed segments back into a decoded stream</li>
+</ol>
+
+<h3>Framing</h3>
+
+<p>An Ogg bitstream is logically arranged into pages, but to decode
+the pages, we have to find them first. The raw bitstream is first fed
+into an <tt>ogg_sync_state</tt> buffer using <tt>ogg_sync_buffer()</tt>
+and <tt>ogg_sync_wrote()</tt>. After each block we submit to the sync
+buffer, we should check to see if we can frame and extract a complete
+page or pages using <tt>ogg_sync_pageout()</tt>. Extra pages are
+buffered; allowing them to build up in the <tt>ogg_sync_state</tt>
+buffer will eventually exhaust memory.</p>
+
+<p>The Ogg pages returned from <tt>ogg_sync_pageout</tt> need not be
+decoded further to be used as landmarks in seeking; seeking can be
+either a rough process of simply jumping to approximately intuited
+portions of the bitstream, or it can be a precise bisection process
+that captures pages and inspects data position. When seeking,
+however, sequential multiplexing (chaining) must be accounted for;
+beginning play in a new logical bitstream requires initializing a
+synthesis engine with the headers from that bitstream. Vorbis
+bitstreams do not make use of concurent multiplexing (grouping).</p>
+
+<h3>Sorting</h3>
+
+<p>The pages produced by <tt>ogg_sync_pageout</tt> are then sorted by
+serial number to seperate logical bitstreams. Initialize logical
+bitstream buffers (<tt>og_stream_state</tt>) using
+<tt>ogg_stream_init()</tt>. Pages are submitted to the matching
+logical bitstream buffer using <tt>ogg_stream_pagein</tt>; the serial
+number of the page and the stream buffer must match, or the page will
+be rejected. A page submitted out of sequence will simply be noted,
+and in the course of outputting packets, the hole will be flagged
+(<tt>ogg_sync_pageout</tt> and <tt>ogg_stream_packetout</tt> will
+return a negative value at positions where they had to recapture the
+stream).</p>
+
+<h3>Extracting packets</h3>
+
+<p>After submitting page[s] to a logical stream, read available packets
+using <tt>ogg_stream_packetout</tt>.</p>
+
+<h3>Decoding packets</h3>
+
+<h3>Reassembling data segments</h3>
+
+<h2>Ogg Bitstream Manipulation Structures</h2>
+
+<p>Two of the Ogg bitstream data structures are intended to be
+transparent to the developer; the fields should be used directly.</p>
+
+<h3>ogg_packet</h3>
+
+<pre>
+typedef struct {
+ unsigned char *packet;
+ long bytes;
+ long b_o_s;
+ long e_o_s;
+
+ size64 granulepos;
+
+} ogg_packet;
+</pre>
+
+<dl>
+<dt>packet:</dt>
+<dd>a pointer to the byte data of the raw packet</dd>
+<dt>bytes:</dt>
+<dd>the size of the packet' raw data</dd>
+<dt>b_o_s:</dt>
+<dd>beginning of stream; nonzero if this is the first packet of
+ the logical bitstream</dd>
+<dt>e_o_s:</dt>
+<dd>end of stream; nonzero if this is the last packet of the
+ logical bitstream</dd>
+<dt>granulepos:</dt>
+<dd>the absolute position of this packet in the original
+ uncompressed data stream.</dd>
+</dl>
+
+<h4>encoding notes</h4>
+
+<p>The encoder is responsible for setting all of
+the fields of the packet to appropriate values before submission to
+<tt>ogg_stream_packetin()</tt>; however, it is noted that the value in
+<tt>b_o_s</tt> is ignored; the first page produced from a given
+<tt>ogg_stream_state</tt> structure will be stamped as the initial
+page. <tt>e_o_s</tt>, however, must be set; this is the means by
+which the stream encoding primitives handle end of stream and cleanup.</p>
+
+<h4>decoding notes</h4>
+
+<p><tt>ogg_stream_packetout()</tt> sets the fields
+to appropriate values. Note that granulepos will be >= 0 only in the
+case that the given packet actually represents that position (ie, only
+the last packet completed on any page will have a meaningful
+<tt>granulepos</tt>). Intervening frames will see <tt>granulepos</tt> set
+to -1.</p>
+
+<h3>ogg_page</h3>
+
+<pre>
+typedef struct {
+ unsigned char *header;
+ long header_len;
+ unsigned char *body;
+ long body_len;
+} ogg_page;
+</pre>
+
+<dl>
+<dt>header:</dt>
+<dd>pointer to the page header data</dd>
+<dt>header_len:</dt>
+<dd>length of the page header in bytes</dd>
+<dt>body:</dt>
+<dd>pointer to the page body</dd>
+<dt>body_len:</dt>
+<dd>length of the page body</dd>
+</dl>
+
+<p>Note that although the <tt>header</tt> and <tt>body</tt> pointers do
+not necessarily point into a single contiguous page vector, the page
+body must immediately follow the header in the bitstream.</p>
+
+<h2>Ogg Bitstream Manipulation Functions</h2>
+
+<h3>
+int ogg_page_bos(ogg_page *og);
+</h3>
+
+<p>Returns the 'beginning of stream' flag for the given Ogg page. The
+beginning of stream flag is set on the initial page of a logical
+bitstream.</p>
+
+<p>Zero indicates the flag is cleared (this is not the initial page of a
+logical bitstream). Nonzero indicates the flag is set (this is the
+initial page of a logical bitstream).</p>
+
+<h3>
+int ogg_page_continued(ogg_page *og);
+</h3>
+
+<p>Returns the 'packet continued' flag for the given Ogg page. The packet
+continued flag indicates whether or not the body data of this page
+begins with packet continued from a preceeding page.</p>
+
+<p>Zero (unset) indicates that the body data begins with a new packet.
+Nonzero (set) indicates that the first packet data on the page is a
+continuation from the preceeding page.</p>
+
+<h3>
+int ogg_page_eos(ogg_page *og);
+</h3>
+
+<p>Returns the 'end of stream' flag for a give Ogg page. The end of page
+flag is set on the last (terminal) page of a logical bitstream.</p>
+
+<p>Zero (unset) indicates that this is not the last page of a logical
+bitstream. Nonzero (set) indicates that this is the last page of a
+logical bitstream and that no addiitonal pages belonging to this
+bitstream may follow.</p>
+
+<h3>
+size64 ogg_page_granulepos(ogg_page *og);
+</h3>
+
+<p>Returns the position of this page as an absolute position within the
+original uncompressed data. The position, as returned, is 'frames
+encoded to date up to and including the last whole packet on this
+page'. Partial packets begun on this page but continued to the
+following page are not included. If no packet ends on this page, the
+frame position value will be equal to the frame position value of the
+preceeding page. If none of the original uncompressed data is yet
+represented in the logical bitstream (for example, the first page of a
+bitstream consists only of a header packet; this packet encodes only
+metadata), the value shall be zero.</p>
+
+<p>The units of the framenumber are determined by media mapping. A
+vorbis audio bitstream, for example, defines one frame to be the
+channel values from a single sampling period (eg, a 16 bit stereo
+bitstream consists of two samples of two bytes for a total of four
+bytes, thus a frame would be four bytes). A video stream defines one
+frame to be a single frame of video.</p>
+
+<h3>
+int ogg_page_pageno(ogg_page *og);
+</h3>
+
+<p>Returns the sequential page number of the given Ogg page. The first
+page in a logical bitstream is numbered zero; following pages are
+numbered in increasing monotonic order.</p>
+
+<h3>
+int ogg_page_serialno(ogg_page *og);
+</h3>
+
+<p>Returns the serial number of the given Ogg page. The serial number is
+used as a handle to distinguish various logical bitstreams in a
+physical Ogg bitstresm. Every logical bitstream within a
+physical bitstream must use a unique (within the scope of the physical
+bitstream) serial number, which is stamped on all bitstream pages.</p>
+
+<h3>
+int ogg_page_version(ogg_page *og);
+</h3>
+
+<p>Returns the revision of the Ogg bitstream structure of the given page.
+Currently, the only permitted number is zero. Later revisions of the
+bitstream spec will increment this version should any changes be
+incompatable.</p>
+
+<h3>
+int ogg_stream_clear(ogg_stream_state *os);
+</h3>
+
+<p>Clears and deallocates the internal storage of the given Ogg stream.
+After clearing, the stream structure is not initialized for use;
+<tt>ogg_stream_init</tt> must be called to reinitialize for use.
+Use <tt>ogg_stream_reset</tt> to reset the stream state
+to a fresh, intiialized state.</p>
+
+<p><tt>ogg_stream_clear</tt> does not call <tt>free()</tt> on the pointer
+<tt>os</tt>, allowing use of this call on stream structures in static
+or automatic storage. <tt>ogg_stream_destroy</tt>is a complimentary
+function that frees the pointer as well.</p>
+
+<p>Returns zero on success and non-zero on failure. This function always
+succeeds.</p>
+
+<h3>
+int ogg_stream_destroy(ogg_stream_state *os);
+</h3>
+
+<p>Clears and deallocates the internal storage of the given Ogg stream,
+then frees the storage associated with the pointer <tt>os</tt>.</p>
+
+<p><tt>ogg_stream_clear</tt> does not call <tt>free()</tt> on the pointer
+<tt>os</tt>, allowing use of that call on stream structures in static
+or automatic storage.</p>
+
+<p>Returns zero on success and non-zero on failure. This function always
+succeeds.</p>
+
+<h3>
+int ogg_stream_init(ogg_stream_state *os,int serialno);
+</h3>
+
+<p>Initialize the storage associated with <tt>os</tt> for use as an Ogg
+stream. This call is used to initialize a stream for both encode and
+decode. The given serial number is the serial number that will be
+stamped on pages of the produced bitstream (during encode), or used as
+a check that pages match (during decode).</p>
+
+<p>Returns zero on success, nonzero on failure.</p>
+
+<h3>
+int ogg_stream_packetin(ogg_stream_state *os, ogg_packet *op);
+</h3>
+
+<p>Used during encoding to add the given raw packet to the given Ogg
+bitstream. The contents of <tt>op</tt> are copied;
+<tt>ogg_stream_packetin</tt> does not retain any pointers into
+<tt>op</tt>'s storage. The encoding proccess buffers incoming packets
+until enough packets have been assembled to form an entire page;
+<tt>ogg_stream_pageout</tt> is used to read complete pages.</p>
+
+<p>Returns zero on success, nonzero on failure.</p>
+
+<h3>
+int ogg_stream_packetout(ogg_stream_state *os,ogg_packet *op);
+</h3>
+
+<p>Used during decoding to read raw packets from the given logical
+bitstream. <tt>ogg_stream_packetout</tt> will only return complete
+packets for which checksumming indicates no corruption. The size and
+contents of the packet exactly match those given in the encoding
+process. </p>
+
+<p>Returns zero if the next packet is not ready to be read (not buffered
+or incomplete), positive if it returned a complete packet in
+<tt>op</tt> and negative if there is a gap, extra bytes or corruption
+at this position in the bitstream (essentially that the bitstream had
+to be recaptured). A negative value is not necessarily an error. It
+would be a common occurence when seeking, for example, which requires
+recapture of the bitstream at the position decoding continued.</p>
+
+<p>If the return value is positive, <tt>ogg_stream_packetout</tt> placed
+a packet in <tt>op</tt>. The data in <tt>op</tt> points to static
+storage that is valid until the next call to
+<tt>ogg_stream_pagein</tt>, <tt>ogg_stream_clear</tt>,
+<tt>ogg_stream_reset</tt>, or <tt>ogg_stream_destroy</tt>. The
+pointers are not invalidated by more calls to
+<tt>ogg_stream_packetout</tt>.</p>
+
+<h3>
+int ogg_stream_pagein(ogg_stream_state *os, ogg_page *og);
+</h3>
+
+<p>Used during decoding to buffer the given complete, pre-verified page
+for decoding into raw Ogg packets. The given page must be framed,
+normally produced by <tt>ogg_sync_pageout</tt>, and from the logical
+bitstream associated with <tt>os</tt> (the serial numbers must match).
+The contents of the given page are copied; <tt>ogg_stream_pagein</tt>
+retains no pointers into <tt>og</tt> storage.</p>
+
+<p>Returns zero on success and non-zero on failure.</p>
+
+<h3>
+int ogg_stream_pageout(ogg_stream_state *os, ogg_page *og);
+</h3>
+
+<p>Used during encode to read complete pages from the stream buffer. The
+returned page is ready for sending out to the real world.</p>
+
+<p>Returns zero if there is no complete page ready for reading. Returns
+nonzero when it has placed data for a complete page into
+<tt>og</tt>. Note that the storage returned in og points into internal
+storage; the pointers in <tt>og</tt> are valid until the next call to
+<tt>ogg_stream_pageout</tt>, <tt>ogg_stream_packetin</tt>,
+<tt>ogg_stream_reset</tt>, <tt>ogg_stream_clear</tt> or
+<tt>ogg_stream_destroy</tt>.</p>
+
+<h3>
+int ogg_stream_reset(ogg_stream_state *os);
+</h3>
+
+<p>Resets the given stream's state to that of a blank, unused stream;
+this may be used during encode or decode.</p>
+
+<p>Note that if used during encode, it does not alter the stream's serial
+number. In addition, the next page produced during encoding will be
+marked as the 'initial' page of the logical bitstream.</p>
+
+<p>When used during decode, this simply clears the data buffer of any
+pending pages. Beginning and end of stream cues are read from the
+bitstream and are unaffected by reset.</p>
+
+<p>Returns zero on success and non-zero on failure. This function always
+succeeds.</p>
+
+<h3>
+char *ogg_sync_buffer(ogg_sync_state *oy, long size);
+</h3>
+
+<p>This call is used to buffer a raw bitstream for framing and
+verification. <tt>ogg_sync_buffer</tt> handles stream capture and
+recapture, checksumming, and division into Ogg pages (as required by
+<tt>ogg_stream_pagein</tt>).</p>
+
+<p><tt>ogg_sync_buffer</tt> exposes a buffer area into which the decoder
+copies the next (up to) <tt>size</tt> bytes. We expose the buffer
+(rather than taking a buffer) in order to avoid an extra copy many
+uses; this way, for example, <tt>read()</tt> can transfer data
+directly into the stream buffer without first needing to place it in
+temporary storage.</p>
+
+<p>Returns a pointer into <tt>oy</tt>'s internal bitstream sync buffer;
+the remaining space in the sync buffer is at least <tt>size</tt>
+bytes. The decoder need not write all of <tt>size</tt> bytes;
+<tt>ogg_sync_wrote</tt> is used to inform the engine how many bytes
+were actually written. Use of <tt>ogg_sync_wrote</tt> after writing
+into the exposed buffer is mandantory.</p>
+
+<h3>
+int ogg_sync_clear(ogg_sync_state *oy);
+</h3>
+
+<p><tt>ogg_sync_clear</tt>
+clears and deallocates the internal storage of the given Ogg sync
+buffer. After clearing, the sync structure is not initialized for
+use; <tt>ogg_sync_init</tt> must be called to reinitialize for use.
+Use <tt>ogg_sync_reset</tt> to reset the sync state and buffer to a
+fresh, intiialized state.</p>
+
+<p><tt>ogg_sync_clear</tt> does not call <tt>free()</tt> on the pointer
+<tt>oy</tt>, allowing use of this call on sync structures in static
+or automatic storage. <tt>ogg_sync_destroy</tt>is a complimentary
+function that frees the pointer as well.</p>
+
+<p>Returns zero on success and non-zero on failure. This function always
+succeeds.</p>
+
+<h3>
+int ogg_sync_destroy(ogg_sync_state *oy);
+</h3>
+
+<p>Clears and deallocates the internal storage of the given Ogg sync
+buffer, then frees the storage associated with the pointer
+<tt>oy</tt>.</p>
+
+<p><tt>ogg_sync_clear</tt> does not call <tt>free()</tt> on the pointer
+<tt>oy</tt>, allowing use of that call on stream structures in static
+or automatic storage.</p>
+
+<p>Returns zero on success and non-zero on failure. This function always
+succeeds.</p>
+
+<h3>
+int ogg_sync_init(ogg_sync_state *oy);
+</h3>
+
+<p>Initializes the sync buffer <tt>oy</tt> for use.</p>
+
+<p>Returns zero on success and non-zero on failure. This function always
+succeeds.</p>
+
+<h3>
+int ogg_sync_pageout(ogg_sync_state *oy, ogg_page *og);
+</h3>
+
+<p>Reads complete, framed, verified Ogg pages from the sync buffer,
+placing the page data in <tt>og</tt>.</p>
+
+<p>Returns zero when there's no complete pages buffered for
+retrieval. Returns negative when a loss of sync or recapture occurred
+(this is not necessarily an error; recapture would be required after
+seeking, for example). Returns positive when a page is returned in
+<tt>og</tt>. Note that the data in <tt>og</tt> points into the sync
+buffer storage; the pointers are valid until the next call to
+<tt>ogg_sync_buffer</tt>, <tt>ogg_sync_clear</tt>,
+<tt>ogg_sync_destroy</tt> or <tt>ogg_sync_reset</tt>.</p>
+
+<h3>
+int ogg_sync_reset(ogg_sync_state *oy);
+</h3>
+
+<p><tt>ogg_sync_reset</tt> resets the sync state in <tt>oy</tt> to a
+clean, empty state. This is useful, for example, when seeking to a
+new location in a bitstream.</p>
+
+<p>Returns zero on success, nonzero on failure.</p>
+
+<h3>
+int ogg_sync_wrote(ogg_sync_state *oy, long bytes);
+</h3>
+
+<p>Used to inform the sync state as to how many bytes were actually
+written into the exposed sync buffer. It must be equal to or less
+than the size of the buffer requested.</p>
+
+<p>Returns zero on success and non-zero on failure; failure occurs only
+when the number of bytes written were larger than the buffer.</p>
+
+<div id="copyright">
+ The Xiph Fish Logo is a
+ trademark (™) of Xiph.Org.<br/>
+
+ These pages © 1994 - 2005 Xiph.Org. All rights reserved.
+</div>
+
+</body>
+</html>
Property changes on: trunk/vorbis/doc/programming.html
___________________________________________________________________
Name: svn:eol-style
+ native
Modified: trunk/vorbis/doc/stereo.html
===================================================================
--- trunk/vorbis/doc/stereo.html 2005-12-20 20:18:59 UTC (rev 10666)
+++ trunk/vorbis/doc/stereo.html 2005-12-21 01:19:37 UTC (rev 10667)
@@ -1,418 +1,418 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html>
-<head>
-
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
-<title>Ogg Vorbis Documentation</title>
-
-<style type="text/css">
-body {
- margin: 0 18px 0 18px;
- padding-bottom: 30px;
- font-family: Verdana, Arial, Helvetica, sans-serif;
- color: #333333;
- font-size: .8em;
-}
-
-a {
- color: #3366cc;
-}
-
-img {
- border: 0;
-}
-
-#xiphlogo {
- margin: 30px 0 16px 0;
-}
-
-#content p {
- line-height: 1.4;
-}
-
-h1, h1 a, h2, h2 a, h3, h3 a, h4, h4 a {
- font-weight: bold;
- color: #ff9900;
- margin: 1.3em 0 8px 0;
-}
-
-h1 {
- font-size: 1.3em;
-}
-
-h2 {
- font-size: 1.2em;
-}
-
-h3 {
- font-size: 1.1em;
-}
-
-li {
- line-height: 1.4;
-}
-
-#copyright {
- margin-top: 30px;
- line-height: 1.5em;
- text-align: center;
- font-size: .8em;
- color: #888888;
- clear: both;
-}
-</style>
-
-</head>
-
-<body>
-
-<div id="xiphlogo">
- <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.org"/></a>
-</div>
-
-<h1>Ogg Vorbis stereo-specific channel coupling discussion</h1>
-
-<h2>Abstract</h2>
-
-<p>The Vorbis audio CODEC provides a channel coupling
-mechanisms designed to reduce effective bitrate by both eliminating
-interchannel redundancy and eliminating stereo image information
-labeled inaudible or undesirable according to spatial psychoacoustic
-models. This document describes both the mechanical coupling
-mechanisms available within the Vorbis specification, as well as the
-specific stereo coupling models used by the reference
-<tt>libvorbis</tt> codec provided by xiph.org.</p>
-
-<h2>Mechanisms</h2>
-
-<p>In encoder release beta 4 and earlier, Vorbis supported multiple
-channel encoding, but the channels were encoded entirely separately
-with no cross-analysis or redundancy elimination between channels.
-This multichannel strategy is very similar to the mp3's <em>dual
-stereo</em> mode and Vorbis uses the same name for its analogous
-uncoupled multichannel modes.</p>
-
-<p>However, the Vorbis spec provides for, and Vorbis release 1.0 rc1 and
-later implement a coupled channel strategy. Vorbis has two specific
-mechanisms that may be used alone or in conjunction to implement
-channel coupling. The first is <em>channel interleaving</em> via
-residue backend type 2, and the second is <em>square polar
-mapping</em>. These two general mechanisms are particularly well
-suited to coupling due to the structure of Vorbis encoding, as we'll
-explore below, and using both we can implement both totally
-<em>lossless stereo image coupling</em> [bit-for-bit decode-identical
-to uncoupled modes], as well as various lossy models that seek to
-eliminate inaudible or unimportant aspects of the stereo image in
-order to enhance bitrate. The exact coupling implementation is
-generalized to allow the encoder a great deal of flexibility in
-implementation of a stereo or surround model without requiring any
-significant complexity increase over the combinatorially simpler
-mid/side joint stereo of mp3 and other current audio codecs.</p>
-
-<p>A particular Vorbis bitstream may apply channel coupling directly to
-more than a pair of channels; polar mapping is hierarchical such that
-polar coupling may be extrapolated to an arbitrary number of channels
-and is not restricted to only stereo, quadraphonics, ambisonics or 5.1
-surround. However, the scope of this document restricts itself to the
-stereo coupling case.</p>
-
-<h3>Square Polar Mapping</h3>
-
-<h4>maximal correlation</h4>
-
-<p>Recall that the basic structure of a a Vorbis I stream first generates
-from input audio a spectral 'floor' function that serves as an
-MDCT-domain whitening filter. This floor is meant to represent the
-rough envelope of the frequency spectrum, using whatever metric the
-encoder cares to define. This floor is subtracted from the log
-frequency spectrum, effectively normalizing the spectrum by frequency.
-Each input channel is associated with a unique floor function.</p>
-
-<p>The basic idea behind any stereo coupling is that the left and right
-channels usually correlate. This correlation is even stronger if one
-first accounts for energy differences in any given frequency band
-across left and right; think for example of individual instruments
-mixed into different portions of the stereo image, or a stereo
-recording with a dominant feature not perfectly in the center. The
-floor functions, each specific to a channel, provide the perfect means
-of normalizing left and right energies across the spectrum to maximize
-correlation before coupling. This feature of the Vorbis format is not
-a convenient accident.</p>
-
-<p>Because we strive to maximally correlate the left and right channels
-and generally succeed in doing so, left and right residue is typically
-nearly identical. We could use channel interleaving (discussed below)
-alone to efficiently remove the redundancy between the left and right
-channels as a side effect of entropy encoding, but a polar
-representation gives benefits when left/right correlation is
-strong.</p>
-
-<h4>point and diffuse imaging</h4>
-
-<p>The first advantage of a polar representation is that it effectively
-separates the spatial audio information into a 'point image'
-(magnitude) at a given frequency and located somewhere in the sound
-field, and a 'diffuse image' (angle) that fills a large amount of
-space simultaneously. Even if we preserve only the magnitude (point)
-data, a detailed and carefully chosen floor function in each channel
-provides us with a free, fine-grained, frequency relative intensity
-stereo*. Angle information represents diffuse sound fields, such as
-reverberation that fills the entire space simultaneously.</p>
-
-<p>*<em>Because the Vorbis model supports a number of different possible
-stereo models and these models may be mixed, we do not use the term
-'intensity stereo' talking about Vorbis; instead we use the terms
-'point stereo', 'phase stereo' and subcategories of each.</em></p>
-
-<p>The majority of a stereo image is representable by polar magnitude
-alone, as strong sounds tend to be produced at near-point sources;
-even non-diffuse, fast, sharp echoes track very accurately using
-magnitude representation almost alone (for those experimenting with
-Vorbis tuning, this strategy works much better with the precise,
-piecewise control of floor 1; the continuous approximation of floor 0
-results in unstable imaging). Reverberation and diffuse sounds tend
-to contain less energy and be psychoacoustically dominated by the
-point sources embedded in them. Thus, we again tend to concentrate
-more represented energy into a predictably smaller number of numbers.
-Separating representation of point and diffuse imaging also allows us
-to model and manipulate point and diffuse qualities separately.</p>
-
-<h4>controlling bit leakage and symbol crosstalk</h4>
-
-<p>Because polar
-representation concentrates represented energy into fewer large
-values, we reduce bit 'leakage' during cascading (multistage VQ
-encoding) as a secondary benefit. A single large, monolithic VQ
-codebook is more efficient than a cascaded book due to entropy
-'crosstalk' among symbols between different stages of a multistage cascade.
-Polar representation is a way of further concentrating entropy into
-predictable locations so that codebook design can take steps to
-improve multistage codebook efficiency. It also allows us to cascade
-various elements of the stereo image independently.</p>
-
-<h4>eliminating trigonometry and rounding</h4>
-
-<p>Rounding and computational complexity are potential problems with a
-polar representation. As our encoding process involves quantization,
-mixing a polar representation and quantization makes it potentially
-impossible, depending on implementation, to construct a coupled stereo
-mechanism that results in bit-identical decompressed output compared
-to an uncoupled encoding should the encoder desire it.</p>
-
-<p>Vorbis uses a mapping that preserves the most useful qualities of
-polar representation, relies only on addition/subtraction (during
-decode; high quality encoding still requires some trig), and makes it
-trivial before or after quantization to represent an angle/magnitude
-through a one-to-one mapping from possible left/right value
-permutations. We do this by basing our polar representation on the
-unit square rather than the unit-circle.</p>
-
-<p>Given a magnitude and angle, we recover left and right using the
-following function (note that A/B may be left/right or right/left
-depending on the coupling definition used by the encoder):</p>
-
-<pre>
- if(magnitude>0)
- if(angle>0){
- A=magnitude;
- B=magnitude-angle;
- }else{
- B=magnitude;
- A=magnitude+angle;
- }
- else
- if(angle>0){
- A=magnitude;
- B=magnitude+angle;
- }else{
- B=magnitude;
- A=magnitude-angle;
- }
- }
-</pre>
-
-<p>The function is antisymmetric for positive and negative magnitudes in
-order to eliminate a redundant value when quantizing. For example, if
-we're quantizing to integer values, we can visualize a magnitude of 5
-and an angle of -2 as follows:</p>
-
-<p><img src="squarepolar.png" alt="square polar"/></p>
-
-<p>This representation loses or replicates no values; if the range of A
-and B are integral -5 through 5, the number of possible Cartesian
-permutations is 121. Represented in square polar notation, the
-possible values are:</p>
-
-<pre>
- 0, 0
-
--1,-2 -1,-1 -1, 0 -1, 1
-
- 1,-2 1,-1 1, 0 1, 1
-
--2,-4 -2,-3 -2,-2 -2,-1 -2, 0 -2, 1 -2, 2 -2, 3
-
- 2,-4 2,-3 ... following the pattern ...
-
- ... 5, 1 5, 2 5, 3 5, 4 5, 5 5, 6 5, 7 5, 8 5, 9
-
-</pre>
-
-<p>...for a grand total of 121 possible values, the same number as in
-Cartesian representation (note that, for example, <tt>5,-10</tt> is
-the same as <tt>-5,10</tt>, so there's no reason to represent
-both. 2,10 cannot happen, and there's no reason to account for it.)
-It's also obvious that this mapping is exactly reversible.</p>
-
-<h3>Channel interleaving</h3>
-
-<p>We can remap and A/B vector using polar mapping into a magnitude/angle
-vector, and it's clear that, in general, this concentrates energy in
-the magnitude vector and reduces the amount of information to encode
-in the angle vector. Encoding these vectors independently with
-residue backend #0 or residue backend #1 will result in bitrate
-savings. However, there are still implicit correlations between the
-magnitude and angle vectors. The most obvious is that the amplitude
-of the angle is bounded by its corresponding magnitude value.</p>
-
-<p>Entropy coding the results, then, further benefits from the entropy
-model being able to compress magnitude and angle simultaneously. For
-this reason, Vorbis implements residue backend #2 which pre-interleaves
-a number of input vectors (in the stereo case, two, A and B) into a
-single output vector (with the elements in the order of
-A_0, B_0, A_1, B_1, A_2 ... A_n-1, B_n-1) before entropy encoding. Thus
-each vector to be coded by the vector quantization backend consists of
-matching magnitude and angle values.</p>
-
-<p>The astute reader, at this point, will notice that in the theoretical
-case in which we can use monolithic codebooks of arbitrarily large
-size, we can directly interleave and encode left and right without
-polar mapping; in fact, the polar mapping does not appear to lend any
-benefit whatsoever to the efficiency of the entropy coding. In fact,
-it is perfectly possible and reasonable to build a Vorbis encoder that
-dispenses with polar mapping entirely and merely interleaves the
-channel. Libvorbis based encoders may configure such an encoding and
-it will work as intended.</p>
-
-<p>However, when we leave the ideal/theoretical domain, we notice that
-polar mapping does give additional practical benefits, as discussed in
-the above section on polar mapping and summarized again here:</p>
-
-<ul>
-<li>Polar mapping aids in controlling entropy 'leakage' between stages
-of a cascaded codebook.</li>
-<li>Polar mapping separates the stereo image
-into point and diffuse components which may be analyzed and handled
-differently.</li>
-</ul>
-
-<h2>Stereo Models</h2>
-
-<h3>Dual Stereo</h3>
-
-<p>Dual stereo refers to stereo encoding where the channels are entirely
-separate; they are analyzed and encoded as entirely distinct entities.
-This terminology is familiar from mp3.</p>
-
-<h3>Lossless Stereo</h3>
-
-<p>Using polar mapping and/or channel interleaving, it's possible to
-couple Vorbis channels losslessly, that is, construct a stereo
-coupling encoding that both saves space but also decodes
-bit-identically to dual stereo. OggEnc 1.0 and later uses this
-mode in all high-bitrate encoding.</p>
-
-<p>Overall, this stereo mode is overkill; however, it offers a safe
-alternative to users concerned about the slightest possible
-degradation to the stereo image or archival quality audio.</p>
-
-<h3>Phase Stereo</h3>
-
-<p>Phase stereo is the least aggressive means of gracefully dropping
-resolution from the stereo image; it affects only diffuse imaging.</p>
-
-<p>It's often quoted that the human ear is deaf to signal phase above
-about 4kHz; this is nearly true and a passable rule of thumb, but it
-can be demonstrated that even an average user can tell the difference
-between high frequency in-phase and out-of-phase noise. Obviously
-then, the statement is not entirely true. However, it's also the case
-that one must resort to nearly such an extreme demonstration before
-finding the counterexample.</p>
-
-<p>'Phase stereo' is simply a more aggressive quantization of the polar
-angle vector; above 4kHz it's generally quite safe to quantize noise
-and noisy elements to only a handful of allowed phases, or to thin the
-phase with respect to the magnitude. The phases of high amplitude
-pure tones may or may not be preserved more carefully (they are
-relatively rare and L/R tend to be in phase, so there is generally
-little reason not to spend a few more bits on them)</p>
-
-<h4>example: eight phase stereo</h4>
-
-<p>Vorbis may implement phase stereo coupling by preserving the entirety
-of the magnitude vector (essential to fine amplitude and energy
-resolution overall) and quantizing the angle vector to one of only
-four possible values. Given that the magnitude vector may be positive
-or negative, this results in left and right phase having eight
-possible permutation, thus 'eight phase stereo':</p>
-
-<p><img src="eightphase.png" alt="eight phase"/></p>
-
-<p>Left and right may be in phase (positive or negative), the most common
-case by far, or out of phase by 90 or 180 degrees.</p>
-
-<h4>example: four phase stereo</h4>
-
-<p>Similarly, four phase stereo takes the quantization one step further;
-it allows only in-phase and 180 degree out-out-phase signals:</p>
-
-<p><img src="fourphase.png" alt="four phase"/></p>
-
-<h3>example: point stereo</h3>
-
-<p>Point stereo eliminates the possibility of out-of-phase signal
-entirely. Any diffuse quality to a sound source tends to collapse
-inward to a point somewhere within the stereo image. A practical
-example would be balanced reverberations within a large, live space;
-normally the sound is diffuse and soft, giving a sonic impression of
-volume. In point-stereo, the reverberations would still exist, but
-sound fairly firmly centered within the image (assuming the
-reverberation was centered overall; if the reverberation is stronger
-to the left, then the point of localization in point stereo would be
-to the left). This effect is most noticeable at low and mid
-frequencies and using headphones (which grant perfect stereo
-separation). Point stereo is is a graceful but generally easy to
-detect degradation to the sound quality and is thus used in frequency
-ranges where it is least noticeable.</p>
-
-<h3>Mixed Stereo</h3>
-
-<p>Mixed stereo is the simultaneous use of more than one of the above
-stereo encoding models, generally using more aggressive modes in
-higher frequencies, lower amplitudes or 'nearly' in-phase sound.</p>
-
-<p>It is also the case that near-DC frequencies should be encoded using
-lossless coupling to avoid frame blocking artifacts.</p>
-
-<h3>Vorbis Stereo Modes</h3>
-
-<p>Vorbis, as of 1.0, uses lossless stereo and a number of mixed modes
-constructed out of lossless and point stereo. Phase stereo was used
-in the rc2 encoder, but is not currently used for simplicity's sake. It
-will likely be re-added to the stereo model in the future.</p>
-
-<div id="copyright">
- The Xiph Fish Logo is a
- trademark (™) of Xiph.Org.<br/>
-
- These pages © 1994 - 2005 Xiph.Org. All rights reserved.
-</div>
-
-</body>
-</html>
-
-
-
-
-
-
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<head>
+
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
+<title>Ogg Vorbis Documentation</title>
+
+<style type="text/css">
+body {
+ margin: 0 18px 0 18px;
+ padding-bottom: 30px;
+ font-family: Verdana, Arial, Helvetica, sans-serif;
+ color: #333333;
+ font-size: .8em;
+}
+
+a {
+ color: #3366cc;
+}
+
+img {
+ border: 0;
+}
+
+#xiphlogo {
+ margin: 30px 0 16px 0;
+}
+
+#content p {
+ line-height: 1.4;
+}
+
+h1, h1 a, h2, h2 a, h3, h3 a, h4, h4 a {
+ font-weight: bold;
+ color: #ff9900;
+ margin: 1.3em 0 8px 0;
+}
+
+h1 {
+ font-size: 1.3em;
+}
+
+h2 {
+ font-size: 1.2em;
+}
+
+h3 {
+ font-size: 1.1em;
+}
+
+li {
+ line-height: 1.4;
+}
+
+#copyright {
+ margin-top: 30px;
+ line-height: 1.5em;
+ text-align: center;
+ font-size: .8em;
+ color: #888888;
+ clear: both;
+}
+</style>
+
+</head>
+
+<body>
+
+<div id="xiphlogo">
+ <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.org"/></a>
+</div>
+
+<h1>Ogg Vorbis stereo-specific channel coupling discussion</h1>
+
+<h2>Abstract</h2>
+
+<p>The Vorbis audio CODEC provides a channel coupling
+mechanisms designed to reduce effective bitrate by both eliminating
+interchannel redundancy and eliminating stereo image information
+labeled inaudible or undesirable according to spatial psychoacoustic
+models. This document describes both the mechanical coupling
+mechanisms available within the Vorbis specification, as well as the
+specific stereo coupling models used by the reference
+<tt>libvorbis</tt> codec provided by xiph.org.</p>
+
+<h2>Mechanisms</h2>
+
+<p>In encoder release beta 4 and earlier, Vorbis supported multiple
+channel encoding, but the channels were encoded entirely separately
+with no cross-analysis or redundancy elimination between channels.
+This multichannel strategy is very similar to the mp3's <em>dual
+stereo</em> mode and Vorbis uses the same name for its analogous
+uncoupled multichannel modes.</p>
+
+<p>However, the Vorbis spec provides for, and Vorbis release 1.0 rc1 and
+later implement a coupled channel strategy. Vorbis has two specific
+mechanisms that may be used alone or in conjunction to implement
+channel coupling. The first is <em>channel interleaving</em> via
+residue backend type 2, and the second is <em>square polar
+mapping</em>. These two general mechanisms are particularly well
+suited to coupling due to the structure of Vorbis encoding, as we'll
+explore below, and using both we can implement both totally
+<em>lossless stereo image coupling</em> [bit-for-bit decode-identical
+to uncoupled modes], as well as various lossy models that seek to
+eliminate inaudible or unimportant aspects of the stereo image in
+order to enhance bitrate. The exact coupling implementation is
+generalized to allow the encoder a great deal of flexibility in
+implementation of a stereo or surround model without requiring any
+significant complexity increase over the combinatorially simpler
+mid/side joint stereo of mp3 and other current audio codecs.</p>
+
+<p>A particular Vorbis bitstream may apply channel coupling directly to
+more than a pair of channels; polar mapping is hierarchical such that
+polar coupling may be extrapolated to an arbitrary number of channels
+and is not restricted to only stereo, quadraphonics, ambisonics or 5.1
+surround. However, the scope of this document restricts itself to the
+stereo coupling case.</p>
+
+<h3>Square Polar Mapping</h3>
+
+<h4>maximal correlation</h4>
+
+<p>Recall that the basic structure of a a Vorbis I stream first generates
+from input audio a spectral 'floor' function that serves as an
+MDCT-domain whitening filter. This floor is meant to represent the
+rough envelope of the frequency spectrum, using whatever metric the
+encoder cares to define. This floor is subtracted from the log
+frequency spectrum, effectively normalizing the spectrum by frequency.
+Each input channel is associated with a unique floor function.</p>
+
+<p>The basic idea behind any stereo coupling is that the left and right
+channels usually correlate. This correlation is even stronger if one
+first accounts for energy differences in any given frequency band
+across left and right; think for example of individual instruments
+mixed into different portions of the stereo image, or a stereo
+recording with a dominant feature not perfectly in the center. The
+floor functions, each specific to a channel, provide the perfect means
+of normalizing left and right energies across the spectrum to maximize
+correlation before coupling. This feature of the Vorbis format is not
+a convenient accident.</p>
+
+<p>Because we strive to maximally correlate the left and right channels
+and generally succeed in doing so, left and right residue is typically
+nearly identical. We could use channel interleaving (discussed below)
+alone to efficiently remove the redundancy between the left and right
+channels as a side effect of entropy encoding, but a polar
+representation gives benefits when left/right correlation is
+strong.</p>
+
+<h4>point and diffuse imaging</h4>
+
+<p>The first advantage of a polar representation is that it effectively
+separates the spatial audio information into a 'point image'
+(magnitude) at a given frequency and located somewhere in the sound
+field, and a 'diffuse image' (angle) that fills a large amount of
+space simultaneously. Even if we preserve only the magnitude (point)
+data, a detailed and carefully chosen floor function in each channel
+provides us with a free, fine-grained, frequency relative intensity
+stereo*. Angle information represents diffuse sound fields, such as
+reverberation that fills the entire space simultaneously.</p>
+
+<p>*<em>Because the Vorbis model supports a number of different possible
+stereo models and these models may be mixed, we do not use the term
+'intensity stereo' talking about Vorbis; instead we use the terms
+'point stereo', 'phase stereo' and subcategories of each.</em></p>
+
+<p>The majority of a stereo image is representable by polar magnitude
+alone, as strong sounds tend to be produced at near-point sources;
+even non-diffuse, fast, sharp echoes track very accurately using
+magnitude representation almost alone (for those experimenting with
+Vorbis tuning, this strategy works much better with the precise,
+piecewise control of floor 1; the continuous approximation of floor 0
+results in unstable imaging). Reverberation and diffuse sounds tend
+to contain less energy and be psychoacoustically dominated by the
+point sources embedded in them. Thus, we again tend to concentrate
+more represented energy into a predictably smaller number of numbers.
+Separating representation of point and diffuse imaging also allows us
+to model and manipulate point and diffuse qualities separately.</p>
+
+<h4>controlling bit leakage and symbol crosstalk</h4>
+
+<p>Because polar
+representation concentrates represented energy into fewer large
+values, we reduce bit 'leakage' during cascading (multistage VQ
+encoding) as a secondary benefit. A single large, monolithic VQ
+codebook is more efficient than a cascaded book due to entropy
+'crosstalk' among symbols between different stages of a multistage cascade.
+Polar representation is a way of further concentrating entropy into
+predictable locations so that codebook design can take steps to
+improve multistage codebook efficiency. It also allows us to cascade
+various elements of the stereo image independently.</p>
+
+<h4>eliminating trigonometry and rounding</h4>
+
+<p>Rounding and computational complexity are potential problems with a
+polar representation. As our encoding process involves quantization,
+mixing a polar representation and quantization makes it potentially
+impossible, depending on implementation, to construct a coupled stereo
+mechanism that results in bit-identical decompressed output compared
+to an uncoupled encoding should the encoder desire it.</p>
+
+<p>Vorbis uses a mapping that preserves the most useful qualities of
+polar representation, relies only on addition/subtraction (during
+decode; high quality encoding still requires some trig), and makes it
+trivial before or after quantization to represent an angle/magnitude
+through a one-to-one mapping from possible left/right value
+permutations. We do this by basing our polar representation on the
+unit square rather than the unit-circle.</p>
+
+<p>Given a magnitude and angle, we recover left and right using the
+following function (note that A/B may be left/right or right/left
+depending on the coupling definition used by the encoder):</p>
+
+<pre>
+ if(magnitude>0)
+ if(angle>0){
+ A=magnitude;
+ B=magnitude-angle;
+ }else{
+ B=magnitude;
+ A=magnitude+angle;
+ }
+ else
+ if(angle>0){
+ A=magnitude;
+ B=magnitude+angle;
+ }else{
+ B=magnitude;
+ A=magnitude-angle;
+ }
+ }
+</pre>
+
+<p>The function is antisymmetric for positive and negative magnitudes in
+order to eliminate a redundant value when quantizing. For example, if
+we're quantizing to integer values, we can visualize a magnitude of 5
+and an angle of -2 as follows:</p>
+
+<p><img src="squarepolar.png" alt="square polar"/></p>
+
+<p>This representation loses or replicates no values; if the range of A
+and B are integral -5 through 5, the number of possible Cartesian
+permutations is 121. Represented in square polar notation, the
+possible values are:</p>
+
+<pre>
+ 0, 0
+
+-1,-2 -1,-1 -1, 0 -1, 1
+
+ 1,-2 1,-1 1, 0 1, 1
+
+-2,-4 -2,-3 -2,-2 -2,-1 -2, 0 -2, 1 -2, 2 -2, 3
+
+ 2,-4 2,-3 ... following the pattern ...
+
+ ... 5, 1 5, 2 5, 3 5, 4 5, 5 5, 6 5, 7 5, 8 5, 9
+
+</pre>
+
+<p>...for a grand total of 121 possible values, the same number as in
+Cartesian representation (note that, for example, <tt>5,-10</tt> is
+the same as <tt>-5,10</tt>, so there's no reason to represent
+both. 2,10 cannot happen, and there's no reason to account for it.)
+It's also obvious that this mapping is exactly reversible.</p>
+
+<h3>Channel interleaving</h3>
+
+<p>We can remap and A/B vector using polar mapping into a magnitude/angle
+vector, and it's clear that, in general, this concentrates energy in
+the magnitude vector and reduces the amount of information to encode
+in the angle vector. Encoding these vectors independently with
+residue backend #0 or residue backend #1 will result in bitrate
+savings. However, there are still implicit correlations between the
+magnitude and angle vectors. The most obvious is that the amplitude
+of the angle is bounded by its corresponding magnitude value.</p>
+
+<p>Entropy coding the results, then, further benefits from the entropy
+model being able to compress magnitude and angle simultaneously. For
+this reason, Vorbis implements residue backend #2 which pre-interleaves
+a number of input vectors (in the stereo case, two, A and B) into a
+single output vector (with the elements in the order of
+A_0, B_0, A_1, B_1, A_2 ... A_n-1, B_n-1) before entropy encoding. Thus
+each vector to be coded by the vector quantization backend consists of
+matching magnitude and angle values.</p>
+
+<p>The astute reader, at this point, will notice that in the theoretical
+case in which we can use monolithic codebooks of arbitrarily large
+size, we can directly interleave and encode left and right without
+polar mapping; in fact, the polar mapping does not appear to lend any
+benefit whatsoever to the efficiency of the entropy coding. In fact,
+it is perfectly possible and reasonable to build a Vorbis encoder that
+dispenses with polar mapping entirely and merely interleaves the
+channel. Libvorbis based encoders may configure such an encoding and
+it will work as intended.</p>
+
+<p>However, when we leave the ideal/theoretical domain, we notice that
+polar mapping does give additional practical benefits, as discussed in
+the above section on polar mapping and summarized again here:</p>
+
+<ul>
+<li>Polar mapping aids in controlling entropy 'leakage' between stages
+of a cascaded codebook.</li>
+<li>Polar mapping separates the stereo image
+into point and diffuse components which may be analyzed and handled
+differently.</li>
+</ul>
+
+<h2>Stereo Models</h2>
+
+<h3>Dual Stereo</h3>
+
+<p>Dual stereo refers to stereo encoding where the channels are entirely
+separate; they are analyzed and encoded as entirely distinct entities.
+This terminology is familiar from mp3.</p>
+
+<h3>Lossless Stereo</h3>
+
+<p>Using polar mapping and/or channel interleaving, it's possible to
+couple Vorbis channels losslessly, that is, construct a stereo
+coupling encoding that both saves space but also decodes
+bit-identically to dual stereo. OggEnc 1.0 and later uses this
+mode in all high-bitrate encoding.</p>
+
+<p>Overall, this stereo mode is overkill; however, it offers a safe
+alternative to users concerned about the slightest possible
+degradation to the stereo image or archival quality audio.</p>
+
+<h3>Phase Stereo</h3>
+
+<p>Phase stereo is the least aggressive means of gracefully dropping
+resolution from the stereo image; it affects only diffuse imaging.</p>
+
+<p>It's often quoted that the human ear is deaf to signal phase above
+about 4kHz; this is nearly true and a passable rule of thumb, but it
+can be demonstrated that even an average user can tell the difference
+between high frequency in-phase and out-of-phase noise. Obviously
+then, the statement is not entirely true. However, it's also the case
+that one must resort to nearly such an extreme demonstration before
+finding the counterexample.</p>
+
+<p>'Phase stereo' is simply a more aggressive quantization of the polar
+angle vector; above 4kHz it's generally quite safe to quantize noise
+and noisy elements to only a handful of allowed phases, or to thin the
+phase with respect to the magnitude. The phases of high amplitude
+pure tones may or may not be preserved more carefully (they are
+relatively rare and L/R tend to be in phase, so there is generally
+little reason not to spend a few more bits on them)</p>
+
+<h4>example: eight phase stereo</h4>
+
+<p>Vorbis may implement phase stereo coupling by preserving the entirety
+of the magnitude vector (essential to fine amplitude and energy
+resolution overall) and quantizing the angle vector to one of only
+four possible values. Given that the magnitude vector may be positive
+or negative, this results in left and right phase having eight
+possible permutation, thus 'eight phase stereo':</p>
+
+<p><img src="eightphase.png" alt="eight phase"/></p>
+
+<p>Left and right may be in phase (positive or negative), the most common
+case by far, or out of phase by 90 or 180 degrees.</p>
+
+<h4>example: four phase stereo</h4>
+
+<p>Similarly, four phase stereo takes the quantization one step further;
+it allows only in-phase and 180 degree out-out-phase signals:</p>
+
+<p><img src="fourphase.png" alt="four phase"/></p>
+
+<h3>example: point stereo</h3>
+
+<p>Point stereo eliminates the possibility of out-of-phase signal
+entirely. Any diffuse quality to a sound source tends to collapse
+inward to a point somewhere within the stereo image. A practical
+example would be balanced reverberations within a large, live space;
+normally the sound is diffuse and soft, giving a sonic impression of
+volume. In point-stereo, the reverberations would still exist, but
+sound fairly firmly centered within the image (assuming the
+reverberation was centered overall; if the reverberation is stronger
+to the left, then the point of localization in point stereo would be
+to the left). This effect is most noticeable at low and mid
+frequencies and using headphones (which grant perfect stereo
+separation). Point stereo is is a graceful but generally easy to
+detect degradation to the sound quality and is thus used in frequency
+ranges where it is least noticeable.</p>
+
+<h3>Mixed Stereo</h3>
+
+<p>Mixed stereo is the simultaneous use of more than one of the above
+stereo encoding models, generally using more aggressive modes in
+higher frequencies, lower amplitudes or 'nearly' in-phase sound.</p>
+
+<p>It is also the case that near-DC frequencies should be encoded using
+lossless coupling to avoid frame blocking artifacts.</p>
+
+<h3>Vorbis Stereo Modes</h3>
+
+<p>Vorbis, as of 1.0, uses lossless stereo and a number of mixed modes
+constructed out of lossless and point stereo. Phase stereo was used
+in the rc2 encoder, but is not currently used for simplicity's sake. It
+will likely be re-added to the stereo model in the future.</p>
+
+<div id="copyright">
+ The Xiph Fish Logo is a
+ trademark (™) of Xiph.Org.<br/>
+
+ These pages © 1994 - 2005 Xiph.Org. All rights reserved.
+</div>
+
+</body>
+</html>
+
+
+
+
+
+
Property changes on: trunk/vorbis/doc/stereo.html
___________________________________________________________________
Name: svn:eol-style
+ native
Modified: trunk/vorbis/doc/v-comment.html
===================================================================
--- trunk/vorbis/doc/v-comment.html 2005-12-20 20:18:59 UTC (rev 10666)
+++ trunk/vorbis/doc/v-comment.html 2005-12-21 01:19:37 UTC (rev 10667)
@@ -1,285 +1,285 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html>
-<head>
-
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
-<title>Ogg Vorbis Documentation</title>
-
-<style type="text/css">
-body {
- margin: 0 18px 0 18px;
- padding-bottom: 30px;
- font-family: Verdana, Arial, Helvetica, sans-serif;
- color: #333333;
- font-size: .8em;
-}
-
-a {
- color: #3366cc;
-}
-
-img {
- border: 0;
-}
-
-#xiphlogo {
- margin: 30px 0 16px 0;
-}
-
-#content p {
- line-height: 1.4;
-}
-
-h1, h1 a, h2, h2 a, h3, h3 a {
- font-weight: bold;
- color: #ff9900;
- margin: 1.3em 0 8px 0;
-}
-
-h1 {
- font-size: 1.3em;
-}
-
-h2 {
- font-size: 1.2em;
-}
-
-h3 {
- font-size: 1.1em;
-}
-
-li {
- line-height: 1.4;
-}
-
-#copyright {
- margin-top: 30px;
- line-height: 1.5em;
- text-align: center;
- font-size: .8em;
- color: #888888;
- clear: both;
-}
-</style>
-
-</head>
-
-<body>
-
-<div id="xiphlogo">
- <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.org"/></a>
-</div>
-
-<h1>Ogg Vorbis I format specification: comment field and header specification</h1>
-
-<h1>Overview</h1>
-
-<p>The Vorbis text comment header is the second (of three) header
-packets that begin a Vorbis bitstream. It is meant for short, text
-comments, not arbitrary metadata; arbitrary metadata belongs in a
-separate logical bitstream (usually an XML stream type) that provides
-greater structure and machine parseability.</p>
-
-<p>The comment field is meant to be used much like someone jotting a
-quick note on the bottom of a CDR. It should be a little information to
-remember the disc by and explain it to others; a short, to-the-point
-text note that need not only be a couple words, but isn't going to be
-more than a short paragraph. The essentials, in other words, whatever
-they turn out to be, eg:</p>
-
-<blockquote><p>
-"Honest Bob and the Factory-to-Dealer-Incentives, _I'm Still Around_,
-opening for Moxy Früvous, 1997"
-</p></blockquote>
-
-<h1>Comment encoding</h1>
-
-<h2>Structure</h2>
-
-<p>The comment header logically is a list of eight-bit-clean vectors; the
-number of vectors is bounded to 2^32-1 and the length of each vector
-is limited to 2^32-1 bytes. The vector length is encoded; the vector
-contents themselves are not null terminated. In addition to the vector
-list, there is a single vector for vendor name (also 8 bit clean,
-length encoded in 32 bits). For example, the 1.0 release of libvorbis
-set the vendor string to "Xiph.Org libVorbis I 20020717".</p>
-
-<p>The comment header is decoded as follows:</p>
-
-<pre>
- 1) [vendor_length] = read an unsigned integer of 32 bits
- 2) [vendor_string] = read a UTF-8 vector as [vendor_length] octets
- 3) [user_comment_list_length] = read an unsigned integer of 32 bits
- 4) iterate [user_comment_list_length] times {
-
- 5) [length] = read an unsigned integer of 32 bits
- 6) this iteration's user comment = read a UTF-8 vector as [length] octets
-
- }
-
- 7) [framing_bit] = read a single bit as boolean
- 8) if ( [framing_bit] unset or end of packet ) then ERROR
- 9) done.
-</pre>
-
-<h2>Content vector format</h2>
-
-<p>The comment vectors are structured similarly to a UNIX environment variable.
-That is, comment fields consist of a field name and a corresponding value and
-look like:</p>
-
-<pre>
-comment[0]="ARTIST=me";
-comment[1]="TITLE=the sound of Vorbis";
-</pre>
-
-<ul>
-<li>A case-insensitive field name that may consist of ASCII 0x20 through
-0x7D, 0x3D ('=') excluded. ASCII 0x41 through 0x5A inclusive (A-Z) is
-to be considered equivalent to ASCII 0x61 through 0x7A inclusive
-(a-z).</li>
-<li>The field name is immediately followed by ASCII 0x3D ('=');
-this equals sign is used to terminate the field name.</li>
-<li>0x3D is followed by the 8 bit clean UTF-8 encoded value of the
-field contents to the end of the field.</li>
-</ul>
-
-<h3>Field names</h3>
-
-<p>Below is a proposed, minimal list of standard field names with a
-description of intended use. No single or group of field names is
-mandatory; a comment header may contain one, all or none of the names
-in this list.</p>
-
-<dl>
-
-<dt>TITLE</dt>
-<dd>Track/Work name</dd>
-
-<dt>VERSION</dt>
-<dd>The version field may be used to differentiate multiple
-versions of the same track title in a single collection.
-(e.g. remix info)</dd>
-
-<dt>ALBUM</dt>
-<dd>The collection name to which this track belongs</dd>
-
-<dt>TRACKNUMBER</dt>
-<dd>The track number of this piece if part of a specific larger collection or album</dd>
-
-<dt>ARTIST</dt>
-<dd>The artist generally considered responsible for the work. In popular music
-this is usually the performing band or singer. For classical music it would be
-the composer. For an audio book it would be the author of the original text.</dd>
-
-<dt>PERFORMER</dt>
-<dd>The artist(s) who performed the work. In classical music this would be the
-conductor, orchestra, soloists. In an audio book it would be the actor who did
-the reading. In popular music this is typically the same as the ARTIST and
-is omitted.</dd>
-
-<dt>COPYRIGHT</dt>
-<dd>Copyright attribution, e.g., '2001 Nobody's Band' or '1999 Jack Moffitt'</dd>
-
-<dt>LICENSE</dt>
-<dd>License information, eg, 'All Rights Reserved', 'Any
-Use Permitted', a URL to a license such as a Creative Commons license
-("www.creativecommons.org/blahblah/license.html") or the EFF Open
-Audio License ('distributed under the terms of the Open Audio
-License. see http://www.eff.org/IP/Open_licenses/eff_oal.html for
-details'), etc.</dd>
-
-<dt>ORGANIZATION</dt>
-<dd>Name of the organization producing the track (i.e.
-the 'record label')</dd>
-
-<dt>DESCRIPTION</dt>
-<dd>A short text description of the contents</dd>
-
-<dt>GENRE</dt>
-<dd>A short text indication of music genre</dd>
-
-<dt>DATE</dt>
-<dd>Date the track was recorded</dd>
-
-<dt>LOCATION</dt>
-<dd>Location where track was recorded</dd>
-
-<dt>CONTACT</dt>
-<dd>Contact information for the creators or distributors of the track.
-This could be a URL, an email address, the physical address of
-the producing label.</dd>
-
-<dt>ISRC</dt>
-<dd>ISRC number for the track; see <a href="http://www.ifpi.org/site-content/online/isrc_intro.html">the
-ISRC intro page</a> for more information on ISRC numbers.</dd>
-
-</dl>
-
-<h3>Implications</h3>
-
-<ul>
-<li>Field names should not be 'internationalized'; this is a
-concession to simplicity not an attempt to exclude the majority of
-the world that doesn't speak English. Field <emph>contents</emph>,
-however, use the UTF-8 character encoding to allow easy representation
-of any language.</li>
-<li>We have the length of the entirety of the field and restrictions on
-the field name so that the field name is bounded in a known way. Thus
-we also have the length of the field contents.</li>
-<li>Individual 'vendors' may use non-standard field names within
-reason. The proper use of comment fields should be clear through
-context at this point. Abuse will be discouraged.</li>
-<li>There is no vendor-specific prefix to 'nonstandard' field names.
-Vendors should make some effort to avoid arbitrarily polluting the
-common namespace. We will generally collect the more useful tags
-here to help with standardization.</li>
-<li>Field names are not required to be unique (occur once) within a
-comment header. As an example, assume a track was recorded by three
-well know artists; the following is permissible, and encouraged:
-<pre>
- ARTIST=Dizzy Gillespie
- ARTIST=Sonny Rollins
- ARTIST=Sonny Stitt
-</pre></li>
-</ul>
-
-<h2>Encoding</h2>
-
-<p>The comment header comprises the entirety of the second bitstream
-header packet. Unlike the first bitstream header packet, it is not
-generally the only packet on the second page and may not be restricted
-to within the second bitstream page. The length of the comment header
-packet is (practically) unbounded. The comment header packet is not
-optional; it must be present in the bitstream even if it is
-effectively empty.</p>
-
-<p>The comment header is encoded as follows (as per Ogg's standard
-bitstream mapping which renders least-significant-bit of the word to be
-coded into the least significant available bit of the current
-bitstream octet first):</p>
-
-<ol>
-<li>Vendor string length (32 bit unsigned quantity specifying number of octets)</li>
-<li>Vendor string ([vendor string length] octets coded from beginning of string
-to end of string, not null terminated)</li>
-<li>Number of comment fields (32 bit unsigned quantity specifying number of fields)</li>
-<li>Comment field 0 length (if [Number of comment fields]>0; 32 bit unsigned
-quantity specifying number of octets)</li>
-<li>Comment field 0 ([Comment field 0 length] octets coded from beginning of
-string to end of string, not null terminated)</li>
-<li>Comment field 1 length (if [Number of comment fields]>1...)...</li>
-</ol>
-
-<p>This is actually somewhat easier to describe in code; implementation of the above
-can be found in vorbis/lib/info.c:_vorbis_pack_comment(),_vorbis_unpack_comment()</p>
-
-<div id="copyright">
- The Xiph Fish Logo is a
- trademark (™) of Xiph.Org.<br/>
-
- These pages © 1994 - 2005 Xiph.Org. All rights reserved.
-</div>
-
-</body>
-</html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<head>
+
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
+<title>Ogg Vorbis Documentation</title>
+
+<style type="text/css">
+body {
+ margin: 0 18px 0 18px;
+ padding-bottom: 30px;
+ font-family: Verdana, Arial, Helvetica, sans-serif;
+ color: #333333;
+ font-size: .8em;
+}
+
+a {
+ color: #3366cc;
+}
+
+img {
+ border: 0;
+}
+
+#xiphlogo {
+ margin: 30px 0 16px 0;
+}
+
+#content p {
+ line-height: 1.4;
+}
+
+h1, h1 a, h2, h2 a, h3, h3 a {
+ font-weight: bold;
+ color: #ff9900;
+ margin: 1.3em 0 8px 0;
+}
+
+h1 {
+ font-size: 1.3em;
+}
+
+h2 {
+ font-size: 1.2em;
+}
+
+h3 {
+ font-size: 1.1em;
+}
+
+li {
+ line-height: 1.4;
+}
+
+#copyright {
+ margin-top: 30px;
+ line-height: 1.5em;
+ text-align: center;
+ font-size: .8em;
+ color: #888888;
+ clear: both;
+}
+</style>
+
+</head>
+
+<body>
+
+<div id="xiphlogo">
+ <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.org"/></a>
+</div>
+
+<h1>Ogg Vorbis I format specification: comment field and header specification</h1>
+
+<h1>Overview</h1>
+
+<p>The Vorbis text comment header is the second (of three) header
+packets that begin a Vorbis bitstream. It is meant for short, text
+comments, not arbitrary metadata; arbitrary metadata belongs in a
+separate logical bitstream (usually an XML stream type) that provides
+greater structure and machine parseability.</p>
+
+<p>The comment field is meant to be used much like someone jotting a
+quick note on the bottom of a CDR. It should be a little information to
+remember the disc by and explain it to others; a short, to-the-point
+text note that need not only be a couple words, but isn't going to be
+more than a short paragraph. The essentials, in other words, whatever
+they turn out to be, eg:</p>
+
+<blockquote><p>
+"Honest Bob and the Factory-to-Dealer-Incentives, _I'm Still Around_,
+opening for Moxy Früvous, 1997"
+</p></blockquote>
+
+<h1>Comment encoding</h1>
+
+<h2>Structure</h2>
+
+<p>The comment header logically is a list of eight-bit-clean vectors; the
+number of vectors is bounded to 2^32-1 and the length of each vector
+is limited to 2^32-1 bytes. The vector length is encoded; the vector
+contents themselves are not null terminated. In addition to the vector
+list, there is a single vector for vendor name (also 8 bit clean,
+length encoded in 32 bits). For example, the 1.0 release of libvorbis
+set the vendor string to "Xiph.Org libVorbis I 20020717".</p>
+
+<p>The comment header is decoded as follows:</p>
+
+<pre>
+ 1) [vendor_length] = read an unsigned integer of 32 bits
+ 2) [vendor_string] = read a UTF-8 vector as [vendor_length] octets
+ 3) [user_comment_list_length] = read an unsigned integer of 32 bits
+ 4) iterate [user_comment_list_length] times {
+
+ 5) [length] = read an unsigned integer of 32 bits
+ 6) this iteration's user comment = read a UTF-8 vector as [length] octets
+
+ }
+
+ 7) [framing_bit] = read a single bit as boolean
+ 8) if ( [framing_bit] unset or end of packet ) then ERROR
+ 9) done.
+</pre>
+
+<h2>Content vector format</h2>
+
+<p>The comment vectors are structured similarly to a UNIX environment variable.
+That is, comment fields consist of a field name and a corresponding value and
+look like:</p>
+
+<pre>
+comment[0]="ARTIST=me";
+comment[1]="TITLE=the sound of Vorbis";
+</pre>
+
+<ul>
+<li>A case-insensitive field name that may consist of ASCII 0x20 through
+0x7D, 0x3D ('=') excluded. ASCII 0x41 through 0x5A inclusive (A-Z) is
+to be considered equivalent to ASCII 0x61 through 0x7A inclusive
+(a-z).</li>
+<li>The field name is immediately followed by ASCII 0x3D ('=');
+this equals sign is used to terminate the field name.</li>
+<li>0x3D is followed by the 8 bit clean UTF-8 encoded value of the
+field contents to the end of the field.</li>
+</ul>
+
+<h3>Field names</h3>
+
+<p>Below is a proposed, minimal list of standard field names with a
+description of intended use. No single or group of field names is
+mandatory; a comment header may contain one, all or none of the names
+in this list.</p>
+
+<dl>
+
+<dt>TITLE</dt>
+<dd>Track/Work name</dd>
+
+<dt>VERSION</dt>
+<dd>The version field may be used to differentiate multiple
+versions of the same track title in a single collection.
+(e.g. remix info)</dd>
+
+<dt>ALBUM</dt>
+<dd>The collection name to which this track belongs</dd>
+
+<dt>TRACKNUMBER</dt>
+<dd>The track number of this piece if part of a specific larger collection or album</dd>
+
+<dt>ARTIST</dt>
+<dd>The artist generally considered responsible for the work. In popular music
+this is usually the performing band or singer. For classical music it would be
+the composer. For an audio book it would be the author of the original text.</dd>
+
+<dt>PERFORMER</dt>
+<dd>The artist(s) who performed the work. In classical music this would be the
+conductor, orchestra, soloists. In an audio book it would be the actor who did
+the reading. In popular music this is typically the same as the ARTIST and
+is omitted.</dd>
+
+<dt>COPYRIGHT</dt>
+<dd>Copyright attribution, e.g., '2001 Nobody's Band' or '1999 Jack Moffitt'</dd>
+
+<dt>LICENSE</dt>
+<dd>License information, eg, 'All Rights Reserved', 'Any
+Use Permitted', a URL to a license such as a Creative Commons license
+("www.creativecommons.org/blahblah/license.html") or the EFF Open
+Audio License ('distributed under the terms of the Open Audio
+License. see http://www.eff.org/IP/Open_licenses/eff_oal.html for
+details'), etc.</dd>
+
+<dt>ORGANIZATION</dt>
+<dd>Name of the organization producing the track (i.e.
+the 'record label')</dd>
+
+<dt>DESCRIPTION</dt>
+<dd>A short text description of the contents</dd>
+
+<dt>GENRE</dt>
+<dd>A short text indication of music genre</dd>
+
+<dt>DATE</dt>
+<dd>Date the track was recorded</dd>
+
+<dt>LOCATION</dt>
+<dd>Location where track was recorded</dd>
+
+<dt>CONTACT</dt>
+<dd>Contact information for the creators or distributors of the track.
+This could be a URL, an email address, the physical address of
+the producing label.</dd>
+
+<dt>ISRC</dt>
+<dd>ISRC number for the track; see <a href="http://www.ifpi.org/site-content/online/isrc_intro.html">the
+ISRC intro page</a> for more information on ISRC numbers.</dd>
+
+</dl>
+
+<h3>Implications</h3>
+
+<ul>
+<li>Field names should not be 'internationalized'; this is a
+concession to simplicity not an attempt to exclude the majority of
+the world that doesn't speak English. Field <emph>contents</emph>,
+however, use the UTF-8 character encoding to allow easy representation
+of any language.</li>
+<li>We have the length of the entirety of the field and restrictions on
+the field name so that the field name is bounded in a known way. Thus
+we also have the length of the field contents.</li>
+<li>Individual 'vendors' may use non-standard field names within
+reason. The proper use of comment fields should be clear through
+context at this point. Abuse will be discouraged.</li>
+<li>There is no vendor-specific prefix to 'nonstandard' field names.
+Vendors should make some effort to avoid arbitrarily polluting the
+common namespace. We will generally collect the more useful tags
+here to help with standardization.</li>
+<li>Field names are not required to be unique (occur once) within a
+comment header. As an example, assume a track was recorded by three
+well know artists; the following is permissible, and encouraged:
+<pre>
+ ARTIST=Dizzy Gillespie
+ ARTIST=Sonny Rollins
+ ARTIST=Sonny Stitt
+</pre></li>
+</ul>
+
+<h2>Encoding</h2>
+
+<p>The comment header comprises the entirety of the second bitstream
+header packet. Unlike the first bitstream header packet, it is not
+generally the only packet on the second page and may not be restricted
+to within the second bitstream page. The length of the comment header
+packet is (practically) unbounded. The comment header packet is not
+optional; it must be present in the bitstream even if it is
+effectively empty.</p>
+
+<p>The comment header is encoded as follows (as per Ogg's standard
+bitstream mapping which renders least-significant-bit of the word to be
+coded into the least significant available bit of the current
+bitstream octet first):</p>
+
+<ol>
+<li>Vendor string length (32 bit unsigned quantity specifying number of octets)</li>
+<li>Vendor string ([vendor string length] octets coded from beginning of string
+to end of string, not null terminated)</li>
+<li>Number of comment fields (32 bit unsigned quantity specifying number of fields)</li>
+<li>Comment field 0 length (if [Number of comment fields]>0; 32 bit unsigned
+quantity specifying number of octets)</li>
+<li>Comment field 0 ([Comment field 0 length] octets coded from beginning of
+string to end of string, not null terminated)</li>
+<li>Comment field 1 length (if [Number of comment fields]>1...)...</li>
+</ol>
+
+<p>This is actually somewhat easier to describe in code; implementation of the above
+can be found in vorbis/lib/info.c:_vorbis_pack_comment(),_vorbis_unpack_comment()</p>
+
+<div id="copyright">
+ The Xiph Fish Logo is a
+ trademark (™) of Xiph.Org.<br/>
+
+ These pages © 1994 - 2005 Xiph.Org. All rights reserved.
+</div>
+
+</body>
+</html>
Property changes on: trunk/vorbis/doc/v-comment.html
___________________________________________________________________
Name: svn:eol-style
+ native
Modified: trunk/vorbis/doc/vorbis-fidelity.html
===================================================================
--- trunk/vorbis/doc/vorbis-fidelity.html 2005-12-20 20:18:59 UTC (rev 10666)
+++ trunk/vorbis/doc/vorbis-fidelity.html 2005-12-21 01:19:37 UTC (rev 10667)
@@ -1,180 +1,180 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html>
-<head>
-
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
-<title>Ogg Vorbis Documentation</title>
-
-<style type="text/css">
-body {
- margin: 0 18px 0 18px;
- padding-bottom: 30px;
- font-family: Verdana, Arial, Helvetica, sans-serif;
- color: #333333;
- font-size: .8em;
-}
-
-a {
- color: #3366cc;
-}
-
-img {
- border: 0;
-}
-
-#xiphlogo {
- margin: 30px 0 16px 0;
-}
-
-#content p {
- line-height: 1.4;
-}
-
-h1, h1 a, h2, h2 a, h3, h3 a {
- font-weight: bold;
- color: #ff9900;
- margin: 1.3em 0 8px 0;
-}
-
-h1 {
- font-size: 1.3em;
-}
-
-h2 {
- font-size: 1.2em;
-}
-
-h3 {
- font-size: 1.1em;
-}
-
-li {
- line-height: 1.4;
-}
-
-#copyright {
- margin-top: 30px;
- line-height: 1.5em;
- text-align: center;
- font-size: .8em;
- color: #888888;
- clear: both;
-}
-</style>
-
-</head>
-
-<body>
-
-<div id="xiphlogo">
- <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.org"/></a>
-</div>
-
-<h1>Ogg Vorbis: Fidelity measurement and terminology discussion</h1>
-
-<p>Terminology discussed in this document is based on common terminology
-associated with contemporary codecs such as MPEG I audio layer 3
-(mp3). However, some differences in terminology are useful in the
-context of Vorbis as Vorbis functions somewhat differently than most
-current formats. For clarity, then, we describe a common terminology
-for discussion of Vorbis's and other formats' audio quality.</p>
-
-<h2>Subjective and Objective</h2>
-
-<p><em>Objective</em> fidelity is a measure, based on a computable,
-mechanical metric, of how carefully an output matches an input. For
-example, a stereo amplifier may claim to introduce less that .01%
-total harmonic distortion when amplifying an input signal; this claim
-is easy to verify given proper equipment, and any number of testers are
-likely to arrive at the same, exact results. One need not listen to
-the equipment to make this measurement.</p>
-
-<p>However, given two amplifiers with identical, verifiable objective
-specifications, listeners may strongly prefer the sound quality of one
-over the other. This is actually the case in the decades old debate
-[some would say jihad] among audiophiles involving vacuum tube versus
-solid state amplifiers. There are people who can tell the difference,
-and strongly prefer one over the other despite seemingly identical,
-measurable quality. This preference is <em>subjective</em> and
-difficult to measure but nonetheless real.</p>
-
-<p>Individual elements of subjective differences often can be qualified,
-but overall subjective quality generally is not measurable. Different
-observers are likely to disagree on the exact results of a subjective
-test as each observer's perspective differs. When measuring
-subjective qualities, the best one can hope for is average, empirical
-results that show statistical significance across a group.</p>
-
-<p>Perceptual codecs are most concerned with subjective, not objective,
-quality. This is why evaluating a perceptual codec via distortion
-measures and sonograms alone is useless; these objective measures may
-provide insight into the quality or functioning of a codec, but cannot
-answer the much squishier subjective question, "Does it sound
-good?". The tube amplifier example is perhaps not the best as very few
-people can hear, or care to hear, the minute differences between tubes
-and transistors, whereas the subjective differences in perceptual
-codecs tend to be quite large even when objective differences are
-not.</p>
-
-<h2>Fidelity, Artifacts and Differences</h2>
-
-<p>Audio <em>artifacts</em> and loss of fidelity or more simply
-put, audio <em>differences</em> are not the same thing.</p>
-
-<p>A loss of fidelity implies differences between the perceived input and
-output signal; it does not necessarily imply that the differences in
-output are displeasing or that the output sounds poor (although this
-is often the case). Tube amplifiers are <em>not</em> higher fidelity
-than modern solid state and digital systems. They simply produce a
-form of distortion and coloring that is either unnoticeable or actually
-pleasing to many ears.</p>
-
-<p>As compared to an original signal using hard metrics, all perceptual
-codecs [ASPEC, ATRAC, MP3, WMA, AAC, TwinVQ, AC3 and Vorbis included]
-lose objective fidelity in order to reduce bitrate. This is fact. The
-idea is to lose fidelity in ways that cannot be perceived. However,
-most current streaming applications demand bitrates lower than what
-can be achieved by sacrificing only objective fidelity; this is also
-fact, despite whatever various company press releases might claim.
-Subjective fidelity eventually must suffer in one way or another.</p>
-
-<p>The goal is to choose the best possible tradeoff such that the
-fidelity loss is graceful and not obviously noticeable. Most listeners
-of FM radio do not realize how much lower fidelity that medium is as
-compared to compact discs or DAT. However, when compared directly to
-source material, the difference is obvious. A cassette tape is lower
-fidelity still, and yet the degradation, relatively speaking, is
-graceful and generally easy not to notice. Compare this graceful loss
-of quality to an average 44.1kHz stereo mp3 encoded at 80 or 96kbps.
-The mp3 might actually be higher objective fidelity but subjectively
-sounds much worse.</p>
-
-<p>Thus, when a CODEC <em>must</em> sacrifice subjective quality in order
-to satisfy a user's requirements, the result should be a
-<em>difference</em> that is generally either difficult to notice
-without comparison, or easy to ignore. An <em>artifact</em>, on the
-other hand, is an element introduced into the output that is
-immediately noticeable, obviously foreign, and undesired. The famous
-'underwater' or 'twinkling' effect synonymous with low bitrate (or
-poorly encoded) mp3 is an example of an <em>artifact</em>. This
-working definition differs slightly from common usage, but the coined
-distinction between differences and artifacts is useful for our
-discussion.</p>
-
-<p>The goal, when it is absolutely necessary to sacrifice subjective
-fidelity, is obviously to strive for differences and not artifacts.
-The vast majority of codecs today fail at this task miserably,
-predictably, and regularly in one way or another. Avoiding such
-failures when it is necessary to sacrifice subjective quality is a
-fundamental design objective of Vorbis and that objective is reflected
-in Vorbis's design and tuning.</p>
-
-<div id="copyright">
- The Xiph Fish Logo is a
- trademark (™) of Xiph.Org.<br/>
-
- These pages © 1994 - 2005 Xiph.Org. All rights reserved.
-</div>
-
-</body>
-</html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<head>
+
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
+<title>Ogg Vorbis Documentation</title>
+
+<style type="text/css">
+body {
+ margin: 0 18px 0 18px;
+ padding-bottom: 30px;
+ font-family: Verdana, Arial, Helvetica, sans-serif;
+ color: #333333;
+ font-size: .8em;
+}
+
+a {
+ color: #3366cc;
+}
+
+img {
+ border: 0;
+}
+
+#xiphlogo {
+ margin: 30px 0 16px 0;
+}
+
+#content p {
+ line-height: 1.4;
+}
+
+h1, h1 a, h2, h2 a, h3, h3 a {
+ font-weight: bold;
+ color: #ff9900;
+ margin: 1.3em 0 8px 0;
+}
+
+h1 {
+ font-size: 1.3em;
+}
+
+h2 {
+ font-size: 1.2em;
+}
+
+h3 {
+ font-size: 1.1em;
+}
+
+li {
+ line-height: 1.4;
+}
+
+#copyright {
+ margin-top: 30px;
+ line-height: 1.5em;
+ text-align: center;
+ font-size: .8em;
+ color: #888888;
+ clear: both;
+}
+</style>
+
+</head>
+
+<body>
+
+<div id="xiphlogo">
+ <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.org"/></a>
+</div>
+
+<h1>Ogg Vorbis: Fidelity measurement and terminology discussion</h1>
+
+<p>Terminology discussed in this document is based on common terminology
+associated with contemporary codecs such as MPEG I audio layer 3
+(mp3). However, some differences in terminology are useful in the
+context of Vorbis as Vorbis functions somewhat differently than most
+current formats. For clarity, then, we describe a common terminology
+for discussion of Vorbis's and other formats' audio quality.</p>
+
+<h2>Subjective and Objective</h2>
+
+<p><em>Objective</em> fidelity is a measure, based on a computable,
+mechanical metric, of how carefully an output matches an input. For
+example, a stereo amplifier may claim to introduce less that .01%
+total harmonic distortion when amplifying an input signal; this claim
+is easy to verify given proper equipment, and any number of testers are
+likely to arrive at the same, exact results. One need not listen to
+the equipment to make this measurement.</p>
+
+<p>However, given two amplifiers with identical, verifiable objective
+specifications, listeners may strongly prefer the sound quality of one
+over the other. This is actually the case in the decades old debate
+[some would say jihad] among audiophiles involving vacuum tube versus
+solid state amplifiers. There are people who can tell the difference,
+and strongly prefer one over the other despite seemingly identical,
+measurable quality. This preference is <em>subjective</em> and
+difficult to measure but nonetheless real.</p>
+
+<p>Individual elements of subjective differences often can be qualified,
+but overall subjective quality generally is not measurable. Different
+observers are likely to disagree on the exact results of a subjective
+test as each observer's perspective differs. When measuring
+subjective qualities, the best one can hope for is average, empirical
+results that show statistical significance across a group.</p>
+
+<p>Perceptual codecs are most concerned with subjective, not objective,
+quality. This is why evaluating a perceptual codec via distortion
+measures and sonograms alone is useless; these objective measures may
+provide insight into the quality or functioning of a codec, but cannot
+answer the much squishier subjective question, "Does it sound
+good?". The tube amplifier example is perhaps not the best as very few
+people can hear, or care to hear, the minute differences between tubes
+and transistors, whereas the subjective differences in perceptual
+codecs tend to be quite large even when objective differences are
+not.</p>
+
+<h2>Fidelity, Artifacts and Differences</h2>
+
+<p>Audio <em>artifacts</em> and loss of fidelity or more simply
+put, audio <em>differences</em> are not the same thing.</p>
+
+<p>A loss of fidelity implies differences between the perceived input and
+output signal; it does not necessarily imply that the differences in
+output are displeasing or that the output sounds poor (although this
+is often the case). Tube amplifiers are <em>not</em> higher fidelity
+than modern solid state and digital systems. They simply produce a
+form of distortion and coloring that is either unnoticeable or actually
+pleasing to many ears.</p>
+
+<p>As compared to an original signal using hard metrics, all perceptual
+codecs [ASPEC, ATRAC, MP3, WMA, AAC, TwinVQ, AC3 and Vorbis included]
+lose objective fidelity in order to reduce bitrate. This is fact. The
+idea is to lose fidelity in ways that cannot be perceived. However,
+most current streaming applications demand bitrates lower than what
+can be achieved by sacrificing only objective fidelity; this is also
+fact, despite whatever various company press releases might claim.
+Subjective fidelity eventually must suffer in one way or another.</p>
+
+<p>The goal is to choose the best possible tradeoff such that the
+fidelity loss is graceful and not obviously noticeable. Most listeners
+of FM radio do not realize how much lower fidelity that medium is as
+compared to compact discs or DAT. However, when compared directly to
+source material, the difference is obvious. A cassette tape is lower
+fidelity still, and yet the degradation, relatively speaking, is
+graceful and generally easy not to notice. Compare this graceful loss
+of quality to an average 44.1kHz stereo mp3 encoded at 80 or 96kbps.
+The mp3 might actually be higher objective fidelity but subjectively
+sounds much worse.</p>
+
+<p>Thus, when a CODEC <em>must</em> sacrifice subjective quality in order
+to satisfy a user's requirements, the result should be a
+<em>difference</em> that is generally either difficult to notice
+without comparison, or easy to ignore. An <em>artifact</em>, on the
+other hand, is an element introduced into the output that is
+immediately noticeable, obviously foreign, and undesired. The famous
+'underwater' or 'twinkling' effect synonymous with low bitrate (or
+poorly encoded) mp3 is an example of an <em>artifact</em>. This
+working definition differs slightly from common usage, but the coined
+distinction between differences and artifacts is useful for our
+discussion.</p>
+
+<p>The goal, when it is absolutely necessary to sacrifice subjective
+fidelity, is obviously to strive for differences and not artifacts.
+The vast majority of codecs today fail at this task miserably,
+predictably, and regularly in one way or another. Avoiding such
+failures when it is necessary to sacrifice subjective quality is a
+fundamental design objective of Vorbis and that objective is reflected
+in Vorbis's design and tuning.</p>
+
+<div id="copyright">
+ The Xiph Fish Logo is a
+ trademark (™) of Xiph.Org.<br/>
+
+ These pages © 1994 - 2005 Xiph.Org. All rights reserved.
+</div>
+
+</body>
+</html>
Property changes on: trunk/vorbis/doc/vorbis-fidelity.html
___________________________________________________________________
Name: svn:eol-style
+ native
Modified: trunk/vorbis/doc/vorbis.html
===================================================================
--- trunk/vorbis/doc/vorbis.html 2005-12-20 20:18:59 UTC (rev 10666)
+++ trunk/vorbis/doc/vorbis.html 2005-12-21 01:19:37 UTC (rev 10667)
@@ -1,234 +1,234 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html>
-<head>
-
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
-<title>Ogg Vorbis Documentation</title>
-
-<style type="text/css">
-body {
- margin: 0 18px 0 18px;
- padding-bottom: 30px;
- font-family: Verdana, Arial, Helvetica, sans-serif;
- color: #333333;
- font-size: .8em;
-}
-
-a {
- color: #3366cc;
-}
-
-img {
- border: 0;
-}
-
-#xiphlogo {
- margin: 30px 0 16px 0;
-}
-
-#content p {
- line-height: 1.4;
-}
-
-h1, h1 a, h2, h2 a, h3, h3 a {
- font-weight: bold;
- color: #ff9900;
- margin: 1.3em 0 8px 0;
-}
-
-h1 {
- font-size: 1.3em;
-}
-
-h2 {
- font-size: 1.2em;
-}
-
-h3 {
- font-size: 1.1em;
-}
-
-li {
- line-height: 1.4;
-}
-
-#copyright {
- margin-top: 30px;
- line-height: 1.5em;
- text-align: center;
- font-size: .8em;
- color: #888888;
- clear: both;
-}
-</style>
-
-</head>
-
-<body>
-
-<div id="xiphlogo">
- <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.org"/></a>
-</div>
-
-<h1>Ogg Vorbis encoding format documentation</h1>
-
-<p><img src="wait.png" alt="wait"/>As of writing, not all the below document
-links are live. They will be populated as we complete the documents.</p>
-
-<h2>Documents</h2>
-
-<ul>
-<li><a href="packet.html">Vorbis packet structure</a></li>
-<li><a href="envelope.html">Temporal envelope shaping and blocksize</a></li>
-<li><a href="mdct.html">Time domain segmentation and MDCT transform</a></li>
-<li><a href="resolution.html">The resolution floor</a></li>
-<li><a href="residuals.html">MDCT-domain fine structure</a></li>
-</ul>
-
-<ul>
-<li><a href="probmodel.html">The Vorbis probability model</a></li>
-<li><a href="bitpack.html">The Vorbis bitpacker</a></li>
-</ul>
-
-<ul>
-<li><a href="oggstream.html">Ogg bitstream overview</a></li>
-<li><a href="framing.html">Ogg logical bitstream and framing spec</a></li>
-<li><a href="vorbis-stream.html">Vorbis packet->Ogg bitstream mapping</a></li>
-</ul>
-
-<ul>
-<li><a href="programming.html">Programming with libvorbis</a></li>
-</ul>
-
-<h2>Description</h2>
-
-<p>Ogg Vorbis is a general purpose compressed audio format
-for high quality (44.1-48.0kHz, 16+ bit, polyphonic) audio and music
-at moderate fixed and variable bitrates (40-80 kb/s/channel). This
-places Vorbis in the same class as audio representations including
-MPEG-1 audio layer 3, MPEG-4 audio (AAC and TwinVQ), and PAC.</p>
-
-<p>Vorbis is the first of a planned family of Ogg multimedia coding
-formats being developed as part of the Xiph.org Foundation's Ogg multimedia
-project. See <a href="http://www.xiph.org/">http://www.xiph.org/</a>
-for more information.</p>
-
-<h2>Vorbis technical documents</h2>
-
-<p>A Vorbis encoder takes in overlapping (but contiguous) short-time
-segments of audio data. The encoder analyzes the content of the audio
-to determine an optimal compact representation; this phase of encoding
-is known as <em>analysis</em>. For each short-time block of sound,
-the encoder then packs an efficient representation of the signal, as
-determined by analysis, into a raw packet much smaller than the size
-required by the original signal; this phase is <em>coding</em>.
-Lastly, in a streaming environment, the raw packets are then
-structured into a continuous stream of octets; this last phase is
-<em>streaming</em>. Note that the stream of octets is referred to both
-as a 'byte-' and 'bit-'stream; the latter usage is acceptible as the
-stream of octets is a physical representation of a true logical
-bit-by-bit stream.</p>
-
-<p>A Vorbis decoder performs a mirror image process of extracting the
-original sequence of raw packets from an Ogg stream (<em>stream
-decomposition</em>), reconstructing the signal representation from the
-raw data in the packet (<em>decoding</em>) and them reconstituting an
-audio signal from the decoded representation (<em>synthesis</em>).</p>
-
-<p>The <a href="programming.html">Programming with libvorbis</a>
-documents discuss use of the reference Vorbis codec library
-(libvorbis) produced by the Xiph.org Foundation.</p>
-
-<p>The data representations and algorithms necessary at each step to
-encode and decode Ogg Vorbis bitstreams are described by the below
-documents in sufficient detail to construct a complete Vorbis codec.
-Note that at the time of writing, Vorbis is still in a 'Request For
-Comments' stage of development; despite being in advanced stages of
-development, input from the multimedia community is welcome.</p>
-
-<h3>Vorbis analysis and synthesis</h3>
-
-<p>Analysis begins by seperating an input audio stream into individual,
-overlapping short-time segments of audio data. These segments are
-then transformed into an alternate representation, seeking to
-represent the original signal in a more efficient form that codes into
-a smaller number of bytes. The analysis and transformation stage is
-the most complex element of producing a Vorbis bitstream.</p>
-
-<p>The corresponding synthesis step in the decoder is simpler; there is
-no analysis to perform, merely a mechanical, deterministic
-reconstruction of the original audio data from the transform-domain
-representation.</p>
-
-<ul>
-<li><a href="packet.html">Vorbis packet structure</a>:
-Describes the basic analysis components necessary to produce Vorbis
-packets and the structure of the packet itself.</li>
-<li><a href="envelope.html">Temporal envelope shaping and blocksize</a>:
-Use of temporal envelope shaping and variable blocksize to minimize
-time-domain energy leakage during wide dynamic range and spectral energy
-swings. Also discusses time-related principles of psychoacoustics.</li>
-<li><a href="mdct.html">Time domain segmentation and MDCT transform</a>:
-Division of time domain data into individual overlapped, windowed
-short-time vectors and transformation using the MDCT</li>
-<li><a href="resolution.html">The resolution floor</a>: Use of frequency
-doamin psychoacoustics, and the MDCT-domain noise, masking and resolution
-floors</li>
-<li><a href="residuals.html">MDCT-domain fine structure</a>: Production,
-quantization and massaging of MDCT-spectrum fine structure</li>
-</ul>
-
-<h3>Vorbis coding and decoding</h3>
-
-<p>Coding and decoding converts the transform-domain representation of
-the original audio produced by analysis to and from a bitwise packed
-raw data packet. Coding and decoding consist of two logically
-orthogonal concepts, <em>back-end coding</em> and <em>bitpacking</em>.</p>
-
-<p><em>Back-end coding</em> uses a probability model to represent the raw numbers
-of the audio representation in as few physical bits as possible;
-familiar examples of back-end coding include Huffman coding and Vector
-Quantization.</p>
-
-<p><em>Bitpacking</em> arranges the variable sized words of the back-end
-coding into a vector of octets without wasting space. The octets
-produced by coding a single short-time audio segment is one raw Vorbis
-packet.</p>
-
-<ul>
-<li><a href="probmodel.html">The Vorbis probability model</a></li>
-<li><a href="bitpack.html">The Vorbis bitpacker</a>: Arrangement of
-variable bit-length words into an octet-aligned packet.</li>
-</ul>
-
-<h3>Vorbis streaming and stream decomposition</h3>
-
-<p>Vorbis packets contain the raw, bitwise-compressed representation of a
-snippet of audio. These packets contain no structure and cannot be
-strung together directly into a stream; for streamed transmission and
-storage, Vorbis packets are encoded into an Ogg bitstream.</p>
-
-<ul>
-<li><a href="oggstream.html">Ogg bitstream overview</a>: High-level
-description of Ogg logical bitstreams, how logical bitstreams
-(of mixed media types) can be combined into physical bitstreams, and
-restrictions on logical-to-physical mapping. Note that this document is
-not specific only to Ogg Vorbis.</li>
-<li><a href="framing.html">Ogg logical bitstream and framing
-spec</a>: Low level, complete specification of Ogg logical
-bitstream pages. Note that this document is not specific only to Ogg
-Vorbis.</li>
-<li><a href="vorbis-stream.html">Vorbis bitstream mapping</a>:
-Specifically describes mapping Vorbis data into an
-Ogg physical bitstream.</li>
-</ul>
-
-<div id="copyright">
- The Xiph Fish Logo is a
- trademark (™) of Xiph.Org.<br/>
-
- These pages © 1994 - 2005 Xiph.Org. All rights reserved.
-</div>
-
-</body>
-</html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<head>
+
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
+<title>Ogg Vorbis Documentation</title>
+
+<style type="text/css">
+body {
+ margin: 0 18px 0 18px;
+ padding-bottom: 30px;
+ font-family: Verdana, Arial, Helvetica, sans-serif;
+ color: #333333;
+ font-size: .8em;
+}
+
+a {
+ color: #3366cc;
+}
+
+img {
+ border: 0;
+}
+
+#xiphlogo {
+ margin: 30px 0 16px 0;
+}
+
+#content p {
+ line-height: 1.4;
+}
+
+h1, h1 a, h2, h2 a, h3, h3 a {
+ font-weight: bold;
+ color: #ff9900;
+ margin: 1.3em 0 8px 0;
+}
+
+h1 {
+ font-size: 1.3em;
+}
+
+h2 {
+ font-size: 1.2em;
+}
+
+h3 {
+ font-size: 1.1em;
+}
+
+li {
+ line-height: 1.4;
+}
+
+#copyright {
+ margin-top: 30px;
+ line-height: 1.5em;
+ text-align: center;
+ font-size: .8em;
+ color: #888888;
+ clear: both;
+}
+</style>
+
+</head>
+
+<body>
+
+<div id="xiphlogo">
+ <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.org"/></a>
+</div>
+
+<h1>Ogg Vorbis encoding format documentation</h1>
+
+<p><img src="wait.png" alt="wait"/>As of writing, not all the below document
+links are live. They will be populated as we complete the documents.</p>
+
+<h2>Documents</h2>
+
+<ul>
+<li><a href="packet.html">Vorbis packet structure</a></li>
+<li><a href="envelope.html">Temporal envelope shaping and blocksize</a></li>
+<li><a href="mdct.html">Time domain segmentation and MDCT transform</a></li>
+<li><a href="resolution.html">The resolution floor</a></li>
+<li><a href="residuals.html">MDCT-domain fine structure</a></li>
+</ul>
+
+<ul>
+<li><a href="probmodel.html">The Vorbis probability model</a></li>
+<li><a href="bitpack.html">The Vorbis bitpacker</a></li>
+</ul>
+
+<ul>
+<li><a href="oggstream.html">Ogg bitstream overview</a></li>
+<li><a href="framing.html">Ogg logical bitstream and framing spec</a></li>
+<li><a href="vorbis-stream.html">Vorbis packet->Ogg bitstream mapping</a></li>
+</ul>
+
+<ul>
+<li><a href="programming.html">Programming with libvorbis</a></li>
+</ul>
+
+<h2>Description</h2>
+
+<p>Ogg Vorbis is a general purpose compressed audio format
+for high quality (44.1-48.0kHz, 16+ bit, polyphonic) audio and music
+at moderate fixed and variable bitrates (40-80 kb/s/channel). This
+places Vorbis in the same class as audio representations including
+MPEG-1 audio layer 3, MPEG-4 audio (AAC and TwinVQ), and PAC.</p>
+
+<p>Vorbis is the first of a planned family of Ogg multimedia coding
+formats being developed as part of the Xiph.org Foundation's Ogg multimedia
+project. See <a href="http://www.xiph.org/">http://www.xiph.org/</a>
+for more information.</p>
+
+<h2>Vorbis technical documents</h2>
+
+<p>A Vorbis encoder takes in overlapping (but contiguous) short-time
+segments of audio data. The encoder analyzes the content of the audio
+to determine an optimal compact representation; this phase of encoding
+is known as <em>analysis</em>. For each short-time block of sound,
+the encoder then packs an efficient representation of the signal, as
+determined by analysis, into a raw packet much smaller than the size
+required by the original signal; this phase is <em>coding</em>.
+Lastly, in a streaming environment, the raw packets are then
+structured into a continuous stream of octets; this last phase is
+<em>streaming</em>. Note that the stream of octets is referred to both
+as a 'byte-' and 'bit-'stream; the latter usage is acceptible as the
+stream of octets is a physical representation of a true logical
+bit-by-bit stream.</p>
+
+<p>A Vorbis decoder performs a mirror image process of extracting the
+original sequence of raw packets from an Ogg stream (<em>stream
+decomposition</em>), reconstructing the signal representation from the
+raw data in the packet (<em>decoding</em>) and them reconstituting an
+audio signal from the decoded representation (<em>synthesis</em>).</p>
+
+<p>The <a href="programming.html">Programming with libvorbis</a>
+documents discuss use of the reference Vorbis codec library
+(libvorbis) produced by the Xiph.org Foundation.</p>
+
+<p>The data representations and algorithms necessary at each step to
+encode and decode Ogg Vorbis bitstreams are described by the below
+documents in sufficient detail to construct a complete Vorbis codec.
+Note that at the time of writing, Vorbis is still in a 'Request For
+Comments' stage of development; despite being in advanced stages of
+development, input from the multimedia community is welcome.</p>
+
+<h3>Vorbis analysis and synthesis</h3>
+
+<p>Analysis begins by seperating an input audio stream into individual,
+overlapping short-time segments of audio data. These segments are
+then transformed into an alternate representation, seeking to
+represent the original signal in a more efficient form that codes into
+a smaller number of bytes. The analysis and transformation stage is
+the most complex element of producing a Vorbis bitstream.</p>
+
+<p>The corresponding synthesis step in the decoder is simpler; there is
+no analysis to perform, merely a mechanical, deterministic
+reconstruction of the original audio data from the transform-domain
+representation.</p>
+
+<ul>
+<li><a href="packet.html">Vorbis packet structure</a>:
+Describes the basic analysis components necessary to produce Vorbis
+packets and the structure of the packet itself.</li>
+<li><a href="envelope.html">Temporal envelope shaping and blocksize</a>:
+Use of temporal envelope shaping and variable blocksize to minimize
+time-domain energy leakage during wide dynamic range and spectral energy
+swings. Also discusses time-related principles of psychoacoustics.</li>
+<li><a href="mdct.html">Time domain segmentation and MDCT transform</a>:
+Division of time domain data into individual overlapped, windowed
+short-time vectors and transformation using the MDCT</li>
+<li><a href="resolution.html">The resolution floor</a>: Use of frequency
+doamin psychoacoustics, and the MDCT-domain noise, masking and resolution
+floors</li>
+<li><a href="residuals.html">MDCT-domain fine structure</a>: Production,
+quantization and massaging of MDCT-spectrum fine structure</li>
+</ul>
+
+<h3>Vorbis coding and decoding</h3>
+
+<p>Coding and decoding converts the transform-domain representation of
+the original audio produced by analysis to and from a bitwise packed
+raw data packet. Coding and decoding consist of two logically
+orthogonal concepts, <em>back-end coding</em> and <em>bitpacking</em>.</p>
+
+<p><em>Back-end coding</em> uses a probability model to represent the raw numbers
+of the audio representation in as few physical bits as possible;
+familiar examples of back-end coding include Huffman coding and Vector
+Quantization.</p>
+
+<p><em>Bitpacking</em> arranges the variable sized words of the back-end
+coding into a vector of octets without wasting space. The octets
+produced by coding a single short-time audio segment is one raw Vorbis
+packet.</p>
+
+<ul>
+<li><a href="probmodel.html">The Vorbis probability model</a></li>
+<li><a href="bitpack.html">The Vorbis bitpacker</a>: Arrangement of
+variable bit-length words into an octet-aligned packet.</li>
+</ul>
+
+<h3>Vorbis streaming and stream decomposition</h3>
+
+<p>Vorbis packets contain the raw, bitwise-compressed representation of a
+snippet of audio. These packets contain no structure and cannot be
+strung together directly into a stream; for streamed transmission and
+storage, Vorbis packets are encoded into an Ogg bitstream.</p>
+
+<ul>
+<li><a href="oggstream.html">Ogg bitstream overview</a>: High-level
+description of Ogg logical bitstreams, how logical bitstreams
+(of mixed media types) can be combined into physical bitstreams, and
+restrictions on logical-to-physical mapping. Note that this document is
+not specific only to Ogg Vorbis.</li>
+<li><a href="framing.html">Ogg logical bitstream and framing
+spec</a>: Low level, complete specification of Ogg logical
+bitstream pages. Note that this document is not specific only to Ogg
+Vorbis.</li>
+<li><a href="vorbis-stream.html">Vorbis bitstream mapping</a>:
+Specifically describes mapping Vorbis data into an
+Ogg physical bitstream.</li>
+</ul>
+
+<div id="copyright">
+ The Xiph Fish Logo is a
+ trademark (™) of Xiph.Org.<br/>
+
+ These pages © 1994 - 2005 Xiph.Org. All rights reserved.
+</div>
+
+</body>
+</html>
Property changes on: trunk/vorbis/doc/vorbis.html
___________________________________________________________________
Name: svn:eol-style
+ native
More information about the commits
mailing list