manual.lyx

一个开源的sip源代码

In any hands-free communication system (Fig.
 
\begin_inset LatexCommand \ref{fig:Acoustic-echo-model}

\end_inset

), speech from the remote end is played in the local loudspeaker, propagates
 in the room and is captured by the microphone.
 If the audio captured from the microphone is sent directly to the remote
 end, then the remove user hears an echo of his voice.
 An acoustic echo canceller is designed to remove the acoustic echo before
 it is sent to the remote end.
 It is important to understand that the echo canceller is meant to improve
 the quality on the 
\series bold
remote
\series default
 end.
\end_layout

\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Standard
\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
begin{center}
\end_layout

\end_inset


\begin_inset Graphics
	filename echo_path.eps
	width 10cm

\end_inset


\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
end{center}
\end_layout

\end_inset


\end_layout

\begin_layout Caption
Acoustic echo model
\begin_inset LatexCommand \label{fig:Acoustic-echo-model}

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard

\newpage

\end_layout

\begin_layout Chapter
Compiling
\end_layout

\begin_layout Standard
Compiling Speex under UNIX or any platform supported by autoconf (e.g.
 Win32/cygwin) is as easy as typing:
\end_layout

\begin_layout LyX-Code
% ./configure [options]
\end_layout

\begin_layout LyX-Code
% make
\end_layout

\begin_layout LyX-Code
% make install
\end_layout

\begin_layout Standard
The options supported by the Speex configure script are:
\end_layout

\begin_layout Description
--prefix=<path> Specifies where to install Speex
\end_layout

\begin_layout Description
--enable-shared/--disable-shared Whether to compile shared libraries
\end_layout

\begin_layout Description
--enable-static/--disable-static Whether to compile static libraries
\end_layout

\begin_layout Description
--disable-wideband Disable the wideband part of Speex (typically to same
 space)
\end_layout

\begin_layout Description
--enable-valgrind Enable extra information when (and only when) running
 with valgrind
\end_layout

\begin_layout Description
--enable-sse Enable use of SSE instructions (x86/float only)
\end_layout

\begin_layout Description
--enable-fixed-point
\begin_inset LatexCommand \index{fixed-point}

\end_inset

 Compile Speex for a processor that does not have a floating point unit
 (FPU)
\end_layout

\begin_layout Description
--enable-arm4-asm Enable assembly specific to the ARMv4 architecture (gcc
 only)
\end_layout

\begin_layout Description
--enable-arm5e-asm Enable assembly specific to the ARMv5E architecture (gcc
 only)
\end_layout

\begin_layout Description
--enable-fixed-point-debug Use only for debugging the fixed-point
\begin_inset LatexCommand \index{fixed-point}

\end_inset

 code (very slow)
\end_layout

\begin_layout Description
--enable-epic-48k Enable a special (and non-compatible) 4.8 kbps narrowband
 mode
\end_layout

\begin_layout Description
--enable-ti-c55x Enable support for the TI C5x family
\end_layout

\begin_layout Description
--enable-blackfin-asm Enable assembly specific to the Blackfin DSP architecture
 (gcc only)
\end_layout

\begin_layout Description
--enable-16bit-precision Reduces precision to 16 bits in time-critical areas
 (fixed-point only)
\end_layout

\begin_layout Standard

\newpage

\end_layout

\begin_layout Chapter
Command-line encoder/decoder
\begin_inset LatexCommand \label{sec:Command-line-encoder/decoder}

\end_inset


\end_layout

\begin_layout Standard
The base Speex distribution includes a command-line encoder (
\emph on
speexenc
\emph default
) and decoder (
\emph on
speexdec
\emph default
).
 This section describes how to use these tools.
\end_layout

\begin_layout Section

\emph on
speexenc
\begin_inset LatexCommand \index{speexenc}

\end_inset


\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_layout LyX-Code
speexenc [options] input_file output_file
\end_layout

\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 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)
\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_layout Description
--quality\InsetSpace ~
n Set the encoding quality (0-10), default is 8
\end_layout

\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_layout Description
--abr\InsetSpace ~
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\InsetSpace ~
n Pack n frames in each Ogg packet (this saves space at low bit-rates)
\end_layout

\begin_layout Description
--comp\InsetSpace ~
n Set encoding speed/quality tradeoff.
 The higher the value of n, the slower the encoding (default is 3)
\end_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 Description
--version\InsetSpace ~
(-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\InsetSpace ~
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 LatexCommand \index{speexdec}

\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\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_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 Description
--version\InsetSpace ~
(-v) Print version information
\end_layout

\begin_layout Standard

\newpage

\end_layout

\begin_layout Chapter
Programming with Speex (the libspeex
\begin_inset LatexCommand \index{libspeex}

\end_inset

 API
\begin_inset LatexCommand \index{API}

\end_inset

)
\begin_inset LatexCommand \label{sec:Programming-with-Speex}

\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 Section
Encoding
\begin_inset LatexCommand \label{sub:Encoding}

\end_inset


\end_layout

\begin_layout Standard
In order to encode speech using Speex, you first need to:
\end_layout

\begin_layout LyX-Code
#include <speex/speex.h>
\end_layout

\begin_layout Standard
You then need to declare a Speex bit-packing struct
\end_layout

\begin_layout LyX-Code
SpeexBits bits;
\end_layout

\begin_layout Standard
and a Speex encoder state
\end_layout

\begin_layout LyX-Code
void *enc_state;
\end_layout

\begin_layout Standard
The two are initialized by:
\end_layout

\begin_layout LyX-Code
speex_bits_init(&bits);
\end_layout

\begin_layout LyX-Code
enc_state = speex_encoder_init(&speex_nb_mode);
\end_layout

\begin_layout Standard
For wideband coding, 
\emph on
speex_nb_mode
\emph default
 will be replaced by 
\emph on
speex_wb_mode
\emph default
.
 In most cases, you will need to know the frame size used by the mode you
 are using.
 You can get that value in the 
\emph on
frame_size
\emph default
 variable with:
\end_layout

\begin_layout LyX-Code
speex_encoder_ctl(enc_state,SPEEX_GET_FRAME_SIZE,&frame_size);
\end_layout

\begin_layout Standard
In practice, 
\emph on
frame_size
\emph default
 will correspond to 20 ms when using 8, 16, or 32 kHz sampling rate.
\end_layout

\begin_layout Standard
Once the initialization is done, for every input frame:
\end_layout

\begin_layout LyX-Code
speex_bits_reset(&bits);
\end_layout

\begin_layout LyX-Code
speex_encode_int(enc_state, input_frame, &bits);
\end_layout

\begin_layout LyX-Code
nbBytes = speex_bits_write(&bits, byte_ptr, MAX_NB_BYTES);
\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