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