Add preflight:media — check FFmpeg version and transcript shape up front

[Mimmo2026]

What

Adds npm run preflight:media, which catches two failures that currently surface only part-way through a run.

1. FFmpeg version

cut-silences and cut-mistakes pass their filtergraph using ffmpeg's -/option file syntax:

"-/filter_complex", scriptPath,

That syntax does not exist before FFmpeg 7. On FFmpeg 6 the run dies with Unrecognized option '/filter_complex' — after transcription and cut planning are already done.

The requirement isn't documented: README.md and docs/SETUP.md both ask for "FFmpeg (including ffprobe)" with no minimum version, and scripts/preflight.mjs does not check ffmpeg at all. docs/VERIFICATION.md records the release QA as FFmpeg 8.1.1, so the floor has never been exercised downward.

Reproduced on macOS 15 with FFmpeg 6.0: npm run check and npm test pass, npm run test:media fails at the first render.

2. Transcript shape

From docs/TOOLS-AND-API-KEYS.md:

Paragraphs, SRT subtitles, and segment-only transcripts do not supply the required word timing.

This rejects those in about a second instead of minutes in, and also catches:

• a missing or non-numeric start / end / text on any word
• a missing numeric audio_duration_secs
• a last word ending past the stated duration — i.e. the transcript is not on this recording's timeline, which is the wrong-file pairing that costs a whole pass to discover

Usage

npm run preflight:media                        # ffmpeg only
npm run preflight:media -- transcript.json     # also validate a transcript

Exit 1 if anything would fail. No new dependencies. npm run check and npm test both still pass.

Note

If the intended floor is lower than FFmpeg 7, the alternative fix is to inline the filtergraph instead of reading it from a file — though that trades the version requirement for an argument-length limit on long sources, which is presumably why the file form was chosen.