Installation & Setup

The main component, aec_speexdsp, is an open-source SpeexDSP-based echo canceller with adaptive filters covering up to ~1 s of echo path. Its transport requires ESP-IDF TDM support, and its microphone buffers require PSRAM. ESP32-P4 is the tested target; ESP32-S3 has the required TDM and FPU hardware but still needs board-specific validation. The repository also includes an optional voice-assistant engine for compatible full-duplex integrations.

Using the Waveshare 7B? The fastest path is to use the complete audio-test and voice-assistant examples. Run the audio test first, then move to the voice assistant after the complete capture, reference, and playback path is verified.

You do not need to manually download this repository. Reference it from external_components:

Installation

external_components:
  - source:
      type: git
      url: https://github.com/matt123p/esphome-aec
      ref: v1.01
      path: src/esphome
    components: [aec_speexdsp]

If you use the ES7210, its current ESPHome component does not expose TDM mode. Until that support is merged, load the implementation from ESPHome pull request 18954 separately:

external_components:
  - source:
      type: git
      url: https://github.com/matt123p/esphome
      ref: feature/es7210-aec-fix
      path: esphome/components
    components: [es7210]

Then:

  1. Configure ESPHome for a TDM-capable target with a hardware FPU (ESP32-S3 or ESP32-P4) using framework: type: esp-idf, and enable PSRAM.
  2. Compile the DSP with performance optimization — add both keys to the esp32: framework sdkconfig_options (they form a Kconfig choice, so the size default must be explicitly cleared):
    sdkconfig_options:
      CONFIG_COMPILER_OPTIMIZATION_SIZE: "n"
      CONFIG_COMPILER_OPTIMIZATION_PERF: "y"
    
  3. Configure the ADC and DAC/codecs for 16-bit, 16 kHz TDM. Codec-specific components are not included with aec_speexdsp.
  4. Determine the board’s MCLK, BCLK, LRCLK, DIN, and DOUT pins.
  5. Determine which four RX slots contain microphone and analog-reference data, and which TX slots the DAC consumes.
  6. Add the hub and its microphone and speaker children.
  7. Start with the known-good settings below, then map and tune the reference.

Known-good aec_speexdsp starting configuration

Known-good audio starting configuration for the Waveshare 7B using the analog hardware reference:

esp32:
  board: esp32-p4
  variant: ESP32P4
  engineering_sample: true
  flash_size: 32MB
  cpu_frequency: 360MHz
  framework:
    type: esp-idf
    advanced:
      loop_task_stack_size: 16384
      enable_idf_experimental_features: true
    sdkconfig_options:
      # Compile for speed, not size: the default (-Os) makes the
      # floating-point DSP loops several times slower. Both options are
      # needed - they form a Kconfig choice and the size default must be
      # explicitly cleared.
      CONFIG_COMPILER_OPTIMIZATION_SIZE: "n"
      CONFIG_COMPILER_OPTIMIZATION_PERF: "y"
      # Size the ESP-DSP twiddle tables for the largest frame this component
      # allows (frame_size 1024 -> 2048-point window).
      CONFIG_DSP_MAX_FFT_SIZE_2048: "y"

psram:
  mode: hex
  speed: 200MHz
  ignore_not_found: false

esp_ldo:
  - channel: 3
    voltage: 2.5V

external_components:
  - source:
      type: git
      url: https://github.com/matt123p/esphome-aec
      ref: v1.01
      path: src/esphome
    components: [aec_speexdsp]
  - source:
      type: git
      url: https://github.com/matt123p/esphome
      ref: feature/es7210-aec-fix
      path: esphome/components
    components: [es7210]

i2c:
  - id: audio_i2c
    sda: GPIO7
    scl: GPIO8
    frequency: 400kHz

audio_adc:
  - platform: es7210
    id: mic_adc
    i2c_id: audio_i2c
    address: 0x40
    bits_per_sample: 16bit
    sample_rate: 16000
    mic_gain: 33db
    tdm: true

audio_dac:
  - platform: es8311
    id: speaker_dac
    i2c_id: audio_i2c
    address: 0x18
    bits_per_sample: 16bit
    sample_rate: 16000
    use_mclk: true

aec_speexdsp:
  id: voice_audio
  audio_adc: mic_adc
  mclk_pin: GPIO13
  bclk_pin: GPIO12
  lrclk_pin: GPIO10
  din_pin: GPIO11
  dout_pin: GPIO9
  i2s_port: 0
  tdm_slots: 4
  microphone_slots: [0, 2]
  reference_source: analog_slot
  reference_slot: 1
  tx_slots: [0, 1]
  frame_size: 256
  # The component default is 2048; this full workload uses 1024 for headroom.
  filter_length: 1024
  noise_suppression: true
  noise_suppression_level_db: 10
  echo_suppress_db: 25
  agc:
    enabled: true
  vad: true
  playback_gain_db: -12
  resampler: true

microphone:
  - platform: aec_speexdsp
    id: cleaned_microphone
    aec_speexdsp_id: voice_audio

speaker:
  - platform: aec_speexdsp
    id: full_duplex_speaker
    aec_speexdsp_id: voice_audio

For an ESP32-S3, adapt the target, pins, PSRAM, power and clock settings to the actual board; the P4-specific settings above are not portable unchanged. AEC is very sensitive to timing alignment between the reference and the microphones. It will only work effectively with a hardware reference captured in sync with the microphone channels. Choose a board with a hardware loopback path.

filter_length is a plain sample count of echo tail (16 samples = 1 ms at 16 kHz). The component default is 2048 samples (~128 ms), while the complete Waveshare examples use 1024 (~64 ms) to preserve CPU and internal-RAM headroom. Values up to 16384 (~1 s) are accepted. Longer filters can cover more echo but cost CPU and memory — see Configuration Reference and the performance notes.

Do not configure another component to own the same I2S peripheral or pins. The audio_adc object only initializes the codec; the hub creates and owns the paired ESP-IDF TDM RX/TX channels. The speaker child does not take an audio_dac option; configure the board’s top-level audio_dac: separately.

For a staged hardware bring-up of a brand-new board, see First-Time Board Setup and AEC Bring-Up.