modified for upcoming 0.7.0
[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 and described here should
1702  only be considered as a reference implementation.
1703  The enhancement system is devided in two parts.
1704  First, the synthesis filter 
1705 \begin_inset Formula $S(z)=1/A(z)$
1706 \end_inset 
1707
1708  is replaced by an enhanced filter
1709 \begin_inset Formula \[
1710 S'(z)=\frac{A\left(z/a_{2}\right)A\left(z/a_{3}\right)}{A\left(z\right)A\left(z/a_{1}\right)}\]
1711
1712 \end_inset 
1713
1714 where 
1715 \begin_inset Formula $a_{1}$
1716 \end_inset 
1717
1718  and 
1719 \begin_inset Formula $a_{2}$
1720 \end_inset 
1721
1722  depend on the mode in use and 
1723 \begin_inset Formula $a_{3}=\frac{1}{r}\left(1-\frac{1-ra_{1}}{1-ra_{2}}\right)$
1724 \end_inset 
1725
1726  with 
1727 \begin_inset Formula $r=.9$
1728 \end_inset 
1729
1730 .
1731  The second part of the enhancement consists of using a comb filter to enhance
1732  the pitch in the excitation.
1733  
1734 \layout Section
1735 \pagebreak_top 
1736 Speex wideband mode (sub-band CELP)
1737 \layout Standard
1738
1739 For wideband, the Speex approach uses a 
1740 \emph on 
1741 q
1742 \emph default 
1743 uadrature 
1744 \emph on 
1745 m
1746 \emph default 
1747 irror 
1748 \emph on 
1749 f
1750 \emph default 
1751 ilter (QMF) to split the band in two.
1752  The 16 kHz signal is thus divided into two 8 kHz signals, one representing
1753  the low band (0-4 kHz), the other the high band (4-8 kHz).
1754  The low band is encoded with the narrowband mode described in section 
1755 \begin_inset LatexCommand \ref{sec:Speex-narrowband-mode}
1756
1757 \end_inset 
1758
1759  in such a way that the resulting 
1760 \begin_inset Quotes eld
1761 \end_inset 
1762
1763 embedded narrowband bit-stream
1764 \begin_inset Quotes erd
1765 \end_inset 
1766
1767  can also be decoded with the narrowband decoder.
1768  Since the low band encoding has already been described only the high band
1769  encoding is described in this section.
1770 \layout Subsection
1771
1772 Linear Prediction
1773 \layout Standard
1774
1775 The linear prediction part used for the high-band is very similar to what
1776  is done for narrowband.
1777  The only difference is that we use only 12 bits to encode the high-band
1778  LSP's.
1779 \layout Subsection
1780
1781 Pitch Prediction
1782 \layout Standard
1783
1784 That part is easy: there's no pitch prediction for the high-band.
1785  There are two reasons for that.
1786  First, there is usually little harmonic structure in this band (above 4
1787  kHz).
1788  Second, it would be very hard to implement since the QMF folds the 4-8
1789  kHz band into 4-0 kHz (reversing the frequency axis), which means that
1790  the location of the harmonics are no longer at multiples of the fundamental
1791  (pitch).
1792 \layout Subsection
1793
1794 Excitation Quantization
1795 \layout Standard
1796
1797 The high-band excitation is coded in the same way as for narrowband.
1798  
1799 \layout Subsection
1800
1801 Bit allocation
1802 \layout Standard
1803
1804 For the wideband mode, all the narrowband frame is packed before the high-band
1805  is encoded.
1806  The narrowband part of the bit-stream is as defined in table 
1807 \begin_inset LatexCommand \ref{cap:bits-narrowband}
1808
1809 \end_inset 
1810
1811 .
1812  The high-band follows, as described in table 
1813 \begin_inset LatexCommand \ref{cap:bits-wideband}
1814
1815 \end_inset 
1816
1817 .
1818  This also means that a wideband frame may be correctly decoded by a narrowband
1819  decoder with the only caveat that if more than one frame is packed in the
1820  same packet, the decoder will need to skip the high-band parts in order
1821  to sync with the bit-stream.
1822 \layout Standard
1823
1824
1825 \begin_inset Float table
1826 placement htbp
1827 wide true
1828 collapsed false
1829
1830 \layout Standard
1831
1832
1833 \begin_inset  Tabular
1834 <lyxtabular version="3" rows="6" columns="6">
1835 <features>
1836 <column alignment="center" valignment="top" leftline="true" width="0pt">
1837 <column alignment="center" valignment="top" leftline="true" width="0pt">
1838 <column alignment="center" valignment="top" leftline="true" width="0pt">
1839 <column alignment="center" valignment="top" leftline="true" width="0pt">
1840 <column alignment="center" valignment="top" leftline="true" width="0pt">
1841 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
1842 <row topline="true" bottomline="true">
1843 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1844 \begin_inset Text
1845
1846 \layout Standard
1847
1848 Parameter
1849 \end_inset 
1850 </cell>
1851 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1852 \begin_inset Text
1853
1854 \layout Standard
1855
1856 Update rate
1857 \end_inset 
1858 </cell>
1859 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1860 \begin_inset Text
1861
1862 \layout Standard
1863
1864 0
1865 \end_inset 
1866 </cell>
1867 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1868 \begin_inset Text
1869
1870 \layout Standard
1871
1872 1
1873 \end_inset 
1874 </cell>
1875 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1876 \begin_inset Text
1877
1878 \layout Standard
1879
1880 2
1881 \end_inset 
1882 </cell>
1883 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1884 \begin_inset Text
1885
1886 \layout Standard
1887
1888 3
1889 \end_inset 
1890 </cell>
1891 </row>
1892 <row topline="true">
1893 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1894 \begin_inset Text
1895
1896 \layout Standard
1897
1898 Mode ID
1899 \end_inset 
1900 </cell>
1901 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1902 \begin_inset Text
1903
1904 \layout Standard
1905
1906 frame
1907 \end_inset 
1908 </cell>
1909 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1910 \begin_inset Text
1911
1912 \layout Standard
1913
1914 3
1915 \end_inset 
1916 </cell>
1917 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1918 \begin_inset Text
1919
1920 \layout Standard
1921
1922 3
1923 \end_inset 
1924 </cell>
1925 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1926 \begin_inset Text
1927
1928 \layout Standard
1929
1930 3
1931 \end_inset 
1932 </cell>
1933 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1934 \begin_inset Text
1935
1936 \layout Standard
1937
1938 3
1939 \end_inset 
1940 </cell>
1941 </row>
1942 <row topline="true">
1943 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1944 \begin_inset Text
1945
1946 \layout Standard
1947
1948 LSP
1949 \end_inset 
1950 </cell>
1951 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1952 \begin_inset Text
1953
1954 \layout Standard
1955
1956 frame
1957 \end_inset 
1958 </cell>
1959 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1960 \begin_inset Text
1961
1962 \layout Standard
1963
1964 0
1965 \end_inset 
1966 </cell>
1967 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1968 \begin_inset Text
1969
1970 \layout Standard
1971
1972 12
1973 \end_inset 
1974 </cell>
1975 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1976 \begin_inset Text
1977
1978 \layout Standard
1979
1980 12
1981 \end_inset 
1982 </cell>
1983 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1984 \begin_inset Text
1985
1986 \layout Standard
1987
1988 12
1989 \end_inset 
1990 </cell>
1991 </row>
1992 <row topline="true">
1993 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1994 \begin_inset Text
1995
1996 \layout Standard
1997
1998 Excitation gain
1999 \end_inset 
2000 </cell>
2001 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2002 \begin_inset Text
2003
2004 \layout Standard
2005
2006 sub-frame
2007 \end_inset 
2008 </cell>
2009 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2010 \begin_inset Text
2011
2012 \layout Standard
2013
2014 0
2015 \end_inset 
2016 </cell>
2017 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2018 \begin_inset Text
2019
2020 \layout Standard
2021
2022 5
2023 \end_inset 
2024 </cell>
2025 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2026 \begin_inset Text
2027
2028 \layout Standard
2029
2030 4
2031 \end_inset 
2032 </cell>
2033 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2034 \begin_inset Text
2035
2036 \layout Standard
2037
2038 4
2039 \end_inset 
2040 </cell>
2041 </row>
2042 <row topline="true" bottomline="true">
2043 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2044 \begin_inset Text
2045
2046 \layout Standard
2047
2048 Excitation VQ
2049 \end_inset 
2050 </cell>
2051 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2052 \begin_inset Text
2053
2054 \layout Standard
2055
2056 sub-frame
2057 \end_inset 
2058 </cell>
2059 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2060 \begin_inset Text
2061
2062 \layout Standard
2063
2064 0
2065 \end_inset 
2066 </cell>
2067 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2068 \begin_inset Text
2069
2070 \layout Standard
2071
2072 0
2073 \end_inset 
2074 </cell>
2075 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2076 \begin_inset Text
2077
2078 \layout Standard
2079
2080 20
2081 \end_inset 
2082 </cell>
2083 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2084 \begin_inset Text
2085
2086 \layout Standard
2087
2088 40
2089 \end_inset 
2090 </cell>
2091 </row>
2092 <row topline="true" bottomline="true">
2093 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2094 \begin_inset Text
2095
2096 \layout Standard
2097
2098 Total
2099 \end_inset 
2100 </cell>
2101 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2102 \begin_inset Text
2103
2104 \layout Standard
2105
2106 frame
2107 \end_inset 
2108 </cell>
2109 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2110 \begin_inset Text
2111
2112 \layout Standard
2113
2114 3
2115 \end_inset 
2116 </cell>
2117 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2118 \begin_inset Text
2119
2120 \layout Standard
2121
2122 35
2123 \end_inset 
2124 </cell>
2125 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2126 \begin_inset Text
2127
2128 \layout Standard
2129
2130 111
2131 \end_inset 
2132 </cell>
2133 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2134 \begin_inset Text
2135
2136 \layout Standard
2137
2138 191
2139 \end_inset 
2140 </cell>
2141 </row>
2142 </lyxtabular>
2143
2144 \end_inset 
2145
2146
2147 \layout Caption
2148
2149 Bit allocation for high-band in wideband mode
2150 \begin_inset LatexCommand \label{cap:bits-wideband}
2151
2152 \end_inset 
2153
2154
2155 \end_inset 
2156
2157
2158 \layout Section
2159
2160 Command-line encoder/decoder
2161 \layout Standard
2162
2163 The base Speex distribution includes a command-line encoder (
2164 \emph on 
2165 speexenc
2166 \emph default 
2167 ) and decoder (
2168 \emph on 
2169 speexdec
2170 \emph default 
2171 ).
2172 \layout Subsection
2173
2174
2175 \emph on 
2176 speexenc
2177 \layout Standard
2178
2179 The encoder takes the following options:
2180 \layout Description
2181
2182 --narrowband\SpecialChar ~
2183 (-n) Tells Speex to treat the input as narrowband (8 kHz).
2184  This is the default
2185 \layout Description
2186
2187 --wideband\SpecialChar ~
2188 (-w) Tells Speex to treat the input as wideband (16 kHz)
2189 \layout Description
2190
2191 --quality\SpecialChar ~
2192 n Set the encoding quality (0-10)
2193 \layout Description
2194
2195 --vbr Enable VBR (Variable Bit-Rate), disabled by default
2196 \layout Description
2197
2198 --nframes\SpecialChar ~
2199 n Pack n frames in each Ogg packet (this saves space at low bit-rates)
2200 \layout Description
2201
2202 --comp\SpecialChar ~
2203 n Set encoding speed/quality tradeoff.
2204  The higher the value of n, the slower the encoding (default is 3)
2205 \layout Description
2206
2207 -V Verbose operation, print bit-rate currently in use
2208 \layout Description
2209
2210 --help\SpecialChar ~
2211 (-h) Print the help
2212 \layout Description
2213
2214 --version\SpecialChar ~
2215 (-v) Pring version information
2216 \layout Subsection
2217
2218
2219 \emph on 
2220 speexdec
2221 \layout Standard
2222
2223 The decoder takes the following options:
2224 \layout Description
2225
2226 --enh enable post-filter
2227 \layout Description
2228
2229 --no-enh disable post-filter (default)
2230 \layout Description
2231
2232 -V Verbose operation, print bit-rate currently in use
2233 \layout Description
2234
2235 --help\SpecialChar ~
2236 (-h) Print the help
2237 \layout Description
2238
2239 --version\SpecialChar ~
2240 (-v) Pring version information
2241 \layout Section
2242 \pagebreak_top 
2243 Programming with Speex (the libspeex API)
2244 \layout Subsection
2245
2246 Encoding
2247 \layout Standard
2248
2249 In order to encode speech using Speex, you first need to:
2250 \layout LyX-Code
2251
2252 #include <speex.h>
2253 \layout Standard
2254
2255 You then need to declare a Speex bit-packing struct
2256 \layout LyX-Code
2257
2258 SpeexBits bits;
2259 \layout Standard
2260
2261 and a Speex encoder state
2262 \layout LyX-Code
2263
2264 void *enc_state;
2265 \layout Standard
2266
2267 The two are initialized by:
2268 \layout LyX-Code
2269
2270 speex_bits_init(&bits);
2271 \layout LyX-Code
2272
2273 enc_state = speex_encoder_init(&speex_nb_mode);
2274 \layout Standard
2275
2276 For wideband coding, 
2277 \emph on 
2278 speex_nb_mode
2279 \emph default 
2280  will be replaced by 
2281 \emph on 
2282 speex_wb_mode
2283 \emph default 
2284 .
2285  In most cases, you will need to know the frame size used by the mode you
2286  are using.
2287  You can get that value in the 
2288 \emph on 
2289 frame_size
2290 \emph default 
2291  variable with:
2292 \layout LyX-Code
2293
2294 speex_encoder_ctl(enc_state,SPEEX_GET_FRAME_SIZE,&frame_size);
2295 \layout Standard
2296
2297 Once the initialization is done, for every input frame:
2298 \layout LyX-Code
2299
2300 speex_bits_reset(&bits);
2301 \layout LyX-Code
2302
2303 speex_encode(enc_state, input_frame, &bits);
2304 \layout LyX-Code
2305
2306 nbBytes = speex_bits_write(&bits, byte_ptr, MAX_NB_BYTES);
2307 \layout Standard
2308
2309 where 
2310 \emph on 
2311 input_frame
2312 \emph default 
2313  is a 
2314 \emph on 
2315 (float *)
2316 \emph default 
2317  pointing to the beginning of a speech frame, 
2318 \emph on 
2319 byte_ptr
2320 \emph default 
2321  is a 
2322 \emph on 
2323 (char *)
2324 \emph default 
2325  where the encoded frame will be written, 
2326 \emph on 
2327 MAX_NB_BYTES
2328 \emph default 
2329  is the maximum number of bytes that can be written to 
2330 \emph on 
2331 byte_ptr
2332 \emph default 
2333  without causing an overflow and 
2334 \emph on 
2335 nbBytes
2336 \emph default 
2337  is the number of bytes actually written to 
2338 \emph on 
2339 byte_ptr
2340 \emph default 
2341  (the encoded size in bytes).
2342  Before calling speex_bits_write, it is possible to find the number of bytes
2343  that need to be written by calling 
2344 \family typewriter 
2345 speex_bits_nbytes(&bits)
2346 \family default 
2347 , which returns a number of bytes.
2348  
2349 \layout Standard
2350
2351 After you're done with the encoding, free all resources with:
2352 \layout LyX-Code
2353
2354 speex_bits_destroy(&bits);
2355 \layout LyX-Code
2356
2357 speex_encoder_destroy(&enc_state);
2358 \layout Standard
2359
2360 That's about it for the encoder.
2361  
2362 \layout Subsection
2363
2364 Decoding
2365 \layout Standard
2366
2367 In order to encode speech using Speex, you first need to:
2368 \layout LyX-Code
2369
2370 #include <speex.h>
2371 \layout Standard
2372
2373 You then need to declare a Speex bit-packing struct
2374 \layout LyX-Code
2375
2376 SpeexBits bits;
2377 \layout Standard
2378
2379 and a Speex encoder state
2380 \layout LyX-Code
2381
2382 void *dec_state;
2383 \layout Standard
2384
2385 The two are initialized by:
2386 \layout LyX-Code
2387
2388 speex_bits_init(&bits);
2389 \layout LyX-Code
2390
2391 dec_state = speex_decoder_init(&speex_nb_mode);
2392 \layout Standard
2393
2394 For wideband decoding, 
2395 \emph on 
2396 speex_nb_mode
2397 \emph default 
2398  will be replaced by 
2399 \emph on 
2400 speex_wb_mode
2401 \emph default 
2402 .
2403  You can get that value in the 
2404 \emph on 
2405 frame_size
2406 \emph default 
2407  variable with:
2408 \layout LyX-Code
2409
2410 speex_decoder_ctl(dec_state, SPEEX_GET_FRAME_SIZE, &frame_size); 
2411 \layout Standard
2412
2413 There is also a parameter that can be set for the decoder: whether or not
2414  to use a perceptual post-filter.
2415  This can be set by: 
2416 \layout LyX-Code
2417
2418 speex_decoder_ctl(dec_state, SPEEX_SET_PF, &pf); 
2419 \layout Standard
2420
2421 where pf is an int that with value 0 to have the post-filter disabled and
2422  1 to have it enabled.
2423 \layout Standard
2424
2425 Again, once the decoder initialization is done, for every input frame:
2426 \layout LyX-Code
2427
2428 speex_bits_read_from(&bits, input_bytes, nbBytes);
2429 \layout LyX-Code
2430
2431 speex_decode(st, &bits, output_frame, 0);
2432 \layout Standard
2433
2434 where input_bytes is a 
2435 \emph on 
2436 (char *)
2437 \emph default 
2438  containing the bit-stream data received for a frame, 
2439 \emph on 
2440 nbBytes
2441 \emph default 
2442  is the size (in bytes) of that bit-stream, and 
2443 \emph on 
2444 output_frame
2445 \emph default 
2446  is a 
2447 \emph on 
2448 (float *)
2449 \emph default 
2450  and points to the area where the decoded speech frame will be written.
2451  The last argument indicates whether the frame we'd like to decode was lost.
2452  A value of 0 indicates the normal case where bits points to the bit of
2453  the current frame.
2454  A value of 1 indicates that we don't have the bits for the current frame,
2455  in which case the bits argument should be the same as the bits for the
2456  last correctly received frame.
2457  When a frame is lost, the Speex decoder will do its best to "guess" the
2458  correct signal.
2459 \layout Subsection
2460
2461 Codec Options (speex_*_ctl)
2462 \layout Standard
2463
2464 The Speex encoder and decoder support many options and requests that can
2465  be accessed through the 
2466 \emph on 
2467 speex_encoder_ctl
2468 \emph default 
2469  and 
2470 \emph on 
2471 speex_decoder_ctl
2472 \emph default 
2473  functions.
2474  These functions are similar the the 
2475 \emph on 
2476 ioctl
2477 \emph default 
2478  system call and their prototypes are:
2479 \layout LyX-Code
2480
2481 void speex_encoder_ctl(void *encoder, int request, void *ptr);
2482 \layout LyX-Code
2483
2484 void speex_decoder_ctl(void *encoder, int request, void *ptr);
2485 \layout Standard
2486
2487 The different values of request allowed are (note that some only apply to
2488  the encoder or the decoder):
2489 \layout Description
2490
2491 SPEEX_SET_ENH** Set post-filter to on (1) or off (0) (integer)
2492 \layout Description
2493
2494 SPEEX_GET_ENH** Get post-filter status (integer)
2495 \layout Description
2496
2497 SPEEX_GET_FRAME_SIZE Get the frame size used for the current mode (integer)
2498 \layout Description
2499
2500 SPEEX_SET_QUALITY* Set the encoder speech quality (integer 0 to 10)
2501 \layout Description
2502
2503 SPEEX_GET_QUALITY* Get the current encoder speech quality (integer 0 to
2504  10)
2505 \layout Description
2506
2507 SPEEX_SET_MODE*
2508 \begin_inset Formula $\dagger $
2509 \end_inset 
2510
2511
2512 \layout Description
2513
2514 SPEEX_GET_MODE*
2515 \begin_inset Formula $\dagger $
2516 \end_inset 
2517
2518
2519 \layout Description
2520
2521 SPEEX_SET_LOW_MODE*
2522 \begin_inset Formula $\dagger $
2523 \end_inset 
2524
2525
2526 \layout Description
2527
2528 SPEEX_GET_LOW_MODE*
2529 \begin_inset Formula $\dagger $
2530 \end_inset 
2531
2532
2533 \layout Description
2534
2535 SPEEX_SET_HIGH_MODE*
2536 \begin_inset Formula $\dagger $
2537 \end_inset 
2538
2539
2540 \layout Description
2541
2542 SPEEX_GET_HIGH_MODE*
2543 \begin_inset Formula $\dagger $
2544 \end_inset 
2545
2546
2547 \layout Description
2548
2549 SPEEX_SET_VBR* Set variable bit-rate (VBR) to on (1) or off (0) (integer)
2550 \layout Description
2551
2552 SPEEX_GET_VBR* Get variable bit-rate (VBR) status (integer)
2553 \layout Description
2554
2555 SPEEX_SET_VBR_QUALITY* Set the encoder VBR speech quality (integer 0 to
2556  10)
2557 \layout Description
2558
2559 SPEEX_GET_VBR_QUALITY* Get the current encoder VBR speech quality (integer
2560  0 to 10)
2561 \layout Description
2562
2563 SPEEX_SET_COMPLEXITY* Set the CPU resources allowed for the encoder
2564 \layout Description
2565
2566 SPEEX_GET_COMPLEXITY* Get the CPU resources allowed for the encoder
2567 \layout Description
2568
2569 SPEEX_GET_BITRATE Get the current bit-rate in use (in bps)
2570 \layout Description
2571
2572 * applies only to the encoder
2573 \layout Description
2574
2575 ** applies only to the decoder
2576 \layout Description
2577
2578
2579 \begin_inset Formula $\dagger $
2580 \end_inset 
2581
2582  normally only used internally
2583 \layout Section
2584 \pagebreak_top 
2585 Formats and standards
2586 \layout Standard
2587
2588 Speex can encode speech in both narrowband and wideband and provides different
2589  bit-rates.
2590  However not all features must be supported by a certain implementation
2591  or device.
2592  In order to be said 
2593 \begin_inset Quotes eld
2594 \end_inset 
2595
2596 Speex compatible
2597 \begin_inset Quotes erd
2598 \end_inset 
2599
2600 , an implementation must implement at least a basic set of features.
2601 \layout Standard
2602
2603 At the minimum, all narrowband and wideband modes of operation MUST be supported
2604  at the decoder.
2605  For wideband, a decoder MAY either be able to decode all modes or be able
2606  to decode the embedded narrowband part of all modes (which includes ignoring
2607  the high-band bits).
2608 \layout Standard
2609
2610 For encoders, at least one narrowband and one wideband mode MUST be supported.
2611  Note that the wideband mode MAY be the 
2612 \begin_inset Quotes eld
2613 \end_inset 
2614
2615 null highband
2616 \begin_inset Quotes erd
2617 \end_inset 
2618
2619  mode
2620 \begin_inset Foot
2621 collapsed true
2622
2623 \layout Standard
2624
2625 This can be done by appending 4 zero bits at the end of a narrowband frame
2626 \end_inset 
2627
2628 .
2629  The main reason why all encoding modes do not have to be supported is that
2630  some platforms may not be able to handle the complexity of encoding in
2631  some modes.
2632 \layout Subsection
2633
2634 RTP Payload Format
2635 \layout Standard
2636
2637 Since Speex encoded frames already contain mode information, they can be
2638  sent without any other information in an RTP packet.
2639  If more than one frame is transmitted, no byte padding is performed at
2640  the end of frames, except the last one.
2641  The number of frames contained in each packet MUST be transmitted out-of-band.
2642  
2643 \layout Subsection
2644
2645 Ogg file format
2646 \layout Standard
2647
2648 Speex bit-streams can be stored in Ogg files.
2649  In this case, the first packet of the Ogg file contains the Speex header
2650  described in table 
2651 \begin_inset LatexCommand \ref{cap:ogg_speex_header}
2652
2653 \end_inset 
2654
2655 .
2656  All integer fields in the headers are stored as little-endian.
2657  The 
2658 \family typewriter 
2659 speex_string
2660 \family default 
2661  field must contain the 
2662 \begin_inset Quotes eld
2663 \end_inset 
2664
2665
2666 \family typewriter 
2667 Speex
2668 \family default 
2669 \SpecialChar ~
2670 \SpecialChar ~
2671 \SpecialChar ~
2672
2673 \begin_inset Quotes eld
2674 \end_inset 
2675
2676  (with 3 training spaces), which identifies the bit-stream.
2677  The next field, 
2678 \family typewriter 
2679 speex_version
2680 \family default 
2681  contains the version of Speex that encoded the file.
2682  For now, refer to speex_header.[ch] for more info.
2683  The 
2684 \emph on 
2685 beginning of stream
2686 \emph default 
2687  (
2688 \family typewriter 
2689 b_o_s
2690 \family default 
2691 ) flag is set to 1 for the header.
2692  The header packet has 
2693 \family typewriter 
2694 packetno=0
2695 \family default 
2696  and 
2697 \family typewriter 
2698 granulepos=0
2699 \family default 
2700 .
2701 \layout Standard
2702
2703 The second packet contains a user-comment string, without terminating null.
2704  The content/format of the comment string is not defined.
2705  This packet has 
2706 \family typewriter 
2707 packetno=1
2708 \family default 
2709  and 
2710 \family typewriter 
2711 granulepos=0
2712 \family default 
2713 .
2714 \layout Standard
2715
2716 The third and subsequant packets each contain one or more (number found
2717  in header) Speex frames.
2718  These are identified with 
2719 \family typewriter 
2720 packetno
2721 \family default 
2722  starting from 2 and the 
2723 \family typewriter 
2724 granulepos
2725 \family default 
2726  is the number of the first sample encoded in that packet.
2727 \layout Standard
2728
2729 The stream is terminated by a packet containing the string 
2730 \begin_inset Quotes eld
2731 \end_inset 
2732
2733 END OF STREAM
2734 \begin_inset Quotes erd
2735 \end_inset 
2736
2737  (without terminating null).
2738  The the 
2739 \emph on 
2740 end of stream
2741 \emph default 
2742  (
2743 \family typewriter 
2744 e_o_s
2745 \family default 
2746 ) flag set to 1.
2747  The decoder should rely on the 
2748 \family typewriter 
2749 e_o_s
2750 \family default 
2751  flag and 
2752 \emph on 
2753 not
2754 \emph default 
2755  on the content of the packet.
2756 \layout Standard
2757
2758
2759 \begin_inset Float table
2760 placement htbp
2761 wide true
2762 collapsed false
2763
2764 \layout Standard
2765
2766
2767 \begin_inset  Tabular
2768 <lyxtabular version="3" rows="16" columns="3">
2769 <features>
2770 <column alignment="center" valignment="top" leftline="true" width="0pt">
2771 <column alignment="center" valignment="top" leftline="true" width="0pt">
2772 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
2773 <row topline="true" bottomline="true">
2774 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2775 \begin_inset Text
2776
2777 \layout Standard
2778
2779 Field
2780 \end_inset 
2781 </cell>
2782 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2783 \begin_inset Text
2784
2785 \layout Standard
2786
2787 Type
2788 \end_inset 
2789 </cell>
2790 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2791 \begin_inset Text
2792
2793 \layout Standard
2794
2795 Size
2796 \end_inset 
2797 </cell>
2798 </row>
2799 <row topline="true">
2800 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2801 \begin_inset Text
2802
2803 \layout Standard
2804
2805 speex_string
2806 \end_inset 
2807 </cell>
2808 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2809 \begin_inset Text
2810
2811 \layout Standard
2812
2813 char[]
2814 \end_inset 
2815 </cell>
2816 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2817 \begin_inset Text
2818
2819 \layout Standard
2820
2821 8
2822 \end_inset 
2823 </cell>
2824 </row>
2825 <row topline="true">
2826 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2827 \begin_inset Text
2828
2829 \layout Standard
2830
2831 speex_version
2832 \end_inset 
2833 </cell>
2834 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2835 \begin_inset Text
2836
2837 \layout Standard
2838
2839 char[]
2840 \end_inset 
2841 </cell>
2842 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2843 \begin_inset Text
2844
2845 \layout Standard
2846
2847 20
2848 \end_inset 
2849 </cell>
2850 </row>
2851 <row topline="true">
2852 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2853 \begin_inset Text
2854
2855 \layout Standard
2856
2857 speex_header_version
2858 \end_inset 
2859 </cell>
2860 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2861 \begin_inset Text
2862
2863 \layout Standard
2864
2865 int
2866 \end_inset 
2867 </cell>
2868 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2869 \begin_inset Text
2870
2871 \layout Standard
2872
2873 4
2874 \end_inset 
2875 </cell>
2876 </row>
2877 <row topline="true">
2878 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2879 \begin_inset Text
2880
2881 \layout Standard
2882
2883 header_size
2884 \end_inset 
2885 </cell>
2886 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2887 \begin_inset Text
2888
2889 \layout Standard
2890
2891 int
2892 \end_inset 
2893 </cell>
2894 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2895 \begin_inset Text
2896
2897 \layout Standard
2898
2899 4
2900 \end_inset 
2901 </cell>
2902 </row>
2903 <row topline="true">
2904 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2905 \begin_inset Text
2906
2907 \layout Standard
2908
2909 rate
2910 \end_inset 
2911 </cell>
2912 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2913 \begin_inset Text
2914
2915 \layout Standard
2916
2917 int
2918 \end_inset 
2919 </cell>
2920 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2921 \begin_inset Text
2922
2923 \layout Standard
2924
2925 4
2926 \end_inset 
2927 </cell>
2928 </row>
2929 <row topline="true">
2930 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2931 \begin_inset Text
2932
2933 \layout Standard
2934
2935 mode
2936 \end_inset 
2937 </cell>
2938 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2939 \begin_inset Text
2940
2941 \layout Standard
2942
2943 int
2944 \end_inset 
2945 </cell>
2946 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2947 \begin_inset Text
2948
2949 \layout Standard
2950
2951 4
2952 \end_inset 
2953 </cell>
2954 </row>
2955 <row topline="true">
2956 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2957 \begin_inset Text
2958
2959 \layout Standard
2960
2961 mode_bitstream_version
2962 \end_inset 
2963 </cell>
2964 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2965 \begin_inset Text
2966
2967 \layout Standard
2968
2969 int
2970 \end_inset 
2971 </cell>
2972 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2973 \begin_inset Text
2974
2975 \layout Standard
2976
2977 4
2978 \end_inset 
2979 </cell>
2980 </row>
2981 <row topline="true">
2982 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2983 \begin_inset Text
2984
2985 \layout Standard
2986
2987 nb_channels
2988 \end_inset 
2989 </cell>
2990 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2991 \begin_inset Text
2992
2993 \layout Standard
2994
2995 int
2996 \end_inset 
2997 </cell>
2998 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2999 \begin_inset Text
3000
3001 \layout Standard
3002
3003 4
3004 \end_inset 
3005 </cell>
3006 </row>
3007 <row topline="true">
3008 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3009 \begin_inset Text
3010
3011 \layout Standard
3012
3013 bitrate
3014 \end_inset 
3015 </cell>
3016 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3017 \begin_inset Text
3018
3019 \layout Standard
3020
3021 int
3022 \end_inset 
3023 </cell>
3024 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3025 \begin_inset Text
3026
3027 \layout Standard
3028
3029 4
3030 \end_inset 
3031 </cell>
3032 </row>
3033 <row topline="true">
3034 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3035 \begin_inset Text
3036
3037 \layout Standard
3038
3039 frame_size
3040 \end_inset 
3041 </cell>
3042 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3043 \begin_inset Text
3044
3045 \layout Standard
3046
3047 int
3048 \end_inset 
3049 </cell>
3050 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3051 \begin_inset Text
3052
3053 \layout Standard
3054
3055 4
3056 \end_inset 
3057 </cell>
3058 </row>
3059 <row topline="true">
3060 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3061 \begin_inset Text
3062
3063 \layout Standard
3064
3065 vbr
3066 \end_inset 
3067 </cell>
3068 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3069 \begin_inset Text
3070
3071 \layout Standard
3072
3073 int
3074 \end_inset 
3075 </cell>
3076 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3077 \begin_inset Text
3078
3079 \layout Standard
3080
3081 4
3082 \end_inset 
3083 </cell>
3084 </row>
3085 <row topline="true">
3086 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3087 \begin_inset Text
3088
3089 \layout Standard
3090
3091 frames_per_packet
3092 \end_inset 
3093 </cell>
3094 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3095 \begin_inset Text
3096
3097 \layout Standard
3098
3099 int
3100 \end_inset 
3101 </cell>
3102 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3103 \begin_inset Text
3104
3105 \layout Standard
3106
3107 4
3108 \end_inset 
3109 </cell>
3110 </row>
3111 <row topline="true">
3112 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3113 \begin_inset Text
3114
3115 \layout Standard
3116
3117 reserved1
3118 \end_inset 
3119 </cell>
3120 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3121 \begin_inset Text
3122
3123 \layout Standard
3124
3125 int
3126 \end_inset 
3127 </cell>
3128 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3129 \begin_inset Text
3130
3131 \layout Standard
3132
3133 4
3134 \end_inset 
3135 </cell>
3136 </row>
3137 <row topline="true">
3138 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3139 \begin_inset Text
3140
3141 \layout Standard
3142
3143 reserved2
3144 \end_inset 
3145 </cell>
3146 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3147 \begin_inset Text
3148
3149 \layout Standard
3150
3151 int
3152 \end_inset 
3153 </cell>
3154 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3155 \begin_inset Text
3156
3157 \layout Standard
3158
3159 4
3160 \end_inset 
3161 </cell>
3162 </row>
3163 <row topline="true" bottomline="true">
3164 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3165 \begin_inset Text
3166
3167 \layout Standard
3168
3169 reserved3
3170 \end_inset 
3171 </cell>
3172 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3173 \begin_inset Text
3174
3175 \layout Standard
3176
3177 int
3178 \end_inset 
3179 </cell>
3180 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3181 \begin_inset Text
3182
3183 \layout Standard
3184
3185 4
3186 \end_inset 
3187 </cell>
3188 </row>
3189 </lyxtabular>
3190
3191 \end_inset 
3192
3193
3194 \layout Caption
3195
3196 Ogg/Speex header packet
3197 \begin_inset LatexCommand \label{cap:ogg_speex_header}
3198
3199 \end_inset 
3200
3201
3202 \end_inset 
3203
3204
3205 \layout Standard
3206
3207
3208 \begin_inset ERT
3209 status Collapsed
3210
3211 \layout Standard
3212
3213 \backslash 
3214 clearpage
3215 \end_inset 
3216
3217
3218 \layout Section
3219 \start_of_appendix 
3220 FAQ
3221 \layout Subsection*
3222
3223 Vorbis is open-source and patent-free, why not use it?
3224 \layout Standard
3225
3226 Vorbis is a great project but its goals are not the same as Speex.
3227  Vorbis is mostly aimed at compressing music and audio in general, while
3228  Speex targets speech only.
3229  For that reason Speex can achieve much better results than Vorbis on speech,
3230  typically 2-4 times higher compression at equal quality.
3231 \layout Subsection*
3232
3233 Can I use Speex for compressing music?
3234 \layout Standard
3235
3236 Just like Vorbis is not really adapted to speech, Speex is really not adapted
3237  for music.
3238  In most cases, you'll be better of with Vorbis when it comes to music.
3239 \layout Subsection*
3240
3241 I converted some MP3's to Speex and the quality is bad.
3242  What's wrong?
3243 \layout Standard
3244
3245 This is called transcoding and it will always result in much poorer quality
3246  than the original MP3.
3247  Unless you have a really good (size) reason to do so, never transcode speech.
3248  This is even valid for self transcoding (tandeming), i.e.
3249  If you decode a Speex file and re-encode it again at the same bit-rate,
3250  you will lose quality.
3251 \layout Subsection*
3252
3253 Why is encoding so slow compared to decoding?
3254 \layout Standard
3255
3256 For most kinds of compression, encoding is inherently slower than decoding.
3257  In the case of Speex, encoding consists of finding, for each vector of
3258  5 to 10 samples, the entry that matches the best within a codebook consisting
3259  of 16 to 256 entries.
3260  On the other hand, at decoding all that needs to be done is lookup the
3261  right entry in the codebook using the encoded index.
3262  Since a lookup is much faster than a search, the decoder works much faster
3263  than the encoder.
3264 \layout Subsection*
3265
3266 Why is Speex so slow on my iPaq (insert any platform without an FPU)?
3267 \layout Standard
3268
3269 Well the parenthesis provides the answer: no FPU (floating-point unit).
3270  The Speex code makes heavy use of floating-point operations.
3271  On devices with no FPU, all floating-point instructions need to be emulated.
3272  This is a very time consuming operation.
3273 \layout Subsection*
3274
3275 I'm getting unusual background noise (hiss) when using libspeex in my applicatio
3276 n.
3277  How do I fix that?
3278 \layout Standard
3279
3280 One of the cause could be scaling of the input speech.
3281  Speex expects signals to have a 
3282 \begin_inset Formula $\pm 2^{16}$
3283 \end_inset 
3284
3285  (signed short) dynamic range.
3286  If the dynamic range of your signals is too small (e.g.
3287  
3288 \begin_inset Formula $\pm 1.0$
3289 \end_inset 
3290
3291 ), you will suffer important quantization noise.
3292  A good target is to have a dynamic range around 
3293 \begin_inset Formula $\pm 8000$
3294 \end_inset 
3295
3296  which is large enough, but small enough to make sure there's no clipping
3297  when converting back to signed short.
3298 \layout Subsection*
3299
3300 I get very distorted speech when using libspeex in my application.
3301  What's wrong?
3302 \layout Standard
3303
3304 There are many possible causes for that.
3305  One of them is errors in the way the bits are manipulated.
3306  Another possible cause is the use of the same encoder or decoder state
3307  for more than one audio stream (channel), which produces strange effects
3308  with the filter memories.
3309  If the input speech has an amplitude close to 
3310 \begin_inset Formula $2^{16}$
3311 \end_inset 
3312
3313 , it is possible that at decoding, the amplitude be a bit higher than that,
3314  causing clipping when saving as 16-bit PCM.
3315 \layout Subsection*
3316
3317 Can Speex pass DTMF?
3318 \layout Standard
3319
3320 I guess it all depends on the bit-rate used.
3321  Though no formal testing has yet been performed, I'd say don't go below
3322  the 14.95 kbps mode if you want DTMF to be transmitted correctly.
3323  Also, make sure you don't use the lowest complexity (SPEEX_SET_COMPLEXITY),
3324  as it causes important noise.
3325 \layout Subsection*
3326
3327 Can Speex pass V.9x modem signals correctly?
3328 \layout Standard
3329
3330 If I could to that I'd be very rich by now :-)
3331 \layout Section
3332 \pagebreak_top 
3333 GNU Free Documentation License
3334 \layout Standard
3335
3336 Version 1.1, March 2000
3337 \layout Standard
3338
3339 Copyright (C) 2000 Free Software Foundation, Inc.
3340  59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted
3341  to copy and distribute verbatim copies of this license document, but changing
3342  it is not allowed.
3343  
3344 \layout Subsection*
3345
3346 0.
3347  PREAMBLE
3348 \layout Standard
3349
3350 The purpose of this License is to make a manual, textbook, or other written
3351  document "free" in the sense of freedom: to assure everyone the effective
3352  freedom to copy and redistribute it, with or without modifying it, either
3353  commercially or noncommercially.
3354  Secondarily, this License preserves for the author and publisher a way
3355  to get credit for their work, while not being considered responsible for
3356  modifications made by others.
3357 \layout Standard
3358
3359 This License is a kind of "copyleft", which means that derivative works
3360  of the document must themselves be free in the same sense.
3361  It complements the GNU General Public License, which is a copyleft license
3362  designed for free software.
3363 \layout Standard
3364
3365 We have designed this License in order to use it for manuals for free software,
3366  because free software needs free documentation: a free program should come
3367  with manuals providing the same freedoms that the software does.
3368  But this License is not limited to software manuals; it can be used for
3369  any textual work, regardless of subject matter or whether it is published
3370  as a printed book.
3371  We recommend this License principally for works whose purpose is instruction
3372  or reference.
3373  
3374 \layout Subsection*
3375
3376 1.
3377  APPLICABILITY AND DEFINITIONS
3378 \layout Standard
3379
3380 This License applies to any manual or other work that contains a notice
3381  placed by the copyright holder saying it can be distributed under the terms
3382  of this License.
3383  The "Document", below, refers to any such manual or work.
3384  Any member of the public is a licensee, and is addressed as "you".
3385 \layout Standard
3386
3387 A "Modified Version" of the Document means any work containing the Document
3388  or a portion of it, either copied verbatim, or with modifications and/or
3389  translated into another language.
3390 \layout Standard
3391
3392 A "Secondary Section" is a named appendix or a front-matter section of the
3393  Document that deals exclusively with the relationship of the publishers
3394  or authors of the Document to the Document's overall subject (or to related
3395  matters) and contains nothing that could fall directly within that overall
3396  subject.
3397  (For example, if the Document is in part a textbook of mathematics, a Secondary
3398  Section may not explain any mathematics.) The relationship could be a matter
3399  of historical connection with the subject or with related matters, or of
3400  legal, commercial, philosophical, ethical or political position regarding
3401  them.
3402 \layout Standard
3403
3404 The "Invariant Sections" are certain Secondary Sections whose titles are
3405  designated, as being those of Invariant Sections, in the notice that says
3406  that the Document is released under this License.
3407 \layout Standard
3408
3409 The "Cover Texts" are certain short passages of text that are listed, as
3410  Front-Cover Texts or Back-Cover Texts, in the notice that says that the
3411  Document is released under this License.
3412 \layout Standard
3413
3414 A "Transparent" copy of the Document means a machine-readable copy, represented
3415  in a format whose specification is available to the general public, whose
3416  contents can be viewed and edited directly and straightforwardly with generic
3417  text editors or (for images composed of pixels) generic paint programs
3418  or (for drawings) some widely available drawing editor, and that is suitable
3419  for input to text formatters or for automatic translation to a variety
3420  of formats suitable for input to text formatters.
3421  A copy made in an otherwise Transparent file format whose markup has been
3422  designed to thwart or discourage subsequent modification by readers is
3423  not Transparent.
3424  A copy that is not "Transparent" is called "Opaque".
3425 \layout Standard
3426
3427 Examples of suitable formats for Transparent copies include plain ASCII
3428  without markup, Texinfo input format, LaTeX input format, SGML or XML using
3429  a publicly available DTD, and standard-conforming simple HTML designed
3430  for human modification.
3431  Opaque formats include PostScript, PDF, proprietary formats that can be
3432  read and edited only by proprietary word processors, SGML or XML for which
3433  the DTD and/or processing tools are not generally available, and the machine-ge
3434 nerated HTML produced by some word processors for output purposes only.
3435 \layout Standard
3436
3437 The "Title Page" means, for a printed book, the title page itself, plus
3438  such following pages as are needed to hold, legibly, the material this
3439  License requires to appear in the title page.
3440  For works in formats which do not have any title page as such, "Title Page"
3441  means the text near the most prominent appearance of the work's title,
3442  preceding the beginning of the body of the text.
3443 \layout Subsection*
3444
3445 2.
3446  VERBATIM COPYING
3447 \layout Standard
3448
3449 You may copy and distribute the Document in any medium, either commercially
3450  or noncommercially, provided that this License, the copyright notices,
3451  and the license notice saying this License applies to the Document are
3452  reproduced in all copies, and that you add no other conditions whatsoever
3453  to those of this License.
3454  You may not use technical measures to obstruct or control the reading or
3455  further copying of the copies you make or distribute.
3456  However, you may accept compensation in exchange for copies.
3457  If you distribute a large enough number of copies you must also follow
3458  the conditions in section 3.
3459 \layout Standard
3460
3461 You may also lend copies, under the same conditions stated above, and you
3462  may publicly display copies.
3463 \layout Subsection*
3464
3465 3.
3466  COPYING IN QUANTITY
3467 \layout Standard
3468
3469 If you publish printed copies of the Document numbering more than 100, and
3470  the Document's license notice requires Cover Texts, you must enclose the
3471  copies in covers that carry, clearly and legibly, all these Cover Texts:
3472  Front-Cover Texts on the front cover, and Back-Cover Texts on the back
3473  cover.
3474  Both covers must also clearly and legibly identify you as the publisher
3475  of these copies.
3476  The front cover must present the full title with all words of the title
3477  equally prominent and visible.
3478  You may add other material on the covers in addition.
3479  Copying with changes limited to the covers, as long as they preserve the
3480  title of the Document and satisfy these conditions, can be treated as verbatim
3481  copying in other respects.
3482 \layout Standard
3483
3484 If the required texts for either cover are too voluminous to fit legibly,
3485  you should put the first ones listed (as many as fit reasonably) on the
3486  actual cover, and continue the rest onto adjacent pages.
3487 \layout Standard
3488
3489 If you publish or distribute Opaque copies of the Document numbering more
3490  than 100, you must either include a machine-readable Transparent copy along
3491  with each Opaque copy, or state in or with each Opaque copy a publicly-accessib
3492 le computer-network location containing a complete Transparent copy of the
3493  Document, free of added material, which the general network-using public
3494  has access to download anonymously at no charge using public-standard network
3495  protocols.
3496  If you use the latter option, you must take reasonably prudent steps, when
3497  you begin distribution of Opaque copies in quantity, to ensure that this
3498  Transparent copy will remain thus accessible at the stated location until
3499  at least one year after the last time you distribute an Opaque copy (directly
3500  or through your agents or retailers) of that edition to the public.
3501 \layout Standard
3502
3503 It is requested, but not required, that you contact the authors of the Document
3504  well before redistributing any large number of copies, to give them a chance
3505  to provide you with an updated version of the Document.
3506  
3507 \layout Subsection*
3508
3509 4.
3510  MODIFICATIONS
3511 \layout Standard
3512
3513 You may copy and distribute a Modified Version of the Document under the
3514  conditions of sections 2 and 3 above, provided that you release the Modified
3515  Version under precisely this License, with the Modified Version filling
3516  the role of the Document, thus licensing distribution and modification
3517  of the Modified Version to whoever possesses a copy of it.
3518  In addition, you must do these things in the Modified Version: 
3519 \layout Itemize
3520
3521 A.
3522  Use in the Title Page (and on the covers, if any) a title distinct from
3523  that of the Document, and from those of previous versions (which should,
3524  if there were any, be listed in the History section of the Document).
3525  You may use the same title as a previous version if the original publisher
3526  of that version gives permission.
3527 \layout Itemize
3528
3529 B.
3530  List on the Title Page, as authors, one or more persons or entities responsible
3531  for authorship of the modifications in the Modified Version, together with
3532  at least five of the principal authors of the Document (all of its principal
3533  authors, if it has less than five).
3534 \layout Itemize
3535
3536 C.
3537  State on the Title page the name of the publisher of the Modified Version,
3538  as the publisher.
3539 \layout Itemize
3540
3541 D.
3542  Preserve all the copyright notices of the Document.
3543 \layout Itemize
3544
3545 E.
3546  Add an appropriate copyright notice for your modifications adjacent to
3547  the other copyright notices.
3548 \layout Itemize
3549
3550 F.
3551  Include, immediately after the copyright notices, a license notice giving
3552  the public permission to use the Modified Version under the terms of this
3553  License, in the form shown in the Addendum below.
3554 \layout Itemize
3555
3556 G.
3557  Preserve in that license notice the full lists of Invariant Sections and
3558  required Cover Texts given in the Document's license notice.
3559 \layout Itemize
3560
3561 H.
3562  Include an unaltered copy of this License.
3563 \layout Itemize
3564
3565 I.
3566  Preserve the section entitled "History", and its title, and add to it an
3567  item stating at least the title, year, new authors, and publisher of the
3568  Modified Version as given on the Title Page.
3569  If there is no section entitled "History" in the Document, create one stating
3570  the title, year, authors, and publisher of the Document as given on its
3571  Title Page, then add an item describing the Modified Version as stated
3572  in the previous sentence.
3573 \layout Itemize
3574
3575 J.
3576  Preserve the network location, if any, given in the Document for public
3577  access to a Transparent copy of the Document, and likewise the network
3578  locations given in the Document for previous versions it was based on.
3579  These may be placed in the "History" section.
3580  You may omit a network location for a work that was published at least
3581  four years before the Document itself, or if the original publisher of
3582  the version it refers to gives permission.
3583 \layout Itemize
3584
3585 K.
3586  In any section entitled "Acknowledgements" or "Dedications", preserve the
3587  section's title, and preserve in the section all the substance and tone
3588  of each of the contributor acknowledgements and/or dedications given therein.
3589 \layout Itemize
3590
3591 L.
3592  Preserve all the Invariant Sections of the Document, unaltered in their
3593  text and in their titles.
3594  Section numbers or the equivalent are not considered part of the section
3595  titles.
3596 \layout Itemize
3597
3598 M.
3599  Delete any section entitled "Endorsements".
3600  Such a section may not be included in the Modified Version.
3601 \layout Itemize
3602
3603 N.
3604  Do not retitle any existing section as "Endorsements" or to conflict in
3605  title with any Invariant Section.
3606  
3607 \layout Standard
3608
3609 If the Modified Version includes new front-matter sections or appendices
3610  that qualify as Secondary Sections and contain no material copied from
3611  the Document, you may at your option designate some or all of these sections
3612  as invariant.
3613  To do this, add their titles to the list of Invariant Sections in the Modified
3614  Version's license notice.
3615  These titles must be distinct from any other section titles.
3616 \layout Standard
3617
3618 You may add a section entitled "Endorsements", provided it contains nothing
3619  but endorsements of your Modified Version by various parties--for example,
3620  statements of peer review or that the text has been approved by an organization
3621  as the authoritative definition of a standard.
3622 \layout Standard
3623
3624 You may add a passage of up to five words as a Front-Cover Text, and a passage
3625  of up to 25 words as a Back-Cover Text, to the end of the list of Cover
3626  Texts in the Modified Version.
3627  Only one passage of Front-Cover Text and one of Back-Cover Text may be
3628  added by (or through arrangements made by) any one entity.
3629  If the Document already includes a cover text for the same cover, previously
3630  added by you or by arrangement made by the same entity you are acting on
3631  behalf of, you may not add another; but you may replace the old one, on
3632  explicit permission from the previous publisher that added the old one.
3633 \layout Standard
3634
3635 The author(s) and publisher(s) of the Document do not by this License give
3636  permission to use their names for publicity for or to assert or imply endorseme
3637 nt of any Modified Version.
3638  
3639 \layout Subsection*
3640
3641 5.
3642  COMBINING DOCUMENTS
3643 \layout Standard
3644
3645 You may combine the Document with other documents released under this License,
3646  under the terms defined in section 4 above for modified versions, provided
3647  that you include in the combination all of the Invariant Sections of all
3648  of the original documents, unmodified, and list them all as Invariant Sections
3649  of your combined work in its license notice.
3650 \layout Standard
3651
3652 The combined work need only contain one copy of this License, and multiple
3653  identical Invariant Sections may be replaced with a single copy.
3654  If there are multiple Invariant Sections with the same name but different
3655  contents, make the title of each such section unique by adding at the end
3656  of it, in parentheses, the name of the original author or publisher of
3657  that section if known, or else a unique number.
3658  Make the same adjustment to the section titles in the list of Invariant
3659  Sections in the license notice of the combined work.
3660 \layout Standard
3661
3662 In the combination, you must combine any sections entitled "History" in
3663  the various original documents, forming one section entitled "History";
3664  likewise combine any sections entitled "Acknowledgements", and any sections
3665  entitled "Dedications".
3666  You must delete all sections entitled "Endorsements."
3667 \layout Subsection*
3668
3669 6.
3670  COLLECTIONS OF DOCUMENTS
3671 \layout Standard
3672
3673 You may make a collection consisting of the Document and other documents
3674  released under this License, and replace the individual copies of this
3675  License in the various documents with a single copy that is included in
3676  the collection, provided that you follow the rules of this License for
3677  verbatim copying of each of the documents in all other respects.
3678 \layout Standard
3679
3680 You may extract a single document from such a collection, and distribute
3681  it individually under this License, provided you insert a copy of this
3682  License into the extracted document, and follow this License in all other
3683  respects regarding verbatim copying of that document.
3684  
3685 \layout Subsection*
3686
3687 7.
3688  AGGREGATION WITH INDEPENDENT WORKS
3689 \layout Standard
3690
3691 A compilation of the Document or its derivatives with other separate and
3692  independent documents or works, in or on a volume of a storage or distribution
3693  medium, does not as a whole count as a Modified Version of the Document,
3694  provided no compilation copyright is claimed for the compilation.
3695  Such a compilation is called an "aggregate", and this License does not
3696  apply to the other self-contained works thus compiled with the Document,
3697  on account of their being thus compiled, if they are not themselves derivative
3698  works of the Document.
3699 \layout Standard
3700
3701 If the Cover Text requirement of section 3 is applicable to these copies
3702  of the Document, then if the Document is less than one quarter of the entire
3703  aggregate, the Document's Cover Texts may be placed on covers that surround
3704  only the Document within the aggregate.
3705  Otherwise they must appear on covers around the whole aggregate.
3706 \layout Subsection*
3707
3708 8.
3709  TRANSLATION
3710 \layout Standard
3711
3712 Translation is considered a kind of modification, so you may distribute
3713  translations of the Document under the terms of section 4.
3714  Replacing Invariant Sections with translations requires special permission
3715  from their copyright holders, but you may include translations of some
3716  or all Invariant Sections in addition to the original versions of these
3717  Invariant Sections.
3718  You may include a translation of this License provided that you also include
3719  the original English version of this License.
3720  In case of a disagreement between the translation and the original English
3721  version of this License, the original English version will prevail.
3722 \layout Subsection*
3723
3724 9.
3725  TERMINATION
3726 \layout Standard
3727
3728 You may not copy, modify, sublicense, or distribute the Document except
3729  as expressly provided for under this License.
3730  Any other attempt to copy, modify, sublicense or distribute the Document
3731  is void, and will automatically terminate your rights under this License.
3732  However, parties who have received copies, or rights, from you under this
3733  License will not have their licenses terminated so long as such parties
3734  remain in full compliance.
3735  
3736 \layout Subsection*
3737
3738 10.
3739  FUTURE REVISIONS OF THIS LICENSE
3740 \layout Standard
3741
3742 The Free Software Foundation may publish new, revised versions of the GNU
3743  Free Documentation License from time to time.
3744  Such new versions will be similar in spirit to the present version, but
3745  may differ in detail to address new problems or concerns.
3746  See http://www.gnu.org/copyleft/.
3747 \layout Standard
3748
3749 Each version of the License is given a distinguishing version number.
3750  If the Document specifies that a particular numbered version of this License
3751  "or any later version" applies to it, you have the option of following
3752  the terms and conditions either of that specified version or of any later
3753  version that has been published (not as a draft) by the Free Software Foundatio
3754 n.
3755  If the Document does not specify a version number of this License, you
3756  may choose any version ever published (not as a draft) by the Free Software
3757  Foundation.
3758 \the_end