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