api-reference.md

API reference

Everything below is importable from the top-level echoquell package unless a submodule is noted. Signals are mono float64 NumPy arrays.

Pipeline — echoquell.aec

cancel_echo(far, mic, config=None) -> AecResult

Run the full align → DTD → adaptive → residual chain. config is an AecConfig; the default cancels with NLMS, double-talk detection, and residual suppression enabled.

AecConfig

Field	Default	Meaning
method	"nlms"	"nlms", "rls", or "fdaf"
n_taps	256	filter length (block size for FDAF)
mu	0.5	adaptive step size
align_delay	False	GCC-PHAT bulk-delay compensation
max_delay	None	cap on the searched delay
detect_doubletalk	True	freeze adaptation during double talk
residual_suppression	True	apply the spectral post-filter
res	ResConfig()	residual-suppression tuning

AecResult

Fields: output, linear (before residual suppression), doubletalk (mask used), delay (samples applied), weights (final taps).

Adaptive filters — echoquell.filters, echoquell.fdaf

NLMS(n_taps, mu=0.5, delta=1e-3)

RLS(n_taps, forgetting=0.999, delta=1.0)

FDAF(block, mu=0.5, delta=1e-3, forgetting=0.9)

All expose .run(far, mic, *, freeze=None) -> AdaptResult and .reset(). freeze is an optional per-sample boolean mask; where truthy, the filter outputs but does not adapt. AdaptResult carries error (cancelled signal), echo_estimate, and weights.

Double-talk detection — echoquell.dtd

geigel_dtd(far, mic, *, window=256, threshold=1.0, hangover=120) -> ndarray[bool]

crosscorr_dtd(far, mic, *, frame=256, hop=128, threshold=0.8) -> ndarray[bool]

Both return a per-sample boolean mask suitable for the freeze argument above.

Residual suppression — echoquell.res

suppress_residual(error, far, *, config=None, stft_config=None) -> ndarray

Spectral Wiener-style suppression of residual echo. config is a ResConfig (leakage, gain_floor, overestimation, smoothing).

Alignment — echoquell.align

estimate_delay(far, mic, *, max_delay=None) -> int

align(far, mic, delay) -> tuple[ndarray, ndarray]

Metrics — echoquell.metrics

erle(mic, cancelled) -> float

erle_over_time(mic, cancelled, *, frame=1024, hop=None) -> tuple[ndarray, ndarray]

misalignment(estimated, truth) -> float

echo_suppression(echo_before, echo_after) -> float

Simulation — echoquell.simulate

make_scenario(...) -> Scenario

room_impulse_response(length, *, rt60=0.2, sample_rate=16000, direct_delay=20, rng=None) -> ndarray

speech_like(n_samples, *, rng=None) -> ndarray

Scenario fields: far, mic, echo, near, rir, doubletalk.

I/O — echoquell.io

read_wav(path) -> tuple[ndarray, int]

write_wav(path, signal, sample_rate) -> None

Pure-Python reference — echoquell.reference

nlms_reference(far, mic, *, n_taps=256, mu=0.5, delta=1e-3) -> tuple[list, list]