From fe6f8462abfc56fb87145456f81c87faa285aa88 Mon Sep 17 00:00:00 2001 From: BlackMark Date: Mon, 22 Jun 2026 01:48:40 +0200 Subject: [PATCH] docs: lessons learned for rate-measurement hardening + the test harness Co-Authored-By: Claude Opus 4.8 --- README.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/README.md b/README.md index e328c8f..5c28fdf 100644 --- a/README.md +++ b/README.md @@ -375,6 +375,21 @@ Non-obvious things that cost time and constrain the design: captures post-mix at the device format (always correct). The Audio panel shows each stream's provenance (known / measuring / measured rate (ch/bits assumed)) so what the mirror is using is always visible — see Limitations. +- **A short measurement window *rejects* a bad reading, it can't *average* it away.** + Measuring the rate over ~200 ms made one extra ~10 ms WASAPI buffer at a window edge a + ~5% error, which lands *between* standard rates (they're >8% apart) — so 44100 read as + ~46205 and got published verbatim. The robust fix isn't just a longer window: it's to + **refuse any window that doesn't snap to a standard rate** and require **consensus** + across windows, since a quantization/burst error big enough to miss the right rate + lands in no-man's-land rather than on a wrong neighbour. Only commit a non-standard + estimate as explicitly *low-confidence* (shown red). The operator can also re-measure + or override the format via a per-stream `AudioRingHeader` op channel; the host rebuilds + its render client when `format_generation` bumps, so it takes effect live. +- **Drive the ImGui overlay for tests through an IPC harness, not synthetic input.** + `PostMessage`-d mouse clicks don't reliably reach ImGui widgets, and key/coordinate + simulation is brittle. A tiny debug-only command channel (`-DCOOP_TEST_HARNESS`, file- + based) that calls the *same* code the buttons do — and replies with state — makes UI + validation deterministic and scriptable, and is compiled out of the shipped product. - **Capturing at `Present` decouples the mirror from DWM composition.** The hook copies the backbuffer inside the game's `Present`, which the game issues at its true render rate regardless of how DWM composites that *window*. So an unfocused game window can