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