Merge remote-tracking branch 'origin/main' into auto/no-disc-and-menu-captures

docs/port/AUDIO-VERIFICATION.md

@@ -89,18 +89,25 @@ under a dummy driver" is a weaker claim than "heard", and the difference matters
 ## 3. A virtual device, when something insists on a real one
 
 For anything that opens a device rather than a bus — the emulator, most
-obviously — a PulseAudio **null sink** is a real device that records to a file:
+obviously — a PulseAudio **null sink** is a real device that records to a file.
+`pulseaudio-utils` is in both images, and `audio-capture` wraps it:
 
 ```bash
-pactl load-module module-null-sink sink_name=cap sink_properties=device.description=cap
-PULSE_SINK=cap <the application>
-parec -d cap.monitor --file-format=wav /tmp/captured.wav
+audio-capture run /tmp/menu.wav -- run-canary        # start sink, run, record
+audio-capture start                                  # or drive it by hand
+PULSE_SINK=cap godot --path port
+audio-capture record /tmp/out.wav &
 ```
 
-This is the route to capturing what the *game* plays — the menu move and confirm
-cues behind HANDOFF Q8 — rather than what we think it should play. It needs
-`pulseaudio-utils` in the image, so it is a rebuild, not something to reach for
-mid-iteration.
+This is the route to capturing what the **game** plays — the menu move and
+confirm cues behind HANDOFF Q8 — rather than what we believe it should play.
+Those bindings are currently a name match against the authors' own identifiers;
+a capture turns them into a measurement.
+
+⚠️ `audio-capture run` reports the peak level and **warns when the result is
+silent**, because silence is the failure that looks like success: a WAV of
+exactly the right duration, full of zeroes, because the application opened a
+different sink. A duration check alone would pass it.
 
 ## What none of this establishes