Documentation for the echo canceller and preprocessor -- Yeh!!
authorjm <jm@0101bb08-14d6-0310-b084-bc0e0c8e3800>
Sun, 12 Nov 2006 11:26:03 +0000 (11:26 +0000)
committerjm <jm@0101bb08-14d6-0310-b084-bc0e0c8e3800>
Sun, 12 Nov 2006 11:26:03 +0000 (11:26 +0000)
git-svn-id: http://svn.xiph.org/trunk/speex@12091 0101bb08-14d6-0310-b084-bc0e0c8e3800

Speex.kdevelop
configure.ac
include/speex/speex.h
include/speex/speex_echo.h
include/speex/speex_preprocess.h
libspeex/mdf.c
libspeex/preprocess.c

index e4e0749..1fc9ab1 100644 (file)
@@ -11,6 +11,7 @@
     <absoluteprojectpath>false</absoluteprojectpath>
     <description/>
     <secondaryLanguages/>
+    <versioncontrol/>
   </general>
   <kdevautoproject>
     <general>
         <envvar value="1" name="WANT_AUTOMAKE_1_6" />
       </envvars>
       <abortonerror>false</abortonerror>
-      <numberofjobs>1</numberofjobs>
+      <numberofjobs>4</numberofjobs>
       <dontact>false</dontact>
       <makebin/>
+      <runmultiplejobs>true</runmultiplejobs>
+      <prio>0</prio>
     </make>
   </kdevautoproject>
   <kdevdebugger>
@@ -69,6 +72,7 @@
     <display>
       <staticmembers>false</staticmembers>
       <demanglenames>true</demanglenames>
+      <outputradix>10</outputradix>
     </display>
   </kdevdebugger>
   <kdevfilecreate>
       <argumentsHintDelay>400</argumentsHintDelay>
       <headerCompletionDelay>250</headerCompletionDelay>
     </codecompletion>
+    <qt>
+      <used>false</used>
+      <version>3</version>
+      <root/>
+    </qt>
+    <creategettersetter>
+      <prefixGet/>
+      <prefixSet>set</prefixSet>
+      <prefixVariable>m_,_</prefixVariable>
+      <parameterName>theValue</parameterName>
+      <inlineGet>true</inlineGet>
+      <inlineSet>true</inlineSet>
+    </creategettersetter>
   </kdevcppsupport>
   <kdevfileview>
     <groups>
index 6f12e55..114eef0 100644 (file)
@@ -6,11 +6,11 @@ AM_CONFIG_HEADER([config.h])
 
 SPEEX_MAJOR_VERSION=1
 SPEEX_MINOR_VERSION=1
-SPEEX_MICRO_VERSION=13
-SPEEX_EXTRA_VERSION=
+SPEEX_MICRO_VERSION=14
+SPEEX_EXTRA_VERSION=-svn
 #SPEEX_VERSION=
 SPEEX_VERSION=$SPEEX_MAJOR_VERSION.$SPEEX_MINOR_VERSION.$SPEEX_MICRO_VERSION$SPEEX_EXTRA_VERSION
-SPEEX_VERSION="1.2beta1"
+#SPEEX_VERSION="1.2beta1"
 
 SPEEX_LT_CURRENT=5
 SPEEX_LT_REVISION=0
index 7f8afa6..71640c1 100644 (file)
 
 #ifndef SPEEX_H
 #define SPEEX_H
+/** @defgroup Codec Speex encoder and decoder
+ *  This is the Speex codec itself.
+ *  @{
+ */
 
 #include "speex/speex_bits.h"
 #include "speex/speex_types.h"
@@ -427,5 +431,5 @@ const SpeexMode * speex_lib_get_mode (int mode);
 }
 #endif
 
-
+/** @}*/
 #endif
index 6091e37..506c897 100644 (file)
 
 #ifndef SPEEX_ECHO_H
 #define SPEEX_ECHO_H
-
+/** @defgroup SpeexEchoState Acoustic echo canceller
+ *  This is the acoustic echo canceller module.
+ *  @{
+ */
 #include "speex/speex_types.h"
 
 #ifdef __cplusplus
@@ -48,36 +51,62 @@ extern "C" {
 /** Get sampling rate */
 #define SPEEX_ECHO_GET_SAMPLING_RATE 25
 
-
-/*struct drft_lookup;*/
+/** Internal echo canceller state. Should never be accessed directly. */
 struct SpeexEchoState_;
 
+/** @class SpeexEchoState
+ * This holds the state of the echo canceller. You need one per channel. 
+*/
+
 typedef struct SpeexEchoState_ SpeexEchoState;
 
-/** Creates a new echo canceller state */
+/** Creates a new echo canceller state
+ * @param frame_size Number of samples to process at one time (should correspond to 10-20 ms)
+ * @param filter_length Number of samples of echo to cancel (should generally correspond to 100-500 ms)
+ * @return Newly-created echo canceller state
+ */
 SpeexEchoState *speex_echo_state_init(int frame_size, int filter_length);
 
-/** Destroys an echo canceller state */
+/** Destroys an echo canceller state 
+ * @param st Echo canceller state
+*/
 void speex_echo_state_destroy(SpeexEchoState *st);
 
-/** Performs echo cancellation a frame */
+/** Performs echo cancellation a frame, based on the audio sent to the speaker (no delay is added
+ * to playback ni this form)
+ *
+ * @param st Echo canceller state
+ * @param rec signal from the microphone (near end + far end echo)
+ * @param play Signal played to the speaker (received from far end)
+ * @param out Returns near-end signal with echo removed
+ */
 void speex_echo_cancellation(SpeexEchoState *st, const spx_int16_t *rec, const spx_int16_t *play, spx_int16_t *out);
 
 /** Performs echo cancellation a frame (deprecated) */
 void speex_echo_cancel(SpeexEchoState *st, const spx_int16_t *rec, const spx_int16_t *play, spx_int16_t *out, spx_int32_t *Yout);
 
-/** Perform echo cancellation using internal playback buffer */
-void speex_echo_capture(SpeexEchoState *st, const spx_int16_t *rec, spx_int16_t *out, spx_int32_t *Yout);
+/** Perform echo cancellation using internal playback buffer, which is delayed by two frames
+ * to account for the delay introduced by most soundcards (but it could be off!)
+ * @param st Echo canceller state
+ * @param rec signal from the microphone (near end + far end echo)
+ * @param out Returns near-end signal with echo removed
+*/
+void speex_echo_capture(SpeexEchoState *st, const spx_int16_t *rec, spx_int16_t *out);
 
-/** Let the echo canceller know that a frame was just played */
+/** Let the echo canceller know that a frame was just queued to the soundcard
+ * @param st Echo canceller state
+ * @param play Signal played to the speaker (received from far end)
+*/
 void speex_echo_playback(SpeexEchoState *st, const spx_int16_t *play);
 
-/** Reset the echo canceller state */
+/** Reset the echo canceller to its original state 
+ * @param st Echo canceller state
+ */
 void speex_echo_state_reset(SpeexEchoState *st);
 
 /** Used like the ioctl function to control the echo canceller parameters
  *
- * @param state Encoder state
+ * @param st Echo canceller state
  * @param request ioctl-type request (one of the SPEEX_ECHO_* macros)
  * @param ptr Data exchanged to-from function
  * @return 0 if no error, -1 if request in unknown
@@ -88,4 +117,6 @@ int speex_echo_ctl(SpeexEchoState *st, int request, void *ptr);
 }
 #endif
 
+
+/** @}*/
 #endif
index 11888ba..c134b33 100644 (file)
@@ -1,8 +1,10 @@
 /* Copyright (C) 2003 Epic Games
    Written by Jean-Marc Valin */
 /**
-   @file speex_preprocess.h
-   @brief Speex preprocessor
+ *  @file speex_preprocess.h
+ *  @brief Speex preprocessor. The preprocess can do noise suppression, 
+ * residual echo suppression (after using the echo canceller), automatic
+ * gain control (AGC) and voice activity detection (VAD).
 */
 /*
    Redistribution and use in source and binary forms, with or without
 
 #ifndef SPEEX_PREPROCESS_H
 #define SPEEX_PREPROCESS_H
+/** @defgroup SpeexPreprocessState Preprocessor
+ *  This is the Speex preprocessor. The preprocess can do noise suppression, 
+ * residual echo suppression (after using the echo canceller), automatic
+ * gain control (AGC) and voice activity detection (VAD).
+ *  @{
+ */
 
 #include "speex/speex_types.h"
 
@@ -46,22 +54,41 @@ struct SpeexPreprocessState_;
 typedef struct SpeexPreprocessState_ SpeexPreprocessState;
 
 
-/** Creates a new preprocessing state */
+/** Creates a new preprocessing state. You MUST create one state per channel processed.
+ * @param frame_size Number of samples to process at one time (should correspond to 10-20 ms). Must be
+ * the same value as that used for the echo canceller for residual echo cancellation to work.
+ * @param sampling_rate Sampling rate used for the input.
+ * @return Newly created preprocessor state
+*/
 SpeexPreprocessState *speex_preprocess_state_init(int frame_size, int sampling_rate);
 
-/** Destroys a denoising state */
+/** Destroys a preprocessor state 
+ * @param st Preprocessor state to destroy
+*/
 void speex_preprocess_state_destroy(SpeexPreprocessState *st);
 
-/** Preprocess a frame */
+/** Preprocess a frame 
+ * @param st Preprocessor state
+ * @param x Audio sample vector (in and out). Must be same size as specified in speex_preprocess_state_init().
+ * @return Bool value for voice activity (1 for speech, 0 for noise/silence), ONLY if VAD turned on.
+*/
 int speex_preprocess_run(SpeexPreprocessState *st, spx_int16_t *x);
 
-/** Preprocess a frame (deprecated*/
+/** Preprocess a frame (deprecated, use speex_preprocess_run() instead)*/
 int speex_preprocess(SpeexPreprocessState *st, spx_int16_t *x, spx_int32_t *echo);
 
-/** Preprocess a frame */
-void speex_preprocess_estimate_update(SpeexPreprocessState *st, spx_int16_t *x, spx_int32_t *echo);
+/** Update preprocessor state, but do not compute the output
+ * @param st Preprocessor state
+ * @param x Audio sample vector (in only). Must be same size as specified in speex_preprocess_state_init().
+*/
+void speex_preprocess_estimate_update(SpeexPreprocessState *st, spx_int16_t *x);
 
-/** Used like the ioctl function to control the preprocessor parameters */
+/** Used like the ioctl function to control the preprocessor parameters 
+ * @param st Preprocessor state
+ * @param request ioctl-type request (one of the SPEEX_PREPROCESS_* macros)
+ * @param ptr Data exchanged to-from function
+ * @return 0 if no error, -1 if request in unknown
+*/
 int speex_preprocess_ctl(SpeexPreprocessState *st, int request, void *ptr);
 
 
@@ -107,20 +134,29 @@ int speex_preprocess_ctl(SpeexPreprocessState *st, int request, void *ptr);
 #define SPEEX_PREPROCESS_SET_PROB_CONTINUE 16
 #define SPEEX_PREPROCESS_GET_PROB_CONTINUE 17
 
+/** Set maximum attenuation of the noise in dB (negative number) */
 #define SPEEX_PREPROCESS_SET_NOISE_SUPPRESS 18
+/** Get maximum attenuation of the noise in dB (negative number) */
 #define SPEEX_PREPROCESS_GET_NOISE_SUPPRESS 19
 
+/** Set maximum attenuation of the residual echo in dB (negative number) */
 #define SPEEX_PREPROCESS_SET_ECHO_SUPPRESS 20
+/** Get maximum attenuation of the residual echo in dB (negative number) */
 #define SPEEX_PREPROCESS_GET_ECHO_SUPPRESS 21
 
+/** Set maximum attenuation of the residual echo in dB when near end is active (negative number) */
 #define SPEEX_PREPROCESS_SET_ECHO_SUPPRESS_ACTIVE 22
+/** Get maximum attenuation of the residual echo in dB when near end is active (negative number) */
 #define SPEEX_PREPROCESS_GET_ECHO_SUPPRESS_ACTIVE 23
 
+/** Set the corresponding echo canceller state so that residual echo suppression can be performed (NULL for no residual echo suppression) */
 #define SPEEX_PREPROCESS_SET_ECHO_STATE 24
+/** Get the corresponding echo canceller state */
 #define SPEEX_PREPROCESS_GET_ECHO_STATE 25
 
 #ifdef __cplusplus
 }
 #endif
 
+/** @}*/
 #endif
index 466ab05..b6674d9 100644 (file)
@@ -449,7 +449,7 @@ void speex_echo_state_destroy(SpeexEchoState *st)
    speex_free(st);
 }
 
-void speex_echo_capture(SpeexEchoState *st, const spx_int16_t *rec, spx_int16_t *out, spx_int32_t *Yout)
+void speex_echo_capture(SpeexEchoState *st, const spx_int16_t *rec, spx_int16_t *out)
 {
    int i;
    /*speex_warning_int("capture with fill level ", st->play_buf_pos/st->frame_size);*/
index e3a94b8..749066d 100644 (file)
@@ -989,7 +989,7 @@ int speex_preprocess_run(SpeexPreprocessState *st, spx_int16_t *x)
    }
 }
 
-void speex_preprocess_estimate_update(SpeexPreprocessState *st, spx_int16_t *x, spx_int32_t *echo)
+void speex_preprocess_estimate_update(SpeexPreprocessState *st, spx_int16_t *x)
 {
    int i;
    int N = st->ps_size;