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 typedefPJ_BEGIN_DECL struct pjmedia_echo_state pjmedia_echo_state

Opaque type for PJMEDIA Echo Canceller state.

Enums

enum pjmedia_echo_flag

Echo cancellation options.

Values:

PJMEDIA_ECHO_DEFAULT = 0

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 = 1

Force to use Speex AEC as the backend echo canceller algorithm. This setting is mutually exclusive with PJMEDIA_ECHO_SIMPLE and PJMEDIA_ECHO_WEBRTC.

PJMEDIA_ECHO_SIMPLE = 2

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 and PJMEDIA_ECHO_WEBRTC.

PJMEDIA_ECHO_WEBRTC = 3

Force to use WebRTC AEC as the backend echo canceller algorithm. This setting is mutually exclusive with PJMEDIA_ECHO_SIMPLE and PJMEDIA_ECHO_SPEEX.

PJMEDIA_ECHO_ALGO_MASK = 15

For internal use.

PJMEDIA_ECHO_NO_LOCK = 16

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 = 32

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 = 64

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

PJMEDIA_ECHO_USE_NOISE_SUPPRESSOR = 128

If PJMEDIA_ECHO_USE_NOISE_SUPPRESSOR flag is specified, the echo canceller will also apply noise suppressor method to reduce noise.

PJMEDIA_ECHO_AGGRESSIVENESS_DEFAULT = 0

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

PJMEDIA_ECHO_AGGRESSIVENESS_CONSERVATIVE = 0x100

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

PJMEDIA_ECHO_AGGRESSIVENESS_MODERATE = 0x200

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

PJMEDIA_ECHO_AGGRESSIVENESS_AGGRESSIVE = 0x300

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

PJMEDIA_ECHO_AGGRESSIVENESS_MASK = 0xF00

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.

Return

PJ_SUCCESS on success, or the appropriate status.

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.

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.

Return

PJ_SUCCESS on success, or the appropriate status.

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.

pj_status_t pjmedia_echo_destroy(pjmedia_echo_state *echo)

Destroy the Echo Canceller.

Return

PJ_SUCCESS on success.

Parameters
  • echo: The Echo Canceller.

pj_status_t pjmedia_echo_reset(pjmedia_echo_state *echo)

Reset the echo canceller.

Return

PJ_SUCCESS on success.

Parameters
  • echo: The Echo Canceller.

pj_status_t pjmedia_echo_get_stat(pjmedia_echo_state *echo, pjmedia_echo_stat *p_stat)

Get the echo canceller statistics.

Return

PJ_SUCCESS on success.

Parameters
  • echo: The Echo Canceller.

  • p_stat: Pointer to receive the stat.

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().

Return

PJ_SUCCESS on success.

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.

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.

Return

PJ_SUCCESS on success.

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.

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.

Return

PJ_SUCCESS on success.

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.

struct pjmedia_echo_stat
#include <echo.h>

Echo cancellation statistics.