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