Accoustic Echo Cancellation API

Echo Cancellation API. More...

Data Structures
struct	pjmedia_echo_stat

Macros
#define	PJMEDIA_ECHO_STAT_NOT_SPECIFIED   999999

Typedefs
typedef 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_WEBRTC = 3 ,   PJMEDIA_ECHO_WEBRTC_AEC3 = 4 ,   PJMEDIA_ECHO_ALGO_MASK = 15 ,   PJMEDIA_ECHO_NO_LOCK = 16 ,   PJMEDIA_ECHO_USE_SIMPLE_FIFO = 32 ,   PJMEDIA_ECHO_USE_SW_ECHO = 64 ,   PJMEDIA_ECHO_USE_NOISE_SUPPRESSOR = 128 ,   PJMEDIA_ECHO_USE_GAIN_CONTROLLER = 256 ,   PJMEDIA_ECHO_AGGRESSIVENESS_DEFAULT = 0 ,   PJMEDIA_ECHO_AGGRESSIVENESS_CONSERVATIVE = 0x1000 ,   PJMEDIA_ECHO_AGGRESSIVENESS_MODERATE = 0x2000 ,   PJMEDIA_ECHO_AGGRESSIVENESS_AGGRESSIVE = 0x3000 ,   PJMEDIA_ECHO_AGGRESSIVENESS_MASK = 0xF000 }

Functions
void	pjmedia_echo_stat_default (pjmedia_echo_stat *stat)
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_get_stat (pjmedia_echo_state *echo, pjmedia_echo_stat *p_stat)
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.

Macro Definition Documentation

PJMEDIA_ECHO_STAT_NOT_SPECIFIED

#define PJMEDIA_ECHO_STAT_NOT_SPECIFIED   999999

Statistic not specified.

Typedef Documentation

pjmedia_echo_state

typedef struct pjmedia_echo_state pjmedia_echo_state

Opaque type for PJMEDIA Echo Canceller state.

Enumeration Type Documentation

pjmedia_echo_flag

enum pjmedia_echo_flag

Echo cancellation options.

Enumerator
PJMEDIA_ECHO_DEFAULT	Use any available backend echo canceller algorithm. This is the default settings. You can only choose one backend.
PJMEDIA_ECHO_SPEEX	Force to use Speex AEC as the backend echo canceller algorithm. You can only choose one backend.
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. You can only choose one backend.
PJMEDIA_ECHO_WEBRTC	Force to use WebRTC AEC as the backend echo canceller algorithm. You can only choose one backend.
PJMEDIA_ECHO_WEBRTC_AEC3	Force to use WebRTC AEC3 as the backend echo canceller algorithm. You can only choose one backend.
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.
PJMEDIA_ECHO_USE_SW_ECHO	If PJMEDIA_ECHO_USE_SW_ECHO flag is specified, software echo canceller will be used instead of device EC.
PJMEDIA_ECHO_USE_NOISE_SUPPRESSOR	If PJMEDIA_ECHO_USE_NOISE_SUPPRESSOR flag is specified, the echo canceller will also apply noise suppressor method to reduce noise.
PJMEDIA_ECHO_USE_GAIN_CONTROLLER	If PJMEDIA_ECHO_USE_GAIN_CONTROLLER flag is specified, the echo canceller will also apply automatic gain control.
PJMEDIA_ECHO_AGGRESSIVENESS_DEFAULT	Use default aggressiveness setting for the echo canceller algorithm. This setting is mutually exclusive with the other aggressiveness settings.
PJMEDIA_ECHO_AGGRESSIVENESS_CONSERVATIVE	Use conservative aggressiveness setting for the echo canceller algorithm. This setting is mutually exclusive with the other aggressiveness settings.
PJMEDIA_ECHO_AGGRESSIVENESS_MODERATE	Use moderate aggressiveness setting for the echo canceller algorithm. This setting is mutually exclusive with the other aggressiveness settings.
PJMEDIA_ECHO_AGGRESSIVENESS_AGGRESSIVE	Use aggressive aggressiveness setting for the echo canceller algorithm. This setting is mutually exclusive with the other aggressiveness settings.
PJMEDIA_ECHO_AGGRESSIVENESS_MASK	For internal use.

Function Documentation

pjmedia_echo_stat_default()

void pjmedia_echo_stat_default

(

pjmedia_echo_stat *

stat

)

Initialize Echo cancellation stat.

Parameters

stat	The statistic to be initialized.

pjmedia_echo_create()

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.

pjmedia_echo_create2()

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.

pjmedia_echo_destroy()

pj_status_t pjmedia_echo_destroy

(

pjmedia_echo_state *

echo

)

Destroy the Echo Canceller.

Parameters

echo	The Echo Canceller.

Returns

PJ_SUCCESS on success.

pjmedia_echo_reset()

pj_status_t pjmedia_echo_reset

(

pjmedia_echo_state *

echo

)

Reset the echo canceller.

Parameters

echo	The Echo Canceller.

Returns

PJ_SUCCESS on success.

pjmedia_echo_get_stat()

pj_status_t pjmedia_echo_get_stat	(	pjmedia_echo_state *	echo,
		pjmedia_echo_stat *	p_stat
	)

Get the echo canceller statistics.

Parameters

echo	The Echo Canceller.
p_stat	Pointer to receive the stat.

Returns

PJ_SUCCESS on success.

pjmedia_echo_playback()

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.

pjmedia_echo_capture()

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.

pjmedia_echo_cancel()

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.

References PJ_END_DECL.