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