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