Preparing for rc2
[speexdsp.git] / doc / manual.lyx
index ac9c891..af400e5 100644 (file)
@@ -29,7 +29,7 @@
 
 The Speex Codec Manual
 \newline 
-(draft)
+(for version 1.0rc2)
 \layout Author
 
 Jean-Marc Valin
@@ -45,36 +45,6 @@ Permission is granted to copy, distribute and/or modify this document under
  A copy of the license is included in the section entitled "GNU Free Documentati
 on License".
  
-\layout Section*
-
-Disclaimer
-\layout Standard
-
-This document is meant to provide useful information on the Speex codec
- but there is absolutely no warranty regarding usefulness or correctness
- of the information provided.
- Also, some techniques used in Speex are said to be 
-\begin_inset Quotes eld
-\end_inset 
-
-similar
-\begin_inset Quotes erd
-\end_inset 
-
- to techniques used in known codecs.
- This should not be understood as an acknowledgment that Speex is using
- any patented algorithm used in these codecs, but merely that comprehension
- of Speex can be facilitated by thinking that the principles of operation
- are the same or similar.
- Of course, there's also the obligatory 
-\begin_inset Quotes eld
-\end_inset 
-
-all trademarks are property of their respective owner
-\begin_inset Quotes erd
-\end_inset 
-
-.
 \layout Standard
 \pagebreak_top \pagebreak_bottom 
 
@@ -96,59 +66,126 @@ all trademarks are property of their respective owner
 Introduction to Speex
 \layout Standard
 
-Speex has been designed with the following goals in mind:
-\layout Itemize
+The Speex project (
+\family typewriter 
+http://www.speex.org/
+\family default 
+) has been started because there was a need for a speech codec that was
+ open-source and free from software patents.
+ These are essential conditions for being used by any open-source software.
+ There is already Vorbis that does general audio, but it is not really suitable
+ for speech.
+ Also, unlike many other speech codecs, Speex is not targeted at cell phones
+ (not many open-source cell phones anyway :-) ) but rather voice over IP
+ (VoIP) and file-based compression.
+\layout Standard
 
-No use of patented algorithms (e.g.
- no ACELP)
-\layout Itemize
+As design goals, we wanted to have a codec that would allowed both very
+ good quality speech and low bit-rate (unfortunately not at the same time!),
+ which led us to developing a codec with multiple bit-rates.
+ Of course very good quality also meant we had to do wideband (16 kHz sampling
+ rate) in addition to narrowband (telephone quality, 8 kHz sampling rate).
+\layout Standard
 
-Optimized for speech, not music
-\layout Itemize
+Designing for VoIP instead of cell phone use means that Speex must be robust
+ to lost packets, but not to corrupted ones since packets either arrive
+ unaltered or don't arrive at all.
+ Also, the idea was to have a reasonnable complexity and memory requirement
+ without compromising too much on the efficiency of the codec.
+\layout Standard
 
-Good for Voice over IP (VoIP)
-\layout Itemize
+All this led us to the choice of CELP
+\begin_inset LatexCommand \index{CELP}
 
-Provide very good quality speech (at least as an option)
-\layout Itemize
+\end_inset 
+
+ as the encoding technique to use for Speex.
+ One of the main reasons is that CELP has long proved that it could do the
+ job and scale well to both low bit-rates (think DoD CELP @ 4.8 kbps) and
+ high bit-rates (think G.728 @ 16 kbps).
+\layout Standard
 
-Allow a wide range of quality/bit-rates
+The main characteristics can be summerized as follows:
 \layout Itemize
 
-Integrate both narrowband and wideband coding
+Free software/open-source
+\begin_inset LatexCommand \index{open-source}
+
+\end_inset 
+
+, patent
+\begin_inset LatexCommand \index{patent}
+
+\end_inset 
+
+ and royalty-free
 \layout Itemize
 
-Reasonable complexity
-\layout Standard
+Integration of narrowband
+\begin_inset LatexCommand \index{narrowband}
+
+\end_inset 
+
+ and wideband
+\begin_inset LatexCommand \index{wideband}
+
+\end_inset 
 
-Throughout the design the following assumptions and constraints were considered
+ in the same bit-stream
 \layout Itemize
 
-Presence of packet losses
+Wide range of bit-rates available (from 2 kbps to 44 kbps)
 \layout Itemize
 
-Integrity of received frames (no bit-errors)
+Dynamic bit-rate switching and Variable Bit-Rate
+\begin_inset LatexCommand \index{variable bit-rate}
+
+\end_inset 
+
+ (VBR)
 \layout Itemize
 
-Memory footprint is neither critical nor unlimited
-\layout Standard
+Voice Activity Detection
+\begin_inset LatexCommand \index{voice activity detection}
 
-This led us to choose the CELP technique for Speex.
- Also many design decisions were based on the original goals and assumptions:
+\end_inset 
+
+ (VAD, integrated with VBR)
 \layout Itemize
 
-Minimizing the amount of information extracted from past frames (for robustness
- to packet loss)
+Variable complexity
+\begin_inset LatexCommand \index{complexity}
+
+\end_inset 
+
+
 \layout Itemize
 
-Dynamically-selectable codebooks (LSP, pitch and innovation)
+Ultra-wideband mode at 32 kHz (up to 48 kHz)
 \layout Itemize
 
-G.728-like fixed codebooks (without backward-adaptive grains because of patent
- issues)
-\layout Section
+Intensity stereo encoding option
+\layout Standard
+
+The next two sections describe the internals of the codec and require some
+ signal processing knowledge.
+ If you are only interested in using Speex, you can skip to section 
+\begin_inset LatexCommand \ref{sec:Command-line-encoder/decoder}
 
+\end_inset 
+
+.
+\layout Section
+\pagebreak_top 
 Introduction to CELP Coding
+\begin_inset LatexCommand \index{CELP}
+
+\end_inset 
+
+
 \layout Standard
 
 Speex is based on CELP, which stands for Code Excited Linear Prediction.
@@ -178,75 +215,97 @@ perceptually weighted domain
 \end_inset 
 
 
-\layout Subsection
-
-Linear Prediction
 \layout Standard
 
-The linear prediction model represents each speech sample as linear combination
- of past samples, plus an error signal called the excitation (or residual).
-\begin_inset Formula \[
-x(n)=\sum _{i=1}^{N}a_{i}x(n-i)+e(n)\]
+This section describes the basic ideas behind CELP.
+ Note that it's still incomplete.
+\layout Subsection
+
+Linear Prediction (LPC)
+\begin_inset LatexCommand \index{linear prediction}
 
 \end_inset 
 
 
 \layout Standard
 
-In the 
-\emph on 
-z
-\emph default 
--domain, this can be expressed as
+Linear prediction is at the base of may speech coding techniques, including
+ CELP.
+ The idea behind it is to predict the signal 
+\begin_inset Formula $x(n)$
+\end_inset 
+
+ using a linear combination of its past samples:
 \layout Standard
 
 
 \begin_inset Formula \[
-x(z)=\frac{1}{A(z)}\: e(z)\]
+y[n]=\sum _{i=1}^{N}a_{i}x[n-i]\]
+
+\end_inset 
 
+where 
+\begin_inset Formula $y[n]$
 \end_inset 
 
+ is the linear prediction of 
+\begin_inset Formula $x[n]$
+\end_inset 
 
-\layout Standard
+.
+ The prediction error is thus given by:
+\begin_inset Formula \[
+e[n]=x[n]-y[n]=x[n]-\sum _{i=1}^{N}a_{i}x[n-i]\]
 
-where 
-\begin_inset Formula $A(z)$
 \end_inset 
 
- is defined as
+
 \layout Standard
 
+The goal of the LPC analysis is to find the best prediction coefficients
+\begin_inset Formula $a_{i}$
+\end_inset 
 
+ which minimize the quadratic error function:
 \begin_inset Formula \[
-A(z)=1-\sum _{i=1}^{N}a_{i}z^{-i}\]
+E=\sum _{n=0}^{L-1}\left[e[n]\right]^{2}=\sum _{n=0}^{L-1}\left[x[n]-\sum _{i=1}^{N}a_{i}x[n-i]\right]^{2}\]
 
 \end_inset 
 
+That can be done by making all derivatives 
+\begin_inset Formula $\frac{\partial E}{\partial a_{i}}$
+\end_inset 
 
-\layout Standard
+ equal to zero:
+\begin_inset Formula \[
+\frac{\partial E}{\partial a_{i}}=\frac{\partial }{\partial a_{i}}\sum _{n=0}^{L-1}\left[x[n]-\sum _{i=1}^{N}a_{i}x[n-i]\right]^{2}=0\]
 
-We usually refer to 
-\begin_inset Formula $A(z)$
 \end_inset 
 
- as the analysis filter and 
-\begin_inset Formula $1/A(z)$
-\end_inset 
 
- as the synthesis filter.
 \layout Standard
 
 The 
-\begin_inset Formula $A(z)$
+\begin_inset Formula $a_{i}$
+\end_inset 
+
+ filter coefficients are computed using the Levinson-Durbin
+\begin_inset LatexCommand \index{Levinson-Durbin}
+
 \end_inset 
 
- filter is computed using the Levinson-Durbin algorithm, which starts from
- the auto-correlation 
+ algorithm, which starts from the auto-correlation
+\begin_inset LatexCommand \index{auto-correlation}
+
+\end_inset 
+
 \begin_inset Formula $R(m)$
 \end_inset 
 
  of the signal 
-\begin_inset Formula $x(n)$
+\begin_inset Formula $x[n]$
 \end_inset 
 
 .
@@ -254,7 +313,7 @@ The
 
 
 \begin_inset Formula \[
-r(m)=\sum _{i=0}^{N-1}x(i)x(i-m)\]
+R(m)=\sum _{i=0}^{N-1}x[i]x[i-m]\]
 
 \end_inset 
 
@@ -268,10 +327,10 @@ For an order
  filter, we have:
 \begin_inset Formula \[
 \mathbf{R}=\left[\begin{array}{cccc}
r(0) & r(1) & \cdots  & r(N-1)\\
r(1) & r(0) & \cdots  & r(N-2)\\
R(0) & R(1) & \cdots  & R(N-1)\\
R(1) & R(0) & \cdots  & R(N-2)\\
  \vdots  & \vdots  & \ddots  & \vdots \\
r(N-1) & r(N-2) & \cdots  & r(0)\end{array}
R(N-1) & R(N-2) & \cdots  & R(0)\end{array}
 \right]\]
 
 \end_inset 
@@ -279,8 +338,8 @@ For an order
 
 \begin_inset Formula \[
 \mathbf{r}=\left[\begin{array}{c}
r(1)\\
r(2)\\
R(1)\\
R(2)\\
  \vdots \\
  R(N)\end{array}
 \right]\]
@@ -325,29 +384,113 @@ The filter coefficients
  This is in theory; in practice because of finite precision, there are two
  commonly used techniques to make sure we have a stable filter.
  First, we multiply 
-\begin_inset Formula $r(0)$
+\begin_inset Formula $R(0)$
 \end_inset 
 
  by a number slightly above one (such as 1.0001), which is equivalent to
  adding noise to the signal.
  Also, we can apply a window the the auto-correlation, which is equivalent
  to filtering in the frequency domain, reducing sharp resonances.
+\layout Standard
+
+The linear prediction model represents each speech sample as linear combination
+ of past samples, plus an error signal called the excitation (or residual).
+\begin_inset Formula \[
+x[n]=\sum _{i=1}^{N}a_{i}x[n-i]+e[n]\]
+
+\end_inset 
+
+
+\layout Standard
+
+In the 
+\emph on 
+z
+\emph default 
+-domain, this can be expressed as
+\layout Standard
+
+
+\begin_inset Formula \[
+x(z)=\frac{1}{A(z)}\: e(z)\]
+
+\end_inset 
+
+
+\layout Standard
+
+where 
+\begin_inset Formula $A(z)$
+\end_inset 
+
+ is defined as
+\layout Standard
+
+
+\begin_inset Formula \[
+A(z)=1-\sum _{i=1}^{N}a_{i}z^{-i}\]
+
+\end_inset 
+
+
+\layout Standard
+
+We usually refer to 
+\begin_inset Formula $A(z)$
+\end_inset 
+
+ as the analysis filter and 
+\begin_inset Formula $1/A(z)$
+\end_inset 
+
+ as the synthesis filter.
+ The whole process is called short-term prediction as it predicts the signal
+\begin_inset Formula $x[n]$
+\end_inset 
+
+ using a prediction using only the 
+\begin_inset Formula $N$
+\end_inset 
+
+ past samples, where 
+\begin_inset Formula $N$
+\end_inset 
+
+ is usually around 10.
+\layout Standard
+
+Because LPC coefficients have very little robustness to quantization, they
+ are converted to Line Spectral Pair
+\begin_inset LatexCommand \index{line spectral pair}
+
+\end_inset 
+
+ (LSP) coefficients which have a much better behaviour with quantization,
+ one of them being that it's easy to keep the filter stable.
 \layout Subsection
 
 Pitch Prediction
+\begin_inset LatexCommand \index{pitch}
+
+\end_inset 
+
+
 \layout Standard
 
-During voiced segments, the speech signal is very periodic, so it is possible
- to take advantage of that by expressing the excitation signal 
-\begin_inset Formula $e(n)$
+During voiced segments, the speech signal is periodic, so it is possible
+ to take advantage of that property by approximating the excitation signal
+\begin_inset Formula $e[n]$
 \end_inset 
 
- as
+ by a gain times the past of the excitation:
 \layout Standard
 
 
 \begin_inset Formula \[
-e(n)=\beta e(n-T)+c(n)\]
+e[n]\simeq p[n]=\beta e[n-T]\]
 
 \end_inset 
 
@@ -371,45 +514,103 @@ where
 innovation codebook
 \emph default 
 .
- In the 
+ We call that long-term prediction since the excitation is predicted from
+\begin_inset Formula $e[n-T]$
+\end_inset 
+
+ with 
+\begin_inset Formula $T\gg N$
+\end_inset 
+
+.
+\layout Subsection
+
+Innovation Codebook
+\layout Standard
+
+The final excitation 
+\begin_inset Formula $e[n]$
+\end_inset 
+
+ will be the sum of the pitch prediction and an 
 \emph on 
-z
+innovation
 \emph default 
--domain, the excitation can be expressed as:
+ signal 
+\begin_inset Formula $c[n]$
+\end_inset 
+
+ taken from a fixed codebook.
 \layout Standard
 
 
 \begin_inset Formula \[
-e(z)=\frac{1}{1-\beta z^{-T}}\: c(z)\]
+e[n]=p[n]+c[n]=\beta e[n-T]+c[n]\]
 
 \end_inset 
 
-
-\layout Subsection
-
-Innovation Codebook
-\layout Standard
-
 This is where most of the bits in a CELP codec are allocated.
  It represents the information that couldn't be obtained either from linear
  prediction or pitch prediction.
+ In the 
+\emph on 
+z
+\emph default 
+-domain we can represent the final signal 
+\begin_inset Formula $X(z)$
+\end_inset 
+
+ as 
+\begin_inset Formula \[
+X(z)=\frac{C(z)}{A(z)\left(1-\beta z^{-T}\right)}\]
+
+\end_inset 
+
+
 \layout Subsection
 
 Analysis-by-Synthesis and Error Weighting
+\begin_inset LatexCommand \index{error weighting}
+
+\end_inset 
+
+
+\begin_inset LatexCommand \index{analysis-by-synthesis}
+
+\end_inset 
+
+
 \layout Standard
 
 Most (if not all) modern audio codecs attempt to 
-\emph on 
+\begin_inset Quotes eld
+\end_inset 
+
 shape
-\emph default 
- the noise so that it is the hardest to detect with the ear.
- That means that more noise can be tolerated in parts of the spectrum that
- are louder and 
+\begin_inset Quotes erd
+\end_inset 
+
+ the noise so that it appears mostly in the frequency regions where the
+ ear cannot detect it.
+ For example, the ear is more tolerant to noise in parts of the spectrum
+ that are louder and 
 \emph on 
 vice versa
 \emph default 
 .
- That's why the error is minimized for the perceptually weighted signal
+ That's why instead of minimizing the simple quadratic error
+\begin_inset Formula \[
+E=\sum _{n}\left(x[n]-\overline{x}[n]\right)^{2}\]
+
+\end_inset 
+
+where 
+\begin_inset Formula $\overline{x}[n]$
+\end_inset 
+
+ is the encoder signal, we minimize the error for the perceptually weighted
+ signal
 \begin_inset Formula \[
 X_{w}(z)=W(z)X(z)\]
 
@@ -444,10 +645,42 @@ A_{noise}(z)=\frac{1}{W(z)}=\frac{A\left(\frac{z}{\gamma _{2}}\right)}{A\left(\f
 \end_inset 
 
 
-\layout Section
-
-Speex narrowband mode
-\begin_inset LatexCommand \label{sec:Speex-narrowband-mode}
+\layout Standard
+
+If a filter 
+\begin_inset Formula $A(z)$
+\end_inset 
+
+ has (complex) poles at 
+\begin_inset Formula $p_{i}$
+\end_inset 
+
+ in the 
+\begin_inset Formula $z$
+\end_inset 
+
+-plane, the filter 
+\begin_inset Formula $A(z/\gamma )$
+\end_inset 
+
+ filter will have its poles at 
+\begin_inset Formula $p_{i}^{'}=\gamma p_{i}$
+\end_inset 
+
+, making it a flatter version of 
+\begin_inset Formula $A(z)$
+\end_inset 
+
+.
+\layout Section
+\pagebreak_top 
+Speex narrowband mode
+\begin_inset LatexCommand \label{sec:Speex-narrowband-mode}
+
+\end_inset 
+
+
+\begin_inset LatexCommand \index{narrowband}
 
 \end_inset 
 
@@ -465,18 +698,38 @@ This section looks at how Speex works for narrowband (
 
 , corresponding to 160 samples.
  Each frame is also subdivided into 4 sub-frames of 40 samples each.
+\layout Standard
+
+Also many design decisions were based on the original goals and assumptions:
+\layout Itemize
+
+Minimizing the amount of information extracted from past frames (for robustness
+ to packet loss)
+\layout Itemize
+
+Dynamically-selectable codebooks (LSP, pitch and innovation)
+\layout Itemize
+
+sub-vector fixed (innovation) codebooks
 \layout Subsection
 
 LPC Analysis
+\begin_inset LatexCommand \index{linear prediction}
+
+\end_inset 
+
+
 \layout Standard
 
-An LPC analysis is first performed on a (Hamming) window that spans all
- the current frame and half a frame in advance.
- The LPC coefficients are then converted to Line Spectral Pair (LSP), a
- representation that is more robust to quantization.
- The LSP's are quantized using 30 bits for higher quality modes and 18 bits
- for lower quality.
- The quantized LSP's are considered to be associated to the 
+An LPC analysis is first performed on a (asymetric Hamming) window that
+ spans all the current frame and half a frame in advance.
+ The LPC coefficients are then converted to Line Spectral Pair
+\begin_inset LatexCommand \index{line spectral pair}
+
+\end_inset 
+
+ (LSP), a representation that is more robust to quantization.
+ The LSP's are considered to be associated to the 
 \begin_inset Formula $4^{th}$
 \end_inset 
 
@@ -484,11 +737,24 @@ An LPC analysis is first performed on a (Hamming) window that spans all
  interpolated using the current and previous LSP's.
 \layout Standard
 
+The LSP's are encoded using 30 bits for higher quality modes and 18 bits
+ for lower quality, through the use of a multi-stage split-vector quantizer.
+ For the lower quality modes, the 10 coefficients are first quantized with
+ 6 bits and the error is then divided in two 5-coefficient sub-vectors.
+ Each of them is quantized with 6 bits, for a total of 18 bits.
+ For the higher quality modes, the remaining error on both sub-vectors is
+ further quantized with 6 bits each, for a total of 30 bits.
+\layout Standard
+
 The perceptual weighting filter 
 \begin_inset Formula $W(z)$
 \end_inset 
 
- used by Speex corresponds to the one described by eq.
+ used by Speex is derived from the LPC filter 
+\begin_inset Formula $A(z)$
+\end_inset 
+
+ and corresponds to the one described by eq.
  
 \begin_inset LatexCommand \ref{eq:weighting_filter}
 
@@ -511,15 +777,21 @@ The perceptual weighting filter
 \layout Subsection
 
 Pitch Prediction (adaptive codebook)
-\layout Standard
+\begin_inset LatexCommand \index{pitch}
+
+\end_inset 
+
 
-Speex uses a 3-tap prediction for pitch.
- That is, 
 \layout Standard
 
+Speex uses a 3-tap prediction for pitch.
+ That is, the pitch prediction signal 
+\begin_inset Formula $p[n]$
+\end_inset 
 
+ is obtained by the past of the excitation by:
 \begin_inset Formula \[
-e(n)=\beta _{0}e(n-T-1)+\beta _{1}e(n-T)+\beta _{2}e(n-T+1)+c(n)\]
+p[n]=\beta _{0}e[n-T-1]+\beta _{1}e[n-T]+\beta _{2}e[n-T+1]\]
 
 \end_inset 
 
@@ -535,7 +807,33 @@ where
 \end_inset 
 
  are the prediction (filter) taps.
+ It is worth noting that when the pitch is smaller than the sub-frame size,
+ we repeat the excitation at a period 
+\begin_inset Formula $T$
+\end_inset 
+
+.
+ For example, when 
+\begin_inset Formula $n-T+1$
+\end_inset 
+
+, we use 
+\begin_inset Formula $n-2T+1$
+\end_inset 
+
+ instead.
  The period and quantized gains are determined in closed loop.
+ In most modes, the pitch period is encoded with 7 bits in the 
+\begin_inset Formula $\left[17,144\right]$
+\end_inset 
+
+ range and the 
+\begin_inset Formula $\beta _{i}$
+\end_inset 
+
+ coefficients are vector-quantized using 7 bits (15 kbps narrowband and
+ above) at higher bit-rates and 5 bits at lower bit-rates (11 kbps narrowband
+ and below).
 \layout Subsection
 
 Innovation Codebook
@@ -547,18 +845,7 @@ n (VQ).
  the gain at the same time.
  This save many bits that would otherwise be allocated for a separate gain
  at the price of a slight increase in complexity.
- Except for the absence of (backward-adaptive) gain, the technique used
- in Speex is similar to G.728 (LD-CELP).
- However since we do not have a low-delay constraint, the search can be
- made more 
-\begin_inset Quotes eld
-\end_inset 
-
-global
-\begin_inset Quotes erd
-\end_inset 
-
- and make use of the whole information available for a sub-frame.
 \layout Subsection
 
 Bit allocation
@@ -580,11 +867,21 @@ There are 7 different narrowband bit-rates defined for Speex, ranging from
  All frame-based parameters are packed before sub-frame parameters.
  The parameters for a certain sub-frame are all packed before the following
  sub-frame is packed.
+ Note that the 
+\begin_inset Quotes eld
+\end_inset 
+
+OL
+\begin_inset Quotes erd
+\end_inset 
+
+ in the parameter description means the the parameter is an open loop estimation
+ based on the whole frame.
 \layout Standard
 
 
 \begin_inset Float table
-placement htbp
+placement h
 wide true
 collapsed false
 
@@ -592,7 +889,7 @@ collapsed false
 
 
 \begin_inset  Tabular
-<lyxtabular version="3" rows="11" columns="9">
+<lyxtabular version="3" rows="12" columns="11">
 <features>
 <column alignment="center" valignment="top" leftline="true" width="0pt">
 <column alignment="center" valignment="top" leftline="true" width="0pt">
@@ -602,6 +899,8 @@ collapsed false
 <column alignment="center" valignment="top" leftline="true" width="0pt">
 <column alignment="center" valignment="top" leftline="true" width="0pt">
 <column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="center" valignment="top" leftline="true" width="0pt">
 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
 <row topline="true" bottomline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -676,6 +975,22 @@ Update rate
 6
 \end_inset 
 </cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+7
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+8
+\end_inset 
+</cell>
 </row>
 <row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -683,7 +998,7 @@ Update rate
 
 \layout Standard
 
-Mode ID
+Wideband bit
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -699,7 +1014,7 @@ frame
 
 \layout Standard
 
-4
+1
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -707,7 +1022,7 @@ frame
 
 \layout Standard
 
-4
+1
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -715,7 +1030,7 @@ frame
 
 \layout Standard
 
-4
+1
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -723,7 +1038,7 @@ frame
 
 \layout Standard
 
-4
+1
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -731,7 +1046,7 @@ frame
 
 \layout Standard
 
-4
+1
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -739,7 +1054,7 @@ frame
 
 \layout Standard
 
-4
+1
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -747,33 +1062,33 @@ frame
 
 \layout Standard
 
-4
+1
 \end_inset 
 </cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-LSP
+1
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-frame
+1
 \end_inset 
 </cell>
+</row>
+<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-0
+Mode ID
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -781,7 +1096,7 @@ frame
 
 \layout Standard
 
-18
+frame
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -789,7 +1104,7 @@ frame
 
 \layout Standard
 
-18
+4
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -797,7 +1112,7 @@ frame
 
 \layout Standard
 
-18
+4
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -805,7 +1120,7 @@ frame
 
 \layout Standard
 
-18
+4
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -813,57 +1128,57 @@ frame
 
 \layout Standard
 
-30
+4
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-30
+4
 \end_inset 
 </cell>
-</row>
-<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-OL pitch
+4
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-frame
+4
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-0
+4
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-7
+4
 \end_inset 
 </cell>
+</row>
+<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-7
+LSP
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -871,7 +1186,7 @@ frame
 
 \layout Standard
 
-0
+frame
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -887,25 +1202,23 @@ frame
 
 \layout Standard
 
-0
+18
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-0
+18
 \end_inset 
 </cell>
-</row>
-<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-OL pitch gain
+18
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -913,7 +1226,7 @@ OL pitch gain
 
 \layout Standard
 
-frame
+18
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -921,39 +1234,41 @@ frame
 
 \layout Standard
 
-0
+30
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-4
+30
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-0
+30
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-0
+18
 \end_inset 
 </cell>
+</row>
+<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-0
+OL pitch
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -961,10 +1276,10 @@ frame
 
 \layout Standard
 
-0
+frame
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
@@ -972,14 +1287,12 @@ frame
 0
 \end_inset 
 </cell>
-</row>
-<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-Exc gain
+7
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -987,7 +1300,7 @@ Exc gain
 
 \layout Standard
 
-frame
+7
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1003,7 +1316,7 @@ frame
 
 \layout Standard
 
-5
+0
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1011,49 +1324,57 @@ frame
 
 \layout Standard
 
-5
+0
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-5
+0
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-5
+0
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+7
 \end_inset 
 </cell>
+</row>
+<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-5
+OL pitch gain
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-5
+frame
 \end_inset 
 </cell>
-</row>
-<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-Fine pitch
+0
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1061,7 +1382,7 @@ Fine pitch
 
 \layout Standard
 
-sub-frame
+4
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1093,23 +1414,23 @@ sub-frame
 
 \layout Standard
 
-7
+0
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-7
+0
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-7
+0
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -1117,7 +1438,7 @@ sub-frame
 
 \layout Standard
 
-7
+4
 \end_inset 
 </cell>
 </row>
@@ -1127,7 +1448,7 @@ sub-frame
 
 \layout Standard
 
-Pitch gain
+OL Exc gain
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1135,7 +1456,7 @@ Pitch gain
 
 \layout Standard
 
-sub-frame
+frame
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1151,7 +1472,7 @@ sub-frame
 
 \layout Standard
 
-0
+5
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1183,7 +1504,7 @@ sub-frame
 
 \layout Standard
 
-7
+5
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -1191,7 +1512,23 @@ sub-frame
 
 \layout Standard
 
-7
+5
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+5
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+5
 \end_inset 
 </cell>
 </row>
@@ -1201,7 +1538,7 @@ sub-frame
 
 \layout Standard
 
-Innovation gain
+Fine pitch
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1225,7 +1562,7 @@ sub-frame
 
 \layout Standard
 
-3
+0
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1241,7 +1578,7 @@ sub-frame
 
 \layout Standard
 
-3
+7
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1249,7 +1586,7 @@ sub-frame
 
 \layout Standard
 
-3
+7
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1257,7 +1594,7 @@ sub-frame
 
 \layout Standard
 
-3
+7
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -1265,17 +1602,33 @@ sub-frame
 
 \layout Standard
 
-3
+7
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+7
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0
 \end_inset 
 </cell>
 </row>
-<row topline="true" bottomline="true">
+<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-Innovation VQ
+Pitch gain
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1307,7 +1660,7 @@ sub-frame
 
 \layout Standard
 
-16
+5
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1315,7 +1668,7 @@ sub-frame
 
 \layout Standard
 
-20
+5
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1323,7 +1676,7 @@ sub-frame
 
 \layout Standard
 
-35
+5
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1331,7 +1684,7 @@ sub-frame
 
 \layout Standard
 
-48
+7
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -1339,33 +1692,33 @@ sub-frame
 
 \layout Standard
 
-64
+7
 \end_inset 
 </cell>
-</row>
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-Total
+7
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-frame
+0
 \end_inset 
 </cell>
+</row>
+<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-4
+Innovation gain
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1373,7 +1726,7 @@ frame
 
 \layout Standard
 
-50
+sub-frame
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1381,7 +1734,7 @@ frame
 
 \layout Standard
 
-118
+0
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1389,7 +1742,7 @@ frame
 
 \layout Standard
 
-167
+1
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1397,7 +1750,7 @@ frame
 
 \layout Standard
 
-227
+0
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1405,93 +1758,67 @@ frame
 
 \layout Standard
 
-299
+1
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-363
+1
 \end_inset 
 </cell>
-</row>
-</lyxtabular>
-
-\end_inset 
-
-
-\layout Caption
-
-Bit allocation for narrowband modes
-\begin_inset LatexCommand \label{cap:bits-narrowband}
-
-\end_inset 
-
-
-\end_inset 
-
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
 \layout Standard
 
-So far, no MOS (mean opinion score) subjective evaluation has been performed
- for Speex.
- In order to give an idea of the quality achivable with it, table 
-\begin_inset LatexCommand \ref{cap:quality_vs_bps}
-
+3
 \end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
- presents my own subjective opinion on it.
- It sould be noted that different people will perceive the quality differently
- and that the person that designed the codec often has a bias (one way or
- another) when it comes to subjective evaluation.
- Last thing, it should be noted that for most codecs (including Speex) encoding
- quality sometimes varies depending on the input.
 \layout Standard
 
-
-\begin_inset Float table
-placement htbp
-wide true
-collapsed false
+3
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
 \layout Standard
 
-
-\begin_inset  Tabular
-<lyxtabular version="3" rows="8" columns="3">
-<features>
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+3
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-Mode
+0
 \end_inset 
 </cell>
+</row>
+<row topline="true" bottomline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-Bitrate (bps)
+Innovation VQ
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-Quality
+sub-frame
 \end_inset 
 </cell>
-</row>
-<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
@@ -1505,25 +1832,23 @@ Quality
 
 \layout Standard
 
-200
+0
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-No sound (VBR only)
+16
 \end_inset 
 </cell>
-</row>
-<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-1
+20
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1531,33 +1856,31 @@ No sound (VBR only)
 
 \layout Standard
 
-2,500
+35
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-Comfort noise only (VBR only)
+48
 \end_inset 
 </cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-2
+64
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-5,900
+96
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -1565,17 +1888,17 @@ Comfort noise only (VBR only)
 
 \layout Standard
 
-Very noticeable artifacts/noise, good intelligibility
+10
 \end_inset 
 </cell>
 </row>
-<row topline="true">
+<row topline="true" bottomline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-3
+Total
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1583,25 +1906,23 @@ Very noticeable artifacts/noise, good intelligibility
 
 \layout Standard
 
-8,350
+frame
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-Artifacts/noise often noticeable
+5
 \end_inset 
 </cell>
-</row>
-<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-4
+43
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1609,25 +1930,23 @@ Artifacts/noise often noticeable
 
 \layout Standard
 
-11,350
+119
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-Artifacts usually noticeable only with headphones
+160
 \end_inset 
 </cell>
-</row>
-<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-5
+220
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1635,7 +1954,7 @@ Artifacts usually noticeable only with headphones
 
 \layout Standard
 
-14,950
+300
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -1643,25 +1962,15 @@ Artifacts usually noticeable only with headphones
 
 \layout Standard
 
-Need good headphones to tell the difference
-\end_inset 
-</cell>
-</row>
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-6
+364
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-18,150
+492
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -1669,7 +1978,7 @@ Need good headphones to tell the difference
 
 \layout Standard
 
-Hard to tell the difference even with good headphones
+79
 \end_inset 
 </cell>
 </row>
@@ -1680,8 +1989,8 @@ Hard to tell the difference even with good headphones
 
 \layout Caption
 
-Quality versus bit-rate
-\begin_inset LatexCommand \label{cap:quality_vs_bps}
+Bit allocation for narrowband modes
+\begin_inset LatexCommand \label{cap:bits-narrowband}
 
 \end_inset 
 
@@ -1689,130 +1998,102 @@ Quality versus bit-rate
 \end_inset 
 
 
-\layout Subsection
-
-Perceptual enhancement
 \layout Standard
 
-This part of the codec only applies to the decoder and can even be changed
- without affecting inter-operability.
- For that reason, the implementation provided should only be considered
- as a reference implementation.
-\layout Section
+So far, no MOS (Mean Opinion Score
+\begin_inset LatexCommand \index{mean opinion score}
 
-Speex wideband mode (sub-band CELP)
-\layout Standard
+\end_inset 
 
-For wideband, the Speex approach uses a 
-\emph on 
-q
-\emph default 
-uadrature 
-\emph on 
-m
-\emph default 
-irror 
-\emph on 
-f
-\emph default 
-ilter (QMF) to split the band in two.
- The 16 kHz signal is thus divided into two 8 kHz signals, one representing
- the low band (0-4 kHz), the other the high band (4-8 kHz).
- The low band is encoded with the narrowband mode described in section 
-\begin_inset LatexCommand \ref{sec:Speex-narrowband-mode}
+) subjective evaluation has been performed for Speex.
+ In order to give an idea of the quality achivable with it, table 
+\begin_inset LatexCommand \ref{cap:quality_vs_bps}
 
 \end_inset 
 
- in such a way that the resulting 
-\begin_inset Quotes eld
-\end_inset 
+ presents my own subjective opinion on it.
+ It sould be noted that different people will perceive the quality differently
+ and that the person that designed the codec often has a bias (one way or
+ another) when it comes to subjective evaluation.
+ Last thing, it should be noted that for most codecs (including Speex) encoding
+ quality sometimes varies depending on the input.
+ Note that the complexity is only approximate (withing 0.5 mflops and using
+ the lowers complexity setting).
+ Decoding requires approximately 0.5 mflops
+\begin_inset LatexCommand \index{complexity}
 
-embedded narrowband bit-stream
-\begin_inset Quotes erd
 \end_inset 
 
- can also be decoded with the narrowband decoder.
- Since the low band encoding has already been described only the high band
- encoding is described in this section.
-\layout Subsection
-
-Linear Prediction
+ in most modes (1 mflops with perceptual enhancement).
 \layout Standard
 
-The linear prediction part used for the high-band is very similar to what
- is done for narrowband.
- The only difference is that we use only 12 bits to encode the high-band
- LSP's.
-\layout Subsection
 
-Pitch Prediction
+\begin_inset Float table
+placement h
+wide true
+collapsed false
+
 \layout Standard
 
-That part is easy: there's no pitch prediction for the high-band.
- There are two reasons for that.
- First, there is usually little harmonic structure in this band (above 4
- kHz).
- Second, it would be very hard to implement since the QMF folds the 4-8
- kHz band into 4-0 kHz (reversing the frequency axis), which means that
- the location of the harmonics are no longer at multiples of the fundamental
- (pitch).
-\layout Subsection
 
-Excitation Quantization
+\begin_inset  Tabular
+<lyxtabular version="3" rows="17" columns="4">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
 \layout Standard
 
-The high-band excitation is coded in the same way as for narrowband.
-\layout Subsection
+Mode
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-Bit allocation
 \layout Standard
 
-For the wideband mode, all the narrowband frame is packed before the high-band
- is encoded.
- The narrowband part of the bit-stream is as defined in table 
-\begin_inset LatexCommand \ref{cap:bits-narrowband}
+Bit-rate
+\begin_inset LatexCommand \index{bit-rate}
 
 \end_inset 
 
-.
- The high-band follows, as described in table 
-\begin_inset LatexCommand \ref{cap:bits-wideband}
-
+ (bps)
 \end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-.
- This also means that a wideband frame may be correctly decoded by a narrowband
- decoder with the only caveat that if more than one frame is packed in the
- same packet, the decoder will need to skip the high-band parts in order
- to sync with the bit-stream.
 \layout Standard
 
+mflops
+\begin_inset LatexCommand \index{complexity}
 
-\begin_inset Float table
-placement htbp
-wide true
-collapsed false
+\end_inset 
 
-\layout Standard
 
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
-\begin_inset  Tabular
-<lyxtabular version="3" rows="6" columns="6">
-<features>
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
-<row topline="true" bottomline="true">
+\layout Standard
+
+Quality/description
+\end_inset 
+</cell>
+</row>
+<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-Parameter
+0
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1820,7 +2101,7 @@ Parameter
 
 \layout Standard
 
-Update rate
+250
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1828,9 +2109,19 @@ Update rate
 
 \layout Standard
 
-0
+N/A
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+No sound (VBR only)
 \end_inset 
 </cell>
+</row>
+<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
@@ -1844,7 +2135,7 @@ Update rate
 
 \layout Standard
 
-2
+2,150
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1852,7 +2143,15 @@ Update rate
 
 \layout Standard
 
-3
+6
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Vocoder (mostly for comfort noise)
 \end_inset 
 </cell>
 </row>
@@ -1862,7 +2161,7 @@ Update rate
 
 \layout Standard
 
-Mode ID
+2
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1870,7 +2169,7 @@ Mode ID
 
 \layout Standard
 
-frame
+5,950
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1878,9 +2177,19 @@ frame
 
 \layout Standard
 
-3
+9
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Very noticeable artifacts/noise, good intelligibility
 \end_inset 
 </cell>
+</row>
+<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
@@ -1894,7 +2203,7 @@ frame
 
 \layout Standard
 
-3
+8,000
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1902,7 +2211,15 @@ frame
 
 \layout Standard
 
-3
+10
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Artifacts/noise sometimes noticeable
 \end_inset 
 </cell>
 </row>
@@ -1912,7 +2229,7 @@ frame
 
 \layout Standard
 
-LSP
+4
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1920,7 +2237,7 @@ LSP
 
 \layout Standard
 
-frame
+11,000
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1928,15 +2245,25 @@ frame
 
 \layout Standard
 
-0
+14
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Artifacts usually noticeable only with headphones
 \end_inset 
 </cell>
+</row>
+<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-12
+5
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1944,7 +2271,7 @@ frame
 
 \layout Standard
 
-12
+15,000
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1952,7 +2279,15 @@ frame
 
 \layout Standard
 
-12
+11
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Need good headphones to tell the difference
 \end_inset 
 </cell>
 </row>
@@ -1962,7 +2297,7 @@ frame
 
 \layout Standard
 
-Excitation gain
+6
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1970,7 +2305,7 @@ Excitation gain
 
 \layout Standard
 
-sub-frame
+18,200
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1978,23 +2313,25 @@ sub-frame
 
 \layout Standard
 
-0
+17.5
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-5
+Hard to tell the difference even with good headphones
 \end_inset 
 </cell>
+</row>
+<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-4
+7
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -2002,33 +2339,33 @@ sub-frame
 
 \layout Standard
 
-4
+24,600
 \end_inset 
 </cell>
-</row>
-<row topline="true" bottomline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-Excitation VQ
+14.5
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-sub-frame
+Completely transparent for voice, good quality music
 \end_inset 
 </cell>
+</row>
+<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-0
+8
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -2036,7 +2373,7 @@ sub-frame
 
 \layout Standard
 
-0
+3,950
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -2044,25 +2381,25 @@ sub-frame
 
 \layout Standard
 
-20
+-
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-40
+Very noticeable artifacts/noise, good intelligibility
 \end_inset 
 </cell>
 </row>
-<row topline="true" bottomline="true">
+<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-Total
+9
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -2070,7 +2407,7 @@ Total
 
 \layout Standard
 
-frame
+N/A
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -2078,23 +2415,25 @@ frame
 
 \layout Standard
 
-3
+N/A
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-35
+reserved
 \end_inset 
 </cell>
+</row>
+<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-111
+10
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -2102,487 +2441,2322 @@ frame
 
 \layout Standard
 
-191
+N/A
 \end_inset 
 </cell>
-</row>
-</lyxtabular>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
 
+N/A
 \end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
+\layout Standard
 
-\layout Caption
+reserved
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-Bit allocation for high-band in wideband mode
-\begin_inset LatexCommand \label{cap:bits-wideband}
+\layout Standard
 
+11
 \end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
+\layout Standard
 
+N/A
 \end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
+\layout Standard
 
-\layout Section
+N/A
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
-Command-line encoder/decoder
 \layout Standard
 
-The base Speex distribution includes a command-line encoder (
-\emph on 
-speexenc
-\emph default 
-) and decoder (
-\emph on 
-speexdec
-\emph default 
-).
-\layout Subsection
-
+reserved
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-\emph on 
-speexenc
 \layout Standard
 
-The encoder takes the following options:
-\layout Description
+12
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
---narrowband\SpecialChar ~
-(-n) Tells Speex to treat the input as narrowband (8 kHz).
- This is the default
-\layout Description
+\layout Standard
 
---wideband\SpecialChar ~
-(-w) Tells Speex to treat the input as wideband (16 kHz)
-\layout Description
+N/A
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
---quality\SpecialChar ~
-n Set the encoding quality (0-10)
-\layout Description
+\layout Standard
 
---vbr Enable VBR (Variable Bit-Rate), disabled by default
-\layout Description
-
---nframes\SpecialChar ~
-n Pack n frames in each Ogg packet (this saves space at low bit-rates)
-\layout Description
+N/A
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
---comp\SpecialChar ~
-n Set encoding speed/quality tradeoff.
- The higher the value of n, the slower the encoding (default is 3)
-\layout Description
+\layout Standard
 
---help\SpecialChar ~
-(-h) Print the help
-\layout Description
+reserved
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
---version\SpecialChar ~
-(-v) Pring version information
-\layout Subsection
+\layout Standard
 
+13
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-\emph on 
-speexdec
 \layout Standard
 
-The decoder takes the following options:
-\layout Description
+N/A
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
---enh enable post-filter
-\layout Description
+\layout Standard
 
---no-enh disable post-filter (default)
-\layout Description
+N/A
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
---help\SpecialChar ~
-(-h) Print the help
-\layout Description
+\layout Standard
 
---version\SpecialChar ~
-(-v) Pring version information
-\layout Section
+Application-defined, interpreted by callback or skipped
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-Programming with Speex (the libspeex API)
-\layout Subsection
+\layout Standard
+
+14
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-Encoding
 \layout Standard
 
-In order to encode speech using Speex, you first need to:
-\layout LyX-Code
+N/A
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-#include <speex.h>
 \layout Standard
 
-You then need to declare a Speex bit-packing struct
-\layout LyX-Code
+N/A
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
-SpeexBits bits;
 \layout Standard
 
-and a Speex encoder state
-\layout LyX-Code
+Speex in-band signaling
+\end_inset 
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-void *enc_state;
 \layout Standard
 
-The two are initialized by:
-\layout LyX-Code
+15
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-speex_bits_init(&bits);
-\layout LyX-Code
+\layout Standard
+
+N/A
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-enc_state = speex_encoder_init(&speex_nb_mode);
 \layout Standard
 
-For wideband coding, 
-\emph on 
-speex_nb_mode
-\emph default 
- will be replaced by 
-\emph on 
-speex_wb_mode
-\emph default 
-.
- In most cases, you will need to know the frame size used by the mode you
- are using.
- You can get that value in the 
-\emph on 
-frame_size
-\emph default 
- variable with:
-\layout LyX-Code
+N/A
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
-speex_encoder_ctl(enc_state,SPEEX_GET_FRAME_SIZE,&frame_size);
 \layout Standard
 
-Once the initialization is done, for every input frame:
-\layout LyX-Code
+Terminator code
+\end_inset 
+</cell>
+</row>
+</lyxtabular>
 
-speex_bits_reset(&bits);
-\layout LyX-Code
+\end_inset 
 
-speex_encode(enc_state, input_frame, &bits);
-\layout LyX-Code
 
-nbBytes = speex_bits_write(&bits, byte_ptr, MAX_NB_BYTES);
-\layout Standard
+\layout Caption
 
-where 
-\emph on 
-input_frame
-\emph default 
- is a 
-\emph on 
-(float *)
-\emph default 
- pointing to the beginning of a speech frame, 
-\emph on 
-byte_ptr
-\emph default 
- is a 
-\emph on 
-(char *)
-\emph default 
- where the encoded frame will be written, 
-\emph on 
-MAX_NB_BYTES
-\emph default 
- is the maximum number of bytes that can be written to 
-\emph on 
-byte_ptr
-\emph default 
- without causing an overflow and 
-\emph on 
-nbBytes
-\emph default 
- is the number of bytes actually written to 
-\emph on 
-byte_ptr
-\emph default 
- (the encoded size in bytes).
- Before calling speex_bits_write, it is possible to find the number of bytes
- that need to be written by calling 
-\family typewriter 
-speex_bits_nbytes(&bits)
-\family default 
-, which returns a number of bytes.
-\layout Standard
+Quality versus bit-rate
+\begin_inset LatexCommand \label{cap:quality_vs_bps}
 
-After you're done with the encoding, free all resources with:
-\layout LyX-Code
+\end_inset 
 
-speex_bits_destroy(&bits);
-\layout LyX-Code
 
-speex_encoder_destroy(&enc_state);
-\layout Standard
+\end_inset 
+
 
-That's about it for the encoder.
 \layout Subsection
 
-Decoding
-\layout Standard
+Perceptual enhancement
+\begin_inset LatexCommand \index{perceptual enhancement}
+
+\end_inset 
 
-In order to encode speech using Speex, you first need to:
-\layout LyX-Code
 
-#include <speex.h>
 \layout Standard
 
-You then need to declare a Speex bit-packing struct
-\layout LyX-Code
+This part of the codec only applies to the decoder and can even be changed
+ without affecting inter-operability.
+ For that reason, the implementation provided and described here should
+ only be considered as a reference implementation.
+ The enhancement system is devided in two parts.
+ First, the synthesis filter 
+\begin_inset Formula $S(z)=1/A(z)$
+\end_inset 
 
-SpeexBits bits;
-\layout Standard
+ is replaced by an enhanced filter
+\begin_inset Formula \[
+S'(z)=\frac{A\left(z/a_{2}\right)A\left(z/a_{3}\right)}{A\left(z\right)A\left(z/a_{1}\right)}\]
 
-and a Speex encoder state
-\layout LyX-Code
+\end_inset 
 
-void *dec_state;
-\layout Standard
+where 
+\begin_inset Formula $a_{1}$
+\end_inset 
 
-The two are initialized by:
-\layout LyX-Code
+ and 
+\begin_inset Formula $a_{2}$
+\end_inset 
+
+ depend on the mode in use and 
+\begin_inset Formula $a_{3}=\frac{1}{r}\left(1-\frac{1-ra_{1}}{1-ra_{2}}\right)$
+\end_inset 
+
+ with 
+\begin_inset Formula $r=.9$
+\end_inset 
+
+.
+ The second part of the enhancement consists of using a comb filter to enhance
+ the pitch in the excitation domain.
+\layout Section
+\pagebreak_top 
+Speex wideband mode (sub-band CELP)
+\begin_inset LatexCommand \index{wideband}
+
+\end_inset 
 
-speex_bits_init(&bits);
-\layout LyX-Code
 
-dec_state = speex_decoder_init(&speex_nb_mode);
 \layout Standard
 
-For wideband decoding, 
+For wideband, the Speex approach uses a 
 \emph on 
-speex_nb_mode
+q
 \emph default 
- will be replaced by 
+uadrature 
 \emph on 
-speex_wb_mode
+m
 \emph default 
-.
- You can get that value in the 
+irror 
 \emph on 
-frame_size
+f
 \emph default 
- variable with:
-\layout LyX-Code
+ilter
+\begin_inset LatexCommand \index{quadrature mirror filter}
 
-speex_decoder_ctl(dec_state, SPEEX_GET_FRAME_SIZE, &frame_size); 
-\layout Standard
-
-There is also a parameter that can be set for the decoder: whether or not
- to use a perceptual post-filter.
- This can be set by: 
-\layout LyX-Code
+\end_inset 
+
+ (QMF) to split the band in two.
+ The 16 kHz signal is thus divided into two 8 kHz signals, one representing
+ the low band (0-4 kHz), the other the high band (4-8 kHz).
+ The low band is encoded with the narrowband mode described in section 
+\begin_inset LatexCommand \ref{sec:Speex-narrowband-mode}
+
+\end_inset 
+
+ in such a way that the resulting 
+\begin_inset Quotes eld
+\end_inset 
+
+embedded narrowband bit-stream
+\begin_inset Quotes erd
+\end_inset 
+
+ can also be decoded with the narrowband decoder.
+ Since the low band encoding has already been described only the high band
+ encoding is described in this section.
+\layout Subsection
+
+Linear Prediction
+\layout Standard
+
+The linear prediction part used for the high-band is very similar to what
+ is done for narrowband.
+ The only difference is that we use only 12 bits to encode the high-band
+ LSP's using a multi-stage vector quantizer (MSVQ).
+ The first level quantizes the 10 coefficients with 6 bits and the error
+ is then quantized using 6 bits too.
+\layout Subsection
+
+Pitch Prediction
+\layout Standard
+
+That part is easy: there's no pitch prediction for the high-band.
+ There are two reasons for that.
+ First, there is usually little harmonic structure in this band (above 4
+ kHz).
+ Second, it would be very hard to implement since the QMF folds the 4-8
+ kHz band into 4-0 kHz (reversing the frequency axis), which means that
+ the location of the harmonics are no longer at multiples of the fundamental
+ (pitch).
+\layout Subsection
+
+Excitation Quantization
+\layout Standard
+
+The high-band excitation is coded in the same way as for narrowband.
+\layout Subsection
+
+Bit allocation
+\layout Standard
+
+For the wideband mode, all the narrowband frame is packed before the high-band
+ is encoded.
+ The narrowband part of the bit-stream is as defined in table 
+\begin_inset LatexCommand \ref{cap:bits-narrowband}
+
+\end_inset 
+
+.
+ The high-band follows, as described in table 
+\begin_inset LatexCommand \ref{cap:bits-wideband}
+
+\end_inset 
+
+.
+ This also means that a wideband frame may be correctly decoded by a narrowband
+ decoder with the only caveat that if more than one frame is packed in the
+ same packet, the decoder will need to skip the high-band parts in order
+ to sync with the bit-stream.
+\layout Standard
+
+
+\begin_inset Float table
+placement h
+wide true
+collapsed false
+
+\layout Standard
+
+
+\begin_inset  Tabular
+<lyxtabular version="3" rows="7" columns="7">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Parameter
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Update rate
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+1
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+2
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+3
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+4
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Wideband bit
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+frame
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+1
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+1
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+1
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+1
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+1
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Mode ID
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+frame
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+3
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+3
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+3
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+3
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+3
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+LSP
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+frame
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+12
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+12
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+12
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+12
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Excitation gain
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+sub-frame
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+5
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+4
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+4
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+4
+\end_inset 
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Excitation VQ
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+sub-frame
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+20
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+40
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+80
+\end_inset 
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Total
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+frame
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+4
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+36
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+112
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+192
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+352
+\end_inset 
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset 
+
+
+\layout Caption
+
+Bit allocation for high-band in wideband mode
+\begin_inset LatexCommand \label{cap:bits-wideband}
+
+\end_inset 
+
+
+\end_inset 
+
+
+\layout Standard
+
+
+\begin_inset ERT
+status Open
+
+\layout Standard
+
+\backslash 
+clearpage
+\end_inset 
+
+
+\layout Section
+\pagebreak_top 
+Feature description
+\layout Standard
+
+This section explains the main Speex features, as well as some concepts
+ in speech coding that help better understand the next sections.
+\layout Subsection*
+
+Sampling rate
+\begin_inset LatexCommand \index{sampling rate}
+
+\end_inset 
+
+
+\layout Standard
+
+Speex is mainly designed for 3 different sampling rates: 8 kHz, 16 kHz,
+ and 32 kHz.
+ These are respectively refered to as narrowband
+\begin_inset LatexCommand \index{narrowband}
+
+\end_inset 
+
+, wideband
+\begin_inset LatexCommand \index{wideband}
+
+\end_inset 
+
+ and ultra-wideband
+\begin_inset LatexCommand \index{ultra-wideband}
+
+\end_inset 
+
+.
+\layout Subsection*
+
+Quality
+\begin_inset LatexCommand \index{quality}
+
+\end_inset 
+
+
+\layout Standard
+
+Speex encoding is controlled most of the time by a quality parameter that
+ range from 0 to 10.
+ In constant bit-rate
+\begin_inset LatexCommand \index{constant bit-rate}
+
+\end_inset 
+
+ (CBR) operation, the quality parameter is an integer, while for variable
+ bit-rate (VBR), the parameter is a float.
+\layout Subsection*
+
+Complexity
+\begin_inset LatexCommand \index{complexity}
+
+\end_inset 
+
+ (variable)
+\layout Standard
+
+With Speex, it is possible to vary the complexity allowed for the encoder.
+ This is done by controlling how the search is performed with an integer
+ ranging from 1 to 10 in a way that's similar to the -1 to -9 options to
+\emph on 
+gzip
+\emph default 
+ and 
+\emph on 
+bzip2
+\emph default 
+ compression utilities.
+ For normal use, the noise level at complexity 1is between 1 and 2 dB higher
+ than at complexity 10, but the CPU requirements for complexity 10 is about
+ 5 time higher than for complexity 1.
+ In practice, the best trade-off is between complexity 2 and 4, though higher
+ settings are often useful when encoding non-speech sounds like DTMF
+\begin_inset LatexCommand \index{DTMF}
+
+\end_inset 
+
+ tones.
+\layout Subsection*
+
+Variable Bit-Rate
+\begin_inset LatexCommand \index{variable bit-rate}
+
+\end_inset 
+
+ (VBR)
+\layout Standard
+
+Variable bit-rate (VBR) allows a codec to change its bit-rate dynamically
+ to adapt to the 
+\begin_inset Quotes eld
+\end_inset 
+
+difficulty
+\begin_inset Quotes erd
+\end_inset 
+
+ of the audio being encoded.
+ In the example of Speex, sounds like vowels and high-energy transients
+ require a higher bit-rate to achieve good quality, while fricatives (e.g.
+ s,f sounds) can be coded adequately with less bits.
+ For this reason, VBR can achive lower bit-rate for the same quality, or
+ a better quality for a certain bit-rate.
+ Despite its advantages, VBR has two main drawbacks: first, by only specifying
+ quality, there's no guaranty about the final average bit-rate.
+ Second, for some real-time applications like voice over IP (VoIP), what
+ counts is the maximum bit-rate, which must be low enough for the communication
+ channel.
+\layout Subsection*
+
+Average Bit-Rate
+\begin_inset LatexCommand \index{average bit-rate}
+
+\end_inset 
+
+ (ABR)
+\layout Standard
+
+Average bit-rate solves one of the problems of VBR, as it dynamically adjusts
+ VBR quality in order to meet a specific target bit-rate.
+ Because the quality/bit-rate is adjusted in real-time (open-loop), the
+ global quality will be slightly lower than that obtained be encoding in
+ VBR with exactly the right quality setting to meet the target average bit-rate.
+\layout Subsection*
+
+Voice Activity Detection
+\begin_inset LatexCommand \index{voice activity detection}
+
+\end_inset 
+
+ (VAD)
+\layout Standard
+
+When enabled, voice activity detection detects whether the audio being encoded
+ is speech or silence/background noise.
+ VAD is always implicitly activated when encoding in VBR, so the option
+ is only useful in non-VBR operation.
+ In this case, Speex detects non-speech periods and encode them with just
+ enough bits to reproduce the background noise.
+ This is called 
+\begin_inset Quotes eld
+\end_inset 
+
+comfort noise generation
+\begin_inset Quotes erd
+\end_inset 
+
+ (CNG).
+\layout Subsection*
+
+Discontinuous Transmission
+\begin_inset LatexCommand \index{discontinuous transmission}
+
+\end_inset 
+
+ (DTX)
+\layout Standard
+
+Discontinuous transmission is an addition to VAD operation, that allows
+ to stop transmitting completely when the background noise is stationnary.
+ In file-based operation, since we cannot just stop writing to the file,
+ only 5 bits are used for such frames (corresponding to 250 bps).
+\layout Subsection*
+
+Perceptual enhancement
+\begin_inset LatexCommand \index{perceptual enhancement}
+
+\end_inset 
+
+
+\layout Standard
+
+Perceptual enhancement is a part of the decoder which, when turned on, tries
+ to reduce (the perception of) the noise produced by the coding/decoding
+ process.
+ In most cases, perceptual enhancement make the sound further from the original
+\emph on 
+objectively
+\emph default 
+ (if you use SNR), but in the end it still 
+\emph on 
+sounds
+\emph default 
+ better (subjective improvement).
+\layout Subsection*
+
+Algorithmic delay
+\begin_inset LatexCommand \index{algorithmic delay}
+
+\end_inset 
+
+
+\layout Standard
+
+Every speech codec introduces a delay in the transmission.
+ For Speex, this delay is equal to the frame size, plus some amount of 
+\begin_inset Quotes eld
+\end_inset 
+
+look-ahead
+\begin_inset Quotes erd
+\end_inset 
+
+ required to process each frame.
+ In narrowband operation (8 kHz), the delay is 30 ms, while for wideband
+ (16 kHz), the delay is 34 ms.
+ These values don't account for the CPU time it takes to encode or decode
+ the frames.
+\layout Section
+\pagebreak_top 
+Command-line encoder/decoder
+\begin_inset LatexCommand \label{sec:Command-line-encoder/decoder}
+
+\end_inset 
+
+
+\layout Standard
+
+The base Speex distribution includes a command-line encoder (
+\emph on 
+speexenc
+\emph default 
+) and decoder (
+\emph on 
+speexdec
+\emph default 
+).
+ This section describes how to use these tools.
+\layout Subsection
+
+
+\emph on 
+speexenc
+\begin_inset LatexCommand \index{speexenc}
+
+\end_inset 
+
+
+\layout Standard
+
+The 
+\emph on 
+speexenc
+\emph default 
+ utility is used to create Speex files from raw PCM or wave files.
+ It can be used by calling: 
+\layout LyX-Code
+
+speexenc [options] input_file output_file
+\layout Standard
+
+The value '-' for input_file or output_file corresponds respectively to
+ stdin and stdout.
+ The valid options are:
+\layout Description
+
+--narrowband\SpecialChar ~
+(-n) Tell Speex to treat the input as narrowband (8 kHz).
+ This is the default
+\layout Description
+
+--wideband\SpecialChar ~
+(-w) Tell Speex to treat the input as wideband (16 kHz)
+\layout Description
+
+--ultra-wideband\SpecialChar ~
+(-u) Tell Speex to treat the input as 
+\begin_inset Quotes eld
+\end_inset 
+
+ultra-wideband
+\begin_inset Quotes erd
+\end_inset 
+
+ (32 kHz)
+\layout Description
+
+--quality\SpecialChar ~
+n Set the encoding quality (0-10), default is 8
+\layout Description
+
+--bitrate\SpecialChar ~
+n Encoding bit-rate (use bit-rate n or lower) 
+\layout Description
+
+--vbr Enable VBR (Variable Bit-Rate), disabled by default
+\layout Description
+
+--abr\SpecialChar ~
+n Enable ABR (Average Bit-Rate) at n kbps, disabled by default
+\layout Description
+
+--vad Enable VAD (Voice Activity Detection), disabled by default
+\layout Description
+
+--dtx Enable DTX (Discontinuous Transmission), disabled by default
+\layout Description
+
+--nframes\SpecialChar ~
+n Pack n frames in each Ogg packet (this saves space at low bit-rates)
+\layout Description
+
+--comp\SpecialChar ~
+n Set encoding speed/quality tradeoff.
+ The higher the value of n, the slower the encoding (default is 3)
+\layout Description
+
+-V Verbose operation, print bit-rate currently in use
+\layout Description
+
+--help\SpecialChar ~
+(-h) Print the help
+\layout Description
+
+--version\SpecialChar ~
+(-v) Print version information
+\layout Subsubsection*
+
+Speex comments
+\layout Description
+
+--comment Add the given string as an extra comment.
+ This may be used multiple times.
+\layout Description
+
+--author Author of this track.
+\layout Description
+
+--title Title for this track.
+\layout Subsubsection*
+
+Raw input options
+\layout Description
+
+--rate\SpecialChar ~
+n Sampling rate for raw input
+\layout Description
+
+--stereo Consider raw input as stereo 
+\layout Description
+
+--le Raw input is little-endian 
+\layout Description
+
+--be Raw input is big-endian 
+\layout Description
+
+--8bit Raw input is 8-bit unsigned 
+\layout Description
+
+--16bit Raw input is 16-bit signed 
+\layout Subsection
+
+
+\emph on 
+speexdec
+\begin_inset LatexCommand \index{speexdec}
+
+\end_inset 
+
+
+\layout Standard
+
+The 
+\emph on 
+speexdec
+\emph default 
+ utility is used to decode Speex files and can be used by calling: 
+\layout LyX-Code
+
+speexdec [options] speex_file [output_file]
+\layout Standard
+
+The value '-' for input_file or output_file corresponds respectively to
+ stdin and stdout.
+ Also, when no output_file is specified, the file is played to the soundcard.
+ The valid options are:
+\layout Description
+
+--enh enable post-filter (default)
+\layout Description
+
+--no-enh disable post-filter
+\layout Description
+
+--force-nb Force decoding in narrowband 
+\layout Description
+
+--force-wb Force decoding in wideband 
+\layout Description
+
+--force-uwb Force decoding in ultra-wideband 
+\layout Description
+
+--mono Force decoding in mono 
+\layout Description
+
+--stereo Force decoding in stereo 
+\layout Description
+
+--rate\SpecialChar ~
+n For decoding at n Hz sampling rate
+\layout Description
+
+--packet-loss\SpecialChar ~
+n Simulate n % random packet loss
+\layout Description
+
+-V Verbose operation, print bit-rate currently in use
+\layout Description
+
+--help\SpecialChar ~
+(-h) Print the help
+\layout Description
+
+--version\SpecialChar ~
+(-v) Print version information
+\layout Section
+\pagebreak_top 
+Programming with Speex (the libspeex
+\begin_inset LatexCommand \index{libspeex}
+
+\end_inset 
+
+ API
+\begin_inset LatexCommand \index{API}
+
+\end_inset 
+
+)
+\layout Subsection
+
+Encoding
+\layout Standard
+
+In order to encode speech using Speex, you first need to:
+\layout LyX-Code
+
+#include <speex.h>
+\layout Standard
+
+You then need to declare a Speex bit-packing struct
+\layout LyX-Code
+
+SpeexBits bits;
+\layout Standard
+
+and a Speex encoder state
+\layout LyX-Code
+
+void *enc_state;
+\layout Standard
+
+The two are initialized by:
+\layout LyX-Code
+
+speex_bits_init(&bits);
+\layout LyX-Code
+
+enc_state = speex_encoder_init(&speex_nb_mode);
+\layout Standard
+
+For wideband coding, 
+\emph on 
+speex_nb_mode
+\emph default 
+ will be replaced by 
+\emph on 
+speex_wb_mode
+\emph default 
+.
+ In most cases, you will need to know the frame size used by the mode you
+ are using.
+ You can get that value in the 
+\emph on 
+frame_size
+\emph default 
+ variable with:
+\layout LyX-Code
+
+speex_encoder_ctl(enc_state,SPEEX_GET_FRAME_SIZE,&frame_size);
+\layout Standard
+
+Once the initialization is done, for every input frame:
+\layout LyX-Code
+
+speex_bits_reset(&bits);
+\layout LyX-Code
+
+speex_encode(enc_state, input_frame, &bits);
+\layout LyX-Code
+
+nbBytes = speex_bits_write(&bits, byte_ptr, MAX_NB_BYTES);
+\layout Standard
+
+where 
+\emph on 
+input_frame
+\emph default 
+ is a 
+\emph on 
+(float *)
+\emph default 
+ pointing to the beginning of a speech frame, 
+\emph on 
+byte_ptr
+\emph default 
+ is a 
+\emph on 
+(char *)
+\emph default 
+ where the encoded frame will be written, 
+\emph on 
+MAX_NB_BYTES
+\emph default 
+ is the maximum number of bytes that can be written to 
+\emph on 
+byte_ptr
+\emph default 
+ without causing an overflow and 
+\emph on 
+nbBytes
+\emph default 
+ is the number of bytes actually written to 
+\emph on 
+byte_ptr
+\emph default 
+ (the encoded size in bytes).
+ Before calling speex_bits_write, it is possible to find the number of bytes
+ that need to be written by calling 
+\family typewriter 
+speex_bits_nbytes(&bits)
+\family default 
+, which returns a number of bytes.
+\layout Standard
+
+After you're done with the encoding, free all resources with:
+\layout LyX-Code
+
+speex_bits_destroy(&bits);
+\layout LyX-Code
+
+speex_encoder_destroy(enc_state);
+\layout Standard
+
+That's about it for the encoder.
+\layout Subsection
+
+Decoding
+\layout Standard
+
+In order to encode speech using Speex, you first need to:
+\layout LyX-Code
+
+#include <speex.h>
+\layout Standard
+
+You also need to declare a Speex bit-packing struct
+\layout LyX-Code
+
+SpeexBits bits;
+\layout Standard
+
+and a Speex encoder state
+\layout LyX-Code
+
+void *dec_state;
+\layout Standard
+
+The two are initialized by:
+\layout LyX-Code
+
+speex_bits_init(&bits);
+\layout LyX-Code
+
+dec_state = speex_decoder_init(&speex_nb_mode);
+\layout Standard
+
+For wideband decoding, 
+\emph on 
+speex_nb_mode
+\emph default 
+ will be replaced by 
+\emph on 
+speex_wb_mode
+\emph default 
+.
+ If you need to obtain the size of the frames that will be used by the decoder,
+ you can get that value in the 
+\emph on 
+frame_size
+\emph default 
+ variable with:
+\layout LyX-Code
+
+speex_decoder_ctl(dec_state, SPEEX_GET_FRAME_SIZE, &frame_size); 
+\layout Standard
+
+There is also a parameter that can be set for the decoder: whether or not
+ to use a perceptual post-filter.
+ This can be set by: 
+\layout LyX-Code
+
+speex_decoder_ctl(dec_state, SPEEX_SET_ENH, &enh); 
+\layout Standard
+
+where 
+\emph on 
+enh
+\emph default 
+ is an int that with value 0 to have the post-filter disabled and 1 to have
+ it enabled.
+\layout Standard
+
+Again, once the decoder initialization is done, for every input frame:
+\layout LyX-Code
+
+speex_bits_read_from(&bits, input_bytes, nbBytes);
+\layout LyX-Code
+
+speex_decode(st, &bits, output_frame);
+\layout Standard
+
+where input_bytes is a 
+\emph on 
+(char *)
+\emph default 
+ containing the bit-stream data received for a frame, 
+\emph on 
+nbBytes
+\emph default 
+ is the size (in bytes) of that bit-stream, and 
+\emph on 
+output_frame
+\emph default 
+ is a 
+\emph on 
+(float *)
+\emph default 
+ and points to the area where the decoded speech frame will be written.
+ A NULL value as the first argument indicates that we don't have the bits
+ for the current frame.
+ When a frame is lost, the Speex decoder will do its best to "guess" the
+ correct signal.
+\layout Standard
+
+After you're done with the decoding, free all resources with:
+\layout LyX-Code
+
+speex_bits_destroy(&bits);
+\layout LyX-Code
+
+speex_decoder_destroy(dec_state);
+\layout Subsection
+
+Codec Options (speex_*_ctl)
+\layout Standard
+
+The Speex encoder and decoder support many options and requests that can
+ be accessed through the 
+\emph on 
+speex_encoder_ctl
+\emph default 
+ and 
+\emph on 
+speex_decoder_ctl
+\emph default 
+ functions.
+ These functions are similar the the 
+\emph on 
+ioctl
+\emph default 
+ system call and their prototypes are:
+\layout LyX-Code
+
+void speex_encoder_ctl(void *encoder, int request, void *ptr);
+\layout LyX-Code
+
+void speex_decoder_ctl(void *encoder, int request, void *ptr);
+\layout Standard
+
+The different values of request allowed are (note that some only apply to
+ the encoder or the decoder):
+\layout Description
+
+SPEEX_SET_ENH** Set perceptual enhancer
+\begin_inset LatexCommand \index{perceptual enhancement}
+
+\end_inset 
+
+ to on (1) or off (0) (integer)
+\layout Description
+
+SPEEX_GET_ENH** Get perceptual enhancer status (integer)
+\layout Description
+
+SPEEX_GET_FRAME_SIZE Get the frame size used for the current mode (integer)
+\layout Description
+
+SPEEX_SET_QUALITY* Set the encoder speech quality (integer 0 to 10)
+\layout Description
+
+SPEEX_GET_QUALITY* Get the current encoder speech quality (integer 0 to
+ 10)
+\layout Description
+
+SPEEX_SET_MODE*
+\begin_inset Formula $\dagger $
+\end_inset 
+
+
+\layout Description
+
+SPEEX_GET_MODE*
+\begin_inset Formula $\dagger $
+\end_inset 
+
+
+\layout Description
+
+SPEEX_SET_LOW_MODE*
+\begin_inset Formula $\dagger $
+\end_inset 
+
+
+\layout Description
+
+SPEEX_GET_LOW_MODE*
+\begin_inset Formula $\dagger $
+\end_inset 
+
+
+\layout Description
+
+SPEEX_SET_HIGH_MODE*
+\begin_inset Formula $\dagger $
+\end_inset 
+
+
+\layout Description
+
+SPEEX_GET_HIGH_MODE*
+\begin_inset Formula $\dagger $
+\end_inset 
+
+
+\layout Description
+
+SPEEX_SET_VBR* Set variable bit-rate (VBR) to on (1) or off (0) (integer)
+\layout Description
+
+SPEEX_GET_VBR* Get variable bit-rate
+\begin_inset LatexCommand \index{variable bit-rate}
+
+\end_inset 
+
+ (VBR) status (integer)
+\layout Description
+
+SPEEX_SET_VBR_QUALITY* Set the encoder VBR speech quality (integer 0 to
+ 10)
+\layout Description
+
+SPEEX_GET_VBR_QUALITY* Get the current encoder VBR speech quality (integer
+ 0 to 10)
+\layout Description
+
+SPEEX_SET_COMPLEXITY* Set the CPU resources allowed for the encoder (integer
+ 1 to 10)
+\layout Description
+
+SPEEX_GET_COMPLEXITY* Get the CPU resources allowed for the encoder (integer
+ 1 to 10)
+\layout Description
+
+SPEEX_SET_BITRATE* Set the bit-rate to use to the closest value not exceeding
+ the parameter (integer in bps)
+\layout Description
+
+SPEEX_GET_BITRATE Get the current bit-rate in use (integer in bps)
+\layout Description
+
+SPEEX_SET_SAMPLING_RATE Set real sampling rate (integer in Hz)
+\layout Description
+
+SPEEX_GET_SAMPLING_RATE Get real sampling rate (integer in Hz)
+\layout Description
+
+SPEEX_RESET_STATE Reset the encoder/decoder state to its original state
+ (zeros all memories)
+\layout Description
+
+SPEEX_SET_VAD* Set voice activity detection
+\begin_inset LatexCommand \index{voice activity detection}
+
+\end_inset 
+
+ (VAD) to on (1) or off (0) (integer)
+\layout Description
+
+SPEEX_GET_VAD* Get voice activity detection (VAD) status (integer)
+\layout Description
+
+SPEEX_SET_DTX* Set discontinuous transmission
+\begin_inset LatexCommand \index{discontinuous transmission}
+
+\end_inset 
+
+ (DTX) to on (1) or off (0) (integer)
+\layout Description
+
+SPEEX_GET_DTX* Get discontinuous transmission (DTX) status (integer)
+\layout Description
+
+SPEEX_SET_ABR* Set average bit-rate
+\begin_inset LatexCommand \index{average bit-rate}
+
+\end_inset 
+
+ (ABR) to a value n in bits per second (integer in bps)
+\layout Description
+
+SPEEX_GET_ABR* Get average bit-rate (ABR) setting (integer in bps)
+\layout Description
+
+* applies only to the encoder
+\layout Description
+
+** applies only to the decoder
+\layout Description
+
+
+\begin_inset Formula $\dagger $
+\end_inset 
+
+ normally only used internally
+\layout Subsection
+
+Mode queries
+\layout Standard
+
+Speex modes have a querry system similar to the speex_encoder_ctl and speex_deco
+der_ctl calls.
+ Since modes are read-only, it is only possible to get information about
+ a particular mode.
+ The function used to do that is:
+\layout LyX-Code
+
+void speex_mode_query(SpeexMode *mode, int request, void *ptr);
+\layout Standard
+
+The admissible values for request are (unless otherwise note, the values
+ are returned through 
+\emph on 
+ptr
+\emph default 
+):
+\layout Description
+
+SPEEX_MODE_FRAME_SIZE Get the frame size (in samples) for the mode
+\layout Description
+
+SPEEX_SUBMODE_BITRATE Get the bit-rate for a submode number specified throught
+\emph on 
+ptr
+\emph default 
+ (integer in bps).
+\layout Subsection
+
+Packing and in-band signalling
+\begin_inset LatexCommand \index{in-band signalling}
+
+\end_inset 
+
+
+\layout Standard
+
+Sometimes it is desirable to pack more than one frame per packet (or other
+ basic unit of storage).
+ The proper way to do it is to call speex_encode 
+\begin_inset Formula $N$
+\end_inset 
+
+ times before writing the stream with speex_bits_write.
+ In cases where the number of frames is not determined by an out-of-band
+ mechanism, it is possible to include a terminator code.
+ That terminator consists of the code 15 (decimal) encoded with 5 bits,
+ as shown in figure 
+\begin_inset LatexCommand \ref{cap:quality_vs_bps}
+
+\end_inset 
+
+.
+\layout Standard
+
+It is also possible to send in-band 
+\begin_inset Quotes eld
+\end_inset 
+
+messages
+\begin_inset Quotes erd
+\end_inset 
+
+ to the other side.
+ All these messages are encoded as a 
+\begin_inset Quotes eld
+\end_inset 
+
+pseudo-frame
+\begin_inset Quotes erd
+\end_inset 
+
+ of mode 14 which contain a 4-bit message type code, followed by the message.
+ Table 
+\begin_inset LatexCommand \ref{cap:In-band-signalling-codes}
+
+\end_inset 
+
+ lists the available codes, their meaning and the size of the message that
+ follow.
+ Most of these messages are requests that are sent to the encoder or decoder
+ on the other end, which is free to comply or ignore them.
+ By default, all in-band messages are ignored.
+\layout Standard
+
+
+\begin_inset Float table
+placement htbp
+wide false
+collapsed false
+
+\layout Standard
+
+
+\begin_inset  Tabular
+<lyxtabular version="3" rows="17" columns="3">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+code
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Size (bits)
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Content
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+1
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Asks decoder to set perceptual enhancement off (0) or on(1)
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+1
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+1
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+reserved
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+2
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+4
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Asks encoder to switch to mode N
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+3
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+4
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Asks encoder to switch to mode N for low-band
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+4
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+4
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Asks encoder to switch to mode N for high-band
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+5
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-speex_decoder_ctl(dec_state, SPEEX_SET_PF, &pf); 
 \layout Standard
 
-where pf is an int that with value 0 to have the post-filter disabled and
- 1 to have it enabled.
+4
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
 \layout Standard
 
-Again, once the decoder initialization is done, for every input frame:
-\layout LyX-Code
+Asks encoder to switch to quality N for VBR
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-speex_bits_read_from(&bits, input_bytes, nbBytes);
-\layout LyX-Code
+\layout Standard
+
+6
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-speex_decode(st, &bits, output_frame, 0);
 \layout Standard
 
-where input_bytes is a 
-\emph on 
-(char *)
-\emph default 
- containing the bit-stream data received for a frame, 
-\emph on 
-nbBytes
-\emph default 
- is the size (in bytes) of that bit-stream, and 
-\emph on 
-output_frame
-\emph default 
- is a 
-\emph on 
-(float *)
-\emph default 
- and points to the area where the decoded speech frame will be written.
- The last argument indicates whether the frame we'd like to decode was lost.
- A value of 0 indicates the normal case where bits points to the bit of
- the current frame.
- A value of 1 indicates that we don't have the bits for the current frame,
- in which case the bits argument should be the same as the bits for the
- last correctly received frame.
- When a frame is lost, the Speex decoder will do its best to "guess" the
- correct signal.
-\layout Subsection
+4
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
-Codec Options (speex_*_ctl)
 \layout Standard
 
-The Speex encoder and decoder support many options and requests that can
- be accessed through the 
-\emph on 
-speex_encoder_ctl
-\emph default 
- and 
-\emph on 
-speex_decoder_ctl
-\emph default 
- functions.
- These functions are similar the the 
-\emph on 
-ioctl
-\emph default 
- system call and their prototypes are:
-\layout LyX-Code
+Request acknowloedge (0=no, 1=all, 2=only for in-band data)
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-void speex_encoder_ctl(void *encoder, int request, void *ptr);
-\layout LyX-Code
+\layout Standard
+
+7
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-void speex_decoder_ctl(void *encoder, int request, void *ptr);
 \layout Standard
 
-The different values of request allowed are (note that some only apply to
- the encoder or the decoder):
-\layout Description
+4
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
-SPEEX_SET_ENH** Set post-filter to on (1) or off (0) (integer)
-\layout Description
+\layout Standard
 
-SPEEX_GET_ENH** Get post-filter status (integer)
-\layout Description
+Asks encoder to set VBR off (0), on(1), VAD(2), DTX(3)
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-SPEEX_GET_FRAME_SIZE Get the frame size used for the current mode (integer)
-\layout Description
+\layout Standard
 
-SPEEX_SET_QUALITY* Set the encoder speech quality (integer 0 to 10)
-\layout Description
+8
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+8
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Transmit (8-bit) character to the other end
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+9
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+8
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Intensity stereo information
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+10
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+16
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Announce maximum bit-rate acceptable (N in bytes/second)
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+11
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+16
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+reserved
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+12
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+32
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Acknowledge receiving packet N
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+13
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+32
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+reserved
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+14
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-SPEEX_GET_QUALITY* Get the current encoder speech quality (integer 0 to
- 10)
-\layout Description
+\layout Standard
 
-SPEEX_SET_MODE*
-\begin_inset Formula $\dagger $
+64
 \end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
+\layout Standard
 
-\layout Description
-
-SPEEX_GET_MODE*
-\begin_inset Formula $\dagger $
+reserved
 \end_inset 
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
+\layout Standard
 
-\layout Description
-
-SPEEX_SET_LOW_MODE*
-\begin_inset Formula $\dagger $
+15
 \end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
+\layout Standard
 
-\layout Description
-
-SPEEX_GET_LOW_MODE*
-\begin_inset Formula $\dagger $
+64
 \end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
+\layout Standard
 
-\layout Description
+reserved
+\end_inset 
+</cell>
+</row>
+</lyxtabular>
 
-SPEEX_SET_HIGH_MODE*
-\begin_inset Formula $\dagger $
 \end_inset 
 
 
-\layout Description
+\layout Caption
+
+In-band signalling codes
+\begin_inset LatexCommand \label{cap:In-band-signalling-codes}
 
-SPEEX_GET_HIGH_MODE*
-\begin_inset Formula $\dagger $
 \end_inset 
 
 
-\layout Description
+\end_inset 
 
-SPEEX_SET_VBR* Set variable bit-rate (VBR) to on (1) or off (0) (integer)
-\layout Description
 
-SPEEX_GET_VBR* Get variable bit-rate (VBR) status (integer)
-\layout Description
+\layout Standard
 
-SPEEX_SET_VBR_QUALITY* Set the encoder VBR speech quality (integer 0 to
- 10)
-\layout Description
+Finally, applications may define custom in-band messages using mode 13.
+ The size of the message in bytes is encoded with 5 bits, so that the decoder
+ can skip it if it doesn't know how to interpret it.
+\layout Section
+\pagebreak_top 
+Formats and standards
+\begin_inset LatexCommand \index{standards}
 
-SPEEX_GET_VBR_QUALITY* Get the current encoder VBR speech quality (integer
- 0 to 10)
-\layout Description
+\end_inset 
 
-SPEEX_SET_COMPLEXITY* Set the CPU resources allowed for the encoder
-\layout Description
 
-SPEEX_GET_COMPLEXITY* Get the CPU resources allowed for the encoder
-\layout Description
+\layout Standard
 
-SPEEX_GET_BITRATE Get the current bit-rate in use (in bps)
-\layout Description
+Speex can encode speech in both narrowband and wideband and provides different
+ bit-rates.
+ However not all features must be supported by a certain implementation
+ or device.
+ In order to be said 
+\begin_inset Quotes eld
+\end_inset 
 
-* applies only to the encoder
-\layout Description
+Speex compatible
+\begin_inset Quotes erd
+\end_inset 
 
-** applies only to the decoder
-\layout Description
+ (whatever that means), an implementation must implement at least a basic
+ set of features.
+\layout Standard
 
+At the minimum, all narrowband modes of operation MUST be supported at the
+ decoder.
+ This includes the decoding of a wideband bit-stream by the narrowband decoder
+\begin_inset Foot
+collapsed true
 
-\begin_inset Formula $\dagger $
-\end_inset 
+\layout Standard
 
- normally only used internally
-\layout Section
+The wideband bit-stream contains an embedded narrowband bit-stream which
+ can be decoded alone
+\end_inset 
 
-Formats and standards
+.
+ If present, a wideband decoder MUST be able to decode a narrowband stream,
+ and MAY either be able to decode all wideband modes or be able to decode
+ the embedded narrowband part of all modes (which includes ignoring the
+ high-band bits).
 \layout Standard
 
-Speex can encode speech in both narrowband and wideband and provides different
- bit-rates.
- All modes of operation MUST be supported at the decoder and at least one
- MUST be supported by the encoder.
- The main reason is that not all platforms may be able to handle the complexity
- of encoding for all modes.
+For encoders, at least one narrowband or wideband mode MUST be supported.
+ The main reason why all encoding modes do not have to be supported is that
+ some platforms may not be able to handle the complexity of encoding in
+ some modes.
 \layout Subsection
 
-RTP Payload Format
+RTP
+\begin_inset LatexCommand \index{RTP}
+
+\end_inset 
+
+ Payload Format 
 \layout Standard
 
-Since Speex encoded frames already contain mode information, they can be
- sent without any other information in an RTP packet.
- If more than one frame is transmitted, no byte padding is performed at
- the end of frames, except the last one.
+The latest RTP payload draft can be found at 
+\begin_inset LatexCommand \url{http://www.speex.org/drafts/latest}
+
+\end_inset 
+
+.
+ We are (2003/01/14) about to send the latest draft to the IETF for comments.
  
 \layout Subsection
 
-Ogg file format
+MIME Type
 \layout Standard
 
-Speex bit-streams can be stored in Ogg files.
- In this case, the first packet of the Ogg file contains the Speex header
- (see speex_header.h for now) and the second packet contains a user-comment
- string (without terminating null).
- After the header and comment packets, next packets contain one or more
- (number found in header) Speex frames.
- The stream is terminated by a packet containing the string 
-\begin_inset Quotes eld
-\end_inset 
+Speex will use the MIME type 
+\family typewriter 
+audio/speex
+\family default 
+.
+ We will apply for that type in the near future.
+\layout Subsection
+
+Ogg
+\begin_inset LatexCommand \index{Ogg}
 
-END OF STREAM
-\begin_inset Quotes erd
 \end_inset 
 
- (without terminating null).
+ file format
 \layout Standard
 
 Speex bit-streams can be stored in Ogg files.
@@ -2624,10 +4798,14 @@ speex_version
 \emph on 
 beginning of stream
 \emph default 
- (b_o_s) flag is set to 1 for the header.
+ (
+\family typewriter 
+b_o_s
+\family default 
+) flag is set to 1 for the header.
  The header packet has 
 \family typewriter 
-packetno=1
+packetno=0
 \family default 
  and 
 \family typewriter 
@@ -2636,8 +4814,9 @@ granulepos=0
 .
 \layout Standard
 
-The second packet contains a user-comment string, without terminating null.
- The content/format of comment is not defined.
+The second packet contains the Speex comment header.
+ The format used is the Vorbis comment format described here: http://www.xiph.org/
+ogg/vorbis/doc/v-comment.html .
  This packet has 
 \family typewriter 
 packetno=1
@@ -2655,23 +4834,20 @@ The third and subsequant packets each contain one or more (number found
 \family typewriter 
 packetno
 \family default 
- starting from 3 and the 
+ starting from 2 and the 
 \family typewriter 
 granulepos
 \family default 
- is the number of the first sample encoded in that packet.
-\layout Standard
-
-The stream is terminated by a packet containing the string 
-\begin_inset Quotes eld
-\end_inset 
-
-END OF STREAM
-\begin_inset Quotes erd
-\end_inset 
-
- (without terminating null).
+ is the number of the last sample encoded in that packet.
+ Le last of these packets has the 
+\emph on 
+end of stream
+\emph default 
+ (
+\family typewriter 
+e_o_s
+\family default 
+) flag is set to 1.
 \layout Standard
 
 
@@ -2773,7 +4949,7 @@ char[]
 
 \layout Standard
 
-speex_header_version
+speex_version_id
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -3033,7 +5209,7 @@ int
 
 \layout Standard
 
-reserved1
+extra_headers
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -3059,7 +5235,7 @@ int
 
 \layout Standard
 
-reserved2
+reserved1
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -3085,7 +5261,7 @@ int
 
 \layout Standard
 
-reserved3
+reserved2
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -3136,6 +5312,255 @@ clearpage
 
 \layout Section
 \start_of_appendix 
+FAQ
+\layout Subsection*
+
+Vorbis is open-source
+\begin_inset LatexCommand \index{open-source}
+
+\end_inset 
+
+ and patent-free
+\begin_inset LatexCommand \index{patent}
+
+\end_inset 
+
+, why do we need Speex?
+\layout Standard
+
+Vorbis is a great project but its goals are not the same as Speex.
+ Vorbis is mostly aimed at compressing music and audio in general, while
+ Speex targets speech only.
+ For that reason Speex can achieve much better results than Vorbis on speech,
+ typically 2-4 times higher compression at equal quality.
+\layout Subsection*
+
+Under what license is Speex released?
+\layout Standard
+
+As of version 1.0 beta 1, Speex in released under Xiph's BSD-like license.
+ This license is the most permissive of the open-source licenses.
+\layout Subsection*
+
+Ogg
+\begin_inset LatexCommand \index{Ogg}
+
+\end_inset 
+
+, Speex, Vorbis
+\begin_inset LatexCommand \index{Vorbis}
+
+\end_inset 
+
+, what's the difference?
+\layout Standard
+
+Ogg is a 
+\begin_inset Quotes eld
+\end_inset 
+
+container format
+\begin_inset Quotes erd
+\end_inset 
+
+ for holding multimedia data.
+ Vorbis is an audio codec that uses Ogg to store its bit-streams as files,
+ hence the name Ogg Vorbis.
+ Speex also uses the Ogg format to store its bit-streams as files, so technicall
+y they would be 
+\begin_inset Quotes eld
+\end_inset 
+
+Ogg Speex
+\begin_inset Quotes erd
+\end_inset 
+
+ files (I prefer to call them just Speex files).
+ One difference with Vorbis however, is that Speex is less tied with Ogg.
+ Actually, if what you do is Voice of IP (VoIP), you don't need Ogg at all.
+\layout Subsection*
+
+What's the extension for Speex?
+\layout Standard
+
+Speex files have the .spx extension.
+ Note however that all the Speex tools (speexenc, speexdec) do not rely
+ on the extension at all so any extension will work.
+\layout Subsection*
+
+Can I use Speex for compressing music
+\begin_inset LatexCommand \index{music}
+
+\end_inset 
+
+?
+\layout Standard
+
+Just like Vorbis is not really adapted to speech, Speex is really not adapted
+ for music.
+ In most cases, you'll be better of with Vorbis when it comes to music.
+\layout Subsection*
+
+I converted some MP3's to Speex and the quality is bad.
+ What's wrong?
+\layout Standard
+
+This is called transcoding and it will always result in much poorer quality
+ than the original MP3.
+ Unless you have a really good (size) reason to do so, never transcode speech.
+ This is even valid for self transcoding (tandeming), i.e.
+ If you decode a Speex file and re-encode it again at the same bit-rate,
+ you will lose quality.
+\layout Subsection*
+
+Does Speex run on Windows?
+\layout Standard
+
+As of 0.8.0, Speex can now compile on Windows.
+ There are also several front-ends available from the web site.
+\layout Subsection*
+
+Why is encoding so slow compared to decoding?
+\layout Standard
+
+For most kinds of compression, encoding is inherently slower than decoding.
+ In the case of Speex, encoding consists of finding, for each vector of
+ 5 to 10 samples, the entry that matches the best within a codebook consisting
+ of 16 to 256 entries.
+ On the other hand, at decoding all that needs to be done is lookup the
+ right entry in the codebook using the encoded index.
+ Since a lookup is much faster than a search, the decoder works much faster
+ than the encoder.
+\layout Subsection*
+
+Why is Speex so slow on my iPaq (or insert any platform without an FPU)?
+\layout Standard
+
+Well the parenthesis provides the answer: no FPU (floating-point unit).
+ The Speex code makes heavy use of floating-point operations.
+ On devices with no FPU, all floating-point instructions need to be emulated.
+ This is a very time consuming operation.
+\layout Subsection*
+
+I'm getting unusual background noise (hiss) when using libspeex in my applicatio
+n.
+ How do I fix that?
+\layout Standard
+
+One of the cause could be scaling of the input speech.
+ Speex expects signals to have a 
+\begin_inset Formula $\pm 2^{15}$
+\end_inset 
+
+ (signed short) dynamic range.
+ If the dynamic range of your signals is too small (e.g.
+\begin_inset Formula $\pm 1.0$
+\end_inset 
+
+), you will suffer important quantization noise.
+ A good target is to have a dynamic range around 
+\begin_inset Formula $\pm 8000$
+\end_inset 
+
+ which is large enough, but small enough to make sure there's no clipping
+ when converting back to signed short.
+\layout Subsection*
+
+I get very distorted speech when using libspeex in my application.
+ What's wrong?
+\layout Standard
+
+There are many possible causes for that.
+ One of them is errors in the way the bits are manipulated.
+ Another possible cause is the use of the same encoder or decoder state
+ for more than one audio stream (channel), which produces strange effects
+ with the filter memories.
+ If the input speech has an amplitude close to 
+\begin_inset Formula $\pm 2^{15}$
+\end_inset 
+
+, it is possible that at decoding, the amplitude be a bit higher than that,
+ causing clipping when saving as 16-bit PCM.
+\layout Subsection*
+
+Can Speex pass DTMF
+\begin_inset LatexCommand \index{DTMF}
+
+\end_inset 
+
+?
+\layout Standard
+
+I guess it all depends on the bit-rate used.
+ Though no formal testing has yet been performed, I'd say don't go below
+ the 15 kbps mode if you want DTMF to be transmitted correctly.
+ DTMF at 8 kbps may work but your mileage may vary.
+ Also, make sure you don't use the lowest complexity (see SPEEX_SET_COMPLEXITY
+ or --comp option), as it causes important noise.
+\layout Subsection*
+
+Can Speex pass V.9x modem signals correctly?
+\layout Standard
+
+If I could to that I'd be very rich by now :-)
+\layout Subsection*
+
+What is your (Jean-Marc) relationship with the University of Sherbrooke
+ and how does Speex fit into that?
+\layout Standard
+
+I am currently (2003/01/13) doing a Ph.D.
+ at the University of Sherbrooke in mobile robotics.
+ Although I did my master with the Sherbrooke speech coding group (in speech
+ enhancement, not coding), I am not associated with them anymore.
+ It should 
+\series bold 
+not
+\series default 
+ be understood that they or the University of Sherbrooke endorse the Speex
+ project in any way.
+ Furthermore, Speex does not make use of any code or proprietary technology
+ developed in the Sherbrooke speech coding group.
+\layout Subsection*
+
+CELP, ACELP
+\begin_inset LatexCommand \index{ACELP}
+
+\end_inset 
+
+, what's the difference?
+\layout Standard
+
+CELP stands for 
+\begin_inset Quotes eld
+\end_inset 
+
+Code Excited Linear Prediction
+\begin_inset Quotes erd
+\end_inset 
+
+, while ACELP stands for 
+\begin_inset Quotes eld
+\end_inset 
+
+
+\emph on 
+Algebraic
+\emph default 
+ Code Excited Linear Prediction
+\begin_inset Quotes erd
+\end_inset 
+
+.
+ That means ACELP is a CELP technique that uses an algebraic codebook represente
+d as a sum of unit pulses, thus making the codebook search much more efficient.
+ This technique was invented at the University of Sherbrooke and is now
+ one of the most widely used form of CELP.
+ Unfortunately, since it is patented, it cannot be used in Speex.
+\layout Section
+\pagebreak_top 
 GNU Free Documentation License
 \layout Standard
 
@@ -3561,4 +5986,12 @@ n.
  If the Document does not specify a version number of this License, you
  may choose any version ever published (not as a draft) by the Free Software
  Foundation.
+\layout Standard
+
+
+\begin_inset LatexCommand \printindex{}
+
+\end_inset 
+
+
 \the_end