echoquell

Acoustic echo cancellation, offline and in pure NumPy.

echoquell is a small toolkit for cancelling the echo that a teleconferencing terminal picks up when the far-end audio played through its loudspeaker leaks back into its microphone. It implements the pieces a real canceller is built from and keeps them legible and testable:

• Adaptive filters — normalised LMS, recursive least squares, and a frequency-domain (overlap-save) block filter.
• Double-talk detection — Geigel and cross-correlation detectors that freeze adaptation while the near-end talker is speaking.
• Residual echo suppression — a spectral post-filter for the echo the linear stage cannot remove.
• Evaluation — ERLE (global and time-varying), filter misalignment, and broadband echo suppression.
• Reproducible scenarios — a synthetic room/echo/double-talk simulator so results are seed-deterministic and need no external audio.

Everything runs offline on plain arrays. The only runtime dependency is NumPy; WAV I/O uses the standard library.

Install

pip install echoquell

Or from a checkout:

pip install -e ".[dev]"

Quick start

from echoquell import cancel_echo, make_scenario
from echoquell.metrics import erle

# A 1 s far-end / microphone pair with a double-talk burst in the middle.
scenario = make_scenario(n_samples=16000, doubletalk_region=(0.5, 0.75), seed=0)

result = cancel_echo(scenario.far, scenario.mic)
print(f"ERLE: {erle(scenario.mic, result.output):.1f} dB")

Pick a different algorithm or turn stages off through AecConfig:

from echoquell.aec import AecConfig

cfg = AecConfig(method="rls", n_taps=256, detect_doubletalk=True, residual_suppression=True)
result = cancel_echo(scenario.far, scenario.mic, cfg)

Command line

# Cancel echo in a far-end/mic WAV pair.
echoquell cancel far.wav mic.wav out.wav --method nlms --taps 256

# Score an algorithm on a synthetic scenario.
echoquell evaluate --method rls --taps 256

Documentation

• docs/usage.md — task-oriented guide.
• docs/architecture.md — how the stages fit together.
• docs/design-notes.md — why things work the way they do.
• docs/api-reference.md — the public API.

License

MIT — see LICENSE.