manual.lyx

一个开源的sip源代码

\end_layout

\begin_layout Standard
As of version 1.2beta2, a new 
\family typewriter
echo_diagnostic.m
\family default
 tool is included in the source distribution.
 The first step is to define DUMP_ECHO_CANCEL_DATA during the build.
 This causes the echo canceller to automatically save the near-end, far-end
 and output signals to files (aec_rec.sw aec_play.sw and aec_out.sw).
 These are exactly what the AEC receives and outputs.
 From there, it is necessary to start Octave and type:
\end_layout

\begin_layout LyX-Code
echo_diagnostic('aec_rec.sw', 'aec_play.sw', 'aec_diagnostic.sw', 1024);
\end_layout

\begin_layout Standard
The value of 1024 is the filter length and can be changed.
 There will be some (hopefully) useful messages printed and echo cancelled
 audio will be saved to aec_diagnostic.sw .
 If even that output is bad (almost no cancellation) then there is  probably
 problem with the playback or recording process.
\end_layout

\begin_layout Section
Jitter Buffer
\end_layout

\begin_layout Standard
There are two jitter buffers.
 Both can be enabled by including:
\end_layout

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

\begin_layout Subsection
Generic Jitter Buffer
\end_layout

\begin_layout Subsection
Speex Jitter Buffer
\end_layout

\begin_layout Section
Resampler
\end_layout

\begin_layout Standard
As of version 1.2beta2, Speex includes a resampling modules.
 To make use of the resampler, it is necessary to include its header file:
\end_layout

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

\begin_layout Standard
For each stream that is to be resampled, it is necessary to create a resampler
 state with:
\end_layout

\begin_layout LyX-Code
SpeexResamplerState *resampler;
\end_layout

\begin_layout LyX-Code
resampler = speex_resampler_init(nb_channels, input_rate, output_rate, quality);
\end_layout

\begin_layout Standard
where nb_channels is the number of channels that will be used (either interleave
d or non-interleaved), input_rate is the sampling rate of the input stream,
 output_rate is the sampling rate of the output stream and quality is the
 requested quality setting (0 to 10).
 The quality parameter is useful for controlling the quality/complexity/latency
 tradeoff.
 Using a higher quality setting means less noise/aliasing, a higher complexity
 and a higher latency.
 Usually, a quality of 3 is acceptable for most desktop uses and quality
 10 is mostly recommended for pro audio work.
 Quality 0 usually has a decent sound (certainly better than using linear
 interpolation resampling), but artifacts may be heard.
\end_layout

\begin_layout Section
Codec Options (speex_*_ctl)
\begin_inset LatexCommand \label{sub:Codec-Options}

\end_inset


\end_layout

\begin_layout Quote
\align center

\emph on
Entities should not be multiplied beyond necessity -- William of Ockham.
\end_layout

\begin_layout Quote
\align center

\emph on
Just because there's an option doesn't mean you have to use it -- me.
\end_layout

\begin_layout Standard
The Speex encoder and decoder support many options and requests that can
 be accessed through the 
\emph on
speex_encoder_ctl
\emph default
 and 
\emph on
speex_decoder_ctl
\emph default
 functions.
 Despite that, the defaults are good for many applications and 
\series bold
optional settings should only be used when one understands them and knows
 that they are needed
\series default
.
 A common error is to attempt to set many unnecessary settings.
 These functions are similar to the 
\emph on
ioctl
\emph default
 system call and their prototypes are:
\end_layout

\begin_layout LyX-Code
void speex_encoder_ctl(void *encoder, int request, void *ptr);
\end_layout

\begin_layout LyX-Code
void speex_decoder_ctl(void *encoder, int request, void *ptr);
\end_layout

\begin_layout Standard
The different values of request allowed are (note that some only apply to
 the encoder or the decoder):
\end_layout

\begin_layout Description
SPEEX_SET_ENH** Set perceptual enhancer
\begin_inset LatexCommand \index{perceptual enhancement}

\end_inset

 to on (1) or off (0) (integer)
\end_layout

\begin_layout Description
SPEEX_GET_ENH** Get perceptual enhancer status (integer)
\end_layout

\begin_layout Description
SPEEX_GET_FRAME_SIZE Get the frame size used for the current mode (integer)
\end_layout

\begin_layout Description
SPEEX_SET_QUALITY* Set the encoder speech quality (integer 0 to 10)
\end_layout

\begin_layout Description
SPEEX_GET_QUALITY* Get the current encoder speech quality (integer 0 to
 10)
\end_layout

\begin_layout Description
SPEEX_SET_MODE*
\begin_inset Formula $\dagger$
\end_inset


\end_layout

\begin_layout Description
SPEEX_GET_MODE*
\begin_inset Formula $\dagger$
\end_inset


\end_layout

\begin_layout Description
SPEEX_SET_LOW_MODE*
\begin_inset Formula $\dagger$
\end_inset


\end_layout

\begin_layout Description
SPEEX_GET_LOW_MODE*
\begin_inset Formula $\dagger$
\end_inset


\end_layout

\begin_layout Description
SPEEX_SET_HIGH_MODE*
\begin_inset Formula $\dagger$
\end_inset


\end_layout

\begin_layout Description
SPEEX_GET_HIGH_MODE*
\begin_inset Formula $\dagger$
\end_inset


\end_layout

\begin_layout Description
SPEEX_SET_VBR* Set variable bit-rate (VBR) to on (1) or off (0) (integer)
\end_layout

\begin_layout Description
SPEEX_GET_VBR* Get variable bit-rate
\begin_inset LatexCommand \index{variable bit-rate}

\end_inset

 (VBR) status (integer)
\end_layout

\begin_layout Description
SPEEX_SET_VBR_QUALITY* Set the encoder VBR speech quality (float 0 to 10)
\end_layout

\begin_layout Description
SPEEX_GET_VBR_QUALITY* Get the current encoder VBR speech quality (float
 0 to 10)
\end_layout

\begin_layout Description
SPEEX_SET_COMPLEXITY* Set the CPU resources allowed for the encoder (integer
 1 to 10)
\end_layout

\begin_layout Description
SPEEX_GET_COMPLEXITY* Get the CPU resources allowed for the encoder (integer
 1 to 10)
\end_layout

\begin_layout Description
SPEEX_SET_BITRATE* Set the bit-rate to use to the closest value not exceeding
 the parameter (integer in bps)
\end_layout

\begin_layout Description
SPEEX_GET_BITRATE Get the current bit-rate in use (integer in bps)
\end_layout

\begin_layout Description
SPEEX_SET_SAMPLING_RATE Set real sampling rate (integer in Hz)
\end_layout

\begin_layout Description
SPEEX_GET_SAMPLING_RATE Get real sampling rate (integer in Hz)
\end_layout

\begin_layout Description
SPEEX_RESET_STATE Reset the encoder/decoder state to its original state
 (zeros all memories)
\end_layout

\begin_layout Description
SPEEX_SET_VAD* Set voice activity detection
\begin_inset LatexCommand \index{voice activity detection}

\end_inset

 (VAD) to on (1) or off (0) (integer)
\end_layout

\begin_layout Description
SPEEX_GET_VAD* Get voice activity detection (VAD) status (integer)
\end_layout

\begin_layout Description
SPEEX_SET_DTX* Set discontinuous transmission
\begin_inset LatexCommand \index{discontinuous transmission}

\end_inset

 (DTX) to on (1) or off (0) (integer)
\end_layout

\begin_layout Description
SPEEX_GET_DTX* Get discontinuous transmission (DTX) status (integer)
\end_layout

\begin_layout Description
SPEEX_SET_ABR* Set average bit-rate
\begin_inset LatexCommand \index{average bit-rate}

\end_inset

 (ABR) to a value n in bits per second (integer in bps)
\end_layout

\begin_layout Description
SPEEX_GET_ABR* Get average bit-rate (ABR) setting (integer in bps)
\end_layout

\begin_layout Description
SPEEX_SET_PLC_TUNING* Tell the encoder to optimize encoding for a certain
 percentage of packet loss (integer in percent)
\end_layout

\begin_layout Description
SPEEX_GET_PLC_TUNING* Get the current tuning of the encoder for PLC (integer
 in percent)
\end_layout

\begin_layout Description
* applies only to the encoder
\end_layout

\begin_layout Description
** applies only to the decoder
\end_layout

\begin_layout Description
\begin_inset Formula $\dagger$
\end_inset

 normally only used internally
\end_layout

\begin_layout Section
Mode queries
\begin_inset LatexCommand \label{sub:Mode-queries}

\end_inset


\end_layout

\begin_layout Standard
Speex modes have a query system similar to the speex_encoder_ctl and speex_decod
er_ctl calls.
 Since modes are read-only, it is only possible to get information about
 a particular mode.
 The function used to do that is:
\end_layout

\begin_layout LyX-Code
void speex_mode_query(SpeexMode *mode, int request, void *ptr);
\end_layout

\begin_layout Standard
The admissible values for request are (unless otherwise note, the values
 are returned through 
\emph on
ptr
\emph default
):
\end_layout

\begin_layout Description
SPEEX_MODE_FRAME_SIZE Get the frame size (in samples) for the mode
\end_layout

\begin_layout Description
SPEEX_SUBMODE_BITRATE Get the bit-rate for a submode number specified through
 
\emph on
ptr
\emph default
 (integer in bps).
 
\end_layout

\begin_layout Section
Preprocessor options
\begin_inset LatexCommand \label{sub:Preprocessor-options}

\end_inset


\end_layout

\begin_layout Description
SPEEX_PREPROCESS_SET_DENOISE Turns denoising on(1) or off(2) (integer)
\end_layout

\begin_layout Description
SPEEX_PREPROCESS_GET_DENOISE Get denoising status (integer)
\end_layout

\begin_layout Description
SPEEX_PREPROCESS_SET_AGC Turns automatic gain control (AGC) on(1) or off(2)
 (integer)
\end_layout

\begin_layout Description
SPEEX_PREPROCESS_GET_AGC Get AGC status (integer)
\end_layout

\begin_layout Description
SPEEX_PREPROCESS_SET_VAD Turns voice activity detector (VAD) on(1) or off(2)
 (integer)
\end_layout

\begin_layout Description
SPEEX_PREPROCESS_GET_VAD Get VAD status (integer)
\end_layout

\begin_layout Description
SPEEX_PREPROCESS_SET_AGC_LEVEL
\end_layout

\begin_layout Description
SPEEX_PREPROCESS_GET_AGC_LEVEL
\end_layout

\begin_layout Description
SPEEX_PREPROCESS_SET_DEREVERB Turns reverberation removal on(1) or off(2)
 (integer)
\end_layout

\begin_layout Description
SPEEX_PREPROCESS_GET_DEREVERB Get reverberation removal status (integer)
\end_layout

\begin_layout Description
SPEEX_PREPROCESS_SET_DEREVERB_LEVEL
\end_layout

\begin_layout Description
SPEEX_PREPROCESS_GET_DEREVERB_LEVEL
\end_layout

\begin_layout Description
SPEEX_PREPROCESS_SET_DEREVERB_DECAY
\end_layout

\begin_layout Description
SPEEX_PREPROCESS_GET_DEREVERB_DECAY
\end_layout

\begin_layout Description
SPEEX_PREPROCESS_SET_PROB_START
\end_layout

\begin_layout Description
SPEEX_PREPROCESS_GET_PROB_START
\end_layout

\begin_layout Description
SPEEX_PREPROCESS_SET_PROB_CONTINUE
\end_layout

\begin_layout Description
SPEEX_PREPROCESS_GET_PROB_CONTINUE
\end_layout

\begin_layout Description
SPEEX_PREPROCESS_SET_NOISE_SUPPRESS Set maximum attenuation of the noise
 in dB (negative number)
\end_layout

\begin_layout Description
SPEEX_PREPROCESS_GET_NOISE_SUPPRESS Get maximum attenuation of the noise
 in dB (negative number)
\end_layout

\begin_layout Description
SPEEX_PREPROCESS_SET_ECHO_SUPPRESS Set maximum attenuation of the residual
 echo in dB (negative number)
\end_layout

\begin_layout Description
SPEEX_PREPROCESS_GET_ECHO_SUPPRESS Set maximum attenuation of the residual
 echo in dB (negative number)
\end_layout

\begin_layout Description
SPEEX_PREPROCESS_SET_ECHO_SUPPRESS_ACTIVE Set maximum attenuation of the
 echo in dB when near end is active (negative number)
\end_layout

\begin_layout Description
SPEEX_PREPROCESS_GET_ECHO_SUPPRESS_ACTIVE Set maximum attenuation of the
 echo in dB when near end is active (negative number)
\end_layout

\begin_layout Description
SPEEX_PREPROCESS_SET_ECHO_STATE Set the associated echo canceller for residual
 echo suppression (NULL for no residual echo suppression)
\end_layout

\begin_layout Description
SPEEX_PREPROCESS_GET_ECHO_STATE Get the associated echo canceller
\end_layout

\begin_layout Section
Packing and in-band signalling
\begin_inset LatexCommand \index{in-band signalling}

\end_inset


\end_layout

\begin_layout Standard
Sometimes it is desirable to pack more than one frame per packet (or other
 basic unit of storage).
 The proper way to do it is to call speex_encode 
\begin_inset Formula $N$
\end_inset

 times before writing the stream with speex_bits_write.
 In cases where the number of frames is not determined by an out-of-band
 mechanism, it is possible to include a terminator code.
 That terminator consists of the code 15 (decimal) encoded with 5 bits,
 as shown in Table 
\begin_inset 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.
\end_layout

\begin_layout Standard
It is also possible to send in-band 
\begin_inset Quotes eld
\end_inset

messages
\begin_inset Quotes erd
\end_inset

 to the other side.
 All these messages are encoded as 
\begin_inset Quotes eld
\end_inset

pseudo-frames
\begin_inset Quotes erd
\end_inset

 of mode 14 which contain a 4-bit message type code, followed by the message.
 Table 
\begin_inset LatexCommand \ref{cap:In-band-signalling-codes}

\end_inset

 lists the available codes, their meaning and the size of the message that
 follows.
 Most of these messages are requests that are sent to the encoder or decoder
 on the other end, which is free to comply or ignore them.
 By default, all in-band messages are ignored.
\end_layout

\begin_layout Standard
\begin_inset Float table
placement htbp
wide false
sideways false
status open

\begin_layout Standard
\begin_inset Tabular
<lyxtabular version="3" rows="17" columns="3">
<features>
<column alignment="center" valignment="top" leftline="true" width="0pt">
<column alignment="center" valignment="top" leftline="true" width="0pt">
<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Code
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Size (bits)
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">