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.