ffmpeg-skill 1.4.7 → 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.7",
+  "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/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")
@@ -912,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')."""
@@ -928,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
@@ -1002,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:

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

@@ -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)

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/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/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: