BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJMEDIA Reference

Accoustic Echo Cancellation API

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_WEBRTC = 3,
  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_AGGRESSIVENESS_DEFAULT = 0,
  PJMEDIA_ECHO_AGGRESSIVENESS_CONSERVATIVE = 0x100,
  PJMEDIA_ECHO_AGGRESSIVENESS_MODERATE = 0x200,
  PJMEDIA_ECHO_AGGRESSIVENESS_AGGRESSIVE = 0x300,
  PJMEDIA_ECHO_AGGRESSIVENESS_MASK = 0xF00
}
 

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

◆ pjmedia_echo_state

typedef typedefPJ_BEGIN_DECL struct pjmedia_echo_state pjmedia_echo_state

Opaque type for PJMEDIA Echo Canceller state.

Enumeration Type Documentation

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

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

PJMEDIA_ECHO_WEBRTC 

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 

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_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_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
poolPool to allocate memory.
clock_rateMedia clock rate/sampling rate.
samples_per_frameNumber of samples per frame.
tail_msTail length, miliseconds.
latency_msTotal lacency introduced by playback and recording device. Set to zero if the latency is not known.
optionsOptions. 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_echoPointer 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
poolPool to allocate memory.
clock_rateMedia clock rate/sampling rate.
channel_countNumber of channels.
samples_per_frameNumber of samples per frame.
tail_msTail length, miliseconds.
latency_msTotal lacency introduced by playback and recording device. Set to zero if the latency is not known.
optionsOptions. 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_echoPointer 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
echoThe 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
echoThe Echo Canceller.
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
echoThe Echo Canceller.
play_frmSample 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
echoThe Echo Canceller.
rec_frmOn 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.
optionsEcho 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
echoThe Echo Canceller.
rec_frmOn 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_frmSample 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.
optionsEcho cancellation options, reserved for future use. Put zero for now.
reservedReserved for future use, put NULL for now.
Returns
PJ_SUCCESS on success.

 


PJMEDIA small footprint Open Source media stack
Copyright (C) 2006-2008 Teluu Inc.