[xiph-commits] r12809 - trunk/speex/doc

[jm at svn.xiph.org]

Author: jm
Date: 2007-03-27 04:21:46 -0700 (Tue, 27 Mar 2007)
New Revision: 12809

Modified:
   trunk/speex/doc/manual.lyx
Log:
Attempting to make Speex harder to misuse (for those who RTFM)


Modified: trunk/speex/doc/manual.lyx
===================================================================
--- trunk/speex/doc/manual.lyx	2007-03-27 09:10:37 UTC (rev 12808)
+++ trunk/speex/doc/manual.lyx	2007-03-27 11:21:46 UTC (rev 12809)
@@ -1,4 +1,4 @@
-#LyX 1.4.3 created this file. For more info see http://www.lyx.org/
+#LyX 1.4.4 created this file. For more info see http://www.lyx.org/
 \lyxformat 245
 \begin_document
 \begin_header
@@ -1729,6 +1729,31 @@
  same.
 \end_layout
 
+\begin_layout Standard
+As of version 1.2beta2, a new 
+\family typewriter
+echo_diagnostic.m
+\family default
+ tool is included in the source distribution.
+ The first step is to define DUMP_ECHO_CANCEL_DATA during the build.
+ This causes the echo canceller to automatically save the near-end, far-end
+ and output signals to files (aec_rec.sw aec_play.sw and aec_out.sw).
+ These are exactly what the AEC receives and outputs.
+ From there, it is necessary to start Octave and type:
+\end_layout
+
+\begin_layout LyX-Code
+echo_diagnostic('aec_rec.sw', 'aec_play.sw', 'aec_diagnostic.sw', 1024);
+\end_layout
+
+\begin_layout Standard
+The value of 1024 is the filter length and can be changed.
+ There will be some (hopefully) useful messages printed and echo cancelled
+ audio will be saved to aec_diagnostic.sw .
+ If even that output is bad (almost no cancellation) then there is  probably
+ problem with the playback or recording process.
+\end_layout
+
 \begin_layout Section
 Codec Options (speex_*_ctl)
 \begin_inset LatexCommand \label{sub:Codec-Options}
@@ -1738,6 +1763,20 @@
 
 \end_layout
 
+\begin_layout Quote
+\align center
+
+\emph on
+Entities should not be multiplied beyond necessity -- William of Ockham.
+\end_layout
+
+\begin_layout Quote
+\align center
+
+\emph on
+Just because there's an option doesn't mean you have to use it -- me.
+\end_layout
+
 \begin_layout Standard
 The Speex encoder and decoder support many options and requests that can
  be accessed through the 
@@ -1749,6 +1788,13 @@
 speex_decoder_ctl
 \emph default
  functions.
+ Despite that, the defaults are good for many applications and 
+\series bold
+optional settings should only be used when one understands them and knows
+ that they are needed
+\series default
+.
+ A common error is to attempt to set many unnecessary settings.
  These functions are similar to the 
 \emph on
 ioctl
@@ -3495,6 +3541,14 @@
 
 \end_layout
 
+\begin_layout Quote
+\align center
+
+\emph on
+Do not meddle in the affairs of poles, for they are subtle and quick to
+ leave the unit circle.
+\end_layout
+
 \begin_layout Standard
 Speex is based on CELP, which stands for Code Excited Linear Prediction.
  This section attempts to introduce the principles behind CELP, so if you