Updated draft
[speexdsp.git] / doc / manual.lyx
index a6de549..43710b8 100644 (file)
@@ -1,20 +1,34 @@
-#LyX 1.4.2 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 article
+\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 default
-\spacing onehalf
+\paperfontsize 10
+\spacing single
+\use_hyperref false
 \papersize letterpaper
-\use_geometry false
-\use_amsmath 1
+\use_geometry true
+\use_amsmath 2
+\use_esint 0
 \cite_engine basic
 \use_bibtopic false
 \paperorientation portrait
+\leftmargin 2cm
+\topmargin 2cm
+\rightmargin 2cm
+\bottommargin 2cm
 \secnumdepth 3
 \tocdepth 3
 \paragraph_separation indent
 \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-beta1)
+The Speex Manual
+\begin_inset Newline newline
+\end_inset
+
+Version 1.2
 \end_layout
 
 \begin_layout Author
@@ -40,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-2005 Jean-Marc Valin/Xiph.org Foundation
+\end_inset
+
+ 2002-2008 Jean-Marc Valin/Xiph.org Foundation
 \end_layout
 
 \begin_layout Standard
@@ -56,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
 
@@ -74,191 +115,237 @@ on License".
 \end_inset
 
 
-\newpage
+\begin_inset Newpage newpage
+\end_inset
+
 
 \end_layout
 
-\begin_layout Section
+\begin_layout Chapter
 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
- (not many open-source cell phones anyway :-) ) 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
-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).
+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 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.
+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 this led us to the choice of CELP
-\begin_inset LatexCommand \index{CELP}
+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 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).
+ 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 Standard
-The main characteristics can be summarized as follows:
-\end_layout
-
-\begin_layout Itemize
-Free software/open-source
-\begin_inset LatexCommand \index{open-source}
+\begin_layout Section
+Getting help
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Getting-help"
 
 \end_inset
 
-, patent
-\begin_inset LatexCommand \index{patent}
 
-\end_inset
+\end_layout
 
- and royalty-free
+\begin_layout Standard
+As for many open source projects, there are many ways to get help with Speex.
+ These include:
 \end_layout
 
 \begin_layout Itemize
-Integration of narrowband
-\begin_inset LatexCommand \index{narrowband}
-
-\end_inset
-
- and wideband
-\begin_inset LatexCommand \index{wideband}
-
-\end_inset
-
- using an embedded bit-stream
+This manual
 \end_layout
 
 \begin_layout Itemize
-Wide range of bit-rates available (from 2 kbps to 44 kbps)
+Other documentation on the Speex website (http://www.speex.org/)
 \end_layout
 
 \begin_layout Itemize
-Dynamic bit-rate switching and Variable Bit-Rate
-\begin_inset LatexCommand \index{variable bit-rate}
-
-\end_inset
-
- (VBR)
+Mailing list: Discuss any Speex-related topic on speex-dev@xiph.org (not
+ just for developers)
 \end_layout
 
 \begin_layout Itemize
-Voice Activity Detection
-\begin_inset LatexCommand \index{voice activity detection}
-
-\end_inset
-
- (VAD, integrated with VBR)
+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
-Variable complexity
-\begin_inset LatexCommand \index{complexity}
-
-\end_inset
-
-
+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 Itemize
-Ultra-wideband mode at 32 kHz (up to 48 kHz)
+\begin_layout Standard
+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 Itemize
-Intensity stereo encoding option
+\begin_layout Standard
+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
+
+) 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 Itemize
-Fixed-point implementation (work in progress)
+\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 Section
+\begin_layout Chapter
 Codec description
-\begin_inset LatexCommand \label{sec:Feature-description}
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Feature-description"
 
 \end_inset
 
@@ -266,22 +353,28 @@ 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 Subsection
+\begin_layout Section
 Concepts
 \end_layout
 
 \begin_layout Standard
-Here are some concepts in speech coding that help better understand the
- rest of the manual.
- Emphasis is placed on the Speex features.
+Before introducing all the Speex features, here are some concepts in speech
+ coding that help better understand the rest of the manual.
+ 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
 
@@ -289,20 +382,52 @@ Sampling rate
 \end_layout
 
 \begin_layout Standard
-Speex is mainly designed for 3 different sampling rates: 8 kHz, 16 kHz,
- and 32 kHz.
- These are respectively refered to as narrowband
-\begin_inset LatexCommand \index{narrowband}
+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
+
+\begin_layout Plain Layout
+ultra-wideband
+\end_layout
 
 \end_inset
 
@@ -311,19 +436,82 @@ Speex is mainly designed for 3 different sampling rates: 8 kHz, 16 kHz,
 \end_layout
 
 \begin_layout Subsection*
+Bit-rate
+\end_layout
+
+\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
 
@@ -334,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
 
@@ -359,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
 
@@ -368,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
 
@@ -389,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.
@@ -400,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
 
@@ -417,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
 
@@ -444,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
 
@@ -460,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
 
@@ -468,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
@@ -484,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
 
@@ -509,979 +738,3804 @@ look-ahead
  the frames.
 \end_layout
 
-\begin_layout Subsection
+\begin_layout Section
 Codec
 \end_layout
 
-\begin_layout Subsection
-Preprocessor
-\end_layout
-
 \begin_layout Standard
-This part refers to the preprocessor module introduced in the 1.1.x branch.
- The preprocessor is designed to be used on the audio 
-\emph on
-before
-\emph default
- running the encoder.
- The preprocessor provides three main functionalities:
+The main characteristics of Speex can be summarized as follows:
 \end_layout
 
 \begin_layout Itemize
-denoising
-\end_layout
+Free software/open-source
+\begin_inset Index
+status collapsed
 
-\begin_layout Itemize
-automatic gain control (AGC)
+\begin_layout Plain Layout
+open-source
 \end_layout
 
-\begin_layout Itemize
-voice activity detection (VAD)
-\end_layout
+\end_inset
 
-\begin_layout Standard
-The denoiser can be used to reduce the amount of background noise present
- in the input signal.
- This provides higher quality speech whether or not the denoised signal
- is encoded with Speex (or at all).
- However, when using the denoised signal with the codec, there is an additional
- benefit.
- Speech codecs in general (Speex included) tend to perform poorly on noisy
- input, which tends to amplify the noise.
- The denoiser greatly reduces this effect.
-\end_layout
+, patent
+\begin_inset Index
+status collapsed
 
-\begin_layout Standard
-Automatic gain control (AGC) is a feature that deals with the fact that
- the recording volume may vary by a large amount between different setups.
- The AGC provides a way to adjust a signal to a reference volume.
- This is useful for voice over IP because it removes the need for manual
- adjustment of the microphone gain.
- A secondary advantage is that by setting the microphone gain to a conservative
- (low) level, it is easier to avoid clipping.
+\begin_layout Plain Layout
+patent
 \end_layout
 
-\begin_layout Standard
-The voice activity detector (VAD) provided by the preprocessor is more advanced
- than the one directly provided in the codec.
-\end_layout
+\end_inset
 
-\begin_layout Subsection
-Adaptive Jitter Buffer
+ and royalty-free
 \end_layout
 
-\begin_layout Subsection
-Acoustic Echo Canceller
+\begin_layout Itemize
+Integration of narrowband
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+narrowband
 \end_layout
 
-\begin_layout Standard
+\end_inset
 
-\newpage
+ and wideband
+\begin_inset Index
+status collapsed
 
+\begin_layout Plain Layout
+wideband
 \end_layout
 
-\begin_layout Section
-Compiling
-\end_layout
+\end_inset
 
-\begin_layout Standard
-Compiling Speex under UNIX or any platform supported by autoconf (e.g.
- Win32/cygwin) is as easy as typing:
+ using an embedded bit-stream
 \end_layout
 
-\begin_layout LyX-Code
-% ./configure [options]
+\begin_layout Itemize
+Wide range of bit-rates available (from 2.15 kbps to 44 kbps)
 \end_layout
 
-\begin_layout LyX-Code
-% make
-\end_layout
+\begin_layout Itemize
+Dynamic bit-rate switching (AMR) and Variable Bit-Rate
+\begin_inset Index
+status collapsed
 
-\begin_layout LyX-Code
-% make install
+\begin_layout Plain Layout
+variable bit-rate
 \end_layout
 
-\begin_layout Standard
-The options supported by the Speex configure script are:
+\end_inset
+
+ (VBR) operation
 \end_layout
 
-\begin_layout Description
---prefix=<path> Specifies where to install Speex
-\end_layout
+\begin_layout Itemize
+Voice Activity Detection
+\begin_inset Index
+status collapsed
 
-\begin_layout Description
---enable-shared/--disable-shared Whether to compile shared libraries
+\begin_layout Plain Layout
+voice activity detection
 \end_layout
 
-\begin_layout Description
---enable-static/--disable-static Whether to compile static libraries
-\end_layout
+\end_inset
 
-\begin_layout Description
---disable-wideband Disable the wideband part of Speex (typically to same
- space)
+ (VAD, integrated with VBR) and discontinuous transmission (DTX)
 \end_layout
 
-\begin_layout Description
---enable-valgrind Enable extra information when (and only when) running
- with valgrind
-\end_layout
+\begin_layout Itemize
+Variable complexity
+\begin_inset Index
+status collapsed
 
-\begin_layout Description
---enable-sse Enable use of SSE instructions (x86/float only)
+\begin_layout Plain Layout
+complexity
 \end_layout
 
-\begin_layout Description
---enable-fixed-point
-\begin_inset LatexCommand \index{fixed-point}
-
 \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)
+\begin_layout Itemize
+Embedded wideband structure (scalable sampling rate)
 \end_layout
 
-\begin_layout Description
---enable-arm5e-asm Enable assembly specific to the ARMv5E architecture (gcc
- only)
+\begin_layout Itemize
+Ultra-wideband sampling rate at 32 kHz
 \end_layout
 
-\begin_layout Description
---enable-fixed-point-debug Use only for debugging the fixed-point
-\begin_inset LatexCommand \index{fixed-point}
+\begin_layout Itemize
+Intensity stereo encoding option
+\end_layout
 
-\end_inset
+\begin_layout Itemize
+Fixed-point implementation
+\end_layout
 
- code (very slow)
+\begin_layout Section
+Preprocessor
 \end_layout
 
-\begin_layout Description
---enable-epic-48k Enable a special (and non-compatible) 4.8 kbps narrowband
- mode
+\begin_layout Standard
+This part refers to the preprocessor module introduced in the 1.1.x branch.
+ The preprocessor is designed to be used on the audio 
+\emph on
+before
+\emph default
+ running the encoder.
+ The preprocessor provides three main functionalities:
 \end_layout
 
-\begin_layout Description
---enable-ti-c55x Enable support for the TI C5x family
+\begin_layout Itemize
+noise suppression
 \end_layout
 
-\begin_layout Description
---enable-blackfin-asm Enable assembly specific to the Blackfin DSP architecture
- (gcc only)
+\begin_layout Itemize
+automatic gain control (AGC)
 \end_layout
 
-\begin_layout Description
---enable-16bit-precision Reduces precision to 16 bits in time-critical areas
- (fixed-point only)
+\begin_layout Itemize
+voice activity detection (VAD)
 \end_layout
 
 \begin_layout Standard
+The denoiser can be used to reduce the amount of background noise present
+ in the input signal.
+ This provides higher quality speech whether or not the denoised signal
+ is encoded with Speex (or at all).
+ However, when using the denoised signal with the codec, there is an additional
+ benefit.
+ Speech codecs in general (Speex included) tend to perform poorly on noisy
+ input, which tends to amplify the noise.
+ The denoiser greatly reduces this effect.
+\end_layout
 
-\newpage
+\begin_layout Standard
+Automatic gain control (AGC) is a feature that deals with the fact that
+ the recording volume may vary by a large amount between different setups.
+ The AGC provides a way to adjust a signal to a reference volume.
+ This is useful for voice over IP because it removes the need for manual
+ adjustment of the microphone gain.
+ A secondary advantage is that by setting the microphone gain to a conservative
+ (low) level, it is easier to avoid clipping.
+\end_layout
 
+\begin_layout Standard
+The voice activity detector (VAD) provided by the preprocessor is more advanced
+ than the one directly provided in the codec.
 \end_layout
 
 \begin_layout Section
-Command-line encoder/decoder
-\begin_inset LatexCommand \label{sec:Command-line-encoder/decoder}
-
-\end_inset
-
-
+Adaptive Jitter Buffer
 \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.
+When transmitting voice (or any content for that matter) over UDP or RTP,
+ packet may be lost, arrive with different delay, or even out of order.
+ The purpose of a jitter buffer is to reorder packets and buffer them long
+ enough (but no longer than necessary) so they can be sent to be decoded.
 \end_layout
 
-\begin_layout Subsection
+\begin_layout Section
+Acoustic Echo Canceller
+\end_layout
 
-\emph on
-speexenc
-\begin_inset LatexCommand \index{speexenc}
+\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
-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: 
-\end_layout
+\begin_inset Float figure
+wide false
+sideways false
+status open
 
-\begin_layout LyX-Code
-speexenc [options] input_file output_file
-\end_layout
+\begin_layout Plain Layout
+\begin_inset ERT
+status collapsed
 
-\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 Plain Layout
 
-\begin_layout Description
---narrowband\InsetSpace ~
-(-n) Tell Speex to treat the input as narrowband (8 kHz).
- This is the default
-\end_layout
 
-\begin_layout Description
---wideband\InsetSpace ~
-(-w) Tell Speex to treat the input as wideband (16 kHz)
+\backslash
+begin{center}
 \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)
-\end_layout
+\begin_inset Graphics
+       filename echo_path.eps
+       width 10cm
 
-\begin_layout Description
---quality\InsetSpace ~
-n Set the encoding quality (0-10), default is 8
-\end_layout
+\end_inset
 
-\begin_layout Description
---bitrate\InsetSpace ~
-n Encoding bit-rate (use bit-rate n or lower) 
-\end_layout
 
-\begin_layout Description
---vbr Enable VBR (Variable Bit-Rate), disabled by default
-\end_layout
+\begin_inset ERT
+status collapsed
 
-\begin_layout Description
---abr\InsetSpace ~
-n Enable ABR (Average Bit-Rate) at n kbps, disabled by default
-\end_layout
+\begin_layout Plain Layout
 
-\begin_layout Description
---vad Enable VAD (Voice Activity Detection), disabled by default
-\end_layout
 
-\begin_layout Description
---dtx Enable DTX (Discontinuous Transmission), disabled by default
+\backslash
+end{center}
 \end_layout
 
-\begin_layout Description
---nframes\InsetSpace ~
-n Pack n frames in each Ogg packet (this saves space at low bit-rates)
-\end_layout
+\end_inset
 
-\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_layout
 
-\begin_layout Description
--V Verbose operation, print bit-rate currently in use
 \end_layout
 
-\begin_layout Description
---help\InsetSpace ~
-(-h) Print the help
-\end_layout
+\begin_layout Plain Layout
+\begin_inset Caption
 
-\begin_layout Description
---version\InsetSpace ~
-(-v) Print version information
-\end_layout
+\begin_layout Plain Layout
+Acoustic echo model
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:Acoustic-echo-model"
 
-\begin_layout Subsubsection*
-Speex comments
-\end_layout
+\end_inset
 
-\begin_layout Description
---comment Add the given string as an extra comment.
- This may be used multiple times.
-\end_layout
 
-\begin_layout Description
---author Author of this track.
 \end_layout
 
-\begin_layout Description
---title Title for this track.
-\end_layout
+\end_inset
 
-\begin_layout Subsubsection*
-Raw input options
-\end_layout
 
-\begin_layout Description
---rate\InsetSpace ~
-n Sampling rate for raw input
 \end_layout
 
-\begin_layout Description
---stereo Consider raw input as stereo 
-\end_layout
+\end_inset
 
-\begin_layout Description
---le Raw input is little-endian 
-\end_layout
 
-\begin_layout Description
---be Raw input is big-endian 
 \end_layout
 
-\begin_layout Description
---8bit Raw input is 8-bit unsigned 
+\begin_layout Section
+Resampler
 \end_layout
 
-\begin_layout Description
---16bit Raw input is 16-bit signed 
+\begin_layout Standard
+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 Subsection
+\begin_layout Section
+Integration
+\end_layout
 
+\begin_layout Standard
+Knowing 
 \emph on
-speexdec
-\begin_inset LatexCommand \index{speexdec}
+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"
 
 \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 
-\emph on
-speexdec
-\emph default
- utility is used to decode Speex files and can be used by calling: 
-\end_layout
+\begin_inset Float figure
+wide false
+sideways false
+status open
 
-\begin_layout LyX-Code
-speexdec [options] speex_file [output_file]
-\end_layout
+\begin_layout Plain Layout
+\begin_inset ERT
+status collapsed
 
-\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
+\begin_layout Plain Layout
 
-\begin_layout Description
---enh enable post-filter (default)
+
+\backslash
+begin{center}
 \end_layout
 
-\begin_layout Description
---no-enh disable post-filter
-\end_layout
-
-\begin_layout Description
---force-nb Force decoding in narrowband 
-\end_layout
-
-\begin_layout Description
---force-wb Force decoding in wideband 
-\end_layout
+\end_inset
 
-\begin_layout Description
---force-uwb Force decoding in ultra-wideband 
-\end_layout
 
-\begin_layout Description
---mono Force decoding in mono 
-\end_layout
+\begin_inset Graphics
+       filename components.eps
+       width 80text%
 
-\begin_layout Description
---stereo Force decoding in stereo 
-\end_layout
+\end_inset
 
-\begin_layout Description
---rate\InsetSpace ~
-n Force decoding at n Hz sampling rate
-\end_layout
 
-\begin_layout Description
---packet-loss\InsetSpace ~
-n Simulate n % random packet loss
-\end_layout
+\begin_inset ERT
+status collapsed
 
-\begin_layout Description
--V Verbose operation, print bit-rate currently in use
-\end_layout
+\begin_layout Plain Layout
 
-\begin_layout Description
---help\InsetSpace ~
-(-h) Print the help
-\end_layout
 
-\begin_layout Description
---version\InsetSpace ~
-(-v) Print version information
+\backslash
+end{center}
 \end_layout
 
-\begin_layout Standard
+\end_inset
 
-\newpage
 
 \end_layout
 
-\begin_layout Section
-Programming with Speex (the libspeex
-\begin_inset LatexCommand \index{libspeex}
-
-\end_inset
+\begin_layout Plain Layout
+\begin_inset Caption
 
- API
-\begin_inset LatexCommand \index{API}
+\begin_layout Plain Layout
+Integration of all the components in a VoIP client.
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:Integration-VoIP"
 
 \end_inset
 
-)
-\begin_inset LatexCommand \label{sec:Programming-with-Speex}
+
+\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}
-
 \end_inset
 
-.
-\end_layout
 
-\begin_layout Subsection
-Encoding
-\begin_inset LatexCommand \label{sub:Encoding}
+\end_layout
 
+\begin_layout Standard
+\begin_inset Newpage newpage
 \end_inset
 
 
 \end_layout
 
+\begin_layout Chapter
+Compiling and Porting
+\end_layout
+
 \begin_layout Standard
-In order to encode speech using Speex, you first need to:
+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
-#include <speex/speex.h>
+% ./configure [options]
 \end_layout
 
-\begin_layout Standard
-You then need to declare a Speex bit-packing struct
+\begin_layout LyX-Code
+% make
 \end_layout
 
 \begin_layout LyX-Code
-SpeexBits bits;
+% make install
 \end_layout
 
 \begin_layout Standard
-and a Speex encoder state
+The options supported by the Speex configure script are:
 \end_layout
 
-\begin_layout LyX-Code
-void *enc_state;
+\begin_layout Description
+--prefix=<path> Specifies the base path for installing Speex (e.g.
+ /usr)
 \end_layout
 
-\begin_layout Standard
-The two are initialized by:
+\begin_layout Description
+--enable-shared/--disable-shared Whether to compile shared libraries
 \end_layout
 
-\begin_layout LyX-Code
-speex_bits_init(&bits);
+\begin_layout Description
+--enable-static/--disable-static Whether to compile static libraries
 \end_layout
 
-\begin_layout LyX-Code
-enc_state = speex_encoder_init(&speex_nb_mode);
+\begin_layout Description
+--disable-wideband Disable the wideband part of Speex (typically to save
+ space)
 \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:
+\begin_layout Description
+--enable-valgrind Enable extra hits for valgrind for debugging purposes
+ (do not use by default)
 \end_layout
 
-\begin_layout LyX-Code
-speex_encoder_ctl(enc_state,SPEEX_GET_FRAME_SIZE,&frame_size);
+\begin_layout Description
+--enable-sse Enable use of SSE instructions (x86/float only)
 \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.
+\begin_layout Description
+--enable-fixed-point
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+fixed-point
 \end_layout
 
-\begin_layout Standard
-Once the initialization is done, for every input frame:
+\end_inset
+
+ Compile Speex for a processor that does not have a floating point unit
+ (FPU)
 \end_layout
 
-\begin_layout LyX-Code
-speex_bits_reset(&bits);
+\begin_layout Description
+--enable-arm4-asm Enable assembly specific to the ARMv4 architecture (gcc
+ only)
 \end_layout
 
-\begin_layout LyX-Code
-speex_encode_int(enc_state, input_frame, &bits);
+\begin_layout Description
+--enable-arm5e-asm Enable assembly specific to the ARMv5E architecture (gcc
+ only)
 \end_layout
 
-\begin_layout LyX-Code
-nbBytes = speex_bits_write(&bits, byte_ptr, MAX_NB_BYTES);
+\begin_layout Description
+--enable-fixed-point-debug Use only for debugging the fixed-point
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+fixed-point
 \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.
+\end_inset
+
+ code (very slow)
 \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 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 Section
+Platforms
 \end_layout
 
 \begin_layout Standard
-After you're done with the encoding, free all resources with:
+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 LyX-Code
-speex_bits_destroy(&bits);
+\begin_layout Itemize
+x86 & x86-64
 \end_layout
 
-\begin_layout LyX-Code
-speex_encoder_destroy(enc_state);
+\begin_layout Itemize
+Power
 \end_layout
 
-\begin_layout Standard
-That's about it for the encoder.
+\begin_layout Itemize
+SPARC
 \end_layout
 
-\begin_layout Subsection
-Decoding
-\begin_inset LatexCommand \label{sub:Decoding}
+\begin_layout Itemize
+ARM
+\end_layout
 
-\end_inset
+\begin_layout Itemize
+Blackfin
+\end_layout
 
+\begin_layout Itemize
+Coldfire (68k family)
+\end_layout
 
+\begin_layout Itemize
+TI C54xx & C55xx
 \end_layout
 
-\begin_layout Standard
-In order to decode speech using Speex, you first need to:
+\begin_layout Itemize
+TI C6xxx
 \end_layout
 
-\begin_layout LyX-Code
-#include <speex/speex.h>
+\begin_layout Itemize
+TriMedia (experimental)
 \end_layout
 
 \begin_layout Standard
-You also need to declare a Speex bit-packing struct
+Operating systems on top of which Speex is known to work include (it probably
+ works on many others):
 \end_layout
 
-\begin_layout LyX-Code
-SpeexBits bits;
+\begin_layout Itemize
+Linux
 \end_layout
 
-\begin_layout Standard
-and a Speex decoder state
+\begin_layout Itemize
+\begin_inset Formula $\mu$
+\end_inset
+
+Clinux
 \end_layout
 
-\begin_layout LyX-Code
-void *dec_state;
+\begin_layout Itemize
+MacOS X
 \end_layout
 
-\begin_layout Standard
-The two are initialized by:
+\begin_layout Itemize
+BSD
 \end_layout
 
-\begin_layout LyX-Code
-speex_bits_init(&bits);
+\begin_layout Itemize
+Other UNIX/POSIX variants
 \end_layout
 
-\begin_layout LyX-Code
-dec_state = speex_decoder_init(&speex_nb_mode);
+\begin_layout Itemize
+Symbian
 \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 with:
+The source code directory include additional information for compiling on
+ certain architectures or operating systems in README.xxx files.
 \end_layout
 
-\begin_layout LyX-Code
-speex_decoder_ctl(dec_state, SPEEX_GET_FRAME_SIZE, &frame_size); 
+\begin_layout Section
+Porting and Optimising
 \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: 
+Here are a few things to consider when porting or optimising Speex for a
+ new platform or an existing one.
 \end_layout
 
-\begin_layout LyX-Code
-speex_decoder_ctl(dec_state, SPEEX_SET_ENH, &enh); 
+\begin_layout Subsection
+CPU optimisation
 \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.
+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 Standard
-Again, once the decoder initialization is done, for every input frame:
+Other important things to check on some DSP architectures are:
 \end_layout
 
-\begin_layout LyX-Code
-speex_bits_read_from(&bits, input_bytes, nbBytes);
+\begin_layout Itemize
+Make sure the cache is set to write-back mode
 \end_layout
 
-\begin_layout LyX-Code
-speex_decode_int(dec_state, &bits, output_frame);
+\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
-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.
+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 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.
-\end_layout
+\begin_layout Itemize
+\begin_inset listings
+inline true
+status collapsed
 
-\begin_layout Standard
-After you're done with the decoding, free all resources with:
-\end_layout
+\begin_layout Plain Layout
 
-\begin_layout LyX-Code
-speex_bits_destroy(&bits);
+filter_mem16()
 \end_layout
 
-\begin_layout LyX-Code
-speex_decoder_destroy(dec_state);
+\end_inset
+
+
 \end_layout
 
-\begin_layout Subsection
-Preprocessor
-\begin_inset LatexCommand \label{sub:Preprocessor}
+\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
-In order to use the Speex preprocessor
-\begin_inset LatexCommand \index{preprocessor}
+\begin_layout Itemize
+\begin_inset listings
+inline true
+status collapsed
 
-\end_inset
+\begin_layout Plain Layout
 
-, you first need to:
+vq_nbest()
 \end_layout
 
-\begin_layout LyX-Code
-#include <speex/speex_preprocess.h>
-\end_layout
+\end_inset
+
 
-\begin_layout Standard
-Then, a preprocessor state can be created as:
 \end_layout
 
-\begin_layout LyX-Code
-SpeexPreprocessState *preprocess_state = speex_preprocess_state_init(frame_size,
- sampling_rate);
+\begin_layout Itemize
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+pitch_xcorr()
 \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
-).
+\end_inset
+
+
 \end_layout
 
-\begin_layout Standard
-For each input frame, you need to call:
+\begin_layout Itemize
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+interp_pitch()
 \end_layout
 
-\begin_layout LyX-Code
-speex_preprocess(preprocess_state, audio_frame, echo_residue);
+\end_inset
+
+
 \end_layout
 
 \begin_layout Standard
-where 
-\family typewriter
-audio_frame
-\family default
- is used both as input and output and 
-\family typewriter
-echo_residue
-\family default
- is either an array filled by the echo canceller, or NULL if the preprocessor
- is used without the echo canceller.
+The filtering functions 
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+filter_mem16()
 \end_layout
 
-\begin_layout Standard
-In cases where the output audio is not useful for a certain frame, it is
- possible to use instead:
+\end_inset
+
+ and 
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+iir_mem16()
 \end_layout
 
-\begin_layout LyX-Code
-speex_preprocess_estimate_update(preprocess_state, audio_frame, echo_residue);
+\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 Standard
-This call will update all the preprocessor internal state variables without
- computing the output audio, thus saving some CPU cycles.
+\begin_layout Subsection
+Memory optimisation
 \end_layout
 
 \begin_layout Standard
-The behaviour of the preprocessor can be changed using:
+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 LyX-Code
-speex_preprocess_ctl(preprocess_state, request, ptr);
+\begin_layout Itemize
+Wideband support (--disable-wideband)
 \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 Itemize
+Support for stereo (removing stereo.c)
 \end_layout
 
-\begin_layout Standard
-The preprocessor state can be destroyed using:
+\begin_layout Itemize
+VBR support (--disable-vbr or DISABLE_VBR)
 \end_layout
 
-\begin_layout LyX-Code
-speex_preprocess_state_destroy(preprocess_state);
+\begin_layout Itemize
+Static codebooks that are not needed for the bit-rates you are using (*_table.c
+ files)
 \end_layout
 
-\begin_layout Subsection
-Echo Cancellation
-\begin_inset LatexCommand \label{sub:Echo-Cancellation}
+\begin_layout Standard
+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
 
+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
 
-\end_layout
+manual
+\begin_inset Quotes erd
+\end_inset
 
-\begin_layout Standard
-The Speex library now includes an echo cancellation
-\begin_inset LatexCommand \index{echo cancellation}
+ 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 Plain Layout
+In this case, one must be careful with threads
+\end_layout
 
 \end_inset
 
- algorithm suitable for Acoustic Echo Cancellation
-\begin_inset LatexCommand \index{acoustic echo cancellation}
+.
+ 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
+\begin_inset Newpage newpage
 \end_inset
 
- (AEC).
- In order to use the echo canceller, you first need to
+
 \end_layout
 
-\begin_layout LyX-Code
-#include <speex/speex_echo.h>
+\begin_layout Chapter
+Command-line encoder/decoder
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Command-line-encoder/decoder"
+
+\end_inset
+
+
 \end_layout
 
 \begin_layout Standard
-Then, an echo canceller state can be created by:
+The base Speex distribution includes a command-line encoder (
+\emph on
+speexenc
+\emph default
+) and decoder (
+\emph on
+speexdec
+\emph default
+).
+ 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
-SpeexEchoState *echo_state = speex_echo_state_init(frame_size, filter_length);
-\end_layout
+\begin_layout Section
 
-\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
+\emph on
+speexenc
+\begin_inset Index
+status collapsed
 
-\begin_inset LatexCommand \index{tail length}
+\begin_layout Plain Layout
+speexenc
+\end_layout
 
 \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:
+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: 
 \end_layout
 
 \begin_layout LyX-Code
-speex_echo_cancel(echo_state, input_frame, echo_frame, output_frame, residue);
+speexenc [options] input_file output_file
 \end_layout
 
 \begin_layout Standard
-where 
-\family typewriter
+The value '-' for input_file or output_file corresponds respectively to
+ stdin and stdout.
+ The valid options are:
+\end_layout
+
+\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 Description
+--wideband
+\begin_inset space ~
+\end_inset
+
+(-w) Tell Speex to treat the input as wideband (16 kHz)
+\end_layout
+
+\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 Description
+--quality
+\begin_inset space ~
+\end_inset
+
+n Set the encoding quality (0-10), default is 8
+\end_layout
+
+\begin_layout Description
+--bitrate
+\begin_inset space ~
+\end_inset
+
+n Encoding bit-rate (use bit-rate n or lower) 
+\end_layout
+
+\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 Description
+--dtx Enable DTX (Discontinuous Transmission), disabled by default
+\end_layout
+
+\begin_layout Description
+--nframes
+\begin_inset space ~
+\end_inset
+
+n Pack n frames in each Ogg packet (this saves space at low bit-rates)
+\end_layout
+
+\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 Description
+-V Verbose operation, print bit-rate currently in use
+\end_layout
+
+\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 Subsection*
+Speex comments
+\end_layout
+
+\begin_layout Description
+--comment Add the given string as an extra comment.
+ This may be used multiple times.
+\end_layout
+
+\begin_layout Description
+--author Author of this track.
+\end_layout
+
+\begin_layout Description
+--title Title for this track.
+\end_layout
+
+\begin_layout Subsection*
+Raw input options
+\end_layout
+
+\begin_layout Description
+--rate
+\begin_inset space ~
+\end_inset
+
+n Sampling rate for raw input
+\end_layout
+
+\begin_layout Description
+--stereo Consider raw input as stereo 
+\end_layout
+
+\begin_layout Description
+--le Raw input is little-endian 
+\end_layout
+
+\begin_layout Description
+--be Raw input is big-endian 
+\end_layout
+
+\begin_layout Description
+--8bit Raw input is 8-bit unsigned 
+\end_layout
+
+\begin_layout Description
+--16bit Raw input is 16-bit signed 
+\end_layout
+
+\begin_layout Section
+
+\emph on
+speexdec
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+speexdec
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+The 
+\emph on
+speexdec
+\emph default
+ utility is used to decode Speex files and can be used by calling: 
+\end_layout
+
+\begin_layout LyX-Code
+speexdec [options] speex_file [output_file]
+\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:
+\end_layout
+
+\begin_layout Description
+--enh enable post-filter (default)
+\end_layout
+
+\begin_layout Description
+--no-enh disable post-filter
+\end_layout
+
+\begin_layout Description
+--force-nb Force decoding in narrowband 
+\end_layout
+
+\begin_layout Description
+--force-wb Force decoding in wideband 
+\end_layout
+
+\begin_layout Description
+--force-uwb Force decoding in ultra-wideband 
+\end_layout
+
+\begin_layout Description
+--mono Force decoding in mono 
+\end_layout
+
+\begin_layout Description
+--stereo Force decoding in stereo 
+\end_layout
+
+\begin_layout Description
+--rate
+\begin_inset space ~
+\end_inset
+
+n Force decoding at n Hz sampling rate
+\end_layout
+
+\begin_layout Description
+--packet-loss
+\begin_inset space ~
+\end_inset
+
+n Simulate n % random packet loss
+\end_layout
+
+\begin_layout Description
+-V Verbose operation, print bit-rate currently in use
+\end_layout
+
+\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
+\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
+.
+ 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
+.
+ Examples of code can also be found in Appendix 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Sample-code"
+
+\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 Section
+Encoding
+\begin_inset CommandInset label
+LatexCommand label
+name "sub:Encoding"
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+In order to encode speech using Speex, one first needs to:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+#include <speex/speex.h>
+\end_layout
+
+\end_inset
+
+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 Plain Layout
+
+void *enc_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
+
+enc_state = speex_encoder_init(&speex_nb_mode);
+\end_layout
+
+\end_inset
+
+
+\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 at the sampling
+ rate you are using.
+ 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_encoder_ctl(enc_state,SPEEX_GET_FRAME_SIZE,&frame_size);
+\end_layout
+
+\end_inset
+
+
+\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.
+ 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 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
+Once the 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_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
+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.
+\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.
+\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 Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+)
+\end_layout
+
+\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
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+)
+\end_layout
+
+\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
+
+\begin_layout Plain Layout
+
+spx_int32_t
+\end_layout
+
+\end_inset
+
+)
+\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 
+\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_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
+
+\end_inset
+
+)
+\end_layout
+
+\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
+Echo Cancellation
+\begin_inset CommandInset label
+LatexCommand label
+name "sub:Echo-Cancellation"
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+The Speex library now includes an echo cancellation
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+echo cancellation
+\end_layout
+
+\end_inset
+
+ algorithm suitable for Acoustic Echo Cancellation
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+acoustic echo cancellation
+\end_layout
+
+\end_inset
+
+ (AEC).
+ In order to use the echo canceller, you first need to
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+#include <speex/speex_echo.h>
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Then, an echo canceller state can be created by:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+SpeexEchoState *echo_state = speex_echo_state_init(frame_size, filter_length);
+\end_layout
+
+\end_inset
+
+
+\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_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+tail length
+\end_layout
+
+\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 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
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+where 
+\family typewriter
 input_frame
 \family default
  is the audio as captured by the microphone, 
@@ -1494,465 +4548,971 @@ echo_frame
 output_frame
 \family default
  is the signal with echo removed.
- The 
+\end_layout
+
+\begin_layout Standard
+One important thing to keep in mind is the relationship between 
 \family typewriter
-residue
+input_frame
 \family default
- parameter is optional (you can set it to NULL) and is used to return the
- estimated power spectrum of the echo residue so it can be removed by the
- preprocessor (if you with to use it).
+ 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 Plain Layout
+
+read_from_soundcard(input_frame, frame_size);
+\end_layout
+
+\begin_layout Plain Layout
+
+speex_echo_cancellation(echo_state, input_frame, echo_frame, output_frame);
+\end_layout
+
+\end_inset
+
+
+\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"
+
+\end_inset
+
+).
+ This is done by calling:
+\begin_inset listings
+lstparams "breaklines=true"
+inline false
+status open
+
+\begin_layout Plain Layout
+
+speex_preprocess_ctl(preprocess_state, SPEEX_PREPROCESS_SET_ECHO_STATE,echo_stat
+e);
+\end_layout
+
+\end_inset
+
+in the initialisation.
+\end_layout
+
+\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 Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+speex_echo_playback(echo_state, echo_frame);
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+every time an audio frame is played.
+ Then, the capture context/thread calls:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+speex_echo_capture(echo_state, input_frame, output_frame);
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\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 Standard
+The echo cancellation state can be destroyed with:
 \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
+inline false
+status open
+
+\begin_layout Plain Layout
+
+speex_echo_state_destroy(echo_state);
 \end_layout
 
-\begin_layout LyX-Code
-write_to_soundcard(echo_frame, frame_size);
+\end_inset
+
+
 \end_layout
 
-\begin_layout LyX-Code
-read_from_soundcard(input_frame, frame_size);
+\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
 
-\begin_layout LyX-Code
-speex_echo_cancel(echo_state, input_frame, echo_frame, output_frame, residue);
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+speex_echo_state_reset(echo_state);
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Troubleshooting
 \end_layout
 
 \begin_layout Standard
-As stated above, if you wish to further reduce the echo present in the signal,
- you can do so by passing 
-\family typewriter
-residue
-\family default
- as the last parameter of 
-\family typewriter
-speex_preprocess()
-\family default
- function (see Section 
-\begin_inset LatexCommand \ref{sub:Preprocessor}
+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 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
 
+locked
+\begin_inset Quotes erd
 \end_inset
 
-).
+ 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 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
+
+ on the playback (far end) signal slightly before the echo canceller 
+\begin_inset Quotes eld
+\end_inset
+
+sees
+\begin_inset Quotes erd
+\end_inset
+
+ 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 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 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
-As of version 1.2-beta1, there is an alternative, simpler API that can be
- used instead of 
-\emph on
-speex_echo_cancel()
-\emph default
-.
- When audio capture and playback are handled asynchronously (e.g.
- in different threads or using the 
-\emph on
-poll()
-\emph default
- or 
+Also useful is reading 
 \emph on
-select()
+Echo Cancellation Demystified
 \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:
+ by Alexey Frunze
+\begin_inset Foot
+status collapsed
+
+\begin_layout Plain Layout
+http://www.embeddedstar.com/articles/2003/7/article20030720-1.html
+\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:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+lstparams "language=Matlab"
+inline false
+status open
+
+\begin_layout Plain Layout
+
+echo_diagnostic('aec_rec.sw', 'aec_play.sw', 'aec_diagnostic.sw', 1024);
+\end_layout
+
+\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.
+\end_layout
+
+\begin_layout Section
+Jitter Buffer
+\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 Plain Layout
+
+#include <speex/speex_jitter.h>
+\end_layout
+
+\end_inset
+
+ and a new jitter buffer state can be initialised by:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+lstparams "breaklines=true"
+inline false
+status open
+
+\begin_layout Plain Layout
+
+JitterBuffer *state = jitter_buffer_init(step);
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+where the 
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+step
+\end_layout
+
+\end_inset
+
+ 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
+The jitter buffer API is based on the 
+\begin_inset listings
+inline true
+status open
+
+\begin_layout Plain Layout
+
+JitterBufferPacket
+\end_layout
+
+\end_inset
+
+ type, which is defined as:
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+typedef struct {
+\end_layout
+
+\begin_layout Plain Layout
+
+   char        *data;       /* Data bytes contained in the packet */
+\end_layout
+
+\begin_layout Plain Layout
+
+   spx_uint32_t len;        /* Length of the packet in bytes */
+\end_layout
+
+\begin_layout Plain Layout
+
+   spx_uint32_t timestamp;  /* Timestamp for the packet */
+\end_layout
+
+\begin_layout Plain Layout
+
+   spx_uint32_t span;       /* Time covered by the packet (timestamp units)
+ */
+\end_layout
+
+\begin_layout Plain Layout
+
+} JitterBufferPacket; 
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+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
+
+\begin_layout Standard
+When a packet arrives, it need to be inserter into the jitter buffer by:
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+JitterBufferPacket packet;
+\end_layout
+
+\begin_layout Plain Layout
+
+/* Fill in each field in the packet struct */
+\end_layout
+
+\begin_layout Plain Layout
+
+jitter_buffer_put(state, &packet);
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+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
+
+\begin_layout Plain Layout
+
+int start_offset;
 \end_layout
 
-\begin_layout LyX-Code
-speex_echo_playback(echo_state, echo_frame);
+\begin_layout Plain Layout
+
+err = jitter_buffer_get(state, &packet, desired_span, &start_offset);
+\end_layout
+
+\end_inset
+
+
 \end_layout
 
 \begin_layout Standard
-every time an audio frame is played.
- Then, the capture context/thread calls:
+If 
+\begin_inset listings
+inline true
+status open
+
+\begin_layout Plain Layout
+
+jitter_buffer_put()
 \end_layout
 
-\begin_layout LyX-Code
-speex_echo_capture(echo_state, input_frame, output_frame, residue);
+\end_inset
+
+ and 
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+jitter_buffer_get()
 \end_layout
 
-\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
+\end_inset
+
+ are called from different threads, then 
+\series bold
+you need to protect the jitter buffer state with a mutex
+\series default
 .
- When capture and playback are done synchronously, 
-\emph on
-speex_echo_cancel()
-\emph default
- is still prefered since it gives better control on the exact input/echo
- timing.
 \end_layout
 
 \begin_layout Standard
-The echo cancellation state can be destroyed with:
+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
+
+\begin_layout Plain Layout
+
+jitter_buffer_tick(state);
 \end_layout
 
-\begin_layout LyX-Code
-speex_echo_state_destroy(echo_state);
+\end_inset
+
+
 \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
+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 LyX-Code
-speex_echo_state_reset(echo_state);
+\begin_layout Plain Layout
+
+jitter_buffer_remaining_span(state, remaining);
 \end_layout
 
-\begin_layout Subsubsection
-Troubleshooting
+\end_inset
+
+
 \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
+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
 
-\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
 
-locked
-\begin_inset Quotes erd
-\end_inset
+), but 
+\begin_inset listings
+inline true
+status collapsed
 
- on the same clock source.
+\begin_layout Plain Layout
+
+jitter_buffer_get()
 \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
+ returned 320 samples, we would have 
+\begin_inset listings
+inline true
+status open
 
- on the playback (far end) signal slightly before the echo canceller 
-\begin_inset Quotes eld
-\end_inset
+\begin_layout Plain Layout
+
+remaining=64
+\end_layout
 
-sees
-\begin_inset Quotes erd
 \end_inset
 
- 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 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.
+\begin_layout Section
+Resampler
 \end_layout
 
-\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.
+\begin_layout Standard
+Speex includes a resampling modules.
+ To make use of the resampler, it is necessary to include its header file:
 \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_inset listings
+inline false
+status open
 
-\begin_layout Standard
-http://www.embeddedstar.com/articles/2003/7/article20030720-1.html
+\begin_layout Plain Layout
+
+#include <speex/speex_resampler.h>
 \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 Subsection
-Codec Options (speex_*_ctl)
-\begin_inset LatexCommand \label{sub:Codec-Options}
+\begin_layout Standard
+For each stream that is to be resampled, it is necessary to create a resampler
+ state with:
+\end_layout
 
-\end_inset
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
 
+\begin_layout Plain Layout
 
+SpeexResamplerState *resampler;
 \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 Plain Layout
 
-\begin_layout LyX-Code
-void speex_encoder_ctl(void *encoder, int request, void *ptr);
+resampler = speex_resampler_init(nb_channels, input_rate, output_rate, quality,
+ &err);
 \end_layout
 
-\begin_layout LyX-Code
-void speex_decoder_ctl(void *encoder, int request, void *ptr);
+\end_inset
+
+
 \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
+where 
+\begin_inset listings
+inline true
+status collapsed
 
-\begin_layout Description
-SPEEX_SET_ENH** Set perceptual enhancer
-\begin_inset LatexCommand \index{perceptual enhancement}
+\begin_layout Plain Layout
+
+nb_channels
+\end_layout
 
 \end_inset
 
- to on (1) or off (0) (integer)
+ 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
 
-\begin_layout Description
-SPEEX_GET_ENH** Get perceptual enhancer status (integer)
+\end_inset
+
+ is the sampling rate of the input stream, 
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+output_rate
 \end_layout
 
-\begin_layout Description
-SPEEX_GET_FRAME_SIZE Get the frame size used for the current mode (integer)
+\end_inset
+
+ is the sampling rate of the output stream and 
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+quality
 \end_layout
 
-\begin_layout Description
-SPEEX_SET_QUALITY* Set the encoder speech quality (integer 0 to 10)
+\end_inset
+
+ 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
 
-\begin_layout Description
-SPEEX_GET_QUALITY* Get the current encoder speech quality (integer 0 to
- 10)
+\begin_layout Standard
+The actual resampling is performed using
 \end_layout
 
-\begin_layout Description
-SPEEX_SET_MODE*
-\begin_inset Formula $\dagger$
-\end_inset
+\begin_layout Standard
+\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
 
-\begin_layout Description
-SPEEX_GET_MODE*
-\begin_inset Formula $\dagger$
 \end_inset
 
+where 
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
 
+channelID
 \end_layout
 
-\begin_layout Description
-SPEEX_SET_LOW_MODE*
-\begin_inset Formula $\dagger$
 \end_inset
 
+ 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
 
-\begin_layout Description
-SPEEX_GET_LOW_MODE*
-\begin_inset Formula $\dagger$
 \end_inset
 
+ 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
 
-\begin_layout Description
-SPEEX_SET_HIGH_MODE*
-\begin_inset Formula $\dagger$
 \end_inset
 
+ and 
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
 
+out_length
 \end_layout
 
-\begin_layout Description
-SPEEX_GET_HIGH_MODE*
-\begin_inset Formula $\dagger$
 \end_inset
 
+ 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
 
-\end_layout
+\begin_layout Plain Layout
 
-\begin_layout Description
-SPEEX_SET_VBR* Set variable bit-rate (VBR) to on (1) or off (0) (integer)
+speex_resampler_process_float()
 \end_layout
 
-\begin_layout Description
-SPEEX_GET_VBR* Get variable bit-rate
-\begin_inset LatexCommand \index{variable bit-rate}
-
 \end_inset
 
- (VBR) status (integer)
+ behaves similarly.
 \end_layout
 
-\begin_layout Description
-SPEEX_SET_VBR_QUALITY* Set the encoder VBR speech quality (float 0 to 10)
-\end_layout
+\begin_layout Standard
+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 Description
-SPEEX_GET_VBR_QUALITY* Get the current encoder VBR speech quality (float
- 0 to 10)
+\begin_layout Plain Layout
+
+speex_resampler_process_interleaved_float()
 \end_layout
 
-\begin_layout Description
-SPEEX_SET_COMPLEXITY* Set the CPU resources allowed for the encoder (integer
- 1 to 10)
+\end_inset
+
+.
+ The arguments are the same except that there is no 
+\begin_inset listings
+inline true
+status collapsed
+
+\begin_layout Plain Layout
+
+channelID
 \end_layout
 
-\begin_layout Description
-SPEEX_GET_COMPLEXITY* Get the CPU resources allowed for the encoder (integer
- 1 to 10)
+\end_inset
+
+ 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 Description
-SPEEX_SET_BITRATE* Set the bit-rate to use to the closest value not exceeding
- the parameter (integer in bps)
+\begin_layout Standard
+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
 
-\begin_layout Description
-SPEEX_GET_BITRATE Get the current bit-rate in use (integer in bps)
+\end_inset
+
+ and 
+\begin_inset listings
+inline true
+status open
+
+\begin_layout Plain Layout
+
+speex_resampler_set_rate()
 \end_layout
 
-\begin_layout Description
-SPEEX_SET_SAMPLING_RATE Set real sampling rate (integer in Hz)
+\end_inset
+
+.
+ The only side effect is that a new filter will have to be recomputed, consuming
+ many CPU cycles.
 \end_layout
 
-\begin_layout Description
-SPEEX_GET_SAMPLING_RATE Get real sampling rate (integer in Hz)
-\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 Description
-SPEEX_RESET_STATE Reset the encoder/decoder state to its original state
- (zeros all memories)
-\end_layout
+\begin_layout Plain Layout
 
-\begin_layout Description
-SPEEX_SET_VAD* Set voice activity detection
-\begin_inset LatexCommand \index{voice activity detection}
+speex_resampler_skip_zeros()
+\end_layout
 
 \end_inset
 
- (VAD) to on (1) or off (0) (integer)
-\end_layout
+\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 Description
-SPEEX_GET_VAD* Get voice activity detection (VAD) status (integer)
-\end_layout
+\begin_layout Plain Layout
 
-\begin_layout Description
-SPEEX_SET_DTX* Set discontinuous transmission
-\begin_inset LatexCommand \index{discontinuous transmission}
+speex_resampler_destroy()
+\end_layout
 
 \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 Section
+Ring Buffer
 \end_layout
 
-\begin_layout Description
-SPEEX_SET_ABR* Set average bit-rate
-\begin_inset LatexCommand \index{average bit-rate}
-
+\begin_layout Standard
+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
 
- (ABR) to a value n in bits per second (integer in bps)
+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 Description
-SPEEX_GET_ABR* Get average bit-rate (ABR) setting (integer in bps)
-\end_layout
+\begin_layout Standard
+\begin_inset Newpage newpage
+\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
-\end_layout
+\begin_layout Chapter
+Formats and standards
+\begin_inset Index
+status collapsed
 
-\begin_layout Description
-** applies only to the decoder
+\begin_layout Plain Layout
+standards
 \end_layout
 
-\begin_layout Description
-\begin_inset Formula $\dagger$
 \end_inset
 
- normally only used internally
-\end_layout
 
-\begin_layout Subsection
-Mode queries
-\begin_inset LatexCommand \label{sub:Mode-queries}
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Formats-and-standards"
 
 \end_inset
 
@@ -1960,220 +5520,283 @@ 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
+Speex can encode speech in both narrowband and wideband and provides different
+ bit-rates.
+ However, not all features need to be supported by a certain implementation
+ or device.
+ In order to be called 
+\begin_inset Quotes eld
+\end_inset
 
-\begin_layout LyX-Code
-void speex_mode_query(SpeexMode *mode, int request, void *ptr);
+Speex compatible
+\begin_inset Quotes erd
+\end_inset
+
+ (whatever that means), an implementation must implement at least a basic
+ set of features.
 \end_layout
 
 \begin_layout Standard
-The admissible values for request are (unless otherwise note, the values
- are returned through 
-\emph on
-ptr
-\emph default
-):
+At the minimum, all narrowband modes of operation MUST be supported at the
+ decoder.
+ This includes the decoding of a wideband bit-stream by the narrowband decoder
+\begin_inset Foot
+status collapsed
+
+\begin_layout Plain Layout
+The wideband bit-stream contains an embedded narrowband bit-stream which
+ can be decoded alone
 \end_layout
 
-\begin_layout Description
-SPEEX_MODE_FRAME_SIZE Get the frame size (in samples) for the mode
+\end_inset
+
+.
+ If present, a wideband decoder MUST be able to decode a narrowband stream,
+ and MAY either be able to decode all wideband modes or be able to decode
+ the embedded narrowband part of all modes (which includes ignoring the
+ high-band bits).
 \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).
+\begin_layout Standard
+For encoders, at least one narrowband or wideband mode MUST be supported.
+ The main reason why all encoding modes do not have to be supported is that
+ some platforms may not be able to handle the complexity of encoding in
+ some modes.
 \end_layout
 
-\begin_layout Subsection
-Preprocessor options
-\begin_inset LatexCommand \label{sub:Preprocessor-options}
+\begin_layout Section
+RTP
+\begin_inset Index
+status collapsed
 
-\end_inset
+\begin_layout Plain Layout
+RTP
+\end_layout
 
+\end_inset
 
+ Payload Format 
 \end_layout
 
-\begin_layout Description
-SPEEX_PREPROCESS_SET_DENOISE Turns denoising on(1) or off(2) (integer)
-\end_layout
+\begin_layout Standard
+The RTP payload draft is included in appendix 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:IETF-draft"
 
-\begin_layout Description
-SPEEX_PREPROCESS_GET_DENOISE Get denoising status (integer)
-\end_layout
+\end_inset
 
-\begin_layout Description
-SPEEX_PREPROCESS_SET_AGC Turns automatic gain control (AGC) on(1) or off(2)
- (integer)
-\end_layout
+ and the latest version is available at 
+\begin_inset Flex URL
+status collapsed
 
-\begin_layout Description
-SPEEX_PREPROCESS_GET_AGC Get AGC status (integer)
-\end_layout
+\begin_layout Plain Layout
 
-\begin_layout Description
-SPEEX_PREPROCESS_SET_VAD Turns voice activity detector (VAD) on(1) or off(2)
- (integer)
+http://www.speex.org/drafts/latest
 \end_layout
 
-\begin_layout Description
-SPEEX_PREPROCESS_GET_VAD Get VAD status (integer)
-\end_layout
+\end_inset
 
-\begin_layout Description
-SPEEX_PREPROCESS_SET_AGC_LEVEL
+.
+ This draft has been sent (2003/02/26) to the Internet Engineering Task
+ Force (IETF) and will be discussed at the March 18th meeting in San Francisco.
 \end_layout
 
-\begin_layout Description
-SPEEX_PREPROCESS_GET_AGC_LEVEL
+\begin_layout Section
+MIME Type
 \end_layout
 
-\begin_layout Description
-SPEEX_PREPROCESS_SET_DEREVERB Turns reverberation removal on(1) or off(2)
- (integer)
+\begin_layout Standard
+For now, you should use the MIME type audio/x-speex for Speex-in-Ogg.
+ We will apply for type 
+\family typewriter
+audio/speex
+\family default
+ in the near future.
 \end_layout
 
-\begin_layout Description
-SPEEX_PREPROCESS_GET_DEREVERB Get reverberation removal status (integer)
-\end_layout
+\begin_layout Section
+Ogg
+\begin_inset Index
+status collapsed
 
-\begin_layout Description
-SPEEX_PREPROCESS_SET_DEREVERB_LEVEL
+\begin_layout Plain Layout
+Ogg
 \end_layout
 
-\begin_layout Description
-SPEEX_PREPROCESS_GET_DEREVERB_LEVEL
-\end_layout
+\end_inset
 
-\begin_layout Description
-SPEEX_PREPROCESS_SET_DEREVERB_DECAY
+ file format
 \end_layout
 
-\begin_layout Description
-SPEEX_PREPROCESS_GET_DEREVERB_DECAY
-\end_layout
+\begin_layout Standard
+Speex bit-streams can be stored in Ogg files.
+ In this case, the first packet of the Ogg file contains the Speex header
+ described in table 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "cap:ogg_speex_header"
 
-\begin_layout Subsection
-Packing and in-band signalling
-\begin_inset LatexCommand \index{in-band signalling}
+\end_inset
 
+.
+ All integer fields in the headers are stored as little-endian.
+ The 
+\family typewriter
+speex_string
+\family default
+ field must contain the 
+\begin_inset Quotes eld
 \end_inset
 
 
-\end_layout
+\family typewriter
+Speex
+\family default
 
-\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$
+\begin_inset space ~
 \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 space ~
+\end_inset
+
+
+\begin_inset space ~
+\end_inset
+
+
+\begin_inset Quotes erd
 \end_inset
 
+ (with 3 trailing spaces), which identifies the bit-stream.
+ The next field, 
+\family typewriter
+speex_version
+\family default
+ contains the version of Speex that encoded the file.
+ For now, refer to speex_header.[ch] for more info.
+ The 
+\emph on
+beginning of stream
+\emph default
+ (
+\family typewriter
+b_o_s
+\family default
+) flag is set to 1 for the header.
+ The header packet has 
+\family typewriter
+packetno=0
+\family default
+ and 
+\family typewriter
+granulepos=0
+\family default
 .
- 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
+The second packet contains the Speex comment header.
+ The format used is the Vorbis comment format described here: http://www.xiph.org/
+ogg/vorbis/doc/v-comment.html .
+ This packet has 
+\family typewriter
+packetno=1
+\family default
+ and 
+\family typewriter
+granulepos=0
+\family default
+.
+\end_layout
+
+\begin_layout Standard
+The third and subsequent packets each contain one or more (number found
+ in header) Speex frames.
+ These are identified with 
+\family typewriter
+packetno
+\family default
+ starting from 2 and the 
+\family typewriter
+granulepos
+\family default
+ is the number of the last sample encoded in that packet.
+ The last of these packets has the 
+\emph on
+end of stream
+\emph default
+ (
+\family typewriter
+e_o_s
+\family default
+) flag is set to 1.
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float table
+placement htbp
+wide true
+sideways false
+status open
 
-messages
-\begin_inset Quotes erd
-\end_inset
+\begin_layout Plain Layout
+\begin_inset ERT
+status collapsed
 
- to the other side.
- All these messages are encoded as 
-\begin_inset Quotes eld
-\end_inset
+\begin_layout Plain Layout
 
-pseudo-frames
-\begin_inset Quotes erd
-\end_inset
 
- of mode 14 which contain a 4-bit message type code, followed by the message.
- Table 
-\begin_inset LatexCommand \ref{cap:In-band-signalling-codes}
+\backslash
+begin{center}
+\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.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float table
-placement htbp
-wide false
-sideways false
-status open
 
-\begin_layout Standard
 \begin_inset Tabular
-<lyxtabular version="3" rows="17" columns="3">
+<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
-Code
+\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
-Size (bits)
+\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
-Content
+\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
-0
+\begin_layout Plain Layout
+speex_string
 \end_layout
 
 \end_inset
@@ -2181,8 +5804,8 @@ Content
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-1
+\begin_layout Plain Layout
+char[]
 \end_layout
 
 \end_inset
@@ -2190,19 +5813,19 @@ Content
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-Asks decoder to set perceptual enhancement off (0) or on(1)
+\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
-1
+\begin_layout Plain Layout
+speex_version
 \end_layout
 
 \end_inset
@@ -2210,8 +5833,8 @@ Asks decoder to set perceptual enhancement off (0) or on(1)
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-1
+\begin_layout Plain Layout
+char[]
 \end_layout
 
 \end_inset
@@ -2219,27 +5842,19 @@ Asks decoder to set perceptual enhancement off (0) or on(1)
 <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
+\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
-2
+\begin_layout Plain Layout
+speex_version_id
 \end_layout
 
 \end_inset
@@ -2247,8 +5862,8 @@ agressive
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-4
+\begin_layout Plain Layout
+int
 \end_layout
 
 \end_inset
@@ -2256,19 +5871,19 @@ agressive
 <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
+\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
-3
+\begin_layout Plain Layout
+header_size
 \end_layout
 
 \end_inset
@@ -2276,8 +5891,8 @@ Asks encoder to switch to mode N
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-4
+\begin_layout Plain Layout
+int
 \end_layout
 
 \end_inset
@@ -2285,19 +5900,19 @@ Asks encoder to switch to mode N
 <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
+\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
-4
+\begin_layout Plain Layout
+rate
 \end_layout
 
 \end_inset
@@ -2305,8 +5920,8 @@ Asks encoder to switch to mode N for low-band
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-4
+\begin_layout Plain Layout
+int
 \end_layout
 
 \end_inset
@@ -2314,19 +5929,19 @@ Asks encoder to switch to mode N for low-band
 <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 high-band
+\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
-5
+\begin_layout Plain Layout
+mode
 \end_layout
 
 \end_inset
@@ -2334,8 +5949,8 @@ Asks encoder to switch to mode N for high-band
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-4
+\begin_layout Plain Layout
+int
 \end_layout
 
 \end_inset
@@ -2343,19 +5958,19 @@ Asks encoder to switch to mode N for high-band
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-Asks encoder to switch to quality N for VBR
+\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
-6
+\begin_layout Plain Layout
+mode_bitstream_version
 \end_layout
 
 \end_inset
@@ -2363,8 +5978,8 @@ Asks encoder to switch to quality N for VBR
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-4
+\begin_layout Plain Layout
+int
 \end_layout
 
 \end_inset
@@ -2372,19 +5987,19 @@ Asks encoder to switch to quality N for VBR
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-Request acknowloedge (0=no, 1=all, 2=only for in-band data)
+\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
-7
+\begin_layout Plain Layout
+nb_channels
 \end_layout
 
 \end_inset
@@ -2392,8 +6007,8 @@ Request acknowloedge (0=no, 1=all, 2=only for in-band data)
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-4
+\begin_layout Plain Layout
+int
 \end_layout
 
 \end_inset
@@ -2401,19 +6016,19 @@ Request acknowloedge (0=no, 1=all, 2=only for in-band data)
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-Asks encoder to set CBR (0), VAD(1), DTX(3), VBR(5), VBR+DTX(7)
+\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
-8
+\begin_layout Plain Layout
+bitrate
 \end_layout
 
 \end_inset
@@ -2421,8 +6036,8 @@ Asks encoder to set CBR (0), VAD(1), DTX(3), VBR(5), VBR+DTX(7)
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-8
+\begin_layout Plain Layout
+int
 \end_layout
 
 \end_inset
@@ -2430,19 +6045,19 @@ Asks encoder to set CBR (0), VAD(1), DTX(3), VBR(5), VBR+DTX(7)
 <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
+\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
-9
+\begin_layout Plain Layout
+frame_size
 \end_layout
 
 \end_inset
@@ -2450,8 +6065,8 @@ Transmit (8-bit) character to the other end
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-8
+\begin_layout Plain Layout
+int
 \end_layout
 
 \end_inset
@@ -2459,19 +6074,19 @@ Transmit (8-bit) character to the other end
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-Intensity stereo information
+\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
-10
+\begin_layout Plain Layout
+vbr
 \end_layout
 
 \end_inset
@@ -2479,8 +6094,8 @@ Intensity stereo information
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-16
+\begin_layout Plain Layout
+int
 \end_layout
 
 \end_inset
@@ -2488,19 +6103,19 @@ Intensity stereo information
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-Announce maximum bit-rate acceptable (N in bytes/second)
+\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
-11
+\begin_layout Plain Layout
+frames_per_packet
 \end_layout
 
 \end_inset
@@ -2508,8 +6123,8 @@ Announce maximum bit-rate acceptable (N in bytes/second)
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-16
+\begin_layout Plain Layout
+int
 \end_layout
 
 \end_inset
@@ -2517,19 +6132,19 @@ Announce maximum bit-rate acceptable (N in bytes/second)
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-reserved
+\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
-12
+\begin_layout Plain Layout
+extra_headers
 \end_layout
 
 \end_inset
@@ -2537,8 +6152,8 @@ reserved
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-32
+\begin_layout Plain Layout
+int
 \end_layout
 
 \end_inset
@@ -2546,19 +6161,19 @@ reserved
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-Acknowledge receiving packet N
+\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
-13
+\begin_layout Plain Layout
+reserved1
 \end_layout
 
 \end_inset
@@ -2566,8 +6181,8 @@ Acknowledge receiving packet N
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-32
+\begin_layout Plain Layout
+int
 \end_layout
 
 \end_inset
@@ -2575,793 +6190,762 @@ Acknowledge receiving packet N
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-reserved
+\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
-14
+\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
-64
+\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
-reserved
+\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">
-\begin_inset Text
+</lyxtabular>
 
-\begin_layout Standard
-15
+\end_inset
+
+
+\begin_inset ERT
+status collapsed
+
+\begin_layout Plain Layout
+
+
+\backslash
+end{center}
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
+
+\end_layout
+
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Ogg/Speex header packet
+\begin_inset CommandInset label
+LatexCommand label
+name "cap:ogg_speex_header"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
 
 \begin_layout Standard
-64
+\begin_inset ERT
+status collapsed
+
+\begin_layout Plain Layout
+
+
+\backslash
+clearpage
 \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
+
+\end_layout
+
+\begin_layout Chapter
+Introduction to CELP Coding
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+CELP
 \end_layout
 
 \end_inset
-</cell>
-</row>
-</lyxtabular>
+
+
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Introduction-to-CELP"
 
 \end_inset
 
 
 \end_layout
 
-\begin_layout Caption
-In-band signalling codes
-\begin_inset LatexCommand \label{cap:In-band-signalling-codes}
+\begin_layout Quote
+\align center
+
+\emph on
+Do not meddle in the affairs of poles, for they are subtle and quick to
+ leave the unit circle.
+\end_layout
+
+\begin_layout Standard
+Speex is based on CELP, which stands for Code Excited Linear Prediction.
+ This section attempts to introduce the principles behind CELP, so if you
+ are already familiar with CELP, you can safely skip to section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Speex-narrowband-mode"
 
 \end_inset
 
+.
+ The CELP technique is based on three ideas:
+\end_layout
+
+\begin_layout Enumerate
+The use of a linear prediction (LP) model to model the vocal tract
+\end_layout
 
+\begin_layout Enumerate
+The use of (adaptive and fixed) codebook entries as input (excitation) of
+ the LP model
 \end_layout
 
+\begin_layout Enumerate
+The search performed in closed-loop in a 
+\begin_inset Quotes eld
+\end_inset
+
+perceptually weighted domain
+\begin_inset Quotes erd
 \end_inset
 
 
 \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.
+This section describes the basic ideas behind CELP.
+ This is still a work in progress.
 \end_layout
 
-\begin_layout Standard
-
-\newpage
+\begin_layout Section
+Source-Filter Model of Speech Prediction
+\end_layout
 
+\begin_layout Standard
+The source-filter model of speech production assumes that the vocal cords
+ are the source of spectrally flat sound (the excitation signal), and that
+ the vocal tract acts as a filter to spectrally shape the various sounds
+ of speech.
+ While still an approximation, the model is widely used in speech coding
+ because of its simplicity.Its use is also the reason why most speech codecs
+ (Speex included) perform badly on music signals.
+ The different phonemes can be distinguished by their excitation (source)
+ and spectral shape (filter).
+ Voiced sounds (e.g.
+ vowels) have an excitation signal that is periodic and that can be approximated
+ by an impulse train in the time domain or by regularly-spaced harmonics
+ in the frequency domain.
+ On the other hand, fricatives (such as the "s", "sh" and "f" sounds) have
+ an excitation signal that is similar to white Gaussian noise.
+ So called voice fricatives (such as "z" and "v") have excitation signal
+ composed of an harmonic part and a noisy part.
 \end_layout
 
-\begin_layout Section
-Formats and standards
-\begin_inset LatexCommand \index{standards}
+\begin_layout Standard
+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 CommandInset ref
+LatexCommand ref
+reference "fig:The-CELP-model"
 
 \end_inset
 
+.
+\end_layout
+
+\begin_layout Standard
+\begin_inset Float figure
+wide false
+sideways false
+status open
 
-\begin_inset LatexCommand \label{sec:Formats-and-standards}
+\begin_layout Plain Layout
+\begin_inset ERT
+status collapsed
 
-\end_inset
+\begin_layout Plain Layout
 
 
+\backslash
+begin{center}
 \end_layout
 
-\begin_layout Standard
-Speex can encode speech in both narrowband and wideband and provides different
- bit-rates.
- However, not all features need to be supported by a certain implementation
- or device.
- In order to be called 
-\begin_inset Quotes eld
 \end_inset
 
-Speex compatible
-\begin_inset Quotes erd
+
+\begin_inset Graphics
+       filename celp_decoder.eps
+       width 45page%
+       keepAspectRatio
+
 \end_inset
 
- (whatever that means), an implementation must implement at least a basic
- set of features.
-\end_layout
 
-\begin_layout Standard
-At the minimum, all narrowband modes of operation MUST be supported at the
- decoder.
- This includes the decoding of a wideband bit-stream by the narrowband decoder
-\begin_inset Foot
+\begin_inset ERT
 status collapsed
 
-\begin_layout Standard
-The wideband bit-stream contains an embedded narrowband bit-stream which
- can be decoded alone
+\begin_layout Plain Layout
+
+
+\backslash
+end{center}
 \end_layout
 
 \end_inset
 
-.
- If present, a wideband decoder MUST be able to decode a narrowband stream,
- and MAY either be able to decode all wideband modes or be able to decode
- the embedded narrowband part of all modes (which includes ignoring the
- high-band bits).
-\end_layout
 
-\begin_layout Standard
-For encoders, at least one narrowband or wideband mode MUST be supported.
- The main reason why all encoding modes do not have to be supported is that
- some platforms may not be able to handle the complexity of encoding in
- some modes.
 \end_layout
 
-\begin_layout Subsection
-RTP
-\begin_inset LatexCommand \index{RTP}
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+The CELP model of speech synthesis (decoder)
+\begin_inset CommandInset label
+LatexCommand label
+name "fig:The-CELP-model"
 
 \end_inset
 
- Payload Format 
 \end_layout
 
-\begin_layout Standard
-The RTP payload draft is included in appendix 
-\begin_inset LatexCommand \ref{sec:IETF-draft}
-
 \end_inset
 
- and the latest version is available at 
-\begin_inset LatexCommand \url{http://www.speex.org/drafts/latest}
+
+\end_layout
 
 \end_inset
 
-.
- This draft has been sent (2003/02/26) to the Internet Engineering Task
- Force (IETF) and will be discussed at the March 18th meeting in San Francisco.
-\end_layout
 
-\begin_layout Subsection
-MIME Type
 \end_layout
 
-\begin_layout Standard
-For now, you should use the MIME type audio/x-speex for Speex-in-Ogg.
- We will apply for type 
-\family typewriter
-audio/speex
-\family default
- in the near future.
+\begin_layout Section
+Linear Prediction Coefficients (LPC)
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+linear prediction
 \end_layout
 
-\begin_layout Subsection
-Ogg
-\begin_inset LatexCommand \index{Ogg}
+\end_inset
+
 
+\end_layout
+
+\begin_layout Standard
+Linear prediction is at the base of many speech coding techniques, including
+ CELP.
+ The idea behind it is to predict the signal 
+\begin_inset Formula $x[n]$
 \end_inset
 
- file format
+ using a linear combination of its past samples:
 \end_layout
 
 \begin_layout Standard
-Speex bit-streams can be stored in Ogg files.
- In this case, the first packet of the Ogg file contains the Speex header
- described in table 
-\begin_inset LatexCommand \ref{cap:ogg_speex_header}
+\begin_inset Formula \[
+y[n]=\sum_{i=1}^{N}a_{i}x[n-i]\]
 
 \end_inset
 
-.
- All integer fields in the headers are stored as little-endian.
- The 
-\family typewriter
-speex_string
-\family default
- field must contain the 
-\begin_inset Quotes eld
+where 
+\begin_inset Formula $y[n]$
 \end_inset
 
-
-\family typewriter
-Speex
-\family default
-\InsetSpace ~
-\InsetSpace ~
-\InsetSpace ~
-
-\begin_inset Quotes erd
+ is the linear prediction of 
+\begin_inset Formula $x[n]$
 \end_inset
 
- (with 3 trailing spaces), which identifies the bit-stream.
- The next field, 
-\family typewriter
-speex_version
-\family default
- contains the version of Speex that encoded the file.
- For now, refer to speex_header.[ch] for more info.
- The 
-\emph on
-beginning of stream
-\emph default
- (
-\family typewriter
-b_o_s
-\family default
-) flag is set to 1 for the header.
- The header packet has 
-\family typewriter
-packetno=0
-\family default
- and 
-\family typewriter
-granulepos=0
-\family default
 .
-\end_layout
+ The prediction error is thus given by:
+\begin_inset Formula \[
+e[n]=x[n]-y[n]=x[n]-\sum_{i=1}^{N}a_{i}x[n-i]\]
+
+\end_inset
 
-\begin_layout Standard
-The second packet contains the Speex comment header.
- The format used is the Vorbis comment format described here: http://www.xiph.org/
-ogg/vorbis/doc/v-comment.html .
- This packet has 
-\family typewriter
-packetno=1
-\family default
- and 
-\family typewriter
-granulepos=0
-\family default
-.
-\end_layout
 
-\begin_layout Standard
-The third and subsequent packets each contain one or more (number found
- in header) Speex frames.
- These are identified with 
-\family typewriter
-packetno
-\family default
- starting from 2 and the 
-\family typewriter
-granulepos
-\family default
- is the number of the last sample encoded in that packet.
- The last of these packets has the 
-\emph on
-end of stream
-\emph default
- (
-\family typewriter
-e_o_s
-\family default
-) flag is set to 1.
 \end_layout
 
 \begin_layout Standard
-\begin_inset Float table
-placement htbp
-wide true
-sideways false
-status open
+The goal of the LPC analysis is to find the best prediction coefficients
+\begin_inset Formula $a_{i}$
+\end_inset
 
-\begin_layout Standard
-\begin_inset Tabular
-<lyxtabular version="3" rows="16" columns="3">
-<features>
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+ which minimize the quadratic error function:
+\begin_inset Formula \[
+E=\sum_{n=0}^{L-1}\left[e[n]\right]^{2}=\sum_{n=0}^{L-1}\left[x[n]-\sum_{i=1}^{N}a_{i}x[n-i]\right]^{2}\]
 
-\begin_layout Standard
-Field
-\end_layout
+\end_inset
 
+That can be done by making all derivatives 
+\begin_inset Formula $\frac{\partial E}{\partial a_{i}}$
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-Type
-\end_layout
+ equal to zero:
+\begin_inset Formula \[
+\frac{\partial E}{\partial a_{i}}=\frac{\partial}{\partial a_{i}}\sum_{n=0}^{L-1}\left[x[n]-\sum_{i=1}^{N}a_{i}x[n-i]\right]^{2}=0\]
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-Size
-\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
-speex_string
-\end_layout
+For an order 
+\begin_inset Formula $N$
+\end_inset
 
+ filter, the filter coefficients 
+\begin_inset Formula $a_{i}$
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-char[]
-\end_layout
+ are found by solving the system 
+\begin_inset Formula $N\times N$
+\end_inset
 
+ linear system 
+\begin_inset Formula $\mathbf{Ra}=\mathbf{r}$
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-8
-\end_layout
+, where
+\begin_inset Formula \[
+\mathbf{R}=\left[\begin{array}{cccc}
+R(0) & R(1) & \cdots & R(N-1)\\
+R(1) & R(0) & \cdots & R(N-2)\\
+\vdots & \vdots & \ddots & \vdots\\
+R(N-1) & R(N-2) & \cdots & R(0)\end{array}\right]\]
 
 \end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-speex_version
-\end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_inset Formula \[
+\mathbf{r}=\left[\begin{array}{c}
+R(1)\\
+R(2)\\
+\vdots\\
+R(N)\end{array}\right]\]
 
-\begin_layout Standard
-char[]
-\end_layout
+\end_inset
 
+with 
+\begin_inset Formula $R(m)$
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-20
+, the auto-correlation
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+auto-correlation
 \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
-speex_version_id
+ of the signal 
+\begin_inset Formula $x[n]$
+\end_inset
+
+, computed as:
 \end_layout
 
+\begin_layout Standard
+\begin_inset Formula \[
+R(m)=\sum_{i=0}^{N-1}x[i]x[i-m]\]
+
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-int
+
 \end_layout
 
+\begin_layout Standard
+Because 
+\begin_inset Formula $\mathbf{R}$
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-4
+ is Hermitian Toeplitz, the Levinson-Durbin
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+Levinson-Durbin
 \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
-header_size
-\end_layout
+ algorithm can be used, making the solution to the problem 
+\begin_inset Formula $\mathcal{O}\left(N^{2}\right)$
+\end_inset
 
+ instead of 
+\begin_inset Formula $\mathcal{O}\left(N^{3}\right)$
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-int
-\end_layout
+.
+ Also, it can be proven that all the roots of 
+\begin_inset Formula $A(z)$
+\end_inset
 
+ are within the unit circle, which means that 
+\begin_inset Formula $1/A(z)$
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-4
+ is always stable.
+ This is in theory; in practice because of finite precision, there are two
+ commonly used techniques to make sure we have a stable filter.
+ First, we multiply 
+\begin_inset Formula $R(0)$
+\end_inset
+
+ by a number slightly above one (such as 1.0001), which is equivalent to
+ adding noise to the signal.
+ Also, we can apply a window to the auto-correlation, which is equivalent
+ to filtering in the frequency domain, reducing sharp resonances.
 \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 Section
+Pitch Prediction
+\begin_inset Index
+status collapsed
 
-\begin_layout Standard
-rate
+\begin_layout Plain Layout
+pitch
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-int
+
 \end_layout
 
+\begin_layout Standard
+During voiced segments, the speech signal is periodic, so it is possible
+ to take advantage of that property by approximating the excitation signal
+\begin_inset Formula $e[n]$
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-4
+ by a gain times the past of the excitation:
 \end_layout
 
+\begin_layout Standard
+\begin_inset Formula \[
+e[n]\simeq p[n]=\beta e[n-T]\ ,\]
+
 \end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-mode
-\end_layout
+where 
+\begin_inset Formula $T$
+\end_inset
 
+ is the pitch period, 
+\begin_inset Formula $\beta$
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-int
-\end_layout
+ is the pitch gain.
+ We call that long-term prediction since the excitation is predicted from
+\begin_inset Formula $e[n-T]$
+\end_inset
 
+ with 
+\begin_inset Formula $T\gg N$
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-4
+.
 \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 Section
+Innovation Codebook
+\end_layout
 
 \begin_layout Standard
-mode_bitstream_version
-\end_layout
+The final excitation 
+\begin_inset Formula $e[n]$
+\end_inset
 
+ will be the sum of the pitch prediction and an 
+\emph on
+innovation
+\emph default
+ signal 
+\begin_inset Formula $c[n]$
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-int
+ taken from a fixed codebook, hence the name 
+\emph on
+Code
+\emph default
+ Excited Linear Prediction.
+ 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]\ .\]
+
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-4
-\end_layout
+The quantization of 
+\begin_inset Formula $c[n]$
+\end_inset
 
+ is where most of the bits in a CELP codec are allocated.
+ It represents the information that couldn't be obtained either from linear
+ prediction or pitch prediction.
+ In the 
+\emph on
+z
+\emph default
+-domain we can represent the final signal 
+\begin_inset Formula $X(z)$
 \end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-nb_channels
-\end_layout
+ as
+\begin_inset Formula \[
+X(z)=\frac{C(z)}{A(z)\left(1-\beta z^{-T}\right)}\]
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-int
+
 \end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\begin_layout Section
+Noise Weighting
+\begin_inset Index
+status collapsed
 
-\begin_layout Standard
-4
+\begin_layout Plain Layout
+error weighting
 \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
-bitrate
-\end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_inset Index
+status collapsed
 
-\begin_layout Standard
-int
+\begin_layout Plain Layout
+analysis-by-synthesis
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-4
+
 \end_layout
 
+\begin_layout Standard
+Most (if not all) modern audio codecs attempt to 
+\begin_inset Quotes eld
 \end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-frame_size
-\end_layout
+shape
+\begin_inset Quotes erd
+\end_inset
 
+ the noise so that it appears mostly in the frequency regions where the
+ ear cannot detect it.
+ For example, the ear is more tolerant to noise in parts of the spectrum
+ that are louder and 
+\emph on
+vice versa
+\emph default
+.
+ In order to maximize speech quality, CELP codecs minimize the mean square
+ of the error (noise) in the perceptually weighted domain.
+ This means that a perceptual noise 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
-int
-\end_layout
+ is applied to the error signal in the encoder.
+ In most CELP codecs, 
+\begin_inset Formula $W(z)$
+\end_inset
 
+ is a pole-zero weighting filter derived from the linear prediction coefficients
+ (LPC), generally using bandwidth expansion.
+ Let the spectral envelope be represented by the synthesis filter 
+\begin_inset Formula $1/A(z)$
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-4
-\end_layout
+, 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}
 
 \end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-vbr
-\end_layout
+where 
+\begin_inset Formula $\gamma_{1}=0.9$
+\end_inset
 
+ and 
+\begin_inset Formula $\gamma_{2}=0.6$
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-int
-\end_layout
+ in the Speex reference implementation.
+ If a filter 
+\begin_inset Formula $A(z)$
+\end_inset
 
+ has (complex) poles at 
+\begin_inset Formula $p_{i}$
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-4
-\end_layout
+ in the 
+\begin_inset Formula $z$
+\end_inset
 
+-plane, the filter 
+\begin_inset Formula $A(z/\gamma)$
 \end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-frames_per_packet
-\end_layout
+ will have its poles at 
+\begin_inset Formula $p'_{i}=\gamma p_{i}$
+\end_inset
 
+, making it a flatter version of 
+\begin_inset Formula $A(z)$
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-int
+.
 \end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
 \begin_layout Standard
-4
-\end_layout
+The weighting filter is applied to the error signal used to optimize the
+ codebook search through analysis-by-synthesis (AbS).
+ This results in a spectral shape of the noise that tends towards 
+\begin_inset Formula $1/W(z)$
+\end_inset
 
+.
+ While the simplicity of the model has been an important reason for the
+ success of CELP, it remains that 
+\begin_inset Formula $W(z)$
 \end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-extra_headers
-\end_layout
+ is a very rough approximation for the perceptually optimal noise weighting
+ function.
+ Fig.
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "cap:Standard-noise-shaping"
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-int
-\end_layout
+ illustrates the noise shaping that results from Eq.
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "eq:gamma-weighting"
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-4
-\end_layout
+.
+ Throughout this paper, we refer to 
+\begin_inset Formula $W(z)$
+\end_inset
 
+ as the noise weighting filter and to 
+\begin_inset Formula $1/W(z)$
 \end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-reserved1
+ as the noise shaping filter (or curve).
 \end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
 \begin_layout Standard
-int
-\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
-4
-\end_layout
+\begin_layout Plain 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
-reserved2
+\backslash
+begin{center}
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-int
-\end_layout
+
+\begin_inset Graphics
+       filename ref_shaping.eps
+       width 45page%
+       keepAspectRatio
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-4
-\end_layout
 
-\end_inset
-</cell>
-</row>
-</lyxtabular>
+\begin_inset ERT
+status collapsed
+
+\begin_layout Plain Layout
+
+
+\backslash
+end{center}
+\end_layout
 
 \end_inset
 
 
 \end_layout
 
-\begin_layout Caption
-Ogg/Speex header packet
-\begin_inset LatexCommand \label{cap:ogg_speex_header}
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Standard noise shaping in CELP.
+ Arbitrary y-axis offset.
+\begin_inset CommandInset label
+LatexCommand label
+name "cap:Standard-noise-shaping"
 
 \end_inset
 
@@ -3373,833 +6957,944 @@ Ogg/Speex header packet
 
 \end_layout
 
-\begin_layout Standard
+\end_inset
 
-\newpage
 
 \end_layout
 
 \begin_layout Section
-Introduction to CELP Coding
-\begin_inset LatexCommand \index{CELP}
+Analysis-by-Synthesis
+\end_layout
+
+\begin_layout Standard
+One of the main principles behind CELP is called Analysis-by-Synthesis (AbS),
+ meaning that the encoding (analysis) is performed by perceptually optimising
+ the decoded (synthesis) signal in a closed loop.
+ In theory, the best CELP stream would be produced by trying all possible
+ bit combinations and selecting the one that produces the best-sounding
+ decoded signal.
+ This is obviously not possible in practice for two reasons: the required
+ complexity is beyond any currently available hardware and the 
+\begin_inset Quotes eld
+\end_inset
 
+best sounding
+\begin_inset Quotes erd
 \end_inset
 
+ selection criterion implies a human listener.
+\end_layout
 
-\begin_inset LatexCommand \label{sec:Introduction-to-CELP}
+\begin_layout Standard
+In order to achieve real-time encoding using limited computing resources,
+ the CELP optimisation is broken down into smaller, more manageable, sequential
+ searches using the perceptual weighting function described earlier.
+\end_layout
 
+\begin_layout Standard
+\begin_inset Newpage newpage
 \end_inset
 
 
 \end_layout
 
-\begin_layout Standard
-Speex is based on CELP, which stands for Code Excited Linear Prediction.
- This section attempts to introduce the principles behind CELP, so if you
- are already familiar with CELP, you can safely skip to section 
-\begin_inset LatexCommand \ref{sec:Speex-narrowband-mode}
-
-\end_inset
+\begin_layout Chapter
+The Speex Decoder Specification
+\end_layout
 
-.
- The CELP technique is based on three ideas:
+\begin_layout Section
+Narrowband decoder
 \end_layout
 
-\begin_layout Enumerate
-The use of a linear prediction (LP) model to model the vocal tract
+\begin_layout Standard
+<Insert decoder figure here>
 \end_layout
 
-\begin_layout Enumerate
-The use of (adaptive and fixed) codebook entries as input (excitation) of
- the LP model
+\begin_layout Subsection
+Narrowband modes
 \end_layout
 
-\begin_layout Enumerate
-The search performed in closed-loop in a 
+\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
 
-perceptually weighted domain
+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
-This section describes the basic ideas behind CELP.
- Note that it's still incomplete.
-\end_layout
+\begin_inset Float table
+placement h
+wide true
+sideways false
+status open
 
-\begin_layout Subsection
-Linear Prediction (LPC)
-\begin_inset LatexCommand \index{linear prediction}
+\begin_layout Plain Layout
+\begin_inset ERT
+status collapsed
 
-\end_inset
+\begin_layout Plain Layout
 
 
+\backslash
+begin{center}
 \end_layout
 
-\begin_layout Standard
-Linear prediction is at the base of many speech coding techniques, including
- CELP.
- The idea behind it is to predict the signal 
-\begin_inset Formula $x[n]$
 \end_inset
 
- using a linear combination of its past samples:
-\end_layout
 
-\begin_layout Standard
-\begin_inset Formula \[
-y[n]=\sum_{i=1}^{N}a_{i}x[n-i]\]
+\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
 
-where 
-\begin_inset Formula $y[n]$
-\end_inset
+\begin_layout Plain Layout
+Update rate
+\end_layout
 
- is the linear prediction of 
-\begin_inset Formula $x[n]$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-.
- The prediction error is thus given by:
-\begin_inset Formula \[
-e[n]=x[n]-y[n]=x[n]-\sum_{i=1}^{N}a_{i}x[n-i]\]
+\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
 
-\begin_layout Standard
-The goal of the LPC analysis is to find the best prediction coefficients
-\begin_inset Formula $a_{i}$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- which minimize the quadratic error function:
-\begin_inset Formula \[
-E=\sum_{n=0}^{L-1}\left[e[n]\right]^{2}=\sum_{n=0}^{L-1}\left[x[n]-\sum_{i=1}^{N}a_{i}x[n-i]\right]^{2}\]
-
-\end_inset
+\begin_layout Plain Layout
+2
+\end_layout
 
-That can be done by making all derivatives 
-\begin_inset Formula $\frac{\partial E}{\partial a_{i}}$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- equal to zero:
-\begin_inset Formula \[
-\frac{\partial E}{\partial a_{i}}=\frac{\partial}{\partial a_{i}}\sum_{n=0}^{L-1}\left[x[n]-\sum_{i=1}^{N}a_{i}x[n-i]\right]^{2}=0\]
+\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
 
-\begin_layout Standard
-The 
-\begin_inset Formula $a_{i}$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- filter coefficients are computed using the Levinson-Durbin
-\begin_inset LatexCommand \index{Levinson-Durbin}
+\begin_layout Plain Layout
+5
+\end_layout
 
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- algorithm, which starts from the auto-correlation
-\begin_inset LatexCommand \index{auto-correlation}
+\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_inset Formula $R(m)$
-\end_inset
+\begin_layout Plain Layout
+7
+\end_layout
 
- of the signal 
-\begin_inset Formula $x[n]$
 \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
 
-\begin_layout Standard
-\begin_inset Formula \[
-R(m)=\sum_{i=0}^{N-1}x[i]x[i-m]\]
-
 \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
 
-\begin_layout Standard
-For an order 
-\begin_inset Formula $N$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- filter, we have:
-\begin_inset Formula \[
-\mathbf{R}=\left[\begin{array}{cccc}
-R(0) & R(1) & \cdots & R(N-1)\\
-R(1) & R(0) & \cdots & R(N-2)\\
-\vdots & \vdots & \ddots & \vdots\\
-R(N-1) & R(N-2) & \cdots & R(0)\end{array}\right]\]
+\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_inset Formula \[
-\mathbf{r}=\left[\begin{array}{c}
-R(1)\\
-R(2)\\
-\vdots\\
-R(N)\end{array}\right]\]
+\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
 
-\begin_layout Standard
-The filter coefficients 
-\begin_inset Formula $a_{i}$
-\end_inset
-
- are found by solving the system 
-\begin_inset Formula $\mathbf{Ra}=\mathbf{r}$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-.
- What the Levinson-Durbin algorithm does here is making the solution to
- the problem 
-\begin_inset Formula $\mathcal{O}\left(N^{2}\right)$
-\end_inset
+\begin_layout Plain Layout
+1
+\end_layout
 
- instead of 
-\begin_inset Formula $\mathcal{O}\left(N^{3}\right)$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- by exploiting the fact that matrix 
-\begin_inset Formula $\mathbf{R}$
-\end_inset
+\begin_layout Plain Layout
+1
+\end_layout
 
- is toeplitz hermitian.
- Also, it can be proven that all the roots of 
-\begin_inset Formula $A(z)$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- are within the unit circle, which means that 
-\begin_inset Formula $1/A(z)$
-\end_inset
+\begin_layout Plain Layout
+1
+\end_layout
 
- is always stable.
- This is in theory; in practice because of finite precision, there are two
- commonly used techniques to make sure we have a stable filter.
- First, we multiply 
-\begin_inset Formula $R(0)$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- by a number slightly above one (such as 1.0001), which is equivalent to
- adding noise to the signal.
- Also, we can apply a window to the auto-correlation, which is equivalent
- to filtering in the frequency domain, reducing sharp resonances.
+\begin_layout Plain Layout
+1
 \end_layout
 
-\begin_layout Standard
-The linear prediction model represents each speech sample as a linear combinatio
-n of past samples, plus an error signal called the excitation (or residual).
-\begin_inset Formula \[
-x[n]=\sum_{i=1}^{N}a_{i}x[n-i]+e[n]\]
-
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-
-\end_layout
-
-\begin_layout Standard
-In the 
-\emph on
-z
-\emph default
--domain, this can be expressed as
+\begin_layout Plain Layout
+1
 \end_layout
 
-\begin_layout Standard
-\begin_inset Formula \[
-x(z)=\frac{1}{A(z)}\: e(z)\]
-
 \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
-where 
-\begin_inset Formula $A(z)$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
- is defined as
+\begin_layout Plain Layout
+1
 \end_layout
 
-\begin_layout Standard
-\begin_inset Formula \[
-A(z)=1-\sum_{i=1}^{N}a_{i}z^{-i}\]
-
 \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
 
-\begin_layout Standard
-We usually refer to 
-\begin_inset Formula $A(z)$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- as the analysis filter and 
-\begin_inset Formula $1/A(z)$
-\end_inset
+\begin_layout Plain Layout
+frame
+\end_layout
 
- as the synthesis filter.
- The whole process is called short-term prediction as it predicts the signal
-\begin_inset Formula $x[n]$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- using a prediction using only the 
-\begin_inset Formula $N$
-\end_inset
+\begin_layout Plain Layout
+4
+\end_layout
 
- past samples, where 
-\begin_inset Formula $N$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- is usually around 10.
+\begin_layout Plain Layout
+4
 \end_layout
 
-\begin_layout Standard
-Because LPC coefficients have very little robustness to quantization, they
- are converted to Line Spectral Pair
-\begin_inset LatexCommand \index{line spectral pair}
-
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- (LSP) coefficients which have a much better behaviour with quantization,
- one of them being that it's easy to keep the filter stable.
+\begin_layout Plain Layout
+4
 \end_layout
 
-\begin_layout Standard
-\begin_inset Note Comment
-status collapsed
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-\begin_layout Standard
-Describe LSP's
+\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 Subsection
-Pitch Prediction
-\begin_inset LatexCommand \index{pitch}
-
 \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 Standard
-During voiced segments, the speech signal is periodic, so it is possible
- to take advantage of that property by approximating the excitation signal
-\begin_inset Formula $e[n]$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- by a gain times the past of the excitation:
+\begin_layout Plain Layout
+4
 \end_layout
 
-\begin_layout Standard
-\begin_inset Formula \[
-e[n]\simeq p[n]=\beta e[n-T]\]
-
 \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 Standard
-where 
-\begin_inset Formula $T$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
- is the pitch period, 
-\begin_inset Formula $\beta$
-\end_inset
+\begin_layout Plain Layout
+4
+\end_layout
 
- is the pitch gain.
- We call that long-term prediction since the excitation is predicted from
-\begin_inset Formula $e[n-T]$
 \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
 
- with 
-\begin_inset Formula $T\gg N$
 \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_layout Subsection
-Innovation Codebook
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+0
 \end_layout
 
-\begin_layout Standard
-The final excitation 
-\begin_inset Formula $e[n]$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+18
+\end_layout
 
- will be the sum of the pitch prediction and an 
-\emph on
-innovation
-\emph default
- signal 
-\begin_inset Formula $c[n]$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- taken from a fixed codebook, hence the name 
-\emph on
-Code
-\emph default
- Excited Linear Prediction.
- The final excitation is given by:
+\begin_layout Plain Layout
+18
 \end_layout
 
-\begin_layout Standard
-\begin_inset Formula \[
-e[n]=p[n]+c[n]=\beta e[n-T]+c[n]\]
-
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-The quantization of 
-\begin_inset Formula $c[n]$
-\end_inset
+\begin_layout Plain Layout
+18
+\end_layout
 
- is where most of the bits in a CELP codec are allocated.
- It represents the information that couldn't be obtained either from linear
- prediction or pitch prediction.
- In the 
-\emph on
-z
-\emph default
--domain we can represent the final signal 
-\begin_inset Formula $X(z)$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- as 
-\begin_inset Formula \[
-X(z)=\frac{C(z)}{A(z)\left(1-\beta z^{-T}\right)}\]
+\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
+30
 \end_layout
 
-\begin_layout Subsection
-Analysis-by-Synthesis and Error Weighting
-\begin_inset LatexCommand \index{error weighting}
-
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-
-\begin_inset LatexCommand \index{analysis-by-synthesis}
+\begin_layout Plain Layout
+30
+\end_layout
 
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-
+\begin_layout Plain Layout
+30
 \end_layout
 
-\begin_layout Standard
-Most (if not all) modern audio codecs attempt to 
-\begin_inset Quotes eld
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+18
+\end_layout
 
-shape
-\begin_inset Quotes erd
 \end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- the noise so that it appears mostly in the frequency regions where the
- ear cannot detect it.
- For example, the ear is more tolerant to noise in parts of the spectrum
- that are louder and 
-\emph on
-vice versa
-\emph default
-.
- That's why instead of minimizing the simple quadratic error
-\begin_inset Formula \[
-E=\sum_{n}\left(x[n]-\overline{x}[n]\right)^{2}\]
+\begin_layout Plain Layout
+OL pitch
+\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
 
-where 
-\begin_inset Formula $\overline{x}[n]$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- is the encoder signal, we minimize the error for the perceptually weighted
- signal
-\begin_inset Formula \[
-X_{w}(z)=W(z)X(z)\]
+\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
+7
+\end_layout
 
-where 
-\begin_inset Formula $W(z)$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- is the weighting filter, usually of the form
+\begin_layout Plain Layout
+7
 \end_layout
 
-\begin_layout Standard
-\begin_inset Formula \begin{equation}
-W(z)=\frac{A\left(\frac{z}{\gamma_{1}}\right)}{A\left(\frac{z}{\gamma_{2}}\right)}\label{eq:weighting_filter}\end{equation}
-
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-
+\begin_layout Plain Layout
+0
 \end_layout
 
-\begin_layout Standard
-with control parameters 
-\begin_inset Formula $\gamma_{1}>\gamma_{2}$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-.
- If the noise is white in the perceptually weighted domain, then in the
- signal domain its spectral shape will be of the form
-\begin_inset Formula \[
-A_{noise}(z)=\frac{1}{W(z)}=\frac{A\left(\frac{z}{\gamma_{2}}\right)}{A\left(\frac{z}{\gamma_{1}}\right)}\]
+\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
+0
 \end_layout
 
-\begin_layout Standard
-If a filter 
-\begin_inset Formula $A(z)$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- has (complex) poles at 
-\begin_inset Formula $p_{i}$
-\end_inset
+\begin_layout Plain Layout
+0
+\end_layout
 
- in the 
-\begin_inset Formula $z$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
--plane, the filter 
-\begin_inset Formula $A(z/\gamma)$
-\end_inset
+\begin_layout Plain Layout
+0
+\end_layout
 
- will have its poles at 
-\begin_inset Formula $p'_{i}=\gamma p_{i}$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+7
+\end_layout
 
-, making it a flatter version of 
-\begin_inset Formula $A(z)$
 \end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-.
+\begin_layout Plain Layout
+OL pitch gain
 \end_layout
 
-\begin_layout Standard
-Analysis-by-synthesis refers to the fact that when trying to find the best
- pitch parameters (
-\begin_inset Formula $T$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-, 
-\begin_inset Formula $\beta$
-\end_inset
+\begin_layout Plain Layout
+frame
+\end_layout
 
-) and innovation signal 
-\begin_inset Formula $c[n]$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-, we do not work by making the excitation 
-\begin_inset Formula $e[n]$
-\end_inset
+\begin_layout Plain Layout
+0
+\end_layout
 
- as close as the original one (which would be simpler), but apply the synthesis
- (and weighting) filter and try making 
-\begin_inset Formula $X_{w}(z)$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- as close to the original as possible.
+\begin_layout Plain Layout
+4
 \end_layout
 
-\begin_layout Standard
-
-\newpage
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
+\begin_layout Plain Layout
+0
 \end_layout
 
-\begin_layout Section
-Speex narrowband mode
-\begin_inset LatexCommand \label{sec:Speex-narrowband-mode}
-
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-
-\begin_inset LatexCommand \index{narrowband}
+\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
+0
 \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" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+0
+\end_layout
 
- sampling rate) operation.
- The frame size for this mode is 
-\begin_inset Formula $20\:\mathrm{ms}$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-, corresponding to 160 samples.
- Each frame is also subdivided into 4 sub-frames of 40 samples each.
+\begin_layout Plain Layout
+0
 \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
+0
 \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" rightline="true" usebox="none">
+\begin_inset Text
 
-\begin_layout Itemize
-sub-vector fixed (innovation) codebooks
+\begin_layout Plain Layout
+4
 \end_layout
 
-\begin_layout Subsection
-LPC Analysis
-\begin_inset LatexCommand \index{linear prediction}
-
 \end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-
+\begin_layout Plain Layout
+OL Exc gain
 \end_layout
 
-\begin_layout Standard
-An LPC analysis is first performed on a (asymetric Hamming) window that
- spans all of the current frame and half a frame in advance.
- The LPC coefficients are then converted to Line Spectral Pair
-\begin_inset LatexCommand \index{line spectral pair}
-
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+frame
+\end_layout
 
- (LSP), a representation that is more robust to quantization.
- The LSP's are considered to be associated to the 
-\begin_inset Formula $4^{th}$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- sub-frames and the LSP's associated to the first 3 sub-frames are linearly
- interpolated using the current and previous LSP's.
+\begin_layout Plain Layout
+0
 \end_layout
 
-\begin_layout Standard
-The LSP's are encoded using 30 bits for higher quality modes and 18 bits
- for lower quality, through the use of a multi-stage split-vector quantizer.
- For the lower quality modes, the 10 coefficients are first quantized with
- 6 bits and the error is then divided in two 5-coefficient sub-vectors.
- Each of them is quantized with 6 bits, for a total of 18 bits.
- For the higher quality modes, the remaining error on both sub-vectors is
- further quantized with 6 bits each, for a total of 30 bits.
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+5
 \end_layout
 
-\begin_layout Standard
-The perceptual 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 Plain Layout
+5
+\end_layout
 
- used by Speex is derived from the LPC filter 
-\begin_inset Formula $A(z)$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- and corresponds to the one described by eq.
-\begin_inset LatexCommand \ref{eq:weighting_filter}
+\begin_layout Plain Layout
+5
+\end_layout
 
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- with 
-\begin_inset Formula $\gamma_{1}=0.9$
-\end_inset
+\begin_layout Plain Layout
+5
+\end_layout
 
- and 
-\begin_inset Formula $\gamma_{2}=0.6$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+5
+\end_layout
 
-.
- We can use the unquantized 
-\begin_inset Formula $A(z)$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- filter since the weighting filter is only used in the encoder.
+\begin_layout Plain Layout
+5
 \end_layout
 
-\begin_layout Subsection
-Pitch Prediction (adaptive codebook)
-\begin_inset LatexCommand \index{pitch}
-
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-
+\begin_layout Plain Layout
+5
 \end_layout
 
-\begin_layout Standard
-Speex uses a 3-tap prediction for pitch.
- That is, the pitch prediction signal 
-\begin_inset Formula $p[n]$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
- is obtained by the past of the excitation by:
-\begin_inset Formula \[
-p[n]=\beta_{0}e[n-T-1]+\beta_{1}e[n-T]+\beta_{2}e[n-T+1]\]
+\begin_layout Plain Layout
+5
+\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
+Fine pitch
 \end_layout
 
-\begin_layout Standard
-where 
-\begin_inset Formula $T$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- is the pitch period and the 
-\begin_inset Formula $\beta_{i}$
-\end_inset
+\begin_layout Plain Layout
+sub-frame
+\end_layout
 
- are the prediction (filter) taps.
- It is worth noting that when the pitch is smaller than the sub-frame size,
- we repeat the excitation at a period 
-\begin_inset Formula $T$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-.
- For example, when 
-\begin_inset Formula $n-T+1$
-\end_inset
+\begin_layout Plain Layout
+0
+\end_layout
 
-, we use 
-\begin_inset Formula $n-2T+1$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- instead.
- The period and quantized gains are determined in closed loop (analysis-by-synth
-esis).
- In most modes, the pitch period is encoded with 7 bits in the 
-\begin_inset Formula $\left[17,144\right]$
-\end_inset
+\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 (15 kbps narrowband and
- above) at higher bit-rates and 5 bits at lower bit-rates (11 kbps narrowband
- and below).
+\begin_layout Plain Layout
+0
 \end_layout
 
-\begin_layout Subsection
-Innovation Codebook
-\end_layout
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-\begin_layout Standard
-In Speex, the innovation signal is quantized using sub-vector shape-only
- vector quantization (VQ).
- That means that the innovation signal is divided in sub-vectors (of size
- 5 to 20) and quantized using a codebook that represents both the shape
- and the gain at the same time.
- This saves many bits that would otherwise be allocated for a separate gain
- at the price of a slight increase in complexity.
+\begin_layout Plain Layout
+7
 \end_layout
 
-\begin_layout Subsection
-Bit allocation
-\end_layout
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-\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}
+\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
+7
+\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
+7
+\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
+7
 \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
+0
+\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
+Pitch gain
 \end_layout
 
 \end_inset
@@ -4207,8 +7902,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
@@ -4216,7 +7911,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
 
@@ -4225,8 +7920,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
+0
 \end_layout
 
 \end_inset
@@ -4234,8 +7929,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
+5
 \end_layout
 
 \end_inset
@@ -4243,8 +7938,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
+5
 \end_layout
 
 \end_inset
@@ -4252,8 +7947,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
+5
 \end_layout
 
 \end_inset
@@ -4261,25 +7956,25 @@ Update rate
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-5
+\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
-6
+\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
+\begin_layout Plain Layout
 7
 \end_layout
 
@@ -4288,19 +7983,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
+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
-Wideband bit
+\begin_layout Plain Layout
+Innovation gain
 \end_layout
 
 \end_inset
@@ -4308,8 +8003,8 @@ Wideband bit
 <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
@@ -4317,8 +8012,8 @@ 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
@@ -4326,7 +8021,7 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 1
 \end_layout
 
@@ -4335,8 +8030,8 @@ 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
@@ -4344,7 +8039,7 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 1
 \end_layout
 
@@ -4353,7 +8048,7 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
+\begin_layout Plain Layout
 1
 \end_layout
 
@@ -4362,26 +8057,26 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-1
+\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
-1
+\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
-1
+\begin_layout Plain Layout
+3
 \end_layout
 
 \end_inset
@@ -4389,642 +8084,882 @@ 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
+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
-Mode ID
+\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
-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
-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
-4
+\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
-4
+\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
-4
+\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
-4
+\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
-4
+\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
-4
+\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
-LSP
+\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
-0
+\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
-18
+\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
-18
+\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
-18
+\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 Plain Layout
+220
+\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
+300
+\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
+364
+\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
+492
+\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
+79
+\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
+Bit allocation for narrowband modes
+\begin_inset CommandInset label
+LatexCommand label
+name "cap:bits-narrowband"
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+LSP decoding
+\end_layout
+
 \begin_layout Standard
-18
+Depending on the mode, LSP parameters are encoded using either 18 bits or
+ 30 bits.
+\end_layout
+
+\begin_layout Standard
+Interpolation
+\end_layout
+
+\begin_layout Standard
+Safe margin
 \end_layout
 
+\begin_layout Subsection
+Adaptive codebook
+\end_layout
+
+\begin_layout Standard
+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
-30
+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" rightline="true" usebox="none">
-\begin_inset Text
+\begin_layout Subsection
+Innovation codebook
+\end_layout
 
 \begin_layout Standard
-30
+Split codebook, size and entries depend on bit-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
-30
+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" rightline="true" usebox="none">
-\begin_inset Text
+\begin_layout Standard
+Depending on the mode, higher resolution per sub-frame
+\end_layout
 
 \begin_layout Standard
-18
+innovation sub-vectors concatenated, gain applied
 \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
+Perceptual enhancement
+\end_layout
 
 \begin_layout Standard
-OL pitch
+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
-frame
+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
-0
+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" 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" 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" 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>
-<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
-0
+\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
-0
+\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" rightline="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" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-0
-\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" rightline="true" usebox="none">
-\begin_inset Text
+
+.
+ All other parameters are encoded at the sub-frame level.
+\end_layout
 
 \begin_layout Standard
-7
+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>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-OL pitch gain
-\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
-frame
-\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
-0
+ 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" 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
-4
+\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" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-0
-\end_layout
+
+\begin_inset Graphics
+       filename speex_analysis.eps
+       width 35page%
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-0
+
+\begin_inset ERT
+status collapsed
+
+\begin_layout Plain Layout
+
+
+\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
 
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\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
-0
+
 \end_layout
 
 \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>
-<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>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\begin_layout Section
+Sub-Frame Analysis-by-Synthesis
+\end_layout
 
 \begin_layout Standard
-4
+\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>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-OL Exc gain
-\end_layout
+
+\begin_inset Graphics
+       filename speex_abs.eps
+       lyxscale 75
+       width 40page%
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-frame
+
+\begin_inset ERT
+status collapsed
+
+\begin_layout Plain Layout
+
+
+\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
 
+\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
-5
+
 \end_layout
 
 \end_inset
-</cell>
-<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
 
-\begin_layout Standard
-5
+
 \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
-5
-\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" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-5
-\end_layout
+where 
+\begin_inset Formula $g_{0}$
+\end_inset
 
+, 
+\begin_inset Formula $g_{1}$
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-5
-\end_layout
+ and 
+\begin_inset Formula $g_{2}$
+\end_inset
 
+ are the jointly quantized pitch gains and 
+\begin_inset Formula $e[n]$
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-5
-\end_layout
+ 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
 
+.
+ For example, when 
+\begin_inset Formula $n-T+1\geq0$
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-5
-\end_layout
+, we use 
+\begin_inset Formula $n-2T+1$
+\end_inset
 
+ instead.
+ In most modes, the pitch period is encoded with 7 bits in the 
+\begin_inset Formula $\left[17,144\right]$
 \end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-Fine pitch
+ 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 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
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-sub-frame
+.
+ 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
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_layout Section
+Bit-rates
+\end_layout
 
 \begin_layout Standard
-0
+So far, no MOS (Mean Opinion Score
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+mean opinion score
 \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
+) subjective evaluation has been performed for Speex.
+ 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
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-0
+ presents my own subjective opinion on it.
+ 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
+ quality sometimes varies depending on the input.
+ Note that the complexity is only approximate (within 0.5 mflops and using
+ the lowest complexity setting).
+ Decoding requires approximately 0.5 mflops
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+complexity
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
+ in most modes (1 mflops with perceptual enhancement).
+\end_layout
 
 \begin_layout Standard
-7
+\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
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="17" columns="5">
+<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">
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-7
+\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
-7
+\begin_layout Plain Layout
+Quality
 \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
-7
+\begin_layout Plain Layout
+Bit-rate
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+bit-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
-7
+ (bps)
 \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
+mflops
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+complexity
 \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
-Pitch gain
+
 \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
-sub-frame
+\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
 
@@ -5033,8 +8968,8 @@ sub-frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-0
+\begin_layout Plain Layout
+-
 \end_layout
 
 \end_inset
@@ -5042,8 +8977,8 @@ sub-frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-5
+\begin_layout Plain Layout
+250
 \end_layout
 
 \end_inset
@@ -5051,73 +8986,75 @@ sub-frame
 <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" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-5
+\begin_layout Plain Layout
+No transmission (DTX)
 \end_layout
 
 \end_inset
 </cell>
+</row>
+<row>
 <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
 </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
 </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
+2,150
 \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
+6
 \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" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-Innovation gain
+\begin_layout Plain Layout
+Vocoder (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
-sub-frame
+\begin_layout Plain Layout
+2
 \end_layout
 
 \end_inset
@@ -5125,8 +9062,8 @@ sub-frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-0
+\begin_layout Plain Layout
+2
 \end_layout
 
 \end_inset
@@ -5134,8 +9071,8 @@ sub-frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-1
+\begin_layout Plain Layout
+5,950
 \end_layout
 
 \end_inset
@@ -5143,26 +9080,28 @@ sub-frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-0
+\begin_layout Plain Layout
+9
 \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
-1
+\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
-1
+\begin_layout Plain Layout
+3
 \end_layout
 
 \end_inset
@@ -5170,26 +9109,26 @@ sub-frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-3
+\begin_layout Plain Layout
+3-4
 \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
-3
+\begin_layout Plain Layout
+8,000
 \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
-3
+\begin_layout Plain Layout
+10
 \end_layout
 
 \end_inset
@@ -5197,19 +9136,19 @@ sub-frame
 <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 topline="true" bottomline="true">
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-Innovation VQ
+\begin_layout Plain Layout
+4
 \end_layout
 
 \end_inset
@@ -5217,8 +9156,8 @@ Innovation VQ
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-sub-frame
+\begin_layout Plain Layout
+5-6
 \end_layout
 
 \end_inset
@@ -5226,8 +9165,8 @@ sub-frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-0
+\begin_layout Plain Layout
+11,000
 \end_layout
 
 \end_inset
@@ -5235,26 +9174,28 @@ sub-frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-0
+\begin_layout Plain Layout
+14
 \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
-16
+\begin_layout Plain Layout
+Artifacts usually noticeable only with 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
-20
+\begin_layout Plain Layout
+5
 \end_layout
 
 \end_inset
@@ -5262,8 +9203,8 @@ sub-frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-35
+\begin_layout Plain Layout
+7-8
 \end_layout
 
 \end_inset
@@ -5271,17 +9212,17 @@ sub-frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-48
+\begin_layout Plain Layout
+15,000
 \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
-64
+\begin_layout Plain Layout
+11
 \end_layout
 
 \end_inset
@@ -5289,28 +9230,28 @@ sub-frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-96
+\begin_layout Plain Layout
+Need good headphones to tell the difference
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-10
+\begin_layout Plain Layout
+6
 \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
-Total
+\begin_layout Plain Layout
+9
 \end_layout
 
 \end_inset
@@ -5318,8 +9259,8 @@ Total
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-frame
+\begin_layout Plain Layout
+18,200
 \end_layout
 
 \end_inset
@@ -5327,26 +9268,28 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-5
+\begin_layout Plain Layout
+17.5
 \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
-43
+\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
-119
+\begin_layout Plain Layout
+7
 \end_layout
 
 \end_inset
@@ -5354,8 +9297,8 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-160
+\begin_layout Plain Layout
+10
 \end_layout
 
 \end_inset
@@ -5363,8 +9306,8 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-220
+\begin_layout Plain Layout
+24,600
 \end_layout
 
 \end_inset
@@ -5372,8 +9315,8 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-300
+\begin_layout Plain Layout
+14.5
 \end_layout
 
 \end_inset
@@ -5381,101 +9324,66 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-364
+\begin_layout Plain Layout
+Completely transparent for voice, good quality music
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-492
+\begin_layout Plain Layout
+8
 \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
-79
+\begin_layout Plain Layout
+1
 \end_layout
 
 \end_inset
 </cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
+\begin_layout Plain Layout
+3,950
 \end_layout
 
-\begin_layout Caption
-Bit allocation for narrowband modes
-\begin_inset LatexCommand \label{cap:bits-narrowband}
-
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-
+\begin_layout Plain Layout
+10.5
 \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, good intelligibility
 \end_layout
 
-\begin_layout Standard
-So far, no MOS (Mean Opinion Score
-\begin_inset LatexCommand \index{mean opinion score}
-
-\end_inset
-
-) subjective evaluation has been performed for Speex.
- In order to give an idea of the quality achivable with it, table 
-\begin_inset LatexCommand \ref{cap:quality_vs_bps}
-
-\end_inset
-
- presents my own subjective opinion on it.
- It sould be noted that different people will perceive the quality differently
- and that the person that designed the codec often has a bias (one way or
- another) when it comes to subjective evaluation.
- Last thing, it should be noted that for most codecs (including Speex) encoding
- quality sometimes varies depending on the input.
- Note that the complexity is only approximate (within 0.5 mflops and using
- the lowest complexity setting).
- Decoding requires approximately 0.5 mflops
-\begin_inset LatexCommand \index{complexity}
-
 \end_inset
-
- in most modes (1 mflops with perceptual enhancement).
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float table
-placement h
-wide true
-sideways false
-status open
-
-\begin_layout Standard
-\begin_inset Tabular
-<lyxtabular version="3" rows="17" columns="4">
-<features>
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
-<row topline="true" bottomline="true">
+</cell>
+</row>
+<row>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-Mode
+\begin_layout Plain Layout
+9
 \end_layout
 
 \end_inset
@@ -5483,13 +9391,17 @@ Mode
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-Bit-rate
-\begin_inset LatexCommand \index{bit-rate}
+\begin_layout Plain Layout
+-
+\end_layout
 
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- (bps)
+\begin_layout Plain Layout
+-
 \end_layout
 
 \end_inset
@@ -5497,33 +9409,37 @@ Bit-rate
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-mflops
-\begin_inset LatexCommand \index{complexity}
+\begin_layout Plain Layout
+-
+\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>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-Quality/description
+\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">
 \begin_inset Text
 
-\begin_layout Standard
-0
+\begin_layout Plain Layout
+-
 \end_layout
 
 \end_inset
@@ -5531,8 +9447,8 @@ Quality/description
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-250
+\begin_layout Plain Layout
+-
 \end_layout
 
 \end_inset
@@ -5540,8 +9456,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
+-
 \end_layout
 
 \end_inset
@@ -5549,19 +9465,19 @@ N/A
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-No transmission (DTX)
+\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
-1
+\begin_layout Plain Layout
+11
 \end_layout
 
 \end_inset
@@ -5569,8 +9485,8 @@ No transmission (DTX)
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-2,150
+\begin_layout Plain Layout
+-
 \end_layout
 
 \end_inset
@@ -5578,37 +9494,37 @@ No transmission (DTX)
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-6
+\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" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-Vocoder (mostly for comfort noise)
+\begin_layout Plain Layout
+-
 \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" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-2
+\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 Standard
-5,950
+\begin_layout Plain Layout
+12
 \end_layout
 
 \end_inset
@@ -5616,66 +9532,64 @@ Vocoder (mostly for comfort noise)
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-9
+\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" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-Very noticeable artifacts/noise, good intelligibility
+\begin_layout Plain Layout
+-
 \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
-3
+\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" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-8,000
+\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 Standard
-10
+\begin_layout Plain Layout
+13
 \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
-Artifacts/noise sometimes noticeable
+\begin_layout Plain Layout
+-
 \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
-4
+\begin_layout Plain Layout
+-
 \end_layout
 
 \end_inset
@@ -5683,37 +9597,37 @@ Artifacts/noise sometimes noticeable
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-11,000
+\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" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-14
+\begin_layout Plain Layout
+Application-defined, interpreted by callback or skipped
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-Artifacts usually noticeable only with headphones
+\begin_layout Plain Layout
+14
 \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
+\begin_layout Plain Layout
+-
 \end_layout
 
 \end_inset
@@ -5721,8 +9635,8 @@ Artifacts usually noticeable only with headphones
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-15,000
+\begin_layout Plain Layout
+-
 \end_layout
 
 \end_inset
@@ -5730,8 +9644,8 @@ Artifacts usually noticeable only with headphones
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-11
+\begin_layout Plain Layout
+-
 \end_layout
 
 \end_inset
@@ -5739,247 +9653,415 @@ 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
-Need good headphones to tell the difference
+\begin_layout Plain Layout
+Speex in-band signaling
 \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
-6
+\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
-18,200
+\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
-17.5
+\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
-Hard to tell the difference even with good headphones
+\begin_layout Plain Layout
+-
 \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
-7
+\begin_layout Plain Layout
+Terminator code
 \end_layout
 
 \end_inset
 </cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+</row>
+</lyxtabular>
 
-\begin_layout Standard
-24,600
+\end_inset
+
+
+\begin_inset ERT
+status collapsed
+
+\begin_layout Plain Layout
+
+
+\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
-14.5
+
 \end_layout
 
+\begin_layout Plain Layout
+\begin_inset Caption
+
+\begin_layout Plain Layout
+Quality versus bit-rate
+\begin_inset CommandInset label
+LatexCommand label
+name "cap:quality_vs_bps"
+
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-Completely transparent for voice, good quality music
+
 \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
-8
+
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-3,950
+
+\end_layout
+
+\begin_layout Section
+Perceptual enhancement
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+perceptual enhancement
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
+
+\end_layout
 
 \begin_layout Standard
-10.5
+
+\series bold
+This section was only valid for version 1.1.12 and earlier.
+ It does not apply to version 1.2-beta1 (and later), for which the new perceptual
+ enhancement is not yet documented.
 \end_layout
 
+\begin_layout Standard
+This part of the codec only applies to the decoder and can even be changed
+ without affecting inter-operability.
+ For that reason, the implementation provided and described here should
+ only be considered as a reference implementation.
+ The enhancement system is divided into two parts.
+ First, the synthesis filter 
+\begin_inset Formula $S(z)=1/A(z)$
+\end_inset
+
+ is replaced by an enhanced filter:
+\begin_inset Formula \[
+S'(z)=\frac{A\left(z/a_{2}\right)A\left(z/a_{3}\right)}{A\left(z\right)A\left(z/a_{1}\right)}\]
+
+\end_inset
+
+where 
+\begin_inset Formula $a_{1}$
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+
+ and 
+\begin_inset Formula $a_{2}$
+\end_inset
+
+ depend on the mode in use and 
+\begin_inset Formula $a_{3}=\frac{1}{r}\left(1-\frac{1-ra_{1}}{1-ra_{2}}\right)$
+\end_inset
+
+ with 
+\begin_inset Formula $r=.9$
+\end_inset
+
+.
+ The second part of the enhancement consists of using a comb filter to enhance
+ the pitch in the excitation domain.
+\end_layout
 
 \begin_layout Standard
-Very noticeable artifacts/noise, good intelligibility
+\begin_inset Newpage newpage
+\end_inset
+
+
+\end_layout
+
+\begin_layout Chapter
+Speex wideband mode (sub-band CELP)
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+wideband
 \end_layout
 
 \end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
+
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Speex-wideband-mode"
+
+\end_inset
+
+
+\end_layout
 
 \begin_layout Standard
-9
+For wideband, the Speex approach uses a 
+\emph on
+q
+\emph default
+uadrature 
+\emph on
+m
+\emph default
+irror 
+\emph on
+f
+\emph default
+ilter
+\begin_inset Index
+status collapsed
+
+\begin_layout Plain Layout
+quadrature mirror filter
 \end_layout
 
 \end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
+ (QMF) to split the band in two.
+ The 16 kHz signal is thus divided into two 8 kHz signals, one representing
+ the low band (0-4 kHz), the other the high band (4-8 kHz).
+ The low band is encoded with the narrowband mode described in section 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Speex-narrowband-mode"
+
+\end_inset
+
+ in such a way that the resulting 
+\begin_inset Quotes eld
+\end_inset
+
+embedded narrowband bit-stream
+\begin_inset Quotes erd
+\end_inset
+
+ can also be decoded with the narrowband decoder.
+ Since the low band encoding has already been described, only the high band
+ encoding is described in this section.
+\end_layout
+
+\begin_layout Section
+Linear Prediction
+\end_layout
 
 \begin_layout Standard
-N/A
+The linear prediction part used for the high-band is very similar to what
+ is done for narrowband.
+ The only difference is that we use only 12 bits to encode the high-band
+ LSP's using a multi-stage vector quantizer (MSVQ).
+ The first level quantizes the 10 coefficients with 6 bits and the error
+ is then quantized using 6 bits, too.
 \end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+\begin_layout Section
+Pitch Prediction
+\end_layout
 
 \begin_layout Standard
-N/A
+That part is easy: there's no pitch prediction for the high-band.
+ There are two reasons for that.
+ First, there is usually little harmonic structure in this band (above 4
+ kHz).
+ Second, it would be very hard to implement since the QMF folds the 4-8
+ kHz band into 4-0 kHz (reversing the frequency axis), which means that
+ the location of the harmonics is no longer at multiples of the fundamental
+ (pitch).
 \end_layout
 
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+\begin_layout Section
+Excitation Quantization
+\end_layout
 
 \begin_layout Standard
-reserved
+The high-band excitation is coded in the same way as for narrowband.
 \end_layout
 
+\begin_layout Section
+Bit allocation
+\end_layout
+
+\begin_layout Standard
+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 CommandInset ref
+LatexCommand ref
+reference "cap:bits-narrowband"
+
 \end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
+
+.
+ The high-band follows, as described in table 
+\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
+
+.
+ This also means that a wideband frame may be correctly decoded by a narrowband
+ decoder with the only caveat that if more than one frame is packed in the
+ same packet, the decoder will need to skip the high-band parts in order
+ to sync with the bit-stream.
+\end_layout
 
 \begin_layout Standard
-10
+\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
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
 
-\begin_layout Standard
-N/A
+
+\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" 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
+Update rate
 \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
-reserved
+\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">
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-11
+\begin_layout Plain Layout
+1
 \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
+2
 \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
+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" bottomline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-reserved
+\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
-12
+\begin_layout Plain Layout
+Wideband bit
 \end_layout
 
 \end_inset
@@ -5987,8 +10069,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
+frame
 \end_layout
 
 \end_inset
@@ -5996,28 +10078,17 @@ N/A
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-N/A
-\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
+\begin_layout Plain Layout
+1
 \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
+\begin_layout Plain Layout
+1
 \end_layout
 
 \end_inset
@@ -6025,8 +10096,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
+1
 \end_layout
 
 \end_inset
@@ -6034,8 +10105,8 @@ 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
+1
 \end_layout
 
 \end_inset
@@ -6043,19 +10114,19 @@ N/A
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-Application-defined, interpreted by callback or skipped
+\begin_layout Plain Layout
+1
 \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
-14
+\begin_layout Plain Layout
+Mode ID
 \end_layout
 
 \end_inset
@@ -6063,8 +10134,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
+frame
 \end_layout
 
 \end_inset
@@ -6072,28 +10143,17 @@ N/A
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-N/A
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Standard
-Speex in-band signaling
+\begin_layout Plain Layout
+3
 \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
+\begin_layout Plain Layout
+3
 \end_layout
 
 \end_inset
@@ -6101,8 +10161,8 @@ Speex in-band signaling
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-N/A
+\begin_layout Plain Layout
+3
 \end_layout
 
 \end_inset
@@ -6110,8 +10170,8 @@ 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
+3
 \end_layout
 
 \end_inset
@@ -6119,226 +10179,84 @@ N/A
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-Terminator code
+\begin_layout Plain Layout
+3
 \end_layout
 
 \end_inset
 </cell>
 </row>
-</lyxtabular>
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Caption
-Quality versus bit-rate
-\begin_inset LatexCommand \label{cap:quality_vs_bps}
-
-\end_inset
-
+<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
 
-\begin_layout Subsection
-Perceptual enhancement
-\begin_inset LatexCommand \index{perceptual enhancement}
-
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-
+\begin_layout Plain Layout
+0
 \end_layout
 
-\begin_layout Standard
-This part of the codec only applies to the decoder and can even be changed
- without affecting inter-operability.
- For that reason, the implementation provided and described here should
- only be considered as a reference implementation.
- The enhancement system is divided into two parts.
- First, the synthesis filter 
-\begin_inset Formula $S(z)=1/A(z)$
-\end_inset
-
- is replaced by an enhanced filter
-\begin_inset Formula \[
-S'(z)=\frac{A\left(z/a_{2}\right)A\left(z/a_{3}\right)}{A\left(z\right)A\left(z/a_{1}\right)}\]
-
-\end_inset
-
-where 
-\begin_inset Formula $a_{1}$
-\end_inset
-
- and 
-\begin_inset Formula $a_{2}$
-\end_inset
-
- depend on the mode in use and 
-\begin_inset Formula $a_{3}=\frac{1}{r}\left(1-\frac{1-ra_{1}}{1-ra_{2}}\right)$
-\end_inset
-
- with 
-\begin_inset Formula $r=.9$
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-.
- The second part of the enhancement consists of using a comb filter to enhance
- the pitch in the excitation domain.
-\end_layout
-
-\begin_layout Standard
-
-\newpage
-
+\begin_layout Plain Layout
+12
 \end_layout
 
-\begin_layout Section
-Speex wideband mode (sub-band CELP)
-\begin_inset LatexCommand \index{wideband}
-
-\end_inset
-
-
-\begin_inset LatexCommand \label{sec:Speex-wideband-mode}
-
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
-
+\begin_layout Plain Layout
+12
 \end_layout
 
-\begin_layout Standard
-For wideband, the Speex approach uses a 
-\emph on
-q
-\emph default
-uadrature 
-\emph on
-m
-\emph default
-irror 
-\emph on
-f
-\emph default
-ilter
-\begin_inset LatexCommand \index{quadrature mirror filter}
-
-\end_inset
-
- (QMF) to split the band in two.
- The 16 kHz signal is thus divided into two 8 kHz signals, one representing
- the low band (0-4 kHz), the other the high band (4-8 kHz).
- The low band is encoded with the narrowband mode described in section 
-\begin_inset LatexCommand \ref{sec:Speex-narrowband-mode}
-
-\end_inset
-
- in such a way that the resulting 
-\begin_inset Quotes eld
-\end_inset
-
-embedded narrowband bit-stream
-\begin_inset Quotes erd
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
 
- can also be decoded with the narrowband decoder.
- Since the low band encoding has already been described, only the high band
- encoding is described in this section.
-\end_layout
-
-\begin_layout Subsection
-Linear Prediction
-\end_layout
-
-\begin_layout Standard
-The linear prediction part used for the high-band is very similar to what
- is done for narrowband.
- The only difference is that we use only 12 bits to encode the high-band
- LSP's using a multi-stage vector quantizer (MSVQ).
- The first level quantizes the 10 coefficients with 6 bits and the error
- is then quantized using 6 bits, too.
-\end_layout
-
-\begin_layout Subsection
-Pitch Prediction
-\end_layout
-
-\begin_layout Standard
-That part is easy: there's no pitch prediction for the high-band.
- There are two reasons for that.
- First, there is usually little harmonic structure in this band (above 4
- kHz).
- Second, it would be very hard to implement since the QMF folds the 4-8
- kHz band into 4-0 kHz (reversing the frequency axis), which means that
- the location of the harmonics is no longer at multiples of the fundamental
- (pitch).
-\end_layout
-
-\begin_layout Subsection
-Excitation Quantization
-\end_layout
-
-\begin_layout Standard
-The high-band excitation is coded in the same way as for narrowband.
-\end_layout
-
-\begin_layout Subsection
-Bit allocation
+\begin_layout Plain Layout
+12
 \end_layout
 
-\begin_layout Standard
-For the wideband mode, the entire narrowband frame is packed before the
- high-band is encoded.
- The narrowband part of the bit-stream is as defined in table 
-\begin_inset LatexCommand \ref{cap:bits-narrowband}
-
-\end_inset
-
-.
- The high-band follows, as described in table 
-\begin_inset LatexCommand \ref{cap:bits-wideband}
-
 \end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
-.
- This also means that a wideband frame may be correctly decoded by a narrowband
- decoder with the only caveat that if more than one frame is packed in the
- same packet, the decoder will need to skip the high-band parts in order
- to sync with the bit-stream.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float table
-placement h
-wide true
-sideways false
-status open
+\begin_layout Plain Layout
+12
+\end_layout
 
-\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">
+\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
@@ -6346,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
@@ -6355,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
 
@@ -6364,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
@@ -6373,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
@@ -6382,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
 
@@ -6559,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
@@ -6586,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
@@ -6606,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
@@ -6633,55 +10656,57 @@ 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" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-4
+\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
 
 \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
-Excitation VQ
+\begin_layout Plain Layout
+12,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
-sub-frame
+\begin_layout Plain Layout
+Artifacts/noise usually 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
+5
 \end_layout
 
 \end_inset
@@ -6689,26 +10714,28 @@ sub-frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-0
+\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
-20
+\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
-40
+\begin_layout Plain Layout
+6
 \end_layout
 
 \end_inset
@@ -6716,19 +10743,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
+20,600
+\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
+Need good headphones to tell the difference
 \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
-Total
+\begin_layout Plain Layout
+7
 \end_layout
 
 \end_inset
@@ -6736,17 +10772,28 @@ Total
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-frame
+\begin_layout Plain Layout
+23,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
+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
-4
+\begin_layout Plain Layout
+8
 \end_layout
 
 \end_inset
@@ -6754,26 +10801,28 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-36
+\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
-112
+\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
-192
+\begin_layout Plain Layout
+9
 \end_layout
 
 \end_inset
@@ -6781,59 +10830,64 @@ frame
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 \begin_inset Text
 
-\begin_layout Standard
-352
+\begin_layout Plain Layout
+34,200
 \end_layout
 
 \end_inset
 </cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
+\begin_layout Plain Layout
+Hard to tell the difference even with good headphones
 \end_layout
 
-\begin_layout Caption
-Bit allocation for high-band in wideband mode
-\begin_inset LatexCommand \label{cap:bits-wideband}
-
 \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
+10
 \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
+42,200
 \end_layout
 
-\begin_layout Standard
-\begin_inset ERT
-status open
-
-\begin_layout Standard
-
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
 
-\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
@@ -6841,417 +10895,177 @@ clearpage
 
 \end_layout
 
-\begin_layout Section
-\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 the most permissive of the 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 (15 kbps for version < 1.1.1).
- Also, make sure you don't use the lowest complexity (see SPEEX_SET_COMPLEXITY
- or --comp option), as it causes significant noise.
-\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
-Currently (2005/05/11), I'm doing my 
-\emph on
-Ph.D.
-
-\emph default
- at the University of Sherbrooke in mobile robotics.
- Although I did my master with the Sherbrooke speech coding group (in speech
- enhancement, not coding), I am not associated with them anymore.
- It should 
+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
+\begin_inset CommandInset include
+LatexCommand lstinputlisting
+filename "sampledec.c"
+lstparams "caption={Source code for sampledec},label={sampledec-source-code},numbers=left,numberstyle={\\footnotesize}"
 
-Code Excited Linear Prediction
-\begin_inset Quotes erd
-\end_inset
-
-, while ACELP stands for 
-\begin_inset Quotes eld
 \end_inset
 
 
-\emph on
-Algebraic
-\emph default
- Code Excited Linear Prediction
-\begin_inset Quotes erd
-\end_inset
-
-.
- That means ACELP is a CELP technique that uses an algebraic codebook represente
-d as a sum of unit pulses, thus making the codebook search much more efficient.
- This technique was invented at the University of Sherbrooke and is now
- one of the most widely used form of CELP.
- Unfortunately, since it is patented, it cannot be used in Speex.
 \end_layout
 
 \begin_layout Standard
-
-\newpage
-
-\end_layout
-
-\begin_layout Section
-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 Subsection
-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 Subsection
-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 Section
+\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
 
@@ -7259,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
 
@@ -7268,14 +11083,17 @@ preview false
 \end_layout
 
 \begin_layout Standard
+\begin_inset Newpage newpage
+\end_inset
 
-\newpage
 
 \end_layout
 
-\begin_layout Section
+\begin_layout Chapter
 Speex License
-\begin_inset LatexCommand \label{sec:Speex-License}
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Speex-License"
 
 \end_inset
 
@@ -7283,49 +11101,23 @@ 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
 
-\begin_layout Section
+\begin_layout Chapter
 GNU Free Documentation License
 \end_layout
 
@@ -7341,7 +11133,7 @@ Copyright (C) 2000 Free Software Foundation, Inc.
  
 \end_layout
 
-\begin_layout Subsection*
+\begin_layout Section*
 0.
  PREAMBLE
 \end_layout
@@ -7375,7 +11167,7 @@ We have designed this License in order to use it for manuals for free software,
  
 \end_layout
 
-\begin_layout Subsection*
+\begin_layout Section*
 1.
  APPLICABILITY AND DEFINITIONS
 \end_layout
@@ -7453,7 +11245,7 @@ The "Title Page" means, for a printed book, the title page itself, plus
  preceding the beginning of the body of the text.
 \end_layout
 
-\begin_layout Subsection*
+\begin_layout Section*
 2.
  VERBATIM COPYING
 \end_layout
@@ -7476,7 +11268,7 @@ You may also lend copies, under the same conditions stated above, and you
  may publicly display copies.
 \end_layout
 
-\begin_layout Subsection*
+\begin_layout Section*
 3.
  COPYING IN QUANTITY
 \end_layout
@@ -7525,7 +11317,7 @@ It is requested, but not required, that you contact the authors of the Document
  
 \end_layout
 
-\begin_layout Subsection*
+\begin_layout Section*
 4.
  MODIFICATIONS
 \end_layout
@@ -7677,7 +11469,7 @@ nt of any Modified Version.
  
 \end_layout
 
-\begin_layout Subsection*
+\begin_layout Section*
 5.
  COMBINING DOCUMENTS
 \end_layout
@@ -7709,7 +11501,7 @@ In the combination, you must combine any sections entitled "History" in
  You must delete all sections entitled "Endorsements."
 \end_layout
 
-\begin_layout Subsection*
+\begin_layout Section*
 6.
  COLLECTIONS OF DOCUMENTS
 \end_layout
@@ -7730,7 +11522,7 @@ You may extract a single document from such a collection, and distribute
  
 \end_layout
 
-\begin_layout Subsection*
+\begin_layout Section*
 7.
  AGGREGATION WITH INDEPENDENT WORKS
 \end_layout
@@ -7754,7 +11546,7 @@ If the Cover Text requirement of section 3 is applicable to these copies
  Otherwise they must appear on covers around the whole aggregate.
 \end_layout
 
-\begin_layout Subsection*
+\begin_layout Section*
 8.
  TRANSLATION
 \end_layout
@@ -7772,7 +11564,7 @@ Translation is considered a kind of modification, so you may distribute
  version of this License, the original English version will prevail.
 \end_layout
 
-\begin_layout Subsection*
+\begin_layout Section*
 9.
  TERMINATION
 \end_layout
@@ -7788,7 +11580,7 @@ You may not copy, modify, sublicense, or distribute the Document except
  
 \end_layout
 
-\begin_layout Subsection*
+\begin_layout Section*
 10.
  FUTURE REVISIONS OF THIS LICENSE
 \end_layout
@@ -7814,7 +11606,8 @@ n.
 \end_layout
 
 \begin_layout Standard
-\begin_inset LatexCommand \printindex{}
+\begin_inset CommandInset index_print
+LatexCommand printindex
 
 \end_inset