2a37a3908b6a6cbfb3d95caa799fc814cd17d8be
[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 0.7.0)
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 has been started because there was a need for a speech
100  codec that was open-source and free from software patents.
101  These are essential conditions for being used by any open-source software.
102  There is already Vorbis that does general audio, but it is not really suitable
103  for speech.
104  Also, unlike many other speech codecs, Speex is not targeted at cell phones
105  (not many open-source cell phones anyway :-) ) but rather voice over IP
106  (VoIP) and file-based compression.
107  
108 \layout Standard
109
110 As design goals, we wanted to have a codec that would allowed both very
111  good quality speech and low bit-rate (unfortunately not at the same time!),
112  which led us to developing a codec with multiple bit-rates.
113  Of course very good quality also meant we had to do wideband (16 kHz sampling
114  rate) in addition to narrowband (telephone quality, 8 kHz sampling rate).
115 \layout Standard
116
117 Designing for VoIP instead of cell phone use means that Speex must be robust
118  to lost packets, but not to corrupted ones since packets either arrive
119  unaltered or don't arrive at all.
120  Also, the idea was to have a reasonnable complexity and memory requirement
121  without compromising too much on the efficiency of the codec.
122 \layout Standard
123
124 All this led us to the choice of CELP as the encoding technique to use for
125  Speex.
126  One of the main reasons is that CELP has long proved that it could do the
127  job and scale well to both low bit-rates (think DoD CELP @ 4.8 kbps) and
128  high bit-rates (think G.728 @ 16 kbps).
129  
130 \layout Section
131 \pagebreak_top 
132 Introduction to CELP Coding
133 \layout Standard
134
135 Speex is based on CELP, which stands for Code Excited Linear Prediction.
136  This section attempts to introduce the principles behind CELP, so if you
137  are already familiar with CELP, you can safely skip to section 
138 \begin_inset LatexCommand \ref{sec:Speex-narrowband-mode}
139
140 \end_inset 
141
142 .
143  The CELP technique is based on three ideas:
144 \layout Enumerate
145
146 The use of a linear prediction (LP) model to model the vocal tract
147 \layout Enumerate
148
149 The use of (adaptive and fixed) codebook entries as input (excitation) of
150  the LP model
151 \layout Enumerate
152
153 The search performed in closed-loop in a 
154 \begin_inset Quotes eld
155 \end_inset 
156
157 perceptually weighted domain
158 \begin_inset Quotes erd
159 \end_inset 
160
161
162 \layout Subsection
163
164 Linear Prediction
165 \layout Standard
166
167 The linear prediction model represents each speech sample as linear combination
168  of past samples, plus an error signal called the excitation (or residual).
169 \begin_inset Formula \[
170 x(n)=\sum _{i=1}^{N}a_{i}x(n-i)+e(n)\]
171
172 \end_inset 
173
174
175 \layout Standard
176
177 In the 
178 \emph on 
179 z
180 \emph default 
181 -domain, this can be expressed as
182 \layout Standard
183
184
185 \begin_inset Formula \[
186 x(z)=\frac{1}{A(z)}\: e(z)\]
187
188 \end_inset 
189
190
191 \layout Standard
192
193 where 
194 \begin_inset Formula $A(z)$
195 \end_inset 
196
197  is defined as
198 \layout Standard
199
200
201 \begin_inset Formula \[
202 A(z)=1-\sum _{i=1}^{N}a_{i}z^{-i}\]
203
204 \end_inset 
205
206
207 \layout Standard
208
209 We usually refer to 
210 \begin_inset Formula $A(z)$
211 \end_inset 
212
213  as the analysis filter and 
214 \begin_inset Formula $1/A(z)$
215 \end_inset 
216
217  as the synthesis filter.
218 \layout Standard
219
220 The 
221 \begin_inset Formula $A(z)$
222 \end_inset 
223
224  filter is computed using the Levinson-Durbin algorithm, which starts from
225  the auto-correlation 
226 \begin_inset Formula $R(m)$
227 \end_inset 
228
229  of the signal 
230 \begin_inset Formula $x(n)$
231 \end_inset 
232
233 .
234 \layout Standard
235
236
237 \begin_inset Formula \[
238 r(m)=\sum _{i=0}^{N-1}x(i)x(i-m)\]
239
240 \end_inset 
241
242
243 \layout Standard
244
245 For an order 
246 \begin_inset Formula $N$
247 \end_inset 
248
249  filter, we have:
250 \begin_inset Formula \[
251 \mathbf{R}=\left[\begin{array}{cccc}
252  r(0) & r(1) & \cdots  & r(N-1)\\
253  r(1) & r(0) & \cdots  & r(N-2)\\
254  \vdots  & \vdots  & \ddots  & \vdots \\
255  r(N-1) & r(N-2) & \cdots  & r(0)\end{array}
256 \right]\]
257
258 \end_inset 
259
260
261 \begin_inset Formula \[
262 \mathbf{r}=\left[\begin{array}{c}
263  r(1)\\
264  r(2)\\
265  \vdots \\
266  R(N)\end{array}
267 \right]\]
268
269 \end_inset 
270
271
272 \layout Standard
273
274 The filter coefficients 
275 \begin_inset Formula $a_{i}$
276 \end_inset 
277
278  are found by solving the system 
279 \begin_inset Formula $\mathbf{Ra}=\mathbf{r}$
280 \end_inset 
281
282 .
283  What the Levinson-Durbin algorithm does here is making the solution to
284  the problem 
285 \begin_inset Formula $\mathcal{O}\left(N^{2}\right)$
286 \end_inset 
287
288  instead of 
289 \begin_inset Formula $\mathcal{O}\left(N^{3}\right)$
290 \end_inset 
291
292  by exploiting the fact that matrix 
293 \begin_inset Formula $\mathbf{R}$
294 \end_inset 
295
296  is toeplitz hermitian.
297  Also, it can be proved that all the roots of 
298 \begin_inset Formula $A(z)$
299 \end_inset 
300
301  are withing the unit circle, which means that 
302 \begin_inset Formula $1/A(z)$
303 \end_inset 
304
305  is always stable.
306  This is in theory; in practice because of finite precision, there are two
307  commonly used techniques to make sure we have a stable filter.
308  First, we multiply 
309 \begin_inset Formula $r(0)$
310 \end_inset 
311
312  by a number slightly above one (such as 1.0001), which is equivalent to
313  adding noise to the signal.
314  Also, we can apply a window the the auto-correlation, which is equivalent
315  to filtering in the frequency domain, reducing sharp resonances.
316 \layout Subsection
317
318 Pitch Prediction
319 \layout Standard
320
321 During voiced segments, the speech signal is very periodic, so it is possible
322  to take advantage of that by expressing the excitation signal 
323 \begin_inset Formula $e(n)$
324 \end_inset 
325
326  as
327 \layout Standard
328
329
330 \begin_inset Formula \[
331 e(n)=\beta e(n-T)+c(n)\]
332
333 \end_inset 
334
335
336 \layout Standard
337
338 where 
339 \begin_inset Formula $T$
340 \end_inset 
341
342  is the pitch period, 
343 \begin_inset Formula $\beta $
344 \end_inset 
345
346  is the pitch gain and 
347 \begin_inset Formula $c(n)$
348 \end_inset 
349
350  is taken from the 
351 \emph on 
352 innovation codebook
353 \emph default 
354 .
355  In the 
356 \emph on 
357 z
358 \emph default 
359 -domain, the excitation can be expressed as:
360 \layout Standard
361
362
363 \begin_inset Formula \[
364 e(z)=\frac{1}{1-\beta z^{-T}}\: c(z)\]
365
366 \end_inset 
367
368
369 \layout Subsection
370
371 Innovation Codebook
372 \layout Standard
373
374 This is where most of the bits in a CELP codec are allocated.
375  It represents the information that couldn't be obtained either from linear
376  prediction or pitch prediction.
377 \layout Subsection
378
379 Analysis-by-Synthesis and Error Weighting
380 \layout Standard
381
382 Most (if not all) modern audio codecs attempt to 
383 \emph on 
384 shape
385 \emph default 
386  the noise so that it is the hardest to detect with the ear.
387  That means that more noise can be tolerated in parts of the spectrum that
388  are louder and 
389 \emph on 
390 vice versa
391 \emph default 
392 .
393  That's why the error is minimized for the perceptually weighted signal
394 \begin_inset Formula \[
395 X_{w}(z)=W(z)X(z)\]
396
397 \end_inset 
398
399 where 
400 \begin_inset Formula $W(z)$
401 \end_inset 
402
403  is the weighting filter, usually of the form
404 \layout Standard
405
406
407 \begin_inset Formula \begin{equation}
408 W(z)=\frac{A\left(\frac{z}{\gamma _{1}}\right)}{A\left(\frac{z}{\gamma _{2}}\right)}\label{eq:weighting_filter}\end{equation}
409
410 \end_inset 
411
412
413 \layout Standard
414
415 with control parameters 
416 \begin_inset Formula $\gamma _{1}>\gamma _{2}$
417 \end_inset 
418
419 .
420  If the noise is white in the perceptually weighted domain, then in the
421  signal domain its spectral shape will be of the form
422 \begin_inset Formula \[
423 A_{noise}(z)=\frac{1}{W(z)}=\frac{A\left(\frac{z}{\gamma _{2}}\right)}{A\left(\frac{z}{\gamma _{1}}\right)}\]
424
425 \end_inset 
426
427
428 \layout Section
429 \pagebreak_top 
430 Speex narrowband mode
431 \begin_inset LatexCommand \label{sec:Speex-narrowband-mode}
432
433 \end_inset 
434
435
436 \layout Standard
437
438 This section looks at how Speex works for narrowband (
439 \begin_inset Formula $8\: \mathrm{kHz}$
440 \end_inset 
441
442  sampling rate) operation.
443  The frame size for this mode is 
444 \begin_inset Formula $20\: \mathrm{ms}$
445 \end_inset 
446
447 , corresponding to 160 samples.
448  Each frame is also subdivided into 4 sub-frames of 40 samples each.
449 \layout Standard
450
451 Also many design decisions were based on the original goals and assumptions:
452 \layout Itemize
453
454 Minimizing the amount of information extracted from past frames (for robustness
455  to packet loss)
456 \layout Itemize
457
458 Dynamically-selectable codebooks (LSP, pitch and innovation)
459 \layout Itemize
460
461 G.728-like fixed codebooks (without backward-adaptive grains because of patent
462  issues)
463 \layout Subsection
464
465 LPC Analysis
466 \layout Standard
467
468 An LPC analysis is first performed on a (Hamming) window that spans all
469  the current frame and half a frame in advance.
470  The LPC coefficients are then converted to Line Spectral Pair (LSP), a
471  representation that is more robust to quantization.
472  The LSP's are quantized using 30 bits for higher quality modes and 18 bits
473  for lower quality.
474  The quantized LSP's are considered to be associated to the 
475 \begin_inset Formula $4^{th}$
476 \end_inset 
477
478  sub-frames and the LSP's associated to the first 3 sub-frames are linearly
479  interpolated using the current and previous LSP's.
480 \layout Standard
481
482 The perceptual weighting filter 
483 \begin_inset Formula $W(z)$
484 \end_inset 
485
486  used by Speex corresponds to the one described by eq.
487  
488 \begin_inset LatexCommand \ref{eq:weighting_filter}
489
490 \end_inset 
491
492  with 
493 \begin_inset Formula $\gamma _{1}=0.9$
494 \end_inset 
495
496  and 
497 \begin_inset Formula $\gamma _{2}=0.6$
498 \end_inset 
499
500 .
501  We can use the unquantized 
502 \begin_inset Formula $A(z)$
503 \end_inset 
504
505  filter since the weighting filter is only used in the encoder.
506 \layout Subsection
507
508 Pitch Prediction (adaptive codebook)
509 \layout Standard
510
511 Speex uses a 3-tap prediction for pitch.
512  That is, 
513 \layout Standard
514
515
516 \begin_inset Formula \[
517 e(n)=\beta _{0}e(n-T-1)+\beta _{1}e(n-T)+\beta _{2}e(n-T+1)+c(n)\]
518
519 \end_inset 
520
521
522 \layout Standard
523
524 where 
525 \begin_inset Formula $T$
526 \end_inset 
527
528  is the pitch period and the 
529 \begin_inset Formula $\beta _{i}$
530 \end_inset 
531
532  are the prediction (filter) taps.
533  The period and quantized gains are determined in closed loop.
534 \layout Subsection
535
536 Innovation Codebook
537 \layout Standard
538
539 In Speex, the innovation signal is quantized using shape-only vector quantizatio
540 n (VQ).
541  That means that the codebooks that are used represent both the shape and
542  the gain at the same time.
543  This save many bits that would otherwise be allocated for a separate gain
544  at the price of a slight increase in complexity.
545  Except for the absence of (backward-adaptive) gain, the technique used
546  in Speex is similar to G.728 (LD-CELP).
547  However since we do not have a low-delay constraint, the search can be
548  made more 
549 \begin_inset Quotes eld
550 \end_inset 
551
552 global
553 \begin_inset Quotes erd
554 \end_inset 
555
556  and make use of the whole information available for a sub-frame.
557 \layout Subsection
558
559 Bit allocation
560 \layout Standard
561
562 There are 7 different narrowband bit-rates defined for Speex, ranging from
563  200 bps to 18.15 kbps, although the modes below 5.9 kbps should not be used
564  for speech.
565  The bit-allocation for each mode is detailed in table 
566 \begin_inset LatexCommand \ref{cap:bits-narrowband}
567
568 \end_inset 
569
570 .
571  Each frame starts with the mode ID encoded with 4 bits which allows a range
572  from 0 to 15, though only the first 7 values are used (the others are reserved).
573  The parameters are listed in the table in the order they are packed in
574  the bit-stream.
575  All frame-based parameters are packed before sub-frame parameters.
576  The parameters for a certain sub-frame are all packed before the following
577  sub-frame is packed.
578 \layout Standard
579
580
581 \begin_inset Float table
582 placement htbp
583 wide true
584 collapsed false
585
586 \layout Standard
587
588
589 \begin_inset  Tabular
590 <lyxtabular version="3" rows="12" columns="9">
591 <features>
592 <column alignment="center" valignment="top" leftline="true" width="0pt">
593 <column alignment="center" valignment="top" leftline="true" width="0pt">
594 <column alignment="center" valignment="top" leftline="true" width="0pt">
595 <column alignment="center" valignment="top" leftline="true" width="0pt">
596 <column alignment="center" valignment="top" leftline="true" width="0pt">
597 <column alignment="center" valignment="top" leftline="true" width="0pt">
598 <column alignment="center" valignment="top" leftline="true" width="0pt">
599 <column alignment="center" valignment="top" leftline="true" width="0pt">
600 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
601 <row topline="true" bottomline="true">
602 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
603 \begin_inset Text
604
605 \layout Standard
606
607 Parameter
608 \end_inset 
609 </cell>
610 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
611 \begin_inset Text
612
613 \layout Standard
614
615 Update rate
616 \end_inset 
617 </cell>
618 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
619 \begin_inset Text
620
621 \layout Standard
622
623 0
624 \end_inset 
625 </cell>
626 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
627 \begin_inset Text
628
629 \layout Standard
630
631 1
632 \end_inset 
633 </cell>
634 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
635 \begin_inset Text
636
637 \layout Standard
638
639 2
640 \end_inset 
641 </cell>
642 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
643 \begin_inset Text
644
645 \layout Standard
646
647 3
648 \end_inset 
649 </cell>
650 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
651 \begin_inset Text
652
653 \layout Standard
654
655 4
656 \end_inset 
657 </cell>
658 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
659 \begin_inset Text
660
661 \layout Standard
662
663 5
664 \end_inset 
665 </cell>
666 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
667 \begin_inset Text
668
669 \layout Standard
670
671 6
672 \end_inset 
673 </cell>
674 </row>
675 <row topline="true">
676 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
677 \begin_inset Text
678
679 \layout Standard
680
681 Wideband bit
682 \end_inset 
683 </cell>
684 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
685 \begin_inset Text
686
687 \layout Standard
688
689 frame
690 \end_inset 
691 </cell>
692 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
693 \begin_inset Text
694
695 \layout Standard
696
697 1
698 \end_inset 
699 </cell>
700 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
701 \begin_inset Text
702
703 \layout Standard
704
705 1
706 \end_inset 
707 </cell>
708 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
709 \begin_inset Text
710
711 \layout Standard
712
713 1
714 \end_inset 
715 </cell>
716 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
717 \begin_inset Text
718
719 \layout Standard
720
721 1
722 \end_inset 
723 </cell>
724 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
725 \begin_inset Text
726
727 \layout Standard
728
729 1
730 \end_inset 
731 </cell>
732 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
733 \begin_inset Text
734
735 \layout Standard
736
737 1
738 \end_inset 
739 </cell>
740 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
741 \begin_inset Text
742
743 \layout Standard
744
745 1
746 \end_inset 
747 </cell>
748 </row>
749 <row topline="true">
750 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
751 \begin_inset Text
752
753 \layout Standard
754
755 Mode ID
756 \end_inset 
757 </cell>
758 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
759 \begin_inset Text
760
761 \layout Standard
762
763 frame
764 \end_inset 
765 </cell>
766 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
767 \begin_inset Text
768
769 \layout Standard
770
771 4
772 \end_inset 
773 </cell>
774 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
775 \begin_inset Text
776
777 \layout Standard
778
779 4
780 \end_inset 
781 </cell>
782 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
783 \begin_inset Text
784
785 \layout Standard
786
787 4
788 \end_inset 
789 </cell>
790 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
791 \begin_inset Text
792
793 \layout Standard
794
795 4
796 \end_inset 
797 </cell>
798 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
799 \begin_inset Text
800
801 \layout Standard
802
803 4
804 \end_inset 
805 </cell>
806 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
807 \begin_inset Text
808
809 \layout Standard
810
811 4
812 \end_inset 
813 </cell>
814 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
815 \begin_inset Text
816
817 \layout Standard
818
819 4
820 \end_inset 
821 </cell>
822 </row>
823 <row topline="true">
824 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
825 \begin_inset Text
826
827 \layout Standard
828
829 LSP
830 \end_inset 
831 </cell>
832 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
833 \begin_inset Text
834
835 \layout Standard
836
837 frame
838 \end_inset 
839 </cell>
840 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
841 \begin_inset Text
842
843 \layout Standard
844
845 0
846 \end_inset 
847 </cell>
848 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
849 \begin_inset Text
850
851 \layout Standard
852
853 18
854 \end_inset 
855 </cell>
856 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
857 \begin_inset Text
858
859 \layout Standard
860
861 18
862 \end_inset 
863 </cell>
864 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
865 \begin_inset Text
866
867 \layout Standard
868
869 18
870 \end_inset 
871 </cell>
872 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
873 \begin_inset Text
874
875 \layout Standard
876
877 18
878 \end_inset 
879 </cell>
880 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
881 \begin_inset Text
882
883 \layout Standard
884
885 30
886 \end_inset 
887 </cell>
888 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
889 \begin_inset Text
890
891 \layout Standard
892
893 30
894 \end_inset 
895 </cell>
896 </row>
897 <row topline="true">
898 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
899 \begin_inset Text
900
901 \layout Standard
902
903 OL pitch
904 \end_inset 
905 </cell>
906 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
907 \begin_inset Text
908
909 \layout Standard
910
911 frame
912 \end_inset 
913 </cell>
914 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
915 \begin_inset Text
916
917 \layout Standard
918
919 0
920 \end_inset 
921 </cell>
922 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
923 \begin_inset Text
924
925 \layout Standard
926
927 7
928 \end_inset 
929 </cell>
930 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
931 \begin_inset Text
932
933 \layout Standard
934
935 7
936 \end_inset 
937 </cell>
938 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
939 \begin_inset Text
940
941 \layout Standard
942
943 0
944 \end_inset 
945 </cell>
946 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
947 \begin_inset Text
948
949 \layout Standard
950
951 0
952 \end_inset 
953 </cell>
954 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
955 \begin_inset Text
956
957 \layout Standard
958
959 0
960 \end_inset 
961 </cell>
962 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
963 \begin_inset Text
964
965 \layout Standard
966
967 0
968 \end_inset 
969 </cell>
970 </row>
971 <row topline="true">
972 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
973 \begin_inset Text
974
975 \layout Standard
976
977 OL pitch gain
978 \end_inset 
979 </cell>
980 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
981 \begin_inset Text
982
983 \layout Standard
984
985 frame
986 \end_inset 
987 </cell>
988 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
989 \begin_inset Text
990
991 \layout Standard
992
993 0
994 \end_inset 
995 </cell>
996 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
997 \begin_inset Text
998
999 \layout Standard
1000
1001 4
1002 \end_inset 
1003 </cell>
1004 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1005 \begin_inset Text
1006
1007 \layout Standard
1008
1009 0
1010 \end_inset 
1011 </cell>
1012 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1013 \begin_inset Text
1014
1015 \layout Standard
1016
1017 0
1018 \end_inset 
1019 </cell>
1020 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1021 \begin_inset Text
1022
1023 \layout Standard
1024
1025 0
1026 \end_inset 
1027 </cell>
1028 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1029 \begin_inset Text
1030
1031 \layout Standard
1032
1033 0
1034 \end_inset 
1035 </cell>
1036 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1037 \begin_inset Text
1038
1039 \layout Standard
1040
1041 0
1042 \end_inset 
1043 </cell>
1044 </row>
1045 <row topline="true">
1046 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1047 \begin_inset Text
1048
1049 \layout Standard
1050
1051 OL Exc gain
1052 \end_inset 
1053 </cell>
1054 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1055 \begin_inset Text
1056
1057 \layout Standard
1058
1059 frame
1060 \end_inset 
1061 </cell>
1062 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1063 \begin_inset Text
1064
1065 \layout Standard
1066
1067 0
1068 \end_inset 
1069 </cell>
1070 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1071 \begin_inset Text
1072
1073 \layout Standard
1074
1075 5
1076 \end_inset 
1077 </cell>
1078 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1079 \begin_inset Text
1080
1081 \layout Standard
1082
1083 5
1084 \end_inset 
1085 </cell>
1086 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1087 \begin_inset Text
1088
1089 \layout Standard
1090
1091 5
1092 \end_inset 
1093 </cell>
1094 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1095 \begin_inset Text
1096
1097 \layout Standard
1098
1099 5
1100 \end_inset 
1101 </cell>
1102 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1103 \begin_inset Text
1104
1105 \layout Standard
1106
1107 5
1108 \end_inset 
1109 </cell>
1110 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1111 \begin_inset Text
1112
1113 \layout Standard
1114
1115 5
1116 \end_inset 
1117 </cell>
1118 </row>
1119 <row topline="true">
1120 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1121 \begin_inset Text
1122
1123 \layout Standard
1124
1125 Fine pitch
1126 \end_inset 
1127 </cell>
1128 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1129 \begin_inset Text
1130
1131 \layout Standard
1132
1133 sub-frame
1134 \end_inset 
1135 </cell>
1136 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1137 \begin_inset Text
1138
1139 \layout Standard
1140
1141 0
1142 \end_inset 
1143 </cell>
1144 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1145 \begin_inset Text
1146
1147 \layout Standard
1148
1149 0
1150 \end_inset 
1151 </cell>
1152 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1153 \begin_inset Text
1154
1155 \layout Standard
1156
1157 0
1158 \end_inset 
1159 </cell>
1160 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1161 \begin_inset Text
1162
1163 \layout Standard
1164
1165 7
1166 \end_inset 
1167 </cell>
1168 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1169 \begin_inset Text
1170
1171 \layout Standard
1172
1173 7
1174 \end_inset 
1175 </cell>
1176 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1177 \begin_inset Text
1178
1179 \layout Standard
1180
1181 7
1182 \end_inset 
1183 </cell>
1184 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1185 \begin_inset Text
1186
1187 \layout Standard
1188
1189 7
1190 \end_inset 
1191 </cell>
1192 </row>
1193 <row topline="true">
1194 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1195 \begin_inset Text
1196
1197 \layout Standard
1198
1199 Pitch gain
1200 \end_inset 
1201 </cell>
1202 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1203 \begin_inset Text
1204
1205 \layout Standard
1206
1207 sub-frame
1208 \end_inset 
1209 </cell>
1210 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1211 \begin_inset Text
1212
1213 \layout Standard
1214
1215 0
1216 \end_inset 
1217 </cell>
1218 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1219 \begin_inset Text
1220
1221 \layout Standard
1222
1223 0
1224 \end_inset 
1225 </cell>
1226 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1227 \begin_inset Text
1228
1229 \layout Standard
1230
1231 5
1232 \end_inset 
1233 </cell>
1234 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1235 \begin_inset Text
1236
1237 \layout Standard
1238
1239 5
1240 \end_inset 
1241 </cell>
1242 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1243 \begin_inset Text
1244
1245 \layout Standard
1246
1247 5
1248 \end_inset 
1249 </cell>
1250 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1251 \begin_inset Text
1252
1253 \layout Standard
1254
1255 7
1256 \end_inset 
1257 </cell>
1258 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1259 \begin_inset Text
1260
1261 \layout Standard
1262
1263 7
1264 \end_inset 
1265 </cell>
1266 </row>
1267 <row topline="true">
1268 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1269 \begin_inset Text
1270
1271 \layout Standard
1272
1273 Innovation gain
1274 \end_inset 
1275 </cell>
1276 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1277 \begin_inset Text
1278
1279 \layout Standard
1280
1281 sub-frame
1282 \end_inset 
1283 </cell>
1284 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1285 \begin_inset Text
1286
1287 \layout Standard
1288
1289 0
1290 \end_inset 
1291 </cell>
1292 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1293 \begin_inset Text
1294
1295 \layout Standard
1296
1297 1
1298 \end_inset 
1299 </cell>
1300 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1301 \begin_inset Text
1302
1303 \layout Standard
1304
1305 0
1306 \end_inset 
1307 </cell>
1308 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1309 \begin_inset Text
1310
1311 \layout Standard
1312
1313 1
1314 \end_inset 
1315 </cell>
1316 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1317 \begin_inset Text
1318
1319 \layout Standard
1320
1321 1
1322 \end_inset 
1323 </cell>
1324 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1325 \begin_inset Text
1326
1327 \layout Standard
1328
1329 3
1330 \end_inset 
1331 </cell>
1332 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1333 \begin_inset Text
1334
1335 \layout Standard
1336
1337 3
1338 \end_inset 
1339 </cell>
1340 </row>
1341 <row topline="true" bottomline="true">
1342 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1343 \begin_inset Text
1344
1345 \layout Standard
1346
1347 Innovation VQ
1348 \end_inset 
1349 </cell>
1350 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1351 \begin_inset Text
1352
1353 \layout Standard
1354
1355 sub-frame
1356 \end_inset 
1357 </cell>
1358 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1359 \begin_inset Text
1360
1361 \layout Standard
1362
1363 0
1364 \end_inset 
1365 </cell>
1366 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1367 \begin_inset Text
1368
1369 \layout Standard
1370
1371 0
1372 \end_inset 
1373 </cell>
1374 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1375 \begin_inset Text
1376
1377 \layout Standard
1378
1379 16
1380 \end_inset 
1381 </cell>
1382 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1383 \begin_inset Text
1384
1385 \layout Standard
1386
1387 20
1388 \end_inset 
1389 </cell>
1390 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1391 \begin_inset Text
1392
1393 \layout Standard
1394
1395 35
1396 \end_inset 
1397 </cell>
1398 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1399 \begin_inset Text
1400
1401 \layout Standard
1402
1403 48
1404 \end_inset 
1405 </cell>
1406 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1407 \begin_inset Text
1408
1409 \layout Standard
1410
1411 64
1412 \end_inset 
1413 </cell>
1414 </row>
1415 <row topline="true" bottomline="true">
1416 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1417 \begin_inset Text
1418
1419 \layout Standard
1420
1421 Total
1422 \end_inset 
1423 </cell>
1424 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1425 \begin_inset Text
1426
1427 \layout Standard
1428
1429 frame
1430 \end_inset 
1431 </cell>
1432 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1433 \begin_inset Text
1434
1435 \layout Standard
1436
1437 5
1438 \end_inset 
1439 </cell>
1440 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1441 \begin_inset Text
1442
1443 \layout Standard
1444
1445 43
1446 \end_inset 
1447 </cell>
1448 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1449 \begin_inset Text
1450
1451 \layout Standard
1452
1453 119
1454 \end_inset 
1455 </cell>
1456 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1457 \begin_inset Text
1458
1459 \layout Standard
1460
1461 160
1462 \end_inset 
1463 </cell>
1464 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1465 \begin_inset Text
1466
1467 \layout Standard
1468
1469 220
1470 \end_inset 
1471 </cell>
1472 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1473 \begin_inset Text
1474
1475 \layout Standard
1476
1477 300
1478 \end_inset 
1479 </cell>
1480 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1481 \begin_inset Text
1482
1483 \layout Standard
1484
1485 364
1486 \end_inset 
1487 </cell>
1488 </row>
1489 </lyxtabular>
1490
1491 \end_inset 
1492
1493
1494 \layout Caption
1495
1496 Bit allocation for narrowband modes
1497 \begin_inset LatexCommand \label{cap:bits-narrowband}
1498
1499 \end_inset 
1500
1501
1502 \end_inset 
1503
1504
1505 \layout Standard
1506
1507 So far, no MOS (mean opinion score) subjective evaluation has been performed
1508  for Speex.
1509  In order to give an idea of the quality achivable with it, table 
1510 \begin_inset LatexCommand \ref{cap:quality_vs_bps}
1511
1512 \end_inset 
1513
1514  presents my own subjective opinion on it.
1515  It sould be noted that different people will perceive the quality differently
1516  and that the person that designed the codec often has a bias (one way or
1517  another) when it comes to subjective evaluation.
1518  Last thing, it should be noted that for most codecs (including Speex) encoding
1519  quality sometimes varies depending on the input.
1520 \layout Standard
1521
1522
1523 \begin_inset Float table
1524 placement htbp
1525 wide true
1526 collapsed false
1527
1528 \layout Standard
1529
1530
1531 \begin_inset  Tabular
1532 <lyxtabular version="3" rows="8" columns="3">
1533 <features>
1534 <column alignment="center" valignment="top" leftline="true" width="0pt">
1535 <column alignment="center" valignment="top" leftline="true" width="0pt">
1536 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
1537 <row topline="true" bottomline="true">
1538 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1539 \begin_inset Text
1540
1541 \layout Standard
1542
1543 Mode
1544 \end_inset 
1545 </cell>
1546 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1547 \begin_inset Text
1548
1549 \layout Standard
1550
1551 Bitrate (bps)
1552 \end_inset 
1553 </cell>
1554 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1555 \begin_inset Text
1556
1557 \layout Standard
1558
1559 Quality
1560 \end_inset 
1561 </cell>
1562 </row>
1563 <row topline="true">
1564 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1565 \begin_inset Text
1566
1567 \layout Standard
1568
1569 0
1570 \end_inset 
1571 </cell>
1572 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1573 \begin_inset Text
1574
1575 \layout Standard
1576
1577 250
1578 \end_inset 
1579 </cell>
1580 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1581 \begin_inset Text
1582
1583 \layout Standard
1584
1585 No sound (VBR only)
1586 \end_inset 
1587 </cell>
1588 </row>
1589 <row topline="true">
1590 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1591 \begin_inset Text
1592
1593 \layout Standard
1594
1595 1
1596 \end_inset 
1597 </cell>
1598 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1599 \begin_inset Text
1600
1601 \layout Standard
1602
1603 2,150
1604 \end_inset 
1605 </cell>
1606 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1607 \begin_inset Text
1608
1609 \layout Standard
1610
1611 Comfort noise only (VBR only)
1612 \end_inset 
1613 </cell>
1614 </row>
1615 <row topline="true">
1616 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1617 \begin_inset Text
1618
1619 \layout Standard
1620
1621 2
1622 \end_inset 
1623 </cell>
1624 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1625 \begin_inset Text
1626
1627 \layout Standard
1628
1629 5,950
1630 \end_inset 
1631 </cell>
1632 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1633 \begin_inset Text
1634
1635 \layout Standard
1636
1637 Very noticeable artifacts/noise, good intelligibility
1638 \end_inset 
1639 </cell>
1640 </row>
1641 <row topline="true">
1642 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1643 \begin_inset Text
1644
1645 \layout Standard
1646
1647 3
1648 \end_inset 
1649 </cell>
1650 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1651 \begin_inset Text
1652
1653 \layout Standard
1654
1655 8,000
1656 \end_inset 
1657 </cell>
1658 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1659 \begin_inset Text
1660
1661 \layout Standard
1662
1663 Artifacts/noise sometimes noticeable
1664 \end_inset 
1665 </cell>
1666 </row>
1667 <row topline="true">
1668 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1669 \begin_inset Text
1670
1671 \layout Standard
1672
1673 4
1674 \end_inset 
1675 </cell>
1676 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1677 \begin_inset Text
1678
1679 \layout Standard
1680
1681 11,000
1682 \end_inset 
1683 </cell>
1684 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1685 \begin_inset Text
1686
1687 \layout Standard
1688
1689 Artifacts usually noticeable only with headphones
1690 \end_inset 
1691 </cell>
1692 </row>
1693 <row topline="true">
1694 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1695 \begin_inset Text
1696
1697 \layout Standard
1698
1699 5
1700 \end_inset 
1701 </cell>
1702 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1703 \begin_inset Text
1704
1705 \layout Standard
1706
1707 15,000
1708 \end_inset 
1709 </cell>
1710 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1711 \begin_inset Text
1712
1713 \layout Standard
1714
1715 Need good headphones to tell the difference
1716 \end_inset 
1717 </cell>
1718 </row>
1719 <row topline="true" bottomline="true">
1720 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1721 \begin_inset Text
1722
1723 \layout Standard
1724
1725 6
1726 \end_inset 
1727 </cell>
1728 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1729 \begin_inset Text
1730
1731 \layout Standard
1732
1733 18,200
1734 \end_inset 
1735 </cell>
1736 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1737 \begin_inset Text
1738
1739 \layout Standard
1740
1741 Hard to tell the difference even with good headphones
1742 \end_inset 
1743 </cell>
1744 </row>
1745 </lyxtabular>
1746
1747 \end_inset 
1748
1749
1750 \layout Caption
1751
1752 Quality versus bit-rate
1753 \begin_inset LatexCommand \label{cap:quality_vs_bps}
1754
1755 \end_inset 
1756
1757
1758 \end_inset 
1759
1760
1761 \layout Subsection
1762
1763 Perceptual enhancement
1764 \layout Standard
1765
1766 This part of the codec only applies to the decoder and can even be changed
1767  without affecting inter-operability.
1768  For that reason, the implementation provided and described here should
1769  only be considered as a reference implementation.
1770  The enhancement system is devided in two parts.
1771  First, the synthesis filter 
1772 \begin_inset Formula $S(z)=1/A(z)$
1773 \end_inset 
1774
1775  is replaced by an enhanced filter
1776 \begin_inset Formula \[
1777 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)}\]
1778
1779 \end_inset 
1780
1781 where 
1782 \begin_inset Formula $a_{1}$
1783 \end_inset 
1784
1785  and 
1786 \begin_inset Formula $a_{2}$
1787 \end_inset 
1788
1789  depend on the mode in use and 
1790 \begin_inset Formula $a_{3}=\frac{1}{r}\left(1-\frac{1-ra_{1}}{1-ra_{2}}\right)$
1791 \end_inset 
1792
1793  with 
1794 \begin_inset Formula $r=.9$
1795 \end_inset 
1796
1797 .
1798  The second part of the enhancement consists of using a comb filter to enhance
1799  the pitch in the excitation.
1800  
1801 \layout Section
1802 \pagebreak_top 
1803 Speex wideband mode (sub-band CELP)
1804 \layout Standard
1805
1806 For wideband, the Speex approach uses a 
1807 \emph on 
1808 q
1809 \emph default 
1810 uadrature 
1811 \emph on 
1812 m
1813 \emph default 
1814 irror 
1815 \emph on 
1816 f
1817 \emph default 
1818 ilter (QMF) to split the band in two.
1819  The 16 kHz signal is thus divided into two 8 kHz signals, one representing
1820  the low band (0-4 kHz), the other the high band (4-8 kHz).
1821  The low band is encoded with the narrowband mode described in section 
1822 \begin_inset LatexCommand \ref{sec:Speex-narrowband-mode}
1823
1824 \end_inset 
1825
1826  in such a way that the resulting 
1827 \begin_inset Quotes eld
1828 \end_inset 
1829
1830 embedded narrowband bit-stream
1831 \begin_inset Quotes erd
1832 \end_inset 
1833
1834  can also be decoded with the narrowband decoder.
1835  Since the low band encoding has already been described only the high band
1836  encoding is described in this section.
1837 \layout Subsection
1838
1839 Linear Prediction
1840 \layout Standard
1841
1842 The linear prediction part used for the high-band is very similar to what
1843  is done for narrowband.
1844  The only difference is that we use only 12 bits to encode the high-band
1845  LSP's.
1846 \layout Subsection
1847
1848 Pitch Prediction
1849 \layout Standard
1850
1851 That part is easy: there's no pitch prediction for the high-band.
1852  There are two reasons for that.
1853  First, there is usually little harmonic structure in this band (above 4
1854  kHz).
1855  Second, it would be very hard to implement since the QMF folds the 4-8
1856  kHz band into 4-0 kHz (reversing the frequency axis), which means that
1857  the location of the harmonics are no longer at multiples of the fundamental
1858  (pitch).
1859 \layout Subsection
1860
1861 Excitation Quantization
1862 \layout Standard
1863
1864 The high-band excitation is coded in the same way as for narrowband.
1865  
1866 \layout Subsection
1867
1868 Bit allocation
1869 \layout Standard
1870
1871 For the wideband mode, all the narrowband frame is packed before the high-band
1872  is encoded.
1873  The narrowband part of the bit-stream is as defined in table 
1874 \begin_inset LatexCommand \ref{cap:bits-narrowband}
1875
1876 \end_inset 
1877
1878 .
1879  The high-band follows, as described in table 
1880 \begin_inset LatexCommand \ref{cap:bits-wideband}
1881
1882 \end_inset 
1883
1884 .
1885  This also means that a wideband frame may be correctly decoded by a narrowband
1886  decoder with the only caveat that if more than one frame is packed in the
1887  same packet, the decoder will need to skip the high-band parts in order
1888  to sync with the bit-stream.
1889 \layout Standard
1890
1891
1892 \begin_inset Float table
1893 placement htbp
1894 wide true
1895 collapsed false
1896
1897 \layout Standard
1898
1899
1900 \begin_inset  Tabular
1901 <lyxtabular version="3" rows="7" columns="6">
1902 <features>
1903 <column alignment="center" valignment="top" leftline="true" width="0pt">
1904 <column alignment="center" valignment="top" leftline="true" width="0pt">
1905 <column alignment="center" valignment="top" leftline="true" width="0pt">
1906 <column alignment="center" valignment="top" leftline="true" width="0pt">
1907 <column alignment="center" valignment="top" leftline="true" width="0pt">
1908 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
1909 <row topline="true" bottomline="true">
1910 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1911 \begin_inset Text
1912
1913 \layout Standard
1914
1915 Parameter
1916 \end_inset 
1917 </cell>
1918 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1919 \begin_inset Text
1920
1921 \layout Standard
1922
1923 Update rate
1924 \end_inset 
1925 </cell>
1926 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1927 \begin_inset Text
1928
1929 \layout Standard
1930
1931 0
1932 \end_inset 
1933 </cell>
1934 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1935 \begin_inset Text
1936
1937 \layout Standard
1938
1939 1
1940 \end_inset 
1941 </cell>
1942 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1943 \begin_inset Text
1944
1945 \layout Standard
1946
1947 2
1948 \end_inset 
1949 </cell>
1950 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1951 \begin_inset Text
1952
1953 \layout Standard
1954
1955 3
1956 \end_inset 
1957 </cell>
1958 </row>
1959 <row topline="true">
1960 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1961 \begin_inset Text
1962
1963 \layout Standard
1964
1965 Wideband bit
1966 \end_inset 
1967 </cell>
1968 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1969 \begin_inset Text
1970
1971 \layout Standard
1972
1973 frame
1974 \end_inset 
1975 </cell>
1976 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1977 \begin_inset Text
1978
1979 \layout Standard
1980
1981 1
1982 \end_inset 
1983 </cell>
1984 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1985 \begin_inset Text
1986
1987 \layout Standard
1988
1989 1
1990 \end_inset 
1991 </cell>
1992 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1993 \begin_inset Text
1994
1995 \layout Standard
1996
1997 1
1998 \end_inset 
1999 </cell>
2000 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2001 \begin_inset Text
2002
2003 \layout Standard
2004
2005 1
2006 \end_inset 
2007 </cell>
2008 </row>
2009 <row topline="true">
2010 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2011 \begin_inset Text
2012
2013 \layout Standard
2014
2015 Mode ID
2016 \end_inset 
2017 </cell>
2018 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2019 \begin_inset Text
2020
2021 \layout Standard
2022
2023 frame
2024 \end_inset 
2025 </cell>
2026 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2027 \begin_inset Text
2028
2029 \layout Standard
2030
2031 3
2032 \end_inset 
2033 </cell>
2034 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2035 \begin_inset Text
2036
2037 \layout Standard
2038
2039 3
2040 \end_inset 
2041 </cell>
2042 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2043 \begin_inset Text
2044
2045 \layout Standard
2046
2047 3
2048 \end_inset 
2049 </cell>
2050 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2051 \begin_inset Text
2052
2053 \layout Standard
2054
2055 3
2056 \end_inset 
2057 </cell>
2058 </row>
2059 <row topline="true">
2060 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2061 \begin_inset Text
2062
2063 \layout Standard
2064
2065 LSP
2066 \end_inset 
2067 </cell>
2068 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2069 \begin_inset Text
2070
2071 \layout Standard
2072
2073 frame
2074 \end_inset 
2075 </cell>
2076 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2077 \begin_inset Text
2078
2079 \layout Standard
2080
2081 0
2082 \end_inset 
2083 </cell>
2084 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2085 \begin_inset Text
2086
2087 \layout Standard
2088
2089 12
2090 \end_inset 
2091 </cell>
2092 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2093 \begin_inset Text
2094
2095 \layout Standard
2096
2097 12
2098 \end_inset 
2099 </cell>
2100 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2101 \begin_inset Text
2102
2103 \layout Standard
2104
2105 12
2106 \end_inset 
2107 </cell>
2108 </row>
2109 <row topline="true">
2110 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2111 \begin_inset Text
2112
2113 \layout Standard
2114
2115 Excitation gain
2116 \end_inset 
2117 </cell>
2118 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2119 \begin_inset Text
2120
2121 \layout Standard
2122
2123 sub-frame
2124 \end_inset 
2125 </cell>
2126 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2127 \begin_inset Text
2128
2129 \layout Standard
2130
2131 0
2132 \end_inset 
2133 </cell>
2134 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2135 \begin_inset Text
2136
2137 \layout Standard
2138
2139 5
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 4
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 4
2156 \end_inset 
2157 </cell>
2158 </row>
2159 <row topline="true" bottomline="true">
2160 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2161 \begin_inset Text
2162
2163 \layout Standard
2164
2165 Excitation VQ
2166 \end_inset 
2167 </cell>
2168 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2169 \begin_inset Text
2170
2171 \layout Standard
2172
2173 sub-frame
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 0
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 0
2190 \end_inset 
2191 </cell>
2192 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2193 \begin_inset Text
2194
2195 \layout Standard
2196
2197 20
2198 \end_inset 
2199 </cell>
2200 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2201 \begin_inset Text
2202
2203 \layout Standard
2204
2205 40
2206 \end_inset 
2207 </cell>
2208 </row>
2209 <row topline="true" bottomline="true">
2210 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2211 \begin_inset Text
2212
2213 \layout Standard
2214
2215 Total
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 frame
2224 \end_inset 
2225 </cell>
2226 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2227 \begin_inset Text
2228
2229 \layout Standard
2230
2231 4
2232 \end_inset 
2233 </cell>
2234 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2235 \begin_inset Text
2236
2237 \layout Standard
2238
2239 36
2240 \end_inset 
2241 </cell>
2242 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2243 \begin_inset Text
2244
2245 \layout Standard
2246
2247 112
2248 \end_inset 
2249 </cell>
2250 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2251 \begin_inset Text
2252
2253 \layout Standard
2254
2255 192
2256 \end_inset 
2257 </cell>
2258 </row>
2259 </lyxtabular>
2260
2261 \end_inset 
2262
2263
2264 \layout Caption
2265
2266 Bit allocation for high-band in wideband mode
2267 \begin_inset LatexCommand \label{cap:bits-wideband}
2268
2269 \end_inset 
2270
2271
2272 \end_inset 
2273
2274
2275 \layout Section
2276
2277 Command-line encoder/decoder
2278 \layout Standard
2279
2280 The base Speex distribution includes a command-line encoder (
2281 \emph on 
2282 speexenc
2283 \emph default 
2284 ) and decoder (
2285 \emph on 
2286 speexdec
2287 \emph default 
2288 ).
2289 \layout Subsection
2290
2291
2292 \emph on 
2293 speexenc
2294 \layout Standard
2295
2296 The encoder takes the following options:
2297 \layout Description
2298
2299 --narrowband\SpecialChar ~
2300 (-n) Tells Speex to treat the input as narrowband (8 kHz).
2301  This is the default
2302 \layout Description
2303
2304 --wideband\SpecialChar ~
2305 (-w) Tells Speex to treat the input as wideband (16 kHz)
2306 \layout Description
2307
2308 --quality\SpecialChar ~
2309 n Set the encoding quality (0-10)
2310 \layout Description
2311
2312 --vbr Enable VBR (Variable Bit-Rate), disabled by default
2313 \layout Description
2314
2315 --nframes\SpecialChar ~
2316 n Pack n frames in each Ogg packet (this saves space at low bit-rates)
2317 \layout Description
2318
2319 --comp\SpecialChar ~
2320 n Set encoding speed/quality tradeoff.
2321  The higher the value of n, the slower the encoding (default is 3)
2322 \layout Description
2323
2324 -V Verbose operation, print bit-rate currently in use
2325 \layout Description
2326
2327 --help\SpecialChar ~
2328 (-h) Print the help
2329 \layout Description
2330
2331 --version\SpecialChar ~
2332 (-v) Pring version information
2333 \layout Subsection
2334
2335
2336 \emph on 
2337 speexdec
2338 \layout Standard
2339
2340 The decoder takes the following options:
2341 \layout Description
2342
2343 --enh enable post-filter
2344 \layout Description
2345
2346 --no-enh disable post-filter (default)
2347 \layout Description
2348
2349 -V Verbose operation, print bit-rate currently in use
2350 \layout Description
2351
2352 --help\SpecialChar ~
2353 (-h) Print the help
2354 \layout Description
2355
2356 --version\SpecialChar ~
2357 (-v) Pring version information
2358 \layout Section
2359 \pagebreak_top 
2360 Programming with Speex (the libspeex API)
2361 \layout Subsection
2362
2363 Encoding
2364 \layout Standard
2365
2366 In order to encode speech using Speex, you first need to:
2367 \layout LyX-Code
2368
2369 #include <speex.h>
2370 \layout Standard
2371
2372 You then need to declare a Speex bit-packing struct
2373 \layout LyX-Code
2374
2375 SpeexBits bits;
2376 \layout Standard
2377
2378 and a Speex encoder state
2379 \layout LyX-Code
2380
2381 void *enc_state;
2382 \layout Standard
2383
2384 The two are initialized by:
2385 \layout LyX-Code
2386
2387 speex_bits_init(&bits);
2388 \layout LyX-Code
2389
2390 enc_state = speex_encoder_init(&speex_nb_mode);
2391 \layout Standard
2392
2393 For wideband coding, 
2394 \emph on 
2395 speex_nb_mode
2396 \emph default 
2397  will be replaced by 
2398 \emph on 
2399 speex_wb_mode
2400 \emph default 
2401 .
2402  In most cases, you will need to know the frame size used by the mode you
2403  are using.
2404  You can get that value in the 
2405 \emph on 
2406 frame_size
2407 \emph default 
2408  variable with:
2409 \layout LyX-Code
2410
2411 speex_encoder_ctl(enc_state,SPEEX_GET_FRAME_SIZE,&frame_size);
2412 \layout Standard
2413
2414 Once the initialization is done, for every input frame:
2415 \layout LyX-Code
2416
2417 speex_bits_reset(&bits);
2418 \layout LyX-Code
2419
2420 speex_encode(enc_state, input_frame, &bits);
2421 \layout LyX-Code
2422
2423 nbBytes = speex_bits_write(&bits, byte_ptr, MAX_NB_BYTES);
2424 \layout Standard
2425
2426 where 
2427 \emph on 
2428 input_frame
2429 \emph default 
2430  is a 
2431 \emph on 
2432 (float *)
2433 \emph default 
2434  pointing to the beginning of a speech frame, 
2435 \emph on 
2436 byte_ptr
2437 \emph default 
2438  is a 
2439 \emph on 
2440 (char *)
2441 \emph default 
2442  where the encoded frame will be written, 
2443 \emph on 
2444 MAX_NB_BYTES
2445 \emph default 
2446  is the maximum number of bytes that can be written to 
2447 \emph on 
2448 byte_ptr
2449 \emph default 
2450  without causing an overflow and 
2451 \emph on 
2452 nbBytes
2453 \emph default 
2454  is the number of bytes actually written to 
2455 \emph on 
2456 byte_ptr
2457 \emph default 
2458  (the encoded size in bytes).
2459  Before calling speex_bits_write, it is possible to find the number of bytes
2460  that need to be written by calling 
2461 \family typewriter 
2462 speex_bits_nbytes(&bits)
2463 \family default 
2464 , which returns a number of bytes.
2465  
2466 \layout Standard
2467
2468 After you're done with the encoding, free all resources with:
2469 \layout LyX-Code
2470
2471 speex_bits_destroy(&bits);
2472 \layout LyX-Code
2473
2474 speex_encoder_destroy(enc_state);
2475 \layout Standard
2476
2477 That's about it for the encoder.
2478  
2479 \layout Subsection
2480
2481 Decoding
2482 \layout Standard
2483
2484 In order to encode speech using Speex, you first need to:
2485 \layout LyX-Code
2486
2487 #include <speex.h>
2488 \layout Standard
2489
2490 You then need to declare a Speex bit-packing struct
2491 \layout LyX-Code
2492
2493 SpeexBits bits;
2494 \layout Standard
2495
2496 and a Speex encoder state
2497 \layout LyX-Code
2498
2499 void *dec_state;
2500 \layout Standard
2501
2502 The two are initialized by:
2503 \layout LyX-Code
2504
2505 speex_bits_init(&bits);
2506 \layout LyX-Code
2507
2508 dec_state = speex_decoder_init(&speex_nb_mode);
2509 \layout Standard
2510
2511 For wideband decoding, 
2512 \emph on 
2513 speex_nb_mode
2514 \emph default 
2515  will be replaced by 
2516 \emph on 
2517 speex_wb_mode
2518 \emph default 
2519 .
2520  You can get that value in the 
2521 \emph on 
2522 frame_size
2523 \emph default 
2524  variable with:
2525 \layout LyX-Code
2526
2527 speex_decoder_ctl(dec_state, SPEEX_GET_FRAME_SIZE, &frame_size); 
2528 \layout Standard
2529
2530 There is also a parameter that can be set for the decoder: whether or not
2531  to use a perceptual post-filter.
2532  This can be set by: 
2533 \layout LyX-Code
2534
2535 speex_decoder_ctl(dec_state, SPEEX_SET_PF, &pf); 
2536 \layout Standard
2537
2538 where pf is an int that with value 0 to have the post-filter disabled and
2539  1 to have it enabled.
2540 \layout Standard
2541
2542 Again, once the decoder initialization is done, for every input frame:
2543 \layout LyX-Code
2544
2545 speex_bits_read_from(&bits, input_bytes, nbBytes);
2546 \layout LyX-Code
2547
2548 speex_decode(st, &bits, output_frame, 0);
2549 \layout Standard
2550
2551 where input_bytes is a 
2552 \emph on 
2553 (char *)
2554 \emph default 
2555  containing the bit-stream data received for a frame, 
2556 \emph on 
2557 nbBytes
2558 \emph default 
2559  is the size (in bytes) of that bit-stream, and 
2560 \emph on 
2561 output_frame
2562 \emph default 
2563  is a 
2564 \emph on 
2565 (float *)
2566 \emph default 
2567  and points to the area where the decoded speech frame will be written.
2568  The last argument indicates whether the frame we'd like to decode was lost.
2569  A value of 0 indicates the normal case where bits points to the bit of
2570  the current frame.
2571  A value of 1 indicates that we don't have the bits for the current frame,
2572  in which case the bits argument should be the same as the bits for the
2573  last correctly received frame.
2574  When a frame is lost, the Speex decoder will do its best to "guess" the
2575  correct signal.
2576 \layout Standard
2577
2578 After you're done with the decoding, free all resources with:
2579 \layout LyX-Code
2580
2581 speex_bits_destroy(&bits);
2582 \layout LyX-Code
2583
2584 speex_decoder_destroy(dec_state);
2585 \layout Subsection
2586
2587 Codec Options (speex_*_ctl)
2588 \layout Standard
2589
2590 The Speex encoder and decoder support many options and requests that can
2591  be accessed through the 
2592 \emph on 
2593 speex_encoder_ctl
2594 \emph default 
2595  and 
2596 \emph on 
2597 speex_decoder_ctl
2598 \emph default 
2599  functions.
2600  These functions are similar the the 
2601 \emph on 
2602 ioctl
2603 \emph default 
2604  system call and their prototypes are:
2605 \layout LyX-Code
2606
2607 void speex_encoder_ctl(void *encoder, int request, void *ptr);
2608 \layout LyX-Code
2609
2610 void speex_decoder_ctl(void *encoder, int request, void *ptr);
2611 \layout Standard
2612
2613 The different values of request allowed are (note that some only apply to
2614  the encoder or the decoder):
2615 \layout Description
2616
2617 SPEEX_SET_ENH** Set post-filter to on (1) or off (0) (integer)
2618 \layout Description
2619
2620 SPEEX_GET_ENH** Get post-filter status (integer)
2621 \layout Description
2622
2623 SPEEX_GET_FRAME_SIZE Get the frame size used for the current mode (integer)
2624 \layout Description
2625
2626 SPEEX_SET_QUALITY* Set the encoder speech quality (integer 0 to 10)
2627 \layout Description
2628
2629 SPEEX_GET_QUALITY* Get the current encoder speech quality (integer 0 to
2630  10)
2631 \layout Description
2632
2633 SPEEX_SET_MODE*
2634 \begin_inset Formula $\dagger $
2635 \end_inset 
2636
2637
2638 \layout Description
2639
2640 SPEEX_GET_MODE*
2641 \begin_inset Formula $\dagger $
2642 \end_inset 
2643
2644
2645 \layout Description
2646
2647 SPEEX_SET_LOW_MODE*
2648 \begin_inset Formula $\dagger $
2649 \end_inset 
2650
2651
2652 \layout Description
2653
2654 SPEEX_GET_LOW_MODE*
2655 \begin_inset Formula $\dagger $
2656 \end_inset 
2657
2658
2659 \layout Description
2660
2661 SPEEX_SET_HIGH_MODE*
2662 \begin_inset Formula $\dagger $
2663 \end_inset 
2664
2665
2666 \layout Description
2667
2668 SPEEX_GET_HIGH_MODE*
2669 \begin_inset Formula $\dagger $
2670 \end_inset 
2671
2672
2673 \layout Description
2674
2675 SPEEX_SET_VBR* Set variable bit-rate (VBR) to on (1) or off (0) (integer)
2676 \layout Description
2677
2678 SPEEX_GET_VBR* Get variable bit-rate (VBR) status (integer)
2679 \layout Description
2680
2681 SPEEX_SET_VBR_QUALITY* Set the encoder VBR speech quality (integer 0 to
2682  10)
2683 \layout Description
2684
2685 SPEEX_GET_VBR_QUALITY* Get the current encoder VBR speech quality (integer
2686  0 to 10)
2687 \layout Description
2688
2689 SPEEX_SET_COMPLEXITY* Set the CPU resources allowed for the encoder
2690 \layout Description
2691
2692 SPEEX_GET_COMPLEXITY* Get the CPU resources allowed for the encoder
2693 \layout Description
2694
2695 SPEEX_GET_BITRATE Get the current bit-rate in use (in bps)
2696 \layout Description
2697
2698 * applies only to the encoder
2699 \layout Description
2700
2701 ** applies only to the decoder
2702 \layout Description
2703
2704
2705 \begin_inset Formula $\dagger $
2706 \end_inset 
2707
2708  normally only used internally
2709 \layout Subsection
2710
2711 Packing more than one frame per packet
2712 \layout Standard
2713
2714 Sometimes it is desirable to pack more than one frame per packet (or other
2715  basic unit of storage).
2716  The proper way to do it is to call speex_encode 
2717 \begin_inset Formula $N$
2718 \end_inset 
2719
2720  times before writing the stream with speex_bits_write.
2721 \layout Section
2722 \pagebreak_top 
2723 Formats and standards
2724 \layout Standard
2725
2726 Speex can encode speech in both narrowband and wideband and provides different
2727  bit-rates.
2728  However not all features must be supported by a certain implementation
2729  or device.
2730  In order to be said 
2731 \begin_inset Quotes eld
2732 \end_inset 
2733
2734 Speex compatible
2735 \begin_inset Quotes erd
2736 \end_inset 
2737
2738 , an implementation must implement at least a basic set of features.
2739 \layout Standard
2740
2741 At the minimum, all narrowband and wideband modes of operation MUST be supported
2742  at the decoder.
2743  For wideband, a decoder MAY either be able to decode all modes or be able
2744  to decode the embedded narrowband part of all modes (which includes ignoring
2745  the high-band bits).
2746 \layout Standard
2747
2748 For encoders, at least one narrowband and one wideband mode MUST be supported.
2749  Note that the wideband mode MAY be the 
2750 \begin_inset Quotes eld
2751 \end_inset 
2752
2753 null highband
2754 \begin_inset Quotes erd
2755 \end_inset 
2756
2757  mode
2758 \begin_inset Foot
2759 collapsed true
2760
2761 \layout Standard
2762
2763 This can be done by appending 4 zero bits at the end of a narrowband frame
2764 \end_inset 
2765
2766 .
2767  The main reason why all encoding modes do not have to be supported is that
2768  some platforms may not be able to handle the complexity of encoding in
2769  some modes.
2770 \layout Subsection
2771
2772 RTP Payload Format
2773 \layout Standard
2774
2775 Since Speex encoded frames already contain mode information, they can be
2776  sent without any other information in an RTP packet.
2777  If more than one frame is transmitted, no byte padding is performed at
2778  the end of frames, except the last one.
2779  The number of frames contained in each packet MUST be transmitted out-of-band.
2780  
2781 \layout Subsection
2782
2783 Ogg file format
2784 \layout Standard
2785
2786 Speex bit-streams can be stored in Ogg files.
2787  In this case, the first packet of the Ogg file contains the Speex header
2788  described in table 
2789 \begin_inset LatexCommand \ref{cap:ogg_speex_header}
2790
2791 \end_inset 
2792
2793 .
2794  All integer fields in the headers are stored as little-endian.
2795  The 
2796 \family typewriter 
2797 speex_string
2798 \family default 
2799  field must contain the 
2800 \begin_inset Quotes eld
2801 \end_inset 
2802
2803
2804 \family typewriter 
2805 Speex
2806 \family default 
2807 \SpecialChar ~
2808 \SpecialChar ~
2809 \SpecialChar ~
2810
2811 \begin_inset Quotes eld
2812 \end_inset 
2813
2814  (with 3 training spaces), which identifies the bit-stream.
2815  The next field, 
2816 \family typewriter 
2817 speex_version
2818 \family default 
2819  contains the version of Speex that encoded the file.
2820  For now, refer to speex_header.[ch] for more info.
2821  The 
2822 \emph on 
2823 beginning of stream
2824 \emph default 
2825  (
2826 \family typewriter 
2827 b_o_s
2828 \family default 
2829 ) flag is set to 1 for the header.
2830  The header packet has 
2831 \family typewriter 
2832 packetno=0
2833 \family default 
2834  and 
2835 \family typewriter 
2836 granulepos=0
2837 \family default 
2838 .
2839 \layout Standard
2840
2841 The second packet contains a user-comment string, without terminating null.
2842  The content/format of the comment string is not defined.
2843  This packet has 
2844 \family typewriter 
2845 packetno=1
2846 \family default 
2847  and 
2848 \family typewriter 
2849 granulepos=0
2850 \family default 
2851 .
2852 \layout Standard
2853
2854 The third and subsequant packets each contain one or more (number found
2855  in header) Speex frames.
2856  These are identified with 
2857 \family typewriter 
2858 packetno
2859 \family default 
2860  starting from 2 and the 
2861 \family typewriter 
2862 granulepos
2863 \family default 
2864  is the number of the first sample encoded in that packet.
2865 \layout Standard
2866
2867 The stream is terminated by a packet containing the string 
2868 \begin_inset Quotes eld
2869 \end_inset 
2870
2871 END OF STREAM
2872 \begin_inset Quotes erd
2873 \end_inset 
2874
2875  (without terminating null).
2876  The 
2877 \emph on 
2878 end of stream
2879 \emph default 
2880  (
2881 \family typewriter 
2882 e_o_s
2883 \family default 
2884 ) flag is set to 1.
2885  The decoder should rely on the 
2886 \family typewriter 
2887 e_o_s
2888 \family default 
2889  flag and 
2890 \emph on 
2891 not
2892 \emph default 
2893  on the content of the packet.
2894 \layout Standard
2895
2896
2897 \begin_inset Float table
2898 placement htbp
2899 wide true
2900 collapsed false
2901
2902 \layout Standard
2903
2904
2905 \begin_inset  Tabular
2906 <lyxtabular version="3" rows="16" columns="3">
2907 <features>
2908 <column alignment="center" valignment="top" leftline="true" width="0pt">
2909 <column alignment="center" valignment="top" leftline="true" width="0pt">
2910 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
2911 <row topline="true" bottomline="true">
2912 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2913 \begin_inset Text
2914
2915 \layout Standard
2916
2917 Field
2918 \end_inset 
2919 </cell>
2920 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2921 \begin_inset Text
2922
2923 \layout Standard
2924
2925 Type
2926 \end_inset 
2927 </cell>
2928 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2929 \begin_inset Text
2930
2931 \layout Standard
2932
2933 Size
2934 \end_inset 
2935 </cell>
2936 </row>
2937 <row topline="true">
2938 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2939 \begin_inset Text
2940
2941 \layout Standard
2942
2943 speex_string
2944 \end_inset 
2945 </cell>
2946 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2947 \begin_inset Text
2948
2949 \layout Standard
2950
2951 char[]
2952 \end_inset 
2953 </cell>
2954 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2955 \begin_inset Text
2956
2957 \layout Standard
2958
2959 8
2960 \end_inset 
2961 </cell>
2962 </row>
2963 <row topline="true">
2964 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2965 \begin_inset Text
2966
2967 \layout Standard
2968
2969 speex_version
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 char[]
2978 \end_inset 
2979 </cell>
2980 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2981 \begin_inset Text
2982
2983 \layout Standard
2984
2985 20
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 speex_header_version
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 int
3004 \end_inset 
3005 </cell>
3006 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3007 \begin_inset Text
3008
3009 \layout Standard
3010
3011 4
3012 \end_inset 
3013 </cell>
3014 </row>
3015 <row topline="true">
3016 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3017 \begin_inset Text
3018
3019 \layout Standard
3020
3021 header_size
3022 \end_inset 
3023 </cell>
3024 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3025 \begin_inset Text
3026
3027 \layout Standard
3028
3029 int
3030 \end_inset 
3031 </cell>
3032 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3033 \begin_inset Text
3034
3035 \layout Standard
3036
3037 4
3038 \end_inset 
3039 </cell>
3040 </row>
3041 <row topline="true">
3042 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3043 \begin_inset Text
3044
3045 \layout Standard
3046
3047 rate
3048 \end_inset 
3049 </cell>
3050 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3051 \begin_inset Text
3052
3053 \layout Standard
3054
3055 int
3056 \end_inset 
3057 </cell>
3058 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3059 \begin_inset Text
3060
3061 \layout Standard
3062
3063 4
3064 \end_inset 
3065 </cell>
3066 </row>
3067 <row topline="true">
3068 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3069 \begin_inset Text
3070
3071 \layout Standard
3072
3073 mode
3074 \end_inset 
3075 </cell>
3076 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3077 \begin_inset Text
3078
3079 \layout Standard
3080
3081 int
3082 \end_inset 
3083 </cell>
3084 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3085 \begin_inset Text
3086
3087 \layout Standard
3088
3089 4
3090 \end_inset 
3091 </cell>
3092 </row>
3093 <row topline="true">
3094 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3095 \begin_inset Text
3096
3097 \layout Standard
3098
3099 mode_bitstream_version
3100 \end_inset 
3101 </cell>
3102 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3103 \begin_inset Text
3104
3105 \layout Standard
3106
3107 int
3108 \end_inset 
3109 </cell>
3110 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3111 \begin_inset Text
3112
3113 \layout Standard
3114
3115 4
3116 \end_inset 
3117 </cell>
3118 </row>
3119 <row topline="true">
3120 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3121 \begin_inset Text
3122
3123 \layout Standard
3124
3125 nb_channels
3126 \end_inset 
3127 </cell>
3128 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3129 \begin_inset Text
3130
3131 \layout Standard
3132
3133 int
3134 \end_inset 
3135 </cell>
3136 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3137 \begin_inset Text
3138
3139 \layout Standard
3140
3141 4
3142 \end_inset 
3143 </cell>
3144 </row>
3145 <row topline="true">
3146 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3147 \begin_inset Text
3148
3149 \layout Standard
3150
3151 bitrate
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 int
3160 \end_inset 
3161 </cell>
3162 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3163 \begin_inset Text
3164
3165 \layout Standard
3166
3167 4
3168 \end_inset 
3169 </cell>
3170 </row>
3171 <row topline="true">
3172 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3173 \begin_inset Text
3174
3175 \layout Standard
3176
3177 frame_size
3178 \end_inset 
3179 </cell>
3180 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3181 \begin_inset Text
3182
3183 \layout Standard
3184
3185 int
3186 \end_inset 
3187 </cell>
3188 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3189 \begin_inset Text
3190
3191 \layout Standard
3192
3193 4
3194 \end_inset 
3195 </cell>
3196 </row>
3197 <row topline="true">
3198 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3199 \begin_inset Text
3200
3201 \layout Standard
3202
3203 vbr
3204 \end_inset 
3205 </cell>
3206 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3207 \begin_inset Text
3208
3209 \layout Standard
3210
3211 int
3212 \end_inset 
3213 </cell>
3214 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3215 \begin_inset Text
3216
3217 \layout Standard
3218
3219 4
3220 \end_inset 
3221 </cell>
3222 </row>
3223 <row topline="true">
3224 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3225 \begin_inset Text
3226
3227 \layout Standard
3228
3229 frames_per_packet
3230 \end_inset 
3231 </cell>
3232 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3233 \begin_inset Text
3234
3235 \layout Standard
3236
3237 int
3238 \end_inset 
3239 </cell>
3240 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3241 \begin_inset Text
3242
3243 \layout Standard
3244
3245 4
3246 \end_inset 
3247 </cell>
3248 </row>
3249 <row topline="true">
3250 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3251 \begin_inset Text
3252
3253 \layout Standard
3254
3255 reserved1
3256 \end_inset 
3257 </cell>
3258 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3259 \begin_inset Text
3260
3261 \layout Standard
3262
3263 int
3264 \end_inset 
3265 </cell>
3266 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3267 \begin_inset Text
3268
3269 \layout Standard
3270
3271 4
3272 \end_inset 
3273 </cell>
3274 </row>
3275 <row topline="true">
3276 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3277 \begin_inset Text
3278
3279 \layout Standard
3280
3281 reserved2
3282 \end_inset 
3283 </cell>
3284 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3285 \begin_inset Text
3286
3287 \layout Standard
3288
3289 int
3290 \end_inset 
3291 </cell>
3292 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3293 \begin_inset Text
3294
3295 \layout Standard
3296
3297 4
3298 \end_inset 
3299 </cell>
3300 </row>
3301 <row topline="true" bottomline="true">
3302 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3303 \begin_inset Text
3304
3305 \layout Standard
3306
3307 reserved3
3308 \end_inset 
3309 </cell>
3310 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3311 \begin_inset Text
3312
3313 \layout Standard
3314
3315 int
3316 \end_inset 
3317 </cell>
3318 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3319 \begin_inset Text
3320
3321 \layout Standard
3322
3323 4
3324 \end_inset 
3325 </cell>
3326 </row>
3327 </lyxtabular>
3328
3329 \end_inset 
3330
3331
3332 \layout Caption
3333
3334 Ogg/Speex header packet
3335 \begin_inset LatexCommand \label{cap:ogg_speex_header}
3336
3337 \end_inset 
3338
3339
3340 \end_inset 
3341
3342
3343 \layout Standard
3344
3345
3346 \begin_inset ERT
3347 status Collapsed
3348
3349 \layout Standard
3350
3351 \backslash 
3352 clearpage
3353 \end_inset 
3354
3355
3356 \layout Section
3357 \start_of_appendix 
3358 FAQ
3359 \layout Subsection*
3360
3361 Vorbis is open-source and patent-free, why do we need Speex?
3362 \layout Standard
3363
3364 Vorbis is a great project but its goals are not the same as Speex.
3365  Vorbis is mostly aimed at compressing music and audio in general, while
3366  Speex targets speech only.
3367  For that reason Speex can achieve much better results than Vorbis on speech,
3368  typically 2-4 times higher compression at equal quality.
3369 \layout Subsection*
3370
3371 Can I use Speex for compressing music?
3372 \layout Standard
3373
3374 Just like Vorbis is not really adapted to speech, Speex is really not adapted
3375  for music.
3376  In most cases, you'll be better of with Vorbis when it comes to music.
3377 \layout Subsection*
3378
3379 I converted some MP3's to Speex and the quality is bad.
3380  What's wrong?
3381 \layout Standard
3382
3383 This is called transcoding and it will always result in much poorer quality
3384  than the original MP3.
3385  Unless you have a really good (size) reason to do so, never transcode speech.
3386  This is even valid for self transcoding (tandeming), i.e.
3387  If you decode a Speex file and re-encode it again at the same bit-rate,
3388  you will lose quality.
3389 \layout Subsection*
3390
3391 Why is encoding so slow compared to decoding?
3392 \layout Standard
3393
3394 For most kinds of compression, encoding is inherently slower than decoding.
3395  In the case of Speex, encoding consists of finding, for each vector of
3396  5 to 10 samples, the entry that matches the best within a codebook consisting
3397  of 16 to 256 entries.
3398  On the other hand, at decoding all that needs to be done is lookup the
3399  right entry in the codebook using the encoded index.
3400  Since a lookup is much faster than a search, the decoder works much faster
3401  than the encoder.
3402 \layout Subsection*
3403
3404 Why is Speex so slow on my iPaq (or insert any platform without an FPU)?
3405 \layout Standard
3406
3407 Well the parenthesis provides the answer: no FPU (floating-point unit).
3408  The Speex code makes heavy use of floating-point operations.
3409  On devices with no FPU, all floating-point instructions need to be emulated.
3410  This is a very time consuming operation.
3411 \layout Subsection*
3412
3413 I'm getting unusual background noise (hiss) when using libspeex in my applicatio
3414 n.
3415  How do I fix that?
3416 \layout Standard
3417
3418 One of the cause could be scaling of the input speech.
3419  Speex expects signals to have a 
3420 \begin_inset Formula $\pm 2^{16}$
3421 \end_inset 
3422
3423  (signed short) dynamic range.
3424  If the dynamic range of your signals is too small (e.g.
3425  
3426 \begin_inset Formula $\pm 1.0$
3427 \end_inset 
3428
3429 ), you will suffer important quantization noise.
3430  A good target is to have a dynamic range around 
3431 \begin_inset Formula $\pm 8000$
3432 \end_inset 
3433
3434  which is large enough, but small enough to make sure there's no clipping
3435  when converting back to signed short.
3436 \layout Subsection*
3437
3438 I get very distorted speech when using libspeex in my application.
3439  What's wrong?
3440 \layout Standard
3441
3442 There are many possible causes for that.
3443  One of them is errors in the way the bits are manipulated.
3444  Another possible cause is the use of the same encoder or decoder state
3445  for more than one audio stream (channel), which produces strange effects
3446  with the filter memories.
3447  If the input speech has an amplitude close to 
3448 \begin_inset Formula $2^{16}$
3449 \end_inset 
3450
3451 , it is possible that at decoding, the amplitude be a bit higher than that,
3452  causing clipping when saving as 16-bit PCM.
3453 \layout Subsection*
3454
3455 Can Speex pass DTMF?
3456 \layout Standard
3457
3458 I guess it all depends on the bit-rate used.
3459  Though no formal testing has yet been performed, I'd say don't go below
3460  the 15 kbps mode if you want DTMF to be transmitted correctly.
3461  Also, make sure you don't use the lowest complexity (see SPEEX_SET_COMPLEXITY),
3462  as it causes important noise.
3463 \layout Subsection*
3464
3465 Can Speex pass V.9x modem signals correctly?
3466 \layout Standard
3467
3468 If I could to that I'd be very rich by now :-)
3469 \layout Subsection*
3470
3471 What is your (Jean-Marc) relationship with the University of Sherbrooke
3472  and how does Speex fit into that?
3473 \layout Standard
3474
3475 I am currently (2002/08/13) doing a Ph.D.
3476  at the University of Sherbrooke in mobile robotics.
3477  Although I did my master with the Sherbrooke speech coding group (in speech
3478  enhancement, not coding), I am not associated with them anymore.
3479  It should 
3480 \series bold 
3481 not
3482 \series default 
3483  be understood that they or the University of Sherbrooke endorse the Speex
3484  project in any way.
3485  Furthermore, Speex does not make use of any code or proprietary technology
3486  developed in the Sherbrooke speech coding group.
3487  
3488 \layout Subsection*
3489
3490 CELP, ACELP, what's the difference?
3491 \layout Standard
3492
3493 CELP stands for 
3494 \begin_inset Quotes eld
3495 \end_inset 
3496
3497 Code Excited Linear Prediction
3498 \begin_inset Quotes erd
3499 \end_inset 
3500
3501 , while ACELP stands for 
3502 \begin_inset Quotes eld
3503 \end_inset 
3504
3505
3506 \emph on 
3507 Algebraic
3508 \emph default 
3509  Code Excited Linear Prediction
3510 \begin_inset Quotes erd
3511 \end_inset 
3512
3513 .
3514  That means ACELP is a CELP technique that uses an algebraic codebook represente
3515 d as a sum of unit pulses, thus making the codebook search much more efficient.
3516  This technique was invented at the University of Sherbrooke and is now
3517  one of the most widely used form of CELP.
3518  Unfortunately, since it is patented, it cannot be used in Speex.
3519 \layout Section
3520 \pagebreak_top 
3521 GNU Free Documentation License
3522 \layout Standard
3523
3524 Version 1.1, March 2000
3525 \layout Standard
3526
3527 Copyright (C) 2000 Free Software Foundation, Inc.
3528  59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted
3529  to copy and distribute verbatim copies of this license document, but changing
3530  it is not allowed.
3531  
3532 \layout Subsection*
3533
3534 0.
3535  PREAMBLE
3536 \layout Standard
3537
3538 The purpose of this License is to make a manual, textbook, or other written
3539  document "free" in the sense of freedom: to assure everyone the effective
3540  freedom to copy and redistribute it, with or without modifying it, either
3541  commercially or noncommercially.
3542  Secondarily, this License preserves for the author and publisher a way
3543  to get credit for their work, while not being considered responsible for
3544  modifications made by others.
3545 \layout Standard
3546
3547 This License is a kind of "copyleft", which means that derivative works
3548  of the document must themselves be free in the same sense.
3549  It complements the GNU General Public License, which is a copyleft license
3550  designed for free software.
3551 \layout Standard
3552
3553 We have designed this License in order to use it for manuals for free software,
3554  because free software needs free documentation: a free program should come
3555  with manuals providing the same freedoms that the software does.
3556  But this License is not limited to software manuals; it can be used for
3557  any textual work, regardless of subject matter or whether it is published
3558  as a printed book.
3559  We recommend this License principally for works whose purpose is instruction
3560  or reference.
3561  
3562 \layout Subsection*
3563
3564 1.
3565  APPLICABILITY AND DEFINITIONS
3566 \layout Standard
3567
3568 This License applies to any manual or other work that contains a notice
3569  placed by the copyright holder saying it can be distributed under the terms
3570  of this License.
3571  The "Document", below, refers to any such manual or work.
3572  Any member of the public is a licensee, and is addressed as "you".
3573 \layout Standard
3574
3575 A "Modified Version" of the Document means any work containing the Document
3576  or a portion of it, either copied verbatim, or with modifications and/or
3577  translated into another language.
3578 \layout Standard
3579
3580 A "Secondary Section" is a named appendix or a front-matter section of the
3581  Document that deals exclusively with the relationship of the publishers
3582  or authors of the Document to the Document's overall subject (or to related
3583  matters) and contains nothing that could fall directly within that overall
3584  subject.
3585  (For example, if the Document is in part a textbook of mathematics, a Secondary
3586  Section may not explain any mathematics.) The relationship could be a matter
3587  of historical connection with the subject or with related matters, or of
3588  legal, commercial, philosophical, ethical or political position regarding
3589  them.
3590 \layout Standard
3591
3592 The "Invariant Sections" are certain Secondary Sections whose titles are
3593  designated, as being those of Invariant Sections, in the notice that says
3594  that the Document is released under this License.
3595 \layout Standard
3596
3597 The "Cover Texts" are certain short passages of text that are listed, as
3598  Front-Cover Texts or Back-Cover Texts, in the notice that says that the
3599  Document is released under this License.
3600 \layout Standard
3601
3602 A "Transparent" copy of the Document means a machine-readable copy, represented
3603  in a format whose specification is available to the general public, whose
3604  contents can be viewed and edited directly and straightforwardly with generic
3605  text editors or (for images composed of pixels) generic paint programs
3606  or (for drawings) some widely available drawing editor, and that is suitable
3607  for input to text formatters or for automatic translation to a variety
3608  of formats suitable for input to text formatters.
3609  A copy made in an otherwise Transparent file format whose markup has been
3610  designed to thwart or discourage subsequent modification by readers is
3611  not Transparent.
3612  A copy that is not "Transparent" is called "Opaque".
3613 \layout Standard
3614
3615 Examples of suitable formats for Transparent copies include plain ASCII
3616  without markup, Texinfo input format, LaTeX input format, SGML or XML using
3617  a publicly available DTD, and standard-conforming simple HTML designed
3618  for human modification.
3619  Opaque formats include PostScript, PDF, proprietary formats that can be
3620  read and edited only by proprietary word processors, SGML or XML for which
3621  the DTD and/or processing tools are not generally available, and the machine-ge
3622 nerated HTML produced by some word processors for output purposes only.
3623 \layout Standard
3624
3625 The "Title Page" means, for a printed book, the title page itself, plus
3626  such following pages as are needed to hold, legibly, the material this
3627  License requires to appear in the title page.
3628  For works in formats which do not have any title page as such, "Title Page"
3629  means the text near the most prominent appearance of the work's title,
3630  preceding the beginning of the body of the text.
3631 \layout Subsection*
3632
3633 2.
3634  VERBATIM COPYING
3635 \layout Standard
3636
3637 You may copy and distribute the Document in any medium, either commercially
3638  or noncommercially, provided that this License, the copyright notices,
3639  and the license notice saying this License applies to the Document are
3640  reproduced in all copies, and that you add no other conditions whatsoever
3641  to those of this License.
3642  You may not use technical measures to obstruct or control the reading or
3643  further copying of the copies you make or distribute.
3644  However, you may accept compensation in exchange for copies.
3645  If you distribute a large enough number of copies you must also follow
3646  the conditions in section 3.
3647 \layout Standard
3648
3649 You may also lend copies, under the same conditions stated above, and you
3650  may publicly display copies.
3651 \layout Subsection*
3652
3653 3.
3654  COPYING IN QUANTITY
3655 \layout Standard
3656
3657 If you publish printed copies of the Document numbering more than 100, and
3658  the Document's license notice requires Cover Texts, you must enclose the
3659  copies in covers that carry, clearly and legibly, all these Cover Texts:
3660  Front-Cover Texts on the front cover, and Back-Cover Texts on the back
3661  cover.
3662  Both covers must also clearly and legibly identify you as the publisher
3663  of these copies.
3664  The front cover must present the full title with all words of the title
3665  equally prominent and visible.
3666  You may add other material on the covers in addition.
3667  Copying with changes limited to the covers, as long as they preserve the
3668  title of the Document and satisfy these conditions, can be treated as verbatim
3669  copying in other respects.
3670 \layout Standard
3671
3672 If the required texts for either cover are too voluminous to fit legibly,
3673  you should put the first ones listed (as many as fit reasonably) on the
3674  actual cover, and continue the rest onto adjacent pages.
3675 \layout Standard
3676
3677 If you publish or distribute Opaque copies of the Document numbering more
3678  than 100, you must either include a machine-readable Transparent copy along
3679  with each Opaque copy, or state in or with each Opaque copy a publicly-accessib
3680 le computer-network location containing a complete Transparent copy of the
3681  Document, free of added material, which the general network-using public
3682  has access to download anonymously at no charge using public-standard network
3683  protocols.
3684  If you use the latter option, you must take reasonably prudent steps, when
3685  you begin distribution of Opaque copies in quantity, to ensure that this
3686  Transparent copy will remain thus accessible at the stated location until
3687  at least one year after the last time you distribute an Opaque copy (directly
3688  or through your agents or retailers) of that edition to the public.
3689 \layout Standard
3690
3691 It is requested, but not required, that you contact the authors of the Document
3692  well before redistributing any large number of copies, to give them a chance
3693  to provide you with an updated version of the Document.
3694  
3695 \layout Subsection*
3696
3697 4.
3698  MODIFICATIONS
3699 \layout Standard
3700
3701 You may copy and distribute a Modified Version of the Document under the
3702  conditions of sections 2 and 3 above, provided that you release the Modified
3703  Version under precisely this License, with the Modified Version filling
3704  the role of the Document, thus licensing distribution and modification
3705  of the Modified Version to whoever possesses a copy of it.
3706  In addition, you must do these things in the Modified Version: 
3707 \layout Itemize
3708
3709 A.
3710  Use in the Title Page (and on the covers, if any) a title distinct from
3711  that of the Document, and from those of previous versions (which should,
3712  if there were any, be listed in the History section of the Document).
3713  You may use the same title as a previous version if the original publisher
3714  of that version gives permission.
3715 \layout Itemize
3716
3717 B.
3718  List on the Title Page, as authors, one or more persons or entities responsible
3719  for authorship of the modifications in the Modified Version, together with
3720  at least five of the principal authors of the Document (all of its principal
3721  authors, if it has less than five).
3722 \layout Itemize
3723
3724 C.
3725  State on the Title page the name of the publisher of the Modified Version,
3726  as the publisher.
3727 \layout Itemize
3728
3729 D.
3730  Preserve all the copyright notices of the Document.
3731 \layout Itemize
3732
3733 E.
3734  Add an appropriate copyright notice for your modifications adjacent to
3735  the other copyright notices.
3736 \layout Itemize
3737
3738 F.
3739  Include, immediately after the copyright notices, a license notice giving
3740  the public permission to use the Modified Version under the terms of this
3741  License, in the form shown in the Addendum below.
3742 \layout Itemize
3743
3744 G.
3745  Preserve in that license notice the full lists of Invariant Sections and
3746  required Cover Texts given in the Document's license notice.
3747 \layout Itemize
3748
3749 H.
3750  Include an unaltered copy of this License.
3751 \layout Itemize
3752
3753 I.
3754  Preserve the section entitled "History", and its title, and add to it an
3755  item stating at least the title, year, new authors, and publisher of the
3756  Modified Version as given on the Title Page.
3757  If there is no section entitled "History" in the Document, create one stating
3758  the title, year, authors, and publisher of the Document as given on its
3759  Title Page, then add an item describing the Modified Version as stated
3760  in the previous sentence.
3761 \layout Itemize
3762
3763 J.
3764  Preserve the network location, if any, given in the Document for public
3765  access to a Transparent copy of the Document, and likewise the network
3766  locations given in the Document for previous versions it was based on.
3767  These may be placed in the "History" section.
3768  You may omit a network location for a work that was published at least
3769  four years before the Document itself, or if the original publisher of
3770  the version it refers to gives permission.
3771 \layout Itemize
3772
3773 K.
3774  In any section entitled "Acknowledgements" or "Dedications", preserve the
3775  section's title, and preserve in the section all the substance and tone
3776  of each of the contributor acknowledgements and/or dedications given therein.
3777 \layout Itemize
3778
3779 L.
3780  Preserve all the Invariant Sections of the Document, unaltered in their
3781  text and in their titles.
3782  Section numbers or the equivalent are not considered part of the section
3783  titles.
3784 \layout Itemize
3785
3786 M.
3787  Delete any section entitled "Endorsements".
3788  Such a section may not be included in the Modified Version.
3789 \layout Itemize
3790
3791 N.
3792  Do not retitle any existing section as "Endorsements" or to conflict in
3793  title with any Invariant Section.
3794  
3795 \layout Standard
3796
3797 If the Modified Version includes new front-matter sections or appendices
3798  that qualify as Secondary Sections and contain no material copied from
3799  the Document, you may at your option designate some or all of these sections
3800  as invariant.
3801  To do this, add their titles to the list of Invariant Sections in the Modified
3802  Version's license notice.
3803  These titles must be distinct from any other section titles.
3804 \layout Standard
3805
3806 You may add a section entitled "Endorsements", provided it contains nothing
3807  but endorsements of your Modified Version by various parties--for example,
3808  statements of peer review or that the text has been approved by an organization
3809  as the authoritative definition of a standard.
3810 \layout Standard
3811
3812 You may add a passage of up to five words as a Front-Cover Text, and a passage
3813  of up to 25 words as a Back-Cover Text, to the end of the list of Cover
3814  Texts in the Modified Version.
3815  Only one passage of Front-Cover Text and one of Back-Cover Text may be
3816  added by (or through arrangements made by) any one entity.
3817  If the Document already includes a cover text for the same cover, previously
3818  added by you or by arrangement made by the same entity you are acting on
3819  behalf of, you may not add another; but you may replace the old one, on
3820  explicit permission from the previous publisher that added the old one.
3821 \layout Standard
3822
3823 The author(s) and publisher(s) of the Document do not by this License give
3824  permission to use their names for publicity for or to assert or imply endorseme
3825 nt of any Modified Version.
3826  
3827 \layout Subsection*
3828
3829 5.
3830  COMBINING DOCUMENTS
3831 \layout Standard
3832
3833 You may combine the Document with other documents released under this License,
3834  under the terms defined in section 4 above for modified versions, provided
3835  that you include in the combination all of the Invariant Sections of all
3836  of the original documents, unmodified, and list them all as Invariant Sections
3837  of your combined work in its license notice.
3838 \layout Standard
3839
3840 The combined work need only contain one copy of this License, and multiple
3841  identical Invariant Sections may be replaced with a single copy.
3842  If there are multiple Invariant Sections with the same name but different
3843  contents, make the title of each such section unique by adding at the end
3844  of it, in parentheses, the name of the original author or publisher of
3845  that section if known, or else a unique number.
3846  Make the same adjustment to the section titles in the list of Invariant
3847  Sections in the license notice of the combined work.
3848 \layout Standard
3849
3850 In the combination, you must combine any sections entitled "History" in
3851  the various original documents, forming one section entitled "History";
3852  likewise combine any sections entitled "Acknowledgements", and any sections
3853  entitled "Dedications".
3854  You must delete all sections entitled "Endorsements."
3855 \layout Subsection*
3856
3857 6.
3858  COLLECTIONS OF DOCUMENTS
3859 \layout Standard
3860
3861 You may make a collection consisting of the Document and other documents
3862  released under this License, and replace the individual copies of this
3863  License in the various documents with a single copy that is included in
3864  the collection, provided that you follow the rules of this License for
3865  verbatim copying of each of the documents in all other respects.
3866 \layout Standard
3867
3868 You may extract a single document from such a collection, and distribute
3869  it individually under this License, provided you insert a copy of this
3870  License into the extracted document, and follow this License in all other
3871  respects regarding verbatim copying of that document.
3872  
3873 \layout Subsection*
3874
3875 7.
3876  AGGREGATION WITH INDEPENDENT WORKS
3877 \layout Standard
3878
3879 A compilation of the Document or its derivatives with other separate and
3880  independent documents or works, in or on a volume of a storage or distribution
3881  medium, does not as a whole count as a Modified Version of the Document,
3882  provided no compilation copyright is claimed for the compilation.
3883  Such a compilation is called an "aggregate", and this License does not
3884  apply to the other self-contained works thus compiled with the Document,
3885  on account of their being thus compiled, if they are not themselves derivative
3886  works of the Document.
3887 \layout Standard
3888
3889 If the Cover Text requirement of section 3 is applicable to these copies
3890  of the Document, then if the Document is less than one quarter of the entire
3891  aggregate, the Document's Cover Texts may be placed on covers that surround
3892  only the Document within the aggregate.
3893  Otherwise they must appear on covers around the whole aggregate.
3894 \layout Subsection*
3895
3896 8.
3897  TRANSLATION
3898 \layout Standard
3899
3900 Translation is considered a kind of modification, so you may distribute
3901  translations of the Document under the terms of section 4.
3902  Replacing Invariant Sections with translations requires special permission
3903  from their copyright holders, but you may include translations of some
3904  or all Invariant Sections in addition to the original versions of these
3905  Invariant Sections.
3906  You may include a translation of this License provided that you also include
3907  the original English version of this License.
3908  In case of a disagreement between the translation and the original English
3909  version of this License, the original English version will prevail.
3910 \layout Subsection*
3911
3912 9.
3913  TERMINATION
3914 \layout Standard
3915
3916 You may not copy, modify, sublicense, or distribute the Document except
3917  as expressly provided for under this License.
3918  Any other attempt to copy, modify, sublicense or distribute the Document
3919  is void, and will automatically terminate your rights under this License.
3920  However, parties who have received copies, or rights, from you under this
3921  License will not have their licenses terminated so long as such parties
3922  remain in full compliance.
3923  
3924 \layout Subsection*
3925
3926 10.
3927  FUTURE REVISIONS OF THIS LICENSE
3928 \layout Standard
3929
3930 The Free Software Foundation may publish new, revised versions of the GNU
3931  Free Documentation License from time to time.
3932  Such new versions will be similar in spirit to the present version, but
3933  may differ in detail to address new problems or concerns.
3934  See http://www.gnu.org/copyleft/.
3935 \layout Standard
3936
3937 Each version of the License is given a distinguishing version number.
3938  If the Document specifies that a particular numbered version of this License
3939  "or any later version" applies to it, you have the option of following
3940  the terms and conditions either of that specified version or of any later
3941  version that has been published (not as a draft) by the Free Software Foundatio
3942 n.
3943  If the Document does not specify a version number of this License, you
3944  may choose any version ever published (not as a draft) by the Free Software
3945  Foundation.
3946 \the_end