Group PJMEDIA_Echo_Cancel

group PJMEDIA_Echo_Cancel

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.

Defines

PJMEDIA_ECHO_STAT_NOT_SPECIFIED

Statistic not specified.

Typedefs

typedef struct pjmedia_echo_state pjmedia_echo_state

Opaque type for PJMEDIA Echo Canceller state.

Enums

enum pjmedia_echo_flag

Echo cancellation options.

Values:

enumerator PJMEDIA_ECHO_DEFAULT

Use any available backend echo canceller algorithm. This is the default settings. You can only choose one backend.

enumerator PJMEDIA_ECHO_SPEEX

Force to use Speex AEC as the backend echo canceller algorithm. You can only choose one backend.

enumerator 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.

enumerator PJMEDIA_ECHO_WEBRTC

Force to use WebRTC AEC as the backend echo canceller algorithm. You can only choose one backend.

enumerator PJMEDIA_ECHO_WEBRTC_AEC3

Force to use WebRTC AEC3 as the backend echo canceller algorithm. You can only choose one backend.

enumerator PJMEDIA_ECHO_ALGO_MASK

For internal use.

enumerator 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.

enumerator 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.

enumerator PJMEDIA_ECHO_USE_SW_ECHO

If PJMEDIA_ECHO_USE_SW_ECHO flag is specified, software echo canceller will be used instead of device EC.

enumerator 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.

enumerator PJMEDIA_ECHO_USE_GAIN_CONTROLLER

If PJMEDIA_ECHO_USE_GAIN_CONTROLLER flag is specified, the echo canceller will also apply automatic gain control.

enumerator PJMEDIA_ECHO_AGGRESSIVENESS_DEFAULT

Use default aggressiveness setting for the echo canceller algorithm. This setting is mutually exclusive with the other aggressiveness settings.

enumerator PJMEDIA_ECHO_AGGRESSIVENESS_CONSERVATIVE

Use conservative aggressiveness setting for the echo canceller algorithm. This setting is mutually exclusive with the other aggressiveness settings.

enumerator PJMEDIA_ECHO_AGGRESSIVENESS_MODERATE

Use moderate aggressiveness setting for the echo canceller algorithm. This setting is mutually exclusive with the other aggressiveness settings.

enumerator PJMEDIA_ECHO_AGGRESSIVENESS_AGGRESSIVE

Use aggressive aggressiveness setting for the echo canceller algorithm. This setting is mutually exclusive with the other aggressiveness settings.

enumerator PJMEDIA_ECHO_AGGRESSIVENESS_MASK

For internal use.

Functions

void pjmedia_echo_stat_default(pjmedia_echo_stat *stat)

Initialize Echo cancellation stat.

Parameters:

stat – The statistic to be initialized.

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_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.

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.

struct pjmedia_echo_stat
#include <echo.h>

Echo cancellation statistics.

Public Members

const char *name

The name of the EC backend. NULL if not specified.

int delay

Echo delay value (in ms). PJMEDIA_ECHO_STAT_NOT_SPECIFIED if unavailable.

double return_loss

Echo return loss. PJMEDIA_ECHO_STAT_NOT_SPECIFIED if unavailable.

double return_loss_enh

Echo return loss enhancement. PJMEDIA_ECHO_STAT_NOT_SPECIFIED if unavailable.

int std

Echo delay standard deviation (in ms). PJMEDIA_ECHO_STAT_NOT_SPECIFIED if unavailable.

float frac_delay

Fraction of poor delay. Value between 0 to 1. The closer to 1, the poorer the EC quality. PJMEDIA_ECHO_STAT_NOT_SPECIFIED if unavailable.

unsigned learning

Learning still in progress? PJ_TRUE if yes, false if done. PJMEDIA_ECHO_STAT_NOT_SPECIFIED if unavailable.

unsigned duration

Learning duration (in ms). PJMEDIA_ECHO_STAT_NOT_SPECIFIED if unavailable.

unsigned tail

Detected echo tail length (in ms). PJMEDIA_ECHO_STAT_NOT_SPECIFIED if unavailable.

int min_factor

Minimum scaling factor (in ms). PJMEDIA_ECHO_STAT_NOT_SPECIFIED if unavailable.

int avg_factor

Average scaling factor (in ms). PJMEDIA_ECHO_STAT_NOT_SPECIFIED if unavailable.

pj_str_t stat_info

Text describing the statistic.

char buf_[128]

Internal buffer.