From 952c856da5ab68110f379057b9c819163cd9441d Mon Sep 17 00:00:00 2001 From: Sylpheed port agent Date: Sun, 30 Aug 2026 04:26:07 +0000 Subject: [PATCH] port: make the documented control sweep executable; it was prose AUDIO-VERIFICATION.md calls its six-file sweep 'the tool's real specification' and nothing ran it -- in a tool whose own history is two invented thresholds caught only by controls. The same document states the principle it was breaking: a control that does not execute is not a control. tools/port/check-capture-controls rebuilds five of the six and asserts their verdicts. The starved capture is gone and is reported MISSING rather than omitted, and deliberately not synthesised from its published statistics -- a control fitted to the answer it must give is not a control. Two things the sweep had to learn to be honest about. check-capture emits TWO verdicts and the doc's table compresses them; the voice control is PASS on channels and UNJUDGED on starvation by design, so the sweep asserts the pair. And a starved file short-circuits before the channel check, recorded as n/a rather than FAIL -- the check did not run and the check failed are different facts. My first 'real music bed' control was -ac 6 from a stereo source and FAILED correctly: an upmix leaves channels silent and byte-identical, which is what the provenance check exists to catch. The control was wrong, not the tool. Rebuilt from six non-overlapping spans of real audio. A second attempt used aloop=-1 and hung ffmpeg indefinitely. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01N7FiFFFwbvG2uxdcEh8HyF --- docs/port/AUDIO-VERIFICATION.md | 6 ++ tools/port/check-capture-controls | 103 ++++++++++++++++++++++++++++++ 2 files changed, 109 insertions(+) create mode 100755 tools/port/check-capture-controls diff --git a/docs/port/AUDIO-VERIFICATION.md b/docs/port/AUDIO-VERIFICATION.md index 9be88cf3..0599ca00 100644 --- a/docs/port/AUDIO-VERIFICATION.md +++ b/docs/port/AUDIO-VERIFICATION.md @@ -260,6 +260,12 @@ actually decides the sample layout; a float tee is 32-bit and is still caught. ### The control sweep, which is the tool's real specification +**Run it: `tools/port/check-capture-controls`.** 🔴 Until 2026-08-30 this table was prose — the specification existed and nothing executed it, so a regression in `check-capture` or a drifting threshold would have gone unremarked in a tool whose own history is *two invented thresholds that were both wrong and were caught only by controls*. This document states the principle it was breaking: **"a control that does not execute is not a control."** + +⚠️ The verdicts below are **compressed**. `check-capture` emits two — one for channel provenance, one for starvation — and the sweep asserts the pair, because the voice control is `PASS` on channels and `UNJUDGED` on starvation *by design* and a single word cannot say that. A starved file **short-circuits** before the channel check, which the sweep records as `n/a` rather than as a failure: *the check did not run* and *the check failed* are different facts. + +⚠️ The **starved capture cannot be rebuilt** — that artifact was transient and is gone. The sweep reports it `MISSING` rather than omitting it, and deliberately does not synthesise one from the statistics published above: a control fitted to the answer it must give is not a control either. + | file | verdict | |---|---| | real music+SFX bed | `PASS` | diff --git a/tools/port/check-capture-controls b/tools/port/check-capture-controls new file mode 100755 index 00000000..4046791a --- /dev/null +++ b/tools/port/check-capture-controls @@ -0,0 +1,103 @@ +#!/usr/bin/env bash +# Run `check-capture` against its own documented control sweep. +# +# tools/port/check-capture-controls +# +# `AUDIO-VERIFICATION.md` calls that sweep **"the tool's real specification"** +# and prints it as a table. Nothing executed it. So the specification was prose: +# if `check-capture` regressed, or if a threshold drifted, no run would have said +# so -- and this is a tool whose own history is two invented thresholds that were +# both wrong and were caught only by controls. +# +# 🔴 The same document states the principle this violates: **"A control that does +# not execute is not a control."** It was written about a mono file that skipped +# its own check. The sweep as a whole was in exactly that condition. +# +# ⚠️ One control CANNOT be rebuilt: the starved capture itself was a transient +# artifact and is gone. It is reported as MISSING rather than omitted, because a +# sweep that quietly drops a control is the defect it exists to catch. +set -euo pipefail +cd "${PROJECT_DIR:-/work}" +W="${TMPDIR:-/tmp}/capture-controls"; mkdir -p "$W" +CC=tools/port/check-capture +fail=0 + +# `check-capture` emits TWO verdicts -- one for channel provenance, one for +# starvation -- and `AUDIO-VERIFICATION.md`'s table compresses them into a word. +# That is fine for a summary and wrong for an assertion: the voice control is +# `PASS` on channels and `UNJUDGED` on starvation *by design*, and a sweep that +# collapsed those could not tell "passed" from "declined to judge". So both are +# reported, and a control names the pair it expects. +verdict() { # file -> "/" + local out ch st + out=$("$CC" "$1" 2>&1 || true) + if grep -q '^PARTIAL' <<<"$out"; then echo "PARTIAL/PARTIAL"; return; fi + # A starved file SHORT-CIRCUITS: the tool reports the starvation and never + # reaches the channel check, which is right -- channel provenance is moot in a + # recording with holes punched through it. Reported as `n/a`, not as a failure: + # "the check did not run" and "the check failed" are different facts, and + # collapsing them is how a sweep starts asserting things it never observed. + if grep -qi 'no duplicated channels' <<<"$out"; then ch=PASS + elif grep -qi 'BYTE-IDENTICAL' <<<"$out"; then ch=FAIL + else ch=n/a; fi + if grep -q 'UNJUDGED' <<<"$out"; then st=UNJUDGED + elif grep -qi 'starv\|holes\|FAIL' <<<"$out"; then st=FAIL + else st=PASS; fi + echo "$ch/$st" +} +expect() { # name, file, wanted + local got; got=$(verdict "$2") + if [ "$got" = "$3" ]; then printf ' %-42s %-8s ok\n' "$1" "$got" + else printf ' %-42s %-8s 🔴 EXPECTED %s\n' "$1" "$got" "$3"; fail=1; fi +} + +# Six distinct tones -- the duplicate-channel control. Frequencies chosen so no +# two channels share one, which is what the provenance check looks for. +ffmpeg -v error -y -f lavfi -i "sine=frequency=400:duration=6" \ + -f lavfi -i "sine=frequency=800:duration=6" -f lavfi -i "sine=frequency=200:duration=6" \ + -f lavfi -i "sine=frequency=1600:duration=6" -f lavfi -i "sine=frequency=3200:duration=6" \ + -f lavfi -i "sine=frequency=6400:duration=6" \ + -filter_complex "[0:a][1:a][2:a][3:a][4:a][5:a]join=inputs=6:channel_layout=5.1[a]" \ + -map "[a]" -c:a pcm_s16le "$W/tones.wav" +ffmpeg -v error -y -i "$W/tones.wav" -c:a pcm_f32le "$W/tones_f32.wav" + +# A real music+SFX bed: six channels of REAL material, one per channel. +# +# 🔴 The first version of this control was `-ac 6` from the stereo bed, and it +# FAILED -- correctly. An upmix leaves channels 2-5 silent and byte-identical, +# which is exactly what the provenance check exists to catch, so the control was +# a broken capture wearing a control's name. The tool was right and the control +# was wrong, which is the outcome a sweep must be able to tell from its opposite. +# +# Six NON-OVERLAPPING spans of real audio, one per channel, all continuous. A +# second attempt used `aloop=-1` to stretch the short UI cues into full-length +# channels and hung ffmpeg indefinitely; spans of the long assets need no looping. +ffmpeg -v error -y -i export/audio/bgm/main_menu.ogg \ + -i export/audio/voice/ADV.ogg -i export/audio/voice/S00A.ogg \ + -filter_complex "[0:a]atrim=2:10,asetpts=N/SR/TB,aformat=channel_layouts=mono[a0]; \ + [0:a]atrim=20:28,asetpts=N/SR/TB,aformat=channel_layouts=mono[a1]; \ + [1:a]atrim=15:23,asetpts=N/SR/TB,aformat=channel_layouts=mono[a2]; \ + [1:a]atrim=40:48,asetpts=N/SR/TB,aformat=channel_layouts=mono[a3]; \ + [2:a]atrim=12:20,asetpts=N/SR/TB,aformat=channel_layouts=mono[a4]; \ + [2:a]atrim=35:43,asetpts=N/SR/TB,aformat=channel_layouts=mono[a5]; \ + [a0][a1][a2][a3][a4][a5]join=inputs=6:channel_layout=5.1[a]" \ + -map "[a]" -c:a pcm_s16le "$W/bed.wav" + +# The same bed with 350 ms holes punched through it, every second. +ffmpeg -v error -y -i "$W/bed.wav" \ + -af "volume=enable='lt(mod(t,1),0.35)':volume=0" -c:a pcm_s16le "$W/holes.wav" +# A voice track: mono, with the real pauses of speech. +ffmpeg -v error -y -i export/audio/voice/ADV.ogg -t 60 -ac 1 -c:a pcm_s16le "$W/voice.wav" + +echo "check-capture against its documented control sweep:" +expect "six distinct tones (PCM)" "$W/tones.wav" PASS/PASS +expect "the same tones as float32" "$W/tones_f32.wav" PARTIAL/PARTIAL +expect "real music bed" "$W/bed.wav" PASS/PASS +expect "bed with 350 ms holes punched in" "$W/holes.wav" n/a/FAIL +expect "voice track, mono, real pauses" "$W/voice.wav" PASS/UNJUDGED +printf ' %-42s %-8s the artifact is gone; not synthesised, because\n' "the starved capture" "MISSING" +printf ' %-42s %-8s fitting one to its published statistics would be\n' "" "" +printf ' %-42s %-8s a control shaped to the answer it must give\n' "" "" +echo +[ $fail -eq 0 ] && echo "the sweep matches the specification" || echo "🔴 check-capture no longer matches AUDIO-VERIFICATION.md" +exit $fail