Updated draft
[speexdsp.git] / doc / manual.lyx
index da2550e..43710b8 100644 (file)
@@ -1,17 +1,27 @@
-#LyX 1.4.4 created this file. For more info see http://www.lyx.org/
-\lyxformat 245
+#LyX 1.6.0rc2 created this file. For more info see http://www.lyx.org/
+\lyxformat 340
 \begin_document
 \begin_header
 \textclass scrbook
 \language english
 \inputencoding auto
-\fontscheme pslatex
+\font_roman times
+\font_sans helvet
+\font_typewriter courier
+\font_default_family default
+\font_sc false
+\font_osf false
+\font_sf_scale 100
+\font_tt_scale 100
+
 \graphics default
 \paperfontsize 10
-\spacing onehalf
+\spacing single
+\use_hyperref false
 \papersize letterpaper
 \use_geometry true
 \use_amsmath 2
+\use_esint 0
 \cite_engine basic
 \use_bibtopic false
 \paperorientation portrait
 \papercolumns 1
 \papersides 1
 \paperpagestyle headings
+\listings_params "basicstyle={\ttfamily},breaklines=true,language=C,xleftmargin=0mm"
 \tracking_changes false
-\output_changes true
+\output_changes false
+\author "" 
+\author "" 
 \end_header
 
 \begin_body
 
 \begin_layout Title
-The Speex Codec Manual
-\newline
-(version 1.2-beta2)
+The Speex Manual
+\begin_inset Newline newline
+\end_inset
+
+Version 1.2
 \end_layout
 
 \begin_layout Author
@@ -44,9 +59,27 @@ Jean-Marc Valin
 \end_layout
 
 \begin_layout Standard
+\begin_inset Newpage newpage
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Copyright 
+\begin_inset ERT
+status collapsed
+
+\begin_layout Plain Layout
+
+
+\backslash
+copyright
+\end_layout
 
-\newpage
-Copyright (c) 2002-2006 Jean-Marc Valin/Xiph.org Foundation
+\end_inset
+
+ 2002-2008 Jean-Marc Valin/Xiph.org Foundation
 \end_layout
 
 \begin_layout Standard
@@ -60,15 +93,19 @@ on License".
 \end_layout
 
 \begin_layout Standard
+\begin_inset Newpage newpage
+\end_inset
 
-\newpage
 
-\begin_inset LatexCommand \tableofcontents{}
+\begin_inset CommandInset toc
+LatexCommand tableofcontents
 
 \end_inset
 
 
-\newpage
+\begin_inset Newpage newpage
+\end_inset
+
 
 \end_layout
 
@@ -78,7 +115,9 @@ on License".
 \end_inset
 
 
-\newpage
+\begin_inset Newpage newpage
+\end_inset
+
 
 \end_layout
 
@@ -87,106 +126,226 @@ Introduction to Speex
 \end_layout
 
 \begin_layout Standard
-The Speex project (
+The Speex codec (
 \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
- but rather at voice over IP (VoIP) and file-based compression.
+) exists because there is a need for a speech codec that is open-source
+ and free from software patent royalties.
+ These are essential conditions for being usable in any open-source software.
+ In essence, Speex is to speech what Vorbis is to audio/music.
+ Unlike many other speech codecs, Speex is not designed for mobile phones
+ but rather for packet networks and voice over IP (VoIP) applications.
+ File-based compression is of course also supported.
+\end_layout
+
+\begin_layout Standard
+The Speex codec is designed to be very flexible and support a wide range
+ of speech quality and bit-rate.
+ Support for very good quality speech also means that Speex can encode wideband
+ speech (16 kHz sampling rate) in addition to narrowband speech (telephone
+ quality, 8 kHz sampling rate).
+\end_layout
+
+\begin_layout Standard
+Designing for VoIP instead of mobile phones means that Speex is robust to
+ lost packets, but not to corrupted ones.
+ This is based on the assumption that in VoIP, packets either arrive unaltered
+ or don't arrive at all.
+ Because Speex is targeted at a wide range of devices, it has modest (adjustable
+) complexity and a small memory footprint.
+\end_layout
+
+\begin_layout Standard
+All the design goals led to the choice of CELP
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+CELP
+\end_layout
+
+\end_inset
+
+ as the encoding technique.
+ One of the main reasons is that CELP has long proved that it could work
+ reliably and scale well to both low bit-rates (e.g.
+ DoD CELP @ 4.8 kbps) and high bit-rates (e.g.
+ G.728 @ 16 kbps).
  
 \end_layout
 
+\begin_layout Section
+Getting help
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Getting-help"
+
+\end_inset
+
+
+\end_layout
+
 \begin_layout Standard
-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).
+As for many open source projects, there are many ways to get help with Speex.
+ These include:
+\end_layout
+
+\begin_layout Itemize
+This manual
+\end_layout
+
+\begin_layout Itemize
+Other documentation on the Speex website (http://www.speex.org/)
+\end_layout
+
+\begin_layout Itemize
+Mailing list: Discuss any Speex-related topic on speex-dev@xiph.org (not
+ just for developers)
+\end_layout
+
+\begin_layout Itemize
+IRC: The main channel is #speex on irc.freenode.net.
+ Note that due to time differences, it may take a while to get someone,
+ so please be patient.
+\end_layout
+
+\begin_layout Itemize
+Email the author privately at jean-marc.valin@usherbrooke.ca 
+\series bold
+only
+\series default
+ for private/delicate topics you do not wish to discuss publicly.
 \end_layout
 
 \begin_layout Standard
-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.
+Before asking for help (mailing list or IRC), 
+\series bold
+it is important to first read this manual
+\series default
+ (OK, so if you made it here it's already a good sign).
+ It is generally considered rude to ask on a mailing list about topics that
+ are clearly detailed in the documentation.
+ On the other hand, it's perfectly OK (and encouraged) to ask for clarifications
+ about something covered in the manual.
+ This manual does not (yet) cover everything about Speex, so everyone is
+ encouraged to ask questions, send comments, feature requests, or just let
+ us know how Speex is being used.
 \end_layout
 
 \begin_layout Standard
-All this led us to the choice of CELP
-\begin_inset LatexCommand \index{CELP}
+Here are some additional guidelines related to the mailing list.
+ Before reporting bugs in Speex to the list, it is strongly recommended
+ (if possible) to first test whether these bugs can be reproduced using
+ the speexenc and speexdec (see Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Command-line-encoder/decoder"
 
 \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).
+) command-line utilities.
+ Bugs reported based on 3rd party code are both harder to find and far too
+ often caused by errors that have nothing to do with Speex.
  
 \end_layout
 
+\begin_layout Section
+About this document
+\end_layout
+
 \begin_layout Standard
 This document is divided in the following way.
  Section 
-\begin_inset LatexCommand \ref{sec:Feature-description}
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Feature-description"
+
+\end_inset
+
+ describes the different Speex features and defines many basic terms that
+ are used throughout this manual.
+ Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Command-line-encoder/decoder"
 
 \end_inset
 
- describes the different Speex features and defines some terms that will
- be used in later sections.
+ documents the standard command-line tools provided in the Speex distribution.
  Section 
-\begin_inset LatexCommand \ref{sec:Command-line-encoder/decoder}
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Programming-with-Speex"
 
 \end_inset
 
- provides information about the standard command-line tools, while 
-\begin_inset LatexCommand \ref{sec:Programming-with-Speex}
+ includes detailed instructions about programming using the libspeex
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+libspeex
+\end_layout
 
 \end_inset
 
contains information about programming using the Speex API.
+ API.
  Section 
-\begin_inset LatexCommand \ref{sec:Formats-and-standards}
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Formats-and-standards"
 
 \end_inset
 
  has some information related to Speex and standards.
- The three last sections describe the internals of the codec and require
- some signal processing knowledge.
+\end_layout
+
+\begin_layout Standard
+The three last sections describe the algorithms used in Speex.
+ These sections require signal processing knowledge, but are not required
+ for merely using Speex.
+ They are intended for people who want to understand how Speex really works
+ and/or want to do research based on Speex.
  Section 
-\begin_inset LatexCommand \ref{sec:Introduction-to-CELP}
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Introduction-to-CELP"
 
 \end_inset
 
  explains the general idea behind CELP, while sections 
-\begin_inset LatexCommand \ref{sec:Speex-narrowband-mode}
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Speex-narrowband-mode"
 
 \end_inset
 
  and 
-\begin_inset LatexCommand \ref{sec:Speex-wideband-mode}
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Speex-wideband-mode"
 
 \end_inset
 
  are specific to Speex.
- Note that if you are only interested in using Speex, those three last sections
- are not required.
 \end_layout
 
 \begin_layout Standard
+\begin_inset Newpage newpage
+\end_inset
 
-\newpage
 
 \end_layout
 
 \begin_layout Chapter
 Codec description
-\begin_inset LatexCommand \label{sec:Feature-description}
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Feature-description"
 
 \end_inset
 
@@ -194,7 +353,7 @@ Codec description
 \end_layout
 
 \begin_layout Standard
-This section describes the main features provided by Speex.
+This section describes Speex and its features into more details.
 \end_layout
 
 \begin_layout Section
@@ -204,12 +363,18 @@ Concepts
 \begin_layout Standard
 Before introducing all the Speex features, here are some concepts in speech
  coding that help better understand the rest of the manual.
- Emphasis is placed on Speex.
+ Although some are general concepts in speech/audio processing, others are
+ specific to Speex.
 \end_layout
 
 \begin_layout Subsection*
 Sampling rate
-\begin_inset LatexCommand \index{sampling rate}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+sampling rate
+\end_layout
 
 \end_inset
 
@@ -217,54 +382,136 @@ Sampling rate
 \end_layout
 
 \begin_layout Standard
-Speex is mainly designed for three different sampling rates: 8 kHz, 16 kHz,
- and 32 kHz.
- These are respectively refered to as narrowband
-\begin_inset LatexCommand \index{narrowband}
+The sampling rate expressed in Hertz (Hz) is the number of samples taken
+ from a signal per second.
+ For a sampling rate of 
+\begin_inset Formula $F_{s}$
+\end_inset
+
+ kHz, the highest frequency that can be represented is equal to 
+\begin_inset Formula $F_{s}/2$
+\end_inset
+
+ kHz (
+\begin_inset Formula $F_{s}/2$
+\end_inset
+
+ is known as the Nyquist frequency).
+ This is a fundamental property in signal processing and is described by
+ the sampling theorem.
+ Speex is mainly designed for three different sampling rates: 8 kHz, 16
+ kHz, and 32 kHz.
+ These are respectively referred to as narrowband
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+narrowband
+\end_layout
 
 \end_inset
 
 , wideband
-\begin_inset LatexCommand \index{wideband}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+wideband
+\end_layout
 
 \end_inset
 
  and ultra-wideband
-\begin_inset LatexCommand \index{ultra-wideband}
+\begin_inset Index
+status collapsed
 
-\end_inset
+\begin_layout Plain Layout
+ultra-wideband
+\end_layout
 
-.
- For a sampling rate of 
-\begin_inset Formula $F_{s}$
 \end_inset
 
- kHz, the highest frequency that can be represented is equal to 
-\begin_inset Formula $F_{s}/2$
-\end_inset
+.
+\end_layout
 
- kHz.
- This is a consequence of Nyquist's sampling theorem (and 
-\begin_inset Formula $F_{s}/2$
-\end_inset
+\begin_layout Subsection*
+Bit-rate
+\end_layout
 
- is known as the Nyquist frequency).
+\begin_layout Standard
+When encoding a speech signal, the bit-rate is defined as the number of
+ bits per unit of time required to encode the speech.
+ It is measured in 
+\emph on
+bits per second
+\emph default
+ (bps), or generally 
+\emph on
+kilobits per second
+\emph default
+.
+ It is important to make the distinction between 
+\emph on
+kilo
+\series bold
+bits
+\series default
+\emph default
+\emph on
+per second
+\emph default
+ (k
+\series bold
+b
+\series default
+ps) and 
+\emph on
+kilo
+\series bold
+bytes
+\series default
+\emph default
+\emph on
+per second
+\emph default
+ (k
+\series bold
+B
+\series default
+ps).
 \end_layout
 
 \begin_layout Subsection*
 Quality
-\begin_inset LatexCommand \index{quality}
+\begin_inset Index
+status collapsed
 
-\end_inset
+\begin_layout Plain Layout
+quality
+\end_layout
 
+\end_inset
 
+ (variable)
 \end_layout
 
 \begin_layout Standard
-Speex encoding is controlled most of the time by a quality parameter that
- ranges from 0 to 10.
+Speex is a lossy codec, which means that it achieves compression at the
+ expense of fidelity of the input speech signal.
+ Unlike some other speech codecs, it is possible to control the trade-off
+ made between quality and bit-rate.
+ The Speex encoding process 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}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+constant bit-rate
+\end_layout
 
 \end_inset
 
@@ -275,7 +522,12 @@ Speex encoding is controlled most of the time by a quality parameter that
 
 \begin_layout Subsection*
 Complexity
-\begin_inset LatexCommand \index{complexity}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+complexity
+\end_layout
 
 \end_inset
 
@@ -300,7 +552,12 @@ bzip2
  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}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+DTMF
+\end_layout
 
 \end_inset
 
@@ -309,7 +566,12 @@ bzip2
 
 \begin_layout Subsection*
 Variable Bit-Rate
-\begin_inset LatexCommand \index{variable bit-rate}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+variable bit-rate
+\end_layout
 
 \end_inset
 
@@ -330,7 +592,7 @@ difficulty
  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
+ For this reason, VBR can achieve 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.
@@ -341,7 +603,12 @@ difficulty
 
 \begin_layout Subsection*
 Average Bit-Rate
-\begin_inset LatexCommand \index{average bit-rate}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+average bit-rate
+\end_layout
 
 \end_inset
 
@@ -358,7 +625,12 @@ Average bit-rate solves one of the problems of VBR, as it dynamically adjusts
 
 \begin_layout Subsection*
 Voice Activity Detection
-\begin_inset LatexCommand \index{voice activity detection}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+voice activity detection
+\end_layout
 
 \end_inset
 
@@ -385,7 +657,12 @@ comfort noise generation
 
 \begin_layout Subsection*
 Discontinuous Transmission
-\begin_inset LatexCommand \index{discontinuous transmission}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+discontinuous transmission
+\end_layout
 
 \end_inset
 
@@ -401,7 +678,12 @@ Discontinuous transmission is an addition to VAD/VBR operation, that allows
 
 \begin_layout Subsection*
 Perceptual enhancement
-\begin_inset LatexCommand \index{perceptual enhancement}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+perceptual enhancement
+\end_layout
 
 \end_inset
 
@@ -409,15 +691,16 @@ Perceptual enhancement
 \end_layout
 
 \begin_layout Standard
-Perceptual enhancement is a part of the decoder which, when turned on, tries
- to reduce (the perception of) the noise produced by the coding/decoding
- process.
- In most cases, perceptual enhancement make the sound further from the original
+Perceptual enhancement is a part of the decoder which, when turned on, attempts
+ to reduce the perception of the noise/distortion produced by the encoding/decod
+ing process.
+ In most cases, perceptual enhancement brings the sound further from the
+ original 
 \emph on
 objectively
 \emph default
- (if you use SNR), but in the end it still 
+ (e.g.
+ considering only SNR), but in the end it still 
 \emph on
 sounds
 \emph default
@@ -425,8 +708,13 @@ sounds
 \end_layout
 
 \begin_layout Subsection*
-Algorithmic delay
-\begin_inset LatexCommand \index{algorithmic delay}
+Latency and algorithmic delay
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+algorithmic delay
+\end_layout
 
 \end_inset
 
@@ -460,12 +748,22 @@ The main characteristics of Speex can be summarized as follows:
 
 \begin_layout Itemize
 Free software/open-source
-\begin_inset LatexCommand \index{open-source}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+open-source
+\end_layout
 
 \end_inset
 
 , patent
-\begin_inset LatexCommand \index{patent}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+patent
+\end_layout
 
 \end_inset
 
@@ -474,12 +772,22 @@ Free software/open-source
 
 \begin_layout Itemize
 Integration of narrowband
-\begin_inset LatexCommand \index{narrowband}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+narrowband
+\end_layout
 
 \end_inset
 
  and wideband
-\begin_inset LatexCommand \index{wideband}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+wideband
+\end_layout
 
 \end_inset
 
@@ -492,7 +800,12 @@ Wide range of bit-rates available (from 2.15 kbps to 44 kbps)
 
 \begin_layout Itemize
 Dynamic bit-rate switching (AMR) and Variable Bit-Rate
-\begin_inset LatexCommand \index{variable bit-rate}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+variable bit-rate
+\end_layout
 
 \end_inset
 
@@ -501,7 +814,12 @@ Dynamic bit-rate switching (AMR) and Variable Bit-Rate
 
 \begin_layout Itemize
 Voice Activity Detection
-\begin_inset LatexCommand \index{voice activity detection}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+voice activity detection
+\end_layout
 
 \end_inset
 
@@ -510,7 +828,12 @@ Voice Activity Detection
 
 \begin_layout Itemize
 Variable complexity
-\begin_inset LatexCommand \index{complexity}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+complexity
+\end_layout
 
 \end_inset
 
@@ -522,7 +845,7 @@ Embedded wideband structure (scalable sampling rate)
 \end_layout
 
 \begin_layout Itemize
-Ultra-wideband mode at 32 kHz
+Ultra-wideband sampling rate at 32 kHz
 \end_layout
 
 \begin_layout Itemize
@@ -530,7 +853,7 @@ Intensity stereo encoding option
 \end_layout
 
 \begin_layout Itemize
-Fixed-point implementation (work in progress)
+Fixed-point implementation
 \end_layout
 
 \begin_layout Section
@@ -604,16 +927,39 @@ Acoustic Echo Canceller
 \end_layout
 
 \begin_layout Standard
+In any hands-free communication system (Fig.
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:Acoustic-echo-model"
+
+\end_inset
+
+), speech from the remote end is played in the local loudspeaker, propagates
+ in the room and is captured by the microphone.
+ If the audio captured from the microphone is sent directly to the remote
+ end, then the remove user hears an echo of his voice.
+ An acoustic echo canceller is designed to remove the acoustic echo before
+ it is sent to the remote end.
+ It is important to understand that the echo canceller is meant to improve
+ the quality on the 
+\series bold
+remote
+\series default
+ end.
+\end_layout
+
+\begin_layout Standard
 \begin_inset Float figure
 wide false
 sideways false
 status open
 
-\begin_layout Standard
+\begin_layout Plain Layout
 \begin_inset ERT
 status collapsed
 
-\begin_layout Standard
+\begin_layout Plain Layout
 
 
 \backslash
@@ -633,7 +979,7 @@ begin{center}
 \begin_inset ERT
 status collapsed
 
-\begin_layout Standard
+\begin_layout Plain Layout
 
 
 \backslash
@@ -645,8 +991,18 @@ end{center}
 
 \end_layout
 
-\begin_layout Caption
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
 Acoustic echo model
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:Acoustic-echo-model"
+
+\end_inset
+
+
 \end_layout
 
 \end_inset
@@ -654,834 +1010,821 @@ Acoustic echo model
 
 \end_layout
 
-\begin_layout Standard
+\end_inset
 
-\newpage
 
 \end_layout
 
-\begin_layout Chapter
-Compiling
+\begin_layout Section
+Resampler
 \end_layout
 
 \begin_layout Standard
-Compiling Speex under UNIX or any platform supported by autoconf (e.g.
- Win32/cygwin) is as easy as typing:
+In some cases, it may be useful to convert audio from one sampling rate
+ to another.
+ There are many reasons for that.
+ It can be for mixing streams that have different sampling rates, for supporting
+ sampling rates that the soundcard doesn't support, for transcoding, etc.
+ That's why there is now a resampler that is part of the Speex project.
+ This resampler can be used to convert between any two arbitrary rates (the
+ ratio must only be a rational number) and there is control over the quality/com
+plexity tradeoff.
 \end_layout
 
-\begin_layout LyX-Code
-% ./configure [options]
+\begin_layout Section
+Integration
 \end_layout
 
-\begin_layout LyX-Code
-% make
-\end_layout
+\begin_layout Standard
+Knowing 
+\emph on
+how
+\emph default
+ to use eacho of the components is not that useful unless we know 
+\emph on
+where
+\emph default
+ to use them.
+ Figure 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:Integration-VoIP"
 
-\begin_layout LyX-Code
-% make install
+\end_inset
+
+ shows where each of the components would be used in a typical VoIP client.
+ Components in dotted lines are optional, though they may be very useful
+ in some circumstances.
+ There are several important things to note from there.
+ The AEC must be placed as close as possible to the playback and capture.
+ Only the resampling may be closer.
+ Also, it is very important to use the same clock for both mic capture and
+ speaker/headphones playback.
 \end_layout
 
 \begin_layout Standard
-The options supported by the Speex configure script are:
-\end_layout
+\begin_inset Float figure
+wide false
+sideways false
+status open
 
-\begin_layout Description
---prefix=<path> Specifies where to install Speex
-\end_layout
+\begin_layout Plain Layout
+\begin_inset ERT
+status collapsed
 
-\begin_layout Description
---enable-shared/--disable-shared Whether to compile shared libraries
-\end_layout
+\begin_layout Plain Layout
 
-\begin_layout Description
---enable-static/--disable-static Whether to compile static libraries
+
+\backslash
+begin{center}
 \end_layout
 
-\begin_layout Description
---disable-wideband Disable the wideband part of Speex (typically to same
- space)
-\end_layout
-
-\begin_layout Description
---enable-valgrind Enable extra information when (and only when) running
- with valgrind
-\end_layout
+\end_inset
 
-\begin_layout Description
---enable-sse Enable use of SSE instructions (x86/float only)
-\end_layout
 
-\begin_layout Description
---enable-fixed-point
-\begin_inset LatexCommand \index{fixed-point}
+\begin_inset Graphics
+       filename components.eps
+       width 80text%
 
 \end_inset
 
- Compile Speex for a processor that does not have a floating point unit
- (FPU)
-\end_layout
-
-\begin_layout Description
---enable-arm4-asm Enable assembly specific to the ARMv4 architecture (gcc
- only)
-\end_layout
 
-\begin_layout Description
---enable-arm5e-asm Enable assembly specific to the ARMv5E architecture (gcc
- only)
-\end_layout
+\begin_inset ERT
+status collapsed
 
-\begin_layout Description
---enable-fixed-point-debug Use only for debugging the fixed-point
-\begin_inset LatexCommand \index{fixed-point}
+\begin_layout Plain Layout
 
-\end_inset
 
- code (very slow)
+\backslash
+end{center}
 \end_layout
 
-\begin_layout Description
---enable-epic-48k Enable a special (and non-compatible) 4.8 kbps narrowband
- mode
-\end_layout
+\end_inset
 
-\begin_layout Description
---enable-ti-c55x Enable support for the TI C5x family
-\end_layout
 
-\begin_layout Description
---enable-blackfin-asm Enable assembly specific to the Blackfin DSP architecture
- (gcc only)
 \end_layout
 
-\begin_layout Description
---enable-16bit-precision Reduces precision to 16 bits in time-critical areas
- (fixed-point only)
-\end_layout
+\begin_layout Plain Layout
+\begin_inset Caption
 
-\begin_layout Standard
+\begin_layout Plain Layout
+Integration of all the components in a VoIP client.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:Integration-VoIP"
 
-\newpage
+\end_inset
 
-\end_layout
 
-\begin_layout Chapter
-Command-line encoder/decoder
-\begin_inset LatexCommand \label{sec:Command-line-encoder/decoder}
+\end_layout
 
 \end_inset
 
 
 \end_layout
 
-\begin_layout Standard
-The base Speex distribution includes a command-line encoder (
-\emph on
-speexenc
-\emph default
-) and decoder (
-\emph on
-speexdec
-\emph default
-).
- This section describes how to use these tools.
-\end_layout
+\end_inset
 
-\begin_layout Section
 
-\emph on
-speexenc
-\begin_inset LatexCommand \index{speexenc}
+\end_layout
 
+\begin_layout Standard
+\begin_inset Newpage newpage
 \end_inset
 
 
 \end_layout
 
+\begin_layout Chapter
+Compiling and Porting
+\end_layout
+
 \begin_layout Standard
-The 
-\emph on
-speexenc
-\emph default
- utility is used to create Speex files from raw PCM or wave files.
- It can be used by calling: 
+Compiling Speex under UNIX/Linux or any other platform supported by autoconf
+ (e.g.
+ Win32/cygwin) is as easy as typing:
 \end_layout
 
 \begin_layout LyX-Code
-speexenc [options] input_file output_file
+% ./configure [options]
 \end_layout
 
-\begin_layout Standard
-The value '-' for input_file or output_file corresponds respectively to
- stdin and stdout.
- The valid options are:
+\begin_layout LyX-Code
+% make
 \end_layout
 
-\begin_layout Description
---narrowband\InsetSpace ~
-(-n) Tell Speex to treat the input as narrowband (8 kHz).
- This is the default
+\begin_layout LyX-Code
+% make install
 \end_layout
 
-\begin_layout Description
---wideband\InsetSpace ~
-(-w) Tell Speex to treat the input as wideband (16 kHz)
+\begin_layout Standard
+The options supported by the Speex configure script are:
 \end_layout
 
 \begin_layout Description
---ultra-wideband\InsetSpace ~
-(-u) Tell Speex to treat the input as 
-\begin_inset Quotes eld
-\end_inset
-
-ultra-wideband
-\begin_inset Quotes erd
-\end_inset
-
- (32 kHz)
+--prefix=<path> Specifies the base path for installing Speex (e.g.
+ /usr)
 \end_layout
 
 \begin_layout Description
---quality\InsetSpace ~
-n Set the encoding quality (0-10), default is 8
+--enable-shared/--disable-shared Whether to compile shared libraries
 \end_layout
 
 \begin_layout Description
---bitrate\InsetSpace ~
-n Encoding bit-rate (use bit-rate n or lower) 
+--enable-static/--disable-static Whether to compile static libraries
 \end_layout
 
 \begin_layout Description
---vbr Enable VBR (Variable Bit-Rate), disabled by default
+--disable-wideband Disable the wideband part of Speex (typically to save
+ space)
 \end_layout
 
 \begin_layout Description
---abr\InsetSpace ~
-n Enable ABR (Average Bit-Rate) at n kbps, disabled by default
+--enable-valgrind Enable extra hits for valgrind for debugging purposes
+ (do not use by default)
 \end_layout
 
 \begin_layout Description
---vad Enable VAD (Voice Activity Detection), disabled by default
+--enable-sse Enable use of SSE instructions (x86/float only)
 \end_layout
 
 \begin_layout Description
---dtx Enable DTX (Discontinuous Transmission), disabled by default
-\end_layout
+--enable-fixed-point
+\begin_inset Index
+status collapsed
 
-\begin_layout Description
---nframes\InsetSpace ~
-n Pack n frames in each Ogg packet (this saves space at low bit-rates)
+\begin_layout Plain Layout
+fixed-point
 \end_layout
 
-\begin_layout Description
---comp\InsetSpace ~
-n Set encoding speed/quality tradeoff.
The higher the value of n, the slower the encoding (default is 3)
+\end_inset
+
+ Compile Speex for a processor that does not have a floating point unit
(FPU)
 \end_layout
 
 \begin_layout Description
--V Verbose operation, print bit-rate currently in use
+--enable-arm4-asm Enable assembly specific to the ARMv4 architecture (gcc
+ only)
 \end_layout
 
 \begin_layout Description
---help\InsetSpace ~
-(-h) Print the help
+--enable-arm5e-asm Enable assembly specific to the ARMv5E architecture (gcc
+ only)
 \end_layout
 
 \begin_layout Description
---version\InsetSpace ~
-(-v) Print version information
-\end_layout
+--enable-fixed-point-debug Use only for debugging the fixed-point
+\begin_inset Index
+status collapsed
 
-\begin_layout Subsection*
-Speex comments
+\begin_layout Plain Layout
+fixed-point
 \end_layout
 
-\begin_layout Description
---comment Add the given string as an extra comment.
- This may be used multiple times.
+\end_inset
+
+ code (very slow)
 \end_layout
 
 \begin_layout Description
---author Author of this track.
+--enable-ti-c55x Enable support for the TI C5x family
 \end_layout
 
 \begin_layout Description
---title Title for this track.
+--enable-blackfin-asm Enable assembly specific to the Blackfin DSP architecture
+ (gcc only)
 \end_layout
 
-\begin_layout Subsection*
-Raw input options
+\begin_layout Section
+Platforms
 \end_layout
 
-\begin_layout Description
---rate\InsetSpace ~
-n Sampling rate for raw input
+\begin_layout Standard
+Speex is known to compile and work on a large number of architectures, both
+ floating-point and fixed-point.
+ In general, any architecture that can natively compute the multiplication
+ of two signed 16-bit numbers (32-bit result) and runs at a sufficient clock
+ rate (architecture-dependent) is capable of running Speex.
+ Architectures on which Speex is 
+\series bold
+known
+\series default
+ to work (it probably works on many others) are:
 \end_layout
 
-\begin_layout Description
---stereo Consider raw input as stereo 
+\begin_layout Itemize
+x86 & x86-64
 \end_layout
 
-\begin_layout Description
---le Raw input is little-endian 
+\begin_layout Itemize
+Power
 \end_layout
 
-\begin_layout Description
---be Raw input is big-endian 
+\begin_layout Itemize
+SPARC
 \end_layout
 
-\begin_layout Description
---8bit Raw input is 8-bit unsigned 
+\begin_layout Itemize
+ARM
 \end_layout
 
-\begin_layout Description
---16bit Raw input is 16-bit signed 
+\begin_layout Itemize
+Blackfin
 \end_layout
 
-\begin_layout Section
-
-\emph on
-speexdec
-\begin_inset LatexCommand \index{speexdec}
+\begin_layout Itemize
+Coldfire (68k family)
+\end_layout
 
-\end_inset
+\begin_layout Itemize
+TI C54xx & C55xx
+\end_layout
 
+\begin_layout Itemize
+TI C6xxx
+\end_layout
 
+\begin_layout Itemize
+TriMedia (experimental)
 \end_layout
 
 \begin_layout Standard
-The 
-\emph on
-speexdec
-\emph default
- utility is used to decode Speex files and can be used by calling: 
+Operating systems on top of which Speex is known to work include (it probably
+ works on many others):
 \end_layout
 
-\begin_layout LyX-Code
-speexdec [options] speex_file [output_file]
+\begin_layout Itemize
+Linux
 \end_layout
 
-\begin_layout Standard
-The value '-' for input_file or output_file corresponds respectively to
- stdin and stdout.
- Also, when no output_file is specified, the file is played to the soundcard.
- The valid options are:
+\begin_layout Itemize
+\begin_inset Formula $\mu$
+\end_inset
+
+Clinux
 \end_layout
 
-\begin_layout Description
---enh enable post-filter (default)
+\begin_layout Itemize
+MacOS X
 \end_layout
 
-\begin_layout Description
---no-enh disable post-filter
+\begin_layout Itemize
+BSD
 \end_layout
 
-\begin_layout Description
---force-nb Force decoding in narrowband 
+\begin_layout Itemize
+Other UNIX/POSIX variants
 \end_layout
 
-\begin_layout Description
---force-wb Force decoding in wideband 
+\begin_layout Itemize
+Symbian
 \end_layout
 
-\begin_layout Description
---force-uwb Force decoding in ultra-wideband 
+\begin_layout Standard
+The source code directory include additional information for compiling on
+ certain architectures or operating systems in README.xxx files.
 \end_layout
 
-\begin_layout Description
---mono Force decoding in mono 
+\begin_layout Section
+Porting and Optimising
 \end_layout
 
-\begin_layout Description
---stereo Force decoding in stereo 
+\begin_layout Standard
+Here are a few things to consider when porting or optimising Speex for a
+ new platform or an existing one.
 \end_layout
 
-\begin_layout Description
---rate\InsetSpace ~
-n Force decoding at n Hz sampling rate
+\begin_layout Subsection
+CPU optimisation
 \end_layout
 
-\begin_layout Description
---packet-loss\InsetSpace ~
-n Simulate n % random packet loss
+\begin_layout Standard
+The single factor that will affect the CPU usage of Speex the most is whether
+ it is compiled for floating point or fixed-point.
+ If your CPU/DSP does not have a floating-point unit FPU, then compiling
+ as fixed-point will be orders of magnitudes faster.
+ If there is an FPU present, then it is important to test which version
+ is faster.
+ On the x86 architecture, floating-point is 
+\series bold
+generally
+\series default
+ faster, but not always.
+ To compile Speex as fixed-point, you need to pass --fixed-point to the
+ configure script or define the FIXED_POINT macro for the compiler.
+ As of 1.2beta3, it is now possible to disable the floating-point compatibility
+ API, which means that your code can link without a float emulation library.
+ To do that configure with --disable-float-api or define the DISABLE_FLOAT_API
+ macro.
+ Until the VBR feature is ported to fixed-point, you will also need to configure
+ with --disable-vbr or define DISABLE_VBR.
 \end_layout
 
-\begin_layout Description
--V Verbose operation, print bit-rate currently in use
+\begin_layout Standard
+Other important things to check on some DSP architectures are:
 \end_layout
 
-\begin_layout Description
---help\InsetSpace ~
-(-h) Print the help
+\begin_layout Itemize
+Make sure the cache is set to write-back mode
 \end_layout
 
-\begin_layout Description
---version\InsetSpace ~
-(-v) Print version information
+\begin_layout Itemize
+If the chip has SRAM instead of cache, make sure as much code and data are
+ in SRAM, rather than in RAM
 \end_layout
 
 \begin_layout Standard
+If you are going to be writing assembly, then the following functions are
+\series bold
+usually
+\series default
+ the first ones you should consider optimising:
+\end_layout
+
+\begin_layout Itemize
+\begin_inset listings
+inline true
+status collapsed
 
-\newpage
+\begin_layout Plain Layout
 
+filter_mem16()
 \end_layout
 
-\begin_layout Chapter
-Programming with Speex (the libspeex
-\begin_inset LatexCommand \index{libspeex}
-
 \end_inset
 
- API
-\begin_inset LatexCommand \index{API}
 
-\end_inset
+\end_layout
 
-)
-\begin_inset LatexCommand \label{sec:Programming-with-Speex}
+\begin_layout Itemize
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+iir_mem16()
+\end_layout
 
 \end_inset
 
 
 \end_layout
 
-\begin_layout Standard
-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}
+\begin_layout Itemize
+\begin_inset listings
+inline true
+status collapsed
 
-\end_inset
+\begin_layout Plain Layout
 
-.
+vq_nbest()
 \end_layout
 
-\begin_layout Section
-Encoding
-\begin_inset LatexCommand \label{sub:Encoding}
-
 \end_inset
 
 
 \end_layout
 
-\begin_layout Standard
-In order to encode speech using Speex, you first need to:
-\end_layout
+\begin_layout Itemize
+\begin_inset listings
+inline true
+status collapsed
 
-\begin_layout LyX-Code
-#include <speex/speex.h>
-\end_layout
+\begin_layout Plain Layout
 
-\begin_layout Standard
-You then need to declare a Speex bit-packing struct
+pitch_xcorr()
 \end_layout
 
-\begin_layout LyX-Code
-SpeexBits bits;
-\end_layout
+\end_inset
 
-\begin_layout Standard
-and a Speex encoder state
-\end_layout
 
-\begin_layout LyX-Code
-void *enc_state;
 \end_layout
 
-\begin_layout Standard
-The two are initialized by:
-\end_layout
+\begin_layout Itemize
+\begin_inset listings
+inline true
+status collapsed
 
-\begin_layout LyX-Code
-speex_bits_init(&bits);
-\end_layout
+\begin_layout Plain Layout
 
-\begin_layout LyX-Code
-enc_state = speex_encoder_init(&speex_nb_mode);
+interp_pitch()
 \end_layout
 
-\begin_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:
-\end_layout
+\end_inset
 
-\begin_layout LyX-Code
-speex_encoder_ctl(enc_state,SPEEX_GET_FRAME_SIZE,&frame_size);
-\end_layout
 
-\begin_layout Standard
-In practice, 
-\emph on
-frame_size
-\emph default
- will correspond to 20 ms when using 8, 16, or 32 kHz sampling rate.
 \end_layout
 
 \begin_layout Standard
-Once the initialization is done, for every input frame:
+The filtering functions 
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+filter_mem16()
 \end_layout
 
-\begin_layout LyX-Code
-speex_bits_reset(&bits);
+\end_inset
+
+ and 
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+iir_mem16()
 \end_layout
 
-\begin_layout LyX-Code
-speex_encode_int(enc_state, input_frame, &bits);
+\end_inset
+
+ are implemented in the direct form II transposed (DF2T).
+ However, for architectures based on multiply-accumulate (MAC), DF2T requires
+ frequent reload of the accumulator, which can make the code very slow.
+ For these architectures (e.g.
+ Blackfin and Coldfire), a better approach is to implement those functions
+ as direct form I (DF1), which is easier to express in terms of MAC.
+ When doing that however, 
+\series bold
+it is important to make sure that the DF1 implementation still behaves like
+ the original DF2T behaviour when it comes to memory values
+\series default
+.
+ This is necessary because the filter is time-varying and must compute exactly
+ the same value (not counting machine rounding) on any encoder or decoder.
 \end_layout
 
-\begin_layout LyX-Code
-nbBytes = speex_bits_write(&bits, byte_ptr, MAX_NB_BYTES);
+\begin_layout Subsection
+Memory optimisation
 \end_layout
 
 \begin_layout Standard
-where 
-\emph on
-input_frame
-\emph default
- is a 
-\emph on
-(
-\emph default
-short
-\emph on
- *)
-\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.
+Memory optimisation is mainly something that should be considered for small
+ embedded platforms.
+ For PCs, Speex is already so tiny that it's just not worth doing any of
+ the things suggested here.
+ There are several ways to reduce the memory usage of Speex, both in terms
+ of code size and data size.
+ For optimising code size, the trick is to first remove features you do
+ not need.
+ Some examples of things that can easily be disabled 
+\series bold
+if you don't need them
+\series default
+ are:
 \end_layout
 
-\begin_layout Standard
-It is still possible to use the 
-\emph on
-speex_encode()
-\emph default
- function, which takes a 
-\emph on
-(float *)
-\emph default
- for the audio.
- However, this would make an eventual port to an FPU-less platform (like
- ARM) more complicated.
- Internally, 
-\emph on
-speex_encode() 
-\emph default
-and
-\emph on
- speex_encode_int()
-\emph default
- are processed in the same way.
- Whether the encoder uses the fixed-point version is only decided by the
- compile-time flags, not at the API level.
+\begin_layout Itemize
+Wideband support (--disable-wideband)
 \end_layout
 
-\begin_layout Standard
-After you're done with the encoding, free all resources with:
+\begin_layout Itemize
+Support for stereo (removing stereo.c)
 \end_layout
 
-\begin_layout LyX-Code
-speex_bits_destroy(&bits);
+\begin_layout Itemize
+VBR support (--disable-vbr or DISABLE_VBR)
 \end_layout
 
-\begin_layout LyX-Code
-speex_encoder_destroy(enc_state);
+\begin_layout Itemize
+Static codebooks that are not needed for the bit-rates you are using (*_table.c
+ files)
 \end_layout
 
 \begin_layout Standard
-That's about it for the encoder.
-\end_layout
+Speex also has several methods for allocating temporary arrays.
+ When using a compiler that supports C99 properly (as of 2007, Microsoft
+ compilers don't, but gcc does), it is best to define VAR_ARRAYS.
+ That makes use of the variable-size array feature of C99.
+ The next best is to define USE_ALLOCA so that Speex can use alloca() to
+ allocate the temporary arrays.
+ Note that on many systems, alloca() is buggy so it may not work.
+ If none of VAR_ARRAYS and USE_ALLOCA are defined, then Speex falls back
+ to allocating a large 
+\begin_inset Quotes eld
+\end_inset
 
-\begin_layout Section
-Decoding
-\begin_inset LatexCommand \label{sub:Decoding}
+scratch space
+\begin_inset Quotes erd
+\end_inset
 
+ and doing its own internal allocation.
+ The main disadvantage of this solution is that it is wasteful.
+ It needs to allocate enough stack for the worst case scenario (worst bit-rate,
+ highest complexity setting, ...) and by default, the memory isn't shared between
+ multiple encoder/decoder states.
+ Still, if the 
+\begin_inset Quotes eld
 \end_inset
 
+manual
+\begin_inset Quotes erd
+\end_inset
 
-\end_layout
+ allocation is the only option left, there are a few things that can be
+ improved.
+ By overriding the speex_alloc_scratch() call in os_support.h, it is possible
+ to always return the same memory area for all states
+\begin_inset Foot
+status collapsed
 
-\begin_layout Standard
-In order to decode speech using Speex, you first need to:
+\begin_layout Plain Layout
+In this case, one must be careful with threads
 \end_layout
 
-\begin_layout LyX-Code
-#include <speex/speex.h>
+\end_inset
+
+.
+ In addition to that, by redefining the NB_ENC_STACK and NB_DEC_STACK (or
+ similar for wideband), it is possible to only allocate memory for a scenario
+ that is known in advance.
+ In this case, it is important to measure the amount of memory required
+ for the specific sampling rate, bit-rate and complexity level being used.
 \end_layout
 
 \begin_layout Standard
-You also need to declare a Speex bit-packing struct
-\end_layout
+\begin_inset Newpage newpage
+\end_inset
 
-\begin_layout LyX-Code
-SpeexBits bits;
-\end_layout
 
-\begin_layout Standard
-and a Speex decoder state
 \end_layout
 
-\begin_layout LyX-Code
-void *dec_state;
-\end_layout
+\begin_layout Chapter
+Command-line encoder/decoder
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Command-line-encoder/decoder"
 
-\begin_layout Standard
-The two are initialized by:
-\end_layout
+\end_inset
 
-\begin_layout LyX-Code
-speex_bits_init(&bits);
-\end_layout
 
-\begin_layout LyX-Code
-dec_state = speex_decoder_init(&speex_nb_mode);
 \end_layout
 
 \begin_layout Standard
-For wideband decoding, 
-\emph on
-speex_nb_mode
-\emph default
- will be replaced by 
+The base Speex distribution includes a command-line encoder (
 \emph on
-speex_wb_mode
+speexenc
 \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 
+) and decoder (
 \emph on
-frame_size
+speexdec
 \emph default
- variable with:
+).
+ Those tools produce and read Speex files encapsulated in the Ogg container.
+ Although it is possible to encapsulate Speex in any container, Ogg is the
+ recommended container for files.
+ This section describes how to use the command line tools for Speex files
+ in Ogg.
 \end_layout
 
-\begin_layout LyX-Code
-speex_decoder_ctl(dec_state, SPEEX_GET_FRAME_SIZE, &frame_size); 
-\end_layout
+\begin_layout Section
 
-\begin_layout Standard
-There is also a parameter that can be set for the decoder: whether or not
- to use a perceptual enhancer.
- This can be set by: 
+\emph on
+speexenc
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+speexenc
 \end_layout
 
-\begin_layout LyX-Code
-speex_decoder_ctl(dec_state, SPEEX_SET_ENH, &enh); 
+\end_inset
+
+
 \end_layout
 
 \begin_layout Standard
-wher
+Th
 \emph on
-enh
+speexenc
 \emph default
is an int with value 0 to have the enhancer disabled and 1 to have it enabled.
- As of 1.2-beta1, the default is now to enable the enhancer.
utility is used to create Speex files from raw PCM or wave files.
+ It can be used by calling: 
 \end_layout
 
-\begin_layout Standard
-Again, once the decoder initialization is done, for every input frame:
+\begin_layout LyX-Code
+speexenc [options] input_file output_file
 \end_layout
 
-\begin_layout LyX-Code
-speex_bits_read_from(&bits, input_bytes, nbBytes);
+\begin_layout Standard
+The value '-' for input_file or output_file corresponds respectively to
+ stdin and stdout.
+ The valid options are:
 \end_layout
 
-\begin_layout LyX-Code
-speex_decode_int(dec_state, &bits, output_frame);
+\begin_layout Description
+--narrowband
+\begin_inset space ~
+\end_inset
+
+(-n) Tell Speex to treat the input as narrowband (8 kHz).
+ This is the default
 \end_layout
 
-\begin_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
-(short *)
-\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.
-\end_layout
+\begin_layout Description
+--wideband
+\begin_inset space ~
+\end_inset
 
-\begin_layout Standard
-As for the encoder, the 
-\emph on
-speex_decode()
-\emph default
- function can still be used, with a 
-\emph on
-(float *)
-\emph default
- as the output for the audio.
+(-w) Tell Speex to treat the input as wideband (16 kHz)
 \end_layout
 
-\begin_layout Standard
-After you're done with the decoding, free all resources with:
+\begin_layout Description
+--ultra-wideband
+\begin_inset space ~
+\end_inset
+
+(-u) Tell Speex to treat the input as 
+\begin_inset Quotes eld
+\end_inset
+
+ultra-wideband
+\begin_inset Quotes erd
+\end_inset
+
+ (32 kHz)
 \end_layout
 
-\begin_layout LyX-Code
-speex_bits_destroy(&bits);
+\begin_layout Description
+--quality
+\begin_inset space ~
+\end_inset
+
+n Set the encoding quality (0-10), default is 8
 \end_layout
 
-\begin_layout LyX-Code
-speex_decoder_destroy(dec_state);
+\begin_layout Description
+--bitrate
+\begin_inset space ~
+\end_inset
+
+n Encoding bit-rate (use bit-rate n or lower) 
 \end_layout
 
-\begin_layout Section
-Preprocessor
-\begin_inset LatexCommand \label{sub:Preprocessor}
+\begin_layout Description
+--vbr Enable VBR (Variable Bit-Rate), disabled by default
+\end_layout
 
+\begin_layout Description
+--abr
+\begin_inset space ~
 \end_inset
 
+n Enable ABR (Average Bit-Rate) at n kbps, disabled by default
+\end_layout
 
+\begin_layout Description
+--vad Enable VAD (Voice Activity Detection), disabled by default
 \end_layout
 
-\begin_layout Standard
-In order to use the Speex preprocessor
-\begin_inset LatexCommand \index{preprocessor}
+\begin_layout Description
+--dtx Enable DTX (Discontinuous Transmission), disabled by default
+\end_layout
 
+\begin_layout Description
+--nframes
+\begin_inset space ~
 \end_inset
 
-, you first need to:
+n Pack n frames in each Ogg packet (this saves space at low bit-rates)
 \end_layout
 
-\begin_layout LyX-Code
-#include <speex/speex_preprocess.h>
+\begin_layout Description
+--comp
+\begin_inset space ~
+\end_inset
+
+n Set encoding speed/quality tradeoff.
+ The higher the value of n, the slower the encoding (default is 3)
 \end_layout
 
-\begin_layout Standard
-Then, a preprocessor state can be created as:
+\begin_layout Description
+-V Verbose operation, print bit-rate currently in use
 \end_layout
 
-\begin_layout LyX-Code
-SpeexPreprocessState *preprocess_state = speex_preprocess_state_init(frame_size,
- sampling_rate);
+\begin_layout Description
+--help
+\begin_inset space ~
+\end_inset
+
+(-h) Print the help
 \end_layout
 
-\begin_layout Standard
-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
-).
+\begin_layout Description
+--version
+\begin_inset space ~
+\end_inset
+
+(-v) Print version information
 \end_layout
 
-\begin_layout Standard
-For each input frame, you need to call:
+\begin_layout Subsection*
+Speex comments
 \end_layout
 
-\begin_layout LyX-Code
-speex_preprocess_run(preprocess_state, audio_frame);
+\begin_layout Description
+--comment Add the given string as an extra comment.
+ This may be used multiple times.
 \end_layout
 
-\begin_layout Standard
-where 
-\family typewriter
-audio_frame
-\family default
- is used both as input and output.
+\begin_layout Description
+--author Author of this track.
 \end_layout
 
-\begin_layout Standard
-In cases where the output audio is not useful for a certain frame, it is
- possible to use instead:
+\begin_layout Description
+--title Title for this track.
 \end_layout
 
-\begin_layout LyX-Code
-speex_preprocess_estimate_update(preprocess_state, audio_frame);
+\begin_layout Subsection*
+Raw input options
 \end_layout
 
-\begin_layout Standard
-This call will update all the preprocessor internal state variables without
- computing the output audio, thus saving some CPU cycles.
+\begin_layout Description
+--rate
+\begin_inset space ~
+\end_inset
+
+n Sampling rate for raw input
 \end_layout
 
-\begin_layout Standard
-The behaviour of the preprocessor can be changed using:
+\begin_layout Description
+--stereo Consider raw input as stereo 
 \end_layout
 
-\begin_layout LyX-Code
-speex_preprocess_ctl(preprocess_state, request, ptr);
+\begin_layout Description
+--le Raw input is little-endian 
 \end_layout
 
-\begin_layout Standard
-which is used in the same way as the encoder and decoder equivalent.
- Options are listed in Section .
+\begin_layout Description
+--be Raw input is big-endian 
 \end_layout
 
-\begin_layout Standard
-The preprocessor state can be destroyed using:
+\begin_layout Description
+--8bit Raw input is 8-bit unsigned 
 \end_layout
 
-\begin_layout LyX-Code
-speex_preprocess_state_destroy(preprocess_state);
+\begin_layout Description
+--16bit Raw input is 16-bit signed 
 \end_layout
 
 \begin_layout Section
-Echo Cancellation
-\begin_inset LatexCommand \label{sub:Echo-Cancellation}
+
+\emph on
+speexdec
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+speexdec
+\end_layout
 
 \end_inset
 
@@ -1489,590 +1832,2892 @@ Echo Cancellation
 \end_layout
 
 \begin_layout Standard
-The Speex library now includes an echo cancellation
-\begin_inset LatexCommand \index{echo cancellation}
+The 
+\emph on
+speexdec
+\emph default
+ utility is used to decode Speex files and can be used by calling: 
+\end_layout
 
-\end_inset
+\begin_layout LyX-Code
+speexdec [options] speex_file [output_file]
+\end_layout
 
- algorithm suitable for Acoustic Echo Cancellation
-\begin_inset LatexCommand \index{acoustic echo cancellation}
+\begin_layout Standard
+The value '-' for input_file or output_file corresponds respectively to
+ stdin and stdout.
+ Also, when no output_file is specified, the file is played to the soundcard.
+ The valid options are:
+\end_layout
 
-\end_inset
+\begin_layout Description
+--enh enable post-filter (default)
+\end_layout
 
- (AEC).
- In order to use the echo canceller, you first need to
+\begin_layout Description
+--no-enh disable post-filter
 \end_layout
 
-\begin_layout LyX-Code
-#include <speex/speex_echo.h>
+\begin_layout Description
+--force-nb Force decoding in narrowband 
 \end_layout
 
-\begin_layout Standard
-Then, an echo canceller state can be created by:
+\begin_layout Description
+--force-wb Force decoding in wideband 
 \end_layout
 
-\begin_layout LyX-Code
-SpeexEchoState *echo_state = speex_echo_state_init(frame_size, filter_length);
+\begin_layout Description
+--force-uwb Force decoding in ultra-wideband 
 \end_layout
 
-\begin_layout Standard
-where 
-\family typewriter
-frame_size
-\family default
- is the amount of data (in samples) you want to process at once and 
-\family typewriter
-filter_length
-\family default
- is the length (in samples) of the echo cancelling filter you want to use
- (also known as 
-\shape italic
-tail length
-\shape default
+\begin_layout Description
+--mono Force decoding in mono 
+\end_layout
 
-\begin_inset LatexCommand \index{tail length}
+\begin_layout Description
+--stereo Force decoding in stereo 
+\end_layout
 
+\begin_layout Description
+--rate
+\begin_inset space ~
 \end_inset
 
-).
- 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).
+n Force decoding at n Hz sampling rate
 \end_layout
 
-\begin_layout Standard
-Once the echo canceller state is created, audio can be processed by:
+\begin_layout Description
+--packet-loss
+\begin_inset space ~
+\end_inset
+
+n Simulate n % random packet loss
 \end_layout
 
-\begin_layout LyX-Code
-speex_echo_cancellation(echo_state, input_frame, echo_frame, output_frame);
+\begin_layout Description
+-V Verbose operation, print bit-rate currently in use
 \end_layout
 
-\begin_layout Standard
-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.
+\begin_layout Description
+--help
+\begin_inset space ~
+\end_inset
+
+(-h) Print the help
+\end_layout
+
+\begin_layout Description
+--version
+\begin_inset space ~
+\end_inset
+
+(-v) Print version information
 \end_layout
 
 \begin_layout Standard
-One important thing to keep in mind is the relationship between 
-\family typewriter
-input_frame
-\family default
- and 
-\family typewriter
-echo_frame
-\family default
+\begin_inset Newpage newpage
+\end_inset
+
+
+\end_layout
+
+\begin_layout Chapter
+Using the Speex Codec API (
+\emph on
+libspeex
+\emph default
+
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+libspeex
+\end_layout
+
+\end_inset
+
+)
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Programming-with-Speex"
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+The 
+\emph on
+libspeex
+\emph default
+ library contains all the functions for encoding and decoding speech with
+ the Speex codec.
+ When linking on a UNIX system, one must add 
+\emph on
+-lspeex -lm
+\emph default
+ to the compiler command line.
+ One important thing to know is that 
+\series bold
+libspeex calls are reentrant, but not thread-safe
+\series 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
+ That means that it is fine to use calls from many threads, but 
+\series bold
+calls using the same state from multiple threads must be protected by mutexes
+\series 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:
-\end_layout
+ Examples of code can also be found in Appendix 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Sample-code"
 
-\begin_layout LyX-Code
-write_to_soundcard(echo_frame, frame_size);
+\end_inset
+
+ and the complete API documentation is included in the Documentation section
+ of the Speex website (http://www.speex.org/).
 \end_layout
 
-\begin_layout LyX-Code
-read_from_soundcard(input_frame, frame_size);
+\begin_layout Section
+Encoding
+\begin_inset CommandInset label
+LatexCommand label
+name "sub:Encoding"
+
+\end_inset
+
+
 \end_layout
 
-\begin_layout LyX-Code
-speex_echo_cancellation(echo_state, input_frame, echo_frame, output_frame);
+\begin_layout Standard
+In order to encode speech using Speex, one first needs to:
 \end_layout
 
 \begin_layout Standard
-If you wish to further reduce the echo present in the signal, you can do
- so by 
-\family typewriter
-associating the echo canceller to the preprocessor
-\family default
- (see Section 
-\begin_inset LatexCommand \ref{sub:Preprocessor}
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+#include <speex/speex.h>
+\end_layout
 
 \end_inset
 
-).
- This is done by calling:
+Then in the code, a Speex bit-packing struct must be declared, along with
+ a Speex encoder state:
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+SpeexBits bits;
 \end_layout
 
-\begin_layout LyX-Code
-speex_preprocess_ctl(preprocess_state, SPEEX_PREPROCESS_SET_ECHO_STATE,
- echo_state);
+\begin_layout Plain Layout
+
+void *enc_state;
 \end_layout
 
-\begin_layout Standard
-in the initialisation.
+\end_inset
+
+The two are initialized by:
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+speex_bits_init(&bits);
+\end_layout
+
+\begin_layout Plain Layout
+
+enc_state = speex_encoder_init(&speex_nb_mode);
+\end_layout
+
+\end_inset
+
+
 \end_layout
 
 \begin_layout Standard
-As of version 1.2-beta2, there is an alternative, simpler API that can be
- used instead of 
+For wideband coding, 
 \emph on
-speex_echo_cancellation()
+speex_nb_mode
+\emph default
+ will be replaced by 
+\emph on
+speex_wb_mode
 \emph default
 .
- When audio capture and playback are handled asynchronously (e.g.
- in different threads or using the 
+ In most cases, you will need to know the frame size used at the sampling
+ rate you are using.
+ You can get that value in the 
 \emph on
-poll()
+frame_size
 \emph default
- or 
+ variable (expressed in 
+\series bold
+samples
+\series default
+, not bytes) with:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+speex_encoder_ctl(enc_state,SPEEX_GET_FRAME_SIZE,&frame_size);
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+In practice, 
 \emph on
-select()
+frame_size
 \emph default
- system call), it can be difficult to keep track of what input_frame comes
- with what echo_frame.
- Instead, the playback comtext/thread can simply call:
+ will correspond to 20 ms when using 8, 16, or 32 kHz sampling rate.
+ There are many parameters that can be set for the Speex encoder, but the
+ most useful one is the quality parameter that controls the quality vs bit-rate
+ tradeoff.
+ This is set by:
 \end_layout
 
-\begin_layout LyX-Code
-speex_echo_playback(echo_state, echo_frame);
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+speex_encoder_ctl(enc_state,SPEEX_SET_QUALITY,&quality);
+\end_layout
+
+\end_inset
+
+where 
+\emph on
+quality
+\emph default
+ is an integer value ranging from 0 to 10 (inclusively).
+ The mapping between quality and bit-rate is described in Fig.
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "cap:quality_vs_bps"
+
+\end_inset
+
+ for narrowband.
 \end_layout
 
 \begin_layout Standard
-every time an audio frame is played.
- Then, the capture context/thread calls:
+Once the initialization is done, for every input frame:
 \end_layout
 
-\begin_layout LyX-Code
-speex_echo_capture(echo_state, input_frame, output_frame);
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+speex_bits_reset(&bits);
+\end_layout
+
+\begin_layout Plain Layout
+
+speex_encode_int(enc_state, input_frame, &bits);
+\end_layout
+
+\begin_layout Plain Layout
+
+nbBytes = speex_bits_write(&bits, byte_ptr, MAX_NB_BYTES);
+\end_layout
+
+\end_inset
+
+
 \end_layout
 
 \begin_layout Standard
-for every frame captured.
- Internally, 
+where 
 \emph on
-speex_echo_playback()
+input_frame
 \emph default
- simply buffers the playback frame so it can be used by 
+ is a 
 \emph on
-speex_echo_capture()
+(
 \emph default
- to call 
+short 
 \emph on
-speex_echo_cancel()
+*)
 \emph default
-.
- A side effect of using this alternate API is that the playback audio is
- delayed by two frames, which is the normal delay caused by the soundcard.
- When capture and playback are already synchronised, 
+ pointing to the beginning of a speech frame, 
 \emph on
-speex_echo_cancellation()
+byte_ptr
 \emph default
- is preferable since it gives better control on the exact input/echo timing.
-\end_layout
-
-\begin_layout Standard
-The echo cancellation state can be destroyed with:
-\end_layout
-
-\begin_layout LyX-Code
-speex_echo_state_destroy(echo_state);
+ 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.
 \end_layout
 
 \begin_layout Standard
-It is also possible to reset the state of the echo canceller so it can be
- reused without the need to create another state with:
-\end_layout
+It is still possible to use the 
+\emph on
+speex_encode()
+\emph default
+ function, which takes a 
+\emph on
+(float *)
+\emph default
+ for the audio.
+ However, this would make an eventual port to an FPU-less platform (like
+ ARM) more complicated.
+ Internally, 
+\emph on
+speex_encode()
+\emph default
+ and 
+\emph on
+speex_encode_int()
+\emph default
+ are processed in the same way.
+ Whether the encoder uses the fixed-point version is only decided by the
+ compile-time flags, not at the API level.
+\end_layout
+
+\begin_layout Standard
+After you're done with the encoding, free all resources with:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+speex_bits_destroy(&bits);
+\end_layout
+
+\begin_layout Plain Layout
+
+speex_encoder_destroy(enc_state);
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+That's about it for the encoder.
+\end_layout
+
+\begin_layout Section
+Decoding
+\begin_inset CommandInset label
+LatexCommand label
+name "sub:Decoding"
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+In order to decode speech using Speex, you first need to:
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+#include <speex/speex.h>
+\end_layout
+
+\end_inset
+
+You also need to declare a Speex bit-packing struct
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+SpeexBits bits;
+\end_layout
+
+\end_inset
+
+and a Speex decoder state
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+void *dec_state;
+\end_layout
+
+\end_inset
+
+The two are initialized by:
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+speex_bits_init(&bits);
+\end_layout
+
+\begin_layout Plain Layout
+
+dec_state = speex_decoder_init(&speex_nb_mode);
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+For wideband decoding, 
+\emph on
+speex_nb_mode
+\emph default
+ will be replaced by 
+\emph on
+speex_wb_mode
+\emph default
+.
+ If you need to obtain the size of the frames that will be used by the decoder,
+ you can get that value in the 
+\emph on
+frame_size
+\emph default
+ variable (expressed in 
+\series bold
+samples
+\series default
+, not bytes) with:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+speex_decoder_ctl(dec_state, SPEEX_GET_FRAME_SIZE, &frame_size);
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+There is also a parameter that can be set for the decoder: whether or not
+ to use a perceptual enhancer.
+ This can be set by: 
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+speex_decoder_ctl(dec_state, SPEEX_SET_ENH, &enh);
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+where 
+\emph on
+enh
+\emph default
+ is an int with value 0 to have the enhancer disabled and 1 to have it enabled.
+ As of 1.2-beta1, the default is now to enable the enhancer.
+\end_layout
+
+\begin_layout Standard
+Again, once the decoder initialization is done, for every input frame:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+speex_bits_read_from(&bits, input_bytes, nbBytes);
+\end_layout
+
+\begin_layout Plain Layout
+
+speex_decode_int(dec_state, &bits, output_frame);
+\end_layout
+
+\end_inset
+
+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
+(short *)
+\emph default
+ and points to the area where the decoded speech frame will be written.
+ A NULL value as the second 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.
+\end_layout
+
+\begin_layout Standard
+As for the encoder, the 
+\emph on
+speex_decode()
+\emph default
+ function can still be used, with a 
+\emph on
+(float *)
+\emph default
+ as the output for the audio.
+ After you're done with the decoding, free all resources with:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+speex_bits_destroy(&bits);
+\end_layout
+
+\begin_layout Plain Layout
+
+speex_decoder_destroy(dec_state);
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section
+Codec Options (speex_*_ctl)
+\begin_inset CommandInset label
+LatexCommand label
+name "sub:Codec-Options"
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Quote
+\align center
+
+\emph on
+Entities should not be multiplied beyond necessity -- William of Ockham.
+\end_layout
+
+\begin_layout Quote
+\align center
+
+\emph on
+Just because there's an option for it doesn't mean you have to turn it on
+ -- me.
+\end_layout
+
+\begin_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 to the 
+\emph on
+ioctl
+\emph default
+ system call and their prototypes are:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+void speex_encoder_ctl(void *encoder, int request, void *ptr);
+\end_layout
+
+\begin_layout Plain Layout
+
+void speex_decoder_ctl(void *encoder, int request, void *ptr);
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Despite those functions, the defaults are usually good for many applications
+ and 
+\series bold
+optional settings should only be used when one understands them and knows
+ that they are needed
+\series default
+.
+ A common error is to attempt to set many unnecessary settings.
+\end_layout
+
+\begin_layout Standard
+Here is a list of the values allowed for the requests.
+ Some only apply to the encoder or the decoder.
+ Because the last argument is of type 
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+void *
+\end_layout
+
+\end_inset
+
+, the 
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+_ctl()
+\end_layout
+
+\end_inset
+
+ functions are 
+\series bold
+not type safe
+\series default
+, and should thus be used with care.
+ The type 
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+ is the same as the C99 
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+int32_t
+\end_layout
+
+\end_inset
+
+ type.
+\end_layout
+
+\begin_layout Description
+SPEEX_SET_ENH
+\begin_inset Formula $\ddagger$
+\end_inset
+
+ Set perceptual enhancer
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+perceptual enhancement
+\end_layout
+
+\end_inset
+
+ to on (1) or off (0) (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+, default is on)
+\end_layout
+
+\begin_layout Description
+SPEEX_GET_ENH
+\begin_inset Formula $\ddagger$
+\end_inset
+
+ Get perceptual enhancer status (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+)
+\end_layout
+
+\begin_layout Description
+SPEEX_GET_FRAME_SIZE Get the number of samples per frame for the current
+ mode (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+)
+\end_layout
+
+\begin_layout Description
+SPEEX_SET_QUALITY
+\begin_inset Formula $\dagger$
+\end_inset
+
+ Set the encoder speech quality (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+ from 0 to 10, default is 8)
+\end_layout
+
+\begin_layout Description
+SPEEX_GET_QUALITY
+\begin_inset Formula $\dagger$
+\end_inset
+
+ Get the current encoder speech quality (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+ from 0 to 10)
+\end_layout
+
+\begin_layout Description
+SPEEX_SET_MODE
+\begin_inset Formula $\dagger$
+\end_inset
+
+ Set the mode number, as specified in the RTP spec (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+)
+\end_layout
+
+\begin_layout Description
+SPEEX_GET_MODE
+\begin_inset Formula $\dagger$
+\end_inset
+
+ Get the current mode number, as specified in the RTP spec (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+)
+\end_layout
+
+\begin_layout Description
+SPEEX_SET_VBR
+\begin_inset Formula $\dagger$
+\end_inset
+
+ Set variable bit-rate (VBR) to on (1) or off (0) (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+, default is off)
+\end_layout
+
+\begin_layout Description
+SPEEX_GET_VBR
+\begin_inset Formula $\dagger$
+\end_inset
+
+ Get variable bit-rate
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+variable bit-rate
+\end_layout
+
+\end_inset
+
+ (VBR) status (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+)
+\end_layout
+
+\begin_layout Description
+SPEEX_SET_VBR_QUALITY
+\begin_inset Formula $\dagger$
+\end_inset
+
+ Set the encoder VBR speech quality (float 0.0 to 10.0, default is 8.0)
+\end_layout
+
+\begin_layout Description
+SPEEX_GET_VBR_QUALITY
+\begin_inset Formula $\dagger$
+\end_inset
+
+ Get the current encoder VBR speech quality (float 0 to 10)
+\end_layout
+
+\begin_layout Description
+SPEEX_SET_COMPLEXITY
+\begin_inset Formula $\dagger$
+\end_inset
+
+ Set the CPU resources allowed for the encoder (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+ from 1 to 10, default is 2)
+\end_layout
+
+\begin_layout Description
+SPEEX_GET_COMPLEXITY
+\begin_inset Formula $\dagger$
+\end_inset
+
+ Get the CPU resources allowed for the encoder (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+ from 1 to 10, default is 2)
+\end_layout
+
+\begin_layout Description
+SPEEX_SET_BITRATE
+\begin_inset Formula $\dagger$
+\end_inset
+
+ Set the bit-rate to use the closest value not exceeding the parameter (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+ in bits per second)
+\end_layout
+
+\begin_layout Description
+SPEEX_GET_BITRATE Get the current bit-rate in use (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+ in bits per second)
+\end_layout
+
+\begin_layout Description
+SPEEX_SET_SAMPLING_RATE Set real sampling rate (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+ in Hz)
+\end_layout
+
+\begin_layout Description
+SPEEX_GET_SAMPLING_RATE Get real sampling rate (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+ in Hz)
+\end_layout
+
+\begin_layout Description
+SPEEX_RESET_STATE Reset the encoder/decoder state to its original state,
+ clearing all memories (no argument)
+\end_layout
+
+\begin_layout Description
+SPEEX_SET_VAD
+\begin_inset Formula $\dagger$
+\end_inset
+
+ Set voice activity detection
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+voice activity detection
+\end_layout
+
+\end_inset
+
+ (VAD) to on (1) or off (0) (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+, default is off)
+\end_layout
+
+\begin_layout Description
+SPEEX_GET_VAD
+\begin_inset Formula $\dagger$
+\end_inset
+
+ Get voice activity detection (VAD) status (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+)
+\end_layout
+
+\begin_layout Description
+SPEEX_SET_DTX
+\begin_inset Formula $\dagger$
+\end_inset
+
+ Set discontinuous transmission
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+discontinuous transmission
+\end_layout
+
+\end_inset
+
+ (DTX) to on (1) or off (0) (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+, default is off)
+\end_layout
+
+\begin_layout Description
+SPEEX_GET_DTX
+\begin_inset Formula $\dagger$
+\end_inset
+
+ Get discontinuous transmission (DTX) status (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+)
+\end_layout
+
+\begin_layout Description
+SPEEX_SET_ABR
+\begin_inset Formula $\dagger$
+\end_inset
+
+ Set average bit-rate
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+average bit-rate
+\end_layout
+
+\end_inset
+
+ (ABR) to a value n in bits per second (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+ in bits per second)
+\end_layout
+
+\begin_layout Description
+SPEEX_GET_ABR
+\begin_inset Formula $\dagger$
+\end_inset
+
+ Get average bit-rate (ABR) setting (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+ in bits per second)
+\end_layout
+
+\begin_layout Description
+SPEEX_SET_PLC_TUNING
+\begin_inset Formula $\dagger$
+\end_inset
+
+ Tell the encoder to optimize encoding for a certain percentage of packet
+ loss (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+ in percent)
+\end_layout
+
+\begin_layout Description
+SPEEX_GET_PLC_TUNING
+\begin_inset Formula $\dagger$
+\end_inset
+
+ Get the current tuning of the encoder for PLC (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+ in percent)
+\end_layout
+
+\begin_layout Description
+SPEEX_SET_VBR_MAX_BITRATE
+\begin_inset Formula $\dagger$
+\end_inset
+
+ Set the maximum bit-rate allowed in VBR operation (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+ in bits per second)
+\end_layout
+
+\begin_layout Description
+SPEEX_GET_VBR_MAX_BITRATE
+\begin_inset Formula $\dagger$
+\end_inset
+
+ Get the current maximum bit-rate allowed in VBR operation (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+ in bits per second)
+\end_layout
+
+\begin_layout Description
+SPEEX_SET_HIGHPASS Set the high-pass filter on (1) or off (0) (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+, default is on)
+\end_layout
+
+\begin_layout Description
+SPEEX_GET_HIGHPASS Get the current high-pass filter status (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+)
+\end_layout
+
+\begin_layout Description
+\begin_inset Formula $\dagger$
+\end_inset
+
+ applies only to the encoder
+\end_layout
+
+\begin_layout Description
+\begin_inset Formula $\ddagger$
+\end_inset
+
+ applies only to the decoder
+\end_layout
+
+\begin_layout Section
+Mode queries
+\begin_inset CommandInset label
+LatexCommand label
+name "sub:Mode-queries"
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+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:
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+void speex_mode_query(SpeexMode *mode, int request, void *ptr);
+\end_layout
+
+\end_inset
+
+The admissible values for request are (unless otherwise note, the values
+ are returned through 
+\emph on
+ptr
+\emph default
+):
+\end_layout
+
+\begin_layout Description
+SPEEX_MODE_FRAME_SIZE Get the frame size (in samples) for the mode
+\end_layout
+
+\begin_layout Description
+SPEEX_SUBMODE_BITRATE Get the bit-rate for a submode number specified through
+\emph on
+ptr
+\emph default
+ (integer in bps).
+\end_layout
+
+\begin_layout Section
+Packing and in-band signalling
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+in-band signalling
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Sometimes it is desirable to pack more than one frame per packet (or other
+ basic unit of storage).
+ The proper way to do it is to call speex_encode 
+\begin_inset Formula $N$
+\end_inset
+
+ times before writing the stream with speex_bits_write.
+ In cases where the number of frames is not determined by an out-of-band
+ mechanism, it is possible to include a terminator code.
+ That terminator consists of the code 15 (decimal) encoded with 5 bits,
+ as shown in Table 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "cap:quality_vs_bps"
+
+\end_inset
+
+.
+ 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.
+\end_layout
+
+\begin_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 CommandInset ref
+LatexCommand ref
+reference "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.
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float table
+placement htbp
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\begin_inset ERT
+status collapsed
+
+\begin_layout Plain Layout
+
+
+\backslash
+begin{center}
+\end_layout
+
+\end_inset
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="17" columns="3">
+<features>
+<column alignment="center" valignment="top" width="0pt">
+<column alignment="center" valignment="top" width="0pt">
+<column alignment="center" valignment="top" width="0pt">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Code
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Size (bits)
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Content
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Asks decoder to set perceptual enhancement off (0) or on(1)
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Asks (if 1) the encoder to be less 
+\begin_inset Quotes eld
+\end_inset
+
+aggressive
+\begin_inset Quotes erd
+\end_inset
+
+ due to high packet loss
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+2
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+4
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Asks encoder to switch to mode N
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+3
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+4
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Asks encoder to switch to mode N for low-band
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+4
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+4
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Asks encoder to switch to mode N for high-band
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+5
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+4
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Asks encoder to switch to quality N for VBR
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+6
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+4
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Request acknowledge (0=no, 1=all, 2=only for in-band data)
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+7
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+4
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Asks encoder to set CBR (0), VAD(1), DTX(3), VBR(5), VBR+DTX(7)
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+8
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+8
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Transmit (8-bit) character to the other end
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+9
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+8
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Intensity stereo information
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+10
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+16
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Announce maximum bit-rate acceptable (N in bytes/second)
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+11
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+16
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+reserved
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+12
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+32
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Acknowledge receiving packet N
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+13
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+32
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+reserved
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+14
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+64
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+reserved
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+15
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+64
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+reserved
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\begin_inset ERT
+status collapsed
+
+\begin_layout Plain Layout
+
+
+\backslash
+end{center}
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+In-band signalling codes
+\begin_inset CommandInset label
+LatexCommand label
+name "cap:In-band-signalling-codes"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_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.
+\begin_inset Newpage newpage
+\end_inset
+
+
+\end_layout
+
+\begin_layout Chapter
+Speech Processing API (
+\emph on
+libspeexdsp
+\emph default
+)
+\end_layout
+
+\begin_layout Standard
+As of version 1.2beta3, the non-codec parts of the Speex package are now
+ in a separate library called 
+\emph on
+libspeexdsp
+\emph default
+.
+ This library includes the preprocessor, the acoustic echo canceller, the
+ jitter buffer, and the resampler.
+ In a UNIX environment, it can be linked into a program by adding 
+\emph on
+-lspeexdsp -lm
+\emph default
+ to the compiler command line.
+ Just like for libspeex, 
+\series bold
+libspeexdsp calls are reentrant, but not thread-safe
+\series default
+.
+ That means that it is fine to use calls from many threads, but 
+\series bold
+calls using the same state from multiple threads must be protected by mutexes
+\series default
+.
+\end_layout
+
+\begin_layout Section
+Preprocessor
+\begin_inset CommandInset label
+LatexCommand label
+name "sub:Preprocessor"
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\noindent
+In order to use the Speex preprocessor
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+preprocessor
+\end_layout
+
+\end_inset
+
+, you first need to:
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+#include <speex/speex_preprocess.h>
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\noindent
+Then, a preprocessor state can be created as:
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+SpeexPreprocessState *preprocess_state = speex_preprocess_state_init(frame_size,
+ sampling_rate);
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\noindent
+and 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
+).
+\end_layout
+
+\begin_layout Standard
+For each input frame, you need to call:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+speex_preprocess_run(preprocess_state, audio_frame);
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\noindent
+where 
+\family typewriter
+audio_frame
+\family default
+ is used both as input and output.
+ In cases where the output audio is not useful for a certain frame, it is
+ possible to use instead:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+speex_preprocess_estimate_update(preprocess_state, audio_frame);
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\noindent
+This call will update all the preprocessor internal state variables without
+ computing the output audio, thus saving some CPU cycles.
+\end_layout
+
+\begin_layout Standard
+The behaviour of the preprocessor can be changed using:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+speex_preprocess_ctl(preprocess_state, request, ptr);
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+\noindent
+which is used in the same way as the encoder and decoder equivalent.
+ Options are listed in Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sub:Preprocessor-options"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Standard
+The preprocessor state can be destroyed using:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+speex_preprocess_state_destroy(preprocess_state);
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Preprocessor options
+\begin_inset CommandInset label
+LatexCommand label
+name "sub:Preprocessor-options"
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+As with the codec, the preprocessor also has options that can be controlled
+ using an ioctl()-like call.
+ The available options are:
+\end_layout
+
+\begin_layout Description
+SPEEX_PREPROCESS_SET_DENOISE Turns denoising on(1) or off(2) (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+)
+\end_layout
+
+\begin_layout Description
+SPEEX_PREPROCESS_GET_DENOISE Get denoising status (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+)
+\end_layout
+
+\begin_layout Description
+SPEEX_PREPROCESS_SET_AGC Turns automatic gain control (AGC) on(1) or off(2)
+ (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+)
+\end_layout
+
+\begin_layout Description
+SPEEX_PREPROCESS_GET_AGC Get AGC status (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+)
+\end_layout
+
+\begin_layout Description
+SPEEX_PREPROCESS_SET_VAD Turns voice activity detector (VAD) on(1) or off(2)
+ (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+)
+\end_layout
+
+\begin_layout Description
+SPEEX_PREPROCESS_GET_VAD Get VAD status (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+)
+\end_layout
+
+\begin_layout Description
+SPEEX_PREPROCESS_SET_AGC_LEVEL
+\end_layout
+
+\begin_layout Description
+SPEEX_PREPROCESS_GET_AGC_LEVEL
+\end_layout
+
+\begin_layout Description
+SPEEX_PREPROCESS_SET_DEREVERB Turns reverberation removal on(1) or off(2)
+ (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+)
+\end_layout
+
+\begin_layout Description
+SPEEX_PREPROCESS_GET_DEREVERB Get reverberation removal status (
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+)
+\end_layout
+
+\begin_layout Description
+SPEEX_PREPROCESS_SET_DEREVERB_LEVEL Not working yet, do not use
+\end_layout
+
+\begin_layout Description
+SPEEX_PREPROCESS_GET_DEREVERB_LEVEL Not working yet, do not use
+\end_layout
+
+\begin_layout Description
+SPEEX_PREPROCESS_SET_DEREVERB_DECAY Not working yet, do not use
+\end_layout
+
+\begin_layout Description
+SPEEX_PREPROCESS_GET_DEREVERB_DECAY Not working yet, do not use
+\end_layout
+
+\begin_layout Description
+SPEEX_PREPROCESS_SET_PROB_START
+\end_layout
+
+\begin_layout Description
+SPEEX_PREPROCESS_GET_PROB_START
+\end_layout
+
+\begin_layout Description
+SPEEX_PREPROCESS_SET_PROB_CONTINUE
+\end_layout
+
+\begin_layout Description
+SPEEX_PREPROCESS_GET_PROB_CONTINUE
+\end_layout
+
+\begin_layout Description
+SPEEX_PREPROCESS_SET_NOISE_SUPPRESS Set maximum attenuation of the noise
+ in dB (negative 
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+)
+\end_layout
+
+\begin_layout Description
+SPEEX_PREPROCESS_GET_NOISE_SUPPRESS Get maximum attenuation of the noise
+ in dB (negative 
+\begin_inset listings
+inline true
+status collapsed
 
-\begin_layout LyX-Code
-speex_echo_state_reset(echo_state);
-\end_layout
+\begin_layout Plain Layout
 
-\begin_layout Subsection
-Troubleshooting
+spx_int32_t
 \end_layout
 
-\begin_layout Standard
-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
+\end_inset
+
+)
 \end_layout
 
-\begin_layout Itemize
-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
+\begin_layout Description
+SPEEX_PREPROCESS_SET_ECHO_SUPPRESS Set maximum attenuation of the residual
+ echo in dB (negative 
+\begin_inset listings
+inline true
+status collapsed
 
-locked
-\begin_inset Quotes erd
-\end_inset
+\begin_layout Plain Layout
 
- on the same clock source.
+spx_int32_t
 \end_layout
 
-\begin_layout Itemize
-The delay between the record and playback signals must be minimal.
- Any signal played has to 
-\begin_inset Quotes eld
 \end_inset
 
-appear
-\begin_inset Quotes erd
-\end_inset
+)
+\end_layout
 
- on the playback (far end) signal slightly before the echo canceller 
-\begin_inset Quotes eld
-\end_inset
+\begin_layout Description
+SPEEX_PREPROCESS_GET_ECHO_SUPPRESS Get maximum attenuation of the residual
+ echo in dB (negative 
+\begin_inset listings
+inline true
+status collapsed
 
-sees
-\begin_inset Quotes erd
-\end_inset
+\begin_layout Plain Layout
 
- 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.
+spx_int32_t
 \end_layout
 
-\begin_layout Itemize
-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.
-\end_layout
+\end_inset
 
-\begin_layout Itemize
-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.
+)
 \end_layout
 
-\begin_layout Standard
-Also useful is reading 
-\emph on
-Echo Cancellation Demystified
-\emph default
- by Alexey Frunze
-\begin_inset Foot
+\begin_layout Description
+SPEEX_PREPROCESS_SET_ECHO_SUPPRESS_ACTIVE Set maximum attenuation of the
+ echo in dB when near end is active (negative 
+\begin_inset listings
+inline true
 status collapsed
 
-\begin_layout Standard
-http://www.embeddedstar.com/articles/2003/7/article20030720-1.html
+\begin_layout Plain Layout
+
+spx_int32_t
 \end_layout
 
 \end_inset
 
-, which explains the fundamental principles of echo cancellation.
- The details of the algorithm described in the article are different, but
- the general ideas of echo cancellation through adaptive filters are the
- same.
+)
 \end_layout
 
-\begin_layout Standard
-As of version 1.2beta2, a new 
-\family typewriter
-echo_diagnostic.m
-\family default
- tool is included in the source distribution.
- The first step is to define DUMP_ECHO_CANCEL_DATA during the build.
- This causes the echo canceller to automatically save the near-end, far-end
- and output signals to files (aec_rec.sw aec_play.sw and aec_out.sw).
- These are exactly what the AEC receives and outputs.
- From there, it is necessary to start Octave and type:
+\begin_layout Description
+SPEEX_PREPROCESS_GET_ECHO_SUPPRESS_ACTIVE Get maximum attenuation of the
+ echo in dB when near end is active (negative 
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+spx_int32_t
 \end_layout
 
-\begin_layout LyX-Code
-echo_diagnostic('aec_rec.sw', 'aec_play.sw', 'aec_diagnostic.sw', 1024);
+\end_inset
+
+)
 \end_layout
 
-\begin_layout Standard
-The value of 1024 is the filter length and can be changed.
- There will be some (hopefully) useful messages printed and echo cancelled
- audio will be saved to aec_diagnostic.sw .
- If even that output is bad (almost no cancellation) then there is  probably
- problem with the playback or recording process.
+\begin_layout Description
+SPEEX_PREPROCESS_SET_ECHO_STATE Set the associated echo canceller for residual
+ echo suppression (pointer or NULL for no residual echo suppression)
+\end_layout
+
+\begin_layout Description
+SPEEX_PREPROCESS_GET_ECHO_STATE Get the associated echo canceller (pointer)
 \end_layout
 
 \begin_layout Section
-Codec Options (speex_*_ctl)
-\begin_inset LatexCommand \label{sub:Codec-Options}
+Echo Cancellation
+\begin_inset CommandInset label
+LatexCommand label
+name "sub:Echo-Cancellation"
 
 \end_inset
 
 
 \end_layout
 
-\begin_layout Quote
-\align center
+\begin_layout Standard
+The Speex library now includes an echo cancellation
+\begin_inset Index
+status collapsed
 
-\emph on
-Entities should not be multiplied beyond necessity -- William of Ockham.
+\begin_layout Plain Layout
+echo cancellation
 \end_layout
 
-\begin_layout Quote
-\align center
+\end_inset
 
-\emph on
-Just because there's an option doesn't mean you have to use it -- me.
-\end_layout
+ algorithm suitable for Acoustic Echo Cancellation
+\begin_inset Index
+status collapsed
 
-\begin_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.
- Despite that, the defaults are good for many applications and 
-\series bold
-optional settings should only be used when one understands them and knows
- that they are needed
-\series default
-.
- A common error is to attempt to set many unnecessary settings.
- These functions are similar to the 
-\emph on
-ioctl
-\emph default
- system call and their prototypes are:
+\begin_layout Plain Layout
+acoustic echo cancellation
 \end_layout
 
-\begin_layout LyX-Code
-void speex_encoder_ctl(void *encoder, int request, void *ptr);
-\end_layout
+\end_inset
 
-\begin_layout LyX-Code
-void speex_decoder_ctl(void *encoder, int request, void *ptr);
+ (AEC).
+ In order to use the echo canceller, you first need to
 \end_layout
 
 \begin_layout Standard
-The different values of request allowed are (note that some only apply to
- the encoder or the decoder):
-\end_layout
+\begin_inset listings
+inline false
+status open
 
-\begin_layout Description
-SPEEX_SET_ENH** Set perceptual enhancer
-\begin_inset LatexCommand \index{perceptual enhancement}
+\begin_layout Plain Layout
+
+#include <speex/speex_echo.h>
+\end_layout
 
 \end_inset
 
- to on (1) or off (0) (integer)
-\end_layout
 
-\begin_layout Description
-SPEEX_GET_ENH** Get perceptual enhancer status (integer)
 \end_layout
 
-\begin_layout Description
-SPEEX_GET_FRAME_SIZE Get the frame size used for the current mode (integer)
+\begin_layout Standard
+Then, an echo canceller state can be created by:
 \end_layout
 
-\begin_layout Description
-SPEEX_SET_QUALITY* Set the encoder speech quality (integer 0 to 10)
-\end_layout
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
 
-\begin_layout Description
-SPEEX_GET_QUALITY* Get the current encoder speech quality (integer 0 to
- 10)
+\begin_layout Plain Layout
+
+SpeexEchoState *echo_state = speex_echo_state_init(frame_size, filter_length);
 \end_layout
 
-\begin_layout Description
-SPEEX_SET_MODE*
-\begin_inset Formula $\dagger$
 \end_inset
 
 
 \end_layout
 
-\begin_layout Description
-SPEEX_GET_MODE*
-\begin_inset Formula $\dagger$
-\end_inset
+\begin_layout Standard
+where 
+\family typewriter
+frame_size
+\family default
+ is the amount of data (in samples) you want to process at once and 
+\family typewriter
+filter_length
+\family default
+ is the length (in samples) of the echo cancelling filter you want to use
+ (also known as 
+\shape italic
+tail length
+\shape default
 
+\begin_inset Index
+status collapsed
 
+\begin_layout Plain Layout
+tail length
 \end_layout
 
-\begin_layout Description
-SPEEX_SET_LOW_MODE*
-\begin_inset Formula $\dagger$
 \end_inset
 
+).
+ 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).
+\end_layout
 
+\begin_layout Standard
+Once the echo canceller state is created, audio can be processed by:
 \end_layout
 
-\begin_layout Description
-SPEEX_GET_LOW_MODE*
-\begin_inset Formula $\dagger$
-\end_inset
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
 
+\begin_layout Plain Layout
 
+speex_echo_cancellation(echo_state, input_frame, echo_frame, output_frame);
 \end_layout
 
-\begin_layout Description
-SPEEX_SET_HIGH_MODE*
-\begin_inset Formula $\dagger$
 \end_inset
 
 
 \end_layout
 
-\begin_layout Description
-SPEEX_GET_HIGH_MODE*
-\begin_inset Formula $\dagger$
-\end_inset
+\begin_layout Standard
+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.
+\end_layout
+
+\begin_layout Standard
+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:
+\begin_inset listings
+lstparams "breaklines=true"
+inline false
+status open
 
+\begin_layout Plain Layout
 
+write_to_soundcard(echo_frame, frame_size);
 \end_layout
 
-\begin_layout Description
-SPEEX_SET_VBR* Set variable bit-rate (VBR) to on (1) or off (0) (integer)
+\begin_layout Plain Layout
+
+read_from_soundcard(input_frame, frame_size);
 \end_layout
 
-\begin_layout Description
-SPEEX_GET_VBR* Get variable bit-rate
-\begin_inset LatexCommand \index{variable bit-rate}
+\begin_layout Plain Layout
+
+speex_echo_cancellation(echo_state, input_frame, echo_frame, output_frame);
+\end_layout
 
 \end_inset
 
- (VBR) status (integer)
-\end_layout
 
-\begin_layout Description
-SPEEX_SET_VBR_QUALITY* Set the encoder VBR speech quality (float 0 to 10)
 \end_layout
 
-\begin_layout Description
-SPEEX_GET_VBR_QUALITY* Get the current encoder VBR speech quality (float
- 0 to 10)
-\end_layout
+\begin_layout Standard
+If you wish to further reduce the echo present in the signal, you can do
+ so by associating the echo canceller to the preprocessor (see Section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sub:Preprocessor"
 
-\begin_layout Description
-SPEEX_SET_COMPLEXITY* Set the CPU resources allowed for the encoder (integer
- 1 to 10)
-\end_layout
+\end_inset
 
-\begin_layout Description
-SPEEX_GET_COMPLEXITY* Get the CPU resources allowed for the encoder (integer
- 1 to 10)
-\end_layout
+).
+ This is done by calling:
+\begin_inset listings
+lstparams "breaklines=true"
+inline false
+status open
 
-\begin_layout Description
-SPEEX_SET_BITRATE* Set the bit-rate to use to the closest value not exceeding
- the parameter (integer in bps)
-\end_layout
+\begin_layout Plain Layout
 
-\begin_layout Description
-SPEEX_GET_BITRATE Get the current bit-rate in use (integer in bps)
+speex_preprocess_ctl(preprocess_state, SPEEX_PREPROCESS_SET_ECHO_STATE,echo_stat
+e);
 \end_layout
 
-\begin_layout Description
-SPEEX_SET_SAMPLING_RATE Set real sampling rate (integer in Hz)
-\end_layout
+\end_inset
 
-\begin_layout Description
-SPEEX_GET_SAMPLING_RATE Get real sampling rate (integer in Hz)
+in the initialisation.
 \end_layout
 
-\begin_layout Description
-SPEEX_RESET_STATE Reset the encoder/decoder state to its original state
- (zeros all memories)
+\begin_layout Standard
+As of version 1.2-beta2, there is an alternative, simpler API that can be
+ used instead of 
+\emph on
+speex_echo_cancellation()
+\emph default
+.
+ When audio capture and playback are handled asynchronously (e.g.
+ in different threads or using the 
+\emph on
+poll()
+\emph default
+ or 
+\emph on
+select()
+\emph default
+ system call), it can be difficult to keep track of what input_frame comes
+ with what echo_frame.
+ Instead, the playback context/thread can simply call:
 \end_layout
 
-\begin_layout Description
-SPEEX_SET_VAD* Set voice activity detection
-\begin_inset LatexCommand \index{voice activity detection}
-
-\end_inset
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
 
- (VAD) to on (1) or off (0) (integer)
-\end_layout
+\begin_layout Plain Layout
 
-\begin_layout Description
-SPEEX_GET_VAD* Get voice activity detection (VAD) status (integer)
+speex_echo_playback(echo_state, echo_frame);
 \end_layout
 
-\begin_layout Description
-SPEEX_SET_DTX* Set discontinuous transmission
-\begin_inset LatexCommand \index{discontinuous transmission}
-
 \end_inset
 
- (DTX) to on (1) or off (0) (integer)
+
 \end_layout
 
-\begin_layout Description
-SPEEX_GET_DTX* Get discontinuous transmission (DTX) status (integer)
+\begin_layout Standard
+every time an audio frame is played.
+ Then, the capture context/thread calls:
 \end_layout
 
-\begin_layout Description
-SPEEX_SET_ABR* Set average bit-rate
-\begin_inset LatexCommand \index{average bit-rate}
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
 
-\end_inset
+\begin_layout Plain Layout
 
- (ABR) to a value n in bits per second (integer in bps)
+speex_echo_capture(echo_state, input_frame, output_frame);
 \end_layout
 
-\begin_layout Description
-SPEEX_GET_ABR* Get average bit-rate (ABR) setting (integer in bps)
-\end_layout
+\end_inset
 
-\begin_layout Description
-SPEEX_SET_PLC_TUNING* Tell the encoder to optimize encoding for a certain
- percentage of packet loss (integer in percent)
-\end_layout
 
-\begin_layout Description
-SPEEX_GET_PLC_TUNING* Get the current tuning of the encoder for PLC (integer
- in percent)
 \end_layout
 
-\begin_layout Description
-* applies only to the encoder
+\begin_layout Standard
+for every frame captured.
+ Internally, 
+\emph on
+speex_echo_playback()
+\emph default
+ simply buffers the playback frame so it can be used by 
+\emph on
+speex_echo_capture()
+\emph default
+ to call 
+\emph on
+speex_echo_cancel()
+\emph default
+.
+ A side effect of using this alternate API is that the playback audio is
+ delayed by two frames, which is the normal delay caused by the soundcard.
+ When capture and playback are already synchronised, 
+\emph on
+speex_echo_cancellation()
+\emph default
+ is preferable since it gives better control on the exact input/echo timing.
 \end_layout
 
-\begin_layout Description
-** applies only to the decoder
+\begin_layout Standard
+The echo cancellation state can be destroyed with:
 \end_layout
 
-\begin_layout Description
-\begin_inset Formula $\dagger$
-\end_inset
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
 
- normally only used internally
-\end_layout
+\begin_layout Plain Layout
 
-\begin_layout Section
-Mode queries
-\begin_inset LatexCommand \label{sub:Mode-queries}
+speex_echo_state_destroy(echo_state);
+\end_layout
 
 \end_inset
 
@@ -2080,782 +4725,794 @@ Mode queries
 \end_layout
 
 \begin_layout Standard
-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:
-\end_layout
-
-\begin_layout LyX-Code
-void speex_mode_query(SpeexMode *mode, int request, void *ptr);
+It is also possible to reset the state of the echo canceller so it can be
+ reused without the need to create another state with:
 \end_layout
 
 \begin_layout Standard
-The admissible values for request are (unless otherwise note, the values
- are returned through 
-\emph on
-ptr
-\emph default
-):
-\end_layout
+\begin_inset listings
+inline false
+status open
 
-\begin_layout Description
-SPEEX_MODE_FRAME_SIZE Get the frame size (in samples) for the mode
-\end_layout
+\begin_layout Plain Layout
 
-\begin_layout Description
-SPEEX_SUBMODE_BITRATE Get the bit-rate for a submode number specified through
-\emph on
-ptr
-\emph default
- (integer in bps).
+speex_echo_state_reset(echo_state);
 \end_layout
 
-\begin_layout Section
-Preprocessor options
-\begin_inset LatexCommand \label{sub:Preprocessor-options}
-
 \end_inset
 
 
 \end_layout
 
-\begin_layout Description
-SPEEX_PREPROCESS_SET_DENOISE Turns denoising on(1) or off(2) (integer)
+\begin_layout Subsection
+Troubleshooting
 \end_layout
 
-\begin_layout Description
-SPEEX_PREPROCESS_GET_DENOISE Get denoising status (integer)
+\begin_layout Standard
+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
 \end_layout
 
-\begin_layout Description
-SPEEX_PREPROCESS_SET_AGC Turns automatic gain control (AGC) on(1) or off(2)
- (integer)
-\end_layout
+\begin_layout Itemize
+Using a different soundcard to do the capture and plaback will 
+\series bold
+not
+\series default
+ 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
 
-\begin_layout Description
-SPEEX_PREPROCESS_GET_AGC Get AGC status (integer)
-\end_layout
+locked
+\begin_inset Quotes erd
+\end_inset
 
-\begin_layout Description
-SPEEX_PREPROCESS_SET_VAD Turns voice activity detector (VAD) on(1) or off(2)
- (integer)
+ on the same clock source.
+ If not, the clocks will always have a small amount of drift, which will
+ prevent the echo canceller from adapting.
 \end_layout
 
-\begin_layout Description
-SPEEX_PREPROCESS_GET_VAD Get VAD status (integer)
-\end_layout
+\begin_layout Itemize
+The delay between the record and playback signals must be minimal.
+ Any signal played has to 
+\begin_inset Quotes eld
+\end_inset
 
-\begin_layout Description
-SPEEX_PREPROCESS_SET_AGC_LEVEL
-\end_layout
+appear
+\begin_inset Quotes erd
+\end_inset
 
-\begin_layout Description
-SPEEX_PREPROCESS_GET_AGC_LEVEL
-\end_layout
+ on the playback (far end) signal slightly before the echo canceller 
+\begin_inset Quotes eld
+\end_inset
 
-\begin_layout Description
-SPEEX_PREPROCESS_SET_DEREVERB Turns reverberation removal on(1) or off(2)
- (integer)
-\end_layout
+sees
+\begin_inset Quotes erd
+\end_inset
 
-\begin_layout Description
-SPEEX_PREPROCESS_GET_DEREVERB Get reverberation removal status (integer)
+ 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.
 \end_layout
 
-\begin_layout Description
-SPEEX_PREPROCESS_SET_DEREVERB_LEVEL
+\begin_layout Itemize
+When it comes to echo tail length (filter length), longer is 
+\series bold
+not
+\series default
+ 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.
 \end_layout
 
-\begin_layout Description
-SPEEX_PREPROCESS_GET_DEREVERB_LEVEL
+\begin_layout Itemize
+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.
 \end_layout
 
-\begin_layout Description
-SPEEX_PREPROCESS_SET_DEREVERB_DECAY
-\end_layout
+\begin_layout Standard
+Also useful is reading 
+\emph on
+Echo Cancellation Demystified
+\emph default
+ by Alexey Frunze
+\begin_inset Foot
+status collapsed
 
-\begin_layout Description
-SPEEX_PREPROCESS_GET_DEREVERB_DECAY
+\begin_layout Plain Layout
+http://www.embeddedstar.com/articles/2003/7/article20030720-1.html
 \end_layout
 
-\begin_layout Description
-SPEEX_PREPROCESS_SET_PROB_START
-\end_layout
+\end_inset
 
-\begin_layout Description
-SPEEX_PREPROCESS_GET_PROB_START
+, which explains the fundamental principles of echo cancellation.
+ The details of the algorithm described in the article are different, but
+ the general ideas of echo cancellation through adaptive filters are the
+ same.
 \end_layout
 
-\begin_layout Description
-SPEEX_PREPROCESS_SET_PROB_CONTINUE
+\begin_layout Standard
+As of version 1.2beta2, a new 
+\family typewriter
+echo_diagnostic.m
+\family default
+ tool is included in the source distribution.
+ The first step is to define DUMP_ECHO_CANCEL_DATA during the build.
+ This causes the echo canceller to automatically save the near-end, far-end
+ and output signals to files (aec_rec.sw aec_play.sw and aec_out.sw).
+ These are exactly what the AEC receives and outputs.
+ From there, it is necessary to start Octave and type:
 \end_layout
 
-\begin_layout Description
-SPEEX_PREPROCESS_GET_PROB_CONTINUE
-\end_layout
+\begin_layout Standard
+\begin_inset listings
+lstparams "language=Matlab"
+inline false
+status open
 
-\begin_layout Description
-SPEEX_PREPROCESS_SET_NOISE_SUPPRESS Set maximum attenuation of the noise
- in dB (negative number)
-\end_layout
+\begin_layout Plain Layout
 
-\begin_layout Description
-SPEEX_PREPROCESS_GET_NOISE_SUPPRESS Get maximum attenuation of the noise
- in dB (negative number)
+echo_diagnostic('aec_rec.sw', 'aec_play.sw', 'aec_diagnostic.sw', 1024);
 \end_layout
 
-\begin_layout Description
-SPEEX_PREPROCESS_SET_ECHO_SUPPRESS Set maximum attenuation of the residual
- echo in dB (negative number)
-\end_layout
+\end_inset
 
-\begin_layout Description
-SPEEX_PREPROCESS_GET_ECHO_SUPPRESS Set maximum attenuation of the residual
- echo in dB (negative number)
-\end_layout
 
-\begin_layout Description
-SPEEX_PREPROCESS_SET_ECHO_SUPPRESS_ACTIVE Set maximum attenuation of the
- echo in dB when near end is active (negative number)
 \end_layout
 
-\begin_layout Description
-SPEEX_PREPROCESS_GET_ECHO_SUPPRESS_ACTIVE Set maximum attenuation of the
- echo in dB when near end is active (negative number)
+\begin_layout Standard
+The value of 1024 is the filter length and can be changed.
+ There will be some (hopefully) useful messages printed and echo cancelled
+ audio will be saved to aec_diagnostic.sw .
+ If even that output is bad (almost no cancellation) then there is  probably
+ problem with the playback or recording process.
 \end_layout
 
-\begin_layout Description
-SPEEX_PREPROCESS_SET_ECHO_STATE Set the associated echo canceller for residual
- echo suppression (NULL for no residual echo suppression)
+\begin_layout Section
+Jitter Buffer
 \end_layout
 
-\begin_layout Description
-SPEEX_PREPROCESS_GET_ECHO_STATE Get the associated echo canceller
-\end_layout
+\begin_layout Standard
+The jitter buffer can be enabled by including:
+\begin_inset listings
+lstparams "breaklines=true"
+inline false
+status open
 
-\begin_layout Section
-Packing and in-band signalling
-\begin_inset LatexCommand \index{in-band signalling}
+\begin_layout Plain Layout
 
-\end_inset
+#include <speex/speex_jitter.h>
+\end_layout
 
+\end_inset
 
+ and a new jitter buffer state can be initialised by:
 \end_layout
 
 \begin_layout Standard
-Sometimes it is desirable to pack more than one frame per packet (or other
- basic unit of storage).
- The proper way to do it is to call speex_encode 
-\begin_inset Formula $N$
-\end_inset
-
- times before writing the stream with speex_bits_write.
- In cases where the number of frames is not determined by an out-of-band
- mechanism, it is possible to include a terminator code.
- That terminator consists of the code 15 (decimal) encoded with 5 bits,
- as shown in Table 
-\begin_inset LatexCommand \ref{cap:quality_vs_bps}
+\begin_inset listings
+lstparams "breaklines=true"
+inline false
+status open
 
-\end_inset
+\begin_layout Plain Layout
 
-.
- 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.
+JitterBuffer *state = jitter_buffer_init(step);
 \end_layout
 
-\begin_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
+\end_layout
 
-pseudo-frames
-\begin_inset Quotes erd
-\end_inset
+\begin_layout Standard
+where the 
+\begin_inset listings
+inline true
+status collapsed
 
- 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}
+\begin_layout Plain Layout
+
+step
+\end_layout
 
 \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.
+ argument is the default time step (in timestamp units) used for adjusting
+ the delay and doing concealment.
+ A value of 1 is always correct, but higher values may be more convenient
+ sometimes.
+ For example, if you are only able to do concealment on 20ms frames, there
+ is no point in the jitter buffer asking you to do it on one sample.
+ Another example is that for video, it makes no sense to adjust the delay
+ by less than a full frame.
+ The value provided can always be changed at a later time.
 \end_layout
 
 \begin_layout Standard
-\begin_inset Float table
-placement htbp
-wide false
-sideways false
+The jitter buffer API is based on the 
+\begin_inset listings
+inline true
 status open
 
-\begin_layout Standard
-\begin_inset Tabular
-<lyxtabular version="3" rows="17" columns="3">
-<features>
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_layout Plain Layout
 
-\begin_layout Standard
-Code
+JitterBufferPacket
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-Size (bits)
-\end_layout
+ type, which is defined as:
+\begin_inset listings
+inline false
+status open
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\begin_layout Plain Layout
 
-\begin_layout Standard
-Content
+typedef struct {
 \end_layout
 
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_layout Plain Layout
 
-\begin_layout Standard
-0
+   char        *data;       /* Data bytes contained in the packet */
 \end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_layout Plain Layout
 
-\begin_layout Standard
-1
+   spx_uint32_t len;        /* Length of the packet in bytes */
 \end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\begin_layout Plain Layout
 
-\begin_layout Standard
-Asks decoder to set perceptual enhancement off (0) or on(1)
+   spx_uint32_t timestamp;  /* Timestamp for the packet */
 \end_layout
 
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_layout Plain Layout
 
-\begin_layout Standard
-1
+   spx_uint32_t span;       /* Time covered by the packet (timestamp units)
+ */
 \end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_layout Plain Layout
 
-\begin_layout Standard
-1
+} JitterBufferPacket; 
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Standard
-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_layout
 
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
 \begin_layout Standard
-2
+As an example, for audio the timestamp field would be what is obtained from
+ the RTP timestamp field and the span would be the number of samples that
+ are encoded in the packet.
+ For Speex narrowband, span would be 160 if only one frame is included in
+ the packet.
 \end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
 \begin_layout Standard
-4
-\end_layout
+When a packet arrives, it need to be inserter into the jitter buffer by:
+\begin_inset listings
+inline false
+status open
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\begin_layout Plain Layout
 
-\begin_layout Standard
-Asks encoder to switch to mode N
+JitterBufferPacket packet;
 \end_layout
 
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_layout Plain Layout
 
-\begin_layout Standard
-3
+/* Fill in each field in the packet struct */
 \end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_layout Plain Layout
 
-\begin_layout Standard
-4
+jitter_buffer_put(state, &packet);
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-Asks encoder to switch to mode N for low-band
-\end_layout
 
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\end_layout
 
 \begin_layout Standard
-4
-\end_layout
+When the decoder is ready to decode a packet the packet to be decoded can
+ be obtained by: 
+\begin_inset listings
+inline false
+status open
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_layout Plain Layout
 
-\begin_layout Standard
-4
+int start_offset;
 \end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\begin_layout Plain Layout
 
-\begin_layout Standard
-Asks encoder to switch to mode N for high-band
+err = jitter_buffer_get(state, &packet, desired_span, &start_offset);
 \end_layout
 
 \end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-5
-\end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\end_layout
 
 \begin_layout Standard
-4
-\end_layout
+If 
+\begin_inset listings
+inline true
+status open
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\begin_layout Plain Layout
 
-\begin_layout Standard
-Asks encoder to switch to quality N for VBR
+jitter_buffer_put()
 \end_layout
 
 \end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-6
-\end_layout
+ and 
+\begin_inset listings
+inline true
+status collapsed
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_layout Plain Layout
 
-\begin_layout Standard
-4
+jitter_buffer_get()
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+
+ are called from different threads, then 
+\series bold
+you need to protect the jitter buffer state with a mutex
+\series default
+.
+\end_layout
 
 \begin_layout Standard
-Request acknowloedge (0=no, 1=all, 2=only for in-band data)
-\end_layout
+Because the jitter buffer is designed not to use an explicit timer, it needs
+ to be told about the time explicitly.
+ This is done by calling: 
+\begin_inset listings
+inline false
+status open
 
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_layout Plain Layout
 
-\begin_layout Standard
-7
+jitter_buffer_tick(state);
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-4
-\end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\end_layout
 
 \begin_layout Standard
-Asks encoder to set CBR (0), VAD(1), DTX(3), VBR(5), VBR+DTX(7)
+This needs to be done periodically in the playing thread.
+ This will be the last jitter buffer call before going to sleep (until more
+ data is played back).
+ In some cases, it may be preferable to use 
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+jitter_buffer_remaining_span(state, remaining);
 \end_layout
 
 \end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
+
+\end_layout
 
 \begin_layout Standard
-8
+The second argument is used to specify that we are still holding data that
+ has not been written to the playback device.
+ For instance, if 256 samples were needed by the soundcard (specified by
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+desired_span
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-8
+), but 
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+jitter_buffer_get()
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-Transmit (8-bit) character to the other end
+ returned 320 samples, we would have 
+\begin_inset listings
+inline true
+status open
+
+\begin_layout Plain Layout
+
+remaining=64
 \end_layout
 
 \end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-9
+.
 \end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_layout Section
+Resampler
+\end_layout
 
 \begin_layout Standard
-8
+Speex includes a resampling modules.
+ To make use of the resampler, it is necessary to include its header file:
 \end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
 \begin_layout Standard
-Intensity stereo information
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+#include <speex/speex_resampler.h>
 \end_layout
 
 \end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-10
+
 \end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_layout Standard
+For each stream that is to be resampled, it is necessary to create a resampler
+ state with:
+\end_layout
 
 \begin_layout Standard
-16
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+SpeexResamplerState *resampler;
 \end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\begin_layout Plain Layout
 
-\begin_layout Standard
-Announce maximum bit-rate acceptable (N in bytes/second)
+resampler = speex_resampler_init(nb_channels, input_rate, output_rate, quality,
+ &err);
 \end_layout
 
 \end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
+
+\end_layout
 
 \begin_layout Standard
-11
+where 
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+nb_channels
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-16
+ is the number of channels that will be used (either interleaved or non-interlea
+ved), 
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+input_rate
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-reserved
+ is the sampling rate of the input stream, 
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+output_rate
 \end_layout
 
 \end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-12
+ is the sampling rate of the output stream and 
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+quality
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-32
+ is the requested quality setting (0 to 10).
+ The quality parameter is useful for controlling the quality/complexity/latency
+ tradeoff.
+ Using a higher quality setting means less noise/aliasing, a higher complexity
+ and a higher latency.
+ Usually, a quality of 3 is acceptable for most desktop uses and quality
+ 10 is mostly recommended for pro audio work.
+ Quality 0 usually has a decent sound (certainly better than using linear
+ interpolation resampling), but artifacts may be heard.
 \end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\begin_layout Standard
+The actual resampling is performed using
+\end_layout
 
 \begin_layout Standard
-Acknowledge receiving packet N
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+err = speex_resampler_process_int(resampler, channelID, in, &in_length,
+ out, &out_length);
 \end_layout
 
 \end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-13
+where 
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+channelID
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-32
+ is the ID of the channel to be processed.
+ For a mono stream, use 0.
+ The 
+\emph on
+in
+\emph default
+ pointer points to the first sample of the input buffer for the selected
+ channel and 
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+out
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-reserved
+ points to the first sample of the output.
+ The size of the input and output buffers are specified by 
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+in_length
 \end_layout
 
 \end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-14
+ and 
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+out_length
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-64
+ respectively.
+ Upon completion, these values are replaced by the number of samples read
+ and written by the resampler.
+ Unless an error occurs, either all input samples will be read or all output
+ samples will be written to (or both).
+ For floating-point samples, the function 
+\begin_inset listings
+inline true
+status open
+
+\begin_layout Plain Layout
+
+speex_resampler_process_float()
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+
+ behaves similarly.
+\end_layout
 
 \begin_layout Standard
-reserved
+It is also possible to process multiple channels at once.
+ To do that, you can use speex_resampler_process_interleaved_int() or 
+\begin_inset listings
+inline true
+status open
+
+\begin_layout Plain Layout
+
+speex_resampler_process_interleaved_float()
 \end_layout
 
 \end_inset
-</cell>
-</row>
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-15
+.
+ The arguments are the same except that there is no 
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+channelID
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
+ argument.
+ Note that the 
+\series bold
+length parameters are per-channel
+\series default
+.
+ So if you have 1024 samples for each of 4 channels, you pass 1024 and not
+ 4096.
+\end_layout
 
 \begin_layout Standard
-64
+The resampler allows changing the quality and input/output sampling frequencies
+ on the fly without glitches.
+ This can be done with calls such as 
+\begin_inset listings
+inline true
+status open
+
+\begin_layout Plain Layout
+
+speex_resampler_set_quality()
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-reserved
+ and 
+\begin_inset listings
+inline true
+status open
+
+\begin_layout Plain Layout
+
+speex_resampler_set_rate()
 \end_layout
 
 \end_inset
-</cell>
-</row>
-</lyxtabular>
 
-\end_inset
+.
+ The only side effect is that a new filter will have to be recomputed, consuming
+ many CPU cycles.
+\end_layout
+
+\begin_layout Standard
+When resampling a file, it is often desirable to have the output file perfectly
+ synchronised with the input.
+ To do that, you need to call 
+\begin_inset listings
+inline true
+status open
 
+\begin_layout Plain Layout
 
+speex_resampler_skip_zeros()
 \end_layout
 
-\begin_layout Caption
-In-band signalling codes
-\begin_inset LatexCommand \label{cap:In-band-signalling-codes}
-
 \end_inset
 
+\series bold
+before
+\series default
+ you start processing any samples.
+ For real-time applications (e.g.
+ VoIP), it is not recommended to do that as the first process frame will
+ be shorter to compensate for the delay (the skipped zeros).
+ To destroy a resampler state, just call 
+\begin_inset listings
+inline true
+status open
+
+\begin_layout Plain Layout
 
+speex_resampler_destroy()
 \end_layout
 
 \end_inset
 
+.
+\end_layout
 
+\begin_layout Section
+Ring Buffer
 \end_layout
 
 \begin_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.
+In some cases, it is necessary to interface components that use different
+ block sizes.
+ For example, it is possible that the soundcard does not support reading/writing
+ in blocks of 20
+\begin_inset space ~
+\end_inset
+
+ms or sometimes, complicated resampling ratios mean that the blocks don't
+ always have the same time.
+ In thoses cases, it is often necessary to buffer a bit of audio using a
+ ring buffer.
 \end_layout
 
 \begin_layout Standard
+\begin_inset Newpage newpage
+\end_inset
 
-\newpage
 
 \end_layout
 
 \begin_layout Chapter
 Formats and standards
-\begin_inset LatexCommand \index{standards}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+standards
+\end_layout
 
 \end_inset
 
 
-\begin_inset LatexCommand \label{sec:Formats-and-standards}
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Formats-and-standards"
 
 \end_inset
 
@@ -2886,7 +5543,7 @@ At the minimum, all narrowband modes of operation MUST be supported at the
 \begin_inset Foot
 status collapsed
 
-\begin_layout Standard
+\begin_layout Plain Layout
 The wideband bit-stream contains an embedded narrowband bit-stream which
  can be decoded alone
 \end_layout
@@ -2909,7 +5566,12 @@ For encoders, at least one narrowband or wideband mode MUST be supported.
 
 \begin_layout Section
 RTP
-\begin_inset LatexCommand \index{RTP}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+RTP
+\end_layout
 
 \end_inset
 
@@ -2918,12 +5580,20 @@ RTP
 
 \begin_layout Standard
 The RTP payload draft is included in appendix 
-\begin_inset LatexCommand \ref{sec:IETF-draft}
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:IETF-draft"
 
 \end_inset
 
  and the latest version is available at 
-\begin_inset LatexCommand \url{http://www.speex.org/drafts/latest}
+\begin_inset Flex URL
+status collapsed
+
+\begin_layout Plain Layout
+
+http://www.speex.org/drafts/latest
+\end_layout
 
 \end_inset
 
@@ -2948,7 +5618,12 @@ audio/speex
 
 \begin_layout Section
 Ogg
-\begin_inset LatexCommand \index{Ogg}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+Ogg
+\end_layout
 
 \end_inset
 
@@ -2959,7 +5634,9 @@ Ogg
 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}
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "cap:ogg_speex_header"
 
 \end_inset
 
@@ -2977,9 +5654,18 @@ speex_string
 \family typewriter
 Speex
 \family default
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
+
+\begin_inset space ~
+\end_inset
+
+
+\begin_inset space ~
+\end_inset
+
+
+\begin_inset space ~
+\end_inset
+
 
 \begin_inset Quotes erd
 \end_inset
@@ -3056,11 +5742,11 @@ wide true
 sideways false
 status open
 
-\begin_layout Standard
+\begin_layout Plain Layout
 \begin_inset ERT
 status collapsed
 
-\begin_layout Standard
+\begin_layout Plain Layout
 
 
 \backslash
@@ -3073,43 +5759,43 @@ begin{center}
 \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">
+<column alignment="center" valignment="top" width="0pt">
+<column alignment="center" valignment="top" width="0pt">
+<column alignment="center" valignment="top" width="0pt">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 Field
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 Type
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 Size
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 speex_string
 \end_layout
 
@@ -3118,7 +5804,7 @@ speex_string
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 char[]
 \end_layout
 
@@ -3127,18 +5813,18 @@ char[]
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 8
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 speex_version
 \end_layout
 
@@ -3147,7 +5833,7 @@ speex_version
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 char[]
 \end_layout
 
@@ -3156,18 +5842,18 @@ char[]
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 20
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 speex_version_id
 \end_layout
 
@@ -3176,7 +5862,7 @@ speex_version_id
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 int
 \end_layout
 
@@ -3185,18 +5871,18 @@ int
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 4
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 header_size
 \end_layout
 
@@ -3205,7 +5891,7 @@ header_size
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 int
 \end_layout
 
@@ -3214,18 +5900,18 @@ int
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 4
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 rate
 \end_layout
 
@@ -3234,7 +5920,7 @@ rate
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 int
 \end_layout
 
@@ -3243,18 +5929,18 @@ int
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 4
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 mode
 \end_layout
 
@@ -3263,7 +5949,7 @@ mode
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 int
 \end_layout
 
@@ -3272,18 +5958,18 @@ int
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 4
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 mode_bitstream_version
 \end_layout
 
@@ -3292,7 +5978,7 @@ mode_bitstream_version
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 int
 \end_layout
 
@@ -3301,18 +5987,18 @@ int
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 4
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 nb_channels
 \end_layout
 
@@ -3321,7 +6007,7 @@ nb_channels
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 int
 \end_layout
 
@@ -3330,18 +6016,18 @@ int
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 4
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 bitrate
 \end_layout
 
@@ -3350,7 +6036,7 @@ bitrate
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 int
 \end_layout
 
@@ -3359,18 +6045,18 @@ int
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 4
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 frame_size
 \end_layout
 
@@ -3379,7 +6065,7 @@ frame_size
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 int
 \end_layout
 
@@ -3388,18 +6074,18 @@ int
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 4
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 vbr
 \end_layout
 
@@ -3408,7 +6094,7 @@ vbr
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 int
 \end_layout
 
@@ -3417,18 +6103,18 @@ int
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 4
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 frames_per_packet
 \end_layout
 
@@ -3437,7 +6123,7 @@ frames_per_packet
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 int
 \end_layout
 
@@ -3446,18 +6132,18 @@ int
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 4
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 extra_headers
 \end_layout
 
@@ -3466,7 +6152,7 @@ extra_headers
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 int
 \end_layout
 
@@ -3475,18 +6161,18 @@ int
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 4
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 reserved1
 \end_layout
 
@@ -3495,7 +6181,7 @@ reserved1
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 int
 \end_layout
 
@@ -3504,36 +6190,36 @@ int
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 4
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 reserved2
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 int
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 4
 \end_layout
 
@@ -3548,7 +6234,7 @@ int
 \begin_inset ERT
 status collapsed
 
-\begin_layout Standard
+\begin_layout Plain Layout
 
 
 \backslash
@@ -3560,9 +6246,19 @@ end{center}
 
 \end_layout
 
-\begin_layout Caption
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
 Ogg/Speex header packet
-\begin_inset LatexCommand \label{cap:ogg_speex_header}
+\begin_inset CommandInset label
+LatexCommand label
+name "cap:ogg_speex_header"
+
+\end_inset
+
+
+\end_layout
 
 \end_inset
 
@@ -3578,7 +6274,7 @@ Ogg/Speex header packet
 \begin_inset ERT
 status collapsed
 
-\begin_layout Standard
+\begin_layout Plain Layout
 
 
 \backslash
@@ -3592,12 +6288,19 @@ clearpage
 
 \begin_layout Chapter
 Introduction to CELP Coding
-\begin_inset LatexCommand \index{CELP}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+CELP
+\end_layout
 
 \end_inset
 
 
-\begin_inset LatexCommand \label{sec:Introduction-to-CELP}
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Introduction-to-CELP"
 
 \end_inset
 
@@ -3616,7 +6319,9 @@ Do not meddle in the affairs of poles, for they are subtle and quick to
 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}
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Speex-narrowband-mode"
 
 \end_inset
 
@@ -3678,7 +6383,9 @@ The source-filter model of speech production assumes that the vocal cords
 The source-filter model is usually tied with the use of Linear prediction.
  The CELP model is based on source-filter model, as can be seen from the
  CELP decoder illustrated in Figure 
-\begin_inset LatexCommand \ref{fig:The-CELP-model}
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "fig:The-CELP-model"
 
 \end_inset
 
@@ -3692,11 +6399,11 @@ wide false
 sideways false
 status open
 
-\begin_layout Standard
+\begin_layout Plain Layout
 \begin_inset ERT
 status collapsed
 
-\begin_layout Standard
+\begin_layout Plain Layout
 
 
 \backslash
@@ -3717,7 +6424,7 @@ begin{center}
 \begin_inset ERT
 status collapsed
 
-\begin_layout Standard
+\begin_layout Plain Layout
 
 
 \backslash
@@ -3729,9 +6436,14 @@ end{center}
 
 \end_layout
 
-\begin_layout Caption
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
 The CELP model of speech synthesis (decoder)
-\begin_inset LatexCommand \label{fig:The-CELP-model}
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:The-CELP-model"
 
 \end_inset
 
@@ -3743,9 +6455,19 @@ The CELP model of speech synthesis (decoder)
 
 \end_layout
 
+\end_inset
+
+
+\end_layout
+
 \begin_layout Section
-Linear Prediction (LPC)
-\begin_inset LatexCommand \index{linear prediction}
+Linear Prediction Coefficients (LPC)
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+linear prediction
+\end_layout
 
 \end_inset
 
@@ -3853,7 +6575,12 @@ with
 \end_inset
 
 , the auto-correlation
-\begin_inset LatexCommand \index{auto-correlation}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+auto-correlation
+\end_layout
 
 \end_inset
 
@@ -3878,8 +6605,13 @@ Because
 \begin_inset Formula $\mathbf{R}$
 \end_inset
 
- is toeplitz hermitian, the Levinson-Durbin
-\begin_inset LatexCommand \index{Levinson-Durbin}
+ is Hermitian Toeplitz, the Levinson-Durbin
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+Levinson-Durbin
+\end_layout
 
 \end_inset
 
@@ -3915,7 +6647,12 @@ Because
 
 \begin_layout Section
 Pitch Prediction
-\begin_inset LatexCommand \index{pitch}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+pitch
+\end_layout
 
 \end_inset
 
@@ -3934,14 +6671,10 @@ During voiced segments, the speech signal is periodic, so it is possible
 
 \begin_layout Standard
 \begin_inset Formula \[
-e[n]\simeq p[n]=\beta e[n-T]\]
+e[n]\simeq p[n]=\beta e[n-T]\ ,\]
 
 \end_inset
 
-
-\end_layout
-
-\begin_layout Standard
 where 
 \begin_inset Formula $T$
 \end_inset
@@ -3985,12 +6718,12 @@ innovation
 Code
 \emph default
  Excited Linear Prediction.
- The final excitation is given by:
+ The final excitation is given by
 \end_layout
 
 \begin_layout Standard
 \begin_inset Formula \[
-e[n]=p[n]+c[n]=\beta e[n-T]+c[n]\]
+e[n]=p[n]+c[n]=\beta e[n-T]+c[n]\ .\]
 
 \end_inset
 
@@ -4009,7 +6742,7 @@ z
 \begin_inset Formula $X(z)$
 \end_inset
 
- as 
+ as
 \begin_inset Formula \[
 X(z)=\frac{C(z)}{A(z)\left(1-\beta z^{-T}\right)}\]
 
@@ -4020,12 +6753,22 @@ X(z)=\frac{C(z)}{A(z)\left(1-\beta z^{-T}\right)}\]
 
 \begin_layout Section
 Noise Weighting
-\begin_inset LatexCommand \index{error weighting}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+error weighting
+\end_layout
 
 \end_inset
 
 
-\begin_inset LatexCommand \index{analysis-by-synthesis}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+analysis-by-synthesis
+\end_layout
 
 \end_inset
 
@@ -4066,9 +6809,9 @@ vice versa
 \begin_inset Formula $1/A(z)$
 \end_inset
 
-, CELP codecs typically derive the noise weighting filter as: 
+, CELP codecs typically derive the noise weighting filter as 
 \begin_inset Formula \begin{equation}
-W(z)=\frac{A(z/\gamma_{1})}{A(z/\gamma_{2})}\label{eq:gamma-weighting}\end{equation}
+W(z)=\frac{A(z/\gamma_{1})}{A(z/\gamma_{2})}\ ,\label{eq:gamma-weighting}\end{equation}
 
 \end_inset
 
@@ -4125,13 +6868,17 @@ The weighting filter is applied to the error signal used to optimize the
  function.
  Fig.
  
-\begin_inset LatexCommand \ref{cap:Standard-noise-shaping}
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "cap:Standard-noise-shaping"
 
 \end_inset
 
  illustrates the noise shaping that results from Eq.
  
-\begin_inset LatexCommand \ref{eq:gamma-weighting}
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "eq:gamma-weighting"
 
 \end_inset
 
@@ -4153,11 +6900,11 @@ wide false
 sideways false
 status open
 
-\begin_layout Standard
+\begin_layout Plain Layout
 \begin_inset ERT
 status collapsed
 
-\begin_layout Standard
+\begin_layout Plain Layout
 
 
 \backslash
@@ -4178,7 +6925,7 @@ begin{center}
 \begin_inset ERT
 status collapsed
 
-\begin_layout Standard
+\begin_layout Plain Layout
 
 
 \backslash
@@ -4190,10 +6937,20 @@ end{center}
 
 \end_layout
 
-\begin_layout Caption
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
 Standard noise shaping in CELP.
  Arbitrary y-axis offset.
-\begin_inset LatexCommand \label{cap:Standard-noise-shaping}
+\begin_inset CommandInset label
+LatexCommand label
+name "cap:Standard-noise-shaping"
+
+\end_inset
+
+
+\end_layout
 
 \end_inset
 
@@ -4236,409 +6993,605 @@ In order to achieve real-time encoding using limited computing resources,
 \end_layout
 
 \begin_layout Standard
+\begin_inset Newpage newpage
+\end_inset
+
+
+\end_layout
+
+\begin_layout Chapter
+The Speex Decoder Specification
+\end_layout
+
+\begin_layout Section
+Narrowband decoder
+\end_layout
+
+\begin_layout Standard
+<Insert decoder figure here>
+\end_layout
+
+\begin_layout Subsection
+Narrowband modes
+\end_layout
+
+\begin_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 CommandInset ref
+LatexCommand ref
+reference "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.
+ 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.
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float table
+placement h
+wide true
+sideways false
+status open
+
+\begin_layout Plain Layout
+\begin_inset ERT
+status collapsed
+
+\begin_layout Plain Layout
+
+
+\backslash
+begin{center}
+\end_layout
+
+\end_inset
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="12" columns="11">
+<features>
+<column alignment="center" valignment="top" width="0pt">
+<column alignment="center" valignment="top" width="0pt">
+<column alignment="center" valignment="top" width="0pt">
+<column alignment="center" valignment="top" width="0pt">
+<column alignment="center" valignment="top" width="0pt">
+<column alignment="center" valignment="top" width="0pt">
+<column alignment="center" valignment="top" width="0pt">
+<column alignment="center" valignment="top" width="0pt">
+<column alignment="center" valignment="top" width="0pt">
+<column alignment="center" valignment="top" width="0pt">
+<column alignment="center" valignment="top" width="0pt">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Parameter
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Update rate
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+2
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+3
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+4
+\end_layout
 
-\newpage
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
 
+\begin_layout Plain Layout
+5
 \end_layout
 
-\begin_layout Chapter
-Speex narrowband mode
-\begin_inset LatexCommand \label{sec:Speex-narrowband-mode}
-
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-
-\begin_inset LatexCommand \index{narrowband}
+\begin_layout Plain Layout
+6
+\end_layout
 
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-
+\begin_layout Plain Layout
+7
 \end_layout
 
-\begin_layout Standard
-This section looks at how Speex works for narrowband (
-\begin_inset Formula $8\:\mathrm{kHz}$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+8
+\end_layout
 
- sampling rate) operation.
- The frame size for this mode is 
-\begin_inset Formula $20\:\mathrm{ms}$
 \end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-, corresponding to 160 samples.
- Each frame is also subdivided into 4 sub-frames of 40 samples each.
+\begin_layout Plain Layout
+Wideband bit
 \end_layout
 
-\begin_layout Standard
-Also many design decisions were based on the original goals and assumptions:
-\end_layout
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-\begin_layout Itemize
-Minimizing the amount of information extracted from past frames (for robustness
- to packet loss)
+\begin_layout Plain Layout
+frame
 \end_layout
 
-\begin_layout Itemize
-Dynamically-selectable codebooks (LSP, pitch and innovation)
-\end_layout
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-\begin_layout Itemize
-sub-vector fixed (innovation) codebooks
+\begin_layout Plain Layout
+1
 \end_layout
 
-\begin_layout Section
-Whole-Frame Analysis
-\begin_inset LatexCommand \index{linear prediction}
-
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-
+\begin_layout Plain Layout
+1
 \end_layout
 
-\begin_layout Standard
-In narrowband, Speex frames are 20 ms long (160 samples) and are subdivided
- in 4 sub-frames of 5 ms each (40 samples).
- For most narrowband bit-rates (8 kbps and above), the only parameters encoded
- at the frame level are the Line Spectral Pairs (LSP) and a global excitation
- gain 
-\begin_inset Formula $g_{frame}$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-, as shown in Fig.
-\begin_inset LatexCommand \ref{cap:Frame-open-loop-analysis}
+\begin_layout Plain Layout
+1
+\end_layout
 
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-.
- All other parameters are encoded at the sub-frame level.
+\begin_layout Plain Layout
+1
 \end_layout
 
-\begin_layout Standard
-Linear prediction analysis is performed once per frame using an asymmetric
- Hamming window centered on the fourth sub-frame.
- Because linear prediction coefficients (LPC) are not robust to quantization,
- they are first are converted to line spectral pairs (LSP)
-\begin_inset LatexCommand \index{line spectral pair}
-
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-.
- The LSP's are considered to be associated to the 
-\begin_inset Formula $4^{th}$
-\end_inset
+\begin_layout Plain Layout
+1
+\end_layout
 
- sub-frames and the LSP's associated to the first 3 sub-frames are linearly
- interpolated using the current and previous LSP coefficients.
- The LSP coefficients and converted back to the LPC filter 
-\begin_inset Formula $\hat{A}(z)$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-.
- The non-quantized interpolated filter is denoted 
-\begin_inset Formula $A(z)$
-\end_inset
+\begin_layout Plain Layout
+1
+\end_layout
 
- and can be used for the weighting filter 
-\begin_inset Formula $W(z)$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- because it does not need to be available to the decoder.
+\begin_layout Plain Layout
+1
 \end_layout
 
-\begin_layout Standard
-To make Speex more robust to packet loss, no prediction is applied on the
- LSP coefficients prior to quantization.
- The LSPs are encoded using vector quantizatin (VQ) with 30 bits for higher
- quality modes and 18 bits for lower quality.
-\end_layout
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-\begin_layout Standard
-\begin_inset Float figure
-wide false
-sideways false
-status open
+\begin_layout Plain Layout
+1
+\end_layout
 
-\begin_layout Standard
-\begin_inset ERT
-status collapsed
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
+1
+\end_layout
 
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-\backslash
-begin{center}
+\begin_layout Plain Layout
+Mode ID
 \end_layout
 
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-
-\begin_inset Graphics
-       filename speex_analysis.eps
-       width 35page%
+\begin_layout Plain Layout
+frame
+\end_layout
 
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
+\begin_layout Plain Layout
+4
+\end_layout
 
-\begin_inset ERT
-status collapsed
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
+4
+\end_layout
 
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-\backslash
-end{center}
+\begin_layout Plain Layout
+4
 \end_layout
 
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-
+\begin_layout Plain Layout
+4
 \end_layout
 
-\begin_layout Caption
-Frame open-loop analysis
-\begin_inset LatexCommand \label{cap:Frame-open-loop-analysis}
-
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-
+\begin_layout Plain Layout
+4
 \end_layout
 
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-
+\begin_layout Plain Layout
+4
 \end_layout
 
-\begin_layout Section
-Sub-Frame Analysis-by-Synthesis
-\end_layout
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-\begin_layout Standard
-\begin_inset Float figure
-wide false
-sideways false
-status open
+\begin_layout Plain Layout
+4
+\end_layout
 
-\begin_layout Standard
-\begin_inset ERT
-status collapsed
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
+4
+\end_layout
 
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
-\backslash
-begin{center}
+\begin_layout Plain Layout
+4
 \end_layout
 
 \end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-
-\begin_inset Graphics
-       filename speex_abs.eps
-       lyxscale 75
-       width 40page%
+\begin_layout Plain Layout
+LSP
+\end_layout
 
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
+\begin_layout Plain Layout
+frame
+\end_layout
 
-\begin_inset ERT
-status collapsed
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
+0
+\end_layout
 
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-\backslash
-end{center}
+\begin_layout Plain Layout
+18
 \end_layout
 
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-
+\begin_layout Plain Layout
+18
 \end_layout
 
-\begin_layout Caption
-Analysis-by-synthesis closed-loop optimization on a sub-frame.
-\begin_inset LatexCommand \label{cap:Sub-frame-AbS}
-
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-
+\begin_layout Plain Layout
+18
 \end_layout
 
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-
+\begin_layout Plain Layout
+18
 \end_layout
 
-\begin_layout Standard
-The analysis-by-synthesis (AbS) encoder loop is described in Fig.
-\begin_inset LatexCommand \ref{cap:Sub-frame-AbS}
-
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+30
+\end_layout
 
-.
- There are three main aspects where Speex significantly differs from most
- other CELP codecs.
- First, while most recent CELP codecs make use of fractional pitch estimation
- with a single gain, Speex uses an integer to encode the pitch period, but
- uses a 3-tap predictor (3 gains).
- The adaptive codebook contribution 
-\begin_inset Formula $e_{a}[n]$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- can thus be expressed as:
-\begin_inset Formula \begin{equation}
-e_{a}[n]=g_{0}e[n-T-1]+g_{1}e[n-T]+g_{2}e[n-T+1]\label{eq:adaptive-3tap}\end{equation}
+\begin_layout Plain Layout
+30
+\end_layout
 
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-where 
-\begin_inset Formula $g_{0}$
-\end_inset
+\begin_layout Plain Layout
+30
+\end_layout
 
-, 
-\begin_inset Formula $g_{1}$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
- and 
-\begin_inset Formula $g_{2}$
-\end_inset
+\begin_layout Plain Layout
+18
+\end_layout
 
- are the jointly quantized pitch gains and 
-\begin_inset Formula $e[n]$
 \end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- is the codec excitation memory.
- 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
+\begin_layout Plain Layout
+OL pitch
+\end_layout
 
-.
- For example, when 
-\begin_inset Formula $n-T+1\geq0$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-, we use 
-\begin_inset Formula $n-2T+1$
-\end_inset
+\begin_layout Plain Layout
+frame
+\end_layout
 
- instead.
- In most modes, the pitch period is encoded with 7 bits in the 
-\begin_inset Formula $\left[17,144\right]$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+0
+\end_layout
 
- range and the 
-\begin_inset Formula $\beta_{i}$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- coefficients are vector-quantized using 7 bits at higher bit-rates (15
- kbps narrowband and above) and 5 bits at lower bit-rates (11 kbps narrowband
- and below).
+\begin_layout Plain Layout
+7
 \end_layout
 
-\begin_layout Standard
-Many current CELP codecs use moving average (MA) prediction to encode the
- fixed codebook gain.
- This provides slightly better coding at the expense of introducing a dependency
- on previously encoded frames.
- A second difference is that Speex encodes the fixed codebook gain as the
- product of the global excitation gain 
-\begin_inset Formula $g_{frame}$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+7
+\end_layout
 
- with a sub-frame gain corrections 
-\begin_inset Formula $g_{subf}$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-.
- This increases robustness to packet loss by eliminating the inter-frame
- dependency.
- The sub-frame gain correction is encoded before the fixed codebook is searched
- (not closed-loop optimized) and uses between 0 and 3 bits per sub-frame,
- depending on the bit-rate.
+\begin_layout Plain Layout
+0
 \end_layout
 
-\begin_layout Standard
-The third difference is that Speex uses sub-vector quantization of the innovatio
-n (fixed codebook) signal instead of an algebraic codebook.
- Each sub-frame is divided into sub-vectors of lengths ranging between 5
- and 20 samples.
- Each sub-vector is chosen from a bitrate-dependent codebook and all sub-vectors
- are concatenated to form a sub-frame.
- As an example, the 3.95 kbps mode uses a sub-vector size of 20 samples with
- 32 entries in the codebook (5 bits).
- This means that the innovation is encoded with 10 bits per sub-frame, or
- 2000 bps.
- On the other hand, the 18.2 kbps mode uses a sub-vector size of 5 samples
- with 256 entries in the codebook (8 bits), so the innovation uses 64 bits
- per sub-frame, or 12800 bps.
-\end_layout
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-\begin_layout Section
-Bit allocation
+\begin_layout Plain Layout
+0
 \end_layout
 
-\begin_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
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+0
+\end_layout
 
-.
- 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
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+0
+\end_layout
 
-OL
-\begin_inset Quotes erd
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- in the parameter description means that the parameter is an open loop estimatio
-n based on the whole frame.
+\begin_layout Plain Layout
+0
 \end_layout
 
-\begin_layout Standard
-\begin_inset Float table
-placement h
-wide true
-sideways false
-status open
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
-\begin_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">
+\begin_layout Plain Layout
+7
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-Parameter
+\begin_layout Plain Layout
+OL pitch gain
 \end_layout
 
 \end_inset
@@ -4646,8 +7599,8 @@ Parameter
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-Update rate
+\begin_layout Plain Layout
+frame
 \end_layout
 
 \end_inset
@@ -4655,7 +7608,7 @@ Update rate
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 0
 \end_layout
 
@@ -4664,8 +7617,8 @@ Update rate
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-1
+\begin_layout Plain Layout
+4
 \end_layout
 
 \end_inset
@@ -4673,8 +7626,8 @@ Update rate
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-2
+\begin_layout Plain Layout
+0
 \end_layout
 
 \end_inset
@@ -4682,8 +7635,8 @@ Update rate
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-3
+\begin_layout Plain Layout
+0
 \end_layout
 
 \end_inset
@@ -4691,8 +7644,8 @@ Update rate
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-4
+\begin_layout Plain Layout
+0
 \end_layout
 
 \end_inset
@@ -4700,26 +7653,26 @@ Update rate
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-5
+\begin_layout Plain Layout
+0
 \end_layout
 
 \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
 
-\begin_layout Standard
-6
+\begin_layout Plain Layout
+0
 \end_layout
 
 \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
 
-\begin_layout Standard
-7
+\begin_layout Plain Layout
+0
 \end_layout
 
 \end_inset
@@ -4727,19 +7680,19 @@ Update rate
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-8
+\begin_layout Plain Layout
+4
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-Wideband bit
+\begin_layout Plain Layout
+OL Exc gain
 \end_layout
 
 \end_inset
@@ -4747,7 +7700,7 @@ Wideband bit
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 frame
 \end_layout
 
@@ -4756,17 +7709,17 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-1
+\begin_layout Plain Layout
+0
 \end_layout
 
 \end_inset
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
-
-\begin_layout Standard
-1
+
+\begin_layout Plain Layout
+5
 \end_layout
 
 \end_inset
@@ -4774,8 +7727,8 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-1
+\begin_layout Plain Layout
+5
 \end_layout
 
 \end_inset
@@ -4783,8 +7736,8 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-1
+\begin_layout Plain Layout
+5
 \end_layout
 
 \end_inset
@@ -4792,8 +7745,8 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-1
+\begin_layout Plain Layout
+5
 \end_layout
 
 \end_inset
@@ -4801,26 +7754,26 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-1
+\begin_layout Plain Layout
+5
 \end_layout
 
 \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
 
-\begin_layout Standard
-1
+\begin_layout Plain Layout
+5
 \end_layout
 
 \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
 
-\begin_layout Standard
-1
+\begin_layout Plain Layout
+5
 \end_layout
 
 \end_inset
@@ -4828,19 +7781,19 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-1
+\begin_layout Plain Layout
+5
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-Mode ID
+\begin_layout Plain Layout
+Fine pitch
 \end_layout
 
 \end_inset
@@ -4848,8 +7801,8 @@ Mode ID
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-frame
+\begin_layout Plain Layout
+sub-frame
 \end_layout
 
 \end_inset
@@ -4857,8 +7810,8 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-4
+\begin_layout Plain Layout
+0
 \end_layout
 
 \end_inset
@@ -4866,8 +7819,8 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-4
+\begin_layout Plain Layout
+0
 \end_layout
 
 \end_inset
@@ -4875,8 +7828,8 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-4
+\begin_layout Plain Layout
+0
 \end_layout
 
 \end_inset
@@ -4884,8 +7837,8 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-4
+\begin_layout Plain Layout
+7
 \end_layout
 
 \end_inset
@@ -4893,8 +7846,8 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-4
+\begin_layout Plain Layout
+7
 \end_layout
 
 \end_inset
@@ -4902,26 +7855,26 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-4
+\begin_layout Plain Layout
+7
 \end_layout
 
 \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
 
-\begin_layout Standard
-4
+\begin_layout Plain Layout
+7
 \end_layout
 
 \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
 
-\begin_layout Standard
-4
+\begin_layout Plain Layout
+7
 \end_layout
 
 \end_inset
@@ -4929,19 +7882,19 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-4
+\begin_layout Plain Layout
+0
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-LSP
+\begin_layout Plain Layout
+Pitch gain
 \end_layout
 
 \end_inset
@@ -4949,8 +7902,8 @@ LSP
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-frame
+\begin_layout Plain Layout
+sub-frame
 \end_layout
 
 \end_inset
@@ -4958,7 +7911,7 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 0
 \end_layout
 
@@ -4967,8 +7920,8 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-18
+\begin_layout Plain Layout
+0
 \end_layout
 
 \end_inset
@@ -4976,8 +7929,8 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-18
+\begin_layout Plain Layout
+5
 \end_layout
 
 \end_inset
@@ -4985,8 +7938,8 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-18
+\begin_layout Plain Layout
+5
 \end_layout
 
 \end_inset
@@ -4994,8 +7947,8 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-18
+\begin_layout Plain Layout
+5
 \end_layout
 
 \end_inset
@@ -5003,26 +7956,26 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-30
+\begin_layout Plain Layout
+7
 \end_layout
 
 \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
 
-\begin_layout Standard
-30
+\begin_layout Plain Layout
+7
 \end_layout
 
 \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
 
-\begin_layout Standard
-30
+\begin_layout Plain Layout
+7
 \end_layout
 
 \end_inset
@@ -5030,19 +7983,19 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-18
+\begin_layout Plain Layout
+0
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-OL pitch
+\begin_layout Plain Layout
+Innovation gain
 \end_layout
 
 \end_inset
@@ -5050,8 +8003,8 @@ OL pitch
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-frame
+\begin_layout Plain Layout
+sub-frame
 \end_layout
 
 \end_inset
@@ -5059,7 +8012,7 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 0
 \end_layout
 
@@ -5068,8 +8021,8 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-7
+\begin_layout Plain Layout
+1
 \end_layout
 
 \end_inset
@@ -5077,8 +8030,8 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-7
+\begin_layout Plain Layout
+0
 \end_layout
 
 \end_inset
@@ -5086,8 +8039,8 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-0
+\begin_layout Plain Layout
+1
 \end_layout
 
 \end_inset
@@ -5095,8 +8048,8 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-0
+\begin_layout Plain Layout
+1
 \end_layout
 
 \end_inset
@@ -5104,26 +8057,26 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-0
+\begin_layout Plain Layout
+3
 \end_layout
 
 \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
 
-\begin_layout Standard
-0
+\begin_layout Plain Layout
+3
 \end_layout
 
 \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
 
-\begin_layout Standard
-0
+\begin_layout Plain Layout
+3
 \end_layout
 
 \end_inset
@@ -5131,755 +8084,762 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-7
+\begin_layout Plain Layout
+0
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-OL pitch gain
+\begin_layout Plain Layout
+Innovation VQ
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-frame
+\begin_layout Plain Layout
+sub-frame
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 0
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-4
+\begin_layout Plain Layout
+0
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-0
+\begin_layout Plain Layout
+16
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-0
+\begin_layout Plain Layout
+20
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-0
+\begin_layout Plain Layout
+35
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-0
+\begin_layout Plain Layout
+48
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-0
+\begin_layout Plain Layout
+64
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-0
+\begin_layout Plain Layout
+96
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-4
+\begin_layout Plain Layout
+10
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-OL Exc gain
+\begin_layout Plain Layout
+Total
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 frame
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Standard
-0
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 5
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-5
+\begin_layout Plain Layout
+43
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-5
+\begin_layout Plain Layout
+119
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-5
+\begin_layout Plain Layout
+160
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-5
+\begin_layout Plain Layout
+220
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-5
+\begin_layout Plain Layout
+300
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-5
+\begin_layout Plain Layout
+364
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-5
+\begin_layout Plain Layout
+492
 \end_layout
 
 \end_inset
 </cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-Fine pitch
+\begin_layout Plain Layout
+79
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Standard
-sub-frame
-\end_layout
+</row>
+</lyxtabular>
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Standard
-0
-\end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-0
-\end_layout
+\begin_inset ERT
+status collapsed
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_layout Plain Layout
 
-\begin_layout Standard
-0
+
+\backslash
+end{center}
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-7
+
 \end_layout
 
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Bit allocation for narrowband modes
+\begin_inset CommandInset label
+LatexCommand label
+name "cap:bits-narrowband"
+
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-7
+
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-7
+
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-7
+
 \end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\begin_layout Subsection
+LSP decoding
+\end_layout
 
 \begin_layout Standard
-7
+Depending on the mode, LSP parameters are encoded using either 18 bits or
+ 30 bits.
 \end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\begin_layout Standard
+Interpolation
+\end_layout
 
 \begin_layout Standard
-0
+Safe margin
 \end_layout
 
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_layout Subsection
+Adaptive codebook
+\end_layout
 
 \begin_layout Standard
-Pitch gain
-\end_layout
+For rates of 8 kbit/s and above, the pitch period is encoded for each subframe.
+ The real period is 
+\begin_inset Formula $T=p_{i}+17$
+\end_inset
 
+ where 
+\begin_inset Formula $p_{i}$
+\end_inset
+
+ is a value encoded with 7 bits and 17 corresponds to the minimum pitch.
+ The maximum period is 144.
+ At 5.95 kbit/s (mode 2), the pitch period is similarly encoded, but only
+ once for the frame.
+ Each sub-frame then has a 2-bit offset that is added to the pitch value
+ of the frame.
+ In that case, the pitch for each sub-frame is equal to 
+\begin_inset Formula $T-1+offset$
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
+.
+ For rates below 5.95 kbit/s, only the per-frame pitch is used and the pitch
+ is constant for all sub-frames.
+\end_layout
 
 \begin_layout Standard
-sub-frame
+Speex uses a 3-tap predictor for rates of 5.95 kbit/s and above.
+ The three gain values are obtained from a 5-bit or a 7-bit codebook, depending
+ on the mode.
+  
 \end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_layout Subsection
+Innovation codebook
+\end_layout
 
 \begin_layout Standard
-0
+Split codebook, size and entries depend on bit-rate
 \end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
 \begin_layout Standard
-0
+a 5-bit gain is encoder on a per-frame basis
 \end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_layout Standard
+Depending on the mode, higher resolution per sub-frame
+\end_layout
 
 \begin_layout Standard
-5
+innovation sub-vectors concatenated, gain applied
 \end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_layout Subsection
+Perceptual enhancement
+\end_layout
 
 \begin_layout Standard
-5
+Optional, implementation-defined.
 \end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_layout Section
+Wideband embedded decoder
+\end_layout
 
 \begin_layout Standard
-5
+QMF filter.
+ Narrowband signal decoded using narrowband decoder
 \end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_layout Standard
+For the high band, the decoder is similar to the narrowband decoder, with
+ the main difference being that there is no adaptive codebook.
+\end_layout
 
 \begin_layout Standard
-7
+Gain is per-subframe
 \end_layout
 
+\begin_layout Chapter
+Speex narrowband mode
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Speex-narrowband-mode"
+
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-7
+
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+narrowband
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-7
+
 \end_layout
 
+\begin_layout Standard
+This section looks at how Speex works for narrowband (
+\begin_inset Formula $8\:\mathrm{kHz}$
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+
+ 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.
+\end_layout
 
 \begin_layout Standard
-0
+Also many design decisions were based on the original goals and assumptions:
 \end_layout
 
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_layout Itemize
+Minimizing the amount of information extracted from past frames (for robustness
+ to packet loss)
+\end_layout
 
-\begin_layout Standard
-Innovation gain
+\begin_layout Itemize
+Dynamically-selectable codebooks (LSP, pitch and innovation)
 \end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_layout Itemize
+sub-vector fixed (innovation) codebooks
+\end_layout
 
-\begin_layout Standard
-sub-frame
+\begin_layout Section
+Whole-Frame Analysis
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+linear prediction
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-0
+
 \end_layout
 
+\begin_layout Standard
+In narrowband, Speex frames are 20 ms long (160 samples) and are subdivided
+ in 4 sub-frames of 5 ms each (40 samples).
+ For most narrowband bit-rates (8 kbps and above), the only parameters encoded
+ at the frame level are the Line Spectral Pairs (LSP) and a global excitation
+ gain 
+\begin_inset Formula $g_{frame}$
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-1
-\end_layout
+, as shown in Fig.
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "cap:Frame-open-loop-analysis"
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
+.
+ All other parameters are encoded at the sub-frame level.
+\end_layout
 
 \begin_layout Standard
-0
+Linear prediction analysis is performed once per frame using an asymmetric
+ Hamming window centered on the fourth sub-frame.
+ Because linear prediction coefficients (LPC) are not robust to quantization,
+ they are first converted to line spectral pairs (LSP)
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+line spectral pair
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-1
-\end_layout
+.
+ 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 coefficients.
+ The LSP coefficients and converted back to the LPC filter 
+\begin_inset Formula $\hat{A}(z)$
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-1
-\end_layout
+.
+ The non-quantized interpolated filter is denoted 
+\begin_inset Formula $A(z)$
+\end_inset
 
+ and can be used for the weighting filter 
+\begin_inset Formula $W(z)$
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-3
+ because it does not need to be available to the decoder.
 \end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\begin_layout Standard
+To make Speex more robust to packet loss, no prediction is applied on the
+ LSP coefficients prior to quantization.
+ The LSPs are encoded using vector quantization (VQ) with 30 bits for higher
+ quality modes and 18 bits for lower quality.
+\end_layout
 
 \begin_layout Standard
-3
+\begin_inset Float figure
+wide false
+sideways false
+status open
+
+\begin_layout Plain Layout
+\begin_inset ERT
+status collapsed
+
+\begin_layout Plain Layout
+
+
+\backslash
+begin{center}
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-3
-\end_layout
+
+\begin_inset Graphics
+       filename speex_analysis.eps
+       width 35page%
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-0
-\end_layout
 
-\end_inset
-</cell>
-</row>
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_inset ERT
+status collapsed
 
-\begin_layout Standard
-Innovation VQ
-\end_layout
+\begin_layout Plain Layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-sub-frame
+\backslash
+end{center}
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-0
+
 \end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_layout Plain Layout
+\begin_inset Caption
 
-\begin_layout Standard
-0
-\end_layout
+\begin_layout Plain Layout
+Frame open-loop analysis
+\begin_inset CommandInset label
+LatexCommand label
+name "cap:Frame-open-loop-analysis"
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-16
+
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-20
+
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-35
+
 \end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_layout Section
+Sub-Frame Analysis-by-Synthesis
+\end_layout
 
 \begin_layout Standard
-48
-\end_layout
+\begin_inset Float figure
+wide false
+sideways false
+status open
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\begin_layout Plain Layout
+\begin_inset ERT
+status collapsed
 
-\begin_layout Standard
-64
-\end_layout
+\begin_layout Plain Layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-96
+\backslash
+begin{center}
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-10
-\end_layout
+
+\begin_inset Graphics
+       filename speex_abs.eps
+       lyxscale 75
+       width 40page%
 
 \end_inset
-</cell>
-</row>
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-Total
-\end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_inset ERT
+status collapsed
 
-\begin_layout Standard
-frame
-\end_layout
+\begin_layout Plain Layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-5
+\backslash
+end{center}
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-43
+
 \end_layout
 
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Analysis-by-synthesis closed-loop optimization on a sub-frame.
+\begin_inset CommandInset label
+LatexCommand label
+name "cap:Sub-frame-AbS"
+
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-119
+
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-160
+
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-220
+
 \end_layout
 
+\begin_layout Standard
+The analysis-by-synthesis (AbS) encoder loop is described in Fig.
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "cap:Sub-frame-AbS"
+
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-300
-\end_layout
+.
+ There are three main aspects where Speex significantly differs from most
+ other CELP codecs.
+ First, while most recent CELP codecs make use of fractional pitch estimation
+ with a single gain, Speex uses an integer to encode the pitch period, but
+ uses a 3-tap predictor (3 gains).
+ The adaptive codebook contribution 
+\begin_inset Formula $e_{a}[n]$
+\end_inset
+
+ can thus be expressed as:
+\begin_inset Formula \begin{equation}
+e_{a}[n]=g_{0}e[n-T-1]+g_{1}e[n-T]+g_{2}e[n-T+1]\label{eq:adaptive-3tap}\end{equation}
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-364
-\end_layout
+where 
+\begin_inset Formula $g_{0}$
+\end_inset
+
+, 
+\begin_inset Formula $g_{1}$
+\end_inset
 
+ and 
+\begin_inset Formula $g_{2}$
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-492
-\end_layout
+ are the jointly quantized pitch gains and 
+\begin_inset Formula $e[n]$
+\end_inset
 
+ is the codec excitation memory.
+ 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
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-79
-\end_layout
+.
+ For example, when 
+\begin_inset Formula $n-T+1\geq0$
+\end_inset
 
+, we use 
+\begin_inset Formula $n-2T+1$
 \end_inset
-</cell>
-</row>
-</lyxtabular>
 
+ instead.
+ 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 at higher bit-rates (15
+ kbps narrowband and above) and 5 bits at lower bit-rates (11 kbps narrowband
+ and below).
 \end_layout
 
-\begin_layout Caption
-Bit allocation for narrowband modes
-\begin_inset LatexCommand \label{cap:bits-narrowband}
+\begin_layout Standard
+Many current CELP codecs use moving average (MA) prediction to encode the
+ fixed codebook gain.
+ This provides slightly better coding at the expense of introducing a dependency
+ on previously encoded frames.
+ A second difference is that Speex encodes the fixed codebook gain as the
+ product of the global excitation gain 
+\begin_inset Formula $g_{frame}$
+\end_inset
 
+ with a sub-frame gain corrections 
+\begin_inset Formula $g_{subf}$
 \end_inset
 
+.
+ This increases robustness to packet loss by eliminating the inter-frame
+ dependency.
+ The sub-frame gain correction is encoded before the fixed codebook is searched
+ (not closed-loop optimized) and uses between 0 and 3 bits per sub-frame,
+ depending on the bit-rate.
+\end_layout
 
+\begin_layout Standard
+The third difference is that Speex uses sub-vector quantization of the innovatio
+n (fixed codebook) signal instead of an algebraic codebook.
+ Each sub-frame is divided into sub-vectors of lengths ranging between 5
+ and 20 samples.
+ Each sub-vector is chosen from a bitrate-dependent codebook and all sub-vectors
+ are concatenated to form a sub-frame.
+ As an example, the 3.95 kbps mode uses a sub-vector size of 20 samples with
+ 32 entries in the codebook (5 bits).
+ This means that the innovation is encoded with 10 bits per sub-frame, or
+ 2000 bps.
+ On the other hand, the 18.2 kbps mode uses a sub-vector size of 5 samples
+ with 256 entries in the codebook (8 bits), so the innovation uses 64 bits
+ per sub-frame, or 12800 bps.
 \end_layout
 
-\end_inset
-
-
+\begin_layout Section
+Bit-rates
 \end_layout
 
 \begin_layout Standard
 So far, no MOS (Mean Opinion Score
-\begin_inset LatexCommand \index{mean opinion score}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+mean opinion score
+\end_layout
 
 \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}
+ In order to give an idea of the quality achievable with it, table 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "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
+ It should 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
@@ -5887,7 +8847,12 @@ So far, no MOS (Mean Opinion Score
  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}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+complexity
+\end_layout
 
 \end_inset
 
@@ -5901,30 +8866,58 @@ wide true
 sideways false
 status open
 
-\begin_layout Standard
+\begin_layout Plain Layout
+\begin_inset ERT
+status collapsed
+
+\begin_layout Plain Layout
+
+
+\backslash
+begin{center}
+\end_layout
+
+\end_inset
+
+
 \begin_inset Tabular
-<lyxtabular version="3" rows="17" columns="4">
+<lyxtabular version="3" rows="17" columns="5">
 <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">
+<column alignment="center" valignment="top" width="0pt">
+<column alignment="center" valignment="top" width="0pt">
+<column alignment="center" valignment="top" width="0pt">
+<column alignment="center" valignment="top" width="0pt">
+<column alignment="center" valignment="top" width="0pt">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 Mode
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
+Quality
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
 Bit-rate
-\begin_inset LatexCommand \index{bit-rate}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+bit-rate
+\end_layout
 
 \end_inset
 
@@ -5933,12 +8926,17 @@ Bit-rate
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 mflops
-\begin_inset LatexCommand \index{complexity}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+complexity
+\end_layout
 
 \end_inset
 
@@ -5947,21 +8945,21 @@ mflops
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 Quality/description
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 0
 \end_layout
 
@@ -5970,7 +8968,16 @@ Quality/description
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
+-
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
 250
 \end_layout
 
@@ -5979,8 +8986,8 @@ Quality/description
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-N/A
+\begin_layout Plain Layout
+0
 \end_layout
 
 \end_inset
@@ -5988,18 +8995,18 @@ N/A
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 No transmission (DTX)
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 1
 \end_layout
 
@@ -6008,7 +9015,16 @@ No transmission (DTX)
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
+0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
 2,150
 \end_layout
 
@@ -6017,7 +9033,7 @@ No transmission (DTX)
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 6
 \end_layout
 
@@ -6026,18 +9042,18 @@ No transmission (DTX)
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 Vocoder (mostly for comfort noise)
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 2
 \end_layout
 
@@ -6046,7 +9062,16 @@ Vocoder (mostly for comfort noise)
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
+2
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
 5,950
 \end_layout
 
@@ -6055,7 +9080,7 @@ Vocoder (mostly for comfort noise)
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 9
 \end_layout
 
@@ -6064,18 +9089,18 @@ Vocoder (mostly for comfort noise)
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 Very noticeable artifacts/noise, good intelligibility
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 3
 \end_layout
 
@@ -6084,7 +9109,16 @@ Very noticeable artifacts/noise, good intelligibility
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
+3-4
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
 8,000
 \end_layout
 
@@ -6093,7 +9127,7 @@ Very noticeable artifacts/noise, good intelligibility
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 10
 \end_layout
 
@@ -6102,18 +9136,18 @@ Very noticeable artifacts/noise, good intelligibility
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 Artifacts/noise sometimes noticeable
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 4
 \end_layout
 
@@ -6122,7 +9156,16 @@ Artifacts/noise sometimes noticeable
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
+5-6
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
 11,000
 \end_layout
 
@@ -6131,7 +9174,7 @@ Artifacts/noise sometimes noticeable
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 14
 \end_layout
 
@@ -6140,18 +9183,18 @@ Artifacts/noise sometimes noticeable
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 Artifacts usually noticeable only with headphones
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 5
 \end_layout
 
@@ -6160,7 +9203,16 @@ Artifacts usually noticeable only with headphones
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
+7-8
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
 15,000
 \end_layout
 
@@ -6169,7 +9221,7 @@ Artifacts usually noticeable only with headphones
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 11
 \end_layout
 
@@ -6178,18 +9230,18 @@ Artifacts usually noticeable only with headphones
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 Need good headphones to tell the difference
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 6
 \end_layout
 
@@ -6198,7 +9250,16 @@ Need good headphones to tell the difference
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
+9
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
 18,200
 \end_layout
 
@@ -6207,7 +9268,7 @@ Need good headphones to tell the difference
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 17.5
 \end_layout
 
@@ -6216,18 +9277,18 @@ Need good headphones to tell the difference
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 Hard to tell the difference even with good headphones
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 7
 \end_layout
 
@@ -6236,7 +9297,16 @@ Hard to tell the difference even with good headphones
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
+10
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
 24,600
 \end_layout
 
@@ -6245,7 +9315,7 @@ Hard to tell the difference even with good headphones
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 14.5
 \end_layout
 
@@ -6254,18 +9324,18 @@ Hard to tell the difference even with good headphones
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 Completely transparent for voice, good quality music
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 8
 \end_layout
 
@@ -6274,7 +9344,16 @@ Completely transparent for voice, good quality music
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
+1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
 3,950
 \end_layout
 
@@ -6283,7 +9362,7 @@ Completely transparent for voice, good quality music
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 10.5
 \end_layout
 
@@ -6292,18 +9371,18 @@ Completely transparent for voice, good quality music
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 Very noticeable artifacts/noise, good intelligibility
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 9
 \end_layout
 
@@ -6312,8 +9391,8 @@ Very noticeable artifacts/noise, good intelligibility
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-N/A
+\begin_layout Plain Layout
+-
 \end_layout
 
 \end_inset
@@ -6321,8 +9400,17 @@ N/A
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-N/A
+\begin_layout Plain Layout
+-
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+-
 \end_layout
 
 \end_inset
@@ -6330,18 +9418,18 @@ N/A
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 reserved
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 10
 \end_layout
 
@@ -6350,8 +9438,8 @@ reserved
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-N/A
+\begin_layout Plain Layout
+-
 \end_layout
 
 \end_inset
@@ -6359,8 +9447,17 @@ N/A
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-N/A
+\begin_layout Plain Layout
+-
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+-
 \end_layout
 
 \end_inset
@@ -6368,18 +9465,18 @@ N/A
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 reserved
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 11
 \end_layout
 
@@ -6388,8 +9485,8 @@ reserved
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-N/A
+\begin_layout Plain Layout
+-
 \end_layout
 
 \end_inset
@@ -6397,8 +9494,17 @@ N/A
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-N/A
+\begin_layout Plain Layout
+-
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+-
 \end_layout
 
 \end_inset
@@ -6406,18 +9512,18 @@ N/A
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 reserved
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 12
 \end_layout
 
@@ -6426,8 +9532,8 @@ reserved
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-N/A
+\begin_layout Plain Layout
+-
 \end_layout
 
 \end_inset
@@ -6435,8 +9541,17 @@ N/A
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-N/A
+\begin_layout Plain Layout
+-
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+-
 \end_layout
 
 \end_inset
@@ -6444,18 +9559,18 @@ N/A
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 reserved
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 13
 \end_layout
 
@@ -6464,8 +9579,8 @@ reserved
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-N/A
+\begin_layout Plain Layout
+-
 \end_layout
 
 \end_inset
@@ -6473,8 +9588,17 @@ N/A
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-N/A
+\begin_layout Plain Layout
+-
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+-
 \end_layout
 
 \end_inset
@@ -6482,18 +9606,18 @@ N/A
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 Application-defined, interpreted by callback or skipped
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 14
 \end_layout
 
@@ -6502,8 +9626,8 @@ Application-defined, interpreted by callback or skipped
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-N/A
+\begin_layout Plain Layout
+-
 \end_layout
 
 \end_inset
@@ -6511,8 +9635,17 @@ N/A
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-N/A
+\begin_layout Plain Layout
+-
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+-
 \end_layout
 
 \end_inset
@@ -6520,61 +9653,93 @@ N/A
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 Speex in-band signaling
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 15
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-N/A
+\begin_layout Plain Layout
+-
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-N/A
+\begin_layout Plain Layout
+-
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
+-
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
 Terminator code
 \end_layout
 
 \end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\begin_inset ERT
+status collapsed
+
+\begin_layout Plain Layout
+
+
+\backslash
+end{center}
+\end_layout
+
+\end_inset
 
 
 \end_layout
 
-\begin_layout Caption
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
 Quality versus bit-rate
-\begin_inset LatexCommand \label{cap:quality_vs_bps}
+\begin_inset CommandInset label
+LatexCommand label
+name "cap:quality_vs_bps"
+
+\end_inset
+
+
+\end_layout
 
 \end_inset
 
@@ -6588,7 +9753,12 @@ Quality versus bit-rate
 
 \begin_layout Section
 Perceptual enhancement
-\begin_inset LatexCommand \index{perceptual enhancement}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+perceptual enhancement
+\end_layout
 
 \end_inset
 
@@ -6642,19 +9812,27 @@ where
 \end_layout
 
 \begin_layout Standard
+\begin_inset Newpage newpage
+\end_inset
 
-\newpage
 
 \end_layout
 
 \begin_layout Chapter
 Speex wideband mode (sub-band CELP)
-\begin_inset LatexCommand \index{wideband}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+wideband
+\end_layout
 
 \end_inset
 
 
-\begin_inset LatexCommand \label{sec:Speex-wideband-mode}
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Speex-wideband-mode"
 
 \end_inset
 
@@ -6675,7 +9853,12 @@ irror
 f
 \emph default
 ilter
-\begin_inset LatexCommand \index{quadrature mirror filter}
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+quadrature mirror filter
+\end_layout
 
 \end_inset
 
@@ -6683,7 +9866,9 @@ ilter
  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}
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Speex-narrowband-mode"
 
 \end_inset
 
@@ -6745,13 +9930,26 @@ Bit allocation
 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}
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "cap:bits-narrowband"
 
 \end_inset
 
 .
  The high-band follows, as described in table 
-\begin_inset LatexCommand \ref{cap:bits-wideband}
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "cap:bits-wideband"
+
+\end_inset
+
+.
+ For wideband, the mode ID is the same as the Speex quality setting and
+ is defined in table 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "tab:wideband-quality"
 
 \end_inset
 
@@ -6762,30 +9960,303 @@ For the wideband mode, the entire narrowband frame is packed before the
  to sync with the bit-stream.
 \end_layout
 
-\begin_layout Standard
-\begin_inset Float table
-placement h
-wide true
-sideways false
-status open
+\begin_layout Standard
+\begin_inset Float table
+placement h
+wide true
+sideways false
+status open
+
+\begin_layout Plain Layout
+\begin_inset ERT
+status collapsed
+
+\begin_layout Plain Layout
+
+
+\backslash
+begin{center}
+\end_layout
+
+\end_inset
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="7" columns="7">
+<features>
+<column alignment="center" valignment="top" width="0pt">
+<column alignment="center" valignment="top" width="0pt">
+<column alignment="center" valignment="top" width="0pt">
+<column alignment="center" valignment="top" width="0pt">
+<column alignment="center" valignment="top" width="0pt">
+<column alignment="center" valignment="top" width="0pt">
+<column alignment="center" valignment="top" width="0pt">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Parameter
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Update rate
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+2
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+3
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+4
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Wideband bit
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+frame
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+1
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+1
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Mode ID
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+frame
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+3
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+3
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+3
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+3
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+3
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+LSP
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+frame
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+0
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+12
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+12
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+12
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
-\begin_layout Standard
-\begin_inset Tabular
-<lyxtabular version="3" rows="7" columns="7">
-<features>
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
-<row topline="true" bottomline="true">
+\begin_layout Plain Layout
+12
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-Parameter
+\begin_layout Plain Layout
+Excitation gain
 \end_layout
 
 \end_inset
@@ -6793,8 +10264,8 @@ Parameter
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-Update rate
+\begin_layout Plain Layout
+sub-frame
 \end_layout
 
 \end_inset
@@ -6802,7 +10273,7 @@ Update rate
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 0
 \end_layout
 
@@ -6811,8 +10282,8 @@ Update rate
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-1
+\begin_layout Plain Layout
+5
 \end_layout
 
 \end_inset
@@ -6820,8 +10291,8 @@ Update rate
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-2
+\begin_layout Plain Layout
+4
 \end_layout
 
 \end_inset
@@ -6829,175 +10300,267 @@ Update rate
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-3
+\begin_layout Plain Layout
+4
 \end_layout
 
 \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
 
-\begin_layout Standard
+\begin_layout Plain Layout
 4
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-Wideband bit
+\begin_layout Plain Layout
+Excitation VQ
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-frame
+\begin_layout Plain Layout
+sub-frame
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-1
+\begin_layout Plain Layout
+0
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-1
+\begin_layout Plain Layout
+0
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-1
+\begin_layout Plain Layout
+20
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-1
+\begin_layout Plain Layout
+40
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-1
+\begin_layout Plain Layout
+80
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-Mode ID
+\begin_layout Plain Layout
+Total
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 frame
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-3
+\begin_layout Plain Layout
+4
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-3
+\begin_layout Plain Layout
+36
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-3
+\begin_layout Plain Layout
+112
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-3
+\begin_layout Plain Layout
+192
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-3
+\begin_layout Plain Layout
+352
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+</lyxtabular>
+
+\end_inset
+
+
+\begin_inset ERT
+status collapsed
+
+\begin_layout Plain Layout
+
+
+\backslash
+end{center}
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Bit allocation for high-band in wideband mode
+\begin_inset CommandInset label
+LatexCommand label
+name "cap:bits-wideband"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
 
 \begin_layout Standard
-LSP
+\begin_inset Float table
+placement h
+wide true
+sideways false
+status open
+
+\begin_layout Plain Layout
+\begin_inset ERT
+status collapsed
+
+\begin_layout Plain Layout
+
+
+\backslash
+begin{center}
+\end_layout
+
+\end_inset
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="12" columns="3">
+<features>
+<column alignment="center" valignment="top" width="0pt">
+<column alignment="center" valignment="top" width="0pt">
+<column alignment="center" valignment="top" width="0pt">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Mode/Quality
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-frame
+\begin_layout Plain Layout
+Bit-rate
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+bit-rate
+\end_layout
+
+\end_inset
+
+ (bps)
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Quality/description
 \end_layout
 
 \end_inset
 </cell>
+</row>
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 0
 \end_layout
 
@@ -7006,26 +10569,28 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-12
+\begin_layout Plain Layout
+3,950
 \end_layout
 
 \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
 
-\begin_layout Standard
-12
+\begin_layout Plain Layout
+Barely intelligible (mostly for comfort noise)
 \end_layout
 
 \end_inset
 </cell>
+</row>
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-12
+\begin_layout Plain Layout
+1
 \end_layout
 
 \end_inset
@@ -7033,19 +10598,28 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-12
+\begin_layout Plain Layout
+5,750
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Very noticeable artifacts/noise, poor intelligibility
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-Excitation gain
+\begin_layout Plain Layout
+2
 \end_layout
 
 \end_inset
@@ -7053,26 +10627,28 @@ Excitation gain
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-sub-frame
+\begin_layout Plain Layout
+7,750
 \end_layout
 
 \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
 
-\begin_layout Standard
-0
+\begin_layout Plain Layout
+Very noticeable artifacts/noise, good intelligibility
 \end_layout
 
 \end_inset
 </cell>
+</row>
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-5
+\begin_layout Plain Layout
+3
 \end_layout
 
 \end_inset
@@ -7080,16 +10656,27 @@ sub-frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-4
+\begin_layout Plain Layout
+9,800
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Artifacts/noise sometimes annoying
 \end_layout
 
 \end_inset
 </cell>
+</row>
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 4
 \end_layout
 
@@ -7098,19 +10685,28 @@ sub-frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-4
+\begin_layout Plain Layout
+12,800
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Artifacts/noise usually noticeable
 \end_layout
 
 \end_inset
 </cell>
 </row>
-<row topline="true" bottomline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-Excitation VQ
+\begin_layout Plain Layout
+5
 \end_layout
 
 \end_inset
@@ -7118,26 +10714,28 @@ Excitation VQ
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-sub-frame
+\begin_layout Plain Layout
+16,800
 \end_layout
 
 \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
 
-\begin_layout Standard
-0
+\begin_layout Plain Layout
+Artifacts/noise sometimes noticeable
 \end_layout
 
 \end_inset
 </cell>
+</row>
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-0
+\begin_layout Plain Layout
+6
 \end_layout
 
 \end_inset
@@ -7145,17 +10743,28 @@ sub-frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-20
+\begin_layout Plain Layout
+20,600
 \end_layout
 
 \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
 
-\begin_layout Standard
-40
+\begin_layout Plain Layout
+Need good headphones to tell the difference
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+7
 \end_layout
 
 \end_inset
@@ -7163,28 +10772,28 @@ sub-frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-80
+\begin_layout Plain Layout
+23,800
 \end_layout
 
 \end_inset
 </cell>
-</row>
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-Total
+\begin_layout Plain Layout
+Need good headphones to tell the difference
 \end_layout
 
 \end_inset
 </cell>
+</row>
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-frame
+\begin_layout Plain Layout
+8
 \end_layout
 
 \end_inset
@@ -7192,26 +10801,28 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-4
+\begin_layout Plain Layout
+27,800
 \end_layout
 
 \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
 
-\begin_layout Standard
-36
+\begin_layout Plain Layout
+Hard to tell the difference even with good headphones
 \end_layout
 
 \end_inset
 </cell>
+</row>
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-112
+\begin_layout Plain Layout
+9
 \end_layout
 
 \end_inset
@@ -7219,68 +10830,64 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-192
+\begin_layout Plain Layout
+34,200
 \end_layout
 
 \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
 
-\begin_layout Standard
-352
+\begin_layout Plain Layout
+Hard to tell the difference even with good headphones
 \end_layout
 
 \end_inset
 </cell>
 </row>
-</lyxtabular>
-
-\end_inset
-
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
 
+\begin_layout Plain Layout
+10
 \end_layout
 
-\begin_layout Caption
-Bit allocation for high-band in wideband mode
-\begin_inset LatexCommand \label{cap:bits-wideband}
-
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-
+\begin_layout Plain Layout
+42,200
 \end_layout
 
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset ERT
-status open
-
-\begin_layout Standard
-
-
-\backslash
-clearpage
+\begin_layout Plain Layout
+Completely transparent for voice, good quality music
 \end_layout
 
 \end_inset
+</cell>
+</row>
+</lyxtabular>
 
+\end_inset
 
-\end_layout
 
-\begin_layout Standard
 \begin_inset ERT
 status collapsed
 
-\begin_layout Standard
+\begin_layout Plain Layout
 
 
 \backslash
-clearpage
+end{center}
 \end_layout
 
 \end_inset
@@ -7288,418 +10895,177 @@ clearpage
 
 \end_layout
 
-\begin_layout Chapter
-\start_of_appendix
-FAQ
-\end_layout
-
-\begin_layout Subsection*
-Vorbis is open-source
-\begin_inset LatexCommand \index{open-source}
-
-\end_inset
+\begin_layout Plain Layout
+\begin_inset Caption
 
- and patent-free
-\begin_inset LatexCommand \index{patent}
+\begin_layout Plain Layout
+Quality versus bit-rate for the wideband encoder
+\begin_inset CommandInset label
+LatexCommand label
+name "tab:wideband-quality"
 
 \end_inset
 
-; why do we need Speex?
-\end_layout
 
-\begin_layout Standard
-Vorbis is a great project but its goals are not the same as Speex.
- Vorbis is mostly aimed at compressing music and audio in general, while
- Speex targets speech only.
- For that reason Speex can achieve much better results than Vorbis on speech,
- typically 2-4 times higher compression at equal quality.
 \end_layout
 
-\begin_layout Subsection*
-Isn't there an open-source implementation of the GSM-FR codec? Why is Speex
- necessary?
-\end_layout
+\end_inset
 
-\begin_layout Standard
-First of all, it's not clear whether GSM-FR is covered by a Philips patent
- (see http://kbs.cs.tu-berlin.de/~jutta/toast.html).
- Also, GSM-FR offers mediocre quality at a relatively high bit-rate, while
- Speex can offer equivalent quality at almost half the bit-rate.
- Last but not least, Speex offers a wide range of bit-rates and sampling
- rates, while GSM-FR is limited to 8 kHz speech at 13 kbps.
-\end_layout
 
-\begin_layout Subsection*
-Under what license is Speex released?
 \end_layout
 
-\begin_layout Standard
-As of version 1.0 beta 1, Speex is released under Xiph's version of the (revised)
- BSD license (see Appendix 
-\begin_inset LatexCommand \ref{sec:Speex-License}
-
 \end_inset
 
-).
- This license is one of the most permissive open-source licenses.
-\end_layout
 
-\begin_layout Subsection*
-Am I allowed to use Speex in commercial software?
 \end_layout
 
 \begin_layout Standard
-Yes.
- As long as you comply with the license.
- This basically means you have to keep the copyright notice and you can't
- use our name to promote your product without authorization.
- For more details, see license in Appendix 
-\begin_inset LatexCommand \ref{sec:Speex-License}
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Subsection*
-Ogg
-\begin_inset LatexCommand \index{Ogg}
-
-\end_inset
+\begin_inset ERT
+status open
 
-, Speex, Vorbis
-\begin_inset LatexCommand \index{Vorbis}
+\begin_layout Plain Layout
 
-\end_inset
 
-, what's the difference?
+\backslash
+clearpage
 \end_layout
 
-\begin_layout Standard
-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
-
-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.
-\end_layout
 
-\begin_layout Subsection*
-What's the extension for Speex?
 \end_layout
 
 \begin_layout Standard
-Speex files have the .spx extension.
- Note, however that the Speex tools (speexenc, speexdec) do not rely on
- the extension at all, so any extension will work.
-\end_layout
-
-\begin_layout Subsection*
-Can I use Speex for compressing music
-\begin_inset LatexCommand \index{music}
+\begin_inset ERT
+status collapsed
 
-\end_inset
+\begin_layout Plain Layout
 
-?
-\end_layout
 
-\begin_layout Standard
-Just like Vorbis is not really adapted to speech, Speex is really not adapted
- for music.
- In most cases, you'll be better of with Vorbis when it comes to music.
+\backslash
+clearpage
 \end_layout
 
-\begin_layout Subsection*
-I converted some MP3s to Speex and the quality is bad.
- What's wrong?
-\end_layout
+\end_inset
 
-\begin_layout Standard
-This is called transcoding and it will always result in much poorer quality
- than the original MP3.
- Unless you have a really good (size) reason to do so, never transcode speech.
- This is even valid for self transcoding (tandeming), i.e.
- If you decode a Speex file and re-encode it again at the same bit-rate,
- you will lose quality.
-\end_layout
 
-\begin_layout Subsection*
-Does Speex run on Windows?
 \end_layout
 
-\begin_layout Standard
-Compilation on Windows has been supported since version 0.8.0.
- There are also several front-ends available from the website.
-\end_layout
+\begin_layout Chapter
+\start_of_appendix
+Sample code
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Sample-code"
 
-\begin_layout Subsection*
-Why is encoding so slow compared to decoding?
-\end_layout
+\end_inset
 
-\begin_layout Standard
-For most kinds of compression, encoding is inherently slower than decoding.
- In the case of Speex, encoding consists of finding, for each vector of
- 5 to 10 samples, the entry that matches the best within a codebook consisting
- of 16 to 256 entries.
- On the other hand, at decoding all that needs to be done is 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.
-\end_layout
 
-\begin_layout Subsection*
-Why is Speex so slow on my iPaq (or insert any platform without an FPU)?
 \end_layout
 
 \begin_layout Standard
-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).
-\end_layout
-
-\begin_layout Subsection*
-I'm getting unusual background noise (hiss) when using libspeex in my applicatio
-n.
- How do I fix that?
-\end_layout
+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
 
-\begin_layout Standard
-One of the causes could be scaling of the input speech.
- Speex expects signals to have a 
-\begin_inset Formula $\pm2^{15}$
+\begin_inset Newline newline
 \end_inset
 
- (signed short) dynamic range.
- If the dynamic range of your signals is too small (e.g.
-\begin_inset Formula $\pm1.0$
-\end_inset
+% sampleenc in_file.sw | sampledec out_file.sw
+\family default
 
-), you will suffer important quantization noise.
- A good target is to have a dynamic range around 
-\begin_inset Formula $\pm8000$
+\begin_inset Newline newline
 \end_inset
 
- which is large enough, but small enough to make sure there's no clipping
when converting back to signed short.
+where both files are raw (no header) files encoded at 16 bits per sample
(in the machine natural endianness).
 \end_layout
 
-\begin_layout Subsection*
-I get very distorted speech when using libspeex in my application.
- What's wrong?
+\begin_layout Section
+sampleenc.c
 \end_layout
 
 \begin_layout Standard
-There are many possible causes for that.
- One of them is errors in the way the bits are manipulated.
- Another possible cause is the use of the same encoder or decoder state
- for more than one audio stream (channel), which produces strange effects
- with the filter memories.
- If the input speech has an amplitude close to 
-\begin_inset Formula $\pm2^{15}$
-\end_inset
-
-, it is possible that at decoding, the amplitude be a bit higher than that,
- causing clipping when saving as 16-bit PCM.
-\end_layout
-
-\begin_layout Subsection*
-How does Speex compare to other proprietary codecs?
+sampleenc takes a raw 16 bits/sample file, encodes it and outputs a Speex
+ stream to stdout.
+ Note that the packing used is 
+\series bold
+not
+\series default
+ compatible with that of speexenc/speexdec.
 \end_layout
 
 \begin_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.
-\end_layout
-
-\begin_layout Subsection*
-Can Speex pass DTMF
-\begin_inset LatexCommand \index{DTMF}
+\begin_inset CommandInset include
+LatexCommand lstinputlisting
+filename "sampleenc.c"
+lstparams "caption={Source code for sampleenc},label={sampleenc-source-code},numbers=left,numberstyle={\\footnotesize}"
 
 \end_inset
 
-?
-\end_layout
-
-\begin_layout Standard
-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.
- Also, make sure you don't use the lowest complexity (see SPEEX_SET_COMPLEXITY
- or --comp option), as it causes significant noise.
-\end_layout
 
-\begin_layout Subsection*
-Can Speex pass V.9x modem signals correctly?
-\end_layout
-
-\begin_layout Standard
-If I could do that I'd be very rich by now :-) Seriously, that would break
- fundamental laws of information theory.
 \end_layout
 
-\begin_layout Subsection*
-What is your (Jean-Marc) relationship with the University of Sherbrooke
- and how does Speex fit into that?
+\begin_layout Section
+sampledec.c
 \end_layout
 
 \begin_layout Standard
-I have completed my 
-\emph on
-Ph.D.
-
-\emph default
- at the University of Sherbrooke in 2005 in mobile robotics.
- Although I did my master with the Sherbrooke speech coding group (in speech
- enhancement, not coding), was no longer associated with them when developing
- Speex.
- It should 
+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 
 \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.
-\end_layout
-
-\begin_layout Subsection*
-CELP, ACELP
-\begin_inset LatexCommand \index{ACELP}
-
-\end_inset
-
-, what's the difference?
+ compatible with that of speexenc/speexdec.
 \end_layout
 
 \begin_layout Standard
-CELP stands for 
-\begin_inset Quotes eld
-\end_inset
-
-Code Excited Linear Prediction
-\begin_inset Quotes erd
-\end_inset
+\begin_inset CommandInset include
+LatexCommand lstinputlisting
+filename "sampledec.c"
+lstparams "caption={Source code for sampledec},label={sampledec-source-code},numbers=left,numberstyle={\\footnotesize}"
 
-, while ACELP stands for 
-\begin_inset Quotes eld
 \end_inset
 
 
-\emph on
-Algebraic
-\emph default
- Code Excited Linear Prediction
-\begin_inset Quotes erd
-\end_inset
-
-.
- That means ACELP is a CELP technique that uses an algebraic codebook represente
-d as a sum of unit pulses, thus making the codebook search much more efficient.
- This technique was invented at the University of Sherbrooke and is now
- one of the most widely used form of CELP.
- Unfortunately, since it is patented, it cannot be used in Speex.
 \end_layout
 
 \begin_layout Standard
-
-\newpage
-
-\end_layout
-
-\begin_layout Chapter
-Sample code
-\begin_inset LatexCommand \label{sec:Sample-code}
-
+\begin_inset Newpage newpage
 \end_inset
 
 
 \end_layout
 
-\begin_layout Standard
-This section shows sample code for encoding and decoding speech using the
- Speex API.
- The commands can be used to encode and decode a file by calling:
-\family typewriter
-
-\newline
-% sampleenc in_file.sw | sampledec out_file.sw
-\family default
-
-\newline
-where both files are raw (no header) files encoded at 16 bits per sample
- (in the machine natural endianness).
-\end_layout
-
-\begin_layout Section
-sampleenc.c
-\end_layout
-
-\begin_layout Standard
-sampleenc takes a raw 16 bits/sample file, encodes it and outputs a Speex
- stream to stdout.
- Note that the packing used is NOT compatible with that of speexenc/speexdec.
+\begin_layout Chapter
+Jitter Buffer for Speex
 \end_layout
 
 \begin_layout Standard
-\begin_inset Include \verbatiminput{sampleenc.c}
-preview false
+\begin_inset CommandInset include
+LatexCommand lstinputlisting
+filename "../speexclient/speex_jitter_buffer.c"
+lstparams "caption={Example of using the jitter buffer for Speex packets},label={example-speex-jitter},numbers=left,numberstyle={\\footnotesize}"
 
 \end_inset
 
 
 \end_layout
 
-\begin_layout Section
-sampledec.c
-\end_layout
-
-\begin_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.
-\end_layout
-
 \begin_layout Standard
-\begin_inset Include \verbatiminput{sampledec.c}
-preview false
-
+\begin_inset Newpage newpage
 \end_inset
 
 
 \end_layout
 
-\begin_layout Standard
-
-\newpage
-
-\end_layout
-
 \begin_layout Chapter
 IETF RTP Profile
-\begin_inset LatexCommand \label{sec:IETF-draft}
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:IETF-draft"
 
 \end_inset
 
@@ -7707,8 +11073,9 @@ IETF RTP Profile
 \end_layout
 
 \begin_layout Standard
-\begin_inset Include \verbatiminput{draft-herlein-speex-rtp-profile-02.txt}
-preview false
+\begin_inset CommandInset include
+LatexCommand verbatiminput
+filename "draft-ietf-avt-rtp-speex-05-tmp.txt"
 
 \end_inset
 
@@ -7716,14 +11083,17 @@ preview false
 \end_layout
 
 \begin_layout Standard
+\begin_inset Newpage newpage
+\end_inset
 
-\newpage
 
 \end_layout
 
 \begin_layout Chapter
 Speex License
-\begin_inset LatexCommand \label{sec:Speex-License}
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Speex-License"
 
 \end_inset
 
@@ -7731,45 +11101,19 @@ Speex License
 \end_layout
 
 \begin_layout Standard
-Redistribution and use in source and binary forms, with or without modification,
- are permitted provided that the following conditions are met:
-\end_layout
+\begin_inset CommandInset include
+LatexCommand verbatiminput
+filename "../COPYING"
 
-\begin_layout Itemize
-Redistributions of source code must retain the above copyright notice, this
- list of conditions and the following disclaimer.
-\end_layout
+\end_inset
 
-\begin_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.
-\end_layout
 
-\begin_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.
-\end_layout
-
-\begin_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.
 \end_layout
 
 \begin_layout Standard
+\begin_inset Newpage newpage
+\end_inset
 
-\newpage
 
 \end_layout
 
@@ -8262,7 +11606,8 @@ n.
 \end_layout
 
 \begin_layout Standard
-\begin_inset LatexCommand \printindex{}
+\begin_inset CommandInset index_print
+LatexCommand printindex
 
 \end_inset