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

# ADEC

## ADEC API Functions

group ADEC API Functions

  Functions

  void adec_init(adec_state_t *state, adec_config_t *config)

    Initialise ADEC data structures.

    This function initialises ADEC state for a given configuration. It must be called at startup to initialise the ADEC data structures before processing any frames, and can be called at any time after that to reset the ADEC instance, returning the internal ADEC state to its defaults.

    Example with ADEC configured for delay estimation only at startup

          adec_state_t adec_state;
          adec_config_t adec_conf;
          adec_conf.bypass = 1; // Bypass automatic DE correction
          adec_conf.force_de_cycle_trigger = 1; // Force a delay correction cycle, so that delay correction happens once after initialisation
          adec_init(&adec_state, &adec_conf);
          // Application needs to ensure that adec_state->adec_config.force_de_cycle_trigger is set to 0 after ADEC has requested a transition to delay estimation mode once in order to ensure that delay is corrected only at startup.

    Example with ADEC configured for automatic delay estimation and correction

          adec_state_t adec_state;
          adec_conf.bypass = 0;
          adec_conf.force_de_cycle_trigger = 0;
          adec_init(&adec_state, &adec_conf);

    Parameters:

      - state – [out] Pointer to ADEC state structure

      - config – [in] Pointer to ADEC configuration structure.

  void adec_process_frame(
    adec_state_t *state,
    adec_output_t *adec_output,
    const adec_input_t *adec_in,
  )

    Perform ADEC processing on an input frame of data.

    This function takes information about the latest AEC processed frame and the latest measured delay estimate as input, and decides if a delay correction between input microphone and reference signals is required. If a correction is needed, it outputs a new requested input delay, optionally accompanied with a request for AEC restart in a different configuration. It updates the internal ADEC state structure to reflect the current state of the ADEC process.

    Parameters:

      - state – [inout] ADEC internal state structure

      - adec_output – [out] ADEC output structure

      - adec_in – [in] ADEC input structure

  void adec_estimate_delay(
    de_output_t *de_output,
    const bfp_complex_s32_t *H_hat,
    unsigned num_phases,
  )

    Estimate microphone delay.

    This function measures the microphone signal delay wrt the reference signal. It does so by looking for the phase with the peak energy among all AEC filter phases and uses the peak energy phase index as the estimate of the microphone delay. Along with the measured delay, it also outputs information about the peak phase energy that can then be used to gauge the AEC filter convergence and the reliability of the measured delay.

    Parameters:

      - de_state – [out] Delay estimator output structure

      - H_hat – [in] bfp_complex_s32_t array storing the AEC filter spectrum

      - Number – [in] of phases in the AEC filter

## ADEC Defines

group ADEC #define constants

  Defines

  ADEC_PEAK_TO_AVERAGE_HISTORY_DEPTH

    Number of frames far we look back to smooth the peak to average filter power ratio history.

  ADEC_PEAK_LINREG_HISTORY_SIZE

    Number of frames of peak power history we look at while computing AEC goodness metric. NOT USER MODIFIABLE.

  ADEC_DE_DELAY_MS

    Initial delay of microphone in the DE mode in milliseconds. This allows measuring up to `ADEC_DE_DELAY_MS` ms of delay in cases when the mic is earlier than the reference.

  ADEC_DE_DELAY_SAMPS

    Same as `ADEC_DE_DELAY_MS` but in samples.

## ADEC Data Structures and Enums

group ADEC Data Structure and Enum Definitions

  Enums

  enum adec_mode_t

    Values:

    enumerator ADEC_NORMAL_AEC_MODE

      ADEC processing mode where it monitors AEC performance and requests small delay correction.

    enumerator ADEC_DELAY_ESTIMATOR_MODE

      ADEC processing mode for bulk delay correction in which it measures for a new delay offset.

  struct adec_config_t
    #include <adec_state.h>

    ADEC configuration structure.

    This is used to provide configuration when initialising ADEC at startup. A copy of this structure is present in the ADEC state structure and available to be modified by the application for run time control of ADEC configuration.

    Public Members

    int32_t bypass

      Bypass ADEC decision making process. When set to 1, ADEC evaluates the current input frame metrics but doesn’t make any delay correction or aec reset and reconfiguration requests

    int32_t force_de_cycle_trigger

      Force trigger a delay estimation cycle. When set to 1, ADEC bypasses the ADEC monitoring process and transitions to delay estimation mode for measuring delay offset. Initialising ADEC with this flag set to 1 can be used to get an initial delay estimate at boot.

  struct de_output_t
    #include <adec_state.h>

    Delay estimator output structure.

    Public Members

    int32_t measured_delay_samples

      Estimated microphone delay in time domain samples.

    int32_t peak_power_phase_index

      Phase index of peak energy AEC filter phase.

    float_s32_t peak_phase_power

      Maximum per phase energy across all AEC filter phases.

    float_s32_t sum_phase_powers

      Sum of filter energy across all filter phases.

    float_s32_t peak_to_average_ratio

      Ratio of peak filter phase energy to average filter phase energy. Used to evaluate how well the filter has converged.

    float_s32_t phase_power[AEC_LIB_MAX_PHASES]

      Phase energy of all AEC filter phases.

  struct adec_output_t
    #include <adec_state.h>

    ADEC output structure.

    Public Members

    int32_t delay_change_request_flag

      Flag indicating if ADEC is requesting an input delay correction

    int32_t requested_mic_delay_samples

      Mic delay in samples requested by ADEC. Relevant when delay_change_request_flag is 1. Note that this value is a signed integer. A positive `requested_mic_delay_samples` requires the microphone to be delayed so the application needs to delay the input mic signal by `requested_mic_delay_samples` samples. A negative `requested_mic_delay_samples` means ADEC is requesting the input mic signal to be moved earlier in time. This, the application should do my delaying the input reference signal by `abs(requested_mic_delay_samples)` samples.

    int32_t reset_aec_flag

      flag indicating ADEC’s request for a reset of part of the AEC state to get AEC filter to start adapting from a 0 filter. ADEC requests this when a small delay correction needs to be applied that doesn’t require a full reset of the AEC.

    int32_t delay_estimator_enabled_flag

      Flag indicating if AEC needs to be run configured in delay estimation mode.

    int32_t requested_delay_samples_debug

      Requested delay samples without clamping to +- MAX_DELAY_SAMPLES. Used only for debugging.

  struct aec_to_adec_t
    #include <adec_state.h>

    Input structure containing current frame’s information from AEC.

    Public Members

    float_s32_t y_ema_energy_ch0

      EWMA energy of AEC input mic signal channel 0

    float_s32_t error_ema_energy_ch0

      EWMA energy of AEC filter error output signal channel 0

    int32_t shadow_flag_ch0

      shadow_flag value for the current frame computed within the AEC

  struct adec_input_t
    #include <adec_state.h>

    ADEC input structure.

    Public Members

    de_output_t from_de

      ADEC input from the delay estimator

    aec_to_adec_t from_aec

      ADEC input from AEC

    int32_t far_end_active_flag

      Flag indicating if there is activity on reference input channels.

  struct adec_state_t
    #include <adec_state.h>

    ADEC state structure.

    This structure holds the current state of the ADEC instance and members are updated each time that `adec_process_frame()` runs. Many of these members are statistics from tracking the AEC performance. The user should not directly modify any of these members, except the config.

    Public Members

    float_s32_t max_peak_to_average_ratio_since_reset

      Maximum peak to average AEC filter phase energy ratio seen since a delay correction was last requested.

    float_s32_t peak_to_average_ratio_history[ADEC_PEAK_TO_AVERAGE_HISTORY_DEPTH + 1]

      Last ADEC_PEAK_TO_AVERAGE_HISTORY_DEPTH frames peak_to_average_ratio of phase energies.

    float_s32_t peak_power_history[ADEC_PEAK_LINREG_HISTORY_SIZE]

      Last ADEC_PEAK_LINREG_HISTORY_SIZE frames peak phase power.

    float_s32_t aec_peak_to_average_good_aec_threshold

      Threshold was considering peak to average ratio as good.

    q8_24 agm_q24

      AEC goodness metric indicating a measure of how well AEC filter is performing.

    q8_24 erle_bad_bits_q24

      log2 of threshold below which AEC output’s measured ERLE is considered bad

    q8_24 erle_good_bits_q24

      log2 of threshold above which AEC output’s measured ERLE is considered good

    q8_24 peak_phase_energy_trend_gain_q24

      Multiplier used for scaling agm’s sensitivity to peak phase energy trend.

    q8_24 erle_bad_gain_q24

      Multiplier determining how steeply we reduce aec’s goodness when measured erle falls below the bad erle threshold.

    adec_mode_t mode

      ADEC’s mode of operation. Can be operating in normal AEC or delay estimation mode.

    int32_t gated_milliseconds_since_mode_change

      milliseconds elapsed since a delay change was last requested. Used to ensure that delay corrections are not requested too early without allowing enough time for aec filter to converge.

    int32_t last_measured_delay

      Last measured delay.

    int32_t peak_power_history_idx

      index storing the head of the peak_power_history circular buffer

    int32_t peak_power_history_valid

      Flag indicating whether the peak_power_history buffer has been filled at least once.

    int32_t sf_copy_flag

      Flag indicating if shadow to main filter copy has happened at least once in the AEC.

    int32_t convergence_counter

      Counter indicating number of frames the AEC shadow filter has been attempting to converge.

    int32_t shadow_flag_counter

      Counter indicating number of frame the AEC shadow filter has been better than the main filter.

    adec_config_t adec_config

      ADEC configuration parameters structure. Can be modified by application at run-time to reconfigure ADEC.