Patch by David Rowe: normalize16() on Blackfin now writes data 16-bit at a time
[speexdsp.git] / doc / manual.lyx
index 913adc0..d8ea5dc 100644 (file)
@@ -1,14 +1,13 @@
-#LyX 1.2 created this file. For more info see http://www.lyx.org/
-\lyxformat 220
+#LyX 1.3 created this file. For more info see http://www.lyx.org/
+\lyxformat 221
 \textclass article
 \language english
 \inputencoding auto
-\fontscheme default
+\fontscheme pslatex
 \graphics default
-\float_placement h
 \paperfontsize default
-\spacing single 
-\papersize Default
+\spacing onehalf 
+\papersize letterpaper
 \paperpackage a4
 \use_geometry 0
 \use_amsmath 0
 
 The Speex Codec Manual
 \newline 
-(draft for Speex 1.0rc1)
+(version 1.1.11)
 \layout Author
 
 Jean-Marc Valin
 \layout Standard
 \pagebreak_top 
-Copyright (c) 2002 Jean-Marc Valin.
+Copyright (c) 2002-2005 Jean-Marc Valin/Xiph.org Foundation
 \layout Standard
 
 Permission is granted to copy, distribute and/or modify this document under
@@ -45,36 +44,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 
 
@@ -106,13 +75,13 @@ http://www.speex.org/
  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.
+ (not many open-source cell phones anyway :-) ) but rather at voice over
IP (VoIP) and file-based compression.
  
 \layout Standard
 
-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!),
+As design goals, we wanted to have a codec that would allow 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).
@@ -121,7 +90,7 @@ As design goals, we wanted to have a codec that would allowed both very
 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
+ Also, the idea was to have a reasonable complexity and memory requirement
  without compromising too much on the efficiency of the codec.
 \layout Standard
 
@@ -137,7 +106,7 @@ All this led us to the choice of CELP
  
 \layout Standard
 
-The main characteristics can be summerized as follows:
+The main characteristics can be summarized as follows:
 \layout Itemize
 
 Free software/open-source
@@ -153,20 +122,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
using an embedded 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
@@ -197,1173 +166,1588 @@ Ultra-wideband mode at 32 kHz (up to 48 kHz)
 \layout Itemize
 
 Intensity stereo encoding option
+\layout Itemize
+
+Fixed-point implementation (work in progress)
 \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}
+This document is divided in the following way.
+ Section 
+\begin_inset LatexCommand \ref{sec:Feature-description}
 
 \end_inset 
 
-.
-\layout Section
-\pagebreak_top 
-Introduction to CELP Coding
-\begin_inset LatexCommand \index{CELP}
+ describes the different Speex features and defines some terms that will
+ be used in later sections.
+ Section 
+\begin_inset LatexCommand \ref{sec:Command-line-encoder/decoder}
 
 \end_inset 
 
-
-\layout Standard
-
-Speex is based on CELP, which stands for Code Excited Linear Prediction.
- This section attempts to introduce the principles behind CELP, so if you
- are already familiar with CELP, you can safely skip to section 
-\begin_inset LatexCommand \ref{sec:Speex-narrowband-mode}
+ provides information about the standard command-line tools, while 
+\begin_inset LatexCommand \ref{sec:Programming-with-Speex}
 
 \end_inset 
 
-.
- The CELP technique is based on three ideas:
-\layout Enumerate
+ contains information about programming using the Speex API.
+ Section 
+\begin_inset LatexCommand \ref{sec:Formats-and-standards}
 
-The use of a linear prediction (LP) model to model the vocal tract
-\layout Enumerate
+\end_inset 
 
-The use of (adaptive and fixed) codebook entries as input (excitation) of
- the LP model
-\layout Enumerate
+ has some information related to Speex and standards.
+ The three last sections describe the internals of the codec and require
+ some signal processing knowledge.
+ Section 
+\begin_inset LatexCommand \ref{sec:Introduction-to-CELP}
 
-The search performed in closed-loop in a 
-\begin_inset Quotes eld
 \end_inset 
 
-perceptually weighted domain
-\begin_inset Quotes erd
+ explains the general idea behind CELP, while sections 
+\begin_inset LatexCommand \ref{sec:Speex-narrowband-mode}
+
 \end_inset 
 
+ and 
+\begin_inset LatexCommand \ref{sec:Speex-wideband-mode}
 
-\layout Subsection
+\end_inset 
 
-Linear Prediction (LPC)
-\begin_inset LatexCommand \index{linear prediction}
+ are specific to Speex.
+ Note that if you are only interested in using Speex, those three last sections
+ are not required.
+\layout Section
+\pagebreak_top 
+Codec description
+\begin_inset LatexCommand \label{sec:Feature-description}
 
 \end_inset 
 
 
 \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 
+This section describes the main features provided by Speex.
+\layout Subsection
 
- using a linear combination of its past samples:
+Concepts
 \layout Standard
 
+Here are some concepts in speech coding that help better understand the
+ rest of the manual.
+ Emphasis is placed on the Speex features.
+\layout Subsection*
 
-\begin_inset Formula \[
-y[n]=\sum _{i=1}^{N}a_{i}x[n-i]\]
+Sampling rate
+\begin_inset LatexCommand \index{sampling rate}
 
 \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]\]
+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}
 
-\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}\]
+ and ultra-wideband
+\begin_inset LatexCommand \index{ultra-wideband}
 
 \end_inset 
 
-That can be done by making all derivatives 
-\begin_inset Formula $\frac{\partial E}{\partial a_{i}}$
-\end_inset 
+.
+\layout Subsection*
 
- 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\]
+Quality
+\begin_inset LatexCommand \index{quality}
 
 \end_inset 
 
 
 \layout Standard
 
-The 
-\begin_inset Formula $a_{i}$
-\end_inset 
-
- filter coefficients are computed using the Levinson-Durbin
-\begin_inset LatexCommand \index{Levinson-Durbin}
+Speex encoding is controlled most of the time by a quality parameter that
+ ranges from 0 to 10.
+ In constant bit-rate
+\begin_inset LatexCommand \index{constant bit-rate}
 
 \end_inset 
 
- algorithm, which starts from the auto-correlation
-\begin_inset LatexCommand \index{auto-correlation}
+ (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
  
-\begin_inset Formula $R(m)$
-\end_inset 
+\emph on 
+gzip
+\emph default 
+ and 
+\emph on 
+bzip2
+\emph default 
+ compression utilities.
+ For normal use, the noise level at complexity 1 is between 1 and 2 dB higher
+ than at complexity 10, but the CPU requirements for complexity 10 is about
+ 5 times 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}
 
- of the signal 
-\begin_inset Formula $x[n]$
 \end_inset 
 
-.
-\layout Standard
-
+ tones.
+\layout Subsection*
 
-\begin_inset Formula \[
-R(m)=\sum _{i=0}^{N-1}x[i]x[i-m]\]
+Variable Bit-Rate
+\begin_inset LatexCommand \index{variable bit-rate}
 
 \end_inset 
 
-
+ (VBR)
 \layout Standard
 
-For an order 
-\begin_inset Formula $N$
+Variable bit-rate (VBR) allows a codec to change its bit-rate dynamically
+ to adapt to the 
+\begin_inset Quotes eld
 \end_inset 
 
- 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)\\
- \vdots  & \vdots  & \ddots  & \vdots \\
- R(N-1) & R(N-2) & \cdots  & R(0)\end{array}
-\right]\]
-
+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*
 
-\begin_inset Formula \[
-\mathbf{r}=\left[\begin{array}{c}
- R(1)\\
- R(2)\\
- \vdots \\
- R(N)\end{array}
-\right]\]
+Average Bit-Rate
+\begin_inset LatexCommand \index{average bit-rate}
 
 \end_inset 
 
-
+ (ABR)
 \layout Standard
 
-The filter coefficients 
-\begin_inset Formula $a_{i}$
-\end_inset 
+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 by encoding in
+ VBR with exactly the right quality setting to meet the target average bit-rate.
+\layout Subsection*
 
- are found by solving the system 
-\begin_inset Formula $\mathbf{Ra}=\mathbf{r}$
-\end_inset 
+Voice Activity Detection
+\begin_inset LatexCommand \index{voice activity detection}
 
-.
- What the Levinson-Durbin algorithm does here is making the solution to
- the problem 
-\begin_inset Formula $\mathcal{O}\left(N^{2}\right)$
 \end_inset 
 
- instead of 
-\begin_inset Formula $\mathcal{O}\left(N^{3}\right)$
-\end_inset 
+ (VAD)
+\layout Standard
 
- by exploiting the fact that matrix 
-\begin_inset Formula $\mathbf{R}$
+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 
 
- is toeplitz hermitian.
- Also, it can be proved that all the roots of 
-\begin_inset Formula $A(z)$
+comfort noise generation
+\begin_inset Quotes erd
 \end_inset 
 
- are withing the unit circle, which means that 
-\begin_inset Formula $1/A(z)$
-\end_inset 
+ (CNG).
+\layout Subsection*
+
+Discontinuous Transmission
+\begin_inset LatexCommand \index{discontinuous transmission}
 
- is always stable.
- 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)$
 \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.
+ (DTX)
 \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]\]
+Discontinuous transmission is an addition to VAD/VBR operation, that allows
+ to stop transmitting completely when the background noise is stationary.
+ 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
 
-In the 
+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 
-z
+objectively
 \emph default 
--domain, this can be expressed as
-\layout Standard
-
+ (if you use SNR), but in the end it still 
+\emph on 
+sounds
+\emph default 
+ better (subjective improvement).
+\layout Subsection*
 
-\begin_inset Formula \[
-x(z)=\frac{1}{A(z)}\: e(z)\]
+Algorithmic delay
+\begin_inset LatexCommand \index{algorithmic delay}
 
 \end_inset 
 
 
 \layout Standard
 
-where 
-\begin_inset Formula $A(z)$
+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 
 
- is defined as
-\layout Standard
+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 Subsection
 
-\begin_inset Formula \[
-A(z)=1-\sum _{i=1}^{N}a_{i}z^{-i}\]
+Codec
+\layout Subsection
 
-\end_inset 
+Preprocessor
+\layout Standard
+
+This part refers to the preprocessor module introduced in the 1.1.x branch.
+ The preprocessor is designed to be used on the audio 
+\emph on 
+before
+\emph default 
+ running the encoder.
+ The preprocessor provides three main functionalities:
+\layout Itemize
+
+denoising
+\layout Itemize
 
+automatic gain control (AGC)
+\layout Itemize
 
+voice activity detection (VAD)
 \layout Standard
 
-We usually refer to 
-\begin_inset Formula $A(z)$
-\end_inset 
+The denoiser can be used to reduce the amount of background noise present
+ in the input signal.
+ This provides higher quality speech whether or not the denoised signal
+ is encoded with Speex (or at all).
+ However, when using the denoised signal with the codec, there is an additional
+ benefit.
+ Speech codecs in general (Speex included) tend to perform poorly on noisy
+ input, which tends to amplify the noise.
+ The denoiser greatly reduces this effect.
+\layout Standard
 
- as the analysis filter and 
-\begin_inset Formula $1/A(z)$
-\end_inset 
+Automatic gain control (AGC) is a feature that deals with the fact that
+ the recording volume may vary by a large amount between different setups.
+ The AGC provides a way to adjust a signal to a reference volume.
+ This is useful for voice over IP because it removes the need for manual
+ adjustment of the microphone gain.
+ A secondary advantage is that by setting the microphone gain to a conservative
+ (low) level, it is easier to avoid clipping.
+\layout Standard
 
- as the synthesis filter.
- The whole process is called short-term prediction as it predicts the signal
+The voice activity detector (VAD) provided by the preprocessor is more advanced
+ than the one directly provided in the codec.
  
-\begin_inset Formula $x[n]$
-\end_inset 
+\layout Subsection
 
- using a prediction using only the 
-\begin_inset Formula $N$
-\end_inset 
+Adaptive Jitter Buffer
+\layout Subsection
 
- past samples, where 
-\begin_inset Formula $N$
-\end_inset 
+Acoustic Echo Canceller
+\layout Section
+\pagebreak_top 
+Compiling
+\layout Standard
 
- is usually around 10.
+Compiling Speex under UNIX or any platform supported by autoconf (e.g.
+ Win32/cygwin) is as easy as typing:
+\layout LyX-Code
+
+% ./configure [options]
+\layout LyX-Code
+
+% make
+\layout LyX-Code
+
+% make install
 \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}
+The options supported by the Speex configure script are:
+\layout Description
 
-\end_inset 
+--prefix=<path> Specifies where to install Speex
+\layout Description
 
- (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
+--enable-shared/--disable-shared Whether to compile shared libraries
+\layout Description
 
-Pitch Prediction
-\begin_inset LatexCommand \index{pitch}
+--enable-static/--disable-static Whether to compile static libraries
+\layout Description
 
-\end_inset 
+--disable-wideband Disable the wideband part of Speex (typically to same
+ space)
+\layout Description
 
+--enable-valgrind Enable extra information when (and only when) running
+ with valgrind
+\layout Description
 
-\layout Standard
+--enable-sse Enable use of SSE instructions (x86/float only)
+\layout Description
+
+--enable-fixed-point
+\begin_inset LatexCommand \index{fixed-point}
 
-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 
 
- by a gain times the past of the excitation:
-\layout Standard
+ Compile Speex for a processor that does not have a floating point unit
+ (FPU)
+\layout Description
 
+--enable-arm4-asm Enable assembly specific to the ARMv4 architecture (gcc
+ only)
+\layout Description
 
-\begin_inset Formula \[
-e[n]\simeq p[n]=\beta e[n-T]\]
+--enable-arm5e-asm Enable assembly specific to the ARMv5E architecture (gcc
+ only)
+\layout Description
+
+--enable-fixed-point-debug Use only for debugging the fixed-point
+\begin_inset LatexCommand \index{fixed-point}
 
 \end_inset 
 
+ code (very slow)
+\layout Description
 
-\layout Standard
+--enable-epic-48k Enable a special (and non-compatible) 4.8 kbps narrowband
+ mode
+\layout Description
 
-where 
-\begin_inset Formula $T$
-\end_inset 
+--enable-ti-c55x Enable support for the TI C5x family
+\layout Description
 
- is the pitch period, 
-\begin_inset Formula $\beta $
-\end_inset 
+--enable-blackfin-asm Enable assembly specific to the Blackfin DSP architecture
+ (gcc only)
+\layout Description
+
+--enable-16bit-precision Reduces precision to 16 bits in time-critical areas
+ (fixed-point only)
+\layout Section
+\pagebreak_top 
+Command-line encoder/decoder
+\begin_inset LatexCommand \label{sec:Command-line-encoder/decoder}
 
- is the pitch gain and 
-\begin_inset Formula $c(n)$
 \end_inset 
 
- is taken from the 
+
+\layout Standard
+
+The base Speex distribution includes a command-line encoder (
 \emph on 
-innovation codebook
+speexenc
 \emph default 
-.
- We call that long-term prediction since the excitation is predicted from
-\begin_inset Formula $e[n-T]$
-\end_inset 
+) 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}
 
- 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 
+The 
 \emph on 
-innovation
+speexenc
 \emph default 
- signal 
-\begin_inset Formula $c[n]$
-\end_inset 
+ utility is used to create Speex files from raw PCM or wave files.
+ It can be used by calling: 
+\layout LyX-Code
 
- taken from a fixed codebook.
+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
 
-\begin_inset Formula \[
-e[n]=p[n]+c[n]=\beta e[n-T]+c[n]\]
+--narrowband\SpecialChar ~
+(-n) Tell Speex to treat the input as narrowband (8 kHz).
+ This is the default
+\layout Description
 
-\end_inset 
+--wideband\SpecialChar ~
+(-w) Tell Speex to treat the input as wideband (16 kHz)
+\layout Description
 
-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)$
+--ultra-wideband\SpecialChar ~
+(-u) Tell Speex to treat the input as 
+\begin_inset Quotes eld
 \end_inset 
 
- as 
-\begin_inset Formula \[
-X(z)=\frac{C(z)}{A(z)\left(1-\beta z^{-T}\right)}\]
-
+ultra-wideband
+\begin_inset Quotes erd
 \end_inset 
 
+ (32 kHz)
+\layout Description
 
-\layout Subsection
+--quality\SpecialChar ~
+n Set the encoding quality (0-10), default is 8
+\layout Description
 
-Analysis-by-Synthesis and Error Weighting
-\begin_inset LatexCommand \index{error weighting}
+--bitrate\SpecialChar ~
+n Encoding bit-rate (use bit-rate n or lower) 
+\layout Description
 
-\end_inset 
+--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
 
-\begin_inset LatexCommand \index{analysis-by-synthesis}
+--vad Enable VAD (Voice Activity Detection), disabled by default
+\layout Description
 
-\end_inset 
+--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
 
-\layout Standard
+--comp\SpecialChar ~
+n Set encoding speed/quality tradeoff.
+ The higher the value of n, the slower the encoding (default is 3)
+\layout Description
 
-Most (if not all) modern audio codecs attempt to 
-\begin_inset Quotes eld
-\end_inset 
+-V Verbose operation, print bit-rate currently in use
+\layout Description
 
-shape
-\begin_inset Quotes erd
-\end_inset 
+--help\SpecialChar ~
+(-h) Print the help
+\layout Description
 
- 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 instead of minimizing the simple quadratic error
-\begin_inset Formula \[
-E=\sum _{n}\left(x[n]-\overline{x}[n]\right)^{2}\]
+--version\SpecialChar ~
+(-v) Print version information
+\layout Subsubsection*
 
-\end_inset 
+Speex comments
+\layout Description
 
-where 
-\begin_inset Formula $\overline{x}[n]$
-\end_inset 
+--comment Add the given string as an extra comment.
+ This may be used multiple times.
+\layout Description
 
- is the encoder signal, we minimize the error for the perceptually weighted
- signal
-\begin_inset Formula \[
-X_{w}(z)=W(z)X(z)\]
+--author Author of this track.
+\layout Description
 
-\end_inset 
+--title Title for this track.
+\layout Subsubsection*
 
-where 
-\begin_inset Formula $W(z)$
-\end_inset 
+Raw input options
+\layout Description
 
- is the weighting filter, usually of the form
-\layout Standard
+--rate\SpecialChar ~
+n Sampling rate for raw input
+\layout Description
 
+--stereo Consider raw input as stereo 
+\layout Description
 
-\begin_inset Formula \begin{equation}
-W(z)=\frac{A\left(\frac{z}{\gamma _{1}}\right)}{A\left(\frac{z}{\gamma _{2}}\right)}\label{eq:weighting_filter}\end{equation}
+--le Raw input is little-endian 
+\layout Description
 
-\end_inset 
+--be Raw input is big-endian 
+\layout Description
 
+--8bit Raw input is 8-bit unsigned 
+\layout Description
 
-\layout Standard
+--16bit Raw input is 16-bit signed 
+\layout Subsection
 
-with control parameters 
-\begin_inset Formula $\gamma _{1}>\gamma _{2}$
-\end_inset 
 
-.
- If the noise is white in the perceptually weighted domain, then in the
- signal domain its spectral shape will be of the form
-\begin_inset Formula \[
-A_{noise}(z)=\frac{1}{W(z)}=\frac{A\left(\frac{z}{\gamma _{2}}\right)}{A\left(\frac{z}{\gamma _{1}}\right)}\]
+\emph on 
+speexdec
+\begin_inset LatexCommand \index{speexdec}
 
 \end_inset 
 
 
 \layout Standard
 
-If a filter 
-\begin_inset Formula $A(z)$
-\end_inset 
+The 
+\emph on 
+speexdec
+\emph default 
+ utility is used to decode Speex files and can be used by calling: 
+\layout LyX-Code
 
- has (complex) poles at 
-\begin_inset Formula $p_{i}$
-\end_inset 
+speexdec [options] speex_file [output_file]
+\layout Standard
 
- in the 
-\begin_inset Formula $z$
-\end_inset 
+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
 
--plane, the filter 
-\begin_inset Formula $A(z/\gamma )$
-\end_inset 
+--enh enable post-filter (default)
+\layout Description
 
- filter will have its poles at 
-\begin_inset Formula $p_{i}^{'}=\gamma p_{i}$
-\end_inset 
+--no-enh disable post-filter
+\layout Description
 
-, making it a flatter version of 
-\begin_inset Formula $A(z)$
-\end_inset 
+--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 Force 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 
-Speex narrowband mode
-\begin_inset LatexCommand \label{sec:Speex-narrowband-mode}
+Programming with Speex (the libspeex
+\begin_inset LatexCommand \index{libspeex}
 
 \end_inset 
 
-
-\begin_inset LatexCommand \index{narrowband}
+ API
+\begin_inset LatexCommand \index{API}
 
 \end_inset 
 
+)
+\begin_inset LatexCommand \label{sec:Programming-with-Speex}
 
-\layout Standard
-
-This section looks at how Speex works for narrowband (
-\begin_inset Formula $8\: \mathrm{kHz}$
 \end_inset 
 
- sampling rate) operation.
- The frame size for this mode is 
-\begin_inset Formula $20\: \mathrm{ms}$
-\end_inset 
 
-, 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
+This section explains how to use the Speex API.
+ Examples of code can also be found in appendix 
+\begin_inset LatexCommand \ref{sec:Sample-code}
 
-Dynamically-selectable codebooks (LSP, pitch and innovation)
-\layout Itemize
+\end_inset 
 
-G.728-like fixed codebooks (without backward-adaptive gains because of patent
- issues)
+.
 \layout Subsection
 
-LPC Analysis
-\begin_inset LatexCommand \index{linear prediction}
+Encoding
+\begin_inset LatexCommand \label{sub:Encoding}
 
 \end_inset 
 
 
 \layout Standard
 
-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 
+In order to encode speech using Speex, you first need to:
+\layout LyX-Code
 
- sub-frames and the LSP's associated to the first 3 sub-frames are linearly
- interpolated using the current and previous LSP's.
+#include <speex/speex.h>
 \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
+You then need to declare a Speex bit-packing struct
+\layout LyX-Code
 
-The perceptual weighting filter 
-\begin_inset Formula $W(z)$
-\end_inset 
+SpeexBits bits;
+\layout Standard
 
- used by Speex is derived from the LPC filter 
-\begin_inset Formula $A(z)$
-\end_inset 
+and a Speex encoder state
+\layout LyX-Code
 
- and corresponds to the one described by eq.
-\begin_inset LatexCommand \ref{eq:weighting_filter}
+void *enc_state;
+\layout Standard
 
-\end_inset 
+The two are initialized by:
+\layout LyX-Code
 
- with 
-\begin_inset Formula $\gamma _{1}=0.9$
-\end_inset 
+speex_bits_init(&bits);
+\layout LyX-Code
 
- and 
-\begin_inset Formula $\gamma _{2}=0.6$
-\end_inset 
+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 
 .
- We can use the unquantized 
-\begin_inset Formula $A(z)$
-\end_inset 
+ 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
 
- filter since the weighting filter is only used in the encoder.
-\layout Subsection
+speex_encoder_ctl(enc_state,SPEEX_GET_FRAME_SIZE,&frame_size);
+\layout Standard
 
-Pitch Prediction (adaptive codebook)
-\begin_inset LatexCommand \index{pitch}
+In practice, 
+\emph on 
+frame_size
+\emph default 
+ will correspond to 20 ms when using 8, 16, or 32 kHz sampling rate.
+\layout Standard
 
-\end_inset 
+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
 
-Speex uses a 3-tap prediction for pitch.
- That is, the pitch prediction signal 
-\begin_inset Formula $p[n]$
-\end_inset 
+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
 
- is obtained by the past of the excitation by:
-\begin_inset Formula \[
-p[n]=\beta _{0}e[n-T-1]+\beta _{1}e[n-T]+\beta _{2}e[n-T+1]\]
+When using an unstable release (1.1.x), it is possible to use the 
+\emph on 
+speex_encode_int()
+\emph default 
+ function, which takes a 
+\emph on 
+(short *)
+\emph default 
+ for the audio.
+ This is usually simpler and it makes an eventual port to an FPU-less platform
+ (like ARM) easier.
+\layout Standard
 
-\end_inset 
+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
 
-where 
-\begin_inset Formula $T$
-\end_inset 
+That's about it for the encoder.
+\layout Subsection
 
- is the pitch period and the 
-\begin_inset Formula $\beta _{i}$
-\end_inset 
+Decoding
+\begin_inset LatexCommand \label{sub:Decoding}
 
- 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 
+\layout Standard
 
- 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 
+In order to decode speech using Speex, you first need to:
+\layout LyX-Code
 
- range and the 
-\begin_inset Formula $\beta _{i}$
-\end_inset 
+#include <speex/speex.h>
+\layout Standard
 
- 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
+You also need to declare a Speex bit-packing struct
+\layout LyX-Code
 
-Innovation Codebook
+SpeexBits bits;
 \layout Standard
 
-In Speex, the innovation signal is quantized using shape-only vector quantizatio
-n (VQ).
- That means that the codebooks that are used represent both the shape and
- 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 
+and a Speex decoder state
+\layout LyX-Code
 
-global
-\begin_inset Quotes erd
-\end_inset 
-
- and make use of the whole information available for a sub-frame.
-\layout Subsection
-
-Bit allocation
+void *dec_state;
 \layout Standard
 
-There are 7 different narrowband bit-rates defined for Speex, ranging from
- 200 bps to 18.15 kbps, although the modes below 5.9 kbps should not be used
- for speech.
- The bit-allocation for each mode is detailed in table 
-\begin_inset LatexCommand \ref{cap:bits-narrowband}
+The two are initialized by:
+\layout LyX-Code
 
-\end_inset 
+speex_bits_init(&bits);
+\layout LyX-Code
 
-.
- Each frame starts with the mode ID encoded with 4 bits which allows a range
- from 0 to 15, though only the first 7 values are used (the others are reserved).
- The parameters are listed in the table in the order they are packed in
- the bit-stream.
- 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 
+dec_state = speex_decoder_init(&speex_nb_mode);
+\layout Standard
 
-OL
-\begin_inset Quotes erd
-\end_inset 
+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
 
- in the parameter description means the the parameter is an open loop estimation
- based on the whole frame.
+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
 
-\begin_inset Float table
-placement h
-wide true
-collapsed false
+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
 
-\begin_inset  Tabular
-<lyxtabular version="3" rows="12" columns="10">
-<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" 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
+speex_bits_read_from(&bits, input_bytes, nbBytes);
+\layout LyX-Code
 
+speex_decode(dec_state, &bits, output_frame);
 \layout Standard
 
-Parameter
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+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
 
+As for the encoder, the 1.1.x branch introduces the 
+\emph on 
+speex_decode_int()
+\emph default 
+ function which also uses a 
+\emph on 
+(short *)
+\emph default 
+ as the output for the audio.
 \layout Standard
 
-Update rate
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+After you're done with the decoding, free all resources with:
+\layout LyX-Code
 
-\layout Standard
+speex_bits_destroy(&bits);
+\layout LyX-Code
 
-0
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+speex_decoder_destroy(dec_state);
+\layout Subsection
 
-\layout Standard
+Preprocessor
+\begin_inset LatexCommand \label{sub:Preprocessor}
 
-1
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
 
 \layout Standard
 
-2
+In order to use the Speex preprocessor
+\begin_inset LatexCommand \index{preprocessor}
+
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
+, you first need to:
+\layout LyX-Code
+
+#include <speex/speex_preprocess.h>
 \layout Standard
 
-3
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+Then, a preprocessor state can be created as:
+\layout LyX-Code
 
+SpeexPreprocessState *preprocess_state = speex_preprocess_state_init(frame_size,
+ sampling_rate);
 \layout Standard
 
-4
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
+It is recommended to use the same value for 
+\family typewriter 
+frame_size
+\family default 
+ as is used by the encoder (20 
+\emph on 
+ms
+\emph default 
+).
 \layout Standard
 
-5
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+For each input frame, you need to call:
+\layout LyX-Code
 
+speex_preprocess(preprocess_state, audio_frame, echo_residue);
 \layout Standard
 
-6
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
+where 
+\family typewriter 
+audio_frame
+\family default 
+ is used both as input and output and 
+\family typewriter 
+echo_residue
+\family default 
+ is either an array filled by the echo canceller, or NULL if the preprocessor
+ is used without the echo canceller.
 \layout Standard
 
-7
-\end_inset 
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+In cases where the output audio is not useful for a certain frame, it is
+ possible to use instead:
+\layout LyX-Code
 
+speex_preprocess_estimate_update(preprocess_state, audio_frame, echo_residue);
 \layout Standard
 
-Wideband bit
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
+This call will update all the preprocessor internal state variables without
+ computing the output audio, thus saving some CPU cycles.
 \layout Standard
 
-frame
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+The behaviour of the preprocessor can be changed using:
+\layout LyX-Code
 
+speex_preprocess_ctl(preprocess_state, request, ptr);
 \layout Standard
 
-1
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
+which is used in the same way as the encoder and decoder equivalent.
+ Options are listed in Section .
 \layout Standard
 
-1
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+The preprocessor state can be destroyed using:
+\layout LyX-Code
 
-\layout Standard
+speex_preprocess_state_destroy(preprocess_state);
+\layout Subsection
+
+Echo Cancellation
+\begin_inset LatexCommand \label{sub:Echo-Cancellation}
 
-1
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
 
 \layout Standard
 
-1
+The Speex library now includes an echo cancellation
+\begin_inset LatexCommand \index{echo cancellation}
+
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+ algorithm suitable for Acoustic Echo Cancellation
+\begin_inset LatexCommand \index{acoustic echo cancellation}
 
-1
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
+ (AEC).
+ In order to use the echo canceller, you first need to
+\layout LyX-Code
+
+#include <speex/speex_echo.h>
 \layout Standard
 
-1
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+Then, an echo canceller state can be created by:
+\layout LyX-Code
 
+SpeexEchoState *echo_state = speex_echo_state_init(frame_size, filter_length);
 \layout Standard
 
-1
+where 
+\family typewriter 
+frame_size
+\family default 
+ is the amount of data (in samples) you want to process at once and 
+\family typewriter 
+filter_length
+\family default 
+ is the length (in samples) of the echo cancelling filter you want to use
+ (also known as 
+\shape italic 
+tail length
+\shape default 
+
+\begin_inset LatexCommand \index{tail length}
+
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
+).
+ It is recommended to use a frame size in the order of 20 ms (or equal to
+ the codec frame size) and make sure it is easy to perform an FFT of that
+ size (powers of two are better than prime sizes).
+ The recommended tail length is approximately the third of the room reverberatio
+n time.
+ For example, in a small room, reverberation time is in the order of 300
+ ms, so a tail length of 100 ms is a good choice (800 samples at 8000 Hz
+ sampling rate).
 \layout Standard
 
-1
-\end_inset 
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+Once the echo canceller state is created, audio can be processed by:
+\layout LyX-Code
 
+speex_echo_cancel(echo_state, input_frame, echo_frame, output_frame, residue);
 \layout Standard
 
-Mode ID
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
+where 
+\family typewriter 
+input_frame
+\family default 
+ is the audio as captured by the microphone, 
+\family typewriter 
+echo_frame
+\family default 
+ is the signal that was played in the speaker (and needs to be removed)
+ and 
+\family typewriter 
+output_frame
+\family default 
+ is the signal with echo removed.
+ The 
+\family typewriter 
+residue
+\family default 
+ parameter is optional (you can set it to NULL) and is used to return the
+ estimated power spectrum of the echo residue so it can be removed by the
+ preprocessor (if you with to use it).
 \layout Standard
 
-frame
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+One important thing to keep in mind is the relationship between 
+\family typewriter 
+input_frame
+\family default 
+ and 
+\family typewriter 
+echo_frame
+\family default 
+.
+ It is important that, at any time, any echo that is present in the input
+ has already been sent to the echo canceller as 
+\family typewriter 
+echo_frame
+\family default 
+.
+ In other words, the echo canceller cannot remove a signal that it hasn't
+ yet received.
+ On the other hand, the delay between the input signal and the echo signal
+ must be small enough because otherwise part of the echo cancellation filter
+ is inefficient.
+ In the ideal case, you code would look like:
+\layout LyX-Code
 
-\layout Standard
+write_to_soundcard(echo_frame, frame_size);
+\layout LyX-Code
 
-4
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+read_from_soundcard(input_frame, frame_size);
+\layout LyX-Code
 
+speex_echo_cancel(echo_state, input_frame, echo_frame, output_frame, residue);
 \layout Standard
 
-4
+As stated above, if you wish to further reduce the echo present in the signal,
+ you can do so by passing 
+\family typewriter 
+residue
+\family default 
+ as the last parameter of 
+\family typewriter 
+speex_preprocess()
+\family default 
+ function (see Section 
+\begin_inset LatexCommand \ref{sub:Preprocessor}
+
 \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
+The echo cancellation state can be destroyed as:
+\layout LyX-Code
 
+speex_echo_state_destroy(echo_state);
 \layout Standard
 
-4
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+It is also possible to reset the state of the echo canceller so it can be
+ reused without the need to create another state as:
+\layout LyX-Code
+
+speex_echo_state_reset(echo_state);
+\layout Subsubsection
 
+Troubleshooting
 \layout Standard
 
-4
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+There are several things that may prevent the echo canceller from working
+ properly.
+ One of them is a bug (or something suboptimal) in the code, but there are
+ many others you should consider first
+\layout Itemize
 
-\layout Standard
+Using a different soundcard to do the capture and plaback will *not* work,
+ regardless of what you may think.
+ The only exception to that is if the two cards can be made to have their
+ sampling clock 
+\begin_inset Quotes eld
+\end_inset 
 
-4
+locked
+\begin_inset Quotes erd
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+ on the same clock source.
+\layout Itemize
 
-4
+The delay between the record and playback signals must be minimal.
+ Any signal played has to 
+\begin_inset Quotes eld
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
 
-4
+appear
+\begin_inset Quotes erd
 \end_inset 
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+ on the playback (far end) signal slightly before the echo canceller 
+\begin_inset Quotes eld
+\end_inset 
 
-LSP
+sees
+\begin_inset Quotes erd
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+ it in the near end signal, but excessive delay means that part of the filter
+ length is wasted.
+ In the worst situations, the delay is such that it is longer than the filter
+ length, in which case, no echo can be cancelled.
+\layout Itemize
 
-frame
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+When it comes to echo tail length (filter length), longer is *not* better.
+ Actually, the longer the tail length, the longer it takes for the filter
+ to adapt.
+ Of course, a tail length that is too short will not cancel enough echo,
+ but the most common problem seen is that people set a very long tail length
+ and then wonder why no echo is being cancelled.
+\layout Itemize
 
-\layout Standard
+Non-linear distortion cannot (by definition) be modeled by the linear adaptive
+ filter used in the echo canceller and thus cannot be cancelled.
+ Use good audio gear and avoid saturation/clipping.
+\layout Subsection
+
+Codec Options (speex_*_ctl)
+\begin_inset LatexCommand \label{sub:Codec-Options}
 
-0
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
 
 \layout Standard
 
-18
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+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 to 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
 
-18
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+The different values of request allowed are (note that some only apply to
+ the encoder or the decoder):
+\layout Description
 
-\layout Standard
+SPEEX_SET_ENH** Set perceptual enhancer
+\begin_inset LatexCommand \index{perceptual enhancement}
 
-18
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+ to on (1) or off (0) (integer)
+\layout Description
 
-18
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+SPEEX_GET_ENH** Get perceptual enhancer status (integer)
+\layout Description
 
-\layout Standard
+SPEEX_GET_FRAME_SIZE Get the frame size used for the current mode (integer)
+\layout Description
 
-30
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+SPEEX_SET_QUALITY* Set the encoder speech quality (integer 0 to 10)
+\layout Description
 
-\layout Standard
+SPEEX_GET_QUALITY* Get the current encoder speech quality (integer 0 to
+ 10)
+\layout Description
 
-30
+SPEEX_SET_MODE*
+\begin_inset Formula $\dagger$
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
 
-30
+\layout Description
+
+SPEEX_GET_MODE*
+\begin_inset Formula $\dagger$
 \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
+\layout Description
+
+SPEEX_SET_LOW_MODE*
+\begin_inset Formula $\dagger$
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
 
-frame
+\layout Description
+
+SPEEX_GET_LOW_MODE*
+\begin_inset Formula $\dagger$
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
 
-0
+\layout Description
+
+SPEEX_SET_HIGH_MODE*
+\begin_inset Formula $\dagger$
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
 
-7
+\layout Description
+
+SPEEX_GET_HIGH_MODE*
+\begin_inset Formula $\dagger$
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
 
-7
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\layout Description
 
-\layout Standard
+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}
 
-0
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+ (VBR) status (integer)
+\layout Description
 
-0
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+SPEEX_SET_VBR_QUALITY* Set the encoder VBR speech quality (float 0 to 10)
+\layout Description
 
-\layout Standard
+SPEEX_GET_VBR_QUALITY* Get the current encoder VBR speech quality (float
+ 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}
 
-0
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+
+ (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
+
+SPEEX_SET_PLC_TUNING* Tell the encoder to optimize encoding for a certain
+ percentage of packet loss (integer in percent)
+\layout Description
+
+SPEEX_GET_PLC_TUNING* Get the current tuning of the encoder for PLC (integer
+ in percent)
+\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
+\begin_inset LatexCommand \label{sub:Mode-queries}
+
+\end_inset 
+
 
 \layout Standard
 
-0
+Speex modes have a query system similar to the speex_encoder_ctl and speex_decod
+er_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 through
+\emph on 
+ptr
+\emph default 
+ (integer in bps).
+\layout Subsection
+
+Preprocessor options
+\begin_inset LatexCommand \label{sub:Preprocessor-options}
+
+\end_inset 
+
+
+\layout Description
+
+SPEEX_PREPROCESS_SET_DENOISE Turns denoising on(1) or off(2) (integer)
+\layout Description
+
+SPEEX_PREPROCESS_GET_DENOISE Get denoising status (integer)
+\layout Description
+
+SPEEX_PREPROCESS_SET_AGC Turns automatic gain control (AGC) on(1) or off(2)
+ (integer)
+\layout Description
+
+SPEEX_PREPROCESS_GET_AGC Get AGC status (integer)
+\layout Description
+
+SPEEX_PREPROCESS_SET_VAD Turns voice activity detector (VAD) on(1) or off(2)
+ (integer)
+\layout Description
+
+SPEEX_PREPROCESS_GET_VAD Get VAD status (integer)
+\layout Description
+
+SPEEX_PREPROCESS_SET_AGC_LEVEL
+\layout Description
+
+SPEEX_PREPROCESS_GET_AGC_LEVEL
+\layout Description
+
+SPEEX_PREPROCESS_SET_DEREVERB Turns reverberation removal on(1) or off(2)
+ (integer)
+\layout Description
+
+SPEEX_PREPROCESS_GET_DEREVERB Get reverberation removal status (integer)
+\layout Description
+
+SPEEX_PREPROCESS_SET_DEREVERB_LEVEL
+\layout Description
+
+SPEEX_PREPROCESS_GET_DEREVERB_LEVEL
+\layout Description
+
+SPEEX_PREPROCESS_SET_DEREVERB_DECAY
+\layout Description
+
+SPEEX_PREPROCESS_GET_DEREVERB_DECAY
+\layout Subsection
+
+Packing and in-band signalling
+\begin_inset LatexCommand \index{in-band signalling}
+
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+
 
 \layout Standard
 
-0
+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 Table 
+\begin_inset LatexCommand \ref{cap:quality_vs_bps}
+
 \end_inset 
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
+.
+ Note that as of version 1.0.2, calling speex_bits_write automatically inserts
+ the terminator so as to fill the last byte.
+ This doesn't involves any overhead and makes sure Speex can always detect
+ when there is no more frame in a packet.
 \layout Standard
 
-OL pitch gain
+It is also possible to send in-band 
+\begin_inset Quotes eld
 \end_inset 
-</cell>
+
+messages
+\begin_inset Quotes erd
+\end_inset 
+
+ to the other side.
+ All these messages are encoded as 
+\begin_inset Quotes eld
+\end_inset 
+
+pseudo-frames
+\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
+ follows.
+ 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
 
-frame
+Code
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1371,17 +1755,19 @@ frame
 
 \layout Standard
 
-0
+Size (bits)
 \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
+Content
 \end_inset 
 </cell>
+</row>
+<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
@@ -1395,31 +1781,33 @@ frame
 
 \layout Standard
 
-0
+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
 
-0
+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
 
-0
+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
 
-0
+1
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -1427,7 +1815,15 @@ frame
 
 \layout Standard
 
-0
+Asks (if 1) the encoder to be less 
+\begin_inset Quotes eld
+\end_inset 
+
+agressive
+\begin_inset Quotes erd
+\end_inset 
+
+ due to high packet loss
 \end_inset 
 </cell>
 </row>
@@ -1437,7 +1833,7 @@ frame
 
 \layout Standard
 
-OL Exc gain
+2
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1445,23 +1841,25 @@ OL Exc gain
 
 \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
+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
 
-5
+3
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1469,23 +1867,25 @@ frame
 
 \layout Standard
 
-5
+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
 
-5
+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
 
-5
+4
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1493,7 +1893,7 @@ frame
 
 \layout Standard
 
-5
+4
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -1501,15 +1901,7 @@ frame
 
 \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
+Asks encoder to switch to mode N for high-band
 \end_inset 
 </cell>
 </row>
@@ -1519,7 +1911,7 @@ frame
 
 \layout Standard
 
-Fine pitch
+5
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1527,23 +1919,25 @@ Fine pitch
 
 \layout Standard
 
-sub-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
+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
 
 \layout Standard
 
-0
+6
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1551,17 +1945,19 @@ sub-frame
 
 \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
+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
 
@@ -1575,15 +1971,7 @@ sub-frame
 
 \layout Standard
 
-7
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-7
+4
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -1591,7 +1979,7 @@ sub-frame
 
 \layout Standard
 
-7
+Asks encoder to set CBR (0), VAD(1), DTX(3), VBR(5), VBR+DTX(7)
 \end_inset 
 </cell>
 </row>
@@ -1601,7 +1989,7 @@ sub-frame
 
 \layout Standard
 
-Pitch gain
+8
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1609,23 +1997,25 @@ Pitch gain
 
 \layout Standard
 
-sub-frame
+8
 \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
+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
 
-0
+9
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1633,23 +2023,25 @@ sub-frame
 
 \layout Standard
 
-5
+8
 \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
+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
 
-5
+10
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1657,15 +2049,7 @@ sub-frame
 
 \layout Standard
 
-7
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-7
+16
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -1673,7 +2057,7 @@ sub-frame
 
 \layout Standard
 
-7
+Announce maximum bit-rate acceptable (N in bytes/second)
 \end_inset 
 </cell>
 </row>
@@ -1683,7 +2067,7 @@ sub-frame
 
 \layout Standard
 
-Innovation gain
+11
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1691,23 +2075,25 @@ Innovation gain
 
 \layout Standard
 
-sub-frame
+16
 \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
+reserved
 \end_inset 
 </cell>
+</row>
+<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-1
+12
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1715,23 +2101,25 @@ sub-frame
 
 \layout Standard
 
-0
+32
 \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
 
-1
+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
 
-1
+13
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1739,15 +2127,7 @@ sub-frame
 
 \layout Standard
 
-3
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-3
+32
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -1755,17 +2135,17 @@ sub-frame
 
 \layout Standard
 
-3
+reserved
 \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
+14
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1773,23 +2153,25 @@ Innovation VQ
 
 \layout Standard
 
-sub-frame
+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
 
-0
+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
 
-0
+15
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1797,180 +2179,232 @@ sub-frame
 
 \layout Standard
 
-16
+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
 
-20
+reserved
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
+</row>
+</lyxtabular>
 
-35
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
 
-48
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\layout Caption
 
-\layout Standard
+In-band signalling codes
+\begin_inset LatexCommand \label{cap:In-band-signalling-codes}
 
-64
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
 
-96
 \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
+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}
+
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
 
-5
+\begin_inset LatexCommand \label{sec:Formats-and-standards}
+
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
 
 \layout Standard
 
-43
+Speex can encode speech in both narrowband and wideband and provides different
+ bit-rates.
+ However, not all features need to be supported by a certain implementation
+ or device.
+ In order to be called 
+\begin_inset Quotes eld
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
-
-119
+Speex compatible
+\begin_inset Quotes erd
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
+ (whatever that means), an implementation must implement at least a basic
+ set of features.
 \layout Standard
 
-160
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+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
 
 \layout Standard
 
-220
+The wideband bit-stream contains an embedded narrowband bit-stream which
+ can be decoded alone
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
+.
+ 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
 
-300
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+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
 
-\layout Standard
+RTP
+\begin_inset LatexCommand \index{RTP}
 
-364
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
+ Payload Format 
 \layout Standard
 
-492
-\end_inset 
-</cell>
-</row>
-</lyxtabular>
+The RTP payload draft is included in appendix 
+\begin_inset LatexCommand \ref{sec:IETF-draft}
 
 \end_inset 
 
-
-\layout Caption
-
-Bit allocation for narrowband modes
-\begin_inset LatexCommand \label{cap:bits-narrowband}
+ and the latest version is available at 
+\begin_inset LatexCommand \url{http://www.speex.org/drafts/latest}
 
 \end_inset 
 
+.
+ This draft has been sent (2003/02/26) to the Internet Engineering Task
+ Force (IETF) and will be discussed at the March 18th meeting in San Francisco.
+\layout Subsection
 
-\end_inset 
+MIME Type
+\layout Standard
+
+For now, you should use the MIME type audio/x-speex for Speex-in-Ogg.
+ We will apply for type 
+\family typewriter 
+audio/speex
+\family default 
+ in the near future.
+\layout Subsection
+
+Ogg
+\begin_inset LatexCommand \index{Ogg}
 
+\end_inset 
 
+ file format
 \layout Standard
 
-So far, no MOS (Mean Opinion Score
-\begin_inset LatexCommand \index{mean opinion score}
+Speex bit-streams can be stored in Ogg files.
+ In this case, the first packet of the Ogg file contains the Speex header
+ described in table 
+\begin_inset LatexCommand \ref{cap:ogg_speex_header}
 
 \end_inset 
 
-) 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}
-
+.
+ All integer fields in the headers are stored as little-endian.
+ The 
+\family typewriter 
+speex_string
+\family default 
+ field must contain the 
+\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}
 
+\family typewriter 
+Speex
+\family default 
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+
+\begin_inset Quotes erd
 \end_inset 
 
- in most modes (1 mflops with perceptual enhancement).
+ (with 3 trailing spaces), which identifies the bit-stream.
+ The next field, 
+\family typewriter 
+speex_version
+\family default 
+ contains the version of Speex that encoded the file.
+ For now, refer to speex_header.[ch] for more info.
+ The 
+\emph on 
+beginning of stream
+\emph default 
+ (
+\family typewriter 
+b_o_s
+\family default 
+) flag is set to 1 for the header.
+ The header packet has 
+\family typewriter 
+packetno=0
+\family default 
+ and 
+\family typewriter 
+granulepos=0
+\family default 
+.
+\layout Standard
+
+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
+\family default 
+ and 
+\family typewriter 
+granulepos=0
+\family default 
+.
+\layout Standard
+
+The third and subsequent packets each contain one or more (number found
+ in header) Speex frames.
+ These are identified with 
+\family typewriter 
+packetno
+\family default 
+ starting from 2 and the 
+\family typewriter 
+granulepos
+\family default 
+ is the number of the last sample encoded in that packet.
+ The 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
 
 
 \begin_inset Float table
-placement h
+placement htbp
 wide true
 collapsed false
 
@@ -1978,11 +2412,10 @@ collapsed false
 
 
 \begin_inset  Tabular
-<lyxtabular version="3" rows="17" columns="4">
+<lyxtabular version="3" rows="16" 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" 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">
@@ -1990,7 +2423,7 @@ collapsed false
 
 \layout Standard
 
-Mode
+Field
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1998,25 +2431,33 @@ Mode
 
 \layout Standard
 
-Bit-rate
-\begin_inset LatexCommand \index{bit-rate}
-
+Type
 \end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
- (bps)
+\layout Standard
+
+Size
 \end_inset 
 </cell>
+</row>
+<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-mflops
-\begin_inset LatexCommand \index{complexity}
-
+speex_string
 \end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
+\layout Standard
 
+char[]
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -2024,7 +2465,7 @@ mflops
 
 \layout Standard
 
-Quality/description
+8
 \end_inset 
 </cell>
 </row>
@@ -2034,7 +2475,7 @@ Quality/description
 
 \layout Standard
 
-0
+speex_version
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -2042,75 +2483,77 @@ Quality/description
 
 \layout Standard
 
-250
+char[]
 \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
 
-N/A
+20
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-No sound (VBR only)
+speex_version_id
 \end_inset 
 </cell>
-</row>
-<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-1
+int
 \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
 
-2,150
+4
 \end_inset 
 </cell>
+</row>
+<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-6
+header_size
 \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
 
-Vocoder (mostly for comfort noise)
+int
 \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
+4
 \end_inset 
 </cell>
+</row>
+<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-5,950
+rate
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -2118,7 +2561,7 @@ Vocoder (mostly for comfort noise)
 
 \layout Standard
 
-9
+int
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -2126,7 +2569,7 @@ Vocoder (mostly for comfort noise)
 
 \layout Standard
 
-Very noticeable artifacts/noise, good intelligibility
+4
 \end_inset 
 </cell>
 </row>
@@ -2136,7 +2579,7 @@ Very noticeable artifacts/noise, good intelligibility
 
 \layout Standard
 
-3
+mode
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -2144,41 +2587,51 @@ Very noticeable artifacts/noise, good intelligibility
 
 \layout Standard
 
-8,000
+int
 \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
 
-10
+4
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-Artifacts/noise sometimes noticeable
+mode_bitstream_version
 \end_inset 
 </cell>
-</row>
-<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
+int
+\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">
 \begin_inset Text
 
 \layout Standard
 
-11,000
+nb_channels
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -2186,7 +2639,7 @@ Artifacts/noise sometimes noticeable
 
 \layout Standard
 
-14
+int
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -2194,7 +2647,7 @@ Artifacts/noise sometimes noticeable
 
 \layout Standard
 
-Artifacts usually noticeable only with headphones
+4
 \end_inset 
 </cell>
 </row>
@@ -2204,7 +2657,7 @@ Artifacts usually noticeable only with headphones
 
 \layout Standard
 
-5
+bitrate
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -2212,75 +2665,77 @@ Artifacts usually noticeable only with headphones
 
 \layout Standard
 
-15,000
+int
 \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
 
-11
+4
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-Need good headphones to tell the difference
+frame_size
 \end_inset 
 </cell>
-</row>
-<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-6
+int
 \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,200
+4
 \end_inset 
 </cell>
+</row>
+<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-17.5
+vbr
 \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
 
-Hard to tell the difference even with good headphones
+int
 \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
 
-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
 
-24,600
+frames_per_packet
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -2288,7 +2743,7 @@ Hard to tell the difference even with good headphones
 
 \layout Standard
 
-14.5
+int
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -2296,7 +2751,7 @@ Hard to tell the difference even with good headphones
 
 \layout Standard
 
-Completely transparent for voice, good quality music
+4
 \end_inset 
 </cell>
 </row>
@@ -2306,7 +2761,7 @@ Completely transparent for voice, good quality music
 
 \layout Standard
 
-8
+extra_headers
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -2314,15 +2769,7 @@ Completely transparent for voice, good quality music
 
 \layout Standard
 
-N/A
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-N/A
+int
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -2330,7 +2777,7 @@ N/A
 
 \layout Standard
 
-reserved
+4
 \end_inset 
 </cell>
 </row>
@@ -2340,15 +2787,7 @@ reserved
 
 \layout Standard
 
-9
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-N/A
+reserved1
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -2356,7 +2795,7 @@ N/A
 
 \layout Standard
 
-N/A
+int
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -2364,25 +2803,17 @@ N/A
 
 \layout Standard
 
-reserved
+4
 \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>
+<row topline="true" bottomline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-N/A
+reserved2
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -2390,7 +2821,7 @@ N/A
 
 \layout Standard
 
-N/A
+int
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 
 \layout Standard
 
-reserved
+4
 \end_inset 
 </cell>
 </row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
+</lyxtabular>
 
-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 Caption
 
-\layout Standard
+Ogg/Speex header packet
+\begin_inset LatexCommand \label{cap:ogg_speex_header}
 
-N/A
 \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
+\layout Section
+\pagebreak_top 
+Introduction to CELP Coding
+\begin_inset LatexCommand \index{CELP}
+
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
 
-N/A
+\begin_inset LatexCommand \label{sec:Introduction-to-CELP}
+
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
 
 \layout Standard
 
-N/A
+Speex is based on CELP, which stands for Code Excited Linear Prediction.
+ This section attempts to introduce the principles behind CELP, so if you
+ are already familiar with CELP, you can safely skip to section 
+\begin_inset LatexCommand \ref{sec:Speex-narrowband-mode}
+
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+.
+ The CELP technique is based on three ideas:
+\layout Enumerate
 
-reserved
-\end_inset 
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+The use of a linear prediction (LP) model to model the vocal tract
+\layout Enumerate
 
-\layout Standard
+The use of (adaptive and fixed) codebook entries as input (excitation) of
+ the LP model
+\layout Enumerate
 
-13
+The search performed in closed-loop in a 
+\begin_inset Quotes eld
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
 
-N/A
+perceptually weighted domain
+\begin_inset Quotes erd
 \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" rightline="true" usebox="none">
-\begin_inset Text
+This section describes the basic ideas behind CELP.
+ Note that it's still incomplete.
+\layout Subsection
 
-\layout Standard
+Linear Prediction (LPC)
+\begin_inset LatexCommand \index{linear prediction}
 
-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
+
 
 \layout Standard
 
-14
+Linear prediction is at the base of many speech coding techniques, including
+ CELP.
+ The idea behind it is to predict the signal 
+\begin_inset Formula $x[n]$
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
+ using a linear combination of its past samples:
 \layout Standard
 
-N/A
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+\begin_inset Formula \[
+y[n]=\sum_{i=1}^{N}a_{i}x[n-i]\]
 
-N/A
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+where 
+\begin_inset Formula $y[n]$
+\end_inset 
 
-Speex in-band signaling
+ is the linear prediction of 
+\begin_inset Formula $x[n]$
 \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
+.
+ 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]\]
 
-15
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
 
 \layout Standard
 
-N/A
+The goal of the LPC analysis is to find the best prediction coefficients
+\begin_inset Formula $a_{i}$
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+ 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}\]
 
-N/A
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+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\]
 
-Terminator code
 \end_inset 
-</cell>
-</row>
-</lyxtabular>
 
+
+\layout Standard
+
+The 
+\begin_inset Formula $a_{i}$
 \end_inset 
 
+ filter coefficients are computed using the Levinson-Durbin
+\begin_inset LatexCommand \index{Levinson-Durbin}
 
-\layout Caption
+\end_inset 
 
-Quality versus bit-rate
-\begin_inset LatexCommand \label{cap:quality_vs_bps}
+ 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]$
 \end_inset 
 
+.
+\layout Standard
 
-\layout Subsection
 
-Perceptual enhancement
-\begin_inset LatexCommand \index{perceptual enhancement}
+\begin_inset Formula \[
+R(m)=\sum_{i=0}^{N-1}x[i]x[i-m]\]
 
 \end_inset 
 
 
 \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 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)$
+For an order 
+\begin_inset Formula $N$
 \end_inset 
 
- is replaced by an enhanced filter
+ filter, we have:
 \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)}\]
+\mathbf{R}=\left[\begin{array}{cccc}
+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}\right]\]
 
 \end_inset 
 
-where 
-\begin_inset Formula $a_{1}$
-\end_inset 
 
- and 
-\begin_inset Formula $a_{2}$
+\begin_inset Formula \[
+\mathbf{r}=\left[\begin{array}{c}
+R(1)\\
+R(2)\\
+\vdots\\
+R(N)\end{array}\right]\]
+
 \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)$
+
+\layout Standard
+
+The filter coefficients 
+\begin_inset Formula $a_{i}$
 \end_inset 
 
- with 
-\begin_inset Formula $r=.9$
+ are found by solving the system 
+\begin_inset Formula $\mathbf{Ra}=\mathbf{r}$
 \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}
-
+ What the Levinson-Durbin algorithm does here is making the solution to
+ the problem 
+\begin_inset Formula $\mathcal{O}\left(N^{2}\right)$
 \end_inset 
 
-
-\layout Standard
-
-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
-\begin_inset LatexCommand \index{quadrature mirror filter}
-
+ instead of 
+\begin_inset Formula $\mathcal{O}\left(N^{3}\right)$
 \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}
-
+ by exploiting the fact that matrix 
+\begin_inset Formula $\mathbf{R}$
 \end_inset 
 
- in such a way that the resulting 
-\begin_inset Quotes eld
+ is toeplitz hermitian.
+ Also, it can be proven that all the roots of 
+\begin_inset Formula $A(z)$
 \end_inset 
 
-embedded narrowband bit-stream
-\begin_inset Quotes erd
+ are within the unit circle, which means that 
+\begin_inset Formula $1/A(z)$
 \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
+ is always stable.
+ 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)$
+\end_inset 
 
-Linear Prediction
+ 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 to the auto-correlation, which is equivalent
+ to filtering in the frequency domain, reducing sharp resonances.
 \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
+The linear prediction model represents each speech sample as a linear combinatio
+n 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]\]
 
-Pitch Prediction
-\layout Standard
+\end_inset 
 
-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
+In the 
+\emph on 
+z
+\emph default 
+-domain, this can be expressed as
 \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}
+\begin_inset Formula \[
+x(z)=\frac{1}{A(z)}\: e(z)\]
 
 \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
 
+\layout Standard
 
-\begin_inset Float table
-placement h
-wide true
-collapsed false
+where 
+\begin_inset Formula $A(z)$
+\end_inset 
 
+ is defined as
 \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
+\begin_inset Formula \[
+A(z)=1-\sum_{i=1}^{N}a_{i}z^{-i}\]
 
-Parameter
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
 
 \layout Standard
 
-Update rate
+We usually refer to 
+\begin_inset Formula $A(z)$
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+ as the analysis filter and 
+\begin_inset Formula $1/A(z)$
+\end_inset 
 
-0
+ as the synthesis filter.
+ The whole process is called short-term prediction as it predicts the signal
+\begin_inset Formula $x[n]$
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+ using a prediction using only the 
+\begin_inset Formula $N$
+\end_inset 
 
-1
+ past samples, where 
+\begin_inset Formula $N$
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
+ is usually around 10.
 \layout Standard
 
-2
+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 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+ (LSP) coefficients which have a much better behaviour with quantization,
+ one of them being that it's easy to keep the filter stable.
+\layout Comment
 
-3
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+Describe LSP's
+\layout Subsection
 
-\layout Standard
+Pitch Prediction
+\begin_inset LatexCommand \index{pitch}
 
-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
+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 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
+ by a gain times the past of the excitation:
 \layout Standard
 
-frame
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+\begin_inset Formula \[
+e[n]\simeq p[n]=\beta e[n-T]\]
 
-1
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
 
 \layout Standard
 
-1
+where 
+\begin_inset Formula $T$
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
 
-1
+ is the pitch period, 
+\begin_inset Formula $\beta$
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+ is the pitch gain.
+ We call that long-term prediction since the excitation is predicted from
+\begin_inset Formula $e[n-T]$
+\end_inset 
 
-1
+ with 
+\begin_inset Formula $T\gg N$
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
+.
+\layout Subsection
+
+Innovation Codebook
 \layout Standard
 
-1
+The final excitation 
+\begin_inset Formula $e[n]$
 \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
+ will be the sum of the pitch prediction and an 
+\emph on 
+innovation
+\emph default 
+ signal 
+\begin_inset Formula $c[n]$
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
+ taken from a fixed codebook, hence the name 
+\emph on 
+Code
+\emph default 
+ Excited Linear Prediction.
+ The final excitation is given by:
 \layout Standard
 
-frame
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+\begin_inset Formula \[
+e[n]=p[n]+c[n]=\beta e[n-T]+c[n]\]
 
-3
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
 
-3
+The quantization of 
+\begin_inset Formula $c[n]$
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
-
-3
+ 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 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+ as 
+\begin_inset Formula \[
+X(z)=\frac{C(z)}{A(z)\left(1-\beta z^{-T}\right)}\]
 
-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 Subsection
 
-\layout Standard
+Analysis-by-Synthesis and Error Weighting
+\begin_inset LatexCommand \index{error weighting}
 
-LSP
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
 
-frame
+\begin_inset LatexCommand \index{analysis-by-synthesis}
+
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
 
 \layout Standard
 
-0
+Most (if not all) modern audio codecs attempt to 
+\begin_inset Quotes eld
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
-
-12
+shape
+\begin_inset Quotes erd
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+ 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 instead of minimizing the simple quadratic error
+\begin_inset Formula \[
+E=\sum_{n}\left(x[n]-\overline{x}[n]\right)^{2}\]
 
-12
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
 
-12
+where 
+\begin_inset Formula $\overline{x}[n]$
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+ is the encoder signal, we minimize the error for the perceptually weighted
+ signal
+\begin_inset Formula \[
+X_{w}(z)=W(z)X(z)\]
 
-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
+where 
+\begin_inset Formula $W(z)$
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
+ is the weighting filter, usually of the form
 \layout Standard
 
-sub-frame
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+\begin_inset Formula \begin{equation}
+W(z)=\frac{A\left(\frac{z}{\gamma_{1}}\right)}{A\left(\frac{z}{\gamma_{2}}\right)}\label{eq:weighting_filter}\end{equation}
 
-0
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
 
 \layout Standard
 
-5
+with control parameters 
+\begin_inset Formula $\gamma_{1}>\gamma_{2}$
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+.
+ If the noise is white in the perceptually weighted domain, then in the
+ signal domain its spectral shape will be of the form
+\begin_inset Formula \[
+A_{noise}(z)=\frac{1}{W(z)}=\frac{A\left(\frac{z}{\gamma_{2}}\right)}{A\left(\frac{z}{\gamma_{1}}\right)}\]
 
-4
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
 
 \layout Standard
 
-4
+If a filter 
+\begin_inset Formula $A(z)$
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
-
-4
+ has (complex) poles at 
+\begin_inset Formula $p_{i}$
 \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
+ in the 
+\begin_inset Formula $z$
+\end_inset 
 
-Excitation VQ
+-plane, the filter 
+\begin_inset Formula $A(z/\gamma)$
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+ will have its poles at 
+\begin_inset Formula $p'_{i}=\gamma p_{i}$
+\end_inset 
 
-sub-frame
+, making it a flatter version of 
+\begin_inset Formula $A(z)$
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
+.
 \layout Standard
 
-0
+Analysis-by-synthesis refers to the fact that when trying to find the best
+ pitch parameters (
+\begin_inset Formula $T$
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+, 
+\begin_inset Formula $\beta$
+\end_inset 
 
-0
+) and innovation signal 
+\begin_inset Formula $c[n]$
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+, we do not work by making the excitation 
+\begin_inset Formula $e[n]$
+\end_inset 
 
-20
+ as close as the original one (which would be simpler), but apply the synthesis
+ (and weighting) filter and try making 
+\begin_inset Formula $X_{w}(z)$
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+ as close to the original as possible.
+\layout Section
+\pagebreak_top 
+Speex narrowband mode
+\begin_inset LatexCommand \label{sec:Speex-narrowband-mode}
 
-40
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
 
-80
+\begin_inset LatexCommand \index{narrowband}
+
 \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
+This section looks at how Speex works for narrowband (
+\begin_inset Formula $8\:\mathrm{kHz}$
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
 
-frame
+ sampling rate) operation.
+ The frame size for this mode is 
+\begin_inset Formula $20\:\mathrm{ms}$
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
+, corresponding to 160 samples.
+ Each frame is also subdivided into 4 sub-frames of 40 samples each.
 \layout Standard
 
-4
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+Also many design decisions were based on the original goals and assumptions:
+\layout Itemize
 
-\layout Standard
+Minimizing the amount of information extracted from past frames (for robustness
+ to packet loss)
+\layout Itemize
 
-36
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+Dynamically-selectable codebooks (LSP, pitch and innovation)
+\layout Itemize
 
-\layout Standard
+sub-vector fixed (innovation) codebooks
+\layout Subsection
+
+LPC Analysis
+\begin_inset LatexCommand \index{linear prediction}
 
-112
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
 
 \layout Standard
 
-192
+An LPC analysis is first performed on a (asymetric Hamming) window that
+ spans all of 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 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
+ sub-frames and the LSP's associated to the first 3 sub-frames are linearly
+ interpolated using the current and previous LSP's.
 \layout Standard
 
-352
-\end_inset 
-</cell>
-</row>
-</lyxtabular>
+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 is derived from the LPC filter 
+\begin_inset Formula $A(z)$
+\end_inset 
 
-\layout Caption
+ and corresponds to the one described by eq.
+\begin_inset LatexCommand \ref{eq:weighting_filter}
 
-Bit allocation for high-band in wideband mode
-\begin_inset LatexCommand \label{cap:bits-wideband}
+\end_inset 
 
+ with 
+\begin_inset Formula $\gamma_{1}=0.9$
 \end_inset 
 
+ and 
+\begin_inset Formula $\gamma_{2}=0.6$
+\end_inset 
 
+.
+ We can use the unquantized 
+\begin_inset Formula $A(z)$
 \end_inset 
 
+ filter since the weighting filter is only used in the encoder.
+\layout Subsection
 
-\layout Standard
+Pitch Prediction (adaptive codebook)
+\begin_inset LatexCommand \index{pitch}
 
+\end_inset 
 
-\begin_inset ERT
-status Open
 
 \layout Standard
 
-\backslash 
-clearpage
+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 \[
+p[n]=\beta_{0}e[n-T-1]+\beta_{1}e[n-T]+\beta_{2}e[n-T+1]\]
+
+\end_inset 
 
-\layout Section
-\pagebreak_top 
-Feature description
-\layout Subsection*
 
-Sampling rate
 \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, wideband and ultra-wideband.
-\layout Subsection*
+where 
+\begin_inset Formula $T$
+\end_inset 
 
-Quality
-\layout Subsection*
+ is the pitch period and the 
+\begin_inset Formula $\beta_{i}$
+\end_inset 
 
-Complexity (variable)
-\layout Standard
+ 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 
 
-With Speex, it is possible to vary the complexity allowed for the encoder.
-\layout Subsection*
+.
+ For example, when 
+\begin_inset Formula $n-T+1$
+\end_inset 
 
-Variable Bit-Rate (VBR)
-\layout Standard
+, we use 
+\begin_inset Formula $n-2T+1$
+\end_inset 
 
-Variable bit-rate (VBR) allows a codec to change its bit-rate dynamically
- to adapt to the 
-\begin_inset Quotes eld
+ instead.
+ The period and quantized gains are determined in closed loop (analysis-by-synth
+esis).
+ In most modes, the pitch period is encoded with 7 bits in the 
+\begin_inset Formula $\left[17,144\right]$
 \end_inset 
 
-difficulty
-\begin_inset Quotes erd
+ range and the 
+\begin_inset Formula $\beta_{i}$
 \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 (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*
+ 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
 
-Average Bit-Rate (ABR)
+Innovation Codebook
 \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.
-\layout Subsection*
+In Speex, the innovation signal is quantized using sub-vector shape-only
+ vector quantization (VQ).
+ That means that the innovation signal is divided in sub-vectors (of size
+ 5 to 20) and quantized using a codebook that represents both the shape
+ and the gain at the same time.
+ This saves many bits that would otherwise be allocated for a separate gain
+ at the price of a slight increase in complexity.
+\layout Subsection
 
-Voice Activity Detection (VAD)
+Bit allocation
 \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 calles 
+There are 7 different narrowband bit-rates defined for Speex, ranging from
+ 250 bps to 24.6 kbps, although the modes below 5.9 kbps should not be used
+ for speech.
+ The bit-allocation for each mode is detailed in table 
+\begin_inset LatexCommand \ref{cap:bits-narrowband}
+
+\end_inset 
+
+.
+ Each frame starts with the mode ID encoded with 4 bits which allows a range
+ from 0 to 15, though only the first 7 values are used (the others are reserved).
+ The parameters are listed in the table in the order they are packed in
+ the bit-stream.
+ 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 
 
-comfort noise generation
+OL
 \begin_inset Quotes erd
 \end_inset 
 
- (CNG).
-\layout Subsection*
-
-Discontinuous Transmission (DTX)
+ in the parameter description means that the parameter is an open loop estimatio
+n based on the whole frame.
 \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
-\layout Standard
+\begin_inset Float table
+placement h
+wide true
+collapsed false
 
-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 Section
-\pagebreak_top 
-Command-line encoder/decoder
-\begin_inset LatexCommand \label{sec:Command-line-encoder/decoder}
+\layout Standard
 
-\end_inset 
 
+\begin_inset  Tabular
+<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">
+<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" 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 base Speex distribution includes a command-line encoder (
-\emph on 
-speexenc
-\emph default 
-) and decoder (
-\emph on 
-speexdec
-\emph default 
-).
-\layout Subsection
-
+Parameter
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-\emph on 
-speexenc
-\begin_inset LatexCommand \index{speexenc}
+\layout Standard
 
+Update rate
 \end_inset 
-
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
 \layout Standard
 
-The encoder takes the following options:
-\layout Description
+0
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
---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
+\layout Standard
 
---ultra-wideband\SpecialChar ~
-(-u) Tell Speex to treat the input as 
-\begin_inset Quotes eld
+1
 \end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-ultra-wideband
-\begin_inset Quotes erd
+\layout Standard
+
+2
 \end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- (32 kHz)
-\layout Description
+\layout Standard
 
---quality\SpecialChar ~
-n Set the encoding quality (0-10), default is 8
-\layout Description
+3
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
---bitrate\SpecialChar ~
-n Encoding bit-rate (use bit-rate n or lower) 
-\layout Description
+\layout Standard
 
---vbr Enable VBR (Variable Bit-Rate), disabled by default
-\layout Description
+4
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
---abr\SpecialChar ~
-n Enable ABR (Average Bit-Rate) at n kbps, disabled by default
-\layout Description
+\layout Standard
 
---vad Enable VAD (Voice Activity Detection), disabled by default
-\layout Description
+5
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
---dtx Enable DTX (Discontinuous Transmission), disabled by default
-\layout Description
+\layout Standard
 
---nframes\SpecialChar ~
-n Pack n frames in each Ogg packet (this saves space at low bit-rates)
-\layout Description
+6
+\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
 
--V Verbose operation, print bit-rate currently in use
-\layout Description
+7
+\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) Print version information
-\layout Subsubsection*
+8
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-Speex comments
-\layout Description
+\layout Standard
 
---comment Add the given string as an extra comment.
- This may be used multiple times.
-\layout Description
+Wideband bit
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
---author Author of this track.
-\layout Description
+\layout Standard
 
---title Title for this track.
-\layout Subsubsection*
+frame
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-Raw input options
-\layout Description
+\layout Standard
 
---rate\SpecialChar ~
-n Sampling rate for raw input
-\layout Description
+1
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
---stereo Consider raw input as stereo 
-\layout Description
+\layout Standard
 
---le Raw input is little-endian 
-\layout Description
+1
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
---be Raw input is big-endian 
-\layout Description
+\layout Standard
 
---8bit Raw input is 8-bit unsigned 
-\layout Description
+1
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
---16bit Raw input is 16-bit signed 
-\layout Subsection
+\layout Standard
 
+1
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-\emph on 
-speexdec
-\begin_inset LatexCommand \index{speexdec}
+\layout Standard
 
+1
 \end_inset 
-
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
 \layout Standard
 
-The decoder takes the following options:
-\layout Description
-
---enh enable post-filter (default)
-\layout Description
+1
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
---no-enh disable post-filter
-\layout Description
+\layout Standard
 
---force-nb Force decoding in narrowband 
-\layout Description
+1
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
---force-wb Force decoding in wideband 
-\layout Description
+\layout Standard
 
---force-uwb Force decoding in ultra-wideband 
-\layout Description
+1
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
---mono Force decoding in mono 
-\layout Description
+\layout Standard
 
---stereo Force decoding in stereo 
-\layout Description
+1
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
---rate\SpecialChar ~
-n For decoding at n Hz sampling rate
-\layout Description
+\layout Standard
 
---packet-loss\SpecialChar ~
-n Simulate n % rando m packet loss
-\layout Description
+Mode ID
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
--V Verbose operation, print bit-rate currently in use
-\layout Description
+\layout Standard
 
---help\SpecialChar ~
-(-h) Print the help
-\layout Description
+frame
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
---version\SpecialChar ~
-(-v) Print version information
-\layout Section
-\pagebreak_top 
-Programming with Speex (the libspeex
-\begin_inset LatexCommand \index{libspeex}
+\layout Standard
 
+4
 \end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- API
-\begin_inset LatexCommand \index{API}
+\layout Standard
 
+4
 \end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-)
-\layout Subsection
-
-Encoding
 \layout Standard
 
-In order to encode speech using Speex, you first need to:
-\layout LyX-Code
+4
+\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
+4
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-SpeexBits bits;
 \layout Standard
 
-and a Speex encoder state
-\layout LyX-Code
+4
+\end_inset 
+</cell>
+<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
+4
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
-speex_bits_init(&bits);
-\layout LyX-Code
+\layout Standard
+
+4
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="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
+4
+\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
+4
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-speex_bits_reset(&bits);
-\layout LyX-Code
+\layout Standard
 
-speex_encode(enc_state, input_frame, &bits);
-\layout LyX-Code
+LSP
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-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.
+frame
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
 \layout Standard
 
-After you're done with the encoding, free all resources with:
-\layout LyX-Code
+0
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-speex_bits_destroy(&bits);
-\layout LyX-Code
+\layout Standard
+
+18
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-speex_encoder_destroy(enc_state);
 \layout Standard
 
-That's about it for the encoder.
-\layout Subsection
+18
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-Decoding
 \layout Standard
 
-In order to encode speech using Speex, you first need to:
-\layout LyX-Code
+18
+\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
+18
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-SpeexBits bits;
 \layout Standard
 
-and a Speex encoder state
-\layout LyX-Code
+30
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
-void *dec_state;
 \layout Standard
 
-The two are initialized by:
-\layout LyX-Code
+30
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
-speex_bits_init(&bits);
-\layout LyX-Code
+\layout Standard
+
+30
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
-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 
-.
- You can get that value in the 
-\emph on 
-frame_size
-\emph default 
- variable with:
-\layout LyX-Code
+18
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-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
+OL pitch
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-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.
+frame
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
 \layout Standard
 
-Again, once the decoder initialization is done, for every input frame:
-\layout LyX-Code
+0
+\end_inset 
+</cell>
+<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
+
+7
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-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.
+7
+\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
+
+0
+\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>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+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
+
+OL pitch gain
+\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
+
+4
+\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
+
+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" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0
+\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>
+<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">
+\begin_inset Text
+
+\layout Standard
+
+OL Exc gain
+\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
+
+5
+\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
+
+5
+\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
+
+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>
+<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">
+\begin_inset Text
+
+\layout Standard
+
+Fine pitch
+\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
 
-After you're done with the decoding, free all resources with:
-\layout LyX-Code
+0
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-speex_bits_destroy(&bits);
-\layout LyX-Code
+\layout Standard
 
-speex_decoder_destroy(dec_state);
-\layout Subsection
+7
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="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
+7
+\end_inset 
+</cell>
+<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" 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
+
+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">
+\begin_inset Text
+
+\layout Standard
+
+Pitch 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
+
+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
+
+5
+\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
+
+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
+
+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">
+\begin_inset Text
+
+\layout Standard
+
+Innovation 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
+
+1
+\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
+
+1
+\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" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+3
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+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">
+\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
+Innovation VQ
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-SPEEX_SET_ENH** Set perceptual enhancer to on (1) or off (0) (integer)
-\layout Description
+\layout Standard
 
-SPEEX_GET_ENH** Get perceptual enhancer status (integer)
-\layout Description
+sub-frame
+\end_inset 
+</cell>
+<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
+0
+\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 $
+0
 \end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
+\layout Standard
 
-\layout Description
-
-SPEEX_GET_MODE*
-\begin_inset Formula $\dagger $
+16
 \end_inset 
+</cell>
+<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 $
+20
 \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 $
+35
 \end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
+\layout Standard
 
-\layout Description
-
-SPEEX_SET_HIGH_MODE*
-\begin_inset Formula $\dagger $
+48
 \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_HIGH_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
+96
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
-SPEEX_SET_VBR* Set variable bit-rate (VBR) to on (1) or off (0) (integer)
-\layout Description
+\layout Standard
 
-SPEEX_GET_VBR* Get variable bit-rate (VBR) status (integer)
-\layout Description
+10
+\end_inset 
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-SPEEX_SET_VBR_QUALITY* Set the encoder VBR speech quality (integer 0 to
- 10)
-\layout Description
+\layout Standard
 
-SPEEX_GET_VBR_QUALITY* Get the current encoder VBR speech quality (integer
- 0 to 10)
-\layout Description
+Total
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-SPEEX_SET_COMPLEXITY* Set the CPU resources allowed for the encoder (integer
- 1 to 10)
-\layout Description
+\layout Standard
 
-SPEEX_GET_COMPLEXITY* Get the CPU resources allowed for the encoder (integer
- 1 to 10)
-\layout Description
+frame
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-SPEEX_SET_BITRATE* Set the bit-rate to use to the closest value not exceeding
- the parameter (integer in bps)
-\layout Description
+\layout Standard
 
-SPEEX_GET_BITRATE Get the current bit-rate in use (integer in bps)
-\layout Description
+5
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-SPEEX_SET_SAMPLING_RATE Set real sampling rate (integer in Hz)
-\layout Description
+\layout Standard
 
-SPEEX_GET_SAMPLING_RATE Get real sampling rate (integer in Hz)
-\layout Description
+43
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-* applies only to the encoder
-\layout Description
+\layout Standard
 
-** applies only to the decoder
-\layout Description
+119
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
+\layout Standard
 
-\begin_inset Formula $\dagger $
+160
 \end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- normally only used internally
-\layout Subsection
+\layout Standard
+
+220
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-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
+300
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
-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
+364
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
-SPEEX_MODE_FRAME_SIZE Get the frame size (in samples) for the mode
-\layout Description
+\layout Standard
 
-SPEEX_SUBMODE_BITRATE Get the bit-rate for a submode number specified throught
-\emph on 
-ptr
-\emph default 
- (integer in bps).
-\layout Subsection
+492
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
-Packing and in-band signalling
-\begin_inset LatexCommand \index{in-band signalling}
+\layout Standard
+
+79
+\end_inset 
+</cell>
+</row>
+</lyxtabular>
 
 \end_inset 
 
 
-\layout Standard
+\layout Caption
+
+Bit allocation for narrowband modes
+\begin_inset LatexCommand \label{cap:bits-narrowband}
 
-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 
+So far, no MOS (Mean Opinion Score
+\begin_inset LatexCommand \index{mean opinion score}
 
-messages
-\begin_inset Quotes erd
 \end_inset 
 
- to the other side.
- All these messages are encoded as a 
-\begin_inset Quotes eld
-\end_inset 
+) 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}
 
-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}
+ 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 (within 0.5 mflops and using
+ the lowest complexity setting).
+ Decoding requires approximately 0.5 mflops
+\begin_inset LatexCommand \index{complexity}
 
 \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.
+ in most modes (1 mflops with perceptual enhancement).
 \layout Standard
 
 
 \begin_inset Float table
-placement htbp
-wide false
+placement h
+wide true
 collapsed false
 
 \layout Standard
 
 
 \begin_inset  Tabular
-<lyxtabular version="3" rows="17" columns="3">
+<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">
@@ -3961,7 +4754,7 @@ collapsed false
 
 \layout Standard
 
-code
+Mode
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -3969,7 +4762,25 @@ code
 
 \layout Standard
 
-Size (bits)
+Bit-rate
+\begin_inset LatexCommand \index{bit-rate}
+
+\end_inset 
+
+ (bps)
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+mflops
+\begin_inset LatexCommand \index{complexity}
+
+\end_inset 
+
+
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -3977,7 +4788,7 @@ Size (bits)
 
 \layout Standard
 
-Content
+Quality/description
 \end_inset 
 </cell>
 </row>
@@ -3995,7 +4806,15 @@ Content
 
 \layout Standard
 
-1
+250
+\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" rightline="true" usebox="none">
@@ -4003,7 +4822,7 @@ Content
 
 \layout Standard
 
-Asks decoder to set perceptual enhancement off (0) or on(1)
+No transmission (DTX)
 \end_inset 
 </cell>
 </row>
@@ -4021,7 +4840,15 @@ Asks decoder to set perceptual enhancement off (0) or on(1)
 
 \layout Standard
 
-1
+2,150
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+6
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -4029,7 +4856,7 @@ Asks decoder to set perceptual enhancement off (0) or on(1)
 
 \layout Standard
 
-reserved
+Vocoder (mostly for comfort noise)
 \end_inset 
 </cell>
 </row>
@@ -4047,7 +4874,15 @@ reserved
 
 \layout Standard
 
-4
+5,950
+\end_inset 
+</cell>
+<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" rightline="true" usebox="none">
@@ -4055,7 +4890,7 @@ reserved
 
 \layout Standard
 
-Asks encoder to switch to mode N
+Very noticeable artifacts/noise, good intelligibility
 \end_inset 
 </cell>
 </row>
@@ -4073,7 +4908,15 @@ Asks encoder to switch to mode N
 
 \layout Standard
 
-4
+8,000
+\end_inset 
+</cell>
+<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" rightline="true" usebox="none">
@@ -4081,7 +4924,7 @@ Asks encoder to switch to mode N
 
 \layout Standard
 
-Asks encoder to switch to mode N for low-band
+Artifacts/noise sometimes noticeable
 \end_inset 
 </cell>
 </row>
@@ -4099,7 +4942,15 @@ Asks encoder to switch to mode N for low-band
 
 \layout Standard
 
-4
+11,000
+\end_inset 
+</cell>
+<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" rightline="true" usebox="none">
@@ -4107,7 +4958,7 @@ Asks encoder to switch to mode N for low-band
 
 \layout Standard
 
-Asks encoder to switch to mode N for high-band
+Artifacts usually noticeable only with headphones
 \end_inset 
 </cell>
 </row>
@@ -4125,7 +4976,15 @@ Asks encoder to switch to mode N for high-band
 
 \layout Standard
 
-4
+15,000
+\end_inset 
+</cell>
+<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" rightline="true" usebox="none">
@@ -4133,7 +4992,7 @@ Asks encoder to switch to mode N for high-band
 
 \layout Standard
 
-Asks encoder to switch to quality N for VBR
+Need good headphones to tell the difference
 \end_inset 
 </cell>
 </row>
@@ -4151,7 +5010,15 @@ Asks encoder to switch to quality N for VBR
 
 \layout Standard
 
-4
+18,200
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+17.5
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -4159,7 +5026,7 @@ Asks encoder to switch to quality N for VBR
 
 \layout Standard
 
-Request acknowloedge (0=no, 1=all, 2=only for in-band data)
+Hard to tell the difference even with good headphones
 \end_inset 
 </cell>
 </row>
@@ -4177,7 +5044,15 @@ Request acknowloedge (0=no, 1=all, 2=only for in-band data)
 
 \layout Standard
 
-4
+24,600
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+14.5
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -4185,7 +5060,7 @@ Request acknowloedge (0=no, 1=all, 2=only for in-band data)
 
 \layout Standard
 
-Asks encoder to set VBR off (0), on(1), VAD(2), DTX(3)
+Completely transparent for voice, good quality music
 \end_inset 
 </cell>
 </row>
@@ -4203,7 +5078,15 @@ Asks encoder to set VBR off (0), on(1), VAD(2), DTX(3)
 
 \layout Standard
 
-8
+3,950
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+10.5
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -4211,7 +5094,7 @@ Asks encoder to set VBR off (0), on(1), VAD(2), DTX(3)
 
 \layout Standard
 
-Transmit (8-bit) character to the other end
+Very noticeable artifacts/noise, good intelligibility
 \end_inset 
 </cell>
 </row>
@@ -4229,7 +5112,15 @@ Transmit (8-bit) character to the other end
 
 \layout Standard
 
-8
+N/A
+\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" rightline="true" usebox="none">
@@ -4237,7 +5128,7 @@ Transmit (8-bit) character to the other end
 
 \layout Standard
 
-Intensity stereo information
+reserved
 \end_inset 
 </cell>
 </row>
@@ -4255,7 +5146,15 @@ Intensity stereo information
 
 \layout Standard
 
-16
+N/A
+\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" rightline="true" usebox="none">
@@ -4263,7 +5162,7 @@ Intensity stereo information
 
 \layout Standard
 
-Announce maximum bit-rate acceptable (N in bytes/second)
+reserved
 \end_inset 
 </cell>
 </row>
@@ -4281,7 +5180,15 @@ Announce maximum bit-rate acceptable (N in bytes/second)
 
 \layout Standard
 
-16
+N/A
+\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" rightline="true" usebox="none">
@@ -4307,7 +5214,15 @@ reserved
 
 \layout Standard
 
-32
+N/A
+\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" rightline="true" usebox="none">
@@ -4315,7 +5230,7 @@ reserved
 
 \layout Standard
 
-Acknowledge receiving packet N
+reserved
 \end_inset 
 </cell>
 </row>
@@ -4333,7 +5248,15 @@ Acknowledge receiving packet N
 
 \layout Standard
 
-32
+N/A
+\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" rightline="true" usebox="none">
@@ -4341,7 +5264,7 @@ Acknowledge receiving packet N
 
 \layout Standard
 
-reserved
+Application-defined, interpreted by callback or skipped
 \end_inset 
 </cell>
 </row>
@@ -4359,7 +5282,15 @@ reserved
 
 \layout Standard
 
-64
+N/A
+\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" rightline="true" usebox="none">
@@ -4367,7 +5298,7 @@ reserved
 
 \layout Standard
 
-reserved
+Speex in-band signaling
 \end_inset 
 </cell>
 </row>
@@ -4385,229 +5316,197 @@ reserved
 
 \layout Standard
 
-64
+N/A
+\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" rightline="true" usebox="none">
 \begin_inset Text
 
-\layout Standard
+\layout Standard
+
+Terminator code
+\end_inset 
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset 
+
+
+\layout Caption
+
+Quality versus bit-rate
+\begin_inset LatexCommand \label{cap:quality_vs_bps}
+
+\end_inset 
+
+
+\end_inset 
+
+
+\layout Subsection
+
+Perceptual enhancement
+\begin_inset LatexCommand \index{perceptual enhancement}
+
+\end_inset 
+
+
+\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 and described here should
+ only be considered as a reference implementation.
+ The enhancement system is divided into two parts.
+ First, the synthesis filter 
+\begin_inset Formula $S(z)=1/A(z)$
+\end_inset 
+
+ 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)}\]
+
+\end_inset 
 
-reserved
+where 
+\begin_inset Formula $a_{1}$
 \end_inset 
-</cell>
-</row>
-</lyxtabular>
 
+ 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 
 
-\layout Caption
+ with 
+\begin_inset Formula $r=.9$
+\end_inset 
 
-In-band signalling codes
-\begin_inset LatexCommand \label{cap:In-band-signalling-codes}
+.
+ 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 
 
 
+\begin_inset LatexCommand \label{sec:Speex-wideband-mode}
+
 \end_inset 
 
 
 \layout Standard
 
-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}
+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
+\begin_inset LatexCommand \index{quadrature mirror filter}
 
 \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}
 
-\layout Standard
+\end_inset 
 
-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 
+ in such a way that the resulting 
 \begin_inset Quotes eld
 \end_inset 
 
-Speex compatible
+embedded narrowband bit-stream
 \begin_inset Quotes erd
 \end_inset 
 
- (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
-
-\layout Standard
-
-The wideband bit-stream contains an embedded narrowband bit-stream which
- can be decoded alone
-\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
 
-.
- 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).
+Linear Prediction
 \layout Standard
 
-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.
+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
 
-RTP
-\begin_inset LatexCommand \index{RTP}
-
-\end_inset 
-
- Payload Format 
+Pitch Prediction
 \layout Standard
 
-The latest RTP payload draft can be found at 
-\begin_inset LatexCommand \url{http://www.speex.org/drafts/latest}
-
-\end_inset 
-
-.
- We are (2002/11/11) about to send the latest draft to the IETF for comments.
-\layout Comment
-
-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.
+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 is no longer at multiples of the fundamental
+ (pitch).
 \layout Subsection
 
-MIME Type
+Excitation Quantization
 \layout Standard
 
-Speex will use the MIME type 
-\family typewriter 
-audio/speex
-\family default 
-.
- We will apply for that type in the near future.
+The high-band excitation is coded in the same way as for narrowband.
 \layout Subsection
 
-Ogg
-\begin_inset LatexCommand \index{Ogg}
-
-\end_inset 
-
- file format
+Bit allocation
 \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
described in table 
-\begin_inset LatexCommand \ref{cap:ogg_speex_header}
+For the wideband mode, the entire 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 
 
 .
- All integer fields in the headers are stored as little-endian.
- The 
-\family typewriter 
-speex_string
-\family default 
- field must contain the 
-\begin_inset Quotes eld
-\end_inset 
-
-
-\family typewriter 
-Speex
-\family default 
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
+ The high-band follows, as described in table 
+\begin_inset LatexCommand \ref{cap:bits-wideband}
 
-\begin_inset Quotes eld
 \end_inset 
 
- (with 3 training spaces), which identifies the bit-stream.
- The next field, 
-\family typewriter 
-speex_version
-\family default 
- contains the version of Speex that encoded the file.
- For now, refer to speex_header.[ch] for more info.
- The 
-\emph on 
-beginning of stream
-\emph default 
- (
-\family typewriter 
-b_o_s
-\family default 
-) flag is set to 1 for the header.
- The header packet has 
-\family typewriter 
-packetno=0
-\family default 
- and 
-\family typewriter 
-granulepos=0
-\family default 
-.
-\layout Standard
-
-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
-\family default 
- and 
-\family typewriter 
-granulepos=0
-\family default 
 .
-\layout Standard
-
-The third and subsequant packets each contain one or more (number found
- in header) Speex frames.
- These are identified with 
-\family typewriter 
-packetno
-\family default 
- starting from 2 and the 
-\family typewriter 
-granulepos
-\family default 
- 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.
+ 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 htbp
+placement h
 wide true
 collapsed false
 
@@ -4615,10 +5514,14 @@ collapsed false
 
 
 \begin_inset  Tabular
-<lyxtabular version="3" rows="16" columns="3">
+<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">
@@ -4626,7 +5529,7 @@ collapsed false
 
 \layout Standard
 
-Field
+Parameter
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -4634,25 +5537,23 @@ Field
 
 \layout Standard
 
-Type
+Update rate
 \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
 
-Size
+0
 \end_inset 
 </cell>
-</row>
-<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-speex_string
+1
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -4660,15 +5561,23 @@ speex_string
 
 \layout Standard
 
-char[]
+2
 \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
 
-8
+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>
@@ -4678,7 +5587,7 @@ char[]
 
 \layout Standard
 
-speex_version
+Wideband bit
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -4686,25 +5595,23 @@ speex_version
 
 \layout Standard
 
-char[]
+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
 
-20
+1
 \end_inset 
 </cell>
-</row>
-<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-speex_header_version
+1
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -4712,51 +5619,49 @@ speex_header_version
 
 \layout Standard
 
-int
+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
 
-4
+1
 \end_inset 
 </cell>
-</row>
-<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-header_size
+1
 \end_inset 
 </cell>
+</row>
+<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-int
+Mode ID
 \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
 
-4
+frame
 \end_inset 
 </cell>
-</row>
-<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-rate
+3
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -4764,25 +5669,23 @@ rate
 
 \layout Standard
 
-int
+3
 \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
 
-4
+3
 \end_inset 
 </cell>
-</row>
-<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-mode
+3
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -4790,25 +5693,25 @@ mode
 
 \layout Standard
 
-int
+3
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-4
+LSP
 \end_inset 
 </cell>
-</row>
-<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-mode_bitstream_version
+frame
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -4816,25 +5719,23 @@ mode_bitstream_version
 
 \layout Standard
 
-int
+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
 
-4
+12
 \end_inset 
 </cell>
-</row>
-<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-nb_channels
+12
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -4842,15 +5743,15 @@ nb_channels
 
 \layout Standard
 
-int
+12
 \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
 
-4
+12
 \end_inset 
 </cell>
 </row>
@@ -4860,7 +5761,7 @@ int
 
 \layout Standard
 
-bitrate
+Excitation gain
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -4868,25 +5769,23 @@ bitrate
 
 \layout Standard
 
-int
+sub-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
 
-4
+0
 \end_inset 
 </cell>
-</row>
-<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-frame_size
+5
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -4894,10 +5793,10 @@ frame_size
 
 \layout Standard
 
-int
+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
@@ -4905,40 +5804,38 @@ int
 4
 \end_inset 
 </cell>
-</row>
-<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-vbr
+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
 
-int
+Excitation 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
 
-4
+sub-frame
 \end_inset 
 </cell>
-</row>
-<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-frames_per_packet
+0
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -4946,25 +5843,23 @@ frames_per_packet
 
 \layout Standard
 
-int
+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
 
-4
+20
 \end_inset 
 </cell>
-</row>
-<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-reserved1
+40
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -4972,25 +5867,25 @@ reserved1
 
 \layout Standard
 
-int
+80
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-4
+Total
 \end_inset 
 </cell>
-</row>
-<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-reserved2
+frame
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -4998,25 +5893,23 @@ reserved2
 
 \layout Standard
 
-int
+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
 
-4
+36
 \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
 
-reserved3
+112
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -5024,15 +5917,15 @@ reserved3
 
 \layout Standard
 
-int
+192
 \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
 
-4
+352
 \end_inset 
 </cell>
 </row>
@@ -5043,8 +5936,8 @@ int
 
 \layout Caption
 
-Ogg/Speex header packet
-\begin_inset LatexCommand \label{cap:ogg_speex_header}
+Bit allocation for high-band in wideband mode
+\begin_inset LatexCommand \label{cap:bits-wideband}
 
 \end_inset 
 
@@ -5056,6 +5949,19 @@ Ogg/Speex header packet
 
 
 \begin_inset ERT
+status Open
+
+\layout Standard
+
+\backslash 
+clearpage
+\end_inset 
+
+
+\layout Standard
+
+
+\begin_inset ERT
 status Collapsed
 
 \layout Standard
@@ -5080,7 +5986,7 @@ Vorbis is open-source
 
 \end_inset 
 
-, why do we need Speex?
+; why do we need Speex?
 \layout Standard
 
 Vorbis is a great project but its goals are not the same as Speex.
@@ -5090,6 +5996,46 @@ 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*
 
+Isn't there an open-source implementation of the GSM-FR codec? Why is Speex
+ necessary?
+\layout Standard
+
+First of all, it's not clear whether GSM-FR is covered by a Philips patent
+ (see http://kbs.cs.tu-berlin.de/~jutta/toast.html).
+ Also, GSM-FR offers mediocre quality at a relatively high bit-rate, while
+ Speex can offer equivalent quality at almost half the bit-rate.
+ Last but not least, Speex offers a wide range of bit-rates and sampling
+ rates, while GSM-FR is limited to 8 kHz speech at 13 kbps.
+\layout Subsection*
+
+Under what license is Speex released?
+\layout Standard
+
+As of version 1.0 beta 1, Speex is released under Xiph's version of the (revised)
+ BSD license (see Appendix 
+\begin_inset LatexCommand \ref{sec:Speex-License}
+
+\end_inset 
+
+).
+ This license is the most permissive of the open-source licenses.
+\layout Subsection*
+
+Am I allowed to use Speex in commercial software?
+\layout Standard
+
+Yes.
+ As long as you comply with the license.
+ This basically means you have to keep the copyright notice and you can't
+ use our name to promote your product without authorization.
+ For more details, see license in Appendix 
+\begin_inset LatexCommand \ref{sec:Speex-License}
+
+\end_inset 
+
+.
+\layout Subsection*
+
 Ogg
 \begin_inset LatexCommand \index{Ogg}
 
@@ -5103,15 +6049,7 @@ Ogg
 , what's the difference?
 \layout Standard
 
-Ogg is a 
-\begin_inset Quotes eld
-\end_inset 
-
-file format
-\begin_inset Quotes erd
-\end_inset 
-
- for holding multimedia data.
+Ogg is a container format 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
@@ -5125,7 +6063,15 @@ Ogg Speex
 
  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.
+ Actually, if you just do Voice over 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 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
@@ -5141,7 +6087,7 @@ Just like Vorbis is not really adapted to speech, Speex is really not adapted
  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.
+I converted some MP3s to Speex and the quality is bad.
  What's wrong?
 \layout Standard
 
@@ -5156,8 +6102,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.
+Compilation on Windows has been supported since version 0.8.0.
There are also several front-ends available from the website.
 \layout Subsection*
 
 Why is encoding so slow compared to decoding?
@@ -5167,7 +6113,7 @@ 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
+ On the other hand, at decoding all that needs to be done is look up 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.
@@ -5176,10 +6122,11 @@ For most kinds of compression, encoding is inherently slower than decoding.
 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.
+You probably didn't build Speex with the fixed-point option (--enable-fixed-poin
+t).
+ Even if you did, not all modes have been ported to use fixed-point arithmetic,
+ so the code may be slowed down by a few float operations left (e.g.
+ in the wideband mode).
 \layout Subsection*
 
 I'm getting unusual background noise (hiss) when using libspeex in my applicatio
@@ -5187,20 +6134,20 @@ n.
  How do I fix that?
 \layout Standard
 
-One of the cause could be scaling of the input speech.
+One of the causes could be scaling of the input speech.
  Speex expects signals to have a 
-\begin_inset Formula $\pm 2^{15}$
+\begin_inset Formula $\pm2^{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$
+\begin_inset Formula $\pm1.0$
 \end_inset 
 
 ), you will suffer important quantization noise.
  A good target is to have a dynamic range around 
-\begin_inset Formula $\pm 8000$
+\begin_inset Formula $\pm8000$
 \end_inset 
 
  which is large enough, but small enough to make sure there's no clipping
@@ -5217,13 +6164,30 @@ There are many possible causes for that.
  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}$
+\begin_inset Formula $\pm2^{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*
 
+How does Speex compare to other proprietary codecs?
+\layout Standard
+
+It's hard to give precise figures since no formal listening tests have been
+ performed yet.
+ All I can say is that in terms of quality, Speex competes on the same ground
+ as other proprietary codecs (not necessarily the best, but not the worst
+ either).
+ Speex also has many features that are not present in most other codecs.
+ These include variable bit-rate (VBR), integration of narrowband and wideband,
+ as well as stereo support.
+ Of course, another area where Speex is really hard to beat is the quality/price
+ ratio.
+ Unlike many very expensive codecs, Speex is free and anyone may distribute
+ or modify it at will.
+\layout Subsection*
+
 Can Speex pass DTMF
 \begin_inset LatexCommand \index{DTMF}
 
@@ -5233,24 +6197,28 @@ Can Speex pass DTMF
 \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.
+ Though no formal testing has yet been performed, I'd say is correctly at
+ 8 kbps and above (15 kbps for version < 1.1.1).
  Also, make sure you don't use the lowest complexity (see SPEEX_SET_COMPLEXITY
- or --comp option), as it causes important noise.
+ or --comp option), as it causes significant 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 :-)
+If I could do that I'd be very rich by now :-) Seriously, that would break
+ fundamental laws of information theory.
 \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 (2002/08/13) doing a Ph.D.
+Currently (2005/05/11), I'm doing my 
+\emph on 
+Ph.D.
+
+\emph default 
  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.
@@ -5258,8 +6226,8 @@ I am currently (2002/08/13) doing a Ph.D.
 \series bold 
 not
 \series default 
- be understood that they or the University of Sherbrooke endorse the Speex
project in any way.
+ be understood that they or the University of Sherbrooke have anything to
do with the Speex project.
  Furthermore, Speex does not make use of any code or proprietary technology
  developed in the Sherbrooke speech coding group.
  
@@ -5301,6 +6269,119 @@ d as a sum of unit pulses, thus making the codebook search much more efficient.
  Unfortunately, since it is patented, it cannot be used in Speex.
 \layout Section
 \pagebreak_top 
+Sample code
+\begin_inset LatexCommand \label{sec:Sample-code}
+
+\end_inset 
+
+
+\layout Standard
+
+This section shows sample code for encoding and decoding speech using the
+ Speex API.
+ The commands can be used to encode and decode a file by calling:
+\family typewriter 
+
+\newline 
+% sampleenc in_file.sw | sampledec out_file.sw
+\family default 
+
+\newline 
+where both files are raw (no header) files encoded at 16 bits per sample
+ (in the machine natural endianness).
+\layout Subsection
+
+sampleenc.c
+\layout Standard
+
+sampleenc takes a raw 16 bits/sample file, encodes it and outputs a Speex
+ stream to stdout.
+ Note that the packing used is NOT compatible with that of speexenc/speexdec.
+\layout Standard
+
+
+\begin_inset Include \verbatiminput{sampleenc.c}
+preview false
+
+\end_inset 
+
+
+\layout Subsection
+
+sampledec.c
+\layout Standard
+
+sampledec reads a Speex stream from stdin, decodes it and outputs it to
+ a raw 16 bits/sample file.
+ Note that the packing used is NOT compatible with that of speexenc/speexdec.
+\layout Standard
+
+
+\begin_inset Include \verbatiminput{sampledec.c}
+preview false
+
+\end_inset 
+
+
+\layout Section
+\pagebreak_top 
+IETF RTP Profile
+\begin_inset LatexCommand \label{sec:IETF-draft}
+
+\end_inset 
+
+
+\layout Standard
+
+
+\begin_inset Include \verbatiminput{draft-herlein-speex-rtp-profile-02.txt}
+preview false
+
+\end_inset 
+
+
+\layout Section
+\pagebreak_top 
+Speex License
+\begin_inset LatexCommand \label{sec:Speex-License}
+
+\end_inset 
+
+
+\layout Standard
+
+Redistribution and use in source and binary forms, with or without modification,
+ are permitted provided that the following conditions are met:
+\layout Itemize
+
+Redistributions of source code must retain the above copyright notice, this
+ list of conditions and the following disclaimer.
+\layout Itemize
+
+Redistributions in binary form must reproduce the above copyright notice,
+ this list of conditions and the following disclaimer in the documentation
+ and/or other materials provided with the distribution.
+\layout Itemize
+
+Neither the name of the Xiph.org Foundation nor the names of its contributors
+ may be used to endorse or promote products derived from this software without
+ specific prior written permission.
+\layout Standard
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS
+ IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ PURPOSE ARE DISCLAIMED.
+ IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+ INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+ BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+ USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+\layout Section
+\pagebreak_top 
 GNU Free Documentation License
 \layout Standard