10ce136064dd8c6545812761209ce77c2a2d8cac
[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 \paperfontsize default
9 \spacing single 
10 \papersize Default
11 \paperpackage a4
12 \use_geometry 0
13 \use_amsmath 0
14 \use_natbib 0
15 \use_numerical_citations 0
16 \paperorientation portrait
17 \secnumdepth 3
18 \tocdepth 3
19 \paragraph_separation indent
20 \defskip medskip
21 \quotes_language english
22 \quotes_times 2
23 \papercolumns 1
24 \papersides 1
25 \paperpagestyle headings
26
27 \layout Title
28
29 The Speex Codec Manual
30 \newline 
31 (draft)
32 \layout Author
33
34 Jean-Marc Valin
35 \layout Standard
36 \pagebreak_top 
37 Copyright (c) 2002 Jean-Marc Valin.
38 \layout Standard
39
40 Permission is granted to copy, distribute and/or modify this document under
41  the terms of the GNU Free Documentation License, Version 1.1 or any later
42  version published by the Free Software Foundation; with no Invariant Section,
43  with no Front-Cover Texts, and with no Back-Cover.
44  A copy of the license is included in the section entitled "GNU Free Documentati
45 on License".
46  
47 \layout Section*
48
49 Disclaimer
50 \layout Standard
51
52 This document is meant to provide useful information on the Speex codec
53  but there is absolutely no warranty regarding usefulness or correctness
54  of the information provided.
55  Also, some techniques used in Speex are said to be 
56 \begin_inset Quotes eld
57 \end_inset 
58
59 similar
60 \begin_inset Quotes erd
61 \end_inset 
62
63  to techniques used in known codecs.
64  This should not be understood as an acknowledgment that Speex is using
65  any patented algorithm used in these codecs, but merely that comprehension
66  of Speex can be facilitated by thinking that the principles of operation
67  are the same or similar.
68  Of course, there's also the obligatory 
69 \begin_inset Quotes eld
70 \end_inset 
71
72 all trademarks are property of their respective owner
73 \begin_inset Quotes erd
74 \end_inset 
75
76 .
77 \layout Standard
78 \pagebreak_top \pagebreak_bottom 
79
80 \begin_inset LatexCommand \tableofcontents{}
81
82 \end_inset 
83
84
85 \layout Standard
86 \pagebreak_bottom 
87
88 \begin_inset FloatList table
89
90 \end_inset 
91
92
93 \layout Section
94
95 Introduction to Speex
96 \layout Standard
97
98 Speex has been designed with the following goals in mind:
99 \layout Itemize
100
101 No use of patented algorithms (implies that we can't use patented algorithms
102  such as ACELP)
103 \layout Itemize
104
105 Good for Voice over IP (VoIP)
106 \layout Itemize
107
108 Provide very good quality speech (at least as an option)
109 \layout Itemize
110
111 Allow a wide range of quality/bit-rates
112 \layout Itemize
113
114 Integrate both narrowband and wideband coding
115 \layout Itemize
116
117 Reasonable complexity
118 \layout Standard
119
120 Throughout the design the following assumptions and constraints were considered
121 \layout Itemize
122
123 Presence of packet losses
124 \layout Itemize
125
126 Integrity of received frames (no bit-errors)
127 \layout Itemize
128
129 Memory footprint is neither critical nor unlimited
130 \layout Standard
131
132 This led us to choose the CELP technique for Speex.
133  Also many design decisions were based on the original goals and assumptions:
134 \layout Itemize
135
136 Minimizing the amount of information extracted from past frames (for robustness
137  to packet loss)
138 \layout Itemize
139
140 Dynamically-selectable codebooks (LSP, pitch and innovation)
141 \layout Itemize
142
143 G.728-like fixed codebooks (without backward-adaptive grains) because of
144  patent issues
145 \layout Section
146
147 Introduction to CELP Coding
148 \layout Standard
149
150 Speex is based on the CELP, which stands for Code Excited Linear Prediction.
151  This section attempts to introduce the principles behind CELP, so if you
152  are already familiar with CELP, you can safely skip to section 
153 \begin_inset LatexCommand \ref{sec:Speex-narrowband-mode}
154
155 \end_inset 
156
157 .
158  The CELP technique is based on three ideas:
159 \layout Enumerate
160
161 The use of a linear prediction (LP) model to model the vocal tract
162 \layout Enumerate
163
164 The use of (adaptive and fixed) codebook entries as input (excitation) of
165  the LP model
166 \layout Enumerate
167
168 The search performed in closed-loop in a 
169 \begin_inset Quotes eld
170 \end_inset 
171
172 perceptually weighted domain
173 \begin_inset Quotes erd
174 \end_inset 
175
176
177 \layout Subsection
178
179 Linear Prediction
180 \layout Standard
181
182 The linear prediction model represents each speech sample as linear combination
183  of past samples, plus an error signal called the excitation (or residual).
184 \begin_inset Formula \[
185 x(n)=\sum _{i=1}^{N}a_{i}x(n-i)+e(n)\]
186
187 \end_inset 
188
189
190 \layout Standard
191
192 In the 
193 \emph on 
194 z
195 \emph default 
196 -domain, this can be expressed as
197 \layout Standard
198
199
200 \begin_inset Formula \[
201 x(z)=\frac{1}{A(z)}\: e(z)\]
202
203 \end_inset 
204
205
206 \layout Standard
207
208 where 
209 \begin_inset Formula $A(z)$
210 \end_inset 
211
212  is defined as
213 \layout Standard
214
215
216 \begin_inset Formula \[
217 A(z)=1-\sum _{i=1}^{N}a_{i}z^{-i}\]
218
219 \end_inset 
220
221
222 \layout Standard
223
224 We usually refer to 
225 \begin_inset Formula $A(z)$
226 \end_inset 
227
228  as the analysis filter and 
229 \begin_inset Formula $1/A(z)$
230 \end_inset 
231
232  as the synthesis filter.
233 \layout Standard
234
235 The 
236 \begin_inset Formula $A(z)$
237 \end_inset 
238
239  filter is computed using the Levinson-Durbin algorithm, which starts from
240  the auto-correlation 
241 \begin_inset Formula $R(m)$
242 \end_inset 
243
244  of the signal 
245 \begin_inset Formula $x(n)$
246 \end_inset 
247
248 .
249 \layout Standard
250
251
252 \begin_inset Formula \[
253 r(m)=\sum _{i=0}^{N-1}x(i)x(i-m)\]
254
255 \end_inset 
256
257
258 \layout Standard
259
260 For an order 
261 \begin_inset Formula $N$
262 \end_inset 
263
264  filter, we have:
265 \begin_inset Formula \[
266 \mathbf{R}=\left[\begin{array}{cccc}
267  r(0) & r(1) & \cdots  & r(N-1)\\
268  r(1) & r(0) & \cdots  & r(N-2)\\
269  \vdots  & \vdots  & \ddots  & \vdots \\
270  r(N-1) & r(N-2) & \cdots  & r(0)\end{array}
271 \right]\]
272
273 \end_inset 
274
275
276 \begin_inset Formula \[
277 \mathbf{r}=\left[\begin{array}{c}
278  r(1)\\
279  r(2)\\
280  \vdots \\
281  R(N)\end{array}
282 \right]\]
283
284 \end_inset 
285
286
287 \layout Standard
288
289 The filter coefficients 
290 \begin_inset Formula $a_{i}$
291 \end_inset 
292
293  are found by solving the system 
294 \begin_inset Formula $\mathbf{Ra}=\mathbf{r}$
295 \end_inset 
296
297 .
298  What the Levinson-Durbin algorithm does here is making the solution to
299  the problem 
300 \begin_inset Formula $\mathcal{O}\left(N^{2}\right)$
301 \end_inset 
302
303  instead of 
304 \begin_inset Formula $\mathcal{O}\left(N^{3}\right)$
305 \end_inset 
306
307  by exploiting the fact that matrix 
308 \begin_inset Formula $\mathbf{R}$
309 \end_inset 
310
311  is toeplitz hermitian.
312  Also, it can be proved that all the roots of 
313 \begin_inset Formula $A(z)$
314 \end_inset 
315
316  are withing the unit circle, which means that 
317 \begin_inset Formula $1/A(z)$
318 \end_inset 
319
320  is always stable.
321  This is in theory; in practice because of finite precision, there are two
322  commonly used techniques to make sure we have a stable filter.
323  First, we multiply 
324 \begin_inset Formula $r(0)$
325 \end_inset 
326
327  by a number slightly above one (such as 1.0001), which is equivalent to
328  adding noise to the signal.
329  Also, we can apply a window the the auto-correlation, which is equivalent
330  to filtering in the frequency domain, reducing sharp resonances.
331 \layout Subsection
332
333 Pitch Prediction
334 \layout Standard
335
336 During voiced segments, the speech signal is very periodic, so it is possible
337  to take advantage of that.
338 \layout Standard
339
340
341 \begin_inset Formula \[
342 e(n)=\beta e(n-T)+c(n)\]
343
344 \end_inset 
345
346
347 \layout Standard
348
349 where 
350 \begin_inset Formula $T$
351 \end_inset 
352
353  is the pitch period and 
354 \begin_inset Formula $\beta $
355 \end_inset 
356
357  is the pitch gain.
358  In the 
359 \emph on 
360 z
361 \emph default 
362 -domain, the excitation can be expressed as:
363 \layout Standard
364
365
366 \begin_inset Formula \[
367 e(z)=\frac{1}{1-\beta z^{-T}}\: c(z)\]
368
369 \end_inset 
370
371 where 
372 \begin_inset Formula $c(n)$
373 \end_inset 
374
375  is taken from the 
376 \emph on 
377 innovation codebook
378 \emph default 
379 .
380 \layout Subsection
381
382 Innovation Codebook
383 \layout Standard
384
385 This is where most of the bits in a CELP codec are allocated.
386  It represents the information that couldn't be obtained either from linear
387  prediction or pitch prediction.
388 \layout Subsection
389
390 Analysis-by-Synthesis and Error Weighting
391 \layout Standard
392
393 Most (if not all) modern audio codecs attempt to 
394 \emph on 
395 shape
396 \emph default 
397  the noise so that it is the hardest to detect with the ear.
398  That means that more noise can be tolerated in parts of the spectrum that
399  are louder and 
400 \emph on 
401 vice versa
402 \emph default 
403 .
404  That's why the error is minimized for the perceptually weighted signal
405 \begin_inset Formula \[
406 X_{w}(z)=W(z)X(z)\]
407
408 \end_inset 
409
410 where 
411 \begin_inset Formula $W(z)$
412 \end_inset 
413
414  is the weighting filter, usually of the form
415 \layout Standard
416
417
418 \begin_inset Formula \begin{equation}
419 W(z)=\frac{A\left(\frac{z}{\gamma _{1}}\right)}{A\left(\frac{z}{\gamma _{2}}\right)}\label{eq:weighting_filter}\end{equation}
420
421 \end_inset 
422
423
424 \layout Standard
425
426 with control parameters 
427 \begin_inset Formula $\gamma _{1}>\gamma _{2}$
428 \end_inset 
429
430 .
431  If the noise is white in the perceptually weighted domain, then in the
432  signal domain its spectral shape will be of the form
433 \begin_inset Formula \[
434 A_{noise}(z)=\frac{1}{W(z)}=\frac{A\left(\frac{z}{\gamma _{2}}\right)}{A\left(\frac{z}{\gamma _{1}}\right)}\]
435
436 \end_inset 
437
438
439 \layout Section
440
441 Speex narrowband mode
442 \begin_inset LatexCommand \label{sec:Speex-narrowband-mode}
443
444 \end_inset 
445
446
447 \layout Standard
448
449 This section looks at how Speex works for narrowband (
450 \begin_inset Formula $8\: \mathrm{kHz}$
451 \end_inset 
452
453  sampling rate) operation.
454  The frame size for this mode is 
455 \begin_inset Formula $20\: \mathrm{ms}$
456 \end_inset 
457
458 , corresponding to 160 samples.
459  Each frame is also subdivided into 4 sub-frames of 40 samples each.
460 \layout Subsection
461
462 LPC Analysis
463 \layout Standard
464
465 An LPC analysis is first performed on a (Hamming) window that spans all
466  the current frame and half a frame in advance.
467  The LPC coefficients are then converted to Line Spectral Pair (LSP), a
468  representation that is more robust to quantization.
469  The LSP's are quantized using 30 bits for higher quality modes and 18 bits
470  for lower quality.
471  The quantized LSP's are considered to be associated to the 
472 \begin_inset Formula $4^{th}$
473 \end_inset 
474
475  sub-frames and the LSP's associated to the first 3 sub-frames are linearly
476  interpolated using the current and previous LSP's.
477 \layout Standard
478
479 The perceptual weighting filter 
480 \begin_inset Formula $W(z)$
481 \end_inset 
482
483  used by Speex corresponds to the one described by eq.
484  
485 \begin_inset LatexCommand \ref{eq:weighting_filter}
486
487 \end_inset 
488
489  with 
490 \begin_inset Formula $\gamma _{1}=0.9$
491 \end_inset 
492
493  and 
494 \begin_inset Formula $\gamma _{2}=0.6$
495 \end_inset 
496
497 .
498  We can use the unquantized 
499 \begin_inset Formula $A(z)$
500 \end_inset 
501
502  filter since the weighting filter is only used in the encoder.
503 \layout Subsection
504
505 Pitch Prediction (adaptive codebook)
506 \layout Standard
507
508 Speex uses a 3-tap prediction for pitch.
509  That is, 
510 \layout Standard
511
512
513 \begin_inset Formula \[
514 e(n)=\beta _{0}e(n-T-1)+\beta _{1}e(n-T)+\beta _{2}e(n-T+1)+c(n)\]
515
516 \end_inset 
517
518
519 \layout Standard
520
521 where 
522 \begin_inset Formula $T$
523 \end_inset 
524
525  is the pitch period and the 
526 \begin_inset Formula $\beta _{i}$
527 \end_inset 
528
529  are the prediction (filter) taps.
530  The period and quantized gains are determined in closed loop.
531 \layout Subsection
532
533 Innovation Codebook
534 \layout Standard
535
536 In Speex, the innovation signal is quantized using shape-only vector quantizatio
537 n (VQ).
538  That means that the codebooks that are used represent both the shape and
539  the gain at the same time.
540  This save many bits that would otherwise be allocated for a separate gain
541  at the price of a slight increase in complexity.
542  Except for the absence of (backward-adaptive) gain, the technique used
543  in Speex is similar to G.728 (LD-CELP).
544  However since we do not have a low-delay constraint, the search can be
545  made more 
546 \begin_inset Quotes eld
547 \end_inset 
548
549 global
550 \begin_inset Quotes erd
551 \end_inset 
552
553  and make use of the whole information available for a sub-frame.
554 \layout Subsection
555
556 Bit allocation
557 \layout Standard
558
559 There are 7 different narrowband bit-rates defined for Speex, ranging from
560  200 bps to 18.15 kbps, although the modes below 5.9 kbps should not be used
561  for speech.
562  The bit-allocation for each mode is detailed in table 
563 \begin_inset LatexCommand \ref{cap:bits-narrowband}
564
565 \end_inset 
566
567 .
568  Each frame starts with the mode ID encoded with 4 bits which allows a range
569  from 0 to 15, though only the first 7 values are used (the others are reserved).
570  The parameters are listed in the table in the order they are packed in
571  the bit-stream.
572  All frame-based parameters are packed before sub-frame parameters.
573  The parameters for a certain sub-frame are all packed before the following
574  sub-frame is packed.
575 \layout Standard
576
577
578 \begin_inset Float table
579 placement htbp
580 wide true
581 collapsed false
582
583 \layout Standard
584
585
586 \begin_inset  Tabular
587 <lyxtabular version="3" rows="11" columns="9">
588 <features>
589 <column alignment="center" valignment="top" leftline="true" width="0pt">
590 <column alignment="center" valignment="top" leftline="true" width="0pt">
591 <column alignment="center" valignment="top" leftline="true" width="0pt">
592 <column alignment="center" valignment="top" leftline="true" width="0pt">
593 <column alignment="center" valignment="top" leftline="true" width="0pt">
594 <column alignment="center" valignment="top" leftline="true" width="0pt">
595 <column alignment="center" valignment="top" leftline="true" width="0pt">
596 <column alignment="center" valignment="top" leftline="true" width="0pt">
597 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
598 <row topline="true" bottomline="true">
599 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
600 \begin_inset Text
601
602 \layout Standard
603
604 Parameter
605 \end_inset 
606 </cell>
607 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
608 \begin_inset Text
609
610 \layout Standard
611
612 Update rate
613 \end_inset 
614 </cell>
615 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
616 \begin_inset Text
617
618 \layout Standard
619
620 0
621 \end_inset 
622 </cell>
623 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
624 \begin_inset Text
625
626 \layout Standard
627
628 1
629 \end_inset 
630 </cell>
631 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
632 \begin_inset Text
633
634 \layout Standard
635
636 2
637 \end_inset 
638 </cell>
639 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
640 \begin_inset Text
641
642 \layout Standard
643
644 3
645 \end_inset 
646 </cell>
647 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
648 \begin_inset Text
649
650 \layout Standard
651
652 4
653 \end_inset 
654 </cell>
655 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
656 \begin_inset Text
657
658 \layout Standard
659
660 5
661 \end_inset 
662 </cell>
663 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
664 \begin_inset Text
665
666 \layout Standard
667
668 6
669 \end_inset 
670 </cell>
671 </row>
672 <row topline="true">
673 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
674 \begin_inset Text
675
676 \layout Standard
677
678 Mode ID
679 \end_inset 
680 </cell>
681 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
682 \begin_inset Text
683
684 \layout Standard
685
686 frame
687 \end_inset 
688 </cell>
689 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
690 \begin_inset Text
691
692 \layout Standard
693
694 4
695 \end_inset 
696 </cell>
697 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
698 \begin_inset Text
699
700 \layout Standard
701
702 4
703 \end_inset 
704 </cell>
705 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
706 \begin_inset Text
707
708 \layout Standard
709
710 4
711 \end_inset 
712 </cell>
713 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
714 \begin_inset Text
715
716 \layout Standard
717
718 4
719 \end_inset 
720 </cell>
721 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
722 \begin_inset Text
723
724 \layout Standard
725
726 4
727 \end_inset 
728 </cell>
729 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
730 \begin_inset Text
731
732 \layout Standard
733
734 4
735 \end_inset 
736 </cell>
737 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
738 \begin_inset Text
739
740 \layout Standard
741
742 4
743 \end_inset 
744 </cell>
745 </row>
746 <row topline="true">
747 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
748 \begin_inset Text
749
750 \layout Standard
751
752 LSP
753 \end_inset 
754 </cell>
755 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
756 \begin_inset Text
757
758 \layout Standard
759
760 frame
761 \end_inset 
762 </cell>
763 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
764 \begin_inset Text
765
766 \layout Standard
767
768 0
769 \end_inset 
770 </cell>
771 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
772 \begin_inset Text
773
774 \layout Standard
775
776 18
777 \end_inset 
778 </cell>
779 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
780 \begin_inset Text
781
782 \layout Standard
783
784 18
785 \end_inset 
786 </cell>
787 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
788 \begin_inset Text
789
790 \layout Standard
791
792 18
793 \end_inset 
794 </cell>
795 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
796 \begin_inset Text
797
798 \layout Standard
799
800 18
801 \end_inset 
802 </cell>
803 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
804 \begin_inset Text
805
806 \layout Standard
807
808 30
809 \end_inset 
810 </cell>
811 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
812 \begin_inset Text
813
814 \layout Standard
815
816 30
817 \end_inset 
818 </cell>
819 </row>
820 <row topline="true">
821 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
822 \begin_inset Text
823
824 \layout Standard
825
826 OL pitch
827 \end_inset 
828 </cell>
829 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
830 \begin_inset Text
831
832 \layout Standard
833
834 frame
835 \end_inset 
836 </cell>
837 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
838 \begin_inset Text
839
840 \layout Standard
841
842 0
843 \end_inset 
844 </cell>
845 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
846 \begin_inset Text
847
848 \layout Standard
849
850 7
851 \end_inset 
852 </cell>
853 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
854 \begin_inset Text
855
856 \layout Standard
857
858 7
859 \end_inset 
860 </cell>
861 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
862 \begin_inset Text
863
864 \layout Standard
865
866 0
867 \end_inset 
868 </cell>
869 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
870 \begin_inset Text
871
872 \layout Standard
873
874 0
875 \end_inset 
876 </cell>
877 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
878 \begin_inset Text
879
880 \layout Standard
881
882 0
883 \end_inset 
884 </cell>
885 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
886 \begin_inset Text
887
888 \layout Standard
889
890 0
891 \end_inset 
892 </cell>
893 </row>
894 <row topline="true">
895 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
896 \begin_inset Text
897
898 \layout Standard
899
900 OL pitch gain
901 \end_inset 
902 </cell>
903 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
904 \begin_inset Text
905
906 \layout Standard
907
908 frame
909 \end_inset 
910 </cell>
911 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
912 \begin_inset Text
913
914 \layout Standard
915
916 0
917 \end_inset 
918 </cell>
919 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
920 \begin_inset Text
921
922 \layout Standard
923
924 4
925 \end_inset 
926 </cell>
927 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
928 \begin_inset Text
929
930 \layout Standard
931
932 0
933 \end_inset 
934 </cell>
935 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
936 \begin_inset Text
937
938 \layout Standard
939
940 0
941 \end_inset 
942 </cell>
943 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
944 \begin_inset Text
945
946 \layout Standard
947
948 0
949 \end_inset 
950 </cell>
951 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
952 \begin_inset Text
953
954 \layout Standard
955
956 0
957 \end_inset 
958 </cell>
959 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
960 \begin_inset Text
961
962 \layout Standard
963
964 0
965 \end_inset 
966 </cell>
967 </row>
968 <row topline="true">
969 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
970 \begin_inset Text
971
972 \layout Standard
973
974 Exc gain
975 \end_inset 
976 </cell>
977 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
978 \begin_inset Text
979
980 \layout Standard
981
982 frame
983 \end_inset 
984 </cell>
985 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
986 \begin_inset Text
987
988 \layout Standard
989
990 0
991 \end_inset 
992 </cell>
993 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
994 \begin_inset Text
995
996 \layout Standard
997
998 5
999 \end_inset 
1000 </cell>
1001 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1002 \begin_inset Text
1003
1004 \layout Standard
1005
1006 5
1007 \end_inset 
1008 </cell>
1009 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1010 \begin_inset Text
1011
1012 \layout Standard
1013
1014 5
1015 \end_inset 
1016 </cell>
1017 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1018 \begin_inset Text
1019
1020 \layout Standard
1021
1022 5
1023 \end_inset 
1024 </cell>
1025 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1026 \begin_inset Text
1027
1028 \layout Standard
1029
1030 5
1031 \end_inset 
1032 </cell>
1033 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1034 \begin_inset Text
1035
1036 \layout Standard
1037
1038 5
1039 \end_inset 
1040 </cell>
1041 </row>
1042 <row topline="true">
1043 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1044 \begin_inset Text
1045
1046 \layout Standard
1047
1048 Fine pitch
1049 \end_inset 
1050 </cell>
1051 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1052 \begin_inset Text
1053
1054 \layout Standard
1055
1056 sub-frame
1057 \end_inset 
1058 </cell>
1059 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1060 \begin_inset Text
1061
1062 \layout Standard
1063
1064 0
1065 \end_inset 
1066 </cell>
1067 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1068 \begin_inset Text
1069
1070 \layout Standard
1071
1072 0
1073 \end_inset 
1074 </cell>
1075 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1076 \begin_inset Text
1077
1078 \layout Standard
1079
1080 0
1081 \end_inset 
1082 </cell>
1083 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1084 \begin_inset Text
1085
1086 \layout Standard
1087
1088 7
1089 \end_inset 
1090 </cell>
1091 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1092 \begin_inset Text
1093
1094 \layout Standard
1095
1096 7
1097 \end_inset 
1098 </cell>
1099 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1100 \begin_inset Text
1101
1102 \layout Standard
1103
1104 7
1105 \end_inset 
1106 </cell>
1107 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1108 \begin_inset Text
1109
1110 \layout Standard
1111
1112 7
1113 \end_inset 
1114 </cell>
1115 </row>
1116 <row topline="true">
1117 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1118 \begin_inset Text
1119
1120 \layout Standard
1121
1122 Pitch gain
1123 \end_inset 
1124 </cell>
1125 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1126 \begin_inset Text
1127
1128 \layout Standard
1129
1130 sub-frame
1131 \end_inset 
1132 </cell>
1133 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1134 \begin_inset Text
1135
1136 \layout Standard
1137
1138 0
1139 \end_inset 
1140 </cell>
1141 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1142 \begin_inset Text
1143
1144 \layout Standard
1145
1146 0
1147 \end_inset 
1148 </cell>
1149 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1150 \begin_inset Text
1151
1152 \layout Standard
1153
1154 5
1155 \end_inset 
1156 </cell>
1157 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1158 \begin_inset Text
1159
1160 \layout Standard
1161
1162 5
1163 \end_inset 
1164 </cell>
1165 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1166 \begin_inset Text
1167
1168 \layout Standard
1169
1170 5
1171 \end_inset 
1172 </cell>
1173 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1174 \begin_inset Text
1175
1176 \layout Standard
1177
1178 7
1179 \end_inset 
1180 </cell>
1181 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1182 \begin_inset Text
1183
1184 \layout Standard
1185
1186 7
1187 \end_inset 
1188 </cell>
1189 </row>
1190 <row topline="true">
1191 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1192 \begin_inset Text
1193
1194 \layout Standard
1195
1196 Innovation gain
1197 \end_inset 
1198 </cell>
1199 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1200 \begin_inset Text
1201
1202 \layout Standard
1203
1204 sub-frame
1205 \end_inset 
1206 </cell>
1207 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1208 \begin_inset Text
1209
1210 \layout Standard
1211
1212 0
1213 \end_inset 
1214 </cell>
1215 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1216 \begin_inset Text
1217
1218 \layout Standard
1219
1220 3
1221 \end_inset 
1222 </cell>
1223 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1224 \begin_inset Text
1225
1226 \layout Standard
1227
1228 0
1229 \end_inset 
1230 </cell>
1231 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1232 \begin_inset Text
1233
1234 \layout Standard
1235
1236 3
1237 \end_inset 
1238 </cell>
1239 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1240 \begin_inset Text
1241
1242 \layout Standard
1243
1244 3
1245 \end_inset 
1246 </cell>
1247 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1248 \begin_inset Text
1249
1250 \layout Standard
1251
1252 3
1253 \end_inset 
1254 </cell>
1255 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1256 \begin_inset Text
1257
1258 \layout Standard
1259
1260 3
1261 \end_inset 
1262 </cell>
1263 </row>
1264 <row topline="true" bottomline="true">
1265 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1266 \begin_inset Text
1267
1268 \layout Standard
1269
1270 Innovation VQ
1271 \end_inset 
1272 </cell>
1273 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1274 \begin_inset Text
1275
1276 \layout Standard
1277
1278 sub-frame
1279 \end_inset 
1280 </cell>
1281 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1282 \begin_inset Text
1283
1284 \layout Standard
1285
1286 0
1287 \end_inset 
1288 </cell>
1289 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1290 \begin_inset Text
1291
1292 \layout Standard
1293
1294 0
1295 \end_inset 
1296 </cell>
1297 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1298 \begin_inset Text
1299
1300 \layout Standard
1301
1302 16
1303 \end_inset 
1304 </cell>
1305 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1306 \begin_inset Text
1307
1308 \layout Standard
1309
1310 20
1311 \end_inset 
1312 </cell>
1313 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1314 \begin_inset Text
1315
1316 \layout Standard
1317
1318 35
1319 \end_inset 
1320 </cell>
1321 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1322 \begin_inset Text
1323
1324 \layout Standard
1325
1326 48
1327 \end_inset 
1328 </cell>
1329 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1330 \begin_inset Text
1331
1332 \layout Standard
1333
1334 64
1335 \end_inset 
1336 </cell>
1337 </row>
1338 <row topline="true" bottomline="true">
1339 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1340 \begin_inset Text
1341
1342 \layout Standard
1343
1344 Total
1345 \end_inset 
1346 </cell>
1347 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1348 \begin_inset Text
1349
1350 \layout Standard
1351
1352 frame
1353 \end_inset 
1354 </cell>
1355 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1356 \begin_inset Text
1357
1358 \layout Standard
1359
1360 4
1361 \end_inset 
1362 </cell>
1363 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1364 \begin_inset Text
1365
1366 \layout Standard
1367
1368 50
1369 \end_inset 
1370 </cell>
1371 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1372 \begin_inset Text
1373
1374 \layout Standard
1375
1376 118
1377 \end_inset 
1378 </cell>
1379 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1380 \begin_inset Text
1381
1382 \layout Standard
1383
1384 167
1385 \end_inset 
1386 </cell>
1387 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1388 \begin_inset Text
1389
1390 \layout Standard
1391
1392 227
1393 \end_inset 
1394 </cell>
1395 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1396 \begin_inset Text
1397
1398 \layout Standard
1399
1400 299
1401 \end_inset 
1402 </cell>
1403 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1404 \begin_inset Text
1405
1406 \layout Standard
1407
1408 363
1409 \end_inset 
1410 </cell>
1411 </row>
1412 </lyxtabular>
1413
1414 \end_inset 
1415
1416
1417 \layout Caption
1418
1419 Bit allocation for narrowband modes
1420 \begin_inset LatexCommand \label{cap:bits-narrowband}
1421
1422 \end_inset 
1423
1424
1425 \end_inset 
1426
1427
1428 \layout Subsection
1429
1430 Perceptual post-filter
1431 \layout Standard
1432
1433 This part of the codec only applies to the decoder and can even be changed
1434  without affecting inter-operability.
1435  
1436 \layout Section
1437
1438 Speex wideband mode (sub-band CELP)
1439 \layout Standard
1440
1441 For wideband, the Speex approach is similar to the ITU-T G.722 (ADPCM) wideband
1442  standard in that it uses a 
1443 \emph on 
1444 q
1445 \emph default 
1446 uadrature 
1447 \emph on 
1448 m
1449 \emph default 
1450 irror 
1451 \emph on 
1452 f
1453 \emph default 
1454 ilter (QMF) to split the band in two.
1455  The 16 kHz signal is thus divided into two 8 kHz signals, one representing
1456  the low band (0-4 kHz), the other the high band (4-8 kHz).
1457  The low band is encoded with the narrowband mode described in section 
1458 \begin_inset LatexCommand \ref{sec:Speex-narrowband-mode}
1459
1460 \end_inset 
1461
1462  in such a way that the resulting 
1463 \begin_inset Quotes eld
1464 \end_inset 
1465
1466 embedded narrowband bit-stream
1467 \begin_inset Quotes erd
1468 \end_inset 
1469
1470  can also be decoded with the narrowband decoder.
1471  Since the low band encoding has already been described only the high band
1472  encoding is described in this section.
1473 \layout Subsection
1474
1475 Linear Prediction
1476 \layout Standard
1477
1478 The linear prediction part used for the high-band is very similar to what
1479  is done for narrowband.
1480  The only difference is that we use only 12 bits to encode the high-band
1481  LSP's.
1482 \layout Subsection
1483
1484 Pitch Prediction
1485 \layout Standard
1486
1487 That part is easy: there's no pitch prediction for the high-band.
1488  There are two reasons for that.
1489  First, there is usually little harmonic structure in this band (above 4
1490  kHz).
1491  Second, it would be very hard to implement since the QMF folds the 4-8
1492  kHz band into 4-0 kHz (reversing the frequency axis), which means that
1493  the location of the harmonics are no longer at multiples of the fundamental
1494  (pitch).
1495 \layout Subsection
1496
1497 Excitation Quantization
1498 \layout Standard
1499
1500 The high-band excitation is coded in the same way as for narrowband.
1501  
1502 \layout Subsection
1503
1504 Bit allocation
1505 \layout Standard
1506
1507 For the wideband mode, all the narrowband frame is packed before the high-band
1508  is encoded.
1509  The narrowband part of the bit-stream is as defined in table 
1510 \begin_inset LatexCommand \ref{cap:bits-narrowband}
1511
1512 \end_inset 
1513
1514 .
1515  The high-band follows, as described in table 
1516 \begin_inset LatexCommand \ref{cap:bits-wideband}
1517
1518 \end_inset 
1519
1520 .
1521  This also means that a wideband frame may be correctly decoded by a narrowband
1522  decoder with the only caveat that is more than one frame is packed in the
1523  same packet, the decoder will need to skip the high-band parts in order
1524  to be in sync with the bit-stream.
1525 \layout Standard
1526
1527
1528 \begin_inset Float table
1529 placement htbp
1530 wide true
1531 collapsed false
1532
1533 \layout Standard
1534
1535
1536 \begin_inset  Tabular
1537 <lyxtabular version="3" rows="6" columns="6">
1538 <features>
1539 <column alignment="center" valignment="top" leftline="true" width="0pt">
1540 <column alignment="center" valignment="top" leftline="true" width="0pt">
1541 <column alignment="center" valignment="top" leftline="true" width="0pt">
1542 <column alignment="center" valignment="top" leftline="true" width="0pt">
1543 <column alignment="center" valignment="top" leftline="true" width="0pt">
1544 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
1545 <row topline="true" bottomline="true">
1546 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1547 \begin_inset Text
1548
1549 \layout Standard
1550
1551 Parameter
1552 \end_inset 
1553 </cell>
1554 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1555 \begin_inset Text
1556
1557 \layout Standard
1558
1559 Update rate
1560 \end_inset 
1561 </cell>
1562 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1563 \begin_inset Text
1564
1565 \layout Standard
1566
1567 0
1568 \end_inset 
1569 </cell>
1570 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1571 \begin_inset Text
1572
1573 \layout Standard
1574
1575 1
1576 \end_inset 
1577 </cell>
1578 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1579 \begin_inset Text
1580
1581 \layout Standard
1582
1583 2
1584 \end_inset 
1585 </cell>
1586 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1587 \begin_inset Text
1588
1589 \layout Standard
1590
1591 3
1592 \end_inset 
1593 </cell>
1594 </row>
1595 <row topline="true">
1596 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1597 \begin_inset Text
1598
1599 \layout Standard
1600
1601 Mode ID
1602 \end_inset 
1603 </cell>
1604 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1605 \begin_inset Text
1606
1607 \layout Standard
1608
1609 frame
1610 \end_inset 
1611 </cell>
1612 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1613 \begin_inset Text
1614
1615 \layout Standard
1616
1617 3
1618 \end_inset 
1619 </cell>
1620 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1621 \begin_inset Text
1622
1623 \layout Standard
1624
1625 3
1626 \end_inset 
1627 </cell>
1628 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1629 \begin_inset Text
1630
1631 \layout Standard
1632
1633 3
1634 \end_inset 
1635 </cell>
1636 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1637 \begin_inset Text
1638
1639 \layout Standard
1640
1641 3
1642 \end_inset 
1643 </cell>
1644 </row>
1645 <row topline="true">
1646 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1647 \begin_inset Text
1648
1649 \layout Standard
1650
1651 LSP
1652 \end_inset 
1653 </cell>
1654 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1655 \begin_inset Text
1656
1657 \layout Standard
1658
1659 frame
1660 \end_inset 
1661 </cell>
1662 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1663 \begin_inset Text
1664
1665 \layout Standard
1666
1667 0
1668 \end_inset 
1669 </cell>
1670 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1671 \begin_inset Text
1672
1673 \layout Standard
1674
1675 12
1676 \end_inset 
1677 </cell>
1678 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1679 \begin_inset Text
1680
1681 \layout Standard
1682
1683 12
1684 \end_inset 
1685 </cell>
1686 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1687 \begin_inset Text
1688
1689 \layout Standard
1690
1691 12
1692 \end_inset 
1693 </cell>
1694 </row>
1695 <row topline="true">
1696 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1697 \begin_inset Text
1698
1699 \layout Standard
1700
1701 Excitation gain
1702 \end_inset 
1703 </cell>
1704 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1705 \begin_inset Text
1706
1707 \layout Standard
1708
1709 sub-frame
1710 \end_inset 
1711 </cell>
1712 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1713 \begin_inset Text
1714
1715 \layout Standard
1716
1717 0
1718 \end_inset 
1719 </cell>
1720 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1721 \begin_inset Text
1722
1723 \layout Standard
1724
1725 5
1726 \end_inset 
1727 </cell>
1728 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1729 \begin_inset Text
1730
1731 \layout Standard
1732
1733 4
1734 \end_inset 
1735 </cell>
1736 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1737 \begin_inset Text
1738
1739 \layout Standard
1740
1741 4
1742 \end_inset 
1743 </cell>
1744 </row>
1745 <row topline="true" bottomline="true">
1746 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1747 \begin_inset Text
1748
1749 \layout Standard
1750
1751 Excitation VQ
1752 \end_inset 
1753 </cell>
1754 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1755 \begin_inset Text
1756
1757 \layout Standard
1758
1759 sub-frame
1760 \end_inset 
1761 </cell>
1762 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1763 \begin_inset Text
1764
1765 \layout Standard
1766
1767 0
1768 \end_inset 
1769 </cell>
1770 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1771 \begin_inset Text
1772
1773 \layout Standard
1774
1775 0
1776 \end_inset 
1777 </cell>
1778 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1779 \begin_inset Text
1780
1781 \layout Standard
1782
1783 20
1784 \end_inset 
1785 </cell>
1786 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1787 \begin_inset Text
1788
1789 \layout Standard
1790
1791 40
1792 \end_inset 
1793 </cell>
1794 </row>
1795 <row topline="true" bottomline="true">
1796 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1797 \begin_inset Text
1798
1799 \layout Standard
1800
1801 Total
1802 \end_inset 
1803 </cell>
1804 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1805 \begin_inset Text
1806
1807 \layout Standard
1808
1809 frame
1810 \end_inset 
1811 </cell>
1812 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1813 \begin_inset Text
1814
1815 \layout Standard
1816
1817 3
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 35
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 111
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 191
1842 \end_inset 
1843 </cell>
1844 </row>
1845 </lyxtabular>
1846
1847 \end_inset 
1848
1849
1850 \layout Caption
1851
1852 Bit allocation for high-band in wideband mode
1853 \begin_inset LatexCommand \label{cap:bits-wideband}
1854
1855 \end_inset 
1856
1857
1858 \end_inset 
1859
1860
1861 \layout Section
1862
1863 Programming with Speex (the libspeex API)
1864 \layout Subsection
1865
1866 Encoding
1867 \layout Standard
1868
1869 In order to encode speech using Speex, you first need to:
1870 \layout LyX-Code
1871
1872 #include <speex.h>
1873 \layout Standard
1874
1875 You then need to declare a Speex bit-packing struct
1876 \layout LyX-Code
1877
1878 SpeexBits bits;
1879 \layout Standard
1880
1881 and a Speex encoder state
1882 \layout LyX-Code
1883
1884 void *enc_state;
1885 \layout Standard
1886
1887 The two are initialized by:
1888 \layout LyX-Code
1889
1890 speex_bits_init(&bits);
1891 \layout LyX-Code
1892
1893 enc_state = speex_encoder_init(&speex_nb_mode);
1894 \layout Standard
1895
1896 For wideband coding, 
1897 \emph on 
1898 speex_nb_mode
1899 \emph default 
1900  will be replaced by 
1901 \emph on 
1902 speex_wb_mode
1903 \emph default 
1904 .
1905  In most cases, you will need to know the frame size used by the mode you
1906  are using.
1907  You can get that value in the 
1908 \emph on 
1909 frame_size
1910 \emph default 
1911  variable with:
1912 \layout LyX-Code
1913
1914 speex_encoder_ctl(enc_state,SPEEX_GET_FRAME_SIZE,&frame_size);
1915 \layout Standard
1916
1917 Once the initialization is done, for every input frame:
1918 \layout LyX-Code
1919
1920 speex_bits_reset(&bits);
1921 \layout LyX-Code
1922
1923 speex_encode(enc_state, input_frame, &bits);
1924 \layout LyX-Code
1925
1926 nbBytes = speex_bits_write(&bits, byte_ptr, MAX_NB_BYTES);
1927 \layout Standard
1928
1929 where 
1930 \emph on 
1931 input_frame
1932 \emph default 
1933  is a 
1934 \emph on 
1935 (float *)
1936 \emph default 
1937  pointing to the beginning of a speech frame, 
1938 \emph on 
1939 byte_ptr
1940 \emph default 
1941  is a 
1942 \emph on 
1943 (char *)
1944 \emph default 
1945  where the encoded frame will be written, 
1946 \emph on 
1947 MAX_NB_BYTES
1948 \emph default 
1949  is the maximum number of bytes that can be written to 
1950 \emph on 
1951 byte_ptr
1952 \emph default 
1953  without causing an overflow and 
1954 \emph on 
1955 nbBytes
1956 \emph default 
1957  is the number of bytes actually written to 
1958 \emph on 
1959 byte_ptr
1960 \emph default 
1961  (the encoded size in bytes).
1962  Before calling speex_bits_write, it is possible to find the number of bytes
1963  that need to be written by calling 
1964 \family typewriter 
1965 speex_bits_nbytes(&bits)
1966 \family default 
1967 , which returns a number of bytes.
1968  
1969 \layout Standard
1970
1971 After you're done with the encoding, free all resources with:
1972 \layout LyX-Code
1973
1974 speex_bits_destroy(&bits);
1975 \layout LyX-Code
1976
1977 speex_encoder_destroy(&enc_state);
1978 \layout Standard
1979
1980 That's about it for the encoder.
1981  
1982 \layout Subsection
1983
1984 Decoding
1985 \layout Standard
1986
1987 In order to encode speech using Speex, you first need to:
1988 \layout LyX-Code
1989
1990 #include <speex.h>
1991 \layout Standard
1992
1993 You then need to declare a Speex bit-packing struct
1994 \layout LyX-Code
1995
1996 SpeexBits bits;
1997 \layout Standard
1998
1999 and a Speex encoder state
2000 \layout LyX-Code
2001
2002 void *dec_state;
2003 \layout Standard
2004
2005 The two are initialized by:
2006 \layout LyX-Code
2007
2008 speex_bits_init(&bits);
2009 \layout LyX-Code
2010
2011 dec_state = speex_decoder_init(&speex_nb_mode);
2012 \layout Standard
2013
2014 For wideband decoding, 
2015 \emph on 
2016 speex_nb_mode
2017 \emph default 
2018  will be replaced by 
2019 \emph on 
2020 speex_wb_mode
2021 \emph default 
2022 .
2023  You can get that value in the 
2024 \emph on 
2025 frame_size
2026 \emph default 
2027  variable with:
2028 \layout LyX-Code
2029
2030 speex_decoder_ctl(dec_state, SPEEX_GET_FRAME_SIZE, &frame_size); 
2031 \layout Standard
2032
2033 There is also a parameter that can be set for the decoder: whether or not
2034  to use a perceptual post-filter.
2035  This can be set by: 
2036 \layout LyX-Code
2037
2038 speex_decoder_ctl(dec_state, SPEEX_SET_PF, &pf); 
2039 \layout Standard
2040
2041 where pf is an int that with value 0 to have the post-filter disabled and
2042  1 to have it enabled.
2043 \layout Standard
2044
2045 Again, once the decoder initialization is done, for every input frame:
2046 \layout LyX-Code
2047
2048 speex_bits_read_from(&bits, input_bytes, nbBytes);
2049 \layout LyX-Code
2050
2051 speex_decode(st, &bits, output_frame, 0);
2052 \layout Standard
2053
2054 where input_bytes is a 
2055 \emph on 
2056 (char *)
2057 \emph default 
2058  containing the bit-stream data received for a frame, 
2059 \emph on 
2060 nbBytes
2061 \emph default 
2062  is the size (in bytes) of that bit-stream, and 
2063 \emph on 
2064 output_frame
2065 \emph default 
2066  is a 
2067 \emph on 
2068 (float *)
2069 \emph default 
2070  and points to the area where the decoded speech frame will be written.
2071  The last argument indicates whether the frame we'd like to decode was lost.
2072  A value of 0 indicates the normal case where bits points to the bit of
2073  the current frame.
2074  A value of 1 indicates that we don't have the bits for the current frame,
2075  in which case the bits argument should be the same as the bits for the
2076  last correctly received frame.
2077  When a frame is lost, the Speex decoder will do its best to "guess" the
2078  correct signal.
2079 \layout Subsection
2080
2081 Codec Options (speex_*_ctl)
2082 \layout Standard
2083
2084 The Speex encoder and decoder support many options and requests that can
2085  be accessed through the 
2086 \emph on 
2087 speex_encoder_ctl
2088 \emph default 
2089  and 
2090 \emph on 
2091 speex_decoder_ctl
2092 \emph default 
2093  functions.
2094  These functions are similar the the 
2095 \emph on 
2096 ioctl
2097 \emph default 
2098  system call and their prototypes are:
2099 \layout LyX-Code
2100
2101 void speex_encoder_ctl(void *encoder, int request, void *ptr);
2102 \layout LyX-Code
2103
2104 void speex_decoder_ctl(void *encoder, int request, void *ptr);
2105 \layout Standard
2106
2107 The different values of request allowed are (note that some only apply to
2108  the encoder or the decoder):
2109 \layout Description
2110
2111 SPEEX_SET_PF** Set post-filter to on (1) or off (0) (integer)
2112 \layout Description
2113
2114 SPEEX_GET_PF** Get post-filter status (integer)
2115 \layout Description
2116
2117 SPEEX_GET_FRAME_SIZE Get the frame size used for the current mode (integer)
2118 \layout Description
2119
2120 SPEEX_SET_QUALITY* Set the encoder speech quality (integer 0 to 10)
2121 \layout Description
2122
2123 SPEEX_GET_QUALITY* Get the current encoder speech quality (integer 0 to
2124  10)
2125 \layout Description
2126
2127 SPEEX_SET_MODE*
2128 \begin_inset Formula $\dagger $
2129 \end_inset 
2130
2131
2132 \layout Description
2133
2134 SPEEX_GET_MODE*
2135 \begin_inset Formula $\dagger $
2136 \end_inset 
2137
2138
2139 \layout Description
2140
2141 SPEEX_SET_LOW_MODE*
2142 \begin_inset Formula $\dagger $
2143 \end_inset 
2144
2145
2146 \layout Description
2147
2148 SPEEX_GET_LOW_MODE*
2149 \begin_inset Formula $\dagger $
2150 \end_inset 
2151
2152
2153 \layout Description
2154
2155 SPEEX_SET_HIGH_MODE*
2156 \begin_inset Formula $\dagger $
2157 \end_inset 
2158
2159
2160 \layout Description
2161
2162 SPEEX_GET_HIGH_MODE*
2163 \begin_inset Formula $\dagger $
2164 \end_inset 
2165
2166
2167 \layout Description
2168
2169 SPEEX_SET_VBR* Set variable bit-rate (VBR) to on (1) or off (0) (integer)
2170 \layout Description
2171
2172 SPEEX_GET_VBR* Get variable bit-rate (VBR) status (integer)
2173 \layout Description
2174
2175 SPEEX_SET_VBR_QUALITY* Set the encoder VBR speech quality (integer 0 to
2176  10)
2177 \layout Description
2178
2179 SPEEX_GET_VBR_QUALITY* Get the current encoder VBR speech quality (integer
2180  0 to 10)
2181 \layout Description
2182
2183 * applies only to the encoder
2184 \layout Description
2185
2186 ** applies only to the decoder
2187 \layout Description
2188
2189
2190 \begin_inset Formula $\dagger $
2191 \end_inset 
2192
2193  normally only used internally
2194 \layout Section
2195
2196 Formats and standards
2197 \layout Standard
2198
2199 Speex can encode speech in both narrowband and wideband and provides different
2200  bit-rates.
2201  All modes of operation MUST be supported at the decoder and at least one
2202  MUST be supported by the encoder.
2203  The main reason is that not all platforms may be able to handle the complexity
2204  of encoding for all modes.
2205 \layout Subsection
2206
2207 RTP Payload Format
2208 \layout Standard
2209
2210 Since Speex encoded frames already contain mode information, they can be
2211  sent without any other information in an RTP packet.
2212  If more than one frame is transmitted, no byte padding is performed at
2213  the end of frames, except the last one.
2214 \layout Subsection
2215
2216 Ogg file format
2217 \layout Standard
2218
2219 Speex bit-streams can be stored in Ogg files.
2220  In this case, the first packet of the Ogg file contains the Speex header
2221  (see speex_header.h for now) and the second packet contains comments.
2222  The next frames contain one or more (number found in header) Speex frames.
2223 \layout LyX-Code
2224
2225 \layout Section
2226 \pagebreak_top \start_of_appendix 
2227 GNU Free Documentation License
2228 \layout Standard
2229
2230 Version 1.1, March 2000
2231 \layout Standard
2232
2233 Copyright (C) 2000 Free Software Foundation, Inc.
2234  59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted
2235  to copy and distribute verbatim copies of this license document, but changing
2236  it is not allowed.
2237  
2238 \layout Subsection*
2239
2240 0.
2241  PREAMBLE
2242 \layout Standard
2243
2244 The purpose of this License is to make a manual, textbook, or other written
2245  document "free" in the sense of freedom: to assure everyone the effective
2246  freedom to copy and redistribute it, with or without modifying it, either
2247  commercially or noncommercially.
2248  Secondarily, this License preserves for the author and publisher a way
2249  to get credit for their work, while not being considered responsible for
2250  modifications made by others.
2251 \layout Standard
2252
2253 This License is a kind of "copyleft", which means that derivative works
2254  of the document must themselves be free in the same sense.
2255  It complements the GNU General Public License, which is a copyleft license
2256  designed for free software.
2257 \layout Standard
2258
2259 We have designed this License in order to use it for manuals for free software,
2260  because free software needs free documentation: a free program should come
2261  with manuals providing the same freedoms that the software does.
2262  But this License is not limited to software manuals; it can be used for
2263  any textual work, regardless of subject matter or whether it is published
2264  as a printed book.
2265  We recommend this License principally for works whose purpose is instruction
2266  or reference.
2267  
2268 \layout Subsection*
2269
2270 1.
2271  APPLICABILITY AND DEFINITIONS
2272 \layout Standard
2273
2274 This License applies to any manual or other work that contains a notice
2275  placed by the copyright holder saying it can be distributed under the terms
2276  of this License.
2277  The "Document", below, refers to any such manual or work.
2278  Any member of the public is a licensee, and is addressed as "you".
2279 \layout Standard
2280
2281 A "Modified Version" of the Document means any work containing the Document
2282  or a portion of it, either copied verbatim, or with modifications and/or
2283  translated into another language.
2284 \layout Standard
2285
2286 A "Secondary Section" is a named appendix or a front-matter section of the
2287  Document that deals exclusively with the relationship of the publishers
2288  or authors of the Document to the Document's overall subject (or to related
2289  matters) and contains nothing that could fall directly within that overall
2290  subject.
2291  (For example, if the Document is in part a textbook of mathematics, a Secondary
2292  Section may not explain any mathematics.) The relationship could be a matter
2293  of historical connection with the subject or with related matters, or of
2294  legal, commercial, philosophical, ethical or political position regarding
2295  them.
2296 \layout Standard
2297
2298 The "Invariant Sections" are certain Secondary Sections whose titles are
2299  designated, as being those of Invariant Sections, in the notice that says
2300  that the Document is released under this License.
2301 \layout Standard
2302
2303 The "Cover Texts" are certain short passages of text that are listed, as
2304  Front-Cover Texts or Back-Cover Texts, in the notice that says that the
2305  Document is released under this License.
2306 \layout Standard
2307
2308 A "Transparent" copy of the Document means a machine-readable copy, represented
2309  in a format whose specification is available to the general public, whose
2310  contents can be viewed and edited directly and straightforwardly with generic
2311  text editors or (for images composed of pixels) generic paint programs
2312  or (for drawings) some widely available drawing editor, and that is suitable
2313  for input to text formatters or for automatic translation to a variety
2314  of formats suitable for input to text formatters.
2315  A copy made in an otherwise Transparent file format whose markup has been
2316  designed to thwart or discourage subsequent modification by readers is
2317  not Transparent.
2318  A copy that is not "Transparent" is called "Opaque".
2319 \layout Standard
2320
2321 Examples of suitable formats for Transparent copies include plain ASCII
2322  without markup, Texinfo input format, LaTeX input format, SGML or XML using
2323  a publicly available DTD, and standard-conforming simple HTML designed
2324  for human modification.
2325  Opaque formats include PostScript, PDF, proprietary formats that can be
2326  read and edited only by proprietary word processors, SGML or XML for which
2327  the DTD and/or processing tools are not generally available, and the machine-ge
2328 nerated HTML produced by some word processors for output purposes only.
2329 \layout Standard
2330
2331 The "Title Page" means, for a printed book, the title page itself, plus
2332  such following pages as are needed to hold, legibly, the material this
2333  License requires to appear in the title page.
2334  For works in formats which do not have any title page as such, "Title Page"
2335  means the text near the most prominent appearance of the work's title,
2336  preceding the beginning of the body of the text.
2337 \layout Subsection*
2338
2339 2.
2340  VERBATIM COPYING
2341 \layout Standard
2342
2343 You may copy and distribute the Document in any medium, either commercially
2344  or noncommercially, provided that this License, the copyright notices,
2345  and the license notice saying this License applies to the Document are
2346  reproduced in all copies, and that you add no other conditions whatsoever
2347  to those of this License.
2348  You may not use technical measures to obstruct or control the reading or
2349  further copying of the copies you make or distribute.
2350  However, you may accept compensation in exchange for copies.
2351  If you distribute a large enough number of copies you must also follow
2352  the conditions in section 3.
2353 \layout Standard
2354
2355 You may also lend copies, under the same conditions stated above, and you
2356  may publicly display copies.
2357 \layout Subsection*
2358
2359 3.
2360  COPYING IN QUANTITY
2361 \layout Standard
2362
2363 If you publish printed copies of the Document numbering more than 100, and
2364  the Document's license notice requires Cover Texts, you must enclose the
2365  copies in covers that carry, clearly and legibly, all these Cover Texts:
2366  Front-Cover Texts on the front cover, and Back-Cover Texts on the back
2367  cover.
2368  Both covers must also clearly and legibly identify you as the publisher
2369  of these copies.
2370  The front cover must present the full title with all words of the title
2371  equally prominent and visible.
2372  You may add other material on the covers in addition.
2373  Copying with changes limited to the covers, as long as they preserve the
2374  title of the Document and satisfy these conditions, can be treated as verbatim
2375  copying in other respects.
2376 \layout Standard
2377
2378 If the required texts for either cover are too voluminous to fit legibly,
2379  you should put the first ones listed (as many as fit reasonably) on the
2380  actual cover, and continue the rest onto adjacent pages.
2381 \layout Standard
2382
2383 If you publish or distribute Opaque copies of the Document numbering more
2384  than 100, you must either include a machine-readable Transparent copy along
2385  with each Opaque copy, or state in or with each Opaque copy a publicly-accessib
2386 le computer-network location containing a complete Transparent copy of the
2387  Document, free of added material, which the general network-using public
2388  has access to download anonymously at no charge using public-standard network
2389  protocols.
2390  If you use the latter option, you must take reasonably prudent steps, when
2391  you begin distribution of Opaque copies in quantity, to ensure that this
2392  Transparent copy will remain thus accessible at the stated location until
2393  at least one year after the last time you distribute an Opaque copy (directly
2394  or through your agents or retailers) of that edition to the public.
2395 \layout Standard
2396
2397 It is requested, but not required, that you contact the authors of the Document
2398  well before redistributing any large number of copies, to give them a chance
2399  to provide you with an updated version of the Document.
2400  
2401 \layout Subsection*
2402
2403 4.
2404  MODIFICATIONS
2405 \layout Standard
2406
2407 You may copy and distribute a Modified Version of the Document under the
2408  conditions of sections 2 and 3 above, provided that you release the Modified
2409  Version under precisely this License, with the Modified Version filling
2410  the role of the Document, thus licensing distribution and modification
2411  of the Modified Version to whoever possesses a copy of it.
2412  In addition, you must do these things in the Modified Version: 
2413 \layout Itemize
2414
2415 A.
2416  Use in the Title Page (and on the covers, if any) a title distinct from
2417  that of the Document, and from those of previous versions (which should,
2418  if there were any, be listed in the History section of the Document).
2419  You may use the same title as a previous version if the original publisher
2420  of that version gives permission.
2421 \layout Itemize
2422
2423 B.
2424  List on the Title Page, as authors, one or more persons or entities responsible
2425  for authorship of the modifications in the Modified Version, together with
2426  at least five of the principal authors of the Document (all of its principal
2427  authors, if it has less than five).
2428 \layout Itemize
2429
2430 C.
2431  State on the Title page the name of the publisher of the Modified Version,
2432  as the publisher.
2433 \layout Itemize
2434
2435 D.
2436  Preserve all the copyright notices of the Document.
2437 \layout Itemize
2438
2439 E.
2440  Add an appropriate copyright notice for your modifications adjacent to
2441  the other copyright notices.
2442 \layout Itemize
2443
2444 F.
2445  Include, immediately after the copyright notices, a license notice giving
2446  the public permission to use the Modified Version under the terms of this
2447  License, in the form shown in the Addendum below.
2448 \layout Itemize
2449
2450 G.
2451  Preserve in that license notice the full lists of Invariant Sections and
2452  required Cover Texts given in the Document's license notice.
2453 \layout Itemize
2454
2455 H.
2456  Include an unaltered copy of this License.
2457 \layout Itemize
2458
2459 I.
2460  Preserve the section entitled "History", and its title, and add to it an
2461  item stating at least the title, year, new authors, and publisher of the
2462  Modified Version as given on the Title Page.
2463  If there is no section entitled "History" in the Document, create one stating
2464  the title, year, authors, and publisher of the Document as given on its
2465  Title Page, then add an item describing the Modified Version as stated
2466  in the previous sentence.
2467 \layout Itemize
2468
2469 J.
2470  Preserve the network location, if any, given in the Document for public
2471  access to a Transparent copy of the Document, and likewise the network
2472  locations given in the Document for previous versions it was based on.
2473  These may be placed in the "History" section.
2474  You may omit a network location for a work that was published at least
2475  four years before the Document itself, or if the original publisher of
2476  the version it refers to gives permission.
2477 \layout Itemize
2478
2479 K.
2480  In any section entitled "Acknowledgements" or "Dedications", preserve the
2481  section's title, and preserve in the section all the substance and tone
2482  of each of the contributor acknowledgements and/or dedications given therein.
2483 \layout Itemize
2484
2485 L.
2486  Preserve all the Invariant Sections of the Document, unaltered in their
2487  text and in their titles.
2488  Section numbers or the equivalent are not considered part of the section
2489  titles.
2490 \layout Itemize
2491
2492 M.
2493  Delete any section entitled "Endorsements".
2494  Such a section may not be included in the Modified Version.
2495 \layout Itemize
2496
2497 N.
2498  Do not retitle any existing section as "Endorsements" or to conflict in
2499  title with any Invariant Section.
2500  
2501 \layout Standard
2502
2503 If the Modified Version includes new front-matter sections or appendices
2504  that qualify as Secondary Sections and contain no material copied from
2505  the Document, you may at your option designate some or all of these sections
2506  as invariant.
2507  To do this, add their titles to the list of Invariant Sections in the Modified
2508  Version's license notice.
2509  These titles must be distinct from any other section titles.
2510 \layout Standard
2511
2512 You may add a section entitled "Endorsements", provided it contains nothing
2513  but endorsements of your Modified Version by various parties--for example,
2514  statements of peer review or that the text has been approved by an organization
2515  as the authoritative definition of a standard.
2516 \layout Standard
2517
2518 You may add a passage of up to five words as a Front-Cover Text, and a passage
2519  of up to 25 words as a Back-Cover Text, to the end of the list of Cover
2520  Texts in the Modified Version.
2521  Only one passage of Front-Cover Text and one of Back-Cover Text may be
2522  added by (or through arrangements made by) any one entity.
2523  If the Document already includes a cover text for the same cover, previously
2524  added by you or by arrangement made by the same entity you are acting on
2525  behalf of, you may not add another; but you may replace the old one, on
2526  explicit permission from the previous publisher that added the old one.
2527 \layout Standard
2528
2529 The author(s) and publisher(s) of the Document do not by this License give
2530  permission to use their names for publicity for or to assert or imply endorseme
2531 nt of any Modified Version.
2532  
2533 \layout Subsection*
2534
2535 5.
2536  COMBINING DOCUMENTS
2537 \layout Standard
2538
2539 You may combine the Document with other documents released under this License,
2540  under the terms defined in section 4 above for modified versions, provided
2541  that you include in the combination all of the Invariant Sections of all
2542  of the original documents, unmodified, and list them all as Invariant Sections
2543  of your combined work in its license notice.
2544 \layout Standard
2545
2546 The combined work need only contain one copy of this License, and multiple
2547  identical Invariant Sections may be replaced with a single copy.
2548  If there are multiple Invariant Sections with the same name but different
2549  contents, make the title of each such section unique by adding at the end
2550  of it, in parentheses, the name of the original author or publisher of
2551  that section if known, or else a unique number.
2552  Make the same adjustment to the section titles in the list of Invariant
2553  Sections in the license notice of the combined work.
2554 \layout Standard
2555
2556 In the combination, you must combine any sections entitled "History" in
2557  the various original documents, forming one section entitled "History";
2558  likewise combine any sections entitled "Acknowledgements", and any sections
2559  entitled "Dedications".
2560  You must delete all sections entitled "Endorsements."
2561 \layout Subsection*
2562
2563 6.
2564  COLLECTIONS OF DOCUMENTS
2565 \layout Standard
2566
2567 You may make a collection consisting of the Document and other documents
2568  released under this License, and replace the individual copies of this
2569  License in the various documents with a single copy that is included in
2570  the collection, provided that you follow the rules of this License for
2571  verbatim copying of each of the documents in all other respects.
2572 \layout Standard
2573
2574 You may extract a single document from such a collection, and distribute
2575  it individually under this License, provided you insert a copy of this
2576  License into the extracted document, and follow this License in all other
2577  respects regarding verbatim copying of that document.
2578  
2579 \layout Subsection*
2580
2581 7.
2582  AGGREGATION WITH INDEPENDENT WORKS
2583 \layout Standard
2584
2585 A compilation of the Document or its derivatives with other separate and
2586  independent documents or works, in or on a volume of a storage or distribution
2587  medium, does not as a whole count as a Modified Version of the Document,
2588  provided no compilation copyright is claimed for the compilation.
2589  Such a compilation is called an "aggregate", and this License does not
2590  apply to the other self-contained works thus compiled with the Document,
2591  on account of their being thus compiled, if they are not themselves derivative
2592  works of the Document.
2593 \layout Standard
2594
2595 If the Cover Text requirement of section 3 is applicable to these copies
2596  of the Document, then if the Document is less than one quarter of the entire
2597  aggregate, the Document's Cover Texts may be placed on covers that surround
2598  only the Document within the aggregate.
2599  Otherwise they must appear on covers around the whole aggregate.
2600 \layout Subsection*
2601
2602 8.
2603  TRANSLATION
2604 \layout Standard
2605
2606 Translation is considered a kind of modification, so you may distribute
2607  translations of the Document under the terms of section 4.
2608  Replacing Invariant Sections with translations requires special permission
2609  from their copyright holders, but you may include translations of some
2610  or all Invariant Sections in addition to the original versions of these
2611  Invariant Sections.
2612  You may include a translation of this License provided that you also include
2613  the original English version of this License.
2614  In case of a disagreement between the translation and the original English
2615  version of this License, the original English version will prevail.
2616 \layout Subsection*
2617
2618 9.
2619  TERMINATION
2620 \layout Standard
2621
2622 You may not copy, modify, sublicense, or distribute the Document except
2623  as expressly provided for under this License.
2624  Any other attempt to copy, modify, sublicense or distribute the Document
2625  is void, and will automatically terminate your rights under this License.
2626  However, parties who have received copies, or rights, from you under this
2627  License will not have their licenses terminated so long as such parties
2628  remain in full compliance.
2629  
2630 \layout Subsection*
2631
2632 10.
2633  FUTURE REVISIONS OF THIS LICENSE
2634 \layout Standard
2635
2636 The Free Software Foundation may publish new, revised versions of the GNU
2637  Free Documentation License from time to time.
2638  Such new versions will be similar in spirit to the present version, but
2639  may differ in detail to address new problems or concerns.
2640  See http://www.gnu.org/copyleft/.
2641 \layout Standard
2642
2643 Each version of the License is given a distinguishing version number.
2644  If the Document specifies that a particular numbered version of this License
2645  "or any later version" applies to it, you have the option of following
2646  the terms and conditions either of that specified version or of any later
2647  version that has been published (not as a draft) by the Free Software Foundatio
2648 n.
2649  If the Document does not specify a version number of this License, you
2650  may choose any version ever published (not as a draft) by the Free Software
2651  Foundation.
2652 \the_end