Prosody signal path processing: API: sm_path_echocancel

Prototype Definition

int sm_path_echocancel(struct sm_path_echocancel_parms *cancelp)

Parameters

*cancelp

a structure of the following type:

typedef struct sm_path_echocancel_parms {
	tSMPathId path;						/* in */
	tSM_INT enable;						/* in */
	tSMDatafeedId reference;				/* in */
	tSM_INT non_linear;					/* in */
	enum kSMPathEchoNonLinearMode {
		kSMPathEchoNonLinearModeMuting,
		kSMPathEchoNonLinearModeCNG,
	} mode;							/* in */
	tSM_INT use_agc;					/* in */
	tSM_INT fix_agc;					/* in */
	tSM_INT span;						/* in */
	tSM_INT delay;						/* in */
	enum kSMPathEchoToneAction {
		kSMPathEchoToneActionNone,
		kSMPathEchoTonetActionMuteTTY,
	} tone_action;						/* in */
} SM_PATH_ECHOCANCEL_PARMS;

Description

Configures echo cancellation on a signal path. The input is examined for an echo of the reference signal, and any echo found is suppressed.

Non-linear echo cancellation can operate in two modes. The default is non-linear echo cancellation with muting, which is suitable for large-scale conferencing and/or IVR applications, where it is important that the signal is completely muted whenever the caller is not speaking.

Non-linear echo cancellation with comfort noise generation (CNG) never mutes the signal. Instead it replaces any residual traces of echo with "comfort noise". This mode of operation is most appropriate to IP gateway applications where background noise is desirable to maintain the illusion of continuity.

If tone_action is set to mute TTY, the echo cancellation algorithm will expect to encounter TTY tones on its primary input and its reference. Its output will be muted whenever such tones are present on its reference and for a short time afterwards (thus muting echoes of tones). It will pass though TTY tones present on its primary input at other times. This behaviour should only be enabled if TTY tones are expected in the signal path. It would normally be used with non-linear mode disabled.

Requires the module echocan.

Fields

path

The signal path to be configured

enable

Enables (non-zero) or disables (zero) echo cancellation of the input signal.

reference

The datafeed which is the reference signal. Only used if enable is non-zero.

non_linear

Enables (non-zero) or disables (zero) non-linear processing. The exact behaviour of the non-linear processing module is controlled by mode . Negative values represent the lower limit in dBm0. Positive values cause the default value of -42dBm0 to be used. Only used if enable is non-zero.

mode

Selects the non-linear echo cancellation mode to be used. Only used if non_linear is non-zero. One of these values:

kSMPathEchoNonLinearModeMuting

Uses non-linear processing to suppress the signal whenever echo or background noise are dominant. This mode of operation is suitable for large-scale conferencing and/or IVR applications, where it is important that the signal is completely muted whenever the caller is not speaking.

kSMPathEchoNonLinearModeCNG

Uses non-linear processing to replace the signal with comfort noise whenever echo might otherwise be audible. This mode of operation is most appropriate to IP gateway applications where background noise is desirable to maintain the illusion of continuity.

use_agc

Enables (non-zero) or disables (zero) the use of automatic gain control on the input signal. Only used if enable is non-zero.

fix_agc

Enables (non-zero) or disables (zero) holding the gain fixed at its current value. This can be used after the AGC gain factor has adjusted itself to prevent further changes. Only used if enable is non-zero.

span

If non-zero, sets the span (in milliseconds) of the echo cancellation. A side effect of this is that the input conditioning may be re-initialised. Only used if enable is non-zero.

delay

If non-zero, sets delay (in milliseconds) before the reference signal is presented to echo cancellation reference input (allowing application to compensate for time it takes reference signal to reach the TDM circuit, so avoiding the effective span being diminished by this amount). Input conditioning is re-initialised. To set a zero delay, use the value -1. If zero, the delay is unchanged and input conditioning is not re-initialised. The default delay is zero milliseconds.

tone_action

One of these values:

kSMPathEchoToneActionNone

No special action on occurence of tones.

kSMPathEchoTonetActionMuteTTY

TTY tones are expected - when detected action taken to mute TTY echo but passthrough non-echo TTY.

Returns

0 if call completed successfully, otherwise a standard error.

This function is part of the Prosody signal path processing API.