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