Preparing for rc2
[speexdsp.git] / doc / manual.lyx
index 9d26643..af400e5 100644 (file)
@@ -29,7 +29,7 @@
 
 The Speex Codec Manual
 \newline 
-(draft for Speex 1.0beta4)
+(for version 1.0rc2)
 \layout Author
 
 Jean-Marc Valin
@@ -45,36 +45,6 @@ Permission is granted to copy, distribute and/or modify this document under
  A copy of the license is included in the section entitled "GNU Free Documentati
 on License".
  
-\layout Section*
-
-Disclaimer
-\layout Standard
-
-This document is meant to provide useful information on the Speex codec
- but there is absolutely no warranty regarding usefulness or correctness
- of the information provided.
- Also, some techniques used in Speex are said to be 
-\begin_inset Quotes eld
-\end_inset 
-
-similar
-\begin_inset Quotes erd
-\end_inset 
-
- to techniques used in known codecs.
- This should not be understood as an acknowledgment that Speex is using
- any patented algorithm used in these codecs, but merely that comprehension
- of Speex can be facilitated by thinking that the principles of operation
- are the same or similar.
- Of course, there's also the obligatory 
-\begin_inset Quotes eld
-\end_inset 
-
-all trademarks are property of their respective owner
-\begin_inset Quotes erd
-\end_inset 
-
-.
 \layout Standard
 \pagebreak_top \pagebreak_bottom 
 
@@ -153,20 +123,20 @@ Free software/open-source
  and royalty-free
 \layout Itemize
 
-Integration of wideband
-\begin_inset LatexCommand \index{wideband}
+Integration of narrowband
+\begin_inset LatexCommand \index{narrowband}
 
 \end_inset 
 
- and narrowband
-\begin_inset LatexCommand \index{narrowband}
+ and wideband
+\begin_inset LatexCommand \index{wideband}
 
 \end_inset 
 
  in the same bit-stream
 \layout Itemize
 
-Wide range of bit-rates available
+Wide range of bit-rates available (from 2 kbps to 44 kbps)
 \layout Itemize
 
 Dynamic bit-rate switching and Variable Bit-Rate
@@ -197,6 +167,17 @@ Ultra-wideband mode at 32 kHz (up to 48 kHz)
 \layout Itemize
 
 Intensity stereo encoding option
+\layout Standard
+
+The next two sections describe the internals of the codec and require some
+ signal processing knowledge.
+ If you are only interested in using Speex, you can skip to section 
+\begin_inset LatexCommand \ref{sec:Command-line-encoder/decoder}
+
+\end_inset 
+
+.
 \layout Section
 \pagebreak_top 
 Introduction to CELP Coding
@@ -234,6 +215,10 @@ perceptually weighted domain
 \end_inset 
 
 
+\layout Standard
+
+This section describes the basic ideas behind CELP.
+ Note that it's still incomplete.
 \layout Subsection
 
 Linear Prediction (LPC)
@@ -494,17 +479,18 @@ Pitch Prediction
 
 \layout Standard
 
-During voiced segments, the speech signal is very periodic, so it is possible
- to take advantage of that by expressing the excitation signal 
-\begin_inset Formula $e(n)$
+During voiced segments, the speech signal is periodic, so it is possible
+ to take advantage of that property by approximating the excitation signal
+\begin_inset Formula $e[n]$
 \end_inset 
 
- as
+ by a gain times the past of the excitation:
 \layout Standard
 
 
 \begin_inset Formula \[
-e[n]=\beta e[n-T]+c[n]\]
+e[n]\simeq p[n]=\beta e[n-T]\]
 
 \end_inset 
 
@@ -528,28 +514,60 @@ where
 innovation codebook
 \emph default 
 .
- In the 
+ We call that long-term prediction since the excitation is predicted from
+\begin_inset Formula $e[n-T]$
+\end_inset 
+
+ with 
+\begin_inset Formula $T\gg N$
+\end_inset 
+
+.
+\layout Subsection
+
+Innovation Codebook
+\layout Standard
+
+The final excitation 
+\begin_inset Formula $e[n]$
+\end_inset 
+
+ will be the sum of the pitch prediction and an 
 \emph on 
-z
+innovation
 \emph default 
--domain, the excitation can be expressed as:
+ signal 
+\begin_inset Formula $c[n]$
+\end_inset 
+
+ taken from a fixed codebook.
 \layout Standard
 
 
 \begin_inset Formula \[
-e(z)=\frac{1}{1-\beta z^{-T}}\: c(z)\]
+e[n]=p[n]+c[n]=\beta e[n-T]+c[n]\]
 
 \end_inset 
 
-
-\layout Subsection
-
-Innovation Codebook
-\layout Standard
-
 This is where most of the bits in a CELP codec are allocated.
  It represents the information that couldn't be obtained either from linear
  prediction or pitch prediction.
+ In the 
+\emph on 
+z
+\emph default 
+-domain we can represent the final signal 
+\begin_inset Formula $X(z)$
+\end_inset 
+
+ as 
+\begin_inset Formula \[
+X(z)=\frac{C(z)}{A(z)\left(1-\beta z^{-T}\right)}\]
+
+\end_inset 
+
+
 \layout Subsection
 
 Analysis-by-Synthesis and Error Weighting
@@ -692,8 +710,7 @@ Minimizing the amount of information extracted from past frames (for robustness
 Dynamically-selectable codebooks (LSP, pitch and innovation)
 \layout Itemize
 
-G.728-like fixed codebooks (without backward-adaptive gains because of patent
- issues)
+sub-vector fixed (innovation) codebooks
 \layout Subsection
 
 LPC Analysis
@@ -828,18 +845,7 @@ n (VQ).
  the gain at the same time.
  This save many bits that would otherwise be allocated for a separate gain
  at the price of a slight increase in complexity.
- Except for the absence of (backward-adaptive) gain, the technique used
- in Speex is similar to G.728 (LD-CELP).
- However since we do not have a low-delay constraint, the search can be
- made more 
-\begin_inset Quotes eld
-\end_inset 
-
-global
-\begin_inset Quotes erd
-\end_inset 
-
- and make use of the whole information available for a sub-frame.
 \layout Subsection
 
 Bit allocation
@@ -883,7 +889,7 @@ collapsed false
 
 
 \begin_inset  Tabular
-<lyxtabular version="3" rows="12" columns="10">
+<lyxtabular version="3" rows="12" columns="11">
 <features>
 <column alignment="center" valignment="top" leftline="true" width="0pt">
 <column alignment="center" valignment="top" leftline="true" width="0pt">
@@ -894,6 +900,7 @@ collapsed false
 <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" 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">
@@ -976,6 +983,14 @@ Update rate
 7
 \end_inset 
 </cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+8
+\end_inset 
+</cell>
 </row>
 <row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1058,6 +1073,14 @@ frame
 1
 \end_inset 
 </cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+1
+\end_inset 
+</cell>
 </row>
 <row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1140,6 +1163,14 @@ frame
 4
 \end_inset 
 </cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+4
+\end_inset 
+</cell>
 </row>
 <row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1222,6 +1253,14 @@ frame
 30
 \end_inset 
 </cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+18
+\end_inset 
+</cell>
 </row>
 <row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1304,6 +1343,14 @@ frame
 0
 \end_inset 
 </cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+7
+\end_inset 
+</cell>
 </row>
 <row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1386,6 +1433,14 @@ frame
 0
 \end_inset 
 </cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+4
+\end_inset 
+</cell>
 </row>
 <row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1468,6 +1523,14 @@ frame
 5
 \end_inset 
 </cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+5
+\end_inset 
+</cell>
 </row>
 <row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1550,6 +1613,14 @@ sub-frame
 7
 \end_inset 
 </cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0
+\end_inset 
+</cell>
 </row>
 <row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1632,6 +1703,14 @@ sub-frame
 7
 \end_inset 
 </cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0
+\end_inset 
+</cell>
 </row>
 <row topline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1714,6 +1793,14 @@ sub-frame
 3
 \end_inset 
 </cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0
+\end_inset 
+</cell>
 </row>
 <row topline="true" bottomline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1796,6 +1883,14 @@ sub-frame
 96
 \end_inset 
 </cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+10
+\end_inset 
+</cell>
 </row>
 <row topline="true" bottomline="true">
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1878,6 +1973,14 @@ frame
 492
 \end_inset 
 </cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+79
+\end_inset 
+</cell>
 </row>
 </lyxtabular>
 
@@ -2270,7 +2373,7 @@ Completely transparent for voice, good quality music
 
 \layout Standard
 
-N/A
+3,950
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -2278,7 +2381,7 @@ N/A
 
 \layout Standard
 
-N/A
+-
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -2286,7 +2389,7 @@ N/A
 
 \layout Standard
 
-(Tones/DTMF to be implemented)
+Very noticeable artifacts/noise, good intelligibility
 \end_inset 
 </cell>
 </row>
@@ -3147,7 +3250,232 @@ clearpage
 
 \layout Section
 \pagebreak_top 
+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.
+\layout Subsection*
+
+Sampling rate
+\begin_inset LatexCommand \index{sampling rate}
+
+\end_inset 
+
+
+\layout Standard
+
+Speex is mainly designed for 3 different sampling rates: 8 kHz, 16 kHz,
+ and 32 kHz.
+ These are respectively refered to as narrowband
+\begin_inset LatexCommand \index{narrowband}
+
+\end_inset 
+
+, wideband
+\begin_inset LatexCommand \index{wideband}
+
+\end_inset 
+
+ and ultra-wideband
+\begin_inset LatexCommand \index{ultra-wideband}
+
+\end_inset 
+
+.
+\layout Subsection*
+
+Quality
+\begin_inset LatexCommand \index{quality}
+
+\end_inset 
+
+
+\layout Standard
+
+Speex encoding is controlled most of the time by a quality parameter that
+ range from 0 to 10.
+ In constant bit-rate
+\begin_inset LatexCommand \index{constant bit-rate}
+
+\end_inset 
+
+ (CBR) operation, the quality parameter is an integer, while for variable
+ bit-rate (VBR), the parameter is a float.
+\layout Subsection*
+
+Complexity
+\begin_inset LatexCommand \index{complexity}
+
+\end_inset 
+
+ (variable)
+\layout Standard
+
+With Speex, it is possible to vary the complexity allowed for the encoder.
+ This is done by controlling how the search is performed with an integer
+ ranging from 1 to 10 in a way that's similar to the -1 to -9 options to
+\emph on 
+gzip
+\emph default 
+ and 
+\emph on 
+bzip2
+\emph default 
+ compression utilities.
+ For normal use, the noise level at complexity 1is 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.
+ 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}
+
+\end_inset 
+
+ tones.
+\layout Subsection*
+
+Variable Bit-Rate
+\begin_inset LatexCommand \index{variable bit-rate}
+
+\end_inset 
+
+ (VBR)
+\layout Standard
+
+Variable bit-rate (VBR) allows a codec to change its bit-rate dynamically
+ to adapt to the 
+\begin_inset Quotes eld
+\end_inset 
+
+difficulty
+\begin_inset Quotes erd
+\end_inset 
+
+ of the audio being encoded.
+ In the example of Speex, sounds like vowels and high-energy transients
+ require a higher bit-rate to achieve good quality, while fricatives (e.g.
+ s,f sounds) can be coded adequately with less bits.
+ For this reason, VBR can achive lower bit-rate for the same quality, or
+ a better quality for a certain bit-rate.
+ Despite its advantages, VBR has two main drawbacks: first, by only specifying
+ quality, there's no guaranty about the final average bit-rate.
+ Second, for some real-time applications like voice over IP (VoIP), what
+ counts is the maximum bit-rate, which must be low enough for the communication
+ channel.
+\layout Subsection*
+
+Average Bit-Rate
+\begin_inset LatexCommand \index{average bit-rate}
+
+\end_inset 
+
+ (ABR)
+\layout Standard
+
+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
+ VBR with exactly the right quality setting to meet the target average bit-rate.
+\layout Subsection*
+
+Voice Activity Detection
+\begin_inset LatexCommand \index{voice activity detection}
+
+\end_inset 
+
+ (VAD)
+\layout Standard
+
+When enabled, voice activity detection detects whether the audio being encoded
+ is speech or silence/background noise.
+ VAD is always implicitly activated when encoding in VBR, so the option
+ is only useful in non-VBR operation.
+ In this case, Speex detects non-speech periods and encode them with just
+ enough bits to reproduce the background noise.
+ This is called 
+\begin_inset Quotes eld
+\end_inset 
+
+comfort noise generation
+\begin_inset Quotes erd
+\end_inset 
+
+ (CNG).
+\layout Subsection*
+
+Discontinuous Transmission
+\begin_inset LatexCommand \index{discontinuous transmission}
+
+\end_inset 
+
+ (DTX)
+\layout Standard
+
+Discontinuous transmission is an addition to VAD operation, that allows
+ to stop transmitting completely when the background noise is stationnary.
+ 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*
+
+Perceptual enhancement
+\begin_inset LatexCommand \index{perceptual enhancement}
+
+\end_inset 
+
+
+\layout Standard
+
+Perceptual enhancement is a part of the decoder which, when turned on, tries
+ to reduce (the perception of) the noise produced by the coding/decoding
+ process.
+ In most cases, perceptual enhancement make the sound further from the original
+\emph on 
+objectively
+\emph default 
+ (if you use SNR), but in the end it still 
+\emph on 
+sounds
+\emph default 
+ better (subjective improvement).
+\layout Subsection*
+
+Algorithmic delay
+\begin_inset LatexCommand \index{algorithmic delay}
+
+\end_inset 
+
+
+\layout Standard
+
+Every speech codec introduces a delay in the transmission.
+ For Speex, this delay is equal to the frame size, plus some amount of 
+\begin_inset Quotes eld
+\end_inset 
+
+look-ahead
+\begin_inset Quotes erd
+\end_inset 
+
+ required to process each frame.
+ In narrowband operation (8 kHz), the delay is 30 ms, while for wideband
+ (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 Section
+\pagebreak_top 
 Command-line encoder/decoder
+\begin_inset LatexCommand \label{sec:Command-line-encoder/decoder}
+
+\end_inset 
+
+
 \layout Standard
 
 The base Speex distribution includes a command-line encoder (
@@ -3159,6 +3487,7 @@ speexenc
 speexdec
 \emph default 
 ).
+ This section describes how to use these tools.
 \layout Subsection
 
 
@@ -3171,7 +3500,20 @@ speexenc
 
 \layout Standard
 
-The encoder takes the following options:
+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: 
+\layout LyX-Code
+
+speexenc [options] input_file output_file
+\layout Standard
+
+The value '-' for input_file or output_file corresponds respectively to
+ stdin and stdout.
+ The valid options are:
 \layout Description
 
 --narrowband\SpecialChar ~
@@ -3196,7 +3538,7 @@ ultra-wideband
 \layout Description
 
 --quality\SpecialChar ~
-n Set the encoding quality (0-10), default is 3
+n Set the encoding quality (0-10), default is 8
 \layout Description
 
 --bitrate\SpecialChar ~
@@ -3206,6 +3548,16 @@ n Encoding bit-rate (use bit-rate n or lower)
 --vbr Enable VBR (Variable Bit-Rate), disabled by default
 \layout Description
 
+--abr\SpecialChar ~
+n Enable ABR (Average Bit-Rate) at n kbps, disabled by default
+\layout Description
+
+--vad Enable VAD (Voice Activity Detection), disabled by default
+\layout Description
+
+--dtx Enable DTX (Discontinuous Transmission), disabled by default
+\layout Description
+
 --nframes\SpecialChar ~
 n Pack n frames in each Ogg packet (this saves space at low bit-rates)
 \layout Description
@@ -3274,13 +3626,26 @@ speexdec
 
 \layout Standard
 
-The decoder takes the following options:
+The 
+\emph on 
+speexdec
+\emph default 
+ utility is used to decode Speex files and can be used by calling: 
+\layout LyX-Code
+
+speexdec [options] speex_file [output_file]
+\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:
 \layout Description
 
---enh enable post-filter
+--enh enable post-filter (default)
 \layout Description
 
---no-enh disable post-filter (default)
+--no-enh disable post-filter
 \layout Description
 
 --force-nb Force decoding in narrowband 
@@ -3303,7 +3668,7 @@ n For decoding at n Hz sampling rate
 \layout Description
 
 --packet-loss\SpecialChar ~
-n Simulate n % rando m packet loss
+n Simulate n % random packet loss
 \layout Description
 
 -V Verbose operation, print bit-rate currently in use
@@ -3457,7 +3822,7 @@ In order to encode speech using Speex, you first need to:
 #include <speex.h>
 \layout Standard
 
-You then need to declare a Speex bit-packing struct
+You also need to declare a Speex bit-packing struct
 \layout LyX-Code
 
 SpeexBits bits;
@@ -3487,7 +3852,8 @@ speex_nb_mode
 speex_wb_mode
 \emph default 
 .
- You can get that value in the 
+ If you need to obtain the size of the frames that will be used by the decoder,
+ you can get that value in the 
 \emph on 
 frame_size
 \emph default 
@@ -3502,11 +3868,15 @@ There is also a parameter that can be set for the decoder: whether or not
  This can be set by: 
 \layout LyX-Code
 
-speex_decoder_ctl(dec_state, SPEEX_SET_PF, &pf); 
+speex_decoder_ctl(dec_state, SPEEX_SET_ENH, &enh); 
 \layout Standard
 
-where pf is an int that with value 0 to have the post-filter disabled and
- 1 to have it enabled.
+where 
+\emph on 
+enh
+\emph default 
+ is an int that with value 0 to have the post-filter disabled and 1 to have
+ it enabled.
 \layout Standard
 
 Again, once the decoder initialization is done, for every input frame:
@@ -3580,7 +3950,12 @@ The different values of request allowed are (note that some only apply to
  the encoder or the decoder):
 \layout Description
 
-SPEEX_SET_ENH** Set perceptual enhancer to on (1) or off (0) (integer)
+SPEEX_SET_ENH** Set perceptual enhancer
+\begin_inset LatexCommand \index{perceptual enhancement}
+
+\end_inset 
+
+ to on (1) or off (0) (integer)
 \layout Description
 
 SPEEX_GET_ENH** Get perceptual enhancer status (integer)
@@ -3641,7 +4016,12 @@ SPEEX_GET_HIGH_MODE*
 SPEEX_SET_VBR* Set variable bit-rate (VBR) to on (1) or off (0) (integer)
 \layout Description
 
-SPEEX_GET_VBR* Get variable bit-rate (VBR) status (integer)
+SPEEX_GET_VBR* Get variable bit-rate
+\begin_inset LatexCommand \index{variable bit-rate}
+
+\end_inset 
+
+ (VBR) status (integer)
 \layout Description
 
 SPEEX_SET_VBR_QUALITY* Set the encoder VBR speech quality (integer 0 to
@@ -3652,10 +4032,12 @@ SPEEX_GET_VBR_QUALITY* Get the current encoder VBR speech quality (integer
  0 to 10)
 \layout Description
 
-SPEEX_SET_COMPLEXITY* Set the CPU resources allowed for the encoder
+SPEEX_SET_COMPLEXITY* Set the CPU resources allowed for the encoder (integer
+ 1 to 10)
 \layout Description
 
-SPEEX_GET_COMPLEXITY* Get the CPU resources allowed for the encoder
+SPEEX_GET_COMPLEXITY* Get the CPU resources allowed for the encoder (integer
+ 1 to 10)
 \layout Description
 
 SPEEX_SET_BITRATE* Set the bit-rate to use to the closest value not exceeding
@@ -3665,12 +4047,47 @@ SPEEX_SET_BITRATE* Set the bit-rate to use to the closest value not exceeding
 SPEEX_GET_BITRATE Get the current bit-rate in use (integer in bps)
 \layout Description
 
-SPEEX_SET_SAMPLING_RATE Set real sampling rate (is used to determine real
- bit-rate)
+SPEEX_SET_SAMPLING_RATE Set real sampling rate (integer in Hz)
+\layout Description
+
+SPEEX_GET_SAMPLING_RATE Get real sampling rate (integer in Hz)
+\layout Description
+
+SPEEX_RESET_STATE Reset the encoder/decoder state to its original state
+ (zeros all memories)
+\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)
+\layout Description
+
+SPEEX_GET_VAD* Get voice activity detection (VAD) status (integer)
+\layout Description
+
+SPEEX_SET_DTX* Set discontinuous transmission
+\begin_inset LatexCommand \index{discontinuous transmission}
+
+\end_inset 
+
+ (DTX) to on (1) or off (0) (integer)
 \layout Description
 
-SPEEX_GET_SAMPLING_RATE Get real sampling rate (is used to determine real
- bit-rate)
+SPEEX_GET_DTX* Get discontinuous transmission (DTX) status (integer)
+\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)
+\layout Description
+
+SPEEX_GET_ABR* Get average bit-rate (ABR) setting (integer in bps)
 \layout Description
 
 * applies only to the encoder
@@ -3715,7 +4132,8 @@ SPEEX_SUBMODE_BITRATE Get the bit-rate for a submode number specified throught
 \emph on 
 ptr
 \emph default 
-.
+ (integer in bps).
 \layout Subsection
 
 Packing and in-band signalling
@@ -3838,7 +4256,7 @@ Content
 
 \layout Standard
 
-Asks decoder to set perceptual enhancement on (1) or off(1)
+Asks decoder to set perceptual enhancement off (0) or on(1)
 \end_inset 
 </cell>
 </row>
@@ -3864,7 +4282,7 @@ Asks decoder to set perceptual enhancement on (1) or off(1)
 
 \layout Standard
 
-Asks encoder to set VBR on (1) or off(1)
+reserved
 \end_inset 
 </cell>
 </row>
@@ -4020,7 +4438,7 @@ Request acknowloedge (0=no, 1=all, 2=only for in-band data)
 
 \layout Standard
 
-reserved
+Asks encoder to set VBR off (0), on(1), VAD(2), DTX(3)
 \end_inset 
 </cell>
 </row>
@@ -4318,15 +4736,7 @@ The latest RTP payload draft can be found at
 \end_inset 
 
 .
- We are (2002/11/11) about to send the latest draft to the IETF for comments.
-\layout Comment
-
-Since Speex encoded frames already contain mode information, they can be
- sent without any other information in an RTP packet.
- If more than one frame is transmitted, no byte padding is performed at
- the end of frames, except the last one.
- The number of frames contained in each packet MUST be transmitted out-of-band.
+ We are (2003/01/14) about to send the latest draft to the IETF for comments.
  
 \layout Subsection
 
@@ -4539,7 +4949,7 @@ char[]
 
 \layout Standard
 
-speex_header_version
+speex_version_id
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -4799,7 +5209,7 @@ int
 
 \layout Standard
 
-reserved1
+extra_headers
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -4825,7 +5235,7 @@ int
 
 \layout Standard
 
-reserved2
+reserved1
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -4851,7 +5261,7 @@ int
 
 \layout Standard
 
-reserved3
+reserved2
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -4925,6 +5335,13 @@ 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*
 
+Under what license is Speex released?
+\layout Standard
+
+As of version 1.0 beta 1, Speex in released under Xiph's BSD-like license.
+ This license is the most permissive of the open-source licenses.
+\layout Subsection*
+
 Ogg
 \begin_inset LatexCommand \index{Ogg}
 
@@ -4942,7 +5359,7 @@ Ogg is a
 \begin_inset Quotes eld
 \end_inset 
 
-file format
+container format
 \begin_inset Quotes erd
 \end_inset 
 
@@ -4963,6 +5380,14 @@ Ogg Speex
  Actually, if what you do is Voice of 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.
+\layout Subsection*
+
 Can I use Speex for compressing music
 \begin_inset LatexCommand \index{music}
 
@@ -4991,8 +5416,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, though limited testing has
been done so far.
+As of 0.8.0, Speex can now compile on Windows.
There are also several front-ends available from the web site.
 \layout Subsection*
 
 Why is encoding so slow compared to decoding?
@@ -5070,6 +5495,7 @@ Can Speex pass DTMF
 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.
  Also, make sure you don't use the lowest complexity (see SPEEX_SET_COMPLEXITY
  or --comp option), as it causes important noise.
 \layout Subsection*
@@ -5084,7 +5510,7 @@ What is your (Jean-Marc) relationship with the University of Sherbrooke
  and how does Speex fit into that?
 \layout Standard
 
-I am currently (2002/08/13) doing a Ph.D.
+I am currently (2003/01/13) doing a Ph.D.
  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.