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