Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
Toggle table of contents sidebar

# 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