Patch by David Rowe: normalize16() on Blackfin now writes data 16-bit at a time
[speexdsp.git] / doc / manual.lyx
index 050ad43..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)
+(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 
 
@@ -96,1371 +65,1678 @@ all trademarks are property of their respective owner
 Introduction to Speex
 \layout Standard
 
-Speex has been designed with the following goals in mind:
-\layout Itemize
+The Speex project (
+\family typewriter 
+http://www.speex.org/
+\family default 
+) has been started because there was a need for a speech codec that was
+ open-source and free from software patents.
+ These are essential conditions for being used by any open-source software.
+ There is already Vorbis that does general audio, but it is not really suitable
+ for speech.
+ Also, unlike many other speech codecs, Speex is not targeted at cell phones
+ (not many open-source cell phones anyway :-) ) but rather at voice over
+ IP (VoIP) and file-based compression.
+\layout Standard
 
-No use of patented algorithms (e.g.
- no ACELP)
-\layout Itemize
+As design goals, we wanted to have a codec that would 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).
+\layout Standard
 
-Optimized for speech, not music
-\layout Itemize
+Designing for VoIP instead of cell phone use means that Speex must be robust
+ to lost packets, but not to corrupted ones since packets either arrive
+ unaltered or don't arrive at all.
+ Also, the idea was to have a reasonable complexity and memory requirement
+ without compromising too much on the efficiency of the codec.
+\layout Standard
 
-Good for Voice over IP (VoIP)
-\layout Itemize
+All this led us to the choice of CELP
+\begin_inset LatexCommand \index{CELP}
 
-Provide very good quality speech (at least as an option)
-\layout Itemize
+\end_inset 
+
+ as the encoding technique to use for Speex.
+ One of the main reasons is that CELP has long proved that it could do the
+ job and scale well to both low bit-rates (think DoD CELP @ 4.8 kbps) and
+ high bit-rates (think G.728 @ 16 kbps).
+\layout Standard
 
-Allow a wide range of quality/bit-rates
+The main characteristics can be summarized as follows:
 \layout Itemize
 
-Integrate both narrowband and wideband coding
+Free software/open-source
+\begin_inset LatexCommand \index{open-source}
+
+\end_inset 
+
+, patent
+\begin_inset LatexCommand \index{patent}
+
+\end_inset 
+
+ and royalty-free
 \layout Itemize
 
-Reasonable complexity
-\layout Standard
+Integration of narrowband
+\begin_inset LatexCommand \index{narrowband}
+
+\end_inset 
+
+ and wideband
+\begin_inset LatexCommand \index{wideband}
+
+\end_inset 
 
-Throughout the design the following assumptions and constraints were considered
+ using an embedded bit-stream
 \layout Itemize
 
-Presence of packet losses
+Wide range of bit-rates available (from 2 kbps to 44 kbps)
 \layout Itemize
 
-Integrity of received frames (no bit-errors)
+Dynamic bit-rate switching and Variable Bit-Rate
+\begin_inset LatexCommand \index{variable bit-rate}
+
+\end_inset 
+
+ (VBR)
 \layout Itemize
 
-Memory footprint is neither critical nor unlimited
-\layout Standard
+Voice Activity Detection
+\begin_inset LatexCommand \index{voice activity detection}
 
-This led us to choose the CELP technique for Speex.
- Also many design decisions were based on the original goals and assumptions:
+\end_inset 
+
+ (VAD, integrated with VBR)
 \layout Itemize
 
-Minimizing the amount of information extracted from past frames (for robustness
- to packet loss)
+Variable complexity
+\begin_inset LatexCommand \index{complexity}
+
+\end_inset 
+
+
 \layout Itemize
 
-Dynamically-selectable codebooks (LSP, pitch and innovation)
+Ultra-wideband mode at 32 kHz (up to 48 kHz)
 \layout Itemize
 
-G.728-like fixed codebooks (without backward-adaptive grains because of patent
- issues)
-\layout Section
+Intensity stereo encoding option
+\layout Itemize
 
-Introduction to CELP Coding
+Fixed-point implementation (work in progress)
 \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}
+This document is divided in the following way.
+ Section 
+\begin_inset LatexCommand \ref{sec:Feature-description}
 
 \end_inset 
 
-.
- The CELP technique is based on three ideas:
-\layout Enumerate
-
-The use of a linear prediction (LP) model to model the vocal tract
-\layout Enumerate
-
-The use of (adaptive and fixed) codebook entries as input (excitation) of
- the LP model
-\layout Enumerate
+ 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}
 
-The search performed in closed-loop in a 
-\begin_inset Quotes eld
 \end_inset 
 
-perceptually weighted domain
-\begin_inset Quotes erd
-\end_inset 
+ provides information about the standard command-line tools, while 
+\begin_inset LatexCommand \ref{sec:Programming-with-Speex}
 
+\end_inset 
 
-\layout Subsection
+ contains information about programming using the Speex API.
+ Section 
+\begin_inset LatexCommand \ref{sec:Formats-and-standards}
 
-Linear Prediction
-\layout Standard
+\end_inset 
 
-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)\]
+ 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}
 
 \end_inset 
 
+ explains the general idea behind CELP, while sections 
+\begin_inset LatexCommand \ref{sec:Speex-narrowband-mode}
 
-\layout Standard
+\end_inset 
 
-In the 
-\emph on 
-z
-\emph default 
--domain, this can be expressed as
-\layout Standard
+ and 
+\begin_inset LatexCommand \ref{sec:Speex-wideband-mode}
 
+\end_inset 
 
-\begin_inset Formula \[
-x(z)=\frac{1}{A(z)}\: e(z)\]
+ 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
 
-where 
-\begin_inset Formula $A(z)$
-\end_inset 
+This section describes the main features provided by Speex.
+\layout Subsection
 
- is defined as
+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 \[
-A(z)=1-\sum _{i=1}^{N}a_{i}z^{-i}\]
+Sampling rate
+\begin_inset LatexCommand \index{sampling rate}
 
 \end_inset 
 
 
 \layout Standard
 
-We usually refer to 
-\begin_inset Formula $A(z)$
-\end_inset 
+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}
 
- as the analysis filter and 
-\begin_inset Formula $1/A(z)$
 \end_inset 
 
- as the synthesis filter.
-\layout Standard
+, wideband
+\begin_inset LatexCommand \index{wideband}
 
-The 
-\begin_inset Formula $A(z)$
 \end_inset 
 
- filter is computed using the Levinson-Durbin algorithm, which starts from
- the auto-correlation 
-\begin_inset Formula $R(m)$
-\end_inset 
+ and ultra-wideband
+\begin_inset LatexCommand \index{ultra-wideband}
 
- of the signal 
-\begin_inset Formula $x(n)$
 \end_inset 
 
 .
-\layout Standard
-
+\layout Subsection*
 
-\begin_inset Formula \[
-r(m)=\sum _{i=0}^{N-1}x(i)x(i-m)\]
+Quality
+\begin_inset LatexCommand \index{quality}
 
 \end_inset 
 
 
 \layout Standard
 
-For an order 
-\begin_inset Formula $N$
-\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]\]
+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 
 
+ (CBR) operation, the quality parameter is an integer, while for variable
+ bit-rate (VBR), the parameter is a float.
+\layout Subsection*
 
-\begin_inset Formula \[
-\mathbf{r}=\left[\begin{array}{c}
- r(1)\\
- r(2)\\
- \vdots \\
- R(N)\end{array}
-\right]\]
+Complexity
+\begin_inset LatexCommand \index{complexity}
 
 \end_inset 
 
-
+ (variable)
 \layout Standard
 
-The filter coefficients 
-\begin_inset Formula $a_{i}$
-\end_inset 
+With Speex, it is possible to vary the complexity allowed for the encoder.
+ This is done by controlling how the search is performed with an integer
+ ranging from 1 to 10 in a way that's similar to the -1 to -9 options to
+\emph on 
+gzip
+\emph default 
+ and 
+\emph on 
+bzip2
+\emph default 
+ compression utilities.
+ For normal use, the noise level at complexity 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}
 
- are found by solving the system 
-\begin_inset Formula $\mathbf{Ra}=\mathbf{r}$
 \end_inset 
 
-.
- 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 
+ tones.
+\layout Subsection*
 
- instead of 
-\begin_inset Formula $\mathcal{O}\left(N^{3}\right)$
-\end_inset 
+Variable Bit-Rate
+\begin_inset LatexCommand \index{variable bit-rate}
 
- by exploiting the fact that matrix 
-\begin_inset Formula $\mathbf{R}$
 \end_inset 
 
- is toeplitz hermitian.
- Also, it can be proved that all the roots of 
-\begin_inset Formula $A(z)$
-\end_inset 
+ (VBR)
+\layout Standard
 
- are withing the unit circle, which means that 
-\begin_inset Formula $1/A(z)$
+Variable bit-rate (VBR) allows a codec to change its bit-rate dynamically
+ to adapt to the 
+\begin_inset Quotes eld
 \end_inset 
 
- 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)$
+difficulty
+\begin_inset Quotes erd
 \end_inset 
 
- by a number slightly above one (such as 1.0001), which is equivalent to
- adding noise to the signal.
- Also, we can apply a window the the auto-correlation, which is equivalent
- to filtering in the frequency domain, reducing sharp resonances.
-\layout Subsection
+ 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*
 
-Pitch Prediction
-\layout Standard
+Average Bit-Rate
+\begin_inset LatexCommand \index{average bit-rate}
 
-During voiced segments, the speech signal is very periodic, so it is possible
- to take advantage of that by expressing the excitation signal 
-\begin_inset Formula $e(n)$
 \end_inset 
 
- as
+ (ABR)
 \layout Standard
 
+Average bit-rate solves one of the problems of VBR, as it dynamically adjusts
+ VBR quality in order to meet a specific target bit-rate.
+ Because the quality/bit-rate is adjusted in real-time (open-loop), the
+ global quality will be slightly lower than that obtained by encoding in
+ VBR with exactly the right quality setting to meet the target average bit-rate.
+\layout Subsection*
 
-\begin_inset Formula \[
-e(n)=\beta e(n-T)+c(n)\]
+Voice Activity Detection
+\begin_inset LatexCommand \index{voice activity detection}
 
 \end_inset 
 
-
+ (VAD)
 \layout Standard
 
-where 
-\begin_inset Formula $T$
+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 the pitch period, 
-\begin_inset Formula $\beta $
+comfort noise generation
+\begin_inset Quotes erd
 \end_inset 
 
- is the pitch gain and 
-\begin_inset Formula $c(n)$
+ (CNG).
+\layout Subsection*
+
+Discontinuous Transmission
+\begin_inset LatexCommand \index{discontinuous transmission}
+
 \end_inset 
 
- is taken from the 
-\emph on 
-innovation codebook
-\emph default 
-.
- In the 
-\emph on 
-z
-\emph default 
--domain, the excitation can be expressed as:
+ (DTX)
 \layout Standard
 
+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*
 
-\begin_inset Formula \[
-e(z)=\frac{1}{1-\beta z^{-T}}\: c(z)\]
+Perceptual enhancement
+\begin_inset LatexCommand \index{perceptual enhancement}
 
 \end_inset 
 
 
-\layout Subsection
-
-Innovation Codebook
-\layout Standard
-
-This is where most of the bits in a CELP codec are allocated.
- It represents the information that couldn't be obtained either from linear
- prediction or pitch prediction.
-\layout Subsection
-
-Analysis-by-Synthesis and Error Weighting
 \layout Standard
 
-Most (if not all) modern audio codecs attempt to 
+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 
-shape
+objectively
 \emph default 
- the noise so that it is the hardest to detect with the ear.
- That means that more noise can be tolerated in parts of the spectrum that
- are louder and 
+ (if you use SNR), but in the end it still 
 \emph on 
-vice versa
+sounds
 \emph default 
-.
- That's why the error is minimized for the perceptually weighted signal
-\begin_inset Formula \[
-X_{w}(z)=W(z)X(z)\]
+ better (subjective improvement).
+\layout Subsection*
 
-\end_inset 
+Algorithmic delay
+\begin_inset LatexCommand \index{algorithmic delay}
 
-where 
-\begin_inset Formula $W(z)$
 \end_inset 
 
- is the weighting filter, usually of the form
-\layout Standard
 
+\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}
+Every speech codec introduces a delay in the transmission.
+ For Speex, this delay is equal to the frame size, plus some amount of 
+\begin_inset Quotes eld
+\end_inset 
 
+look-ahead
+\begin_inset Quotes erd
 \end_inset 
 
+ required to process each frame.
+ In narrowband operation (8 kHz), the delay is 30 ms, while for wideband
+ (16 kHz), the delay is 34 ms.
+ These values don't account for the CPU time it takes to encode or decode
+ the frames.
+\layout Subsection
+
+Codec
+\layout Subsection
 
+Preprocessor
 \layout Standard
 
-with control parameters 
-\begin_inset Formula $\gamma _{1}>\gamma _{2}$
-\end_inset 
+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
 
-.
- 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)}\]
+denoising
+\layout Itemize
 
-\end_inset 
+automatic gain control (AGC)
+\layout Itemize
 
+voice activity detection (VAD)
+\layout Standard
 
-\layout Section
+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
 
-Speex narrowband mode
-\begin_inset LatexCommand \label{sec:Speex-narrowband-mode}
+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
 
-\end_inset 
+The voice activity detector (VAD) provided by the preprocessor is more advanced
+ than the one directly provided in the codec.
+\layout Subsection
 
+Adaptive Jitter Buffer
+\layout Subsection
 
+Acoustic Echo Canceller
+\layout Section
+\pagebreak_top 
+Compiling
 \layout Standard
 
-This section looks at how Speex works for narrowband (
-\begin_inset Formula $8\: \mathrm{kHz}$
-\end_inset 
+Compiling Speex under UNIX or any platform supported by autoconf (e.g.
+ Win32/cygwin) is as easy as typing:
+\layout LyX-Code
 
- sampling rate) operation.
- The frame size for this mode is 
-\begin_inset Formula $20\: \mathrm{ms}$
-\end_inset 
+% ./configure [options]
+\layout LyX-Code
 
-, corresponding to 160 samples.
- Each frame is also subdivided into 4 sub-frames of 40 samples each.
-\layout Subsection
+% make
+\layout LyX-Code
 
-LPC Analysis
+% make install
 \layout Standard
 
-An LPC analysis is first performed on a (Hamming) window that spans all
- the current frame and half a frame in advance.
- The LPC coefficients are then converted to Line Spectral Pair (LSP), a
- representation that is more robust to quantization.
- The LSP's are quantized using 30 bits for higher quality modes and 18 bits
- for lower quality.
- The quantized LSP's are considered to be associated to the 
-\begin_inset Formula $4^{th}$
-\end_inset 
+The options supported by the Speex configure script are:
+\layout Description
 
- 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
+--prefix=<path> Specifies where to install Speex
+\layout Description
 
-The perceptual weighting filter 
-\begin_inset Formula $W(z)$
-\end_inset 
+--enable-shared/--disable-shared Whether to compile shared libraries
+\layout Description
 
- used by Speex corresponds to the one described by eq.
-\begin_inset LatexCommand \ref{eq:weighting_filter}
+--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
 
- with 
-\begin_inset Formula $\gamma _{1}=0.9$
-\end_inset 
+--enable-valgrind Enable extra information when (and only when) running
+ with valgrind
+\layout Description
+
+--enable-sse Enable use of SSE instructions (x86/float only)
+\layout Description
+
+--enable-fixed-point
+\begin_inset LatexCommand \index{fixed-point}
 
- and 
-\begin_inset Formula $\gamma _{2}=0.6$
 \end_inset 
 
-.
- We can use the unquantized 
-\begin_inset Formula $A(z)$
+ 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
+
+--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 
 
- filter since the weighting filter is only used in the encoder.
-\layout Subsection
+ code (very slow)
+\layout Description
 
-Pitch Prediction (adaptive codebook)
-\layout Standard
+--enable-epic-48k Enable a special (and non-compatible) 4.8 kbps narrowband
+ mode
+\layout Description
 
-Speex uses a 3-tap prediction for pitch.
- That is, 
-\layout Standard
+--enable-ti-c55x Enable support for the TI C5x family
+\layout Description
 
+--enable-blackfin-asm Enable assembly specific to the Blackfin DSP architecture
+ (gcc only)
+\layout Description
 
-\begin_inset Formula \[
-e(n)=\beta _{0}e(n-T-1)+\beta _{1}e(n-T)+\beta _{2}e(n-T+1)+c(n)\]
+--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}
 
 \end_inset 
 
 
 \layout Standard
 
-where 
-\begin_inset Formula $T$
-\end_inset 
+The base Speex distribution includes a command-line encoder (
+\emph on 
+speexenc
+\emph default 
+) and decoder (
+\emph on 
+speexdec
+\emph default 
+).
+ This section describes how to use these tools.
+\layout Subsection
+
+
+\emph on 
+speexenc
+\begin_inset LatexCommand \index{speexenc}
 
- is the pitch period and the 
-\begin_inset Formula $\beta _{i}$
 \end_inset 
 
- are the prediction (filter) taps.
- The period and quantized gains are determined in closed loop.
-\layout Subsection
 
-Innovation Codebook
 \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 
+The 
+\emph on 
+speexenc
+\emph default 
+ utility is used to create Speex files from raw PCM or wave files.
+ It can be used by calling: 
+\layout LyX-Code
+
+speexenc [options] input_file output_file
+\layout Standard
+
+The value '-' for input_file or output_file corresponds respectively to
+ stdin and stdout.
+ The valid options are:
+\layout Description
+
+--narrowband\SpecialChar ~
+(-n) Tell Speex to treat the input as narrowband (8 kHz).
+ This is the default
+\layout Description
+
+--wideband\SpecialChar ~
+(-w) Tell Speex to treat the input as wideband (16 kHz)
+\layout Description
+
+--ultra-wideband\SpecialChar ~
+(-u) Tell Speex to treat the input as 
 \begin_inset Quotes eld
 \end_inset 
 
-global
+ultra-wideband
 \begin_inset Quotes erd
 \end_inset 
 
- and make use of the whole information available for a sub-frame.
-\layout Subsection
+ (32 kHz)
+\layout Description
 
-Bit allocation
-\layout Standard
+--quality\SpecialChar ~
+n Set the encoding quality (0-10), default is 8
+\layout Description
 
-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}
+--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
 
-.
- 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.
-\layout Standard
+--abr\SpecialChar ~
+n Enable ABR (Average Bit-Rate) at n kbps, disabled by default
+\layout Description
 
+--vad Enable VAD (Voice Activity Detection), disabled by default
+\layout Description
 
-\begin_inset Float table
-placement htbp
-wide true
-collapsed false
+--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
 
+--comp\SpecialChar ~
+n Set encoding speed/quality tradeoff.
+ The higher the value of n, the slower the encoding (default is 3)
+\layout Description
 
-\begin_inset  Tabular
-<lyxtabular version="3" rows="11" columns="9">
-<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" rightline="true" width="0pt">
-<row topline="true" bottomline="true">
-<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
 
-Parameter
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+--version\SpecialChar ~
+(-v) Print version information
+\layout Subsubsection*
 
-\layout Standard
+Speex comments
+\layout Description
 
-Update rate
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+--comment Add the given string as an extra comment.
+ This may be used multiple times.
+\layout Description
 
-\layout Standard
+--author Author of this track.
+\layout Description
 
-0
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+--title Title for this track.
+\layout Subsubsection*
 
-\layout Standard
+Raw input options
+\layout Description
 
-1
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+--rate\SpecialChar ~
+n Sampling rate for raw input
+\layout Description
 
-\layout Standard
+--stereo Consider raw input as stereo 
+\layout Description
 
-2
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+--le Raw input is little-endian 
+\layout Description
 
-\layout Standard
+--be Raw input is big-endian 
+\layout Description
 
-3
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+--8bit Raw input is 8-bit unsigned 
+\layout Description
 
-\layout Standard
+--16bit Raw input is 16-bit signed 
+\layout Subsection
 
-4
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+\emph on 
+speexdec
+\begin_inset LatexCommand \index{speexdec}
 
-5
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
 
-6
-\end_inset 
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
 \layout Standard
 
-Mode ID
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+The 
+\emph on 
+speexdec
+\emph default 
+ utility is used to decode Speex files and can be used by calling: 
+\layout LyX-Code
 
+speexdec [options] speex_file [output_file]
 \layout Standard
 
-frame
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+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
 
-\layout Standard
+--enh enable post-filter (default)
+\layout Description
 
-4
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+--no-enh disable post-filter
+\layout Description
 
-\layout Standard
+--force-nb Force decoding in narrowband 
+\layout Description
 
-4
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="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
 
-4
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+--mono Force decoding in mono 
+\layout Description
 
-\layout Standard
+--stereo Force decoding in stereo 
+\layout Description
 
-4
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+--rate\SpecialChar ~
+n Force decoding at n Hz sampling rate
+\layout Description
 
-\layout Standard
+--packet-loss\SpecialChar ~
+n Simulate n % random packet loss
+\layout Description
 
-4
-\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
+
+--version\SpecialChar ~
+(-v) Print version information
+\layout Section
+\pagebreak_top 
+Programming with Speex (the libspeex
+\begin_inset LatexCommand \index{libspeex}
 
-4
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+ API
+\begin_inset LatexCommand \index{API}
 
-4
 \end_inset 
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+)
+\begin_inset LatexCommand \label{sec:Programming-with-Speex}
 
-LSP
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
 
 \layout Standard
 
-frame
+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}
+
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+.
+\layout Subsection
+
+Encoding
+\begin_inset LatexCommand \label{sub:Encoding}
 
-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
+In order to encode speech using Speex, you first need to:
+\layout LyX-Code
 
+#include <speex/speex.h>
 \layout Standard
 
-18
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+You then need to declare a Speex bit-packing struct
+\layout LyX-Code
 
+SpeexBits bits;
 \layout Standard
 
-18
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+and a Speex encoder state
+\layout LyX-Code
 
+void *enc_state;
 \layout Standard
 
-18
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+The two are initialized by:
+\layout LyX-Code
 
+speex_bits_init(&bits);
+\layout LyX-Code
+
+enc_state = speex_encoder_init(&speex_nb_mode);
 \layout Standard
 
-30
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+For wideband coding, 
+\emph on 
+speex_nb_mode
+\emph default 
+ will be replaced by 
+\emph on 
+speex_wb_mode
+\emph default 
+.
+ In most cases, you will need to know the frame size used by the mode you
+ are using.
+ You can get that value in the 
+\emph on 
+frame_size
+\emph default 
+ variable with:
+\layout LyX-Code
 
+speex_encoder_ctl(enc_state,SPEEX_GET_FRAME_SIZE,&frame_size);
 \layout Standard
 
-30
-\end_inset 
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
+In practice, 
+\emph on 
+frame_size
+\emph default 
+ will correspond to 20 ms when using 8, 16, or 32 kHz sampling rate.
 \layout Standard
 
-OL pitch
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+Once the initialization is done, for every input frame:
+\layout LyX-Code
 
-\layout Standard
+speex_bits_reset(&bits);
+\layout LyX-Code
 
-frame
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+speex_encode(enc_state, input_frame, &bits);
+\layout LyX-Code
 
+nbBytes = speex_bits_write(&bits, byte_ptr, MAX_NB_BYTES);
 \layout Standard
 
-0
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+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
 
+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
 
-7
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+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
 
-7
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+That's about it for the encoder.
+\layout Subsection
 
-\layout Standard
+Decoding
+\begin_inset LatexCommand \label{sub:Decoding}
 
-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
+In order to decode speech using Speex, you first need to:
+\layout LyX-Code
 
+#include <speex/speex.h>
 \layout Standard
 
-0
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+You also need to declare a Speex bit-packing struct
+\layout LyX-Code
 
+SpeexBits bits;
 \layout Standard
 
-0
-\end_inset 
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+and a Speex decoder state
+\layout LyX-Code
 
+void *dec_state;
 \layout Standard
 
-OL pitch gain
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+The two are initialized by:
+\layout LyX-Code
+
+speex_bits_init(&bits);
+\layout LyX-Code
 
+dec_state = speex_decoder_init(&speex_nb_mode);
 \layout Standard
 
-frame
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+For wideband decoding, 
+\emph on 
+speex_nb_mode
+\emph default 
+ will be replaced by 
+\emph on 
+speex_wb_mode
+\emph default 
+.
+ If you need to obtain the size of the frames that will be used by the decoder,
+ you can get that value in the 
+\emph on 
+frame_size
+\emph default 
+ variable with:
+\layout LyX-Code
 
+speex_decoder_ctl(dec_state, SPEEX_GET_FRAME_SIZE, &frame_size); 
 \layout Standard
 
-0
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+There is also a parameter that can be set for the decoder: whether or not
+ to use a perceptual post-filter.
+ This can be set by: 
+\layout LyX-Code
 
+speex_decoder_ctl(dec_state, SPEEX_SET_ENH, &enh); 
 \layout Standard
 
-4
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
+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
 
-0
-\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
 
+speex_decode(dec_state, &bits, output_frame);
 \layout Standard
 
-0
-\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
 
-0
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
+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
 
-0
-\end_inset 
-</cell>
-</row>
-<row topline="true">
-<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
 
-Exc gain
-\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}
 
-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
+In order to use the Speex preprocessor
+\begin_inset LatexCommand \index{preprocessor}
 
-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
+, you first need to:
+\layout LyX-Code
 
+#include <speex/speex_preprocess.h>
 \layout Standard
 
-5
-\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
 
-5
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="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>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="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
 
-Fine pitch
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="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
 
-sub-frame
-\end_inset 
-</cell>
-<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
 
-0
-\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
 
-0
-\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
 
-0
-\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
 
-7
-\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}
 
-7
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
 
 \layout Standard
 
-7
+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" rightline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+ algorithm suitable for Acoustic Echo Cancellation
+\begin_inset LatexCommand \index{acoustic echo cancellation}
 
-7
 \end_inset 
-</cell>
-</row>
-<row topline="true">
-<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
 
-Pitch gain
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="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
 
-sub-frame
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+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 
 
-\layout Standard
+\begin_inset LatexCommand \index{tail length}
 
-0
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="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
 
-0
-\end_inset 
-</cell>
-<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
 
-5
-\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
 
-5
-\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
 
-5
-\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
 
-7
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
+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}
 
-7
 \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
+The echo cancellation state can be destroyed as:
+\layout LyX-Code
 
+speex_echo_state_destroy(echo_state);
 \layout Standard
 
-sub-frame
-\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
 
-0
-\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 
 
-3
+locked
+\begin_inset Quotes erd
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+ on the same clock source.
+\layout Itemize
 
-0
+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" usebox="none">
-\begin_inset Text
 
-\layout Standard
-
-3
+appear
+\begin_inset Quotes erd
 \end_inset 
-</cell>
-<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 
 
-3
+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
 
-3
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="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}
 
-3
 \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
 
-Innovation VQ
-\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
 
-sub-frame
-\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}
 
-0
 \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
 
-0
-\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
 
-16
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="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
 
-20
+SPEEX_SET_MODE*
+\begin_inset Formula $\dagger$
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
 
-35
+\layout Description
+
+SPEEX_GET_MODE*
+\begin_inset Formula $\dagger$
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
 
-48
+\layout Description
+
+SPEEX_SET_LOW_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
 
-64
+\layout Description
+
+SPEEX_GET_LOW_MODE*
+\begin_inset Formula $\dagger$
 \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
+\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
 
-frame
+\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
 
-4
-\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}
 
-50
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+ (VBR) status (integer)
+\layout Description
 
-118
-\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}
 
-167
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+ (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}
 
-227
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+ (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}
 
-299
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+ (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
 
-363
+
+\begin_inset Formula $\dagger$
 \end_inset 
-</cell>
-</row>
-</lyxtabular>
+
+ normally only used internally
+\layout Subsection
+
+Mode queries
+\begin_inset LatexCommand \label{sub:Mode-queries}
 
 \end_inset 
 
 
-\layout Caption
+\layout Standard
 
-Bit allocation for narrowband modes
-\begin_inset LatexCommand \label{cap:bits-narrowband}
+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 
 
 
 \layout Standard
 
-So far, no MOS (mean opinion score) subjective evaluation has been performed
- for Speex.
- In order to give an idea of the quality achivable with it, table 
+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 
 
- 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 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
+
+It is also possible to send in-band 
+\begin_inset Quotes eld
+\end_inset 
+
+messages
+\begin_inset Quotes erd
+\end_inset 
+
+ to the other side.
+ All these messages are encoded as 
+\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 true
+wide false
 collapsed false
 
 \layout Standard
 
 
 \begin_inset  Tabular
-<lyxtabular version="3" rows="8" columns="3">
+<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">
@@ -1471,7 +1747,7 @@ collapsed false
 
 \layout Standard
 
-Mode
+Code
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1479,7 +1755,7 @@ Mode
 
 \layout Standard
 
-Bitrate (bps)
+Size (bits)
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -1487,7 +1763,7 @@ Bitrate (bps)
 
 \layout Standard
 
-Quality
+Content
 \end_inset 
 </cell>
 </row>
@@ -1505,7 +1781,7 @@ Quality
 
 \layout Standard
 
-200
+1
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -1513,7 +1789,7 @@ Quality
 
 \layout Standard
 
-No sound (VBR only)
+Asks decoder to set perceptual enhancement off (0) or on(1)
 \end_inset 
 </cell>
 </row>
@@ -1531,7 +1807,7 @@ No sound (VBR only)
 
 \layout Standard
 
-2,500
+1
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -1539,7 +1815,15 @@ No sound (VBR only)
 
 \layout Standard
 
-Comfort noise only (VBR only)
+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>
@@ -1557,7 +1841,7 @@ Comfort noise only (VBR only)
 
 \layout Standard
 
-5,900
+4
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -1565,7 +1849,7 @@ Comfort noise only (VBR only)
 
 \layout Standard
 
-Very noticeable artifacts/noise, good intelligibility
+Asks encoder to switch to mode N
 \end_inset 
 </cell>
 </row>
@@ -1583,7 +1867,7 @@ Very noticeable artifacts/noise, good intelligibility
 
 \layout Standard
 
-8,350
+4
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -1591,7 +1875,7 @@ Very noticeable artifacts/noise, good intelligibility
 
 \layout Standard
 
-Artifacts/noise often noticeable
+Asks encoder to switch to mode N for low-band
 \end_inset 
 </cell>
 </row>
@@ -1609,7 +1893,7 @@ Artifacts/noise often noticeable
 
 \layout Standard
 
-11,350
+4
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -1617,7 +1901,7 @@ Artifacts/noise often noticeable
 
 \layout Standard
 
-Artifacts usually noticeable only with headphones
+Asks encoder to switch to mode N for high-band
 \end_inset 
 </cell>
 </row>
@@ -1635,7 +1919,7 @@ Artifacts usually noticeable only with headphones
 
 \layout Standard
 
-14,950
+4
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -1643,11 +1927,11 @@ Artifacts usually noticeable only with headphones
 
 \layout Standard
 
-Need good headphones to tell the difference
+Asks encoder to switch to quality N for VBR
 \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
 
@@ -1661,7 +1945,7 @@ Need good headphones to tell the difference
 
 \layout Standard
 
-18,150
+4
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -1669,174 +1953,121 @@ Need good headphones to tell the difference
 
 \layout Standard
 
-Hard to tell the difference even with good headphones
+Request acknowloedge (0=no, 1=all, 2=only for in-band data)
 \end_inset 
 </cell>
 </row>
-</lyxtabular>
+<row topline="true">
+<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 Standard
 
-\layout Caption
+4
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
-Quality versus bit-rate
-\begin_inset LatexCommand \label{cap:quality_vs_bps}
+\layout Standard
 
+Asks encoder to set CBR (0), VAD(1), DTX(3), VBR(5), VBR+DTX(7)
 \end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
+\layout Standard
 
+8
 \end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
+\layout Standard
 
-\layout Subsection
+8
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
-Perceptual post-filter
 \layout Standard
 
-This part of the codec only applies to the decoder and can even be changed
- without affecting inter-operability.
- For that reason, the implementation provided should only be considered
- as a reference implementation.
-\layout Section
+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
 
-Speex wideband mode (sub-band CELP)
 \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 (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}
-
+9
 \end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- in such a way that the resulting 
-\begin_inset Quotes eld
-\end_inset 
+\layout Standard
 
-embedded narrowband bit-stream
-\begin_inset Quotes erd
+8
 \end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
- 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
+\layout Standard
+
+Intensity stereo information
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-Linear Prediction
 \layout Standard
 
-The linear prediction part used for the high-band is very similar to what
- is done for narrowband.
- The only difference is that we use only 12 bits to encode the high-band
- LSP's.
-\layout Subsection
+10
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-Pitch Prediction
 \layout Standard
 
-That part is easy: there's no pitch prediction for the high-band.
- There are two reasons for that.
- First, there is usually little harmonic structure in this band (above 4
- kHz).
- Second, it would be very hard to implement since the QMF folds the 4-8
- kHz band into 4-0 kHz (reversing the frequency axis), which means that
- the location of the harmonics are no longer at multiples of the fundamental
- (pitch).
-\layout Subsection
-
-Excitation Quantization
-\layout Standard
-
-The high-band excitation is coded in the same way as for narrowband.
-\layout Subsection
-
-Bit allocation
-\layout Standard
-
-For the wideband mode, all the narrowband frame is packed before the high-band
- is encoded.
- The narrowband part of the bit-stream is as defined in table 
-\begin_inset LatexCommand \ref{cap:bits-narrowband}
-
-\end_inset 
-
-.
- The high-band follows, as described in table 
-\begin_inset LatexCommand \ref{cap:bits-wideband}
-
-\end_inset 
-
-.
- This also means that a wideband frame may be correctly decoded by a narrowband
- decoder with the only caveat that if more than one frame is packed in the
- same packet, the decoder will need to skip the high-band parts in order
- to sync with the bit-stream.
-\layout Standard
-
-
-\begin_inset Float table
-placement htbp
-wide true
-collapsed false
-
-\layout Standard
-
-
-\begin_inset  Tabular
-<lyxtabular version="3" rows="6" columns="6">
-<features>
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-Parameter
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-Update rate
+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
+Announce maximum bit-rate acceptable (N in bytes/second)
 \end_inset 
 </cell>
+</row>
+<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-1
+11
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1844,15 +2075,15 @@ Update rate
 
 \layout Standard
 
-2
+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
 
-3
+reserved
 \end_inset 
 </cell>
 </row>
@@ -1862,7 +2093,7 @@ Update rate
 
 \layout Standard
 
-Mode ID
+12
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1870,23 +2101,25 @@ Mode ID
 
 \layout Standard
 
-frame
+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
 
-3
+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
 
-3
+13
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1894,15 +2127,15 @@ frame
 
 \layout Standard
 
-3
+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
 
-3
+reserved
 \end_inset 
 </cell>
 </row>
@@ -1912,7 +2145,7 @@ frame
 
 \layout Standard
 
-LSP
+14
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1920,23 +2153,25 @@ LSP
 
 \layout Standard
 
-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
 
-12
+15
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1944,687 +2179,3605 @@ frame
 
 \layout Standard
 
-12
+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
 
-12
+reserved
 \end_inset 
 </cell>
 </row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
+</lyxtabular>
 
-Excitation gain
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
 
-sub-frame
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\layout Caption
 
-\layout Standard
+In-band signalling codes
+\begin_inset LatexCommand \label{cap:In-band-signalling-codes}
 
-0
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
 
-5
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
 
-4
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
 \layout Standard
 
-4
-\end_inset 
-</cell>
-</row>
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\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}
 
-Excitation VQ
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
 
-sub-frame
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+\begin_inset LatexCommand \label{sec:Formats-and-standards}
 
-0
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
 
 \layout Standard
 
-0
+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
 
-20
+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
 
-40
-\end_inset 
-</cell>
-</row>
-<row topline="true" bottomline="true">
-<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
 
-Total
+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
 
-frame
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="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}
 
-3
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
+ Payload Format 
 \layout Standard
 
-35
+The RTP payload draft is included in appendix 
+\begin_inset LatexCommand \ref{sec:IETF-draft}
+
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+ and the latest version is available at 
+\begin_inset LatexCommand \url{http://www.speex.org/drafts/latest}
 
-111
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
+.
+ 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
+
+MIME Type
 \layout Standard
 
-191
-\end_inset 
-</cell>
-</row>
-</lyxtabular>
+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
 
-\end_inset 
+Ogg
+\begin_inset LatexCommand \index{Ogg}
 
+\end_inset 
 
-\layout Caption
+ file format
+\layout Standard
 
-Bit allocation for high-band in wideband mode
-\begin_inset LatexCommand \label{cap:bits-wideband}
+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 
 
-
+.
+ 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 
 
 
-\layout Section
+\family typewriter 
+Speex
+\family default 
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
 
-Command-line encoder/decoder
-\layout Standard
+\begin_inset Quotes erd
+\end_inset 
 
-The base Speex distribution includes a command-line encoder (
-\emph on 
-speexenc
-\emph default 
-) and decoder (
+ (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 
-speexdec
+beginning of stream
 \emph default 
-).
-\layout Subsection
+ (
+\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 
-speexenc
+end of stream
+\emph default 
+ (
+\family typewriter 
+e_o_s
+\family default 
+) flag is set to 1.
 \layout Standard
 
-The encoder takes the following options:
-\layout Description
 
---narrowband\SpecialChar ~
-(-n) Tells Speex to treat the input as narrowband (8 kHz).
- This is the default
-\layout Description
+\begin_inset Float table
+placement htbp
+wide true
+collapsed false
 
---wideband\SpecialChar ~
-(-w) Tells Speex to treat the input as wideband (16 kHz)
-\layout Description
+\layout Standard
 
---quality\SpecialChar ~
-n Set the encoding quality (0-10)
-\layout Description
 
---vbr Enable VBR (Variable Bit-Rate), disabled by default
-\layout Description
+\begin_inset  Tabular
+<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" rightline="true" width="0pt">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
---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
+Field
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
---help\SpecialChar ~
-(-h) Print the help
-\layout Description
+\layout Standard
 
---version\SpecialChar ~
-(-v) Pring version information
-\layout Subsection
+Type
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
+\layout Standard
+
+Size
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-\emph on 
-speexdec
 \layout Standard
 
-The decoder takes the following options:
-\layout Description
+speex_string
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
---pf enable post-filter
-\layout Description
+\layout Standard
 
---nopf disable post-filter (default)
-\layout Description
+char[]
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
---help\SpecialChar ~
-(-h) Print the help
-\layout Description
+\layout Standard
 
---version\SpecialChar ~
-(-v) Pring version information
-\layout Section
+8
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-Programming with Speex (the libspeex API)
-\layout Subsection
+\layout Standard
+
+speex_version
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-Encoding
 \layout Standard
 
-In order to encode speech using Speex, you first need to:
-\layout LyX-Code
+char[]
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
-#include <speex.h>
 \layout Standard
 
-You then need to declare a Speex bit-packing struct
-\layout LyX-Code
+20
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<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
+speex_version_id
+\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
+int
+\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>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-enc_state = speex_encoder_init(&speex_nb_mode);
 \layout Standard
 
-For wideband coding, 
-\emph on 
-speex_nb_mode
-\emph default 
- will be replaced by 
-\emph on 
-speex_wb_mode
-\emph default 
-.
- In most cases, you will need to know the frame size used by the mode you
- are using.
- You can get that value in the 
-\emph on 
-frame_size
-\emph default 
- variable with:
-\layout LyX-Code
+header_size
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="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
+int
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="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
+4
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<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 
+rate
+\end_inset 
+</cell>
+<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
+
+mode
+\end_inset 
+</cell>
+<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
+
+mode_bitstream_version
+\end_inset 
+</cell>
+<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
+
+nb_channels
+\end_inset 
+</cell>
+<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
+
+bitrate
+\end_inset 
+</cell>
+<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
+
+frame_size
+\end_inset 
+</cell>
+<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
+
+vbr
+\end_inset 
+</cell>
+<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
+
+frames_per_packet
+\end_inset 
+</cell>
+<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
+
+extra_headers
+\end_inset 
+</cell>
+<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
+
+reserved1
+\end_inset 
+</cell>
+<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" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+reserved2
+\end_inset 
+</cell>
+<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>
+</lyxtabular>
+
+\end_inset 
+
+
+\layout Caption
+
+Ogg/Speex header packet
+\begin_inset LatexCommand \label{cap:ogg_speex_header}
+
+\end_inset 
+
+
+\end_inset 
+
+
+\layout Section
+\pagebreak_top 
+Introduction to CELP Coding
+\begin_inset LatexCommand \index{CELP}
+
+\end_inset 
+
+
+\begin_inset LatexCommand \label{sec:Introduction-to-CELP}
+
+\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}
+
+\end_inset 
+
+.
+ The CELP technique is based on three ideas:
+\layout Enumerate
+
+The use of a linear prediction (LP) model to model the vocal tract
+\layout Enumerate
+
+The use of (adaptive and fixed) codebook entries as input (excitation) of
+ the LP model
+\layout Enumerate
+
+The search performed in closed-loop in a 
+\begin_inset Quotes eld
+\end_inset 
+
+perceptually weighted domain
+\begin_inset Quotes erd
+\end_inset 
+
+
+\layout Standard
+
+This section describes the basic ideas behind CELP.
+ Note that it's still incomplete.
+\layout Subsection
+
+Linear Prediction (LPC)
+\begin_inset LatexCommand \index{linear prediction}
+
+\end_inset 
+
+
+\layout Standard
+
+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 
+
+ using a linear combination of its past samples:
+\layout Standard
+
+
+\begin_inset Formula \[
+y[n]=\sum_{i=1}^{N}a_{i}x[n-i]\]
+
+\end_inset 
+
+where 
+\begin_inset Formula $y[n]$
+\end_inset 
+
+ is the linear prediction of 
+\begin_inset Formula $x[n]$
+\end_inset 
+
+.
+ The prediction error is thus given by:
+\begin_inset Formula \[
+e[n]=x[n]-y[n]=x[n]-\sum_{i=1}^{N}a_{i}x[n-i]\]
+
+\end_inset 
+
+
+\layout Standard
+
+The goal of the LPC analysis is to find the best prediction coefficients
+\begin_inset Formula $a_{i}$
+\end_inset 
+
+ which minimize the quadratic error function:
+\begin_inset Formula \[
+E=\sum_{n=0}^{L-1}\left[e[n]\right]^{2}=\sum_{n=0}^{L-1}\left[x[n]-\sum_{i=1}^{N}a_{i}x[n-i]\right]^{2}\]
+
+\end_inset 
+
+That can be done by making all derivatives 
+\begin_inset Formula $\frac{\partial E}{\partial a_{i}}$
+\end_inset 
+
+ equal to zero:
+\begin_inset Formula \[
+\frac{\partial E}{\partial a_{i}}=\frac{\partial}{\partial a_{i}}\sum_{n=0}^{L-1}\left[x[n]-\sum_{i=1}^{N}a_{i}x[n-i]\right]^{2}=0\]
+
+\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}
+
+\end_inset 
+
+ 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
+
+
+\begin_inset Formula \[
+R(m)=\sum_{i=0}^{N-1}x[i]x[i-m]\]
+
+\end_inset 
+
+
+\layout Standard
+
+For an order 
+\begin_inset Formula $N$
+\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]\]
+
+\end_inset 
+
+
+\begin_inset Formula \[
+\mathbf{r}=\left[\begin{array}{c}
+R(1)\\
+R(2)\\
+\vdots\\
+R(N)\end{array}\right]\]
+
+\end_inset 
+
+
+\layout Standard
+
+The filter coefficients 
+\begin_inset Formula $a_{i}$
+\end_inset 
+
+ are found by solving the system 
+\begin_inset Formula $\mathbf{Ra}=\mathbf{r}$
+\end_inset 
+
+.
+ 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 
+
+ by exploiting the fact that matrix 
+\begin_inset Formula $\mathbf{R}$
+\end_inset 
+
+ is toeplitz hermitian.
+ Also, it can be proven that all the roots of 
+\begin_inset Formula $A(z)$
+\end_inset 
+
+ are within the unit circle, which means that 
+\begin_inset Formula $1/A(z)$
+\end_inset 
+
+ 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 to the auto-correlation, which is equivalent
+ to filtering in the frequency domain, reducing sharp resonances.
+\layout Standard
+
+The linear prediction model represents each speech sample as 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]\]
+
+\end_inset 
+
+
+\layout Standard
+
+In the 
+\emph on 
+z
+\emph default 
+-domain, this can be expressed as
+\layout Standard
+
+
+\begin_inset Formula \[
+x(z)=\frac{1}{A(z)}\: e(z)\]
+
+\end_inset 
+
+
+\layout Standard
+
+where 
+\begin_inset Formula $A(z)$
+\end_inset 
+
+ is defined as
+\layout Standard
+
+
+\begin_inset Formula \[
+A(z)=1-\sum_{i=1}^{N}a_{i}z^{-i}\]
+
+\end_inset 
+
+
+\layout Standard
+
+We usually refer to 
+\begin_inset Formula $A(z)$
+\end_inset 
+
+ as the analysis filter and 
+\begin_inset Formula $1/A(z)$
+\end_inset 
+
+ as the synthesis filter.
+ The whole process is called short-term prediction as it predicts the signal
+\begin_inset Formula $x[n]$
+\end_inset 
+
+ using a prediction using only the 
+\begin_inset Formula $N$
+\end_inset 
+
+ past samples, where 
+\begin_inset Formula $N$
+\end_inset 
+
+ is usually around 10.
+\layout Standard
+
+Because LPC coefficients have very little robustness to quantization, they
+ are converted to Line Spectral Pair
+\begin_inset LatexCommand \index{line spectral pair}
+
+\end_inset 
+
+ (LSP) coefficients which have a much better behaviour with quantization,
+ one of them being that it's easy to keep the filter stable.
+\layout Comment
+
+Describe LSP's
+\layout Subsection
+
+Pitch Prediction
+\begin_inset LatexCommand \index{pitch}
+
+\end_inset 
+
+
+\layout Standard
+
+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
+
+
+\begin_inset Formula \[
+e[n]\simeq p[n]=\beta e[n-T]\]
+
+\end_inset 
+
+
+\layout Standard
+
+where 
+\begin_inset Formula $T$
+\end_inset 
+
+ is the pitch period, 
+\begin_inset Formula $\beta$
+\end_inset 
+
+ is the pitch gain.
+ We call that long-term prediction since the excitation is predicted from
+\begin_inset Formula $e[n-T]$
+\end_inset 
+
+ with 
+\begin_inset Formula $T\gg N$
+\end_inset 
+
+.
+\layout Subsection
+
+Innovation Codebook
+\layout Standard
+
+The final excitation 
+\begin_inset Formula $e[n]$
+\end_inset 
+
+ will be the sum of the pitch prediction and an 
+\emph on 
+innovation
+\emph default 
+ signal 
+\begin_inset Formula $c[n]$
+\end_inset 
+
+ taken from a fixed codebook, hence the name 
+\emph on 
+Code
+\emph default 
+ Excited Linear Prediction.
+ The final excitation is given by:
+\layout Standard
+
+
+\begin_inset Formula \[
+e[n]=p[n]+c[n]=\beta e[n-T]+c[n]\]
+
+\end_inset 
+
+The quantization of 
+\begin_inset Formula $c[n]$
+\end_inset 
+
+ is where most of the bits in a CELP codec are allocated.
+ It represents the information that couldn't be obtained either from linear
+ prediction or pitch prediction.
+ In the 
+\emph on 
+z
+\emph default 
+-domain we can represent the final signal 
+\begin_inset Formula $X(z)$
+\end_inset 
+
+ as 
+\begin_inset Formula \[
+X(z)=\frac{C(z)}{A(z)\left(1-\beta z^{-T}\right)}\]
+
+\end_inset 
+
+
+\layout Subsection
+
+Analysis-by-Synthesis and Error Weighting
+\begin_inset LatexCommand \index{error weighting}
+
+\end_inset 
+
+
+\begin_inset LatexCommand \index{analysis-by-synthesis}
+
+\end_inset 
+
+
+\layout Standard
+
+Most (if not all) modern audio codecs attempt to 
+\begin_inset Quotes eld
+\end_inset 
+
+shape
+\begin_inset Quotes erd
+\end_inset 
+
+ the noise so that it appears mostly in the frequency regions where the
+ ear cannot detect it.
+ For example, the ear is more tolerant to noise in parts of the spectrum
+ that are louder and 
+\emph on 
+vice versa
+\emph default 
+.
+ That's why instead of minimizing the simple quadratic error
+\begin_inset Formula \[
+E=\sum_{n}\left(x[n]-\overline{x}[n]\right)^{2}\]
+
+\end_inset 
+
+where 
+\begin_inset Formula $\overline{x}[n]$
+\end_inset 
+
+ is the encoder signal, we minimize the error for the perceptually weighted
+ signal
+\begin_inset Formula \[
+X_{w}(z)=W(z)X(z)\]
+
+\end_inset 
+
+where 
+\begin_inset Formula $W(z)$
+\end_inset 
+
+ is the weighting filter, usually of the form
+\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}
+
+\end_inset 
+
+
+\layout Standard
+
+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)}\]
+
+\end_inset 
+
+
+\layout Standard
+
+If a filter 
+\begin_inset Formula $A(z)$
+\end_inset 
+
+ has (complex) poles at 
+\begin_inset Formula $p_{i}$
+\end_inset 
+
+ in the 
+\begin_inset Formula $z$
+\end_inset 
+
+-plane, the filter 
+\begin_inset Formula $A(z/\gamma)$
+\end_inset 
+
+ will have its poles at 
+\begin_inset Formula $p'_{i}=\gamma p_{i}$
+\end_inset 
+
+, making it a flatter version of 
+\begin_inset Formula $A(z)$
+\end_inset 
+
+.
+\layout Standard
+
+Analysis-by-synthesis refers to the fact that when trying to find the best
+ pitch parameters (
+\begin_inset Formula $T$
+\end_inset 
+
+, 
+\begin_inset Formula $\beta$
+\end_inset 
+
+) and innovation signal 
+\begin_inset Formula $c[n]$
+\end_inset 
+
+, we do not work by making the excitation 
+\begin_inset Formula $e[n]$
+\end_inset 
+
+ 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 
+
+ as close to the original as possible.
+\layout Section
+\pagebreak_top 
+Speex narrowband mode
+\begin_inset LatexCommand \label{sec:Speex-narrowband-mode}
+
+\end_inset 
+
+
+\begin_inset LatexCommand \index{narrowband}
+
+\end_inset 
+
+
+\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
+
+Dynamically-selectable codebooks (LSP, pitch and innovation)
+\layout Itemize
+
+sub-vector fixed (innovation) codebooks
+\layout Subsection
+
+LPC Analysis
+\begin_inset LatexCommand \index{linear prediction}
+
+\end_inset 
+
+
+\layout Standard
+
+An LPC analysis is first performed on a (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 
+
+ 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
+
+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 
+
+ and corresponds to the one described by eq.
+\begin_inset LatexCommand \ref{eq:weighting_filter}
+
+\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
+
+Pitch Prediction (adaptive codebook)
+\begin_inset LatexCommand \index{pitch}
+
+\end_inset 
+
+
+\layout Standard
+
+Speex uses a 3-tap prediction for pitch.
+ That is, the pitch prediction signal 
+\begin_inset Formula $p[n]$
+\end_inset 
+
+ is obtained by the past of the excitation by:
+\begin_inset Formula \[
+p[n]=\beta_{0}e[n-T-1]+\beta_{1}e[n-T]+\beta_{2}e[n-T+1]\]
+
+\end_inset 
+
+
+\layout Standard
+
+where 
+\begin_inset Formula $T$
+\end_inset 
+
+ is the pitch period and the 
+\begin_inset Formula $\beta_{i}$
+\end_inset 
+
+ are the prediction (filter) taps.
+ It is worth noting that when the pitch is smaller than the sub-frame size,
+ we repeat the excitation at a period 
+\begin_inset Formula $T$
+\end_inset 
+
+.
+ For example, when 
+\begin_inset Formula $n-T+1$
+\end_inset 
+
+, we use 
+\begin_inset Formula $n-2T+1$
+\end_inset 
+
+ instead.
+ The period and quantized gains are determined in closed loop (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 
+
+ range and the 
+\begin_inset Formula $\beta_{i}$
+\end_inset 
+
+ coefficients are vector-quantized using 7 bits (15 kbps narrowband and
+ above) at higher bit-rates and 5 bits at lower bit-rates (11 kbps narrowband
+ and below).
+\layout Subsection
+
+Innovation Codebook
+\layout Standard
+
+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
+
+Bit allocation
+\layout Standard
+
+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 
+
+OL
+\begin_inset Quotes erd
+\end_inset 
+
+ in the parameter description means that the parameter is an open loop estimatio
+n based on the whole frame.
+\layout Standard
+
+
+\begin_inset Float table
+placement h
+wide true
+collapsed false
+
+\layout Standard
+
+
+\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
+
+Parameter
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Update rate
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+1
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+2
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+3
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+4
+\end_inset 
+</cell>
+<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
+
+6
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+7
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+8
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Wideband bit
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+frame
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+1
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+1
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+1
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+1
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+1
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+1
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+1
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+1
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+1
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Mode ID
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+frame
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+4
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+4
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+4
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+4
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+4
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+4
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+4
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+4
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+4
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+LSP
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+frame
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+18
+\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
+
+\layout Standard
+
+18
+\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
+
+\layout Standard
+
+30
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+30
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+30
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+18
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+OL pitch
+\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
+
+7
+\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 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
+
+0
+\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 Standard
+
+7
+\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
+
+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
+
+\layout Standard
+
+Innovation VQ
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+sub-frame
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+16
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+20
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+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 Standard
+
+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>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+10
+\end_inset 
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Total
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+frame
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+5
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+43
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+119
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+160
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+220
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+300
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+364
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+492
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+79
+\end_inset 
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset 
+
+
+\layout Caption
+
+Bit allocation for narrowband modes
+\begin_inset LatexCommand \label{cap:bits-narrowband}
+
+\end_inset 
+
+
+\end_inset 
+
+
+\layout Standard
+
+So far, no MOS (Mean Opinion Score
+\begin_inset LatexCommand \index{mean opinion score}
+
+\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}
+
+\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 (within 0.5 mflops and using
+ the lowest complexity setting).
+ Decoding requires approximately 0.5 mflops
+\begin_inset LatexCommand \index{complexity}
+
+\end_inset 
+
+ in most modes (1 mflops with perceptual enhancement).
+\layout Standard
+
+
+\begin_inset Float table
+placement h
+wide true
+collapsed false
+
+\layout Standard
+
+
+\begin_inset  Tabular
+<lyxtabular version="3" rows="17" columns="4">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Mode
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+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">
+\begin_inset Text
+
+\layout Standard
+
+Quality/description
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+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">
+\begin_inset Text
+
+\layout Standard
+
+No transmission (DTX)
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+1
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+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">
+\begin_inset Text
+
+\layout Standard
+
+Vocoder (mostly for comfort noise)
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+2
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+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">
+\begin_inset Text
+
+\layout Standard
+
+Very noticeable artifacts/noise, good intelligibility
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+3
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+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">
+\begin_inset Text
+
+\layout Standard
+
+Artifacts/noise sometimes noticeable
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+4
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+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">
+\begin_inset Text
+
+\layout Standard
+
+Artifacts usually noticeable only with headphones
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+5
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+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">
+\begin_inset Text
+
+\layout Standard
+
+Need good headphones to tell the difference
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<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" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+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">
+\begin_inset Text
+
+\layout Standard
+
+Hard to tell the difference even with good headphones
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+7
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+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">
+\begin_inset Text
+
+\layout Standard
+
+Completely transparent for voice, good quality music
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+8
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+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">
+\begin_inset Text
+
+\layout Standard
+
+Very noticeable artifacts/noise, good intelligibility
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+9
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+N/A
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+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
+
+10
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+N/A
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+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
+
+11
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+N/A
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+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
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+N/A
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+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
+
+13
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+N/A
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+N/A
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+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
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+N/A
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+N/A
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Speex in-band signaling
+\end_inset 
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+15
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+N/A
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+N/A
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\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 
+
+where 
+\begin_inset Formula $a_{1}$
+\end_inset 
+
+ and 
+\begin_inset Formula $a_{2}$
+\end_inset 
+
+ depend on the mode in use and 
+\begin_inset Formula $a_{3}=\frac{1}{r}\left(1-\frac{1-ra_{1}}{1-ra_{2}}\right)$
+\end_inset 
+
+ with 
+\begin_inset Formula $r=.9$
+\end_inset 
+
+.
+ The second part of the enhancement consists of using a comb filter to enhance
+ the pitch in the excitation domain.
+\layout Section
+\pagebreak_top 
+Speex wideband mode (sub-band CELP)
+\begin_inset LatexCommand \index{wideband}
+
+\end_inset 
+
+
+\begin_inset LatexCommand \label{sec:Speex-wideband-mode}
+
+\end_inset 
+
+
+\layout Standard
+
+For wideband, the Speex approach uses a 
 \emph on 
-byte_ptr
+q
 \emph default 
- without causing an overflow and 
+uadrature 
 \emph on 
-nbBytes
+m
 \emph default 
- is the number of bytes actually written to 
+irror 
 \emph on 
-byte_ptr
+f
 \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
+ilter
+\begin_inset LatexCommand \index{quadrature mirror filter}
 
-After you're done with the encoding, free all resources with:
-\layout LyX-Code
+\end_inset 
 
-speex_bits_destroy(&bits);
-\layout LyX-Code
+ (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}
 
-speex_encoder_destroy(&enc_state);
-\layout Standard
+\end_inset 
 
-That's about it for the encoder.
+ in such a way that the resulting 
+\begin_inset Quotes eld
+\end_inset 
+
+embedded narrowband bit-stream
+\begin_inset Quotes erd
+\end_inset 
+
+ can also be decoded with the narrowband decoder.
+ Since the low band encoding has already been described, only the high band
+ encoding is described in this section.
 \layout Subsection
 
-Decoding
+Linear Prediction
 \layout Standard
 
-In order to encode speech using Speex, you first need to:
-\layout LyX-Code
+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
 
-#include <speex.h>
+Pitch Prediction
 \layout Standard
 
-You then need to declare a Speex bit-packing struct
-\layout LyX-Code
+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
 
-SpeexBits bits;
+Excitation Quantization
 \layout Standard
 
-and a Speex encoder state
-\layout LyX-Code
+The high-band excitation is coded in the same way as for narrowband.
+\layout Subsection
 
-void *dec_state;
+Bit allocation
 \layout Standard
 
-The two are initialized by:
-\layout LyX-Code
+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}
 
-speex_bits_init(&bits);
-\layout LyX-Code
+\end_inset 
 
-dec_state = speex_decoder_init(&speex_nb_mode);
-\layout Standard
+.
+ The high-band follows, as described in table 
+\begin_inset LatexCommand \ref{cap:bits-wideband}
+
+\end_inset 
 
-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
+ This also means that a wideband frame may be correctly decoded by a narrowband
+ decoder with the only caveat that if more than one frame is packed in the
+ same packet, the decoder will need to skip the high-band parts in order
+ to sync with the bit-stream.
+\layout Standard
+
+
+\begin_inset Float table
+placement h
+wide true
+collapsed false
 
-speex_decoder_ctl(dec_state, SPEEX_GET_FRAME_SIZE, &frame_size); 
 \layout Standard
 
-There is also a parameter that can be set for the decoder: whether or not
- to use a perceptual post-filter.
- This can be set by: 
-\layout LyX-Code
 
-speex_decoder_ctl(dec_state, SPEEX_SET_PF, &pf); 
+\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
 
-where pf is an int that with value 0 to have the post-filter disabled and
- 1 to have it enabled.
+Parameter
+\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
+Update rate
+\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
+
+0
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-speex_decode(st, &bits, output_frame, 0);
 \layout Standard
 
-where input_bytes is a 
-\emph on 
-(char *)
-\emph default 
- containing the bit-stream data received for a frame, 
-\emph on 
-nbBytes
-\emph default 
- is the size (in bytes) of that bit-stream, and 
-\emph on 
-output_frame
-\emph default 
- is a 
-\emph on 
-(float *)
-\emph default 
- and points to the area where the decoded speech frame will be written.
- The last argument indicates whether the frame we'd like to decode was lost.
- A value of 0 indicates the normal case where bits points to the bit of
- the current frame.
- A value of 1 indicates that we don't have the bits for the current frame,
- in which case the bits argument should be the same as the bits for the
- last correctly received frame.
- When a frame is lost, the Speex decoder will do its best to "guess" the
- correct signal.
-\layout Subsection
+1
+\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
+2
+\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
+
+3
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-void speex_decoder_ctl(void *encoder, int request, void *ptr);
 \layout Standard
 
-The different values of request allowed are (note that some only apply to
- the encoder or the decoder):
-\layout Description
+4
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-SPEEX_SET_PF** Set post-filter to on (1) or off (0) (integer)
-\layout Description
+\layout Standard
 
-SPEEX_GET_PF** Get post-filter status (integer)
-\layout Description
+Wideband bit
+\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
+frame
+\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 $
+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 Description
+\layout Standard
 
-SPEEX_GET_MODE*
-\begin_inset Formula $\dagger $
+1
 \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 $
+1
 \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 $
+1
 \end_inset 
+</cell>
+</row>
+<row topline="true">
+<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 $
+Mode ID
 \end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
+\layout Standard
 
-\layout Description
-
-SPEEX_GET_HIGH_MODE*
-\begin_inset Formula $\dagger $
+frame
 \end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
+\layout Standard
 
-\layout Description
+3
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="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
+3
+\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 (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
+3
+\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
-\layout Description
+\layout Standard
 
-SPEEX_GET_COMPLEXITY* Get the CPU resources allowed for the encoder
-\layout Description
+3
+\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
+3
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
+\layout Standard
 
-\begin_inset Formula $\dagger $
+LSP
 \end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- normally only used internally
-\layout Section
-
-Formats and standards
 \layout Standard
 
-Speex can encode speech in both narrowband and wideband and provides different
- bit-rates.
- All modes of operation MUST be supported at the decoder and at least one
- MUST be supported by the encoder.
- The main reason is that not all platforms may be able to handle the complexity
- of encoding for all modes.
-\layout Subsection
+frame
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-RTP Payload Format
 \layout Standard
 
-Since Speex encoded frames already contain mode information, they can be
- sent without any other information in an RTP packet.
- If more than one frame is transmitted, no byte padding is performed at
- the end of frames, except the last one.
-\layout Subsection
+0
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-Ogg file format
 \layout Standard
 
-Speex bit-streams can be stored in Ogg files.
- In this case, the first packet of the Ogg file contains the Speex header
- (see speex_header.h for now) and the second packet contains comments.
- The next frames contain one or more (number found in header) Speex frames.
- The header format is described in table 
-\begin_inset LatexCommand \ref{cap:ogg_speex_header}
-
+12
 \end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-.
- All integer fields are stored as little-endian.
 \layout Standard
 
-
-\begin_inset Float table
-placement htbp
-wide true
-collapsed false
+12
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
 \layout Standard
 
-
-\begin_inset  Tabular
-<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" rightline="true" width="0pt">
-<row topline="true" bottomline="true">
+12
+\end_inset 
+</cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-Field
+12
 \end_inset 
 </cell>
+</row>
+<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-Type
+Excitation gain
 \end_inset 
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-Size
+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
 
-speex_string
+0
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -2632,25 +5785,23 @@ speex_string
 
 \layout Standard
 
-char[]
+5
 \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
+4
 \end_inset 
 </cell>
-</row>
-<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-speex_version
+4
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -2658,25 +5809,25 @@ speex_version
 
 \layout Standard
 
-char[]
+4
 \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
 
-20
+Excitation VQ
 \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
+sub-frame
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -2684,25 +5835,23 @@ speex_header_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
+0
 \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
+20
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -2710,25 +5859,25 @@ header_size
 
 \layout Standard
 
-int
+40
 \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
+80
 \end_inset 
 </cell>
 </row>
-<row topline="true">
+<row topline="true" bottomline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
 \layout Standard
 
-rate
+Total
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -2736,10 +5885,10 @@ rate
 
 \layout Standard
 
-int
+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
@@ -2747,14 +5896,12 @@ 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
 
-mode
+36
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -2762,304 +5909,479 @@ mode
 
 \layout Standard
 
-int
+112
 \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
+192
 \end_inset 
 </cell>
-</row>
-<row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\layout Standard
+\layout Standard
+
+352
+\end_inset 
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset 
+
+
+\layout Caption
+
+Bit allocation for high-band in wideband mode
+\begin_inset LatexCommand \label{cap:bits-wideband}
+
+\end_inset 
+
+
+\end_inset 
+
+
+\layout Standard
+
+
+\begin_inset ERT
+status Open
+
+\layout Standard
+
+\backslash 
+clearpage
+\end_inset 
+
+
+\layout Standard
+
+
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash 
+clearpage
+\end_inset 
+
+
+\layout Section
+\start_of_appendix 
+FAQ
+\layout Subsection*
+
+Vorbis is open-source
+\begin_inset LatexCommand \index{open-source}
 
-mode_bitstream_version
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+ and patent-free
+\begin_inset LatexCommand \index{patent}
 
-int
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
+; why do we need Speex?
 \layout Standard
 
-4
-\end_inset 
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+Vorbis is a great project but its goals are not the same as Speex.
+ Vorbis is mostly aimed at compressing music and audio in general, while
+ Speex targets speech only.
+ For that reason Speex can achieve much better results than Vorbis on speech,
+ typically 2-4 times higher compression at equal quality.
+\layout Subsection*
 
+Isn't there an open-source implementation of the GSM-FR codec? Why is Speex
+ necessary?
 \layout Standard
 
-nb_channels
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+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
 
-int
+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 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
+).
+ This license is the most permissive of the open-source licenses.
+\layout Subsection*
+
+Am I allowed to use Speex in commercial software?
 \layout Standard
 
-4
+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 
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+.
+\layout Subsection*
+
+Ogg
+\begin_inset LatexCommand \index{Ogg}
 
-bitrate
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+, Speex, Vorbis
+\begin_inset LatexCommand \index{Vorbis}
 
-int
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
+, what's the difference?
 \layout Standard
 
-4
+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
+y they would be 
+\begin_inset Quotes eld
 \end_inset 
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
+Ogg Speex
+\begin_inset Quotes erd
+\end_inset 
+
+ files (I prefer to call them just Speex files).
+ One difference with Vorbis however, is that Speex is less tied with Ogg.
+ Actually, if you just do Voice over IP (VoIP), you don't need Ogg at all.
+\layout Subsection*
+
+What's the extension for Speex?
 \layout Standard
 
-frame_size
+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
+\begin_inset LatexCommand \index{music}
+
 \end_inset 
-</cell>
-<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
+Just like Vorbis is not really adapted to speech, Speex is really not adapted
+ for music.
+ In most cases, you'll be better of with Vorbis when it comes to music.
+\layout Subsection*
 
+I converted some MP3s to Speex and the quality is bad.
+ What's wrong?
 \layout Standard
 
-4
-\end_inset 
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+This is called transcoding and it will always result in much poorer quality
+ than the original MP3.
+ Unless you have a really good (size) reason to do so, never transcode speech.
+ This is even valid for self transcoding (tandeming), i.e.
+ If you decode a Speex file and re-encode it again at the same bit-rate,
+ you will lose quality.
+\layout Subsection*
 
+Does Speex run on Windows?
 \layout Standard
 
-vbr
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+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?
 \layout Standard
 
-int
-\end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+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 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.
+\layout Subsection*
 
+Why is Speex so slow on my iPaq (or insert any platform without an FPU)?
 \layout Standard
 
-4
-\end_inset 
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+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
+n.
+ How do I fix that?
 \layout Standard
 
-frames_per_packet
+One of the causes could be scaling of the input speech.
+ Speex expects signals to have a 
+\begin_inset Formula $\pm2^{15}$
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+ (signed short) dynamic range.
+ If the dynamic range of your signals is too small (e.g.
+\begin_inset Formula $\pm1.0$
+\end_inset 
 
-int
+), you will suffer important quantization noise.
+ A good target is to have a dynamic range around 
+\begin_inset Formula $\pm8000$
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
+ which is large enough, but small enough to make sure there's no clipping
+ when converting back to signed short.
+\layout Subsection*
+
+I get very distorted speech when using libspeex in my application.
+ What's wrong?
 \layout Standard
 
-4
+There are many possible causes for that.
+ One of them is errors in the way the bits are manipulated.
+ Another possible cause is the use of the same encoder or decoder state
+ for more than one audio stream (channel), which produces strange effects
+ with the filter memories.
+ If the input speech has an amplitude close to 
+\begin_inset Formula $\pm2^{15}$
 \end_inset 
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+, 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}
 
-reserved1
 \end_inset 
-</cell>
-<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
+I guess it all depends on the bit-rate used.
+ 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 significant noise.
+\layout Subsection*
 
+Can Speex pass V.9x modem signals correctly?
 \layout Standard
 
-4
-\end_inset 
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+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
 
-reserved2
+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.
+ It should 
+\series bold 
+not
+\series default 
+ 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.
+\layout Subsection*
+
+CELP, ACELP
+\begin_inset LatexCommand \index{ACELP}
+
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
+, what's the difference?
 \layout Standard
 
-int
+CELP stands for 
+\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
+Code Excited Linear Prediction
+\begin_inset Quotes erd
+\end_inset 
 
-4
+, while ACELP stands for 
+\begin_inset Quotes eld
 \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
+\emph on 
+Algebraic
+\emph default 
+ Code Excited Linear Prediction
+\begin_inset Quotes erd
 \end_inset 
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\layout Standard
+.
+ That means ACELP is a CELP technique that uses an algebraic codebook represente
+d as a sum of unit pulses, thus making the codebook search much more efficient.
+ This technique was invented at the University of Sherbrooke and is now
+ one of the most widely used form of CELP.
+ Unfortunately, since it is patented, it cannot be used in Speex.
+\layout Section
+\pagebreak_top 
+Sample code
+\begin_inset LatexCommand \label{sec:Sample-code}
 
-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>
-</lyxtabular>
+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 
 
-\end_inset 
+\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
 
-\layout Caption
+sampleenc.c
+\layout Standard
 
-Ogg/Speex header packet
-\begin_inset LatexCommand \label{cap:ogg_speex_header}
+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
 
-\end_inset 
 
+\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
 
-The speex_string field must contain the 
-\begin_inset Quotes eld
+
+\begin_inset Include \verbatiminput{sampledec.c}
+preview false
+
 \end_inset 
 
 
-\family typewriter 
-Speex
-\family default 
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
+\layout Section
+\pagebreak_top 
+IETF RTP Profile
+\begin_inset LatexCommand \label{sec:IETF-draft}
 
-\begin_inset Quotes eld
 \end_inset 
 
- (with 3 spaces), which identifies the bit-stream.
- The next field, speex_version contains the version of Speex that encoded
- the file.
+
 \layout Standard
 
 
-\begin_inset ERT
-status Collapsed
+\begin_inset Include \verbatiminput{draft-herlein-speex-rtp-profile-02.txt}
+preview false
 
-\layout Standard
+\end_inset 
+
+
+\layout Section
+\pagebreak_top 
+Speex License
+\begin_inset LatexCommand \label{sec:Speex-License}
 
-\backslash 
-clearpage
 \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
-\start_of_appendix 
+\pagebreak_top 
 GNU Free Documentation License
 \layout Standard
 
@@ -3485,4 +6807,12 @@ n.
  If the Document does not specify a version number of this License, you
  may choose any version ever published (not as a draft) by the Free Software
  Foundation.
+\layout Standard
+
+
+\begin_inset LatexCommand \printindex{}
+
+\end_inset 
+
+
 \the_end