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