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