Preparing for rc2
[speexdsp.git] / doc / manual.lyx
index 6aaae5a..af400e5 100644 (file)
@@ -29,7 +29,7 @@
 
 The Speex Codec Manual
 \newline 
-(draft for Speex 1.0rc1)
+(for version 1.0rc2)
 \layout Author
 
 Jean-Marc Valin
@@ -123,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
@@ -215,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)
@@ -706,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
@@ -842,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
@@ -897,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">
@@ -908,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">
@@ -990,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">
@@ -1072,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">
@@ -1154,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">
@@ -1236,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">
@@ -1318,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">
@@ -1400,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">
@@ -1482,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">
@@ -1564,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">
@@ -1646,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">
@@ -1728,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">
@@ -1810,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">
@@ -1892,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>
 
@@ -2284,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">
@@ -2292,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">
@@ -2300,7 +2389,7 @@ N/A
 
 \layout Standard
 
-reserved
+Very noticeable artifacts/noise, good intelligibility
 \end_inset 
 </cell>
 </row>
@@ -3162,21 +3251,68 @@ 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, wideband and ultra-wideband.
+ 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 (variable)
+Complexity
+\begin_inset LatexCommand \index{complexity}
+
+\end_inset 
+
+ (variable)
 \layout Standard
 
 With Speex, it is possible to vary the complexity allowed for the encoder.
@@ -3195,10 +3331,20 @@ bzip2
  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 tones.
+ settings are often useful when encoding non-speech sounds like DTMF
+\begin_inset LatexCommand \index{DTMF}
+
+\end_inset 
+
+ tones.
 \layout Subsection*
 
-Variable Bit-Rate (VBR)
+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
@@ -3223,7 +3369,12 @@ difficulty
  channel.
 \layout Subsection*
 
-Average Bit-Rate (ABR)
+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
@@ -3233,7 +3384,12 @@ Average bit-rate solves one of the problems of VBR, as it dynamically adjusts
  VBR with exactly the right quality setting to meet the target average bit-rate.
 \layout Subsection*
 
-Voice Activity Detection (VAD)
+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
@@ -3253,7 +3409,12 @@ comfort noise generation
  (CNG).
 \layout Subsection*
 
-Discontinuous Transmission (DTX)
+Discontinuous Transmission
+\begin_inset LatexCommand \index{discontinuous transmission}
+
+\end_inset 
+
+ (DTX)
 \layout Standard
 
 Discontinuous transmission is an addition to VAD operation, that allows
@@ -3263,6 +3424,11 @@ Discontinuous transmission is an addition to VAD operation, that allows
 \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
@@ -3278,6 +3444,30 @@ objectively
 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
@@ -3297,6 +3487,7 @@ speexenc
 speexdec
 \emph default 
 ).
+ This section describes how to use these tools.
 \layout Subsection
 
 
@@ -3309,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 ~
@@ -3422,7 +3626,20 @@ 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 (default)
@@ -3605,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;
@@ -3635,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 
@@ -3732,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)
@@ -3793,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
@@ -3825,6 +4053,43 @@ SPEEX_SET_SAMPLING_RATE Set real sampling rate (integer in Hz)
 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_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
 \layout Description
 
@@ -4471,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
 
@@ -4692,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">
@@ -4952,7 +5209,7 @@ int
 
 \layout Standard
 
-reserved1
+extra_headers
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -4978,7 +5235,7 @@ int
 
 \layout Standard
 
-reserved2
+reserved1
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -5004,7 +5261,7 @@ int
 
 \layout Standard
 
-reserved3
+reserved2
 \end_inset 
 </cell>
 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -5078,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}
 
@@ -5095,7 +5359,7 @@ Ogg is a
 \begin_inset Quotes eld
 \end_inset 
 
-file format
+container format
 \begin_inset Quotes erd
 \end_inset 
 
@@ -5116,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}
 
@@ -5144,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?
@@ -5238,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.