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