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