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