ffmpeg-skill 1.4.7 → 1.4.9

package/README.md

@@ -316,6 +316,21 @@ npx ffmpeg-skill doctor --json   # available / missing / missing_optional / unkn
 
 `doctor --json`'s `gpu_encoders` reports which GPU-backed encoders (`nvenc`, `videotoolbox`, `qsv`, `vaapi`, `amf`) this ffmpeg *build* was compiled with — read from `-encoders` alone, so it proves the capability shipped, not that the GPU/driver on this machine will actually accept a job (that needs a real encode, which `doctor`'s introspection never runs). No tool here uses one yet — every tool still assumes CPU x264/x265 — so this is purely informational and never affects `ok` or any tool's `usable`. GPU-accelerated encoding stays deliberately off the roadmap until there's a real-hardware-verified design for it (build-presence alone is not proof a job will succeed) — not a promised feature, just an honest "not yet, and not without proof it actually works."
 
+## Gotchas and best practices
+
+The short list for humans. The agent-facing version, with the reasoning, is the "Things that look right but are wrong" and "Gotchas" sections of [SKILL.md](SKILL.md).
+
+- **Variable frame rate (phone and screen recordings).** `probe.py` flags it; every re-encoding tool conforms to a constant rate automatically, and `cut.py` switches to frame-accurate mode on its own because copy-cuts on VFR land on the wrong frame. Choose the rate yourself with `fit.py input.mp4 --fps 30` when the measured average is odd.
+- **Lossless cuts snap to keyframes.** A stream-copy cut can start up to one GOP earlier than asked. `cut.py` re-encodes when the snap exceeds 0.5 s (`--tolerance` changes the limit). For a strictly lossless file pass `--tolerance -1`, and expect the cut to land on the nearest earlier keyframe; the JSON result lists them under `nearest_keyframes`.
+- **HDR stays HDR.** When the probe reports HDR (HDR10, HLG, Dolby Vision, BT.2020), the tools keep it rather than flatten it. Convert deliberately with `color.py --to-sdr` before H.264 deliverables or LUT work. `export.py` platform presets are SDR and warn on HDR input.
+- **Loudness targets.** −14 LUFS / −1 dBTP for YouTube and social platforms (the `loudness.py` default), `-I -16 --tp -1.5` for podcasts, `-I -23` for broadcast. A clip measured at −40 LUFS or below is room tone, not content; raising it raises the noise. Check true peak as well as LUFS: `check.py file --platform podcast` measures both.
+- **Frame changes first, text second.** Captions and overlays burned before a crop or resize end up off-frame. Reframe, then caption.
+- **Cropping 16:9 to 9:16 discards 70 % of the width.** `fit.py --fit crop` centres by default; pass `--crop-x`/`--crop-y` toward the subject, or pad with `--fit pad --pad-fill blur`. Look at the contact sheet before deciding.
+- **Non-Latin captions need a font with the glyphs.** Without one you get boxes, not an error. Name it (`caption.py --font "Noto Sans CJK JP"`) or point at the file (`overlay.py --font-file /path/to/NotoSansCJK-Regular.ttc`).
+- **Silence detection finds nothing?** The default threshold is −35 dBFS. The tool prints a hint with the track's measured level; raise the threshold (`silence.py --threshold -25`) or shorten `--min-silence`.
+- **Sync results carry a confidence.** Below 0.3, or an offset near the edge of the analysis window, is probably wrong: enlarge `--analyze-seconds` or find a clap. Recordings over ten minutes from separate devices need `sync.py --fix-drift`.
+- **Long chains belong in a plan.** Three hand-chained re-encodes lose quality and are hard to change; `render.py` runs the whole edit from one JSON file, and `--dry-run` shows every ffmpeg command before anything is written.
+
 ## FFmpeg compatibility
 
 The tools need FFmpeg 5.0 or later and Python 3.9 or later (standard library only). What CI actually exercises on every pull request is FFmpeg 5.1.1 (static build), 6.1 (Ubuntu apt), 7.1 (Debian trixie apt), 8.x (macOS Homebrew) and 9.x (Windows gyan.dev), on Python 3.9 and 3.13 (the two ends of the supported range). The capability parser has been run against the listings of these builds:

package/SKILL.md

@@ -5,7 +5,7 @@ description: 'Edit video and audio with local FFmpeg from natural-language reque
 
 # ffmpeg-skill
 
-Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>/scripts/<name>.py`. Every script has `--help`, and all of them accept `--dry-run`, `--json` (structured result with a probe of the output), `--fast` (preview quality), `--progress`, `--timeout SECONDS` (a single ffmpeg run is killed past this and reported as `kind: timeout`; default 1800) and `--overwrite` (consent to replace an output that already exists; without it the tool warns today and refuses from 2.0). Writing tools run nothing under `--dry-run`; `probe`/`check`/`sync`/`multicam`/`scenes`/`cropdetect`/`report` may still run ffmpeg/ffprobe to measure or analyse — they just don't write their final artifact; `verify` accepts the flag but ignores it. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`). Details for every flag: `references/scripts.md`. Device-specific behaviour (iPhone HDR, GoPro, DJI, screen recordings, Zoom): `references/devices.md`.
+Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>/scripts/<name>.py`. Every script has `--help`, and all of them accept `--dry-run`, `--json` (structured result with a probe of the output), `--fast` (preview quality), `--progress`, `--timeout SECONDS` (a single ffmpeg run is killed past this and reported as `kind: timeout`; default 1800) and `--overwrite` (consent to replace an output that already exists; without it the tool warns today and refuses from 2.0). Writing tools run nothing under `--dry-run`; `probe`/`check`/`sync`/`multicam`/`scenes`/`cropdetect`/`report`/`silence`/`loudness`/`stabilize` may still run ffmpeg/ffprobe to measure or analyse — they just don't write their final artifact (nor side files such as `--edl`, `--sheet` or a generated `.ass`); `verify` accepts the flag but ignores it. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`). Details for every flag: `references/scripts.md`. Device-specific behaviour (iPhone HDR, GoPro, DJI, screen recordings, Zoom): `references/devices.md`.
 
 ## Workflow (always follow this order)
 

package/bin/install.js

@@ -27,7 +27,7 @@ const { spawnSync } = require('child_process');
 
 const SKILL_NAME = 'ffmpeg-skill';
 const ROOT = path.resolve(__dirname, '..');
-const PAYLOAD = ['SKILL.md', 'scripts', 'references', 'mcp', 'package.json'];
+const PAYLOAD = ['SKILL.md', 'scripts', 'references', 'docs', 'mcp', 'package.json'];
 
 const args = process.argv.slice(2);
 const has = (flag) => args.includes(flag);
@@ -131,8 +131,20 @@ for (const t of targets) {
       if (!fs.existsSync(src)) { if (item !== 'SKILL.md' && item !== 'scripts') continue; throw new Error(`missing ${item} in package`); }
       copyRecursive(src, path.join(tmpDir, item));
     }
-    fs.rmSync(t.dir, { recursive: true, force: true });
-    fs.renameSync(tmpDir, t.dir);
+    // Swap: move the old install aside, move the new one in, then drop the old copy. If the
+    // second rename fails (a locked file on Windows, a permission error) the old install is put
+    // back, so an upgrade can fail but never leaves the target empty.
+    const bakDir = `${t.dir}.bak-${process.pid}`;
+    fs.rmSync(bakDir, { recursive: true, force: true });
+    const hadOld = fs.existsSync(t.dir);
+    if (hadOld) fs.renameSync(t.dir, bakDir);
+    try {
+      fs.renameSync(tmpDir, t.dir);
+    } catch (err) {
+      if (hadOld) { try { fs.renameSync(bakDir, t.dir); } catch (_) { /* the old copy stays at bakDir */ } }
+      throw err;
+    }
+    if (hadOld) fs.rmSync(bakDir, { recursive: true, force: true });
     console.log(`installed ${t.label}: ${t.dir}`);
   } catch (err) {
     failed = true;

package/docs/contract.md

@@ -0,0 +1,389 @@
+# ffmpeg-skill execution contract
+
+`ffmpeg-skill contract --json` (or `python3 scripts/_contract.py --json`) prints a
+machine-readable description of this skill: which tools exist, what each one needs,
+takes and writes, how its result is verified, and what an agent may assume about
+dry-run, input preservation and repeatability. It is the interface a planning agent
+consumes instead of reading `SKILL.md`, which stays written for a coding agent that
+follows the workflow by hand.
+
+The contract is derived from the code that runs, not maintained beside it:
+
+- the tool list is every script in `scripts/` that does not start with `_`;
+- every `input_schema` is generated from the script's own `argparse` parser at the
+  moment the contract is printed, so a new flag appears in the contract with no other edit;
+- the facts a parser cannot express (role, required ffmpeg components, verification
+  policy, visual-check policy) live in one table in `scripts/_contract.py` and are
+  checked against the scripts, the MCP server and the installer by `tests/test_contract.py`.
+
+## Versions
+
+| Field | Meaning | Changes when |
+|---|---|---|
+| `contract_version` | shape of this document (`1.0`) | a key is renamed, removed or changes meaning |
+| `skill.version` | the npm / package.json version (`1.4.9`) | any release |
+
+A release that adds a tool or a flag keeps `contract_version`; a breaking change to the
+ToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.version`
+for provenance. Consumers should also pin `ffmpeg-skill` itself by npm version or git
+tag, not by tracking `main` — see README, "Development", "Releasing".
+
+The prose tool count in this file, README, `SKILL.md` and `package.json`'s description is
+not generated (it reads naturally in a sentence), so `tests/test_contract.py`'s
+`test_docs_tool_count_matches_the_real_tool_list` checks all five against the real count
+from `scripts/` on every CI run instead — a stale count fails a test rather than drifting
+silently. (`SKILL.md` was added to that check after its "the 28 scripts" sat stale through
+twelve tool additions while the other three files were correct.)
+
+## Stability guarantee (1.x)
+
+1.0.0 was published on 2026-09-11 (by accident: see CHANGELOG.md's 1.0.0 entry; the number
+is kept rather than burned). From 1.0.3 on, the number is treated as the promise it implies.
+For the whole of 1.x:
+
+| Surface | Promise |
+|---|---|
+| Tool ids (`ffmpeg-skill/<name>`) and script names | never removed or renamed |
+| CLI arguments (`argparse` dests, flags, positionals) | never removed, renamed, or made newly required; new optional arguments may be added |
+| `--json` output keys, and the keys of `contract --json` / `doctor --json` | never removed or given a different type; new keys may be added |
+| Exit codes (0 success, 1 failure, 2 unknown/undecidable in `doctor`) | unchanged |
+| `contract_version` (`1.0`) | unchanged; a ToolSpec shape change is a major |
+| MCP `tools/list` names and `inputSchema` property names | derived from the above, so covered by the same promise |
+| Behaviour of a tool for the same input and arguments | may change only to fix a defect or to track an FFmpeg change, and every such change gets a CHANGELOG line |
+
+Not covered: the exact wording of `--help` text, descriptions, stderr messages, and the
+`details`/`notes` free-text fields of JSON output; the internals under `scripts/_*.py`;
+the evals harness; the development skills under `.claude/`.
+
+The promise is enforced, not remembered: `tests/test_contract.py`'s
+`test_mcp_tool_surface_matches_the_frozen_1x_snapshot` pins every tool's argument names and
+which are required against `tests/fixtures/mcp_tools.json`. A removal, rename or newly
+required argument fails CI; an addition fails until the snapshot is regenerated
+(`UPDATE_MCP_SNAPSHOT=1 python3 tests/test_contract.py`), so the diff of the fixture shows a
+reviewer exactly what grew.
+
+## Deprecation policy
+
+Something that has to go (an argument superseded by a better one, an output key that turned
+out to be misleading) is retired in three steps, never in one:
+
+1. **Deprecate** in a minor release: the old form keeps working unchanged, a one-line warning
+   naming the replacement is printed to stderr when it is used, the CHANGELOG entry says
+   "deprecated", and `--help` marks it `(deprecated: use ...)`.
+2. **Keep** it for at least two further minor releases or 90 days, whichever is longer.
+3. **Remove** it only in the next major (2.0.0), listed in that release's CHANGELOG under
+   "Removed", together with the version that first deprecated it.
+
+A defect fix that changes behaviour is not a deprecation: it ships in a patch with a
+CHANGELOG line, and if the old behaviour was something a caller could reasonably have relied
+on, the line says so.
+
+## Skill
+
+```json
+{
+  "contract_version": "1.0",
+  "skill": {"id": "ffmpeg-skill", "version": "1.4.9", "execution_mode": "local", "kind": "execution",
+            "entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},
+            "not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},
+  "requirements": {"python": ">=3.9 (standard library only)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},
+  "execution": {"shell": false, "arbitrary_executables": false, "network": false, "input_mutation": false}
+}
+```
+
+ffmpeg-skill is an execution skill. It measures, transforms and verifies media with
+local FFmpeg. It does not reason, plan, decide, or hold a project model; those belong
+to the agent that calls it.
+
+## ToolSpec
+
+One entry per tool under `tools`, sorted by id. Tool ids are stable:
+`ffmpeg-skill/<script name>` (`ffmpeg-skill/cut`, `ffmpeg-skill/loudness`, …).
+
+| Field | Meaning |
+|---|---|
+| `id`, `name`, `version`, `executable` | `ffmpeg-skill/cut`, `cut`, skill version, `scripts/cut.py` |
+| `role` | `analysis`, `analysis_and_execution`, `execution` or `verification` (see below) |
+| `capabilities.required` | ffmpeg components the tool always needs |
+| `capabilities.optional[]` | `{capability, when}`: needed only for that flag or input |
+| `inputs`, `outputs` | asset kinds consumed and artifact kinds produced, in words |
+| `input_schema` | generated from argparse: `properties` keyed by dest with `type`, `cli`, `enum`, `default`, `description`; `required`; `positional` (order); `mutually_exclusive` |
+| `output_schema` | what `--json` prints on stdout |
+| `supports_dry_run`, `dry_run` | whether `--dry-run` plans without running ffmpeg or writing files |
+| `supports_json` | whether `--json` exists |
+| `mutates_input` | always `false`: no tool overwrites its input |
+| `produces_artifact` | writes a file (media, PNG, HTML, EDL) |
+| `verification` | `{required, tools}`: which tools to run on the output afterwards |
+| `requires_visual_verification` | the picture changed; run `ffmpeg-skill/look` and inspect the PNG |
+| `reencodes_video`, `reencodes_audio` | `"always"` / `"never"` / `"conditional"`, meaning *when that stream is present in the input* — not whether the tool touches the file at all. `"conditional"` tools (`cut`, `export`, `render`, `batch`, `verify`, `caption`, `color`) carry a `reencode_note` explaining what it depends on — for `caption`, `--mode burn` (default) always re-encodes both streams, `--mode mux` copies both untouched; for `color`, `--strip-dovi` and `--retag` are a stream copy of both (retag only re-encodes if the copy attempt fails), while `--to-sdr` / `--lut` / `--correct` always re-encode both. Several visual tools (`fit`, `overlay`, `graphics`, `join`, `multicam`, `silence`) are `"always"` on audio too: this codebase never mixes `-c:v` re-encode with `-c:a copy` in one call, so a caller cannot assume the original audio codec survives just because only the picture changed |
+| `audio_only` | accepts an audio-only input (WAV, MP3, M4A, FLAC, OGG, Opus) |
+| `video_required` | refuses an input without a video stream ("input has no video stream") |
+| | `join` has `audio_only: true` and `video_required: false` since 0.9.1: audio-only inputs are joined as audio (no `look` needed then); mixing audio and video inputs is refused |
+| `deterministic_inputs`, `idempotency_hint` | see Repeatability |
+| `mcp` | the MCP tool name and its positional arguments |
+
+### Roles
+
+| Role | Tools |
+|---|---|
+| `analysis` (measures, writes no media) | probe, scenes |
+| `analysis_and_execution` (measures by default or with a flag, can also write) | silence (`--list`), loudness (`--measure-only`), sync (offset JSON without `-o`) |
+| `execution` (writes a new artifact) | cut, fit, caption, overlay, graphics, multicam, audio, join, color, export, render, batch |
+| `verification` (checks or shows an artifact) | check, look, verify, report |
+
+### Verification policy
+
+The workflow in `SKILL.md` is "probe first, verify last". The contract states it per tool:
+
+| Tool | After it wrote an artifact, run |
+|---|---|
+| cut, silence, audio, sync, batch | probe |
+| loudness | probe, check |
+| export | probe, check |
+| fit, caption, overlay, graphics, color, join, multicam | probe, look |
+| render | probe, check, look |
+| probe, check, look, scenes, verify, report | nothing (they are the verification) |
+
+`requires_visual_verification` is `true` exactly for the tools that change the picture
+(fit, caption, overlay, graphics, color, join, multicam, render). Audio-only tools and
+audio-only inputs never need `look`; the report line is `Look: not needed`. `check`
+rows carry `kind: format` (fix it) or `kind: judgement` (decide with the user).
+
+### Dry run
+
+`supports_dry_run` is measured, not declared: `tests/test_contract.py` runs every tool
+with `--dry-run` behind a fake `ffmpeg` that records any call, and asserts that no
+call happened and no file appeared. Under `--dry-run` a tool prints the command lines
+it would run, reports `dry_run: true`, and never reports an output probe. The
+exceptions are stated per tool in the contract's `dry_run` field: `probe` and `check` are
+read-only (ffprobe still runs); `sync`, `multicam`, `scenes`, `cropdetect`, `report`, `silence`,
+`loudness` and `stabilize` still run their ffmpeg/ffprobe measurements (the analysis is the
+tool's job; only the artifact is skipped, including side files such as `--edl`, `--sheet` or a
+generated `.ass`), and `verify` does not support dry-run (its steps run). `SKILL.md` and
+`references/scripts.md` repeat the same list; the contract is the authority.
+
+### Repeatability
+
+No tool keeps state or uses randomness. `deterministic_inputs` is `false` only for
+`verify`, whose output includes timings. `idempotency_hint` says what "same inputs"
+gives you:
+
+| Hint | Tools |
+|---|---|
+| `bit_exact` | probe, check, scenes, look |
+| `content_equivalent` (same media, bytes may differ between encoder builds) | every encoding tool, cut, sync, report |
+| `cached` | batch (content-hash cache, re-runs skip unchanged inputs) |
+| `environment_dependent` | verify |
+
+## `provides`
+
+`provides` lists these 42 tools by a cross-repository Capability id, for
+`kajisho5/AI-video-production-OS`'s `CapabilityContract.provides`
+(`docs/SPEC.md` there), matching the ids already assigned to this Skill in
+that project's own `docs/CAPABILITY_MATRIX.md` section 9 ("ffmpeg-skill's
+21 raw tools ... are Capabilities in their own right, independent of the
+higher-level Skills that delegate to them"): `[{"id": "ffmpeg-skill.<tool>",
+"lifecycle": "EXPERIMENTAL", "tool_id": "ffmpeg-skill/<tool>"}, ...]`, one
+entry per tool, sorted by id. The Capability id uses a dot
+(`ffmpeg-skill.cut`) - the `<domain>.<verb>` shape every other Skill's
+Capability ids use elsewhere in that project (`video.trim`, `audio.gain`,
+...), with `ffmpeg-skill` as the domain - while `tool_id` carries this
+contract's own slash-shaped `id` (`ffmpeg-skill/cut`) unchanged. It is
+purely additive: derived from `public_tools()`, saying nothing `tools[]`
+doesn't already say, only indexed by Capability id instead of tool name.
+
+## `capability_map`
+
+`provides` re-indexes each tool by an id shaped like the tool name
+(`ffmpeg-skill.cut`); it doesn't tell a caller that "I need to trim a
+video" resolves to `cut`. `capability_map` is the small, hand-authored
+table that closes that gap: `[{"capability": "<domain>.<verb>", "tool_id":
+"ffmpeg-skill/<tool>", "params": {...}}, ...]`. A planner that only knows
+an abstract goal (`video.trim`, `audio.loudness`, `subtitle.burn`,
+`media.stream.inspect`, `media.frames.extract`, `media.proxy`) looks it up here to find
+the tool, then builds and runs that tool's own call from its
+`input_schema` exactly as it would have if it already knew the tool name -
+`capability_map` never executes anything itself, and this skill never
+picks a capability on the caller's behalf.
+
+Some entries also fix one or more `params` where the capability names a
+*specific* behaviour narrower than the whole tool: `video.reframe` maps
+to `fit` with `params: {"fit": "crop"}`, because `fit.py` also does
+duration-fit and letterbox padding, and only the crop mode is a
+"reframe". A caller resolving `video.reframe` should treat those params
+as fixed inputs to that tool's own schema, not as optional defaults.
+
+This list is deliberately short and will stay short: a capability is only
+added when resolving it is a mechanical, no-judgment lookup. There is no
+`video.highlight` entry, for instance, because `scenes.py --highlights`
+ranks candidates by a measured proxy (audio energy or duration), never by
+understood content - offering it as a blindly-delegable capability would
+misrepresent what it does (see SKILL.md, "What this skill does and does
+not decide"). `media.proxy` (a low-bitrate, fast-decode proxy for
+downstream analysis/preview, distinct from `export.py`'s delivery
+presets) resolves to `proxy` - itself a mechanical resize + re-encode
+with no opinion on which asset should be proxied or what for.
+
+## Capabilities
+
+Names: `ffmpeg`, `ffprobe`, `encoder:<name>`, `filter:<name>`, `bsf:<name>`,
+`external:whisper`. `capabilities.required` is the union of every tool's required list;
+`optional` the union of the conditional ones. With detection (the default)
+`available`, `missing` and `missing_optional` are added from `doctor`, which reads
+`ffmpeg -encoders / -filters / -bsfs` and looks for a local whisper. Pass `--static`
+to omit detection. Nothing from the environment other than those lists and the
+ffmpeg/ffprobe/python versions is printed; no environment variables, no paths.
+
+`doctor` has three states per capability. `available` and `missing` come from a listing
+that was read; `unknown` means the listing that would prove the capability could not be
+read (`ffmpeg -filters` in a layout the parser does not recognise, or ffmpeg exiting
+non-zero), and it is never folded into `missing`, so an installed filter is not reported
+absent, nor into `available`, so a failed detection is not a pass. `detection` gives the
+status (`parsed`, `unparsed`, `failed`, `missing`), row count and detail of each listing;
+`errors` lists the unreadable ones. The filter parser recognises the FFmpeg 6/7 layout
+(three flag characters, `..C acompressor A->A`) and the FFmpeg 8 layout (two, `T.
+acompressor A->A`) by the io-spec token, so the flag width does not matter; fixtures for
+both live in `tests/fixtures/`.
+
+`ffmpeg-skill doctor` exits 0 when every required capability is available, 1 when one is
+missing, 2 when none is missing but a required one is unknown. `ok` is true only for 0.
+The keys of 0.9.0 (`available`, `missing`, `missing_optional`, `ok`) are unchanged.
+
+`doctor`'s `tools` field folds that same per-capability `state` into a per-tool answer:
+`{"<tool>": {"usable": "yes"|"no"|"unknown", "missing": [...], "fix": "...", "unknown": [...]}}`.
+`missing`/`unknown` list only that tool's own required capabilities that are in that state
+(`missing` is absent when there is none, same for `unknown`); `fix` is a one-line, plain-language
+remedy for each missing capability, joined with "; " when there is more than one. This exists so
+a caller does not have to cross-reference `available`/`missing` against each tool's own required
+capabilities by hand to answer "can I run `caption.py` on this machine right now" -- `doctor`
+passing overall does not mean every tool is usable (a plain Homebrew `ffmpeg` on macOS is `ok`
+for tools that don't need `subtitles`/`drawtext`/`zscale`, but `caption.usable` is `"no"`).
+
+`doctor`'s `gpu_encoders` field reports GPU-backed encoders (`nvenc`, `videotoolbox`, `qsv`,
+`vaapi`, `amf`) present in this ffmpeg *build*, read from `-encoders` alone — `{"status":
+"parsed"|"unparsed"|"failed"|"missing", "present": [...]}`. It proves the build shipped the
+capability, not that the GPU/driver on this machine will accept a job (that needs a real
+encode, which this introspection never runs). No tool declares or requires a GPU encoder, so
+`gpu_encoders` never affects `ok` or any tool's `usable` — it exists purely so a caller can ask
+the same honest yes/no/unknown question about GPU support that filter/encoder detection already
+answers for everything else, without a tool here needing to use one.
+
+`doctor`'s `fonts` field reports whether the default drawtext font (`caption.py`'s
+`--animate`/`--karaoke`, `graphics.py`'s templates — `BRAND_DEFAULTS["font"]`, `"DejaVu Sans"`)
+is actually installed — `{"default_font": "...", "status": "available"|"missing"|"unknown",
+"detail": "..."}`. drawtext's `font=` is a fontconfig name lookup, and fontconfig silently
+substitutes the closest match for *any* name, known or not — a missing font never fails the
+encode, so drawtext's own exit code cannot detect it. `fc-match` is queried instead: `available`
+when it resolves the name to itself, `missing` when it substitutes a different family, `unknown`
+when `fc-match` itself is not on PATH or fails. Like `gpu_encoders`, this is purely informational
+and never affects `ok` or any tool's `usable` — a substituted font is not a broken tool, just a
+typeface the caller didn't ask for.
+
+## Invocation
+
+Structured arguments are the canonical way to call a tool, on the CLI or through MCP.
+The mapping is stated in `invocation.structured.argument_mapping`: positionals in
+`input_schema.positional` order, `key` → `--key` with `_` → `-`, booleans as bare flags,
+arrays repeated, `output` → `-o`, `loudness.lufs` → `-I`. `--json` is appended for every
+tool except `probe` (JSON by default) and `look`.
+
+The MCP server also accepts `{"argv": [...]}` for CLI compatibility. That path is
+marked `canonical: false`: it is still bound to the named script and never reaches a
+shell, but an agent ecosystem should use the structured form. No tool, CLI or MCP,
+runs a shell, evaluates strings, or executes anything other than the named script,
+`ffmpeg` and `ffprobe`.
+
+## JSON output
+
+Success (`exit 0`): one document matching `output_schema`, always with
+`status: "completed"`, `output`, `dry_run`, `commands`, and `probe` of the output when a
+file was written. `probe` prints its measurement document directly.
+
+Success is decided by `verify_output` in `_common.py`, not by the ffmpeg exit code alone:
+the file must exist, be non-empty and give ffprobe at least one stream. A tool that ran
+ffmpeg successfully but has no usable artifact fails with `kind: output` (a 0-byte file is
+removed so a later step cannot mistake it for a result).
+
+Failure (non-zero exit; 127 when ffmpeg/ffprobe is missing): the message on stderr as
+before, and, when `--json` was given, on stdout:
+
+```json
+{"status": "failed", "exit_code": 1,
+ "error": {"kind": "input | ffmpeg | output | missing_tool | timeout | verification", "message": "...",
+           "code": "INPUT_INVALID | DEPENDENCY_MISSING | FFMPEG_EXECUTION_FAILED | OUTPUT_INVALID | TIMEOUT | VERIFICATION_FAILED | INTERNAL_ERROR",
+           "retryable": false},
+ "commands": ["ffmpeg ..."]}
+```
+
+`message` carries the script's own reason (missing input, ffprobe failure, the last
+stderr lines of ffmpeg, the verification that failed); an optional `error.hint` names the
+flag change that would make a retry meaningful (never a diagnosis of the media); `commands` lists what was planned
+or run so the caller can retry or report without re-deriving the command. `code` is a
+purely additive, statically-mapped relabelling of `kind` (never a new distinction `kind`
+doesn't already make) for a caller that wants a stable enum instead of matching `kind`
+strings. `retryable` is currently always `false`: none of the kinds are distinguishable
+today from a deterministic failure that would fail identically on a blind retry, so nothing
+here claims otherwise until real exit-code/stderr sniffing exists to back that up.
+
+## MCP relationship
+
+`mcp/server.py` is a transport. It holds no tool table and no schema of its own:
+
+```
+argparse parser  →  ToolSpec.input_schema  →  contract  →  MCP tools/list inputSchema
+```
+
+At start-up the server builds the ToolSpecs (`_contract.build(detect=False)`) and
+derives each `tools/list` entry with `_contract.mcp_tool`: the name is the ToolSpec
+name, the order is the contract's sorted order, and `inputSchema` is
+`_contract.mcp_input_schema(ToolSpec)`. `tools/call` maps structured arguments to
+argv with the ToolSpec's `mcp.positional` and `mcp.argument_exceptions`. A new
+public script, a removed one, or a changed parser therefore changes the MCP surface
+with no edit to `mcp/`; `tests/test_contract.py` proves this by copying the skill,
+adding, removing and editing scripts, and reading `tools/list` again.
+
+### Translation, and what JSON Schema cannot say
+
+| ToolSpec.input_schema | MCP inputSchema |
+|---|---|
+| `properties.<dest>.type / enum / default / description / items` | copied as is |
+| `properties.<dest>.cli`, `.common` | dropped (ffmpeg-skill-only keys) |
+| `positional` | same properties, passed by name; description gets a `(positional N)` prefix |
+| `required` | `required` of the structured branch |
+| `mutually_exclusive` groups | `allOf: [{not: {required: [a, b]}} …]` for every pair |
+| `one_of_required` groups | `anyOf: [{required: [a]}, …]` |
+| raw `argv` compatibility | an `argv` array property; top-level `anyOf: [{required: [argv]}, <structured branch>]` |
+| `additionalProperties: false` | kept |
+
+Two things are documented rather than encoded, because JSON Schema has no way to
+express them: when `argv` is present every other key is ignored (stated in the `argv`
+description), and MCP has no notion of positional order, so positionals are named
+properties whose order is only informative. `%(default)s` help interpolation is
+already applied when the ToolSpec is built.
+
+The `tools/list` document is deterministic (byte-identical across processes and
+identical to the translation of `contract --json`), which the tests check.
+
+## Consuming the contract from an agent
+
+A planning agent (for example video-production-agent's SkillRegistry) can:
+
+1. run `ffmpeg-skill contract --json` once and register the skill by `skill.id` and the
+   tools by `id`;
+2. resolve `capabilities.required` against `capabilities.available` before planning;
+3. pick a tool by `role`, `inputs`/`outputs`, `video_required` and `audio_only`;
+4. build the call from `input_schema` and the argument mapping, plan with `--dry-run`;
+5. run, parse `output_schema`, then run `verification.tools`, adding `look` when
+   `requires_visual_verification` is true.
+
+The measurement documents (`probe`, `check`, `scenes`, `sync`) are ffmpeg-skill's own
+shapes, not another system's Observation model; convert them in the agent's adapter.
+ffmpeg-skill contains no agent-specific code.
+
+## Where things live
+
+- `scripts/_contract.py`: the generator (`--json`, `--static`, `doctor`)
+- `bin/install.js`: `ffmpeg-skill contract` and `ffmpeg-skill doctor`
+- `tests/test_contract.py`: schema, consistency (scripts = MCP = installer), MCP inputSchema derived from the contract (equality, determinism, drift, round trips), dry-run, JSON shapes, verification policy, real-media run
+- `evals/contract/`: questions an agent must answer from the contract alone, with the expected answers checked against the live contract
+- `tests/release_check.sh`: runs the contract from the packed and installed copies before a release

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "1.4.7",
+  "version": "1.4.9",
   "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 42 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
   "keywords": [
     "ffmpeg",
@@ -33,6 +33,7 @@
     "references/scripts.md",
     "references/devices.md",
     "references/ci-platform-pitfalls.md",
+    "docs/contract.md",
     "SKILL.md",
     "README.md",
     "LICENSE"

package/scripts/_common.py

@@ -107,11 +107,14 @@ def ffmpeg_version() -> "Tuple[int, int]":
     if _FFMPEG_VERSION is None:
         _FFMPEG_VERSION = (0, 0)
         try:
-            out = subprocess.run(["ffprobe", "-version"], stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True).stdout
+            out = subprocess.run(["ffprobe", "-version"], stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True,
+                                 timeout=PROBE_TIMEOUT).stdout
             m = re.search(r"ffprobe version\s+n?(\d+)\.(\d+)", out)
             if m:
                 _FFMPEG_VERSION = (int(m.group(1)), int(m.group(2)))
-        except OSError:
+        except (OSError, subprocess.TimeoutExpired):
+            # (0, 0) = unknown: every version branch then takes the older, universally accepted
+            # spelling, the same "unknown is not missing" stance doctor takes.
             pass
     return _FFMPEG_VERSION
 
@@ -206,9 +209,9 @@ X264_PRESETS = ("ultrafast", "superfast", "veryfast", "faster", "fast", "medium"
 class Context:
     """Per-process settings that the shared flags (--dry-run, --json, --progress, --fast) set once.
 
-    Scripts read it as attributes (``STATE.dry_run``) or, for older call sites, like a dict
-    (``STATE.dry_run``). Keeping it a single explicit object rather than module globals makes
-    it obvious what run()/emit() depend on and lets tests reset it with ``STATE.reset()``.
+    Scripts read it as attributes (``STATE.dry_run``); the dict-style shims that once served
+    older call sites are gone. Keeping it a single explicit object rather than module globals
+    makes it obvious what run()/emit() depend on and lets tests reset it with ``STATE.reset()``.
     """
 
     __slots__ = ("dry_run", "json", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written", "preexisting")
@@ -353,6 +356,26 @@ def _check_no_overwrite_input(cmd: Sequence[str]) -> None:
                 continue
 
 
+def refuse_output_is_input(output: str, *inputs: str) -> None:
+    """Tool-level twin of the run() guard, for tools whose final ffmpeg command does not name
+    the user's input at all. `cut.py --segments` cuts each part into a temp dir and then concats
+    a list file: the last command's only `-i` is that list, so `-o` equal to the input sailed
+    through _check_no_overwrite_input() and replaced the source with the join (fourth audit,
+    P0). Call it once the output path is known, before any part of the input is consumed."""
+    try:
+        out_real = os.path.realpath(output)
+    except OSError:
+        return
+    for inp in inputs:
+        try:
+            same = os.path.realpath(inp) == out_real
+        except OSError:
+            continue
+        if same:
+            die(f"refusing to run: output {output!r} is the same file as input {inp!r} "
+                f"(the result would replace the source) -- choose a different --output/-o path", kind="input")
+
+
 def _check_existing_output(cmd: Sequence[str]) -> None:
     """An output path that already exists is someone's file: a previous result, a source the
     agent mis-named, a deliverable from another run. ffmpeg's -y (which every command carries so
@@ -912,6 +935,15 @@ class MissingFpsError(ValueError):
     silently swallowing a mistyped/missing --fps as an auto-timed line of digits."""
 
 
+def concat_list_line(path: str) -> str:
+    """One `file '...'` line for the concat demuxer. The demuxer reads backslash as an escape
+    inside the quoted form, so a Windows path (C:\\Users\\...\\part000.mp4) must be written
+    with forward slashes -- ffmpeg opens either spelling on Windows -- and a single quote in the
+    name is closed, escaped and reopened. Shared by cut.py (multi-segment) and sequence.py."""
+    escaped = str(path).replace("\\", "/").replace("'", "'\\''")
+    return f"file '{escaped}'"
+
+
 def parse_time(value: str, fps: Optional[float] = None) -> float:
     """Accept seconds ('12.5'), mm:ss ('1:30'), hh:mm:ss(.ms) ('00:01:30.250'), SRT '00:01:30,250',
     or -- when `fps` is given -- SMPTE non-drop-frame timecode 'hh:mm:ss:ff' ('00:01:30:15')."""
@@ -928,7 +960,12 @@ def parse_time(value: str, fps: Optional[float] = None) -> float:
         frame, whole_fps = int(f), int(round(fps))
         if not (0 <= frame < whole_fps):
             raise ValueError(f"bad SMPTE timecode '{value}': frame {frame} is out of range for {fps:g} fps (0-{whole_fps - 1})")
-        return int(h) * 3600 + int(m) * 60 + int(s) + frame / fps
+        # Non-drop-frame: the timecode counts whole_fps frames per timecode-second, so the real
+        # time is the total frame count over the true rate (at 29.97 an hour of timecode is
+        # 3596.4 s of video). This is exactly what fmt_smpte_time() inverts; before, the two
+        # disagreed by ~0.1 % on the fractional NTSC rates and drifted apart over long files.
+        total_frames = (int(h) * 3600 + int(m) * 60 + int(s)) * whole_fps + frame
+        return total_frames / fps
     if len(parts) > 3:
         raise ValueError(f"bad time: {value}")
     total = 0.0
@@ -937,6 +974,19 @@ def parse_time(value: str, fps: Optional[float] = None) -> float:
     return total
 
 
+def time_arg(value: str, flag: str, fps: Optional[float] = None) -> float:
+    """parse_time() for a command-line flag: SMPTE hh:mm:ss:ff resolves with the input's fps when
+    the caller has one, and every parse failure is a `kind: input` refusal naming the flag (so
+    `--json` callers get a failure document, never a traceback)."""
+    try:
+        return parse_time(value, fps)
+    except MissingFpsError as e:
+        die(f"{flag} {value!r}: {e}")
+    except ValueError as e:
+        die(f"{flag} {value!r}: {e} (use seconds, mm:ss, hh:mm:ss.ms or, with a known fps, hh:mm:ss:ff)")
+    return 0.0  # unreachable
+
+
 def fmt_srt_time(seconds: float) -> str:
     if seconds < 0:
         seconds = 0.0
@@ -1002,7 +1052,26 @@ def default_font_file(font_name: str) -> Optional[str]:
     """
     if platform.system() == "Windows":
         windir = os.environ.get("WINDIR", "C:\\Windows")
-        candidate = Path(windir) / "Fonts" / "arial.ttf"
+        fonts = Path(windir) / "Fonts"
+        # The requested family first: a file whose name starts with the family name with spaces
+        # removed (Noto Sans CJK JP -> NotoSansCJKjp-Regular.otf, Meiryo -> meiryo.ttc), then the
+        # common CJK system fonts when the request looks CJK (so Japanese text does not render as
+        # boxes in Arial), and Arial only as the last resort.
+        wanted = re.sub(r"[^a-z0-9]", "", (font_name or "").lower())
+        try:
+            files = sorted(fonts.iterdir()) if fonts.is_dir() else []
+        except OSError:
+            files = []
+        if wanted:
+            for f in files:
+                stem = re.sub(r"[^a-z0-9]", "", f.stem.lower())
+                if f.suffix.lower() in (".ttf", ".otf", ".ttc") and stem.startswith(wanted):
+                    return str(f)
+        if any(k in wanted for k in ("cjk", "gothic", "mincho", "meiryo", "yugoth", "msgothic", "malgun", "simhei", "simsun", "jp", "kr", "sc", "tc")):
+            for name in ("NotoSansCJKjp-Regular.otf", "NotoSansCJK-Regular.ttc", "meiryo.ttc", "YuGothM.ttc", "msgothic.ttc", "malgun.ttf", "msyh.ttc"):
+                if (fonts / name).exists():
+                    return str(fonts / name)
+        candidate = fonts / "arial.ttf"
         return str(candidate) if candidate.exists() else None
     exe = shutil.which("fc-match")
     if not exe:

package/scripts/audio.py

@@ -91,8 +91,9 @@ def main() -> int:
     fades.add_argument("--fade-in", type=float, default=0.0, help="seconds")
     fades.add_argument("--fade-out", type=float, default=0.0, help="seconds; fades the whole final mix (voice included)")
     music.add_argument("--music-fade-out", type=float, default=0.0, help="seconds; fades only the music bed at the end, voice untouched")
-    fades.add_argument("--stereo", action="store_true", help="force 2-channel output (mono is duplicated to both sides)")
-    fades.add_argument("--mono", action="store_true", help="force 1-channel output")
+    channels = fades.add_mutually_exclusive_group()
+    channels.add_argument("--stereo", action="store_true", help="force 2-channel output (mono is duplicated to both sides)")
+    channels.add_argument("--mono", action="store_true", help="force 1-channel output")
     fades.add_argument("--downmix", action="store_true", help="downmix 5.1/7.1 to stereo using standard weights")
     fades.add_argument("--replace", help="replace the audio with this file (trimmed/padded to the video)")
     dyn = ap.add_argument_group("dynamics (typed; each flag is one option of ffmpeg's acompressor / alimiter / agate)")
@@ -151,6 +152,8 @@ def main() -> int:
     if args.voice:
         fx.append(VOICE_CHAIN)
     elif args.denoise:
+        if not 10 <= args.denoise_strength <= 60:
+            die(f"--denoise-strength must be 10..60 (dB of noise floor to remove), got {args.denoise_strength:g}")
         fx.append(f"afftdn=nf=-{args.denoise_strength:g}:tn=1")
     if args.gain:
         fx.append(f"volume={args.gain:g}dB")

package/scripts/background.py

@@ -14,7 +14,7 @@ import argparse
 import math
 import sys
 
-from _common import add_common, apply_common, die, emit, ffmpeg_base, info, parse_time, probe, run, validate_color, video_args, X264_PRESETS
+from _common import add_common, apply_common, die, emit, ffmpeg_base, info, parse_time, probe, run, validate_color, video_args, X264_PRESETS, time_arg
 
 
 def main() -> int:
@@ -34,7 +34,7 @@ def main() -> int:
     args = ap.parse_args()
     apply_common(args)
 
-    target = parse_time(args.duration)
+    target = time_arg(args.duration, "--duration", args.fps)
     if target <= 0:
         die("--duration must be > 0")
     if args.fps <= 0:

package/scripts/batch.py

@@ -34,7 +34,8 @@ from typing import Any, Dict, List
 from _common import STATE, add_common, apply_common, child_args, die, emit, info, run_tool, read_text_or_die
 
 HERE = Path(__file__).resolve().parent
-MEDIA_EXT = {".mp4", ".mov", ".m4v", ".mkv", ".webm", ".avi", ".mts", ".m2ts", ".mxf", ".wav", ".m4a", ".mp3", ".flac"}
+MEDIA_EXT = {".mp4", ".mov", ".m4v", ".mkv", ".webm", ".avi", ".mts", ".m2ts", ".mxf", ".ts", ".gif",
+             ".wav", ".m4a", ".mp3", ".flac", ".aac", ".ogg", ".opus", ".aif", ".aiff"}
 # recipe steps name the script to run as plain, untrusted JSON -- run_step() joins it onto HERE
 # with the `/` operator, which silently ignores the left side when the right side is itself an
 # absolute path (Path("/scripts") / "/tmp/evil.py" == Path("/tmp/evil.py")), and does nothing to

package/scripts/broll.py

@@ -104,7 +104,7 @@ def main() -> int:
     for i, c in enumerate(cutaways):
         geo = f"scale={w}:{h}:force_original_aspect_ratio=decrease,pad={w}:{h}:(ow-iw)/2:(oh-ih)/2:color={args.pad_color}"
         parts.append(f"[{i + 1}:v]trim=start={c['from']:.3f}:duration={c['length']:.3f},setpts=PTS-STARTPTS+{c['at']:.3f}/TB,"
-                     f"{geo},setsar=1,fps={fps:g},format=yuv420p[b{i}]")
+                     f"{geo},setsar=1,fps={fps:g},format={'yuv420p10le' if (meta_a.get('video') or {}).get('hdr') else 'yuv420p'}[b{i}]")
         parts.append(f"{cur}[b{i}]overlay=0:0:eof_action=pass:enable='between(t,{c['at']:.3f},{c['at'] + c['length']:.3f})'[v{i}]")
         cur = f"[v{i}]"
     vout = cur

package/scripts/caption.py

@@ -109,7 +109,7 @@ def _asr_run(cmd: List[str], subprocess, name: str) -> "subprocess.CompletedProc
 
 def _transcribe_in(tmpdir: str, video: str, out_srt: str, language: Optional[str], model: str, audio_stream: int,
                    ffmpeg: str, shutil, subprocess) -> List[Tuple[float, float, str]]:
-    from _common import run_analysis
+    from _common import run_analysis, STATE, die
     wav = os.path.join(tmpdir, "audio.wav")
     # A wav in our own temp dir: a measurement input for the engine, not a deliverable, so it
     # is not a run() call (no --dry-run gate, not recorded), but it keeps the time limit and
@@ -117,8 +117,14 @@ def _transcribe_in(tmpdir: str, video: str, out_srt: str, language: Optional[str
     run_analysis([ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-y", "-i", video,
                   "-map", f"0:a:{audio_stream}", "-vn", "-ac", "1", "-ar", "16000", "-c:a", "pcm_s16le", wav])
     # 1. whisper.cpp
-    cli = shutil.which("whisper-cli") or shutil.which("whisper-cpp") or shutil.which("main")
-    if cli and (shutil.which("whisper-cli") or shutil.which("whisper-cpp")):
+    cli = shutil.which("whisper-cli") or shutil.which("whisper-cpp")
+    if not cli:
+        # older whisper.cpp builds ship the binary as plain `main`; accept it only when it lives
+        # in a directory that names whisper, so an unrelated /usr/bin/main is never run
+        main_bin = shutil.which("main")
+        if main_bin and "whisper" in os.path.dirname(os.path.realpath(main_bin)).lower():
+            cli = main_bin
+    if cli:
         model_path = model
         if not os.path.exists(model_path):
             for cand in (os.path.expanduser(f"~/.cache/whisper.cpp/ggml-{model}.bin"), f"models/ggml-{model}.bin", f"/usr/local/share/whisper/ggml-{model}.bin"):
@@ -139,9 +145,21 @@ def _transcribe_in(tmpdir: str, video: str, out_srt: str, language: Optional[str
     # 2. faster-whisper (python package)
     try:
         from faster_whisper import WhisperModel  # type: ignore
-        m = WhisperModel(model, device="cpu", compute_type="int8")
-        segments, _ = m.transcribe(wav, language=language, word_timestamps=False)
-        cues = [(seg.start, seg.end, seg.text.strip()) for seg in segments if seg.text.strip()]
+        import threading
+        result: list = []
+
+        def work() -> None:
+            m = WhisperModel(model, device="cpu", compute_type="int8")
+            segments, _ = m.transcribe(wav, language=language, word_timestamps=False)
+            result.extend((seg.start, seg.end, seg.text.strip()) for seg in segments if seg.text.strip())
+
+        # An in-process engine gets the same wall-clock limit as the CLI engines and ffmpeg.
+        t = threading.Thread(target=work, daemon=True)
+        t.start()
+        t.join(STATE.timeout or None)
+        if t.is_alive():
+            die(f"faster-whisper exceeded the {STATE.timeout:.0f} s time limit; raise --timeout for a long recording", code=124, kind="timeout")
+        cues = list(result)
         if cues:
             info("transcribed with faster-whisper")
             write_srt(cues, out_srt)
@@ -182,7 +200,10 @@ def parse_srt(path: str) -> List[Tuple[float, float, str]]:
             if times:
                 a, b = times.split("-->")
                 text = "\n".join(block[block.index(times) + 1:]).strip()
-                cues.append((parse_time(a), parse_time(b), text))
+                try:
+                    cues.append((parse_time(a), parse_time(b), text))
+                except ValueError as e:  # includes MissingFpsError: SRT timings are hh:mm:ss,ms, never frames
+                    die(f"{path}: cannot read the timing line {times.strip()!r}: {e}")
             block = []
     if not cues:
         die(f"no cues found in {path}")
@@ -513,12 +534,16 @@ def main() -> int:
         w, h = meta["video"]["width"], meta["video"]["height"]
         if meta["video"].get("rotation") in (90, -90, 270, -270):
             w, h = h, w
-        write_ass(cues_for_ass, ass_path, args, w, h, video=args.input if meta.get("audio") else None)
+        if not STATE.dry_run:  # the generated ASS is an artifact of this run: a plan writes nothing
+            write_ass(cues_for_ass, ass_path, args, w, h, video=args.input if meta.get("audio") else None)
         info(f"wrote {ass_path} ({len(cues_for_ass)} cues, animate={args.animate}, karaoke={args.karaoke})")
         args.ass = ass_path
+        generated_ass = True
+    else:
+        generated_ass = False
 
     if args.ass:
-        if not os.path.exists(args.ass):
+        if not generated_ass and not os.path.exists(args.ass):
             die(f"ASS file not found: {args.ass}")
         vf = f"ass={escape_filter_path(args.ass)}"
         if args.fonts_dir:

package/scripts/cut.py

@@ -30,14 +30,23 @@ import sys
 import tempfile
 from typing import List, Tuple
 
-from _common import video_args, STATE, add_common, apply_common, audio_codec_for, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, is_audio_output, parse_time, probe, run, X264_PRESETS, keyframes_near
+from _common import video_args, STATE, add_common, apply_common, audio_codec_for, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, is_audio_output, parse_time, probe, run, X264_PRESETS, keyframes_near, MissingFpsError, concat_list_line, refuse_output_is_input
 
 # keyframe timestamps found next to a requested cut that the tolerance turned into a re-encode
 # (reported so the caller can choose a lossless cut at one of them next time)
 NEAREST_KEYFRAMES: list = []
 
 
-def parse_segments(spec: str) -> List[Tuple[float, float]]:
+def _t(value: str, fps) -> float:
+    """parse_time() with the input's fps (SMPTE hh:mm:ss:ff) and every failure as kind input."""
+    try:
+        return parse_time(value, fps)
+    except (ValueError, MissingFpsError) as e:
+        die(f"bad time {value!r}: {e}")
+    return 0.0  # unreachable
+
+
+def parse_segments(spec: str, fps=None) -> List[Tuple[float, float]]:
     segs = []
     for raw in spec.split(","):
         raw = raw.strip()
@@ -46,7 +55,7 @@ def parse_segments(spec: str) -> List[Tuple[float, float]]:
         if "-" not in raw:
             die(f"segment '{raw}' must look like START-END (e.g. 0:05-0:12)")
         a, b = raw.rsplit("-", 1)
-        start, end = parse_time(a), parse_time(b)
+        start, end = _t(a, fps), _t(b, fps)
         if end <= start:
             die(f"segment '{raw}': end must be after start")
         segs.append((start, end))
@@ -156,20 +165,21 @@ def main() -> int:
         info("source looks variable-frame-rate; lossless cuts on VFR are unreliable, switching to --accurate")
         args.accurate = True
 
+    fps = (meta.get("video") or {}).get("fps")
     if args.segments:
-        segments = parse_segments(args.segments)
+        segments = parse_segments(args.segments, fps)
     else:
-        start = parse_time(args.start)
+        start = _t(args.start, fps)
         if start < 0:
             die(f"--start must not be negative, got {args.start!r}")
         if args.end and args.duration:
             die("use --end or --duration, not both")
         if args.end:
-            end = parse_time(args.end)
+            end = _t(args.end, fps)
             if end < 0:
                 die(f"--end must not be negative, got {args.end!r}")
         elif args.duration:
-            end = start + parse_time(args.duration)
+            end = start + _t(args.duration, fps)
         else:
             end = total
         if end <= start:
@@ -182,6 +192,7 @@ def main() -> int:
     segments = [(s, min(e, total) if total else e) for s, e in segments]
 
     output = args.output or default_output(args.input, "cut")
+    refuse_output_is_input(output, args.input)
     ext = os.path.splitext(output)[1] or ".mp4"
 
     reencoded = False
@@ -197,7 +208,7 @@ def main() -> int:
             listfile = os.path.join(tmp, "list.txt")
             with open(listfile, "w", encoding="utf-8") as fh:
                 for p in parts:
-                    fh.write("file '" + p.replace("'", "'\\''") + "'\n")
+                    fh.write(concat_list_line(p) + "\n")
             cmd = ffmpeg_base() + ["-f", "concat", "-safe", "0", "-i", listfile, "-c", "copy", output]
             proc = run(cmd, check=False)
             if proc.returncode != 0:

package/scripts/fit.py

@@ -38,7 +38,7 @@ import sys
 from fractions import Fraction
 from typing import List
 
-from _common import video_args, STATE, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, pad_filters, add_pad_fill_args, X264_PRESETS
+from _common import video_args, STATE, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, pad_filters, add_pad_fill_args, X264_PRESETS, time_arg
 ASPECT_PRESETS = {"16:9": Fraction(16, 9), "9:16": Fraction(9, 16), "1:1": Fraction(1, 1), "4:5": Fraction(4, 5), "4:3": Fraction(4, 3), "21:9": Fraction(21, 9)}
 
 
@@ -155,7 +155,7 @@ def main() -> int:
 
     # ---- duration
     if args.duration:
-        target = parse_time(args.duration)
+        target = time_arg(args.duration, "--duration", meta["video"].get("fps") if meta.get("video") else None)
         if target <= 0:
             die("target duration must be > 0")
         if args.method == "speed":

package/scripts/freeze.py

@@ -19,14 +19,14 @@ Examples:
 import argparse
 import sys
 
-from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args, X264_PRESETS
+from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args, X264_PRESETS, MissingFpsError, parse_time
 
 
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
     ap.add_argument("-o", "--output", help="output file (default: <name>_freeze.<ext>)")
-    ap.add_argument("--at", type=float, help="timestamp to freeze, in seconds (default: the last frame)")
+    ap.add_argument("--at", help="timestamp to freeze: seconds, mm:ss, hh:mm:ss.ms or SMPTE hh:mm:ss:ff (default: the last frame)")
     ap.add_argument("--hold", type=float, required=True, help="how long the freeze lasts, in seconds")
     ap.add_argument("--mode", choices=["insert", "extend"], default="insert",
                      help="insert (default): hold pushes the rest of the clip later; extend: only valid at/after the clip's end, makes the last frame last longer with nothing pushed")
@@ -44,7 +44,13 @@ def main() -> int:
         die("input has no video stream")
     dur = meta.get("duration") or 0.0
     fps = meta["video"].get("fps") or 30.0
-    at = args.at if args.at is not None else dur
+    if args.at is not None:
+        try:
+            at = parse_time(args.at, (meta.get("video") or {}).get("fps"))
+        except (ValueError, MissingFpsError) as e:
+            die(f"--at {args.at!r}: {e}")
+    else:
+        at = dur
     if at < 0 or at > dur:
         die(f"--at {at:g} is outside the clip (0..{dur:.3f})")
     if args.mode == "extend" and at < dur - 0.01:

package/scripts/graphics.py

@@ -21,7 +21,7 @@ import argparse
 import sys
 from typing import List, Optional
 
-from _common import aac_args, add_common, apply_common, cfr_args, color_hex, default_font_file, default_output, die, emit, escape_drawtext, escape_filter_path, ffmpeg_base, info, load_brand, parse_time, probe, run, run_keeping_subtitles, video_args, drawtext_boxborderw, X264_PRESETS
+from _common import aac_args, add_common, apply_common, cfr_args, color_hex, default_font_file, default_output, die, emit, escape_drawtext, escape_filter_path, ffmpeg_base, info, load_brand, parse_time, probe, run, run_keeping_subtitles, video_args, drawtext_boxborderw, X264_PRESETS, time_arg
 
 TEMPLATES = ["lower-third", "title", "chapter", "progress", "countdown", "bug"]
 
@@ -86,8 +86,9 @@ def main() -> int:
     if meta["video"].get("rotation") in (90, -90, 270, -270):
         W, H = H, W
     dur = meta.get("duration") or 0.0
-    s = parse_time(args.start) if args.start else 0.0
-    e = parse_time(args.end) if args.end else dur
+    fps = meta["video"].get("fps")
+    s = time_arg(args.start, "--start", fps) if args.start else 0.0
+    e = time_arg(args.end, "--end", fps) if args.end else dur
     if e <= s:
         die("--end must be after --start")
     en = f"enable='between(t,{s:.3f},{e:.3f})'"

package/scripts/grid.py

@@ -121,6 +121,11 @@ def main() -> int:
     if args.audio_from is not None:
         audio_source = "[aout]" if (args.pad and durations[args.audio_from] < target_duration) else f"{args.audio_from}:a:0"
         cmd += ["-map", audio_source]
+    # A grid is an 8-bit SDR composite by design (a comparison/contact artefact, not a
+    # deliverable); an HDR input is flattened like look.py's contact sheet flattens it. Say so
+    # once so the caller is not surprised by the 8-bit output.
+    if any((m.get("video") or {}).get("hdr") for m in metas):
+        info("note: an HDR input is composited into an 8-bit SDR grid (grid.py is a comparison artefact); use color.py --to-sdr first for a graded conversion")
     cmd += video_args(None, args.crf, args.preset)
     cmd += cfr_args(None, args.fps)
     if args.audio_from is not None:

package/scripts/insert.py

@@ -27,7 +27,7 @@ import argparse
 import math
 import sys
 
-from _common import add_common, apply_common, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, video_args, X264_PRESETS
+from _common import add_common, apply_common, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, video_args, X264_PRESETS, time_arg
 
 
 def even(n: float) -> int:
@@ -52,7 +52,7 @@ def main() -> int:
     args = ap.parse_args()
     apply_common(args)
 
-    target = parse_time(args.duration)
+    target = time_arg(args.duration, "--duration", args.fps)
     if target <= 0:
         die("--duration must be > 0")
     if args.fps <= 0:

package/scripts/join.py

@@ -168,7 +168,10 @@ def main() -> int:
         geo = f"scale={w}:{h}:force_original_aspect_ratio=increase,crop={w}:{h}"
     else:
         geo = f"scale={w}:{h}:force_original_aspect_ratio=decrease,pad={w}:{h}:(ow-iw)/2:(oh-ih)/2:color={args.pad_color}"
-    pixfmt = "yuv420p10le" if (metas[0].get("video") or {}).get("hdr") else "yuv420p"
+    # Any HDR input makes the join HDR (10-bit, HEVC via video_args on that clip's tags): an SDR
+    # first clip used to drag an HDR second clip down to 8-bit without a tone map.
+    hdr_meta = next((m for m in metas if (m.get("video") or {}).get("hdr")), None)
+    pixfmt = "yuv420p10le" if hdr_meta else "yuv420p"
     for i in range(n):
         parts.append(f"[{i}:v]{geo},setsar=1,fps={fps:g},format={pixfmt},settb=AVTB[v{i}]")
         parts.append(f"[{audio_src[i]}]aformat=sample_rates=48000:channel_layouts=stereo,asetpts=PTS-STARTPTS[a{i}]")
@@ -189,7 +192,7 @@ def main() -> int:
 
     output = args.output or default_output(args.inputs[0], "joined", "mp4")
     cmd += ["-filter_complex", ";".join(parts), "-map", "[vout]", "-map", "[aout]"]
-    cmd += video_args(metas[0], args.crf, args.preset) + aac_args() + [output]
+    cmd += video_args(hdr_meta or metas[0], args.crf, args.preset) + aac_args() + [output]
     run(cmd)
     expected = sum(durs) - d * (n - 1)
     r = probe(output, role="output")

package/scripts/look.py

@@ -15,7 +15,7 @@ import sys
 from pathlib import Path
 from typing import List
 
-from _common import add_common, apply_common, default_font_file, die, emit, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run
+from _common import add_common, apply_common, default_font_file, die, emit, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, time_arg
 
 FONT = "fontcolor=white:fontsize=h/18:box=1:boxcolor=black@0.55:boxborderw=6:x=8:y=8"
 
@@ -69,7 +69,7 @@ def main() -> int:
             die("--compare needs --at TIME")
         probe(args.compare)
         for t in args.at:
-            sec = parse_time(t)
+            sec = time_arg(t, "--at", meta["video"].get("fps") if meta.get("video") else None)
             out = args.output or os.path.join(outdir, f"{stem}_vs_{Path(args.compare).stem}_{sec:.3f}s.png")
             half = args.width // 2
             stamp = "" if args.no_timecode else f",drawtext=text='{escape_drawtext(fmt_hms(sec))}':{font_prefix}{FONT}"
@@ -82,10 +82,14 @@ def main() -> int:
             outputs.append(out)
     elif args.at:
         for t in args.at:
-            sec = parse_time(t)
+            sec = time_arg(t, "--at", meta["video"].get("fps") if meta.get("video") else None)
             if dur and sec > dur:
                 die(f"--at {t} is beyond the duration ({dur:.2f}s)")
-            out = os.path.join(outdir, f"{args.output and Path(args.output).stem or stem}_{sec:.3f}s.png")
+            if args.output and len(args.at) == 1 and Path(args.output).suffix.lower() in (".png", ".jpg", ".jpeg", ".webp"):
+                out = args.output  # one frame, one named image file: the caller's -o is the contract
+            else:
+                # several frames, or -o given as a stem/prefix without an image extension
+                out = os.path.join(outdir, f"{args.output and Path(args.output).stem or stem}_{sec:.3f}s.png")
             stamp = "" if args.no_timecode else f",drawtext=text='{escape_drawtext(fmt_hms(sec))}':{font_prefix}{FONT}"
             cmd = ffmpeg_base() + ["-ss", f"{sec:.3f}", "-i", args.input, "-vf", f"scale={args.width}:-2{tc.replace(',' + timecode_filter(font_prefix), '')}{stamp}", "-frames:v", "1", out]
             run(cmd)

package/scripts/loop.py

@@ -18,7 +18,7 @@ import argparse
 import math
 import sys
 
-from _common import add_common, aac_args, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, video_args, X264_PRESETS
+from _common import add_common, aac_args, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, video_args, X264_PRESETS, time_arg
 
 
 def main() -> int:
@@ -49,7 +49,7 @@ def main() -> int:
         target = None
         stream_loop = args.times - 1
     else:
-        target = parse_time(args.duration)
+        target = time_arg(args.duration, "--duration", meta["video"].get("fps") if meta.get("video") else None)
         if target <= src_dur:
             die(f"--duration ({target:g}s) must be longer than the source ({src_dur:.3f}s) -- use cut.py to trim instead")
         stream_loop = math.ceil(target / src_dur) - 1

package/scripts/metadata.py

@@ -48,7 +48,7 @@ def parse_chapters(path: str, duration: float) -> List[Dict[str, Any]]:
         parts = line.split(None, 1)
         try:
             start = parse_time(parts[0])
-        except ValueError:
+        except ValueError:  # MissingFpsError is a ValueError: chapter files carry no fps
             die(f"{path}:{n}: cannot read the time in {line!r} (use seconds, mm:ss or hh:mm:ss.ms)")
         title = parts[1].strip() if len(parts) > 1 else f"Chapter {len(entries) + 1}"
         if entries and start <= entries[-1]["start"]:

package/scripts/overlay.py

@@ -24,7 +24,7 @@ import argparse
 import sys
 from typing import List, Optional
 
-from _common import STATE, load_brand, video_args, add_common, apply_common, default_font_file, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, X264_PRESETS
+from _common import STATE, load_brand, video_args, add_common, apply_common, default_font_file, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, X264_PRESETS, time_arg
 
 POS = {
     "top-left": ("{m}", "{m}"),
@@ -155,8 +155,9 @@ def main() -> int:
     if args.audio_stream and not audio_streams:
         die("--audio-stream needs an input with audio streams")
     vw = meta["video"]["width"]
-    start = parse_time(args.start) if args.start else None
-    end = parse_time(args.end) if args.end else None
+    fps = meta["video"].get("fps")
+    start = time_arg(args.start, "--start", fps) if args.start else None
+    end = time_arg(args.end, "--end", fps) if args.end else None
     if start is not None and end is not None and end <= start:
         die("--end must be after --start")
     if not 0 <= args.opacity <= 1:

package/scripts/pad.py

@@ -16,15 +16,15 @@ Examples:
 import argparse
 import sys
 
-from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, validate_color, video_args, X264_PRESETS
+from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, validate_color, video_args, X264_PRESETS, time_arg
 
 
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
     ap.add_argument("-o", "--output", help="output file (default: <name>_pad.<ext>)")
-    ap.add_argument("--start", type=float, default=0.0, help="seconds of padding to add before the clip (default 0)")
-    ap.add_argument("--end", type=float, default=0.0, help="seconds of padding to add after the clip (default 0)")
+    ap.add_argument("--start", default="0", help="padding to add before the clip: seconds or mm:ss (default 0)")
+    ap.add_argument("--end", default="0", help="padding to add after the clip: seconds or mm:ss (default 0)")
     ap.add_argument("--color", default="black", help="padding colour (default black)")
     ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
     ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
@@ -32,6 +32,8 @@ def main() -> int:
     args = ap.parse_args()
     apply_common(args)
 
+    args.start = time_arg(args.start, "--start")
+    args.end = time_arg(args.end, "--end")
     if args.start < 0 or args.end < 0:
         die(f"--start/--end must be >= 0, got start={args.start:g} end={args.end:g}")
     if args.start == 0 and args.end == 0:

package/scripts/render.py

@@ -166,6 +166,8 @@ def main() -> int:
             part = src
         if c.get("speed"):
             spd = float(c["speed"])
+            if not (spd > 0) or spd != spd or spd == float("inf"):
+                die(f"clip {i}: speed must be a positive number, got {c['speed']!r}")
             dur = (probe(part).get("duration") or 0.0) if not STATE.dry_run else 10.0
             fitted = str(work / f"clip{i:02d}_speed.mp4")
             sh("fit.py", part, "--duration", f"{dur / spd:.3f}", "-o", fitted)

package/scripts/report.py

@@ -57,7 +57,7 @@ def check(path: str, platform: str) -> Optional[Dict[str, Any]]:
 
 
 def fmt_dur(sec: Optional[float]) -> str:
-    if not sec:
+    if sec is None:
         return "?"
     m, s = divmod(sec, 60)
     h, m = divmod(int(m), 60)

package/scripts/scenes.py

@@ -24,7 +24,7 @@ import re
 import sys
 from typing import Dict, List, Tuple
 
-from _common import add_common, apply_common, default_font_file, die, emit, escape_filter_path, ffmpeg_base, info, print_json, probe, require_tool, run, run_analysis, decode_pcm_mono, rms_envelope
+from _common import STATE, add_common, apply_common, default_font_file, die, emit, escape_filter_path, ffmpeg_base, info, print_json, probe, require_tool, run, run_analysis, decode_pcm_mono, rms_envelope
 
 SCORE_RE = re.compile(r"frame:(\d+)\s+pts:\d+\s+pts_time:([0-9.]+)")
 
@@ -168,9 +168,10 @@ def main() -> int:
         result["highlights_rank_by"] = args.rank_by
         info(f"proposed {len(picks)} highlight ranges totalling {result['highlights_total']:.1f}s")
         if args.edl:
-            with open(args.edl, "w", encoding="utf-8") as fh:
-                for s, e in picks:
-                    fh.write(f"{s:.2f}-{e:.2f}\n")
+            if not STATE.dry_run:  # the contract says --edl is not written under --dry-run
+                with open(args.edl, "w", encoding="utf-8") as fh:
+                    for s, e in picks:
+                        fh.write(f"{s:.2f}-{e:.2f}\n")
             info(f"wrote {args.edl}")
 
     if args.sheet:

package/scripts/sequence.py

@@ -19,7 +19,7 @@ import sys
 import tempfile
 from pathlib import Path
 
-from _common import add_common, apply_common, default_output, die, emit, ffmpeg_base, info, probe, run, video_args, X264_PRESETS
+from _common import add_common, apply_common, default_output, die, emit, ffmpeg_base, info, probe, run, video_args, X264_PRESETS, concat_list_line
 
 
 def even(n: float) -> int:
@@ -28,9 +28,7 @@ def even(n: float) -> int:
 
 
 def _concat_list_line(path: Path) -> str:
-    # concat demuxer file paths: backslash and single-quote need escaping inside the quoted form.
-    escaped = str(path).replace("\\", "/").replace("'", "'\\''")
-    return f"file '{escaped}'"
+    return concat_list_line(str(path))
 
 
 def main() -> int:

package/scripts/silence.py

@@ -104,9 +104,10 @@ def main() -> int:
         info("hint: " + summary["hint"])
 
     if args.edl:
-        with open(args.edl, "w", encoding="utf-8") as fh:
-            for s, e in keeps:
-                fh.write(f"{s:.3f}-{e:.3f}\n")
+        if not STATE.dry_run:  # the EDL is an artifact like the cut itself: a plan writes nothing
+            with open(args.edl, "w", encoding="utf-8") as fh:
+                for s, e in keeps:
+                    fh.write(f"{s:.3f}-{e:.3f}\n")
         info(f"wrote {args.edl}")
 
     if args.list: