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.

Typedefs

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:

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.

enumerator PJMEDIA_ECHO_SPEEX

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

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. This setting is mutually exclusive with PJMEDIA_ECHO_SPEEX.

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.

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)

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.