docs(log): 045 — the master bus, painted behind the rain

Keeps the two things worth retelling: the A/B/A design that survived my own
wrong premise about the xrun baseline, and Popen(bufsize=0) returning a raw
FileIO whose short reads read as EOF — green selftest over a backdrop that
could never receive a sample.

armada/tasks/045-spectro-backdrop.md

+---
+log: 045
+title: "The master bus, painted behind the rain"
+date: 2026-09-05
+task: "#10 → #16"
+tags: [rig, midiviz, audio, visuals, perf]
+shareable: true
+---
+
+## Cap (what & why)
+
+PLN's ask, verbatim: *"can we overlay behind a basic spectro? that id remove
+spectro VSTs from ardour and wed have our super perf one as overlay on single
+win?"* One window instead of two, and one fewer plugin in the chain that
+matters.
+
+The whole risk is in one word — **behind**. A spectrum analyser is an audio
+consumer, and this window runs `Restart=always` from login on the machine that
+plays the set.
+
+## Manœuvre (how)
+
+A `SpectrumSource` taps the default sink's **monitor** through `pw-record`
+(dependency-light: `sounddevice` and `pyaudio` aren't installed here, so the
+subprocess approach `tidal-ears` already uses was the right thing to reuse).
+One thread reads exact 2560-sample hops and runs a 2048-point rFFT into 40 log
+bands with fast-attack / slow-release smoothing.
+
+Its entire contact with Qt is **one tuple, swapped under a lock, depth one**. A
+GUI at 5 fps reading an 18.7 fps analyser sees the newest frame and drops the
+rest, on purpose — a 512-deep queue was itself the 1 s HUD lag once, and a full
+buffer at capacity stays full forever.
+
+Off by default twice over: `--spectro` or the `s` key, and the systemd unit
+carries **no flag**, with a comment saying why. Login must never acquire a tap
+on the master bus.
+
+## Prise (findings / artifacts)
+
+- `504b036` on master — 520 lines in `midiviz.py`, 7 new tests, unit comment.
+- **Xruns, A/B/A, 120 s a window**, the same −30 dBFS bed playing in all three
+  so the tap is the only variable: **0 / 0 / 0** added. Counters byte-identical
+  before and after — sink 164, hydra_in 127, input.hydra_in 1965, SC 66.
+- End-to-end with real audio: a 1 kHz tone at −30 dBFS through the actual sink
+  lands in band 22 (984–1148 Hz), every other band 0.00. Silence → 0.000.
+- Independently verified before merging: **zero `pw-record` processes** spawned
+  by a plain selftest, counted by walking `/proc` rather than `pgrep -f` (which
+  matches the harness's own shell); no orphan tap after exit; the spectrum is
+  painted first of eight layers; the exit-78 close path untouched; 899 passed.
+
+## Sel (the shareable learning)
+
+Two corrections came back from the measurement, both against **my own brief**.
+
+I had written "the box currently has zero xruns" as a premise. It doesn't —
+`input.hydra_in` sits at 1965 cumulative. The A/B/A design saved the result
+anyway: comparing *deltas* across three windows with an identical bed answers
+"does the tap cost anything" without needing the absolute floor to be zero. A
+measurement is a comparison, and a wrong premise about the baseline would have
+made a true "0 added" read as a failure.
+
+And the honest limit, stated rather than buried: SuperCollider was **idle**
+during the probe. This is the tap's cost on a quiet graph, not under a live
+set.
+
+The bug worth remembering is smaller and meaner. `Popen(bufsize=0)` hands back
+a *raw* `FileIO`, where `read(n)` is a single `os.read` and short reads are
+normal, not exceptional. The first version read that as EOF, so `blocks=0`,
+**no error recorded**, and the selftest stayed green over a backdrop that could
+never have received a single sample. A green test on a pure function proves
+nothing about whether the data arrives.
+
+## Hameçon (hook)
+
+*"The feature was one word: behind. Everything hard was in the other direction
+— making sure the thing painting the audio never touched it."* Three windows,
+zero xruns, and a green test that was lying about a pipe.
+
+## Sillage (what it unlocks)
+
+It cannot replace the Ardour VSTs yet, and the reason is honest: the matrix
+cells are opaque over the middle of the spectrum, and translucent grid fills
+change how the rain reads — PLN's design call (#16). A backdrop also shows the
+**master bus**, so it can stand in for the master-out analyser and never for a
+per-channel one mid-chain.
+
+Also unblocks the parked 512-quantum question (#14): there is now a measured
+answer for what the spectrum costs before spending the same headroom twice.