Echoff

Reduce computer-speaker audio leaking back into a live microphone stream.

Echoff is a focused Python package for synchronized duplex capture and real-time acoustic echo cancellation (AEC). It timestamp-aligns Windows system-audio loopback and microphone blocks before feeding matched frame pairs to WebRTC's Audio Processing Module. Applications receive the reference, raw microphone, and echo-reduced microphone PCM.

Hear the difference

The same 14-second microphone capture, before and after Echoff's acoustic echo cancellation. Headphones make the comparison easiest to hear:

• ▶ Original microphone signal — echo present
• ▶ Echoff output — echo reduced

Project status: Echoff 0.1 is alpha software. Built-in live capture is physically tested on Windows. The processor APIs are designed for application-owned aligned PCM on other platforms where the LiveKit dependency installs, but those paths are not CI- or hardware-qualified here and Linux and macOS capture backends are not implemented. APIs and artifact schemas may change before 1.0. Echoff is licensed under the MIT License.

Support at a glance

Platform	Built-in live capture	Processor-only use with aligned PCM
Windows 10/11	Supported: WASAPI loopback + WASAPI microphone, with WDM-KS microphone fallback	Supported
Linux	Planned: PipeWire backend	Designed for application-owned PCM where LiveKit installs; not qualified here
macOS	Not implemented	Designed for application-owned PCM where LiveKit installs; not qualified here

Python 3.11 or newer is required. See Platform support for the exact boundary between portable processing and platform-specific capture.

Three-minute Windows quickstart

Create an isolated environment and install the published package:

py -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install echoff

List the endpoints Echoff can select:

.\.venv\Scripts\python.exe -m echoff devices

Then start a 20-second evidence-preserving recording:

.\.venv\Scripts\python.exe -m echoff record --duration 20

While it runs, play continuous speech or music through the normal speakers for at least five seconds. The default readiness heuristic needs 3.25 seconds of active, correctly paired reference audio. Speak for part of the run only if you also want to check that near-end speech survives. The command prints the artifact directory and writes:

computer_audio.wav   # captured render-endpoint reference
microphone_raw.wav   # microphone before AEC
microphone_aec.wav   # microphone after AEC
events.jsonl         # lifecycle and alignment events
config.json          # effective AEC configuration
summary.json         # devices, counters, timing, and final status
analysis.json        # signal-level diagnostics
run.log              # human-readable CLI log

Listen first to microphone_raw.wav and microphone_aec.wav. Speaker playback should be lower in the AEC track while your own speech remains intelligible. The whole-run level difference is only descriptive when real microphone speech is present; use a controlled far-end-only window before calling a number echo suppression. The hardware probe guide shows the repeatable path.

Why Echoff exists

System loopback and microphone devices start independently. Matching their first callbacks by arrival order can pair audio from different moments, leaving WebRTC with the wrong echo reference even when both streams have the same block count. Echoff instead:

1. captures the render reference and microphone on separate streams;
2. pairs blocks by monotonic end timestamp;
3. realigns and resets the adaptive filter after a discontinuity; and
4. submits each reference frame immediately before its matching microphone frame.

This is the capture-and-alignment layer that a bare AEC wrapper does not provide.

Choose the right API

Audio-source situation	Use	Why
Echoff should open the system-output loopback and microphone	AecCapture	Echoff captures, timestamp-aligns, processes, and optionally records both streams
exact time-aligned reference/microphone pairs	WebRtcAecProcessor	One atomic call preserves reference-before-microphone ordering
exact pairs with arbitrary block boundaries	BufferedWebRtcAecProcessor	Buffers partial 10 ms WebRTC frames and flushes the final tail
deterministic streams on one shared clock	StreamingWebRtcAecProcessor	Accepts continuous reference and microphone input separately; performs no timestamp alignment

Do not use the streaming adapter for two independently clocked physical devices. Use AecCapture or align the streams before calling a processor.

Minimal application skeleton

on_frame and on_reference run on Echoff's pairing thread, so move application work to a queue and poll capture health from the application loop:

import time
from queue import Empty, Queue

from echoff import AecCapture, AecConfig, AecFrame

frames: Queue[AecFrame] = Queue()


def handle_clean_audio(samples: tuple[float, ...]) -> None:
    """Replace this with your VAD, recorder, stream, or ASR handoff."""
    pass


capture = AecCapture(AecConfig(), on_frame=frames.put)
capture.start()
try:
    deadline = time.monotonic() + 20
    while time.monotonic() < deadline:
        capture.raise_if_failed()
        try:
            frame = frames.get(timeout=0.1)
        except Empty:
            continue
        handle_clean_audio(frame.microphone_clean)
finally:
    capture.stop()

# Surface a device or processing failure that happened near shutdown.
capture.raise_if_failed()

This bounded-duration example uses an unbounded queue for clarity. Production applications need a bounded, non-blocking handoff and an explicit overload policy; blocking the callback stalls Echoff's pairing thread.

AecFrame contains 48 kHz mono floating-point samples in [-1.0, 1.0], the matched reference and raw microphone, both timestamps, pair skew, and an AEC state snapshot. An AecCapture instance is single-use.

For an application that already owns aligned PCM:

from echoff import AecConfig, WebRtcAecProcessor

reference_10ms = (0.0,) * 480
microphone_10ms = (0.0,) * 480
processor = WebRtcAecProcessor(AecConfig())
clean_microphone = processor.process_pair(reference_10ms, microphone_10ms)

Both inputs must be equal-length, 48 kHz mono floats and contain a whole number of 480-sample (10 ms) frames. Read Integration before wiring physical devices or separate capture clocks.

How the live path works

Windows output -> WASAPI loopback -> timestamp queue --+
                                                       +-> align -> WebRTC APM -> AecFrame
Physical mic  -> WASAPI / WDM-KS -> timestamp queue ---+

Startup phase differences and later discontinuities are realigned instead of silently pairing stale frames. Each realignment starts a fresh AEC epoch. The echo_path_ready state turns true only after 3.25 seconds of paired, active far-end audio; the application decides whether that state should gate VAD or barge-in.

This is continuous timestamp checking with runtime realignment, not automatic tuning of the WebRTC stream_delay_ms hint. A late block from an active Windows loopback stream keeps its original scheduler slot for a bounded 100 ms grace; only a longer absence is classified as endpoint idle and filled with clock-continuous silence.

Validate on your hardware

For repeatable far-end-only evidence, confirm ffplay -version, choose a speech WAV, remain silent, and run:

.\.venv\Scripts\python.exe -m echoff record `
  --play-wav C:\audio\known-speech.wav `
  --repetitions 3

Echoff preserves all three tracks plus the process-timed stimulus windows. Compare runs only after fixing endpoint, microphone, speaker position, volume, input WAV, and stream-delay setting. Do not tune acceptance thresholds after seeing the result.

Documentation

• Documentation home — every guide, grouped by task.
• Getting started and CLI — install, select devices, and complete the first capture.
• Integration and Python API — choose an ownership model and wire Echoff safely.
• Hardware probe and Troubleshooting — validate real hardware and diagnose failures.
• Architecture and Platform support — understand timing, realignment, and OS boundaries.

Privacy

Diagnostic captures may contain private microphone speech and application audio. The default captures\ tree and general WAV/JSONL/log patterns are ignored by this repository; only the two curated demo WAVs under assets/ are explicitly exempt. Custom locations and JSON metadata are not guaranteed to be ignored. They are not encrypted; check git status and review every artifact before sharing.

Development

Clone the repository only when contributing. See Contributing and Development for the editable install, deterministic tests, and hardware-evidence contract.

License

Echoff is open source under the MIT License.