Troubleshooting & Limitations
Troubleshooting
- Silence or the wrong microphone: map every slot with
diagnostic_raw_slot; do not assume the codec’s channel order. - No cancellation: verify that the reference contains playback, confirm reference polarity/gain and check for clipping. Verify hardware reference timing alignment with the microphones. A missing or clipped reference cannot cancel echo.
- Speech sounds chopped or metallic: reduce
echo_suppress_db/echo_suppress_active_db, shorten the filter, test with noise suppression disabled, and check that the ADC is not clipping. - Crackles or gaps: enable
diagnostics, reduce processing cost, disable spectrum metering, and look for I2S errors, underruns, dropped frames, or excessive processing time. - Failure to allocate: confirm PSRAM is enabled and working; remove meters and reduce other memory-heavy features.
- Long playback slowly underruns or overruns: enable
resamplerand play a continuous test for at least 30 seconds. CheckPlayback rate adjustfor the estimated I2S rate and the gradually adjusted playback rate; the offered and accepted throughput inPlayback input rateis informational only — bursty delivery is normal. If the playback rate settles at the 15–17 kHz clamp, check the actual audio clocks, write timing and device load. For bursty gaps, investigate source delivery, the network path and rebuffering. Non-16 kHz audio must be converted before it reaches this component. - Speech too quiet during playback: with the AGC gate enabled, boost is
withheld until speech proves itself. Check
AGC_GATEtelemetry and loweragc.gate.open_rms/open_delay_ms/startup_guard_msif genuine speech cannot acquire boost. The gate controls boost only; it never mutes audio. - Echo becomes louder during playback: AGC is amplifying residual echo.
Raise
agc.gate.open_rms,open_delay_ms, orstartup_guard_ms, or disableagc.gate.enabledand improve cancellation first. -
Wake word fails only during playback: first validate AEC independently, then run ESPHome Micro Wake Word from
cleaned_microphone. - The
DSP loadlog approaches 100%: the canceller can no longer keep up with 16 kHz and frames are dropped. Compile withCONFIG_COMPILER_OPTIMIZATION_PERF(see the performance checklist), run the chip at its maximumcpu_frequency, disable spectrum metering, and only then reducefilter_length. - The startup memory log shows PSRAM in use: the canceller state did not
fit in internal RAM, which measurably slows the frame loop. Reduce
filter_lengthuntil the state fits. - Slow or unstable DSP despite modest settings: confirm both
CONFIG_COMPILER_OPTIMIZATION_SIZE: "n"andCONFIG_COMPILER_OPTIMIZATION_PERF: "y"are set — ESPHome’s size-optimization default makes the floating-point loops several times slower. RISC-V targets (C3/C5/C6) also run this floating-point code in slow soft-float. - Residual echo remains at the end of loud playback: the echo tail is
longer than the filter. Verify hardware reference alignment and increase
filter_length.
For hardware bring-up problems (blank display, undetected codecs, silent slots, a reference that behaves like a microphone), see the troubleshooting section of First-Time Board Setup.
Barge-in detected, but playback does not stop promptly
Local confirmation only releases microphone audio. The provider must hear an intelligible utterance, accept it as an interruption, and send a playback flush through Core. Compare confirmation/capture-gate logs, uploaded PCM levels, provider transcription/interruption events and the device’s flush log.
For full duplex, enable neural_barge_in.speech_protection: true and arm the
capture gate. The unreleased fix holds neural protection over the same capture
window as delivery, including early cancellation on replacement playback.
Without protection, raw-microphone detection can open delivery while Speex
still suppresses the user’s voice in the processed PCM. A faint upload is a
diagnostic clue, not proof that suppression caused the delay. See
speech protection.
Do not combine full duplex with set_response_playing(true), which excludes
response audio from microphone delivery and history.
Current limitations
- The transport requires ESP-IDF TDM support: original ESP32 and ESP32-S2 cannot use it. ESP32-S3/P4 provide TDM and hardware floating point; other TDM-capable targets need performance and memory validation.
- Load scales with
filter_length; very long filters must be validated against theDSP loadlog and sustained microphone throughput. The microphone handoff buffers require working PSRAM, even with a short filter. - No dual-microphone speech enhancement: channels are processed independently (or combined by the optional post-AEC beamformer, which improves pickup but is not source separation).
- No wake-net (feed the cleaned microphone to ESPHome Micro Wake Word instead).
- Reference gain and timing alignment require measurement and tuning. 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.
- Four-slot Philips TDM, 16-bit PCM, and 16 kHz are fixed.
- AEC cannot fully model loudspeaker nonlinearities or rescue clipped signals.