ietf doc: characteristics, bit-stream

1 files changed, 84 insertions, 49 deletions

diff --git a/doc/ietf/draft-valin-celt-codec.xml b/doc/ietf/draft-valin-celt-codec.xml
index eddc7fd..566a0ff 100644
--- a/doc/ietf/draft-valin-celt-codec.xml
+++ b/doc/ietf/draft-valin-celt-codec.xml
@@ -108,9 +108,10 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
 document are to be interpreted as described in RFC 2119 <xref target="rfc2119"/>.
 </t>
+
 </section>
 
-<section anchor="Overview of the CELT Codec" title="Overview of the CELT Codec">
+<section anchor="overview" title="Overview of the CELT Codec">
 
 <t>
 CELT stands for <spanx style="emph">Constrained Energy Lapped Transform</spanx>. This is
@@ -126,23 +127,84 @@ the codec (version 0.3.2 and 0.5.1, respectively), the principles remain the sam
 aliasing calcellation. The main characteristics of CELT are as follows:
 
 <list style="symbols">
-<t>Ultra-low algorithmic delay (typically 3 to 9 ms)</t>
-<t>Full audio bandwidth (44.1 kHz and 48 kHz)</t>
-<t>Support for both speech and music</t>
-<t>Stereo support</t>
-<t>Robustness to packet loss</t>
-<t>Constant bit-rate from 32 kbps to 128 kbps and above</t>
-<t>Open source, with no known intellectual property issue</t>
+<t>Ultra-low algorithmic delay (scalable, typically 3 to 9 ms)</t>
+<t>Sampling rates from 32 kHz to 48 kHz and above (full audio bandwidth)</t>
+<t>Applicable to both speech and music</t>
+<t>Support for mono and stereo</t>
+<t>Adaptive bit-rate from 32 kbps to 128 kbps and above</t>
+<t>Scalable complexity</t>
+<t>Robustness to packet loss (scalable trade-off between quality and loss robustness)</t>
+<t>Open source implementation (floating-point and fixed-point)</t>
+<t>No known intellectual property issue</t>
+</list>
+</t>
+
+<section anchor="bitstream" title="Bit-stream definition">
+
+<t>
+This document contains a detailed description of both the encoder and the decoder, along with a reference implementation. In most circumstances, and unless otherwise stated, the calculations in other implementations do NOT need to produce results that are bit-identical with the reference implementation, so alternate algorithms can sometimes be used. However, there are a few (clearly identified) cases where bit-exactness is required. An implementation is considered to be compatible if, for any valid bit-stream, the decoder's output is perceptually very close to the output produced by the reference decoder.
+</t>
+
+<t>
+The CELT codec does not use a standard <spanx style="emph">bit-packer</spanx>, 
+but rather uses a range coder to pack both integers and entropy-coded symbols. 
+The bit-stream generated by the encoder contains (in the same order) the 
+following parameters:
+</t>
+
+<t>
+<list style="symbols">
+<t>Feature flags (2-4 bits)</t>
+<t>if P=1
+   <list style="symbols">
+      <t>Pitch period</t>
+   </list></t>
+<t>if S=1
+   <list style="symbols">
+      <t>Transient scalefactor</t>
+      <t>if scalefactor=(1 or 2) AND more than 2 short MDCTs
+	     <list style="symbols">
+		    <t>ID of block before transient</t>
+		 </list></t>
+      <t>if scalefactor=3
+	     <list style="symbols">
+		    <t>Transient time</t>
+      </list></t>
+   </list></t>
+<t>Coarse energy encoding (for each band)</t>
+<t>Fine energy encoding (for each band)</t>
+<t>For each band
+   <list style="symbols">
+      <t>if P=1 and band is at the beginning of a pitch band
+	  <list>
+	     <t>Pitch gain bit</t>
+	  </list></t>
+	  <t>PVQ indices</t>
+   </list></t>
+<t>More fine energy (using all remaining bits)</t>
 </list>
 </t>
 
+<t>Note that due to the use of a range coder, all the parameters have to be encoded and decoded in order. </t>
+
+</section>
 
 </section>
 
 <section anchor="CELT Modes" title="CELT Modes">
 <t>
-The operation of both the encoder and decoder depend on the 
-mode data. This data includes:
+The operation of both the encoder and decoder depend on the mode data. A mode
+definition can be created by celt_create_mode() (<xref target="modes.h">modes.h</xref>)
+based on three parameters:
+<list style="symbols">
+<t>frame size (number of samples)</t>
+<t>sampling rate (samples per second)</t>
+<t>number of channels (1 or 2)</t>
+</list>
+</t>
+
+<t>The mode data that is created defines how the encoder and the decoder operate. More specifically, the following information is contained in the mode object:
+
 <list style="symbols">
 <t>Frame size</t>
 <t>Sampling rate</t>
@@ -155,6 +217,11 @@ mode data. This data includes:
 <t>Pulse allocation data</t>
 </list>
 </t>
+
+<t>
+The windowing overlap is the amount of overlap between the frames. CELT uses a low-overlap window that is typically half of the frame size. For a frame size of 256 samples, the overlap is 128 samples, so the total algorithmic delay is 256+128=384. CELT divides the audio into frequency bands, for which the energy is preserved. These bands are chosen to follow the ear's critical bands (Bark scale), with the exception that each band has to contain at least 3 frequency bins. 
+</t>
+
 </section>
 
 <section anchor="CELT Encoder" title="CELT Encoder">
@@ -180,45 +247,7 @@ celt_encode() (<xref target="celt.c">celt.c</xref>).
 </texttable>
 -->
 
-<t>
-The CELT codec does not use a standard <spanx style="emph">bit-packer</spanx>, 
-but rather uses a range coder to pack both integers and entropy-coded symbols. 
-The bit-stream generated by the encoder contains (in the same order) the 
-following symbols:
-</t>
 
-<t>
-<list style="symbols">
-<t>Feature flags (2-4 bits)</t>
-<t>if P=1
-   <list style="symbols">
-      <t>Pitch period</t>
-   </list></t>
-<t>if S=1
-   <list style="symbols">
-      <t>Transient scalefactor</t>
-      <t>if scalefactor=(1 or 2) AND more than 2 short MDCTs
-	     <list style="symbols">
-		    <t>ID of block before transient</t>
-		 </list></t>
-      <t>if scalefactor=3
-	     <list style="symbols">
-		    <t>Transient time</t>
-      </list></t>
-   </list></t>
-<t>Coarse energy encoding (for each band)</t>
-<t>Fine energy encoding (for each band)</t>
-<t>For each band
-   <list style="symbols">
-      <t>if P=1 and band is at the beginning of a pitch band
-	  <list>
-	     <t>Pitch gain bit</t>
-	  </list></t>
-	  <t>PVQ indices</t>
-   </list></t>
-<t>More fine energy (using all remaining bits)</t>
-</list>
-</t>
 
 <!--
 <figure>
@@ -253,7 +282,7 @@ derf?
 <section anchor="Encoder Feature Selection" title="Encoder Feature Selection">
 
 <t>
-The CELT codec has several optional features that be switched on of off, some of which are mutually exclusive. The four main flags are intra-frame energy (I), pitch (P), short blocks (S), and folding (F). Those are described in more details below. There are eight valid combinations of these four features, and they are encoded first into the stream using a variable length code (<xref target="flags-encoding"></xref>). It is left to the implementor to choose to enable each of the flags, with the only restriction that the combination of the four flags needs to correspond to a valid entry in <xref target="flags-encoding"></xref>.
+The CELT codec has several optional features that can be switched on or off, some of which are mutually exclusive. The four main flags are intra-frame energy (I), pitch (P), short blocks (S), and folding (F). Those are described in more details below. There are eight valid combinations of these four features, and they are encoded first into the stream using a variable length code (<xref target="flags-encoding"></xref>). It is left to the implementor to choose to enable each of the flags, with the only restriction that the combination of the four flags needs to correspond to a valid entry in <xref target="flags-encoding"></xref>.
 </t>
 
 <texttable anchor="flags-encoding">
@@ -473,6 +502,12 @@ The last pulse is the only one considering the pitch and minimizes the cost func
 J = -g_f * R^T*y + (g_f)^2 * ||y||^2
 </t>
 
+<t>
+The search described above is considered to be a good trade-off between quality
+and computational cost. However, there are other possible ways to search the PVQ
+codebook and the implementors MAY use any other search methods.
+</t>
+
 <section anchor="Index Encoding" title="Index Encoding">
 <t>
 The best PVQ codeword is encoded by encode_pulses() (<xref target="cwrs.c">cwrs.c</xref>).