ffmpeg-skill 2.3.0 → 2.3.2

package/SKILL.md

@@ -5,13 +5,13 @@ description: 'Edit video and audio with local FFmpeg from natural-language reque
 
 # ffmpeg-skill
 
-Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>/scripts/<name>.py`, and delivery templates in `templates/`. This file is enough to do a job: the table below routes the request, and `--help` on the script about to run is the cheapest full flag list. A reference file costs as much as this one; open one only for a question you have: `references/scripts.md` (every flag of all 42 scripts), `references/devices.md` (iPhone HDR, GoPro, DJI, screen recordings, Zoom), `references/gotchas.md` (the long form of the one-line rules at the end). MCP: `tools/list` shows only the core 12 by default; the other 42 (per this table) stay callable by name via `tools/call`, described by `contract --json`; set `FFMPEG_SKILL_MCP_FULL=1` for all 42.
+Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>/scripts/<name>.py`, and delivery templates in `templates/`. This file is enough to do a job: the table below routes the request, and `--help` on the script about to run is the cheapest full flag list. A reference file costs as much as this one; open one only for a question you have: `references/scripts.md` (every flag of all 42 scripts), `references/devices.md` (iPhone HDR, GoPro, DJI, screen recordings, Zoom), `references/gotchas.md` (the long form of the one-line rules at the end). MCP: `tools/list` shows only the core 12 by default; the other 30 (per this table) stay callable by name via `tools/call`, described by `contract --json`; set `FFMPEG_SKILL_MCP_FULL=1` for all 42.
 
 Shared flags, on every script: `--dry-run`; `--json` (output path, a probe of the output, the commands run); `--json-brief` (status/output/verified plus a `summary`; prefer on writing steps); `--fast` (preview quality); `--progress`; `--timeout SECONDS` (`kind: timeout`, default 1800); `--overwrite` (step 7); `--plan FILE` (the dry run as a plan `render.py FILE` runs later; refuses if an input changed). Re-encoding tools also take `--codec h264|hevc|av1|prores` and `--quality N`: unset, SDR is x264, HDR is x265 Main10; `prores` needs `-o NAME.mov`, `h264` refuses HDR (`color.py --to-sdr` first).
 
 Writing tools run nothing under `--dry-run`; the measuring tools (`probe`, `check`, `sync`, `multicam`, `scenes`, `cropdetect`, `report`, `silence`, `loudness`, `stabilize`) may still run ffmpeg/ffprobe, skipping artifacts/side files (`--edl`, `--sheet`, a generated `.ass`); `verify` ignores the flag. Per tool: `contract --json` `dry_run`.
 
-## Workflow (always follow this order)
+## Workflow (in this order)
 
 0. **Environment, only on failure.** Never start a job with `doctor`: a broken machine fails with `kind: missing_tool` or an ffmpeg error naming the filter/encoder. Run `python3 <skill-dir>/scripts/_contract.py doctor` (or `npx ffmpeg-skill doctor`) after such a failure, or when asked what the machine can do: read `ok`/`usable`, report the missing capability. `contract --json`'s tool schema is for a *planning* agent, not this workflow.
 1. **Probe what you must plan from.** Run `probe.py` on each input you plan from — duration, fps, resolution, codecs, channels, `variable_frame_rate_suspected` — and whenever the user asks about a file. No separate probe before every edit: every writing tool's `--json` already carries its input and a probe of the output. Plan from real numbers, never assumptions.
@@ -96,7 +96,7 @@ Timestamp flags (`--start`, `--end`, `--at`, `--from`, `--duration`, `--offset`,
 | "add subtitles from this SRT", "burn in captions" | `caption.py input.mp4 --srt subs.srt` |
 | "caption it with these lines" (text with times) | `caption.py input.mp4 --text cues.txt` |
 | "keep the subtitles toggleable", "mux in an SRT" | `caption.py input.mp4 --srt subs.srt --mode mux`; repeat `--srt file:lang` for several languages, `.mkv` for more than two |
-| "the captions are tiny / three lines on a Short", "don't chop the sentence" | `caption.py` shrinks the size until the cue fits `--max-lines` before splitting it (`--fit-size off` = 1.16 behaviour, `--min-size` the floor). Keep the template's `--max-lines` (2 on a vertical) and let the size drop; raising it to dodge a shrink stacks two words per line. A word still wider than the column at the floor is sliced at the edge (hyphen preferred), never rewritten, automatic; `broken_inside_word` in the JSON counts it |
+| "the captions are tiny / three lines on a Short", "don't chop the sentence" | `caption.py` shrinks the size until the cue fits `--max-lines` before splitting it (`--fit-size off` keeps `--size` and splits instead, `--min-size` the floor). Keep the template's `--max-lines` (2 on a vertical) and let the size drop; raising it to dodge a shrink stacks two words per line. A word still wider than the column at the floor is sliced at the edge (hyphen preferred), never rewritten, automatic; `broken_inside_word` in the JSON counts it |
 | "transcribe it and caption it" | `caption.py input.mp4 --transcribe --animate pop --karaoke` (needs a local whisper; else `--text`) |
 | "TikTok-style captions with the words popping" | `caption.py input.mp4 --text cues.txt --animate pop --karaoke` |
 | "our logo top-right", "a watermark" | `overlay.py input.mp4 --image logo.png --position top-right --scale 200` |

package/docs/contract.md

@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
 | 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 (`2.3.0`) | any release |
+| `skill.version` | the npm / package.json version (`2.3.2`) | 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`
@@ -119,7 +119,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
   "contract_version": "1.0",
   "deprecated": [],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "2.3.0", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.3.2", "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"},
@@ -225,7 +225,8 @@ subtitle/LUT/font files a filter reads. Tools that print their document without
 (`probe`, the analysis tools) still write the plan at exit; `verify.py` and `render.py`
 refuse `--plan` (their steps run for real; a project file is already a plan). `render.py FILE` executes a plan:
 it refuses (`kind: input`) when an input's size or head/tail hash differs from the plan,
-runs the tool with the planned `argv`, then the verify steps, and reports `plan`, `tool`,
+runs the tool with the planned `argv`, then the verify steps (a `check` step may also carry
+`"content": true`, added by hand, for `check.py --content`), and reports `plan`, `tool`,
 `tool_result` and `check`. `plan_version` is bumped when the document's shape changes.
 
 ### Repeatability
@@ -352,7 +353,10 @@ read (`ffmpeg -filters` in a layout the parser does not recognise, or ffmpeg exi
 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
+`errors` lists the unreadable ones. `filter:drawtext` is also rendered once, with the
+`fontfile=` the tools pass by default: a crash there makes it `missing`; a crash only on a
+bare fontconfig lookup leaves it `available` and adds a `notes` entry (`--font-file`, not a
+bare `--font <family>`, on that machine). 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/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "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",

package/references/scripts.md

@@ -631,7 +631,8 @@ A plan is a single tool's dry run as an artifact: `cut.py in.mp4 --start 2 --end
 head+tail), commands, output, verify}` and runs nothing. `render.py cut.json`
 re-fingerprints the inputs (refusing, `kind: input`, if any changed since the
 plan), runs the tool with the planned argv, then the verify steps (probe; `check`
-for a `--platform` or a platform export preset), and reports `plan`, `tool`,
+for a `--platform` or a platform export preset; add `"content": true` to a check
+step for the black/frozen/silence rows), and reports `plan`, `tool`,
 `tool_result` and `check`. Show the plan to the user, get the yes, execute:
 one round trip instead of re-deriving the command.
 `"export": {"preset": "reels", "normalize": true}` forwards `export.py --normalize`

package/scripts/_ass_overlay.py

@@ -29,7 +29,7 @@ EMOJI_SENTINEL = "\ue000"
 
 
 def emoji_placeholder(box_px: float) -> str:
-    """The ASS override that reserves exactly `box_px` of advance and draws nothing.
+    r"""The ASS override that reserves exactly `box_px` of advance and draws nothing.
 
     Measured, not assumed (1.15 spec, open question 2). U+2588 FULL BLOCK is NOT 1.0 em: its
     advance measured 0.83 em in FreeSans, 0.79 in WenQuanYi Zen Hei and 0.66 in DejaVu Sans,

package/scripts/_common/drawtext.py

@@ -98,7 +98,7 @@ def escape_drawtext(text: str) -> str:
 
 
 def drawtext_text_opts(text: str, tmpdir: "Optional[str]" = None) -> str:
-    """`textfile=<path>:expansion=none` for drawtext -- the one route that is provably safe for
+    r"""`textfile=<path>:expansion=none` for drawtext -- the one route that is provably safe for
     every character on every build shape this repo uses.
 
     The filter-graph parser never sees the text at all: only the PATH is parsed, and

package/scripts/_contract.py

@@ -668,22 +668,42 @@ def _drawtext_probe() -> Dict[str, Any]:
     present and doctor used to report the capability `available` anyway; every tool that actually
     used it (look, scenes --sheet, overlay --text, graphics) then crashed on first real use (#100).
 
-    This runs the cheapest real drawtext render there is: a one-frame synthetic clip, no font=
-    given at all (ffmpeg's own default resolution -- the same path that crashed). A clean exit
-    means drawtext genuinely works here. Anything that could not prove either way (no ffmpeg,
-    timeout, an ordinary nonzero exit with a real ffmpeg error) is `unknown`, same "unknown is not
-    missing" principle as every other capability here. A crash specifically -- killed by signal on
-    POSIX, or an unhandled access violation surfacing as a huge unsigned exit code on Windows -- is
-    the one case this function exists to catch, and folds into `missing`: the filter is present in
-    the build but cannot actually be used as ffmpeg's own default would use it.
+    This runs the cheapest real drawtext render there is: a one-frame synthetic clip, with the
+    fontfile= the tools themselves pass by default (_common.fonts.default_font_file), or no font
+    at all where none resolves. A clean exit means drawtext genuinely works for the tools here.
+    Anything that could not prove either way (no ffmpeg, timeout, an ordinary nonzero exit with a
+    real ffmpeg error) is `unknown`, same "unknown is not missing" principle as every other
+    capability here. A crash specifically -- killed by signal on POSIX, or an unhandled access
+    violation surfacing as a huge unsigned exit code on Windows -- folds into `missing`. When the
+    fontfile= render works but a bare one crashes, drawtext stays available and the result
+    carries a `note`: only a fontconfig lookup (`--font <family>` with no file) would crash.
     """
     exe = shutil.which("ffmpeg")
     if not exe:
         return {"status": "unknown", "detail": "ffmpeg not on PATH"}
+    # Probe the way the tools call drawtext: with the fontfile= they pick by default (#298). On a
+    # build whose fontconfig lookup crashes (#100) the tools still render, because they never ask
+    # fontconfig; probing only the bare `drawtext=text=x` reported such a machine as missing
+    # drawtext altogether. The bare render still runs, and its crash is reported as a note: it is
+    # the path `--font <family>` without a file would take.
+    from _common.fonts import default_font_file
+    from _common.decision import escape_filter_path
+    font_file = default_font_file(_default_font())
+    result = _drawtext_render(exe, f"drawtext=fontfile={escape_filter_path(font_file)}:text=x" if font_file else "drawtext=text=x")
+    if font_file and result["status"] == "available":
+        bare = _drawtext_render(exe, "drawtext=text=x")
+        if bare["status"] == "missing":
+            result["note"] = ("drawtext renders with fontfile= (what every drawtext tool passes by default) but crashes "
+                              "when it has to resolve a font through fontconfig: pass --font-file, not a bare --font "
+                              "<family>, on this machine (https://github.com/kajisho5/ffmpeg-skill/issues/100)")
+    return result
+
+
+def _drawtext_render(exe: str, vf: str) -> Dict[str, Any]:
     try:
         proc = subprocess.run(
             [exe, "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "color=c=black:s=64x64:d=1",
-             "-vf", "drawtext=text=x", "-frames:v", "1", "-f", "null", "-"],
+             "-vf", vf, "-frames:v", "1", "-f", "null", "-"],
             stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, encoding="utf-8", errors="replace", timeout=_DETECT_TIMEOUT,
         )
     except subprocess.TimeoutExpired:
@@ -695,9 +715,8 @@ def _drawtext_probe() -> Dict[str, Any]:
     if proc.returncode < 0 or proc.returncode >= 0x80000000:
         return {"status": "missing",
                 "detail": f"drawtext render crashed (exit {proc.returncode}) instead of failing cleanly -- "
-                           "the filter is present in this build but cannot be used as-is, likely a fontconfig "
-                           "resolution crash (see https://github.com/kajisho5/ffmpeg-skill/issues/100); "
-                           "pass an explicit --font-file to every drawtext tool as a workaround"}
+                           "the filter is present in this build but cannot render even with the fontfile= the "
+                           "tools pass (see https://github.com/kajisho5/ffmpeg-skill/issues/100)"}
     tail = " ".join(proc.stderr.strip().splitlines()[-2:])
     return {"status": "unknown", "detail": f"drawtext probe exited {proc.returncode}: {tail}"}
 
@@ -809,6 +828,8 @@ def doctor() -> Dict[str, Any]:
                 # than downgrading it; see _drawtext_probe()'s own docstring for why a crash alone
                 # is the one case this exists to catch.
                 probe = _drawtext_probe()
+                if probe.get("note"):
+                    drawtext_probe = probe
                 if probe["status"] == "missing":
                     drawtext_probe = probe
                     state[cap] = "missing"
@@ -832,6 +853,7 @@ def doctor() -> Dict[str, Any]:
     errors = [f"{k}: {v['detail']}" for k, v in listings.items() if v["status"] in ("unparsed", "failed")]
     if drawtext_probe is not None and drawtext_probe["status"] != "available":
         errors.append(f"filter:drawtext: {drawtext_probe['detail']}")
+    notes = [f"filter:drawtext: {drawtext_probe['note']}"] if drawtext_probe and drawtext_probe.get("note") else []
     return {
         "version": skill_version(),
         "python": ".".join(str(x) for x in sys.version_info[:3]),
@@ -843,6 +865,7 @@ def doctor() -> Dict[str, Any]:
         "unknown": unknown,
         "detection": {k: {"status": v["status"], "count": len(v["names"]), "detail": v["detail"]} for k, v in listings.items()},
         "errors": errors,
+        **({"notes": notes} if notes else {}),
         "ok": not missing_required and not unknown_required,
         "tools": _tool_usability(state),
         "gpu_encoders": _gpu_encoders(listings["encoders"]),

package/scripts/caption.py

@@ -954,7 +954,7 @@ def main() -> int:
     sty.add_argument("--max-lines", type=int, default=2, help="most lines one cue may occupy; a longer cue is split into consecutive cues (default 2)")
     sty.add_argument("--fit-size", choices=["auto", "on", "off"], default="auto",
                      help="shrink the caption size until the cue fits --max-lines, BEFORE splitting it: "
-                          "'auto' (default) only when no --size was given, 'on' always, 'off' for 1.16 behaviour")
+                          "'auto' (default) only when no --size was given, 'on' always, 'off' keeps --size and splits the cue instead")
     sty.add_argument("--min-size", type=int, default=None,
                      help="smallest size --fit-size may use, in ASS points (default 13 = 4.5%% of the frame height, "
                           "the legibility floor)")

package/scripts/render.py

@@ -729,8 +729,11 @@ def execute_plan(plan: Dict[str, Any], path: str) -> int:
     check_result = None
     exit_code = 0
     for step in plan.get("verify") or []:
-        if step.get("tool") == "check" and step.get("platform") and output:
-            cp = run_tool([str(HERE / "check.py"), output, "--platform", step["platform"], "--json"] + child_args())
+        # a check step names a platform, asks for check.py --content's black/frozen/silence rows
+        # ("content": true), or both -- the same keys a project's "check" stage takes
+        if step.get("tool") == "check" and (step.get("platform") or step.get("content") is True) and output:
+            cp = run_tool([str(HERE / "check.py"), output] + (["--platform", str(step["platform"])] if step.get("platform") else [])
+                          + (["--content"] if step.get("content") is True else []) + ["--json"] + child_args())
             try:
                 check_result = json.loads(cp.stdout)
             except ValueError:
@@ -742,7 +745,7 @@ def execute_plan(plan: Dict[str, Any], path: str) -> int:
     # same command run by hand)
     if exit_code:
         failed_rows = [r["check"] for r in (check_result or {}).get("checks", []) if r.get("status") == "FAIL"]
-        info(f"plan done: {output}, but the {check_result.get('platform')} check failed" + (f": {', '.join(failed_rows)}" if failed_rows else ""))
+        info(f"plan done: {output}, but the {check_result.get('platform') or 'content'} check failed" + (f": {', '.join(failed_rows)}" if failed_rows else ""))
     else:
         info(f"plan done: {output}")
     emit(output, plan=path, tool=tool, stages=[tool] + (["check"] if check_result else []), check=check_result, tool_result=doc,