Change AEC into generic echo canceller framework with either AEC or simple echo suppressor backend can be selected during runtime.

git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@653 74dad513-b988-da41-8d7b-12977e46ad98

6 files changed, 222 insertions, 173 deletions

diff --git a/pjmedia/include/pjmedia.h b/pjmedia/include/pjmedia.h
index 049e36c8..233dc889 100644
--- a/pjmedia/include/pjmedia.h
+++ b/pjmedia/include/pjmedia.h
@@ -25,14 +25,14 @@
  */
 
 #include <pjmedia/types.h>
-#include <pjmedia/aec.h>
-#include <pjmedia/aec_port.h>
 #include <pjmedia/bidirectional.h>
 #include <pjmedia/clock.h>
 #include <pjmedia/codec.h>
 #include <pjmedia/conference.h>
-#include <pjmedia/endpoint.h>
+#include <pjmedia/echo.h>
+#include <pjmedia/echo_port.h>
 #include <pjmedia/errno.h>
+#include <pjmedia/endpoint.h>
 #include <pjmedia/g711.h>
 #include <pjmedia/jbuf.h>
 #include <pjmedia/master_port.h>
diff --git a/pjmedia/include/pjmedia/aec.h b/pjmedia/include/pjmedia/aec.h
deleted file mode 100644
index 84ed7e0f..00000000
--- a/pjmedia/include/pjmedia/aec.h
+++ /dev/null
@@ -1,153 +0,0 @@
-/* $Id$ */
-/* 
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
- */
-#ifndef __PJMEDIA_AEC_H__
-#define __PJMEDIA_AEC_H__
-
-
-/**
- * @file aec.h
- * @brief AEC (Accoustic Echo Cancellation) API.
- */
-#include <pjmedia/types.h>
-
-
-
-/**
- * @defgroup PJMEDIA_AEC AEC AEC (Accoustic Echo Cancellation)
- * @ingroup PJMEDIA_PORT
- * @brief AEC (Accoustic Echo Cancellation) API.
- * @{
- */
-
-
-PJ_BEGIN_DECL
-
-
-/**
- * Opaque type for PJMEDIA AEC.
- */
-typedef struct pjmedia_aec pjmedia_aec;
-
-
-/**
- * Create the AEC. 
- *
- * @param pool		    Pool to allocate memory.
- * @param clock_rate	    Media clock rate/sampling rate.
- * @param samples_per_frame Number of samples per frame.
- * @param tail_ms	    Tail length, miliseconds.
- *
- * @return		    PJ_SUCCESS on success.
- */
-PJ_DECL(pj_status_t) pjmedia_aec_create( pj_pool_t *pool,
-					 unsigned clock_rate,
-					 unsigned samples_per_frame,
-					 unsigned tail_ms,
-					 unsigned options,
-					 pjmedia_aec **p_aec );
-
-
-/**
- * Destroy the AEC. 
- *
- * @param aec		The AEC.
- * @return		PJ_SUCCESS on success.
- */
-PJ_DECL(pj_status_t) pjmedia_aec_destroy(pjmedia_aec *aec );
-
-
-/**
- * Let the AEC knows that a frame has been played to the speaker.
- * The AEC will keep the frame in its internal buffer, to be used
- * when cancelling the echo with #pjmedia_aec_capture().
- *
- * @param aec		The AEC.
- * @param ts		Optional timestamp to let the AEC knows the
- *			position of the frame relative to capture
- *			position. If NULL, the AEC assumes that
- *			application will supply the AEC with continuously
- *			increasing timestamp.
- * @param play_frm	Sample buffer containing frame to be played
- *			(or has been played) to the playback device.
- *			The frame must contain exactly samples_per_frame 
- *			number of samples.
- *
- * @return		PJ_SUCCESS on success.
- */
-PJ_DECL(pj_status_t) pjmedia_aec_playback( pjmedia_aec *aec,
-					   pj_int16_t *play_frm );
-
-
-/**
- * Let the AEC knows that a frame has been captured from the microphone.
- * The AEC will cancel the echo from the captured signal, using the
- * internal buffer (supplied by #pjmedia_aec_playback()) as the
- * FES (Far End Speech) reference.
- *
- * @param aec		The AEC.
- * @param rec_frm	On input, it contains the input signal (captured 
- *			from microphone) which echo is to be removed.
- *			Upon returning this function, this buffer contain
- *			the processed signal with the echo removed.
- *			The frame must contain exactly samples_per_frame 
- *			number of samples.
- * @param options	Echo cancellation options, reserved for future use.
- *			Put zero for now.
- *
- * @return		PJ_SUCCESS on success.
- */
-PJ_DECL(pj_status_t) pjmedia_aec_capture( pjmedia_aec *aec,
-					  pj_int16_t *rec_frm,
-					  unsigned options );
-
-
-/**
- * Perform echo cancellation.
- *
- * @param aec		The AEC.
- * @param rec_frm	On input, it contains the input signal (captured 
- *			from microphone) which echo is to be removed.
- *			Upon returning this function, this buffer contain
- *			the processed signal with the echo removed.
- * @param play_frm	Sample buffer containing frame to be played
- *			(or has been played) to the playback device.
- *			The frame must contain exactly samples_per_frame 
- *			number of samples.
- * @param options	Echo cancellation options, reserved for future use.
- *			Put zero for now.
- * @param reserved	Reserved for future use, put NULL for now.
- *
- * @return		PJ_SUCCESS on success.
- */
-PJ_DECL(pj_status_t) pjmedia_aec_cancel_echo( pjmedia_aec *aec,
-					      pj_int16_t *rec_frm,
-					      const pj_int16_t *play_frm,
-					      unsigned options,
-					      void *reserved );
-
-
-PJ_END_DECL
-
-/**
- * @}
- */
-
-
-#endif	/* __PJMEDIA_AEC_H__ */
-
diff --git a/pjmedia/include/pjmedia/config.h b/pjmedia/include/pjmedia/config.h
index 9e53f562..871177ae 100644
--- a/pjmedia/include/pjmedia/config.h
+++ b/pjmedia/include/pjmedia/config.h
@@ -170,6 +170,15 @@
 
 
 /**
+ * Speex Accoustic Echo Cancellation (AEC).
+ * By default is enabled.
+ */
+#ifndef PJMEDIA_HAS_SPEEX_AEC
+#   define PJMEDIA_HAS_SPEEX_AEC		1
+#endif
+
+
+/**
  * Support for sending and decoding RTCP port in SDP (RFC 3605).
  * Default is yes.
  */
diff --git a/pjmedia/include/pjmedia/echo.h b/pjmedia/include/pjmedia/echo.h
new file mode 100644
index 00000000..205ef4ff
--- /dev/null
+++ b/pjmedia/include/pjmedia/echo.h
@@ -0,0 +1,186 @@
+/* $Id$ */
+/* 
+ * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
+ */
+#ifndef __PJMEDIA_ECHO_H__
+#define __PJMEDIA_ECHO_H__
+
+
+/**
+ * @file echo.h
+ * @brief Echo Cancellation  API.
+ */
+#include <pjmedia/types.h>
+
+
+
+/**
+ * @defgroup PJMEDIA_Echo_Cancel Canceller Echo Cancellation
+ * @ingroup PJMEDIA_PORT
+ * @brief Echo Cancellation API.
+ * @{
+ *
+ * This section describes API to perform echo cancellation to audio signal.
+ * There may be multiple echo canceller implementation in PJMEDIA, ranging
+ * from simple echo suppressor to a full Accoustic Echo Canceller/AEC. By 
+ * using this API, application should be able to use which EC backend to
+ * use base on the requirement and capability of the platform.
+ */
+
+
+PJ_BEGIN_DECL
+
+
+/**
+ * Opaque type for PJMEDIA Echo Canceller state.
+ */
+typedef struct pjmedia_echo_state pjmedia_echo_state;
+
+
+/**
+ * Echo cancellation options.
+ */
+typedef enum pjmedia_echo_flag
+{
+    /**
+     * If PJMEDIA_ECHO_SIMPLE flag is specified during echo canceller
+     * creation, then a simple echo suppressor will be used instead of
+     * an accoustic echo cancellation.
+     */
+    PJMEDIA_ECHO_SIMPLE	= 1,
+
+    /**
+     * If PJMEDIA_ECHO_NO_LOCK flag is specified, no mutex will be created
+     * for the echo canceller, but application will guarantee that echo
+     * canceller will not be called by different threads at the same time.
+     */
+    PJMEDIA_ECHO_NO_LOCK = 2
+
+} pjmedia_echo_flag;
+
+
+
+
+/**
+ * Create the echo canceller. 
+ *
+ * @param pool		    Pool to allocate memory.
+ * @param clock_rate	    Media clock rate/sampling rate.
+ * @param samples_per_frame Number of samples per frame.
+ * @param tail_ms	    Tail length, miliseconds.
+ * @param options	    Options. If PJMEDIA_ECHO_SIMPLE is specified,
+ *			    then a simple echo suppressor implementation 
+ *			    will be used instead of an accoustic echo 
+ *			    cancellation.
+ *			    See #pjmedia_echo_flag for other options.
+ * @param p_echo	    Pointer to receive the Echo Canceller state.
+ *
+ * @return		    PJ_SUCCESS on success, or the appropriate status.
+ */
+PJ_DECL(pj_status_t) pjmedia_echo_create(pj_pool_t *pool,
+					 unsigned clock_rate,
+					 unsigned samples_per_frame,
+					 unsigned tail_ms,
+					 unsigned options,
+					 pjmedia_echo_state **p_echo );
+
+
+/**
+ * Destroy the Echo Canceller. 
+ *
+ * @param echo		The Echo Canceller.
+ *
+ * @return		PJ_SUCCESS on success.
+ */
+PJ_DECL(pj_status_t) pjmedia_echo_destroy(pjmedia_echo_state *echo );
+
+
+/**
+ * Let the Echo Canceller knows that a frame has been played to the speaker.
+ * The Echo Canceller will keep the frame in its internal buffer, to be used
+ * when cancelling the echo with #pjmedia_echo_capture().
+ *
+ * @param echo		The Echo Canceller.
+ * @param play_frm	Sample buffer containing frame to be played
+ *			(or has been played) to the playback device.
+ *			The frame must contain exactly samples_per_frame 
+ *			number of samples.
+ *
+ * @return		PJ_SUCCESS on success.
+ */
+PJ_DECL(pj_status_t) pjmedia_echo_playback(pjmedia_echo_state *echo,
+					   pj_int16_t *play_frm );
+
+
+/**
+ * Let the Echo Canceller knows that a frame has been captured from 
+ * the microphone.
+ * The Echo Canceller will cancel the echo from the captured signal, 
+ * using the internal buffer (supplied by #pjmedia_echo_playback()) 
+ * as the FES (Far End Speech) reference.
+ *
+ * @param echo		The Echo Canceller.
+ * @param rec_frm	On input, it contains the input signal (captured 
+ *			from microphone) which echo is to be removed.
+ *			Upon returning this function, this buffer contain
+ *			the processed signal with the echo removed.
+ *			The frame must contain exactly samples_per_frame 
+ *			number of samples.
+ * @param options	Echo cancellation options, reserved for future use.
+ *			Put zero for now.
+ *
+ * @return		PJ_SUCCESS on success.
+ */
+PJ_DECL(pj_status_t) pjmedia_echo_capture(pjmedia_echo_state *echo,
+					  pj_int16_t *rec_frm,
+					  unsigned options );
+
+
+/**
+ * Perform echo cancellation.
+ *
+ * @param echo		The Echo Canceller.
+ * @param rec_frm	On input, it contains the input signal (captured 
+ *			from microphone) which echo is to be removed.
+ *			Upon returning this function, this buffer contain
+ *			the processed signal with the echo removed.
+ * @param play_frm	Sample buffer containing frame to be played
+ *			(or has been played) to the playback device.
+ *			The frame must contain exactly samples_per_frame 
+ *			number of samples.
+ * @param options	Echo cancellation options, reserved for future use.
+ *			Put zero for now.
+ * @param reserved	Reserved for future use, put NULL for now.
+ *
+ * @return		PJ_SUCCESS on success.
+ */
+PJ_DECL(pj_status_t) pjmedia_echo_cancel( pjmedia_echo_state *echo,
+					  pj_int16_t *rec_frm,
+					  const pj_int16_t *play_frm,
+					  unsigned options,
+					  void *reserved );
+
+
+PJ_END_DECL
+
+/**
+ * @}
+ */
+
+
+#endif	/* __PJMEDIA_ECHO_H__ */
+
diff --git a/pjmedia/include/pjmedia/aec_port.h b/pjmedia/include/pjmedia/echo_port.h
index 2968c915..97abdc1f 100644
--- a/pjmedia/include/pjmedia/aec_port.h
+++ b/pjmedia/include/pjmedia/echo_port.h
@@ -28,9 +28,11 @@
 
 
 /**
- * @defgroup PJMEDIA_AEC_PORT AEC Port
+ * @defgroup PJMEDIA_ECHO_PORT Echo Cancellation Port
  * @ingroup PJMEDIA_PORT
- * @brief AEC (Accoustic Echo Cancellation) media port.
+ * @brief Echo Cancellation Port
+ *
+ * Echo canceller media port, using @ref PJMEDIA_Echo_Cancel backend.
  * @{
  */
 
@@ -39,18 +41,20 @@ PJ_BEGIN_DECL
 
 
 /**
- * Create AEC port. 
+ * Create echo canceller port. 
  *
  * @param pool		Pool to allocate memory.
  * @param dn_port	Downstream port.
  * @param tail_ms	Tail length in miliseconds.
+ * @param options	Options, as in #pjmedia_echo_create().
  * @param p_port	Pointer to receive the port instance.
  *
  * @return		PJ_SUCCESS on success.
  */
-PJ_DECL(pj_status_t) pjmedia_aec_port_create( pj_pool_t *pool,
+PJ_DECL(pj_status_t) pjmedia_echo_port_create(pj_pool_t *pool,
 					      pjmedia_port *dn_port,
 					      unsigned tail_ms,
+					      unsigned options,
 					      pjmedia_port **p_port );
 
 
diff --git a/pjmedia/include/pjmedia/sound_port.h b/pjmedia/include/pjmedia/sound_port.h
index c144275d..7653c35c 100644
--- a/pjmedia/include/pjmedia/sound_port.h
+++ b/pjmedia/include/pjmedia/sound_port.h
@@ -183,36 +183,39 @@ PJ_DECL(pjmedia_snd_stream*) pjmedia_snd_port_get_snd_stream(
 
 
 /**
- * Enable accoustic echo cancellation (AEC) to the specified sound. 
- * The AEC can only be enabled for sound streams with full-duplex direction.
+ * Configure the echo cancellation tail length. By default, echo canceller
+ * is enabled in the sound device with the default tail length. After the
+ * sound port is created, application can query the current echo canceller
+ * tail length by calling #pjmedia_snd_port_get_ec_tail.
  *
- * And note, you should only change the AEC settings when the sound port
- * is not connected to any downstream ports.
+ * Note that you should only change the EC settings when the sound port
+ * is not connected to any downstream ports, otherwise race condition may
+ * occur.
  *
  * @param snd_port	    The sound device port.
- * @param pool		    Pool to re-create the AEC if necessary.
+ * @param pool		    Pool to re-create the echo canceller if necessary.
  * @param tail_ms	    Maximum echo tail length to be supported, in
- *			    miliseconds. If zero is specified, the AEC would
+ *			    miliseconds. If zero is specified, the EC would
  *			    be disabled.
  *
  * @return		    PJ_SUCCESS on success.
  */
-PJ_DECL(pj_status_t) pjmedia_snd_port_set_aec(pjmedia_snd_port *snd_port,
-					      pj_pool_t *pool,
-					      unsigned tail_ms);
+PJ_DECL(pj_status_t) pjmedia_snd_port_set_ec_tail(pjmedia_snd_port *snd_port,
+						  pj_pool_t *pool,
+						  unsigned tail_ms);
 
 
 /**
- * Get current AEC tail length, in miliseconds. The tail length will be zero
- * if AEC is not enabled.
+ * Get current echo canceller tail length, in miliseconds. The tail length 
+ * will be zero if EC is not enabled.
  *
  * @param snd_port	    The sound device port.
  * @param p_length	    Pointer to receive the tail length.
  *
  * @return		    PJ_SUCCESS on success.
  */
-PJ_DECL(pj_status_t) pjmedia_snd_port_get_aec_tail(pjmedia_snd_port *snd_port,
-						   unsigned *p_length);
+PJ_DECL(pj_status_t) pjmedia_snd_port_get_ec_tail(pjmedia_snd_port *snd_port,
+						  unsigned *p_length);