doc/manual.lyx

   1 #LyX 1.5.0 created this file. For more info see http://www.lyx.org/
   2 \lyxformat 276
   3 \begin_document
   4 \begin_header
   5 \textclass scrbook
   6 \language english
   7 \inputencoding auto
   8 \font_roman times
   9 \font_sans helvet
  10 \font_typewriter courier
  11 \font_default_family default
  12 \font_sc false
  13 \font_osf false
  14 \font_sf_scale 100
  15 \font_tt_scale 100
  16 \graphics default
  17 \paperfontsize 10
  18 \spacing single
  19 \papersize letterpaper
  20 \use_geometry true
  21 \use_amsmath 2
  22 \use_esint 0
  23 \cite_engine basic
  24 \use_bibtopic false
  25 \paperorientation portrait
  26 \leftmargin 2cm
  27 \topmargin 2cm
  28 \rightmargin 2cm
  29 \bottommargin 2cm
  30 \secnumdepth 3
  31 \tocdepth 3
  32 \paragraph_separation indent
  33 \defskip medskip
  34 \quotes_language english
  35 \papercolumns 1
  36 \papersides 1
  37 \paperpagestyle headings
  38 \listings_params "basicstyle={\ttfamily},breaklines=true,language=C,xleftmargin=0mm"
  39 \tracking_changes false
  40 \output_changes false
  41 \author ""
  42 \author ""
  43 \end_header
  44
  45 \begin_body
  46
  47 \begin_layout Title
  48 The Speex Codec Manual
  49 \newline
  50 Version 1.2 Beta 3
  51 \end_layout
  52
  53 \begin_layout Author
  54 Jean-Marc Valin
  55 \end_layout
  56
  57 \begin_layout Standard
  58
  59 \newpage
  60
  61 \end_layout
  62
  63 \begin_layout Standard
  64 Copyright
  65 \begin_inset ERT
  66 status collapsed
  67
  68 \begin_layout Standard
  69
  70
  71 \backslash
  72 copyright
  73 \end_layout
  74
  75 \end_inset
  76
  77  2002-2007 Jean-Marc Valin/Xiph.org Foundation
  78 \end_layout
  79
  80 \begin_layout Standard
  81 Permission is granted to copy, distribute and/or modify this document under
  82  the terms of the GNU Free Documentation License, Version 1.1 or any later
  83  version published by the Free Software Foundation; with no Invariant Section,
  84  with no Front-Cover Texts, and with no Back-Cover.
  85  A copy of the license is included in the section entitled "GNU Free Documentati
  86 on License".
  87
  88 \end_layout
  89
  90 \begin_layout Standard
  91
  92 \newpage
  93
  94 \begin_inset LatexCommand tableofcontents
  95
  96 \end_inset
  97
  98
  99 \newpage
 100
 101 \end_layout
 102
 103 \begin_layout Standard
 104 \begin_inset FloatList table
 105
 106 \end_inset
 107
 108
 109 \newpage
 110
 111 \end_layout
 112
 113 \begin_layout Chapter
 114 Introduction to Speex
 115 \end_layout
 116
 117 \begin_layout Standard
 118 The Speex codec (
 119 \family typewriter
 120 http://www.speex.org/
 121 \family default
 122 ) exists because there is a need for a speech codec that is open-source
 123  and free from software patent royalties.
 124  These are essential conditions for being usable in any open-source software.
 125  In essence, Speex is to speech what Vorbis is to audio/music.
 126  Unlike many other speech codecs, Speex is not designed for mobile phones
 127  but rather for packet networks and voice over IP (VoIP) applications.
 128  File-based compression is of course also supported.
 129
 130 \end_layout
 131
 132 \begin_layout Standard
 133 The Speex codec is designed to be very flexible and support a wide range
 134  of speech quality and bit-rate.
 135  Support for very good quality speech also means that Speex can encode wideband
 136  speech (16 kHz sampling rate) in addition to narrowband speech (telephone
 137  quality, 8 kHz sampling rate).
 138 \end_layout
 139
 140 \begin_layout Standard
 141 Designing for VoIP instead of mobile phones means that Speex is robust to
 142  lost packets, but not to corrupted ones.
 143  This is based on the assumption that in VoIP, packets either arrive unaltered
 144  or don't arrive at all.
 145  Because Speex is targeted at a wide range of devices, it has modest (adjustable
 146 ) complexity and a small memory footprint.
 147 \end_layout
 148
 149 \begin_layout Standard
 150 All the design goals led to the choice of CELP
 151 \begin_inset LatexCommand index
 152 name "CELP"
 153
 154 \end_inset
 155
 156  as the encoding technique.
 157  One of the main reasons is that CELP has long proved that it could work
 158  reliably and scale well to both low bit-rates (e.g.
 159  DoD CELP @ 4.8 kbps) and high bit-rates (e.g.
 160  G.728 @ 16 kbps).
 161
 162 \end_layout
 163
 164 \begin_layout Section
 165 Getting help
 166 \begin_inset LatexCommand label
 167 name "sec:Getting-help"
 168
 169 \end_inset
 170
 171
 172 \end_layout
 173
 174 \begin_layout Standard
 175 As for many open source projects, there are many ways to get help with Speex.
 176  These include:
 177 \end_layout
 178
 179 \begin_layout Itemize
 180 This manual
 181 \end_layout
 182
 183 \begin_layout Itemize
 184 Other documentation on the Speex website (http://www.speex.org/)
 185 \end_layout
 186
 187 \begin_layout Itemize
 188 Mailing list: Discuss any Speex-related topic on speex-dev@xiph.org (not
 189  just for developers)
 190 \end_layout
 191
 192 \begin_layout Itemize
 193 IRC: The main channel is #speex on irc.freenode.net.
 194  Note that due to time differences, it may take a while to get someone,
 195  so please be patient.
 196 \end_layout
 197
 198 \begin_layout Itemize
 199 Email the author privately at jean-marc.valin@usherbrooke.ca
 200 \series bold
 201 only
 202 \series default
 203  for private/delicate topics you do not wish to discuss publically.
 204 \end_layout
 205
 206 \begin_layout Standard
 207 Before asking for help (mailing list or IRC),
 208 \series bold
 209 it is important to first read this manual
 210 \series default
 211  (OK, so if you made it here it's already a good sign).
 212  It is generally considered rude to ask on a mailing list about topics that
 213  are clearly detailed in the documentation.
 214  On the other hand, it's perfectly OK (and encouraged) to ask for clarifications
 215  about something covered in the manual.
 216  This manual does not (yet) cover everything about Speex, so everyone is
 217  encouraged to ask questions, send comments, feature requests, or just let
 218  us know how Speex is being used.
 219
 220 \end_layout
 221
 222 \begin_layout Standard
 223 Here are some additional guidelines related to the mailing list.
 224  Before reporting bugs in Speex to the list, it is strongly recommended
 225  (if possible) to first test whether these bugs can be reproduced using
 226  the speexenc and speexdec (see Section
 227 \begin_inset LatexCommand ref
 228 reference "sec:Command-line-encoder/decoder"
 229
 230 \end_inset
 231
 232 ) command-line utilities.
 233  Bugs reported based on 3rd party code are both harder to find and far too
 234  often caused by errors that have nothing to do with Speex.
 235
 236 \end_layout
 237
 238 \begin_layout Section
 239 About this document
 240 \end_layout
 241
 242 \begin_layout Standard
 243 This document is divided in the following way.
 244  Section
 245 \begin_inset LatexCommand ref
 246 reference "sec:Feature-description"
 247
 248 \end_inset
 249
 250  describes the different Speex features and defines many basic terms that
 251  are used throughout this manual.
 252  Section
 253 \begin_inset LatexCommand ref
 254 reference "sec:Command-line-encoder/decoder"
 255
 256 \end_inset
 257
 258  documents the standard command-line tools provided in the Speex distribution.
 259  Section
 260 \begin_inset LatexCommand ref
 261 reference "sec:Programming-with-Speex"
 262
 263 \end_inset
 264
 265  includes detailed instructions about programming using the libspeex
 266 \begin_inset LatexCommand index
 267 name "libspeex"
 268
 269 \end_inset
 270
 271  API.
 272  Section
 273 \begin_inset LatexCommand ref
 274 reference "sec:Formats-and-standards"
 275
 276 \end_inset
 277
 278  has some information related to Speex and standards.
 279
 280 \end_layout
 281
 282 \begin_layout Standard
 283 The three last sections describe the algorithms used in Speex.
 284  These sections require signal processing knowledge, but are not required
 285  for merely using Speex.
 286  They are intended for people who want to understand how Speex really works
 287  and/or want to do research based on Speex.
 288  Section
 289 \begin_inset LatexCommand ref
 290 reference "sec:Introduction-to-CELP"
 291
 292 \end_inset
 293
 294  explains the general idea behind CELP, while sections
 295 \begin_inset LatexCommand ref
 296 reference "sec:Speex-narrowband-mode"
 297
 298 \end_inset
 299
 300  and
 301 \begin_inset LatexCommand ref
 302 reference "sec:Speex-wideband-mode"
 303
 304 \end_inset
 305
 306  are specific to Speex.
 307 \end_layout
 308
 309 \begin_layout Standard
 310
 311 \newpage
 312
 313 \end_layout
 314
 315 \begin_layout Chapter
 316 Codec description
 317 \begin_inset LatexCommand label
 318 name "sec:Feature-description"
 319
 320 \end_inset
 321
 322
 323 \end_layout
 324
 325 \begin_layout Standard
 326 This section describes Speex and its features into more details.
 327 \end_layout
 328
 329 \begin_layout Section
 330 Concepts
 331 \end_layout
 332
 333 \begin_layout Standard
 334 Before introducing all the Speex features, here are some concepts in speech
 335  coding that help better understand the rest of the manual.
 336  Although some are general concepts in speech/audio processing, others are
 337  specific to Speex.
 338 \end_layout
 339
 340 \begin_layout Subsection*
 341 Sampling rate
 342 \begin_inset LatexCommand index
 343 name "sampling rate"
 344
 345 \end_inset
 346
 347
 348 \end_layout
 349
 350 \begin_layout Standard
 351 The sampling rate expressed in Hertz (Hz) is the number of samples taken
 352  from a signal per second.
 353  For a sampling rate of
 354 \begin_inset Formula $F_{s}$
 355 \end_inset
 356
 357  kHz, the highest frequency that can be represented is equal to
 358 \begin_inset Formula $F_{s}/2$
 359 \end_inset
 360
 361  kHz (
 362 \begin_inset Formula $F_{s}/2$
 363 \end_inset
 364
 365  is known as the Nyquist frequency).
 366  This is a fundamental property in signal processing and is described by
 367  the sampling theorem.
 368  Speex is mainly designed for three different sampling rates: 8 kHz, 16
 369  kHz, and 32 kHz.
 370  These are respectively refered to as narrowband
 371 \begin_inset LatexCommand index
 372 name "narrowband"
 373
 374 \end_inset
 375
 376 , wideband
 377 \begin_inset LatexCommand index
 378 name "wideband"
 379
 380 \end_inset
 381
 382  and ultra-wideband
 383 \begin_inset LatexCommand index
 384 name "ultra-wideband"
 385
 386 \end_inset
 387
 388 .
 389
 390 \end_layout
 391
 392 \begin_layout Subsection*
 393 Bit-rate
 394 \end_layout
 395
 396 \begin_layout Standard
 397 When encoding a speech signal, the bit-rate is defined as the number of
 398  bits per unit of time required to encode the speech.
 399  It is measured in
 400 \emph on
 401 bits per second
 402 \emph default
 403  (bps), or generally
 404 \emph on
 405 kilobits per second
 406 \emph default
 407 .
 408  It is important to make the distinction between
 409 \emph on
 410 kilo
 411 \series bold
 412 bits
 413 \series default
 414 \emph default
 415
 416 \emph on
 417 per second
 418 \emph default
 419  (k
 420 \series bold
 421 b
 422 \series default
 423 ps) and
 424 \emph on
 425 kilo
 426 \series bold
 427 bytes
 428 \series default
 429 \emph default
 430
 431 \emph on
 432 per second
 433 \emph default
 434  (k
 435 \series bold
 436 B
 437 \series default
 438 ps).
 439 \end_layout
 440
 441 \begin_layout Subsection*
 442 Quality
 443 \begin_inset LatexCommand index
 444 name "quality"
 445
 446 \end_inset
 447
 448  (variable)
 449 \end_layout
 450
 451 \begin_layout Standard
 452 Speex is a lossy codec, which means that it achives compression at the expense
 453  of fidelity of the input speech signal.
 454  Unlike some other speech codecs, it is possible to control the tradeoff
 455  made between quality and bit-rate.
 456  The Speex encoding process is controlled most of the time by a quality
 457  parameter that ranges from 0 to 10.
 458  In constant bit-rate
 459 \begin_inset LatexCommand index
 460 name "constant bit-rate"
 461
 462 \end_inset
 463
 464  (CBR) operation, the quality parameter is an integer, while for variable
 465  bit-rate (VBR), the parameter is a float.
 466
 467 \end_layout
 468
 469 \begin_layout Subsection*
 470 Complexity
 471 \begin_inset LatexCommand index
 472 name "complexity"
 473
 474 \end_inset
 475
 476  (variable)
 477 \end_layout
 478
 479 \begin_layout Standard
 480 With Speex, it is possible to vary the complexity allowed for the encoder.
 481  This is done by controlling how the search is performed with an integer
 482  ranging from 1 to 10 in a way that's similar to the -1 to -9 options to
 483
 484 \emph on
 485 gzip
 486 \emph default
 487  and
 488 \emph on
 489 bzip2
 490 \emph default
 491  compression utilities.
 492  For normal use, the noise level at complexity 1 is between 1 and 2 dB higher
 493  than at complexity 10, but the CPU requirements for complexity 10 is about
 494  5 times higher than for complexity 1.
 495  In practice, the best trade-off is between complexity 2 and 4, though higher
 496  settings are often useful when encoding non-speech sounds like DTMF
 497 \begin_inset LatexCommand index
 498 name "DTMF"
 499
 500 \end_inset
 501
 502  tones.
 503 \end_layout
 504
 505 \begin_layout Subsection*
 506 Variable Bit-Rate
 507 \begin_inset LatexCommand index
 508 name "variable bit-rate"
 509
 510 \end_inset
 511
 512  (VBR)
 513 \end_layout
 514
 515 \begin_layout Standard
 516 Variable bit-rate (VBR) allows a codec to change its bit-rate dynamically
 517  to adapt to the
 518 \begin_inset Quotes eld
 519 \end_inset
 520
 521 difficulty
 522 \begin_inset Quotes erd
 523 \end_inset
 524
 525  of the audio being encoded.
 526  In the example of Speex, sounds like vowels and high-energy transients
 527  require a higher bit-rate to achieve good quality, while fricatives (e.g.
 528  s,f sounds) can be coded adequately with less bits.
 529  For this reason, VBR can achive lower bit-rate for the same quality, or
 530  a better quality for a certain bit-rate.
 531  Despite its advantages, VBR has two main drawbacks: first, by only specifying
 532  quality, there's no guaranty about the final average bit-rate.
 533  Second, for some real-time applications like voice over IP (VoIP), what
 534  counts is the maximum bit-rate, which must be low enough for the communication
 535  channel.
 536 \end_layout
 537
 538 \begin_layout Subsection*
 539 Average Bit-Rate
 540 \begin_inset LatexCommand index
 541 name "average bit-rate"
 542
 543 \end_inset
 544
 545  (ABR)
 546 \end_layout
 547
 548 \begin_layout Standard
 549 Average bit-rate solves one of the problems of VBR, as it dynamically adjusts
 550  VBR quality in order to meet a specific target bit-rate.
 551  Because the quality/bit-rate is adjusted in real-time (open-loop), the
 552  global quality will be slightly lower than that obtained by encoding in
 553  VBR with exactly the right quality setting to meet the target average bit-rate.
 554 \end_layout
 555
 556 \begin_layout Subsection*
 557 Voice Activity Detection
 558 \begin_inset LatexCommand index
 559 name "voice activity detection"
 560
 561 \end_inset
 562
 563  (VAD)
 564 \end_layout
 565
 566 \begin_layout Standard
 567 When enabled, voice activity detection detects whether the audio being encoded
 568  is speech or silence/background noise.
 569  VAD is always implicitly activated when encoding in VBR, so the option
 570  is only useful in non-VBR operation.
 571  In this case, Speex detects non-speech periods and encode them with just
 572  enough bits to reproduce the background noise.
 573  This is called
 574 \begin_inset Quotes eld
 575 \end_inset
 576
 577 comfort noise generation
 578 \begin_inset Quotes erd
 579 \end_inset
 580
 581  (CNG).
 582 \end_layout
 583
 584 \begin_layout Subsection*
 585 Discontinuous Transmission
 586 \begin_inset LatexCommand index
 587 name "discontinuous transmission"
 588
 589 \end_inset
 590
 591  (DTX)
 592 \end_layout
 593
 594 \begin_layout Standard
 595 Discontinuous transmission is an addition to VAD/VBR operation, that allows
 596  to stop transmitting completely when the background noise is stationary.
 597  In file-based operation, since we cannot just stop writing to the file,
 598  only 5 bits are used for such frames (corresponding to 250 bps).
 599 \end_layout
 600
 601 \begin_layout Subsection*
 602 Perceptual enhancement
 603 \begin_inset LatexCommand index
 604 name "perceptual enhancement"
 605
 606 \end_inset
 607
 608
 609 \end_layout
 610
 611 \begin_layout Standard
 612 Perceptual enhancement is a part of the decoder which, when turned on, attempts
 613  to reduce the perception of the noise/distortion produced by the encoding/decod
 614 ing process.
 615  In most cases, perceptual enhancement brings the sound further from the
 616  original
 617 \emph on
 618 objectively
 619 \emph default
 620  (e.g.
 621  considering only SNR), but in the end it still
 622 \emph on
 623 sounds
 624 \emph default
 625  better (subjective improvement).
 626 \end_layout
 627
 628 \begin_layout Subsection*
 629 Latency and algorithmic delay
 630 \begin_inset LatexCommand index
 631 name "algorithmic delay"
 632
 633 \end_inset
 634
 635
 636 \end_layout
 637
 638 \begin_layout Standard
 639 Every speech codec introduces a delay in the transmission.
 640  For Speex, this delay is equal to the frame size, plus some amount of
 641 \begin_inset Quotes eld
 642 \end_inset
 643
 644 look-ahead
 645 \begin_inset Quotes erd
 646 \end_inset
 647
 648  required to process each frame.
 649  In narrowband operation (8 kHz), the delay is 30 ms, while for wideband
 650  (16 kHz), the delay is 34 ms.
 651  These values don't account for the CPU time it takes to encode or decode
 652  the frames.
 653 \end_layout
 654
 655 \begin_layout Section
 656 Codec
 657 \end_layout
 658
 659 \begin_layout Standard
 660 The main characteristics of Speex can be summarized as follows:
 661 \end_layout
 662
 663 \begin_layout Itemize
 664 Free software/open-source
 665 \begin_inset LatexCommand index
 666 name "open-source"
 667
 668 \end_inset
 669
 670 , patent
 671 \begin_inset LatexCommand index
 672 name "patent"
 673
 674 \end_inset
 675
 676  and royalty-free
 677 \end_layout
 678
 679 \begin_layout Itemize
 680 Integration of narrowband
 681 \begin_inset LatexCommand index
 682 name "narrowband"
 683
 684 \end_inset
 685
 686  and wideband
 687 \begin_inset LatexCommand index
 688 name "wideband"
 689
 690 \end_inset
 691
 692  using an embedded bit-stream
 693 \end_layout
 694
 695 \begin_layout Itemize
 696 Wide range of bit-rates available (from 2.15 kbps to 44 kbps)
 697 \end_layout
 698
 699 \begin_layout Itemize
 700 Dynamic bit-rate switching (AMR) and Variable Bit-Rate
 701 \begin_inset LatexCommand index
 702 name "variable bit-rate"
 703
 704 \end_inset
 705
 706  (VBR) operation
 707 \end_layout
 708
 709 \begin_layout Itemize
 710 Voice Activity Detection
 711 \begin_inset LatexCommand index
 712 name "voice activity detection"
 713
 714 \end_inset
 715
 716  (VAD, integrated with VBR) and discontinuous transmission (DTX)
 717 \end_layout
 718
 719 \begin_layout Itemize
 720 Variable complexity
 721 \begin_inset LatexCommand index
 722 name "complexity"
 723
 724 \end_inset
 725
 726
 727 \end_layout
 728
 729 \begin_layout Itemize
 730 Embedded wideband structure (scalable sampling rate)
 731 \end_layout
 732
 733 \begin_layout Itemize
 734 Ultra-wideband sampling rate at 32 kHz
 735 \end_layout
 736
 737 \begin_layout Itemize
 738 Intensity stereo encoding option
 739 \end_layout
 740
 741 \begin_layout Itemize
 742 Fixed-point implementation
 743 \end_layout
 744
 745 \begin_layout Section
 746 Preprocessor
 747 \end_layout
 748
 749 \begin_layout Standard
 750 This part refers to the preprocessor module introduced in the 1.1.x branch.
 751  The preprocessor is designed to be used on the audio
 752 \emph on
 753 before
 754 \emph default
 755  running the encoder.
 756  The preprocessor provides three main functionalities:
 757 \end_layout
 758
 759 \begin_layout Itemize
 760 noise suppression
 761 \end_layout
 762
 763 \begin_layout Itemize
 764 automatic gain control (AGC)
 765 \end_layout
 766
 767 \begin_layout Itemize
 768 voice activity detection (VAD)
 769 \end_layout
 770
 771 \begin_layout Standard
 772 The denoiser can be used to reduce the amount of background noise present
 773  in the input signal.
 774  This provides higher quality speech whether or not the denoised signal
 775  is encoded with Speex (or at all).
 776  However, when using the denoised signal with the codec, there is an additional
 777  benefit.
 778  Speech codecs in general (Speex included) tend to perform poorly on noisy
 779  input, which tends to amplify the noise.
 780  The denoiser greatly reduces this effect.
 781 \end_layout
 782
 783 \begin_layout Standard
 784 Automatic gain control (AGC) is a feature that deals with the fact that
 785  the recording volume may vary by a large amount between different setups.
 786  The AGC provides a way to adjust a signal to a reference volume.
 787  This is useful for voice over IP because it removes the need for manual
 788  adjustment of the microphone gain.
 789  A secondary advantage is that by setting the microphone gain to a conservative
 790  (low) level, it is easier to avoid clipping.
 791 \end_layout
 792
 793 \begin_layout Standard
 794 The voice activity detector (VAD) provided by the preprocessor is more advanced
 795  than the one directly provided in the codec.
 796
 797 \end_layout
 798
 799 \begin_layout Section
 800 Adaptive Jitter Buffer
 801 \end_layout
 802
 803 \begin_layout Standard
 804 When transmitting voice (or any content for that matter) over UDP or RTP,
 805  packet may be lost, arrive with different delay, or even out of order.
 806  The purpose of a jitter buffer is to reorder packets and buffer them long
 807  enough (but no longer than necessary) so they can be sent to be decoded.
 808
 809 \end_layout
 810
 811 \begin_layout Section
 812 Acoustic Echo Canceller
 813 \end_layout
 814
 815 \begin_layout Standard
 816 In any hands-free communication system (Fig.
 817
 818 \begin_inset LatexCommand ref
 819 reference "fig:Acoustic-echo-model"
 820
 821 \end_inset
 822
 823 ), speech from the remote end is played in the local loudspeaker, propagates
 824  in the room and is captured by the microphone.
 825  If the audio captured from the microphone is sent directly to the remote
 826  end, then the remove user hears an echo of his voice.
 827  An acoustic echo canceller is designed to remove the acoustic echo before
 828  it is sent to the remote end.
 829  It is important to understand that the echo canceller is meant to improve
 830  the quality on the
 831 \series bold
 832 remote
 833 \series default
 834  end.
 835 \end_layout
 836
 837 \begin_layout Standard
 838 \begin_inset Float figure
 839 wide false
 840 sideways false
 841 status open
 842
 843 \begin_layout Standard
 844 \begin_inset ERT
 845 status collapsed
 846
 847 \begin_layout Standard
 848
 849
 850 \backslash
 851 begin{center}
 852 \end_layout
 853
 854 \end_inset
 855
 856
 857 \begin_inset Graphics
 858         filename echo_path.eps
 859         width 10cm
 860
 861 \end_inset
 862
 863
 864 \begin_inset ERT
 865 status collapsed
 866
 867 \begin_layout Standard
 868
 869
 870 \backslash
 871 end{center}
 872 \end_layout
 873
 874 \end_inset
 875
 876
 877 \end_layout
 878
 879 \begin_layout Standard
 880 \begin_inset Caption
 881
 882 \begin_layout Standard
 883 Acoustic echo model
 884 \begin_inset LatexCommand label
 885 name "fig:Acoustic-echo-model"
 886
 887 \end_inset
 888
 889
 890 \end_layout
 891
 892 \end_inset
 893
 894
 895 \end_layout
 896
 897 \end_inset
 898
 899
 900 \end_layout
 901
 902 \begin_layout Section
 903 Resampler
 904 \end_layout
 905
 906 \begin_layout Standard
 907 In some cases, it may be useful to convert audio from one sampling rate
 908  to another.
 909  There are many reasons for that.
 910  It can be for mixing streams that have different sampling rates, for supporting
 911  sampling rates that the soundcard doesn't support, for transcoding, etc.
 912  That's why there is now a resampler that is part of the Speex project.
 913  This resampler can be used to convert between any two arbitrary rates (the
 914  ratio must only be a rational number) and there is control over the quality/com
 915 plexity tradeoff.
 916 \end_layout
 917
 918 \begin_layout Standard
 919
 920 \newpage
 921
 922 \end_layout
 923
 924 \begin_layout Chapter
 925 Compiling
 926 \end_layout
 927
 928 \begin_layout Standard
 929 Compiling Speex under UNIX/Linux or any other platform supported by autoconf
 930  (e.g.
 931  Win32/cygwin) is as easy as typing:
 932 \end_layout
 933
 934 \begin_layout LyX-Code
 935 % ./configure [options]
 936 \end_layout
 937
 938 \begin_layout LyX-Code
 939 % make
 940 \end_layout
 941
 942 \begin_layout LyX-Code
 943 % make install
 944 \end_layout
 945
 946 \begin_layout Standard
 947 The options supported by the Speex configure script are:
 948 \end_layout
 949
 950 \begin_layout Description
 951 --prefix=<path> Specifies the base path for installing Speex (e.g.
 952  /usr)
 953 \end_layout
 954
 955 \begin_layout Description
 956 --enable-shared/--disable-shared Whether to compile shared libraries
 957 \end_layout
 958
 959 \begin_layout Description
 960 --enable-static/--disable-static Whether to compile static libraries
 961 \end_layout
 962
 963 \begin_layout Description
 964 --disable-wideband Disable the wideband part of Speex (typically to save
 965  space)
 966 \end_layout
 967
 968 \begin_layout Description
 969 --enable-valgrind Enable extra hits for valgrind for debugging purposes
 970  (do not use by default)
 971 \end_layout
 972
 973 \begin_layout Description
 974 --enable-sse Enable use of SSE instructions (x86/float only)
 975 \end_layout
 976
 977 \begin_layout Description
 978 --enable-fixed-point
 979 \begin_inset LatexCommand index
 980 name "fixed-point"
 981
 982 \end_inset
 983
 984  Compile Speex for a processor that does not have a floating point unit
 985  (FPU)
 986 \end_layout
 987
 988 \begin_layout Description
 989 --enable-arm4-asm Enable assembly specific to the ARMv4 architecture (gcc
 990  only)
 991 \end_layout
 992
 993 \begin_layout Description
 994 --enable-arm5e-asm Enable assembly specific to the ARMv5E architecture (gcc
 995  only)
 996 \end_layout
 997
 998 \begin_layout Description
 999 --enable-fixed-point-debug Use only for debugging the fixed-point
1000 \begin_inset LatexCommand index
1001 name "fixed-point"
1002
1003 \end_inset
1004
1005  code (very slow)
1006 \end_layout
1007
1008 \begin_layout Description
1009 --enable-epic-48k Enable a special (and non-compatible) 4.8 kbps narrowband
1010  mode (broken in 1.1.x and 1.2beta)
1011 \end_layout
1012
1013 \begin_layout Description
1014 --enable-ti-c55x Enable support for the TI C5x family
1015 \end_layout
1016
1017 \begin_layout Description
1018 --enable-blackfin-asm Enable assembly specific to the Blackfin DSP architecture
1019  (gcc only)
1020 \end_layout
1021
1022 \begin_layout Description
1023 --enable-vorbis-psycho Make the encoder use the Vorbis psycho-acoustic model.
1024  This is very experimental and may be removed in the future.
1025 \end_layout
1026
1027 \begin_layout Section
1028 Platforms
1029 \end_layout
1030
1031 \begin_layout Standard
1032 Speex is known to compile and work on a large number of architectures, both
1033  floating-point and fixed-point.
1034  In general, any architecture that can natively compute the multiplication
1035  of two signed 16-bit numbers (32-bit result) and runs at a sufficient clock
1036  rate (architecture-dependent) is capable of running Speex.
1037  Architectures that are
1038 \series bold
1039 known
1040 \series default
1041  to be supported (it probably works on many others) are:
1042 \end_layout
1043
1044 \begin_layout Itemize
1045 x86 & x86-64
1046 \end_layout
1047
1048 \begin_layout Itemize
1049 Power
1050 \end_layout
1051
1052 \begin_layout Itemize
1053 SPARC
1054 \end_layout
1055
1056 \begin_layout Itemize
1057 ARM
1058 \end_layout
1059
1060 \begin_layout Itemize
1061 Blackfin
1062 \end_layout
1063
1064 \begin_layout Itemize
1065 TI C54xx & C55xx
1066 \end_layout
1067
1068 \begin_layout Itemize
1069 TI C6xxx
1070 \end_layout
1071
1072 \begin_layout Itemize
1073 TriMedia (experimental)
1074 \end_layout
1075
1076 \begin_layout Standard
1077 Operating systems on top of which Speex is known to work include (it probably
1078  works on many others):
1079 \end_layout
1080
1081 \begin_layout Itemize
1082 Linux
1083 \end_layout
1084
1085 \begin_layout Itemize
1086 \begin_inset Formula $\mu$
1087 \end_inset
1088
1089 Clinux
1090 \end_layout
1091
1092 \begin_layout Itemize
1093 MacOS X
1094 \end_layout
1095
1096 \begin_layout Itemize
1097 BSD
1098 \end_layout
1099
1100 \begin_layout Itemize
1101 Other UNIX/POSIX variants
1102 \end_layout
1103
1104 \begin_layout Itemize
1105 Symbian
1106 \end_layout
1107
1108 \begin_layout Standard
1109 The source code directory include additional information for compiling on
1110  certain architectures or operating systems in README.xxx files.
1111 \end_layout
1112
1113 \begin_layout Standard
1114
1115 \newpage
1116
1117 \end_layout
1118
1119 \begin_layout Chapter
1120 Command-line encoder/decoder
1121 \begin_inset LatexCommand label
1122 name "sec:Command-line-encoder/decoder"
1123
1124 \end_inset
1125
1126
1127 \end_layout
1128
1129 \begin_layout Standard
1130 The base Speex distribution includes a command-line encoder (
1131 \emph on
1132 speexenc
1133 \emph default
1134 ) and decoder (
1135 \emph on
1136 speexdec
1137 \emph default
1138 ).
1139  Those tools produce and read Speex files encapsulated in the Ogg container.
1140  Although it is possible to encapsulate Speex in any container, Ogg is the
1141  recommended container for files.
1142  This section describes how to use the command line tools for Speex files
1143  in Ogg.
1144 \end_layout
1145
1146 \begin_layout Section
1147
1148 \emph on
1149 speexenc
1150 \begin_inset LatexCommand index
1151 name "speexenc"
1152
1153 \end_inset
1154
1155
1156 \end_layout
1157
1158 \begin_layout Standard
1159 The
1160 \emph on
1161 speexenc
1162 \emph default
1163  utility is used to create Speex files from raw PCM or wave files.
1164  It can be used by calling:
1165 \end_layout
1166
1167 \begin_layout LyX-Code
1168 speexenc [options] input_file output_file
1169 \end_layout
1170
1171 \begin_layout Standard
1172 The value '-' for input_file or output_file corresponds respectively to
1173  stdin and stdout.
1174  The valid options are:
1175 \end_layout
1176
1177 \begin_layout Description
1178 --narrowband\InsetSpace ~
1179 (-n) Tell Speex to treat the input as narrowband (8 kHz).
1180  This is the default
1181 \end_layout
1182
1183 \begin_layout Description
1184 --wideband\InsetSpace ~
1185 (-w) Tell Speex to treat the input as wideband (16 kHz)
1186 \end_layout
1187
1188 \begin_layout Description
1189 --ultra-wideband\InsetSpace ~
1190 (-u) Tell Speex to treat the input as
1191 \begin_inset Quotes eld
1192 \end_inset
1193
1194 ultra-wideband
1195 \begin_inset Quotes erd
1196 \end_inset
1197
1198  (32 kHz)
1199 \end_layout
1200
1201 \begin_layout Description
1202 --quality\InsetSpace ~
1203 n Set the encoding quality (0-10), default is 8
1204 \end_layout
1205
1206 \begin_layout Description
1207 --bitrate\InsetSpace ~
1208 n Encoding bit-rate (use bit-rate n or lower)
1209 \end_layout
1210
1211 \begin_layout Description
1212 --vbr Enable VBR (Variable Bit-Rate), disabled by default
1213 \end_layout
1214
1215 \begin_layout Description
1216 --abr\InsetSpace ~
1217 n Enable ABR (Average Bit-Rate) at n kbps, disabled by default
1218 \end_layout
1219
1220 \begin_layout Description
1221 --vad Enable VAD (Voice Activity Detection), disabled by default
1222 \end_layout
1223
1224 \begin_layout Description
1225 --dtx Enable DTX (Discontinuous Transmission), disabled by default
1226 \end_layout
1227
1228 \begin_layout Description
1229 --nframes\InsetSpace ~
1230 n Pack n frames in each Ogg packet (this saves space at low bit-rates)
1231 \end_layout
1232
1233 \begin_layout Description
1234 --comp\InsetSpace ~
1235 n Set encoding speed/quality tradeoff.
1236  The higher the value of n, the slower the encoding (default is 3)
1237 \end_layout
1238
1239 \begin_layout Description
1240 -V Verbose operation, print bit-rate currently in use
1241 \end_layout
1242
1243 \begin_layout Description
1244 --help\InsetSpace ~
1245 (-h) Print the help
1246 \end_layout
1247
1248 \begin_layout Description
1249 --version\InsetSpace ~
1250 (-v) Print version information
1251 \end_layout
1252
1253 \begin_layout Subsection*
1254 Speex comments
1255 \end_layout
1256
1257 \begin_layout Description
1258 --comment Add the given string as an extra comment.
1259  This may be used multiple times.
1260
1261 \end_layout
1262
1263 \begin_layout Description
1264 --author Author of this track.
1265
1266 \end_layout
1267
1268 \begin_layout Description
1269 --title Title for this track.
1270
1271 \end_layout
1272
1273 \begin_layout Subsection*
1274 Raw input options
1275 \end_layout
1276
1277 \begin_layout Description
1278 --rate\InsetSpace ~
1279 n Sampling rate for raw input
1280 \end_layout
1281
1282 \begin_layout Description
1283 --stereo Consider raw input as stereo
1284 \end_layout
1285
1286 \begin_layout Description
1287 --le Raw input is little-endian
1288 \end_layout
1289
1290 \begin_layout Description
1291 --be Raw input is big-endian
1292 \end_layout
1293
1294 \begin_layout Description
1295 --8bit Raw input is 8-bit unsigned
1296 \end_layout
1297
1298 \begin_layout Description
1299 --16bit Raw input is 16-bit signed
1300 \end_layout
1301
1302 \begin_layout Section
1303
1304 \emph on
1305 speexdec
1306 \begin_inset LatexCommand index
1307 name "speexdec"
1308
1309 \end_inset
1310
1311
1312 \end_layout
1313
1314 \begin_layout Standard
1315 The
1316 \emph on
1317 speexdec
1318 \emph default
1319  utility is used to decode Speex files and can be used by calling:
1320 \end_layout
1321
1322 \begin_layout LyX-Code
1323 speexdec [options] speex_file [output_file]
1324 \end_layout
1325
1326 \begin_layout Standard
1327 The value '-' for input_file or output_file corresponds respectively to
1328  stdin and stdout.
1329  Also, when no output_file is specified, the file is played to the soundcard.
1330  The valid options are:
1331 \end_layout
1332
1333 \begin_layout Description
1334 --enh enable post-filter (default)
1335 \end_layout
1336
1337 \begin_layout Description
1338 --no-enh disable post-filter
1339 \end_layout
1340
1341 \begin_layout Description
1342 --force-nb Force decoding in narrowband
1343 \end_layout
1344
1345 \begin_layout Description
1346 --force-wb Force decoding in wideband
1347 \end_layout
1348
1349 \begin_layout Description
1350 --force-uwb Force decoding in ultra-wideband
1351 \end_layout
1352
1353 \begin_layout Description
1354 --mono Force decoding in mono
1355 \end_layout
1356
1357 \begin_layout Description
1358 --stereo Force decoding in stereo
1359 \end_layout
1360
1361 \begin_layout Description
1362 --rate\InsetSpace ~
1363 n Force decoding at n Hz sampling rate
1364 \end_layout
1365
1366 \begin_layout Description
1367 --packet-loss\InsetSpace ~
1368 n Simulate n % random packet loss
1369 \end_layout
1370
1371 \begin_layout Description
1372 -V Verbose operation, print bit-rate currently in use
1373 \end_layout
1374
1375 \begin_layout Description
1376 --help\InsetSpace ~
1377 (-h) Print the help
1378 \end_layout
1379
1380 \begin_layout Description
1381 --version\InsetSpace ~
1382 (-v) Print version information
1383 \end_layout
1384
1385 \begin_layout Standard
1386
1387 \newpage
1388
1389 \end_layout
1390
1391 \begin_layout Chapter
1392 Programming with Speex
1393 \begin_inset LatexCommand label
1394 name "sec:Programming-with-Speex"
1395
1396 \end_inset
1397
1398
1399 \end_layout
1400
1401 \begin_layout Standard
1402 This section explains how to use the Speex API.
1403  Examples of code can also be found in Appendix
1404 \begin_inset LatexCommand ref
1405 reference "sec:Sample-code"
1406
1407 \end_inset
1408
1409  and the complete API documentation is included in the Documentation section
1410  of the Speex website (http://www.speex.org/).
1411 \end_layout
1412
1413 \begin_layout Section
1414 Codec API (
1415 \emph on
1416 libspeex
1417 \emph default
1418
1419 \begin_inset LatexCommand index
1420 name "libspeex"
1421
1422 \end_inset
1423
1424 )
1425 \end_layout
1426
1427 \begin_layout Standard
1428 The
1429 \emph on
1430 libspeex
1431 \emph default
1432  library contains all the functions for encoding and decoding speech with
1433  the Speex codec.
1434  When linking on a UNIX system, one must add
1435 \emph on
1436 -lspeex -lm
1437 \emph default
1438  to the compiler command line.
1439  One important thing to know is that
1440 \series bold
1441 libspeex calls are reentrant, but not thread-safe
1442 \series default
1443 .
1444  That means that it is fine to use calls from many threads, but
1445 \series bold
1446 calls using the same state from multiple threads must be protected by mutexes
1447 \series default
1448 .
1449 \end_layout
1450
1451 \begin_layout Subsection
1452 Encoding
1453 \begin_inset LatexCommand label
1454 name "sub:Encoding"
1455
1456 \end_inset
1457
1458
1459 \end_layout
1460
1461 \begin_layout Standard
1462 In order to encode speech using Speex, one first needs to:
1463 \end_layout
1464
1465 \begin_layout Standard
1466 \begin_inset listings
1467 inline false
1468 status open
1469
1470 \begin_layout Standard
1471
1472 #include <speex/speex.h>
1473 \end_layout
1474
1475 \end_inset
1476
1477 Then in the code, a Speex bit-packing struct must be declared, along with
1478  a Speex encoder state:
1479 \begin_inset listings
1480 inline false
1481 status open
1482
1483 \begin_layout Standard
1484
1485 SpeexBits bits;
1486 \end_layout
1487
1488 \begin_layout Standard
1489
1490 void *enc_state;
1491 \end_layout
1492
1493 \end_inset
1494
1495 The two are initialized by:
1496 \begin_inset listings
1497 inline false
1498 status open
1499
1500 \begin_layout Standard
1501
1502 speex_bits_init(&bits);
1503 \end_layout
1504
1505 \begin_layout Standard
1506
1507 enc_state = speex_encoder_init(&speex_nb_mode);
1508 \end_layout
1509
1510 \end_inset
1511
1512
1513 \end_layout
1514
1515 \begin_layout Standard
1516 For wideband coding,
1517 \emph on
1518 speex_nb_mode
1519 \emph default
1520  will be replaced by
1521 \emph on
1522 speex_wb_mode
1523 \emph default
1524 .
1525  In most cases, you will need to know the frame size used at the sampling
1526  rate you are using.
1527  You can get that value in the
1528 \emph on
1529 frame_size
1530 \emph default
1531  variable (expressed in
1532 \series bold
1533 samples
1534 \series default
1535 , not bytes) with:
1536 \end_layout
1537
1538 \begin_layout Standard
1539 \begin_inset listings
1540 inline false
1541 status open
1542
1543 \begin_layout Standard
1544
1545 speex_encoder_ctl(enc_state,SPEEX_GET_FRAME_SIZE,&frame_size);
1546 \end_layout
1547
1548 \end_inset
1549
1550
1551 \end_layout
1552
1553 \begin_layout Standard
1554 In practice,
1555 \emph on
1556 frame_size
1557 \emph default
1558  will correspond to 20 ms when using 8, 16, or 32 kHz sampling rate.
1559  There are many parameters that can be set for the Speex encoder, but the
1560  most useful one is the quality parameter that controls the quality vs bit-rate
1561  tradeoff.
1562  This is set by:
1563 \end_layout
1564
1565 \begin_layout Standard
1566 \begin_inset listings
1567 inline false
1568 status open
1569
1570 \begin_layout Standard
1571
1572 speex_encoder_ctl(enc_state,SPEEX_SET_QUALITY,&quality);
1573 \end_layout
1574
1575 \end_inset
1576
1577 where
1578 \emph on
1579 quality
1580 \emph default
1581  is an integer value ranging from 0 to 10 (inclusively).
1582  The mapping between quality and bit-rate is described in Fig.
1583
1584 \begin_inset LatexCommand ref
1585 reference "cap:quality_vs_bps"
1586
1587 \end_inset
1588
1589  for narrowband.
1590 \end_layout
1591
1592 \begin_layout Standard
1593 Once the initialization is done, for every input frame:
1594 \end_layout
1595
1596 \begin_layout Standard
1597 \begin_inset listings
1598 inline false
1599 status open
1600
1601 \begin_layout Standard
1602
1603 speex_bits_reset(&bits);
1604 \end_layout
1605
1606 \begin_layout Standard
1607
1608 speex_encode_int(enc_state, input_frame, &bits);
1609 \end_layout
1610
1611 \begin_layout Standard
1612
1613 nbBytes = speex_bits_write(&bits, byte_ptr, MAX_NB_BYTES);
1614 \end_layout
1615
1616 \end_inset
1617
1618
1619 \end_layout
1620
1621 \begin_layout Standard
1622 where
1623 \emph on
1624 input_frame
1625 \emph default
1626  is a
1627 \emph on
1628 (
1629 \emph default
1630 short
1631 \emph on
1632 *)
1633 \emph default
1634  pointing to the beginning of a speech frame,
1635 \emph on
1636 byte_ptr
1637 \emph default
1638  is a
1639 \emph on
1640 (char *)
1641 \emph default
1642  where the encoded frame will be written,
1643 \emph on
1644 MAX_NB_BYTES
1645 \emph default
1646  is the maximum number of bytes that can be written to
1647 \emph on
1648 byte_ptr
1649 \emph default
1650  without causing an overflow and
1651 \emph on
1652 nbBytes
1653 \emph default
1654  is the number of bytes actually written to
1655 \emph on
1656 byte_ptr
1657 \emph default
1658  (the encoded size in bytes).
1659  Before calling speex_bits_write, it is possible to find the number of bytes
1660  that need to be written by calling
1661 \family typewriter
1662 speex_bits_nbytes(&bits)
1663 \family default
1664 , which returns a number of bytes.
1665 \end_layout
1666
1667 \begin_layout Standard
1668 It is still possible to use the
1669 \emph on
1670 speex_encode()
1671 \emph default
1672  function, which takes a
1673 \emph on
1674 (float *)
1675 \emph default
1676  for the audio.
1677  However, this would make an eventual port to an FPU-less platform (like
1678  ARM) more complicated.
1679  Internally,
1680 \emph on
1681 speex_encode()
1682 \emph default
1683  and
1684 \emph on
1685 speex_encode_int()
1686 \emph default
1687  are processed in the same way.
1688  Whether the encoder uses the fixed-point version is only decided by the
1689  compile-time flags, not at the API level.
1690 \end_layout
1691
1692 \begin_layout Standard
1693 After you're done with the encoding, free all resources with:
1694 \end_layout
1695
1696 \begin_layout Standard
1697 \begin_inset listings
1698 inline false
1699 status open
1700
1701 \begin_layout Standard
1702
1703 speex_bits_destroy(&bits);
1704 \end_layout
1705
1706 \begin_layout Standard
1707
1708 speex_encoder_destroy(enc_state);
1709 \end_layout
1710
1711 \end_inset
1712
1713
1714 \end_layout
1715
1716 \begin_layout Standard
1717 That's about it for the encoder.
1718
1719 \end_layout
1720
1721 \begin_layout Subsection
1722 Decoding
1723 \begin_inset LatexCommand label
1724 name "sub:Decoding"
1725
1726 \end_inset
1727
1728
1729 \end_layout
1730
1731 \begin_layout Standard
1732 In order to decode speech using Speex, you first need to:
1733 \begin_inset listings
1734 inline false
1735 status open
1736
1737 \begin_layout Standard
1738
1739 #include <speex/speex.h>
1740 \end_layout
1741
1742 \end_inset
1743
1744 You also need to declare a Speex bit-packing struct
1745 \begin_inset listings
1746 inline false
1747 status open
1748
1749 \begin_layout Standard
1750
1751 SpeexBits bits;
1752 \end_layout
1753
1754 \end_inset
1755
1756 and a Speex decoder state
1757 \begin_inset listings
1758 inline false
1759 status open
1760
1761 \begin_layout Standard
1762
1763 void *dec_state;
1764 \end_layout
1765
1766 \end_inset
1767
1768 The two are initialized by:
1769 \begin_inset listings
1770 inline false
1771 status open
1772
1773 \begin_layout Standard
1774
1775 speex_bits_init(&bits);
1776 \end_layout
1777
1778 \begin_layout Standard
1779
1780 dec_state = speex_decoder_init(&speex_nb_mode);
1781 \end_layout
1782
1783 \end_inset
1784
1785
1786 \end_layout
1787
1788 \begin_layout Standard
1789 For wideband decoding,
1790 \emph on
1791 speex_nb_mode
1792 \emph default
1793  will be replaced by
1794 \emph on
1795 speex_wb_mode
1796 \emph default
1797 .
1798  If you need to obtain the size of the frames that will be used by the decoder,
1799  you can get that value in the
1800 \emph on
1801 frame_size
1802 \emph default
1803  variable (expressed in
1804 \series bold
1805 samples
1806 \series default
1807 , not bytes) with:
1808 \end_layout
1809
1810 \begin_layout Standard
1811 \begin_inset listings
1812 inline false
1813 status open
1814
1815 \begin_layout Standard
1816
1817 speex_decoder_ctl(dec_state, SPEEX_GET_FRAME_SIZE, &frame_size);
1818 \end_layout
1819
1820 \end_inset
1821
1822
1823 \end_layout
1824
1825 \begin_layout Standard
1826 There is also a parameter that can be set for the decoder: whether or not
1827  to use a perceptual enhancer.
1828  This can be set by:
1829 \end_layout
1830
1831 \begin_layout Standard
1832 \begin_inset listings
1833 inline false
1834 status open
1835
1836 \begin_layout Standard
1837
1838 speex_decoder_ctl(dec_state, SPEEX_SET_ENH, &enh);
1839 \end_layout
1840
1841 \end_inset
1842
1843
1844 \end_layout
1845
1846 \begin_layout Standard
1847 where
1848 \emph on
1849 enh
1850 \emph default
1851  is an int with value 0 to have the enhancer disabled and 1 to have it enabled.
1852  As of 1.2-beta1, the default is now to enable the enhancer.
1853 \end_layout
1854
1855 \begin_layout Standard
1856 Again, once the decoder initialization is done, for every input frame:
1857 \end_layout
1858
1859 \begin_layout Standard
1860 \begin_inset listings
1861 inline false
1862 status open
1863
1864 \begin_layout Standard
1865
1866 speex_bits_read_from(&bits, input_bytes, nbBytes);
1867 \end_layout
1868
1869 \begin_layout Standard
1870
1871 speex_decode_int(dec_state, &bits, output_frame);
1872 \end_layout
1873
1874 \end_inset
1875
1876 where input_bytes is a
1877 \emph on
1878 (char *)
1879 \emph default
1880  containing the bit-stream data received for a frame,
1881 \emph on
1882 nbBytes
1883 \emph default
1884  is the size (in bytes) of that bit-stream, and
1885 \emph on
1886 output_frame
1887 \emph default
1888  is a
1889 \emph on
1890 (short *)
1891 \emph default
1892  and points to the area where the decoded speech frame will be written.
1893  A NULL value as the second argument indicates that we don't have the bits
1894  for the current frame.
1895  When a frame is lost, the Speex decoder will do its best to "guess" the
1896  correct signal.
1897 \end_layout
1898
1899 \begin_layout Standard
1900 As for the encoder, the
1901 \emph on
1902 speex_decode()
1903 \emph default
1904  function can still be used, with a
1905 \emph on
1906 (float *)
1907 \emph default
1908  as the output for the audio.
1909  After you're done with the decoding, free all resources with:
1910 \end_layout
1911
1912 \begin_layout Standard
1913 \begin_inset listings
1914 inline false
1915 status open
1916
1917 \begin_layout Standard
1918
1919 speex_bits_destroy(&bits);
1920 \end_layout
1921
1922 \begin_layout Standard
1923
1924 speex_decoder_destroy(dec_state);
1925 \end_layout
1926
1927 \end_inset
1928
1929
1930 \end_layout
1931
1932 \begin_layout Subsection
1933 Codec Options (speex_*_ctl)
1934 \begin_inset LatexCommand label
1935 name "sub:Codec-Options"
1936
1937 \end_inset
1938
1939
1940 \end_layout
1941
1942 \begin_layout Quote
1943 \align center
1944
1945 \emph on
1946 Entities should not be multiplied beyond necessity -- William of Ockham.
1947 \end_layout
1948
1949 \begin_layout Quote
1950 \align center
1951
1952 \emph on
1953 Just because there's an option for it doesn't mean you have to turn it on
1954  -- me.
1955 \end_layout
1956
1957 \begin_layout Standard
1958 The Speex encoder and decoder support many options and requests that can
1959  be accessed through the
1960 \emph on
1961 speex_encoder_ctl
1962 \emph default
1963  and
1964 \emph on
1965 speex_decoder_ctl
1966 \emph default
1967  functions.
1968  Despite that, the defaults are good for many applications and
1969 \series bold
1970 optional settings should only be used when one understands them and knows
1971  that they are needed
1972 \series default
1973 .
1974  A common error is to attempt to set many unnecessary settings.
1975  These functions are similar to the
1976 \emph on
1977 ioctl
1978 \emph default
1979  system call and their prototypes are:
1980 \end_layout
1981
1982 \begin_layout Standard
1983 \begin_inset listings
1984 inline false
1985 status open
1986
1987 \begin_layout Standard
1988
1989 void speex_encoder_ctl(void *encoder, int request, void *ptr);
1990 \end_layout
1991
1992 \begin_layout Standard
1993
1994 void speex_decoder_ctl(void *encoder, int request, void *ptr);
1995 \end_layout
1996
1997 \end_inset
1998
1999
2000 \end_layout
2001
2002 \begin_layout Standard
2003 The different values of request allowed are (note that some only apply to
2004  the encoder or the decoder):
2005 \end_layout
2006
2007 \begin_layout Description
2008 SPEEX_SET_ENH** Set perceptual enhancer
2009 \begin_inset LatexCommand index
2010 name "perceptual enhancement"
2011
2012 \end_inset
2013
2014  to on (1) or off (0) (spx_int32_t)
2015 \end_layout
2016
2017 \begin_layout Description
2018 SPEEX_GET_ENH** Get perceptual enhancer status (spx_int32_t)
2019 \end_layout
2020
2021 \begin_layout Description
2022 SPEEX_GET_FRAME_SIZE Get the number of samples per frame for the current
2023  mode (spx_int32_t)
2024 \end_layout
2025
2026 \begin_layout Description
2027 SPEEX_SET_QUALITY* Set the encoder speech quality (spx_int32_t 0 to 10)
2028 \end_layout
2029
2030 \begin_layout Description
2031 SPEEX_GET_QUALITY* Get the current encoder speech quality (spx_int32_t 0
2032  to 10)
2033 \end_layout
2034
2035 \begin_layout Description
2036 SPEEX_SET_MODE* Set the mode number, as specified in the RTP spec (spx_int32_t)
2037 \end_layout
2038
2039 \begin_layout Description
2040 SPEEX_GET_MODE* Get the current mode number, as specified in the RTP spec
2041  (spx_int32_t)
2042 \end_layout
2043
2044 \begin_layout Description
2045 SPEEX_SET_LOW_MODE*
2046 \begin_inset Formula $\dagger$
2047 \end_inset
2048
2049  Use the source, Luke!
2050 \end_layout
2051
2052 \begin_layout Description
2053 SPEEX_GET_LOW_MODE*
2054 \begin_inset Formula $\dagger$
2055 \end_inset
2056
2057  Use the source, Luke!
2058 \end_layout
2059
2060 \begin_layout Description
2061 SPEEX_SET_HIGH_MODE*
2062 \begin_inset Formula $\dagger$
2063 \end_inset
2064
2065  Use the source, Luke!
2066 \end_layout
2067
2068 \begin_layout Description
2069 SPEEX_GET_HIGH_MODE*
2070 \begin_inset Formula $\dagger$
2071 \end_inset
2072
2073  Use the source, Luke!
2074 \end_layout
2075
2076 \begin_layout Description
2077 SPEEX_SET_VBR* Set variable bit-rate (VBR) to on (1) or off (0) (spx_int32_t)
2078 \end_layout
2079
2080 \begin_layout Description
2081 SPEEX_GET_VBR* Get variable bit-rate
2082 \begin_inset LatexCommand index
2083 name "variable bit-rate"
2084
2085 \end_inset
2086
2087  (VBR) status (spx_int32_t)
2088 \end_layout
2089
2090 \begin_layout Description
2091 SPEEX_SET_VBR_QUALITY* Set the encoder VBR speech quality (float 0 to 10)
2092 \end_layout
2093
2094 \begin_layout Description
2095 SPEEX_GET_VBR_QUALITY* Get the current encoder VBR speech quality (float
2096  0 to 10)
2097 \end_layout
2098
2099 \begin_layout Description
2100 SPEEX_SET_COMPLEXITY* Set the CPU resources allowed for the encoder (spx_int32_t
2101  1 to 10)
2102 \end_layout
2103
2104 \begin_layout Description
2105 SPEEX_GET_COMPLEXITY* Get the CPU resources allowed for the encoder (spx_int32_t
2106  1 to 10)
2107 \end_layout
2108
2109 \begin_layout Description
2110 SPEEX_SET_BITRATE* Set the bit-rate to use to the closest value not exceeding
2111  the parameter (spx_int32_t in bps)
2112 \end_layout
2113
2114 \begin_layout Description
2115 SPEEX_GET_BITRATE Get the current bit-rate in use (spx_int32_t in bps)
2116 \end_layout
2117
2118 \begin_layout Description
2119 SPEEX_SET_SAMPLING_RATE Set real sampling rate (spx_int32_t in Hz)
2120 \end_layout
2121
2122 \begin_layout Description
2123 SPEEX_GET_SAMPLING_RATE Get real sampling rate (spx_int32_t in Hz)
2124 \end_layout
2125
2126 \begin_layout Description
2127 SPEEX_RESET_STATE Reset the encoder/decoder state to its original state,
2128  clearing all memories (no argument)
2129 \end_layout
2130
2131 \begin_layout Description
2132 SPEEX_SET_VAD* Set voice activity detection
2133 \begin_inset LatexCommand index
2134 name "voice activity detection"
2135
2136 \end_inset
2137
2138  (VAD) to on (1) or off (0) (spx_int32_t)
2139 \end_layout
2140
2141 \begin_layout Description
2142 SPEEX_GET_VAD* Get voice activity detection (VAD) status (spx_int32_t)
2143 \end_layout
2144
2145 \begin_layout Description
2146 SPEEX_SET_DTX* Set discontinuous transmission
2147 \begin_inset LatexCommand index
2148 name "discontinuous transmission"
2149
2150 \end_inset
2151
2152  (DTX) to on (1) or off (0) (spx_int32_t)
2153 \end_layout
2154
2155 \begin_layout Description
2156 SPEEX_GET_DTX* Get discontinuous transmission (DTX) status (spx_int32_t)
2157 \end_layout
2158
2159 \begin_layout Description
2160 SPEEX_SET_ABR* Set average bit-rate
2161 \begin_inset LatexCommand index
2162 name "average bit-rate"
2163
2164 \end_inset
2165
2166  (ABR) to a value n in bits per second (spx_int32_t in bps)
2167 \end_layout
2168
2169 \begin_layout Description
2170 SPEEX_GET_ABR* Get average bit-rate (ABR) setting (spx_int32_t in bps)
2171 \end_layout
2172
2173 \begin_layout Description
2174 SPEEX_SET_PLC_TUNING* Tell the encoder to optimize encoding for a certain
2175  percentage of packet loss (spx_int32_t in percent)
2176 \end_layout
2177
2178 \begin_layout Description
2179 SPEEX_GET_PLC_TUNING* Get the current tuning of the encoder for PLC (spx_int32_t
2180  in percent)
2181 \end_layout
2182
2183 \begin_layout Description
2184 SPEEX_SET_VBR_MAX_BITRATE* Set the maximum bit-rate allowed in VBR operation
2185  (spx_int32_t in bps)
2186 \end_layout
2187
2188 \begin_layout Description
2189 SPEEX_GET_VBR_MAX_BITRATE* Get the current maximum bit-rate allowed in VBR
2190  operation (spx_int32_t in bps)
2191 \end_layout
2192
2193 \begin_layout Description
2194 SPEEX_SET_HIGHPASS Set the high-pass filter on (1) or off (0) (spx_int32_t)
2195 \end_layout
2196
2197 \begin_layout Description
2198 SPEEX_TET_HIGHPASS Get the current high-pass filter status (spx_int32_t)
2199 \end_layout
2200
2201 \begin_layout Description
2202 * applies only to the encoder
2203 \end_layout
2204
2205 \begin_layout Description
2206 ** applies only to the decoder
2207 \end_layout
2208
2209 \begin_layout Description
2210 \begin_inset Formula $\dagger$
2211 \end_inset
2212
2213  If you can't understand from the source code what this does, you should
2214  not be using it in the first place
2215 \end_layout
2216
2217 \begin_layout Subsection
2218 Mode queries
2219 \begin_inset LatexCommand label
2220 name "sub:Mode-queries"
2221
2222 \end_inset
2223
2224
2225 \end_layout
2226
2227 \begin_layout Standard
2228 Speex modes have a query system similar to the speex_encoder_ctl and speex_decod
2229 er_ctl calls.
2230  Since modes are read-only, it is only possible to get information about
2231  a particular mode.
2232  The function used to do that is:
2233 \begin_inset listings
2234 inline false
2235 status open
2236
2237 \begin_layout Standard
2238
2239 void speex_mode_query(SpeexMode *mode, int request, void *ptr);
2240 \end_layout
2241
2242 \end_inset
2243
2244 The admissible values for request are (unless otherwise note, the values
2245  are returned through
2246 \emph on
2247 ptr
2248 \emph default
2249 ):
2250 \end_layout
2251
2252 \begin_layout Description
2253 SPEEX_MODE_FRAME_SIZE Get the frame size (in samples) for the mode
2254 \end_layout
2255
2256 \begin_layout Description
2257 SPEEX_SUBMODE_BITRATE Get the bit-rate for a submode number specified through
2258
2259 \emph on
2260 ptr
2261 \emph default
2262  (integer in bps).
2263
2264 \end_layout
2265
2266 \begin_layout Subsection
2267 Packing and in-band signalling
2268 \begin_inset LatexCommand index
2269 name "in-band signalling"
2270
2271 \end_inset
2272
2273
2274 \end_layout
2275
2276 \begin_layout Standard
2277 Sometimes it is desirable to pack more than one frame per packet (or other
2278  basic unit of storage).
2279  The proper way to do it is to call speex_encode
2280 \begin_inset Formula $N$
2281 \end_inset
2282
2283  times before writing the stream with speex_bits_write.
2284  In cases where the number of frames is not determined by an out-of-band
2285  mechanism, it is possible to include a terminator code.
2286  That terminator consists of the code 15 (decimal) encoded with 5 bits,
2287  as shown in Table
2288 \begin_inset LatexCommand ref
2289 reference "cap:quality_vs_bps"
2290
2291 \end_inset
2292
2293 .
2294  Note that as of version 1.0.2, calling speex_bits_write automatically inserts
2295  the terminator so as to fill the last byte.
2296  This doesn't involves any overhead and makes sure Speex can always detect
2297  when there is no more frame in a packet.
2298 \end_layout
2299
2300 \begin_layout Standard
2301 It is also possible to send in-band
2302 \begin_inset Quotes eld
2303 \end_inset
2304
2305 messages
2306 \begin_inset Quotes erd
2307 \end_inset
2308
2309  to the other side.
2310  All these messages are encoded as
2311 \begin_inset Quotes eld
2312 \end_inset
2313
2314 pseudo-frames
2315 \begin_inset Quotes erd
2316 \end_inset
2317
2318  of mode 14 which contain a 4-bit message type code, followed by the message.
2319  Table
2320 \begin_inset LatexCommand ref
2321 reference "cap:In-band-signalling-codes"
2322
2323 \end_inset
2324
2325  lists the available codes, their meaning and the size of the message that
2326  follows.
2327  Most of these messages are requests that are sent to the encoder or decoder
2328  on the other end, which is free to comply or ignore them.
2329  By default, all in-band messages are ignored.
2330 \end_layout
2331
2332 \begin_layout Standard
2333 \begin_inset Float table
2334 placement htbp
2335 wide false
2336 sideways false
2337 status open
2338
2339 \begin_layout Standard
2340 \begin_inset ERT
2341 status collapsed
2342
2343 \begin_layout Standard
2344
2345
2346 \backslash
2347 begin{center}
2348 \end_layout
2349
2350 \end_inset
2351
2352
2353 \begin_inset Tabular
2354 <lyxtabular version="3" rows="17" columns="3">
2355 <features>
2356 <column alignment="center" valignment="top" leftline="true" width="0pt">
2357 <column alignment="center" valignment="top" leftline="true" width="0pt">
2358 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
2359 <row topline="true" bottomline="true">
2360 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2361 \begin_inset Text
2362
2363 \begin_layout Standard
2364 Code
2365 \end_layout
2366
2367 \end_inset
2368 </cell>
2369 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2370 \begin_inset Text
2371
2372 \begin_layout Standard
2373 Size (bits)
2374 \end_layout
2375
2376 \end_inset
2377 </cell>
2378 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2379 \begin_inset Text
2380
2381 \begin_layout Standard
2382 Content
2383 \end_layout
2384
2385 \end_inset
2386 </cell>
2387 </row>
2388 <row topline="true">
2389 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2390 \begin_inset Text
2391
2392 \begin_layout Standard
2393 0
2394 \end_layout
2395
2396 \end_inset
2397 </cell>
2398 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2399 \begin_inset Text
2400
2401 \begin_layout Standard
2402 1
2403 \end_layout
2404
2405 \end_inset
2406 </cell>
2407 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2408 \begin_inset Text
2409
2410 \begin_layout Standard
2411 Asks decoder to set perceptual enhancement off (0) or on(1)
2412 \end_layout
2413
2414 \end_inset
2415 </cell>
2416 </row>
2417 <row topline="true">
2418 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2419 \begin_inset Text
2420
2421 \begin_layout Standard
2422 1
2423 \end_layout
2424
2425 \end_inset
2426 </cell>
2427 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2428 \begin_inset Text
2429
2430 \begin_layout Standard
2431 1
2432 \end_layout
2433
2434 \end_inset
2435 </cell>
2436 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2437 \begin_inset Text
2438
2439 \begin_layout Standard
2440 Asks (if 1) the encoder to be less
2441 \begin_inset Quotes eld
2442 \end_inset
2443
2444 agressive
2445 \begin_inset Quotes erd
2446 \end_inset
2447
2448  due to high packet loss
2449 \end_layout
2450
2451 \end_inset
2452 </cell>
2453 </row>
2454 <row topline="true">
2455 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2456 \begin_inset Text
2457
2458 \begin_layout Standard
2459 2
2460 \end_layout
2461
2462 \end_inset
2463 </cell>
2464 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2465 \begin_inset Text
2466
2467 \begin_layout Standard
2468 4
2469 \end_layout
2470
2471 \end_inset
2472 </cell>
2473 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2474 \begin_inset Text
2475
2476 \begin_layout Standard
2477 Asks encoder to switch to mode N
2478 \end_layout
2479
2480 \end_inset
2481 </cell>
2482 </row>
2483 <row topline="true">
2484 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2485 \begin_inset Text
2486
2487 \begin_layout Standard
2488 3
2489 \end_layout
2490
2491 \end_inset
2492 </cell>
2493 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2494 \begin_inset Text
2495
2496 \begin_layout Standard
2497 4
2498 \end_layout
2499
2500 \end_inset
2501 </cell>
2502 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2503 \begin_inset Text
2504
2505 \begin_layout Standard
2506 Asks encoder to switch to mode N for low-band
2507 \end_layout
2508
2509 \end_inset
2510 </cell>
2511 </row>
2512 <row topline="true">
2513 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2514 \begin_inset Text
2515
2516 \begin_layout Standard
2517 4
2518 \end_layout
2519
2520 \end_inset
2521 </cell>
2522 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2523 \begin_inset Text
2524
2525 \begin_layout Standard
2526 4
2527 \end_layout
2528
2529 \end_inset
2530 </cell>
2531 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2532 \begin_inset Text
2533
2534 \begin_layout Standard
2535 Asks encoder to switch to mode N for high-band
2536 \end_layout
2537
2538 \end_inset
2539 </cell>
2540 </row>
2541 <row topline="true">
2542 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2543 \begin_inset Text
2544
2545 \begin_layout Standard
2546 5
2547 \end_layout
2548
2549 \end_inset
2550 </cell>
2551 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2552 \begin_inset Text
2553
2554 \begin_layout Standard
2555 4
2556 \end_layout
2557
2558 \end_inset
2559 </cell>
2560 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2561 \begin_inset Text
2562
2563 \begin_layout Standard
2564 Asks encoder to switch to quality N for VBR
2565 \end_layout
2566
2567 \end_inset
2568 </cell>
2569 </row>
2570 <row topline="true">
2571 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2572 \begin_inset Text
2573
2574 \begin_layout Standard
2575 6
2576 \end_layout
2577
2578 \end_inset
2579 </cell>
2580 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2581 \begin_inset Text
2582
2583 \begin_layout Standard
2584 4
2585 \end_layout
2586
2587 \end_inset
2588 </cell>
2589 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2590 \begin_inset Text
2591
2592 \begin_layout Standard
2593 Request acknowloedge (0=no, 1=all, 2=only for in-band data)
2594 \end_layout
2595
2596 \end_inset
2597 </cell>
2598 </row>
2599 <row topline="true">
2600 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2601 \begin_inset Text
2602
2603 \begin_layout Standard
2604 7
2605 \end_layout
2606
2607 \end_inset
2608 </cell>
2609 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2610 \begin_inset Text
2611
2612 \begin_layout Standard
2613 4
2614 \end_layout
2615
2616 \end_inset
2617 </cell>
2618 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2619 \begin_inset Text
2620
2621 \begin_layout Standard
2622 Asks encoder to set CBR (0), VAD(1), DTX(3), VBR(5), VBR+DTX(7)
2623 \end_layout
2624
2625 \end_inset
2626 </cell>
2627 </row>
2628 <row topline="true">
2629 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2630 \begin_inset Text
2631
2632 \begin_layout Standard
2633 8
2634 \end_layout
2635
2636 \end_inset
2637 </cell>
2638 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2639 \begin_inset Text
2640
2641 \begin_layout Standard
2642 8
2643 \end_layout
2644
2645 \end_inset
2646 </cell>
2647 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2648 \begin_inset Text
2649
2650 \begin_layout Standard
2651 Transmit (8-bit) character to the other end
2652 \end_layout
2653
2654 \end_inset
2655 </cell>
2656 </row>
2657 <row topline="true">
2658 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2659 \begin_inset Text
2660
2661 \begin_layout Standard
2662 9
2663 \end_layout
2664
2665 \end_inset
2666 </cell>
2667 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2668 \begin_inset Text
2669
2670 \begin_layout Standard
2671 8
2672 \end_layout
2673
2674 \end_inset
2675 </cell>
2676 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2677 \begin_inset Text
2678
2679 \begin_layout Standard
2680 Intensity stereo information
2681 \end_layout
2682
2683 \end_inset
2684 </cell>
2685 </row>
2686 <row topline="true">
2687 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2688 \begin_inset Text
2689
2690 \begin_layout Standard
2691 10
2692 \end_layout
2693
2694 \end_inset
2695 </cell>
2696 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2697 \begin_inset Text
2698
2699 \begin_layout Standard
2700 16
2701 \end_layout
2702
2703 \end_inset
2704 </cell>
2705 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2706 \begin_inset Text
2707
2708 \begin_layout Standard
2709 Announce maximum bit-rate acceptable (N in bytes/second)
2710 \end_layout
2711
2712 \end_inset
2713 </cell>
2714 </row>
2715 <row topline="true">
2716 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2717 \begin_inset Text
2718
2719 \begin_layout Standard
2720 11
2721 \end_layout
2722
2723 \end_inset
2724 </cell>
2725 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2726 \begin_inset Text
2727
2728 \begin_layout Standard
2729 16
2730 \end_layout
2731
2732 \end_inset
2733 </cell>
2734 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2735 \begin_inset Text
2736
2737 \begin_layout Standard
2738 reserved
2739 \end_layout
2740
2741 \end_inset
2742 </cell>
2743 </row>
2744 <row topline="true">
2745 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2746 \begin_inset Text
2747
2748 \begin_layout Standard
2749 12
2750 \end_layout
2751
2752 \end_inset
2753 </cell>
2754 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2755 \begin_inset Text
2756
2757 \begin_layout Standard
2758 32
2759 \end_layout
2760
2761 \end_inset
2762 </cell>
2763 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2764 \begin_inset Text
2765
2766 \begin_layout Standard
2767 Acknowledge receiving packet N
2768 \end_layout
2769
2770 \end_inset
2771 </cell>
2772 </row>
2773 <row topline="true">
2774 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2775 \begin_inset Text
2776
2777 \begin_layout Standard
2778 13
2779 \end_layout
2780
2781 \end_inset
2782 </cell>
2783 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2784 \begin_inset Text
2785
2786 \begin_layout Standard
2787 32
2788 \end_layout
2789
2790 \end_inset
2791 </cell>
2792 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2793 \begin_inset Text
2794
2795 \begin_layout Standard
2796 reserved
2797 \end_layout
2798
2799 \end_inset
2800 </cell>
2801 </row>
2802 <row topline="true">
2803 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2804 \begin_inset Text
2805
2806 \begin_layout Standard
2807 14
2808 \end_layout
2809
2810 \end_inset
2811 </cell>
2812 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2813 \begin_inset Text
2814
2815 \begin_layout Standard
2816 64
2817 \end_layout
2818
2819 \end_inset
2820 </cell>
2821 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2822 \begin_inset Text
2823
2824 \begin_layout Standard
2825 reserved
2826 \end_layout
2827
2828 \end_inset
2829 </cell>
2830 </row>
2831 <row topline="true" bottomline="true">
2832 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2833 \begin_inset Text
2834
2835 \begin_layout Standard
2836 15
2837 \end_layout
2838
2839 \end_inset
2840 </cell>
2841 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2842 \begin_inset Text
2843
2844 \begin_layout Standard
2845 64
2846 \end_layout
2847
2848 \end_inset
2849 </cell>
2850 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2851 \begin_inset Text
2852
2853 \begin_layout Standard
2854 reserved
2855 \end_layout
2856
2857 \end_inset
2858 </cell>
2859 </row>
2860 </lyxtabular>
2861
2862 \end_inset
2863
2864
2865 \begin_inset ERT
2866 status collapsed
2867
2868 \begin_layout Standard
2869
2870
2871 \backslash
2872 end{center}
2873 \end_layout
2874
2875 \end_inset
2876
2877
2878 \end_layout
2879
2880 \begin_layout Standard
2881 \begin_inset Caption
2882
2883 \begin_layout Standard
2884 In-band signalling codes
2885 \begin_inset LatexCommand label
2886 name "cap:In-band-signalling-codes"
2887
2888 \end_inset
2889
2890
2891 \end_layout
2892
2893 \end_inset
2894
2895
2896 \end_layout
2897
2898 \end_inset
2899
2900
2901 \end_layout
2902
2903 \begin_layout Standard
2904 Finally, applications may define custom in-band messages using mode 13.
2905  The size of the message in bytes is encoded with 5 bits, so that the decoder
2906  can skip it if it doesn't know how to interpret it.
2907 \end_layout
2908
2909 \begin_layout Section
2910 Speech Processing API (
2911 \emph on
2912 libspeexdsp
2913 \emph default
2914 )
2915 \end_layout
2916
2917 \begin_layout Standard
2918 As of version 1.2beta3, the non-codec parts of the Speex package are now
2919  in a separate library called
2920 \emph on
2921 libspeexdsp
2922 \emph default
2923 .
2924  This library includes the preprocessor, the acoustic echo canceller, the
2925  jitter buffer, and the resampler.
2926  In a UNIX environment, it can be linked into a program by adding
2927 \emph on
2928 -lspeexdsp -lm
2929 \emph default
2930  to the compiler command line.
2931  Just like for libspeex,
2932 \series bold
2933 libspeexdsp calls are reentrant, but not thread-safe
2934 \series default
2935 .
2936  That means that it is fine to use calls from many threads, but
2937 \series bold
2938 calls using the same state from multiple threads must be protected by mutexes
2939 \series default
2940 .
2941 \end_layout
2942
2943 \begin_layout Subsection
2944 Preprocessor
2945 \begin_inset LatexCommand label
2946 name "sub:Preprocessor"
2947
2948 \end_inset
2949
2950
2951 \end_layout
2952
2953 \begin_layout Standard
2954 In order to use the Speex preprocessor
2955 \begin_inset LatexCommand index
2956 name "preprocessor"
2957
2958 \end_inset
2959
2960 , you first need to:
2961 \end_layout
2962
2963 \begin_layout Standard
2964 \begin_inset listings
2965 inline false
2966 status open
2967
2968 \begin_layout Standard
2969
2970 #include <speex/speex_preprocess.h>
2971 \end_layout
2972
2973 \end_inset
2974
2975
2976 \end_layout
2977
2978 \begin_layout Standard
2979 Then, a preprocessor state can be created as:
2980 \end_layout
2981
2982 \begin_layout Standard
2983 \begin_inset listings
2984 inline false
2985 status open
2986
2987 \begin_layout Standard
2988
2989 SpeexPreprocessState *preprocess_state = speex_preprocess_state_init(frame_size,
2990  sampling_rate);
2991 \end_layout
2992
2993 \end_inset
2994
2995
2996 \end_layout
2997
2998 \begin_layout Standard
2999 It is recommended to use the same value for
3000 \family typewriter
3001 frame_size
3002 \family default
3003  as is used by the encoder (20
3004 \emph on
3005 ms
3006 \emph default
3007 ).
3008 \end_layout
3009
3010 \begin_layout Standard
3011 For each input frame, you need to call:
3012 \end_layout
3013
3014 \begin_layout Standard
3015 \begin_inset listings
3016 inline false
3017 status open
3018
3019 \begin_layout Standard
3020
3021 speex_preprocess_run(preprocess_state, audio_frame);
3022 \end_layout
3023
3024 \end_inset
3025
3026
3027 \end_layout
3028
3029 \begin_layout Standard
3030 where
3031 \family typewriter
3032 audio_frame
3033 \family default
3034  is used both as input and output.
3035 \end_layout
3036
3037 \begin_layout Standard
3038 In cases where the output audio is not useful for a certain frame, it is
3039  possible to use instead:
3040 \end_layout
3041
3042 \begin_layout Standard
3043 \begin_inset listings
3044 inline false
3045 status open
3046
3047 \begin_layout Standard
3048
3049 speex_preprocess_estimate_update(preprocess_state, audio_frame);
3050 \end_layout
3051
3052 \end_inset
3053
3054
3055 \end_layout
3056
3057 \begin_layout Standard
3058 This call will update all the preprocessor internal state variables without
3059  computing the output audio, thus saving some CPU cycles.
3060 \end_layout
3061
3062 \begin_layout Standard
3063 The behaviour of the preprocessor can be changed using:
3064 \end_layout
3065
3066 \begin_layout Standard
3067 \begin_inset listings
3068 inline false
3069 status open
3070
3071 \begin_layout Standard
3072
3073 speex_preprocess_ctl(preprocess_state, request, ptr);
3074 \end_layout
3075
3076 \end_inset
3077
3078
3079 \end_layout
3080
3081 \begin_layout Standard
3082 which is used in the same way as the encoder and decoder equivalent.
3083  Options are listed in Section .
3084 \end_layout
3085
3086 \begin_layout Standard
3087 The preprocessor state can be destroyed using:
3088 \end_layout
3089
3090 \begin_layout Standard
3091 \begin_inset listings
3092 inline false
3093 status open
3094
3095 \begin_layout Standard
3096
3097 speex_preprocess_state_destroy(preprocess_state);
3098 \end_layout
3099
3100 \end_inset
3101
3102
3103 \end_layout
3104
3105 \begin_layout Subsubsection
3106 Preprocessor options
3107 \begin_inset LatexCommand label
3108 name "sub:Preprocessor-options"
3109
3110 \end_inset
3111
3112
3113 \end_layout
3114
3115 \begin_layout Description
3116 SPEEX_PREPROCESS_SET_DENOISE Turns denoising on(1) or off(2) (integer)
3117 \end_layout
3118
3119 \begin_layout Description
3120 SPEEX_PREPROCESS_GET_DENOISE Get denoising status (integer)
3121 \end_layout
3122
3123 \begin_layout Description
3124 SPEEX_PREPROCESS_SET_AGC Turns automatic gain control (AGC) on(1) or off(2)
3125  (integer)
3126 \end_layout
3127
3128 \begin_layout Description
3129 SPEEX_PREPROCESS_GET_AGC Get AGC status (integer)
3130 \end_layout
3131
3132 \begin_layout Description
3133 SPEEX_PREPROCESS_SET_VAD Turns voice activity detector (VAD) on(1) or off(2)
3134  (integer)
3135 \end_layout
3136
3137 \begin_layout Description
3138 SPEEX_PREPROCESS_GET_VAD Get VAD status (integer)
3139 \end_layout
3140
3141 \begin_layout Description
3142 SPEEX_PREPROCESS_SET_AGC_LEVEL
3143 \end_layout
3144
3145 \begin_layout Description
3146 SPEEX_PREPROCESS_GET_AGC_LEVEL
3147 \end_layout
3148
3149 \begin_layout Description
3150 SPEEX_PREPROCESS_SET_DEREVERB Turns reverberation removal on(1) or off(2)
3151  (integer)
3152 \end_layout
3153
3154 \begin_layout Description
3155 SPEEX_PREPROCESS_GET_DEREVERB Get reverberation removal status (integer)
3156 \end_layout
3157
3158 \begin_layout Description
3159 SPEEX_PREPROCESS_SET_DEREVERB_LEVEL
3160 \end_layout
3161
3162 \begin_layout Description
3163 SPEEX_PREPROCESS_GET_DEREVERB_LEVEL
3164 \end_layout
3165
3166 \begin_layout Description
3167 SPEEX_PREPROCESS_SET_DEREVERB_DECAY
3168 \end_layout
3169
3170 \begin_layout Description
3171 SPEEX_PREPROCESS_GET_DEREVERB_DECAY
3172 \end_layout
3173
3174 \begin_layout Description
3175 SPEEX_PREPROCESS_SET_PROB_START
3176 \end_layout
3177
3178 \begin_layout Description
3179 SPEEX_PREPROCESS_GET_PROB_START
3180 \end_layout
3181
3182 \begin_layout Description
3183 SPEEX_PREPROCESS_SET_PROB_CONTINUE
3184 \end_layout
3185
3186 \begin_layout Description
3187 SPEEX_PREPROCESS_GET_PROB_CONTINUE
3188 \end_layout
3189
3190 \begin_layout Description
3191 SPEEX_PREPROCESS_SET_NOISE_SUPPRESS Set maximum attenuation of the noise
3192  in dB (negative number)
3193 \end_layout
3194
3195 \begin_layout Description
3196 SPEEX_PREPROCESS_GET_NOISE_SUPPRESS Get maximum attenuation of the noise
3197  in dB (negative number)
3198 \end_layout
3199
3200 \begin_layout Description
3201 SPEEX_PREPROCESS_SET_ECHO_SUPPRESS Set maximum attenuation of the residual
3202  echo in dB (negative number)
3203 \end_layout
3204
3205 \begin_layout Description
3206 SPEEX_PREPROCESS_GET_ECHO_SUPPRESS Set maximum attenuation of the residual
3207  echo in dB (negative number)
3208 \end_layout
3209
3210 \begin_layout Description
3211 SPEEX_PREPROCESS_SET_ECHO_SUPPRESS_ACTIVE Set maximum attenuation of the
3212  echo in dB when near end is active (negative number)
3213 \end_layout
3214
3215 \begin_layout Description
3216 SPEEX_PREPROCESS_GET_ECHO_SUPPRESS_ACTIVE Set maximum attenuation of the
3217  echo in dB when near end is active (negative number)
3218 \end_layout
3219
3220 \begin_layout Description
3221 SPEEX_PREPROCESS_SET_ECHO_STATE Set the associated echo canceller for residual
3222  echo suppression (NULL for no residual echo suppression)
3223 \end_layout
3224
3225 \begin_layout Description
3226 SPEEX_PREPROCESS_GET_ECHO_STATE Get the associated echo canceller
3227 \end_layout
3228
3229 \begin_layout Subsection
3230 Echo Cancellation
3231 \begin_inset LatexCommand label
3232 name "sub:Echo-Cancellation"
3233
3234 \end_inset
3235
3236
3237 \end_layout
3238
3239 \begin_layout Standard
3240 The Speex library now includes an echo cancellation
3241 \begin_inset LatexCommand index
3242 name "echo cancellation"
3243
3244 \end_inset
3245
3246  algorithm suitable for Acoustic Echo Cancellation
3247 \begin_inset LatexCommand index
3248 name "acoustic echo cancellation"
3249
3250 \end_inset
3251
3252  (AEC).
3253  In order to use the echo canceller, you first need to
3254 \end_layout
3255
3256 \begin_layout Standard
3257 \begin_inset listings
3258 inline false
3259 status open
3260
3261 \begin_layout Standard
3262
3263 #include <speex/speex_echo.h>
3264 \end_layout
3265
3266 \end_inset
3267
3268
3269 \end_layout
3270
3271 \begin_layout Standard
3272 Then, an echo canceller state can be created by:
3273 \end_layout
3274
3275 \begin_layout Standard
3276 \begin_inset listings
3277 inline false
3278 status open
3279
3280 \begin_layout Standard
3281
3282 SpeexEchoState *echo_state = speex_echo_state_init(frame_size, filter_length);
3283 \end_layout
3284
3285 \end_inset
3286
3287
3288 \end_layout
3289
3290 \begin_layout Standard
3291 where
3292 \family typewriter
3293 frame_size
3294 \family default
3295  is the amount of data (in samples) you want to process at once and
3296 \family typewriter
3297 filter_length
3298 \family default
3299  is the length (in samples) of the echo cancelling filter you want to use
3300  (also known as
3301 \shape italic
3302 tail length
3303 \shape default
3304
3305 \begin_inset LatexCommand index
3306 name "tail length"
3307
3308 \end_inset
3309
3310 ).
3311  It is recommended to use a frame size in the order of 20 ms (or equal to
3312  the codec frame size) and make sure it is easy to perform an FFT of that
3313  size (powers of two are better than prime sizes).
3314  The recommended tail length is approximately the third of the room reverberatio
3315 n time.
3316  For example, in a small room, reverberation time is in the order of 300
3317  ms, so a tail length of 100 ms is a good choice (800 samples at 8000 Hz
3318  sampling rate).
3319 \end_layout
3320
3321 \begin_layout Standard
3322 Once the echo canceller state is created, audio can be processed by:
3323 \end_layout
3324
3325 \begin_layout Standard
3326 \begin_inset listings
3327 inline false
3328 status open
3329
3330 \begin_layout Standard
3331
3332 speex_echo_cancellation(echo_state, input_frame, echo_frame, output_frame);
3333 \end_layout
3334
3335 \end_inset
3336
3337
3338 \end_layout
3339
3340 \begin_layout Standard
3341 where
3342 \family typewriter
3343 input_frame
3344 \family default
3345  is the audio as captured by the microphone,
3346 \family typewriter
3347 echo_frame
3348 \family default
3349  is the signal that was played in the speaker (and needs to be removed)
3350  and
3351 \family typewriter
3352 output_frame
3353 \family default
3354  is the signal with echo removed.
3355
3356 \end_layout
3357
3358 \begin_layout Standard
3359 One important thing to keep in mind is the relationship between
3360 \family typewriter
3361 input_frame
3362 \family default
3363  and
3364 \family typewriter
3365 echo_frame
3366 \family default
3367 .
3368  It is important that, at any time, any echo that is present in the input
3369  has already been sent to the echo canceller as
3370 \family typewriter
3371 echo_frame
3372 \family default
3373 .
3374  In other words, the echo canceller cannot remove a signal that it hasn't
3375  yet received.
3376  On the other hand, the delay between the input signal and the echo signal
3377  must be small enough because otherwise part of the echo cancellation filter
3378  is inefficient.
3379  In the ideal case, you code would look like:
3380 \begin_inset listings
3381 lstparams "breaklines=true"
3382 inline false
3383 status open
3384
3385 \begin_layout Standard
3386
3387 write_to_soundcard(echo_frame, frame_size);
3388 \end_layout
3389
3390 \begin_layout Standard
3391
3392 read_from_soundcard(input_frame, frame_size);
3393 \end_layout
3394
3395 \begin_layout Standard
3396
3397 speex_echo_cancellation(echo_state, input_frame, echo_frame, output_frame);
3398 \end_layout
3399
3400 \end_inset
3401
3402
3403 \end_layout
3404
3405 \begin_layout Standard
3406 If you wish to further reduce the echo present in the signal, you can do
3407  so by associating the echo canceller to the preprocessor (see Section
3408 \begin_inset LatexCommand ref
3409 reference "sub:Preprocessor"
3410
3411 \end_inset
3412
3413 ).
3414  This is done by calling:
3415 \begin_inset listings
3416 lstparams "breaklines=true"
3417 inline false
3418 status open
3419
3420 \begin_layout Standard
3421
3422 speex_preprocess_ctl(preprocess_state, SPEEX_PREPROCESS_SET_ECHO_STATE,echo_stat
3423 e);
3424 \end_layout
3425
3426 \end_inset
3427
3428 in the initialisation.
3429 \end_layout
3430
3431 \begin_layout Standard
3432 As of version 1.2-beta2, there is an alternative, simpler API that can be
3433  used instead of
3434 \emph on
3435 speex_echo_cancellation()
3436 \emph default
3437 .
3438  When audio capture and playback are handled asynchronously (e.g.
3439  in different threads or using the
3440 \emph on
3441 poll()
3442 \emph default
3443  or
3444 \emph on
3445 select()
3446 \emph default
3447  system call), it can be difficult to keep track of what input_frame comes
3448  with what echo_frame.
3449  Instead, the playback comtext/thread can simply call:
3450 \end_layout
3451
3452 \begin_layout Standard
3453 \begin_inset listings
3454 inline false
3455 status open
3456
3457 \begin_layout Standard
3458
3459 speex_echo_playback(echo_state, echo_frame);
3460 \end_layout
3461
3462 \end_inset
3463
3464
3465 \end_layout
3466
3467 \begin_layout Standard
3468 every time an audio frame is played.
3469  Then, the capture context/thread calls:
3470 \end_layout
3471
3472 \begin_layout Standard
3473 \begin_inset listings
3474 inline false
3475 status open
3476
3477 \begin_layout Standard
3478
3479 speex_echo_capture(echo_state, input_frame, output_frame);
3480 \end_layout
3481
3482 \end_inset
3483
3484
3485 \end_layout
3486
3487 \begin_layout Standard
3488 for every frame captured.
3489  Internally,
3490 \emph on
3491 speex_echo_playback()
3492 \emph default
3493  simply buffers the playback frame so it can be used by
3494 \emph on
3495 speex_echo_capture()
3496 \emph default
3497  to call
3498 \emph on
3499 speex_echo_cancel()
3500 \emph default
3501 .
3502  A side effect of using this alternate API is that the playback audio is
3503  delayed by two frames, which is the normal delay caused by the soundcard.
3504  When capture and playback are already synchronised,
3505 \emph on
3506 speex_echo_cancellation()
3507 \emph default
3508  is preferable since it gives better control on the exact input/echo timing.
3509 \end_layout
3510
3511 \begin_layout Standard
3512 The echo cancellation state can be destroyed with:
3513 \end_layout
3514
3515 \begin_layout Standard
3516 \begin_inset listings
3517 inline false
3518 status open
3519
3520 \begin_layout Standard
3521
3522 speex_echo_state_destroy(echo_state);
3523 \end_layout
3524
3525 \end_inset
3526
3527
3528 \end_layout
3529
3530 \begin_layout Standard
3531 It is also possible to reset the state of the echo canceller so it can be
3532  reused without the need to create another state with:
3533 \end_layout
3534
3535 \begin_layout Standard
3536 \begin_inset listings
3537 inline false
3538 status open
3539
3540 \begin_layout Standard
3541
3542 speex_echo_state_reset(echo_state);
3543 \end_layout
3544
3545 \end_inset
3546
3547
3548 \end_layout
3549
3550 \begin_layout Subsubsection
3551 Troubleshooting
3552 \end_layout
3553
3554 \begin_layout Standard
3555 There are several things that may prevent the echo canceller from working
3556  properly.
3557  One of them is a bug (or something suboptimal) in the code, but there are
3558  many others you should consider first
3559 \end_layout
3560
3561 \begin_layout Itemize
3562 Using a different soundcard to do the capture and plaback will *not* work,
3563  regardless of what you may think.
3564  The only exception to that is if the two cards can be made to have their
3565  sampling clock
3566 \begin_inset Quotes eld
3567 \end_inset
3568
3569 locked
3570 \begin_inset Quotes erd
3571 \end_inset
3572
3573  on the same clock source.
3574 \end_layout
3575
3576 \begin_layout Itemize
3577 The delay between the record and playback signals must be minimal.
3578  Any signal played has to
3579 \begin_inset Quotes eld
3580 \end_inset
3581
3582 appear
3583 \begin_inset Quotes erd
3584 \end_inset
3585
3586  on the playback (far end) signal slightly before the echo canceller
3587 \begin_inset Quotes eld
3588 \end_inset
3589
3590 sees
3591 \begin_inset Quotes erd
3592 \end_inset
3593
3594  it in the near end signal, but excessive delay means that part of the filter
3595  length is wasted.
3596  In the worst situations, the delay is such that it is longer than the filter
3597  length, in which case, no echo can be cancelled.
3598 \end_layout
3599
3600 \begin_layout Itemize
3601 When it comes to echo tail length (filter length), longer is *not* better.
3602  Actually, the longer the tail length, the longer it takes for the filter
3603  to adapt.
3604  Of course, a tail length that is too short will not cancel enough echo,
3605  but the most common problem seen is that people set a very long tail length
3606  and then wonder why no echo is being cancelled.
3607 \end_layout
3608
3609 \begin_layout Itemize
3610 Non-linear distortion cannot (by definition) be modeled by the linear adaptive
3611  filter used in the echo canceller and thus cannot be cancelled.
3612  Use good audio gear and avoid saturation/clipping.
3613 \end_layout
3614
3615 \begin_layout Standard
3616 Also useful is reading
3617 \emph on
3618 Echo Cancellation Demystified
3619 \emph default
3620  by Alexey Frunze
3621 \begin_inset Foot
3622 status collapsed
3623
3624 \begin_layout Standard
3625 http://www.embeddedstar.com/articles/2003/7/article20030720-1.html
3626 \end_layout
3627
3628 \end_inset
3629
3630 , which explains the fundamental principles of echo cancellation.
3631  The details of the algorithm described in the article are different, but
3632  the general ideas of echo cancellation through adaptive filters are the
3633  same.
3634 \end_layout
3635
3636 \begin_layout Standard
3637 As of version 1.2beta2, a new
3638 \family typewriter
3639 echo_diagnostic.m
3640 \family default
3641  tool is included in the source distribution.
3642  The first step is to define DUMP_ECHO_CANCEL_DATA during the build.
3643  This causes the echo canceller to automatically save the near-end, far-end
3644  and output signals to files (aec_rec.sw aec_play.sw and aec_out.sw).
3645  These are exactly what the AEC receives and outputs.
3646  From there, it is necessary to start Octave and type:
3647 \end_layout
3648
3649 \begin_layout Standard
3650 \begin_inset listings
3651 lstparams "language=Matlab"
3652 inline false
3653 status open
3654
3655 \begin_layout Standard
3656
3657 echo_diagnostic('aec_rec.sw', 'aec_play.sw', 'aec_diagnostic.sw', 1024);
3658 \end_layout
3659
3660 \end_inset
3661
3662
3663 \end_layout
3664
3665 \begin_layout Standard
3666 The value of 1024 is the filter length and can be changed.
3667  There will be some (hopefully) useful messages printed and echo cancelled
3668  audio will be saved to aec_diagnostic.sw .
3669  If even that output is bad (almost no cancellation) then there is  probably
3670  problem with the playback or recording process.
3671 \end_layout
3672
3673 \begin_layout Subsection
3674 Jitter Buffer
3675 \end_layout
3676
3677 \begin_layout Standard
3678 The jitter buffer can be enabled by including:
3679 \begin_inset listings
3680 lstparams "breaklines=true"
3681 inline false
3682 status open
3683
3684 \begin_layout Standard
3685
3686 #include <speex/speex_jitter.h>
3687 \end_layout
3688
3689 \end_inset
3690
3691  and a new jitter buffer state can be initialised by:
3692 \end_layout
3693
3694 \begin_layout Standard
3695 \begin_inset listings
3696 lstparams "breaklines=true"
3697 inline false
3698 status open
3699
3700 \begin_layout Standard
3701
3702 JitterBuffer *state = jitter_buffer_init(tick);
3703 \end_layout
3704
3705 \end_inset
3706
3707
3708 \end_layout
3709
3710 \begin_layout Standard
3711 where the
3712 \begin_inset listings
3713 inline true
3714 status collapsed
3715
3716 \begin_layout Standard
3717
3718 tick
3719 \end_layout
3720
3721 \end_inset
3722
3723  argument is the time resolution (in timestamp units) used for the jitter
3724  buffer, and is generally the period at which the data is played out of
3725  the jitter buffer.
3726
3727 \end_layout
3728
3729 \begin_layout Standard
3730 The jitter buffer API is based on the
3731 \begin_inset listings
3732 inline true
3733 status open
3734
3735 \begin_layout Standard
3736
3737 JitterBufferPacket
3738 \end_layout
3739
3740 \end_inset
3741
3742  type, which is defined as:
3743 \begin_inset listings
3744 inline false
3745 status open
3746
3747 \begin_layout Standard
3748
3749 typedef struct {
3750 \end_layout
3751
3752 \begin_layout Standard
3753
3754    char        *data;       /* Data bytes contained in the packet */
3755 \end_layout
3756
3757 \begin_layout Standard
3758
3759    spx_uint32_t len;        /* Length of the packet in bytes */
3760 \end_layout
3761
3762 \begin_layout Standard
3763
3764    spx_uint32_t timestamp;  /* Timestamp for the packet */
3765 \end_layout
3766
3767 \begin_layout Standard
3768
3769    spx_uint32_t span;       /* Time covered by the packet (timestamp units)
3770  */
3771 \end_layout
3772
3773 \begin_layout Standard
3774
3775 } JitterBufferPacket;
3776 \end_layout
3777
3778 \end_inset
3779
3780
3781 \end_layout
3782
3783 \begin_layout Standard
3784 When a packet arrives, it need to be inserter into the jitter buffer by:
3785 \begin_inset listings
3786 inline false
3787 status open
3788
3789 \begin_layout Standard
3790
3791 JitterBufferPacket packet;
3792 \end_layout
3793
3794 \begin_layout Standard
3795
3796 /* Fill in the packet fields */
3797 \end_layout
3798
3799 \begin_layout Standard
3800
3801 jitter_buffer_put(state, &packet);
3802 \end_layout
3803
3804 \end_inset
3805
3806
3807 \end_layout
3808
3809 \begin_layout Standard
3810 When the decoder is ready to decode a packet the packet to be decoded can
3811  be obtained by:
3812 \begin_inset listings
3813 inline false
3814 status open
3815
3816 \begin_layout Standard
3817
3818 int start_offset;
3819 \end_layout
3820
3821 \begin_layout Standard
3822
3823 err = jitter_buffer_get(state, &packet, &start_offset);
3824 \end_layout
3825
3826 \end_inset
3827
3828
3829 \end_layout
3830
3831 \begin_layout Standard
3832 If
3833 \begin_inset listings
3834 inline true
3835 status open
3836
3837 \begin_layout Standard
3838
3839 jitter_buffer_put()
3840 \end_layout
3841
3842 \end_inset
3843
3844  and
3845 \begin_inset listings
3846 inline true
3847 status open
3848
3849 \begin_layout Standard
3850
3851 jitter_buffer_get()
3852 \end_layout
3853
3854 \end_inset
3855
3856  are called from different threads, then
3857 \series bold
3858 you need to protect the jitter buffer state with a mutex
3859 \series default
3860 .
3861
3862 \end_layout
3863
3864 \begin_layout Standard
3865 Because the jitter buffer is designed not to use an explicit timer, it needs
3866  to be told about the time explicitly.
3867  This is done by calling:
3868 \begin_inset listings
3869 inline false
3870 status open
3871
3872 \begin_layout Standard
3873
3874 jitter_buffer_tick(state);
3875 \end_layout
3876
3877 \end_inset
3878
3879
3880 \end_layout
3881
3882 \begin_layout Standard
3883 This needs to be done every time
3884 \begin_inset listings
3885 inline true
3886 status collapsed
3887
3888 \begin_layout Standard
3889
3890 tick
3891 \end_layout
3892
3893 \end_inset
3894
3895  units have elapsed.
3896
3897 \end_layout
3898
3899 \begin_layout Subsection
3900 Resampler
3901 \end_layout
3902
3903 \begin_layout Standard
3904 Speex includes a resampling modules.
3905  To make use of the resampler, it is necessary to include its header file:
3906 \end_layout
3907
3908 \begin_layout Standard
3909 \begin_inset listings
3910 inline false
3911 status open
3912
3913 \begin_layout Standard
3914
3915 #include <speex/speex_resampler.h>
3916 \end_layout
3917
3918 \end_inset
3919
3920
3921 \end_layout
3922
3923 \begin_layout Standard
3924 For each stream that is to be resampled, it is necessary to create a resampler
3925  state with:
3926 \end_layout
3927
3928 \begin_layout Standard
3929 \begin_inset listings
3930 inline false
3931 status open
3932
3933 \begin_layout Standard
3934
3935 SpeexResamplerState *resampler;
3936 \end_layout
3937
3938 \begin_layout Standard
3939
3940 resampler = speex_resampler_init(nb_channels, input_rate, output_rate, quality,
3941  &err);
3942 \end_layout
3943
3944 \end_inset
3945
3946
3947 \end_layout
3948
3949 \begin_layout Standard
3950 where nb_channels is the number of channels that will be used (either interleave
3951 d or non-interleaved), input_rate is the sampling rate of the input stream,
3952  output_rate is the sampling rate of the output stream and quality is the
3953  requested quality setting (0 to 10).
3954  The quality parameter is useful for controlling the quality/complexity/latency
3955  tradeoff.
3956  Using a higher quality setting means less noise/aliasing, a higher complexity
3957  and a higher latency.
3958  Usually, a quality of 3 is acceptable for most desktop uses and quality
3959  10 is mostly recommended for pro audio work.
3960  Quality 0 usually has a decent sound (certainly better than using linear
3961  interpolation resampling), but artifacts may be heard.
3962 \end_layout
3963
3964 \begin_layout Standard
3965 The actual resampling is performed using
3966 \end_layout
3967
3968 \begin_layout Standard
3969 \begin_inset listings
3970 inline false
3971 status open
3972
3973 \begin_layout Standard
3974
3975 err = speex_resampler_process_int(resampler, channelID, in, &in_length,
3976  out, &out_length);
3977 \end_layout
3978
3979 \end_inset
3980
3981 where channelID is the ID of the channel to be processed.
3982  For a mono stream, use 0.
3983  The
3984 \emph on
3985 in
3986 \emph default
3987  pointer points to the first sample of the input buffer for the selected
3988  channel and
3989 \emph on
3990 out
3991 \emph default
3992  points to the first sample of the output.
3993  The size of the input and output buffers are specified by
3994 \emph on
3995 in_length
3996 \emph default
3997  and
3998 \emph on
3999 out_length
4000 \emph default
4001  respectively.
4002  Upon completion, these values are replaced by the number of samples read
4003  and written by the resampler.
4004  Unless an error occurs, either all input samples will be read or all output
4005  samples will be written to (or both).
4006  For floating-point samples, the function speex_resampler_process_float()
4007  behaves similarly.
4008 \end_layout
4009
4010 \begin_layout Standard
4011 It is also possible to process multiple channels at once.
4012
4013 \end_layout
4014
4015 \begin_layout Standard
4016
4017 \newpage
4018
4019 \end_layout
4020
4021 \begin_layout Chapter
4022 Formats and standards
4023 \begin_inset LatexCommand index
4024 name "standards"
4025
4026 \end_inset
4027
4028
4029 \begin_inset LatexCommand label
4030 name "sec:Formats-and-standards"
4031
4032 \end_inset
4033
4034
4035 \end_layout
4036
4037 \begin_layout Standard
4038 Speex can encode speech in both narrowband and wideband and provides different
4039  bit-rates.
4040  However, not all features need to be supported by a certain implementation
4041  or device.
4042  In order to be called
4043 \begin_inset Quotes eld
4044 \end_inset
4045
4046 Speex compatible
4047 \begin_inset Quotes erd
4048 \end_inset
4049
4050  (whatever that means), an implementation must implement at least a basic
4051  set of features.
4052 \end_layout
4053
4054 \begin_layout Standard
4055 At the minimum, all narrowband modes of operation MUST be supported at the
4056  decoder.
4057  This includes the decoding of a wideband bit-stream by the narrowband decoder
4058 \begin_inset Foot
4059 status collapsed
4060
4061 \begin_layout Standard
4062 The wideband bit-stream contains an embedded narrowband bit-stream which
4063  can be decoded alone
4064 \end_layout
4065
4066 \end_inset
4067
4068 .
4069  If present, a wideband decoder MUST be able to decode a narrowband stream,
4070  and MAY either be able to decode all wideband modes or be able to decode
4071  the embedded narrowband part of all modes (which includes ignoring the
4072  high-band bits).
4073 \end_layout
4074
4075 \begin_layout Standard
4076 For encoders, at least one narrowband or wideband mode MUST be supported.
4077  The main reason why all encoding modes do not have to be supported is that
4078  some platforms may not be able to handle the complexity of encoding in
4079  some modes.
4080 \end_layout
4081
4082 \begin_layout Section
4083 RTP
4084 \begin_inset LatexCommand index
4085 name "RTP"
4086
4087 \end_inset
4088
4089  Payload Format
4090 \end_layout
4091
4092 \begin_layout Standard
4093 The RTP payload draft is included in appendix
4094 \begin_inset LatexCommand ref
4095 reference "sec:IETF-draft"
4096
4097 \end_inset
4098
4099  and the latest version is available at
4100 \begin_inset LatexCommand url
4101 target "http://www.speex.org/drafts/latest"
4102
4103 \end_inset
4104
4105 .
4106  This draft has been sent (2003/02/26) to the Internet Engineering Task
4107  Force (IETF) and will be discussed at the March 18th meeting in San Francisco.
4108
4109 \end_layout
4110
4111 \begin_layout Section
4112 MIME Type
4113 \end_layout
4114
4115 \begin_layout Standard
4116 For now, you should use the MIME type audio/x-speex for Speex-in-Ogg.
4117  We will apply for type
4118 \family typewriter
4119 audio/speex
4120 \family default
4121  in the near future.
4122 \end_layout
4123
4124 \begin_layout Section
4125 Ogg
4126 \begin_inset LatexCommand index
4127 name "Ogg"
4128
4129 \end_inset
4130
4131  file format
4132 \end_layout
4133
4134 \begin_layout Standard
4135 Speex bit-streams can be stored in Ogg files.
4136  In this case, the first packet of the Ogg file contains the Speex header
4137  described in table
4138 \begin_inset LatexCommand ref
4139 reference "cap:ogg_speex_header"
4140
4141 \end_inset
4142
4143 .
4144  All integer fields in the headers are stored as little-endian.
4145  The
4146 \family typewriter
4147 speex_string
4148 \family default
4149  field must contain the
4150 \begin_inset Quotes eld
4151 \end_inset
4152
4153
4154 \family typewriter
4155 Speex
4156 \family default
4157 \InsetSpace ~
4158 \InsetSpace ~
4159 \InsetSpace ~
4160
4161 \begin_inset Quotes erd
4162 \end_inset
4163
4164  (with 3 trailing spaces), which identifies the bit-stream.
4165  The next field,
4166 \family typewriter
4167 speex_version
4168 \family default
4169  contains the version of Speex that encoded the file.
4170  For now, refer to speex_header.[ch] for more info.
4171  The
4172 \emph on
4173 beginning of stream
4174 \emph default
4175  (
4176 \family typewriter
4177 b_o_s
4178 \family default
4179 ) flag is set to 1 for the header.
4180  The header packet has
4181 \family typewriter
4182 packetno=0
4183 \family default
4184  and
4185 \family typewriter
4186 granulepos=0
4187 \family default
4188 .
4189 \end_layout
4190
4191 \begin_layout Standard
4192 The second packet contains the Speex comment header.
4193  The format used is the Vorbis comment format described here: http://www.xiph.org/
4194 ogg/vorbis/doc/v-comment.html .
4195  This packet has
4196 \family typewriter
4197 packetno=1
4198 \family default
4199  and
4200 \family typewriter
4201 granulepos=0
4202 \family default
4203 .
4204 \end_layout
4205
4206 \begin_layout Standard
4207 The third and subsequent packets each contain one or more (number found
4208  in header) Speex frames.
4209  These are identified with
4210 \family typewriter
4211 packetno
4212 \family default
4213  starting from 2 and the
4214 \family typewriter
4215 granulepos
4216 \family default
4217  is the number of the last sample encoded in that packet.
4218  The last of these packets has the
4219 \emph on
4220 end of stream
4221 \emph default
4222  (
4223 \family typewriter
4224 e_o_s
4225 \family default
4226 ) flag is set to 1.
4227 \end_layout
4228
4229 \begin_layout Standard
4230 \begin_inset Float table
4231 placement htbp
4232 wide true
4233 sideways false
4234 status open
4235
4236 \begin_layout Standard
4237 \begin_inset ERT
4238 status collapsed
4239
4240 \begin_layout Standard
4241
4242
4243 \backslash
4244 begin{center}
4245 \end_layout
4246
4247 \end_inset
4248
4249
4250 \begin_inset Tabular
4251 <lyxtabular version="3" rows="16" columns="3">
4252 <features>
4253 <column alignment="center" valignment="top" leftline="true" width="0pt">
4254 <column alignment="center" valignment="top" leftline="true" width="0pt">
4255 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
4256 <row topline="true" bottomline="true">
4257 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4258 \begin_inset Text
4259
4260 \begin_layout Standard
4261 Field
4262 \end_layout
4263
4264 \end_inset
4265 </cell>
4266 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4267 \begin_inset Text
4268
4269 \begin_layout Standard
4270 Type
4271 \end_layout
4272
4273 \end_inset
4274 </cell>
4275 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4276 \begin_inset Text
4277
4278 \begin_layout Standard
4279 Size
4280 \end_layout
4281
4282 \end_inset
4283 </cell>
4284 </row>
4285 <row topline="true">
4286 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4287 \begin_inset Text
4288
4289 \begin_layout Standard
4290 speex_string
4291 \end_layout
4292
4293 \end_inset
4294 </cell>
4295 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4296 \begin_inset Text
4297
4298 \begin_layout Standard
4299 char[]
4300 \end_layout
4301
4302 \end_inset
4303 </cell>
4304 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4305 \begin_inset Text
4306
4307 \begin_layout Standard
4308 8
4309 \end_layout
4310
4311 \end_inset
4312 </cell>
4313 </row>
4314 <row topline="true">
4315 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4316 \begin_inset Text
4317
4318 \begin_layout Standard
4319 speex_version
4320 \end_layout
4321
4322 \end_inset
4323 </cell>
4324 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4325 \begin_inset Text
4326
4327 \begin_layout Standard
4328 char[]
4329 \end_layout
4330
4331 \end_inset
4332 </cell>
4333 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4334 \begin_inset Text
4335
4336 \begin_layout Standard
4337 20
4338 \end_layout
4339
4340 \end_inset
4341 </cell>
4342 </row>
4343 <row topline="true">
4344 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4345 \begin_inset Text
4346
4347 \begin_layout Standard
4348 speex_version_id
4349 \end_layout
4350
4351 \end_inset
4352 </cell>
4353 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4354 \begin_inset Text
4355
4356 \begin_layout Standard
4357 int
4358 \end_layout
4359
4360 \end_inset
4361 </cell>
4362 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4363 \begin_inset Text
4364
4365 \begin_layout Standard
4366 4
4367 \end_layout
4368
4369 \end_inset
4370 </cell>
4371 </row>
4372 <row topline="true">
4373 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4374 \begin_inset Text
4375
4376 \begin_layout Standard
4377 header_size
4378 \end_layout
4379
4380 \end_inset
4381 </cell>
4382 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4383 \begin_inset Text
4384
4385 \begin_layout Standard
4386 int
4387 \end_layout
4388
4389 \end_inset
4390 </cell>
4391 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4392 \begin_inset Text
4393
4394 \begin_layout Standard
4395 4
4396 \end_layout
4397
4398 \end_inset
4399 </cell>
4400 </row>
4401 <row topline="true">
4402 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4403 \begin_inset Text
4404
4405 \begin_layout Standard
4406 rate
4407 \end_layout
4408
4409 \end_inset
4410 </cell>
4411 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4412 \begin_inset Text
4413
4414 \begin_layout Standard
4415 int
4416 \end_layout
4417
4418 \end_inset
4419 </cell>
4420 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4421 \begin_inset Text
4422
4423 \begin_layout Standard
4424 4
4425 \end_layout
4426
4427 \end_inset
4428 </cell>
4429 </row>
4430 <row topline="true">
4431 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4432 \begin_inset Text
4433
4434 \begin_layout Standard
4435 mode
4436 \end_layout
4437
4438 \end_inset
4439 </cell>
4440 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4441 \begin_inset Text
4442
4443 \begin_layout Standard
4444 int
4445 \end_layout
4446
4447 \end_inset
4448 </cell>
4449 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4450 \begin_inset Text
4451
4452 \begin_layout Standard
4453 4
4454 \end_layout
4455
4456 \end_inset
4457 </cell>
4458 </row>
4459 <row topline="true">
4460 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4461 \begin_inset Text
4462
4463 \begin_layout Standard
4464 mode_bitstream_version
4465 \end_layout
4466
4467 \end_inset
4468 </cell>
4469 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4470 \begin_inset Text
4471
4472 \begin_layout Standard
4473 int
4474 \end_layout
4475
4476 \end_inset
4477 </cell>
4478 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4479 \begin_inset Text
4480
4481 \begin_layout Standard
4482 4
4483 \end_layout
4484
4485 \end_inset
4486 </cell>
4487 </row>
4488 <row topline="true">
4489 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4490 \begin_inset Text
4491
4492 \begin_layout Standard
4493 nb_channels
4494 \end_layout
4495
4496 \end_inset
4497 </cell>
4498 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">