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