Remove hardcoded docdir, mandir from {doc,src}/Makefile.am, to allow
[speexdsp.git] / doc / manual.lyx
1 #LyX 1.5.0rc1 created this file. For more info see http://www.lyx.org/
2 \lyxformat 271
3 \begin_document
4 \begin_header
5 \textclass scrbook
6 \language english
7 \inputencoding auto
8 \font_roman times
9 \font_sans helvet
10 \font_typewriter courier
11 \font_default_family default
12 \font_sc false
13 \font_osf false
14 \font_sf_scale 100
15 \font_tt_scale 100
16 \graphics default
17 \paperfontsize 10
18 \spacing single
19 \papersize letterpaper
20 \use_geometry true
21 \use_amsmath 2
22 \use_esint 0
23 \cite_engine basic
24 \use_bibtopic false
25 \paperorientation portrait
26 \leftmargin 2cm
27 \topmargin 2cm
28 \rightmargin 2cm
29 \bottommargin 2cm
30 \secnumdepth 3
31 \tocdepth 3
32 \paragraph_separation indent
33 \defskip medskip
34 \quotes_language english
35 \papercolumns 1
36 \papersides 1
37 \paperpagestyle headings
38 \tracking_changes false
39 \output_changes false
40 \author "Jean-Marc Valin,,," 
41 \end_header
42
43 \begin_body
44
45 \begin_layout Title
46 The Speex Codec Manual
47 \newline
48 Version 1.2 Beta 2
49 \end_layout
50
51 \begin_layout Author
52 Jean-Marc Valin
53 \end_layout
54
55 \begin_layout Standard
56
57 \newpage
58
59 \end_layout
60
61 \begin_layout Standard
62 Copyright 
63 \begin_inset ERT
64 status collapsed
65
66 \begin_layout Standard
67
68
69 \backslash
70 copyright
71 \end_layout
72
73 \end_inset
74
75  2002-2007 Jean-Marc Valin/Xiph.org Foundation
76 \end_layout
77
78 \begin_layout Standard
79 Permission is granted to copy, distribute and/or modify this document under
80  the terms of the GNU Free Documentation License, Version 1.1 or any later
81  version published by the Free Software Foundation; with no Invariant Section,
82  with no Front-Cover Texts, and with no Back-Cover.
83  A copy of the license is included in the section entitled "GNU Free Documentati
84 on License".
85  
86 \end_layout
87
88 \begin_layout Standard
89
90 \newpage
91
92 \begin_inset LatexCommand tableofcontents
93
94 \end_inset
95
96
97 \newpage
98
99 \end_layout
100
101 \begin_layout Standard
102 \begin_inset FloatList table
103
104 \end_inset
105
106
107 \newpage
108
109 \end_layout
110
111 \begin_layout Chapter
112 Introduction to Speex
113 \end_layout
114
115 \begin_layout Standard
116 The Speex codec (
117 \family typewriter
118 http://www.speex.org/
119 \family default
120 ) exists because there is a need for a speech codec that is open-source
121  and free from software patent royalties.
122  These are essential conditions for being usable in any open-source software.
123  In essence, Speex is to speech what Vorbis is to audio/music.
124  Unlike many other speech codecs, Speex is not designed for mobile phones
125  but rather for packet networks and voice over IP (VoIP) applications.
126  File-based compression is of course also supported.
127  
128 \end_layout
129
130 \begin_layout Standard
131 The Speex codec is designed to be very flexible and support a wide range
132  of speech quality and bit-rate.
133  Support for very good quality speech also means that Speex can encode wideband
134  speech (16 kHz sampling rate) in addition to narrowband speech (telephone
135  quality, 8 kHz sampling rate).
136 \end_layout
137
138 \begin_layout Standard
139 Designing for VoIP instead of mobile phones means that Speex is robust to
140  lost packets, but not to corrupted ones.
141  This is based on the assumption that in VoIP, packets either arrive unaltered
142  or don't arrive at all.
143  Because Speex is targeted at a wide range of devices, it has modest (adjustable
144 ) complexity and a small memory footprint.
145 \end_layout
146
147 \begin_layout Standard
148 All the design goals led to the choice of CELP
149 \begin_inset LatexCommand index
150 name "CELP"
151
152 \end_inset
153
154  as the encoding technique.
155  One of the main reasons is that CELP has long proved that it could work
156  reliably and scale well to both low bit-rates (e.g.
157  DoD CELP @ 4.8 kbps) and high bit-rates (e.g.
158  G.728 @ 16 kbps).
159  
160 \end_layout
161
162 \begin_layout Section
163 Getting help
164 \begin_inset LatexCommand label
165 name "sec:Getting-help"
166
167 \end_inset
168
169
170 \end_layout
171
172 \begin_layout Standard
173 As for many open source projects, there are many ways to get help with Speex.
174  These include:
175 \end_layout
176
177 \begin_layout Itemize
178 This manual
179 \end_layout
180
181 \begin_layout Itemize
182 Other documentation on the Speex website (http://www.speex.org/)
183 \end_layout
184
185 \begin_layout Itemize
186 Mailing list: Discuss any Speex-related topic on speex-dev@xiph.org (not
187  just for developers)
188 \end_layout
189
190 \begin_layout Itemize
191 IRC: The main channel is #speex on irc.freenode.net.
192  Note that due to time differences, it may take a while to get someone,
193  so please be patient.
194 \end_layout
195
196 \begin_layout Itemize
197 Email the author privately at jean-marc.valin@usherbrooke.ca 
198 \series bold
199 only
200 \series default
201  for private/delicate topics you do not wish to discuss publically.
202 \end_layout
203
204 \begin_layout Standard
205 Before asking for help (mailing list or IRC), 
206 \series bold
207 it is important to first read this manual
208 \series default
209  (OK, so if you made it here it's already a good sign).
210  It is generally considered rude to ask on a mailing list about topics that
211  are clearly detailed in the documentation.
212  On the other hand, it's perfectly OK (and encouraged) to ask for clarifications
213  about something covered in the manual.
214  This manual does not (yet) cover everything about Speex, so everyone is
215  encouraged to ask questions, send comments, feature requests, or just let
216  us know how Speex is being used.
217  
218 \end_layout
219
220 \begin_layout Standard
221 Here are some additional guidelines related to the mailing list.
222  Before reporting bugs in Speex to the list, it is strongly recommended
223  (if possible) to first test whether these bugs can be reproduced using
224  the speexenc and speexdec (see Section 
225 \begin_inset LatexCommand ref
226 reference "sec:Command-line-encoder/decoder"
227
228 \end_inset
229
230 ) command-line utilities.
231  Bugs reported based on 3rd party code are both harder to find and far too
232  often caused by errors that have nothing to do with Speex.
233  
234 \end_layout
235
236 \begin_layout Section
237 About this document
238 \end_layout
239
240 \begin_layout Standard
241 This document is divided in the following way.
242  Section 
243 \begin_inset LatexCommand ref
244 reference "sec:Feature-description"
245
246 \end_inset
247
248  describes the different Speex features and defines many basic terms that
249  are used throughout this manual.
250  Section 
251 \begin_inset LatexCommand ref
252 reference "sec:Command-line-encoder/decoder"
253
254 \end_inset
255
256  documents the standard command-line tools provided in the Speex distribution.
257  Section 
258 \begin_inset LatexCommand ref
259 reference "sec:Programming-with-Speex"
260
261 \end_inset
262
263  includes detailed instructions about programming using the libspeex
264 \begin_inset LatexCommand index
265 name "libspeex"
266
267 \end_inset
268
269  API.
270  Section 
271 \begin_inset LatexCommand ref
272 reference "sec:Formats-and-standards"
273
274 \end_inset
275
276  has some information related to Speex and standards.
277  
278 \end_layout
279
280 \begin_layout Standard
281 The three last sections describe the algorithms used in Speex.
282  These sections require signal processing knowledge, but are not required
283  for merely using Speex.
284  They are intended for people who want to understand how Speex really works
285  and/or want to do research based on Speex.
286  Section 
287 \begin_inset LatexCommand ref
288 reference "sec:Introduction-to-CELP"
289
290 \end_inset
291
292  explains the general idea behind CELP, while sections 
293 \begin_inset LatexCommand ref
294 reference "sec:Speex-narrowband-mode"
295
296 \end_inset
297
298  and 
299 \begin_inset LatexCommand ref
300 reference "sec:Speex-wideband-mode"
301
302 \end_inset
303
304  are specific to Speex.
305 \end_layout
306
307 \begin_layout Standard
308
309 \newpage
310
311 \end_layout
312
313 \begin_layout Chapter
314 Codec description
315 \begin_inset LatexCommand label
316 name "sec:Feature-description"
317
318 \end_inset
319
320
321 \end_layout
322
323 \begin_layout Standard
324 This section describes Speex and its features into more details.
325 \end_layout
326
327 \begin_layout Section
328 Concepts
329 \end_layout
330
331 \begin_layout Standard
332 Before introducing all the Speex features, here are some concepts in speech
333  coding that help better understand the rest of the manual.
334  Although some are general concepts in speech/audio processing, others are
335  specific to Speex.
336 \end_layout
337
338 \begin_layout Subsection*
339 Sampling rate
340 \begin_inset LatexCommand index
341 name "sampling rate"
342
343 \end_inset
344
345
346 \end_layout
347
348 \begin_layout Standard
349 The sampling rate expressed in Hertz (Hz) is the number of samples taken
350  from a signal per second.
351  For a sampling rate of 
352 \begin_inset Formula $F_{s}$
353 \end_inset
354
355  kHz, the highest frequency that can be represented is equal to 
356 \begin_inset Formula $F_{s}/2$
357 \end_inset
358
359  kHz (
360 \begin_inset Formula $F_{s}/2$
361 \end_inset
362
363  is known as the Nyquist frequency).
364  This is a fundamental property in signal processing and is described by
365  the sampling theorem.
366  Speex is mainly designed for three different sampling rates: 8 kHz, 16
367  kHz, and 32 kHz.
368  These are respectively refered to as narrowband
369 \begin_inset LatexCommand index
370 name "narrowband"
371
372 \end_inset
373
374 , wideband
375 \begin_inset LatexCommand index
376 name "wideband"
377
378 \end_inset
379
380  and ultra-wideband
381 \begin_inset LatexCommand index
382 name "ultra-wideband"
383
384 \end_inset
385
386 .
387  
388 \end_layout
389
390 \begin_layout Subsection*
391 Bit-rate
392 \end_layout
393
394 \begin_layout Standard
395 When encoding a speech signal, the bit-rate is defined as the number of
396  bits per unit of time required to encode the speech.
397  It is measured in 
398 \emph on
399 bits per second
400 \emph default
401  (bps), or generally 
402 \emph on
403 kilobits per second
404 \emph default
405 .
406  It is important to make the distinction between 
407 \emph on
408 kilo
409 \series bold
410 bits
411 \series default
412 \emph default
413  
414 \emph on
415 per second
416 \emph default
417  (k
418 \series bold
419 b
420 \series default
421 ps) and 
422 \emph on
423 kilo
424 \series bold
425 bytes
426 \series default
427 \emph default
428  
429 \emph on
430 per second
431 \emph default
432  (k
433 \series bold
434 B
435 \series default
436 ps).
437 \end_layout
438
439 \begin_layout Subsection*
440 Quality
441 \begin_inset LatexCommand index
442 name "quality"
443
444 \end_inset
445
446  (variable)
447 \end_layout
448
449 \begin_layout Standard
450 Speex is a lossy codec, which means that it achives compression at the expense
451  of fidelity of the input speech signal.
452  Unlike some other speech codecs, it is possible to control the tradeoff
453  made between quality and bit-rate.
454  The Speex encoding process is controlled most of the time by a quality
455  parameter that ranges from 0 to 10.
456  In constant bit-rate
457 \begin_inset LatexCommand index
458 name "constant bit-rate"
459
460 \end_inset
461
462  (CBR) operation, the quality parameter is an integer, while for variable
463  bit-rate (VBR), the parameter is a float.
464  
465 \end_layout
466
467 \begin_layout Subsection*
468 Complexity
469 \begin_inset LatexCommand index
470 name "complexity"
471
472 \end_inset
473
474  (variable)
475 \end_layout
476
477 \begin_layout Standard
478 With Speex, it is possible to vary the complexity allowed for the encoder.
479  This is done by controlling how the search is performed with an integer
480  ranging from 1 to 10 in a way that's similar to the -1 to -9 options to
481  
482 \emph on
483 gzip
484 \emph default
485  and 
486 \emph on
487 bzip2
488 \emph default
489  compression utilities.
490  For normal use, the noise level at complexity 1 is between 1 and 2 dB higher
491  than at complexity 10, but the CPU requirements for complexity 10 is about
492  5 times higher than for complexity 1.
493  In practice, the best trade-off is between complexity 2 and 4, though higher
494  settings are often useful when encoding non-speech sounds like DTMF
495 \begin_inset LatexCommand index
496 name "DTMF"
497
498 \end_inset
499
500  tones.
501 \end_layout
502
503 \begin_layout Subsection*
504 Variable Bit-Rate
505 \begin_inset LatexCommand index
506 name "variable bit-rate"
507
508 \end_inset
509
510  (VBR)
511 \end_layout
512
513 \begin_layout Standard
514 Variable bit-rate (VBR) allows a codec to change its bit-rate dynamically
515  to adapt to the 
516 \begin_inset Quotes eld
517 \end_inset
518
519 difficulty
520 \begin_inset Quotes erd
521 \end_inset
522
523  of the audio being encoded.
524  In the example of Speex, sounds like vowels and high-energy transients
525  require a higher bit-rate to achieve good quality, while fricatives (e.g.
526  s,f sounds) can be coded adequately with less bits.
527  For this reason, VBR can achive lower bit-rate for the same quality, or
528  a better quality for a certain bit-rate.
529  Despite its advantages, VBR has two main drawbacks: first, by only specifying
530  quality, there's no guaranty about the final average bit-rate.
531  Second, for some real-time applications like voice over IP (VoIP), what
532  counts is the maximum bit-rate, which must be low enough for the communication
533  channel.
534 \end_layout
535
536 \begin_layout Subsection*
537 Average Bit-Rate
538 \begin_inset LatexCommand index
539 name "average bit-rate"
540
541 \end_inset
542
543  (ABR)
544 \end_layout
545
546 \begin_layout Standard
547 Average bit-rate solves one of the problems of VBR, as it dynamically adjusts
548  VBR quality in order to meet a specific target bit-rate.
549  Because the quality/bit-rate is adjusted in real-time (open-loop), the
550  global quality will be slightly lower than that obtained by encoding in
551  VBR with exactly the right quality setting to meet the target average bit-rate.
552 \end_layout
553
554 \begin_layout Subsection*
555 Voice Activity Detection
556 \begin_inset LatexCommand index
557 name "voice activity detection"
558
559 \end_inset
560
561  (VAD)
562 \end_layout
563
564 \begin_layout Standard
565 When enabled, voice activity detection detects whether the audio being encoded
566  is speech or silence/background noise.
567  VAD is always implicitly activated when encoding in VBR, so the option
568  is only useful in non-VBR operation.
569  In this case, Speex detects non-speech periods and encode them with just
570  enough bits to reproduce the background noise.
571  This is called 
572 \begin_inset Quotes eld
573 \end_inset
574
575 comfort noise generation
576 \begin_inset Quotes erd
577 \end_inset
578
579  (CNG).
580 \end_layout
581
582 \begin_layout Subsection*
583 Discontinuous Transmission
584 \begin_inset LatexCommand index
585 name "discontinuous transmission"
586
587 \end_inset
588
589  (DTX)
590 \end_layout
591
592 \begin_layout Standard
593 Discontinuous transmission is an addition to VAD/VBR operation, that allows
594  to stop transmitting completely when the background noise is stationary.
595  In file-based operation, since we cannot just stop writing to the file,
596  only 5 bits are used for such frames (corresponding to 250 bps).
597 \end_layout
598
599 \begin_layout Subsection*
600 Perceptual enhancement
601 \begin_inset LatexCommand index
602 name "perceptual enhancement"
603
604 \end_inset
605
606
607 \end_layout
608
609 \begin_layout Standard
610 Perceptual enhancement is a part of the decoder which, when turned on, attempts
611  to reduce the perception of the noise/distortion produced by the encoding/decod
612 ing process.
613  In most cases, perceptual enhancement brings the sound further from the
614  original 
615 \emph on
616 objectively
617 \emph default
618  (e.g.
619  considering only SNR), but in the end it still 
620 \emph on
621 sounds
622 \emph default
623  better (subjective improvement).
624 \end_layout
625
626 \begin_layout Subsection*
627 Latency and algorithmic delay
628 \begin_inset LatexCommand index
629 name "algorithmic delay"
630
631 \end_inset
632
633
634 \end_layout
635
636 \begin_layout Standard
637 Every speech codec introduces a delay in the transmission.
638  For Speex, this delay is equal to the frame size, plus some amount of 
639 \begin_inset Quotes eld
640 \end_inset
641
642 look-ahead
643 \begin_inset Quotes erd
644 \end_inset
645
646  required to process each frame.
647  In narrowband operation (8 kHz), the delay is 30 ms, while for wideband
648  (16 kHz), the delay is 34 ms.
649  These values don't account for the CPU time it takes to encode or decode
650  the frames.
651 \end_layout
652
653 \begin_layout Section
654 Codec
655 \end_layout
656
657 \begin_layout Standard
658 The main characteristics of Speex can be summarized as follows:
659 \end_layout
660
661 \begin_layout Itemize
662 Free software/open-source
663 \begin_inset LatexCommand index
664 name "open-source"
665
666 \end_inset
667
668 , patent
669 \begin_inset LatexCommand index
670 name "patent"
671
672 \end_inset
673
674  and royalty-free
675 \end_layout
676
677 \begin_layout Itemize
678 Integration of narrowband
679 \begin_inset LatexCommand index
680 name "narrowband"
681
682 \end_inset
683
684  and wideband
685 \begin_inset LatexCommand index
686 name "wideband"
687
688 \end_inset
689
690  using an embedded bit-stream
691 \end_layout
692
693 \begin_layout Itemize
694 Wide range of bit-rates available (from 2.15 kbps to 44 kbps)
695 \end_layout
696
697 \begin_layout Itemize
698 Dynamic bit-rate switching (AMR) and Variable Bit-Rate
699 \begin_inset LatexCommand index
700 name "variable bit-rate"
701
702 \end_inset
703
704  (VBR) operation
705 \end_layout
706
707 \begin_layout Itemize
708 Voice Activity Detection
709 \begin_inset LatexCommand index
710 name "voice activity detection"
711
712 \end_inset
713
714  (VAD, integrated with VBR) and discontinuous transmission (DTX)
715 \end_layout
716
717 \begin_layout Itemize
718 Variable complexity
719 \begin_inset LatexCommand index
720 name "complexity"
721
722 \end_inset
723
724
725 \end_layout
726
727 \begin_layout Itemize
728 Embedded wideband structure (scalable sampling rate)
729 \end_layout
730
731 \begin_layout Itemize
732 Ultra-wideband sampling rate at 32 kHz
733 \end_layout
734
735 \begin_layout Itemize
736 Intensity stereo encoding option
737 \end_layout
738
739 \begin_layout Itemize
740 Fixed-point implementation
741 \end_layout
742
743 \begin_layout Section
744 Preprocessor
745 \end_layout
746
747 \begin_layout Standard
748 This part refers to the preprocessor module introduced in the 1.1.x branch.
749  The preprocessor is designed to be used on the audio 
750 \emph on
751 before
752 \emph default
753  running the encoder.
754  The preprocessor provides three main functionalities:
755 \end_layout
756
757 \begin_layout Itemize
758 noise suppression
759 \end_layout
760
761 \begin_layout Itemize
762 automatic gain control (AGC)
763 \end_layout
764
765 \begin_layout Itemize
766 voice activity detection (VAD)
767 \end_layout
768
769 \begin_layout Standard
770 The denoiser can be used to reduce the amount of background noise present
771  in the input signal.
772  This provides higher quality speech whether or not the denoised signal
773  is encoded with Speex (or at all).
774  However, when using the denoised signal with the codec, there is an additional
775  benefit.
776  Speech codecs in general (Speex included) tend to perform poorly on noisy
777  input, which tends to amplify the noise.
778  The denoiser greatly reduces this effect.
779 \end_layout
780
781 \begin_layout Standard
782 Automatic gain control (AGC) is a feature that deals with the fact that
783  the recording volume may vary by a large amount between different setups.
784  The AGC provides a way to adjust a signal to a reference volume.
785  This is useful for voice over IP because it removes the need for manual
786  adjustment of the microphone gain.
787  A secondary advantage is that by setting the microphone gain to a conservative
788  (low) level, it is easier to avoid clipping.
789 \end_layout
790
791 \begin_layout Standard
792 The voice activity detector (VAD) provided by the preprocessor is more advanced
793  than the one directly provided in the codec.
794  
795 \end_layout
796
797 \begin_layout Section
798 Adaptive Jitter Buffer
799 \end_layout
800
801 \begin_layout Standard
802 When transmitting voice (or any content for that matter) over UDP or RTP,
803  packet may be lost, arrive with different delay, or even out of order.
804  The purpose of a jitter buffer is to reorder packets and buffer them long
805  enough (but no longer than necessary) so they can be sent to be decoded.
806  
807 \end_layout
808
809 \begin_layout Section
810 Acoustic Echo Canceller
811 \end_layout
812
813 \begin_layout Standard
814 In any hands-free communication system (Fig.
815  
816 \begin_inset LatexCommand ref
817 reference "fig:Acoustic-echo-model"
818
819 \end_inset
820
821 ), speech from the remote end is played in the local loudspeaker, propagates
822  in the room and is captured by the microphone.
823  If the audio captured from the microphone is sent directly to the remote
824  end, then the remove user hears an echo of his voice.
825  An acoustic echo canceller is designed to remove the acoustic echo before
826  it is sent to the remote end.
827  It is important to understand that the echo canceller is meant to improve
828  the quality on the 
829 \series bold
830 remote
831 \series default
832  end.
833 \end_layout
834
835 \begin_layout Standard
836 \begin_inset Float figure
837 wide false
838 sideways false
839 status open
840
841 \begin_layout Standard
842 \begin_inset ERT
843 status collapsed
844
845 \begin_layout Standard
846
847
848 \backslash
849 begin{center}
850 \end_layout
851
852 \end_inset
853
854
855 \begin_inset Graphics
856         filename echo_path.eps
857         width 10cm
858
859 \end_inset
860
861
862 \begin_inset ERT
863 status collapsed
864
865 \begin_layout Standard
866
867
868 \backslash
869 end{center}
870 \end_layout
871
872 \end_inset
873
874
875 \end_layout
876
877 \begin_layout Standard
878 \begin_inset Caption
879
880 \begin_layout Standard
881 Acoustic echo model
882 \begin_inset LatexCommand label
883 name "fig:Acoustic-echo-model"
884
885 \end_inset
886
887
888 \end_layout
889
890 \end_inset
891
892
893 \end_layout
894
895 \end_inset
896
897
898 \end_layout
899
900 \begin_layout Standard
901
902 \newpage
903
904 \end_layout
905
906 \begin_layout Chapter
907 Compiling
908 \end_layout
909
910 \begin_layout Standard
911 Compiling Speex under UNIX/Linux or any other platform supported by autoconf
912  (e.g.
913  Win32/cygwin) is as easy as typing:
914 \end_layout
915
916 \begin_layout LyX-Code
917 % ./configure [options]
918 \end_layout
919
920 \begin_layout LyX-Code
921 % make
922 \end_layout
923
924 \begin_layout LyX-Code
925 % make install
926 \end_layout
927
928 \begin_layout Standard
929 The options supported by the Speex configure script are:
930 \end_layout
931
932 \begin_layout Description
933 --prefix=<path> Specifies the base path for installing Speex (e.g.
934  /usr)
935 \end_layout
936
937 \begin_layout Description
938 --enable-shared/--disable-shared Whether to compile shared libraries
939 \end_layout
940
941 \begin_layout Description
942 --enable-static/--disable-static Whether to compile static libraries
943 \end_layout
944
945 \begin_layout Description
946 --disable-wideband Disable the wideband part of Speex (typically to save
947  space)
948 \end_layout
949
950 \begin_layout Description
951 --enable-valgrind Enable extra hits for valgrind for debugging purposes
952  (do not use by default)
953 \end_layout
954
955 \begin_layout Description
956 --enable-sse Enable use of SSE instructions (x86/float only)
957 \end_layout
958
959 \begin_layout Description
960 --enable-fixed-point
961 \begin_inset LatexCommand index
962 name "fixed-point"
963
964 \end_inset
965
966  Compile Speex for a processor that does not have a floating point unit
967  (FPU)
968 \end_layout
969
970 \begin_layout Description
971 --enable-arm4-asm Enable assembly specific to the ARMv4 architecture (gcc
972  only)
973 \end_layout
974
975 \begin_layout Description
976 --enable-arm5e-asm Enable assembly specific to the ARMv5E architecture (gcc
977  only)
978 \end_layout
979
980 \begin_layout Description
981 --enable-fixed-point-debug Use only for debugging the fixed-point
982 \begin_inset LatexCommand index
983 name "fixed-point"
984
985 \end_inset
986
987  code (very slow)
988 \end_layout
989
990 \begin_layout Description
991 --enable-epic-48k Enable a special (and non-compatible) 4.8 kbps narrowband
992  mode (broken in 1.1.x and 1.2beta)
993 \end_layout
994
995 \begin_layout Description
996 --enable-ti-c55x Enable support for the TI C5x family
997 \end_layout
998
999 \begin_layout Description
1000 --enable-blackfin-asm Enable assembly specific to the Blackfin DSP architecture
1001  (gcc only)
1002 \end_layout
1003
1004 \begin_layout Description
1005 --enable-vorbis-psycho Make the encoder use the Vorbis psycho-acoustic model.
1006  This is very experimental and may be removed in the future.
1007 \end_layout
1008
1009 \begin_layout Section
1010 Platforms
1011 \end_layout
1012
1013 \begin_layout Standard
1014 Speex is known to compile and work on a large number of architectures, both
1015  floating-point and fixed-point.
1016  In general, any architecture that can natively compute the multiplication
1017  of two signed 16-bit numbers (32-bit result) and runs at a sufficient clock
1018  rate (architecture-dependent) is capable of running Speex.
1019  Architectures that are 
1020 \series bold
1021 known
1022 \series default
1023  to be supported (it probably works on many others) are:
1024 \end_layout
1025
1026 \begin_layout Itemize
1027 x86 & x86-64
1028 \end_layout
1029
1030 \begin_layout Itemize
1031 Power
1032 \end_layout
1033
1034 \begin_layout Itemize
1035 SPARC
1036 \end_layout
1037
1038 \begin_layout Itemize
1039 ARM
1040 \end_layout
1041
1042 \begin_layout Itemize
1043 Blackfin
1044 \end_layout
1045
1046 \begin_layout Itemize
1047 TI C54xx & C55xx
1048 \end_layout
1049
1050 \begin_layout Itemize
1051 TI C6xxx
1052 \end_layout
1053
1054 \begin_layout Itemize
1055 TriMedia (experimental)
1056 \end_layout
1057
1058 \begin_layout Standard
1059 Operating systems on top of which Speex is known to work include (it probably
1060  works on many others):
1061 \end_layout
1062
1063 \begin_layout Itemize
1064 Linux
1065 \end_layout
1066
1067 \begin_layout Itemize
1068 \begin_inset Formula $\mu$
1069 \end_inset
1070
1071 Clinux
1072 \end_layout
1073
1074 \begin_layout Itemize
1075 MacOS X
1076 \end_layout
1077
1078 \begin_layout Itemize
1079 BSD
1080 \end_layout
1081
1082 \begin_layout Itemize
1083 Other UNIX/POSIX variants
1084 \end_layout
1085
1086 \begin_layout Itemize
1087 Symbian
1088 \end_layout
1089
1090 \begin_layout Standard
1091 The source code directory include additional information for compiling on
1092  certain architectures or operating systems in README.xxx files.
1093 \end_layout
1094
1095 \begin_layout Standard
1096
1097 \newpage
1098
1099 \end_layout
1100
1101 \begin_layout Chapter
1102 Command-line encoder/decoder
1103 \begin_inset LatexCommand label
1104 name "sec:Command-line-encoder/decoder"
1105
1106 \end_inset
1107
1108
1109 \end_layout
1110
1111 \begin_layout Standard
1112 The base Speex distribution includes a command-line encoder (
1113 \emph on
1114 speexenc
1115 \emph default
1116 ) and decoder (
1117 \emph on
1118 speexdec
1119 \emph default
1120 ).
1121  This section describes how to use these tools.
1122 \end_layout
1123
1124 \begin_layout Section
1125
1126 \emph on
1127 speexenc
1128 \begin_inset LatexCommand index
1129 name "speexenc"
1130
1131 \end_inset
1132
1133
1134 \end_layout
1135
1136 \begin_layout Standard
1137 The 
1138 \emph on
1139 speexenc
1140 \emph default
1141  utility is used to create Speex files from raw PCM or wave files.
1142  It can be used by calling: 
1143 \end_layout
1144
1145 \begin_layout LyX-Code
1146 speexenc [options] input_file output_file
1147 \end_layout
1148
1149 \begin_layout Standard
1150 The value '-' for input_file or output_file corresponds respectively to
1151  stdin and stdout.
1152  The valid options are:
1153 \end_layout
1154
1155 \begin_layout Description
1156 --narrowband\InsetSpace ~
1157 (-n) Tell Speex to treat the input as narrowband (8 kHz).
1158  This is the default
1159 \end_layout
1160
1161 \begin_layout Description
1162 --wideband\InsetSpace ~
1163 (-w) Tell Speex to treat the input as wideband (16 kHz)
1164 \end_layout
1165
1166 \begin_layout Description
1167 --ultra-wideband\InsetSpace ~
1168 (-u) Tell Speex to treat the input as 
1169 \begin_inset Quotes eld
1170 \end_inset
1171
1172 ultra-wideband
1173 \begin_inset Quotes erd
1174 \end_inset
1175
1176  (32 kHz)
1177 \end_layout
1178
1179 \begin_layout Description
1180 --quality\InsetSpace ~
1181 n Set the encoding quality (0-10), default is 8
1182 \end_layout
1183
1184 \begin_layout Description
1185 --bitrate\InsetSpace ~
1186 n Encoding bit-rate (use bit-rate n or lower) 
1187 \end_layout
1188
1189 \begin_layout Description
1190 --vbr Enable VBR (Variable Bit-Rate), disabled by default
1191 \end_layout
1192
1193 \begin_layout Description
1194 --abr\InsetSpace ~
1195 n Enable ABR (Average Bit-Rate) at n kbps, disabled by default
1196 \end_layout
1197
1198 \begin_layout Description
1199 --vad Enable VAD (Voice Activity Detection), disabled by default
1200 \end_layout
1201
1202 \begin_layout Description
1203 --dtx Enable DTX (Discontinuous Transmission), disabled by default
1204 \end_layout
1205
1206 \begin_layout Description
1207 --nframes\InsetSpace ~
1208 n Pack n frames in each Ogg packet (this saves space at low bit-rates)
1209 \end_layout
1210
1211 \begin_layout Description
1212 --comp\InsetSpace ~
1213 n Set encoding speed/quality tradeoff.
1214  The higher the value of n, the slower the encoding (default is 3)
1215 \end_layout
1216
1217 \begin_layout Description
1218 -V Verbose operation, print bit-rate currently in use
1219 \end_layout
1220
1221 \begin_layout Description
1222 --help\InsetSpace ~
1223 (-h) Print the help
1224 \end_layout
1225
1226 \begin_layout Description
1227 --version\InsetSpace ~
1228 (-v) Print version information
1229 \end_layout
1230
1231 \begin_layout Subsection*
1232 Speex comments
1233 \end_layout
1234
1235 \begin_layout Description
1236 --comment Add the given string as an extra comment.
1237  This may be used multiple times.
1238  
1239 \end_layout
1240
1241 \begin_layout Description
1242 --author Author of this track.
1243  
1244 \end_layout
1245
1246 \begin_layout Description
1247 --title Title for this track.
1248  
1249 \end_layout
1250
1251 \begin_layout Subsection*
1252 Raw input options
1253 \end_layout
1254
1255 \begin_layout Description
1256 --rate\InsetSpace ~
1257 n Sampling rate for raw input
1258 \end_layout
1259
1260 \begin_layout Description
1261 --stereo Consider raw input as stereo 
1262 \end_layout
1263
1264 \begin_layout Description
1265 --le Raw input is little-endian 
1266 \end_layout
1267
1268 \begin_layout Description
1269 --be Raw input is big-endian 
1270 \end_layout
1271
1272 \begin_layout Description
1273 --8bit Raw input is 8-bit unsigned 
1274 \end_layout
1275
1276 \begin_layout Description
1277 --16bit Raw input is 16-bit signed 
1278 \end_layout
1279
1280 \begin_layout Section
1281
1282 \emph on
1283 speexdec
1284 \begin_inset LatexCommand index
1285 name "speexdec"
1286
1287 \end_inset
1288
1289
1290 \end_layout
1291
1292 \begin_layout Standard
1293 The 
1294 \emph on
1295 speexdec
1296 \emph default
1297  utility is used to decode Speex files and can be used by calling: 
1298 \end_layout
1299
1300 \begin_layout LyX-Code
1301 speexdec [options] speex_file [output_file]
1302 \end_layout
1303
1304 \begin_layout Standard
1305 The value '-' for input_file or output_file corresponds respectively to
1306  stdin and stdout.
1307  Also, when no output_file is specified, the file is played to the soundcard.
1308  The valid options are:
1309 \end_layout
1310
1311 \begin_layout Description
1312 --enh enable post-filter (default)
1313 \end_layout
1314
1315 \begin_layout Description
1316 --no-enh disable post-filter
1317 \end_layout
1318
1319 \begin_layout Description
1320 --force-nb Force decoding in narrowband 
1321 \end_layout
1322
1323 \begin_layout Description
1324 --force-wb Force decoding in wideband 
1325 \end_layout
1326
1327 \begin_layout Description
1328 --force-uwb Force decoding in ultra-wideband 
1329 \end_layout
1330
1331 \begin_layout Description
1332 --mono Force decoding in mono 
1333 \end_layout
1334
1335 \begin_layout Description
1336 --stereo Force decoding in stereo 
1337 \end_layout
1338
1339 \begin_layout Description
1340 --rate\InsetSpace ~
1341 n Force decoding at n Hz sampling rate
1342 \end_layout
1343
1344 \begin_layout Description
1345 --packet-loss\InsetSpace ~
1346 n Simulate n % random packet loss
1347 \end_layout
1348
1349 \begin_layout Description
1350 -V Verbose operation, print bit-rate currently in use
1351 \end_layout
1352
1353 \begin_layout Description
1354 --help\InsetSpace ~
1355 (-h) Print the help
1356 \end_layout
1357
1358 \begin_layout Description
1359 --version\InsetSpace ~
1360 (-v) Print version information
1361 \end_layout
1362
1363 \begin_layout Standard
1364
1365 \newpage
1366
1367 \end_layout
1368
1369 \begin_layout Chapter
1370 Programming with Speex (the libspeex
1371 \begin_inset LatexCommand index
1372 name "libspeex"
1373
1374 \end_inset
1375
1376  API
1377 \begin_inset LatexCommand index
1378 name "API"
1379
1380 \end_inset
1381
1382 )
1383 \begin_inset LatexCommand label
1384 name "sec:Programming-with-Speex"
1385
1386 \end_inset
1387
1388
1389 \end_layout
1390
1391 \begin_layout Standard
1392 This section explains how to use the Speex API.
1393  Examples of code can also be found in Appendix 
1394 \begin_inset LatexCommand ref
1395 reference "sec:Sample-code"
1396
1397 \end_inset
1398
1399  and the complete API documentation is included in the Documentation section
1400  of the Speex website (http://www.speex.org/).
1401 \end_layout
1402
1403 \begin_layout Section
1404 Encoding
1405 \begin_inset LatexCommand label
1406 name "sub:Encoding"
1407
1408 \end_inset
1409
1410
1411 \end_layout
1412
1413 \begin_layout Standard
1414 In order to encode speech using Speex, one first needs to:
1415 \end_layout
1416
1417 \begin_layout LyX-Code
1418 #include <speex/speex.h>
1419 \end_layout
1420
1421 \begin_layout Standard
1422 Then a Speex bit-packing struct must be declared as:
1423 \end_layout
1424
1425 \begin_layout LyX-Code
1426 SpeexBits bits;
1427 \end_layout
1428
1429 \begin_layout Standard
1430 along with a Speex encoder state
1431 \end_layout
1432
1433 \begin_layout LyX-Code
1434 void *enc_state;
1435 \end_layout
1436
1437 \begin_layout Standard
1438 The two are initialized by:
1439 \end_layout
1440
1441 \begin_layout LyX-Code
1442 speex_bits_init(&bits);
1443 \end_layout
1444
1445 \begin_layout LyX-Code
1446 enc_state = speex_encoder_init(&speex_nb_mode);
1447 \end_layout
1448
1449 \begin_layout Standard
1450 For wideband coding, 
1451 \emph on
1452 speex_nb_mode
1453 \emph default
1454  will be replaced by 
1455 \emph on
1456 speex_wb_mode
1457 \emph default
1458 .
1459  In most cases, you will need to know the frame size used at the sampling
1460  rate you are using.
1461  You can get that value in the 
1462 \emph on
1463 frame_size
1464 \emph default
1465  variable (expressed in 
1466 \series bold
1467 samples
1468 \series default
1469 , not bytes) with:
1470 \end_layout
1471
1472 \begin_layout LyX-Code
1473 speex_encoder_ctl(enc_state,SPEEX_GET_FRAME_SIZE,&frame_size);
1474 \end_layout
1475
1476 \begin_layout Standard
1477 In practice, 
1478 \emph on
1479 frame_size
1480 \emph default
1481  will correspond to 20 ms when using 8, 16, or 32 kHz sampling rate.
1482  There are many parameters that can be set for the Speex encoder, but the
1483  most useful one is the quality parameter that controls the quality vs bit-rate
1484  tradeoff.
1485  This is set by:
1486 \end_layout
1487
1488 \begin_layout LyX-Code
1489 speex_encoder_ctl(enc_state,SPEEX_SET_QUALITY,&quality);
1490 \end_layout
1491
1492 \begin_layout Standard
1493 where 
1494 \emph on
1495 quality
1496 \emph default
1497  is an integer value ranging from 0 to 10 (inclusively).
1498  The mapping between quality and bit-rate is described in Fig.
1499  
1500 \begin_inset LatexCommand ref
1501 reference "cap:quality_vs_bps"
1502
1503 \end_inset
1504
1505  for narrowband.
1506 \end_layout
1507
1508 \begin_layout Standard
1509 Once the initialization is done, for every input frame:
1510 \end_layout
1511
1512 \begin_layout LyX-Code
1513 speex_bits_reset(&bits);
1514 \end_layout
1515
1516 \begin_layout LyX-Code
1517 speex_encode_int(enc_state, input_frame, &bits);
1518 \end_layout
1519
1520 \begin_layout LyX-Code
1521 nbBytes = speex_bits_write(&bits, byte_ptr, MAX_NB_BYTES);
1522 \end_layout
1523
1524 \begin_layout Standard
1525 where 
1526 \emph on
1527 input_frame
1528 \emph default
1529  is a 
1530 \emph on
1531 (
1532 \emph default
1533 short 
1534 \emph on
1535 *)
1536 \emph default
1537  pointing to the beginning of a speech frame, 
1538 \emph on
1539 byte_ptr
1540 \emph default
1541  is a 
1542 \emph on
1543 (char *)
1544 \emph default
1545  where the encoded frame will be written, 
1546 \emph on
1547 MAX_NB_BYTES
1548 \emph default
1549  is the maximum number of bytes that can be written to 
1550 \emph on
1551 byte_ptr
1552 \emph default
1553  without causing an overflow and 
1554 \emph on
1555 nbBytes
1556 \emph default
1557  is the number of bytes actually written to 
1558 \emph on
1559 byte_ptr
1560 \emph default
1561  (the encoded size in bytes).
1562  Before calling speex_bits_write, it is possible to find the number of bytes
1563  that need to be written by calling 
1564 \family typewriter
1565 speex_bits_nbytes(&bits)
1566 \family default
1567 , which returns a number of bytes.
1568 \end_layout
1569
1570 \begin_layout Standard
1571 It is still possible to use the 
1572 \emph on
1573 speex_encode()
1574 \emph default
1575  function, which takes a 
1576 \emph on
1577 (float *)
1578 \emph default
1579  for the audio.
1580  However, this would make an eventual port to an FPU-less platform (like
1581  ARM) more complicated.
1582  Internally, 
1583 \emph on
1584 speex_encode()
1585 \emph default
1586  and 
1587 \emph on
1588 speex_encode_int()
1589 \emph default
1590  are processed in the same way.
1591  Whether the encoder uses the fixed-point version is only decided by the
1592  compile-time flags, not at the API level.
1593 \end_layout
1594
1595 \begin_layout Standard
1596 After you're done with the encoding, free all resources with:
1597 \end_layout
1598
1599 \begin_layout LyX-Code
1600 speex_bits_destroy(&bits);
1601 \end_layout
1602
1603 \begin_layout LyX-Code
1604 speex_encoder_destroy(enc_state);
1605 \end_layout
1606
1607 \begin_layout Standard
1608 That's about it for the encoder.
1609  
1610 \end_layout
1611
1612 \begin_layout Section
1613 Decoding
1614 \begin_inset LatexCommand label
1615 name "sub:Decoding"
1616
1617 \end_inset
1618
1619
1620 \end_layout
1621
1622 \begin_layout Standard
1623 In order to decode speech using Speex, you first need to:
1624 \end_layout
1625
1626 \begin_layout LyX-Code
1627 #include <speex/speex.h>
1628 \end_layout
1629
1630 \begin_layout Standard
1631 You also need to declare a Speex bit-packing struct
1632 \end_layout
1633
1634 \begin_layout LyX-Code
1635 SpeexBits bits;
1636 \end_layout
1637
1638 \begin_layout Standard
1639 and a Speex decoder state
1640 \end_layout
1641
1642 \begin_layout LyX-Code
1643 void *dec_state;
1644 \end_layout
1645
1646 \begin_layout Standard
1647 The two are initialized by:
1648 \end_layout
1649
1650 \begin_layout LyX-Code
1651 speex_bits_init(&bits);
1652 \end_layout
1653
1654 \begin_layout LyX-Code
1655 dec_state = speex_decoder_init(&speex_nb_mode);
1656 \end_layout
1657
1658 \begin_layout Standard
1659 For wideband decoding, 
1660 \emph on
1661 speex_nb_mode
1662 \emph default
1663  will be replaced by 
1664 \emph on
1665 speex_wb_mode
1666 \emph default
1667 .
1668  If you need to obtain the size of the frames that will be used by the decoder,
1669  you can get that value in the 
1670 \emph on
1671 frame_size
1672 \emph default
1673  variable (expressed in 
1674 \series bold
1675 samples
1676 \series default
1677 , not bytes) with:
1678 \end_layout
1679
1680 \begin_layout LyX-Code
1681 speex_decoder_ctl(dec_state, SPEEX_GET_FRAME_SIZE, &frame_size); 
1682 \end_layout
1683
1684 \begin_layout Standard
1685 There is also a parameter that can be set for the decoder: whether or not
1686  to use a perceptual enhancer.
1687  This can be set by: 
1688 \end_layout
1689
1690 \begin_layout LyX-Code
1691 speex_decoder_ctl(dec_state, SPEEX_SET_ENH, &enh); 
1692 \end_layout
1693
1694 \begin_layout Standard
1695 where 
1696 \emph on
1697 enh
1698 \emph default
1699  is an int with value 0 to have the enhancer disabled and 1 to have it enabled.
1700  As of 1.2-beta1, the default is now to enable the enhancer.
1701 \end_layout
1702
1703 \begin_layout Standard
1704 Again, once the decoder initialization is done, for every input frame:
1705 \end_layout
1706
1707 \begin_layout LyX-Code
1708 speex_bits_read_from(&bits, input_bytes, nbBytes);
1709 \end_layout
1710
1711 \begin_layout LyX-Code
1712 speex_decode_int(dec_state, &bits, output_frame);
1713 \end_layout
1714
1715 \begin_layout Standard
1716 where input_bytes is a 
1717 \emph on
1718 (char *)
1719 \emph default
1720  containing the bit-stream data received for a frame, 
1721 \emph on
1722 nbBytes
1723 \emph default
1724  is the size (in bytes) of that bit-stream, and 
1725 \emph on
1726 output_frame
1727 \emph default
1728  is a 
1729 \emph on
1730 (short *)
1731 \emph default
1732  and points to the area where the decoded speech frame will be written.
1733  A NULL value as the second argument indicates that we don't have the bits
1734  for the current frame.
1735  When a frame is lost, the Speex decoder will do its best to "guess" the
1736  correct signal.
1737 \end_layout
1738
1739 \begin_layout Standard
1740 As for the encoder, the 
1741 \emph on
1742 speex_decode()
1743 \emph default
1744  function can still be used, with a 
1745 \emph on
1746 (float *)
1747 \emph default
1748  as the output for the audio.
1749 \end_layout
1750
1751 \begin_layout Standard
1752 After you're done with the decoding, free all resources with:
1753 \end_layout
1754
1755 \begin_layout LyX-Code
1756 speex_bits_destroy(&bits);
1757 \end_layout
1758
1759 \begin_layout LyX-Code
1760 speex_decoder_destroy(dec_state);
1761 \end_layout
1762
1763 \begin_layout Section
1764 Preprocessor
1765 \begin_inset LatexCommand label
1766 name "sub:Preprocessor"
1767
1768 \end_inset
1769
1770
1771 \end_layout
1772
1773 \begin_layout Standard
1774 In order to use the Speex preprocessor
1775 \begin_inset LatexCommand index
1776 name "preprocessor"
1777
1778 \end_inset
1779
1780 , you first need to:
1781 \end_layout
1782
1783 \begin_layout LyX-Code
1784 #include <speex/speex_preprocess.h>
1785 \end_layout
1786
1787 \begin_layout Standard
1788 Then, a preprocessor state can be created as:
1789 \end_layout
1790
1791 \begin_layout LyX-Code
1792 SpeexPreprocessState *preprocess_state = speex_preprocess_state_init(frame_size,
1793  sampling_rate);
1794 \end_layout
1795
1796 \begin_layout Standard
1797 It is recommended to use the same value for 
1798 \family typewriter
1799 frame_size
1800 \family default
1801  as is used by the encoder (20 
1802 \emph on
1803 ms
1804 \emph default
1805 ).
1806 \end_layout
1807
1808 \begin_layout Standard
1809 For each input frame, you need to call:
1810 \end_layout
1811
1812 \begin_layout LyX-Code
1813 speex_preprocess_run(preprocess_state, audio_frame);
1814 \end_layout
1815
1816 \begin_layout Standard
1817 where 
1818 \family typewriter
1819 audio_frame
1820 \family default
1821  is used both as input and output.
1822 \end_layout
1823
1824 \begin_layout Standard
1825 In cases where the output audio is not useful for a certain frame, it is
1826  possible to use instead:
1827 \end_layout
1828
1829 \begin_layout LyX-Code
1830 speex_preprocess_estimate_update(preprocess_state, audio_frame);
1831 \end_layout
1832
1833 \begin_layout Standard
1834 This call will update all the preprocessor internal state variables without
1835  computing the output audio, thus saving some CPU cycles.
1836 \end_layout
1837
1838 \begin_layout Standard
1839 The behaviour of the preprocessor can be changed using:
1840 \end_layout
1841
1842 \begin_layout LyX-Code
1843 speex_preprocess_ctl(preprocess_state, request, ptr);
1844 \end_layout
1845
1846 \begin_layout Standard
1847 which is used in the same way as the encoder and decoder equivalent.
1848  Options are listed in Section .
1849 \end_layout
1850
1851 \begin_layout Standard
1852 The preprocessor state can be destroyed using:
1853 \end_layout
1854
1855 \begin_layout LyX-Code
1856 speex_preprocess_state_destroy(preprocess_state);
1857 \end_layout
1858
1859 \begin_layout Section
1860 Echo Cancellation
1861 \begin_inset LatexCommand label
1862 name "sub:Echo-Cancellation"
1863
1864 \end_inset
1865
1866
1867 \end_layout
1868
1869 \begin_layout Standard
1870 The Speex library now includes an echo cancellation
1871 \begin_inset LatexCommand index
1872 name "echo cancellation"
1873
1874 \end_inset
1875
1876  algorithm suitable for Acoustic Echo Cancellation
1877 \begin_inset LatexCommand index
1878 name "acoustic echo cancellation"
1879
1880 \end_inset
1881
1882  (AEC).
1883  In order to use the echo canceller, you first need to
1884 \end_layout
1885
1886 \begin_layout LyX-Code
1887 #include <speex/speex_echo.h>
1888 \end_layout
1889
1890 \begin_layout Standard
1891 Then, an echo canceller state can be created by:
1892 \end_layout
1893
1894 \begin_layout LyX-Code
1895 SpeexEchoState *echo_state = speex_echo_state_init(frame_size, filter_length);
1896 \end_layout
1897
1898 \begin_layout Standard
1899 where 
1900 \family typewriter
1901 frame_size
1902 \family default
1903  is the amount of data (in samples) you want to process at once and 
1904 \family typewriter
1905 filter_length
1906 \family default
1907  is the length (in samples) of the echo cancelling filter you want to use
1908  (also known as 
1909 \shape italic
1910 tail length
1911 \shape default
1912
1913 \begin_inset LatexCommand index
1914 name "tail length"
1915
1916 \end_inset
1917
1918 ).
1919  It is recommended to use a frame size in the order of 20 ms (or equal to
1920  the codec frame size) and make sure it is easy to perform an FFT of that
1921  size (powers of two are better than prime sizes).
1922  The recommended tail length is approximately the third of the room reverberatio
1923 n time.
1924  For example, in a small room, reverberation time is in the order of 300
1925  ms, so a tail length of 100 ms is a good choice (800 samples at 8000 Hz
1926  sampling rate).
1927 \end_layout
1928
1929 \begin_layout Standard
1930 Once the echo canceller state is created, audio can be processed by:
1931 \end_layout
1932
1933 \begin_layout LyX-Code
1934 speex_echo_cancellation(echo_state, input_frame, echo_frame, output_frame);
1935 \end_layout
1936
1937 \begin_layout Standard
1938 where 
1939 \family typewriter
1940 input_frame
1941 \family default
1942  is the audio as captured by the microphone, 
1943 \family typewriter
1944 echo_frame
1945 \family default
1946  is the signal that was played in the speaker (and needs to be removed)
1947  and 
1948 \family typewriter
1949 output_frame
1950 \family default
1951  is the signal with echo removed.
1952  
1953 \end_layout
1954
1955 \begin_layout Standard
1956 One important thing to keep in mind is the relationship between 
1957 \family typewriter
1958 input_frame
1959 \family default
1960  and 
1961 \family typewriter
1962 echo_frame
1963 \family default
1964 .
1965  It is important that, at any time, any echo that is present in the input
1966  has already been sent to the echo canceller as 
1967 \family typewriter
1968 echo_frame
1969 \family default
1970 .
1971  In other words, the echo canceller cannot remove a signal that it hasn't
1972  yet received.
1973  On the other hand, the delay between the input signal and the echo signal
1974  must be small enough because otherwise part of the echo cancellation filter
1975  is inefficient.
1976  In the ideal case, you code would look like:
1977 \end_layout
1978
1979 \begin_layout LyX-Code
1980 write_to_soundcard(echo_frame, frame_size);
1981 \end_layout
1982
1983 \begin_layout LyX-Code
1984 read_from_soundcard(input_frame, frame_size);
1985 \end_layout
1986
1987 \begin_layout LyX-Code
1988 speex_echo_cancellation(echo_state, input_frame, echo_frame, output_frame);
1989 \end_layout
1990
1991 \begin_layout Standard
1992 If you wish to further reduce the echo present in the signal, you can do
1993  so by 
1994 \family typewriter
1995 associating the echo canceller to the preprocessor
1996 \family default
1997  (see Section 
1998 \begin_inset LatexCommand ref
1999 reference "sub:Preprocessor"
2000
2001 \end_inset
2002
2003 ).
2004  This is done by calling:
2005 \end_layout
2006
2007 \begin_layout LyX-Code
2008 speex_preprocess_ctl(preprocess_state, SPEEX_PREPROCESS_SET_ECHO_STATE,
2009  echo_state);
2010 \end_layout
2011
2012 \begin_layout Standard
2013 in the initialisation.
2014 \end_layout
2015
2016 \begin_layout Standard
2017 As of version 1.2-beta2, there is an alternative, simpler API that can be
2018  used instead of 
2019 \emph on
2020 speex_echo_cancellation()
2021 \emph default
2022 .
2023  When audio capture and playback are handled asynchronously (e.g.
2024  in different threads or using the 
2025 \emph on
2026 poll()
2027 \emph default
2028  or 
2029 \emph on
2030 select()
2031 \emph default
2032  system call), it can be difficult to keep track of what input_frame comes
2033  with what echo_frame.
2034  Instead, the playback comtext/thread can simply call:
2035 \end_layout
2036
2037 \begin_layout LyX-Code
2038 speex_echo_playback(echo_state, echo_frame);
2039 \end_layout
2040
2041 \begin_layout Standard
2042 every time an audio frame is played.
2043  Then, the capture context/thread calls:
2044 \end_layout
2045
2046 \begin_layout LyX-Code
2047 speex_echo_capture(echo_state, input_frame, output_frame);
2048 \end_layout
2049
2050 \begin_layout Standard
2051 for every frame captured.
2052  Internally, 
2053 \emph on
2054 speex_echo_playback()
2055 \emph default
2056  simply buffers the playback frame so it can be used by 
2057 \emph on
2058 speex_echo_capture()
2059 \emph default
2060  to call 
2061 \emph on
2062 speex_echo_cancel()
2063 \emph default
2064 .
2065  A side effect of using this alternate API is that the playback audio is
2066  delayed by two frames, which is the normal delay caused by the soundcard.
2067  When capture and playback are already synchronised, 
2068 \emph on
2069 speex_echo_cancellation()
2070 \emph default
2071  is preferable since it gives better control on the exact input/echo timing.
2072 \end_layout
2073
2074 \begin_layout Standard
2075 The echo cancellation state can be destroyed with:
2076 \end_layout
2077
2078 \begin_layout LyX-Code
2079 speex_echo_state_destroy(echo_state);
2080 \end_layout
2081
2082 \begin_layout Standard
2083 It is also possible to reset the state of the echo canceller so it can be
2084  reused without the need to create another state with:
2085 \end_layout
2086
2087 \begin_layout LyX-Code
2088 speex_echo_state_reset(echo_state);
2089 \end_layout
2090
2091 \begin_layout Subsection
2092 Troubleshooting
2093 \end_layout
2094
2095 \begin_layout Standard
2096 There are several things that may prevent the echo canceller from working
2097  properly.
2098  One of them is a bug (or something suboptimal) in the code, but there are
2099  many others you should consider first
2100 \end_layout
2101
2102 \begin_layout Itemize
2103 Using a different soundcard to do the capture and plaback will *not* work,
2104  regardless of what you may think.
2105  The only exception to that is if the two cards can be made to have their
2106  sampling clock 
2107 \begin_inset Quotes eld
2108 \end_inset
2109
2110 locked
2111 \begin_inset Quotes erd
2112 \end_inset
2113
2114  on the same clock source.
2115 \end_layout
2116
2117 \begin_layout Itemize
2118 The delay between the record and playback signals must be minimal.
2119  Any signal played has to 
2120 \begin_inset Quotes eld
2121 \end_inset
2122
2123 appear
2124 \begin_inset Quotes erd
2125 \end_inset
2126
2127  on the playback (far end) signal slightly before the echo canceller 
2128 \begin_inset Quotes eld
2129 \end_inset
2130
2131 sees
2132 \begin_inset Quotes erd
2133 \end_inset
2134
2135  it in the near end signal, but excessive delay means that part of the filter
2136  length is wasted.
2137  In the worst situations, the delay is such that it is longer than the filter
2138  length, in which case, no echo can be cancelled.
2139 \end_layout
2140
2141 \begin_layout Itemize
2142 When it comes to echo tail length (filter length), longer is *not* better.
2143  Actually, the longer the tail length, the longer it takes for the filter
2144  to adapt.
2145  Of course, a tail length that is too short will not cancel enough echo,
2146  but the most common problem seen is that people set a very long tail length
2147  and then wonder why no echo is being cancelled.
2148 \end_layout
2149
2150 \begin_layout Itemize
2151 Non-linear distortion cannot (by definition) be modeled by the linear adaptive
2152  filter used in the echo canceller and thus cannot be cancelled.
2153  Use good audio gear and avoid saturation/clipping.
2154 \end_layout
2155
2156 \begin_layout Standard
2157 Also useful is reading 
2158 \emph on
2159 Echo Cancellation Demystified
2160 \emph default
2161  by Alexey Frunze
2162 \begin_inset Foot
2163 status collapsed
2164
2165 \begin_layout Standard
2166 http://www.embeddedstar.com/articles/2003/7/article20030720-1.html
2167 \end_layout
2168
2169 \end_inset
2170
2171 , which explains the fundamental principles of echo cancellation.
2172  The details of the algorithm described in the article are different, but
2173  the general ideas of echo cancellation through adaptive filters are the
2174  same.
2175 \end_layout
2176
2177 \begin_layout Standard
2178 As of version 1.2beta2, a new 
2179 \family typewriter
2180 echo_diagnostic.m
2181 \family default
2182  tool is included in the source distribution.
2183  The first step is to define DUMP_ECHO_CANCEL_DATA during the build.
2184  This causes the echo canceller to automatically save the near-end, far-end
2185  and output signals to files (aec_rec.sw aec_play.sw and aec_out.sw).
2186  These are exactly what the AEC receives and outputs.
2187  From there, it is necessary to start Octave and type:
2188 \end_layout
2189
2190 \begin_layout LyX-Code
2191 echo_diagnostic('aec_rec.sw', 'aec_play.sw', 'aec_diagnostic.sw', 1024);
2192 \end_layout
2193
2194 \begin_layout Standard
2195 The value of 1024 is the filter length and can be changed.
2196  There will be some (hopefully) useful messages printed and echo cancelled
2197  audio will be saved to aec_diagnostic.sw .
2198  If even that output is bad (almost no cancellation) then there is  probably
2199  problem with the playback or recording process.
2200 \end_layout
2201
2202 \begin_layout Section
2203 Jitter Buffer
2204 \end_layout
2205
2206 \begin_layout Standard
2207 There are two jitter buffers.
2208  Both can be enabled by including:
2209 \end_layout
2210
2211 \begin_layout LyX-Code
2212 #include <speex/speex_jitter.c>
2213 \end_layout
2214
2215 \begin_layout Subsection
2216 Generic Jitter Buffer
2217 \end_layout
2218
2219 \begin_layout Subsection
2220 Speex Jitter Buffer
2221 \end_layout
2222
2223 \begin_layout Section
2224 Resampler
2225 \end_layout
2226
2227 \begin_layout Standard
2228 As of version 1.2beta2, Speex includes a resampling modules.
2229  To make use of the resampler, it is necessary to include its header file:
2230 \end_layout
2231
2232 \begin_layout LyX-Code
2233 #include <speex/speex_resampler.h>
2234 \end_layout
2235
2236 \begin_layout Standard
2237 For each stream that is to be resampled, it is necessary to create a resampler
2238  state with:
2239 \end_layout
2240
2241 \begin_layout LyX-Code
2242 SpeexResamplerState *resampler;
2243 \end_layout
2244
2245 \begin_layout LyX-Code
2246 resampler = speex_resampler_init(nb_channels, input_rate, output_rate, quality,
2247  &err);
2248 \end_layout
2249
2250 \begin_layout Standard
2251 where nb_channels is the number of channels that will be used (either interleave
2252 d or non-interleaved), input_rate is the sampling rate of the input stream,
2253  output_rate is the sampling rate of the output stream and quality is the
2254  requested quality setting (0 to 10).
2255  The quality parameter is useful for controlling the quality/complexity/latency
2256  tradeoff.
2257  Using a higher quality setting means less noise/aliasing, a higher complexity
2258  and a higher latency.
2259  Usually, a quality of 3 is acceptable for most desktop uses and quality
2260  10 is mostly recommended for pro audio work.
2261  Quality 0 usually has a decent sound (certainly better than using linear
2262  interpolation resampling), but artifacts may be heard.
2263 \end_layout
2264
2265 \begin_layout Standard
2266 The actual resampling is performed using
2267 \end_layout
2268
2269 \begin_layout LyX-Code
2270 err = speex_resampler_process_int(resampler, channelID, in, &in_length,
2271  out, &out_length);
2272 \end_layout
2273
2274 \begin_layout Standard
2275 where channelID is the ID of the channel to be processed.
2276  For a mono stream, use 0.
2277  The 
2278 \emph on
2279 in
2280 \emph default
2281  pointer points to the first sample of the input buffer for the selected
2282  channel and 
2283 \emph on
2284 out
2285 \emph default
2286  points to the first sample of the output.
2287  The size of the input and output buffers are specified by 
2288 \emph on
2289 in_length
2290 \emph default
2291  and 
2292 \emph on
2293 out_length
2294 \emph default
2295  respectively.
2296  Upon completion, these values are replaced by the number of samples read
2297  and written by the resampler.
2298  Unless an error occurs, either all input samples will be read or all output
2299  samples will be written to (or both).
2300  For floating-point samples, the function speex_resampler_process_float()
2301  behaves similarly.
2302 \end_layout
2303
2304 \begin_layout Standard
2305 It is also possible to process multiple channels at once.
2306  
2307 \end_layout
2308
2309 \begin_layout Section
2310 Codec Options (speex_*_ctl)
2311 \begin_inset LatexCommand label
2312 name "sub:Codec-Options"
2313
2314 \end_inset
2315
2316
2317 \end_layout
2318
2319 \begin_layout Quote
2320 \align center
2321
2322 \emph on
2323 Entities should not be multiplied beyond necessity -- William of Ockham.
2324 \end_layout
2325
2326 \begin_layout Quote
2327 \align center
2328
2329 \emph on
2330 Just because there's an option doesn't mean you have to use it -- me.
2331 \end_layout
2332
2333 \begin_layout Standard
2334 The Speex encoder and decoder support many options and requests that can
2335  be accessed through the 
2336 \emph on
2337 speex_encoder_ctl
2338 \emph default
2339  and 
2340 \emph on
2341 speex_decoder_ctl
2342 \emph default
2343  functions.
2344  Despite that, the defaults are good for many applications and 
2345 \series bold
2346 optional settings should only be used when one understands them and knows
2347  that they are needed
2348 \series default
2349 .
2350  A common error is to attempt to set many unnecessary settings.
2351  These functions are similar to the 
2352 \emph on
2353 ioctl
2354 \emph default
2355  system call and their prototypes are:
2356 \end_layout
2357
2358 \begin_layout LyX-Code
2359 void speex_encoder_ctl(void *encoder, int request, void *ptr);
2360 \end_layout
2361
2362 \begin_layout LyX-Code
2363 void speex_decoder_ctl(void *encoder, int request, void *ptr);
2364 \end_layout
2365
2366 \begin_layout Standard
2367 The different values of request allowed are (note that some only apply to
2368  the encoder or the decoder):
2369 \end_layout
2370
2371 \begin_layout Description
2372 SPEEX_SET_ENH** Set perceptual enhancer
2373 \begin_inset LatexCommand index
2374 name "perceptual enhancement"
2375
2376 \end_inset
2377
2378  to on (1) or off (0) (spx_int32_t)
2379 \end_layout
2380
2381 \begin_layout Description
2382 SPEEX_GET_ENH** Get perceptual enhancer status (spx_int32_t)
2383 \end_layout
2384
2385 \begin_layout Description
2386 SPEEX_GET_FRAME_SIZE Get the number of samples per frame for the current
2387  mode (spx_int32_t)
2388 \end_layout
2389
2390 \begin_layout Description
2391 SPEEX_SET_QUALITY* Set the encoder speech quality (spx_int32_t 0 to 10)
2392 \end_layout
2393
2394 \begin_layout Description
2395 SPEEX_GET_QUALITY* Get the current encoder speech quality (spx_int32_t 0
2396  to 10)
2397 \end_layout
2398
2399 \begin_layout Description
2400 SPEEX_SET_MODE* Set the mode number, as specified in the RTP spec (spx_int32_t)
2401 \end_layout
2402
2403 \begin_layout Description
2404 SPEEX_GET_MODE* Get the current mode number, as specified in the RTP spec
2405  (spx_int32_t)
2406 \end_layout
2407
2408 \begin_layout Description
2409 SPEEX_SET_LOW_MODE*
2410 \begin_inset Formula $\dagger$
2411 \end_inset
2412
2413  Use the source, Luke!
2414 \end_layout
2415
2416 \begin_layout Description
2417 SPEEX_GET_LOW_MODE*
2418 \begin_inset Formula $\dagger$
2419 \end_inset
2420
2421  Use the source, Luke!
2422 \end_layout
2423
2424 \begin_layout Description
2425 SPEEX_SET_HIGH_MODE*
2426 \begin_inset Formula $\dagger$
2427 \end_inset
2428
2429  Use the source, Luke!
2430 \end_layout
2431
2432 \begin_layout Description
2433 SPEEX_GET_HIGH_MODE*
2434 \begin_inset Formula $\dagger$
2435 \end_inset
2436
2437  Use the source, Luke!
2438 \end_layout
2439
2440 \begin_layout Description
2441 SPEEX_SET_VBR* Set variable bit-rate (VBR) to on (1) or off (0) (spx_int32_t)
2442 \end_layout
2443
2444 \begin_layout Description
2445 SPEEX_GET_VBR* Get variable bit-rate
2446 \begin_inset LatexCommand index
2447 name "variable bit-rate"
2448
2449 \end_inset
2450
2451  (VBR) status (spx_int32_t)
2452 \end_layout
2453
2454 \begin_layout Description
2455 SPEEX_SET_VBR_QUALITY* Set the encoder VBR speech quality (float 0 to 10)
2456 \end_layout
2457
2458 \begin_layout Description
2459 SPEEX_GET_VBR_QUALITY* Get the current encoder VBR speech quality (float
2460  0 to 10)
2461 \end_layout
2462
2463 \begin_layout Description
2464 SPEEX_SET_COMPLEXITY* Set the CPU resources allowed for the encoder (spx_int32_t
2465  1 to 10)
2466 \end_layout
2467
2468 \begin_layout Description
2469 SPEEX_GET_COMPLEXITY* Get the CPU resources allowed for the encoder (spx_int32_t
2470  1 to 10)
2471 \end_layout
2472
2473 \begin_layout Description
2474 SPEEX_SET_BITRATE* Set the bit-rate to use to the closest value not exceeding
2475  the parameter (spx_int32_t in bps)
2476 \end_layout
2477
2478 \begin_layout Description
2479 SPEEX_GET_BITRATE Get the current bit-rate in use (spx_int32_t in bps)
2480 \end_layout
2481
2482 \begin_layout Description
2483 SPEEX_SET_SAMPLING_RATE Set real sampling rate (spx_int32_t in Hz)
2484 \end_layout
2485
2486 \begin_layout Description
2487 SPEEX_GET_SAMPLING_RATE Get real sampling rate (spx_int32_t in Hz)
2488 \end_layout
2489
2490 \begin_layout Description
2491 SPEEX_RESET_STATE Reset the encoder/decoder state to its original state,
2492  clearing all memories (no argument)
2493 \end_layout
2494
2495 \begin_layout Description
2496 SPEEX_SET_VAD* Set voice activity detection
2497 \begin_inset LatexCommand index
2498 name "voice activity detection"
2499
2500 \end_inset
2501
2502  (VAD) to on (1) or off (0) (spx_int32_t)
2503 \end_layout
2504
2505 \begin_layout Description
2506 SPEEX_GET_VAD* Get voice activity detection (VAD) status (spx_int32_t)
2507 \end_layout
2508
2509 \begin_layout Description
2510 SPEEX_SET_DTX* Set discontinuous transmission
2511 \begin_inset LatexCommand index
2512 name "discontinuous transmission"
2513
2514 \end_inset
2515
2516  (DTX) to on (1) or off (0) (spx_int32_t)
2517 \end_layout
2518
2519 \begin_layout Description
2520 SPEEX_GET_DTX* Get discontinuous transmission (DTX) status (spx_int32_t)
2521 \end_layout
2522
2523 \begin_layout Description
2524 SPEEX_SET_ABR* Set average bit-rate
2525 \begin_inset LatexCommand index
2526 name "average bit-rate"
2527
2528 \end_inset
2529
2530  (ABR) to a value n in bits per second (spx_int32_t in bps)
2531 \end_layout
2532
2533 \begin_layout Description
2534 SPEEX_GET_ABR* Get average bit-rate (ABR) setting (spx_int32_t in bps)
2535 \end_layout
2536
2537 \begin_layout Description
2538 SPEEX_SET_PLC_TUNING* Tell the encoder to optimize encoding for a certain
2539  percentage of packet loss (spx_int32_t in percent)
2540 \end_layout
2541
2542 \begin_layout Description
2543 SPEEX_GET_PLC_TUNING* Get the current tuning of the encoder for PLC (spx_int32_t
2544  in percent)
2545 \end_layout
2546
2547 \begin_layout Description
2548 SPEEX_SET_VBR_MAX_BITRATE* Set the maximum bit-rate allowed in VBR operation
2549  (spx_int32_t in bps)
2550 \end_layout
2551
2552 \begin_layout Description
2553 SPEEX_GET_VBR_MAX_BITRATE* Get the current maximum bit-rate allowed in VBR
2554  operation (spx_int32_t in bps)
2555 \end_layout
2556
2557 \begin_layout Description
2558 SPEEX_SET_HIGHPASS Set the high-pass filter on (1) or off (0) (spx_int32_t)
2559 \end_layout
2560
2561 \begin_layout Description
2562 SPEEX_TET_HIGHPASS Get the current high-pass filter status (spx_int32_t)
2563 \end_layout
2564
2565 \begin_layout Description
2566 * applies only to the encoder
2567 \end_layout
2568
2569 \begin_layout Description
2570 ** applies only to the decoder
2571 \end_layout
2572
2573 \begin_layout Description
2574 \begin_inset Formula $\dagger$
2575 \end_inset
2576
2577  normally only used internally
2578 \end_layout
2579
2580 \begin_layout Section
2581 Mode queries
2582 \begin_inset LatexCommand label
2583 name "sub:Mode-queries"
2584
2585 \end_inset
2586
2587
2588 \end_layout
2589
2590 \begin_layout Standard
2591 Speex modes have a query system similar to the speex_encoder_ctl and speex_decod
2592 er_ctl calls.
2593  Since modes are read-only, it is only possible to get information about
2594  a particular mode.
2595  The function used to do that is:
2596 \end_layout
2597
2598 \begin_layout LyX-Code
2599 void speex_mode_query(SpeexMode *mode, int request, void *ptr);
2600 \end_layout
2601
2602 \begin_layout Standard
2603 The admissible values for request are (unless otherwise note, the values
2604  are returned through 
2605 \emph on
2606 ptr
2607 \emph default
2608 ):
2609 \end_layout
2610
2611 \begin_layout Description
2612 SPEEX_MODE_FRAME_SIZE Get the frame size (in samples) for the mode
2613 \end_layout
2614
2615 \begin_layout Description
2616 SPEEX_SUBMODE_BITRATE Get the bit-rate for a submode number specified through
2617  
2618 \emph on
2619 ptr
2620 \emph default
2621  (integer in bps).
2622  
2623 \end_layout
2624
2625 \begin_layout Section
2626 Preprocessor options
2627 \begin_inset LatexCommand label
2628 name "sub:Preprocessor-options"
2629
2630 \end_inset
2631
2632
2633 \end_layout
2634
2635 \begin_layout Description
2636 SPEEX_PREPROCESS_SET_DENOISE Turns denoising on(1) or off(2) (integer)
2637 \end_layout
2638
2639 \begin_layout Description
2640 SPEEX_PREPROCESS_GET_DENOISE Get denoising status (integer)
2641 \end_layout
2642
2643 \begin_layout Description
2644 SPEEX_PREPROCESS_SET_AGC Turns automatic gain control (AGC) on(1) or off(2)
2645  (integer)
2646 \end_layout
2647
2648 \begin_layout Description
2649 SPEEX_PREPROCESS_GET_AGC Get AGC status (integer)
2650 \end_layout
2651
2652 \begin_layout Description
2653 SPEEX_PREPROCESS_SET_VAD Turns voice activity detector (VAD) on(1) or off(2)
2654  (integer)
2655 \end_layout
2656
2657 \begin_layout Description
2658 SPEEX_PREPROCESS_GET_VAD Get VAD status (integer)
2659 \end_layout
2660
2661 \begin_layout Description
2662 SPEEX_PREPROCESS_SET_AGC_LEVEL
2663 \end_layout
2664
2665 \begin_layout Description
2666 SPEEX_PREPROCESS_GET_AGC_LEVEL
2667 \end_layout
2668
2669 \begin_layout Description
2670 SPEEX_PREPROCESS_SET_DEREVERB Turns reverberation removal on(1) or off(2)
2671  (integer)
2672 \end_layout
2673
2674 \begin_layout Description
2675 SPEEX_PREPROCESS_GET_DEREVERB Get reverberation removal status (integer)
2676 \end_layout
2677
2678 \begin_layout Description
2679 SPEEX_PREPROCESS_SET_DEREVERB_LEVEL
2680 \end_layout
2681
2682 \begin_layout Description
2683 SPEEX_PREPROCESS_GET_DEREVERB_LEVEL
2684 \end_layout
2685
2686 \begin_layout Description
2687 SPEEX_PREPROCESS_SET_DEREVERB_DECAY
2688 \end_layout
2689
2690 \begin_layout Description
2691 SPEEX_PREPROCESS_GET_DEREVERB_DECAY
2692 \end_layout
2693
2694 \begin_layout Description
2695 SPEEX_PREPROCESS_SET_PROB_START
2696 \end_layout
2697
2698 \begin_layout Description
2699 SPEEX_PREPROCESS_GET_PROB_START
2700 \end_layout
2701
2702 \begin_layout Description
2703 SPEEX_PREPROCESS_SET_PROB_CONTINUE
2704 \end_layout
2705
2706 \begin_layout Description
2707 SPEEX_PREPROCESS_GET_PROB_CONTINUE
2708 \end_layout
2709
2710 \begin_layout Description
2711 SPEEX_PREPROCESS_SET_NOISE_SUPPRESS Set maximum attenuation of the noise
2712  in dB (negative number)
2713 \end_layout
2714
2715 \begin_layout Description
2716 SPEEX_PREPROCESS_GET_NOISE_SUPPRESS Get maximum attenuation of the noise
2717  in dB (negative number)
2718 \end_layout
2719
2720 \begin_layout Description
2721 SPEEX_PREPROCESS_SET_ECHO_SUPPRESS Set maximum attenuation of the residual
2722  echo in dB (negative number)
2723 \end_layout
2724
2725 \begin_layout Description
2726 SPEEX_PREPROCESS_GET_ECHO_SUPPRESS Set maximum attenuation of the residual
2727  echo in dB (negative number)
2728 \end_layout
2729
2730 \begin_layout Description
2731 SPEEX_PREPROCESS_SET_ECHO_SUPPRESS_ACTIVE Set maximum attenuation of the
2732  echo in dB when near end is active (negative number)
2733 \end_layout
2734
2735 \begin_layout Description
2736 SPEEX_PREPROCESS_GET_ECHO_SUPPRESS_ACTIVE Set maximum attenuation of the
2737  echo in dB when near end is active (negative number)
2738 \end_layout
2739
2740 \begin_layout Description
2741 SPEEX_PREPROCESS_SET_ECHO_STATE Set the associated echo canceller for residual
2742  echo suppression (NULL for no residual echo suppression)
2743 \end_layout
2744
2745 \begin_layout Description
2746 SPEEX_PREPROCESS_GET_ECHO_STATE Get the associated echo canceller
2747 \end_layout
2748
2749 \begin_layout Section
2750 Packing and in-band signalling
2751 \begin_inset LatexCommand index
2752 name "in-band signalling"
2753
2754 \end_inset
2755
2756
2757 \end_layout
2758
2759 \begin_layout Standard
2760 Sometimes it is desirable to pack more than one frame per packet (or other
2761  basic unit of storage).
2762  The proper way to do it is to call speex_encode 
2763 \begin_inset Formula $N$
2764 \end_inset
2765
2766  times before writing the stream with speex_bits_write.
2767  In cases where the number of frames is not determined by an out-of-band
2768  mechanism, it is possible to include a terminator code.
2769  That terminator consists of the code 15 (decimal) encoded with 5 bits,
2770  as shown in Table 
2771 \begin_inset LatexCommand ref
2772 reference "cap:quality_vs_bps"
2773
2774 \end_inset
2775
2776 .
2777  Note that as of version 1.0.2, calling speex_bits_write automatically inserts
2778  the terminator so as to fill the last byte.
2779  This doesn't involves any overhead and makes sure Speex can always detect
2780  when there is no more frame in a packet.
2781 \end_layout
2782
2783 \begin_layout Standard
2784 It is also possible to send in-band 
2785 \begin_inset Quotes eld
2786 \end_inset
2787
2788 messages
2789 \begin_inset Quotes erd
2790 \end_inset
2791
2792  to the other side.
2793  All these messages are encoded as 
2794 \begin_inset Quotes eld
2795 \end_inset
2796
2797 pseudo-frames
2798 \begin_inset Quotes erd
2799 \end_inset
2800
2801  of mode 14 which contain a 4-bit message type code, followed by the message.
2802  Table 
2803 \begin_inset LatexCommand ref
2804 reference "cap:In-band-signalling-codes"
2805
2806 \end_inset
2807
2808  lists the available codes, their meaning and the size of the message that
2809  follows.
2810  Most of these messages are requests that are sent to the encoder or decoder
2811  on the other end, which is free to comply or ignore them.
2812  By default, all in-band messages are ignored.
2813 \end_layout
2814
2815 \begin_layout Standard
2816 \begin_inset Float table
2817 placement htbp
2818 wide false
2819 sideways false
2820 status open
2821
2822 \begin_layout Standard
2823 \begin_inset ERT
2824 status collapsed
2825
2826 \begin_layout Standard
2827
2828
2829 \backslash
2830 begin{center}
2831 \end_layout
2832
2833 \end_inset
2834
2835
2836 \begin_inset Tabular
2837 <lyxtabular version="3" rows="17" columns="3">
2838 <features>
2839 <column alignment="center" valignment="top" leftline="true" width="0pt">
2840 <column alignment="center" valignment="top" leftline="true" width="0pt">
2841 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
2842 <row topline="true" bottomline="true">
2843 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2844 \begin_inset Text
2845
2846 \begin_layout Standard
2847 Code
2848 \end_layout
2849
2850 \end_inset
2851 </cell>
2852 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2853 \begin_inset Text
2854
2855 \begin_layout Standard
2856 Size (bits)
2857 \end_layout
2858
2859 \end_inset
2860 </cell>
2861 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2862 \begin_inset Text
2863
2864 \begin_layout Standard
2865 Content
2866 \end_layout
2867
2868 \end_inset
2869 </cell>
2870 </row>
2871 <row topline="true">
2872 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2873 \begin_inset Text
2874
2875 \begin_layout Standard
2876 0
2877 \end_layout
2878
2879 \end_inset
2880 </cell>
2881 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2882 \begin_inset Text
2883
2884 \begin_layout Standard
2885 1
2886 \end_layout
2887
2888 \end_inset
2889 </cell>
2890 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2891 \begin_inset Text
2892
2893 \begin_layout Standard
2894 Asks decoder to set perceptual enhancement off (0) or on(1)
2895 \end_layout
2896
2897 \end_inset
2898 </cell>
2899 </row>
2900 <row topline="true">
2901 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2902 \begin_inset Text
2903
2904 \begin_layout Standard
2905 1
2906 \end_layout
2907
2908 \end_inset
2909 </cell>
2910 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2911 \begin_inset Text
2912
2913 \begin_layout Standard
2914 1
2915 \end_layout
2916
2917 \end_inset
2918 </cell>
2919 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2920 \begin_inset Text
2921
2922 \begin_layout Standard
2923 Asks (if 1) the encoder to be less 
2924 \begin_inset Quotes eld
2925 \end_inset
2926
2927 agressive
2928 \begin_inset Quotes erd
2929 \end_inset
2930
2931  due to high packet loss
2932 \end_layout
2933
2934 \end_inset
2935 </cell>
2936 </row>
2937 <row topline="true">
2938 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2939 \begin_inset Text
2940
2941 \begin_layout Standard
2942 2
2943 \end_layout
2944
2945 \end_inset
2946 </cell>
2947 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2948 \begin_inset Text
2949
2950 \begin_layout Standard
2951 4
2952 \end_layout
2953
2954 \end_inset
2955 </cell>
2956 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2957 \begin_inset Text
2958
2959 \begin_layout Standard
2960 Asks encoder to switch to mode N
2961 \end_layout
2962
2963 \end_inset
2964 </cell>
2965 </row>
2966 <row topline="true">
2967 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2968 \begin_inset Text
2969
2970 \begin_layout Standard
2971 3
2972 \end_layout
2973
2974 \end_inset
2975 </cell>
2976 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2977 \begin_inset Text
2978
2979 \begin_layout Standard
2980 4
2981 \end_layout
2982
2983 \end_inset
2984 </cell>
2985 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2986 \begin_inset Text
2987
2988 \begin_layout Standard
2989 Asks encoder to switch to mode N for low-band
2990 \end_layout
2991
2992 \end_inset
2993 </cell>
2994 </row>
2995 <row topline="true">
2996 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2997 \begin_inset Text
2998
2999 \begin_layout Standard
3000 4
3001 \end_layout
3002
3003 \end_inset
3004 </cell>
3005 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3006 \begin_inset Text
3007
3008 \begin_layout Standard
3009 4
3010 \end_layout
3011
3012 \end_inset
3013 </cell>
3014 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3015 \begin_inset Text
3016
3017 \begin_layout Standard
3018 Asks encoder to switch to mode N for high-band
3019 \end_layout
3020
3021 \end_inset
3022 </cell>
3023 </row>
3024 <row topline="true">
3025 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3026 \begin_inset Text
3027
3028 \begin_layout Standard
3029 5
3030 \end_layout
3031
3032 \end_inset
3033 </cell>
3034 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3035 \begin_inset Text
3036
3037 \begin_layout Standard
3038 4
3039 \end_layout
3040
3041 \end_inset
3042 </cell>
3043 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3044 \begin_inset Text
3045
3046 \begin_layout Standard
3047 Asks encoder to switch to quality N for VBR
3048 \end_layout
3049
3050 \end_inset
3051 </cell>
3052 </row>
3053 <row topline="true">
3054 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3055 \begin_inset Text
3056
3057 \begin_layout Standard
3058 6
3059 \end_layout
3060
3061 \end_inset
3062 </cell>
3063 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3064 \begin_inset Text
3065
3066 \begin_layout Standard
3067 4
3068 \end_layout
3069
3070 \end_inset
3071 </cell>
3072 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3073 \begin_inset Text
3074
3075 \begin_layout Standard
3076 Request acknowloedge (0=no, 1=all, 2=only for in-band data)
3077 \end_layout
3078
3079 \end_inset
3080 </cell>
3081 </row>
3082 <row topline="true">
3083 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3084 \begin_inset Text
3085
3086 \begin_layout Standard
3087 7
3088 \end_layout
3089
3090 \end_inset
3091 </cell>
3092 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3093 \begin_inset Text
3094
3095 \begin_layout Standard
3096 4
3097 \end_layout
3098
3099 \end_inset
3100 </cell>
3101 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3102 \begin_inset Text
3103
3104 \begin_layout Standard
3105 Asks encoder to set CBR (0), VAD(1), DTX(3), VBR(5), VBR+DTX(7)
3106 \end_layout
3107
3108 \end_inset
3109 </cell>
3110 </row>
3111 <row topline="true">
3112 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3113 \begin_inset Text
3114
3115 \begin_layout Standard
3116 8
3117 \end_layout
3118
3119 \end_inset
3120 </cell>
3121 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3122 \begin_inset Text
3123
3124 \begin_layout Standard
3125 8
3126 \end_layout
3127
3128 \end_inset
3129 </cell>
3130 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3131 \begin_inset Text
3132
3133 \begin_layout Standard
3134 Transmit (8-bit) character to the other end
3135 \end_layout
3136
3137 \end_inset
3138 </cell>
3139 </row>
3140 <row topline="true">
3141 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3142 \begin_inset Text
3143
3144 \begin_layout Standard
3145 9
3146 \end_layout
3147
3148 \end_inset
3149 </cell>
3150 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3151 \begin_inset Text
3152
3153 \begin_layout Standard
3154 8
3155 \end_layout
3156
3157 \end_inset
3158 </cell>
3159 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3160 \begin_inset Text
3161
3162 \begin_layout Standard
3163 Intensity stereo information
3164 \end_layout
3165
3166 \end_inset
3167 </cell>
3168 </row>
3169 <row topline="true">
3170 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3171 \begin_inset Text
3172
3173 \begin_layout Standard
3174 10
3175 \end_layout
3176
3177 \end_inset
3178 </cell>
3179 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3180 \begin_inset Text
3181
3182 \begin_layout Standard
3183 16
3184 \end_layout
3185
3186 \end_inset
3187 </cell>
3188 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3189 \begin_inset Text
3190
3191 \begin_layout Standard
3192 Announce maximum bit-rate acceptable (N in bytes/second)
3193 \end_layout
3194
3195 \end_inset
3196 </cell>
3197 </row>
3198 <row topline="true">
3199 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3200 \begin_inset Text
3201
3202 \begin_layout Standard
3203 11
3204 \end_layout
3205
3206 \end_inset
3207 </cell>
3208 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3209 \begin_inset Text
3210
3211 \begin_layout Standard
3212 16
3213 \end_layout
3214
3215 \end_inset
3216 </cell>
3217 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3218 \begin_inset Text
3219
3220 \begin_layout Standard
3221 reserved
3222 \end_layout
3223
3224 \end_inset
3225 </cell>
3226 </row>
3227 <row topline="true">
3228 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3229 \begin_inset Text
3230
3231 \begin_layout Standard
3232 12
3233 \end_layout
3234
3235 \end_inset
3236 </cell>
3237 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3238 \begin_inset Text
3239
3240 \begin_layout Standard
3241 32
3242 \end_layout
3243
3244 \end_inset
3245 </cell>
3246 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3247 \begin_inset Text
3248
3249 \begin_layout Standard
3250 Acknowledge receiving packet N
3251 \end_layout
3252
3253 \end_inset
3254 </cell>
3255 </row>
3256 <row topline="true">
3257 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3258 \begin_inset Text
3259
3260 \begin_layout Standard
3261 13
3262 \end_layout
3263
3264 \end_inset
3265 </cell>
3266 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3267 \begin_inset Text
3268
3269 \begin_layout Standard
3270 32
3271 \end_layout
3272
3273 \end_inset
3274 </cell>
3275 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3276 \begin_inset Text
3277
3278 \begin_layout Standard
3279 reserved
3280 \end_layout
3281
3282 \end_inset
3283 </cell>
3284 </row>
3285 <row topline="true">
3286 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3287 \begin_inset Text
3288
3289 \begin_layout Standard
3290 14
3291 \end_layout
3292
3293 \end_inset
3294 </cell>
3295 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3296 \begin_inset Text
3297
3298 \begin_layout Standard
3299 64
3300 \end_layout
3301
3302 \end_inset
3303 </cell>
3304 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3305 \begin_inset Text
3306
3307 \begin_layout Standard
3308 reserved
3309 \end_layout
3310
3311 \end_inset
3312 </cell>
3313 </row>
3314 <row topline="true" bottomline="true">
3315 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3316 \begin_inset Text
3317
3318 \begin_layout Standard
3319 15
3320 \end_layout
3321
3322 \end_inset
3323 </cell>
3324 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3325 \begin_inset Text
3326
3327 \begin_layout Standard
3328 64
3329 \end_layout
3330
3331 \end_inset
3332 </cell>
3333 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3334 \begin_inset Text
3335
3336 \begin_layout Standard
3337 reserved
3338 \end_layout
3339
3340 \end_inset
3341 </cell>
3342 </row>
3343 </lyxtabular>
3344
3345 \end_inset
3346
3347
3348 \begin_inset ERT
3349 status collapsed
3350
3351 \begin_layout Standard
3352
3353
3354 \backslash
3355 end{center}
3356 \end_layout
3357
3358 \end_inset
3359
3360
3361 \end_layout
3362
3363 \begin_layout Standard
3364 \begin_inset Caption
3365
3366 \begin_layout Standard
3367 In-band signalling codes
3368 \begin_inset LatexCommand label
3369 name "cap:In-band-signalling-codes"
3370
3371 \end_inset
3372
3373
3374 \end_layout
3375
3376 \end_inset
3377
3378
3379 \end_layout
3380
3381 \end_inset
3382
3383
3384 \end_layout
3385
3386 \begin_layout Standard
3387 Finally, applications may define custom in-band messages using mode 13.
3388  The size of the message in bytes is encoded with 5 bits, so that the decoder
3389  can skip it if it doesn't know how to interpret it.
3390 \end_layout
3391
3392 \begin_layout Standard
3393
3394 \newpage
3395
3396 \end_layout
3397
3398 \begin_layout Chapter
3399 Formats and standards
3400 \begin_inset LatexCommand index
3401 name "standards"
3402
3403 \end_inset
3404
3405
3406 \begin_inset LatexCommand label
3407 name "sec:Formats-and-standards"
3408
3409 \end_inset
3410
3411
3412 \end_layout
3413
3414 \begin_layout Standard
3415 Speex can encode speech in both narrowband and wideband and provides different
3416  bit-rates.
3417  However, not all features need to be supported by a certain implementation
3418  or device.
3419  In order to be called 
3420 \begin_inset Quotes eld
3421 \end_inset
3422
3423 Speex compatible
3424 \begin_inset Quotes erd
3425 \end_inset
3426
3427  (whatever that means), an implementation must implement at least a basic
3428  set of features.
3429 \end_layout
3430
3431 \begin_layout Standard
3432 At the minimum, all narrowband modes of operation MUST be supported at the
3433  decoder.
3434  This includes the decoding of a wideband bit-stream by the narrowband decoder
3435 \begin_inset Foot
3436 status collapsed
3437
3438 \begin_layout Standard
3439 The wideband bit-stream contains an embedded narrowband bit-stream which
3440  can be decoded alone
3441 \end_layout
3442
3443 \end_inset
3444
3445 .
3446  If present, a wideband decoder MUST be able to decode a narrowband stream,
3447  and MAY either be able to decode all wideband modes or be able to decode
3448  the embedded narrowband part of all modes (which includes ignoring the
3449  high-band bits).
3450 \end_layout
3451
3452 \begin_layout Standard
3453 For encoders, at least one narrowband or wideband mode MUST be supported.
3454  The main reason why all encoding modes do not have to be supported is that
3455  some platforms may not be able to handle the complexity of encoding in
3456  some modes.
3457 \end_layout
3458
3459 \begin_layout Section
3460 RTP
3461 \begin_inset LatexCommand index
3462 name "RTP"
3463
3464 \end_inset
3465
3466  Payload Format 
3467 \end_layout
3468
3469 \begin_layout Standard
3470 The RTP payload draft is included in appendix 
3471 \begin_inset LatexCommand ref
3472 reference "sec:IETF-draft"
3473
3474 \end_inset
3475
3476  and the latest version is available at 
3477 \begin_inset LatexCommand url
3478 target "http://www.speex.org/drafts/latest"
3479
3480 \end_inset
3481
3482 .
3483  This draft has been sent (2003/02/26) to the Internet Engineering Task
3484  Force (IETF) and will be discussed at the March 18th meeting in San Francisco.
3485  
3486 \end_layout
3487
3488 \begin_layout Section
3489 MIME Type
3490 \end_layout
3491
3492 \begin_layout Standard
3493 For now, you should use the MIME type audio/x-speex for Speex-in-Ogg.
3494  We will apply for type 
3495 \family typewriter
3496 audio/speex
3497 \family default
3498  in the near future.
3499 \end_layout
3500
3501 \begin_layout Section
3502 Ogg
3503 \begin_inset LatexCommand index
3504 name "Ogg"
3505
3506 \end_inset
3507
3508  file format
3509 \end_layout
3510
3511 \begin_layout Standard
3512 Speex bit-streams can be stored in Ogg files.
3513  In this case, the first packet of the Ogg file contains the Speex header
3514  described in table 
3515 \begin_inset LatexCommand ref
3516 reference "cap:ogg_speex_header"
3517
3518 \end_inset
3519
3520 .
3521  All integer fields in the headers are stored as little-endian.
3522  The 
3523 \family typewriter
3524 speex_string
3525 \family default
3526  field must contain the 
3527 \begin_inset Quotes eld
3528 \end_inset
3529
3530
3531 \family typewriter
3532 Speex
3533 \family default
3534 \InsetSpace ~
3535 \InsetSpace ~
3536 \InsetSpace ~
3537
3538 \begin_inset Quotes erd
3539 \end_inset
3540
3541  (with 3 trailing spaces), which identifies the bit-stream.
3542  The next field, 
3543 \family typewriter
3544 speex_version
3545 \family default
3546  contains the version of Speex that encoded the file.
3547  For now, refer to speex_header.[ch] for more info.
3548  The 
3549 \emph on
3550 beginning of stream
3551 \emph default
3552  (
3553 \family typewriter
3554 b_o_s
3555 \family default
3556 ) flag is set to 1 for the header.
3557  The header packet has 
3558 \family typewriter
3559 packetno=0
3560 \family default
3561  and 
3562 \family typewriter
3563 granulepos=0
3564 \family default
3565 .
3566 \end_layout
3567
3568 \begin_layout Standard
3569 The second packet contains the Speex comment header.
3570  The format used is the Vorbis comment format described here: http://www.xiph.org/
3571 ogg/vorbis/doc/v-comment.html .
3572  This packet has 
3573 \family typewriter
3574 packetno=1
3575 \family default
3576  and 
3577 \family typewriter
3578 granulepos=0
3579 \family default
3580 .
3581 \end_layout
3582
3583 \begin_layout Standard
3584 The third and subsequent packets each contain one or more (number found
3585  in header) Speex frames.
3586  These are identified with 
3587 \family typewriter
3588 packetno
3589 \family default
3590  starting from 2 and the 
3591 \family typewriter
3592 granulepos
3593 \family default
3594  is the number of the last sample encoded in that packet.
3595  The last of these packets has the 
3596 \emph on
3597 end of stream
3598 \emph default
3599  (
3600 \family typewriter
3601 e_o_s
3602 \family default
3603 ) flag is set to 1.
3604 \end_layout
3605
3606 \begin_layout Standard
3607 \begin_inset Float table
3608 placement htbp
3609 wide true
3610 sideways false
3611 status open
3612
3613 \begin_layout Standard
3614 \begin_inset ERT
3615 status collapsed
3616
3617 \begin_layout Standard
3618
3619
3620 \backslash
3621 begin{center}
3622 \end_layout
3623
3624 \end_inset
3625
3626
3627 \begin_inset Tabular
3628 <lyxtabular version="3" rows="16" columns="3">
3629 <features>
3630 <column alignment="center" valignment="top" leftline="true" width="0pt">
3631 <column alignment="center" valignment="top" leftline="true" width="0pt">
3632 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
3633 <row topline="true" bottomline="true">
3634 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3635 \begin_inset Text
3636
3637 \begin_layout Standard
3638 Field
3639 \end_layout
3640
3641 \end_inset
3642 </cell>
3643 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3644 \begin_inset Text
3645
3646 \begin_layout Standard
3647 Type
3648 \end_layout
3649
3650 \end_inset
3651 </cell>
3652 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3653 \begin_inset Text
3654
3655 \begin_layout Standard
3656 Size
3657 \end_layout
3658
3659 \end_inset
3660 </cell>
3661 </row>
3662 <row topline="true">
3663 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3664 \begin_inset Text
3665
3666 \begin_layout Standard
3667 speex_string
3668 \end_layout
3669
3670 \end_inset
3671 </cell>
3672 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3673 \begin_inset Text
3674
3675 \begin_layout Standard
3676 char[]
3677 \end_layout
3678
3679 \end_inset
3680 </cell>
3681 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3682 \begin_inset Text
3683
3684 \begin_layout Standard
3685 8
3686 \end_layout
3687
3688 \end_inset
3689 </cell>
3690 </row>
3691 <row topline="true">
3692 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3693 \begin_inset Text
3694
3695 \begin_layout Standard
3696 speex_version
3697 \end_layout
3698
3699 \end_inset
3700 </cell>
3701 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3702 \begin_inset Text
3703
3704 \begin_layout Standard
3705 char[]
3706 \end_layout
3707
3708 \end_inset
3709 </cell>
3710 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3711 \begin_inset Text
3712
3713 \begin_layout Standard
3714 20
3715 \end_layout
3716
3717 \end_inset
3718 </cell>
3719 </row>
3720 <row topline="true">
3721 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3722 \begin_inset Text
3723
3724 \begin_layout Standard
3725 speex_version_id
3726 \end_layout
3727
3728 \end_inset
3729 </cell>
3730 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3731 \begin_inset Text
3732
3733 \begin_layout Standard
3734 int
3735 \end_layout
3736
3737 \end_inset
3738 </cell>
3739 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3740 \begin_inset Text
3741
3742 \begin_layout Standard
3743 4
3744 \end_layout
3745
3746 \end_inset
3747 </cell>
3748 </row>
3749 <row topline="true">
3750 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3751 \begin_inset Text
3752
3753 \begin_layout Standard
3754 header_size
3755 \end_layout
3756
3757 \end_inset
3758 </cell>
3759 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3760 \begin_inset Text
3761
3762 \begin_layout Standard
3763 int
3764 \end_layout
3765
3766 \end_inset
3767 </cell>
3768 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3769 \begin_inset Text
3770
3771 \begin_layout Standard
3772 4
3773 \end_layout
3774
3775 \end_inset
3776 </cell>
3777 </row>
3778 <row topline="true">
3779 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3780 \begin_inset Text
3781
3782 \begin_layout Standard
3783 rate
3784 \end_layout
3785
3786 \end_inset
3787 </cell>
3788 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3789 \begin_inset Text
3790
3791 \begin_layout Standard
3792 int
3793 \end_layout
3794
3795 \end_inset
3796 </cell>
3797 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3798 \begin_inset Text
3799
3800 \begin_layout Standard
3801 4
3802 \end_layout
3803
3804 \end_inset
3805 </cell>
3806 </row>
3807 <row topline="true">
3808 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3809 \begin_inset Text
3810
3811 \begin_layout Standard
3812 mode
3813 \end_layout
3814
3815 \end_inset
3816 </cell>
3817 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3818 \begin_inset Text
3819
3820 \begin_layout Standard
3821 int
3822 \end_layout
3823
3824 \end_inset
3825 </cell>
3826 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3827 \begin_inset Text
3828
3829 \begin_layout Standard
3830 4
3831 \end_layout
3832
3833 \end_inset
3834 </cell>
3835 </row>
3836 <row topline="true">
3837 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3838 \begin_inset Text
3839
3840 \begin_layout Standard
3841 mode_bitstream_version
3842 \end_layout
3843
3844 \end_inset
3845 </cell>
3846 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3847 \begin_inset Text
3848
3849 \begin_layout Standard
3850 int
3851 \end_layout
3852
3853 \end_inset
3854 </cell>
3855 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3856 \begin_inset Text
3857
3858 \begin_layout Standard
3859 4
3860 \end_layout
3861
3862 \end_inset
3863 </cell>
3864 </row>
3865 <row topline="true">
3866 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3867 \begin_inset Text
3868
3869 \begin_layout Standard
3870 nb_channels
3871 \end_layout
3872
3873 \end_inset
3874 </cell>
3875 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3876 \begin_inset Text
3877
3878 \begin_layout Standard
3879 int
3880 \end_layout
3881
3882 \end_inset
3883 </cell>
3884 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3885 \begin_inset Text
3886
3887 \begin_layout Standard
3888 4
3889 \end_layout
3890
3891 \end_inset
3892 </cell>
3893 </row>
3894 <row topline="true">
3895 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3896 \begin_inset Text
3897
3898 \begin_layout Standard
3899 bitrate
3900 \end_layout
3901
3902 \end_inset
3903 </cell>
3904 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3905 \begin_inset Text
3906
3907 \begin_layout Standard
3908 int
3909 \end_layout
3910
3911 \end_inset
3912 </cell>
3913 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3914 \begin_inset Text
3915
3916 \begin_layout Standard
3917 4
3918 \end_layout
3919
3920 \end_inset
3921 </cell>
3922 </row>
3923 <row topline="true">
3924 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3925 \begin_inset Text
3926
3927 \begin_layout Standard
3928 frame_size
3929 \end_layout
3930
3931 \end_inset
3932 </cell>
3933 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3934 \begin_inset Text
3935
3936 \begin_layout Standard
3937 int
3938 \end_layout
3939
3940 \end_inset
3941 </cell>
3942 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3943 \begin_inset Text
3944
3945 \begin_layout Standard
3946 4
3947 \end_layout
3948
3949 \end_inset
3950 </cell>
3951 </row>
3952 <row topline="true">
3953 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3954 \begin_inset Text
3955
3956 \begin_layout Standard
3957 vbr
3958 \end_layout
3959
3960 \end_inset
3961 </cell>
3962 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3963 \begin_inset Text
3964
3965 \begin_layout Standard
3966 int
3967 \end_layout
3968
3969 \end_inset
3970 </cell>
3971 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3972 \begin_inset Text
3973
3974 \begin_layout Standard
3975 4
3976 \end_layout
3977
3978 \end_inset
3979 </cell>
3980 </row>
3981 <row topline="true">
3982 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3983 \begin_inset Text
3984
3985 \begin_layout Standard
3986 frames_per_packet
3987 \end_layout
3988
3989 \end_inset
3990 </cell>
3991 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3992 \begin_inset Text
3993
3994 \begin_layout Standard
3995 int
3996 \end_layout
3997
3998 \end_inset
3999 </cell>
4000 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4001 \begin_inset Text
4002
4003 \begin_layout Standard
4004 4
4005 \end_layout
4006
4007 \end_inset
4008 </cell>
4009 </row>
4010 <row topline="true">
4011 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4012 \begin_inset Text
4013
4014 \begin_layout Standard
4015 extra_headers
4016 \end_layout
4017
4018 \end_inset
4019 </cell>
4020 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4021 \begin_inset Text
4022
4023 \begin_layout Standard
4024 int
4025 \end_layout
4026
4027 \end_inset
4028 </cell>
4029 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4030 \begin_inset Text
4031
4032 \begin_layout Standard
4033 4
4034 \end_layout
4035
4036 \end_inset
4037 </cell>
4038 </row>
4039 <row topline="true">
4040 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4041 \begin_inset Text
4042
4043 \begin_layout Standard
4044 reserved1
4045 \end_layout
4046
4047 \end_inset
4048 </cell>
4049 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4050 \begin_inset Text
4051
4052 \begin_layout Standard
4053 int
4054 \end_layout
4055
4056 \end_inset
4057 </cell>
4058 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4059 \begin_inset Text
4060
4061 \begin_layout Standard
4062 4
4063 \end_layout
4064
4065 \end_inset
4066 </cell>
4067 </row>
4068 <row topline="true" bottomline="true">
4069 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4070 \begin_inset Text
4071
4072 \begin_layout Standard
4073 reserved2
4074 \end_layout
4075
4076 \end_inset
4077 </cell>
4078 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4079 \begin_inset Text
4080
4081 \begin_layout Standard
4082 int
4083 \end_layout
4084
4085 \end_inset
4086 </cell>
4087 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4088 \begin_inset Text
4089
4090 \begin_layout Standard
4091 4
4092 \end_layout
4093
4094 \end_inset
4095 </cell>
4096 </row>
4097 </lyxtabular>
4098
4099 \end_inset
4100
4101
4102 \begin_inset ERT
4103 status collapsed
4104
4105 \begin_layout Standard
4106
4107
4108 \backslash
4109 end{center}
4110 \end_layout
4111
4112 \end_inset
4113
4114
4115 \end_layout
4116
4117 \begin_layout Standard
4118 \begin_inset Caption
4119
4120 \begin_layout Standard
4121 Ogg/Speex header packet
4122 \begin_inset LatexCommand label
4123 name "cap:ogg_speex_header"
4124
4125 \end_inset
4126
4127
4128 \end_layout
4129
4130 \end_inset
4131
4132
4133 \end_layout
4134
4135 \end_inset
4136
4137
4138 \end_layout
4139
4140 \begin_layout Standard
4141 \begin_inset ERT
4142 status collapsed
4143
4144 \begin_layout Standard
4145
4146
4147 \backslash
4148 clearpage
4149 \end_layout
4150
4151 \end_inset
4152
4153
4154 \end_layout
4155
4156 \begin_layout Chapter
4157 Introduction to CELP Coding
4158 \begin_inset LatexCommand index
4159 name "CELP"
4160
4161 \end_inset
4162
4163
4164 \begin_inset LatexCommand label
4165 name "sec:Introduction-to-CELP"
4166
4167 \end_inset
4168
4169
4170 \end_layout
4171
4172 \begin_layout Quote
4173 \align center
4174
4175 \emph on
4176 Do not meddle in the affairs of poles, for they are subtle and quick to
4177  leave the unit circle.
4178 \end_layout
4179
4180 \begin_layout Standard
4181 Speex is based on CELP, which stands for Code Excited Linear Prediction.
4182  This section attempts to introduce the principles behind CELP, so if you
4183  are already familiar with CELP, you can safely skip to section 
4184 \begin_inset LatexCommand ref
4185 reference "sec:Speex-narrowband-mode"
4186
4187 \end_inset
4188
4189 .
4190  The CELP technique is based on three ideas:
4191 \end_layout
4192
4193 \begin_layout Enumerate
4194 The use of a linear prediction (LP) model to model the vocal tract
4195 \end_layout
4196
4197 \begin_layout Enumerate
4198 The use of (adaptive and fixed) codebook entries as input (excitation) of
4199  the LP model
4200 \end_layout
4201
4202 \begin_layout Enumerate
4203 The search performed in closed-loop in a 
4204 \begin_inset Quotes eld
4205 \end_inset
4206
4207 perceptually weighted domain
4208 \begin_inset Quotes erd
4209 \end_inset
4210
4211
4212 \end_layout
4213
4214 \begin_layout Standard
4215 This section describes the basic ideas behind CELP.
4216  This is still a work in progress.
4217 \end_layout
4218
4219 \begin_layout Section
4220 Source-Filter Model of Speech Prediction
4221 \end_layout
4222
4223 \begin_layout Standard
4224 The source-filter model of speech production assumes that the vocal cords
4225  are the source of spectrally flat sound (the excitation signal), and that
4226  the vocal tract acts as a filter to spectrally shape the various sounds
4227  of speech.
4228  While still an approximation, the model is widely used in speech coding
4229  because of its simplicity.Its use is also the reason why most speech codecs
4230  (Speex included) perform badly on music signals.
4231  The different phonemes can be distinguished by their excitation (source)
4232  and spectral shape (filter).
4233  Voiced sounds (e.g.
4234  vowels) have an excitation signal that is periodic and that can be approximated
4235  by an impulse train in the time domain or by regularly-spaced harmonics
4236  in the frequency domain.
4237  On the other hand, fricatives (such as the "s", "sh" and "f" sounds) have
4238  an excitation signal that is similar to white Gaussian noise.
4239  So called voice fricatives (such as "z" and "v") have excitation signal
4240  composed of an harmonic part and a noisy part.
4241 \end_layout
4242
4243 \begin_layout Standard
4244 The source-filter model is usually tied with the use of Linear prediction.
4245  The CELP model is based on source-filter model, as can be seen from the
4246  CELP decoder illustrated in Figure 
4247 \begin_inset LatexCommand ref
4248 reference "fig:The-CELP-model"
4249
4250 \end_inset
4251
4252 .
4253  
4254 \end_layout
4255
4256 \begin_layout Standard
4257 \begin_inset Float figure
4258 wide false
4259 sideways false
4260 status open
4261
4262 \begin_layout Standard
4263 \begin_inset ERT
4264 status collapsed
4265
4266 \begin_layout Standard
4267
4268
4269 \backslash
4270 begin{center}
4271 \end_layout
4272
4273 \end_inset
4274
4275
4276 \begin_inset Graphics
4277         filename celp_decoder.eps
4278         width 45page%
4279         keepAspectRatio
4280
4281 \end_inset
4282
4283
4284 \begin_inset ERT
4285 status collapsed
4286
4287 \begin_layout Standard
4288
4289
4290 \backslash
4291 end{center}
4292 \end_layout
4293
4294 \end_inset
4295
4296
4297 \end_layout
4298
4299 \begin_layout Standard
4300 \begin_inset Caption
4301
4302 \begin_layout Standard
4303 The CELP model of speech synthesis (decoder)
4304 \begin_inset LatexCommand label
4305 name "fig:The-CELP-model"
4306
4307 \end_inset
4308
4309  
4310 \end_layout
4311
4312 \end_inset
4313
4314
4315 \end_layout
4316
4317 \end_inset
4318
4319
4320 \end_layout
4321
4322 \begin_layout Section
4323 Linear Prediction (LPC)
4324 \begin_inset LatexCommand index
4325 name "linear prediction"
4326
4327 \end_inset
4328
4329
4330 \end_layout
4331
4332 \begin_layout Standard
4333 Linear prediction is at the base of many speech coding techniques, including
4334  CELP.
4335  The idea behind it is to predict the signal 
4336 \begin_inset Formula $x[n]$
4337 \end_inset
4338
4339  using a linear combination of its past samples:
4340 \end_layout
4341
4342 \begin_layout Standard
4343 \begin_inset Formula \[
4344 y[n]=\sum_{i=1}^{N}a_{i}x[n-i]\]
4345
4346 \end_inset
4347
4348 where 
4349 \begin_inset Formula $y[n]$
4350 \end_inset
4351
4352  is the linear prediction of 
4353 \begin_inset Formula $x[n]$
4354 \end_inset
4355
4356 .
4357  The prediction error is thus given by:
4358 \begin_inset Formula \[
4359 e[n]=x[n]-y[n]=x[n]-\sum_{i=1}^{N}a_{i}x[n-i]\]
4360
4361 \end_inset
4362
4363
4364 \end_layout
4365
4366 \begin_layout Standard
4367 The goal of the LPC analysis is to find the best prediction coefficients
4368  
4369 \begin_inset Formula $a_{i}$
4370 \end_inset
4371
4372  which minimize the quadratic error function:
4373 \begin_inset Formula \[
4374 E=\sum_{n=0}^{L-1}\left[e[n]\right]^{2}=\sum_{n=0}^{L-1}\left[x[n]-\sum_{i=1}^{N}a_{i}x[n-i]\right]^{2}\]
4375
4376 \end_inset
4377
4378 That can be done by making all derivatives 
4379 \begin_inset Formula $\frac{\partial E}{\partial a_{i}}$
4380 \end_inset
4381
4382  equal to zero:
4383 \begin_inset Formula \[
4384 \frac{\partial E}{\partial a_{i}}=\frac{\partial}{\partial a_{i}}\sum_{n=0}^{L-1}\left[x[n]-\sum_{i=1}^{N}a_{i}x[n-i]\right]^{2}=0\]
4385
4386 \end_inset
4387
4388
4389 \end_layout
4390
4391 \begin_layout Standard
4392 For an order 
4393 \begin_inset Formula $N$
4394 \end_inset
4395
4396  filter, the filter coefficients 
4397 \begin_inset Formula $a_{i}$
4398 \end_inset
4399
4400  are found by solving the system 
4401 \begin_inset Formula $N\times N$
4402 \end_inset
4403
4404  linear system 
4405 \begin_inset Formula $\mathbf{Ra}=\mathbf{r}$
4406 \end_inset
4407
4408 , where
4409 \begin_inset Formula \[
4410 \mathbf{R}=\left[\begin{array}{cccc}
4411 R(0) & R(1) & \cdots & R(N-1)\\
4412 R(1) & R(0) & \cdots & R(N-2)\\
4413 \vdots & \vdots & \ddots & \vdots\\
4414 R(N-1) & R(N-2) & \cdots & R(0)\end{array}\right]\]
4415
4416 \end_inset
4417
4418
4419 \begin_inset Formula \[
4420 \mathbf{r}=\left[\begin{array}{c}
4421 R(1)\\
4422 R(2)\\
4423 \vdots\\
4424 R(N)\end{array}\right]\]
4425
4426 \end_inset
4427
4428 with 
4429 \begin_inset Formula $R(m)$
4430 \end_inset
4431
4432 , the auto-correlation
4433 \begin_inset LatexCommand index
4434 name "auto-correlation"
4435
4436 \end_inset
4437
4438  of the signal 
4439 \begin_inset Formula $x[n]$
4440 \end_inset
4441
4442 , computed as:
4443 \end_layout
4444
4445 \begin_layout Standard
4446 \begin_inset Formula \[
4447 R(m)=\sum_{i=0}^{N-1}x[i]x[i-m]\]
4448
4449 \end_inset
4450
4451
4452 \end_layout
4453
4454 \begin_layout Standard
4455 Because 
4456 \begin_inset Formula $\mathbf{R}$
4457 \end_inset
4458
4459  is toeplitz hermitian, the Levinson-Durbin
4460 \begin_inset LatexCommand index
4461 name "Levinson-Durbin"
4462
4463 \end_inset
4464
4465  algorithm can be used, making the solution to the problem 
4466 \begin_inset Formula $\mathcal{O}\left(N^{2}\right)$
4467 \end_inset
4468
4469  instead of 
4470 \begin_inset Formula $\mathcal{O}\left(N^{3}\right)$
4471 \end_inset
4472
4473 .
4474  Also, it can be proven that all the roots of 
4475 \begin_inset Formula $A(z)$