Prosody speech processing: API: sm_condition_input

Prototype Definition

int sm_condition_input(struct sm_condition_input_parms *condp)

Parameters

a structure of the following type:

typedef struct sm_condition_input_parms {
	tSMChannelId channel;					/* in */
	tSMChannelId reference;					/* in */
	enum kSMInputCondRef {
		kSMInputCondRefNone,
		kSMInputCondRefUseInput,
		kSMInputCondRefUseOutput,
	} reference_type;					/* in */
	enum kSMInputCond {
		kSMInputCondNone,
		kSMInputCondEchoCancelation,
	} conditioning_type;					/* in */
	tSM_INT conditioning_param;				/* in */
	tSMChannelId alt_data_dest;				/* in */
	enum kSMInputCondAltDest {
		kSMInputCondAltDestNone,
		kSMInputCondAltDestInput,
		kSMInputCondAltDestOutput,
	} alt_dest_type;						/* in */
	int ectest_type;					/* in */
	float ectest_gain;					/* in */
	int ectest_delay;					/* in */
	unsigned ectest_flen;					/* in */
	float *ectest_filt;					/* in */
} SM_CONDITION_INPUT_PARMS;

Description

Applies or disables conditioning to the signal input to channel channel with respect to reference signal on channel reference. The input signal to be conditioned is called the primary. The reference may either be the input to a channel or the output from a channel. In particular, it can be the output from channel (but not its input). Note that Prosody switching functions (such as sm_switch_channel_input() or sm_channel_datafeed_connect()) must not be used on a reference while it is in use.

If input signal conditioning is enabled, the conditioned version of the input is generated and is directed to one of several places.

If alt_dest_type is kSMInputCondAltDestNone then when other speech processing functions such as conferencing or recording are performed on channel, the conditioned version of the input signal will be used.
If alt_dest_type is kSMInputCondAltDestInput then when such speech processing functions are performed on alt_data_dest, the conditioned version of the input signal will be used. (If sm_condition_input() is used on such a channel, the result is undefined).
If alt_dest_type is kSMInputCondAltDestOutput then the conditioned signal appears as the output from the channel alt_data_dest, which may be the same channel as channel.

Note that Prosody switching functions (such as sm_switch_channel_output() or sm_channel_datafeed_connect()) must not be used on the destination while echo cancellation is being performed.

All channels specified by channel, alt_data_dest, and reference will need to be processed by the same module. This can be ensured through the use of sm_channel_alloc_placed()

The two commonest configurations are:

Cancelling the echo from a prompt being played: In this situation you use one channel, playing the prompt on it, using its output as the reference (so reference = channel and reference_type = kSMInputCondRefUseOutput), and recording its input.
Stand alone echo cancellation: Here you want to send the conditioned signal to an external destination, rather than recording it. You need at least two channels because you need two inputs - one for the primary and one for the reference - and one output, while a single Prosody channel can have at most one input and one output. One way to arrange this is to have channel, whose input is the primary, be specified as the output (i.e. alt_data_dest = channel and alt_dest_type = kSMInputCondAltDestOutput), with a different channel being used for reference.

Only on Prosody S: Not supported by Prosody S.

Fields

channel

The channel on whose input conditioning is to be performed.

reference

The reference channel, if any, which is to be used for conditioning.

reference_type

What sort of reference to use. One of these values:

kSMInputCondRefNone: No reference signal.
kSMInputCondRefUseInput: Use reference input signal.
kSMInputCondRefUseOutput: Use reference output signal.

conditioning_type

The type of conditioning to perform. One of these values:

kSMInputCondNone: Disable input conditioning. This also disables any redirection of a signal such as may have been set up using alt_data_dest.
kSMInputCondEchoCancelation: Remove echo from the input with respect to the specified reference signal. Requires the modules echocan and passthru to have been downloaded.

conditioning_param

Unused.

alt_data_dest

A channel to receive the resulting conditioned signal, if any form of conditioning is enabled.

alt_dest_type

What kind of alternative destination to use. One of these values:

kSMInputCondAltDestNone: Conditioned signal not redirected - conditioned signal replaces signal input to channel.
kSMInputCondAltDestInput: Conditioned signal replaces signal input to alt_data_dest.
kSMInputCondAltDestOutput: Conditioned signal replaces signal being output on alt_data_dest.

ectest_type

For Aculab use only: selects an echo cancellation test mode. If non-zero, creates simulated echo. This is not part of the official API and may be changed arbitrarily.

ectest_gain

For Aculab use only: the amount of signal to mix in as simulated echo. Only used when ectest_type is 1.

ectest_delay

For Aculab use only: the delay (in samples) for the simulated echo. Only used when ectest_type is 1.

ectest_flen

For Aculab use only: the length of the echo generation filter. Only used when ectest_type is 2.

ectest_filt

For Aculab use only: the echo generation filter. Only used when ectest_type is 2.

Returns

0 if call completed successfully, otherwise a standard error such as:

ERR_SM_DEVERR - device error
ERR_SM_BAD_PARAMETER - illegal parameter value

This function is part of the Prosody speech processing API.