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