Suppress speaker echo on the microphone channel

[alpha5611331]

Closes #111.

The branch for the whole echo-suppression feature, landing in the order the work has to happen: the measurement first, because every constant in the gate is sized from it, and measuring after the fact means tuning twice.

Landed so far

1. Explicit microphone processing constraints

Both getUserMedia call sites in live-transcription.service.ts passed only a deviceId, so echoCancellation, noiseSuppression and autoGainControl ran on Chromium's implicit defaults.

This changes no behaviour today - all three already default to true. The point is that they stop moving on their own under a Chromium version bump, and that there is one place to flip them from once the probe says which way they should go. AGC is a named constant because it is the flag most likely to move: it raises gain through quiet passages, which amplifies re-captured interviewer audio on a speaker setup.

The no-device case is an object with no deviceId rather than audio: true, which would have dropped the flags along with it. The flags are plain (advisory) values, not exact, so there is no new OverconstrainedError path.

2. A manual probe for the coupling

test/manual/echo-probe.mjs drives a real Electron session and reports, once a second:

    delayMs   corr   prom    erlDb   ref%   mic%   coupled
    -------   ----   ----    -----   ----   ----   -------
        120   0.87   0.71    -18.4     71     74   yes

It also drives the A/B the constraints work exists for:

pnpm exec electron test/manual/echo-probe.mjs --no-aec
pnpm exec electron test/manual/echo-probe.mjs --no-agc

Manual, like taskbar-probe.mjs: it needs a desktop session, real speakers and someone to play audio into them, so it stays out of test/run.mjs. It is not packaged either - build.files ships only electron-dist, dist and package.json, so the probe's nodeIntegration never reaches a release.

What building and reviewing the probe found

Every one of these is a case of the tool reporting a confident number that was not true, which is the only failure mode that matters in an instrument the rest of the feature is tuned against.

The correlator is right, including the sign. Injected delays of +120, +300, -150, -250 and 0 ms all come back exact to the frame, and the ERL matches the injected gain (0.1 -> -20.0 dB). The two-sided search is not theoretical: the acoustic path is always mic-after-speaker, but what is measured is arrival order at the worklet, and Chromium's getDisplayMedia loopback path carries its own latency, so on some machines the reference arrives after the echo it explains.

Peak height cannot tell coupling from noise. The search takes the max over ~120 candidate lags, and the max of many correlations is biased upward. Measured: 0.53 on pure silence, 0.57 on two independent bursty signals. A CORR_MIN of 0.5 - which looks perfectly reasonable written down, and is what the design started with - calls both of those coupled. That error runs in the dangerous direction: a false "coupled" on a headphone user is what leads a gate to cut a microphone that was never echoing anything.

Replaced with peak prominence, the peak's height above the median lag. A real echo puts a sharp peak on an otherwise flat surface; unrelated signals produce a surface that is uniformly mediocre with a high maximum and no peak.

And the prominence threshold has less margin than the synthetic numbers implied. Synthetics gave 0.28 unrelated against 0.87-1.13 for echo. A live run in a silent room reached 0.47, against a threshold of 0.5. So the run-level verdict now requires several coupled reports rather than latching on the first - one spurious second was previously enough to decide the headline finding for an entire run - and reports the fraction either way, saying INCONCLUSIVE rather than guessing.

A stalled capture was invisible. If frames stop arriving, push() simply stops being called, the report timer keeps firing, and the same numbers print every second looking exactly like a steady measurement. Frames are counted now; a report with no new frames says so and the summary warns.

A mistyped flag was silently ignored. --noaec (a plausible slip for --no-aec) ran with echo cancellation ON and reported a credible number for the configuration you were trying to rule out - in the one tool whose entire job is scoring that A/B. Unknown arguments and a non-positive --seconds now exit 2. A non-numeric --seconds previously reached setTimeout as NaN, ending the run before it started, which reads like a headphone result.

getDisplayMedia was unbounded, so a loopback that never resolves left the probe silent with no output. Bounded at 20s, the same as live-transcription.service.ts.

A note for the gate, recorded in the code: the meter paces its cross-correlation on performance.now(). That is fine for a live capture at 100 frames/s, but it makes the class untestable from synthetic input, because a test loop feeds thousands of frames in a few milliseconds and no interval ever elapses. echo-gate.ts needs unit tests, so it should pace on a frame counter instead.

Still to come on this branch

• Measure - A/B echoCancellation and autoGainControl on 2-3 machines; record delayMs (with sign), correlation, prominence and erlDb.
• Layer 1 - one AudioContext, a two-input worklet, and a delay-aligned energy gate on ch_1 (audio-capture-graph.ts + a dependency-free echo-gate.ts), plus the audio-device-switch.test.mjs rewrite.
• Layer 2 - cross-channel transcript dedup in ingest(), gated on time overlap (echo-dedup.ts).
• Docs - hero docs and a documentation-dialog.tsx entry on speaker vs headphone capture; fix the stale "deduplicates overlapping segments" claim at CLAUDE.md:63.

Verification

• pnpm lint, tsc -b, pnpm test:main all green.
• Probe run end to end on Windows 11 repeatedly: acquires both streams, reports the applied constraints back, runs the correlator, prints the summary. With nothing playing it correctly reports no correlated frames, 0/N (0%) coupled, and points at the ref% column.
• Argument guards exercised (--bogus, --seconds=abc, --seconds=0).
• Correlator verified against synthetic signals of known delay, driving the real file rather than a copy. That harness is not committed - the equivalent coverage belongs in test/echo-gate.test.mjs once the gate exists and is testable, which is what the pacing note above is about.
• Not done: the actual A/B across machines. It needs a person playing a recorded interview through speakers and cannot run from CI.

Supersedes #112, which GitHub closed when the branch was renamed.

[gitar-bot]

Gitar is working

_Gitar