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

# AGC

## AGC API Functions

group AGC API functions

  Functions

  void agc_init(agc_state_t *agc, agc_config_t *config)

    Initialise the AGC.

    This function initialises the AGC state with the provided configuration. It must be called at startup to initialise the AGC before processing any frames, and can be called at any time after that to reset the AGC instance, returning the internal AGC state to its defaults.

    Example with an unmodified profile

          agc_state_t agc;
          agc_init(&agc, &AGC_PROFILE_ASR);

    Example with modification to the profile

          agc_config_t conf = AGC_PROFILE_FIXED_GAIN;
          conf.gain = f32_to_float_s32(100);
          agc_state_t agc;
          agc_init(&agc, &conf);

    Parameters:

      - agc – [out] AGC state structure

      - config – [in] Initial configuration values

  agc_meta_data_t agc_meta_data_init()

    Initialise AGC meta data structure.

    Set the AGC meta data values to indicate no VNR, no AEC and no reference signal.

  void agc_process_frame(
    agc_state_t *agc,
    int32_t output[AGC_FRAME_ADVANCE],
    const int32_t input[AGC_FRAME_ADVANCE],
    agc_meta_data_t *meta_data,
  )

    Perform AGC processing on a frame of input data.

    This function updates the AGC’s internal state based on the input frame and meta-data, and returns an output containing the result of the AGC algorithm applied to the input.

    The `input` and `output` pointers can be equal to perform the processing in-place.

    Example

          int32_t input[AGC_FRAME_ADVANCE];
          int32_t output[AGC_FRAME_ADVANCE];
          agc_meta_data_t md = agc_meta_data_init();
          agc_process_frame(&agc, output, input, &md);

    Parameters:

      - agc – [inout] AGC state structure

      - output – [out] Array to return the resulting frame of data

      - input – [in] Array of frame data on which to perform the AGC

      - meta_data – [in] Meta-data structure with VNR/AEC data

## AGC Defines

Three pre-defined profiles are provided in agc_profiles.h to configure the AGC for different applications:

group Pre-defined AGC configuration profiles

  Defines

  AGC_PROFILE_ASR

    AGC profile tuned for Automatic Speech Recognition (ASR).

  AGC_PROFILE_FIXED_GAIN

    AGC profile tuned to apply a fixed gain.

  AGC_PROFILE_XCV_COMMS

    AGC profile tuned for human to human communications.

These profiles can be used to configure the AGC instance by passing them to the `agc_init()` function.

## AGC Data Structures and Enums

group AGC API structure definitions

  Defines

  AGC_FRAME_ADVANCE

    Length of the frame of data on which the AGC will operate.

  AGC_META_DATA_NO_VNR

    If the application has no VNR, `adapt_on_vnr` must be disabled in the configuration. This pre-processor definition can be assigned to the `vnr_flag` in `agc_meta_data_t` in that situation to make it clear in the code that there is no VNR.

  AGC_META_DATA_NO_AEC

    If the application has no AEC, `lc_enabled` must be disabled in the configuration. This pre-processor definition can be assigned to the `aec_ref_power` and `aec_corr_factor` in `agc_meta_data_t` in that situation to make it clear in the code that there is no AEC.

  AGC_META_DATA_NO_REF

    If the application has no reference signal, this pre-processor definition can be assigned to the `ref_active_flag` in `agc_meta_data_t` to make it clear in the code that there is no reference signal.

  struct agc_config_t
    #include <agc.h>

    AGC configuration structure.

    This structure contains configuration settings that can be changed to alter the behaviour of the AGC instance.

    Members with the “lc_” prefix are parameters for the Loss Control feature.

    Public Members

    int adapt

      Boolean to enable AGC adaption; if enabled, the gain to apply will adapt based on the peak of the input frame and the upper/lower threshold parameters.

    int adapt_on_vnr

      Boolean to enable adaption based on the VNR meta-data; if enabled, adaption will always be performed when voice activity is detected. This must be disabled if the application doesn’t have a VNR.

    float_s32_t vnr_threshold

      VNR threshold for voice activity detection. A higher value will only adapt the AGC on clean speech. A lower value will adapt the AGC on noisy speech, but may also adapt to more non-speech signals.

    int soft_clipping

      Boolean to enable soft-clipping of the output frame.

    float_s32_t gain

      The current gain to be applied, not including loss control. When `adapt` is false, this gain will be applied to every frame. When `adapt` is true, the initial value of this gain will be applied to the first frame and then it will be adapted on subsequent frames.

    float_s32_t max_gain

      The maximum gain allowed when adaption is enabled. This can be used to prevent the AGC amplifying very quiet signals.

    float_s32_t min_gain

      The minimum gain allowed when adaption is enabled.

    float_s32_t upper_threshold

      The target maximum peak level of the AGC output. If the AGC output goes above this level, the gain is reduced.

    float_s32_t lower_threshold

      The target minimum peak level of the AGC output. If the AGC output goes below this level, the gain is increased.

    float_s32_t gain_inc

      Factor by which to increase the gain during adaption.

    float_s32_t gain_dec

      Factor by which to decrease the gain during adaption.

    uint32_t startup_delay

      Number of frames to mute the output at startup.

    int lc_enabled

      Boolean to enable loss control. The loss control applies additional attenuation when there is no near end speech. This must be disabled if the application doesn’t have an AEC or VNR.

    int lc_n_frame_far

      Number of frames required to consider far-end audio active.

    int lc_n_frame_near

      Number of frames required to consider near-end audio active.

    float_s32_t lc_corr_threshold

      Threshold for far-end correlation above which to indicate far-end activity only.

    float_s32_t lc_bg_power_gamma

      Gamma coefficient for estimating the power of the far-end background noise.

    float_s32_t lc_gamma_inc

      Factor by which to increase the loss control gain when less than target value.

    float_s32_t lc_gamma_dec

      Factor by which to decrease the loss control gain when greater than target value.

    float_s32_t lc_far_delta

      Delta multiplier used when only far-end activity is detected.

    float_s32_t lc_near_delta

      Delta multiplier used when only near-end activity is detected. How many times louder the near-end signal must be than the background noise when there is no far-end playback. If the near end speech is not heard during silence, reduce this value. If too much non-speech background noise is heard, increase this value.

    float_s32_t lc_near_delta_far_active

      Delta multiplier used when both near-end and far-end activity is detected. How many times louder the near end signal must be above the residual far-end speech (after the AEC) to be detected during double talk. If the near end speech is not heard during double talk, reduce this value. If there is too much breakthrough of residual far-end echo when there is no near-end speech present, increase this value.

    float_s32_t lc_gain_max

      Loss control gain to apply when near-end activity only is detected.

    float_s32_t lc_gain_double_talk

      Loss control gain to apply when double-talk is detected. Reducing this value will reduce the level of the near-end speech during double-talk, but may help to reduce the level of residual far-end echo that is heard.

    float_s32_t lc_gain_silence

      Loss control gain to apply when silence is detected.

    float_s32_t lc_gain_min

      Loss control gain to apply when far-end activity only is detected.

    float_s32_t lc_vnr_low

      Low VNR threshold for background estimation.

    int lc_vnr_low_count_limit

      Frame count limit for low VNR detection.

  struct agc_state_t
    #include <agc.h>

    AGC state structure.

    This structure holds the current state of the AGC instance and members are updated each time that `agc_process_frame()` runs. Many of these members are exponentially-weighted moving averages (EWMA) which influence the adaption of the AGC gain or the loss control feature. The user should not directly modify any of these members, except the config.

    Public Members

    agc_config_t config

      The current configuration of the AGC. Any member of this configuration structure can be modified and that change will take effect on the next run of `agc_process_frame()`.

    float_s32_t x_slow

      EWMA of the frame peak, which is used to identify the overall trend of a rise or fall in the input signal.

    float_s32_t x_fast

      EWMA of the frame peak, which is used to identify a rise or fall in the peak of frame.

    float_s32_t x_peak

      EWMA of `x_fast`, which is used when adapting to the `agc_config_t::upper_threshold`.

    int lc_t_far

      Timer counting down until enough frames with far-end activity have been processed.

    int lc_t_near

      Timer counting down until enough frames with near-end activity have been processed.

    float_s32_t lc_near_power_est

      EWMA of estimates of the near-end power.

    float_s32_t lc_far_power_est

      EWMA of estimates of the far-end power.

    float_s32_t lc_near_bg_power_est

      EWMA of estimates of the power of near-end background noise.

    float_s32_t lc_gain

      Loss control gain applied on top of the AGC gain in `agc_config_t`.

    float_s32_t lc_far_bg_power_est

      EWMA of estimates of the power of far-end background noise.

    float_s32_t lc_corr_val

      EWMA of the far-end correlation for detecting double-talk.

    int lc_vnr_low_count

      Counter of how many frames the VNR has been low for.

    uint32_t frame_count

      Frame counter since initialisation, used for startup delay

  struct agc_meta_data_t
    #include <agc.h>

    AGC meta data structure.

    This structure holds meta-data about the current frame to be processed, and must be updated to reflect the current frame before calling `agc_process_frame()`.

    Public Members

    float_s32_t vnr_flag

      Estimated voice-to-noise ratio in the current frame.

    float_s32_t aec_ref_power

      The power of the most powerful reference channel.

    float_s32_t aec_corr_factor

      Correlation factor between the microphone input and the AEC’s estimated microphone signal.

    int32_t ref_active_flag

      Flag to indicate if the reference signal is currently active