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