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