documentation update, build/install tweaks
[speexdsp.git] / doc / manual.lyx
1 #LyX 1.3 created this file. For more info see http://www.lyx.org/
2 \lyxformat 221
3 \textclass article
4 \language english
5 \inputencoding auto
6 \fontscheme pslatex
7 \graphics default
8 \paperfontsize default
9 \spacing single 
10 \papersize letterpaper
11 \paperpackage a4
12 \use_geometry 0
13 \use_amsmath 0
14 \use_natbib 0
15 \use_numerical_citations 0
16 \paperorientation portrait
17 \secnumdepth 3
18 \tocdepth 3
19 \paragraph_separation indent
20 \defskip medskip
21 \quotes_language english
22 \quotes_times 2
23 \papercolumns 1
24 \papersides 1
25 \paperpagestyle headings
26
27 \layout Title
28
29 The Speex Codec Manual
30 \newline 
31 (version 1.1.6)
32 \layout Author
33
34 Jean-Marc Valin
35 \layout Standard
36 \pagebreak_top 
37 Copyright (c) 2002-2004 Jean-Marc Valin/Xiph.org Foundation
38 \layout Standard
39
40 Permission is granted to copy, distribute and/or modify this document under
41  the terms of the GNU Free Documentation License, Version 1.1 or any later
42  version published by the Free Software Foundation; with no Invariant Section,
43  with no Front-Cover Texts, and with no Back-Cover.
44  A copy of the license is included in the section entitled "GNU Free Documentati
45 on License".
46  
47 \layout Standard
48 \pagebreak_top \pagebreak_bottom 
49
50 \begin_inset LatexCommand \tableofcontents{}
51
52 \end_inset 
53
54
55 \layout Standard
56 \pagebreak_bottom 
57
58 \begin_inset FloatList table
59
60 \end_inset 
61
62
63 \layout Section
64
65 Introduction to Speex
66 \layout Standard
67
68 The Speex project (
69 \family typewriter 
70 http://www.speex.org/
71 \family default 
72 ) has been started because there was a need for a speech codec that was
73  open-source and free from software patents.
74  These are essential conditions for being used by any open-source software.
75  There is already Vorbis that does general audio, but it is not really suitable
76  for speech.
77  Also, unlike many other speech codecs, Speex is not targeted at cell phones
78  (not many open-source cell phones anyway :-) ) but rather at voice over
79  IP (VoIP) and file-based compression.
80  
81 \layout Standard
82
83 As design goals, we wanted to have a codec that would allow both very good
84  quality speech and low bit-rate (unfortunately not at the same time!),
85  which led us to developing a codec with multiple bit-rates.
86  Of course very good quality also meant we had to do wideband (16 kHz sampling
87  rate) in addition to narrowband (telephone quality, 8 kHz sampling rate).
88 \layout Standard
89
90 Designing for VoIP instead of cell phone use means that Speex must be robust
91  to lost packets, but not to corrupted ones since packets either arrive
92  unaltered or don't arrive at all.
93  Also, the idea was to have a reasonable complexity and memory requirement
94  without compromising too much on the efficiency of the codec.
95 \layout Standard
96
97 All this led us to the choice of CELP
98 \begin_inset LatexCommand \index{CELP}
99
100 \end_inset 
101
102  as the encoding technique to use for Speex.
103  One of the main reasons is that CELP has long proved that it could do the
104  job and scale well to both low bit-rates (think DoD CELP @ 4.8 kbps) and
105  high bit-rates (think G.728 @ 16 kbps).
106  
107 \layout Standard
108
109 The main characteristics can be summarized as follows:
110 \layout Itemize
111
112 Free software/open-source
113 \begin_inset LatexCommand \index{open-source}
114
115 \end_inset 
116
117 , patent
118 \begin_inset LatexCommand \index{patent}
119
120 \end_inset 
121
122  and royalty-free
123 \layout Itemize
124
125 Integration of narrowband
126 \begin_inset LatexCommand \index{narrowband}
127
128 \end_inset 
129
130  and wideband
131 \begin_inset LatexCommand \index{wideband}
132
133 \end_inset 
134
135  using an embedded bit-stream
136 \layout Itemize
137
138 Wide range of bit-rates available (from 2 kbps to 44 kbps)
139 \layout Itemize
140
141 Dynamic bit-rate switching and Variable Bit-Rate
142 \begin_inset LatexCommand \index{variable bit-rate}
143
144 \end_inset 
145
146  (VBR)
147 \layout Itemize
148
149 Voice Activity Detection
150 \begin_inset LatexCommand \index{voice activity detection}
151
152 \end_inset 
153
154  (VAD, integrated with VBR)
155 \layout Itemize
156
157 Variable complexity
158 \begin_inset LatexCommand \index{complexity}
159
160 \end_inset 
161
162
163 \layout Itemize
164
165 Ultra-wideband mode at 32 kHz (up to 48 kHz)
166 \layout Itemize
167
168 Intensity stereo encoding option
169 \layout Itemize
170
171 Fixed-point implementation (work in progress)
172 \layout Standard
173
174 This document is divided in the following way.
175  Section 
176 \begin_inset LatexCommand \ref{sec:Feature-description}
177
178 \end_inset 
179
180  describes the different Speex features and defines some terms that will
181  be used in later sections.
182  Section 
183 \begin_inset LatexCommand \ref{sec:Command-line-encoder/decoder}
184
185 \end_inset 
186
187  provides information about the standard command-line tools, while 
188 \begin_inset LatexCommand \ref{sec:Programming-with-Speex}
189
190 \end_inset 
191
192  contains information about programming using the Speex API.
193  Section 
194 \begin_inset LatexCommand \ref{sec:Formats-and-standards}
195
196 \end_inset 
197
198  has some information related to Speex and standards.
199  The three last sections describe the internals of the codec and require
200  some signal processing knowledge.
201  Section 
202 \begin_inset LatexCommand \ref{sec:Introduction-to-CELP}
203
204 \end_inset 
205
206  explains the general idea behind CELP, while sections 
207 \begin_inset LatexCommand \ref{sec:Speex-narrowband-mode}
208
209 \end_inset 
210
211  and 
212 \begin_inset LatexCommand \ref{sec:Speex-wideband-mode}
213
214 \end_inset 
215
216  are specific to Speex.
217  Note that if you are only interested in using Speex, those three last sections
218  are not required.
219 \layout Section
220 \pagebreak_top 
221 Codec description
222 \begin_inset LatexCommand \label{sec:Feature-description}
223
224 \end_inset 
225
226
227 \layout Standard
228
229 This section describes the main features provided by Speex.
230 \layout Subsection
231
232 Concepts
233 \layout Standard
234
235 Here are some concepts in speech coding that help better understand the
236  rest of the manual.
237  Emphasis is placed on the Speex features.
238 \layout Subsection*
239
240 Sampling rate
241 \begin_inset LatexCommand \index{sampling rate}
242
243 \end_inset 
244
245
246 \layout Standard
247
248 Speex is mainly designed for 3 different sampling rates: 8 kHz, 16 kHz,
249  and 32 kHz.
250  These are respectively refered to as narrowband
251 \begin_inset LatexCommand \index{narrowband}
252
253 \end_inset 
254
255 , wideband
256 \begin_inset LatexCommand \index{wideband}
257
258 \end_inset 
259
260  and ultra-wideband
261 \begin_inset LatexCommand \index{ultra-wideband}
262
263 \end_inset 
264
265 .
266  
267 \layout Subsection*
268
269 Quality
270 \begin_inset LatexCommand \index{quality}
271
272 \end_inset 
273
274
275 \layout Standard
276
277 Speex encoding is controlled most of the time by a quality parameter that
278  ranges from 0 to 10.
279  In constant bit-rate
280 \begin_inset LatexCommand \index{constant bit-rate}
281
282 \end_inset 
283
284  (CBR) operation, the quality parameter is an integer, while for variable
285  bit-rate (VBR), the parameter is a float.
286  
287 \layout Subsection*
288
289 Complexity
290 \begin_inset LatexCommand \index{complexity}
291
292 \end_inset 
293
294  (variable)
295 \layout Standard
296
297 With Speex, it is possible to vary the complexity allowed for the encoder.
298  This is done by controlling how the search is performed with an integer
299  ranging from 1 to 10 in a way that's similar to the -1 to -9 options to
300  
301 \emph on 
302 gzip
303 \emph default 
304  and 
305 \emph on 
306 bzip2
307 \emph default 
308  compression utilities.
309  For normal use, the noise level at complexity 1 is between 1 and 2 dB higher
310  than at complexity 10, but the CPU requirements for complexity 10 is about
311  5 times higher than for complexity 1.
312  In practice, the best trade-off is between complexity 2 and 4, though higher
313  settings are often useful when encoding non-speech sounds like DTMF
314 \begin_inset LatexCommand \index{DTMF}
315
316 \end_inset 
317
318  tones.
319 \layout Subsection*
320
321 Variable Bit-Rate
322 \begin_inset LatexCommand \index{variable bit-rate}
323
324 \end_inset 
325
326  (VBR)
327 \layout Standard
328
329 Variable bit-rate (VBR) allows a codec to change its bit-rate dynamically
330  to adapt to the 
331 \begin_inset Quotes eld
332 \end_inset 
333
334 difficulty
335 \begin_inset Quotes erd
336 \end_inset 
337
338  of the audio being encoded.
339  In the example of Speex, sounds like vowels and high-energy transients
340  require a higher bit-rate to achieve good quality, while fricatives (e.g.
341  s,f sounds) can be coded adequately with less bits.
342  For this reason, VBR can achive lower bit-rate for the same quality, or
343  a better quality for a certain bit-rate.
344  Despite its advantages, VBR has two main drawbacks: first, by only specifying
345  quality, there's no guaranty about the final average bit-rate.
346  Second, for some real-time applications like voice over IP (VoIP), what
347  counts is the maximum bit-rate, which must be low enough for the communication
348  channel.
349 \layout Subsection*
350
351 Average Bit-Rate
352 \begin_inset LatexCommand \index{average bit-rate}
353
354 \end_inset 
355
356  (ABR)
357 \layout Standard
358
359 Average bit-rate solves one of the problems of VBR, as it dynamically adjusts
360  VBR quality in order to meet a specific target bit-rate.
361  Because the quality/bit-rate is adjusted in real-time (open-loop), the
362  global quality will be slightly lower than that obtained by encoding in
363  VBR with exactly the right quality setting to meet the target average bit-rate.
364 \layout Subsection*
365
366 Voice Activity Detection
367 \begin_inset LatexCommand \index{voice activity detection}
368
369 \end_inset 
370
371  (VAD)
372 \layout Standard
373
374 When enabled, voice activity detection detects whether the audio being encoded
375  is speech or silence/background noise.
376  VAD is always implicitly activated when encoding in VBR, so the option
377  is only useful in non-VBR operation.
378  In this case, Speex detects non-speech periods and encode them with just
379  enough bits to reproduce the background noise.
380  This is called 
381 \begin_inset Quotes eld
382 \end_inset 
383
384 comfort noise generation
385 \begin_inset Quotes erd
386 \end_inset 
387
388  (CNG).
389 \layout Subsection*
390
391 Discontinuous Transmission
392 \begin_inset LatexCommand \index{discontinuous transmission}
393
394 \end_inset 
395
396  (DTX)
397 \layout Standard
398
399 Discontinuous transmission is an addition to VAD/VBR operation, that allows
400  to stop transmitting completely when the background noise is stationary.
401  In file-based operation, since we cannot just stop writing to the file,
402  only 5 bits are used for such frames (corresponding to 250 bps).
403 \layout Subsection*
404
405 Perceptual enhancement
406 \begin_inset LatexCommand \index{perceptual enhancement}
407
408 \end_inset 
409
410
411 \layout Standard
412
413 Perceptual enhancement is a part of the decoder which, when turned on, tries
414  to reduce (the perception of) the noise produced by the coding/decoding
415  process.
416  In most cases, perceptual enhancement make the sound further from the original
417  
418 \emph on 
419 objectively
420 \emph default 
421  (if you use SNR), but in the end it still 
422 \emph on 
423 sounds
424 \emph default 
425  better (subjective improvement).
426 \layout Subsection*
427
428 Algorithmic delay
429 \begin_inset LatexCommand \index{algorithmic delay}
430
431 \end_inset 
432
433
434 \layout Standard
435
436 Every speech codec introduces a delay in the transmission.
437  For Speex, this delay is equal to the frame size, plus some amount of 
438 \begin_inset Quotes eld
439 \end_inset 
440
441 look-ahead
442 \begin_inset Quotes erd
443 \end_inset 
444
445  required to process each frame.
446  In narrowband operation (8 kHz), the delay is 30 ms, while for wideband
447  (16 kHz), the delay is 34 ms.
448  These values don't account for the CPU time it takes to encode or decode
449  the frames.
450 \layout Subsection
451
452 Coding
453 \layout Subsection
454
455 Preprocessor
456 \layout Standard
457
458 This part refers to the preprocessor module introduced in the 1.1.x branch.
459  The preprocessor is designed to be used on the audio 
460 \emph on 
461 before
462 \emph default 
463  running the encoder.
464  The preprocessor provides three main functionalities:
465 \layout Itemize
466
467 denoising
468 \layout Itemize
469
470 automatic gain control (AGC)
471 \layout Itemize
472
473 voice activity detection (VAD)
474 \layout Standard
475
476 The denoiser can be used to reduce the amount of background noise present
477  in the input signal.
478  This provides higher quality speech whether or not the denoised signal
479  is encoded with Speex (or at all).
480  However, when using the denoised signal with the codec, there is an additional
481  benefit.
482  Speech codecs in general (Speex included) tend to perform poorly on noisy
483  input, which tends to amplify the noise.
484  The denoiser greatly reduces this effect.
485 \layout Standard
486
487 Automatic gain control (AGC) is a feature that deals with the fact that
488  the recording volume may vary by a large amount between different setups.
489  The AGC provides a way to adjust a signal to a reference volume.
490  This is useful for voice over IP because it removes the need for manual
491  adjustment of the microphone gain.
492  A secondary advantage is that by setting the microphone gain to a conservative
493  (low) level, it is easier to avoid clipping.
494 \layout Standard
495
496 The voice activity detector (VAD) provided by the preprocessor is more advanced
497  than the one directly provided in the codec.
498  
499 \layout Section
500 \pagebreak_top 
501 Command-line encoder/decoder
502 \begin_inset LatexCommand \label{sec:Command-line-encoder/decoder}
503
504 \end_inset 
505
506
507 \layout Standard
508
509 The base Speex distribution includes a command-line encoder (
510 \emph on 
511 speexenc
512 \emph default 
513 ) and decoder (
514 \emph on 
515 speexdec
516 \emph default 
517 ).
518  This section describes how to use these tools.
519 \layout Subsection
520
521
522 \emph on 
523 speexenc
524 \begin_inset LatexCommand \index{speexenc}
525
526 \end_inset 
527
528
529 \layout Standard
530
531 The 
532 \emph on 
533 speexenc
534 \emph default 
535  utility is used to create Speex files from raw PCM or wave files.
536  It can be used by calling: 
537 \layout LyX-Code
538
539 speexenc [options] input_file output_file
540 \layout Standard
541
542 The value '-' for input_file or output_file corresponds respectively to
543  stdin and stdout.
544  The valid options are:
545 \layout Description
546
547 --narrowband\SpecialChar ~
548 (-n) Tell Speex to treat the input as narrowband (8 kHz).
549  This is the default
550 \layout Description
551
552 --wideband\SpecialChar ~
553 (-w) Tell Speex to treat the input as wideband (16 kHz)
554 \layout Description
555
556 --ultra-wideband\SpecialChar ~
557 (-u) Tell Speex to treat the input as 
558 \begin_inset Quotes eld
559 \end_inset 
560
561 ultra-wideband
562 \begin_inset Quotes erd
563 \end_inset 
564
565  (32 kHz)
566 \layout Description
567
568 --quality\SpecialChar ~
569 n Set the encoding quality (0-10), default is 8
570 \layout Description
571
572 --bitrate\SpecialChar ~
573 n Encoding bit-rate (use bit-rate n or lower) 
574 \layout Description
575
576 --vbr Enable VBR (Variable Bit-Rate), disabled by default
577 \layout Description
578
579 --abr\SpecialChar ~
580 n Enable ABR (Average Bit-Rate) at n kbps, disabled by default
581 \layout Description
582
583 --vad Enable VAD (Voice Activity Detection), disabled by default
584 \layout Description
585
586 --dtx Enable DTX (Discontinuous Transmission), disabled by default
587 \layout Description
588
589 --nframes\SpecialChar ~
590 n Pack n frames in each Ogg packet (this saves space at low bit-rates)
591 \layout Description
592
593 --comp\SpecialChar ~
594 n Set encoding speed/quality tradeoff.
595  The higher the value of n, the slower the encoding (default is 3)
596 \layout Description
597
598 -V Verbose operation, print bit-rate currently in use
599 \layout Description
600
601 --help\SpecialChar ~
602 (-h) Print the help
603 \layout Description
604
605 --version\SpecialChar ~
606 (-v) Print version information
607 \layout Subsubsection*
608
609 Speex comments
610 \layout Description
611
612 --comment Add the given string as an extra comment.
613  This may be used multiple times.
614  
615 \layout Description
616
617 --author Author of this track.
618  
619 \layout Description
620
621 --title Title for this track.
622  
623 \layout Subsubsection*
624
625 Raw input options
626 \layout Description
627
628 --rate\SpecialChar ~
629 n Sampling rate for raw input
630 \layout Description
631
632 --stereo Consider raw input as stereo 
633 \layout Description
634
635 --le Raw input is little-endian 
636 \layout Description
637
638 --be Raw input is big-endian 
639 \layout Description
640
641 --8bit Raw input is 8-bit unsigned 
642 \layout Description
643
644 --16bit Raw input is 16-bit signed 
645 \layout Subsection
646
647
648 \emph on 
649 speexdec
650 \begin_inset LatexCommand \index{speexdec}
651
652 \end_inset 
653
654
655 \layout Standard
656
657 The 
658 \emph on 
659 speexdec
660 \emph default 
661  utility is used to decode Speex files and can be used by calling: 
662 \layout LyX-Code
663
664 speexdec [options] speex_file [output_file]
665 \layout Standard
666
667 The value '-' for input_file or output_file corresponds respectively to
668  stdin and stdout.
669  Also, when no output_file is specified, the file is played to the soundcard.
670  The valid options are:
671 \layout Description
672
673 --enh enable post-filter (default)
674 \layout Description
675
676 --no-enh disable post-filter
677 \layout Description
678
679 --force-nb Force decoding in narrowband 
680 \layout Description
681
682 --force-wb Force decoding in wideband 
683 \layout Description
684
685 --force-uwb Force decoding in ultra-wideband 
686 \layout Description
687
688 --mono Force decoding in mono 
689 \layout Description
690
691 --stereo Force decoding in stereo 
692 \layout Description
693
694 --rate\SpecialChar ~
695 n Force decoding at n Hz sampling rate
696 \layout Description
697
698 --packet-loss\SpecialChar ~
699 n Simulate n % random packet loss
700 \layout Description
701
702 -V Verbose operation, print bit-rate currently in use
703 \layout Description
704
705 --help\SpecialChar ~
706 (-h) Print the help
707 \layout Description
708
709 --version\SpecialChar ~
710 (-v) Print version information
711 \layout Section
712 \pagebreak_top 
713 Programming with Speex (the libspeex
714 \begin_inset LatexCommand \index{libspeex}
715
716 \end_inset 
717
718  API
719 \begin_inset LatexCommand \index{API}
720
721 \end_inset 
722
723 )
724 \begin_inset LatexCommand \label{sec:Programming-with-Speex}
725
726 \end_inset 
727
728
729 \layout Standard
730
731 This section explains how to use the Speex API.
732  Examples of code can also be found in appendix 
733 \begin_inset LatexCommand \ref{sec:Sample-code}
734
735 \end_inset 
736
737 .
738 \layout Subsection
739
740 Encoding
741 \layout Standard
742
743 In order to encode speech using Speex, you first need to:
744 \layout LyX-Code
745
746 #include <speex/speex.h>
747 \layout Standard
748
749 You then need to declare a Speex bit-packing struct
750 \layout LyX-Code
751
752 SpeexBits bits;
753 \layout Standard
754
755 and a Speex encoder state
756 \layout LyX-Code
757
758 void *enc_state;
759 \layout Standard
760
761 The two are initialized by:
762 \layout LyX-Code
763
764 speex_bits_init(&bits);
765 \layout LyX-Code
766
767 enc_state = speex_encoder_init(&speex_nb_mode);
768 \layout Standard
769
770 For wideband coding, 
771 \emph on 
772 speex_nb_mode
773 \emph default 
774  will be replaced by 
775 \emph on 
776 speex_wb_mode
777 \emph default 
778 .
779  In most cases, you will need to know the frame size used by the mode you
780  are using.
781  You can get that value in the 
782 \emph on 
783 frame_size
784 \emph default 
785  variable with:
786 \layout LyX-Code
787
788 speex_encoder_ctl(enc_state,SPEEX_GET_FRAME_SIZE,&frame_size);
789 \layout Standard
790
791 In practice, 
792 \emph on 
793 frame_size
794 \emph default 
795  will correspond to 20 ms when using 8, 16, or 32 kHz sampling rate.
796 \layout Standard
797
798 Once the initialization is done, for every input frame:
799 \layout LyX-Code
800
801 speex_bits_reset(&bits);
802 \layout LyX-Code
803
804 speex_encode(enc_state, input_frame, &bits);
805 \layout LyX-Code
806
807 nbBytes = speex_bits_write(&bits, byte_ptr, MAX_NB_BYTES);
808 \layout Standard
809
810 where 
811 \emph on 
812 input_frame
813 \emph default 
814  is a 
815 \emph on 
816 (float *)
817 \emph default 
818  pointing to the beginning of a speech frame, 
819 \emph on 
820 byte_ptr
821 \emph default 
822  is a 
823 \emph on 
824 (char *)
825 \emph default 
826  where the encoded frame will be written, 
827 \emph on 
828 MAX_NB_BYTES
829 \emph default 
830  is the maximum number of bytes that can be written to 
831 \emph on 
832 byte_ptr
833 \emph default 
834  without causing an overflow and 
835 \emph on 
836 nbBytes
837 \emph default 
838  is the number of bytes actually written to 
839 \emph on 
840 byte_ptr
841 \emph default 
842  (the encoded size in bytes).
843  Before calling speex_bits_write, it is possible to find the number of bytes
844  that need to be written by calling 
845 \family typewriter 
846 speex_bits_nbytes(&bits)
847 \family default 
848 , which returns a number of bytes.
849 \layout Standard
850
851 When using an unstable release (1.1.x), it is possible to use the 
852 \emph on 
853 speex_encode_int()
854 \emph default 
855  function, which takes a 
856 \emph on 
857 (short *)
858 \emph default 
859  for the audio.
860  This is usually simpler and it makes an eventual port to an FPU-less platform
861  (like ARM) easier.
862 \layout Standard
863
864 After you're done with the encoding, free all resources with:
865 \layout LyX-Code
866
867 speex_bits_destroy(&bits);
868 \layout LyX-Code
869
870 speex_encoder_destroy(enc_state);
871 \layout Standard
872
873 That's about it for the encoder.
874  
875 \layout Subsection
876
877 Decoding
878 \layout Standard
879
880 In order to encode speech using Speex, you first need to:
881 \layout LyX-Code
882
883 #include <speex/speex.h>
884 \layout Standard
885
886 You also need to declare a Speex bit-packing struct
887 \layout LyX-Code
888
889 SpeexBits bits;
890 \layout Standard
891
892 and a Speex encoder state
893 \layout LyX-Code
894
895 void *dec_state;
896 \layout Standard
897
898 The two are initialized by:
899 \layout LyX-Code
900
901 speex_bits_init(&bits);
902 \layout LyX-Code
903
904 dec_state = speex_decoder_init(&speex_nb_mode);
905 \layout Standard
906
907 For wideband decoding, 
908 \emph on 
909 speex_nb_mode
910 \emph default 
911  will be replaced by 
912 \emph on 
913 speex_wb_mode
914 \emph default 
915 .
916  If you need to obtain the size of the frames that will be used by the decoder,
917  you can get that value in the 
918 \emph on 
919 frame_size
920 \emph default 
921  variable with:
922 \layout LyX-Code
923
924 speex_decoder_ctl(dec_state, SPEEX_GET_FRAME_SIZE, &frame_size); 
925 \layout Standard
926
927 There is also a parameter that can be set for the decoder: whether or not
928  to use a perceptual post-filter.
929  This can be set by: 
930 \layout LyX-Code
931
932 speex_decoder_ctl(dec_state, SPEEX_SET_ENH, &enh); 
933 \layout Standard
934
935 where 
936 \emph on 
937 enh
938 \emph default 
939  is an int that with value 0 to have the post-filter disabled and 1 to have
940  it enabled.
941 \layout Standard
942
943 Again, once the decoder initialization is done, for every input frame:
944 \layout LyX-Code
945
946 speex_bits_read_from(&bits, input_bytes, nbBytes);
947 \layout LyX-Code
948
949 speex_decode(dec_state, &bits, output_frame);
950 \layout Standard
951
952 where input_bytes is a 
953 \emph on 
954 (char *)
955 \emph default 
956  containing the bit-stream data received for a frame, 
957 \emph on 
958 nbBytes
959 \emph default 
960  is the size (in bytes) of that bit-stream, and 
961 \emph on 
962 output_frame
963 \emph default 
964  is a 
965 \emph on 
966 (float *)
967 \emph default 
968  and points to the area where the decoded speech frame will be written.
969  A NULL value as the first argument indicates that we don't have the bits
970  for the current frame.
971  When a frame is lost, the Speex decoder will do its best to "guess" the
972  correct signal.
973 \layout Standard
974
975 As for the encoder, the 1.1.x branch introduces the 
976 \emph on 
977 speex_decode_int()
978 \emph default 
979  function which also uses a 
980 \emph on 
981 (short *)
982 \emph default 
983  as the output for the audio.
984 \layout Standard
985
986 After you're done with the decoding, free all resources with:
987 \layout LyX-Code
988
989 speex_bits_destroy(&bits);
990 \layout LyX-Code
991
992 speex_decoder_destroy(dec_state);
993 \layout Subsection
994
995 Preprocessor
996 \layout Standard
997
998 In order to use the Speex preprocessor, you first need to:
999 \layout LyX-Code
1000
1001 #include <speex/speex_preprocess.h>
1002 \layout Standard
1003
1004 Then, a preprocessor state can be created as:
1005 \layout LyX-Code
1006
1007 SpeexPreprocessState *state = speex_preprocess_state_init(frame_size, sampling_r
1008 ate);
1009 \layout Standard
1010
1011 It is recommended to use the same value for 
1012 \emph on 
1013 frame_size
1014 \emph default 
1015  as is used by the encoder (20 
1016 \emph on 
1017 ms
1018 \emph default 
1019 ).
1020 \layout Subsection
1021
1022 Codec Options (speex_*_ctl)
1023 \layout Standard
1024
1025 The Speex encoder and decoder support many options and requests that can
1026  be accessed through the 
1027 \emph on 
1028 speex_encoder_ctl
1029 \emph default 
1030  and 
1031 \emph on 
1032 speex_decoder_ctl
1033 \emph default 
1034  functions.
1035  These functions are similar to the 
1036 \emph on 
1037 ioctl
1038 \emph default 
1039  system call and their prototypes are:
1040 \layout LyX-Code
1041
1042 void speex_encoder_ctl(void *encoder, int request, void *ptr);
1043 \layout LyX-Code
1044
1045 void speex_decoder_ctl(void *encoder, int request, void *ptr);
1046 \layout Standard
1047
1048 The different values of request allowed are (note that some only apply to
1049  the encoder or the decoder):
1050 \layout Description
1051
1052 SPEEX_SET_ENH** Set perceptual enhancer
1053 \begin_inset LatexCommand \index{perceptual enhancement}
1054
1055 \end_inset 
1056
1057  to on (1) or off (0) (integer)
1058 \layout Description
1059
1060 SPEEX_GET_ENH** Get perceptual enhancer status (integer)
1061 \layout Description
1062
1063 SPEEX_GET_FRAME_SIZE Get the frame size used for the current mode (integer)
1064 \layout Description
1065
1066 SPEEX_SET_QUALITY* Set the encoder speech quality (integer 0 to 10)
1067 \layout Description
1068
1069 SPEEX_GET_QUALITY* Get the current encoder speech quality (integer 0 to
1070  10)
1071 \layout Description
1072
1073 SPEEX_SET_MODE*
1074 \begin_inset Formula $\dagger$
1075 \end_inset 
1076
1077
1078 \layout Description
1079
1080 SPEEX_GET_MODE*
1081 \begin_inset Formula $\dagger$
1082 \end_inset 
1083
1084
1085 \layout Description
1086
1087 SPEEX_SET_LOW_MODE*
1088 \begin_inset Formula $\dagger$
1089 \end_inset 
1090
1091
1092 \layout Description
1093
1094 SPEEX_GET_LOW_MODE*
1095 \begin_inset Formula $\dagger$
1096 \end_inset 
1097
1098
1099 \layout Description
1100
1101 SPEEX_SET_HIGH_MODE*
1102 \begin_inset Formula $\dagger$
1103 \end_inset 
1104
1105
1106 \layout Description
1107
1108 SPEEX_GET_HIGH_MODE*
1109 \begin_inset Formula $\dagger$
1110 \end_inset 
1111
1112
1113 \layout Description
1114
1115 SPEEX_SET_VBR* Set variable bit-rate (VBR) to on (1) or off (0) (integer)
1116 \layout Description
1117
1118 SPEEX_GET_VBR* Get variable bit-rate
1119 \begin_inset LatexCommand \index{variable bit-rate}
1120
1121 \end_inset 
1122
1123  (VBR) status (integer)
1124 \layout Description
1125
1126 SPEEX_SET_VBR_QUALITY* Set the encoder VBR speech quality (float 0 to 10)
1127 \layout Description
1128
1129 SPEEX_GET_VBR_QUALITY* Get the current encoder VBR speech quality (float
1130  0 to 10)
1131 \layout Description
1132
1133 SPEEX_SET_COMPLEXITY* Set the CPU resources allowed for the encoder (integer
1134  1 to 10)
1135 \layout Description
1136
1137 SPEEX_GET_COMPLEXITY* Get the CPU resources allowed for the encoder (integer
1138  1 to 10)
1139 \layout Description
1140
1141 SPEEX_SET_BITRATE* Set the bit-rate to use to the closest value not exceeding
1142  the parameter (integer in bps)
1143 \layout Description
1144
1145 SPEEX_GET_BITRATE Get the current bit-rate in use (integer in bps)
1146 \layout Description
1147
1148 SPEEX_SET_SAMPLING_RATE Set real sampling rate (integer in Hz)
1149 \layout Description
1150
1151 SPEEX_GET_SAMPLING_RATE Get real sampling rate (integer in Hz)
1152 \layout Description
1153
1154 SPEEX_RESET_STATE Reset the encoder/decoder state to its original state
1155  (zeros all memories)
1156 \layout Description
1157
1158 SPEEX_SET_VAD* Set voice activity detection
1159 \begin_inset LatexCommand \index{voice activity detection}
1160
1161 \end_inset 
1162
1163  (VAD) to on (1) or off (0) (integer)
1164 \layout Description
1165
1166 SPEEX_GET_VAD* Get voice activity detection (VAD) status (integer)
1167 \layout Description
1168
1169 SPEEX_SET_DTX* Set discontinuous transmission
1170 \begin_inset LatexCommand \index{discontinuous transmission}
1171
1172 \end_inset 
1173
1174  (DTX) to on (1) or off (0) (integer)
1175 \layout Description
1176
1177 SPEEX_GET_DTX* Get discontinuous transmission (DTX) status (integer)
1178 \layout Description
1179
1180 SPEEX_SET_ABR* Set average bit-rate
1181 \begin_inset LatexCommand \index{average bit-rate}
1182
1183 \end_inset 
1184
1185  (ABR) to a value n in bits per second (integer in bps)
1186 \layout Description
1187
1188 SPEEX_GET_ABR* Get average bit-rate (ABR) setting (integer in bps)
1189 \layout Description
1190
1191 * applies only to the encoder
1192 \layout Description
1193
1194 ** applies only to the decoder
1195 \layout Description
1196
1197
1198 \begin_inset Formula $\dagger$
1199 \end_inset 
1200
1201  normally only used internally
1202 \layout Subsection
1203
1204 Mode queries
1205 \layout Standard
1206
1207 Speex modes have a query system similar to the speex_encoder_ctl and speex_decod
1208 er_ctl calls.
1209  Since modes are read-only, it is only possible to get information about
1210  a particular mode.
1211  The function used to do that is:
1212 \layout LyX-Code
1213
1214 void speex_mode_query(SpeexMode *mode, int request, void *ptr);
1215 \layout Standard
1216
1217 The admissible values for request are (unless otherwise note, the values
1218  are returned through 
1219 \emph on 
1220 ptr
1221 \emph default 
1222 ):
1223 \layout Description
1224
1225 SPEEX_MODE_FRAME_SIZE Get the frame size (in samples) for the mode
1226 \layout Description
1227
1228 SPEEX_SUBMODE_BITRATE Get the bit-rate for a submode number specified through
1229  
1230 \emph on 
1231 ptr
1232 \emph default 
1233  (integer in bps).
1234  
1235 \layout Subsection
1236
1237 Packing and in-band signalling
1238 \begin_inset LatexCommand \index{in-band signalling}
1239
1240 \end_inset 
1241
1242
1243 \layout Standard
1244
1245 Sometimes it is desirable to pack more than one frame per packet (or other
1246  basic unit of storage).
1247  The proper way to do it is to call speex_encode 
1248 \begin_inset Formula $N$
1249 \end_inset 
1250
1251  times before writing the stream with speex_bits_write.
1252  In cases where the number of frames is not determined by an out-of-band
1253  mechanism, it is possible to include a terminator code.
1254  That terminator consists of the code 15 (decimal) encoded with 5 bits,
1255  as shown in figure 
1256 \begin_inset LatexCommand \ref{cap:quality_vs_bps}
1257
1258 \end_inset 
1259
1260 .
1261  Note that as of version 1.0.2, calling speex_bits_write automatically inserts
1262  the terminator so as to fill the last byte.
1263  This doesn't involves any overhead and makes sure Speex can always detect
1264  when there is no more frame in a packet.
1265 \layout Standard
1266
1267 It is also possible to send in-band 
1268 \begin_inset Quotes eld
1269 \end_inset 
1270
1271 messages
1272 \begin_inset Quotes erd
1273 \end_inset 
1274
1275  to the other side.
1276  All these messages are encoded as 
1277 \begin_inset Quotes eld
1278 \end_inset 
1279
1280 pseudo-frames
1281 \begin_inset Quotes erd
1282 \end_inset 
1283
1284  of mode 14 which contain a 4-bit message type code, followed by the message.
1285  Table 
1286 \begin_inset LatexCommand \ref{cap:In-band-signalling-codes}
1287
1288 \end_inset 
1289
1290  lists the available codes, their meaning and the size of the message that
1291  follows.
1292  Most of these messages are requests that are sent to the encoder or decoder
1293  on the other end, which is free to comply or ignore them.
1294  By default, all in-band messages are ignored.
1295 \layout Standard
1296
1297
1298 \begin_inset Float table
1299 placement htbp
1300 wide false
1301 collapsed false
1302
1303 \layout Standard
1304
1305
1306 \begin_inset  Tabular
1307 <lyxtabular version="3" rows="17" columns="3">
1308 <features>
1309 <column alignment="center" valignment="top" leftline="true" width="0pt">
1310 <column alignment="center" valignment="top" leftline="true" width="0pt">
1311 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
1312 <row topline="true" bottomline="true">
1313 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1314 \begin_inset Text
1315
1316 \layout Standard
1317
1318 Code
1319 \end_inset 
1320 </cell>
1321 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1322 \begin_inset Text
1323
1324 \layout Standard
1325
1326 Size (bits)
1327 \end_inset 
1328 </cell>
1329 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1330 \begin_inset Text
1331
1332 \layout Standard
1333
1334 Content
1335 \end_inset 
1336 </cell>
1337 </row>
1338 <row topline="true">
1339 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1340 \begin_inset Text
1341
1342 \layout Standard
1343
1344 0
1345 \end_inset 
1346 </cell>
1347 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1348 \begin_inset Text
1349
1350 \layout Standard
1351
1352 1
1353 \end_inset 
1354 </cell>
1355 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1356 \begin_inset Text
1357
1358 \layout Standard
1359
1360 Asks decoder to set perceptual enhancement off (0) or on(1)
1361 \end_inset 
1362 </cell>
1363 </row>
1364 <row topline="true">
1365 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1366 \begin_inset Text
1367
1368 \layout Standard
1369
1370 1
1371 \end_inset 
1372 </cell>
1373 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1374 \begin_inset Text
1375
1376 \layout Standard
1377
1378 1
1379 \end_inset 
1380 </cell>
1381 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1382 \begin_inset Text
1383
1384 \layout Standard
1385
1386 Asks (if 1) the encoder to be less 
1387 \begin_inset Quotes eld
1388 \end_inset 
1389
1390 agressive
1391 \begin_inset Quotes erd
1392 \end_inset 
1393
1394  due to high packet loss
1395 \end_inset 
1396 </cell>
1397 </row>
1398 <row topline="true">
1399 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1400 \begin_inset Text
1401
1402 \layout Standard
1403
1404 2
1405 \end_inset 
1406 </cell>
1407 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1408 \begin_inset Text
1409
1410 \layout Standard
1411
1412 4
1413 \end_inset 
1414 </cell>
1415 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1416 \begin_inset Text
1417
1418 \layout Standard
1419
1420 Asks encoder to switch to mode N
1421 \end_inset 
1422 </cell>
1423 </row>
1424 <row topline="true">
1425 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1426 \begin_inset Text
1427
1428 \layout Standard
1429
1430 3
1431 \end_inset 
1432 </cell>
1433 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1434 \begin_inset Text
1435
1436 \layout Standard
1437
1438 4
1439 \end_inset 
1440 </cell>
1441 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1442 \begin_inset Text
1443
1444 \layout Standard
1445
1446 Asks encoder to switch to mode N for low-band
1447 \end_inset 
1448 </cell>
1449 </row>
1450 <row topline="true">
1451 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1452 \begin_inset Text
1453
1454 \layout Standard
1455
1456 4
1457 \end_inset 
1458 </cell>
1459 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1460 \begin_inset Text
1461
1462 \layout Standard
1463
1464 4
1465 \end_inset 
1466 </cell>
1467 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1468 \begin_inset Text
1469
1470 \layout Standard
1471
1472 Asks encoder to switch to mode N for high-band
1473 \end_inset 
1474 </cell>
1475 </row>
1476 <row topline="true">
1477 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1478 \begin_inset Text
1479
1480 \layout Standard
1481
1482 5
1483 \end_inset 
1484 </cell>
1485 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1486 \begin_inset Text
1487
1488 \layout Standard
1489
1490 4
1491 \end_inset 
1492 </cell>
1493 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1494 \begin_inset Text
1495
1496 \layout Standard
1497
1498 Asks encoder to switch to quality N for VBR
1499 \end_inset 
1500 </cell>
1501 </row>
1502 <row topline="true">
1503 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1504 \begin_inset Text
1505
1506 \layout Standard
1507
1508 6
1509 \end_inset 
1510 </cell>
1511 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1512 \begin_inset Text
1513
1514 \layout Standard
1515
1516 4
1517 \end_inset 
1518 </cell>
1519 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1520 \begin_inset Text
1521
1522 \layout Standard
1523
1524 Request acknowloedge (0=no, 1=all, 2=only for in-band data)
1525 \end_inset 
1526 </cell>
1527 </row>
1528 <row topline="true">
1529 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1530 \begin_inset Text
1531
1532 \layout Standard
1533
1534 7
1535 \end_inset 
1536 </cell>
1537 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1538 \begin_inset Text
1539
1540 \layout Standard
1541
1542 4
1543 \end_inset 
1544 </cell>
1545 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1546 \begin_inset Text
1547
1548 \layout Standard
1549
1550 Asks encoder to set CBR (0), VAD(1), DTX(3), VBR(5), VBR+DTX(7)
1551 \end_inset 
1552 </cell>
1553 </row>
1554 <row topline="true">
1555 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1556 \begin_inset Text
1557
1558 \layout Standard
1559
1560 8
1561 \end_inset 
1562 </cell>
1563 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1564 \begin_inset Text
1565
1566 \layout Standard
1567
1568 8
1569 \end_inset 
1570 </cell>
1571 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1572 \begin_inset Text
1573
1574 \layout Standard
1575
1576 Transmit (8-bit) character to the other end
1577 \end_inset 
1578 </cell>
1579 </row>
1580 <row topline="true">
1581 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1582 \begin_inset Text
1583
1584 \layout Standard
1585
1586 9
1587 \end_inset 
1588 </cell>
1589 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1590 \begin_inset Text
1591
1592 \layout Standard
1593
1594 8
1595 \end_inset 
1596 </cell>
1597 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1598 \begin_inset Text
1599
1600 \layout Standard
1601
1602 Intensity stereo information
1603 \end_inset 
1604 </cell>
1605 </row>
1606 <row topline="true">
1607 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1608 \begin_inset Text
1609
1610 \layout Standard
1611
1612 10
1613 \end_inset 
1614 </cell>
1615 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1616 \begin_inset Text
1617
1618 \layout Standard
1619
1620 16
1621 \end_inset 
1622 </cell>
1623 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1624 \begin_inset Text
1625
1626 \layout Standard
1627
1628 Announce maximum bit-rate acceptable (N in bytes/second)
1629 \end_inset 
1630 </cell>
1631 </row>
1632 <row topline="true">
1633 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1634 \begin_inset Text
1635
1636 \layout Standard
1637
1638 11
1639 \end_inset 
1640 </cell>
1641 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1642 \begin_inset Text
1643
1644 \layout Standard
1645
1646 16
1647 \end_inset 
1648 </cell>
1649 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1650 \begin_inset Text
1651
1652 \layout Standard
1653
1654 reserved
1655 \end_inset 
1656 </cell>
1657 </row>
1658 <row topline="true">
1659 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1660 \begin_inset Text
1661
1662 \layout Standard
1663
1664 12
1665 \end_inset 
1666 </cell>
1667 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1668 \begin_inset Text
1669
1670 \layout Standard
1671
1672 32
1673 \end_inset 
1674 </cell>
1675 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1676 \begin_inset Text
1677
1678 \layout Standard
1679
1680 Acknowledge receiving packet N
1681 \end_inset 
1682 </cell>
1683 </row>
1684 <row topline="true">
1685 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1686 \begin_inset Text
1687
1688 \layout Standard
1689
1690 13
1691 \end_inset 
1692 </cell>
1693 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1694 \begin_inset Text
1695
1696 \layout Standard
1697
1698 32
1699 \end_inset 
1700 </cell>
1701 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1702 \begin_inset Text
1703
1704 \layout Standard
1705
1706 reserved
1707 \end_inset 
1708 </cell>
1709 </row>
1710 <row topline="true">
1711 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1712 \begin_inset Text
1713
1714 \layout Standard
1715
1716 14
1717 \end_inset 
1718 </cell>
1719 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1720 \begin_inset Text
1721
1722 \layout Standard
1723
1724 64
1725 \end_inset 
1726 </cell>
1727 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1728 \begin_inset Text
1729
1730 \layout Standard
1731
1732 reserved
1733 \end_inset 
1734 </cell>
1735 </row>
1736 <row topline="true" bottomline="true">
1737 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1738 \begin_inset Text
1739
1740 \layout Standard
1741
1742 15
1743 \end_inset 
1744 </cell>
1745 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1746 \begin_inset Text
1747
1748 \layout Standard
1749
1750 64
1751 \end_inset 
1752 </cell>
1753 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1754 \begin_inset Text
1755
1756 \layout Standard
1757
1758 reserved
1759 \end_inset 
1760 </cell>
1761 </row>
1762 </lyxtabular>
1763
1764 \end_inset 
1765
1766
1767 \layout Caption
1768
1769 In-band signalling codes
1770 \begin_inset LatexCommand \label{cap:In-band-signalling-codes}
1771
1772 \end_inset 
1773
1774
1775 \end_inset 
1776
1777
1778 \layout Standard
1779
1780 Finally, applications may define custom in-band messages using mode 13.
1781  The size of the message in bytes is encoded with 5 bits, so that the decoder
1782  can skip it if it doesn't know how to interpret it.
1783 \layout Section
1784 \pagebreak_top 
1785 Formats and standards
1786 \begin_inset LatexCommand \index{standards}
1787
1788 \end_inset 
1789
1790
1791 \begin_inset LatexCommand \label{sec:Formats-and-standards}
1792
1793 \end_inset 
1794
1795
1796 \layout Standard
1797
1798 Speex can encode speech in both narrowband and wideband and provides different
1799  bit-rates.
1800  However, not all features need to be supported by a certain implementation
1801  or device.
1802  In order to be called 
1803 \begin_inset Quotes eld
1804 \end_inset 
1805
1806 Speex compatible
1807 \begin_inset Quotes erd
1808 \end_inset 
1809
1810  (whatever that means), an implementation must implement at least a basic
1811  set of features.
1812 \layout Standard
1813
1814 At the minimum, all narrowband modes of operation MUST be supported at the
1815  decoder.
1816  This includes the decoding of a wideband bit-stream by the narrowband decoder
1817 \begin_inset Foot
1818 collapsed true
1819
1820 \layout Standard
1821
1822 The wideband bit-stream contains an embedded narrowband bit-stream which
1823  can be decoded alone
1824 \end_inset 
1825
1826 .
1827  If present, a wideband decoder MUST be able to decode a narrowband stream,
1828  and MAY either be able to decode all wideband modes or be able to decode
1829  the embedded narrowband part of all modes (which includes ignoring the
1830  high-band bits).
1831 \layout Standard
1832
1833 For encoders, at least one narrowband or wideband mode MUST be supported.
1834  The main reason why all encoding modes do not have to be supported is that
1835  some platforms may not be able to handle the complexity of encoding in
1836  some modes.
1837 \layout Subsection
1838
1839 RTP
1840 \begin_inset LatexCommand \index{RTP}
1841
1842 \end_inset 
1843
1844  Payload Format 
1845 \layout Standard
1846
1847 The RTP payload draft is included in appendix 
1848 \begin_inset LatexCommand \ref{sec:IETF-draft}
1849
1850 \end_inset 
1851
1852  and the latest version is available at 
1853 \begin_inset LatexCommand \url{http://www.speex.org/drafts/latest}
1854
1855 \end_inset 
1856
1857 .
1858  This draft has been sent (2003/02/26) to the Internet Engineering Task
1859  Force (IETF) and will be discussed at the March 18th meeting in San Francisco.
1860  
1861 \layout Subsection
1862
1863 MIME Type
1864 \layout Standard
1865
1866 For now, you should use the MIME type audio/x-speex for Speex-in-Ogg.
1867  We will apply for type 
1868 \family typewriter 
1869 audio/speex
1870 \family default 
1871  in the near future.
1872 \layout Subsection
1873
1874 Ogg
1875 \begin_inset LatexCommand \index{Ogg}
1876
1877 \end_inset 
1878
1879  file format
1880 \layout Standard
1881
1882 Speex bit-streams can be stored in Ogg files.
1883  In this case, the first packet of the Ogg file contains the Speex header
1884  described in table 
1885 \begin_inset LatexCommand \ref{cap:ogg_speex_header}
1886
1887 \end_inset 
1888
1889 .
1890  All integer fields in the headers are stored as little-endian.
1891  The 
1892 \family typewriter 
1893 speex_string
1894 \family default 
1895  field must contain the 
1896 \begin_inset Quotes eld
1897 \end_inset 
1898
1899
1900 \family typewriter 
1901 Speex
1902 \family default 
1903 \SpecialChar ~
1904 \SpecialChar ~
1905 \SpecialChar ~
1906
1907 \begin_inset Quotes erd
1908 \end_inset 
1909
1910  (with 3 trailing spaces), which identifies the bit-stream.
1911  The next field, 
1912 \family typewriter 
1913 speex_version
1914 \family default 
1915  contains the version of Speex that encoded the file.
1916  For now, refer to speex_header.[ch] for more info.
1917  The 
1918 \emph on 
1919 beginning of stream
1920 \emph default 
1921  (
1922 \family typewriter 
1923 b_o_s
1924 \family default 
1925 ) flag is set to 1 for the header.
1926  The header packet has 
1927 \family typewriter 
1928 packetno=0
1929 \family default 
1930  and 
1931 \family typewriter 
1932 granulepos=0
1933 \family default 
1934 .
1935 \layout Standard
1936
1937 The second packet contains the Speex comment header.
1938  The format used is the Vorbis comment format described here: http://www.xiph.org/
1939 ogg/vorbis/doc/v-comment.html .
1940  This packet has 
1941 \family typewriter 
1942 packetno=1
1943 \family default 
1944  and 
1945 \family typewriter 
1946 granulepos=0
1947 \family default 
1948 .
1949 \layout Standard
1950
1951 The third and subsequent packets each contain one or more (number found
1952  in header) Speex frames.
1953  These are identified with 
1954 \family typewriter 
1955 packetno
1956 \family default 
1957  starting from 2 and the 
1958 \family typewriter 
1959 granulepos
1960 \family default 
1961  is the number of the last sample encoded in that packet.
1962  The last of these packets has the 
1963 \emph on 
1964 end of stream
1965 \emph default 
1966  (
1967 \family typewriter 
1968 e_o_s
1969 \family default 
1970 ) flag is set to 1.
1971 \layout Standard
1972
1973
1974 \begin_inset Float table
1975 placement htbp
1976 wide true
1977 collapsed false
1978
1979 \layout Standard
1980
1981
1982 \begin_inset  Tabular
1983 <lyxtabular version="3" rows="16" columns="3">
1984 <features>
1985 <column alignment="center" valignment="top" leftline="true" width="0pt">
1986 <column alignment="center" valignment="top" leftline="true" width="0pt">
1987 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
1988 <row topline="true" bottomline="true">
1989 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1990 \begin_inset Text
1991
1992 \layout Standard
1993
1994 Field
1995 \end_inset 
1996 </cell>
1997 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1998 \begin_inset Text
1999
2000 \layout Standard
2001
2002 Type
2003 \end_inset 
2004 </cell>
2005 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2006 \begin_inset Text
2007
2008 \layout Standard
2009
2010 Size
2011 \end_inset 
2012 </cell>
2013 </row>
2014 <row topline="true">
2015 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2016 \begin_inset Text
2017
2018 \layout Standard
2019
2020 speex_string
2021 \end_inset 
2022 </cell>
2023 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2024 \begin_inset Text
2025
2026 \layout Standard
2027
2028 char[]
2029 \end_inset 
2030 </cell>
2031 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2032 \begin_inset Text
2033
2034 \layout Standard
2035
2036 8
2037 \end_inset 
2038 </cell>
2039 </row>
2040 <row topline="true">
2041 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2042 \begin_inset Text
2043
2044 \layout Standard
2045
2046 speex_version
2047 \end_inset 
2048 </cell>
2049 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2050 \begin_inset Text
2051
2052 \layout Standard
2053
2054 char[]
2055 \end_inset 
2056 </cell>
2057 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2058 \begin_inset Text
2059
2060 \layout Standard
2061
2062 20
2063 \end_inset 
2064 </cell>
2065 </row>
2066 <row topline="true">
2067 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2068 \begin_inset Text
2069
2070 \layout Standard
2071
2072 speex_version_id
2073 \end_inset 
2074 </cell>
2075 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2076 \begin_inset Text
2077
2078 \layout Standard
2079
2080 int
2081 \end_inset 
2082 </cell>
2083 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2084 \begin_inset Text
2085
2086 \layout Standard
2087
2088 4
2089 \end_inset 
2090 </cell>
2091 </row>
2092 <row topline="true">
2093 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2094 \begin_inset Text
2095
2096 \layout Standard
2097
2098 header_size
2099 \end_inset 
2100 </cell>
2101 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2102 \begin_inset Text
2103
2104 \layout Standard
2105
2106 int
2107 \end_inset 
2108 </cell>
2109 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2110 \begin_inset Text
2111
2112 \layout Standard
2113
2114 4
2115 \end_inset 
2116 </cell>
2117 </row>
2118 <row topline="true">
2119 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2120 \begin_inset Text
2121
2122 \layout Standard
2123
2124 rate
2125 \end_inset 
2126 </cell>
2127 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2128 \begin_inset Text
2129
2130 \layout Standard
2131
2132 int
2133 \end_inset 
2134 </cell>
2135 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2136 \begin_inset Text
2137
2138 \layout Standard
2139
2140 4
2141 \end_inset 
2142 </cell>
2143 </row>
2144 <row topline="true">
2145 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2146 \begin_inset Text
2147
2148 \layout Standard
2149
2150 mode
2151 \end_inset 
2152 </cell>
2153 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2154 \begin_inset Text
2155
2156 \layout Standard
2157
2158 int
2159 \end_inset 
2160 </cell>
2161 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2162 \begin_inset Text
2163
2164 \layout Standard
2165
2166 4
2167 \end_inset 
2168 </cell>
2169 </row>
2170 <row topline="true">
2171 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2172 \begin_inset Text
2173
2174 \layout Standard
2175
2176 mode_bitstream_version
2177 \end_inset 
2178 </cell>
2179 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2180 \begin_inset Text
2181
2182 \layout Standard
2183
2184 int
2185 \end_inset 
2186 </cell>
2187 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2188 \begin_inset Text
2189
2190 \layout Standard
2191
2192 4
2193 \end_inset 
2194 </cell>
2195 </row>
2196 <row topline="true">
2197 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2198 \begin_inset Text
2199
2200 \layout Standard
2201
2202 nb_channels
2203 \end_inset 
2204 </cell>
2205 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2206 \begin_inset Text
2207
2208 \layout Standard
2209
2210 int
2211 \end_inset 
2212 </cell>
2213 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2214 \begin_inset Text
2215
2216 \layout Standard
2217
2218 4
2219 \end_inset 
2220 </cell>
2221 </row>
2222 <row topline="true">
2223 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2224 \begin_inset Text
2225
2226 \layout Standard
2227
2228 bitrate
2229 \end_inset 
2230 </cell>
2231 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2232 \begin_inset Text
2233
2234 \layout Standard
2235
2236 int
2237 \end_inset 
2238 </cell>
2239 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2240 \begin_inset Text
2241
2242 \layout Standard
2243
2244 4
2245 \end_inset 
2246 </cell>
2247 </row>
2248 <row topline="true">
2249 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2250 \begin_inset Text
2251
2252 \layout Standard
2253
2254 frame_size
2255 \end_inset 
2256 </cell>
2257 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2258 \begin_inset Text
2259
2260 \layout Standard
2261
2262 int
2263 \end_inset 
2264 </cell>
2265 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2266 \begin_inset Text
2267
2268 \layout Standard
2269
2270 4
2271 \end_inset 
2272 </cell>
2273 </row>
2274 <row topline="true">
2275 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2276 \begin_inset Text
2277
2278 \layout Standard
2279
2280 vbr
2281 \end_inset 
2282 </cell>
2283 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2284 \begin_inset Text
2285
2286 \layout Standard
2287
2288 int
2289 \end_inset 
2290 </cell>
2291 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2292 \begin_inset Text
2293
2294 \layout Standard
2295
2296 4
2297 \end_inset 
2298 </cell>
2299 </row>
2300 <row topline="true">
2301 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2302 \begin_inset Text
2303
2304 \layout Standard
2305
2306 frames_per_packet
2307 \end_inset 
2308 </cell>
2309 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2310 \begin_inset Text
2311
2312 \layout Standard
2313
2314 int
2315 \end_inset 
2316 </cell>
2317 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2318 \begin_inset Text
2319
2320 \layout Standard
2321
2322 4
2323 \end_inset 
2324 </cell>
2325 </row>
2326 <row topline="true">
2327 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2328 \begin_inset Text
2329
2330 \layout Standard
2331
2332 extra_headers
2333 \end_inset 
2334 </cell>
2335 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2336 \begin_inset Text
2337
2338 \layout Standard
2339
2340 int
2341 \end_inset 
2342 </cell>
2343 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2344 \begin_inset Text
2345
2346 \layout Standard
2347
2348 4
2349 \end_inset 
2350 </cell>
2351 </row>
2352 <row topline="true">
2353 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2354 \begin_inset Text
2355
2356 \layout Standard
2357
2358 reserved1
2359 \end_inset 
2360 </cell>
2361 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2362 \begin_inset Text
2363
2364 \layout Standard
2365
2366 int
2367 \end_inset 
2368 </cell>
2369 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2370 \begin_inset Text
2371
2372 \layout Standard
2373
2374 4
2375 \end_inset 
2376 </cell>
2377 </row>
2378 <row topline="true" bottomline="true">
2379 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2380 \begin_inset Text
2381
2382 \layout Standard
2383
2384 reserved2
2385 \end_inset 
2386 </cell>
2387 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2388 \begin_inset Text
2389
2390 \layout Standard
2391
2392 int
2393 \end_inset 
2394 </cell>
2395 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2396 \begin_inset Text
2397
2398 \layout Standard
2399
2400 4
2401 \end_inset 
2402 </cell>
2403 </row>
2404 </lyxtabular>
2405
2406 \end_inset 
2407
2408
2409 \layout Caption
2410
2411 Ogg/Speex header packet
2412 \begin_inset LatexCommand \label{cap:ogg_speex_header}
2413
2414 \end_inset 
2415
2416
2417 \end_inset 
2418
2419
2420 \layout Section
2421 \pagebreak_top 
2422 Introduction to CELP Coding
2423 \begin_inset LatexCommand \index{CELP}
2424
2425 \end_inset 
2426
2427
2428 \begin_inset LatexCommand \label{sec:Introduction-to-CELP}
2429
2430 \end_inset 
2431
2432
2433 \layout Standard
2434
2435 Speex is based on CELP, which stands for Code Excited Linear Prediction.
2436  This section attempts to introduce the principles behind CELP, so if you
2437  are already familiar with CELP, you can safely skip to section 
2438 \begin_inset LatexCommand \ref{sec:Speex-narrowband-mode}
2439
2440 \end_inset 
2441
2442 .
2443  The CELP technique is based on three ideas:
2444 \layout Enumerate
2445
2446 The use of a linear prediction (LP) model to model the vocal tract
2447 \layout Enumerate
2448
2449 The use of (adaptive and fixed) codebook entries as input (excitation) of
2450  the LP model
2451 \layout Enumerate
2452
2453 The search performed in closed-loop in a 
2454 \begin_inset Quotes eld
2455 \end_inset 
2456
2457 perceptually weighted domain
2458 \begin_inset Quotes erd
2459 \end_inset 
2460
2461
2462 \layout Standard
2463
2464 This section describes the basic ideas behind CELP.
2465  Note that it's still incomplete.
2466 \layout Subsection
2467
2468 Linear Prediction (LPC)
2469 \begin_inset LatexCommand \index{linear prediction}
2470
2471 \end_inset 
2472
2473
2474 \layout Standard
2475
2476 Linear prediction is at the base of many speech coding techniques, including
2477  CELP.
2478  The idea behind it is to predict the signal 
2479 \begin_inset Formula $x[n]$
2480 \end_inset 
2481
2482  using a linear combination of its past samples:
2483 \layout Standard
2484
2485
2486 \begin_inset Formula \[
2487 y[n]=\sum_{i=1}^{N}a_{i}x[n-i]\]
2488
2489 \end_inset 
2490
2491 where 
2492 \begin_inset Formula $y[n]$
2493 \end_inset 
2494
2495  is the linear prediction of 
2496 \begin_inset Formula $x[n]$
2497 \end_inset 
2498
2499 .
2500  The prediction error is thus given by:
2501 \begin_inset Formula \[
2502 e[n]=x[n]-y[n]=x[n]-\sum_{i=1}^{N}a_{i}x[n-i]\]
2503
2504 \end_inset 
2505
2506
2507 \layout Standard
2508
2509 The goal of the LPC analysis is to find the best prediction coefficients
2510  
2511 \begin_inset Formula $a_{i}$
2512 \end_inset 
2513
2514  which minimize the quadratic error function:
2515 \begin_inset Formula \[
2516 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}\]
2517
2518 \end_inset 
2519
2520 That can be done by making all derivatives 
2521 \begin_inset Formula $\frac{\partial E}{\partial a_{i}}$
2522 \end_inset 
2523
2524  equal to zero:
2525 \begin_inset Formula \[
2526 \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\]
2527
2528 \end_inset 
2529
2530
2531 \layout Standard
2532
2533 The 
2534 \begin_inset Formula $a_{i}$
2535 \end_inset 
2536
2537  filter coefficients are computed using the Levinson-Durbin
2538 \begin_inset LatexCommand \index{Levinson-Durbin}
2539
2540 \end_inset 
2541
2542  algorithm, which starts from the auto-correlation
2543 \begin_inset LatexCommand \index{auto-correlation}
2544
2545 \end_inset 
2546
2547  
2548 \begin_inset Formula $R(m)$
2549 \end_inset 
2550
2551  of the signal 
2552 \begin_inset Formula $x[n]$
2553 \end_inset 
2554
2555 .
2556 \layout Standard
2557
2558
2559 \begin_inset Formula \[
2560 R(m)=\sum_{i=0}^{N-1}x[i]x[i-m]\]
2561
2562 \end_inset 
2563
2564
2565 \layout Standard
2566
2567 For an order 
2568 \begin_inset Formula $N$
2569 \end_inset 
2570
2571  filter, we have:
2572 \begin_inset Formula \[
2573 \mathbf{R}=\left[\begin{array}{cccc}
2574 R(0) & R(1) & \cdots & R(N-1)\\
2575 R(1) & R(0) & \cdots & R(N-2)\\
2576 \vdots & \vdots & \ddots & \vdots\\
2577 R(N-1) & R(N-2) & \cdots & R(0)\end{array}\right]\]
2578
2579 \end_inset 
2580
2581
2582 \begin_inset Formula \[
2583 \mathbf{r}=\left[\begin{array}{c}
2584 R(1)\\
2585 R(2)\\
2586 \vdots\\
2587 R(N)\end{array}\right]\]
2588
2589 \end_inset 
2590
2591
2592 \layout Standard
2593
2594 The filter coefficients 
2595 \begin_inset Formula $a_{i}$
2596 \end_inset 
2597
2598  are found by solving the system 
2599 \begin_inset Formula $\mathbf{Ra}=\mathbf{r}$
2600 \end_inset 
2601
2602 .
2603  What the Levinson-Durbin algorithm does here is making the solution to
2604  the problem 
2605 \begin_inset Formula $\mathcal{O}\left(N^{2}\right)$
2606 \end_inset 
2607
2608  instead of 
2609 \begin_inset Formula $\mathcal{O}\left(N^{3}\right)$
2610 \end_inset 
2611
2612  by exploiting the fact that matrix 
2613 \begin_inset Formula $\mathbf{R}$
2614 \end_inset 
2615
2616  is toeplitz hermitian.
2617  Also, it can be proven that all the roots of 
2618 \begin_inset Formula $A(z)$
2619 \end_inset 
2620
2621  are within the unit circle, which means that 
2622 \begin_inset Formula $1/A(z)$
2623 \end_inset 
2624
2625  is always stable.
2626  This is in theory; in practice because of finite precision, there are two
2627  commonly used techniques to make sure we have a stable filter.
2628  First, we multiply 
2629 \begin_inset Formula $R(0)$
2630 \end_inset 
2631
2632  by a number slightly above one (such as 1.0001), which is equivalent to
2633  adding noise to the signal.
2634  Also, we can apply a window to the auto-correlation, which is equivalent
2635  to filtering in the frequency domain, reducing sharp resonances.
2636 \layout Standard
2637
2638 The linear prediction model represents each speech sample as a linear combinatio
2639 n of past samples, plus an error signal called the excitation (or residual).
2640 \begin_inset Formula \[
2641 x[n]=\sum_{i=1}^{N}a_{i}x[n-i]+e[n]\]
2642
2643 \end_inset 
2644
2645
2646 \layout Standard
2647
2648 In the 
2649 \emph on 
2650 z
2651 \emph default 
2652 -domain, this can be expressed as
2653 \layout Standard
2654
2655
2656 \begin_inset Formula \[
2657 x(z)=\frac{1}{A(z)}\: e(z)\]
2658
2659 \end_inset 
2660
2661
2662 \layout Standard
2663
2664 where 
2665 \begin_inset Formula $A(z)$
2666 \end_inset 
2667
2668  is defined as
2669 \layout Standard
2670
2671
2672 \begin_inset Formula \[
2673 A(z)=1-\sum_{i=1}^{N}a_{i}z^{-i}\]
2674
2675 \end_inset 
2676
2677
2678 \layout Standard
2679
2680 We usually refer to 
2681 \begin_inset Formula $A(z)$
2682 \end_inset 
2683
2684  as the analysis filter and 
2685 \begin_inset Formula $1/A(z)$
2686 \end_inset 
2687
2688  as the synthesis filter.
2689  The whole process is called short-term prediction as it predicts the signal
2690  
2691 \begin_inset Formula $x[n]$
2692 \end_inset 
2693
2694  using a prediction using only the 
2695 \begin_inset Formula $N$
2696 \end_inset 
2697
2698  past samples, where 
2699 \begin_inset Formula $N$
2700 \end_inset 
2701
2702  is usually around 10.
2703 \layout Standard
2704
2705 Because LPC coefficients have very little robustness to quantization, they
2706  are converted to Line Spectral Pair
2707 \begin_inset LatexCommand \index{line spectral pair}
2708
2709 \end_inset 
2710
2711  (LSP) coefficients which have a much better behaviour with quantization,
2712  one of them being that it's easy to keep the filter stable.
2713  
2714 \layout Comment
2715
2716 Describe LSP's
2717 \layout Subsection
2718
2719 Pitch Prediction
2720 \begin_inset LatexCommand \index{pitch}
2721
2722 \end_inset 
2723
2724
2725 \layout Standard
2726
2727 During voiced segments, the speech signal is periodic, so it is possible
2728  to take advantage of that property by approximating the excitation signal
2729  
2730 \begin_inset Formula $e[n]$
2731 \end_inset 
2732
2733  by a gain times the past of the excitation:
2734 \layout Standard
2735
2736
2737 \begin_inset Formula \[
2738 e[n]\simeq p[n]=\beta e[n-T]\]
2739
2740 \end_inset 
2741
2742
2743 \layout Standard
2744
2745 where 
2746 \begin_inset Formula $T$
2747 \end_inset 
2748
2749  is the pitch period, 
2750 \begin_inset Formula $\beta$
2751 \end_inset 
2752
2753  is the pitch gain.
2754  We call that long-term prediction since the excitation is predicted from
2755  
2756 \begin_inset Formula $e[n-T]$
2757 \end_inset 
2758
2759  with 
2760 \begin_inset Formula $T\gg N$
2761 \end_inset 
2762
2763 .
2764 \layout Subsection
2765
2766 Innovation Codebook
2767 \layout Standard
2768
2769 The final excitation 
2770 \begin_inset Formula $e[n]$
2771 \end_inset 
2772
2773  will be the sum of the pitch prediction and an 
2774 \emph on 
2775 innovation
2776 \emph default 
2777  signal 
2778 \begin_inset Formula $c[n]$
2779 \end_inset 
2780
2781  taken from a fixed codebook, hence the name 
2782 \emph on 
2783 Code
2784 \emph default 
2785  Excited Linear Prediction.
2786  The final excitation is given by:
2787 \layout Standard
2788
2789
2790 \begin_inset Formula \[
2791 e[n]=p[n]+c[n]=\beta e[n-T]+c[n]\]
2792
2793 \end_inset 
2794
2795 The quantization of 
2796 \begin_inset Formula $c[n]$
2797 \end_inset 
2798
2799  is where most of the bits in a CELP codec are allocated.
2800  It represents the information that couldn't be obtained either from linear
2801  prediction or pitch prediction.
2802  In the 
2803 \emph on 
2804 z
2805 \emph default 
2806 -domain we can represent the final signal 
2807 \begin_inset Formula $X(z)$
2808 \end_inset 
2809
2810  as 
2811 \begin_inset Formula \[
2812 X(z)=\frac{C(z)}{A(z)\left(1-\beta z^{-T}\right)}\]
2813
2814 \end_inset 
2815
2816
2817 \layout Subsection
2818
2819 Analysis-by-Synthesis and Error Weighting
2820 \begin_inset LatexCommand \index{error weighting}
2821
2822 \end_inset 
2823
2824
2825 \begin_inset LatexCommand \index{analysis-by-synthesis}
2826
2827 \end_inset 
2828
2829
2830 \layout Standard
2831
2832 Most (if not all) modern audio codecs attempt to 
2833 \begin_inset Quotes eld
2834 \end_inset 
2835
2836 shape
2837 \begin_inset Quotes erd
2838 \end_inset 
2839
2840  the noise so that it appears mostly in the frequency regions where the
2841  ear cannot detect it.
2842  For example, the ear is more tolerant to noise in parts of the spectrum
2843  that are louder and 
2844 \emph on 
2845 vice versa
2846 \emph default 
2847 .
2848  That's why instead of minimizing the simple quadratic error
2849 \begin_inset Formula \[
2850 E=\sum_{n}\left(x[n]-\overline{x}[n]\right)^{2}\]
2851
2852 \end_inset 
2853
2854 where 
2855 \begin_inset Formula $\overline{x}[n]$
2856 \end_inset 
2857
2858  is the encoder signal, we minimize the error for the perceptually weighted
2859  signal
2860 \begin_inset Formula \[
2861 X_{w}(z)=W(z)X(z)\]
2862
2863 \end_inset 
2864
2865 where 
2866 \begin_inset Formula $W(z)$
2867 \end_inset 
2868
2869  is the weighting filter, usually of the form
2870 \layout Standard
2871
2872
2873 \begin_inset Formula \begin{equation}
2874 W(z)=\frac{A\left(\frac{z}{\gamma_{1}}\right)}{A\left(\frac{z}{\gamma_{2}}\right)}\label{eq:weighting_filter}\end{equation}
2875
2876 \end_inset 
2877
2878
2879 \layout Standard
2880
2881 with control parameters 
2882 \begin_inset Formula $\gamma_{1}>\gamma_{2}$
2883 \end_inset 
2884
2885 .
2886  If the noise is white in the perceptually weighted domain, then in the
2887  signal domain its spectral shape will be of the form
2888 \begin_inset Formula \[
2889 A_{noise}(z)=\frac{1}{W(z)}=\frac{A\left(\frac{z}{\gamma_{2}}\right)}{A\left(\frac{z}{\gamma_{1}}\right)}\]
2890
2891 \end_inset 
2892
2893
2894 \layout Standard
2895
2896 If a filter 
2897 \begin_inset Formula $A(z)$
2898 \end_inset 
2899
2900  has (complex) poles at 
2901 \begin_inset Formula $p_{i}$
2902 \end_inset 
2903
2904  in the 
2905 \begin_inset Formula $z$
2906 \end_inset 
2907
2908 -plane, the filter 
2909 \begin_inset Formula $A(z/\gamma)$
2910 \end_inset 
2911
2912  will have its poles at 
2913 \begin_inset Formula $p'_{i}=\gamma p_{i}$
2914 \end_inset 
2915
2916 , making it a flatter version of 
2917 \begin_inset Formula $A(z)$
2918 \end_inset 
2919
2920 .
2921 \layout Standard
2922
2923 Analysis-by-synthesis refers to the fact that when trying to find the best
2924  pitch parameters (
2925 \begin_inset Formula $T$
2926 \end_inset 
2927
2928
2929 \begin_inset Formula $\beta$
2930 \end_inset 
2931
2932 ) and innovation signal 
2933 \begin_inset Formula $c[n]$
2934 \end_inset 
2935
2936 , we do not work by making the excitation 
2937 \begin_inset Formula $e[n]$
2938 \end_inset 
2939
2940  as close as the original one (which would be simpler), but apply the synthesis
2941  (and weighting) filter and try making 
2942 \begin_inset Formula $X_{w}(z)$
2943 \end_inset 
2944
2945  as close to the original as possible.
2946 \layout Section
2947 \pagebreak_top 
2948 Speex narrowband mode
2949 \begin_inset LatexCommand \label{sec:Speex-narrowband-mode}
2950
2951 \end_inset 
2952
2953
2954 \begin_inset LatexCommand \index{narrowband}
2955
2956 \end_inset 
2957
2958
2959 \layout Standard
2960
2961 This section looks at how Speex works for narrowband (
2962 \begin_inset Formula $8\:\mathrm{kHz}$
2963 \end_inset 
2964
2965  sampling rate) operation.
2966  The frame size for this mode is 
2967 \begin_inset Formula $20\:\mathrm{ms}$
2968 \end_inset 
2969
2970 , corresponding to 160 samples.
2971  Each frame is also subdivided into 4 sub-frames of 40 samples each.
2972 \layout Standard
2973
2974 Also many design decisions were based on the original goals and assumptions:
2975 \layout Itemize
2976
2977 Minimizing the amount of information extracted from past frames (for robustness
2978  to packet loss)
2979 \layout Itemize
2980
2981 Dynamically-selectable codebooks (LSP, pitch and innovation)
2982 \layout Itemize
2983
2984 sub-vector fixed (innovation) codebooks
2985 \layout Subsection
2986
2987 LPC Analysis
2988 \begin_inset LatexCommand \index{linear prediction}
2989
2990 \end_inset 
2991
2992
2993 \layout Standard
2994
2995 An LPC analysis is first performed on a (asymetric Hamming) window that
2996  spans all of the current frame and half a frame in advance.
2997  The LPC coefficients are then converted to Line Spectral Pair
2998 \begin_inset LatexCommand \index{line spectral pair}
2999
3000 \end_inset 
3001
3002  (LSP), a representation that is more robust to quantization.
3003  The LSP's are considered to be associated to the 
3004 \begin_inset Formula $4^{th}$
3005 \end_inset 
3006
3007  sub-frames and the LSP's associated to the first 3 sub-frames are linearly
3008  interpolated using the current and previous LSP's.
3009 \layout Standard
3010
3011 The LSP's are encoded using 30 bits for higher quality modes and 18 bits
3012  for lower quality, through the use of a multi-stage split-vector quantizer.
3013  For the lower quality modes, the 10 coefficients are first quantized with
3014  6 bits and the error is then divided in two 5-coefficient sub-vectors.
3015  Each of them is quantized with 6 bits, for a total of 18 bits.
3016  For the higher quality modes, the remaining error on both sub-vectors is
3017  further quantized with 6 bits each, for a total of 30 bits.
3018 \layout Standard
3019
3020 The perceptual weighting filter 
3021 \begin_inset Formula $W(z)$
3022 \end_inset 
3023
3024  used by Speex is derived from the LPC filter 
3025 \begin_inset Formula $A(z)$
3026 \end_inset 
3027
3028  and corresponds to the one described by eq.
3029  
3030 \begin_inset LatexCommand \ref{eq:weighting_filter}
3031
3032 \end_inset 
3033
3034  with 
3035 \begin_inset Formula $\gamma_{1}=0.9$
3036 \end_inset 
3037
3038  and 
3039 \begin_inset Formula $\gamma_{2}=0.6$
3040 \end_inset 
3041
3042 .
3043  We can use the unquantized 
3044 \begin_inset Formula $A(z)$
3045 \end_inset 
3046
3047  filter since the weighting filter is only used in the encoder.
3048 \layout Subsection
3049
3050 Pitch Prediction (adaptive codebook)
3051 \begin_inset LatexCommand \index{pitch}
3052
3053 \end_inset 
3054
3055
3056 \layout Standard
3057
3058 Speex uses a 3-tap prediction for pitch.
3059  That is, the pitch prediction signal 
3060 \begin_inset Formula $p[n]$
3061 \end_inset 
3062
3063  is obtained by the past of the excitation by:
3064 \begin_inset Formula \[
3065 p[n]=\beta_{0}e[n-T-1]+\beta_{1}e[n-T]+\beta_{2}e[n-T+1]\]
3066
3067 \end_inset 
3068
3069
3070 \layout Standard
3071
3072 where 
3073 \begin_inset Formula $T$
3074 \end_inset 
3075
3076  is the pitch period and the 
3077 \begin_inset Formula $\beta_{i}$
3078 \end_inset 
3079
3080  are the prediction (filter) taps.
3081  It is worth noting that when the pitch is smaller than the sub-frame size,
3082  we repeat the excitation at a period 
3083 \begin_inset Formula $T$
3084 \end_inset 
3085
3086 .
3087  For example, when 
3088 \begin_inset Formula $n-T+1$
3089 \end_inset 
3090
3091 , we use 
3092 \begin_inset Formula $n-2T+1$
3093 \end_inset 
3094
3095  instead.
3096  The period and quantized gains are determined in closed loop (analysis-by-synth
3097 esis).
3098  In most modes, the pitch period is encoded with 7 bits in the 
3099 \begin_inset Formula $\left[17,144\right]$
3100 \end_inset 
3101
3102  range and the 
3103 \begin_inset Formula $\beta_{i}$
3104 \end_inset 
3105
3106  coefficients are vector-quantized using 7 bits (15 kbps narrowband and
3107  above) at higher bit-rates and 5 bits at lower bit-rates (11 kbps narrowband
3108  and below).
3109 \layout Subsection
3110
3111 Innovation Codebook
3112 \layout Standard
3113
3114 In Speex, the innovation signal is quantized using sub-vector shape-only
3115  vector quantization (VQ).
3116  That means that the innovation signal is divided in sub-vectors (of size
3117  5 to 20) and quantized using a codebook that represents both the shape
3118  and the gain at the same time.
3119  This saves many bits that would otherwise be allocated for a separate gain
3120  at the price of a slight increase in complexity.
3121  
3122 \layout Subsection
3123
3124 Bit allocation
3125 \layout Standard
3126
3127 There are 7 different narrowband bit-rates defined for Speex, ranging from
3128  250 bps to 24.6 kbps, although the modes below 5.9 kbps should not be used
3129  for speech.
3130  The bit-allocation for each mode is detailed in table 
3131 \begin_inset LatexCommand \ref{cap:bits-narrowband}
3132
3133 \end_inset 
3134
3135 .
3136  Each frame starts with the mode ID encoded with 4 bits which allows a range
3137  from 0 to 15, though only the first 7 values are used (the others are reserved).
3138  The parameters are listed in the table in the order they are packed in
3139  the bit-stream.
3140  All frame-based parameters are packed before sub-frame parameters.
3141  The parameters for a certain sub-frame are all packed before the following
3142  sub-frame is packed.
3143  Note that the 
3144 \begin_inset Quotes eld
3145 \end_inset 
3146
3147 OL
3148 \begin_inset Quotes erd
3149 \end_inset 
3150
3151  in the parameter description means that the parameter is an open loop estimatio
3152 n based on the whole frame.
3153 \layout Standard
3154
3155
3156 \begin_inset Float table
3157 placement h
3158 wide true
3159 collapsed false
3160
3161 \layout Standard
3162
3163
3164 \begin_inset  Tabular
3165 <lyxtabular version="3" rows="12" columns="11">
3166 <features>
3167 <column alignment="center" valignment="top" leftline="true" width="0pt">
3168 <column alignment="center" valignment="top" leftline="true" width="0pt">
3169 <column alignment="center" valignment="top" leftline="true" width="0pt">
3170 <column alignment="center" valignment="top" leftline="true" width="0pt">
3171 <column alignment="center" valignment="top" leftline="true" width="0pt">
3172 <column alignment="center" valignment="top" leftline="true" width="0pt">
3173 <column alignment="center" valignment="top" leftline="true" width="0pt">
3174 <column alignment="center" valignment="top" leftline="true" width="0pt">
3175 <column alignment="center" valignment="top" leftline="true" width="0pt">
3176 <column alignment="center" valignment="top" leftline="true" width="0pt">
3177 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
3178 <row topline="true" bottomline="true">
3179 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3180 \begin_inset Text
3181
3182 \layout Standard
3183
3184 Parameter
3185 \end_inset 
3186 </cell>
3187 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3188 \begin_inset Text
3189
3190 \layout Standard
3191
3192 Update rate
3193 \end_inset 
3194 </cell>
3195 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3196 \begin_inset Text
3197
3198 \layout Standard
3199
3200 0
3201 \end_inset 
3202 </cell>
3203 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3204 \begin_inset Text
3205
3206 \layout Standard
3207
3208 1
3209 \end_inset 
3210 </cell>
3211 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3212 \begin_inset Text
3213
3214 \layout Standard
3215
3216 2
3217 \end_inset 
3218 </cell>
3219 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3220 \begin_inset Text
3221
3222 \layout Standard
3223
3224 3
3225 \end_inset 
3226 </cell>
3227 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3228 \begin_inset Text
3229
3230 \layout Standard
3231
3232 4
3233 \end_inset 
3234 </cell>
3235 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3236 \begin_inset Text
3237
3238 \layout Standard
3239
3240 5
3241 \end_inset 
3242 </cell>
3243 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3244 \begin_inset Text
3245
3246 \layout Standard
3247
3248 6
3249 \end_inset 
3250 </cell>
3251 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3252 \begin_inset Text
3253
3254 \layout Standard
3255
3256 7
3257 \end_inset 
3258 </cell>
3259 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3260 \begin_inset Text
3261
3262 \layout Standard
3263
3264 8
3265 \end_inset 
3266 </cell>
3267 </row>
3268 <row topline="true">
3269 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3270 \begin_inset Text
3271
3272 \layout Standard
3273
3274 Wideband bit
3275 \end_inset 
3276 </cell>
3277 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3278 \begin_inset Text
3279
3280 \layout Standard
3281
3282 frame
3283 \end_inset 
3284 </cell>
3285 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3286 \begin_inset Text
3287
3288 \layout Standard
3289
3290 1
3291 \end_inset 
3292 </cell>
3293 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3294 \begin_inset Text
3295
3296 \layout Standard
3297
3298 1
3299 \end_inset 
3300 </cell>
3301 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3302 \begin_inset Text
3303
3304 \layout Standard
3305
3306 1
3307 \end_inset 
3308 </cell>
3309 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3310 \begin_inset Text
3311
3312 \layout Standard
3313
3314 1
3315 \end_inset 
3316 </cell>
3317 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3318 \begin_inset Text
3319
3320 \layout Standard
3321
3322 1
3323 \end_inset 
3324 </cell>
3325 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3326 \begin_inset Text
3327
3328 \layout Standard
3329
3330 1
3331 \end_inset 
3332 </cell>
3333 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3334 \begin_inset Text
3335
3336 \layout Standard
3337
3338 1
3339 \end_inset 
3340 </cell>
3341 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3342 \begin_inset Text
3343
3344 \layout Standard
3345
3346 1
3347 \end_inset 
3348 </cell>
3349 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3350 \begin_inset Text
3351
3352 \layout Standard
3353
3354 1
3355 \end_inset 
3356 </cell>
3357 </row>
3358 <row topline="true">
3359 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3360 \begin_inset Text
3361
3362 \layout Standard
3363
3364 Mode ID
3365 \end_inset 
3366 </cell>
3367 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3368 \begin_inset Text
3369
3370 \layout Standard
3371
3372 frame
3373 \end_inset 
3374 </cell>
3375 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3376 \begin_inset Text
3377
3378 \layout Standard
3379
3380 4
3381 \end_inset 
3382 </cell>
3383 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3384 \begin_inset Text
3385
3386 \layout Standard
3387
3388 4
3389 \end_inset 
3390 </cell>
3391 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3392 \begin_inset Text
3393
3394 \layout Standard
3395
3396 4
3397 \end_inset 
3398 </cell>
3399 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3400 \begin_inset Text
3401
3402 \layout Standard
3403
3404 4
3405 \end_inset 
3406 </cell>
3407 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3408 \begin_inset Text
3409
3410 \layout Standard
3411
3412 4
3413 \end_inset 
3414 </cell>
3415 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3416 \begin_inset Text
3417
3418 \layout Standard
3419
3420 4
3421 \end_inset 
3422 </cell>
3423 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3424 \begin_inset Text
3425
3426 \layout Standard
3427
3428 4
3429 \end_inset 
3430 </cell>
3431 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3432 \begin_inset Text
3433
3434 \layout Standard
3435
3436 4
3437 \end_inset 
3438 </cell>
3439 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3440 \begin_inset Text
3441
3442 \layout Standard
3443
3444 4
3445 \end_inset 
3446 </cell>
3447 </row>
3448 <row topline="true">
3449 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3450 \begin_inset Text
3451
3452 \layout Standard
3453
3454 LSP
3455 \end_inset 
3456 </cell>
3457 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3458 \begin_inset Text
3459
3460 \layout Standard
3461
3462 frame
3463 \end_inset 
3464 </cell>
3465 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3466 \begin_inset Text
3467
3468 \layout Standard
3469
3470 0
3471 \end_inset 
3472 </cell>
3473 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3474 \begin_inset Text
3475
3476 \layout Standard
3477
3478 18
3479 \end_inset 
3480 </cell>
3481 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3482 \begin_inset Text
3483
3484 \layout Standard
3485
3486 18
3487 \end_inset 
3488 </cell>
3489 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3490 \begin_inset Text
3491
3492 \layout Standard
3493
3494 18
3495 \end_inset 
3496 </cell>
3497 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3498 \begin_inset Text
3499
3500 \layout Standard
3501
3502 18
3503 \end_inset 
3504 </cell>
3505 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3506 \begin_inset Text
3507
3508 \layout Standard
3509
3510 30
3511 \end_inset 
3512 </cell>
3513 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3514 \begin_inset Text
3515
3516 \layout Standard
3517
3518 30
3519 \end_inset 
3520 </cell>
3521 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3522 \begin_inset Text
3523
3524 \layout Standard
3525
3526 30
3527 \end_inset 
3528 </cell>
3529 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3530 \begin_inset Text
3531
3532 \layout Standard
3533
3534 18
3535 \end_inset 
3536 </cell>
3537 </row>
3538 <row topline="true">
3539 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3540 \begin_inset Text
3541
3542 \layout Standard
3543
3544 OL pitch
3545 \end_inset 
3546 </cell>
3547 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3548 \begin_inset Text
3549
3550 \layout Standard
3551
3552 frame
3553 \end_inset 
3554 </cell>
3555 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3556 \begin_inset Text
3557
3558 \layout Standard
3559
3560 0
3561 \end_inset 
3562 </cell>
3563 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3564 \begin_inset Text
3565
3566 \layout Standard
3567
3568 7
3569 \end_inset 
3570 </cell>
3571 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3572 \begin_inset Text
3573
3574 \layout Standard
3575
3576 7
3577 \end_inset 
3578 </cell>
3579 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3580 \begin_inset Text
3581
3582 \layout Standard
3583
3584 0
3585 \end_inset 
3586 </cell>
3587 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3588 \begin_inset Text
3589
3590 \layout Standard
3591
3592 0
3593 \end_inset 
3594 </cell>
3595 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3596 \begin_inset Text
3597
3598 \layout Standard
3599
3600 0
3601 \end_inset 
3602 </cell>
3603 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3604 \begin_inset Text
3605
3606 \layout Standard
3607
3608 0
3609 \end_inset 
3610 </cell>
3611 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3612 \begin_inset Text
3613
3614 \layout Standard
3615
3616 0
3617 \end_inset 
3618 </cell>
3619 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3620 \begin_inset Text
3621
3622 \layout Standard
3623
3624 7
3625 \end_inset 
3626 </cell>
3627 </row>
3628 <row topline="true">
3629 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3630 \begin_inset Text
3631
3632 \layout Standard
3633
3634 OL pitch gain
3635 \end_inset 
3636 </cell>
3637 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3638 \begin_inset Text
3639
3640 \layout Standard
3641
3642 frame
3643 \end_inset 
3644 </cell>
3645 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3646 \begin_inset Text
3647
3648 \layout Standard
3649
3650 0
3651 \end_inset 
3652 </cell>
3653 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3654 \begin_inset Text
3655
3656 \layout Standard
3657
3658 4
3659 \end_inset 
3660 </cell>
3661 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3662 \begin_inset Text
3663
3664 \layout Standard
3665
3666 0
3667 \end_inset 
3668 </cell>
3669 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3670 \begin_inset Text
3671
3672 \layout Standard
3673
3674 0
3675 \end_inset 
3676 </cell>
3677 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3678 \begin_inset Text
3679
3680 \layout Standard
3681
3682 0
3683 \end_inset 
3684 </cell>
3685 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3686 \begin_inset Text
3687
3688 \layout Standard
3689
3690 0
3691 \end_inset 
3692 </cell>
3693 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3694 \begin_inset Text
3695
3696 \layout Standard
3697
3698 0
3699 \end_inset 
3700 </cell>
3701 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3702 \begin_inset Text
3703
3704 \layout Standard
3705
3706 0
3707 \end_inset 
3708 </cell>
3709 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3710 \begin_inset Text
3711
3712 \layout Standard
3713
3714 4
3715 \end_inset 
3716 </cell>
3717 </row>
3718 <row topline="true">
3719 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3720 \begin_inset Text
3721
3722 \layout Standard
3723
3724 OL Exc gain
3725 \end_inset 
3726 </cell>
3727 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3728 \begin_inset Text
3729
3730 \layout Standard
3731
3732 frame
3733 \end_inset 
3734 </cell>
3735 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3736 \begin_inset Text
3737
3738 \layout Standard
3739
3740 0
3741 \end_inset 
3742 </cell>
3743 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3744 \begin_inset Text
3745
3746 \layout Standard
3747
3748 5
3749 \end_inset 
3750 </cell>
3751 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3752 \begin_inset Text
3753
3754 \layout Standard
3755
3756 5
3757 \end_inset 
3758 </cell>
3759 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3760 \begin_inset Text
3761
3762 \layout Standard
3763
3764 5
3765 \end_inset 
3766 </cell>
3767 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3768 \begin_inset Text
3769
3770 \layout Standard
3771
3772 5
3773 \end_inset 
3774 </cell>
3775 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3776 \begin_inset Text
3777
3778 \layout Standard
3779
3780 5
3781 \end_inset 
3782 </cell>
3783 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3784 \begin_inset Text
3785
3786 \layout Standard
3787
3788 5
3789 \end_inset 
3790 </cell>
3791 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3792 \begin_inset Text
3793
3794 \layout Standard
3795
3796 5
3797 \end_inset 
3798 </cell>
3799 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3800 \begin_inset Text
3801
3802 \layout Standard
3803
3804 5
3805 \end_inset 
3806 </cell>
3807 </row>
3808 <row topline="true">
3809 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3810 \begin_inset Text
3811
3812 \layout Standard
3813
3814 Fine pitch
3815 \end_inset 
3816 </cell>
3817 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3818 \begin_inset Text
3819
3820 \layout Standard
3821
3822 sub-frame
3823 \end_inset 
3824 </cell>
3825 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3826 \begin_inset Text
3827
3828 \layout Standard
3829
3830 0
3831 \end_inset 
3832 </cell>
3833 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3834 \begin_inset Text
3835
3836 \layout Standard
3837
3838 0
3839 \end_inset 
3840 </cell>
3841 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3842 \begin_inset Text
3843
3844 \layout Standard
3845
3846 0
3847 \end_inset 
3848 </cell>
3849 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3850 \begin_inset Text
3851
3852 \layout Standard
3853
3854 7
3855 \end_inset 
3856 </cell>
3857 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3858 \begin_inset Text
3859
3860 \layout Standard
3861
3862 7
3863 \end_inset 
3864 </cell>
3865 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3866 \begin_inset Text
3867
3868 \layout Standard
3869
3870 7
3871 \end_inset 
3872 </cell>
3873 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3874 \begin_inset Text
3875
3876 \layout Standard
3877
3878 7
3879 \end_inset 
3880 </cell>
3881 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3882 \begin_inset Text
3883
3884 \layout Standard
3885
3886 7
3887 \end_inset 
3888 </cell>
3889 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3890 \begin_inset Text
3891
3892 \layout Standard
3893
3894 0
3895 \end_inset 
3896 </cell>
3897 </row>
3898 <row topline="true">
3899 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3900 \begin_inset Text
3901
3902 \layout Standard
3903
3904 Pitch gain
3905 \end_inset 
3906 </cell>
3907 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3908 \begin_inset Text
3909
3910 \layout Standard
3911
3912 sub-frame
3913 \end_inset 
3914 </cell>
3915 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3916 \begin_inset Text
3917
3918 \layout Standard
3919
3920 0
3921 \end_inset 
3922 </cell>
3923 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3924 \begin_inset Text
3925
3926 \layout Standard
3927
3928 0
3929 \end_inset 
3930 </cell>
3931 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3932 \begin_inset Text
3933
3934 \layout Standard
3935
3936 5
3937 \end_inset 
3938 </cell>
3939 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3940 \begin_inset Text
3941
3942 \layout Standard
3943
3944 5
3945 \end_inset 
3946 </cell>
3947 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3948 \begin_inset Text
3949
3950 \layout Standard
3951
3952 5
3953 \end_inset 
3954 </cell>
3955 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3956 \begin_inset Text
3957
3958 \layout Standard
3959
3960 7
3961 \end_inset 
3962 </cell>
3963 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3964 \begin_inset Text
3965
3966 \layout Standard
3967
3968 7
3969 \end_inset 
3970 </cell>
3971 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3972 \begin_inset Text
3973
3974 \layout Standard
3975
3976 7
3977 \end_inset 
3978 </cell>
3979 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3980 \begin_inset Text
3981
3982 \layout Standard
3983
3984 0
3985 \end_inset 
3986 </cell>
3987 </row>
3988 <row topline="true">
3989 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3990 \begin_inset Text
3991
3992 \layout Standard
3993
3994 Innovation gain
3995 \end_inset 
3996 </cell>
3997 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3998 \begin_inset Text
3999
4000 \layout Standard
4001
4002 sub-frame
4003 \end_inset 
4004 </cell>
4005 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4006 \begin_inset Text
4007
4008 \layout Standard
4009
4010 0
4011 \end_inset 
4012 </cell>
4013 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4014 \begin_inset Text
4015
4016 \layout Standard
4017
4018 1
4019 \end_inset 
4020 </cell>
4021 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4022 \begin_inset Text
4023
4024 \layout Standard
4025
4026 0
4027 \end_inset 
4028 </cell>
4029 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4030 \begin_inset Text
4031
4032 \layout Standard
4033
4034 1
4035 \end_inset 
4036 </cell>
4037 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4038 \begin_inset Text
4039
4040 \layout Standard
4041
4042 1
4043 \end_inset 
4044 </cell>
4045 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4046 \begin_inset Text
4047
4048 \layout Standard
4049
4050 3
4051 \end_inset 
4052 </cell>
4053 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4054 \begin_inset Text
4055
4056 \layout Standard
4057
4058 3
4059 \end_inset 
4060 </cell>
4061 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4062 \begin_inset Text
4063
4064 \layout Standard
4065
4066 3
4067 \end_inset 
4068 </cell>
4069 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4070 \begin_inset Text
4071
4072 \layout Standard
4073
4074 0
4075 \end_inset 
4076 </cell>
4077 </row>
4078 <row topline="true" bottomline="true">
4079 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4080 \begin_inset Text
4081
4082 \layout Standard
4083
4084 Innovation VQ
4085 \end_inset 
4086 </cell>
4087 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4088 \begin_inset Text
4089
4090 \layout Standard
4091
4092 sub-frame
4093 \end_inset 
4094 </cell>
4095 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4096 \begin_inset Text
4097
4098 \layout Standard
4099
4100 0
4101 \end_inset 
4102 </cell>
4103 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4104 \begin_inset Text
4105
4106 \layout Standard
4107
4108 0
4109 \end_inset 
4110 </cell>
4111 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4112 \begin_inset Text
4113
4114 \layout Standard
4115
4116 16
4117 \end_inset 
4118 </cell>
4119 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4120 \begin_inset Text
4121
4122 \layout Standard
4123
4124 20
4125 \end_inset 
4126 </cell>
4127 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4128 \begin_inset Text
4129
4130 \layout Standard
4131
4132 35
4133 \end_inset 
4134 </cell>
4135 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4136 \begin_inset Text
4137
4138 \layout Standard
4139
4140 48
4141 \end_inset 
4142 </cell>
4143 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4144 \begin_inset Text
4145
4146 \layout Standard
4147
4148 64
4149 \end_inset 
4150 </cell>
4151 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4152 \begin_inset Text
4153
4154 \layout Standard
4155
4156 96
4157 \end_inset 
4158 </cell>
4159 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4160 \begin_inset Text
4161
4162 \layout Standard
4163
4164 10
4165 \end_inset 
4166 </cell>
4167 </row>
4168 <row topline="true" bottomline="true">
4169 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4170 \begin_inset Text
4171
4172 \layout Standard
4173
4174 Total
4175 \end_inset 
4176 </cell>
4177 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4178 \begin_inset Text
4179
4180 \layout Standard
4181
4182 frame
4183 \end_inset 
4184 </cell>
4185 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4186 \begin_inset Text
4187
4188 \layout Standard
4189
4190 5
4191 \end_inset 
4192 </cell>
4193 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4194 \begin_inset Text
4195
4196 \layout Standard
4197
4198 43
4199 \end_inset 
4200 </cell>
4201 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4202 \begin_inset Text
4203
4204 \layout Standard
4205
4206 119
4207 \end_inset 
4208 </cell>
4209 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4210 \begin_inset Text
4211
4212 \layout Standard
4213
4214 160
4215 \end_inset 
4216 </cell>
4217 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4218 \begin_inset Text
4219
4220 \layout Standard
4221
4222 220
4223 \end_inset 
4224 </cell>
4225 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4226 \begin_inset Text
4227
4228 \layout Standard
4229
4230 300
4231 \end_inset 
4232 </cell>
4233 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4234 \begin_inset Text
4235
4236 \layout Standard
4237
4238 364
4239 \end_inset 
4240 </cell>
4241 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4242 \begin_inset Text
4243
4244 \layout Standard
4245
4246 492
4247 \end_inset 
4248 </cell>
4249 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4250 \begin_inset Text
4251
4252 \layout Standard
4253
4254 79
4255 \end_inset 
4256 </cell>
4257 </row>
4258 </lyxtabular>
4259
4260 \end_inset 
4261
4262
4263 \layout Caption
4264
4265 Bit allocation for narrowband modes
4266 \begin_inset LatexCommand \label{cap:bits-narrowband}
4267
4268 \end_inset 
4269
4270
4271 \end_inset 
4272
4273
4274 \layout Standard
4275
4276 So far, no MOS (Mean Opinion Score
4277 \begin_inset LatexCommand \index{mean opinion score}
4278
4279 \end_inset 
4280
4281 ) subjective evaluation has been performed for Speex.
4282  In order to give an idea of the quality achivable with it, table 
4283 \begin_inset LatexCommand \ref{cap:quality_vs_bps}
4284
4285 \end_inset 
4286
4287  presents my own subjective opinion on it.
4288  It sould be noted that different people will perceive the quality differently
4289  and that the person that designed the codec often has a bias (one way or
4290  another) when it comes to subjective evaluation.
4291  Last thing, it should be noted that for most codecs (including Speex) encoding
4292  quality sometimes varies depending on the input.
4293  Note that the complexity is only approximate (within 0.5 mflops and using
4294  the lowest complexity setting).
4295  Decoding requires approximately 0.5 mflops
4296 \begin_inset LatexCommand \index{complexity}
4297
4298 \end_inset 
4299
4300  in most modes (1 mflops with perceptual enhancement).
4301 \layout Standard
4302
4303
4304 \begin_inset Float table
4305 placement h
4306 wide true
4307 collapsed false
4308
4309 \layout Standard
4310
4311
4312 \begin_inset  Tabular
4313 <lyxtabular version="3" rows="17" columns="4">
4314 <features>
4315 <column alignment="center" valignment="top" leftline="true" width="0pt">
4316 <column alignment="center" valignment="top" leftline="true" width="0pt">
4317 <column alignment="center" valignment="top" leftline="true" width="0pt">
4318 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
4319 <row topline="true" bottomline="true">
4320 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4321 \begin_inset Text
4322
4323 \layout Standard
4324
4325 Mode
4326 \end_inset 
4327 </cell>
4328 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4329 \begin_inset Text
4330
4331 \layout Standard
4332
4333 Bit-rate
4334 \begin_inset LatexCommand \index{bit-rate}
4335
4336 \end_inset 
4337
4338  (bps)
4339 \end_inset 
4340 </cell>
4341 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4342 \begin_inset Text
4343
4344 \layout Standard
4345
4346 mflops
4347 \begin_inset LatexCommand \index{complexity}
4348
4349 \end_inset 
4350
4351
4352 \end_inset 
4353 </cell>
4354 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4355 \begin_inset Text
4356
4357 \layout Standard
4358
4359 Quality/description
4360 \end_inset 
4361 </cell>
4362 </row>
4363 <row topline="true">
4364 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4365 \begin_inset Text
4366
4367 \layout Standard
4368
4369 0
4370 \end_inset 
4371 </cell>
4372 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4373 \begin_inset Text
4374
4375 \layout Standard
4376
4377 250
4378 \end_inset 
4379 </cell>
4380 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4381 \begin_inset Text
4382
4383 \layout Standard
4384
4385 N/A
4386 \end_inset 
4387 </cell>
4388 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4389 \begin_inset Text
4390
4391 \layout Standard
4392
4393 No transmission (DTX)
4394 \end_inset 
4395 </cell>
4396 </row>
4397 <row topline="true">
4398 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4399 \begin_inset Text
4400
4401 \layout Standard
4402
4403 1
4404 \end_inset 
4405 </cell>
4406 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4407 \begin_inset Text
4408
4409 \layout Standard
4410
4411 2,150
4412 \end_inset 
4413 </cell>
4414 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4415 \begin_inset Text
4416
4417 \layout Standard
4418
4419 6
4420 \end_inset 
4421 </cell>
4422 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4423 \begin_inset Text
4424
4425 \layout Standard
4426
4427 Vocoder (mostly for comfort noise)
4428 \end_inset 
4429 </cell>
4430 </row>
4431 <row topline="true">
4432 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">