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