Patch by David Rowe: normalize16() on Blackfin now writes data 16-bit at a time
[speexdsp.git] / doc / manual.lyx
index 2e41b0b..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
@@ -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,15 @@ 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 (2004/04/06), I'm doing my 
+Currently (2005/05/11), I'm doing my 
 \emph on 
 Ph.D.
 
@@ -5784,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