Claude Code skill · built 2026-09-08 transcription-repair

Repair an existing music transcription by treating the best human transcription as the musical model and isolated stems as evidence that tests individual claims inside it. Every rule below has a shipped failure behind it.

The principle

Start from the human transcription. Use stems to test claims inside it. A human transcription establishes the grid, the meter, the rhythmic spelling, the instrument vocabulary and the phrase structure. Audio decides whether the written events happened. When the two disagree, investigate that specific disagreement.

The failure this replaces. A repair placed 164 toms using a printed chart for the count and stem onsets for the timing. Ten toms in one measure landed at 11.23, 11.55, 11.94, 12.85, 13.78, 14.74, 15.73, 16.01, 16.45 and 18.63 sixteenths. Two pairs sat under a third of a sixteenth apart, so the writer subdivided to 32nds and stacked High Tom on Hi-Mid Tom. Across 40 tom measures, 30 held a placement over 0.20 of a sixteenth off grid. It was rewritten by hand as plain descending sixteenths 26 minutes later.

The pipeline, in order

1. Asset inventory. Refuses a missing file, an empty file and an iCloud placeholder. A placeholder reads as empty and returns a clean, confident, wrong answer.
2. Key census. tr_ledger.py keys prints every element and property name with counts. A missing key is evidence only after this runs. Searching <Ghost> and finding zero started the sweep that stripped 3,842 ghosted noteheads off sixteen live tabs. The element is <AntiAccent>.
3. Recording identity. Seven checks, each needing evidence: duration, arrangement, opening, closing, three distributed landmarks, known edits, master. An unanswered check is a refusal.
4. The musical clock. Rational quarter-note coordinates, integrating the complete tempo function including progressive automations. Reading only the first tempo builds a clock right for one bar and wrong for the rest.
5. Alignment gate. One-to-one matching against four controls. No CONFIRMED, no stem timing authorizes an edit.
6. Stem reading. The stem label is the instrument identity. Per-onset tom classification, cymbal attack against decay, leakage tests.
7. Grid snapping. Onsets map through the clock into the chart's own subdivision vocabulary. A new subdivision needs affirmative evidence.
8. Two hands, two feet. Run on the voice you did not edit.
9. Edit ledger and promotion. Nine conditions. Passing yields LOCAL_VALIDATED, which is not a submitted revision.

Alignment: the three ways a match rate lies

The landmark route is what actually carries a repetitive part. It requires a stated selection rule, at least 8 landmarks, 50% coverage, chance occupancy computed from the real detected set, a rotation null, a binomial p value, and the list of landmarks that failed. A selection rule chosen after seeing what matched is refused, because the landmarks would then have been chosen because they matched.

The 15 adversarial fixtures

The suite tests whether an answer was earned. Producing an answer from deliberately inadequate evidence fails even when the code runs clean.

Plus eight evidence-quality refusals

An edit with no evidence fields cannot enter the ledger. A PROPOSED edit cannot jump to VALIDATED. Promotion is refused on a failed regression, on a non-CONFIRMED alignment, and on a stale hash. Two tabs agreeing at 99.5% count as one source. An unmeasured source pair is reported rather than assumed independent. An iCloud placeholder is refused as an asset.

Evidence authority is scoped to the question

One ranking that answers every question is the wrong shape.

So an isolated snare stem outranks a human transcription on whether one particular strike exists. A professional score outranks raw onset timing on whether a late strike belongs on the written sixteenth.

Machine evidence is weighted per drum class

Benchmark F1 at a 50 ms one-to-one protocol on MDB Drums. Treating separation quality as one number lets a cymbal proposal inherit a kick's credibility.

Real audio found a defect the fixtures could not

On GP bars 99 to 103 of a coda marked p / pp and "cymbal on dome", cymbal_events(instrument="ride") returned zero fresh attacks against 75 written events. Nothing in the return value said the detector had failed, so the zero read as an absence and very nearly became a deletion.

Two repairs were tried on a reproduction fixture of twelve quiet dome pings under a loud crash bed. Both failed, and the failure is the finding.

A quiet dome ping far under a loud resonant bed is not recoverable from that stem. Three refusals shipped in place of a tuned number.

Three design changes the self-test forced

Each of these failed on the first run, and each failure changed the design rather than the expectation.

Running it

T=~/.claude/skills/transcription-repair

python3 $T/tr_ledger.py keys FILE            # key census. Run FIRST of all
python3 $T/tr_ledger.py diff A B             # note-INSTANCE diff, 7 conflict classes
python3 $T/tr_ledger.py regress ORIG EDIT --scope-track 3

python3 $T/tr_audio.py  onsets STEM.wav --instrument snare --out on.txt
python3 $T/tr_audio.py  align  --notated n.txt --detected on.txt --duration 372.4
python3 $T/tr_audio.py  cymbal RIDE.wav      # NEW_ATTACK / DECAY_ONLY / UNRESOLVED
python3 $T/tr_audio.py  toms   TOMS.wav --calib calib.json
python3 $T/tr_audio.py  leak   --target TOM.wav --others SNARE.wav --at 91.44

python3 $T/tr_score.py  grid   L.json        # the chart's own subdivision vocabulary
python3 $T/tr_score.py  hands  L.json        # two hands, two feet, ornament guards
python3 $T/tr_score.py  ghosts L.json --lane 38
python3 $T/tr_score.py  pedal  L.json

python3 $T/tr_gate.py   tempo  SCORE.gp      # EVERY tempo event
python3 $T/tr_gate.py   track  SCORE.gp      # is this staff actually drums
python3 $T/tr_gate.py   promote --ledger E.jsonl --original A.gp --edited B.gp \
                                --scope-track 3

$T/run_selftests.sh                          # all 4 suites, exit 0 required

Completion

Completion is a saved, scoped artifact at an exact hash whose relevant track passed the whole validation suite, with an edit ledger explaining every changed instance. Successful script execution is not completion, since exit 0 proves only that a tool ran.

A finished repair reads bar by bar. Another musician can reconstruct why every changed event changed. Uncertain events stay visibly unresolved. Expect fewer edits than an unconstrained audio-to-MIDI pass would make. Existing expert work survives unless specific evidence justifies changing it, which is the design target rather than a shortfall against it.