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