Patch by David Rowe: normalize16() on Blackfin now writes data 16-bit at a time
[speexdsp.git] / doc / manual.lyx
index c3c4d32..d8ea5dc 100644 (file)
@@ -1,15 +1,12 @@
 #LyX 1.3 created this file. For more info see http://www.lyx.org/
 \lyxformat 221
 \textclass article
-\begin_preamble
-\usepackage{times}
-\end_preamble
 \language english
 \inputencoding auto
-\fontscheme default
+\fontscheme pslatex
 \graphics default
 \paperfontsize default
-\spacing single 
+\spacing onehalf 
 \papersize letterpaper
 \paperpackage a4
 \use_geometry 0
 
 The Speex Codec Manual
 \newline 
-(version 1.0)
+(version 1.1.11)
 \layout Author
 
 Jean-Marc Valin
 \layout Standard
 \pagebreak_top 
-Copyright (c) 2002-2003 Jean-Marc Valin.
+Copyright (c) 2002-2005 Jean-Marc Valin/Xiph.org Foundation
 \layout Standard
 
 Permission is granted to copy, distribute and/or modify this document under
@@ -78,13 +75,13 @@ http://www.speex.org/
  There is already Vorbis that does general audio, but it is not really suitable
  for speech.
  Also, unlike many other speech codecs, Speex is not targeted at cell phones
- (not many open-source cell phones anyway :-) ) but rather voice over IP
- (VoIP) and file-based compression.
+ (not many open-source cell phones anyway :-) ) but rather at voice over
IP (VoIP) and file-based compression.
  
 \layout Standard
 
-As design goals, we wanted to have a codec that would allowed both very
good quality speech and low bit-rate (unfortunately not at the same time!),
+As design goals, we wanted to have a codec that would allow both very good
+ quality speech and low bit-rate (unfortunately not at the same time!),
  which led us to developing a codec with multiple bit-rates.
  Of course very good quality also meant we had to do wideband (16 kHz sampling
  rate) in addition to narrowband (telephone quality, 8 kHz sampling rate).
@@ -93,7 +90,7 @@ As design goals, we wanted to have a codec that would allowed both very
 Designing for VoIP instead of cell phone use means that Speex must be robust
  to lost packets, but not to corrupted ones since packets either arrive
  unaltered or don't arrive at all.
- Also, the idea was to have a reasonnable complexity and memory requirement
+ Also, the idea was to have a reasonable complexity and memory requirement
  without compromising too much on the efficiency of the codec.
 \layout Standard
 
@@ -109,7 +106,7 @@ All this led us to the choice of CELP
  
 \layout Standard
 
-The main characteristics can be summerized as follows:
+The main characteristics can be summarized as follows:
 \layout Itemize
 
 Free software/open-source
@@ -135,7 +132,7 @@ Integration of narrowband
 
 \end_inset 
 
in the same bit-stream
using an embedded bit-stream
 \layout Itemize
 
 Wide range of bit-rates available (from 2 kbps to 44 kbps)
@@ -169,6 +166,9 @@ Ultra-wideband mode at 32 kHz (up to 48 kHz)
 \layout Itemize
 
 Intensity stereo encoding option
+\layout Itemize
+
+Fixed-point implementation (work in progress)
 \layout Standard
 
 This document is divided in the following way.
@@ -177,7 +177,7 @@ This document is divided in the following way.
 
 \end_inset 
 
- describes the different Speex features and define some terms that will
+ describes the different Speex features and defines some terms that will
  be used in later sections.
  Section 
 \begin_inset LatexCommand \ref{sec:Command-line-encoder/decoder}
@@ -189,7 +189,7 @@ This document is divided in the following way.
 
 \end_inset 
 
- contrains information about programming using the Speex API.
+ contains information about programming using the Speex API.
  Section 
 \begin_inset LatexCommand \ref{sec:Formats-and-standards}
 
@@ -218,7 +218,7 @@ This document is divided in the following way.
  are not required.
 \layout Section
 \pagebreak_top 
-Feature description
+Codec description
 \begin_inset LatexCommand \label{sec:Feature-description}
 
 \end_inset 
@@ -226,9 +226,15 @@ Feature description
 
 \layout Standard
 
-This section explains the main Speex features, as well as some concepts
- in speech coding that help better understand the next sections.
+This section describes the main features provided by Speex.
+\layout Subsection
+
+Concepts
+\layout Standard
+
+Here are some concepts in speech coding that help better understand the
+ rest of the manual.
+ Emphasis is placed on the Speex features.
 \layout Subsection*
 
 Sampling rate
@@ -269,7 +275,7 @@ Quality
 \layout Standard
 
 Speex encoding is controlled most of the time by a quality parameter that
- range from 0 to 10.
+ ranges from 0 to 10.
  In constant bit-rate
 \begin_inset LatexCommand \index{constant bit-rate}
 
@@ -300,9 +306,9 @@ gzip
 bzip2
 \emph default 
  compression utilities.
- For normal use, the noise level at complexity 1is between 1 and 2 dB higher
+ For normal use, the noise level at complexity 1 is between 1 and 2 dB higher
  than at complexity 10, but the CPU requirements for complexity 10 is about
- 5 time higher than for complexity 1.
+ 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}
@@ -353,7 +359,7 @@ Average Bit-Rate
 Average bit-rate solves one of the problems of VBR, as it dynamically adjusts
  VBR quality in order to meet a specific target bit-rate.
  Because the quality/bit-rate is adjusted in real-time (open-loop), the
- global quality will be slightly lower than that obtained be encoding in
+ global quality will be slightly lower than that obtained by encoding in
  VBR with exactly the right quality setting to meet the target average bit-rate.
 \layout Subsection*
 
@@ -391,7 +397,7 @@ Discontinuous Transmission
 \layout Standard
 
 Discontinuous transmission is an addition to VAD/VBR operation, that allows
- to stop transmitting completely when the background noise is stationnary.
+ to stop transmitting completely when the background noise is stationary.
  In file-based operation, since we cannot just stop writing to the file,
  only 5 bits are used for such frames (corresponding to 250 bps).
 \layout Subsection*
@@ -441,6 +447,140 @@ look-ahead
  (16 kHz), the delay is 34 ms.
  These values don't account for the CPU time it takes to encode or decode
  the frames.
+\layout Subsection
+
+Codec
+\layout Subsection
+
+Preprocessor
+\layout Standard
+
+This part refers to the preprocessor module introduced in the 1.1.x branch.
+ The preprocessor is designed to be used on the audio 
+\emph on 
+before
+\emph default 
+ running the encoder.
+ The preprocessor provides three main functionalities:
+\layout Itemize
+
+denoising
+\layout Itemize
+
+automatic gain control (AGC)
+\layout Itemize
+
+voice activity detection (VAD)
+\layout Standard
+
+The denoiser can be used to reduce the amount of background noise present
+ in the input signal.
+ This provides higher quality speech whether or not the denoised signal
+ is encoded with Speex (or at all).
+ However, when using the denoised signal with the codec, there is an additional
+ benefit.
+ Speech codecs in general (Speex included) tend to perform poorly on noisy
+ input, which tends to amplify the noise.
+ The denoiser greatly reduces this effect.
+\layout Standard
+
+Automatic gain control (AGC) is a feature that deals with the fact that
+ the recording volume may vary by a large amount between different setups.
+ The AGC provides a way to adjust a signal to a reference volume.
+ This is useful for voice over IP because it removes the need for manual
+ adjustment of the microphone gain.
+ A secondary advantage is that by setting the microphone gain to a conservative
+ (low) level, it is easier to avoid clipping.
+\layout Standard
+
+The voice activity detector (VAD) provided by the preprocessor is more advanced
+ than the one directly provided in the codec.
+\layout Subsection
+
+Adaptive Jitter Buffer
+\layout Subsection
+
+Acoustic Echo Canceller
+\layout Section
+\pagebreak_top 
+Compiling
+\layout Standard
+
+Compiling Speex under UNIX or any platform supported by autoconf (e.g.
+ Win32/cygwin) is as easy as typing:
+\layout LyX-Code
+
+% ./configure [options]
+\layout LyX-Code
+
+% make
+\layout LyX-Code
+
+% make install
+\layout Standard
+
+The options supported by the Speex configure script are:
+\layout Description
+
+--prefix=<path> Specifies where to install Speex
+\layout Description
+
+--enable-shared/--disable-shared Whether to compile shared libraries
+\layout Description
+
+--enable-static/--disable-static Whether to compile static libraries
+\layout Description
+
+--disable-wideband Disable the wideband part of Speex (typically to same
+ space)
+\layout Description
+
+--enable-valgrind Enable extra information when (and only when) running
+ with valgrind
+\layout Description
+
+--enable-sse Enable use of SSE instructions (x86/float only)
+\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)
+\layout Description
+
+--enable-arm4-asm Enable assembly specific to the ARMv4 architecture (gcc
+ only)
+\layout Description
+
+--enable-arm5e-asm Enable assembly specific to the ARMv5E architecture (gcc
+ only)
+\layout Description
+
+--enable-fixed-point-debug Use only for debugging the fixed-point
+\begin_inset LatexCommand \index{fixed-point}
+
+\end_inset 
+
+ code (very slow)
+\layout Description
+
+--enable-epic-48k Enable a special (and non-compatible) 4.8 kbps narrowband
+ mode
+\layout Description
+
+--enable-ti-c55x Enable support for the TI C5x family
+\layout Description
+
+--enable-blackfin-asm Enable assembly specific to the Blackfin DSP architecture
+ (gcc only)
+\layout Description
+
+--enable-16bit-precision Reduces precision to 16 bits in time-critical areas
+ (fixed-point only)
 \layout Section
 \pagebreak_top 
 Command-line encoder/decoder
@@ -637,7 +777,7 @@ The value '-' for input_file or output_file corresponds respectively to
 \layout Description
 
 --rate\SpecialChar ~
-n For decoding at n Hz sampling rate
+n Force decoding at n Hz sampling rate
 \layout Description
 
 --packet-loss\SpecialChar ~
@@ -683,12 +823,17 @@ This section explains how to use the Speex API.
 \layout Subsection
 
 Encoding
+\begin_inset LatexCommand \label{sub:Encoding}
+
+\end_inset 
+
+
 \layout Standard
 
 In order to encode speech using Speex, you first need to:
 \layout LyX-Code
 
-#include <speex.h>
+#include <speex/speex.h>
 \layout Standard
 
 You then need to declare a Speex bit-packing struct
@@ -733,6 +878,13 @@ frame_size
 speex_encoder_ctl(enc_state,SPEEX_GET_FRAME_SIZE,&frame_size);
 \layout Standard
 
+In practice, 
+\emph on 
+frame_size
+\emph default 
+ will correspond to 20 ms when using 8, 16, or 32 kHz sampling rate.
+\layout Standard
+
 Once the initialization is done, for every input frame:
 \layout LyX-Code
 
@@ -784,7 +936,19 @@ byte_ptr
 speex_bits_nbytes(&bits)
 \family default 
 , which returns a number of bytes.
+\layout Standard
+
+When using an unstable release (1.1.x), it is possible to use the 
+\emph on 
+speex_encode_int()
+\emph default 
+ function, which takes a 
+\emph on 
+(short *)
+\emph default 
+ for the audio.
+ This is usually simpler and it makes an eventual port to an FPU-less platform
+ (like ARM) easier.
 \layout Standard
 
 After you're done with the encoding, free all resources with:
@@ -801,12 +965,17 @@ That's about it for the encoder.
 \layout Subsection
 
 Decoding
+\begin_inset LatexCommand \label{sub:Decoding}
+
+\end_inset 
+
+
 \layout Standard
 
-In order to encode speech using Speex, you first need to:
+In order to decode speech using Speex, you first need to:
 \layout LyX-Code
 
-#include <speex.h>
+#include <speex/speex.h>
 \layout Standard
 
 You also need to declare a Speex bit-packing struct
@@ -815,7 +984,7 @@ You also need to declare a Speex bit-packing struct
 SpeexBits bits;
 \layout Standard
 
-and a Speex encoder state
+and a Speex decoder state
 \layout LyX-Code
 
 void *dec_state;
@@ -872,7 +1041,7 @@ Again, once the decoder initialization is done, for every input frame:
 speex_bits_read_from(&bits, input_bytes, nbBytes);
 \layout LyX-Code
 
-speex_decode(st, &bits, output_frame);
+speex_decode(dec_state, &bits, output_frame);
 \layout Standard
 
 where input_bytes is a 
@@ -898,6 +1067,17 @@ output_frame
  correct signal.
 \layout Standard
 
+As for the encoder, the 1.1.x branch introduces the 
+\emph on 
+speex_decode_int()
+\emph default 
+ function which also uses a 
+\emph on 
+(short *)
+\emph default 
+ as the output for the audio.
+\layout Standard
+
 After you're done with the decoding, free all resources with:
 \layout LyX-Code
 
@@ -907,7 +1087,305 @@ speex_bits_destroy(&bits);
 speex_decoder_destroy(dec_state);
 \layout Subsection
 
+Preprocessor
+\begin_inset LatexCommand \label{sub:Preprocessor}
+
+\end_inset 
+
+
+\layout Standard
+
+In order to use the Speex preprocessor
+\begin_inset LatexCommand \index{preprocessor}
+
+\end_inset 
+
+, you first need to:
+\layout LyX-Code
+
+#include <speex/speex_preprocess.h>
+\layout Standard
+
+Then, a preprocessor state can be created as:
+\layout LyX-Code
+
+SpeexPreprocessState *preprocess_state = speex_preprocess_state_init(frame_size,
+ sampling_rate);
+\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 
+).
+\layout Standard
+
+For each input frame, you need to call:
+\layout LyX-Code
+
+speex_preprocess(preprocess_state, audio_frame, echo_residue);
+\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.
+\layout Standard
+
+In cases where the output audio is not useful for a certain frame, it is
+ possible to use instead:
+\layout LyX-Code
+
+speex_preprocess_estimate_update(preprocess_state, audio_frame, echo_residue);
+\layout Standard
+
+This call will update all the preprocessor internal state variables without
+ computing the output audio, thus saving some CPU cycles.
+\layout Standard
+
+The behaviour of the preprocessor can be changed using:
+\layout LyX-Code
+
+speex_preprocess_ctl(preprocess_state, request, ptr);
+\layout Standard
+
+which is used in the same way as the encoder and decoder equivalent.
+ Options are listed in Section .
+\layout Standard
+
+The preprocessor state can be destroyed using:
+\layout LyX-Code
+
+speex_preprocess_state_destroy(preprocess_state);
+\layout Subsection
+
+Echo Cancellation
+\begin_inset LatexCommand \label{sub:Echo-Cancellation}
+
+\end_inset 
+
+
+\layout Standard
+
+The Speex library now includes an echo cancellation
+\begin_inset LatexCommand \index{echo cancellation}
+
+\end_inset 
+
+ algorithm suitable for Acoustic Echo Cancellation
+\begin_inset LatexCommand \index{acoustic echo cancellation}
+
+\end_inset 
+
+ (AEC).
+ In order to use the echo canceller, you first need to
+\layout LyX-Code
+
+#include <speex/speex_echo.h>
+\layout Standard
+
+Then, an echo canceller state can be created by:
+\layout LyX-Code
+
+SpeexEchoState *echo_state = speex_echo_state_init(frame_size, filter_length);
+\layout Standard
+
+where 
+\family typewriter 
+frame_size
+\family default 
+ is the amount of data (in samples) you want to process at once and 
+\family typewriter 
+filter_length
+\family default 
+ is the length (in samples) of the echo cancelling filter you want to use
+ (also known as 
+\shape italic 
+tail length
+\shape default 
+
+\begin_inset LatexCommand \index{tail length}
+
+\end_inset 
+
+).
+ It is recommended to use a frame size in the order of 20 ms (or equal to
+ the codec frame size) and make sure it is easy to perform an FFT of that
+ size (powers of two are better than prime sizes).
+ The recommended tail length is approximately the third of the room reverberatio
+n time.
+ For example, in a small room, reverberation time is in the order of 300
+ ms, so a tail length of 100 ms is a good choice (800 samples at 8000 Hz
+ sampling rate).
+\layout Standard
+
+Once the echo canceller state is created, audio can be processed by:
+\layout LyX-Code
+
+speex_echo_cancel(echo_state, input_frame, echo_frame, output_frame, residue);
+\layout Standard
+
+where 
+\family typewriter 
+input_frame
+\family default 
+ is the audio as captured by the microphone, 
+\family typewriter 
+echo_frame
+\family default 
+ is the signal that was played in the speaker (and needs to be removed)
+ and 
+\family typewriter 
+output_frame
+\family default 
+ is the signal with echo removed.
+ The 
+\family typewriter 
+residue
+\family default 
+ parameter is optional (you can set it to NULL) and is used to return the
+ estimated power spectrum of the echo residue so it can be removed by the
+ preprocessor (if you with to use it).
+\layout Standard
+
+One important thing to keep in mind is the relationship between 
+\family typewriter 
+input_frame
+\family default 
+ and 
+\family typewriter 
+echo_frame
+\family default 
+.
+ It is important that, at any time, any echo that is present in the input
+ has already been sent to the echo canceller as 
+\family typewriter 
+echo_frame
+\family default 
+.
+ In other words, the echo canceller cannot remove a signal that it hasn't
+ yet received.
+ On the other hand, the delay between the input signal and the echo signal
+ must be small enough because otherwise part of the echo cancellation filter
+ is inefficient.
+ In the ideal case, you code would look like:
+\layout LyX-Code
+
+write_to_soundcard(echo_frame, frame_size);
+\layout LyX-Code
+
+read_from_soundcard(input_frame, frame_size);
+\layout LyX-Code
+
+speex_echo_cancel(echo_state, input_frame, echo_frame, output_frame, residue);
+\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}
+
+\end_inset 
+
+).
+\layout Standard
+
+The echo cancellation state can be destroyed as:
+\layout LyX-Code
+
+speex_echo_state_destroy(echo_state);
+\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 as:
+\layout LyX-Code
+
+speex_echo_state_reset(echo_state);
+\layout Subsubsection
+
+Troubleshooting
+\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
+\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 
+
+ on the same clock source.
+\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.
+\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.
+\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.
+\layout Subsection
+
 Codec Options (speex_*_ctl)
+\begin_inset LatexCommand \label{sub:Codec-Options}
+
+\end_inset 
+
+
 \layout Standard
 
 The Speex encoder and decoder support many options and requests that can
@@ -1076,6 +1554,14 @@ SPEEX_SET_ABR* Set average bit-rate
 SPEEX_GET_ABR* Get average bit-rate (ABR) setting (integer in bps)
 \layout Description
 
+SPEEX_SET_PLC_TUNING* Tell the encoder to optimize encoding for a certain
+ percentage of packet loss (integer in percent)
+\layout Description
+
+SPEEX_GET_PLC_TUNING* Get the current tuning of the encoder for PLC (integer
+ in percent)
+\layout Description
+
 * applies only to the encoder
 \layout Description
 
@@ -1090,10 +1576,15 @@ SPEEX_GET_ABR* Get average bit-rate (ABR) setting (integer in bps)
 \layout Subsection
 
 Mode queries
+\begin_inset LatexCommand \label{sub:Mode-queries}
+
+\end_inset 
+
+
 \layout Standard
 
-Speex modes have a querry system similar to the speex_encoder_ctl and speex_deco
-der_ctl calls.
+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:
@@ -1113,7 +1604,7 @@ ptr
 SPEEX_MODE_FRAME_SIZE Get the frame size (in samples) for the mode
 \layout Description
 
-SPEEX_SUBMODE_BITRATE Get the bit-rate for a submode number specified throught
+SPEEX_SUBMODE_BITRATE Get the bit-rate for a submode number specified through
  
 \emph on 
 ptr
@@ -1122,6 +1613,59 @@ ptr
  
 \layout Subsection
 
+Preprocessor options
+\begin_inset LatexCommand \label{sub:Preprocessor-options}
+
+\end_inset 
+
+
+\layout Description
+
+SPEEX_PREPROCESS_SET_DENOISE Turns denoising on(1) or off(2) (integer)
+\layout Description
+
+SPEEX_PREPROCESS_GET_DENOISE Get denoising status (integer)
+\layout Description
+
+SPEEX_PREPROCESS_SET_AGC Turns automatic gain control (AGC) on(1) or off(2)
+ (integer)
+\layout Description
+
+SPEEX_PREPROCESS_GET_AGC Get AGC status (integer)
+\layout Description
+
+SPEEX_PREPROCESS_SET_VAD Turns voice activity detector (VAD) on(1) or off(2)
+ (integer)
+\layout Description
+
+SPEEX_PREPROCESS_GET_VAD Get VAD status (integer)
+\layout Description
+
+SPEEX_PREPROCESS_SET_AGC_LEVEL
+\layout Description
+
+SPEEX_PREPROCESS_GET_AGC_LEVEL
+\layout Description
+
+SPEEX_PREPROCESS_SET_DEREVERB Turns reverberation removal on(1) or off(2)
+ (integer)
+\layout Description
+
+SPEEX_PREPROCESS_GET_DEREVERB Get reverberation removal status (integer)
+\layout Description
+
+SPEEX_PREPROCESS_SET_DEREVERB_LEVEL
+\layout Description
+
+SPEEX_PREPROCESS_GET_DEREVERB_LEVEL
+\layout Description
+
+SPEEX_PREPROCESS_SET_DEREVERB_DECAY
+\layout Description
+
+SPEEX_PREPROCESS_GET_DEREVERB_DECAY
+\layout Subsection
+
 Packing and in-band signalling
 \begin_inset LatexCommand \index{in-band signalling}
 
@@ -1140,13 +1684,16 @@ Sometimes it is desirable to pack more than one frame per packet (or other
  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 figur
+ as shown in Tabl
 \begin_inset LatexCommand \ref{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.
 \layout Standard
 
 It is also possible to send in-band 
@@ -1158,11 +1705,11 @@ messages
 \end_inset 
 
  to the other side.
- All these messages are encoded as 
+ All these messages are encoded as 
 \begin_inset Quotes eld
 \end_inset 
 
-pseudo-frame
+pseudo-frames
 \begin_inset Quotes erd
 \end_inset 
 
@@ -1173,7 +1720,7 @@ pseudo-frame
 \end_inset 
 
  lists the available codes, their meaning and the size of the message that
- follow.
+ 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.
@@ -1200,7 +1747,7 @@ collapsed false
 
 \layout Standard
 
-code
+Code
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1682,9 +2229,9 @@ Formats and standards
 
 Speex can encode speech in both narrowband and wideband and provides different
  bit-rates.
- However not all features must be supported by a certain implementation
+ However, not all features need to be supported by a certain implementation
  or device.
- In order to be sai
+ In order to be calle
 \begin_inset Quotes eld
 \end_inset 
 
@@ -1748,7 +2295,7 @@ The RTP payload draft is included in appendix
 MIME Type
 \layout Standard
 
-For now, you should use the MIME type audio/speex for Speex.
+For now, you should use the MIME type audio/x-speex for Speex-in-Ogg.
  We will apply for type 
 \family typewriter 
 audio/speex
@@ -1789,10 +2336,10 @@ Speex
 \SpecialChar ~
 \SpecialChar ~
 
-\begin_inset Quotes eld
+\begin_inset Quotes erd
 \end_inset 
 
- (with 3 training spaces), which identifies the bit-stream.
+ (with 3 trailing spaces), which identifies the bit-stream.
  The next field, 
 \family typewriter 
 speex_version
@@ -1833,7 +2380,7 @@ granulepos=0
 .
 \layout Standard
 
-The third and subsequant packets each contain one or more (number found
+The third and subsequent packets each contain one or more (number found
  in header) Speex frames.
  These are identified with 
 \family typewriter 
@@ -2358,7 +2905,7 @@ Linear Prediction (LPC)
 
 \layout Standard
 
-Linear prediction is at the base of may speech coding techniques, including
+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]$
@@ -2520,8 +3067,8 @@ The filter coefficients
  to filtering in the frequency domain, reducing sharp resonances.
 \layout Standard
 
-The linear prediction model represents each speech sample as linear combination
- of past samples, plus an error signal called the excitation (or residual).
+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]\]
 
@@ -2794,8 +3341,8 @@ If a filter
 \begin_inset Formula $A(z/\gamma)$
 \end_inset 
 
filter will have its poles at 
-\begin_inset Formula $p_{i}^{'}=\gamma p_{i}$
+ will have its poles at 
+\begin_inset Formula $p'_{i}=\gamma p_{i}$
 \end_inset 
 
 , making it a flatter version of 
@@ -2878,7 +3425,7 @@ LPC Analysis
 \layout Standard
 
 An LPC analysis is first performed on a (asymetric Hamming) window that
- spans all the current frame and half a frame in advance.
+ 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}
 
@@ -3001,7 +3548,7 @@ In Speex, the innovation signal is quantized using sub-vector shape-only
  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 save many bits that would otherwise be allocated for a separate gain
+ This saves many bits that would otherwise be allocated for a separate gain
  at the price of a slight increase in complexity.
  
 \layout Subsection
@@ -4176,7 +4723,7 @@ So far, no MOS (Mean Opinion Score
  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 lowers complexity setting).
+ the lowest complexity setting).
  Decoding requires approximately 0.5 mflops
 \begin_inset LatexCommand \index{complexity}
 
@@ -4819,7 +5366,7 @@ This part of the codec only applies to the decoder and can even be changed
  without affecting inter-operability.
  For that reason, the implementation provided and described here should
  only be considered as a reference implementation.
- The enhancement system is devided in two parts.
+ The enhancement system is divided into two parts.
  First, the synthesis filter 
 \begin_inset Formula $S(z)=1/A(z)$
 \end_inset 
@@ -4899,7 +5446,7 @@ embedded narrowband bit-stream
 \end_inset 
 
  can also be decoded with the narrowband decoder.
- Since the low band encoding has already been described only the high band
+ Since the low band encoding has already been described, only the high band
  encoding is described in this section.
 \layout Subsection
 
@@ -4911,7 +5458,7 @@ The linear prediction part used for the high-band is very similar to what
  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.
+ is then quantized using 6 bits, too.
 \layout Subsection
 
 Pitch Prediction
@@ -4923,7 +5470,7 @@ That part is easy: there's no pitch prediction for the high-band.
  kHz).
  Second, it would be very hard to implement since the QMF folds the 4-8
  kHz band into 4-0 kHz (reversing the frequency axis), which means that
- the location of the harmonics are no longer at multiples of the fundamental
+ the location of the harmonics is no longer at multiples of the fundamental
  (pitch).
 \layout Subsection
 
@@ -4937,8 +5484,8 @@ The high-band excitation is coded in the same way as for narrowband.
 Bit allocation
 \layout Standard
 
-For the wideband mode, all the narrowband frame is packed before the high-band
- is encoded.
+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}
 
@@ -5439,7 +5986,7 @@ Vorbis is open-source
 
 \end_inset 
 
-, why do we need Speex?
+; why do we need Speex?
 \layout Standard
 
 Vorbis is a great project but its goals are not the same as Speex.
@@ -5449,11 +5996,12 @@ Vorbis is a great project but its goals are not the same as Speex.
  typically 2-4 times higher compression at equal quality.
 \layout Subsection*
 
-Isn't there a GPL implementation of the GSM-FR codec? Why is Speex necessary?
+Isn't there an open-source implementation of the GSM-FR codec? Why is Speex
+ necessary?
 \layout Standard
 
-First of all, it's not clear whether or not GSM-FR is covered by a phillips
patent (see http://kbs.cs.tu-berlin.de/~jutta/toast.html).
+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
@@ -5463,10 +6011,31 @@ First of all, it's not clear whether or not GSM-FR is covered by a phillips
 Under what license is Speex released?
 \layout Standard
 
-As of version 1.0 beta 1, Speex in released under Xiph's BSD-like license.
+As of version 1.0 beta 1, Speex is released under Xiph's version of the (revised)
+ BSD license (see Appendix 
+\begin_inset LatexCommand \ref{sec:Speex-License}
+
+\end_inset 
+
+).
  This license is the most permissive of the open-source licenses.
 \layout Subsection*
 
+Am I allowed to use Speex in commercial software?
+\layout Standard
+
+Yes.
+ As long as you comply with the license.
+ This basically means you have to keep the copyright notice and you can't
+ use our name to promote your product without authorization.
+ For more details, see license in Appendix 
+\begin_inset LatexCommand \ref{sec:Speex-License}
+
+\end_inset 
+
+.
+\layout Subsection*
+
 Ogg
 \begin_inset LatexCommand \index{Ogg}
 
@@ -5480,15 +6049,7 @@ Ogg
 , what's the difference?
 \layout Standard
 
-Ogg is a 
-\begin_inset Quotes eld
-\end_inset 
-
-container format
-\begin_inset Quotes erd
-\end_inset 
-
- for holding multimedia data.
+Ogg is a container format for holding multimedia data.
  Vorbis is an audio codec that uses Ogg to store its bit-streams as files,
  hence the name Ogg Vorbis.
  Speex also uses the Ogg format to store its bit-streams as files, so technicall
@@ -5502,15 +6063,15 @@ Ogg Speex
 
  files (I prefer to call them just Speex files).
  One difference with Vorbis however, is that Speex is less tied with Ogg.
- Actually, if what you do is Voice of IP (VoIP), you don't need Ogg at all.
+ Actually, if you just do Voice over IP (VoIP), you don't need Ogg at all.
 \layout Subsection*
 
 What's the extension for Speex?
 \layout Standard
 
 Speex files have the .spx extension.
- Note however that all the Speex tools (speexenc, speexdec) do not rely
on the extension at all so any extension will work.
+ Note, however that the Speex tools (speexenc, speexdec) do not rely on
the extension at all, so any extension will work.
 \layout Subsection*
 
 Can I use Speex for compressing music
@@ -5526,7 +6087,7 @@ Just like Vorbis is not really adapted to speech, Speex is really not adapted
  In most cases, you'll be better of with Vorbis when it comes to music.
 \layout Subsection*
 
-I converted some MP3's to Speex and the quality is bad.
+I converted some MP3s to Speex and the quality is bad.
  What's wrong?
 \layout Standard
 
@@ -5541,8 +6102,8 @@ This is called transcoding and it will always result in much poorer quality
 Does Speex run on Windows?
 \layout Standard
 
-As of 0.8.0, Speex can now compile on Windows.
- There are also several front-ends available from the web site.
+Compilation on Windows has been supported since version 0.8.0.
+ There are also several front-ends available from the website.
 \layout Subsection*
 
 Why is encoding so slow compared to decoding?
@@ -5552,7 +6113,7 @@ For most kinds of compression, encoding is inherently slower than decoding.
  In the case of Speex, encoding consists of finding, for each vector of
  5 to 10 samples, the entry that matches the best within a codebook consisting
  of 16 to 256 entries.
- On the other hand, at decoding all that needs to be done is lookup the
+ On the other hand, at decoding all that needs to be done is look up the
  right entry in the codebook using the encoded index.
  Since a lookup is much faster than a search, the decoder works much faster
  than the encoder.
@@ -5561,10 +6122,11 @@ For most kinds of compression, encoding is inherently slower than decoding.
 Why is Speex so slow on my iPaq (or insert any platform without an FPU)?
 \layout Standard
 
-Well the parenthesis provides the answer: no FPU (floating-point unit).
- The Speex code makes heavy use of floating-point operations.
- On devices with no FPU, all floating-point instructions need to be emulated.
- This is a very time consuming operation.
+You probably didn't build Speex with the fixed-point option (--enable-fixed-poin
+t).
+ Even if you did, not all modes have been ported to use fixed-point arithmetic,
+ so the code may be slowed down by a few float operations left (e.g.
+ in the wideband mode).
 \layout Subsection*
 
 I'm getting unusual background noise (hiss) when using libspeex in my applicatio
@@ -5572,7 +6134,7 @@ n.
  How do I fix that?
 \layout Standard
 
-One of the cause could be scaling of the input speech.
+One of the causes could be scaling of the input speech.
  Speex expects signals to have a 
 \begin_inset Formula $\pm2^{15}$
 \end_inset 
@@ -5609,6 +6171,23 @@ There are many possible causes for that.
  causing clipping when saving as 16-bit PCM.
 \layout Subsection*
 
+How does Speex compare to other proprietary codecs?
+\layout Standard
+
+It's hard to give precise figures since no formal listening tests have been
+ performed yet.
+ All I can say is that in terms of quality, Speex competes on the same ground
+ as other proprietary codecs (not necessarily the best, but not the worst
+ either).
+ Speex also has many features that are not present in most other codecs.
+ These include variable bit-rate (VBR), integration of narrowband and wideband,
+ as well as stereo support.
+ Of course, another area where Speex is really hard to beat is the quality/price
+ ratio.
+ Unlike many very expensive codecs, Speex is free and anyone may distribute
+ or modify it at will.
+\layout Subsection*
+
 Can Speex pass DTMF
 \begin_inset LatexCommand \index{DTMF}
 
@@ -5618,24 +6197,28 @@ Can Speex pass DTMF
 \layout Standard
 
 I guess it all depends on the bit-rate used.
- Though no formal testing has yet been performed, I'd say don't go below
- the 15 kbps mode if you want DTMF to be transmitted correctly.
- DTMF at 8 kbps may work but your mileage may vary.
+ Though no formal testing has yet been performed, I'd say is correctly at
+ 8 kbps and above (15 kbps for version < 1.1.1).
  Also, make sure you don't use the lowest complexity (see SPEEX_SET_COMPLEXITY
- or --comp option), as it causes important noise.
+ or --comp option), as it causes significant noise.
 \layout Subsection*
 
 Can Speex pass V.9x modem signals correctly?
 \layout Standard
 
-If I could to that I'd be very rich by now :-)
+If I could do that I'd be very rich by now :-) Seriously, that would break
+ fundamental laws of information theory.
 \layout Subsection*
 
 What is your (Jean-Marc) relationship with the University of Sherbrooke
  and how does Speex fit into that?
 \layout Standard
 
-I am currently (2003/03/09) doing a Ph.D.
+Currently (2005/05/11), I'm doing my 
+\emph on 
+Ph.D.
+
+\emph default 
  at the University of Sherbrooke in mobile robotics.
  Although I did my master with the Sherbrooke speech coding group (in speech
  enhancement, not coding), I am not associated with them anymore.
@@ -5643,8 +6226,8 @@ I am currently (2003/03/09) doing a Ph.D.
 \series bold 
 not
 \series default 
- be understood that they or the University of Sherbrooke endorse the Speex
project in any way.
+ be understood that they or the University of Sherbrooke have anything to
do with the Speex project.
  Furthermore, Speex does not make use of any code or proprietary technology
  developed in the Sherbrooke speech coding group.
  
@@ -5751,7 +6334,7 @@ IETF RTP Profile
 \layout Standard
 
 
-\begin_inset Include \verbatiminput{draft-herlein-speex-rtp-profile-00.txt}
+\begin_inset Include \verbatiminput{draft-herlein-speex-rtp-profile-02.txt}
 preview false
 
 \end_inset 
@@ -5759,6 +6342,46 @@ preview false
 
 \layout Section
 \pagebreak_top 
+Speex License
+\begin_inset LatexCommand \label{sec:Speex-License}
+
+\end_inset 
+
+
+\layout Standard
+
+Redistribution and use in source and binary forms, with or without modification,
+ are permitted provided that the following conditions are met:
+\layout Itemize
+
+Redistributions of source code must retain the above copyright notice, this
+ list of conditions and the following disclaimer.
+\layout Itemize
+
+Redistributions in binary form must reproduce the above copyright notice,
+ this list of conditions and the following disclaimer in the documentation
+ and/or other materials provided with the distribution.
+\layout Itemize
+
+Neither the name of the Xiph.org Foundation nor the names of its contributors
+ may be used to endorse or promote products derived from this software without
+ specific prior written permission.
+\layout Standard
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS
+ IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ PURPOSE ARE DISCLAIMED.
+ IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+ INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+ BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+ USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+\layout Section
+\pagebreak_top 
 GNU Free Documentation License
 \layout Standard