IC¶

IC API Functions¶

group High Level API Functions

Functions

int32_t ic_init(ic_state_t *state)¶

Initialise IC and VNR data structures and set parameters according to ic_defines.h.

This is the first function that must called after creating an ic_state_t instance.

Parameters:

state – [inout] pointer to IC state structure

Returns:

Error status of the VNR inference engine initialisation that is done as part of ic_init. 0 if no error, one of TfLiteStatus error enum values in case of error.

void ic_process_frame( ic_state_t *state, int32_t y_data[IC_FRAME_ADVANCE], int32_t x_data[IC_FRAME_ADVANCE], int32_t output[IC_FRAME_ADVANCE], float_s32_t *input_vnr_pred, )¶

Filter one frame of audio data inside the IC, calculate VNR prediction, adapt the IC.

Runs ic_filter, ic_calc_vnr_pred and ic_adapt.

Parameters:

state – [inout] pointer to IC state structure
y_data – [inout] array reference of mic 0 input buffer. Modified during call
x_data – [in] array reference of mic 1 input buffer
output – [out] array reference containing IC processed output buffer
input_vnr_pred – [out] voice to noise estimate of the IC input

void ic_filter( ic_state_t *state, int32_t y_data[IC_FRAME_ADVANCE], int32_t x_data[IC_FRAME_ADVANCE], int32_t output[IC_FRAME_ADVANCE], )¶

Filter one frame of audio data inside the IC.

This should be called once per new frame of IC_FRAME_ADVANCE samples. The y_data array contains the microphone data that is to have the noise subtracted from it and x_data is the noise reference source which is internally delayed before being fed into the adaptive filter. Note that the y_data input array is internally delayed by the call to ic_filter() and so contains the delayed y_data afterwards. Typically it does not matter which mic channel is connected to x or y_data as long as the separation is appropriate. The performance of this filter has been optimised for a 71mm mic separation distance.

Parameters:

state – [inout] pointer to IC state structure
y_data – [inout] array reference of mic 0 input buffer. Modified during call
x_data – [in] array reference of mic 1 input buffer
output – [out] array reference containing IC processed output buffer

void ic_calc_vnr_pred(ic_state_t *state, float_s32_t *input_vnr_pred)¶

Calculate voice to noise ratio estimation for the input and output of the IC.

This function can be called after each call to ic_filter. It will calculate voice to noise ratio which can be used to give information to ic_adapt and to the AGC.

Parameters:

state – [inout] pointer to IC state structure
input_vnr_pred – [out] voice to noise estimate of the IC input

void ic_adapt(ic_state_t *state)¶

Adapts the IC filter according to previous frame’s statistics and VNR input.

This function should be called after each call to ic_filter. Filter and adapt functions are separated so that the external VNR can operate on each frame.

Parameters:

state – [inout] pointer to IC state structure

IC Defines¶

group IC #define constants

Defines

IC_INIT_MU¶: Initial MU value applied on startup. MU controls the adaption rate of the IC and is normally adjusted by the adaption rate controller during operation.

IC_INIT_EMA_ALPHA¶: Alpha used for calculating y_ema_energy, x_ema_energy and error_ema_energy.

IC_INIT_LEAKAGE_ALPHA¶: Alpha used for leaking away H_hat, allowing filter to slowly forget adaption. This value is adjusted by the adaption rate controller if instability is detected.

IC_FILTER_PHASES¶: The number of filter phases supported by the IC. Each filter phase represents 15ms of filter length. Hence a 10 phase filter will allow cancellation of noise sources with up to 150ms of echo tail length. There is a tradeoff between adaption speed and maximum cancellation of the filter; increasing the number of phases will increase the maximum cancellation at the cost of increased xCORE resource usage and slower adaption times.

IC_Y_CHANNEL_DELAY_SAMPS¶: This is the delay, in samples that one of the microphone signals is delayed in order for the filter to be effective. A larger number increases the delay through the filter but may improve cancellation. The group delay through the IC filter is 32 + this number of samples.

IC_INIT_SIGMA_XX_SHIFT¶: Down scaling factor for X energy calculation used for normalisation.

IC_INIT_GAMMA_LOG2¶: Up scaling factor for X energy calculation for used for LMS normalisation.

IC_INIT_DELTA¶: Delta value used in denominator to avoid large values when calculating inverse X energy.

IC_INIT_FAST_RATIO_THRESHOLD¶: Fast ratio threshold to detect instability.

IC_INIT_ENERGY_ALPHA¶: Alpha for EMA input/output energy calculation.

IC_INIT_HIGH_INPUT_VNR_HOLD_LEAKAGE_ALPHA¶: Leakage alpha used in case vnr detects high voice probability.

IC_INIT_INSTABILITY_RECOVERY_LEAKAGE_ALPHA¶: Leakage alpha used in the case where instability is detected. This allows the filter to stabilise without completely forgetting the adaption.

IC_INIT_ADAPT_COUNTER_LIMIT¶: Limits number of frames for which mu and leakage_alpha could be adapted.

IC_INIT_INPUT_VNR_THRESHOLD¶: VNR input threshold which decides whether to hold or adapt the filter.

IC_INIT_INPUT_VNR_THRESHOLD_HIGH¶: VNR high threshold to leak the filter is the speech level is high.

IC_INIT_INPUT_VNR_THRESHOLD_LOW¶: VNR low threshold to adapt faster when the speech level is low.

IC_INIT_VNR_PRED_ALPHA¶: Alpha for EMA VNR prediction calculation.

IC_INIT_INPUT_VNR_PRED¶: Initial value for the input VNR prediction.

IC_Y_CHANNELS¶: Number of Y channels input. This is fixed at 1 for the IC. The Y channel is delayed and used to generate the estimated noise signal to subtract from X. In practical terms it does not matter which microphone is X and which is Y. NOT USER MODIFIABLE.

IC_X_CHANNELS¶: Number of X channels input. This is fixed at 1 for the IC. The X channel is the microphone from which the estimated noise signal is subtracted. In practical terms it does not matter which microphone is X and which is Y. NOT USER MODIFIABLE.

IC_FRAME_LENGTH¶: Time domain samples block length used internally in the IC’s block LMS algorithm. NOT USER MODIFIABLE.

IC_FRAME_ADVANCE¶: IC new samples frame size This is the number of samples of new data that the IC works on every frame. 240 samples at 16kHz is 15msec. Every frame, the IC takes in 15msec of mic data and generates 15msec of interference cancelled output. NOT USER MODIFIABLE.

IC_FD_FRAME_LENGTH¶: Number of bins of spectrum data computed when doing a DFT of a IC_FRAME_LENGTH length time domain vector. The IC_FD_FRAME_LENGTH spectrum values represent the bins from DC to Nyquist. NOT USER MODIFIABLE.

FFT_PADDING¶: Extra 2 samples you need to allocate in time domain so that the full spectrum (DC to nyquist) can be stored after the in-place FFT. NOT USER MODIFIABLE.

IC Data Structures and Enums¶

group IC Data Structures

Enums

enum adaption_config_e¶

Values:

enumerator IC_ADAPTION_AUTO¶

enumerator IC_ADAPTION_FORCE_ON¶

enumerator IC_ADAPTION_FORCE_OFF¶

enum control_flag_e¶

Values:

enumerator HOLD¶

enumerator ADAPT¶

enumerator ADAPT_SLOW¶

enumerator UNSTABLE¶

enumerator FORCE_ADAPT¶

enumerator FORCE_HOLD¶

struct ic_config_params_t¶

#include <ic_state.h>

IC configuration structure.

This structure contains configuration settings that can be changed to alter the behaviour of the IC instance. An instance of this structure is is automatically included as part of the IC state.

It controls the behaviour of the main filter and normalisation thereof. The initial values for these configuration parameters are defined in ic_defines.h and are initialised by ic_init().

Public Members

uint8_t bypass¶: Boolean to control bypassing of filter stage and adaption stage. When set the delayed y audio samples are passed unprocessed to the output. It is recommended to perform an initialisation of the instance after bypass is set as the room transfer function may have changed during that time.

int32_t gamma_log2¶: Up scaling factor for X energy calculation used for normalisation.

uint32_t sigma_xx_shift¶: Down scaling factor for X energy for used for normalisation.

q2_30 ema_alpha_q30¶: Alpha used for calculating error_ema_energy in adapt.

float_s32_t delta¶: Delta value used in denominator to avoid large values when calculating inverse X energy.

struct ic_adaption_controller_config_t¶

#include <ic_state.h>

IC adaption controller configuration structure.

This structure contains configuration settings that can be changed to alter the behaviour of the adaption controller. This includes processing of the raw VNR probability input and optional stability controller logic. It is automatically included as part of the IC state and initialised by ic_init().

The initial values for these configuration parameters are defined in ic_defines.h.

Public Members

q2_30 energy_alpha_q30¶: Alpha for EMA input/output energy calculation.

float_s32_t fast_ratio_threshold¶: Fast ratio threshold to detect instability.

float_s32_t high_input_vnr_hold_leakage_alpha¶: Setting of H_hat leakage which gets set if vnr detects high voice probability.

float_s32_t instability_recovery_leakage_alpha¶: Setting of H_hat leakage which gets set if fast ratio exceeds a threshold.

float_s32_t input_vnr_threshold¶: VNR input threshold which decides whether to hold or adapt the filter.

float_s32_t input_vnr_threshold_high¶: VNR high threshold to leak the filter is the speech level is high.

float_s32_t input_vnr_threshold_low¶: VNR low threshold to adapt faster when the speech level is low.

uint32_t adapt_counter_limit¶: Limits number of frames for which mu and leakage_alpha could be adapted.

uint8_t enable_adaption¶: Boolean which controls whether the IC adapts when ic_adapt() is called.

adaption_config_e adaption_config¶: Enum which controls the way mu and leakage_alpha are being adjusted.

struct ic_adaption_controller_state_t¶

#include <ic_state.h>

IC adaption controller state structure.

This structure contains state used for the instance of the adaption controller logic. It is automatically included as part of the IC state and initialised by ic_init().

Public Members

float_s32_t input_energy¶: EMWA of input frame energy.

float_s32_t output_energy¶: EMWA of output frame energy.

float_s32_t fast_ratio¶: Ratio between output and input EMWA energies.

uint32_t adapt_counter¶: Adaption counter which counts number of frames has been adapted.

control_flag_e control_flag¶: Flag that represents the state of the filter.

ic_adaption_controller_config_t adaption_controller_config¶: Configuration parameters for the adaption controller.

struct ic_state_t¶

#include <ic_state.h>

IC state structure.

This is the main state structure for an instance of the Interference Canceller. Before use it must be initialised using the ic_init() function. It contains everything needed for the IC instance including configuration and internal state of both the filter, adaption logic and adaption controller.

Public Members

bfp_s32_t y_bfp[IC_Y_CHANNELS]¶: BFP array pointing to the time domain y input signal.

bfp_complex_s32_t Y_bfp[IC_Y_CHANNELS]¶: BFP array pointing to the frequency domain Y input signal.

int32_t y[IC_Y_CHANNELS][IC_FRAME_LENGTH + FFT_PADDING]¶: Storage for y and Y mantissas. Note FFT is done in-place so the y storage is reused for Y.

bfp_s32_t x_bfp[IC_X_CHANNELS]¶: BFP array pointing to the time domain x input signal.

bfp_complex_s32_t X_bfp[IC_X_CHANNELS]¶: BFP array pointing to the frequency domain X input signal.

int32_t x[IC_X_CHANNELS][IC_FRAME_LENGTH + FFT_PADDING]¶: Storage for x and X mantissas. Note FFT is done in-place so the x storage is reused for X.

bfp_s32_t prev_y_bfp[IC_Y_CHANNELS]¶: BFP array pointing to previous y samples which are used for framing.

int32_t y_prev_samples[IC_Y_CHANNELS][IC_FRAME_LENGTH - IC_FRAME_ADVANCE]¶: Storage for previous y mantissas.

bfp_s32_t prev_x_bfp[IC_X_CHANNELS]¶: BFP array pointing to previous x samples which are used for framing.

int32_t x_prev_samples[IC_X_CHANNELS][IC_FRAME_LENGTH - IC_FRAME_ADVANCE]¶: Storage for previous x mantissas.

bfp_complex_s32_t Y_hat_bfp[IC_Y_CHANNELS]¶: BFP array pointing to the estimated frequency domain Y signal.

complex_s32_t Y_hat[IC_Y_CHANNELS][IC_FD_FRAME_LENGTH]¶: Storage for Y_hat mantissas.

bfp_complex_s32_t Error_bfp[IC_Y_CHANNELS]¶: BFP array pointing to the frequency domain Error output.

bfp_s32_t error_bfp[IC_Y_CHANNELS]¶: BFP array pointing to the time domain Error output.

complex_s32_t Error[IC_Y_CHANNELS][IC_FD_FRAME_LENGTH]¶: Storage for Error and error mantissas. Note IFFT is done in-place so the Error storage is reused for error.

bfp_complex_s32_t H_hat_bfp[IC_Y_CHANNELS][IC_X_CHANNELS * IC_FILTER_PHASES]¶: BFP array pointing to the frequency domain estimate of transfer function.

complex_s32_t H_hat[IC_Y_CHANNELS][IC_FILTER_PHASES * IC_X_CHANNELS][IC_FD_FRAME_LENGTH]¶: Storage for H_hat mantissas.

bfp_complex_s32_t X_fifo_bfp[IC_X_CHANNELS][IC_FILTER_PHASES]¶: BFP array pointing to the frequency domain X input history used for calculating normalisation.

bfp_complex_s32_t X_fifo_1d_bfp[IC_X_CHANNELS * IC_FILTER_PHASES]¶: 1D alias of the frequency domain X input history used for calculating normalisation.

complex_s32_t X_fifo[IC_X_CHANNELS][IC_FILTER_PHASES][IC_FD_FRAME_LENGTH]¶: Storage for X_fifo mantissas.

bfp_complex_s32_t T_bfp[IC_X_CHANNELS]¶: BFP array pointing to the frequency domain T used for adapting the filter coefficients (H). Note there is no associated storage because we re-use the x input array as a memory optimisation.

bfp_s32_t inv_X_energy_bfp[IC_X_CHANNELS]¶: BFP array pointing to the inverse X energies used for normalisation.

int32_t inv_X_energy[IC_X_CHANNELS][IC_FD_FRAME_LENGTH]¶: Storage for inv_X_energy mantissas.

bfp_s32_t X_energy_bfp[IC_X_CHANNELS]¶: BFP array pointing to the X energies.

int32_t X_energy[IC_X_CHANNELS][IC_FD_FRAME_LENGTH]¶: Storage for X_energy mantissas.

unsigned X_energy_recalc_bin¶: Index state used for calculating energy across all X bins.

bfp_s32_t overlap_bfp[IC_Y_CHANNELS]¶: BFP array pointing to the overlap array used for windowing and overlap operations.

int32_t overlap[IC_Y_CHANNELS][IC_FRAME_OVERLAP]¶: Storage for overlap mantissas.

int32_t y_input_delay[IC_Y_CHANNELS][IC_Y_CHANNEL_DELAY_SAMPS]¶: FIFO for delaying y channel (w.r.t x) to enable adaptive filter to be effective.

uint32_t y_delay_idx[IC_Y_CHANNELS]¶: Index state used for keeping track of y delay FIFO.

float_s32_t mu[IC_Y_CHANNELS][IC_X_CHANNELS]¶: Mu value used for controlling adaption rate.

float_s32_t leakage_alpha¶: Alpha used for leaking away H_hat, allowing filter to slowly forget adaption.

float_s32_t max_X_energy[IC_X_CHANNELS]¶: Used to keep track of peak X energy.

bfp_s32_t sigma_XX_bfp[IC_X_CHANNELS]¶: BFP array pointing to the EMA filtered X input energy.

int32_t sigma_XX[IC_X_CHANNELS][IC_FD_FRAME_LENGTH]¶: Storage for sigma_XX mantissas.

float_s32_t sum_X_energy[IC_X_CHANNELS]¶: X energy sum used for maintaining the X FIFO.

ic_config_params_t config_params¶: Configuration parameters for the IC.

ic_adaption_controller_state_t ic_adaption_controller_state¶: State and configuration parameters for the IC adaption controller.

vnr_pred_state_t vnr_pred_state¶: Input and Output VNR Prediction related state