ffmpeg-skill 1.4.6 → 1.4.8

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,388 @@
+# 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.8`) | 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.8", "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` and `report` still
+run their ffmpeg/ffprobe measurements (the analysis is the tool's job; only the artifact is
+skipped), 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.6",
+  "version": "1.4.8",
   "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/references/scripts.md

@@ -1,6 +1,6 @@
 # Script reference
 
-Every script prints the same information with `--help`; this file exists so the agent can read several at once. All scripts accept `--dry-run`, `--json`, `--fast`, `--progress`, `--timeout SECONDS`, `--overwrite`, `-o OUT` -- but `--dry-run` only guarantees nothing is written for writing tools: `probe` (read-only, `--dry-run` changes nothing) and `check` (skips only the loudness-measurement pass) still run ffprobe/ffmpeg, `sync`/`multicam`/`scenes`/`cropdetect`/`report` still run ffmpeg/ffprobe to measure or analyse (they just don't write the final artifact), and `verify` accepts the flag but ignores it entirely. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`).
+Every script prints the same information with `--help`; this file exists so the agent can read several at once. All scripts accept `--dry-run`, `--json`, `--fast`, `--progress`, `--timeout SECONDS`, `--overwrite`, `-o OUT` -- but `--dry-run` only guarantees nothing is written for writing tools: `probe` (read-only, `--dry-run` changes nothing) still runs ffprobe, `check`/`sync`/`multicam`/`scenes`/`cropdetect`/`report`/`silence`/`loudness`/`stabilize` still run their ffmpeg/ffprobe measurements (a dry-run plan rests on real numbers; they just don't write the final artifact), and `verify` accepts the flag but ignores it entirely. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`).
 
 ## Contents
 - probe.py — inspect

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")
@@ -462,12 +465,17 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subpr
     return proc
 
 
-def run_analysis(cmd: Sequence[str], *, check: bool = True, text: bool = True) -> subprocess.CompletedProcess:
-    """Run an ffmpeg *measurement* (scene scores, crop rectangles, decoded PCM, signal stats):
-    output to `-f null` or a pipe, nothing written. These are not run() calls -- they run under
-    --dry-run too, since the analysis is the tool's whole job -- but they get the same wall-clock
-    limit as any other ffmpeg invocation and, with check=True, the same `kind: ffmpeg` failure
-    instead of an exit-0 "0 scenes found" over a file ffmpeg could not read."""
+def run_analysis(cmd: Sequence[str], *, check: bool = True, text: bool = True, record: bool = False) -> subprocess.CompletedProcess:
+    """Run an ffmpeg *measurement* (scene scores, crop rectangles, decoded PCM, signal stats,
+    silence detection, loudness, stabilisation pass 1): output to `-f null`, a pipe or a temp
+    file, no deliverable written. These are not run() calls -- they run under --dry-run too,
+    since a plan built on a fake measurement is not a plan (silence.py used to report "0
+    silences" and loudness.py a made-up -20 LUFS under --dry-run) -- but they get the same
+    wall-clock limit as any other ffmpeg invocation and, with check=True, the same `kind: ffmpeg`
+    failure instead of an exit-0 "0 scenes found" over a file ffmpeg could not read. record=True
+    lists the command in the --json `commands` like run() does."""
+    if record:
+        STATE.commands.append(_cmdline(cmd))
     limit = _limit_for(cmd)
     try:
         proc = subprocess.run(list(cmd), stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=text, timeout=limit)
@@ -479,6 +487,17 @@ def run_analysis(cmd: Sequence[str], *, check: bool = True, text: bool = True) -
     return proc
 
 
+def dry_run_input_pending(path: str) -> bool:
+    """True when a measurement cannot run because its input does not exist yet under --dry-run:
+    in a render.py/batch.py plan each stage's input is the previous stage's output, which a dry
+    run never wrote. The measurement is then skipped (with a note) rather than failing the plan;
+    on a real file the measurement runs even under --dry-run."""
+    if STATE.dry_run and not os.path.exists(path):
+        info(f"[dry-run] {path} does not exist yet (an earlier dry-run stage would write it); measurement skipped")
+        return True
+    return False
+
+
 def child_limit(per_call: Optional[float] = None) -> Optional[float]:
     """Wall-clock ceiling for running one sibling script as a subprocess (render/batch/report
     stages, the MCP server's dispatch). A tool runs a handful of ffmpeg/ffprobe calls, each
@@ -896,6 +915,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')."""
@@ -912,7 +940,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
@@ -986,7 +1019,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:
@@ -1142,6 +1194,9 @@ def db_to_linear(db: float) -> float:
 def read_text_or_die(path: str, flag: str) -> str:
     """Read a caller-supplied UTF-8 text file (a cue list, chapters, notes) or fail as kind input
     with the flag named, instead of a FileNotFoundError / UnicodeDecodeError traceback."""
+    if os.path.isdir(path):
+        # checked first: Windows raises PermissionError, not IsADirectoryError, for a directory
+        die(f"{flag}: {path} is a directory, not a text file")
     try:
         with open(path, "r", encoding="utf-8") as fh:
             return fh.read()

package/scripts/_contract.py

@@ -215,10 +215,13 @@ DRY_RUN_ANALYSIS = {
     "scenes": "scene and audio-peak measurement runs; --sheet and --edl are not written",
     "report": "probe, loudness and contact-sheet measurements run; the HTML is not written",
     "cropdetect": "the cropdetect filter runs over the sampled windows to measure bars; this tool never writes a file regardless of --dry-run",
+    "silence": "silencedetect runs so the reported silences and keep ranges are real; the cut output is not written",
+    "loudness": "the loudnorm measurement pass runs so input_i and the planned pass-2 command are real; the normalised output is not written",
+    "check": "read-only tool; the loudness measurement runs under --dry-run too, so every row is present",
+    "stabilize": "vidstabdetect (pass 1, into a temp file) runs; the stabilised output (pass 2) is not written",
 }
 DRY_RUN_NOTES = {
     "probe": "read-only tool; --dry-run changes nothing (ffprobe still runs)",
-    "check": "read-only tool; --dry-run skips the ffmpeg loudness measurement, so loudness rows are absent",
     "verify": "not supported: the flag is accepted but the steps run and outputs are written",
 }
 

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/batch.py

@@ -31,10 +31,11 @@ import time
 from pathlib import Path
 from typing import Any, Dict, List
 
-from _common import STATE, add_common, apply_common, child_args, die, emit, info, run_tool
+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
@@ -102,7 +103,10 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path) -> Dict
     final = final_path(src, recipe, outdir)
     t0 = time.time()
     if recipe.get("project"):
-        proj = json.loads(Path(recipe["project"]).read_text(encoding="utf-8"))
+        try:
+            proj = json.loads(read_text_or_die(str(recipe["project"]), "recipe.project"))
+        except ValueError as e:
+            die(f"recipe.project: {recipe['project']} is not valid JSON: {e}")
         idx = int(recipe.get("clip_key", 0))
         proj.setdefault("clips", [{}])
         while len(proj["clips"]) <= idx:

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

@@ -36,7 +36,7 @@ import sys
 from pathlib import Path
 from typing import List, Optional, Tuple
 
-from _common import STATE, color_hex, load_brand, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, fmt_smpte_time, info, MissingFpsError, parse_time, probe, run, x264_args, X264_PRESETS
+from _common import STATE, color_hex, load_brand, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, fmt_smpte_time, info, MissingFpsError, parse_time, probe, run, x264_args, X264_PRESETS, read_text_or_die
 
 ALIGN = {"bottom": 2, "top": 8, "center": 5, "bottom-left": 1, "bottom-right": 3, "top-left": 7, "top-right": 9}
 
@@ -48,33 +48,32 @@ TIME_RE = re.compile(
 def parse_text_cues(path: str, auto_seconds: float, gap: float, fps: Optional[float] = None) -> List[Tuple[float, float, str]]:
     cues: List[Tuple[float, float, str]] = []
     cursor = 0.0
-    with open(path, encoding="utf-8") as fh:
-        for raw in fh:
-            line = raw.rstrip("\n")
-            if not line.strip():
-                continue
-            m = TIME_RE.match(line)
-            if m:
-                try:
-                    start, end = parse_time(m.group("a"), fps), parse_time(m.group("b"), fps)
-                except MissingFpsError as e:
-                    die(f"cue '{line}': {e} -- pass --fps, or --input's own fps is used automatically when given")
-                except ValueError:
-                    # TIME_RE matched (so m.group("text") is the real cue text, not the broken
-                    # timestamp), but one of the two timestamps itself failed to parse (e.g. a
-                    # malformed "00:00:03.15.999") -- falling back to `line.strip()` here used to
-                    # burn the whole raw line, broken timestamp included, into the caption instead
-                    # of just the text after it.
-                    start, end, text = cursor, cursor + auto_seconds, m.group("text").strip()
-                else:
-                    text = m.group("text").strip()
+    for raw in read_text_or_die(path, "--text").lstrip("\ufeff").splitlines(True):
+        line = raw.rstrip("\n")
+        if not line.strip():
+            continue
+        m = TIME_RE.match(line)
+        if m:
+            try:
+                start, end = parse_time(m.group("a"), fps), parse_time(m.group("b"), fps)
+            except MissingFpsError as e:
+                die(f"cue '{line}': {e} -- pass --fps, or --input's own fps is used automatically when given")
+            except ValueError:
+                # TIME_RE matched (so m.group("text") is the real cue text, not the broken
+                # timestamp), but one of the two timestamps itself failed to parse (e.g. a
+                # malformed "00:00:03.15.999") -- falling back to `line.strip()` here used to
+                # burn the whole raw line, broken timestamp included, into the caption instead
+                # of just the text after it.
+                start, end, text = cursor, cursor + auto_seconds, m.group("text").strip()
             else:
-                start, end, text = cursor, cursor + auto_seconds, line.strip()
-            if end <= start:
-                die(f"cue '{line}': end must be after start")
-            text = text.replace(" | ", "\n").replace("|", "\n")
-            cues.append((start, end, text))
-            cursor = end + gap
+                text = m.group("text").strip()
+        else:
+            start, end, text = cursor, cursor + auto_seconds, line.strip()
+        if end <= start:
+            die(f"cue '{line}': end must be after start")
+        text = text.replace(" | ", "\n").replace("|", "\n")
+        cues.append((start, end, text))
+        cursor = end + gap
     if not cues:
         die(f"no cues found in {path}")
     return cues
@@ -110,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
@@ -118,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"):
@@ -140,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)
@@ -173,8 +190,7 @@ def _transcribe_in(tmpdir: str, video: str, out_srt: str, language: Optional[str
 def parse_srt(path: str) -> List[Tuple[float, float, str]]:
     cues: List[Tuple[float, float, str]] = []
     block: List[str] = []
-    with open(path, encoding="utf-8-sig") as fh:
-        content = fh.read().replace("\r\n", "\n") + "\n\n"
+    content = read_text_or_die(path, "--srt").lstrip("\ufeff").replace("\r\n", "\n") + "\n\n"
     for line in content.split("\n"):
         if line.strip():
             block.append(line)

package/scripts/check.py

@@ -25,7 +25,7 @@ import sys
 from fractions import Fraction
 from typing import Any, Dict, List
 
-from _common import STATE, add_common, apply_common, die, emit, info, probe, require_tool, run
+from _common import STATE, add_common, apply_common, die, emit, info, probe, require_tool, run, run_analysis, dry_run_input_pending
 
 SPECS: Dict[str, Dict[str, Any]] = {
     "youtube":   {"max_duration": 12 * 3600, "aspects": ["16:9", "9:16", "1:1", "4:3"], "min_height": 720, "fps_max": 60, "codecs": ["h264", "hevc", "prores", "av1", "vp9"], "max_bytes": 256 * 1024 ** 3, "lufs": -14, "lufs_tol": 2.0, "tp": -1.0, "sdr_only": False},
@@ -41,8 +41,10 @@ SPECS: Dict[str, Dict[str, Any]] = {
 
 
 def measure_loudness(path: str) -> Dict[str, float]:
+    if dry_run_input_pending(path):
+        return {}
     ffmpeg = require_tool("ffmpeg")
-    proc = run([ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-vn", "-af", "loudnorm=I=-14:TP=-1:LRA=11:print_format=json", "-f", "null", "-"], quiet=True, check=False)
+    proc = run_analysis([ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-vn", "-af", "loudnorm=I=-14:TP=-1:LRA=11:print_format=json", "-f", "null", "-"], check=False, record=True)
     m = re.search(r"\{[^{}]*\"input_i\"[^{}]*\}", proc.stderr, re.S)
     if not m:
         return {}

package/scripts/cropdetect.py

@@ -42,14 +42,22 @@ def detect(path: str, seconds: float, samples: int, limit: float, round_to: int,
     ffmpeg = require_tool("ffmpeg")
     per_window = max(0.5, seconds / max(1, samples))
     rects: List[Tuple[int, int, int, int]] = []
+    failures: List[List[str]] = []
     for i in range(samples):
         start = 0.0 if duration <= 0 else (duration - per_window) * i / max(1, samples - 1) if samples > 1 else 0.0
         start = max(0.0, start)
         cmd = [ffmpeg, "-hide_banner", "-nostdin", "-ss", f"{start:.3f}", "-i", path, "-t", f"{per_window:.3f}",
                "-vf", f"cropdetect=limit={limit:g}:round={round_to}:reset=1", "-f", "null", "-"]
-        proc = run_analysis(cmd)
+        proc = run_analysis(cmd, check=False)
+        if proc.returncode != 0:
+            # One window ffmpeg cannot decode (a damaged stretch) is skipped; the other windows
+            # still measure. Only when every window fails is there nothing to report.
+            failures.append(proc.stderr.strip().splitlines()[-1:] or ["?"])
+            continue
         for m in CROP_RE.finditer(proc.stderr):
             rects.append((int(m.group(1)), int(m.group(2)), int(m.group(3)), int(m.group(4))))
+    if failures and len(failures) == samples:
+        die(f"cropdetect could not decode any of the {samples} sampled windows: {failures[-1][0][:300]}", kind="ffmpeg")
     return rects
 
 

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
 
 # 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:
@@ -197,7 +207,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/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/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/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

@@ -85,7 +85,11 @@ def main() -> int:
             sec = parse_time(t)
             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/loudness.py

@@ -18,16 +18,18 @@ import os
 import re
 import sys
 
-from _common import STATE, add_common, apply_common, emit, AUDIO_CODECS, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run
+from _common import STATE, add_common, apply_common, emit, AUDIO_CODECS, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run, run_analysis, dry_run_input_pending
 
 
 
 def measure(path: str, I: float, tp: float, lra: float) -> dict:
-    if STATE.dry_run:
-        return {"input_i": "-20.0", "input_tp": "-3.0", "input_lra": "8.0", "input_thresh": "-30.0", "target_offset": "0.0", "silent": False}
+    if dry_run_input_pending(path):
+        return {"input_i": "-20.0", "input_tp": "-3.0", "input_lra": "8.0", "input_thresh": "-30.0", "target_offset": "0.0", "silent": False, "placeholder": True}
     ffmpeg = require_tool("ffmpeg")
     cmd = [ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-vn", "-af", f"loudnorm=I={I}:TP={tp}:LRA={lra}:print_format=json", "-f", "null", "-"]
-    proc = run(cmd, check=False)
+    # Pass 1 is a measurement: it runs under --dry-run too, so the planned pass-2 command and
+    # the reported input_i are real (before 1.4.6 a dry run returned a made-up -20 LUFS).
+    proc = run_analysis(cmd, check=False, record=True)
     m = re.search(r"\{[^{}]*\"input_i\"[^{}]*\}", proc.stderr, re.S)
     if proc.returncode != 0 or not m:
         die(f"loudness measurement failed:\n{proc.stderr.strip()[-1500:]}", kind="ffmpeg")
@@ -86,6 +88,10 @@ def main() -> int:
     cmd.append(output)
     run(cmd)
 
+    if STATE.dry_run:
+        # pass 1 measured the input for real; there is no output to measure
+        emit(output, measured={k: stats[k] for k in ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset", "silent")})
+        return 0
     after = measure(output, args.lufs, args.tp, args.lra)
     if not after.get("silent"):
         info(f"result:   {float(after['input_i']):.1f} LUFS, TP {float(after['input_tp']):.1f} dBTP (target {args.lufs} LUFS)")

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)
@@ -358,7 +360,7 @@ def main() -> int:
     check_result = None
     exit_code = 0
     if ck and ck.get("platform") and not STATE.dry_run:
-        proc = run_tool([str(HERE / "check.py"), output, "--platform", ck["platform"], "--json"])
+        proc = run_tool([str(HERE / "check.py"), output, "--platform", ck["platform"], "--json"] + child_args())
         try:
             check_result = json.loads(proc.stdout)
         except ValueError:
@@ -386,7 +388,8 @@ def main() -> int:
         # spec (or the check itself could not run): a failed delivery, reported as one.
         failed_rows = [r["check"] for r in (check_result or {}).get("checks", []) if r.get("status") == "FAIL"]
         die(f"rendered {output} but the {ck['platform']} check failed" + (f": {', '.join(failed_rows)}" if failed_rows else ""),
-            kind="verification", output=output, dry_run=STATE.dry_run, stages=stages_done, check=check_result)
+            kind="verification", output=output, dry_run=STATE.dry_run, stages=stages_done, check=check_result,
+            probe=probe(output, role="output"))
     info(f"rendered {output} via {' → '.join(stages_done)}")
     emit(output, stages=stages_done, check=check_result)
     return 0

package/scripts/report.py

@@ -18,7 +18,7 @@ import tempfile
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
-from _common import STATE, add_common, apply_common, die, emit, info, probe, read_text_or_die, run_tool
+from _common import STATE, add_common, apply_common, child_args, die, emit, info, probe, read_text_or_die, run_tool
 
 HERE = Path(__file__).resolve().parent
 
@@ -26,14 +26,14 @@ HERE = Path(__file__).resolve().parent
 def sheet_b64(path: str, tiles: str = "4x2", width: int = 1200) -> Optional[str]:
     with tempfile.TemporaryDirectory(prefix="ffskill_report_") as tmp:
         png = os.path.join(tmp, "sheet.png")
-        proc = run_tool([str(HERE / "look.py"), path, "--tiles", tiles, "--width", str(width), "-o", png])
+        proc = run_tool([str(HERE / "look.py"), path, "--tiles", tiles, "--width", str(width), "-o", png] + child_args())
         if proc.returncode != 0 or not os.path.exists(png):
             return None
         return base64.b64encode(Path(png).read_bytes()).decode("ascii")
 
 
 def loudness(path: str) -> Dict[str, Any]:
-    proc = run_tool([str(HERE / "loudness.py"), path, "--measure-only"])
+    proc = run_tool([str(HERE / "loudness.py"), path, "--measure-only"] + child_args())
     try:
         d = json.loads(proc.stdout)
         return {"lufs": round(float(d["input_i"]), 1), "tp": round(float(d["input_tp"]), 1), "lra": round(float(d["input_lra"]), 1)}
@@ -42,7 +42,7 @@ def loudness(path: str) -> Dict[str, Any]:
 
 
 def check(path: str, platform: str) -> Optional[Dict[str, Any]]:
-    proc = run_tool([str(HERE / "check.py"), path, "--platform", platform, "--json"])
+    proc = run_tool([str(HERE / "check.py"), path, "--platform", platform, "--json"] + child_args())
     try:
         doc = json.loads(proc.stdout)
     except ValueError:
@@ -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/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

@@ -12,20 +12,23 @@ Examples:
   python3 silence.py talk.mp4 --edl keep.txt                  # also save the kept ranges (START-END per line, cut.py --segments format)
 """
 import argparse
+import os
 import re
 import sys
 from typing import List, Tuple
 
-from _common import STATE, video_args, add_common, apply_common, audio_codec_for, cfr_args, default_output, die, emit, ffmpeg_base, info, is_audio_output, print_json, probe, require_tool, run, x264_args, X264_PRESETS, measured_level_dbfs
+from _common import STATE, video_args, add_common, apply_common, audio_codec_for, cfr_args, default_output, die, emit, ffmpeg_base, info, is_audio_output, print_json, probe, require_tool, run, x264_args, X264_PRESETS, measured_level_dbfs, run_analysis, dry_run_input_pending
 
 SIL_RE = re.compile(r"silence_(start|end): ([0-9.]+)")
 
 
 def detect(path: str, threshold: float, min_silence: float) -> List[Tuple[float, float]]:
+    if dry_run_input_pending(path):
+        return []
     ffmpeg = require_tool("ffmpeg")
     cmd = [ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-vn", "-af",
            f"silencedetect=noise={threshold}dB:d={min_silence}", "-f", "null", "-"]
-    proc = run(cmd, quiet=True, check=False)
+    proc = run_analysis(cmd, check=False, record=True)
     if proc.returncode != 0:
         die(f"silencedetect failed:\n{proc.stderr.strip()[-800:]}", kind="ffmpeg")
     silences: List[Tuple[float, float]] = []
@@ -86,7 +89,7 @@ def main() -> int:
         "removed_seconds": round(removed, 3),
     }
     info(f"{len(silences)} silences, keeping {len(keeps)} ranges: {kept:.2f}s of {duration:.2f}s (removing {removed:.2f}s)")
-    if not silences and not STATE.dry_run:
+    if not silences and not (STATE.dry_run and not os.path.exists(args.input)):
         # Nothing under the threshold is a valid result, not a failure -- but an agent that only
         # sees "0 silences" tends to reach for raw ffmpeg next. Say what the floor actually is and
         # what threshold would bite, so the retry is a flag change, not a workaround.

package/scripts/stabilize.py

@@ -27,7 +27,7 @@ import sys
 import tempfile
 from pathlib import Path
 
-from _common import STATE, add_common, apply_common, aac_args, cfr_args, default_output, die, emit, escape_filter_path, ffmpeg_base, info, probe, require_tool, run, video_args, X264_PRESETS
+from _common import STATE, add_common, apply_common, aac_args, cfr_args, default_output, die, emit, escape_filter_path, ffmpeg_base, info, probe, require_tool, run, video_args, X264_PRESETS, run_analysis, dry_run_input_pending
 
 
 def main() -> int:
@@ -62,18 +62,20 @@ def main() -> int:
         trf = str(Path(tmp) / "transforms.trf")
         trf_arg = escape_filter_path(trf)
 
-        if not STATE.dry_run:
-            ffmpeg = require_tool("ffmpeg")
-            detect_vf = f"vidstabdetect=shakiness={args.shakiness}:result={trf_arg}"
-            if args.tripod:
-                # A frame number, not a boolean: frame 1 is the standard reference for "lock to
-                # this fixed frame" (mirrors vidstabtransform's own tripod=1 below).
-                detect_vf += ":tripod=1"
-            detect_cmd = [ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-y", "-i", args.input,
-                          "-vf", detect_vf, "-f", "null", "-"]
-            proc = run(detect_cmd, check=False)
+        ffmpeg = require_tool("ffmpeg")
+        detect_vf = f"vidstabdetect=shakiness={args.shakiness}:result={trf_arg}"
+        if args.tripod:
+            # A frame number, not a boolean: frame 1 is the standard reference for "lock to
+            # this fixed frame" (mirrors vidstabtransform's own tripod=1 below).
+            detect_vf += ":tripod=1"
+        detect_cmd = [ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-y", "-i", args.input,
+                      "-vf", detect_vf, "-f", "null", "-"]
+        # Pass 1 is a measurement into a temp file (the transforms), so it runs under --dry-run
+        # as well; only pass 2, the write, is skipped there.
+        if not dry_run_input_pending(args.input):
+            proc = run_analysis(detect_cmd, check=False, record=True)
             if proc.returncode != 0:
-                die(f"stabilization analysis (pass 1) failed:\n{proc.stderr.strip()[-1500:]}")
+                die(f"stabilization analysis (pass 1) failed:\n{proc.stderr.strip()[-1500:]}", kind="ffmpeg")
 
         crop_mode = {"keep": 0, "black": 1}[args.crop]
         transform_vf = f"vidstabtransform=input={trf_arg}:smoothing={args.smoothing}:crop={crop_mode}:zoom={args.zoom:g}:optzoom=1"