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
- 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 and PJMEDIA_ECHO_WEBRTC.
-
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 and PJMEDIA_ECHO_WEBRTC.
-
enumerator 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.
-
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_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.
-
enumerator PJMEDIA_ECHO_DEFAULT¶
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.
-
PJMEDIA_ECHO_STAT_NOT_SPECIFIED¶