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