Patch by David Rowe: normalize16() on Blackfin now writes data 16-bit at a time
[speexdsp.git] / doc / manual.lyx
index b518d52..d8ea5dc 100644 (file)
@@ -6,7 +6,7 @@
 \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.3)
+(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
@@ -132,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)
@@ -166,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.
@@ -215,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 
@@ -223,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
@@ -438,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
@@ -680,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
@@ -730,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
 
@@ -781,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:
@@ -798,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
@@ -812,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;
@@ -895,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
 
@@ -904,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
@@ -1073,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
 
@@ -1087,6 +1576,11 @@ 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 query system similar to the speex_encoder_ctl and speex_decod
@@ -1119,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}
 
@@ -1137,7 +1684,7 @@ 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 
@@ -5449,7 +5996,8 @@ 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 GSM-FR is covered by a Philips patent
@@ -5515,7 +6063,7 @@ 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 you just do 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?
@@ -5574,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
@@ -5657,14 +6206,19 @@ I guess it all depends on the bit-rate used.
 Can Speex pass V.9x modem signals correctly?
 \layout Standard
 
-If I could do 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
 
-Currently (2003/03/09), I'm 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.
@@ -5672,8 +6226,8 @@ Currently (2003/03/09), I'm 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.
  
@@ -5780,7 +6334,7 @@ IETF RTP Profile
 \layout Standard
 
 
-\begin_inset Include \verbatiminput{draft-herlein-speex-rtp-profile-01.txt}
+\begin_inset Include \verbatiminput{draft-herlein-speex-rtp-profile-02.txt}
 preview false
 
 \end_inset