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