...
[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 second 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 It is also possible to process multiple channels at once.
2206  
2207 \end_layout
2208
2209 \begin_layout Section
2210 Codec Options (speex_*_ctl)
2211 \begin_inset LatexCommand \label{sub:Codec-Options}
2212
2213 \end_inset
2214
2215
2216 \end_layout
2217
2218 \begin_layout Quote
2219 \align center
2220
2221 \emph on
2222 Entities should not be multiplied beyond necessity -- William of Ockham.
2223 \end_layout
2224
2225 \begin_layout Quote
2226 \align center
2227
2228 \emph on
2229 Just because there's an option doesn't mean you have to use it -- me.
2230 \end_layout
2231
2232 \begin_layout Standard
2233 The Speex encoder and decoder support many options and requests that can
2234  be accessed through the 
2235 \emph on
2236 speex_encoder_ctl
2237 \emph default
2238  and 
2239 \emph on
2240 speex_decoder_ctl
2241 \emph default
2242  functions.
2243  Despite that, the defaults are good for many applications and 
2244 \series bold
2245 optional settings should only be used when one understands them and knows
2246  that they are needed
2247 \series default
2248 .
2249  A common error is to attempt to set many unnecessary settings.
2250  These functions are similar to the 
2251 \emph on
2252 ioctl
2253 \emph default
2254  system call and their prototypes are:
2255 \end_layout
2256
2257 \begin_layout LyX-Code
2258 void speex_encoder_ctl(void *encoder, int request, void *ptr);
2259 \end_layout
2260
2261 \begin_layout LyX-Code
2262 void speex_decoder_ctl(void *encoder, int request, void *ptr);
2263 \end_layout
2264
2265 \begin_layout Standard
2266 The different values of request allowed are (note that some only apply to
2267  the encoder or the decoder):
2268 \end_layout
2269
2270 \begin_layout Description
2271 SPEEX_SET_ENH** Set perceptual enhancer
2272 \begin_inset LatexCommand \index{perceptual enhancement}
2273
2274 \end_inset
2275
2276  to on (1) or off (0) (integer)
2277 \end_layout
2278
2279 \begin_layout Description
2280 SPEEX_GET_ENH** Get perceptual enhancer status (integer)
2281 \end_layout
2282
2283 \begin_layout Description
2284 SPEEX_GET_FRAME_SIZE Get the number of samples per frame for the current
2285  mode (integer)
2286 \end_layout
2287
2288 \begin_layout Description
2289 SPEEX_SET_QUALITY* Set the encoder speech quality (integer 0 to 10)
2290 \end_layout
2291
2292 \begin_layout Description
2293 SPEEX_GET_QUALITY* Get the current encoder speech quality (integer 0 to
2294  10)
2295 \end_layout
2296
2297 \begin_layout Description
2298 SPEEX_SET_MODE*
2299 \begin_inset Formula $\dagger$
2300 \end_inset
2301
2302
2303 \end_layout
2304
2305 \begin_layout Description
2306 SPEEX_GET_MODE*
2307 \begin_inset Formula $\dagger$
2308 \end_inset
2309
2310
2311 \end_layout
2312
2313 \begin_layout Description
2314 SPEEX_SET_LOW_MODE*
2315 \begin_inset Formula $\dagger$
2316 \end_inset
2317
2318
2319 \end_layout
2320
2321 \begin_layout Description
2322 SPEEX_GET_LOW_MODE*
2323 \begin_inset Formula $\dagger$
2324 \end_inset
2325
2326
2327 \end_layout
2328
2329 \begin_layout Description
2330 SPEEX_SET_HIGH_MODE*
2331 \begin_inset Formula $\dagger$
2332 \end_inset
2333
2334
2335 \end_layout
2336
2337 \begin_layout Description
2338 SPEEX_GET_HIGH_MODE*
2339 \begin_inset Formula $\dagger$
2340 \end_inset
2341
2342
2343 \end_layout
2344
2345 \begin_layout Description
2346 SPEEX_SET_VBR* Set variable bit-rate (VBR) to on (1) or off (0) (integer)
2347 \end_layout
2348
2349 \begin_layout Description
2350 SPEEX_GET_VBR* Get variable bit-rate
2351 \begin_inset LatexCommand \index{variable bit-rate}
2352
2353 \end_inset
2354
2355  (VBR) status (integer)
2356 \end_layout
2357
2358 \begin_layout Description
2359 SPEEX_SET_VBR_QUALITY* Set the encoder VBR speech quality (float 0 to 10)
2360 \end_layout
2361
2362 \begin_layout Description
2363 SPEEX_GET_VBR_QUALITY* Get the current encoder VBR speech quality (float
2364  0 to 10)
2365 \end_layout
2366
2367 \begin_layout Description
2368 SPEEX_SET_COMPLEXITY* Set the CPU resources allowed for the encoder (integer
2369  1 to 10)
2370 \end_layout
2371
2372 \begin_layout Description
2373 SPEEX_GET_COMPLEXITY* Get the CPU resources allowed for the encoder (integer
2374  1 to 10)
2375 \end_layout
2376
2377 \begin_layout Description
2378 SPEEX_SET_BITRATE* Set the bit-rate to use to the closest value not exceeding
2379  the parameter (integer in bps)
2380 \end_layout
2381
2382 \begin_layout Description
2383 SPEEX_GET_BITRATE Get the current bit-rate in use (integer in bps)
2384 \end_layout
2385
2386 \begin_layout Description
2387 SPEEX_SET_SAMPLING_RATE Set real sampling rate (integer in Hz)
2388 \end_layout
2389
2390 \begin_layout Description
2391 SPEEX_GET_SAMPLING_RATE Get real sampling rate (integer in Hz)
2392 \end_layout
2393
2394 \begin_layout Description
2395 SPEEX_RESET_STATE Reset the encoder/decoder state to its original state
2396  (zeros all memories)
2397 \end_layout
2398
2399 \begin_layout Description
2400 SPEEX_SET_VAD* Set voice activity detection
2401 \begin_inset LatexCommand \index{voice activity detection}
2402
2403 \end_inset
2404
2405  (VAD) to on (1) or off (0) (integer)
2406 \end_layout
2407
2408 \begin_layout Description
2409 SPEEX_GET_VAD* Get voice activity detection (VAD) status (integer)
2410 \end_layout
2411
2412 \begin_layout Description
2413 SPEEX_SET_DTX* Set discontinuous transmission
2414 \begin_inset LatexCommand \index{discontinuous transmission}
2415
2416 \end_inset
2417
2418  (DTX) to on (1) or off (0) (integer)
2419 \end_layout
2420
2421 \begin_layout Description
2422 SPEEX_GET_DTX* Get discontinuous transmission (DTX) status (integer)
2423 \end_layout
2424
2425 \begin_layout Description
2426 SPEEX_SET_ABR* Set average bit-rate
2427 \begin_inset LatexCommand \index{average bit-rate}
2428
2429 \end_inset
2430
2431  (ABR) to a value n in bits per second (integer in bps)
2432 \end_layout
2433
2434 \begin_layout Description
2435 SPEEX_GET_ABR* Get average bit-rate (ABR) setting (integer in bps)
2436 \end_layout
2437
2438 \begin_layout Description
2439 SPEEX_SET_PLC_TUNING* Tell the encoder to optimize encoding for a certain
2440  percentage of packet loss (integer in percent)
2441 \end_layout
2442
2443 \begin_layout Description
2444 SPEEX_GET_PLC_TUNING* Get the current tuning of the encoder for PLC (integer
2445  in percent)
2446 \end_layout
2447
2448 \begin_layout Description
2449 * applies only to the encoder
2450 \end_layout
2451
2452 \begin_layout Description
2453 ** applies only to the decoder
2454 \end_layout
2455
2456 \begin_layout Description
2457 \begin_inset Formula $\dagger$
2458 \end_inset
2459
2460  normally only used internally
2461 \end_layout
2462
2463 \begin_layout Section
2464 Mode queries
2465 \begin_inset LatexCommand \label{sub:Mode-queries}
2466
2467 \end_inset
2468
2469
2470 \end_layout
2471
2472 \begin_layout Standard
2473 Speex modes have a query system similar to the speex_encoder_ctl and speex_decod
2474 er_ctl calls.
2475  Since modes are read-only, it is only possible to get information about
2476  a particular mode.
2477  The function used to do that is:
2478 \end_layout
2479
2480 \begin_layout LyX-Code
2481 void speex_mode_query(SpeexMode *mode, int request, void *ptr);
2482 \end_layout
2483
2484 \begin_layout Standard
2485 The admissible values for request are (unless otherwise note, the values
2486  are returned through 
2487 \emph on
2488 ptr
2489 \emph default
2490 ):
2491 \end_layout
2492
2493 \begin_layout Description
2494 SPEEX_MODE_FRAME_SIZE Get the frame size (in samples) for the mode
2495 \end_layout
2496
2497 \begin_layout Description
2498 SPEEX_SUBMODE_BITRATE Get the bit-rate for a submode number specified through
2499  
2500 \emph on
2501 ptr
2502 \emph default
2503  (integer in bps).
2504  
2505 \end_layout
2506
2507 \begin_layout Section
2508 Preprocessor options
2509 \begin_inset LatexCommand \label{sub:Preprocessor-options}
2510
2511 \end_inset
2512
2513
2514 \end_layout
2515
2516 \begin_layout Description
2517 SPEEX_PREPROCESS_SET_DENOISE Turns denoising on(1) or off(2) (integer)
2518 \end_layout
2519
2520 \begin_layout Description
2521 SPEEX_PREPROCESS_GET_DENOISE Get denoising status (integer)
2522 \end_layout
2523
2524 \begin_layout Description
2525 SPEEX_PREPROCESS_SET_AGC Turns automatic gain control (AGC) on(1) or off(2)
2526  (integer)
2527 \end_layout
2528
2529 \begin_layout Description
2530 SPEEX_PREPROCESS_GET_AGC Get AGC status (integer)
2531 \end_layout
2532
2533 \begin_layout Description
2534 SPEEX_PREPROCESS_SET_VAD Turns voice activity detector (VAD) on(1) or off(2)
2535  (integer)
2536 \end_layout
2537
2538 \begin_layout Description
2539 SPEEX_PREPROCESS_GET_VAD Get VAD status (integer)
2540 \end_layout
2541
2542 \begin_layout Description
2543 SPEEX_PREPROCESS_SET_AGC_LEVEL
2544 \end_layout
2545
2546 \begin_layout Description
2547 SPEEX_PREPROCESS_GET_AGC_LEVEL
2548 \end_layout
2549
2550 \begin_layout Description
2551 SPEEX_PREPROCESS_SET_DEREVERB Turns reverberation removal on(1) or off(2)
2552  (integer)
2553 \end_layout
2554
2555 \begin_layout Description
2556 SPEEX_PREPROCESS_GET_DEREVERB Get reverberation removal status (integer)
2557 \end_layout
2558
2559 \begin_layout Description
2560 SPEEX_PREPROCESS_SET_DEREVERB_LEVEL
2561 \end_layout
2562
2563 \begin_layout Description
2564 SPEEX_PREPROCESS_GET_DEREVERB_LEVEL
2565 \end_layout
2566
2567 \begin_layout Description
2568 SPEEX_PREPROCESS_SET_DEREVERB_DECAY
2569 \end_layout
2570
2571 \begin_layout Description
2572 SPEEX_PREPROCESS_GET_DEREVERB_DECAY
2573 \end_layout
2574
2575 \begin_layout Description
2576 SPEEX_PREPROCESS_SET_PROB_START
2577 \end_layout
2578
2579 \begin_layout Description
2580 SPEEX_PREPROCESS_GET_PROB_START
2581 \end_layout
2582
2583 \begin_layout Description
2584 SPEEX_PREPROCESS_SET_PROB_CONTINUE
2585 \end_layout
2586
2587 \begin_layout Description
2588 SPEEX_PREPROCESS_GET_PROB_CONTINUE
2589 \end_layout
2590
2591 \begin_layout Description
2592 SPEEX_PREPROCESS_SET_NOISE_SUPPRESS Set maximum attenuation of the noise
2593  in dB (negative number)
2594 \end_layout
2595
2596 \begin_layout Description
2597 SPEEX_PREPROCESS_GET_NOISE_SUPPRESS Get maximum attenuation of the noise
2598  in dB (negative number)
2599 \end_layout
2600
2601 \begin_layout Description
2602 SPEEX_PREPROCESS_SET_ECHO_SUPPRESS Set maximum attenuation of the residual
2603  echo in dB (negative number)
2604 \end_layout
2605
2606 \begin_layout Description
2607 SPEEX_PREPROCESS_GET_ECHO_SUPPRESS Set maximum attenuation of the residual
2608  echo in dB (negative number)
2609 \end_layout
2610
2611 \begin_layout Description
2612 SPEEX_PREPROCESS_SET_ECHO_SUPPRESS_ACTIVE Set maximum attenuation of the
2613  echo in dB when near end is active (negative number)
2614 \end_layout
2615
2616 \begin_layout Description
2617 SPEEX_PREPROCESS_GET_ECHO_SUPPRESS_ACTIVE Set maximum attenuation of the
2618  echo in dB when near end is active (negative number)
2619 \end_layout
2620
2621 \begin_layout Description
2622 SPEEX_PREPROCESS_SET_ECHO_STATE Set the associated echo canceller for residual
2623  echo suppression (NULL for no residual echo suppression)
2624 \end_layout
2625
2626 \begin_layout Description
2627 SPEEX_PREPROCESS_GET_ECHO_STATE Get the associated echo canceller
2628 \end_layout
2629
2630 \begin_layout Section
2631 Packing and in-band signalling
2632 \begin_inset LatexCommand \index{in-band signalling}
2633
2634 \end_inset
2635
2636
2637 \end_layout
2638
2639 \begin_layout Standard
2640 Sometimes it is desirable to pack more than one frame per packet (or other
2641  basic unit of storage).
2642  The proper way to do it is to call speex_encode 
2643 \begin_inset Formula $N$
2644 \end_inset
2645
2646  times before writing the stream with speex_bits_write.
2647  In cases where the number of frames is not determined by an out-of-band
2648  mechanism, it is possible to include a terminator code.
2649  That terminator consists of the code 15 (decimal) encoded with 5 bits,
2650  as shown in Table 
2651 \begin_inset LatexCommand \ref{cap:quality_vs_bps}
2652
2653 \end_inset
2654
2655 .
2656  Note that as of version 1.0.2, calling speex_bits_write automatically inserts
2657  the terminator so as to fill the last byte.
2658  This doesn't involves any overhead and makes sure Speex can always detect
2659  when there is no more frame in a packet.
2660 \end_layout
2661
2662 \begin_layout Standard
2663 It is also possible to send in-band 
2664 \begin_inset Quotes eld
2665 \end_inset
2666
2667 messages
2668 \begin_inset Quotes erd
2669 \end_inset
2670
2671  to the other side.
2672  All these messages are encoded as 
2673 \begin_inset Quotes eld
2674 \end_inset
2675
2676 pseudo-frames
2677 \begin_inset Quotes erd
2678 \end_inset
2679
2680  of mode 14 which contain a 4-bit message type code, followed by the message.
2681  Table 
2682 \begin_inset LatexCommand \ref{cap:In-band-signalling-codes}
2683
2684 \end_inset
2685
2686  lists the available codes, their meaning and the size of the message that
2687  follows.
2688  Most of these messages are requests that are sent to the encoder or decoder
2689  on the other end, which is free to comply or ignore them.
2690  By default, all in-band messages are ignored.
2691 \end_layout
2692
2693 \begin_layout Standard
2694 \begin_inset Float table
2695 placement htbp
2696 wide false
2697 sideways false
2698 status open
2699
2700 \begin_layout Standard
2701 \begin_inset ERT
2702 status collapsed
2703
2704 \begin_layout Standard
2705
2706
2707 \backslash
2708 begin{center}
2709 \end_layout
2710
2711 \end_inset
2712
2713
2714 \begin_inset Tabular
2715 <lyxtabular version="3" rows="17" columns="3">
2716 <features>
2717 <column alignment="center" valignment="top" leftline="true" width="0pt">
2718 <column alignment="center" valignment="top" leftline="true" width="0pt">
2719 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
2720 <row topline="true" bottomline="true">
2721 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2722 \begin_inset Text
2723
2724 \begin_layout Standard
2725 Code
2726 \end_layout
2727
2728 \end_inset
2729 </cell>
2730 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2731 \begin_inset Text
2732
2733 \begin_layout Standard
2734 Size (bits)
2735 \end_layout
2736
2737 \end_inset
2738 </cell>
2739 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2740 \begin_inset Text
2741
2742 \begin_layout Standard
2743 Content
2744 \end_layout
2745
2746 \end_inset
2747 </cell>
2748 </row>
2749 <row topline="true">
2750 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2751 \begin_inset Text
2752
2753 \begin_layout Standard
2754 0
2755 \end_layout
2756
2757 \end_inset
2758 </cell>
2759 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2760 \begin_inset Text
2761
2762 \begin_layout Standard
2763 1
2764 \end_layout
2765
2766 \end_inset
2767 </cell>
2768 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2769 \begin_inset Text
2770
2771 \begin_layout Standard
2772 Asks decoder to set perceptual enhancement off (0) or on(1)
2773 \end_layout
2774
2775 \end_inset
2776 </cell>
2777 </row>
2778 <row topline="true">
2779 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2780 \begin_inset Text
2781
2782 \begin_layout Standard
2783 1
2784 \end_layout
2785
2786 \end_inset
2787 </cell>
2788 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2789 \begin_inset Text
2790
2791 \begin_layout Standard
2792 1
2793 \end_layout
2794
2795 \end_inset
2796 </cell>
2797 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2798 \begin_inset Text
2799
2800 \begin_layout Standard
2801 Asks (if 1) the encoder to be less 
2802 \begin_inset Quotes eld
2803 \end_inset
2804
2805 agressive
2806 \begin_inset Quotes erd
2807 \end_inset
2808
2809  due to high packet loss
2810 \end_layout
2811
2812 \end_inset
2813 </cell>
2814 </row>
2815 <row topline="true">
2816 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2817 \begin_inset Text
2818
2819 \begin_layout Standard
2820 2
2821 \end_layout
2822
2823 \end_inset
2824 </cell>
2825 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2826 \begin_inset Text
2827
2828 \begin_layout Standard
2829 4
2830 \end_layout
2831
2832 \end_inset
2833 </cell>
2834 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2835 \begin_inset Text
2836
2837 \begin_layout Standard
2838 Asks encoder to switch to mode N
2839 \end_layout
2840
2841 \end_inset
2842 </cell>
2843 </row>
2844 <row topline="true">
2845 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2846 \begin_inset Text
2847
2848 \begin_layout Standard
2849 3
2850 \end_layout
2851
2852 \end_inset
2853 </cell>
2854 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2855 \begin_inset Text
2856
2857 \begin_layout Standard
2858 4
2859 \end_layout
2860
2861 \end_inset
2862 </cell>
2863 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2864 \begin_inset Text
2865
2866 \begin_layout Standard
2867 Asks encoder to switch to mode N for low-band
2868 \end_layout
2869
2870 \end_inset
2871 </cell>
2872 </row>
2873 <row topline="true">
2874 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2875 \begin_inset Text
2876
2877 \begin_layout Standard
2878 4
2879 \end_layout
2880
2881 \end_inset
2882 </cell>
2883 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2884 \begin_inset Text
2885
2886 \begin_layout Standard
2887 4
2888 \end_layout
2889
2890 \end_inset
2891 </cell>
2892 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2893 \begin_inset Text
2894
2895 \begin_layout Standard
2896 Asks encoder to switch to mode N for high-band
2897 \end_layout
2898
2899 \end_inset
2900 </cell>
2901 </row>
2902 <row topline="true">
2903 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2904 \begin_inset Text
2905
2906 \begin_layout Standard
2907 5
2908 \end_layout
2909
2910 \end_inset
2911 </cell>
2912 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2913 \begin_inset Text
2914
2915 \begin_layout Standard
2916 4
2917 \end_layout
2918
2919 \end_inset
2920 </cell>
2921 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2922 \begin_inset Text
2923
2924 \begin_layout Standard
2925 Asks encoder to switch to quality N for VBR
2926 \end_layout
2927
2928 \end_inset
2929 </cell>
2930 </row>
2931 <row topline="true">
2932 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2933 \begin_inset Text
2934
2935 \begin_layout Standard
2936 6
2937 \end_layout
2938
2939 \end_inset
2940 </cell>
2941 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2942 \begin_inset Text
2943
2944 \begin_layout Standard
2945 4
2946 \end_layout
2947
2948 \end_inset
2949 </cell>
2950 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2951 \begin_inset Text
2952
2953 \begin_layout Standard
2954 Request acknowloedge (0=no, 1=all, 2=only for in-band data)
2955 \end_layout
2956
2957 \end_inset
2958 </cell>
2959 </row>
2960 <row topline="true">
2961 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2962 \begin_inset Text
2963
2964 \begin_layout Standard
2965 7
2966 \end_layout
2967
2968 \end_inset
2969 </cell>
2970 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2971 \begin_inset Text
2972
2973 \begin_layout Standard
2974 4
2975 \end_layout
2976
2977 \end_inset
2978 </cell>
2979 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2980 \begin_inset Text
2981
2982 \begin_layout Standard
2983 Asks encoder to set CBR (0), VAD(1), DTX(3), VBR(5), VBR+DTX(7)
2984 \end_layout
2985
2986 \end_inset
2987 </cell>
2988 </row>
2989 <row topline="true">
2990 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2991 \begin_inset Text
2992
2993 \begin_layout Standard
2994 8
2995 \end_layout
2996
2997 \end_inset
2998 </cell>
2999 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3000 \begin_inset Text
3001
3002 \begin_layout Standard
3003 8
3004 \end_layout
3005
3006 \end_inset
3007 </cell>
3008 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3009 \begin_inset Text
3010
3011 \begin_layout Standard
3012 Transmit (8-bit) character to the other end
3013 \end_layout
3014
3015 \end_inset
3016 </cell>
3017 </row>
3018 <row topline="true">
3019 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3020 \begin_inset Text
3021
3022 \begin_layout Standard
3023 9
3024 \end_layout
3025
3026 \end_inset
3027 </cell>
3028 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3029 \begin_inset Text
3030
3031 \begin_layout Standard
3032 8
3033 \end_layout
3034
3035 \end_inset
3036 </cell>
3037 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3038 \begin_inset Text
3039
3040 \begin_layout Standard
3041 Intensity stereo information
3042 \end_layout
3043
3044 \end_inset
3045 </cell>
3046 </row>
3047 <row topline="true">
3048 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3049 \begin_inset Text
3050
3051 \begin_layout Standard
3052 10
3053 \end_layout
3054
3055 \end_inset
3056 </cell>
3057 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3058 \begin_inset Text
3059
3060 \begin_layout Standard
3061 16
3062 \end_layout
3063
3064 \end_inset
3065 </cell>
3066 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3067 \begin_inset Text
3068
3069 \begin_layout Standard
3070 Announce maximum bit-rate acceptable (N in bytes/second)
3071 \end_layout
3072
3073 \end_inset
3074 </cell>
3075 </row>
3076 <row topline="true">
3077 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3078 \begin_inset Text
3079
3080 \begin_layout Standard
3081 11
3082 \end_layout
3083
3084 \end_inset
3085 </cell>
3086 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3087 \begin_inset Text
3088
3089 \begin_layout Standard
3090 16
3091 \end_layout
3092
3093 \end_inset
3094 </cell>
3095 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3096 \begin_inset Text
3097
3098 \begin_layout Standard
3099 reserved
3100 \end_layout
3101
3102 \end_inset
3103 </cell>
3104 </row>
3105 <row topline="true">
3106 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3107 \begin_inset Text
3108
3109 \begin_layout Standard
3110 12
3111 \end_layout
3112
3113 \end_inset
3114 </cell>
3115 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3116 \begin_inset Text
3117
3118 \begin_layout Standard
3119 32
3120 \end_layout
3121
3122 \end_inset
3123 </cell>
3124 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3125 \begin_inset Text
3126
3127 \begin_layout Standard
3128 Acknowledge receiving packet N
3129 \end_layout
3130
3131 \end_inset
3132 </cell>
3133 </row>
3134 <row topline="true">
3135 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3136 \begin_inset Text
3137
3138 \begin_layout Standard
3139 13
3140 \end_layout
3141
3142 \end_inset
3143 </cell>
3144 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3145 \begin_inset Text
3146
3147 \begin_layout Standard
3148 32
3149 \end_layout
3150
3151 \end_inset
3152 </cell>
3153 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3154 \begin_inset Text
3155
3156 \begin_layout Standard
3157 reserved
3158 \end_layout
3159
3160 \end_inset
3161 </cell>
3162 </row>
3163 <row topline="true">
3164 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3165 \begin_inset Text
3166
3167 \begin_layout Standard
3168 14
3169 \end_layout
3170
3171 \end_inset
3172 </cell>
3173 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3174 \begin_inset Text
3175
3176 \begin_layout Standard
3177 64
3178 \end_layout
3179
3180 \end_inset
3181 </cell>
3182 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3183 \begin_inset Text
3184
3185 \begin_layout Standard
3186 reserved
3187 \end_layout
3188
3189 \end_inset
3190 </cell>
3191 </row>
3192 <row topline="true" bottomline="true">
3193 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3194 \begin_inset Text
3195
3196 \begin_layout Standard
3197 15
3198 \end_layout
3199
3200 \end_inset
3201 </cell>
3202 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3203 \begin_inset Text
3204
3205 \begin_layout Standard
3206 64
3207 \end_layout
3208
3209 \end_inset
3210 </cell>
3211 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3212 \begin_inset Text
3213
3214 \begin_layout Standard
3215 reserved
3216 \end_layout
3217
3218 \end_inset
3219 </cell>
3220 </row>
3221 </lyxtabular>
3222
3223 \end_inset
3224
3225
3226 \begin_inset ERT
3227 status collapsed
3228
3229 \begin_layout Standard
3230
3231
3232 \backslash
3233 end{center}
3234 \end_layout
3235
3236 \end_inset
3237
3238
3239 \end_layout
3240
3241 \begin_layout Caption
3242 In-band signalling codes
3243 \begin_inset LatexCommand \label{cap:In-band-signalling-codes}
3244
3245 \end_inset
3246
3247
3248 \end_layout
3249
3250 \end_inset
3251
3252
3253 \end_layout
3254
3255 \begin_layout Standard
3256 Finally, applications may define custom in-band messages using mode 13.
3257  The size of the message in bytes is encoded with 5 bits, so that the decoder
3258  can skip it if it doesn't know how to interpret it.
3259 \end_layout
3260
3261 \begin_layout Standard
3262
3263 \newpage
3264
3265 \end_layout
3266
3267 \begin_layout Chapter
3268 Formats and standards
3269 \begin_inset LatexCommand \index{standards}
3270
3271 \end_inset
3272
3273
3274 \begin_inset LatexCommand \label{sec:Formats-and-standards}
3275
3276 \end_inset
3277
3278
3279 \end_layout
3280
3281 \begin_layout Standard
3282 Speex can encode speech in both narrowband and wideband and provides different
3283  bit-rates.
3284  However, not all features need to be supported by a certain implementation
3285  or device.
3286  In order to be called 
3287 \begin_inset Quotes eld
3288 \end_inset
3289
3290 Speex compatible
3291 \begin_inset Quotes erd
3292 \end_inset
3293
3294  (whatever that means), an implementation must implement at least a basic
3295  set of features.
3296 \end_layout
3297
3298 \begin_layout Standard
3299 At the minimum, all narrowband modes of operation MUST be supported at the
3300  decoder.
3301  This includes the decoding of a wideband bit-stream by the narrowband decoder
3302 \begin_inset Foot
3303 status collapsed
3304
3305 \begin_layout Standard
3306 The wideband bit-stream contains an embedded narrowband bit-stream which
3307  can be decoded alone
3308 \end_layout
3309
3310 \end_inset
3311
3312 .
3313  If present, a wideband decoder MUST be able to decode a narrowband stream,
3314  and MAY either be able to decode all wideband modes or be able to decode
3315  the embedded narrowband part of all modes (which includes ignoring the
3316  high-band bits).
3317 \end_layout
3318
3319 \begin_layout Standard
3320 For encoders, at least one narrowband or wideband mode MUST be supported.
3321  The main reason why all encoding modes do not have to be supported is that
3322  some platforms may not be able to handle the complexity of encoding in
3323  some modes.
3324 \end_layout
3325
3326 \begin_layout Section
3327 RTP
3328 \begin_inset LatexCommand \index{RTP}
3329
3330 \end_inset
3331
3332  Payload Format 
3333 \end_layout
3334
3335 \begin_layout Standard
3336 The RTP payload draft is included in appendix 
3337 \begin_inset LatexCommand \ref{sec:IETF-draft}
3338
3339 \end_inset
3340
3341  and the latest version is available at 
3342 \begin_inset LatexCommand \url{http://www.speex.org/drafts/latest}
3343
3344 \end_inset
3345
3346 .
3347  This draft has been sent (2003/02/26) to the Internet Engineering Task
3348  Force (IETF) and will be discussed at the March 18th meeting in San Francisco.
3349  
3350 \end_layout
3351
3352 \begin_layout Section
3353 MIME Type
3354 \end_layout
3355
3356 \begin_layout Standard
3357 For now, you should use the MIME type audio/x-speex for Speex-in-Ogg.
3358  We will apply for type 
3359 \family typewriter
3360 audio/speex
3361 \family default
3362  in the near future.
3363 \end_layout
3364
3365 \begin_layout Section
3366 Ogg
3367 \begin_inset LatexCommand \index{Ogg}
3368
3369 \end_inset
3370
3371  file format
3372 \end_layout
3373
3374 \begin_layout Standard
3375 Speex bit-streams can be stored in Ogg files.
3376  In this case, the first packet of the Ogg file contains the Speex header
3377  described in table 
3378 \begin_inset LatexCommand \ref{cap:ogg_speex_header}
3379
3380 \end_inset
3381
3382 .
3383  All integer fields in the headers are stored as little-endian.
3384  The 
3385 \family typewriter
3386 speex_string
3387 \family default
3388  field must contain the 
3389 \begin_inset Quotes eld
3390 \end_inset
3391
3392
3393 \family typewriter
3394 Speex
3395 \family default
3396 \InsetSpace ~
3397 \InsetSpace ~
3398 \InsetSpace ~
3399
3400 \begin_inset Quotes erd
3401 \end_inset
3402
3403  (with 3 trailing spaces), which identifies the bit-stream.
3404  The next field, 
3405 \family typewriter
3406 speex_version
3407 \family default
3408  contains the version of Speex that encoded the file.
3409  For now, refer to speex_header.[ch] for more info.
3410  The 
3411 \emph on
3412 beginning of stream
3413 \emph default
3414  (
3415 \family typewriter
3416 b_o_s
3417 \family default
3418 ) flag is set to 1 for the header.
3419  The header packet has 
3420 \family typewriter
3421 packetno=0
3422 \family default
3423  and 
3424 \family typewriter
3425 granulepos=0
3426 \family default
3427 .
3428 \end_layout
3429
3430 \begin_layout Standard
3431 The second packet contains the Speex comment header.
3432  The format used is the Vorbis comment format described here: http://www.xiph.org/
3433 ogg/vorbis/doc/v-comment.html .
3434  This packet has 
3435 \family typewriter
3436 packetno=1
3437 \family default
3438  and 
3439 \family typewriter
3440 granulepos=0
3441 \family default
3442 .
3443 \end_layout
3444
3445 \begin_layout Standard
3446 The third and subsequent packets each contain one or more (number found
3447  in header) Speex frames.
3448  These are identified with 
3449 \family typewriter
3450 packetno
3451 \family default
3452  starting from 2 and the 
3453 \family typewriter
3454 granulepos
3455 \family default
3456  is the number of the last sample encoded in that packet.
3457  The last of these packets has the 
3458 \emph on
3459 end of stream
3460 \emph default
3461  (
3462 \family typewriter
3463 e_o_s
3464 \family default
3465 ) flag is set to 1.
3466 \end_layout
3467
3468 \begin_layout Standard
3469 \begin_inset Float table
3470 placement htbp
3471 wide true
3472 sideways false
3473 status open
3474
3475 \begin_layout Standard
3476 \begin_inset ERT
3477 status collapsed
3478
3479 \begin_layout Standard
3480
3481
3482 \backslash
3483 begin{center}
3484 \end_layout
3485
3486 \end_inset
3487
3488
3489 \begin_inset Tabular
3490 <lyxtabular version="3" rows="16" columns="3">
3491 <features>
3492 <column alignment="center" valignment="top" leftline="true" width="0pt">
3493 <column alignment="center" valignment="top" leftline="true" width="0pt">
3494 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
3495 <row topline="true" bottomline="true">
3496 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3497 \begin_inset Text
3498
3499 \begin_layout Standard
3500 Field
3501 \end_layout
3502
3503 \end_inset
3504 </cell>
3505 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3506 \begin_inset Text
3507
3508 \begin_layout Standard
3509 Type
3510 \end_layout
3511
3512 \end_inset
3513 </cell>
3514 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3515 \begin_inset Text
3516
3517 \begin_layout Standard
3518 Size
3519 \end_layout
3520
3521 \end_inset
3522 </cell>
3523 </row>
3524 <row topline="true">
3525 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3526 \begin_inset Text
3527
3528 \begin_layout Standard
3529 speex_string
3530 \end_layout
3531
3532 \end_inset
3533 </cell>
3534 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3535 \begin_inset Text
3536
3537 \begin_layout Standard
3538 char[]
3539 \end_layout
3540
3541 \end_inset
3542 </cell>
3543 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3544 \begin_inset Text
3545
3546 \begin_layout Standard
3547 8
3548 \end_layout
3549
3550 \end_inset
3551 </cell>
3552 </row>
3553 <row topline="true">
3554 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3555 \begin_inset Text
3556
3557 \begin_layout Standard
3558 speex_version
3559 \end_layout
3560
3561 \end_inset
3562 </cell>
3563 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3564 \begin_inset Text
3565
3566 \begin_layout Standard
3567 char[]
3568 \end_layout
3569
3570 \end_inset
3571 </cell>
3572 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3573 \begin_inset Text
3574
3575 \begin_layout Standard
3576 20
3577 \end_layout
3578
3579 \end_inset
3580 </cell>
3581 </row>
3582 <row topline="true">
3583 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3584 \begin_inset Text
3585
3586 \begin_layout Standard
3587 speex_version_id
3588 \end_layout
3589
3590 \end_inset
3591 </cell>
3592 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3593 \begin_inset Text
3594
3595 \begin_layout Standard
3596 int
3597 \end_layout
3598
3599 \end_inset
3600 </cell>
3601 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3602 \begin_inset Text
3603
3604 \begin_layout Standard
3605 4
3606 \end_layout
3607
3608 \end_inset
3609 </cell>
3610 </row>
3611 <row topline="true">
3612 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3613 \begin_inset Text
3614
3615 \begin_layout Standard
3616 header_size
3617 \end_layout
3618
3619 \end_inset
3620 </cell>
3621 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3622 \begin_inset Text
3623
3624 \begin_layout Standard
3625 int
3626 \end_layout
3627
3628 \end_inset
3629 </cell>
3630 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3631 \begin_inset Text
3632
3633 \begin_layout Standard
3634 4
3635 \end_layout
3636
3637 \end_inset
3638 </cell>
3639 </row>
3640 <row topline="true">
3641 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3642 \begin_inset Text
3643
3644 \begin_layout Standard
3645 rate
3646 \end_layout
3647
3648 \end_inset
3649 </cell>
3650 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3651 \begin_inset Text
3652
3653 \begin_layout Standard
3654 int
3655 \end_layout
3656
3657 \end_inset
3658 </cell>
3659 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3660 \begin_inset Text
3661
3662 \begin_layout Standard
3663 4
3664 \end_layout
3665
3666 \end_inset
3667 </cell>
3668 </row>
3669 <row topline="true">
3670 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3671 \begin_inset Text
3672
3673 \begin_layout Standard
3674 mode
3675 \end_layout
3676
3677 \end_inset
3678 </cell>
3679 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3680 \begin_inset Text
3681
3682 \begin_layout Standard
3683 int
3684 \end_layout
3685
3686 \end_inset
3687 </cell>
3688 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3689 \begin_inset Text
3690
3691 \begin_layout Standard
3692 4
3693 \end_layout
3694
3695 \end_inset
3696 </cell>
3697 </row>
3698 <row topline="true">
3699 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3700 \begin_inset Text
3701
3702 \begin_layout Standard
3703 mode_bitstream_version
3704 \end_layout
3705
3706 \end_inset
3707 </cell>
3708 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3709 \begin_inset Text
3710
3711 \begin_layout Standard
3712 int
3713 \end_layout
3714
3715 \end_inset
3716 </cell>
3717 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3718 \begin_inset Text
3719
3720 \begin_layout Standard
3721 4
3722 \end_layout
3723
3724 \end_inset
3725 </cell>
3726 </row>
3727 <row topline="true">
3728 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3729 \begin_inset Text
3730
3731 \begin_layout Standard
3732 nb_channels
3733 \end_layout
3734
3735 \end_inset
3736 </cell>
3737 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3738 \begin_inset Text
3739
3740 \begin_layout Standard
3741 int
3742 \end_layout
3743
3744 \end_inset
3745 </cell>
3746 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3747 \begin_inset Text
3748
3749 \begin_layout Standard
3750 4
3751 \end_layout
3752
3753 \end_inset
3754 </cell>
3755 </row>
3756 <row topline="true">
3757 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3758 \begin_inset Text
3759
3760 \begin_layout Standard
3761 bitrate
3762 \end_layout
3763
3764 \end_inset
3765 </cell>
3766 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3767 \begin_inset Text
3768
3769 \begin_layout Standard
3770 int
3771 \end_layout
3772
3773 \end_inset
3774 </cell>
3775 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3776 \begin_inset Text
3777
3778 \begin_layout Standard
3779 4
3780 \end_layout
3781
3782 \end_inset
3783 </cell>
3784 </row>
3785 <row topline="true">
3786 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3787 \begin_inset Text
3788
3789 \begin_layout Standard
3790 frame_size
3791 \end_layout
3792
3793 \end_inset
3794 </cell>
3795 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3796 \begin_inset Text
3797
3798 \begin_layout Standard
3799 int
3800 \end_layout
3801
3802 \end_inset
3803 </cell>
3804 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3805 \begin_inset Text
3806
3807 \begin_layout Standard
3808 4
3809 \end_layout
3810
3811 \end_inset
3812 </cell>
3813 </row>
3814 <row topline="true">
3815 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3816 \begin_inset Text
3817
3818 \begin_layout Standard
3819 vbr
3820 \end_layout
3821
3822 \end_inset
3823 </cell>
3824 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3825 \begin_inset Text
3826
3827 \begin_layout Standard
3828 int
3829 \end_layout
3830
3831 \end_inset
3832 </cell>
3833 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3834 \begin_inset Text
3835
3836 \begin_layout Standard
3837 4
3838 \end_layout
3839
3840 \end_inset
3841 </cell>
3842 </row>
3843 <row topline="true">
3844 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3845 \begin_inset Text
3846
3847 \begin_layout Standard
3848 frames_per_packet
3849 \end_layout
3850
3851 \end_inset
3852 </cell>
3853 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3854 \begin_inset Text
3855
3856 \begin_layout Standard
3857 int
3858 \end_layout
3859
3860 \end_inset
3861 </cell>
3862 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3863 \begin_inset Text
3864
3865 \begin_layout Standard
3866 4
3867 \end_layout
3868
3869 \end_inset
3870 </cell>
3871 </row>
3872 <row topline="true">
3873 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3874 \begin_inset Text
3875
3876 \begin_layout Standard
3877 extra_headers
3878 \end_layout
3879
3880 \end_inset
3881 </cell>
3882 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3883 \begin_inset Text
3884
3885 \begin_layout Standard
3886 int
3887 \end_layout
3888
3889 \end_inset
3890 </cell>
3891 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3892 \begin_inset Text
3893
3894 \begin_layout Standard
3895 4
3896 \end_layout
3897
3898 \end_inset
3899 </cell>
3900 </row>
3901 <row topline="true">
3902 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3903 \begin_inset Text
3904
3905 \begin_layout Standard
3906 reserved1
3907 \end_layout
3908
3909 \end_inset
3910 </cell>
3911 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3912 \begin_inset Text
3913
3914 \begin_layout Standard
3915 int
3916 \end_layout
3917
3918 \end_inset
3919 </cell>
3920 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3921 \begin_inset Text
3922
3923 \begin_layout Standard
3924 4
3925 \end_layout
3926
3927 \end_inset
3928 </cell>
3929 </row>
3930 <row topline="true" bottomline="true">
3931 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3932 \begin_inset Text
3933
3934 \begin_layout Standard
3935 reserved2
3936 \end_layout
3937
3938 \end_inset
3939 </cell>
3940 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3941 \begin_inset Text
3942
3943 \begin_layout Standard
3944 int
3945 \end_layout
3946
3947 \end_inset
3948 </cell>
3949 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3950 \begin_inset Text
3951
3952 \begin_layout Standard
3953 4
3954 \end_layout
3955
3956 \end_inset
3957 </cell>
3958 </row>
3959 </lyxtabular>
3960
3961 \end_inset
3962
3963
3964 \begin_inset ERT
3965 status collapsed
3966
3967 \begin_layout Standard
3968
3969
3970 \backslash
3971 end{center}
3972 \end_layout
3973
3974 \end_inset
3975
3976
3977 \end_layout
3978
3979 \begin_layout Caption
3980 Ogg/Speex header packet
3981 \begin_inset LatexCommand \label{cap:ogg_speex_header}
3982
3983 \end_inset
3984
3985
3986 \end_layout
3987
3988 \end_inset
3989
3990
3991 \end_layout
3992
3993 \begin_layout Standard
3994 \begin_inset ERT
3995 status collapsed
3996
3997 \begin_layout Standard
3998
3999
4000 \backslash
4001 clearpage
4002 \end_layout
4003
4004 \end_inset
4005
4006
4007 \end_layout
4008
4009 \begin_layout Chapter
4010 Introduction to CELP Coding
4011 \begin_inset LatexCommand \index{CELP}
4012
4013 \end_inset
4014
4015
4016 \begin_inset LatexCommand \label{sec:Introduction-to-CELP}
4017
4018 \end_inset
4019
4020
4021 \end_layout
4022
4023 \begin_layout Quote
4024 \align center
4025
4026 \emph on
4027 Do not meddle in the affairs of poles, for they are subtle and quick to
4028  leave the unit circle.
4029 \end_layout
4030
4031 \begin_layout Standard
4032 Speex is based on CELP, which stands for Code Excited Linear Prediction.
4033  This section attempts to introduce the principles behind CELP, so if you
4034  are already familiar with CELP, you can safely skip to section 
4035 \begin_inset LatexCommand \ref{sec:Speex-narrowband-mode}
4036
4037 \end_inset
4038
4039 .
4040  The CELP technique is based on three ideas:
4041 \end_layout
4042
4043 \begin_layout Enumerate
4044 The use of a linear prediction (LP) model to model the vocal tract
4045 \end_layout
4046
4047 \begin_layout Enumerate
4048 The use of (adaptive and fixed) codebook entries as input (excitation) of
4049  the LP model
4050 \end_layout
4051
4052 \begin_layout Enumerate
4053 The search performed in closed-loop in a 
4054 \begin_inset Quotes eld
4055 \end_inset
4056
4057 perceptually weighted domain
4058 \begin_inset Quotes erd
4059 \end_inset
4060
4061
4062 \end_layout
4063
4064 \begin_layout Standard
4065 This section describes the basic ideas behind CELP.
4066  This is still a work in progress.
4067 \end_layout
4068
4069 \begin_layout Section
4070 Source-Filter Model of Speech Prediction
4071 \end_layout
4072
4073 \begin_layout Standard
4074 The source-filter model of speech production assumes that the vocal cords
4075  are the source of spectrally flat sound (the excitation signal), and that
4076  the vocal tract acts as a filter to spectrally shape the various sounds
4077  of speech.
4078  While still an approximation, the model is widely used in speech coding
4079  because of its simplicity.Its use is also the reason why most speech codecs
4080  (Speex included) perform badly on music signals.
4081  The different phonemes can be distinguished by their excitation (source)
4082  and spectral shape (filter).
4083  Voiced sounds (e.g.
4084  vowels) have an excitation signal that is periodic and that can be approximated
4085  by an impulse train in the time domain or by regularly-spaced harmonics
4086  in the frequency domain.
4087  On the other hand, fricatives (such as the "s", "sh" and "f" sounds) have
4088  an excitation signal that is similar to white Gaussian noise.
4089  So called voice fricatives (such as "z" and "v") have excitation signal
4090  composed of an harmonic part and a noisy part.
4091 \end_layout
4092
4093 \begin_layout Standard
4094 The source-filter model is usually tied with the use of Linear prediction.
4095  The CELP model is based on source-filter model, as can be seen from the
4096  CELP decoder illustrated in Figure 
4097 \begin_inset LatexCommand \ref{fig:The-CELP-model}
4098
4099 \end_inset
4100
4101 .
4102  
4103 \end_layout
4104
4105 \begin_layout Standard
4106 \begin_inset Float figure
4107 wide false
4108 sideways false
4109 status open
4110
4111 \begin_layout Standard
4112 \begin_inset ERT
4113 status collapsed
4114
4115 \begin_layout Standard
4116
4117
4118 \backslash
4119 begin{center}
4120 \end_layout
4121
4122 \end_inset
4123
4124
4125 \begin_inset Graphics
4126         filename celp_decoder.eps
4127         width 45page%
4128         keepAspectRatio
4129
4130 \end_inset
4131
4132
4133 \begin_inset ERT
4134 status collapsed
4135
4136 \begin_layout Standard
4137
4138
4139 \backslash
4140 end{center}
4141 \end_layout
4142
4143 \end_inset
4144
4145
4146 \end_layout
4147
4148 \begin_layout Caption
4149 The CELP model of speech synthesis (decoder)
4150 \begin_inset LatexCommand \label{fig:The-CELP-model}
4151
4152 \end_inset
4153
4154  
4155 \end_layout
4156
4157 \end_inset
4158
4159
4160 \end_layout
4161
4162 \begin_layout Section
4163 Linear Prediction (LPC)
4164 \begin_inset LatexCommand \index{linear prediction}
4165
4166 \end_inset
4167
4168
4169 \end_layout
4170
4171 \begin_layout Standard
4172 Linear prediction is at the base of many speech coding techniques, including
4173  CELP.
4174  The idea behind it is to predict the signal 
4175 \begin_inset Formula $x[n]$
4176 \end_inset
4177
4178  using a linear combination of its past samples:
4179 \end_layout
4180
4181 \begin_layout Standard
4182 \begin_inset Formula \[
4183 y[n]=\sum_{i=1}^{N}a_{i}x[n-i]\]
4184
4185 \end_inset
4186
4187 where 
4188 \begin_inset Formula $y[n]$
4189 \end_inset
4190
4191  is the linear prediction of 
4192 \begin_inset Formula $x[n]$
4193 \end_inset
4194
4195 .
4196  The prediction error is thus given by:
4197 \begin_inset Formula \[
4198 e[n]=x[n]-y[n]=x[n]-\sum_{i=1}^{N}a_{i}x[n-i]\]
4199
4200 \end_inset
4201
4202
4203 \end_layout
4204
4205 \begin_layout Standard
4206 The goal of the LPC analysis is to find the best prediction coefficients
4207  
4208 \begin_inset Formula $a_{i}$
4209 \end_inset
4210
4211  which minimize the quadratic error function:
4212 \begin_inset Formula \[
4213 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}\]
4214
4215 \end_inset
4216
4217 That can be done by making all derivatives 
4218 \begin_inset Formula $\frac{\partial E}{\partial a_{i}}$
4219 \end_inset
4220
4221  equal to zero:
4222 \begin_inset Formula \[
4223 \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\]
4224
4225 \end_inset
4226
4227
4228 \end_layout
4229
4230 \begin_layout Standard
4231 For an order 
4232 \begin_inset Formula $N$
4233 \end_inset
4234
4235  filter, the filter coefficients 
4236 \begin_inset Formula $a_{i}$
4237 \end_inset
4238
4239  are found by solving the system 
4240 \begin_inset Formula $N\times N$
4241 \end_inset
4242
4243  linear system 
4244 \begin_inset Formula $\mathbf{Ra}=\mathbf{r}$
4245 \end_inset
4246
4247 , where
4248 \begin_inset Formula \[
4249 \mathbf{R}=\left[\begin{array}{cccc}
4250 R(0) & R(1) & \cdots & R(N-1)\\
4251 R(1) & R(0) & \cdots & R(N-2)\\
4252 \vdots & \vdots & \ddots & \vdots\\
4253 R(N-1) & R(N-2) & \cdots & R(0)\end{array}\right]\]
4254
4255 \end_inset
4256
4257
4258 \begin_inset Formula \[
4259 \mathbf{r}=\left[\begin{array}{c}
4260 R(1)\\
4261 R(2)\\
4262 \vdots\\
4263 R(N)\end{array}\right]\]
4264
4265 \end_inset
4266
4267 with 
4268 \begin_inset Formula $R(m)$
4269 \end_inset
4270
4271 , the auto-correlation
4272 \begin_inset LatexCommand \index{auto-correlation}
4273
4274 \end_inset
4275
4276  of the signal 
4277 \begin_inset Formula $x[n]$
4278 \end_inset
4279
4280 , computed as:
4281 \end_layout
4282
4283 \begin_layout Standard
4284 \begin_inset Formula \[
4285 R(m)=\sum_{i=0}^{N-1}x[i]x[i-m]\]
4286
4287 \end_inset
4288
4289
4290 \end_layout
4291
4292 \begin_layout Standard
4293 Because 
4294 \begin_inset Formula $\mathbf{R}$
4295 \end_inset
4296
4297  is toeplitz hermitian, the Levinson-Durbin
4298 \begin_inset LatexCommand \index{Levinson-Durbin}
4299
4300 \end_inset
4301
4302  algorithm can be used, making the solution to the problem 
4303 \begin_inset Formula $\mathcal{O}\left(N^{2}\right)$
4304 \end_inset
4305
4306  instead of 
4307 \begin_inset Formula $\mathcal{O}\left(N^{3}\right)$
4308 \end_inset
4309
4310 .
4311  Also, it can be proven that all the roots of 
4312 \begin_inset Formula $A(z)$
4313 \end_inset
4314
4315  are within the unit circle, which means that 
4316 \begin_inset Formula $1/A(z)$
4317 \end_inset
4318
4319  is always stable.
4320  This is in theory; in practice because of finite precision, there are two
4321  commonly used techniques to make sure we have a stable filter.
4322  First, we multiply 
4323 \begin_inset Formula $R(0)$
4324 \end_inset
4325
4326  by a number slightly above one (such as 1.0001), which is equivalent to
4327  adding noise to the signal.
4328  Also, we can apply a window to the auto-correlation, which is equivalent
4329  to filtering in the frequency domain, reducing sharp resonances.
4330 \end_layout
4331
4332 \begin_layout Section
4333 Pitch Prediction
4334 \begin_inset LatexCommand \index{pitch}
4335
4336 \end_inset
4337
4338
4339 \end_layout
4340
4341 \begin_layout Standard
4342 During voiced segments, the speech signal is periodic, so it is possible
4343  to take advantage of that property by approximating the excitation signal
4344  
4345 \begin_inset Formula $e[n]$
4346 \end_inset
4347
4348  by a gain times the past of the excitation:
4349 \end_layout
4350
4351 \begin_layout Standard
4352 \begin_inset Formula \[
4353 e[n]\simeq p[n]=\beta e[n-T]\]
4354
4355 \end_inset
4356
4357
4358 \end_layout
4359
4360 \begin_layout Standard
4361 where 
4362 \begin_inset Formula $T$
4363 \end_inset
4364
4365  is the pitch period, 
4366 \begin_inset Formula $\beta$
4367 \end_inset
4368
4369  is the pitch gain.
4370  We call that long-term prediction since the excitation is predicted from
4371  
4372 \begin_inset Formula $e[n-T]$
4373 \end_inset
4374
4375  with 
4376 \begin_inset Formula $T\gg N$
4377 \end_inset
4378
4379 .
4380 \end_layout
4381
4382 \begin_layout Section
4383 Innovation Codebook
4384 \end_layout
4385
4386 \begin_layout Standard
4387 The final excitation 
4388 \begin_inset Formula $e[n]$
4389 \end_inset
4390
4391  will be the sum of the pitch prediction and an 
4392 \emph on
4393 innovation
4394 \emph default
4395  signal 
4396 \begin_inset Formula $c[n]$
4397 \end_inset
4398
4399  taken from a fixed codebook, hence the name 
4400 \emph on
4401 Code
4402 \emph default
4403  Excited Linear Prediction.
4404  The final excitation is given by:
4405 \end_layout
4406
4407 \begin_layout Standard
4408 \begin_inset Formula \[
4409 e[n]=p[n]+c[n]=\beta e[n-T]+c[n]\]
4410
4411 \end_inset
4412
4413 The quantization of 
4414 \begin_inset Formula $c[n]$
4415 \end_inset
4416
4417  is where most of the bits in a CELP codec are allocated.
4418  It represents the information that couldn't be obtained either from linear
4419  prediction or pitch prediction.
4420  In the 
4421 \emph on
4422 z
4423 \emph default
4424 -domain we can represent the final signal 
4425 \begin_inset Formula $X(z)$
4426 \end_inset
4427
4428  as 
4429 \begin_inset Formula \[
4430 X(z)=\frac{C(z)}{A(z)\left(1-\beta z^{-T}\right)}\]
4431
4432 \end_inset
4433
4434
4435 \end_layout
4436
4437 \begin_layout Section
4438 Noise Weighting
4439 \begin_inset LatexCommand \index{error weighting}
4440
4441 \end_inset
4442
4443
4444 \begin_inset LatexCommand \index{analysis-by-synthesis}
4445
4446 \end_inset
4447
4448
4449 \end_layout
4450
4451 \begin_layout Standard
4452 Most (if not all) modern audio codecs attempt to 
4453 \begin_inset Quotes eld
4454 \end_inset
4455
4456 shape
4457 \begin_inset Quotes erd
4458 \end_inset
4459
4460  the noise so that it appears mostly in the frequency regions where the
4461  ear cannot detect it.
4462  For example, the ear is more tolerant to noise in parts of the spectrum
4463  that are louder and 
4464 \emph on
4465 vice versa
4466 \emph default
4467 .
4468  In order to maximize speech quality, CELP codecs minimize the mean square
4469  of the error (noise) in the perceptually weighted domain.
4470  This means that a perceptual noise weighting filter 
4471 \begin_inset Formula $W(z)$
4472 \end_inset
4473
4474  is applied to the error signal in the encoder.
4475  In most CELP codecs, 
4476 \begin_inset Formula $W(z)$
4477 \end_inset
4478
4479  is a pole-zero weighting filter derived from the linear prediction coefficients
4480  (LPC), generally using bandwidth expansion.
4481  Let the spectral envelope be represented by the synthesis filter 
4482 \begin_inset Formula $1/A(z)$
4483 \end_inset
4484
4485 , CELP codecs typically derive the noise weighting filter as: 
4486 \begin_inset Formula \begin{equation}
4487 W(z)=\frac{A(z/\gamma_{1})}{A(z/\gamma_{2})}\label{eq:gamma-weighting}\end{equation}
4488
4489 \end_inset
4490
4491 where 
4492 \begin_inset Formula $\gamma_{1}=0.9$
4493 \end_inset
4494
4495  and 
4496 \begin_inset Formula $\gamma_{2}=0.6$
4497 \end_inset
4498
4499  in the Speex reference implementation.
4500  If a filter 
4501 \begin_inset Formula $A(z)$
4502 \end_inset
4503
4504  has (complex) poles at 
4505 \begin_inset Formula $p_{i}$
4506 \end_inset
4507
4508  in the 
4509 \begin_inset Formula $z$
4510 \end_inset
4511
4512 -plane, the filter 
4513 \begin_inset Formula $A(z/\gamma)$
4514 \end_inset
4515
4516  will have its poles at 
4517 \begin_inset Formula $p'_{i}=\gamma p_{i}$
4518 \end_inset
4519
4520 , making it a flatter version of 
4521 \begin_inset Formula $A(z)$
4522 \end_inset
4523
4524 .
4525 \end_layout
4526
4527 \begin_layout Standard
4528 The weighting filter is applied to the error signal used to optimize the
4529  codebook search through analysis-by-synthesis (AbS).
4530  This results in a spectral shape of the noise that tends towards 
4531 \begin_inset Formula $1/W(z)$
4532 \end_inset
4533
4534 .
4535  While the simplicity of the model has been an important reason for the
4536  success of CELP, it remains that 
4537 \begin_inset Formula $W(z)$
4538 \end_inset
4539
4540  is a very rough approximation for the perceptually optimal noise weighting
4541  function.
4542  Fig.
4543  
4544 \begin_inset LatexCommand \ref{cap:Standard-noise-shaping}
4545
4546 \end_inset
4547
4548  illustrates the noise shaping that results from Eq.
4549  
4550 \begin_inset LatexCommand \ref{eq:gamma-weighting}
4551
4552 \end_inset
4553
4554 .
4555  Throughout this paper, we refer to 
4556 \begin_inset Formula $W(z)$
4557 \end_inset
4558
4559  as the noise weighting filter and to 
4560 \begin_inset Formula $1/W(z)$
4561 \end_inset
4562
4563  as the noise shaping filter (or curve).
4564 \end_layout
4565
4566 \begin_layout Standard
4567 \begin_inset Float figure
4568 wide false
4569 sideways false
4570 status open
4571
4572 \begin_layout Standard
4573 \begin_inset ERT
4574 status collapsed
4575
4576 \begin_layout Standard
4577
4578
4579 \backslash
4580 begin{center}
4581 \end_layout
4582
4583 \end_inset
4584
4585
4586 \begin_inset Graphics
4587         filename ref_shaping.eps
4588         width 45page%
4589         keepAspectRatio
4590
4591 \end_inset
4592
4593
4594 \begin_inset ERT
4595 status collapsed
4596
4597 \begin_layout Standard
4598
4599
4600 \backslash
4601 end{center}
4602 \end_layout
4603
4604 \end_inset
4605
4606
4607 \end_layout
4608
4609 \begin_layout Caption
4610 Standard noise shaping in CELP.
4611  Arbitrary y-axis offset.
4612 \begin_inset LatexCommand \label{cap:Standard-noise-shaping}
4613
4614 \end_inset
4615
4616
4617 \end_layout
4618
4619 \end_inset
4620
4621
4622 \end_layout
4623
4624 \begin_layout Section
4625 Analysis-by-Synthesis
4626 \end_layout
4627
4628 \begin_layout Standard
4629 One of the main principles behind CELP is called Analysis-by-Synthesis (AbS),
4630  meaning that the encoding (analysis) is performed by perceptually optimising
4631  the decoded (synthesis) signal in a closed loop.
4632  In theory, the best CELP stream would be produced by trying all possible
4633  bit combinations and selecting the one that produces the best-sounding
4634  decoded signal.
4635  This is obviously not possible in practice for two reasons: the required
4636  complexity is beyond any currently available hardware and the 
4637 \begin_inset Quotes eld
4638 \end_inset
4639
4640 best sounding
4641 \begin_inset Quotes erd
4642 \end_inset
4643
4644  selection criterion implies a human listener.
4645  
4646 \end_layout
4647
4648 \begin_layout Standard
4649 In order to achieve real-time encoding using limited computing resources,
4650  the CELP optimisation is broken down into smaller, more manageable, sequential
4651  searches using the perceptual weighting function described earlier.
4652 \end_layout
4653
4654 \begin_layout Standard
4655
4656 \newpage
4657
4658 \end_layout
4659
4660 \begin_layout Chapter
4661 Speex narrowband mode
4662 \begin_inset LatexCommand \label{sec:Speex-narrowband-mode}
4663
4664 \end_inset
4665
4666
4667 \begin_inset LatexCommand \index{narrowband}
4668
4669 \end_inset
4670
4671
4672 \end_layout
4673
4674 \begin_layout Standard
4675 This section looks at how Speex works for narrowband (
4676 \begin_inset Formula $8\:\mathrm{kHz}$
4677 \end_inset
4678
4679  sampling rate) operation.
4680  The frame size for this mode is 
4681 \begin_inset Formula $20\:\mathrm{ms}$
4682 \end_inset
4683
4684 , corresponding to 160 samples.
4685  Each frame is also subdivided into 4 sub-frames of 40 samples each.
4686 \end_layout
4687
4688 \begin_layout Standard
4689 Also many design decisions were based on the original goals and assumptions:
4690 \end_layout
4691
4692 \begin_layout Itemize
4693 Minimizing the amount of information extracted from past frames (for robustness
4694  to packet loss)
4695 \end_layout
4696
4697 \begin_layout Itemize
4698 Dynamically-selectable codebooks (LSP, pitch and innovation)
4699 \end_layout
4700
4701 \begin_layout Itemize
4702 sub-vector fixed (innovation) codebooks
4703 \end_layout
4704
4705 \begin_layout Section
4706 Whole-Frame Analysis
4707 \begin_inset LatexCommand \index{linear prediction}
4708
4709 \end_inset
4710
4711
4712 \end_layout
4713
4714 \begin_layout Standard
4715 In narrowband, Speex frames are 20 ms long (160 samples) and are subdivided
4716  in 4 sub-frames of 5 ms each (40 samples).
4717  For most narrowband bit-rates (8 kbps and above), the only parameters encoded
4718  at the frame level are the Line Spectral Pairs (LSP) and a global excitation
4719  gain 
4720 \begin_inset Formula $g_{frame}$
4721 \end_inset
4722
4723 , as shown in Fig.
4724  
4725 \begin_inset LatexCommand \ref{cap:Frame-open-loop-analysis}
4726
4727 \end_inset
4728
4729 .
4730  All other parameters are encoded at the sub-frame level.
4731 \end_layout
4732
4733 \begin_layout Standard
4734 Linear prediction analysis is performed once per frame using an asymmetric
4735  Hamming window centered on the fourth sub-frame.
4736  Because linear prediction coefficients (LPC) are not robust to quantization,
4737  they are first are converted to line spectral pairs (LSP)
4738 \begin_inset LatexCommand \index{line spectral pair}
4739
4740 \end_inset
4741
4742 .
4743  The LSP's are considered to be associated to the 
4744 \begin_inset Formula $4^{th}$
4745 \end_inset
4746
4747  sub-frames and the LSP's associated to the first 3 sub-frames are linearly
4748  interpolated using the current and previous LSP coefficients.
4749  The LSP coefficients and converted back to the LPC filter 
4750 \begin_inset Formula $\hat{A}(z)$
4751 \end_inset
4752
4753 .
4754  The non-quantized interpolated filter is denoted 
4755 \begin_inset Formula $A(z)$
4756 \end_inset
4757
4758  and can be used for the weighting filter 
4759 \begin_inset Formula $W(z)$
4760 \end_inset
4761
4762  because it does not need to be available to the decoder.
4763  
4764 \end_layout
4765
4766 \begin_layout Standard
4767 To make Speex more robust to packet loss, no prediction is applied on the
4768  LSP coefficients prior to quantization.
4769  The LSPs are encoded using vector quantizatin (VQ) with 30 bits for higher
4770  quality modes and 18 bits for lower quality.
4771 \end_layout
4772
4773 \begin_layout Standard
4774 \begin_inset Float figure
4775 wide false
4776 sideways false
4777 status open
4778
4779 \begin_layout Standard
4780 \begin_inset ERT
4781 status collapsed
4782
4783 \begin_layout Standard
4784
4785
4786 \backslash
4787 begin{center}
4788 \end_layout
4789
4790 \end_inset
4791
4792
4793 \begin_inset Graphics
4794         filename speex_analysis.eps
4795         width 35page%
4796
4797 \end_inset
4798
4799
4800 \begin_inset ERT
4801 status collapsed
4802
4803 \begin_layout Standard
4804
4805
4806 \backslash
4807 end{center}
4808 \end_layout
4809
4810 \end_inset
4811
4812
4813 \end_layout
4814
4815 \begin_layout Caption
4816 Frame open-loop analysis
4817 \begin_inset LatexCommand \label{cap:Frame-open-loop-analysis}
4818
4819 \end_inset
4820
4821
4822 \end_layout
4823
4824 \end_inset
4825
4826
4827 \end_layout
4828
4829 \begin_layout Section
4830 Sub-Frame Analysis-by-Synthesis
4831 \end_layout
4832
4833 \begin_layout Standard
4834 \begin_inset Float figure
4835 wide false
4836 sideways false
4837 status open
4838
4839 \begin_layout Standard
4840 \begin_inset ERT
4841 status collapsed
4842
4843 \begin_layout Standard
4844
4845
4846 \backslash
4847 begin{center}
4848 \end_layout
4849
4850 \end_inset
4851
4852
4853 \begin_inset Graphics
4854         filename speex_abs.eps
4855         lyxscale 75
4856         width 40page%
4857
4858 \end_inset
4859
4860
4861 \begin_inset ERT
4862 status collapsed
4863
4864 \begin_layout Standard
4865
4866
4867 \backslash
4868 end{center}
4869 \end_layout
4870
4871 \end_inset
4872
4873
4874 \end_layout
4875
4876 \begin_layout Caption
4877 Analysis-by-synthesis closed-loop optimization on a sub-frame.
4878 \begin_inset LatexCommand \label{cap:Sub-frame-AbS}
4879
4880 \end_inset
4881
4882
4883 \end_layout
4884
4885 \end_inset
4886
4887
4888 \end_layout
4889
4890 \begin_layout Standard
4891 The analysis-by-synthesis (AbS) encoder loop is described in Fig.
4892  
4893 \begin_inset LatexCommand \ref{cap:Sub-frame-AbS}
4894
4895 \end_inset
4896
4897 .
4898  There are three main aspects where Speex significantly differs from most
4899  other CELP codecs.
4900  First, while most recent CELP codecs make use of fractional pitch estimation
4901  with a single gain, Speex uses an integer to encode the pitch period, but
4902  uses a 3-tap predictor (3 gains).
4903  The adaptive codebook contribution 
4904 \begin_inset Formula $e_{a}[n]$
4905 \end_inset
4906
4907  can thus be expressed as:
4908 \begin_inset Formula \begin{equation}
4909 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}
4910
4911 \end_inset
4912
4913 where 
4914 \begin_inset Formula $g_{0}$
4915 \end_inset
4916
4917
4918 \begin_inset Formula $g_{1}$
4919 \end_inset
4920
4921  and 
4922 \begin_inset Formula $g_{2}$
4923 \end_inset
4924
4925  are the jointly quantized pitch gains and 
4926 \begin_inset Formula $e[n]$
4927 \end_inset
4928
4929  is the codec excitation memory.
4930  It is worth noting that when the pitch is smaller than the sub-frame size,
4931  we repeat the excitation at a period 
4932 \begin_inset Formula $T$
4933 \end_inset
4934
4935 .
4936  For example, when 
4937 \begin_inset Formula $n-T+1\geq0$
4938 \end_inset
4939
4940 , we use 
4941 \begin_inset Formula $n-2T+1$
4942 \end_inset
4943
4944  instead.
4945  In most modes, the pitch period is encoded with 7 bits in the 
4946 \begin_inset Formula $\left[17,144\right]$
4947 \end_inset
4948
4949  range and the 
4950 \begin_inset Formula $\beta_{i}$
4951 \end_inset
4952
4953  coefficients are vector-quantized using 7 bits at higher bit-rates (15
4954  kbps narrowband and above) and 5 bits at lower bit-rates (11 kbps narrowband
4955  and below).
4956 \end_layout
4957
4958 \begin_layout Standard
4959 Many current CELP codecs use moving average (MA) prediction to encode the
4960  fixed codebook gain.
4961  This provides slightly better coding at the expense of introducing a dependency
4962  on previously encoded frames.
4963  A second difference is that Speex encodes the fixed codebook gain as the
4964  product of the global excitation gain 
4965 \begin_inset Formula $g_{frame}$
4966 \end_inset
4967
4968  with a sub-frame gain corrections 
4969 \begin_inset Formula $g_{subf}$
4970 \end_inset
4971
4972 .
4973  This increases robustness to packet loss by eliminating the inter-frame
4974  dependency.
4975  The sub-frame gain correction is encoded before the fixed codebook is searched
4976  (not closed-loop optimized) and uses between 0 and 3 bits per sub-frame,
4977  depending on the bit-rate.
4978 \end_layout
4979
4980 \begin_layout Standard
4981 The third difference is that Speex uses sub-vector quantization of the innovatio
4982 n (fixed codebook) signal instead of an algebraic codebook.
4983  Each sub-frame is divided into sub-vectors of lengths ranging between 5
4984  and 20 samples.
4985  Each sub-vector is chosen from a bitrate-dependent codebook and all sub-vectors
4986  are concatenated to form a sub-frame.
4987  As an example, the 3.95 kbps mode uses a sub-vector size of 20 samples with
4988  32 entries in the codebook (5 bits).
4989  This means that the innovation is encoded with 10 bits per sub-frame, or
4990  2000 bps.
4991  On the other hand, the 18.2 kbps mode uses a sub-vector size of 5 samples
4992  with 256 entries in the codebook (8 bits), so the innovation uses 64 bits
4993  per sub-frame, or 12800 bps.
4994  
4995 \end_layout
4996
4997 \begin_layout Section
4998 Bit allocation
4999 \end_layout
5000
5001 \begin_layout Standard
5002 There are 7 different narrowband bit-rates defined for Speex, ranging from
5003  250 bps to 24.6 kbps, although the modes below 5.9 kbps should not be used
5004  for speech.
5005  The bit-allocation for each mode is detailed in table 
5006 \begin_inset LatexCommand \ref{cap:bits-narrowband}
5007
5008 \end_inset
5009
5010 .
5011  Each frame starts with the mode ID encoded with 4 bits which allows a range
5012  from 0 to 15, though only the first 7 values are used (the others are reserved).
5013  The parameters are listed in the table in the order they are packed in
5014  the bit-stream.
5015  All frame-based parameters are packed before sub-frame parameters.
5016  The parameters for a certain sub-frame are all packed before the following
5017  sub-frame is packed.
5018  Note that the 
5019 \begin_inset Quotes eld
5020 \end_inset
5021
5022 OL
5023 \begin_inset Quotes erd
5024 \end_inset
5025
5026  in the parameter description means that the parameter is an open loop estimatio
5027 n based on the whole frame.
5028 \end_layout
5029
5030 \begin_layout Standard
5031 \begin_inset Float table
5032 placement h
5033 wide true
5034 sideways false
5035 status open
5036
5037 \begin_layout Standard
5038 \begin_inset ERT
5039 status collapsed
5040
5041 \begin_layout Standard
5042
5043
5044 \backslash
5045 begin{center}
5046 \end_layout
5047
5048 \end_inset
5049
5050
5051 \begin_inset Tabular
5052 <lyxtabular version="3" rows="12" columns="11">
5053 <features>
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" width="0pt">
5064 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
5065 <row topline="true" bottomline="true">
5066 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5067 \begin_inset Text
5068
5069 \begin_layout Standard
5070 Parameter
5071 \end_layout
5072
5073 \end_inset
5074 </cell>
5075 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5076 \begin_inset Text
5077
5078 \begin_layout Standard
5079 Update rate
5080 \end_layout
5081
5082 \end_inset
5083 </cell>
5084 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5085 \begin_inset Text
5086
5087 \begin_layout Standard
5088 0
5089 \end_layout
5090
5091 \end_inset
5092 </cell>
5093 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5094 \begin_inset Text
5095
5096 \begin_layout Standard
5097 1
5098 \end_layout
5099
5100 \end_inset
5101 </cell>
5102 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5103 \begin_inset Text
5104
5105 \begin_layout Standard
5106 2
5107 \end_layout
5108
5109 \end_inset
5110 </cell>
5111 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5112 \begin_inset Text
5113
5114 \begin_layout Standard
5115 3
5116 \end_layout
5117
5118 \end_inset
5119 </cell>
5120 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5121 \begin_inset Text
5122
5123 \begin_layout Standard
5124 4
5125 \end_layout
5126
5127 \end_inset
5128 </cell>
5129 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5130 \begin_inset Text
5131
5132 \begin_layout Standard
5133 5
5134 \end_layout
5135
5136 \end_inset
5137 </cell>
5138 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5139 \begin_inset Text
5140
5141 \begin_layout Standard
5142 6
5143 \end_layout
5144
5145 \end_inset
5146 </cell>
5147 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5148 \begin_inset Text
5149
5150 \begin_layout Standard
5151 7
5152 \end_layout
5153
5154 \end_inset
5155 </cell>
5156 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5157 \begin_inset Text
5158
5159 \begin_layout Standard
5160 8
5161 \end_layout
5162
5163 \end_inset
5164 </cell>
5165 </row>
5166 <row topline="true">
5167 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5168 \begin_inset Text
5169
5170 \begin_layout Standard
5171 Wideband bit
5172 \end_layout
5173
5174 \end_inset
5175 </cell>
5176 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5177 \begin_inset Text
5178
5179 \begin_layout Standard
5180 frame
5181 \end_layout
5182
5183 \end_inset
5184 </cell>
5185 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5186 \begin_inset Text
5187
5188 \begin_layout Standard
5189 1
5190 \end_layout
5191
5192 \end_inset
5193 </cell>
5194 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5195 \begin_inset Text
5196
5197 \begin_layout Standard
5198 1
5199 \end_layout
5200
5201 \end_inset
5202 </cell>
5203 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5204 \begin_inset Text
5205
5206 \begin_layout Standard
5207 1
5208 \end_layout
5209
5210 \end_inset
5211 </cell>
5212 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5213 \begin_inset Text
5214
5215 \begin_layout Standard
5216 1
5217 \end_layout
5218
5219 \end_inset
5220 </cell>
5221 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5222 \begin_inset Text
5223
5224 \begin_layout Standard
5225 1
5226 \end_layout
5227
5228 \end_inset
5229 </cell>
5230 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5231 \begin_inset Text
5232
5233 \begin_layout Standard
5234 1
5235 \end_layout
5236
5237 \end_inset
5238 </cell>
5239 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5240 \begin_inset Text
5241
5242 \begin_layout Standard
5243 1
5244 \end_layout
5245
5246 \end_inset
5247 </cell>
5248 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5249 \begin_inset Text
5250
5251 \begin_layout Standard
5252 1
5253 \end_layout
5254
5255 \end_inset
5256 </cell>
5257 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5258 \begin_inset Text
5259
5260 \begin_layout Standard
5261 1
5262 \end_layout
5263
5264 \end_inset
5265 </cell>
5266 </row>
5267 <row topline="true">
5268 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5269 \begin_inset Text
5270
5271 \begin_layout Standard
5272 Mode ID
5273 \end_layout
5274
5275 \end_inset
5276 </cell>
5277 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5278 \begin_inset Text
5279
5280 \begin_layout Standard
5281 frame
5282 \end_layout
5283
5284 \end_inset
5285 </cell>
5286 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5287 \begin_inset Text
5288
5289 \begin_layout Standard
5290 4
5291 \end_layout
5292
5293 \end_inset
5294 </cell>
5295 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5296 \begin_inset Text
5297
5298 \begin_layout Standard
5299 4
5300 \end_layout
5301
5302 \end_inset
5303 </cell>
5304 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5305 \begin_inset Text
5306
5307 \begin_layout Standard
5308 4
5309 \end_layout
5310
5311 \end_inset
5312 </cell>
5313 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5314 \begin_inset Text
5315
5316 \begin_layout Standard
5317 4
5318 \end_layout
5319
5320 \end_inset
5321 </cell>
5322 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5323 \begin_inset Text
5324
5325 \begin_layout Standard
5326 4
5327 \end_layout
5328
5329 \end_inset
5330 </cell>
5331 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5332 \begin_inset Text
5333
5334 \begin_layout Standard
5335 4
5336 \end_layout
5337
5338 \end_inset
5339 </cell>
5340 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5341 \begin_inset Text
5342
5343 \begin_layout Standard
5344 4
5345 \end_layout
5346
5347 \end_inset
5348 </cell>
5349 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5350 \begin_inset Text
5351
5352 \begin_layout Standard
5353 4
5354 \end_layout
5355
5356 \end_inset
5357 </cell>
5358 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5359 \begin_inset Text
5360
5361 \begin_layout Standard
5362 4
5363 \end_layout
5364
5365 \end_inset
5366 </cell>
5367 </row>
5368 <row topline="true">
5369 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5370 \begin_inset Text
5371
5372 \begin_layout Standard
5373 LSP
5374 \end_layout
5375
5376 \end_inset
5377 </cell>
5378 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5379 \begin_inset Text
5380
5381 \begin_layout Standard
5382 frame
5383 \end_layout
5384
5385 \end_inset
5386 </cell>
5387 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5388 \begin_inset Text
5389
5390 \begin_layout Standard
5391 0
5392 \end_layout
5393
5394 \end_inset
5395 </cell>
5396 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5397 \begin_inset Text
5398
5399 \begin_layout Standard
5400 18
5401 \end_layout
5402
5403 \end_inset
5404 </cell>
5405 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5406 \begin_inset Text
5407
5408 \begin_layout Standard
5409 18
5410 \end_layout
5411
5412 \end_inset
5413 </cell>
5414 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5415 \begin_inset Text
5416
5417 \begin_layout Standard
5418 18
5419 \end_layout
5420
5421 \end_inset
5422 </cell>
5423 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5424 \begin_inset Text
5425
5426 \begin_layout Standard
5427 18
5428 \end_layout
5429
5430 \end_inset
5431 </cell>
5432 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5433 \begin_inset Text
5434
5435 \begin_layout Standard
5436 30
5437 \end_layout
5438
5439 \end_inset
5440 </cell>
5441 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5442 \begin_inset Text
5443
5444 \begin_layout Standard
5445 30
5446 \end_layout
5447
5448 \end_inset
5449 </cell>
5450 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5451 \begin_inset Text
5452
5453 \begin_layout Standard
5454 30
5455 \end_layout
5456
5457 \end_inset
5458 </cell>
5459 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5460 \begin_inset Text
5461
5462 \begin_layout Standard
5463 18
5464 \end_layout
5465
5466 \end_inset
5467 </cell>
5468 </row>
5469 <row topline="true">
5470 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5471 \begin_inset Text
5472
5473 \begin_layout Standard
5474 OL pitch
5475 \end_layout
5476