Re-arranged the wideband mode so that programs using narrowband only and
[speexdsp.git] / doc / manual.lyx
1 #LyX 1.5.0 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 Beta 3
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-2007 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 publically.
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 refered 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 achives compression at the expense
453  of fidelity of the input speech signal.
454  Unlike some other speech codecs, it is possible to control the tradeoff
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 achive 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 Standard
919
920 \newpage
921
922 \end_layout
923
924 \begin_layout Chapter
925 Compiling
926 \end_layout
927
928 \begin_layout Standard
929 Compiling Speex under UNIX/Linux or any other platform supported by autoconf
930  (e.g.
931  Win32/cygwin) is as easy as typing:
932 \end_layout
933
934 \begin_layout LyX-Code
935 % ./configure [options]
936 \end_layout
937
938 \begin_layout LyX-Code
939 % make
940 \end_layout
941
942 \begin_layout LyX-Code
943 % make install
944 \end_layout
945
946 \begin_layout Standard
947 The options supported by the Speex configure script are:
948 \end_layout
949
950 \begin_layout Description
951 --prefix=<path> Specifies the base path for installing Speex (e.g.
952  /usr)
953 \end_layout
954
955 \begin_layout Description
956 --enable-shared/--disable-shared Whether to compile shared libraries
957 \end_layout
958
959 \begin_layout Description
960 --enable-static/--disable-static Whether to compile static libraries
961 \end_layout
962
963 \begin_layout Description
964 --disable-wideband Disable the wideband part of Speex (typically to save
965  space)
966 \end_layout
967
968 \begin_layout Description
969 --enable-valgrind Enable extra hits for valgrind for debugging purposes
970  (do not use by default)
971 \end_layout
972
973 \begin_layout Description
974 --enable-sse Enable use of SSE instructions (x86/float only)
975 \end_layout
976
977 \begin_layout Description
978 --enable-fixed-point
979 \begin_inset LatexCommand index
980 name "fixed-point"
981
982 \end_inset
983
984  Compile Speex for a processor that does not have a floating point unit
985  (FPU)
986 \end_layout
987
988 \begin_layout Description
989 --enable-arm4-asm Enable assembly specific to the ARMv4 architecture (gcc
990  only)
991 \end_layout
992
993 \begin_layout Description
994 --enable-arm5e-asm Enable assembly specific to the ARMv5E architecture (gcc
995  only)
996 \end_layout
997
998 \begin_layout Description
999 --enable-fixed-point-debug Use only for debugging the fixed-point
1000 \begin_inset LatexCommand index
1001 name "fixed-point"
1002
1003 \end_inset
1004
1005  code (very slow)
1006 \end_layout
1007
1008 \begin_layout Description
1009 --enable-epic-48k Enable a special (and non-compatible) 4.8 kbps narrowband
1010  mode (broken in 1.1.x and 1.2beta)
1011 \end_layout
1012
1013 \begin_layout Description
1014 --enable-ti-c55x Enable support for the TI C5x family
1015 \end_layout
1016
1017 \begin_layout Description
1018 --enable-blackfin-asm Enable assembly specific to the Blackfin DSP architecture
1019  (gcc only)
1020 \end_layout
1021
1022 \begin_layout Description
1023 --enable-vorbis-psycho Make the encoder use the Vorbis psycho-acoustic model.
1024  This is very experimental and may be removed in the future.
1025 \end_layout
1026
1027 \begin_layout Section
1028 Platforms
1029 \end_layout
1030
1031 \begin_layout Standard
1032 Speex is known to compile and work on a large number of architectures, both
1033  floating-point and fixed-point.
1034  In general, any architecture that can natively compute the multiplication
1035  of two signed 16-bit numbers (32-bit result) and runs at a sufficient clock
1036  rate (architecture-dependent) is capable of running Speex.
1037  Architectures that are 
1038 \series bold
1039 known
1040 \series default
1041  to be supported (it probably works on many others) are:
1042 \end_layout
1043
1044 \begin_layout Itemize
1045 x86 & x86-64
1046 \end_layout
1047
1048 \begin_layout Itemize
1049 Power
1050 \end_layout
1051
1052 \begin_layout Itemize
1053 SPARC
1054 \end_layout
1055
1056 \begin_layout Itemize
1057 ARM
1058 \end_layout
1059
1060 \begin_layout Itemize
1061 Blackfin
1062 \end_layout
1063
1064 \begin_layout Itemize
1065 TI C54xx & C55xx
1066 \end_layout
1067
1068 \begin_layout Itemize
1069 TI C6xxx
1070 \end_layout
1071
1072 \begin_layout Itemize
1073 TriMedia (experimental)
1074 \end_layout
1075
1076 \begin_layout Standard
1077 Operating systems on top of which Speex is known to work include (it probably
1078  works on many others):
1079 \end_layout
1080
1081 \begin_layout Itemize
1082 Linux
1083 \end_layout
1084
1085 \begin_layout Itemize
1086 \begin_inset Formula $\mu$
1087 \end_inset
1088
1089 Clinux
1090 \end_layout
1091
1092 \begin_layout Itemize
1093 MacOS X
1094 \end_layout
1095
1096 \begin_layout Itemize
1097 BSD
1098 \end_layout
1099
1100 \begin_layout Itemize
1101 Other UNIX/POSIX variants
1102 \end_layout
1103
1104 \begin_layout Itemize
1105 Symbian
1106 \end_layout
1107
1108 \begin_layout Standard
1109 The source code directory include additional information for compiling on
1110  certain architectures or operating systems in README.xxx files.
1111 \end_layout
1112
1113 \begin_layout Section
1114 Porting and Optimising
1115 \end_layout
1116
1117 \begin_layout Standard
1118 Here are a few things to consider when porting or optimising Speex for a
1119  new platform or an existing one.
1120 \end_layout
1121
1122 \begin_layout Subsection
1123 CPU optimisation
1124 \end_layout
1125
1126 \begin_layout Standard
1127 The following functions are usually the first ones you should consider optimisin
1128 g:
1129 \end_layout
1130
1131 \begin_layout Itemize
1132 \begin_inset listings
1133 inline true
1134 status collapsed
1135
1136 \begin_layout Standard
1137
1138 filter_mem16()
1139 \end_layout
1140
1141 \end_inset
1142
1143
1144 \end_layout
1145
1146 \begin_layout Itemize
1147 \begin_inset listings
1148 inline true
1149 status collapsed
1150
1151 \begin_layout Standard
1152
1153 iir_mem16()
1154 \end_layout
1155
1156 \end_inset
1157
1158
1159 \end_layout
1160
1161 \begin_layout Itemize
1162 \begin_inset listings
1163 inline true
1164 status collapsed
1165
1166 \begin_layout Standard
1167
1168 pitch_xcorr()
1169 \end_layout
1170
1171 \end_inset
1172
1173
1174 \end_layout
1175
1176 \begin_layout Subsection
1177 Memory optimisation
1178 \end_layout
1179
1180 \begin_layout Standard
1181 Memory optimisation is mainly something that should be considered for small
1182  embedded platforms.
1183  For PCs, Speex is already so tiny that it's just not worth doing any of
1184  the things suggested here.
1185  There are several ways to reduce the memory usage of Speex, both in terms
1186  of code size and data size.
1187  For optimising code size, the trick is to first remove features you do
1188  not need.
1189  Some examples of things that can easily be disabled 
1190 \series bold
1191 if you don't need them
1192 \series default
1193  are:
1194 \end_layout
1195
1196 \begin_layout Itemize
1197 Wideband support (--disable-wideband)
1198 \end_layout
1199
1200 \begin_layout Itemize
1201 Support for stereo (removing stereo.c)
1202 \end_layout
1203
1204 \begin_layout Itemize
1205 VBR support (vbr.c and a few lines in nb_celp.c)
1206 \end_layout
1207
1208 \begin_layout Itemize
1209 Static codebooks that are not needed for the bit-rates you are using (*_table.c
1210  files)
1211 \end_layout
1212
1213 \begin_layout Standard
1214
1215 \newpage
1216
1217 \end_layout
1218
1219 \begin_layout Chapter
1220 Command-line encoder/decoder
1221 \begin_inset LatexCommand label
1222 name "sec:Command-line-encoder/decoder"
1223
1224 \end_inset
1225
1226
1227 \end_layout
1228
1229 \begin_layout Standard
1230 The base Speex distribution includes a command-line encoder (
1231 \emph on
1232 speexenc
1233 \emph default
1234 ) and decoder (
1235 \emph on
1236 speexdec
1237 \emph default
1238 ).
1239  Those tools produce and read Speex files encapsulated in the Ogg container.
1240  Although it is possible to encapsulate Speex in any container, Ogg is the
1241  recommended container for files.
1242  This section describes how to use the command line tools for Speex files
1243  in Ogg.
1244 \end_layout
1245
1246 \begin_layout Section
1247
1248 \emph on
1249 speexenc
1250 \begin_inset LatexCommand index
1251 name "speexenc"
1252
1253 \end_inset
1254
1255
1256 \end_layout
1257
1258 \begin_layout Standard
1259 The 
1260 \emph on
1261 speexenc
1262 \emph default
1263  utility is used to create Speex files from raw PCM or wave files.
1264  It can be used by calling: 
1265 \end_layout
1266
1267 \begin_layout LyX-Code
1268 speexenc [options] input_file output_file
1269 \end_layout
1270
1271 \begin_layout Standard
1272 The value '-' for input_file or output_file corresponds respectively to
1273  stdin and stdout.
1274  The valid options are:
1275 \end_layout
1276
1277 \begin_layout Description
1278 --narrowband\InsetSpace ~
1279 (-n) Tell Speex to treat the input as narrowband (8 kHz).
1280  This is the default
1281 \end_layout
1282
1283 \begin_layout Description
1284 --wideband\InsetSpace ~
1285 (-w) Tell Speex to treat the input as wideband (16 kHz)
1286 \end_layout
1287
1288 \begin_layout Description
1289 --ultra-wideband\InsetSpace ~
1290 (-u) Tell Speex to treat the input as 
1291 \begin_inset Quotes eld
1292 \end_inset
1293
1294 ultra-wideband
1295 \begin_inset Quotes erd
1296 \end_inset
1297
1298  (32 kHz)
1299 \end_layout
1300
1301 \begin_layout Description
1302 --quality\InsetSpace ~
1303 n Set the encoding quality (0-10), default is 8
1304 \end_layout
1305
1306 \begin_layout Description
1307 --bitrate\InsetSpace ~
1308 n Encoding bit-rate (use bit-rate n or lower) 
1309 \end_layout
1310
1311 \begin_layout Description
1312 --vbr Enable VBR (Variable Bit-Rate), disabled by default
1313 \end_layout
1314
1315 \begin_layout Description
1316 --abr\InsetSpace ~
1317 n Enable ABR (Average Bit-Rate) at n kbps, disabled by default
1318 \end_layout
1319
1320 \begin_layout Description
1321 --vad Enable VAD (Voice Activity Detection), disabled by default
1322 \end_layout
1323
1324 \begin_layout Description
1325 --dtx Enable DTX (Discontinuous Transmission), disabled by default
1326 \end_layout
1327
1328 \begin_layout Description
1329 --nframes\InsetSpace ~
1330 n Pack n frames in each Ogg packet (this saves space at low bit-rates)
1331 \end_layout
1332
1333 \begin_layout Description
1334 --comp\InsetSpace ~
1335 n Set encoding speed/quality tradeoff.
1336  The higher the value of n, the slower the encoding (default is 3)
1337 \end_layout
1338
1339 \begin_layout Description
1340 -V Verbose operation, print bit-rate currently in use
1341 \end_layout
1342
1343 \begin_layout Description
1344 --help\InsetSpace ~
1345 (-h) Print the help
1346 \end_layout
1347
1348 \begin_layout Description
1349 --version\InsetSpace ~
1350 (-v) Print version information
1351 \end_layout
1352
1353 \begin_layout Subsection*
1354 Speex comments
1355 \end_layout
1356
1357 \begin_layout Description
1358 --comment Add the given string as an extra comment.
1359  This may be used multiple times.
1360  
1361 \end_layout
1362
1363 \begin_layout Description
1364 --author Author of this track.
1365  
1366 \end_layout
1367
1368 \begin_layout Description
1369 --title Title for this track.
1370  
1371 \end_layout
1372
1373 \begin_layout Subsection*
1374 Raw input options
1375 \end_layout
1376
1377 \begin_layout Description
1378 --rate\InsetSpace ~
1379 n Sampling rate for raw input
1380 \end_layout
1381
1382 \begin_layout Description
1383 --stereo Consider raw input as stereo 
1384 \end_layout
1385
1386 \begin_layout Description
1387 --le Raw input is little-endian 
1388 \end_layout
1389
1390 \begin_layout Description
1391 --be Raw input is big-endian 
1392 \end_layout
1393
1394 \begin_layout Description
1395 --8bit Raw input is 8-bit unsigned 
1396 \end_layout
1397
1398 \begin_layout Description
1399 --16bit Raw input is 16-bit signed 
1400 \end_layout
1401
1402 \begin_layout Section
1403
1404 \emph on
1405 speexdec
1406 \begin_inset LatexCommand index
1407 name "speexdec"
1408
1409 \end_inset
1410
1411
1412 \end_layout
1413
1414 \begin_layout Standard
1415 The 
1416 \emph on
1417 speexdec
1418 \emph default
1419  utility is used to decode Speex files and can be used by calling: 
1420 \end_layout
1421
1422 \begin_layout LyX-Code
1423 speexdec [options] speex_file [output_file]
1424 \end_layout
1425
1426 \begin_layout Standard
1427 The value '-' for input_file or output_file corresponds respectively to
1428  stdin and stdout.
1429  Also, when no output_file is specified, the file is played to the soundcard.
1430  The valid options are:
1431 \end_layout
1432
1433 \begin_layout Description
1434 --enh enable post-filter (default)
1435 \end_layout
1436
1437 \begin_layout Description
1438 --no-enh disable post-filter
1439 \end_layout
1440
1441 \begin_layout Description
1442 --force-nb Force decoding in narrowband 
1443 \end_layout
1444
1445 \begin_layout Description
1446 --force-wb Force decoding in wideband 
1447 \end_layout
1448
1449 \begin_layout Description
1450 --force-uwb Force decoding in ultra-wideband 
1451 \end_layout
1452
1453 \begin_layout Description
1454 --mono Force decoding in mono 
1455 \end_layout
1456
1457 \begin_layout Description
1458 --stereo Force decoding in stereo 
1459 \end_layout
1460
1461 \begin_layout Description
1462 --rate\InsetSpace ~
1463 n Force decoding at n Hz sampling rate
1464 \end_layout
1465
1466 \begin_layout Description
1467 --packet-loss\InsetSpace ~
1468 n Simulate n % random packet loss
1469 \end_layout
1470
1471 \begin_layout Description
1472 -V Verbose operation, print bit-rate currently in use
1473 \end_layout
1474
1475 \begin_layout Description
1476 --help\InsetSpace ~
1477 (-h) Print the help
1478 \end_layout
1479
1480 \begin_layout Description
1481 --version\InsetSpace ~
1482 (-v) Print version information
1483 \end_layout
1484
1485 \begin_layout Standard
1486
1487 \newpage
1488
1489 \end_layout
1490
1491 \begin_layout Chapter
1492 Using the Speex Codec API (
1493 \emph on
1494 libspeex
1495 \emph default
1496
1497 \begin_inset LatexCommand index
1498 name "libspeex"
1499
1500 \end_inset
1501
1502 )
1503 \begin_inset LatexCommand label
1504 name "sec:Programming-with-Speex"
1505
1506 \end_inset
1507
1508
1509 \end_layout
1510
1511 \begin_layout Standard
1512 The 
1513 \emph on
1514 libspeex
1515 \emph default
1516  library contains all the functions for encoding and decoding speech with
1517  the Speex codec.
1518  When linking on a UNIX system, one must add 
1519 \emph on
1520 -lspeex -lm
1521 \emph default
1522  to the compiler command line.
1523  One important thing to know is that 
1524 \series bold
1525 libspeex calls are reentrant, but not thread-safe
1526 \series default
1527 .
1528  That means that it is fine to use calls from many threads, but 
1529 \series bold
1530 calls using the same state from multiple threads must be protected by mutexes
1531 \series default
1532 .
1533  Examples of code can also be found in Appendix 
1534 \begin_inset LatexCommand ref
1535 reference "sec:Sample-code"
1536
1537 \end_inset
1538
1539  and the complete API documentation is included in the Documentation section
1540  of the Speex website (http://www.speex.org/).
1541 \end_layout
1542
1543 \begin_layout Section
1544 Encoding
1545 \begin_inset LatexCommand label
1546 name "sub:Encoding"
1547
1548 \end_inset
1549
1550
1551 \end_layout
1552
1553 \begin_layout Standard
1554 In order to encode speech using Speex, one first needs to:
1555 \end_layout
1556
1557 \begin_layout Standard
1558 \begin_inset listings
1559 inline false
1560 status open
1561
1562 \begin_layout Standard
1563
1564 #include <speex/speex.h>
1565 \end_layout
1566
1567 \end_inset
1568
1569 Then in the code, a Speex bit-packing struct must be declared, along with
1570  a Speex encoder state:
1571 \begin_inset listings
1572 inline false
1573 status open
1574
1575 \begin_layout Standard
1576
1577 SpeexBits bits;
1578 \end_layout
1579
1580 \begin_layout Standard
1581
1582 void *enc_state;
1583 \end_layout
1584
1585 \end_inset
1586
1587 The two are initialized by:
1588 \begin_inset listings
1589 inline false
1590 status open
1591
1592 \begin_layout Standard
1593
1594 speex_bits_init(&bits);
1595 \end_layout
1596
1597 \begin_layout Standard
1598
1599 enc_state = speex_encoder_init(&speex_nb_mode);
1600 \end_layout
1601
1602 \end_inset
1603
1604
1605 \end_layout
1606
1607 \begin_layout Standard
1608 For wideband coding, 
1609 \emph on
1610 speex_nb_mode
1611 \emph default
1612  will be replaced by 
1613 \emph on
1614 speex_wb_mode
1615 \emph default
1616 .
1617  In most cases, you will need to know the frame size used at the sampling
1618  rate you are using.
1619  You can get that value in the 
1620 \emph on
1621 frame_size
1622 \emph default
1623  variable (expressed in 
1624 \series bold
1625 samples
1626 \series default
1627 , not bytes) with:
1628 \end_layout
1629
1630 \begin_layout Standard
1631 \begin_inset listings
1632 inline false
1633 status open
1634
1635 \begin_layout Standard
1636
1637 speex_encoder_ctl(enc_state,SPEEX_GET_FRAME_SIZE,&frame_size);
1638 \end_layout
1639
1640 \end_inset
1641
1642
1643 \end_layout
1644
1645 \begin_layout Standard
1646 In practice, 
1647 \emph on
1648 frame_size
1649 \emph default
1650  will correspond to 20 ms when using 8, 16, or 32 kHz sampling rate.
1651  There are many parameters that can be set for the Speex encoder, but the
1652  most useful one is the quality parameter that controls the quality vs bit-rate
1653  tradeoff.
1654  This is set by:
1655 \end_layout
1656
1657 \begin_layout Standard
1658 \begin_inset listings
1659 inline false
1660 status open
1661
1662 \begin_layout Standard
1663
1664 speex_encoder_ctl(enc_state,SPEEX_SET_QUALITY,&quality);
1665 \end_layout
1666
1667 \end_inset
1668
1669 where 
1670 \emph on
1671 quality
1672 \emph default
1673  is an integer value ranging from 0 to 10 (inclusively).
1674  The mapping between quality and bit-rate is described in Fig.
1675  
1676 \begin_inset LatexCommand ref
1677 reference "cap:quality_vs_bps"
1678
1679 \end_inset
1680
1681  for narrowband.
1682 \end_layout
1683
1684 \begin_layout Standard
1685 Once the initialization is done, for every input frame:
1686 \end_layout
1687
1688 \begin_layout Standard
1689 \begin_inset listings
1690 inline false
1691 status open
1692
1693 \begin_layout Standard
1694
1695 speex_bits_reset(&bits);
1696 \end_layout
1697
1698 \begin_layout Standard
1699
1700 speex_encode_int(enc_state, input_frame, &bits);
1701 \end_layout
1702
1703 \begin_layout Standard
1704
1705 nbBytes = speex_bits_write(&bits, byte_ptr, MAX_NB_BYTES);
1706 \end_layout
1707
1708 \end_inset
1709
1710
1711 \end_layout
1712
1713 \begin_layout Standard
1714 where 
1715 \emph on
1716 input_frame
1717 \emph default
1718  is a 
1719 \emph on
1720 (
1721 \emph default
1722 short 
1723 \emph on
1724 *)
1725 \emph default
1726  pointing to the beginning of a speech frame, 
1727 \emph on
1728 byte_ptr
1729 \emph default
1730  is a 
1731 \emph on
1732 (char *)
1733 \emph default
1734  where the encoded frame will be written, 
1735 \emph on
1736 MAX_NB_BYTES
1737 \emph default
1738  is the maximum number of bytes that can be written to 
1739 \emph on
1740 byte_ptr
1741 \emph default
1742  without causing an overflow and 
1743 \emph on
1744 nbBytes
1745 \emph default
1746  is the number of bytes actually written to 
1747 \emph on
1748 byte_ptr
1749 \emph default
1750  (the encoded size in bytes).
1751  Before calling speex_bits_write, it is possible to find the number of bytes
1752  that need to be written by calling 
1753 \family typewriter
1754 speex_bits_nbytes(&bits)
1755 \family default
1756 , which returns a number of bytes.
1757 \end_layout
1758
1759 \begin_layout Standard
1760 It is still possible to use the 
1761 \emph on
1762 speex_encode()
1763 \emph default
1764  function, which takes a 
1765 \emph on
1766 (float *)
1767 \emph default
1768  for the audio.
1769  However, this would make an eventual port to an FPU-less platform (like
1770  ARM) more complicated.
1771  Internally, 
1772 \emph on
1773 speex_encode()
1774 \emph default
1775  and 
1776 \emph on
1777 speex_encode_int()
1778 \emph default
1779  are processed in the same way.
1780  Whether the encoder uses the fixed-point version is only decided by the
1781  compile-time flags, not at the API level.
1782 \end_layout
1783
1784 \begin_layout Standard
1785 After you're done with the encoding, free all resources with:
1786 \end_layout
1787
1788 \begin_layout Standard
1789 \begin_inset listings
1790 inline false
1791 status open
1792
1793 \begin_layout Standard
1794
1795 speex_bits_destroy(&bits);
1796 \end_layout
1797
1798 \begin_layout Standard
1799
1800 speex_encoder_destroy(enc_state);
1801 \end_layout
1802
1803 \end_inset
1804
1805
1806 \end_layout
1807
1808 \begin_layout Standard
1809 That's about it for the encoder.
1810  
1811 \end_layout
1812
1813 \begin_layout Section
1814 Decoding
1815 \begin_inset LatexCommand label
1816 name "sub:Decoding"
1817
1818 \end_inset
1819
1820
1821 \end_layout
1822
1823 \begin_layout Standard
1824 In order to decode speech using Speex, you first need to:
1825 \begin_inset listings
1826 inline false
1827 status open
1828
1829 \begin_layout Standard
1830
1831 #include <speex/speex.h>
1832 \end_layout
1833
1834 \end_inset
1835
1836 You also need to declare a Speex bit-packing struct
1837 \begin_inset listings
1838 inline false
1839 status open
1840
1841 \begin_layout Standard
1842
1843 SpeexBits bits;
1844 \end_layout
1845
1846 \end_inset
1847
1848 and a Speex decoder state
1849 \begin_inset listings
1850 inline false
1851 status open
1852
1853 \begin_layout Standard
1854
1855 void *dec_state;
1856 \end_layout
1857
1858 \end_inset
1859
1860 The two are initialized by:
1861 \begin_inset listings
1862 inline false
1863 status open
1864
1865 \begin_layout Standard
1866
1867 speex_bits_init(&bits);
1868 \end_layout
1869
1870 \begin_layout Standard
1871
1872 dec_state = speex_decoder_init(&speex_nb_mode);
1873 \end_layout
1874
1875 \end_inset
1876
1877
1878 \end_layout
1879
1880 \begin_layout Standard
1881 For wideband decoding, 
1882 \emph on
1883 speex_nb_mode
1884 \emph default
1885  will be replaced by 
1886 \emph on
1887 speex_wb_mode
1888 \emph default
1889 .
1890  If you need to obtain the size of the frames that will be used by the decoder,
1891  you can get that value in the 
1892 \emph on
1893 frame_size
1894 \emph default
1895  variable (expressed in 
1896 \series bold
1897 samples
1898 \series default
1899 , not bytes) with:
1900 \end_layout
1901
1902 \begin_layout Standard
1903 \begin_inset listings
1904 inline false
1905 status open
1906
1907 \begin_layout Standard
1908
1909 speex_decoder_ctl(dec_state, SPEEX_GET_FRAME_SIZE, &frame_size);
1910 \end_layout
1911
1912 \end_inset
1913
1914
1915 \end_layout
1916
1917 \begin_layout Standard
1918 There is also a parameter that can be set for the decoder: whether or not
1919  to use a perceptual enhancer.
1920  This can be set by: 
1921 \end_layout
1922
1923 \begin_layout Standard
1924 \begin_inset listings
1925 inline false
1926 status open
1927
1928 \begin_layout Standard
1929
1930 speex_decoder_ctl(dec_state, SPEEX_SET_ENH, &enh);
1931 \end_layout
1932
1933 \end_inset
1934
1935
1936 \end_layout
1937
1938 \begin_layout Standard
1939 where 
1940 \emph on
1941 enh
1942 \emph default
1943  is an int with value 0 to have the enhancer disabled and 1 to have it enabled.
1944  As of 1.2-beta1, the default is now to enable the enhancer.
1945 \end_layout
1946
1947 \begin_layout Standard
1948 Again, once the decoder initialization is done, for every input frame:
1949 \end_layout
1950
1951 \begin_layout Standard
1952 \begin_inset listings
1953 inline false
1954 status open
1955
1956 \begin_layout Standard
1957
1958 speex_bits_read_from(&bits, input_bytes, nbBytes);
1959 \end_layout
1960
1961 \begin_layout Standard
1962
1963 speex_decode_int(dec_state, &bits, output_frame);
1964 \end_layout
1965
1966 \end_inset
1967
1968 where input_bytes is a 
1969 \emph on
1970 (char *)
1971 \emph default
1972  containing the bit-stream data received for a frame, 
1973 \emph on
1974 nbBytes
1975 \emph default
1976  is the size (in bytes) of that bit-stream, and 
1977 \emph on
1978 output_frame
1979 \emph default
1980  is a 
1981 \emph on
1982 (short *)
1983 \emph default
1984  and points to the area where the decoded speech frame will be written.
1985  A NULL value as the second argument indicates that we don't have the bits
1986  for the current frame.
1987  When a frame is lost, the Speex decoder will do its best to "guess" the
1988  correct signal.
1989 \end_layout
1990
1991 \begin_layout Standard
1992 As for the encoder, the 
1993 \emph on
1994 speex_decode()
1995 \emph default
1996  function can still be used, with a 
1997 \emph on
1998 (float *)
1999 \emph default
2000  as the output for the audio.
2001  After you're done with the decoding, free all resources with:
2002 \end_layout
2003
2004 \begin_layout Standard
2005 \begin_inset listings
2006 inline false
2007 status open
2008
2009 \begin_layout Standard
2010
2011 speex_bits_destroy(&bits);
2012 \end_layout
2013
2014 \begin_layout Standard
2015
2016 speex_decoder_destroy(dec_state);
2017 \end_layout
2018
2019 \end_inset
2020
2021
2022 \end_layout
2023
2024 \begin_layout Section
2025 Codec Options (speex_*_ctl)
2026 \begin_inset LatexCommand label
2027 name "sub:Codec-Options"
2028
2029 \end_inset
2030
2031
2032 \end_layout
2033
2034 \begin_layout Quote
2035 \align center
2036
2037 \emph on
2038 Entities should not be multiplied beyond necessity -- William of Ockham.
2039 \end_layout
2040
2041 \begin_layout Quote
2042 \align center
2043
2044 \emph on
2045 Just because there's an option for it doesn't mean you have to turn it on
2046  -- me.
2047 \end_layout
2048
2049 \begin_layout Standard
2050 The Speex encoder and decoder support many options and requests that can
2051  be accessed through the 
2052 \emph on
2053 speex_encoder_ctl
2054 \emph default
2055  and 
2056 \emph on
2057 speex_decoder_ctl
2058 \emph default
2059  functions.
2060  These functions are similar to the 
2061 \emph on
2062 ioctl
2063 \emph default
2064  system call and their prototypes are:
2065 \end_layout
2066
2067 \begin_layout Standard
2068 \begin_inset listings
2069 inline false
2070 status open
2071
2072 \begin_layout Standard
2073
2074 void speex_encoder_ctl(void *encoder, int request, void *ptr);
2075 \end_layout
2076
2077 \begin_layout Standard
2078
2079 void speex_decoder_ctl(void *encoder, int request, void *ptr);
2080 \end_layout
2081
2082 \end_inset
2083
2084
2085 \end_layout
2086
2087 \begin_layout Standard
2088 Despite those functions, the defaults are usually good for many applications
2089  and 
2090 \series bold
2091 optional settings should only be used when one understands them and knows
2092  that they are needed
2093 \series default
2094 .
2095  A common error is to attempt to set many unnecessary settings.
2096  
2097 \end_layout
2098
2099 \begin_layout Standard
2100 Here is a list of the values allowed for the requests.
2101  Some only apply to the encoder or the decoder.
2102  Because the last argument is of type 
2103 \begin_inset listings
2104 inline true
2105 status collapsed
2106
2107 \begin_layout Standard
2108
2109 void *
2110 \end_layout
2111
2112 \end_inset
2113
2114 , the 
2115 \begin_inset listings
2116 inline true
2117 status collapsed
2118
2119 \begin_layout Standard
2120
2121 _ctl()
2122 \end_layout
2123
2124 \end_inset
2125
2126  functions are 
2127 \series bold
2128 not type safe
2129 \series default
2130 , and shoud thus be used with care.
2131  The type 
2132 \begin_inset listings
2133 inline true
2134 status collapsed
2135
2136 \begin_layout Standard
2137
2138 spx_int32_t
2139 \end_layout
2140
2141 \end_inset
2142
2143  is the same as the C99 
2144 \begin_inset listings
2145 inline true
2146 status collapsed
2147
2148 \begin_layout Standard
2149
2150 int32_t
2151 \end_layout
2152
2153 \end_inset
2154
2155  type.
2156 \end_layout
2157
2158 \begin_layout Description
2159 SPEEX_SET_ENH
2160 \begin_inset Formula $\ddagger$
2161 \end_inset
2162
2163  Set perceptual enhancer
2164 \begin_inset LatexCommand index
2165 name "perceptual enhancement"
2166
2167 \end_inset
2168
2169  to on (1) or off (0) (
2170 \begin_inset listings
2171 inline true
2172 status collapsed
2173
2174 \begin_layout Standard
2175
2176 spx_int32_t
2177 \end_layout
2178
2179 \end_inset
2180
2181 )
2182 \end_layout
2183
2184 \begin_layout Description
2185 SPEEX_GET_ENH
2186 \begin_inset Formula $\ddagger$
2187 \end_inset
2188
2189  Get perceptual enhancer status (
2190 \begin_inset listings
2191 inline true
2192 status collapsed
2193
2194 \begin_layout Standard
2195
2196 spx_int32_t
2197 \end_layout
2198
2199 \end_inset
2200
2201 )
2202 \end_layout
2203
2204 \begin_layout Description
2205 SPEEX_GET_FRAME_SIZE Get the number of samples per frame for the current
2206  mode (
2207 \begin_inset listings
2208 inline true
2209 status collapsed
2210
2211 \begin_layout Standard
2212
2213 spx_int32_t
2214 \end_layout
2215
2216 \end_inset
2217
2218 )
2219 \end_layout
2220
2221 \begin_layout Description
2222 SPEEX_SET_QUALITY
2223 \begin_inset Formula $\dagger$
2224 \end_inset
2225
2226  Set the encoder speech quality (
2227 \begin_inset listings
2228 inline true
2229 status collapsed
2230
2231 \begin_layout Standard
2232
2233 spx_int32_t
2234 \end_layout
2235
2236 \end_inset
2237
2238  from 0 to 10)
2239 \end_layout
2240
2241 \begin_layout Description
2242 SPEEX_GET_QUALITY
2243 \begin_inset Formula $\dagger$
2244 \end_inset
2245
2246  Get the current encoder speech quality (
2247 \begin_inset listings
2248 inline true
2249 status collapsed
2250
2251 \begin_layout Standard
2252
2253 spx_int32_t
2254 \end_layout
2255
2256 \end_inset
2257
2258  from 0 to 10)
2259 \end_layout
2260
2261 \begin_layout Description
2262 SPEEX_SET_MODE
2263 \begin_inset Formula $\dagger$
2264 \end_inset
2265
2266  Set the mode number, as specified in the RTP spec (
2267 \begin_inset listings
2268 inline true
2269 status collapsed
2270
2271 \begin_layout Standard
2272
2273 spx_int32_t
2274 \end_layout
2275
2276 \end_inset
2277
2278 )
2279 \end_layout
2280
2281 \begin_layout Description
2282 SPEEX_GET_MODE
2283 \begin_inset Formula $\dagger$
2284 \end_inset
2285
2286  Get the current mode number, as specified in the RTP spec (
2287 \begin_inset listings
2288 inline true
2289 status collapsed
2290
2291 \begin_layout Standard
2292
2293 spx_int32_t
2294 \end_layout
2295
2296 \end_inset
2297
2298 )
2299 \end_layout
2300
2301 \begin_layout Description
2302 SPEEX_SET_VBR
2303 \begin_inset Formula $\dagger$
2304 \end_inset
2305
2306  Set variable bit-rate (VBR) to on (1) or off (0) (
2307 \begin_inset listings
2308 inline true
2309 status collapsed
2310
2311 \begin_layout Standard
2312
2313 spx_int32_t
2314 \end_layout
2315
2316 \end_inset
2317
2318 )
2319 \end_layout
2320
2321 \begin_layout Description
2322 SPEEX_GET_VBR
2323 \begin_inset Formula $\dagger$
2324 \end_inset
2325
2326  Get variable bit-rate
2327 \begin_inset LatexCommand index
2328 name "variable bit-rate"
2329
2330 \end_inset
2331
2332  (VBR) status (
2333 \begin_inset listings
2334 inline true
2335 status collapsed
2336
2337 \begin_layout Standard
2338
2339 spx_int32_t
2340 \end_layout
2341
2342 \end_inset
2343
2344 )
2345 \end_layout
2346
2347 \begin_layout Description
2348 SPEEX_SET_VBR_QUALITY
2349 \begin_inset Formula $\dagger$
2350 \end_inset
2351
2352  Set the encoder VBR speech quality (float 0 to 10)
2353 \end_layout
2354
2355 \begin_layout Description
2356 SPEEX_GET_VBR_QUALITY
2357 \begin_inset Formula $\dagger$
2358 \end_inset
2359
2360  Get the current encoder VBR speech quality (float 0 to 10)
2361 \end_layout
2362
2363 \begin_layout Description
2364 SPEEX_SET_COMPLEXITY
2365 \begin_inset Formula $\dagger$
2366 \end_inset
2367
2368  Set the CPU resources allowed for the encoder (
2369 \begin_inset listings
2370 inline true
2371 status collapsed
2372
2373 \begin_layout Standard
2374
2375 spx_int32_t
2376 \end_layout
2377
2378 \end_inset
2379
2380  from 1 to 10)
2381 \end_layout
2382
2383 \begin_layout Description
2384 SPEEX_GET_COMPLEXITY
2385 \begin_inset Formula $\dagger$
2386 \end_inset
2387
2388  Get the CPU resources allowed for the encoder (
2389 \begin_inset listings
2390 inline true
2391 status collapsed
2392
2393 \begin_layout Standard
2394
2395 spx_int32_t
2396 \end_layout
2397
2398 \end_inset
2399
2400  from 1 to 10)
2401 \end_layout
2402
2403 \begin_layout Description
2404 SPEEX_SET_BITRATE
2405 \begin_inset Formula $\dagger$
2406 \end_inset
2407
2408  Set the bit-rate to use to the closest value not exceeding the parameter
2409  (
2410 \begin_inset listings
2411 inline true
2412 status collapsed
2413
2414 \begin_layout Standard
2415
2416 spx_int32_t
2417 \end_layout
2418
2419 \end_inset
2420
2421  in bits per second)
2422 \end_layout
2423
2424 \begin_layout Description
2425 SPEEX_GET_BITRATE Get the current bit-rate in use (
2426 \begin_inset listings
2427 inline true
2428 status collapsed
2429
2430 \begin_layout Standard
2431
2432 spx_int32_t
2433 \end_layout
2434
2435 \end_inset
2436
2437  in bits per second)
2438 \end_layout
2439
2440 \begin_layout Description
2441 SPEEX_SET_SAMPLING_RATE Set real sampling rate (
2442 \begin_inset listings
2443 inline true
2444 status collapsed
2445
2446 \begin_layout Standard
2447
2448 spx_int32_t
2449 \end_layout
2450
2451 \end_inset
2452
2453  in Hz)
2454 \end_layout
2455
2456 \begin_layout Description
2457 SPEEX_GET_SAMPLING_RATE Get real sampling rate (
2458 \begin_inset listings
2459 inline true
2460 status collapsed
2461
2462 \begin_layout Standard
2463
2464 spx_int32_t
2465 \end_layout
2466
2467 \end_inset
2468
2469  in Hz)
2470 \end_layout
2471
2472 \begin_layout Description
2473 SPEEX_RESET_STATE Reset the encoder/decoder state to its original state,
2474  clearing all memories (no argument)
2475 \end_layout
2476
2477 \begin_layout Description
2478 SPEEX_SET_VAD
2479 \begin_inset Formula $\dagger$
2480 \end_inset
2481
2482  Set voice activity detection
2483 \begin_inset LatexCommand index
2484 name "voice activity detection"
2485
2486 \end_inset
2487
2488  (VAD) to on (1) or off (0) (
2489 \begin_inset listings
2490 inline true
2491 status collapsed
2492
2493 \begin_layout Standard
2494
2495 spx_int32_t
2496 \end_layout
2497
2498 \end_inset
2499
2500 )
2501 \end_layout
2502
2503 \begin_layout Description
2504 SPEEX_GET_VAD
2505 \begin_inset Formula $\dagger$
2506 \end_inset
2507
2508  Get voice activity detection (VAD) status (
2509 \begin_inset listings
2510 inline true
2511 status collapsed
2512
2513 \begin_layout Standard
2514
2515 spx_int32_t
2516 \end_layout
2517
2518 \end_inset
2519
2520 )
2521 \end_layout
2522
2523 \begin_layout Description
2524 SPEEX_SET_DTX
2525 \begin_inset Formula $\dagger$
2526 \end_inset
2527
2528  Set discontinuous transmission
2529 \begin_inset LatexCommand index
2530 name "discontinuous transmission"
2531
2532 \end_inset
2533
2534  (DTX) to on (1) or off (0) (
2535 \begin_inset listings
2536 inline true
2537 status collapsed
2538
2539 \begin_layout Standard
2540
2541 spx_int32_t
2542 \end_layout
2543
2544 \end_inset
2545
2546 )
2547 \end_layout
2548
2549 \begin_layout Description
2550 SPEEX_GET_DTX
2551 \begin_inset Formula $\dagger$
2552 \end_inset
2553
2554  Get discontinuous transmission (DTX) status (
2555 \begin_inset listings
2556 inline true
2557 status collapsed
2558
2559 \begin_layout Standard
2560
2561 spx_int32_t
2562 \end_layout
2563
2564 \end_inset
2565
2566 )
2567 \end_layout
2568
2569 \begin_layout Description
2570 SPEEX_SET_ABR
2571 \begin_inset Formula $\dagger$
2572 \end_inset
2573
2574  Set average bit-rate
2575 \begin_inset LatexCommand index
2576 name "average bit-rate"
2577
2578 \end_inset
2579
2580  (ABR) to a value n in bits per second (
2581 \begin_inset listings
2582 inline true
2583 status collapsed
2584
2585 \begin_layout Standard
2586
2587 spx_int32_t
2588 \end_layout
2589
2590 \end_inset
2591
2592  in bits per second)
2593 \end_layout
2594
2595 \begin_layout Description
2596 SPEEX_GET_ABR
2597 \begin_inset Formula $\dagger$
2598 \end_inset
2599
2600  Get average bit-rate (ABR) setting (
2601 \begin_inset listings
2602 inline true
2603 status collapsed
2604
2605 \begin_layout Standard
2606
2607 spx_int32_t
2608 \end_layout
2609
2610 \end_inset
2611
2612  in bits per second)
2613 \end_layout
2614
2615 \begin_layout Description
2616 SPEEX_SET_PLC_TUNING
2617 \begin_inset Formula $\dagger$
2618 \end_inset
2619
2620  Tell the encoder to optimize encoding for a certain percentage of packet
2621  loss (
2622 \begin_inset listings
2623 inline true
2624 status collapsed
2625
2626 \begin_layout Standard
2627
2628 spx_int32_t
2629 \end_layout
2630
2631 \end_inset
2632
2633  in percent)
2634 \end_layout
2635
2636 \begin_layout Description
2637 SPEEX_GET_PLC_TUNING
2638 \begin_inset Formula $\dagger$
2639 \end_inset
2640
2641  Get the current tuning of the encoder for PLC (
2642 \begin_inset listings
2643 inline true
2644 status collapsed
2645
2646 \begin_layout Standard
2647
2648 spx_int32_t
2649 \end_layout
2650
2651 \end_inset
2652
2653  in percent)
2654 \end_layout
2655
2656 \begin_layout Description
2657 SPEEX_SET_VBR_MAX_BITRATE
2658 \begin_inset Formula $\dagger$
2659 \end_inset
2660
2661  Set the maximum bit-rate allowed in VBR operation (
2662 \begin_inset listings
2663 inline true
2664 status collapsed
2665
2666 \begin_layout Standard
2667
2668 spx_int32_t
2669 \end_layout
2670
2671 \end_inset
2672
2673  in bits per second)
2674 \end_layout
2675
2676 \begin_layout Description
2677 SPEEX_GET_VBR_MAX_BITRATE
2678 \begin_inset Formula $\dagger$
2679 \end_inset
2680
2681  Get the current maximum bit-rate allowed in VBR operation (
2682 \begin_inset listings
2683 inline true
2684 status collapsed
2685
2686 \begin_layout Standard
2687
2688 spx_int32_t
2689 \end_layout
2690
2691 \end_inset
2692
2693  in bits per second)
2694 \end_layout
2695
2696 \begin_layout Description
2697 SPEEX_SET_HIGHPASS Set the high-pass filter on (1) or off (0) (
2698 \begin_inset listings
2699 inline true
2700 status collapsed
2701
2702 \begin_layout Standard
2703
2704 spx_int32_t
2705 \end_layout
2706
2707 \end_inset
2708
2709 )
2710 \end_layout
2711
2712 \begin_layout Description
2713 SPEEX_TET_HIGHPASS Get the current high-pass filter status (
2714 \begin_inset listings
2715 inline true
2716 status collapsed
2717
2718 \begin_layout Standard
2719
2720 spx_int32_t
2721 \end_layout
2722
2723 \end_inset
2724
2725 )
2726 \end_layout
2727
2728 \begin_layout Description
2729 \begin_inset Formula $\dagger$
2730 \end_inset
2731
2732  applies only to the encoder
2733 \end_layout
2734
2735 \begin_layout Description
2736 \begin_inset Formula $\ddagger$
2737 \end_inset
2738
2739  applies only to the decoder
2740 \end_layout
2741
2742 \begin_layout Section
2743 Mode queries
2744 \begin_inset LatexCommand label
2745 name "sub:Mode-queries"
2746
2747 \end_inset
2748
2749
2750 \end_layout
2751
2752 \begin_layout Standard
2753 Speex modes have a query system similar to the speex_encoder_ctl and speex_decod
2754 er_ctl calls.
2755  Since modes are read-only, it is only possible to get information about
2756  a particular mode.
2757  The function used to do that is:
2758 \begin_inset listings
2759 inline false
2760 status open
2761
2762 \begin_layout Standard
2763
2764 void speex_mode_query(SpeexMode *mode, int request, void *ptr);
2765 \end_layout
2766
2767 \end_inset
2768
2769 The admissible values for request are (unless otherwise note, the values
2770  are returned through 
2771 \emph on
2772 ptr
2773 \emph default
2774 ):
2775 \end_layout
2776
2777 \begin_layout Description
2778 SPEEX_MODE_FRAME_SIZE Get the frame size (in samples) for the mode
2779 \end_layout
2780
2781 \begin_layout Description
2782 SPEEX_SUBMODE_BITRATE Get the bit-rate for a submode number specified through
2783  
2784 \emph on
2785 ptr
2786 \emph default
2787  (integer in bps).
2788  
2789 \end_layout
2790
2791 \begin_layout Section
2792 Packing and in-band signalling
2793 \begin_inset LatexCommand index
2794 name "in-band signalling"
2795
2796 \end_inset
2797
2798
2799 \end_layout
2800
2801 \begin_layout Standard
2802 Sometimes it is desirable to pack more than one frame per packet (or other
2803  basic unit of storage).
2804  The proper way to do it is to call speex_encode 
2805 \begin_inset Formula $N$
2806 \end_inset
2807
2808  times before writing the stream with speex_bits_write.
2809  In cases where the number of frames is not determined by an out-of-band
2810  mechanism, it is possible to include a terminator code.
2811  That terminator consists of the code 15 (decimal) encoded with 5 bits,
2812  as shown in Table 
2813 \begin_inset LatexCommand ref
2814 reference "cap:quality_vs_bps"
2815
2816 \end_inset
2817
2818 .
2819  Note that as of version 1.0.2, calling speex_bits_write automatically inserts
2820  the terminator so as to fill the last byte.
2821  This doesn't involves any overhead and makes sure Speex can always detect
2822  when there is no more frame in a packet.
2823 \end_layout
2824
2825 \begin_layout Standard
2826 It is also possible to send in-band 
2827 \begin_inset Quotes eld
2828 \end_inset
2829
2830 messages
2831 \begin_inset Quotes erd
2832 \end_inset
2833
2834  to the other side.
2835  All these messages are encoded as 
2836 \begin_inset Quotes eld
2837 \end_inset
2838
2839 pseudo-frames
2840 \begin_inset Quotes erd
2841 \end_inset
2842
2843  of mode 14 which contain a 4-bit message type code, followed by the message.
2844  Table 
2845 \begin_inset LatexCommand ref
2846 reference "cap:In-band-signalling-codes"
2847
2848 \end_inset
2849
2850  lists the available codes, their meaning and the size of the message that
2851  follows.
2852  Most of these messages are requests that are sent to the encoder or decoder
2853  on the other end, which is free to comply or ignore them.
2854  By default, all in-band messages are ignored.
2855 \end_layout
2856
2857 \begin_layout Standard
2858 \begin_inset Float table
2859 placement htbp
2860 wide false
2861 sideways false
2862 status open
2863
2864 \begin_layout Standard
2865 \begin_inset ERT
2866 status collapsed
2867
2868 \begin_layout Standard
2869
2870
2871 \backslash
2872 begin{center}
2873 \end_layout
2874
2875 \end_inset
2876
2877
2878 \begin_inset Tabular
2879 <lyxtabular version="3" rows="17" columns="3">
2880 <features>
2881 <column alignment="center" valignment="top" leftline="true" width="0pt">
2882 <column alignment="center" valignment="top" leftline="true" width="0pt">
2883 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
2884 <row topline="true" bottomline="true">
2885 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2886 \begin_inset Text
2887
2888 \begin_layout Standard
2889 Code
2890 \end_layout
2891
2892 \end_inset
2893 </cell>
2894 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2895 \begin_inset Text
2896
2897 \begin_layout Standard
2898 Size (bits)
2899 \end_layout
2900
2901 \end_inset
2902 </cell>
2903 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2904 \begin_inset Text
2905
2906 \begin_layout Standard
2907 Content
2908 \end_layout
2909
2910 \end_inset
2911 </cell>
2912 </row>
2913 <row topline="true">
2914 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2915 \begin_inset Text
2916
2917 \begin_layout Standard
2918 0
2919 \end_layout
2920
2921 \end_inset
2922 </cell>
2923 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2924 \begin_inset Text
2925
2926 \begin_layout Standard
2927 1
2928 \end_layout
2929
2930 \end_inset
2931 </cell>
2932 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2933 \begin_inset Text
2934
2935 \begin_layout Standard
2936 Asks decoder to set perceptual enhancement off (0) or on(1)
2937 \end_layout
2938
2939 \end_inset
2940 </cell>
2941 </row>
2942 <row topline="true">
2943 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2944 \begin_inset Text
2945
2946 \begin_layout Standard
2947 1
2948 \end_layout
2949
2950 \end_inset
2951 </cell>
2952 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2953 \begin_inset Text
2954
2955 \begin_layout Standard
2956 1
2957 \end_layout
2958
2959 \end_inset
2960 </cell>
2961 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2962 \begin_inset Text
2963
2964 \begin_layout Standard
2965 Asks (if 1) the encoder to be less 
2966 \begin_inset Quotes eld
2967 \end_inset
2968
2969 agressive
2970 \begin_inset Quotes erd
2971 \end_inset
2972
2973  due to high packet loss
2974 \end_layout
2975
2976 \end_inset
2977 </cell>
2978 </row>
2979 <row topline="true">
2980 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2981 \begin_inset Text
2982
2983 \begin_layout Standard
2984 2
2985 \end_layout
2986
2987 \end_inset
2988 </cell>
2989 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2990 \begin_inset Text
2991
2992 \begin_layout Standard
2993 4
2994 \end_layout
2995
2996 \end_inset
2997 </cell>
2998 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2999 \begin_inset Text
3000
3001 \begin_layout Standard
3002 Asks encoder to switch to mode N
3003 \end_layout
3004
3005 \end_inset
3006 </cell>
3007 </row>
3008 <row topline="true">
3009 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3010 \begin_inset Text
3011
3012 \begin_layout Standard
3013 3
3014 \end_layout
3015
3016 \end_inset
3017 </cell>
3018 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3019 \begin_inset Text
3020
3021 \begin_layout Standard
3022 4
3023 \end_layout
3024
3025 \end_inset
3026 </cell>
3027 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3028 \begin_inset Text
3029
3030 \begin_layout Standard
3031 Asks encoder to switch to mode N for low-band
3032 \end_layout
3033
3034 \end_inset
3035 </cell>
3036 </row>
3037 <row topline="true">
3038 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3039 \begin_inset Text
3040
3041 \begin_layout Standard
3042 4
3043 \end_layout
3044
3045 \end_inset
3046 </cell>
3047 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3048 \begin_inset Text
3049
3050 \begin_layout Standard
3051 4
3052 \end_layout
3053
3054 \end_inset
3055 </cell>
3056 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3057 \begin_inset Text
3058
3059 \begin_layout Standard
3060 Asks encoder to switch to mode N for high-band
3061 \end_layout
3062
3063 \end_inset
3064 </cell>
3065 </row>
3066 <row topline="true">
3067 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3068 \begin_inset Text
3069
3070 \begin_layout Standard
3071 5
3072 \end_layout
3073
3074 \end_inset
3075 </cell>
3076 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3077 \begin_inset Text
3078
3079 \begin_layout Standard
3080 4
3081 \end_layout
3082
3083 \end_inset
3084 </cell>
3085 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3086 \begin_inset Text
3087
3088 \begin_layout Standard
3089 Asks encoder to switch to quality N for VBR
3090 \end_layout
3091
3092 \end_inset
3093 </cell>
3094 </row>
3095 <row topline="true">
3096 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3097 \begin_inset Text
3098
3099 \begin_layout Standard
3100 6
3101 \end_layout
3102
3103 \end_inset
3104 </cell>
3105 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3106 \begin_inset Text
3107
3108 \begin_layout Standard
3109 4
3110 \end_layout
3111
3112 \end_inset
3113 </cell>
3114 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3115 \begin_inset Text
3116
3117 \begin_layout Standard
3118 Request acknowloedge (0=no, 1=all, 2=only for in-band data)
3119 \end_layout
3120
3121 \end_inset
3122 </cell>
3123 </row>
3124 <row topline="true">
3125 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3126 \begin_inset Text
3127
3128 \begin_layout Standard
3129 7
3130 \end_layout
3131
3132 \end_inset
3133 </cell>
3134 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3135 \begin_inset Text
3136
3137 \begin_layout Standard
3138 4
3139 \end_layout
3140
3141 \end_inset
3142 </cell>
3143 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3144 \begin_inset Text
3145
3146 \begin_layout Standard
3147 Asks encoder to set CBR (0), VAD(1), DTX(3), VBR(5), VBR+DTX(7)
3148 \end_layout
3149
3150 \end_inset
3151 </cell>
3152 </row>
3153 <row topline="true">
3154 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3155 \begin_inset Text
3156
3157 \begin_layout Standard
3158 8
3159 \end_layout
3160
3161 \end_inset
3162 </cell>
3163 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3164 \begin_inset Text
3165
3166 \begin_layout Standard
3167 8
3168 \end_layout
3169
3170 \end_inset
3171 </cell>
3172 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3173 \begin_inset Text
3174
3175 \begin_layout Standard
3176 Transmit (8-bit) character to the other end
3177 \end_layout
3178
3179 \end_inset
3180 </cell>
3181 </row>
3182 <row topline="true">
3183 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3184 \begin_inset Text
3185
3186 \begin_layout Standard
3187 9
3188 \end_layout
3189
3190 \end_inset
3191 </cell>
3192 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3193 \begin_inset Text
3194
3195 \begin_layout Standard
3196 8
3197 \end_layout
3198
3199 \end_inset
3200 </cell>
3201 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3202 \begin_inset Text
3203
3204 \begin_layout Standard
3205 Intensity stereo information
3206 \end_layout
3207
3208 \end_inset
3209 </cell>
3210 </row>
3211 <row topline="true">
3212 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3213 \begin_inset Text
3214
3215 \begin_layout Standard
3216 10
3217 \end_layout
3218
3219 \end_inset
3220 </cell>
3221 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3222 \begin_inset Text
3223
3224 \begin_layout Standard
3225 16
3226 \end_layout
3227
3228 \end_inset
3229 </cell>
3230 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3231 \begin_inset Text
3232
3233 \begin_layout Standard
3234 Announce maximum bit-rate acceptable (N in bytes/second)
3235 \end_layout
3236
3237 \end_inset
3238 </cell>
3239 </row>
3240 <row topline="true">
3241 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3242 \begin_inset Text
3243
3244 \begin_layout Standard
3245 11
3246 \end_layout
3247
3248 \end_inset
3249 </cell>
3250 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3251 \begin_inset Text
3252
3253 \begin_layout Standard
3254 16
3255 \end_layout
3256
3257 \end_inset
3258 </cell>
3259 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3260 \begin_inset Text
3261
3262 \begin_layout Standard
3263 reserved
3264 \end_layout
3265
3266 \end_inset
3267 </cell>
3268 </row>
3269 <row topline="true">
3270 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3271 \begin_inset Text
3272
3273 \begin_layout Standard
3274 12
3275 \end_layout
3276
3277 \end_inset
3278 </cell>
3279 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3280 \begin_inset Text
3281
3282 \begin_layout Standard
3283 32
3284 \end_layout
3285
3286 \end_inset
3287 </cell>
3288 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3289 \begin_inset Text
3290
3291 \begin_layout Standard
3292 Acknowledge receiving packet N
3293 \end_layout
3294
3295 \end_inset
3296 </cell>
3297 </row>
3298 <row topline="true">
3299 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3300 \begin_inset Text
3301
3302 \begin_layout Standard
3303 13
3304 \end_layout
3305
3306 \end_inset
3307 </cell>
3308 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3309 \begin_inset Text
3310
3311 \begin_layout Standard
3312 32
3313 \end_layout
3314
3315 \end_inset
3316 </cell>
3317 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3318 \begin_inset Text
3319
3320 \begin_layout Standard
3321 reserved
3322 \end_layout
3323
3324 \end_inset
3325 </cell>
3326 </row>
3327 <row topline="true">
3328 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3329 \begin_inset Text
3330
3331 \begin_layout Standard
3332 14
3333 \end_layout
3334
3335 \end_inset
3336 </cell>
3337 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3338 \begin_inset Text
3339
3340 \begin_layout Standard
3341 64
3342 \end_layout
3343
3344 \end_inset
3345 </cell>
3346 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3347 \begin_inset Text
3348
3349 \begin_layout Standard
3350 reserved
3351 \end_layout
3352
3353 \end_inset
3354 </cell>
3355 </row>
3356 <row topline="true" bottomline="true">
3357 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3358 \begin_inset Text
3359
3360 \begin_layout Standard
3361 15
3362 \end_layout
3363
3364 \end_inset
3365 </cell>
3366 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3367 \begin_inset Text
3368
3369 \begin_layout Standard
3370 64
3371 \end_layout
3372
3373 \end_inset
3374 </cell>
3375 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3376 \begin_inset Text
3377
3378 \begin_layout Standard
3379 reserved
3380 \end_layout
3381
3382 \end_inset
3383 </cell>
3384 </row>
3385 </lyxtabular>
3386
3387 \end_inset
3388
3389
3390 \begin_inset ERT
3391 status collapsed
3392
3393 \begin_layout Standard
3394
3395
3396 \backslash
3397 end{center}
3398 \end_layout
3399
3400 \end_inset
3401
3402
3403 \end_layout
3404
3405 \begin_layout Standard
3406 \begin_inset Caption
3407
3408 \begin_layout Standard
3409 In-band signalling codes
3410 \begin_inset LatexCommand label
3411 name "cap:In-band-signalling-codes"
3412
3413 \end_inset
3414
3415
3416 \end_layout
3417
3418 \end_inset
3419
3420
3421 \end_layout
3422
3423 \end_inset
3424
3425
3426 \end_layout
3427
3428 \begin_layout Standard
3429 Finally, applications may define custom in-band messages using mode 13.
3430  The size of the message in bytes is encoded with 5 bits, so that the decoder
3431  can skip it if it doesn't know how to interpret it.
3432 \newpage
3433
3434 \end_layout
3435
3436 \begin_layout Chapter
3437 Speech Processing API (
3438 \emph on
3439 libspeexdsp
3440 \emph default
3441 )
3442 \end_layout
3443
3444 \begin_layout Standard
3445 As of version 1.2beta3, the non-codec parts of the Speex package are now
3446  in a separate library called 
3447 \emph on
3448 libspeexdsp
3449 \emph default
3450 .
3451  This library includes the preprocessor, the acoustic echo canceller, the
3452  jitter buffer, and the resampler.
3453  In a UNIX environment, it can be linked into a program by adding 
3454 \emph on
3455 -lspeexdsp -lm
3456 \emph default
3457  to the compiler command line.
3458  Just like for libspeex, 
3459 \series bold
3460 libspeexdsp calls are reentrant, but not thread-safe
3461 \series default
3462 .
3463  That means that it is fine to use calls from many threads, but 
3464 \series bold
3465 calls using the same state from multiple threads must be protected by mutexes
3466 \series default
3467 .
3468 \end_layout
3469
3470 \begin_layout Section
3471 Preprocessor
3472 \begin_inset LatexCommand label
3473 name "sub:Preprocessor"
3474
3475 \end_inset
3476
3477
3478 \end_layout
3479
3480 \begin_layout Standard
3481 \noindent
3482 In order to use the Speex preprocessor
3483 \begin_inset LatexCommand index
3484 name "preprocessor"
3485
3486 \end_inset
3487
3488 , you first need to:
3489 \begin_inset listings
3490 inline false
3491 status open
3492
3493 \begin_layout Standard
3494
3495 #include <speex/speex_preprocess.h>
3496 \end_layout
3497
3498 \end_inset
3499
3500
3501 \end_layout
3502
3503 \begin_layout Standard
3504 \noindent
3505 Then, a preprocessor state can be created as:
3506 \begin_inset listings
3507 inline false
3508 status open
3509
3510 \begin_layout Standard
3511
3512 SpeexPreprocessState *preprocess_state = speex_preprocess_state_init(frame_size,
3513  sampling_rate);
3514 \end_layout
3515
3516 \end_inset
3517
3518
3519 \end_layout
3520
3521 \begin_layout Standard
3522 \noindent
3523 and it is recommended to use the same value for 
3524 \family typewriter
3525 frame_size
3526 \family default
3527  as is used by the encoder (20 
3528 \emph on
3529 ms
3530 \emph default
3531 ).
3532 \end_layout
3533
3534 \begin_layout Standard
3535 For each input frame, you need to call:
3536 \end_layout
3537
3538 \begin_layout Standard
3539 \begin_inset listings
3540 inline false
3541 status open
3542
3543 \begin_layout Standard
3544
3545 speex_preprocess_run(preprocess_state, audio_frame);
3546 \end_layout
3547
3548 \end_inset
3549
3550
3551 \end_layout
3552
3553 \begin_layout Standard
3554 \noindent
3555 where 
3556 \family typewriter
3557 audio_frame
3558 \family default
3559  is used both as input and output.
3560  In cases where the output audio is not useful for a certain frame, it is
3561  possible to use instead:
3562 \end_layout
3563
3564 \begin_layout Standard
3565 \begin_inset listings
3566 inline false
3567 status open
3568
3569 \begin_layout Standard
3570
3571 speex_preprocess_estimate_update(preprocess_state, audio_frame);
3572 \end_layout
3573
3574 \end_inset
3575
3576
3577 \end_layout
3578
3579 \begin_layout Standard
3580 \noindent
3581 This call will update all the preprocessor internal state variables without
3582  computing the output audio, thus saving some CPU cycles.
3583 \end_layout
3584
3585 \begin_layout Standard
3586 The behaviour of the preprocessor can be changed using:
3587 \end_layout
3588
3589 \begin_layout Standard
3590 \begin_inset listings
3591 inline false
3592 status open
3593
3594 \begin_layout Standard
3595
3596 speex_preprocess_ctl(preprocess_state, request, ptr);
3597 \end_layout
3598
3599 \end_inset
3600
3601
3602 \end_layout
3603
3604 \begin_layout Standard
3605 \noindent
3606 which is used in the same way as the encoder and decoder equivalent.
3607  Options are listed in Section 
3608 \begin_inset LatexCommand ref
3609 reference "sub:Preprocessor-options"
3610
3611 \end_inset
3612
3613 .
3614 \end_layout
3615
3616 \begin_layout Standard
3617 The preprocessor state can be destroyed using:
3618 \end_layout
3619
3620 \begin_layout Standard
3621 \begin_inset listings
3622 inline false
3623 status open
3624
3625 \begin_layout Standard
3626
3627 speex_preprocess_state_destroy(preprocess_state);
3628 \end_layout
3629
3630 \end_inset
3631
3632
3633 \end_layout
3634
3635 \begin_layout Subsection
3636 Preprocessor options
3637 \begin_inset LatexCommand label
3638 name "sub:Preprocessor-options"
3639
3640 \end_inset
3641
3642
3643 \end_layout
3644
3645 \begin_layout Standard
3646 As with the codec, the preprocessor also has options that can be controlled
3647  using an ioctl()-like call.
3648  The available options are:
3649 \end_layout
3650
3651 \begin_layout Description
3652 SPEEX_PREPROCESS_SET_DENOISE Turns denoising on(1) or off(2) (
3653 \begin_inset listings
3654 inline true
3655 status collapsed
3656
3657 \begin_layout Standard
3658
3659 spx_int32_t
3660 \end_layout
3661
3662 \end_inset
3663
3664 )
3665 \end_layout
3666
3667 \begin_layout Description
3668 SPEEX_PREPROCESS_GET_DENOISE Get denoising status (
3669 \begin_inset listings
3670 inline true
3671 status collapsed
3672
3673 \begin_layout Standard
3674
3675 spx_int32_t
3676 \end_layout
3677
3678 \end_inset
3679
3680 )
3681 \end_layout
3682
3683 \begin_layout Description
3684 SPEEX_PREPROCESS_SET_AGC Turns automatic gain control (AGC) on(1) or off(2)
3685  (
3686 \begin_inset listings
3687 inline true
3688 status collapsed
3689
3690 \begin_layout Standard
3691
3692 spx_int32_t
3693 \end_layout
3694
3695 \end_inset
3696
3697 )
3698 \end_layout
3699
3700 \begin_layout Description
3701 SPEEX_PREPROCESS_GET_AGC Get AGC status (
3702 \begin_inset listings
3703 inline true
3704 status collapsed
3705
3706 \begin_layout Standard
3707
3708 spx_int32_t
3709 \end_layout
3710
3711 \end_inset
3712
3713 )
3714 \end_layout
3715
3716 \begin_layout Description
3717 SPEEX_PREPROCESS_SET_VAD Turns voice activity detector (VAD) on(1) or off(2)
3718  (
3719 \begin_inset listings
3720 inline true
3721 status collapsed
3722
3723 \begin_layout Standard
3724
3725 spx_int32_t
3726 \end_layout
3727
3728 \end_inset
3729
3730 )
3731 \end_layout
3732
3733 \begin_layout Description
3734 SPEEX_PREPROCESS_GET_VAD Get VAD status (
3735 \begin_inset listings
3736 inline true
3737 status collapsed
3738
3739 \begin_layout Standard
3740
3741 spx_int32_t
3742 \end_layout
3743
3744 \end_inset
3745
3746 )
3747 \end_layout
3748
3749 \begin_layout Description
3750 SPEEX_PREPROCESS_SET_AGC_LEVEL
3751 \end_layout
3752
3753 \begin_layout Description
3754 SPEEX_PREPROCESS_GET_AGC_LEVEL
3755 \end_layout
3756
3757 \begin_layout Description
3758 SPEEX_PREPROCESS_SET_DEREVERB Turns reverberation removal on(1) or off(2)
3759  (
3760 \begin_inset listings
3761 inline true
3762 status collapsed
3763
3764 \begin_layout Standard
3765
3766 spx_int32_t
3767 \end_layout
3768
3769 \end_inset
3770
3771 )
3772 \end_layout
3773
3774 \begin_layout Description
3775 SPEEX_PREPROCESS_GET_DEREVERB Get reverberation removal status (
3776 \begin_inset listings
3777 inline true
3778 status collapsed
3779
3780 \begin_layout Standard
3781
3782 spx_int32_t
3783 \end_layout
3784
3785 \end_inset
3786
3787 )
3788 \end_layout
3789
3790 \begin_layout Description
3791 SPEEX_PREPROCESS_SET_DEREVERB_LEVEL
3792 \end_layout
3793
3794 \begin_layout Description
3795 SPEEX_PREPROCESS_GET_DEREVERB_LEVEL
3796 \end_layout
3797
3798 \begin_layout Description
3799 SPEEX_PREPROCESS_SET_DEREVERB_DECAY
3800 \end_layout
3801
3802 \begin_layout Description
3803 SPEEX_PREPROCESS_GET_DEREVERB_DECAY
3804 \end_layout
3805
3806 \begin_layout Description
3807 SPEEX_PREPROCESS_SET_PROB_START
3808 \end_layout
3809
3810 \begin_layout Description
3811 SPEEX_PREPROCESS_GET_PROB_START
3812 \end_layout
3813
3814 \begin_layout Description
3815 SPEEX_PREPROCESS_SET_PROB_CONTINUE
3816 \end_layout
3817
3818 \begin_layout Description
3819 SPEEX_PREPROCESS_GET_PROB_CONTINUE
3820 \end_layout
3821
3822 \begin_layout Description
3823 SPEEX_PREPROCESS_SET_NOISE_SUPPRESS Set maximum attenuation of the noise
3824  in dB (negative 
3825 \begin_inset listings
3826 inline true
3827 status collapsed
3828
3829 \begin_layout Standard
3830
3831 spx_int32_t
3832 \end_layout
3833
3834 \end_inset
3835
3836 )
3837 \end_layout
3838
3839 \begin_layout Description
3840 SPEEX_PREPROCESS_GET_NOISE_SUPPRESS Get maximum attenuation of the noise
3841  in dB (negative 
3842 \begin_inset listings
3843 inline true
3844 status collapsed
3845
3846 \begin_layout Standard
3847
3848 spx_int32_t
3849 \end_layout
3850
3851 \end_inset
3852
3853 )
3854 \end_layout
3855
3856 \begin_layout Description
3857 SPEEX_PREPROCESS_SET_ECHO_SUPPRESS Set maximum attenuation of the residual
3858  echo in dB (negative 
3859 \begin_inset listings
3860 inline true
3861 status collapsed
3862
3863 \begin_layout Standard
3864
3865 spx_int32_t
3866 \end_layout
3867
3868 \end_inset
3869
3870 )
3871 \end_layout
3872
3873 \begin_layout Description
3874 SPEEX_PREPROCESS_GET_ECHO_SUPPRESS Set maximum attenuation of the residual
3875  echo in dB (negative 
3876 \begin_inset listings
3877 inline true
3878 status collapsed
3879
3880 \begin_layout Standard
3881
3882 spx_int32_t
3883 \end_layout
3884
3885 \end_inset
3886
3887 )
3888 \end_layout
3889
3890 \begin_layout Description
3891 SPEEX_PREPROCESS_SET_ECHO_SUPPRESS_ACTIVE Set maximum attenuation of the
3892  echo in dB when near end is active (negative 
3893 \begin_inset listings
3894 inline true
3895 status collapsed
3896
3897 \begin_layout Standard
3898
3899 spx_int32_t
3900 \end_layout
3901
3902 \end_inset
3903
3904 )
3905 \end_layout
3906
3907 \begin_layout Description
3908 SPEEX_PREPROCESS_GET_ECHO_SUPPRESS_ACTIVE Set maximum attenuation of the
3909  echo in dB when near end is active (negative 
3910 \begin_inset listings
3911 inline true
3912 status collapsed
3913
3914 \begin_layout Standard
3915
3916 spx_int32_t
3917 \end_layout
3918
3919 \end_inset
3920
3921 )
3922 \end_layout
3923
3924 \begin_layout Description
3925 SPEEX_PREPROCESS_SET_ECHO_STATE Set the associated echo canceller for residual
3926  echo suppression (NULL for no residual echo suppression)
3927 \end_layout
3928
3929 \begin_layout Description
3930 SPEEX_PREPROCESS_GET_ECHO_STATE Get the associated echo canceller
3931 \end_layout
3932
3933 \begin_layout Section
3934 Echo Cancellation
3935 \begin_inset LatexCommand label
3936 name "sub:Echo-Cancellation"
3937
3938 \end_inset
3939
3940
3941 \end_layout
3942
3943 \begin_layout Standard
3944 The Speex library now includes an echo cancellation
3945 \begin_inset LatexCommand index
3946 name "echo cancellation"
3947
3948 \end_inset
3949
3950  algorithm suitable for Acoustic Echo Cancellation
3951 \begin_inset LatexCommand index
3952 name "acoustic echo cancellation"
3953
3954 \end_inset
3955
3956  (AEC).
3957  In order to use the echo canceller, you first need to
3958 \end_layout
3959
3960 \begin_layout Standard
3961 \begin_inset listings
3962 inline false
3963 status open
3964
3965 \begin_layout Standard
3966
3967 #include <speex/speex_echo.h>
3968 \end_layout
3969
3970 \end_inset
3971
3972
3973 \end_layout
3974
3975 \begin_layout Standard
3976 Then, an echo canceller state can be created by:
3977 \end_layout
3978
3979 \begin_layout Standard
3980 \begin_inset listings
3981 inline false
3982 status open
3983
3984 \begin_layout Standard
3985
3986 SpeexEchoState *echo_state = speex_echo_state_init(frame_size, filter_length);
3987 \end_layout
3988
3989 \end_inset
3990
3991
3992 \end_layout
3993
3994 \begin_layout Standard
3995 where 
3996 \family typewriter
3997 frame_size
3998 \family default
3999  is the amount of data (in samples) you want to process at once and 
4000 \family typewriter
4001 filter_length
4002 \family default
4003  is the length (in samples) of the echo cancelling filter you want to use
4004  (also known as 
4005 \shape italic
4006 tail length
4007 \shape default
4008
4009 \begin_inset LatexCommand index
4010 name "tail length"
4011
4012 \end_inset
4013
4014 ).
4015  It is recommended to use a frame size in the order of 20 ms (or equal to
4016  the codec frame size) and make sure it is easy to perform an FFT of that
4017  size (powers of two are better than prime sizes).
4018  The recommended tail length is approximately the third of the room reverberatio
4019 n time.
4020  For example, in a small room, reverberation time is in the order of 300
4021  ms, so a tail length of 100 ms is a good choice (800 samples at 8000 Hz
4022  sampling rate).
4023 \end_layout
4024
4025 \begin_layout Standard
4026 Once the echo canceller state is created, audio can be processed by:
4027 \end_layout
4028
4029 \begin_layout Standard
4030 \begin_inset listings
4031 inline false
4032 status open
4033
4034 \begin_layout Standard
4035
4036 speex_echo_cancellation(echo_state, input_frame, echo_frame, output_frame);
4037 \end_layout
4038
4039 \end_inset
4040
4041
4042 \end_layout
4043
4044 \begin_layout Standard
4045 where 
4046 \family typewriter
4047 input_frame
4048 \family default
4049  is the audio as captured by the microphone, 
4050 \family typewriter
4051 echo_frame
4052 \family default
4053  is the signal that was played in the speaker (and needs to be removed)
4054  and 
4055 \family typewriter
4056 output_frame
4057 \family default
4058  is the signal with echo removed.
4059  
4060 \end_layout
4061
4062 \begin_layout Standard
4063 One important thing to keep in mind is the relationship between 
4064 \family typewriter
4065 input_frame
4066 \family default
4067  and 
4068 \family typewriter
4069 echo_frame
4070 \family default
4071 .
4072  It is important that, at any time, any echo that is present in the input
4073  has already been sent to the echo canceller as 
4074 \family typewriter
4075 echo_frame
4076 \family default
4077 .
4078  In other words, the echo canceller cannot remove a signal that it hasn't
4079  yet received.
4080  On the other hand, the delay between the input signal and the echo signal
4081  must be small enough because otherwise part of the echo cancellation filter
4082  is inefficient.
4083  In the ideal case, you code would look like:
4084 \begin_inset listings
4085 lstparams "breaklines=true"
4086 inline false
4087 status open
4088
4089 \begin_layout Standard
4090
4091 write_to_soundcard(echo_frame, frame_size);
4092 \end_layout
4093
4094 \begin_layout Standard
4095
4096 read_from_soundcard(input_frame, frame_size);
4097 \end_layout
4098
4099 \begin_layout Standard
4100
4101 speex_echo_cancellation(echo_state, input_frame, echo_frame, output_frame);
4102 \end_layout
4103
4104 \end_inset
4105
4106
4107 \end_layout
4108
4109 \begin_layout Standard
4110 If you wish to further reduce the echo present in the signal, you can do
4111  so by associating the echo canceller to the preprocessor (see Section 
4112 \begin_inset LatexCommand ref
4113 reference "sub:Preprocessor"
4114
4115 \end_inset
4116
4117 ).
4118  This is done by calling:
4119 \begin_inset listings
4120 lstparams "breaklines=true"
4121 inline false
4122 status open
4123
4124 \begin_layout Standard
4125
4126 speex_preprocess_ctl(preprocess_state, SPEEX_PREPROCESS_SET_ECHO_STATE,echo_stat
4127 e);
4128 \end_layout
4129
4130 \end_inset
4131
4132 in the initialisation.
4133 \end_layout
4134
4135 \begin_layout Standard
4136 As of version 1.2-beta2, there is an alternative, simpler API that can be
4137  used instead of 
4138 \emph on
4139 speex_echo_cancellation()
4140 \emph default
4141 .
4142  When audio capture and playback are handled asynchronously (e.g.
4143  in different threads or using the 
4144 \emph on
4145 poll()
4146 \emph default
4147  or 
4148 \emph on
4149 select()
4150 \emph default
4151  system call), it can be difficult to keep track of what input_frame comes
4152  with what echo_frame.
4153  Instead, the playback comtext/thread can simply call:
4154 \end_layout
4155
4156 \begin_layout Standard
4157 \begin_inset listings
4158 inline false
4159 status open
4160
4161 \begin_layout Standard
4162
4163 speex_echo_playback(echo_state, echo_frame);
4164 \end_layout
4165
4166 \end_inset
4167
4168
4169 \end_layout
4170
4171 \begin_layout Standard
4172 every time an audio frame is played.
4173  Then, the capture context/thread calls:
4174 \end_layout
4175
4176 \begin_layout Standard
4177 \begin_inset listings
4178 inline false
4179 status open
4180
4181 \begin_layout Standard
4182
4183 speex_echo_capture(echo_state, input_frame, output_frame);
4184 \end_layout
4185
4186 \end_inset
4187
4188
4189 \end_layout
4190
4191 \begin_layout Standard
4192 for every frame captured.
4193  Internally, 
4194 \emph on
4195 speex_echo_playback()
4196 \emph default
4197  simply buffers the playback frame so it can be used by 
4198 \emph on
4199 speex_echo_capture()
4200 \emph default
4201  to call 
4202 \emph on
4203 speex_echo_cancel()
4204 \emph default
4205 .
4206  A side effect of using this alternate API is that the playback audio is
4207  delayed by two frames, which is the normal delay caused by the soundcard.
4208  When capture and playback are already synchronised, 
4209 \emph on
4210 speex_echo_cancellation()
4211 \emph default
4212  is preferable since it gives better control on the exact input/echo timing.
4213 \end_layout
4214
4215 \begin_layout Standard
4216 The echo cancellation state can be destroyed with:
4217 \end_layout
4218
4219 \begin_layout Standard
4220 \begin_inset listings
4221 inline false
4222 status open
4223
4224 \begin_layout Standard
4225
4226 speex_echo_state_destroy(echo_state);
4227 \end_layout
4228
4229 \end_inset
4230
4231
4232 \end_layout
4233
4234 \begin_layout Standard
4235 It is also possible to reset the state of the echo canceller so it can be
4236  reused without the need to create another state with:
4237 \end_layout
4238
4239 \begin_layout Standard
4240 \begin_inset listings
4241 inline false
4242 status open
4243
4244 \begin_layout Standard
4245
4246 speex_echo_state_reset(echo_state);
4247 \end_layout
4248
4249 \end_inset
4250
4251
4252 \end_layout
4253
4254 \begin_layout Subsection
4255 Troubleshooting
4256 \end_layout
4257
4258 \begin_layout Standard
4259 There are several things that may prevent the echo canceller from working
4260  properly.
4261  One of them is a bug (or something suboptimal) in the code, but there are
4262  many others you should consider first
4263 \end_layout
4264
4265 \begin_layout Itemize
4266 Using a different soundcard to do the capture and plaback will 
4267 \series bold
4268 not
4269 \series default
4270  work, regardless of what you may think.
4271  The only exception to that is if the two cards can be made to have their
4272  sampling clock 
4273 \begin_inset Quotes eld
4274 \end_inset
4275
4276 locked
4277 \begin_inset Quotes erd
4278 \end_inset
4279
4280  on the same clock source.
4281  If not, the clocks will always have a small amount of drift, which will
4282  prevent the echo canceller from adapting.
4283 \end_layout
4284
4285 \begin_layout Itemize
4286 The delay between the record and playback signals must be minimal.
4287  Any signal played has to 
4288 \begin_inset Quotes eld
4289 \end_inset
4290
4291 appear
4292 \begin_inset Quotes erd
4293 \end_inset
4294
4295  on the playback (far end) signal slightly before the echo canceller 
4296 \begin_inset Quotes eld
4297 \end_inset
4298
4299 sees
4300 \begin_inset Quotes erd
4301 \end_inset
4302
4303  it in the near end signal, but excessive delay means that part of the filter
4304  length is wasted.
4305  In the worst situations, the delay is such that it is longer than the filter
4306  length, in which case, no echo can be cancelled.
4307 \end_layout
4308
4309 \begin_layout Itemize
4310 When it comes to echo tail length (filter length), longer is *not* better.
4311  Actually, the longer the tail length, the longer it takes for the filter
4312  to adapt.
4313  Of course, a tail length that is too short will not cancel enough echo,
4314  but the most common problem seen is that people set a very long tail length
4315  and then wonder why no echo is being cancelled.
4316 \end_layout
4317
4318 \begin_layout Itemize
4319 Non-linear distortion cannot (by definition) be modeled by the linear adaptive
4320  filter used in the echo canceller and thus cannot be cancelled.
4321  Use good audio gear and avoid saturation/clipping.
4322 \end_layout
4323
4324 \begin_layout Standard
4325 Also useful is reading 
4326 \emph on
4327 Echo Cancellation Demystified
4328 \emph default
4329  by Alexey Frunze
4330 \begin_inset Foot
4331 status collapsed
4332
4333 \begin_layout Standard
4334 http://www.embeddedstar.com/articles/2003/7/article20030720-1.html
4335 \end_layout
4336
4337 \end_inset
4338
4339 , which explains the fundamental principles of echo cancellation.
4340  The details of the algorithm described in the article are different, but
4341  the general ideas of echo cancellation through adaptive filters are the
4342  same.
4343 \end_layout
4344
4345 \begin_layout Standard
4346 As of version 1.2beta2, a new 
4347 \family typewriter
4348 echo_diagnostic.m
4349 \family default
4350  tool is included in the source distribution.
4351  The first step is to define DUMP_ECHO_CANCEL_DATA during the build.
4352  This causes the echo canceller to automatically save the near-end, far-end
4353  and output signals to files (aec_rec.sw aec_play.sw and aec_out.sw).
4354  These are exactly what the AEC receives and outputs.
4355  From there, it is necessary to start Octave and type:
4356 \end_layout
4357
4358 \begin_layout Standard
4359 \begin_inset listings
4360 lstparams "language=Matlab"
4361 inline false
4362 status open
4363
4364 \begin_layout Standard
4365
4366 echo_diagnostic('aec_rec.sw', 'aec_play.sw', 'aec_diagnostic.sw', 1024);
4367 \end_layout
4368
4369 \end_inset
4370
4371
4372 \end_layout
4373
4374 \begin_layout Standard
4375 The value of 1024 is the filter length and can be changed.
4376  There will be some (hopefully) useful messages printed and echo cancelled
4377  audio will be saved to aec_diagnostic.sw .
4378  If even that output is bad (almost no cancellation) then there is  probably
4379  problem with the playback or recording process.
4380 \end_layout
4381
4382 \begin_layout Section
4383 Jitter Buffer
4384 \end_layout
4385
4386 \begin_layout Standard
4387 The jitter buffer can be enabled by including:
4388 \begin_inset listings
4389 lstparams "breaklines=true"
4390 inline false
4391 status open
4392
4393 \begin_layout Standard
4394
4395 #include <speex/speex_jitter.h>
4396 \end_layout
4397
4398 \end_inset
4399
4400  and a new jitter buffer state can be initialised by:
4401 \end_layout
4402
4403 \begin_layout Standard
4404 \begin_inset listings
4405 lstparams "breaklines=true"
4406 inline false
4407 status open
4408
4409 \begin_layout Standard
4410
4411 JitterBuffer *state = jitter_buffer_init(tick);
4412 \end_layout
4413
4414 \end_inset
4415
4416
4417 \end_layout
4418
4419 \begin_layout Standard
4420 where the 
4421 \begin_inset listings
4422 inline true
4423 status collapsed
4424
4425 \begin_layout Standard
4426
4427 tick
4428 \end_layout
4429
4430 \end_inset
4431
4432  argument is the time resolution (in timestamp units) used for the jitter
4433  buffer, and is generally the period at which the data is played out of
4434  the jitter buffer.
4435  
4436 \end_layout
4437
4438 \begin_layout Standard
4439 The jitter buffer API is based on the 
4440 \begin_inset listings
4441 inline true
4442 status open
4443
4444 \begin_layout Standard
4445
4446 JitterBufferPacket
4447 \end_layout
4448
4449 \end_inset
4450
4451  type, which is defined as:
4452 \begin_inset listings
4453 inline false
4454 status open
4455
4456 \begin_layout Standard
4457
4458 typedef struct {
4459 \end_layout
4460
4461 \begin_layout Standard
4462
4463    char        *data;       /* Data bytes contained in the packet */
4464 \end_layout
4465
4466 \begin_layout Standard
4467
4468    spx_uint32_t len;        /* Length of the packet in bytes */
4469 \end_layout
4470
4471 \begin_layout Standard
4472
4473    spx_uint32_t timestamp;  /* Timestamp for the packet */
4474 \end_layout
4475
4476 \begin_layout Standard
4477
4478    spx_uint32_t span;       /* Time covered by the packet (timestamp units)
4479  */
4480 \end_layout
4481
4482 \begin_layout Standard
4483
4484 } JitterBufferPacket; 
4485 \end_layout
4486
4487 \end_inset
4488
4489
4490 \end_layout
4491
4492 \begin_layout Standard
4493 When a packet arrives, it need to be inserter into the jitter buffer by:
4494 \begin_inset listings
4495 inline false
4496 status open
4497
4498 \begin_layout Standard
4499
4500 JitterBufferPacket packet;
4501 \end_layout
4502
4503 \begin_layout Standard
4504
4505 /* Fill in the packet fields */
4506 \end_layout
4507
4508 \begin_layout Standard
4509
4510 jitter_buffer_put(state, &packet);
4511 \end_layout
4512
4513 \end_inset
4514
4515
4516 \end_layout
4517
4518 \begin_layout Standard
4519 When the decoder is ready to decode a packet the packet to be decoded can
4520  be obtained by: 
4521 \begin_inset listings
4522 inline false
4523 status open
4524
4525 \begin_layout Standard
4526
4527 int start_offset;
4528 \end_layout
4529
4530 \begin_layout Standard
4531
4532 err = jitter_buffer_get(state, &packet, &start_offset);
4533 \end_layout
4534
4535 \end_inset
4536
4537
4538 \end_layout
4539
4540 \begin_layout Standard
4541 If 
4542 \begin_inset listings
4543 inline true
4544 status open
4545
4546 \begin_layout Standard
4547
4548 jitter_buffer_put()
4549 \end_layout
4550
4551 \end_inset
4552
4553  and 
4554 \begin_inset listings
4555 inline true
4556 status open
4557
4558 \begin_layout Standard
4559
4560 jitter_buffer_get()
4561 \end_layout
4562
4563 \end_inset
4564
4565  are called from different threads, then 
4566 \series bold
4567 you need to protect the jitter buffer state with a mutex
4568 \series default
4569 .
4570  
4571 \end_layout
4572
4573 \begin_layout Standard
4574 Because the jitter buffer is designed not to use an explicit timer, it needs
4575  to be told about the time explicitly.
4576  This is done by calling: 
4577 \begin_inset listings
4578 inline false
4579 status open
4580
4581 \begin_layout Standard
4582
4583 jitter_buffer_tick(state);
4584 \end_layout
4585
4586 \end_inset
4587
4588
4589 \end_layout
4590
4591 \begin_layout Standard
4592 This needs to be done every time 
4593 \begin_inset listings
4594 inline true
4595 status collapsed
4596
4597 \begin_layout Standard
4598
4599 tick
4600 \end_layout
4601
4602 \end_inset
4603
4604  units have elapsed.
4605  
4606 \end_layout
4607
4608 \begin_layout Section
4609 Resampler
4610 \end_layout
4611
4612 \begin_layout Standard
4613 Speex includes a resampling modules.
4614  To make use of the resampler, it is necessary to include its header file:
4615 \end_layout
4616
4617 \begin_layout Standard
4618 \begin_inset listings
4619 inline false
4620 status open
4621
4622 \begin_layout Standard
4623
4624 #include <speex/speex_resampler.h>
4625 \end_layout
4626
4627 \end_inset
4628
4629
4630 \end_layout
4631
4632 \begin_layout Standard
4633 For each stream that is to be resampled, it is necessary to create a resampler
4634  state with:
4635 \end_layout
4636
4637 \begin_layout Standard
4638 \begin_inset listings
4639 inline false
4640 status open
4641
4642 \begin_layout Standard
4643
4644 SpeexResamplerState *resampler;
4645 \end_layout
4646
4647 \begin_layout Standard
4648
4649 resampler = speex_resampler_init(nb_channels, input_rate, output_rate, quality,
4650  &err);
4651 \end_layout
4652
4653 \end_inset
4654
4655
4656 \end_layout
4657
4658 \begin_layout Standard
4659 where nb_channels is the number of channels that will be used (either interleave
4660 d or non-interleaved), input_rate is the sampling rate of the input stream,
4661  output_rate is the sampling rate of the output stream and quality is the
4662  requested quality setting (0 to 10).
4663  The quality parameter is useful for controlling the quality/complexity/latency
4664  tradeoff.
4665  Using a higher quality setting means less noise/aliasing, a higher complexity
4666  and a higher latency.
4667  Usually, a quality of 3 is acceptable for most desktop uses and quality
4668  10 is mostly recommended for pro audio work.
4669  Quality 0 usually has a decent sound (certainly better than using linear
4670  interpolation resampling), but artifacts may be heard.
4671 \end_layout
4672
4673 \begin_layout Standard
4674 The actual resampling is performed using
4675 \end_layout
4676
4677 \begin_layout Standard
4678 \begin_inset listings
4679 inline false
4680 status open
4681
4682 \begin_layout Standard
4683
4684 err = speex_resampler_process_int(resampler, channelID, in, &in_length,
4685  out, &out_length);
4686 \end_layout
4687
4688 \end_inset
4689
4690 where channelID is the ID of the channel to be processed.
4691  For a mono stream, use 0.
4692  The 
4693 \emph on
4694 in
4695 \emph default
4696  pointer points to the first sample of the input buffer for the selected
4697  channel and 
4698 \emph on
4699 out
4700 \emph default
4701  points to the first sample of the output.
4702  The size of the input and output buffers are specified by 
4703 \emph on
4704 in_length
4705 \emph default
4706  and 
4707 \emph on
4708 out_length
4709 \emph default
4710  respectively.
4711  Upon completion, these values are replaced by the number of samples read
4712  and written by the resampler.
4713  Unless an error occurs, either all input samples will be read or all output
4714  samples will be written to (or both).
4715  For floating-point samples, the function speex_resampler_process_float()
4716  behaves similarly.
4717 \end_layout
4718
4719 \begin_layout Standard
4720 It is also possible to process multiple channels at once.
4721  
4722 \end_layout
4723
4724 \begin_layout Section
4725 Ring Buffer
4726 \end_layout
4727
4728 \begin_layout Standard
4729 Put some stuff there...
4730 \end_layout
4731
4732 \begin_layout Standard
4733
4734 \newpage
4735
4736 \end_layout
4737
4738 \begin_layout Chapter
4739 Formats and standards
4740 \begin_inset LatexCommand index
4741 name "standards"
4742
4743 \end_inset
4744
4745
4746 \begin_inset LatexCommand label
4747 name "sec:Formats-and-standards"
4748
4749 \end_inset
4750
4751
4752 \end_layout
4753
4754 \begin_layout Standard
4755 Speex can encode speech in both narrowband and wideband and provides different
4756  bit-rates.
4757  However, not all features need to be supported by a certain implementation
4758  or device.
4759  In order to be called 
4760 \begin_inset Quotes eld
4761 \end_inset
4762
4763 Speex compatible
4764 \begin_inset Quotes erd
4765 \end_inset
4766
4767  (whatever that means), an implementation must implement at least a basic
4768  set of features.
4769 \end_layout
4770
4771 \begin_layout Standard
4772 At the minimum, all narrowband modes of operation MUST be supported at the
4773  decoder.
4774  This includes the decoding of a wideband bit-stream by the narrowband decoder
4775 \begin_inset Foot
4776 status collapsed
4777
4778 \begin_layout Standard
4779 The wideband bit-stream contains an embedded narrowband bit-stream which
4780  can be decoded alone
4781 \end_layout
4782
4783 \end_inset
4784
4785 .
4786  If present, a wideband decoder MUST be able to decode a narrowband stream,
4787  and MAY either be able to decode all wideband modes or be able to decode
4788  the embedded narrowband part of all modes (which includes ignoring the
4789  high-band bits).
4790 \end_layout
4791
4792 \begin_layout Standard
4793 For encoders, at least one narrowband or wideband mode MUST be supported.
4794  The main reason why all encoding modes do not have to be supported is that
4795  some platforms may not be able to handle the complexity of encoding in
4796  some modes.
4797 \end_layout
4798
4799 \begin_layout Section
4800 RTP
4801 \begin_inset LatexCommand index
4802 name "RTP"
4803
4804 \end_inset
4805
4806  Payload Format 
4807 \end_layout
4808
4809 \begin_layout Standard
4810 The RTP payload draft is included in appendix 
4811 \begin_inset LatexCommand ref
4812 reference "sec:IETF-draft"
4813
4814 \end_inset
4815
4816  and the latest version is available at 
4817 \begin_inset LatexCommand url
4818 target "http://www.speex.org/drafts/latest"
4819
4820 \end_inset
4821
4822 .
4823  This draft has been sent (2003/02/26) to the Internet Engineering Task
4824  Force (IETF) and will be discussed at the March 18th meeting in San Francisco.
4825  
4826 \end_layout
4827
4828 \begin_layout Section
4829 MIME Type
4830 \end_layout
4831
4832 \begin_layout Standard
4833 For now, you should use the MIME type audio/x-speex for Speex-in-Ogg.
4834  We will apply for type 
4835 \family typewriter
4836 audio/speex
4837 \family default
4838  in the near future.
4839 \end_layout
4840
4841 \begin_layout Section
4842 Ogg
4843 \begin_inset LatexCommand index
4844 name "Ogg"
4845
4846 \end_inset
4847
4848  file format
4849 \end_layout
4850
4851 \begin_layout Standard
4852 Speex bit-streams can be stored in Ogg files.
4853  In this case, the first packet of the Ogg file contains the Speex header
4854  described in table 
4855 \begin_inset LatexCommand ref
4856 reference "cap:ogg_speex_header"
4857
4858 \end_inset
4859
4860 .
4861  All integer fields in the headers are stored as little-endian.
4862  The 
4863 \family typewriter
4864 speex_string
4865 \family default
4866  field must contain the 
4867 \begin_inset Quotes eld
4868 \end_inset
4869
4870
4871 \family typewriter
4872 Speex
4873 \family default
4874 \InsetSpace ~
4875 \InsetSpace ~
4876 \InsetSpace ~
4877
4878 \begin_inset Quotes erd
4879 \end_inset
4880
4881  (with 3 trailing spaces), which identifies the bit-stream.
4882  The next field, 
4883 \family typewriter
4884 speex_version
4885 \family default
4886  contains the version of Speex that encoded the file.
4887  For now, refer to speex_header.[ch] for more info.
4888  The 
4889 \emph on
4890 beginning of stream
4891 \emph default
4892  (
4893 \family typewriter
4894 b_o_s
4895 \family default
4896 ) flag is set to 1 for the header.
4897  The header packet has 
4898 \family typewriter
4899 packetno=0
4900 \family default
4901  and 
4902 \family typewriter
4903 granulepos=0
4904 \family default
4905 .
4906 \end_layout
4907
4908 \begin_layout Standard
4909 The second packet contains the Speex comment header.
4910  The format used is the Vorbis comment format described here: http://www.xiph.org/
4911 ogg/vorbis/doc/v-comment.html .
4912  This packet has 
4913 \family typewriter
4914 packetno=1
4915 \family default
4916  and 
4917 \family typewriter
4918 granulepos=0
4919 \family default
4920 .
4921 \end_layout
4922
4923 \begin_layout Standard
4924 The third and subsequent packets each contain one or more (number found
4925  in header) Speex frames.
4926  These are identified with 
4927 \family typewriter
4928 packetno
4929 \family default
4930  starting from 2 and the 
4931 \family typewriter
4932 granulepos
4933 \family default
4934  is the number of the last sample encoded in that packet.
4935  The last of these packets has the 
4936 \emph on
4937 end of stream
4938 \emph default
4939  (
4940 \family typewriter
4941 e_o_s
4942 \family default
4943 ) flag is set to 1.
4944 \end_layout
4945
4946 \begin_layout Standard
4947 \begin_inset Float table
4948 placement htbp
4949 wide true
4950 sideways false
4951 status open
4952
4953 \begin_layout Standard
4954 \begin_inset ERT
4955 status collapsed
4956
4957 \begin_layout Standard
4958
4959
4960 \backslash
4961 begin{center}
4962 \end_layout
4963
4964 \end_inset
4965
4966
4967 \begin_inset Tabular
4968 <lyxtabular version="3" rows="16" columns="3">
4969 <features>
4970 <column alignment="center" valignment="top" leftline="true" width="0pt">
4971 <column alignment="center" valignment="top" leftline="true" width="0pt">
4972 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
4973 <row topline="true" bottomline="true">
4974 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4975 \begin_inset Text
4976
4977 \begin_layout Standard
4978 Field
4979 \end_layout
4980
4981 \end_inset
4982 </cell>
4983 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4984 \begin_inset Text
4985
4986 \begin_layout Standard
4987 Type
4988 \end_layout
4989
4990 \end_inset
4991 </cell>
4992 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4993 \begin_inset Text
4994
4995 \begin_layout Standard
4996 Size
4997 \end_layout
4998
4999 \end_inset
5000 </cell>
5001 </row>
5002 <row topline="true">
5003 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5004 \begin_inset Text
5005
5006 \begin_layout Standard
5007 speex_string
5008 \end_layout
5009
5010 \end_inset
5011 </cell>
5012 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5013 \begin_inset Text
5014
5015 \begin_layout Standard
5016 char[]
5017 \end_layout
5018
5019 \end_inset
5020 </cell>
5021 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5022 \begin_inset Text
5023
5024 \begin_layout Standard
5025 8
5026 \end_layout
5027
5028 \end_inset
5029 </cell>
5030 </row>
5031 <row topline="true">
5032 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5033 \begin_inset Text
5034
5035 \begin_layout Standard
5036 speex_version
5037 \end_layout
5038
5039 \end_inset
5040 </cell>
5041 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5042 \begin_inset Text
5043
5044 \begin_layout Standard
5045 char[]
5046 \end_layout
5047
5048 \end_inset
5049 </cell>
5050 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5051 \begin_inset Text
5052
5053 \begin_layout Standard
5054 20
5055 \end_layout
5056
5057 \end_inset
5058 </cell>
5059 </row>
5060 <row topline="true">
5061 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5062 \begin_inset Text
5063
5064 \begin_layout Standard
5065 speex_version_id
5066 \end_layout
5067
5068 \end_inset
5069 </cell>
5070 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5071 \begin_inset Text
5072
5073 \begin_layout Standard
5074 int
5075 \end_layout
5076
5077 \end_inset
5078 </cell>
5079 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5080 \begin_inset Text
5081
5082 \begin_layout Standard
5083 4
5084 \end_layout
5085
5086 \end_inset
5087 </cell>
5088 </row>
5089 <row topline="true">
5090 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5091 \begin_inset Text
5092
5093 \begin_layout Standard
5094 header_size
5095 \end_layout
5096
5097 \end_inset
5098 </cell>
5099 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5100 \begin_inset Text
5101
5102 \begin_layout Standard
5103 int
5104 \end_layout
5105
5106 \end_inset
5107 </cell>
5108 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5109 \begin_inset Text
5110
5111 \begin_layout Standard
5112 4
5113 \end_layout
5114
5115 \end_inset
5116 </cell>
5117 </row>
5118 <row topline="true">
5119 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5120 \begin_inset Text
5121
5122 \begin_layout Standard
5123 rate
5124 \end_layout
5125
5126 \end_inset
5127 </cell>
5128 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5129 \begin_inset Text
5130
5131 \begin_layout Standard
5132 int
5133 \end_layout
5134
5135 \end_inset
5136 </cell>
5137 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5138 \begin_inset Text
5139
5140 \begin_layout Standard
5141 4
5142 \end_layout
5143
5144 \end_inset
5145 </cell>
5146 </row>
5147 <row topline="true">
5148 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5149 \begin_inset Text
5150
5151 \begin_layout Standard
5152 mode
5153 \end_layout
5154
5155 \end_inset
5156 </cell>
5157 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5158 \begin_inset Text
5159
5160 \begin_layout Standard
5161 int
5162 \end_layout
5163
5164 \end_inset
5165 </cell>
5166 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5167 \begin_inset Text
5168
5169 \begin_layout Standard
5170 4
5171 \end_layout
5172
5173 \end_inset
5174 </cell>
5175 </row>
5176 <row topline="true">
5177 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5178 \begin_inset Text
5179
5180 \begin_layout Standard
5181 mode_bitstream_version
5182 \end_layout
5183
5184 \end_inset
5185 </cell>
5186 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5187 \begin_inset Text
5188
5189 \begin_layout Standard
5190 int
5191 \end_layout
5192
5193 \end_inset
5194 </cell>
5195 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5196 \begin_inset Text
5197
5198 \begin_layout Standard
5199 4
5200 \end_layout
5201
5202 \end_inset
5203 </cell>
5204 </row>
5205 <row topline="true">
5206 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5207 \begin_inset Text
5208
5209 \begin_layout Standard
5210 nb_channels
5211 \end_layout
5212
5213 \end_inset
5214 </cell>
5215 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5216 \begin_inset Text
5217
5218 \begin_layout Standard
5219 int
5220 \end_layout
5221
5222 \end_inset
5223 </cell>
5224 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5225 \begin_inset Text
5226
5227 \begin_layout Standard
5228 4
5229 \end_layout
5230
5231 \end_inset
5232 </cell>
5233 </row>
5234 <row topline="true">
5235 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5236 \begin_inset Text
5237
5238 \begin_layout Standard
5239 bitrate
5240 \end_layout
5241
5242 \end_inset
5243 </cell>
5244 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5245 \begin_inset Text
5246
5247 \begin_layout Standard
5248 int
5249 \end_layout
5250
5251 \end_inset
5252 </cell>
5253 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5254 \begin_inset Text
5255
5256 \begin_layout Standard
5257 4
5258 \end_layout
5259
5260 \end_inset
5261 </cell>
5262 </row>
5263 <row topline="true">
5264 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5265 \begin_inset Text
5266
5267 \begin_layout Standard
5268 frame_size
5269 \end_layout
5270
5271 \end_inset
5272 </cell>
5273 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5274 \begin_inset Text
5275
5276 \begin_layout Standard
5277 int
5278 \end_layout
5279
5280 \end_inset
5281 </cell>
5282 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5283 \begin_inset Text
5284
5285 \begin_layout Standard
5286 4
5287 \end_layout
5288
5289 \end_inset
5290 </cell>
5291 </row>
5292 <row topline="true">
5293 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5294 \begin_inset Text
5295
5296 \begin_layout Standard
5297 vbr
5298 \end_layout
5299
5300 \end_inset
5301 </cell>
5302 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5303 \begin_inset Text
5304
5305 \begin_layout Standard
5306 int
5307 \end_layout
5308
5309 \end_inset
5310 </cell>
5311 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5312 \begin_inset Text
5313
5314 \begin_layout Standard
5315 4
5316 \end_layout
5317
5318 \end_inset
5319 </cell>
5320 </row>
5321 <row topline="true">
5322 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5323 \begin_inset Text
5324
5325 \begin_layout Standard
5326 frames_per_packet
5327 \end_layout
5328
5329 \end_inset
5330 </cell>
5331 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5332 \begin_inset Text
5333
5334 \begin_layout Standard
5335 int
5336 \end_layout
5337
5338 \end_inset
5339 </cell>
5340 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5341 \begin_inset Text
5342
5343 \begin_layout Standard
5344 4
5345 \end_layout
5346
5347 \end_inset
5348 </cell>
5349 </row>
5350 <row topline="true">
5351 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5352 \begin_inset Text
5353
5354 \begin_layout Standard
5355 extra_headers
5356 \end_layout
5357
5358 \end_inset
5359 </cell>
5360 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5361 \begin_inset Text
5362
5363 \begin_layout Standard
5364 int
5365 \end_layout
5366
5367 \end_inset
5368 </cell>
5369 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5370 \begin_inset Text
5371
5372 \begin_layout Standard
5373 4
5374 \end_layout
5375
5376 \end_inset
5377 </cell>
5378 </row>
5379 <row topline="true">
5380 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5381 \begin_inset Text
5382
5383 \begin_layout Standard
5384 reserved1
5385 \end_layout
5386
5387 \end_inset
5388 </cell>
5389 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5390 \begin_inset Text
5391
5392 \begin_layout Standard
5393 int
5394 \end_layout
5395
5396 \end_inset
5397 </cell>
5398 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5399 \begin_inset Text
5400
5401 \begin_layout Standard
5402 4
5403 \end_layout
5404
5405 \end_inset
5406 </cell>
5407 </row>
5408 <row topline="true" bottomline="true">
5409 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5410 \begin_inset Text
5411
5412 \begin_layout Standard
5413 reserved2
5414 \end_layout
5415
5416 \end_inset
5417 </cell>
5418 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5419 \begin_inset Text
5420
5421 \begin_layout Standard
5422 int
5423 \end_layout
5424
5425 \end_inset
5426 </cell>
5427 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5428 \begin_inset Text
5429
5430 \begin_layout Standard
5431 4
5432 \end_layout
5433
5434 \end_inset
5435 </cell>
5436 </row>
5437 </lyxtabular>
5438
5439 \end_inset
5440
5441
5442 \begin_inset ERT
5443 status collapsed
5444
5445 \begin_layout Standard
5446
5447
5448 \backslash
5449 end{center}
5450 \end_layout
5451
5452 \end_inset
5453
5454
5455 \end_layout
5456
5457 \begin_layout Standard
5458 \begin_inset Caption
5459
5460 \begin_layout Standard
5461 Ogg/Speex header packet
5462 \begin_inset LatexCommand label
5463 name "cap:ogg_speex_header"
5464
5465 \end_inset
5466
5467
5468 \end_layout
5469
5470 \end_inset
5471
5472
5473 \end_layout
5474
5475 \end_inset
5476
5477
5478 \end_layout
5479
5480 \begin_layout Standard
5481 \begin_inset ERT
5482 status collapsed
5483
5484 \begin_layout Standard
5485
5486
5487 \backslash
5488 clearpage
5489 \end_layout
5490
5491 \end_inset
5492
5493
5494 \end_layout
5495
5496 \begin_layout Chapter
5497 Introduction to CELP Coding
5498 \begin_inset LatexCommand index
5499 name "CELP"
5500
5501 \end_inset
5502
5503
5504 \begin_inset LatexCommand label
5505 name "sec:Introduction-to-CELP"
5506
5507 \end_inset
5508
5509
5510 \end_layout
5511
5512 \begin_layout Quote
5513 \align center
5514
5515 \emph on
5516 Do not meddle in the affairs of poles, for they are subtle and quick to
5517  leave the unit circle.
5518 \end_layout
5519
5520 \begin_layout Standard
5521 Speex is based on CELP, which stands for Code Excited Linear Prediction.
5522  This section attempts to introduce the principles behind CELP, so if you
5523  are already familiar with CELP, you can safely skip to section 
5524 \begin_inset LatexCommand ref
5525 reference "sec:Speex-narrowband-mode"
5526
5527 \end_inset
5528
5529 .
5530  The CELP technique is based on three ideas:
5531 \end_layout
5532
5533 \begin_layout Enumerate
5534 The use of a linear prediction (LP) model to model the vocal tract
5535 \end_layout
5536
5537 \begin_layout Enumerate
5538 The use of (adaptive and fixed) codebook entries as input (excitation) of
5539  the LP model
5540 \end_layout
5541
5542 \begin_layout Enumerate
5543 The search performed in closed-loop in a 
5544 \begin_inset Quotes eld
5545 \end_inset
5546
5547 perceptually weighted domain
5548 \begin_inset Quotes erd
5549 \end_inset
5550
5551
5552 \end_layout
5553
5554 \begin_layout Standard
5555 This section describes the basic ideas behind CELP.
5556  This is still a work in progress.
5557 \end_layout
5558
5559 \begin_layout Section
5560 Source-Filter Model of Speech Prediction
5561 \end_layout
5562
5563 \begin_layout Standard
5564 The source-filter model of speech production assumes that the vocal cords
5565  are the source of spectrally flat sound (the excitation signal), and that
5566  the vocal tract acts as a filter to spectrally shape the various sounds
5567  of speech.
5568  While still an approximation, the model is widely used in speech coding
5569  because of its simplicity.Its use is also the reason why most speech codecs
5570  (Speex included) perform badly on music signals.
5571  The different phonemes can be distinguished by their excitation (source)
5572  and spectral shape (filter).
5573  Voiced sounds (e.g.
5574  vowels) have an excitation signal that is periodic and that can be approximated
5575  by an impulse train in the time domain or by regularly-spaced harmonics
5576  in the frequency domain.
5577  On the other hand, fricatives (such as the "s", "sh" and "f" sounds) have
5578  an excitation signal that is similar to white Gaussian noise.
5579  So called voice fricatives (such as "z" and "v") have excitation signal
5580  composed of an harmonic part and a noisy part.
5581 \end_layout
5582
5583 \begin_layout Standard