oops...
[speexdsp.git] / doc / manual.lyx
1 #LyX 1.5.0 created this file. For more info see http://www.lyx.org/
2 \lyxformat 276
3 \begin_document
4 \begin_header
5 \textclass scrbook
6 \language english
7 \inputencoding auto
8 \font_roman times
9 \font_sans helvet
10 \font_typewriter courier
11 \font_default_family default
12 \font_sc false
13 \font_osf false
14 \font_sf_scale 100
15 \font_tt_scale 100
16 \graphics default
17 \paperfontsize 10
18 \spacing single
19 \papersize letterpaper
20 \use_geometry true
21 \use_amsmath 2
22 \use_esint 0
23 \cite_engine basic
24 \use_bibtopic false
25 \paperorientation portrait
26 \leftmargin 2cm
27 \topmargin 2cm
28 \rightmargin 2cm
29 \bottommargin 2cm
30 \secnumdepth 3
31 \tocdepth 3
32 \paragraph_separation indent
33 \defskip medskip
34 \quotes_language english
35 \papercolumns 1
36 \papersides 1
37 \paperpagestyle headings
38 \listings_params "basicstyle={\ttfamily},breaklines=true,language=C,xleftmargin=0mm"
39 \tracking_changes false
40 \output_changes false
41 \author "" 
42 \author "" 
43 \end_header
44
45 \begin_body
46
47 \begin_layout Title
48 The Speex Codec Manual
49 \newline
50 Version 1.2 Beta 3
51 \end_layout
52
53 \begin_layout Author
54 Jean-Marc Valin
55 \end_layout
56
57 \begin_layout Standard
58
59 \newpage
60
61 \end_layout
62
63 \begin_layout Standard
64 Copyright 
65 \begin_inset ERT
66 status collapsed
67
68 \begin_layout Standard
69
70
71 \backslash
72 copyright
73 \end_layout
74
75 \end_inset
76
77  2002-2007 Jean-Marc Valin/Xiph.org Foundation
78 \end_layout
79
80 \begin_layout Standard
81 Permission is granted to copy, distribute and/or modify this document under
82  the terms of the GNU Free Documentation License, Version 1.1 or any later
83  version published by the Free Software Foundation; with no Invariant Section,
84  with no Front-Cover Texts, and with no Back-Cover.
85  A copy of the license is included in the section entitled "GNU Free Documentati
86 on License".
87  
88 \end_layout
89
90 \begin_layout Standard
91
92 \newpage
93
94 \begin_inset LatexCommand tableofcontents
95
96 \end_inset
97
98
99 \newpage
100
101 \end_layout
102
103 \begin_layout Standard
104 \begin_inset FloatList table
105
106 \end_inset
107
108
109 \newpage
110
111 \end_layout
112
113 \begin_layout Chapter
114 Introduction to Speex
115 \end_layout
116
117 \begin_layout Standard
118 The Speex codec (
119 \family typewriter
120 http://www.speex.org/
121 \family default
122 ) exists because there is a need for a speech codec that is open-source
123  and free from software patent royalties.
124  These are essential conditions for being usable in any open-source software.
125  In essence, Speex is to speech what Vorbis is to audio/music.
126  Unlike many other speech codecs, Speex is not designed for mobile phones
127  but rather for packet networks and voice over IP (VoIP) applications.
128  File-based compression is of course also supported.
129  
130 \end_layout
131
132 \begin_layout Standard
133 The Speex codec is designed to be very flexible and support a wide range
134  of speech quality and bit-rate.
135  Support for very good quality speech also means that Speex can encode wideband
136  speech (16 kHz sampling rate) in addition to narrowband speech (telephone
137  quality, 8 kHz sampling rate).
138 \end_layout
139
140 \begin_layout Standard
141 Designing for VoIP instead of mobile phones means that Speex is robust to
142  lost packets, but not to corrupted ones.
143  This is based on the assumption that in VoIP, packets either arrive unaltered
144  or don't arrive at all.
145  Because Speex is targeted at a wide range of devices, it has modest (adjustable
146 ) complexity and a small memory footprint.
147 \end_layout
148
149 \begin_layout Standard
150 All the design goals led to the choice of CELP
151 \begin_inset LatexCommand index
152 name "CELP"
153
154 \end_inset
155
156  as the encoding technique.
157  One of the main reasons is that CELP has long proved that it could work
158  reliably and scale well to both low bit-rates (e.g.
159  DoD CELP @ 4.8 kbps) and high bit-rates (e.g.
160  G.728 @ 16 kbps).
161  
162 \end_layout
163
164 \begin_layout Section
165 Getting help
166 \begin_inset LatexCommand label
167 name "sec:Getting-help"
168
169 \end_inset
170
171
172 \end_layout
173
174 \begin_layout Standard
175 As for many open source projects, there are many ways to get help with Speex.
176  These include:
177 \end_layout
178
179 \begin_layout Itemize
180 This manual
181 \end_layout
182
183 \begin_layout Itemize
184 Other documentation on the Speex website (http://www.speex.org/)
185 \end_layout
186
187 \begin_layout Itemize
188 Mailing list: Discuss any Speex-related topic on speex-dev@xiph.org (not
189  just for developers)
190 \end_layout
191
192 \begin_layout Itemize
193 IRC: The main channel is #speex on irc.freenode.net.
194  Note that due to time differences, it may take a while to get someone,
195  so please be patient.
196 \end_layout
197
198 \begin_layout Itemize
199 Email the author privately at jean-marc.valin@usherbrooke.ca 
200 \series bold
201 only
202 \series default
203  for private/delicate topics you do not wish to discuss publically.
204 \end_layout
205
206 \begin_layout Standard
207 Before asking for help (mailing list or IRC), 
208 \series bold
209 it is important to first read this manual
210 \series default
211  (OK, so if you made it here it's already a good sign).
212  It is generally considered rude to ask on a mailing list about topics that
213  are clearly detailed in the documentation.
214  On the other hand, it's perfectly OK (and encouraged) to ask for clarifications
215  about something covered in the manual.
216  This manual does not (yet) cover everything about Speex, so everyone is
217  encouraged to ask questions, send comments, feature requests, or just let
218  us know how Speex is being used.
219  
220 \end_layout
221
222 \begin_layout Standard
223 Here are some additional guidelines related to the mailing list.
224  Before reporting bugs in Speex to the list, it is strongly recommended
225  (if possible) to first test whether these bugs can be reproduced using
226  the speexenc and speexdec (see Section 
227 \begin_inset LatexCommand ref
228 reference "sec:Command-line-encoder/decoder"
229
230 \end_inset
231
232 ) command-line utilities.
233  Bugs reported based on 3rd party code are both harder to find and far too
234  often caused by errors that have nothing to do with Speex.
235  
236 \end_layout
237
238 \begin_layout Section
239 About this document
240 \end_layout
241
242 \begin_layout Standard
243 This document is divided in the following way.
244  Section 
245 \begin_inset LatexCommand ref
246 reference "sec:Feature-description"
247
248 \end_inset
249
250  describes the different Speex features and defines many basic terms that
251  are used throughout this manual.
252  Section 
253 \begin_inset LatexCommand ref
254 reference "sec:Command-line-encoder/decoder"
255
256 \end_inset
257
258  documents the standard command-line tools provided in the Speex distribution.
259  Section 
260 \begin_inset LatexCommand ref
261 reference "sec:Programming-with-Speex"
262
263 \end_inset
264
265  includes detailed instructions about programming using the libspeex
266 \begin_inset LatexCommand index
267 name "libspeex"
268
269 \end_inset
270
271  API.
272  Section 
273 \begin_inset LatexCommand ref
274 reference "sec:Formats-and-standards"
275
276 \end_inset
277
278  has some information related to Speex and standards.
279  
280 \end_layout
281
282 \begin_layout Standard
283 The three last sections describe the algorithms used in Speex.
284  These sections require signal processing knowledge, but are not required
285  for merely using Speex.
286  They are intended for people who want to understand how Speex really works
287  and/or want to do research based on Speex.
288  Section 
289 \begin_inset LatexCommand ref
290 reference "sec:Introduction-to-CELP"
291
292 \end_inset
293
294  explains the general idea behind CELP, while sections 
295 \begin_inset LatexCommand ref
296 reference "sec:Speex-narrowband-mode"
297
298 \end_inset
299
300  and 
301 \begin_inset LatexCommand ref
302 reference "sec:Speex-wideband-mode"
303
304 \end_inset
305
306  are specific to Speex.
307 \end_layout
308
309 \begin_layout Standard
310
311 \newpage
312
313 \end_layout
314
315 \begin_layout Chapter
316 Codec description
317 \begin_inset LatexCommand label
318 name "sec:Feature-description"
319
320 \end_inset
321
322
323 \end_layout
324
325 \begin_layout Standard
326 This section describes Speex and its features into more details.
327 \end_layout
328
329 \begin_layout Section
330 Concepts
331 \end_layout
332
333 \begin_layout Standard
334 Before introducing all the Speex features, here are some concepts in speech
335  coding that help better understand the rest of the manual.
336  Although some are general concepts in speech/audio processing, others are
337  specific to Speex.
338 \end_layout
339
340 \begin_layout Subsection*
341 Sampling rate
342 \begin_inset LatexCommand index
343 name "sampling rate"
344
345 \end_inset
346
347
348 \end_layout
349
350 \begin_layout Standard
351 The sampling rate expressed in Hertz (Hz) is the number of samples taken
352  from a signal per second.
353  For a sampling rate of 
354 \begin_inset Formula $F_{s}$
355 \end_inset
356
357  kHz, the highest frequency that can be represented is equal to 
358 \begin_inset Formula $F_{s}/2$
359 \end_inset
360
361  kHz (
362 \begin_inset Formula $F_{s}/2$
363 \end_inset
364
365  is known as the Nyquist frequency).
366  This is a fundamental property in signal processing and is described by
367  the sampling theorem.
368  Speex is mainly designed for three different sampling rates: 8 kHz, 16
369  kHz, and 32 kHz.
370  These are respectively refered to as narrowband
371 \begin_inset LatexCommand index
372 name "narrowband"
373
374 \end_inset
375
376 , wideband
377 \begin_inset LatexCommand index
378 name "wideband"
379
380 \end_inset
381
382  and ultra-wideband
383 \begin_inset LatexCommand index
384 name "ultra-wideband"
385
386 \end_inset
387
388 .
389  
390 \end_layout
391
392 \begin_layout Subsection*
393 Bit-rate
394 \end_layout
395
396 \begin_layout Standard
397 When encoding a speech signal, the bit-rate is defined as the number of
398  bits per unit of time required to encode the speech.
399  It is measured in 
400 \emph on
401 bits per second
402 \emph default
403  (bps), or generally 
404 \emph on
405 kilobits per second
406 \emph default
407 .
408  It is important to make the distinction between 
409 \emph on
410 kilo
411 \series bold
412 bits
413 \series default
414 \emph default
415  
416 \emph on
417 per second
418 \emph default
419  (k
420 \series bold
421 b
422 \series default
423 ps) and 
424 \emph on
425 kilo
426 \series bold
427 bytes
428 \series default
429 \emph default
430  
431 \emph on
432 per second
433 \emph default
434  (k
435 \series bold
436 B
437 \series default
438 ps).
439 \end_layout
440
441 \begin_layout Subsection*
442 Quality
443 \begin_inset LatexCommand index
444 name "quality"
445
446 \end_inset
447
448  (variable)
449 \end_layout
450
451 \begin_layout Standard
452 Speex is a lossy codec, which means that it achives compression at the expense
453  of fidelity of the input speech signal.
454  Unlike some other speech codecs, it is possible to control the tradeoff
455  made between quality and bit-rate.
456  The Speex encoding process is controlled most of the time by a quality
457  parameter that ranges from 0 to 10.
458  In constant bit-rate
459 \begin_inset LatexCommand index
460 name "constant bit-rate"
461
462 \end_inset
463
464  (CBR) operation, the quality parameter is an integer, while for variable
465  bit-rate (VBR), the parameter is a float.
466  
467 \end_layout
468
469 \begin_layout Subsection*
470 Complexity
471 \begin_inset LatexCommand index
472 name "complexity"
473
474 \end_inset
475
476  (variable)
477 \end_layout
478
479 \begin_layout Standard
480 With Speex, it is possible to vary the complexity allowed for the encoder.
481  This is done by controlling how the search is performed with an integer
482  ranging from 1 to 10 in a way that's similar to the -1 to -9 options to
483  
484 \emph on
485 gzip
486 \emph default
487  and 
488 \emph on
489 bzip2
490 \emph default
491  compression utilities.
492  For normal use, the noise level at complexity 1 is between 1 and 2 dB higher
493  than at complexity 10, but the CPU requirements for complexity 10 is about
494  5 times higher than for complexity 1.
495  In practice, the best trade-off is between complexity 2 and 4, though higher
496  settings are often useful when encoding non-speech sounds like DTMF
497 \begin_inset LatexCommand index
498 name "DTMF"
499
500 \end_inset
501
502  tones.
503 \end_layout
504
505 \begin_layout Subsection*
506 Variable Bit-Rate
507 \begin_inset LatexCommand index
508 name "variable bit-rate"
509
510 \end_inset
511
512  (VBR)
513 \end_layout
514
515 \begin_layout Standard
516 Variable bit-rate (VBR) allows a codec to change its bit-rate dynamically
517  to adapt to the 
518 \begin_inset Quotes eld
519 \end_inset
520
521 difficulty
522 \begin_inset Quotes erd
523 \end_inset
524
525  of the audio being encoded.
526  In the example of Speex, sounds like vowels and high-energy transients
527  require a higher bit-rate to achieve good quality, while fricatives (e.g.
528  s,f sounds) can be coded adequately with less bits.
529  For this reason, VBR can achive lower bit-rate for the same quality, or
530  a better quality for a certain bit-rate.
531  Despite its advantages, VBR has two main drawbacks: first, by only specifying
532  quality, there's no guaranty about the final average bit-rate.
533  Second, for some real-time applications like voice over IP (VoIP), what
534  counts is the maximum bit-rate, which must be low enough for the communication
535  channel.
536 \end_layout
537
538 \begin_layout Subsection*
539 Average Bit-Rate
540 \begin_inset LatexCommand index
541 name "average bit-rate"
542
543 \end_inset
544
545  (ABR)
546 \end_layout
547
548 \begin_layout Standard
549 Average bit-rate solves one of the problems of VBR, as it dynamically adjusts
550  VBR quality in order to meet a specific target bit-rate.
551  Because the quality/bit-rate is adjusted in real-time (open-loop), the
552  global quality will be slightly lower than that obtained by encoding in
553  VBR with exactly the right quality setting to meet the target average bit-rate.
554 \end_layout
555
556 \begin_layout Subsection*
557 Voice Activity Detection
558 \begin_inset LatexCommand index
559 name "voice activity detection"
560
561 \end_inset
562
563  (VAD)
564 \end_layout
565
566 \begin_layout Standard
567 When enabled, voice activity detection detects whether the audio being encoded
568  is speech or silence/background noise.
569  VAD is always implicitly activated when encoding in VBR, so the option
570  is only useful in non-VBR operation.
571  In this case, Speex detects non-speech periods and encode them with just
572  enough bits to reproduce the background noise.
573  This is called 
574 \begin_inset Quotes eld
575 \end_inset
576
577 comfort noise generation
578 \begin_inset Quotes erd
579 \end_inset
580
581  (CNG).
582 \end_layout
583
584 \begin_layout Subsection*
585 Discontinuous Transmission
586 \begin_inset LatexCommand index
587 name "discontinuous transmission"
588
589 \end_inset
590
591  (DTX)
592 \end_layout
593
594 \begin_layout Standard
595 Discontinuous transmission is an addition to VAD/VBR operation, that allows
596  to stop transmitting completely when the background noise is stationary.
597  In file-based operation, since we cannot just stop writing to the file,
598  only 5 bits are used for such frames (corresponding to 250 bps).
599 \end_layout
600
601 \begin_layout Subsection*
602 Perceptual enhancement
603 \begin_inset LatexCommand index
604 name "perceptual enhancement"
605
606 \end_inset
607
608
609 \end_layout
610
611 \begin_layout Standard
612 Perceptual enhancement is a part of the decoder which, when turned on, attempts
613  to reduce the perception of the noise/distortion produced by the encoding/decod
614 ing process.
615  In most cases, perceptual enhancement brings the sound further from the
616  original 
617 \emph on
618 objectively
619 \emph default
620  (e.g.
621  considering only SNR), but in the end it still 
622 \emph on
623 sounds
624 \emph default
625  better (subjective improvement).
626 \end_layout
627
628 \begin_layout Subsection*
629 Latency and algorithmic delay
630 \begin_inset LatexCommand index
631 name "algorithmic delay"
632
633 \end_inset
634
635
636 \end_layout
637
638 \begin_layout Standard
639 Every speech codec introduces a delay in the transmission.
640  For Speex, this delay is equal to the frame size, plus some amount of 
641 \begin_inset Quotes eld
642 \end_inset
643
644 look-ahead
645 \begin_inset Quotes erd
646 \end_inset
647
648  required to process each frame.
649  In narrowband operation (8 kHz), the delay is 30 ms, while for wideband
650  (16 kHz), the delay is 34 ms.
651  These values don't account for the CPU time it takes to encode or decode
652  the frames.
653 \end_layout
654
655 \begin_layout Section
656 Codec
657 \end_layout
658
659 \begin_layout Standard
660 The main characteristics of Speex can be summarized as follows:
661 \end_layout
662
663 \begin_layout Itemize
664 Free software/open-source
665 \begin_inset LatexCommand index
666 name "open-source"
667
668 \end_inset
669
670 , patent
671 \begin_inset LatexCommand index
672 name "patent"
673
674 \end_inset
675
676  and royalty-free
677 \end_layout
678
679 \begin_layout Itemize
680 Integration of narrowband
681 \begin_inset LatexCommand index
682 name "narrowband"
683
684 \end_inset
685
686  and wideband
687 \begin_inset LatexCommand index
688 name "wideband"
689
690 \end_inset
691
692  using an embedded bit-stream
693 \end_layout
694
695 \begin_layout Itemize
696 Wide range of bit-rates available (from 2.15 kbps to 44 kbps)
697 \end_layout
698
699 \begin_layout Itemize
700 Dynamic bit-rate switching (AMR) and Variable Bit-Rate
701 \begin_inset LatexCommand index
702 name "variable bit-rate"
703
704 \end_inset
705
706  (VBR) operation
707 \end_layout
708
709 \begin_layout Itemize
710 Voice Activity Detection
711 \begin_inset LatexCommand index
712 name "voice activity detection"
713
714 \end_inset
715
716  (VAD, integrated with VBR) and discontinuous transmission (DTX)
717 \end_layout
718
719 \begin_layout Itemize
720 Variable complexity
721 \begin_inset LatexCommand index
722 name "complexity"
723
724 \end_inset
725
726
727 \end_layout
728
729 \begin_layout Itemize
730 Embedded wideband structure (scalable sampling rate)
731 \end_layout
732
733 \begin_layout Itemize
734 Ultra-wideband sampling rate at 32 kHz
735 \end_layout
736
737 \begin_layout Itemize
738 Intensity stereo encoding option
739 \end_layout
740
741 \begin_layout Itemize
742 Fixed-point implementation
743 \end_layout
744
745 \begin_layout Section
746 Preprocessor
747 \end_layout
748
749 \begin_layout Standard
750 This part refers to the preprocessor module introduced in the 1.1.x branch.
751  The preprocessor is designed to be used on the audio 
752 \emph on
753 before
754 \emph default
755  running the encoder.
756  The preprocessor provides three main functionalities:
757 \end_layout
758
759 \begin_layout Itemize
760 noise suppression
761 \end_layout
762
763 \begin_layout Itemize
764 automatic gain control (AGC)
765 \end_layout
766
767 \begin_layout Itemize
768 voice activity detection (VAD)
769 \end_layout
770
771 \begin_layout Standard
772 The denoiser can be used to reduce the amount of background noise present
773  in the input signal.
774  This provides higher quality speech whether or not the denoised signal
775  is encoded with Speex (or at all).
776  However, when using the denoised signal with the codec, there is an additional
777  benefit.
778  Speech codecs in general (Speex included) tend to perform poorly on noisy
779  input, which tends to amplify the noise.
780  The denoiser greatly reduces this effect.
781 \end_layout
782
783 \begin_layout Standard
784 Automatic gain control (AGC) is a feature that deals with the fact that
785  the recording volume may vary by a large amount between different setups.
786  The AGC provides a way to adjust a signal to a reference volume.
787  This is useful for voice over IP because it removes the need for manual
788  adjustment of the microphone gain.
789  A secondary advantage is that by setting the microphone gain to a conservative
790  (low) level, it is easier to avoid clipping.
791 \end_layout
792
793 \begin_layout Standard
794 The voice activity detector (VAD) provided by the preprocessor is more advanced
795  than the one directly provided in the codec.
796  
797 \end_layout
798
799 \begin_layout Section
800 Adaptive Jitter Buffer
801 \end_layout
802
803 \begin_layout Standard
804 When transmitting voice (or any content for that matter) over UDP or RTP,
805  packet may be lost, arrive with different delay, or even out of order.
806  The purpose of a jitter buffer is to reorder packets and buffer them long
807  enough (but no longer than necessary) so they can be sent to be decoded.
808  
809 \end_layout
810
811 \begin_layout Section
812 Acoustic Echo Canceller
813 \end_layout
814
815 \begin_layout Standard
816 In any hands-free communication system (Fig.
817  
818 \begin_inset LatexCommand ref
819 reference "fig:Acoustic-echo-model"
820
821 \end_inset
822
823 ), speech from the remote end is played in the local loudspeaker, propagates
824  in the room and is captured by the microphone.
825  If the audio captured from the microphone is sent directly to the remote
826  end, then the remove user hears an echo of his voice.
827  An acoustic echo canceller is designed to remove the acoustic echo before
828  it is sent to the remote end.
829  It is important to understand that the echo canceller is meant to improve
830  the quality on the 
831 \series bold
832 remote
833 \series default
834  end.
835 \end_layout
836
837 \begin_layout Standard
838 \begin_inset Float figure
839 wide false
840 sideways false
841 status open
842
843 \begin_layout Standard
844 \begin_inset ERT
845 status collapsed
846
847 \begin_layout Standard
848
849
850 \backslash
851 begin{center}
852 \end_layout
853
854 \end_inset
855
856
857 \begin_inset Graphics
858         filename echo_path.eps
859         width 10cm
860
861 \end_inset
862
863
864 \begin_inset ERT
865 status collapsed
866
867 \begin_layout Standard
868
869
870 \backslash
871 end{center}
872 \end_layout
873
874 \end_inset
875
876
877 \end_layout
878
879 \begin_layout Standard
880 \begin_inset Caption
881
882 \begin_layout Standard
883 Acoustic echo model
884 \begin_inset LatexCommand label
885 name "fig:Acoustic-echo-model"
886
887 \end_inset
888
889
890 \end_layout
891
892 \end_inset
893
894
895 \end_layout
896
897 \end_inset
898
899
900 \end_layout
901
902 \begin_layout Section
903 Resampler
904 \end_layout
905
906 \begin_layout Standard
907 In some cases, it may be useful to convert audio from one sampling rate
908  to another.
909  There are many reasons for that.
910  It can be for mixing streams that have different sampling rates, for supporting
911  sampling rates that the soundcard doesn't support, for transcoding, etc.
912  That's why there is now a resampler that is part of the Speex project.
913  This resampler can be used to convert between any two arbitrary rates (the
914  ratio must only be a rational number) and there is control over the quality/com
915 plexity tradeoff.
916 \end_layout
917
918 \begin_layout Standard
919
920 \newpage
921
922 \end_layout
923
924 \begin_layout Chapter
925 Compiling
926 \end_layout
927
928 \begin_layout Standard
929 Compiling Speex under UNIX/Linux or any other platform supported by autoconf
930  (e.g.
931  Win32/cygwin) is as easy as typing:
932 \end_layout
933
934 \begin_layout LyX-Code
935 % ./configure [options]
936 \end_layout
937
938 \begin_layout LyX-Code
939 % make
940 \end_layout
941
942 \begin_layout LyX-Code
943 % make install
944 \end_layout
945
946 \begin_layout Standard
947 The options supported by the Speex configure script are:
948 \end_layout
949
950 \begin_layout Description
951 --prefix=<path> Specifies the base path for installing Speex (e.g.
952  /usr)
953 \end_layout
954
955 \begin_layout Description
956 --enable-shared/--disable-shared Whether to compile shared libraries
957 \end_layout
958
959 \begin_layout Description
960 --enable-static/--disable-static Whether to compile static libraries
961 \end_layout
962
963 \begin_layout Description
964 --disable-wideband Disable the wideband part of Speex (typically to save
965  space)
966 \end_layout
967
968 \begin_layout Description
969 --enable-valgrind Enable extra hits for valgrind for debugging purposes
970  (do not use by default)
971 \end_layout
972
973 \begin_layout Description
974 --enable-sse Enable use of SSE instructions (x86/float only)
975 \end_layout
976
977 \begin_layout Description
978 --enable-fixed-point
979 \begin_inset LatexCommand index
980 name "fixed-point"
981
982 \end_inset
983
984  Compile Speex for a processor that does not have a floating point unit
985  (FPU)
986 \end_layout
987
988 \begin_layout Description
989 --enable-arm4-asm Enable assembly specific to the ARMv4 architecture (gcc
990  only)
991 \end_layout
992
993 \begin_layout Description
994 --enable-arm5e-asm Enable assembly specific to the ARMv5E architecture (gcc
995  only)
996 \end_layout
997
998 \begin_layout Description
999 --enable-fixed-point-debug Use only for debugging the fixed-point
1000 \begin_inset LatexCommand index
1001 name "fixed-point"
1002
1003 \end_inset
1004
1005  code (very slow)
1006 \end_layout
1007
1008 \begin_layout Description
1009 --enable-epic-48k Enable a special (and non-compatible) 4.8 kbps narrowband
1010  mode (broken in 1.1.x and 1.2beta)
1011 \end_layout
1012
1013 \begin_layout Description
1014 --enable-ti-c55x Enable support for the TI C5x family
1015 \end_layout
1016
1017 \begin_layout Description
1018 --enable-blackfin-asm Enable assembly specific to the Blackfin DSP architecture
1019  (gcc only)
1020 \end_layout
1021
1022 \begin_layout Description
1023 --enable-vorbis-psycho Make the encoder use the Vorbis psycho-acoustic model.
1024  This is very experimental and may be removed in the future.
1025 \end_layout
1026
1027 \begin_layout Section
1028 Platforms
1029 \end_layout
1030
1031 \begin_layout Standard
1032 Speex is known to compile and work on a large number of architectures, both
1033  floating-point and fixed-point.
1034  In general, any architecture that can natively compute the multiplication
1035  of two signed 16-bit numbers (32-bit result) and runs at a sufficient clock
1036  rate (architecture-dependent) is capable of running Speex.
1037  Architectures that are 
1038 \series bold
1039 known
1040 \series default
1041  to be supported (it probably works on many others) are:
1042 \end_layout
1043
1044 \begin_layout Itemize
1045 x86 & x86-64
1046 \end_layout
1047
1048 \begin_layout Itemize
1049 Power
1050 \end_layout
1051
1052 \begin_layout Itemize
1053 SPARC
1054 \end_layout
1055
1056 \begin_layout Itemize
1057 ARM
1058 \end_layout
1059
1060 \begin_layout Itemize
1061 Blackfin
1062 \end_layout
1063
1064 \begin_layout Itemize
1065 TI C54xx & C55xx
1066 \end_layout
1067
1068 \begin_layout Itemize
1069 TI C6xxx
1070 \end_layout
1071
1072 \begin_layout Itemize
1073 TriMedia (experimental)
1074 \end_layout
1075
1076 \begin_layout Standard
1077 Operating systems on top of which Speex is known to work include (it probably
1078  works on many others):
1079 \end_layout
1080
1081 \begin_layout Itemize
1082 Linux
1083 \end_layout
1084
1085 \begin_layout Itemize
1086 \begin_inset Formula $\mu$
1087 \end_inset
1088
1089 Clinux
1090 \end_layout
1091
1092 \begin_layout Itemize
1093 MacOS X
1094 \end_layout
1095
1096 \begin_layout Itemize
1097 BSD
1098 \end_layout
1099
1100 \begin_layout Itemize
1101 Other UNIX/POSIX variants
1102 \end_layout
1103
1104 \begin_layout Itemize
1105 Symbian
1106 \end_layout
1107
1108 \begin_layout Standard
1109 The source code directory include additional information for compiling on
1110  certain architectures or operating systems in README.xxx files.
1111 \end_layout
1112
1113 \begin_layout Standard
1114
1115 \newpage
1116
1117 \end_layout
1118
1119 \begin_layout Chapter
1120 Command-line encoder/decoder
1121 \begin_inset LatexCommand label
1122 name "sec:Command-line-encoder/decoder"
1123
1124 \end_inset
1125
1126
1127 \end_layout
1128
1129 \begin_layout Standard
1130 The base Speex distribution includes a command-line encoder (
1131 \emph on
1132 speexenc
1133 \emph default
1134 ) and decoder (
1135 \emph on
1136 speexdec
1137 \emph default
1138 ).
1139  Those tools produce and read Speex files encapsulated in the Ogg container.
1140  Although it is possible to encapsulate Speex in any container, Ogg is the
1141  recommended container for files.
1142  This section describes how to use the command line tools for Speex files
1143  in Ogg.
1144 \end_layout
1145
1146 \begin_layout Section
1147
1148 \emph on
1149 speexenc
1150 \begin_inset LatexCommand index
1151 name "speexenc"
1152
1153 \end_inset
1154
1155
1156 \end_layout
1157
1158 \begin_layout Standard
1159 The 
1160 \emph on
1161 speexenc
1162 \emph default
1163  utility is used to create Speex files from raw PCM or wave files.
1164  It can be used by calling: 
1165 \end_layout
1166
1167 \begin_layout LyX-Code
1168 speexenc [options] input_file output_file
1169 \end_layout
1170
1171 \begin_layout Standard
1172 The value '-' for input_file or output_file corresponds respectively to
1173  stdin and stdout.
1174  The valid options are:
1175 \end_layout
1176
1177 \begin_layout Description
1178 --narrowband\InsetSpace ~
1179 (-n) Tell Speex to treat the input as narrowband (8 kHz).
1180  This is the default
1181 \end_layout
1182
1183 \begin_layout Description
1184 --wideband\InsetSpace ~
1185 (-w) Tell Speex to treat the input as wideband (16 kHz)
1186 \end_layout
1187
1188 \begin_layout Description
1189 --ultra-wideband\InsetSpace ~
1190 (-u) Tell Speex to treat the input as 
1191 \begin_inset Quotes eld
1192 \end_inset
1193
1194 ultra-wideband
1195 \begin_inset Quotes erd
1196 \end_inset
1197
1198  (32 kHz)
1199 \end_layout
1200
1201 \begin_layout Description
1202 --quality\InsetSpace ~
1203 n Set the encoding quality (0-10), default is 8
1204 \end_layout
1205
1206 \begin_layout Description
1207 --bitrate\InsetSpace ~
1208 n Encoding bit-rate (use bit-rate n or lower) 
1209 \end_layout
1210
1211 \begin_layout Description
1212 --vbr Enable VBR (Variable Bit-Rate), disabled by default
1213 \end_layout
1214
1215 \begin_layout Description
1216 --abr\InsetSpace ~
1217 n Enable ABR (Average Bit-Rate) at n kbps, disabled by default
1218 \end_layout
1219
1220 \begin_layout Description
1221 --vad Enable VAD (Voice Activity Detection), disabled by default
1222 \end_layout
1223
1224 \begin_layout Description
1225 --dtx Enable DTX (Discontinuous Transmission), disabled by default
1226 \end_layout
1227
1228 \begin_layout Description
1229 --nframes\InsetSpace ~
1230 n Pack n frames in each Ogg packet (this saves space at low bit-rates)
1231 \end_layout
1232
1233 \begin_layout Description
1234 --comp\InsetSpace ~
1235 n Set encoding speed/quality tradeoff.
1236  The higher the value of n, the slower the encoding (default is 3)
1237 \end_layout
1238
1239 \begin_layout Description
1240 -V Verbose operation, print bit-rate currently in use
1241 \end_layout
1242
1243 \begin_layout Description
1244 --help\InsetSpace ~
1245 (-h) Print the help
1246 \end_layout
1247
1248 \begin_layout Description
1249 --version\InsetSpace ~
1250 (-v) Print version information
1251 \end_layout
1252
1253 \begin_layout Subsection*
1254 Speex comments
1255 \end_layout
1256
1257 \begin_layout Description
1258 --comment Add the given string as an extra comment.
1259  This may be used multiple times.
1260  
1261 \end_layout
1262
1263 \begin_layout Description
1264 --author Author of this track.
1265  
1266 \end_layout
1267
1268 \begin_layout Description
1269 --title Title for this track.
1270  
1271 \end_layout
1272
1273 \begin_layout Subsection*
1274 Raw input options
1275 \end_layout
1276
1277 \begin_layout Description
1278 --rate\InsetSpace ~
1279 n Sampling rate for raw input
1280 \end_layout
1281
1282 \begin_layout Description
1283 --stereo Consider raw input as stereo 
1284 \end_layout
1285
1286 \begin_layout Description
1287 --le Raw input is little-endian 
1288 \end_layout
1289
1290 \begin_layout Description
1291 --be Raw input is big-endian 
1292 \end_layout
1293
1294 \begin_layout Description
1295 --8bit Raw input is 8-bit unsigned 
1296 \end_layout
1297
1298 \begin_layout Description
1299 --16bit Raw input is 16-bit signed 
1300 \end_layout
1301
1302 \begin_layout Section
1303
1304 \emph on
1305 speexdec
1306 \begin_inset LatexCommand index
1307 name "speexdec"
1308
1309 \end_inset
1310
1311
1312 \end_layout
1313
1314 \begin_layout Standard
1315 The 
1316 \emph on
1317 speexdec
1318 \emph default
1319  utility is used to decode Speex files and can be used by calling: 
1320 \end_layout
1321
1322 \begin_layout LyX-Code
1323 speexdec [options] speex_file [output_file]
1324 \end_layout
1325
1326 \begin_layout Standard
1327 The value '-' for input_file or output_file corresponds respectively to
1328  stdin and stdout.
1329  Also, when no output_file is specified, the file is played to the soundcard.
1330  The valid options are:
1331 \end_layout
1332
1333 \begin_layout Description
1334 --enh enable post-filter (default)
1335 \end_layout
1336
1337 \begin_layout Description
1338 --no-enh disable post-filter
1339 \end_layout
1340
1341 \begin_layout Description
1342 --force-nb Force decoding in narrowband 
1343 \end_layout
1344
1345 \begin_layout Description
1346 --force-wb Force decoding in wideband 
1347 \end_layout
1348
1349 \begin_layout Description
1350 --force-uwb Force decoding in ultra-wideband 
1351 \end_layout
1352
1353 \begin_layout Description
1354 --mono Force decoding in mono 
1355 \end_layout
1356
1357 \begin_layout Description
1358 --stereo Force decoding in stereo 
1359 \end_layout
1360
1361 \begin_layout Description
1362 --rate\InsetSpace ~
1363 n Force decoding at n Hz sampling rate
1364 \end_layout
1365
1366 \begin_layout Description
1367 --packet-loss\InsetSpace ~
1368 n Simulate n % random packet loss
1369 \end_layout
1370
1371 \begin_layout Description
1372 -V Verbose operation, print bit-rate currently in use
1373 \end_layout
1374
1375 \begin_layout Description
1376 --help\InsetSpace ~
1377 (-h) Print the help
1378 \end_layout
1379
1380 \begin_layout Description
1381 --version\InsetSpace ~
1382 (-v) Print version information
1383 \end_layout
1384
1385 \begin_layout Standard
1386
1387 \newpage
1388
1389 \end_layout
1390
1391 \begin_layout Chapter
1392 Using the Speex Codec API (
1393 \emph on
1394 libspeex
1395 \emph default
1396
1397 \begin_inset LatexCommand index
1398 name "libspeex"
1399
1400 \end_inset
1401
1402 )
1403 \begin_inset LatexCommand label
1404 name "sec:Programming-with-Speex"
1405
1406 \end_inset
1407
1408
1409 \end_layout
1410
1411 \begin_layout Standard
1412 The 
1413 \emph on
1414 libspeex
1415 \emph default
1416  library contains all the functions for encoding and decoding speech with
1417  the Speex codec.
1418  When linking on a UNIX system, one must add 
1419 \emph on
1420 -lspeex -lm
1421 \emph default
1422  to the compiler command line.
1423  One important thing to know is that 
1424 \series bold
1425 libspeex calls are reentrant, but not thread-safe
1426 \series default
1427 .
1428  That means that it is fine to use calls from many threads, but 
1429 \series bold
1430 calls using the same state from multiple threads must be protected by mutexes
1431 \series default
1432 .
1433  Examples of code can also be found in Appendix 
1434 \begin_inset LatexCommand ref
1435 reference "sec:Sample-code"
1436
1437 \end_inset
1438
1439  and the complete API documentation is included in the Documentation section
1440  of the Speex website (http://www.speex.org/).
1441 \end_layout
1442
1443 \begin_layout Section
1444 Encoding
1445 \begin_inset LatexCommand label
1446 name "sub:Encoding"
1447
1448 \end_inset
1449
1450
1451 \end_layout
1452
1453 \begin_layout Standard
1454 In order to encode speech using Speex, one first needs to:
1455 \end_layout
1456
1457 \begin_layout Standard
1458 \begin_inset listings
1459 inline false
1460 status open
1461
1462 \begin_layout Standard
1463
1464 #include <speex/speex.h>
1465 \end_layout
1466
1467 \end_inset
1468
1469 Then in the code, a Speex bit-packing struct must be declared, along with
1470  a Speex encoder state:
1471 \begin_inset listings
1472 inline false
1473 status open
1474
1475 \begin_layout Standard
1476
1477 SpeexBits bits;
1478 \end_layout
1479
1480 \begin_layout Standard
1481
1482 void *enc_state;
1483 \end_layout
1484
1485 \end_inset
1486
1487 The two are initialized by:
1488 \begin_inset listings
1489 inline false
1490 status open
1491
1492 \begin_layout Standard
1493
1494 speex_bits_init(&bits);
1495 \end_layout
1496
1497 \begin_layout Standard
1498
1499 enc_state = speex_encoder_init(&speex_nb_mode);
1500 \end_layout
1501
1502 \end_inset
1503
1504
1505 \end_layout
1506
1507 \begin_layout Standard
1508 For wideband coding, 
1509 \emph on
1510 speex_nb_mode
1511 \emph default
1512  will be replaced by 
1513 \emph on
1514 speex_wb_mode
1515 \emph default
1516 .
1517  In most cases, you will need to know the frame size used at the sampling
1518  rate you are using.
1519  You can get that value in the 
1520 \emph on
1521 frame_size
1522 \emph default
1523  variable (expressed in 
1524 \series bold
1525 samples
1526 \series default
1527 , not bytes) with:
1528 \end_layout
1529
1530 \begin_layout Standard
1531 \begin_inset listings
1532 inline false
1533 status open
1534
1535 \begin_layout Standard
1536
1537 speex_encoder_ctl(enc_state,SPEEX_GET_FRAME_SIZE,&frame_size);
1538 \end_layout
1539
1540 \end_inset
1541
1542
1543 \end_layout
1544
1545 \begin_layout Standard
1546 In practice, 
1547 \emph on
1548 frame_size
1549 \emph default
1550  will correspond to 20 ms when using 8, 16, or 32 kHz sampling rate.
1551  There are many parameters that can be set for the Speex encoder, but the
1552  most useful one is the quality parameter that controls the quality vs bit-rate
1553  tradeoff.
1554  This is set by:
1555 \end_layout
1556
1557 \begin_layout Standard
1558 \begin_inset listings
1559 inline false
1560 status open
1561
1562 \begin_layout Standard
1563
1564 speex_encoder_ctl(enc_state,SPEEX_SET_QUALITY,&quality);
1565 \end_layout
1566
1567 \end_inset
1568
1569 where 
1570 \emph on
1571 quality
1572 \emph default
1573  is an integer value ranging from 0 to 10 (inclusively).
1574  The mapping between quality and bit-rate is described in Fig.
1575  
1576 \begin_inset LatexCommand ref
1577 reference "cap:quality_vs_bps"
1578
1579 \end_inset
1580
1581  for narrowband.
1582 \end_layout
1583
1584 \begin_layout Standard
1585 Once the initialization is done, for every input frame:
1586 \end_layout
1587
1588 \begin_layout Standard
1589 \begin_inset listings
1590 inline false
1591 status open
1592
1593 \begin_layout Standard
1594
1595 speex_bits_reset(&bits);
1596 \end_layout
1597
1598 \begin_layout Standard
1599
1600 speex_encode_int(enc_state, input_frame, &bits);
1601 \end_layout
1602
1603 \begin_layout Standard
1604
1605 nbBytes = speex_bits_write(&bits, byte_ptr, MAX_NB_BYTES);
1606 \end_layout
1607
1608 \end_inset
1609
1610
1611 \end_layout
1612
1613 \begin_layout Standard
1614 where 
1615 \emph on
1616 input_frame
1617 \emph default
1618  is a 
1619 \emph on
1620 (
1621 \emph default
1622 short 
1623 \emph on
1624 *)
1625 \emph default
1626  pointing to the beginning of a speech frame, 
1627 \emph on
1628 byte_ptr
1629 \emph default
1630  is a 
1631 \emph on
1632 (char *)
1633 \emph default
1634  where the encoded frame will be written, 
1635 \emph on
1636 MAX_NB_BYTES
1637 \emph default
1638  is the maximum number of bytes that can be written to 
1639 \emph on
1640 byte_ptr
1641 \emph default
1642  without causing an overflow and 
1643 \emph on
1644 nbBytes
1645 \emph default
1646  is the number of bytes actually written to 
1647 \emph on
1648 byte_ptr
1649 \emph default
1650  (the encoded size in bytes).
1651  Before calling speex_bits_write, it is possible to find the number of bytes
1652  that need to be written by calling 
1653 \family typewriter
1654 speex_bits_nbytes(&bits)
1655 \family default
1656 , which returns a number of bytes.
1657 \end_layout
1658
1659 \begin_layout Standard
1660 It is still possible to use the 
1661 \emph on
1662 speex_encode()
1663 \emph default
1664  function, which takes a 
1665 \emph on
1666 (float *)
1667 \emph default
1668  for the audio.
1669  However, this would make an eventual port to an FPU-less platform (like
1670  ARM) more complicated.
1671  Internally, 
1672 \emph on
1673 speex_encode()
1674 \emph default
1675  and 
1676 \emph on
1677 speex_encode_int()
1678 \emph default
1679  are processed in the same way.
1680  Whether the encoder uses the fixed-point version is only decided by the
1681  compile-time flags, not at the API level.
1682 \end_layout
1683
1684 \begin_layout Standard
1685 After you're done with the encoding, free all resources with:
1686 \end_layout
1687
1688 \begin_layout Standard
1689 \begin_inset listings
1690 inline false
1691 status open
1692
1693 \begin_layout Standard
1694
1695 speex_bits_destroy(&bits);
1696 \end_layout
1697
1698 \begin_layout Standard
1699
1700 speex_encoder_destroy(enc_state);
1701 \end_layout
1702
1703 \end_inset
1704
1705
1706 \end_layout
1707
1708 \begin_layout Standard
1709 That's about it for the encoder.
1710  
1711 \end_layout
1712
1713 \begin_layout Section
1714 Decoding
1715 \begin_inset LatexCommand label
1716 name "sub:Decoding"
1717
1718 \end_inset
1719
1720
1721 \end_layout
1722
1723 \begin_layout Standard
1724 In order to decode speech using Speex, you first need to:
1725 \begin_inset listings
1726 inline false
1727 status open
1728
1729 \begin_layout Standard
1730
1731 #include <speex/speex.h>
1732 \end_layout
1733
1734 \end_inset
1735
1736 You also need to declare a Speex bit-packing struct
1737 \begin_inset listings
1738 inline false
1739 status open
1740
1741 \begin_layout Standard
1742
1743 SpeexBits bits;
1744 \end_layout
1745
1746 \end_inset
1747
1748 and a Speex decoder state
1749 \begin_inset listings
1750 inline false
1751 status open
1752
1753 \begin_layout Standard
1754
1755 void *dec_state;
1756 \end_layout
1757
1758 \end_inset
1759
1760 The two are initialized by:
1761 \begin_inset listings
1762 inline false
1763 status open
1764
1765 \begin_layout Standard
1766
1767 speex_bits_init(&bits);
1768 \end_layout
1769
1770 \begin_layout Standard
1771
1772 dec_state = speex_decoder_init(&speex_nb_mode);
1773 \end_layout
1774
1775 \end_inset
1776
1777
1778 \end_layout
1779
1780 \begin_layout Standard
1781 For wideband decoding, 
1782 \emph on
1783 speex_nb_mode
1784 \emph default
1785  will be replaced by 
1786 \emph on
1787 speex_wb_mode
1788 \emph default
1789 .
1790  If you need to obtain the size of the frames that will be used by the decoder,
1791  you can get that value in the 
1792 \emph on
1793 frame_size
1794 \emph default
1795  variable (expressed in 
1796 \series bold
1797 samples
1798 \series default
1799 , not bytes) with:
1800 \end_layout
1801
1802 \begin_layout Standard
1803 \begin_inset listings
1804 inline false
1805 status open
1806
1807 \begin_layout Standard
1808
1809 speex_decoder_ctl(dec_state, SPEEX_GET_FRAME_SIZE, &frame_size);
1810 \end_layout
1811
1812 \end_inset
1813
1814
1815 \end_layout
1816
1817 \begin_layout Standard
1818 There is also a parameter that can be set for the decoder: whether or not
1819  to use a perceptual enhancer.
1820  This can be set by: 
1821 \end_layout
1822
1823 \begin_layout Standard
1824 \begin_inset listings
1825 inline false
1826 status open
1827
1828 \begin_layout Standard
1829
1830 speex_decoder_ctl(dec_state, SPEEX_SET_ENH, &enh);
1831 \end_layout
1832
1833 \end_inset
1834
1835
1836 \end_layout
1837
1838 \begin_layout Standard
1839 where 
1840 \emph on
1841 enh
1842 \emph default
1843  is an int with value 0 to have the enhancer disabled and 1 to have it enabled.
1844  As of 1.2-beta1, the default is now to enable the enhancer.
1845 \end_layout
1846
1847 \begin_layout Standard
1848 Again, once the decoder initialization is done, for every input frame:
1849 \end_layout
1850
1851 \begin_layout Standard
1852 \begin_inset listings
1853 inline false
1854 status open
1855
1856 \begin_layout Standard
1857
1858 speex_bits_read_from(&bits, input_bytes, nbBytes);
1859 \end_layout
1860
1861 \begin_layout Standard
1862
1863 speex_decode_int(dec_state, &bits, output_frame);
1864 \end_layout
1865
1866 \end_inset
1867
1868 where input_bytes is a 
1869 \emph on
1870 (char *)
1871 \emph default
1872  containing the bit-stream data received for a frame, 
1873 \emph on
1874 nbBytes
1875 \emph default
1876  is the size (in bytes) of that bit-stream, and 
1877 \emph on
1878 output_frame
1879 \emph default
1880  is a 
1881 \emph on
1882 (short *)
1883 \emph default
1884  and points to the area where the decoded speech frame will be written.
1885  A NULL value as the second argument indicates that we don't have the bits
1886  for the current frame.
1887  When a frame is lost, the Speex decoder will do its best to "guess" the
1888  correct signal.
1889 \end_layout
1890
1891 \begin_layout Standard
1892 As for the encoder, the 
1893 \emph on
1894 speex_decode()
1895 \emph default
1896  function can still be used, with a 
1897 \emph on
1898 (float *)
1899 \emph default
1900  as the output for the audio.
1901  After you're done with the decoding, free all resources with:
1902 \end_layout
1903
1904 \begin_layout Standard
1905 \begin_inset listings
1906 inline false
1907 status open
1908
1909 \begin_layout Standard
1910
1911 speex_bits_destroy(&bits);
1912 \end_layout
1913
1914 \begin_layout Standard
1915
1916 speex_decoder_destroy(dec_state);
1917 \end_layout
1918
1919 \end_inset
1920
1921
1922 \end_layout
1923
1924 \begin_layout Section
1925 Codec Options (speex_*_ctl)
1926 \begin_inset LatexCommand label
1927 name "sub:Codec-Options"
1928
1929 \end_inset
1930
1931
1932 \end_layout
1933
1934 \begin_layout Quote
1935 \align center
1936
1937 \emph on
1938 Entities should not be multiplied beyond necessity -- William of Ockham.
1939 \end_layout
1940
1941 \begin_layout Quote
1942 \align center
1943
1944 \emph on
1945 Just because there's an option for it doesn't mean you have to turn it on
1946  -- me.
1947 \end_layout
1948
1949 \begin_layout Standard
1950 The Speex encoder and decoder support many options and requests that can
1951  be accessed through the 
1952 \emph on
1953 speex_encoder_ctl
1954 \emph default
1955  and 
1956 \emph on
1957 speex_decoder_ctl
1958 \emph default
1959  functions.
1960  Despite that, the defaults are good for many applications and 
1961 \series bold
1962 optional settings should only be used when one understands them and knows
1963  that they are needed
1964 \series default
1965 .
1966  A common error is to attempt to set many unnecessary settings.
1967  These functions are similar to the 
1968 \emph on
1969 ioctl
1970 \emph default
1971  system call and their prototypes are:
1972 \end_layout
1973
1974 \begin_layout Standard
1975 \begin_inset listings
1976 inline false
1977 status open
1978
1979 \begin_layout Standard
1980
1981 void speex_encoder_ctl(void *encoder, int request, void *ptr);
1982 \end_layout
1983
1984 \begin_layout Standard
1985
1986 void speex_decoder_ctl(void *encoder, int request, void *ptr);
1987 \end_layout
1988
1989 \end_inset
1990
1991
1992 \end_layout
1993
1994 \begin_layout Standard
1995 The different values of request allowed are (note that some only apply to
1996  the encoder or the decoder):
1997 \end_layout
1998
1999 \begin_layout Description
2000 SPEEX_SET_ENH** Set perceptual enhancer
2001 \begin_inset LatexCommand index
2002 name "perceptual enhancement"
2003
2004 \end_inset
2005
2006  to on (1) or off (0) (spx_int32_t)
2007 \end_layout
2008
2009 \begin_layout Description
2010 SPEEX_GET_ENH** Get perceptual enhancer status (spx_int32_t)
2011 \end_layout
2012
2013 \begin_layout Description
2014 SPEEX_GET_FRAME_SIZE Get the number of samples per frame for the current
2015  mode (spx_int32_t)
2016 \end_layout
2017
2018 \begin_layout Description
2019 SPEEX_SET_QUALITY* Set the encoder speech quality (spx_int32_t 0 to 10)
2020 \end_layout
2021
2022 \begin_layout Description
2023 SPEEX_GET_QUALITY* Get the current encoder speech quality (spx_int32_t 0
2024  to 10)
2025 \end_layout
2026
2027 \begin_layout Description
2028 SPEEX_SET_MODE* Set the mode number, as specified in the RTP spec (spx_int32_t)
2029 \end_layout
2030
2031 \begin_layout Description
2032 SPEEX_GET_MODE* Get the current mode number, as specified in the RTP spec
2033  (spx_int32_t)
2034 \end_layout
2035
2036 \begin_layout Description
2037 SPEEX_SET_LOW_MODE*
2038 \begin_inset Formula $\dagger$
2039 \end_inset
2040
2041  Use the source, Luke!
2042 \end_layout
2043
2044 \begin_layout Description
2045 SPEEX_GET_LOW_MODE*
2046 \begin_inset Formula $\dagger$
2047 \end_inset
2048
2049  Use the source, Luke!
2050 \end_layout
2051
2052 \begin_layout Description
2053 SPEEX_SET_HIGH_MODE*
2054 \begin_inset Formula $\dagger$
2055 \end_inset
2056
2057  Use the source, Luke!
2058 \end_layout
2059
2060 \begin_layout Description
2061 SPEEX_GET_HIGH_MODE*
2062 \begin_inset Formula $\dagger$
2063 \end_inset
2064
2065  Use the source, Luke!
2066 \end_layout
2067
2068 \begin_layout Description
2069 SPEEX_SET_VBR* Set variable bit-rate (VBR) to on (1) or off (0) (spx_int32_t)
2070 \end_layout
2071
2072 \begin_layout Description
2073 SPEEX_GET_VBR* Get variable bit-rate
2074 \begin_inset LatexCommand index
2075 name "variable bit-rate"
2076
2077 \end_inset
2078
2079  (VBR) status (spx_int32_t)
2080 \end_layout
2081
2082 \begin_layout Description
2083 SPEEX_SET_VBR_QUALITY* Set the encoder VBR speech quality (float 0 to 10)
2084 \end_layout
2085
2086 \begin_layout Description
2087 SPEEX_GET_VBR_QUALITY* Get the current encoder VBR speech quality (float
2088  0 to 10)
2089 \end_layout
2090
2091 \begin_layout Description
2092 SPEEX_SET_COMPLEXITY* Set the CPU resources allowed for the encoder (spx_int32_t
2093  1 to 10)
2094 \end_layout
2095
2096 \begin_layout Description
2097 SPEEX_GET_COMPLEXITY* Get the CPU resources allowed for the encoder (spx_int32_t
2098  1 to 10)
2099 \end_layout
2100
2101 \begin_layout Description
2102 SPEEX_SET_BITRATE* Set the bit-rate to use to the closest value not exceeding
2103  the parameter (spx_int32_t in bps)
2104 \end_layout
2105
2106 \begin_layout Description
2107 SPEEX_GET_BITRATE Get the current bit-rate in use (spx_int32_t in bps)
2108 \end_layout
2109
2110 \begin_layout Description
2111 SPEEX_SET_SAMPLING_RATE Set real sampling rate (spx_int32_t in Hz)
2112 \end_layout
2113
2114 \begin_layout Description
2115 SPEEX_GET_SAMPLING_RATE Get real sampling rate (spx_int32_t in Hz)
2116 \end_layout
2117
2118 \begin_layout Description
2119 SPEEX_RESET_STATE Reset the encoder/decoder state to its original state,
2120  clearing all memories (no argument)
2121 \end_layout
2122
2123 \begin_layout Description
2124 SPEEX_SET_VAD* Set voice activity detection
2125 \begin_inset LatexCommand index
2126 name "voice activity detection"
2127
2128 \end_inset
2129
2130  (VAD) to on (1) or off (0) (spx_int32_t)
2131 \end_layout
2132
2133 \begin_layout Description
2134 SPEEX_GET_VAD* Get voice activity detection (VAD) status (spx_int32_t)
2135 \end_layout
2136
2137 \begin_layout Description
2138 SPEEX_SET_DTX* Set discontinuous transmission
2139 \begin_inset LatexCommand index
2140 name "discontinuous transmission"
2141
2142 \end_inset
2143
2144  (DTX) to on (1) or off (0) (spx_int32_t)
2145 \end_layout
2146
2147 \begin_layout Description
2148 SPEEX_GET_DTX* Get discontinuous transmission (DTX) status (spx_int32_t)
2149 \end_layout
2150
2151 \begin_layout Description
2152 SPEEX_SET_ABR* Set average bit-rate
2153 \begin_inset LatexCommand index
2154 name "average bit-rate"
2155
2156 \end_inset
2157
2158  (ABR) to a value n in bits per second (spx_int32_t in bps)
2159 \end_layout
2160
2161 \begin_layout Description
2162 SPEEX_GET_ABR* Get average bit-rate (ABR) setting (spx_int32_t in bps)
2163 \end_layout
2164
2165 \begin_layout Description
2166 SPEEX_SET_PLC_TUNING* Tell the encoder to optimize encoding for a certain
2167  percentage of packet loss (spx_int32_t in percent)
2168 \end_layout
2169
2170 \begin_layout Description
2171 SPEEX_GET_PLC_TUNING* Get the current tuning of the encoder for PLC (spx_int32_t
2172  in percent)
2173 \end_layout
2174
2175 \begin_layout Description
2176 SPEEX_SET_VBR_MAX_BITRATE* Set the maximum bit-rate allowed in VBR operation
2177  (spx_int32_t in bps)
2178 \end_layout
2179
2180 \begin_layout Description
2181 SPEEX_GET_VBR_MAX_BITRATE* Get the current maximum bit-rate allowed in VBR
2182  operation (spx_int32_t in bps)
2183 \end_layout
2184
2185 \begin_layout Description
2186 SPEEX_SET_HIGHPASS Set the high-pass filter on (1) or off (0) (spx_int32_t)
2187 \end_layout
2188
2189 \begin_layout Description
2190 SPEEX_TET_HIGHPASS Get the current high-pass filter status (spx_int32_t)
2191 \end_layout
2192
2193 \begin_layout Description
2194 * applies only to the encoder
2195 \end_layout
2196
2197 \begin_layout Description
2198 ** applies only to the decoder
2199 \end_layout
2200
2201 \begin_layout Description
2202 \begin_inset Formula $\dagger$
2203 \end_inset
2204
2205  If you can't understand from the source code what this does, you should
2206  not be using it in the first place
2207 \end_layout
2208
2209 \begin_layout Section
2210 Mode queries
2211 \begin_inset LatexCommand label
2212 name "sub:Mode-queries"
2213
2214 \end_inset
2215
2216
2217 \end_layout
2218
2219 \begin_layout Standard
2220 Speex modes have a query system similar to the speex_encoder_ctl and speex_decod
2221 er_ctl calls.
2222  Since modes are read-only, it is only possible to get information about
2223  a particular mode.
2224  The function used to do that is:
2225 \begin_inset listings
2226 inline false
2227 status open
2228
2229 \begin_layout Standard
2230
2231 void speex_mode_query(SpeexMode *mode, int request, void *ptr);
2232 \end_layout
2233
2234 \end_inset
2235
2236 The admissible values for request are (unless otherwise note, the values
2237  are returned through 
2238 \emph on
2239 ptr
2240 \emph default
2241 ):
2242 \end_layout
2243
2244 \begin_layout Description
2245 SPEEX_MODE_FRAME_SIZE Get the frame size (in samples) for the mode
2246 \end_layout
2247
2248 \begin_layout Description
2249 SPEEX_SUBMODE_BITRATE Get the bit-rate for a submode number specified through
2250  
2251 \emph on
2252 ptr
2253 \emph default
2254  (integer in bps).
2255  
2256 \end_layout
2257
2258 \begin_layout Section
2259 Packing and in-band signalling
2260 \begin_inset LatexCommand index
2261 name "in-band signalling"
2262
2263 \end_inset
2264
2265
2266 \end_layout
2267
2268 \begin_layout Standard
2269 Sometimes it is desirable to pack more than one frame per packet (or other
2270  basic unit of storage).
2271  The proper way to do it is to call speex_encode 
2272 \begin_inset Formula $N$
2273 \end_inset
2274
2275  times before writing the stream with speex_bits_write.
2276  In cases where the number of frames is not determined by an out-of-band
2277  mechanism, it is possible to include a terminator code.
2278  That terminator consists of the code 15 (decimal) encoded with 5 bits,
2279  as shown in Table 
2280 \begin_inset LatexCommand ref
2281 reference "cap:quality_vs_bps"
2282
2283 \end_inset
2284
2285 .
2286  Note that as of version 1.0.2, calling speex_bits_write automatically inserts
2287  the terminator so as to fill the last byte.
2288  This doesn't involves any overhead and makes sure Speex can always detect
2289  when there is no more frame in a packet.
2290 \end_layout
2291
2292 \begin_layout Standard
2293 It is also possible to send in-band 
2294 \begin_inset Quotes eld
2295 \end_inset
2296
2297 messages
2298 \begin_inset Quotes erd
2299 \end_inset
2300
2301  to the other side.
2302  All these messages are encoded as 
2303 \begin_inset Quotes eld
2304 \end_inset
2305
2306 pseudo-frames
2307 \begin_inset Quotes erd
2308 \end_inset
2309
2310  of mode 14 which contain a 4-bit message type code, followed by the message.
2311  Table 
2312 \begin_inset LatexCommand ref
2313 reference "cap:In-band-signalling-codes"
2314
2315 \end_inset
2316
2317  lists the available codes, their meaning and the size of the message that
2318  follows.
2319  Most of these messages are requests that are sent to the encoder or decoder
2320  on the other end, which is free to comply or ignore them.
2321  By default, all in-band messages are ignored.
2322 \end_layout
2323
2324 \begin_layout Standard
2325 \begin_inset Float table
2326 placement htbp
2327 wide false
2328 sideways false
2329 status open
2330
2331 \begin_layout Standard
2332 \begin_inset ERT
2333 status collapsed
2334
2335 \begin_layout Standard
2336
2337
2338 \backslash
2339 begin{center}
2340 \end_layout
2341
2342 \end_inset
2343
2344
2345 \begin_inset Tabular
2346 <lyxtabular version="3" rows="17" columns="3">
2347 <features>
2348 <column alignment="center" valignment="top" leftline="true" width="0pt">
2349 <column alignment="center" valignment="top" leftline="true" width="0pt">
2350 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
2351 <row topline="true" bottomline="true">
2352 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2353 \begin_inset Text
2354
2355 \begin_layout Standard
2356 Code
2357 \end_layout
2358
2359 \end_inset
2360 </cell>
2361 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2362 \begin_inset Text
2363
2364 \begin_layout Standard
2365 Size (bits)
2366 \end_layout
2367
2368 \end_inset
2369 </cell>
2370 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2371 \begin_inset Text
2372
2373 \begin_layout Standard
2374 Content
2375 \end_layout
2376
2377 \end_inset
2378 </cell>
2379 </row>
2380 <row topline="true">
2381 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2382 \begin_inset Text
2383
2384 \begin_layout Standard
2385 0
2386 \end_layout
2387
2388 \end_inset
2389 </cell>
2390 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2391 \begin_inset Text
2392
2393 \begin_layout Standard
2394 1
2395 \end_layout
2396
2397 \end_inset
2398 </cell>
2399 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2400 \begin_inset Text
2401
2402 \begin_layout Standard
2403 Asks decoder to set perceptual enhancement off (0) or on(1)
2404 \end_layout
2405
2406 \end_inset
2407 </cell>
2408 </row>
2409 <row topline="true">
2410 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2411 \begin_inset Text
2412
2413 \begin_layout Standard
2414 1
2415 \end_layout
2416
2417 \end_inset
2418 </cell>
2419 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2420 \begin_inset Text
2421
2422 \begin_layout Standard
2423 1
2424 \end_layout
2425
2426 \end_inset
2427 </cell>
2428 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2429 \begin_inset Text
2430
2431 \begin_layout Standard
2432 Asks (if 1) the encoder to be less 
2433 \begin_inset Quotes eld
2434 \end_inset
2435
2436 agressive
2437 \begin_inset Quotes erd
2438 \end_inset
2439
2440  due to high packet loss
2441 \end_layout
2442
2443 \end_inset
2444 </cell>
2445 </row>
2446 <row topline="true">
2447 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2448 \begin_inset Text
2449
2450 \begin_layout Standard
2451 2
2452 \end_layout
2453
2454 \end_inset
2455 </cell>
2456 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2457 \begin_inset Text
2458
2459 \begin_layout Standard
2460 4
2461 \end_layout
2462
2463 \end_inset
2464 </cell>
2465 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2466 \begin_inset Text
2467
2468 \begin_layout Standard
2469 Asks encoder to switch to mode N
2470 \end_layout
2471
2472 \end_inset
2473 </cell>
2474 </row>
2475 <row topline="true">
2476 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2477 \begin_inset Text
2478
2479 \begin_layout Standard
2480 3
2481 \end_layout
2482
2483 \end_inset
2484 </cell>
2485 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2486 \begin_inset Text
2487
2488 \begin_layout Standard
2489 4
2490 \end_layout
2491
2492 \end_inset
2493 </cell>
2494 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2495 \begin_inset Text
2496
2497 \begin_layout Standard
2498 Asks encoder to switch to mode N for low-band
2499 \end_layout
2500
2501 \end_inset
2502 </cell>
2503 </row>
2504 <row topline="true">
2505 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2506 \begin_inset Text
2507
2508 \begin_layout Standard
2509 4
2510 \end_layout
2511
2512 \end_inset
2513 </cell>
2514 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2515 \begin_inset Text
2516
2517 \begin_layout Standard
2518 4
2519 \end_layout
2520
2521 \end_inset
2522 </cell>
2523 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2524 \begin_inset Text
2525
2526 \begin_layout Standard
2527 Asks encoder to switch to mode N for high-band
2528 \end_layout
2529
2530 \end_inset
2531 </cell>
2532 </row>
2533 <row topline="true">
2534 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2535 \begin_inset Text
2536
2537 \begin_layout Standard
2538 5
2539 \end_layout
2540
2541 \end_inset
2542 </cell>
2543 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2544 \begin_inset Text
2545
2546 \begin_layout Standard
2547 4
2548 \end_layout
2549
2550 \end_inset
2551 </cell>
2552 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2553 \begin_inset Text
2554
2555 \begin_layout Standard
2556 Asks encoder to switch to quality N for VBR
2557 \end_layout
2558
2559 \end_inset
2560 </cell>
2561 </row>
2562 <row topline="true">
2563 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2564 \begin_inset Text
2565
2566 \begin_layout Standard
2567 6
2568 \end_layout
2569
2570 \end_inset
2571 </cell>
2572 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2573 \begin_inset Text
2574
2575 \begin_layout Standard
2576 4
2577 \end_layout
2578
2579 \end_inset
2580 </cell>
2581 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2582 \begin_inset Text
2583
2584 \begin_layout Standard
2585 Request acknowloedge (0=no, 1=all, 2=only for in-band data)
2586 \end_layout
2587
2588 \end_inset
2589 </cell>
2590 </row>
2591 <row topline="true">
2592 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2593 \begin_inset Text
2594
2595 \begin_layout Standard
2596 7
2597 \end_layout
2598
2599 \end_inset
2600 </cell>
2601 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2602 \begin_inset Text
2603
2604 \begin_layout Standard
2605 4
2606 \end_layout
2607
2608 \end_inset
2609 </cell>
2610 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2611 \begin_inset Text
2612
2613 \begin_layout Standard
2614 Asks encoder to set CBR (0), VAD(1), DTX(3), VBR(5), VBR+DTX(7)
2615 \end_layout
2616
2617 \end_inset
2618 </cell>
2619 </row>
2620 <row topline="true">
2621 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2622 \begin_inset Text
2623
2624 \begin_layout Standard
2625 8
2626 \end_layout
2627
2628 \end_inset
2629 </cell>
2630 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2631 \begin_inset Text
2632
2633 \begin_layout Standard
2634 8
2635 \end_layout
2636
2637 \end_inset
2638 </cell>
2639 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2640 \begin_inset Text
2641
2642 \begin_layout Standard
2643 Transmit (8-bit) character to the other end
2644 \end_layout
2645
2646 \end_inset
2647 </cell>
2648 </row>
2649 <row topline="true">
2650 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2651 \begin_inset Text
2652
2653 \begin_layout Standard
2654 9
2655 \end_layout
2656
2657 \end_inset
2658 </cell>
2659 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2660 \begin_inset Text
2661
2662 \begin_layout Standard
2663 8
2664 \end_layout
2665
2666 \end_inset
2667 </cell>
2668 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2669 \begin_inset Text
2670
2671 \begin_layout Standard
2672 Intensity stereo information
2673 \end_layout
2674
2675 \end_inset
2676 </cell>
2677 </row>
2678 <row topline="true">
2679 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2680 \begin_inset Text
2681
2682 \begin_layout Standard
2683 10
2684 \end_layout
2685
2686 \end_inset
2687 </cell>
2688 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2689 \begin_inset Text
2690
2691 \begin_layout Standard
2692 16
2693 \end_layout
2694
2695 \end_inset
2696 </cell>
2697 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2698 \begin_inset Text
2699
2700 \begin_layout Standard
2701 Announce maximum bit-rate acceptable (N in bytes/second)
2702 \end_layout
2703
2704 \end_inset
2705 </cell>
2706 </row>
2707 <row topline="true">
2708 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2709 \begin_inset Text
2710
2711 \begin_layout Standard
2712 11
2713 \end_layout
2714
2715 \end_inset
2716 </cell>
2717 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2718 \begin_inset Text
2719
2720 \begin_layout Standard
2721 16
2722 \end_layout
2723
2724 \end_inset
2725 </cell>
2726 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2727 \begin_inset Text
2728
2729 \begin_layout Standard
2730 reserved
2731 \end_layout
2732
2733 \end_inset
2734 </cell>
2735 </row>
2736 <row topline="true">
2737 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2738 \begin_inset Text
2739
2740 \begin_layout Standard
2741 12
2742 \end_layout
2743
2744 \end_inset
2745 </cell>
2746 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2747 \begin_inset Text
2748
2749 \begin_layout Standard
2750 32
2751 \end_layout
2752
2753 \end_inset
2754 </cell>
2755 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2756 \begin_inset Text
2757
2758 \begin_layout Standard
2759 Acknowledge receiving packet N
2760 \end_layout
2761
2762 \end_inset
2763 </cell>
2764 </row>
2765 <row topline="true">
2766 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2767 \begin_inset Text
2768
2769 \begin_layout Standard
2770 13
2771 \end_layout
2772
2773 \end_inset
2774 </cell>
2775 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2776 \begin_inset Text
2777
2778 \begin_layout Standard
2779 32
2780 \end_layout
2781
2782 \end_inset
2783 </cell>
2784 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2785 \begin_inset Text
2786
2787 \begin_layout Standard
2788 reserved
2789 \end_layout
2790
2791 \end_inset
2792 </cell>
2793 </row>
2794 <row topline="true">
2795 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2796 \begin_inset Text
2797
2798 \begin_layout Standard
2799 14
2800 \end_layout
2801
2802 \end_inset
2803 </cell>
2804 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2805 \begin_inset Text
2806
2807 \begin_layout Standard
2808 64
2809 \end_layout
2810
2811 \end_inset
2812 </cell>
2813 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2814 \begin_inset Text
2815
2816 \begin_layout Standard
2817 reserved
2818 \end_layout
2819
2820 \end_inset
2821 </cell>
2822 </row>
2823 <row topline="true" bottomline="true">
2824 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2825 \begin_inset Text
2826
2827 \begin_layout Standard
2828 15
2829 \end_layout
2830
2831 \end_inset
2832 </cell>
2833 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2834 \begin_inset Text
2835
2836 \begin_layout Standard
2837 64
2838 \end_layout
2839
2840 \end_inset
2841 </cell>
2842 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2843 \begin_inset Text
2844
2845 \begin_layout Standard
2846 reserved
2847 \end_layout
2848
2849 \end_inset
2850 </cell>
2851 </row>
2852 </lyxtabular>
2853
2854 \end_inset
2855
2856
2857 \begin_inset ERT
2858 status collapsed
2859
2860 \begin_layout Standard
2861
2862
2863 \backslash
2864 end{center}
2865 \end_layout
2866
2867 \end_inset
2868
2869
2870 \end_layout
2871
2872 \begin_layout Standard
2873 \begin_inset Caption
2874
2875 \begin_layout Standard
2876 In-band signalling codes
2877 \begin_inset LatexCommand label
2878 name "cap:In-band-signalling-codes"
2879
2880 \end_inset
2881
2882
2883 \end_layout
2884
2885 \end_inset
2886
2887
2888 \end_layout
2889
2890 \end_inset
2891
2892
2893 \end_layout
2894
2895 \begin_layout Standard
2896 Finally, applications may define custom in-band messages using mode 13.
2897  The size of the message in bytes is encoded with 5 bits, so that the decoder
2898  can skip it if it doesn't know how to interpret it.
2899 \newpage
2900
2901 \end_layout
2902
2903 \begin_layout Chapter
2904 Speech Processing API (
2905 \emph on
2906 libspeexdsp
2907 \emph default
2908 )
2909 \end_layout
2910
2911 \begin_layout Standard
2912 As of version 1.2beta3, the non-codec parts of the Speex package are now
2913  in a separate library called 
2914 \emph on
2915 libspeexdsp
2916 \emph default
2917 .
2918  This library includes the preprocessor, the acoustic echo canceller, the
2919  jitter buffer, and the resampler.
2920  In a UNIX environment, it can be linked into a program by adding 
2921 \emph on
2922 -lspeexdsp -lm
2923 \emph default
2924  to the compiler command line.
2925  Just like for libspeex, 
2926 \series bold
2927 libspeexdsp calls are reentrant, but not thread-safe
2928 \series default
2929 .
2930  That means that it is fine to use calls from many threads, but 
2931 \series bold
2932 calls using the same state from multiple threads must be protected by mutexes
2933 \series default
2934 .
2935 \end_layout
2936
2937 \begin_layout Section
2938 Preprocessor
2939 \begin_inset LatexCommand label
2940 name "sub:Preprocessor"
2941
2942 \end_inset
2943
2944
2945 \end_layout
2946
2947 \begin_layout Standard
2948 \noindent
2949 In order to use the Speex preprocessor
2950 \begin_inset LatexCommand index
2951 name "preprocessor"
2952
2953 \end_inset
2954
2955 , you first need to:
2956 \begin_inset listings
2957 inline false
2958 status open
2959
2960 \begin_layout Standard
2961
2962 #include <speex/speex_preprocess.h>
2963 \end_layout
2964
2965 \end_inset
2966
2967
2968 \end_layout
2969
2970 \begin_layout Standard
2971 \noindent
2972 Then, a preprocessor state can be created as:
2973 \begin_inset listings
2974 inline false
2975 status open
2976
2977 \begin_layout Standard
2978
2979 SpeexPreprocessState *preprocess_state = speex_preprocess_state_init(frame_size,
2980  sampling_rate);
2981 \end_layout
2982
2983 \end_inset
2984
2985
2986 \end_layout
2987
2988 \begin_layout Standard
2989 \noindent
2990 and it is recommended to use the same value for 
2991 \family typewriter
2992 frame_size
2993 \family default
2994  as is used by the encoder (20 
2995 \emph on
2996 ms
2997 \emph default
2998 ).
2999 \end_layout
3000
3001 \begin_layout Standard
3002 For each input frame, you need to call:
3003 \end_layout
3004
3005 \begin_layout Standard
3006 \begin_inset listings
3007 inline false
3008 status open
3009
3010 \begin_layout Standard
3011
3012 speex_preprocess_run(preprocess_state, audio_frame);
3013 \end_layout
3014
3015 \end_inset
3016
3017
3018 \end_layout
3019
3020 \begin_layout Standard
3021 \noindent
3022 where 
3023 \family typewriter
3024 audio_frame
3025 \family default
3026  is used both as input and output.
3027  In cases where the output audio is not useful for a certain frame, it is
3028  possible to use instead:
3029 \end_layout
3030
3031 \begin_layout Standard
3032 \begin_inset listings
3033 inline false
3034 status open
3035
3036 \begin_layout Standard
3037
3038 speex_preprocess_estimate_update(preprocess_state, audio_frame);
3039 \end_layout
3040
3041 \end_inset
3042
3043
3044 \end_layout
3045
3046 \begin_layout Standard
3047 \noindent
3048 This call will update all the preprocessor internal state variables without
3049  computing the output audio, thus saving some CPU cycles.
3050 \end_layout
3051
3052 \begin_layout Standard
3053 The behaviour of the preprocessor can be changed using:
3054 \end_layout
3055
3056 \begin_layout Standard
3057 \begin_inset listings
3058 inline false
3059 status open
3060
3061 \begin_layout Standard
3062
3063 speex_preprocess_ctl(preprocess_state, request, ptr);
3064 \end_layout
3065
3066 \end_inset
3067
3068
3069 \end_layout
3070
3071 \begin_layout Standard
3072 \noindent
3073 which is used in the same way as the encoder and decoder equivalent.
3074  Options are listed in Section 
3075 \begin_inset LatexCommand ref
3076 reference "sub:Preprocessor-options"
3077
3078 \end_inset
3079
3080 .
3081 \end_layout
3082
3083 \begin_layout Standard
3084 The preprocessor state can be destroyed using:
3085 \end_layout
3086
3087 \begin_layout Standard
3088 \begin_inset listings
3089 inline false
3090 status open
3091
3092 \begin_layout Standard
3093
3094 speex_preprocess_state_destroy(preprocess_state);
3095 \end_layout
3096
3097 \end_inset
3098
3099
3100 \end_layout
3101
3102 \begin_layout Subsection
3103 Preprocessor options
3104 \begin_inset LatexCommand label
3105 name "sub:Preprocessor-options"
3106
3107 \end_inset
3108
3109
3110 \end_layout
3111
3112 \begin_layout Standard
3113 As with the codec, the preprocessor also has options that can be controlled
3114  using an ioctl()-like call.
3115  The available options are:
3116 \end_layout
3117
3118 \begin_layout Description
3119 SPEEX_PREPROCESS_SET_DENOISE Turns denoising on(1) or off(2) (integer)
3120 \end_layout
3121
3122 \begin_layout Description
3123 SPEEX_PREPROCESS_GET_DENOISE Get denoising status (integer)
3124 \end_layout
3125
3126 \begin_layout Description
3127 SPEEX_PREPROCESS_SET_AGC Turns automatic gain control (AGC) on(1) or off(2)
3128  (integer)
3129 \end_layout
3130
3131 \begin_layout Description
3132 SPEEX_PREPROCESS_GET_AGC Get AGC status (integer)
3133 \end_layout
3134
3135 \begin_layout Description
3136 SPEEX_PREPROCESS_SET_VAD Turns voice activity detector (VAD) on(1) or off(2)
3137  (integer)
3138 \end_layout
3139
3140 \begin_layout Description
3141 SPEEX_PREPROCESS_GET_VAD Get VAD status (integer)
3142 \end_layout
3143
3144 \begin_layout Description
3145 SPEEX_PREPROCESS_SET_AGC_LEVEL
3146 \end_layout
3147
3148 \begin_layout Description
3149 SPEEX_PREPROCESS_GET_AGC_LEVEL
3150 \end_layout
3151
3152 \begin_layout Description
3153 SPEEX_PREPROCESS_SET_DEREVERB Turns reverberation removal on(1) or off(2)
3154  (integer)
3155 \end_layout
3156
3157 \begin_layout Description
3158 SPEEX_PREPROCESS_GET_DEREVERB Get reverberation removal status (integer)
3159 \end_layout
3160
3161 \begin_layout Description
3162 SPEEX_PREPROCESS_SET_DEREVERB_LEVEL
3163 \end_layout
3164
3165 \begin_layout Description
3166 SPEEX_PREPROCESS_GET_DEREVERB_LEVEL
3167 \end_layout
3168
3169 \begin_layout Description
3170 SPEEX_PREPROCESS_SET_DEREVERB_DECAY
3171 \end_layout
3172
3173 \begin_layout Description
3174 SPEEX_PREPROCESS_GET_DEREVERB_DECAY
3175 \end_layout
3176
3177 \begin_layout Description
3178 SPEEX_PREPROCESS_SET_PROB_START
3179 \end_layout
3180
3181 \begin_layout Description
3182 SPEEX_PREPROCESS_GET_PROB_START
3183 \end_layout
3184
3185 \begin_layout Description
3186 SPEEX_PREPROCESS_SET_PROB_CONTINUE
3187 \end_layout
3188
3189 \begin_layout Description
3190 SPEEX_PREPROCESS_GET_PROB_CONTINUE
3191 \end_layout
3192
3193 \begin_layout Description
3194 SPEEX_PREPROCESS_SET_NOISE_SUPPRESS Set maximum attenuation of the noise
3195  in dB (negative number)
3196 \end_layout
3197
3198 \begin_layout Description
3199 SPEEX_PREPROCESS_GET_NOISE_SUPPRESS Get maximum attenuation of the noise
3200  in dB (negative number)
3201 \end_layout
3202
3203 \begin_layout Description
3204 SPEEX_PREPROCESS_SET_ECHO_SUPPRESS Set maximum attenuation of the residual
3205  echo in dB (negative number)
3206 \end_layout
3207
3208 \begin_layout Description
3209 SPEEX_PREPROCESS_GET_ECHO_SUPPRESS Set maximum attenuation of the residual
3210  echo in dB (negative number)
3211 \end_layout
3212
3213 \begin_layout Description
3214 SPEEX_PREPROCESS_SET_ECHO_SUPPRESS_ACTIVE Set maximum attenuation of the
3215  echo in dB when near end is active (negative number)
3216 \end_layout
3217
3218 \begin_layout Description
3219 SPEEX_PREPROCESS_GET_ECHO_SUPPRESS_ACTIVE Set maximum attenuation of the
3220  echo in dB when near end is active (negative number)
3221 \end_layout
3222
3223 \begin_layout Description
3224 SPEEX_PREPROCESS_SET_ECHO_STATE Set the associated echo canceller for residual
3225  echo suppression (NULL for no residual echo suppression)
3226 \end_layout
3227
3228 \begin_layout Description
3229 SPEEX_PREPROCESS_GET_ECHO_STATE Get the associated echo canceller
3230 \end_layout
3231
3232 \begin_layout Section
3233 Echo Cancellation
3234 \begin_inset LatexCommand label
3235 name "sub:Echo-Cancellation"
3236
3237 \end_inset
3238
3239
3240 \end_layout
3241
3242 \begin_layout Standard
3243 The Speex library now includes an echo cancellation
3244 \begin_inset LatexCommand index
3245 name "echo cancellation"
3246
3247 \end_inset
3248
3249  algorithm suitable for Acoustic Echo Cancellation
3250 \begin_inset LatexCommand index
3251 name "acoustic echo cancellation"
3252
3253 \end_inset
3254
3255  (AEC).
3256  In order to use the echo canceller, you first need to
3257 \end_layout
3258
3259 \begin_layout Standard
3260 \begin_inset listings
3261 inline false
3262 status open
3263
3264 \begin_layout Standard
3265
3266 #include <speex/speex_echo.h>
3267 \end_layout
3268
3269 \end_inset
3270
3271
3272 \end_layout
3273
3274 \begin_layout Standard
3275 Then, an echo canceller state can be created by:
3276 \end_layout
3277
3278 \begin_layout Standard
3279 \begin_inset listings
3280 inline false
3281 status open
3282
3283 \begin_layout Standard
3284
3285 SpeexEchoState *echo_state = speex_echo_state_init(frame_size, filter_length);
3286 \end_layout
3287
3288 \end_inset
3289
3290
3291 \end_layout
3292
3293 \begin_layout Standard
3294 where 
3295 \family typewriter
3296 frame_size
3297 \family default
3298  is the amount of data (in samples) you want to process at once and 
3299 \family typewriter
3300 filter_length
3301 \family default
3302  is the length (in samples) of the echo cancelling filter you want to use
3303  (also known as 
3304 \shape italic
3305 tail length
3306 \shape default
3307
3308 \begin_inset LatexCommand index
3309 name "tail length"
3310
3311 \end_inset
3312
3313 ).
3314  It is recommended to use a frame size in the order of 20 ms (or equal to
3315  the codec frame size) and make sure it is easy to perform an FFT of that
3316  size (powers of two are better than prime sizes).
3317  The recommended tail length is approximately the third of the room reverberatio
3318 n time.
3319  For example, in a small room, reverberation time is in the order of 300
3320  ms, so a tail length of 100 ms is a good choice (800 samples at 8000 Hz
3321  sampling rate).
3322 \end_layout
3323
3324 \begin_layout Standard
3325 Once the echo canceller state is created, audio can be processed by:
3326 \end_layout
3327
3328 \begin_layout Standard
3329 \begin_inset listings
3330 inline false
3331 status open
3332
3333 \begin_layout Standard
3334
3335 speex_echo_cancellation(echo_state, input_frame, echo_frame, output_frame);
3336 \end_layout
3337
3338 \end_inset
3339
3340
3341 \end_layout
3342
3343 \begin_layout Standard
3344 where 
3345 \family typewriter
3346 input_frame
3347 \family default
3348  is the audio as captured by the microphone, 
3349 \family typewriter
3350 echo_frame
3351 \family default
3352  is the signal that was played in the speaker (and needs to be removed)
3353  and 
3354 \family typewriter
3355 output_frame
3356 \family default
3357  is the signal with echo removed.
3358  
3359 \end_layout
3360
3361 \begin_layout Standard
3362 One important thing to keep in mind is the relationship between 
3363 \family typewriter
3364 input_frame
3365 \family default
3366  and 
3367 \family typewriter
3368 echo_frame
3369 \family default
3370 .
3371  It is important that, at any time, any echo that is present in the input
3372  has already been sent to the echo canceller as 
3373 \family typewriter
3374 echo_frame
3375 \family default
3376 .
3377  In other words, the echo canceller cannot remove a signal that it hasn't
3378  yet received.
3379  On the other hand, the delay between the input signal and the echo signal
3380  must be small enough because otherwise part of the echo cancellation filter
3381  is inefficient.
3382  In the ideal case, you code would look like:
3383 \begin_inset listings
3384 lstparams "breaklines=true"
3385 inline false
3386 status open
3387
3388 \begin_layout Standard
3389
3390 write_to_soundcard(echo_frame, frame_size);
3391 \end_layout
3392
3393 \begin_layout Standard
3394
3395 read_from_soundcard(input_frame, frame_size);
3396 \end_layout
3397
3398 \begin_layout Standard
3399
3400 speex_echo_cancellation(echo_state, input_frame, echo_frame, output_frame);
3401 \end_layout
3402
3403 \end_inset
3404
3405
3406 \end_layout
3407
3408 \begin_layout Standard
3409 If you wish to further reduce the echo present in the signal, you can do
3410  so by associating the echo canceller to the preprocessor (see Section 
3411 \begin_inset LatexCommand ref
3412 reference "sub:Preprocessor"
3413
3414 \end_inset
3415
3416 ).
3417  This is done by calling:
3418 \begin_inset listings
3419 lstparams "breaklines=true"
3420 inline false
3421 status open
3422
3423 \begin_layout Standard
3424
3425 speex_preprocess_ctl(preprocess_state, SPEEX_PREPROCESS_SET_ECHO_STATE,echo_stat
3426 e);
3427 \end_layout
3428
3429 \end_inset
3430
3431 in the initialisation.
3432 \end_layout
3433
3434 \begin_layout Standard
3435 As of version 1.2-beta2, there is an alternative, simpler API that can be
3436  used instead of 
3437 \emph on
3438 speex_echo_cancellation()
3439 \emph default
3440 .
3441  When audio capture and playback are handled asynchronously (e.g.
3442  in different threads or using the 
3443 \emph on
3444 poll()
3445 \emph default
3446  or 
3447 \emph on
3448 select()
3449 \emph default
3450  system call), it can be difficult to keep track of what input_frame comes
3451  with what echo_frame.
3452  Instead, the playback comtext/thread can simply call:
3453 \end_layout
3454
3455 \begin_layout Standard
3456 \begin_inset listings
3457 inline false
3458 status open
3459
3460 \begin_layout Standard
3461
3462 speex_echo_playback(echo_state, echo_frame);
3463 \end_layout
3464
3465 \end_inset
3466
3467
3468 \end_layout
3469
3470 \begin_layout Standard
3471 every time an audio frame is played.
3472  Then, the capture context/thread calls:
3473 \end_layout
3474
3475 \begin_layout Standard
3476 \begin_inset listings
3477 inline false
3478 status open
3479
3480 \begin_layout Standard
3481
3482 speex_echo_capture(echo_state, input_frame, output_frame);
3483 \end_layout
3484
3485 \end_inset
3486
3487
3488 \end_layout
3489
3490 \begin_layout Standard
3491 for every frame captured.
3492  Internally, 
3493 \emph on
3494 speex_echo_playback()
3495 \emph default
3496  simply buffers the playback frame so it can be used by 
3497 \emph on
3498 speex_echo_capture()
3499 \emph default
3500  to call 
3501 \emph on
3502 speex_echo_cancel()
3503 \emph default
3504 .
3505  A side effect of using this alternate API is that the playback audio is
3506  delayed by two frames, which is the normal delay caused by the soundcard.
3507  When capture and playback are already synchronised, 
3508 \emph on
3509 speex_echo_cancellation()
3510 \emph default
3511  is preferable since it gives better control on the exact input/echo timing.
3512 \end_layout
3513
3514 \begin_layout Standard
3515 The echo cancellation state can be destroyed with:
3516 \end_layout
3517
3518 \begin_layout Standard
3519 \begin_inset listings
3520 inline false
3521 status open
3522
3523 \begin_layout Standard
3524
3525 speex_echo_state_destroy(echo_state);
3526 \end_layout
3527
3528 \end_inset
3529
3530
3531 \end_layout
3532
3533 \begin_layout Standard
3534 It is also possible to reset the state of the echo canceller so it can be
3535  reused without the need to create another state with:
3536 \end_layout
3537
3538 \begin_layout Standard
3539 \begin_inset listings
3540 inline false
3541 status open
3542
3543 \begin_layout Standard
3544
3545 speex_echo_state_reset(echo_state);
3546 \end_layout
3547
3548 \end_inset
3549
3550
3551 \end_layout
3552
3553 \begin_layout Subsection
3554 Troubleshooting
3555 \end_layout
3556
3557 \begin_layout Standard
3558 There are several things that may prevent the echo canceller from working
3559  properly.
3560  One of them is a bug (or something suboptimal) in the code, but there are
3561  many others you should consider first
3562 \end_layout
3563
3564 \begin_layout Itemize
3565 Using a different soundcard to do the capture and plaback will 
3566 \series bold
3567 not
3568 \series default
3569  work, regardless of what you may think.
3570  The only exception to that is if the two cards can be made to have their
3571  sampling clock 
3572 \begin_inset Quotes eld
3573 \end_inset
3574
3575 locked
3576 \begin_inset Quotes erd
3577 \end_inset
3578
3579  on the same clock source.
3580  If not, the clocks will always have a small amount of drift, which will
3581  prevent the echo canceller from adapting.
3582 \end_layout
3583
3584 \begin_layout Itemize
3585 The delay between the record and playback signals must be minimal.
3586  Any signal played has to 
3587 \begin_inset Quotes eld
3588 \end_inset
3589
3590 appear
3591 \begin_inset Quotes erd
3592 \end_inset
3593
3594  on the playback (far end) signal slightly before the echo canceller 
3595 \begin_inset Quotes eld
3596 \end_inset
3597
3598 sees
3599 \begin_inset Quotes erd
3600 \end_inset
3601
3602  it in the near end signal, but excessive delay means that part of the filter
3603  length is wasted.
3604  In the worst situations, the delay is such that it is longer than the filter
3605  length, in which case, no echo can be cancelled.
3606 \end_layout
3607
3608 \begin_layout Itemize
3609 When it comes to echo tail length (filter length), longer is *not* better.
3610  Actually, the longer the tail length, the longer it takes for the filter
3611  to adapt.
3612  Of course, a tail length that is too short will not cancel enough echo,
3613  but the most common problem seen is that people set a very long tail length
3614  and then wonder why no echo is being cancelled.
3615 \end_layout
3616
3617 \begin_layout Itemize
3618 Non-linear distortion cannot (by definition) be modeled by the linear adaptive
3619  filter used in the echo canceller and thus cannot be cancelled.
3620  Use good audio gear and avoid saturation/clipping.
3621 \end_layout
3622
3623 \begin_layout Standard
3624 Also useful is reading 
3625 \emph on
3626 Echo Cancellation Demystified
3627 \emph default
3628  by Alexey Frunze
3629 \begin_inset Foot
3630 status collapsed
3631
3632 \begin_layout Standard
3633 http://www.embeddedstar.com/articles/2003/7/article20030720-1.html
3634 \end_layout
3635
3636 \end_inset
3637
3638 , which explains the fundamental principles of echo cancellation.
3639  The details of the algorithm described in the article are different, but
3640  the general ideas of echo cancellation through adaptive filters are the
3641  same.
3642 \end_layout
3643
3644 \begin_layout Standard
3645 As of version 1.2beta2, a new 
3646 \family typewriter
3647 echo_diagnostic.m
3648 \family default
3649  tool is included in the source distribution.
3650  The first step is to define DUMP_ECHO_CANCEL_DATA during the build.
3651  This causes the echo canceller to automatically save the near-end, far-end
3652  and output signals to files (aec_rec.sw aec_play.sw and aec_out.sw).
3653  These are exactly what the AEC receives and outputs.
3654  From there, it is necessary to start Octave and type:
3655 \end_layout
3656
3657 \begin_layout Standard
3658 \begin_inset listings
3659 lstparams "language=Matlab"
3660 inline false
3661 status open
3662
3663 \begin_layout Standard
3664
3665 echo_diagnostic('aec_rec.sw', 'aec_play.sw', 'aec_diagnostic.sw', 1024);
3666 \end_layout
3667
3668 \end_inset
3669
3670
3671 \end_layout
3672
3673 \begin_layout Standard
3674 The value of 1024 is the filter length and can be changed.
3675  There will be some (hopefully) useful messages printed and echo cancelled
3676  audio will be saved to aec_diagnostic.sw .
3677  If even that output is bad (almost no cancellation) then there is  probably
3678  problem with the playback or recording process.
3679 \end_layout
3680
3681 \begin_layout Section
3682 Jitter Buffer
3683 \end_layout
3684
3685 \begin_layout Standard
3686 The jitter buffer can be enabled by including:
3687 \begin_inset listings
3688 lstparams "breaklines=true"
3689 inline false
3690 status open
3691
3692 \begin_layout Standard
3693
3694 #include <speex/speex_jitter.h>
3695 \end_layout
3696
3697 \end_inset
3698
3699  and a new jitter buffer state can be initialised by:
3700 \end_layout
3701
3702 \begin_layout Standard
3703 \begin_inset listings
3704 lstparams "breaklines=true"
3705 inline false
3706 status open
3707
3708 \begin_layout Standard
3709
3710 JitterBuffer *state = jitter_buffer_init(tick);
3711 \end_layout
3712
3713 \end_inset
3714
3715
3716 \end_layout
3717
3718 \begin_layout Standard
3719 where the 
3720 \begin_inset listings
3721 inline true
3722 status collapsed
3723
3724 \begin_layout Standard
3725
3726 tick
3727 \end_layout
3728
3729 \end_inset
3730
3731  argument is the time resolution (in timestamp units) used for the jitter
3732  buffer, and is generally the period at which the data is played out of
3733  the jitter buffer.
3734  
3735 \end_layout
3736
3737 \begin_layout Standard
3738 The jitter buffer API is based on the 
3739 \begin_inset listings
3740 inline true
3741 status open
3742
3743 \begin_layout Standard
3744
3745 JitterBufferPacket
3746 \end_layout
3747
3748 \end_inset
3749
3750  type, which is defined as:
3751 \begin_inset listings
3752 inline false
3753 status open
3754
3755 \begin_layout Standard
3756
3757 typedef struct {
3758 \end_layout
3759
3760 \begin_layout Standard
3761
3762    char        *data;       /* Data bytes contained in the packet */
3763 \end_layout
3764
3765 \begin_layout Standard
3766
3767    spx_uint32_t len;        /* Length of the packet in bytes */
3768 \end_layout
3769
3770 \begin_layout Standard
3771
3772    spx_uint32_t timestamp;  /* Timestamp for the packet */
3773 \end_layout
3774
3775 \begin_layout Standard
3776
3777    spx_uint32_t span;       /* Time covered by the packet (timestamp units)
3778  */
3779 \end_layout
3780
3781 \begin_layout Standard
3782
3783 } JitterBufferPacket; 
3784 \end_layout
3785
3786 \end_inset
3787
3788
3789 \end_layout
3790
3791 \begin_layout Standard
3792 When a packet arrives, it need to be inserter into the jitter buffer by:
3793 \begin_inset listings
3794 inline false
3795 status open
3796
3797 \begin_layout Standard
3798
3799 JitterBufferPacket packet;
3800 \end_layout
3801
3802 \begin_layout Standard
3803
3804 /* Fill in the packet fields */
3805 \end_layout
3806
3807 \begin_layout Standard
3808
3809 jitter_buffer_put(state, &packet);
3810 \end_layout
3811
3812 \end_inset
3813
3814
3815 \end_layout
3816
3817 \begin_layout Standard
3818 When the decoder is ready to decode a packet the packet to be decoded can
3819  be obtained by: 
3820 \begin_inset listings
3821 inline false
3822 status open
3823
3824 \begin_layout Standard
3825
3826 int start_offset;
3827 \end_layout
3828
3829 \begin_layout Standard
3830
3831 err = jitter_buffer_get(state, &packet, &start_offset);
3832 \end_layout
3833
3834 \end_inset
3835
3836
3837 \end_layout
3838
3839 \begin_layout Standard
3840 If 
3841 \begin_inset listings
3842 inline true
3843 status open
3844
3845 \begin_layout Standard
3846
3847 jitter_buffer_put()
3848 \end_layout
3849
3850 \end_inset
3851
3852  and 
3853 \begin_inset listings
3854 inline true
3855 status open
3856
3857 \begin_layout Standard
3858
3859 jitter_buffer_get()
3860 \end_layout
3861
3862 \end_inset
3863
3864  are called from different threads, then 
3865 \series bold
3866 you need to protect the jitter buffer state with a mutex
3867 \series default
3868 .
3869  
3870 \end_layout
3871
3872 \begin_layout Standard
3873 Because the jitter buffer is designed not to use an explicit timer, it needs
3874  to be told about the time explicitly.
3875  This is done by calling: 
3876 \begin_inset listings
3877 inline false
3878 status open
3879
3880 \begin_layout Standard
3881
3882 jitter_buffer_tick(state);
3883 \end_layout
3884
3885 \end_inset
3886
3887
3888 \end_layout
3889
3890 \begin_layout Standard
3891 This needs to be done every time 
3892 \begin_inset listings
3893 inline true
3894 status collapsed
3895
3896 \begin_layout Standard
3897
3898 tick
3899 \end_layout
3900
3901 \end_inset
3902
3903  units have elapsed.
3904  
3905 \end_layout
3906
3907 \begin_layout Section
3908 Resampler
3909 \end_layout
3910
3911 \begin_layout Standard
3912 Speex includes a resampling modules.
3913  To make use of the resampler, it is necessary to include its header file:
3914 \end_layout
3915
3916 \begin_layout Standard
3917 \begin_inset listings
3918 inline false
3919 status open
3920
3921 \begin_layout Standard
3922
3923 #include <speex/speex_resampler.h>
3924 \end_layout
3925
3926 \end_inset
3927
3928
3929 \end_layout
3930
3931 \begin_layout Standard
3932 For each stream that is to be resampled, it is necessary to create a resampler
3933  state with:
3934 \end_layout
3935
3936 \begin_layout Standard
3937 \begin_inset listings
3938 inline false
3939 status open
3940
3941 \begin_layout Standard
3942
3943 SpeexResamplerState *resampler;
3944 \end_layout
3945
3946 \begin_layout Standard
3947
3948 resampler = speex_resampler_init(nb_channels, input_rate, output_rate, quality,
3949  &err);
3950 \end_layout
3951
3952 \end_inset
3953
3954
3955 \end_layout
3956
3957 \begin_layout Standard
3958 where nb_channels is the number of channels that will be used (either interleave
3959 d or non-interleaved), input_rate is the sampling rate of the input stream,
3960  output_rate is the sampling rate of the output stream and quality is the
3961  requested quality setting (0 to 10).
3962  The quality parameter is useful for controlling the quality/complexity/latency
3963  tradeoff.
3964  Using a higher quality setting means less noise/aliasing, a higher complexity
3965  and a higher latency.
3966  Usually, a quality of 3 is acceptable for most desktop uses and quality
3967  10 is mostly recommended for pro audio work.
3968  Quality 0 usually has a decent sound (certainly better than using linear
3969  interpolation resampling), but artifacts may be heard.
3970 \end_layout
3971
3972 \begin_layout Standard
3973 The actual resampling is performed using
3974 \end_layout
3975
3976 \begin_layout Standard
3977 \begin_inset listings
3978 inline false
3979 status open
3980
3981 \begin_layout Standard
3982
3983 err = speex_resampler_process_int(resampler, channelID, in, &in_length,
3984  out, &out_length);
3985 \end_layout
3986
3987 \end_inset
3988
3989 where channelID is the ID of the channel to be processed.
3990  For a mono stream, use 0.
3991  The 
3992 \emph on
3993 in
3994 \emph default
3995  pointer points to the first sample of the input buffer for the selected
3996  channel and 
3997 \emph on
3998 out
3999 \emph default
4000  points to the first sample of the output.
4001  The size of the input and output buffers are specified by 
4002 \emph on
4003 in_length
4004 \emph default
4005  and 
4006 \emph on
4007 out_length
4008 \emph default
4009  respectively.
4010  Upon completion, these values are replaced by the number of samples read
4011  and written by the resampler.
4012  Unless an error occurs, either all input samples will be read or all output
4013  samples will be written to (or both).
4014  For floating-point samples, the function speex_resampler_process_float()
4015  behaves similarly.
4016 \end_layout
4017
4018 \begin_layout Standard
4019 It is also possible to process multiple channels at once.
4020  
4021 \end_layout
4022
4023 \begin_layout Standard
4024
4025 \newpage
4026
4027 \end_layout
4028
4029 \begin_layout Chapter
4030 Formats and standards
4031 \begin_inset LatexCommand index
4032 name "standards"
4033
4034 \end_inset
4035
4036
4037 \begin_inset LatexCommand label
4038 name "sec:Formats-and-standards"
4039
4040 \end_inset
4041
4042
4043 \end_layout
4044
4045 \begin_layout Standard
4046 Speex can encode speech in both narrowband and wideband and provides different
4047  bit-rates.
4048  However, not all features need to be supported by a certain implementation
4049  or device.
4050  In order to be called 
4051 \begin_inset Quotes eld
4052 \end_inset
4053
4054 Speex compatible
4055 \begin_inset Quotes erd
4056 \end_inset
4057
4058  (whatever that means), an implementation must implement at least a basic
4059  set of features.
4060 \end_layout
4061
4062 \begin_layout Standard
4063 At the minimum, all narrowband modes of operation MUST be supported at the
4064  decoder.
4065  This includes the decoding of a wideband bit-stream by the narrowband decoder
4066 \begin_inset Foot
4067 status collapsed
4068
4069 \begin_layout Standard
4070 The wideband bit-stream contains an embedded narrowband bit-stream which
4071  can be decoded alone
4072 \end_layout
4073
4074 \end_inset
4075
4076 .
4077  If present, a wideband decoder MUST be able to decode a narrowband stream,
4078  and MAY either be able to decode all wideband modes or be able to decode
4079  the embedded narrowband part of all modes (which includes ignoring the
4080  high-band bits).
4081 \end_layout
4082
4083 \begin_layout Standard
4084 For encoders, at least one narrowband or wideband mode MUST be supported.
4085  The main reason why all encoding modes do not have to be supported is that
4086  some platforms may not be able to handle the complexity of encoding in
4087  some modes.
4088 \end_layout
4089
4090 \begin_layout Section
4091 RTP
4092 \begin_inset LatexCommand index
4093 name "RTP"
4094
4095 \end_inset
4096
4097  Payload Format 
4098 \end_layout
4099
4100 \begin_layout Standard
4101 The RTP payload draft is included in appendix 
4102 \begin_inset LatexCommand ref
4103 reference "sec:IETF-draft"
4104
4105 \end_inset
4106
4107  and the latest version is available at 
4108 \begin_inset LatexCommand url
4109 target "http://www.speex.org/drafts/latest"
4110
4111 \end_inset
4112
4113 .
4114  This draft has been sent (2003/02/26) to the Internet Engineering Task
4115  Force (IETF) and will be discussed at the March 18th meeting in San Francisco.
4116  
4117 \end_layout
4118
4119 \begin_layout Section
4120 MIME Type
4121 \end_layout
4122
4123 \begin_layout Standard
4124 For now, you should use the MIME type audio/x-speex for Speex-in-Ogg.
4125  We will apply for type 
4126 \family typewriter
4127 audio/speex
4128 \family default
4129  in the near future.
4130 \end_layout
4131
4132 \begin_layout Section
4133 Ogg
4134 \begin_inset LatexCommand index
4135 name "Ogg"
4136
4137 \end_inset
4138
4139  file format
4140 \end_layout
4141
4142 \begin_layout Standard
4143 Speex bit-streams can be stored in Ogg files.
4144  In this case, the first packet of the Ogg file contains the Speex header
4145  described in table 
4146 \begin_inset LatexCommand ref
4147 reference "cap:ogg_speex_header"
4148
4149 \end_inset
4150
4151 .
4152  All integer fields in the headers are stored as little-endian.
4153  The 
4154 \family typewriter
4155 speex_string
4156 \family default
4157  field must contain the 
4158 \begin_inset Quotes eld
4159 \end_inset
4160
4161
4162 \family typewriter
4163 Speex
4164 \family default
4165 \InsetSpace ~
4166 \InsetSpace ~
4167 \InsetSpace ~
4168
4169 \begin_inset Quotes erd
4170 \end_inset
4171
4172  (with 3 trailing spaces), which identifies the bit-stream.
4173  The next field, 
4174 \family typewriter
4175 speex_version
4176 \family default
4177  contains the version of Speex that encoded the file.
4178  For now, refer to speex_header.[ch] for more info.
4179  The 
4180 \emph on
4181 beginning of stream
4182 \emph default
4183  (
4184 \family typewriter
4185 b_o_s
4186 \family default
4187 ) flag is set to 1 for the header.
4188  The header packet has 
4189 \family typewriter
4190 packetno=0
4191 \family default
4192  and 
4193 \family typewriter
4194 granulepos=0
4195 \family default
4196 .
4197 \end_layout
4198
4199 \begin_layout Standard
4200 The second packet contains the Speex comment header.
4201  The format used is the Vorbis comment format described here: http://www.xiph.org/
4202 ogg/vorbis/doc/v-comment.html .
4203  This packet has 
4204 \family typewriter
4205 packetno=1
4206 \family default
4207  and 
4208 \family typewriter
4209 granulepos=0
4210 \family default
4211 .
4212 \end_layout
4213
4214 \begin_layout Standard
4215 The third and subsequent packets each contain one or more (number found
4216  in header) Speex frames.
4217  These are identified with 
4218 \family typewriter
4219 packetno
4220 \family default
4221  starting from 2 and the 
4222 \family typewriter
4223 granulepos
4224 \family default
4225  is the number of the last sample encoded in that packet.
4226  The last of these packets has the 
4227 \emph on
4228 end of stream
4229 \emph default
4230  (
4231 \family typewriter
4232 e_o_s
4233 \family default
4234 ) flag is set to 1.
4235 \end_layout
4236
4237 \begin_layout Standard
4238 \begin_inset Float table
4239 placement htbp
4240 wide true
4241 sideways false
4242 status open
4243
4244 \begin_layout Standard
4245 \begin_inset ERT
4246 status collapsed
4247
4248 \begin_layout Standard
4249
4250
4251 \backslash
4252 begin{center}
4253 \end_layout
4254
4255 \end_inset
4256
4257
4258 \begin_inset Tabular
4259 <lyxtabular version="3" rows="16" columns="3">
4260 <features>
4261 <column alignment="center" valignment="top" leftline="true" width="0pt">
4262 <column alignment="center" valignment="top" leftline="true" width="0pt">
4263 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
4264 <row topline="true" bottomline="true">
4265 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4266 \begin_inset Text
4267
4268 \begin_layout Standard
4269 Field
4270 \end_layout
4271
4272 \end_inset
4273 </cell>
4274 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4275 \begin_inset Text
4276
4277 \begin_layout Standard
4278 Type
4279 \end_layout
4280
4281 \end_inset
4282 </cell>
4283 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4284 \begin_inset Text
4285
4286 \begin_layout Standard
4287 Size
4288 \end_layout
4289
4290 \end_inset
4291 </cell>
4292 </row>
4293 <row topline="true">
4294 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4295 \begin_inset Text
4296
4297 \begin_layout Standard
4298 speex_string
4299 \end_layout
4300
4301 \end_inset
4302 </cell>
4303 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4304 \begin_inset Text
4305
4306 \begin_layout Standard
4307 char[]
4308 \end_layout
4309
4310 \end_inset
4311 </cell>
4312 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4313 \begin_inset Text
4314
4315 \begin_layout Standard
4316 8
4317 \end_layout
4318
4319 \end_inset
4320 </cell>
4321 </row>
4322 <row topline="true">
4323 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4324 \begin_inset Text
4325
4326 \begin_layout Standard
4327 speex_version
4328 \end_layout
4329
4330 \end_inset
4331 </cell>
4332 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4333 \begin_inset Text
4334
4335 \begin_layout Standard
4336 char[]
4337 \end_layout
4338
4339 \end_inset
4340 </cell>
4341 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4342 \begin_inset Text
4343
4344 \begin_layout Standard
4345 20
4346 \end_layout
4347
4348 \end_inset
4349 </cell>
4350 </row>
4351 <row topline="true">
4352 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4353 \begin_inset Text
4354
4355 \begin_layout Standard
4356 speex_version_id
4357 \end_layout
4358
4359 \end_inset
4360 </cell>
4361 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4362 \begin_inset Text
4363
4364 \begin_layout Standard
4365 int
4366 \end_layout
4367
4368 \end_inset
4369 </cell>
4370 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4371 \begin_inset Text
4372
4373 \begin_layout Standard
4374 4
4375 \end_layout
4376
4377 \end_inset
4378 </cell>
4379 </row>
4380 <row topline="true">
4381 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4382 \begin_inset Text
4383
4384 \begin_layout Standard
4385 header_size
4386 \end_layout
4387
4388 \end_inset
4389 </cell>
4390 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4391 \begin_inset Text
4392
4393 \begin_layout Standard
4394 int
4395 \end_layout
4396
4397 \end_inset
4398 </cell>
4399 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4400 \begin_inset Text
4401
4402 \begin_layout Standard
4403 4
4404 \end_layout
4405
4406 \end_inset
4407 </cell>
4408 </row>
4409 <row topline="true">
4410 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4411 \begin_inset Text
4412
4413 \begin_layout Standard
4414 rate
4415 \end_layout
4416
4417 \end_inset
4418 </cell>
4419 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4420 \begin_inset Text
4421
4422 \begin_layout Standard
4423 int
4424 \end_layout
4425
4426 \end_inset
4427 </cell>
4428 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4429 \begin_inset Text
4430
4431 \begin_layout Standard
4432 4
4433 \end_layout
4434
4435 \end_inset
4436 </cell>
4437 </row>
4438 <row topline="true">
4439 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4440 \begin_inset Text
4441
4442 \begin_layout Standard
4443 mode
4444 \end_layout
4445
4446 \end_inset
4447 </cell>
4448 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4449 \begin_inset Text
4450
4451 \begin_layout Standard
4452 int
4453 \end_layout
4454
4455 \end_inset
4456 </cell>
4457 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4458 \begin_inset Text
4459
4460 \begin_layout Standard
4461 4
4462 \end_layout
4463
4464 \end_inset
4465 </cell>
4466 </row>
4467 <row topline="true">
4468 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4469 \begin_inset Text
4470
4471 \begin_layout Standard
4472 mode_bitstream_version
4473 \end_layout
4474
4475 \end_inset
4476 </cell>
4477 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4478 \begin_inset Text
4479
4480 \begin_layout Standard
4481 int
4482 \end_layout
4483
4484 \end_inset
4485 </cell>
4486 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4487 \begin_inset Text
4488
4489 \begin_layout Standard
4490 4
4491 \end_layout
4492
4493 \end_inset
4494 </cell>
4495 </row>
4496 <row topline="true">
4497 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4498 \begin_inset Text