Preparing for rc2
[speexdsp.git] / doc / manual.lyx
index efc67dc..af400e5 100644 (file)
@@ -29,7 +29,7 @@
 
 The Speex Codec Manual
 \newline 
-(draft for Speex 1.0beta3)
+(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 
 
@@ -153,20 +123,20 @@ Free software/open-source
  and royalty-free
 \layout Itemize
 
-Integration of wideband
-\begin_inset LatexCommand \index{wideband}
+Integration of narrowband
+\begin_inset LatexCommand \index{narrowband}
 
 \end_inset 
 
- and narrowband
-\begin_inset LatexCommand \index{narrowband}
+ and wideband
+\begin_inset LatexCommand \index{wideband}
 
 \end_inset 
 
  in the same bit-stream
 \layout Itemize
 
-Wide range of bit-rates available
+Wide range of bit-rates available (from 2 kbps to 44 kbps)
 \layout Itemize
 
 Dynamic bit-rate switching and Variable Bit-Rate
@@ -191,6 +161,23 @@ Variable complexity
 \end_inset 
 
 
+\layout Itemize
+
+Ultra-wideband mode at 32 kHz (up to 48 kHz)
+\layout Itemize
+
+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
@@ -228,6 +215,10 @@ perceptually weighted domain
 \end_inset 
 
 
+\layout Standard
+
+This section describes the basic ideas behind CELP.
+ Note that it's still incomplete.
 \layout Subsection
 
 Linear Prediction (LPC)
@@ -238,27 +229,57 @@ Linear Prediction (LPC)
 
 \layout Standard
 
+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 \[
-y(n)=\sum _{i=1}^{N}a_{i}x(n-i)\]
+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 
 
+.
+ 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)\]
+e[n]=x[n]-y[n]=x[n]-\sum _{i=1}^{N}a_{i}x[n-i]\]
 
 \end_inset 
 
 
+\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 \[
-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}\]
+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 
 
+ 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\]
+\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\]
 
 \end_inset 
 
@@ -284,7 +305,7 @@ The
 \end_inset 
 
  of the signal 
-\begin_inset Formula $x(n)$
+\begin_inset Formula $x[n]$
 \end_inset 
 
 .
@@ -292,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 
 
@@ -375,7 +396,7 @@ The filter coefficients
 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)\]
+x[n]=\sum _{i=1}^{N}a_{i}x[n-i]+e[n]\]
 
 \end_inset 
 
@@ -423,6 +444,20 @@ We usually refer to
 \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
@@ -444,17 +479,18 @@ Pitch Prediction
 
 \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 
 
@@ -478,28 +514,60 @@ 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
@@ -516,17 +584,33 @@ Analysis-by-Synthesis and Error Weighting
 \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)\]
 
@@ -626,8 +710,7 @@ Minimizing the amount of information extracted from past frames (for robustness
 Dynamically-selectable codebooks (LSP, pitch and innovation)
 \layout Itemize
 
-G.728-like fixed codebooks (without backward-adaptive grains because of patent
- issues)
+sub-vector fixed (innovation) codebooks
 \layout Subsection
 
 LPC Analysis
@@ -638,8 +721,8 @@ LPC Analysis
 
 \layout Standard
 
-An LPC analysis is first performed on a (Hamming) window that spans all
- the current frame and half a frame in advance.
+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}
 
@@ -660,15 +743,18 @@ The LSP's are encoded using 30 bits for higher quality modes and 18 bits
  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
turther quantized with 6 bits each, for a total of 30 bits.
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 is derived from the LPC analysis and 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}
 
@@ -699,12 +785,13 @@ Pitch Prediction (adaptive codebook)
 \layout Standard
 
 Speex uses a 3-tap prediction for pitch.
- That is, 
-\layout Standard
-
+ 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 
 
@@ -720,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
@@ -732,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
@@ -779,7 +881,7 @@ OL
 
 
 \begin_inset Float table
-placement htbp
+placement h
 wide true
 collapsed false
 
@@ -787,7 +889,7 @@ collapsed false
 
 
 \begin_inset  Tabular
-<lyxtabular version="3" rows="12" columns="10">
+<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">
@@ -798,6 +900,7 @@ 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" rightline="true" width="0pt">
 <row topline="true" bottomline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -880,6 +983,14 @@ Update rate
 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">
@@ -962,6 +1073,14 @@ frame
 1
 \end_inset 
 </cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="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">
@@ -1044,6 +1163,14 @@ frame
 4
 \end_inset 
 </cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="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">
@@ -1126,6 +1253,14 @@ frame
 30
 \end_inset 
 </cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+18
+\end_inset 
+</cell>
 </row>
 <row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1208,6 +1343,14 @@ frame
 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">
@@ -1290,6 +1433,14 @@ frame
 0
 \end_inset 
 </cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="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">
@@ -1372,6 +1523,14 @@ frame
 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>
 <row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1454,6 +1613,14 @@ sub-frame
 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">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1536,6 +1703,14 @@ sub-frame
 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">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1618,6 +1793,14 @@ sub-frame
 3
 \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">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1700,6 +1883,14 @@ sub-frame
 96
 \end_inset 
 </cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+10
+\end_inset 
+</cell>
 </row>
 <row topline="true" bottomline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1782,6 +1973,14 @@ frame
 492
 \end_inset 
 </cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+79
+\end_inset 
+</cell>
 </row>
 </lyxtabular>
 
@@ -1830,7 +2029,7 @@ So far, no MOS (Mean Opinion Score
 
 
 \begin_inset Float table
-placement htbp
+placement h
 wide true
 collapsed false
 
@@ -2174,7 +2373,7 @@ Completely transparent for voice, good quality music
 
 \layout Standard
 
-N/A
+3,950
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -2182,7 +2381,7 @@ N/A
 
 \layout Standard
 
-N/A
+-
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -2190,7 +2389,7 @@ N/A
 
 \layout Standard
 
-(Tones/DTMF to be implemented)
+Very noticeable artifacts/noise, good intelligibility
 \end_inset 
 </cell>
 </row>
@@ -2597,7 +2796,7 @@ For the wideband mode, all the narrowband frame is packed before the high-band
 
 
 \begin_inset Float table
-placement htbp
+placement h
 wide true
 collapsed false
 
@@ -3036,33 +3235,285 @@ Bit allocation for high-band in wideband mode
 \end_inset 
 
 
-\layout Section
-\pagebreak_top 
-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
 
+\begin_inset ERT
+status Open
 
-\emph on 
-speexenc
-\begin_inset LatexCommand \index{speexenc}
+\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
 
-The encoder takes the following options:
+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 ~
@@ -3074,13 +3525,39 @@ The encoder takes the following options:
 (-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)
+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
@@ -3099,6 +3576,44 @@ n Set encoding speed/quality tradeoff.
 
 --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
 
 
@@ -3111,13 +3626,45 @@ speexdec
 
 \layout Standard
 
-The decoder takes the following options:
+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
 
---enh enable post-filter
+--force-uwb Force decoding in ultra-wideband 
 \layout Description
 
---no-enh disable post-filter (default)
+--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 ~
@@ -3275,7 +3822,7 @@ In order to encode speech using Speex, you first need to:
 #include <speex.h>
 \layout Standard
 
-You then need to declare a Speex bit-packing struct
+You also need to declare a Speex bit-packing struct
 \layout LyX-Code
 
 SpeexBits bits;
@@ -3305,7 +3852,8 @@ speex_nb_mode
 speex_wb_mode
 \emph default 
 .
- You can get that value in the 
+ 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 
@@ -3320,11 +3868,15 @@ There is also a parameter that can be set for the decoder: whether or not
  This can be set by: 
 \layout LyX-Code
 
-speex_decoder_ctl(dec_state, SPEEX_SET_PF, &pf); 
+speex_decoder_ctl(dec_state, SPEEX_SET_ENH, &enh); 
 \layout Standard
 
-where pf is an int that with value 0 to have the post-filter disabled and
- 1 to have it enabled.
+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:
@@ -3398,7 +3950,12 @@ 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 to on (1) or off (0) (integer)
+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)
@@ -3459,7 +4016,12 @@ SPEEX_GET_HIGH_MODE*
 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)
+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
@@ -3470,15 +4032,64 @@ 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
+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_GET_COMPLEXITY* Get the CPU resources allowed for the encoder
+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
 
@@ -3521,7 +4132,8 @@ 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
@@ -3644,7 +4256,7 @@ Content
 
 \layout Standard
 
-Asks decoder to set perceptual enhancement on (1) or off(1)
+Asks decoder to set perceptual enhancement off (0) or on(1)
 \end_inset 
 </cell>
 </row>
@@ -3670,7 +4282,7 @@ Asks decoder to set perceptual enhancement on (1) or off(1)
 
 \layout Standard
 
-Asks encoder to set VBR on (1) or off(1)
+reserved
 \end_inset 
 </cell>
 </row>
@@ -3826,7 +4438,7 @@ Request acknowloedge (0=no, 1=all, 2=only for in-band data)
 
 \layout Standard
 
-reserved
+Asks encoder to set VBR off (0), on(1), VAD(2), DTX(3)
 \end_inset 
 </cell>
 </row>
@@ -3878,7 +4490,7 @@ Transmit (8-bit) character to the other end
 
 \layout Standard
 
-reserved
+Intensity stereo information
 \end_inset 
 </cell>
 </row>
@@ -4115,20 +4727,30 @@ RTP
 
 \end_inset 
 
- Payload Format
+ Payload Format 
 \layout Standard
 
-This is a work in progress.
-\layout Comment
+The latest RTP payload draft can be found at 
+\begin_inset LatexCommand \url{http://www.speex.org/drafts/latest}
 
-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 number of frames contained in each packet MUST be transmitted out-of-band.
+\end_inset 
+
+.
+ We are (2003/01/14) about to send the latest draft to the IETF for comments.
  
 \layout Subsection
 
+MIME Type
+\layout Standard
+
+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}
 
@@ -4327,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">
@@ -4587,7 +5209,7 @@ int
 
 \layout Standard
 
-reserved1
+extra_headers
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -4613,7 +5235,7 @@ int
 
 \layout Standard
 
-reserved2
+reserved1
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -4639,7 +5261,7 @@ int
 
 \layout Standard
 
-reserved3
+reserved2
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -4713,6 +5335,13 @@ Vorbis is a great project but its goals are not the same as Speex.
  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}
 
@@ -4730,7 +5359,7 @@ Ogg is a
 \begin_inset Quotes eld
 \end_inset 
 
-file format
+container format
 \begin_inset Quotes erd
 \end_inset 
 
@@ -4751,6 +5380,14 @@ Ogg Speex
  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}
 
@@ -4779,8 +5416,8 @@ This is called transcoding and it will always result in much poorer quality
 Does Speex run on Windows?
 \layout Standard
 
-As of 0.8.0, Speex can now compile on Windows, though limited testing has
been done so far.
+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?
@@ -4858,6 +5495,7 @@ Can Speex pass DTMF
 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*
@@ -4872,7 +5510,7 @@ What is your (Jean-Marc) relationship with the University of Sherbrooke
  and how does Speex fit into that?
 \layout Standard
 
-I am currently (2002/08/13) doing a Ph.D.
+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.