Accoustic Echo Cancellation API
[Media Ports Framework]

Echo Cancellation API. More...

Typedefs
typedef typedefPJ_BEGIN_DECL struct pjmedia_echo_state	pjmedia_echo_state
Enumerations
enum	pjmedia_echo_flag {   PJMEDIA_ECHO_DEFAULT = 0,   PJMEDIA_ECHO_SPEEX = 1,   PJMEDIA_ECHO_SIMPLE = 2,   PJMEDIA_ECHO_ALGO_MASK = 15,   PJMEDIA_ECHO_NO_LOCK = 16,   PJMEDIA_ECHO_USE_SIMPLE_FIFO = 32 }
Functions
pj_status_t	pjmedia_echo_create (pj_pool_t *pool, unsigned clock_rate, unsigned samples_per_frame, unsigned tail_ms, unsigned latency_ms, unsigned options, pjmedia_echo_state **p_echo)
pj_status_t	pjmedia_echo_create2 (pj_pool_t *pool, unsigned clock_rate, unsigned channel_count, unsigned samples_per_frame, unsigned tail_ms, unsigned latency_ms, unsigned options, pjmedia_echo_state **p_echo)
pj_status_t	pjmedia_echo_destroy (pjmedia_echo_state *echo)
pj_status_t	pjmedia_echo_reset (pjmedia_echo_state *echo)
pj_status_t	pjmedia_echo_playback (pjmedia_echo_state *echo, pj_int16_t *play_frm)
pj_status_t	pjmedia_echo_capture (pjmedia_echo_state *echo, pj_int16_t *rec_frm, unsigned options)
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)

---

Detailed Description

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.

---

Typedef Documentation

typedef typedefPJ_BEGIN_DECL struct pjmedia_echo_state pjmedia_echo_state

Opaque type for PJMEDIA Echo Canceller state.

---

Enumeration Type Documentation

enum pjmedia_echo_flag

Echo cancellation options.

Enumerator:

PJMEDIA_ECHO_DEFAULT	Use any available backend echo canceller algorithm. This is the default settings. This setting is mutually exclusive with PJMEDIA_ECHO_SIMPLE and PJMEDIA_ECHO_SPEEX.
PJMEDIA_ECHO_SPEEX	Force to use Speex AEC as the backend echo canceller algorithm. This setting is mutually exclusive with PJMEDIA_ECHO_SIMPLE.
PJMEDIA_ECHO_SIMPLE	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. This setting is mutually exclusive with PJMEDIA_ECHO_SPEEX.
PJMEDIA_ECHO_ALGO_MASK	For internal use.
PJMEDIA_ECHO_NO_LOCK	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_USE_SIMPLE_FIFO	If PJMEDIA_ECHO_USE_SIMPLE_FIFO flag is specified, the delay buffer created for the echo canceller will use simple FIFO mechanism, i.e. without using WSOLA to expand and shrink audio samples.

---

Function Documentation

pj_status_t pjmedia_echo_create	(	pj_pool_t *	pool,
		unsigned	clock_rate,
		unsigned	samples_per_frame,
		unsigned	tail_ms,
		unsigned	latency_ms,
		unsigned	options,
		pjmedia_echo_state **	p_echo
	)

Create the echo canceller.

Parameters:

	pool	Pool to allocate memory.
	clock_rate	Media clock rate/sampling rate.
	samples_per_frame	Number of samples per frame.
	tail_ms	Tail length, miliseconds.
	latency_ms	Total lacency introduced by playback and recording device. Set to zero if the latency is not known.
	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.
	p_echo	Pointer to receive the Echo Canceller state.

Returns:

PJ_SUCCESS on success, or the appropriate status.

pj_status_t pjmedia_echo_create2	(	pj_pool_t *	pool,
		unsigned	clock_rate,
		unsigned	channel_count,
		unsigned	samples_per_frame,
		unsigned	tail_ms,
		unsigned	latency_ms,
		unsigned	options,
		pjmedia_echo_state **	p_echo
	)

Create multi-channel the echo canceller.

Parameters:

	pool	Pool to allocate memory.
	clock_rate	Media clock rate/sampling rate.
	channel_count	Number of channels.
	samples_per_frame	Number of samples per frame.
	tail_ms	Tail length, miliseconds.
	latency_ms	Total lacency introduced by playback and recording device. Set to zero if the latency is not known.
	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.
	p_echo	Pointer to receive the Echo Canceller state.

Returns:

PJ_SUCCESS on success, or the appropriate status.

pj_status_t pjmedia_echo_destroy

(

pjmedia_echo_state *

echo

)

Destroy the Echo Canceller.

Parameters:

echo

The Echo Canceller.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_echo_reset

(

pjmedia_echo_state *

echo

)

Reset the echo canceller.

Parameters:

echo

The Echo Canceller.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_echo_playback	(	pjmedia_echo_state *	echo,
		pj_int16_t *	play_frm
	)

Let the Echo Canceller know 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().

Parameters:

	echo	The Echo Canceller.
	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.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_echo_capture	(	pjmedia_echo_state *	echo,
		pj_int16_t *	rec_frm,
		unsigned	options
	)

Let the Echo Canceller know 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.

Parameters:

	echo	The Echo Canceller.
	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.
	options	Echo cancellation options, reserved for future use. Put zero for now.

Returns:

PJ_SUCCESS on success.

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
	)

Perform echo cancellation.

Parameters:

	echo	The Echo Canceller.
	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.
	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.
	options	Echo cancellation options, reserved for future use. Put zero for now.
	reserved	Reserved for future use, put NULL for now.

Returns:

PJ_SUCCESS on success.