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