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