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