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