audio-latency-probe

A small macOS CLI to measure round-trip audio latency between any pair of CoreAudio devices — output → physical/virtual cable → input — by playing a linear chirp and recovering its delay with cross-correlation.

Built for tuning real-time voice DSP loops (e.g. mic → DSP → BlackHole 2ch → Zoom). Before you can pick a sane block size / target latency for a live call, you have to actually measure the device round-trip — the published manufacturer numbers are aspirational. This does that in one command.

Why this project

The Catacolabs/voice-enhancer real-time DSP chain (HPF → Compressor → EQ → DeEsser → PitchShift → Limiter, WSOLA pitch shift v1.0) has been gated for weeks on BlackHole 2ch plumbing into Zoom/Teams. The May 10 cron shipped blackhole-doctor (device introspection) and the May 11 cron shipped preset-audition (offline preset A/B). The missing piece is the runtime budget — what round-trip latency does my actual voice-enhancer → BlackHole → Zoom chain incur, and how much DSP block-size headroom do I have before the call sounds laggy?

audio-latency-probe closes that gap. Plug the planned output device into the planned input device (built-in mic → speakers loopback, or BlackHole 2ch self-loop, or a hardware passthrough), run one command, get a millisecond number plus a confidence score.

It's also a clean consulting-deliverable artifact: "I measured your DSP loop's end-to-end latency at 38 ms with 0.96 correlation — your 120 ms perceptual budget has 82 ms of headroom for additional processing."

Install

cd audio-latency-probe-2026-05-12
pip install -e .

Depends on numpy and sounddevice (which wraps PortAudio).

Run

List CoreAudio devices:

audio-latency-probe devices

Measure the default round-trip (default output → default input):

audio-latency-probe measure

Pick specific devices and run 5 trials:

audio-latency-probe measure --output 2 --input 1 --trials 5 --json

Synthesize an offline self-test (no audio hardware needed) — verifies the chirp + correlation math:

audio-latency-probe selftest

How it works

1. Generate a linear chirp (default 500 Hz → 8 kHz, 50 ms, raised-cosine tapered) at the chosen sample rate.
2. Play the chirp on the output device while simultaneously recording on the input device for a window long enough to capture it back.
3. Cross-correlate the recorded signal against the original chirp; the peak index gives the round-trip latency in samples → milliseconds.
4. Report per-trial latency and the normalized correlation peak as a confidence score (anything above ~0.5 is reliable; under that, the loop probably isn't connected).

Pure NumPy correlation (no scipy dep), single-file DSP, ~350 LOC total.

Roadmap

• One-way mode using a sync marker for asymmetric setups
• CSV/Parquet export for long benchmark sweeps across block sizes
• Wire-up into voice-enhancer CI as a latency regression check

License

MIT