ffmpeg-skill 3.8.16 → 3.8.18

package/docs/contract.md

@@ -26,7 +26,7 @@ The contract is derived from the code that runs, not maintained beside it:
 | Field | Meaning | Changes when |
 |---|---|---|
 | `contract_version` | shape of this document (`2.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`3.8.16`) | any release |
+| `skill.version` | the npm / package.json version (`3.8.18`) | 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`
@@ -154,7 +154,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
   "deprecated": [],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"},
               {"what": "running on FFmpeg 5.x (the requirements.ffmpeg floor)", "since": "2.14.0", "replacement": "FFmpeg 6.1 or later; ...", "removed_in": "3.0.0", "where": "behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "3.8.16", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "3.8.18", "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.10 (standard library only)", "ffmpeg": ">=6.1", "ffprobe": ">=6.1"},
@@ -956,7 +956,7 @@ A refusal also carries `error.reason`, a stable snake_case code for *why*
 `output_is_directory`, `output_dir_missing`, `output_dir_not_writable`, `output_locked`,
 `output_container_codecs` (a `.webm` output for an H.264/HEVC or AAC encode, which WebM cannot hold),
 `media_path_is_url` (`subfile,...:` included), `media_path_is_playlist` (an HLS, DASH, IMF or ffconcat playlist given as media, DASH and IMF told by content whatever the file is called), `media_path_has_line_break` (a path with a line break, which a concat list cannot hold),
-`output_looks_like_option` (an output starting with `-`, other than `-` for stdout), `output_extension_missing` (a media output with no file extension, which leaves ffmpeg no container to choose), `output_path_taken` (two files one run writes share a path), `media_path_not_a_file` (a FIFO or device as input), `silence.py --timemap`'s `timemap_path_taken`, `join.py --copy`'s `join_copy_mismatch`,
+`output_looks_like_option` (an output starting with `-`, other than `-` for stdout), `output_extension_missing` (a media output with no file extension, which leaves ffmpeg no container to choose), `output_path_taken` (two files one run writes share a path), `media_path_not_a_file` (a FIFO or device as input), `still_unreadable` (a file with an image name that ffmpeg cannot decode as one), `silence.py --timemap`'s `timemap_path_taken`, `join.py --copy`'s `join_copy_mismatch`,
 `render.py`'s `plan_*` reasons, `--codec av1`/`prores`'s `encoder_missing` and
 `encoder_list_unreadable`, and `--transcribe`'s `asr_engine_missing`, `no_speech`, `engine_failed`
 and `english_only`), and `error.details`, the facts the message is written from, so a

package/mcp/server.py

@@ -19,6 +19,8 @@ Claude Desktop / Claude Code config example:
 import json
 import os
 import sys
+import queue
+import threading
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
@@ -31,13 +33,22 @@ import _contract  # noqa: E402  (the contract is the only source of tool names,
 import _common  # noqa: E402  (run_tool: the outer wall-clock ceiling on a dispatched tool)
 
 _SPECS: Dict[str, Dict[str, Any]] = {}
+_SPECS_LOCK = threading.Lock()
 
 
 def specs() -> Dict[str, Dict[str, Any]]:
-    """ToolSpecs from the contract, generated once per process (argparse -> ToolSpec -> here)."""
+    """ToolSpecs from the contract, generated once per process (argparse -> ToolSpec -> here).
+
+    Built under a lock and published whole: _contract.build() swaps the process-wide argparse
+    parse_args and sys.argv while it reads each tool's parser, so two first uses at once (a
+    tools/call on the worker thread and a tools/list on the reading loop) could each restore the
+    other's swap and let a tool's main() run for real (review of #530). main() also builds it
+    before the worker starts."""
     if not _SPECS:
-        for spec in _contract.build(detect=False)["tools"]:
-            _SPECS[spec["name"]] = spec
+        with _SPECS_LOCK:
+            if not _SPECS:
+                built = {spec["name"]: spec for spec in _contract.build(detect=False)["tools"]}
+                _SPECS.update(built)
     return _SPECS
 
 
@@ -149,7 +160,9 @@ def timeout_from_call(args: Dict[str, Any]) -> float:
         return _common._env_timeout()
 
 
-def call_tool(name: str, args: Dict[str, Any]) -> Dict[str, Any]:
+def call_tool(name: str, args: Dict[str, Any], on_start: Any = None) -> Dict[str, Any]:
+    """tools/call. `on_start(child)` is handed the tool's process once it runs (the stdio loop
+    keeps it, to stop the call if the client cancels it)."""
     script = SCRIPTS / f"{name}.py"
     if name not in specs() or not script.exists():
         return {"isError": True, "content": [{"type": "text", "text": f"unknown tool {name}"}]}
@@ -165,7 +178,8 @@ def call_tool(name: str, args: Dict[str, Any]) -> Dict[str, Any]:
     env = {k: v for k, v in os.environ.items() if k != _contract.READ_ONLY_ENV}
     if _contract.mcp_read_only(specs()[name]):
         env[_contract.READ_ONLY_ENV] = "1"
-    proc = _common.run_tool([str(script)] + argv, per_call=per_call, env=env)
+    started = {"on_start": on_start} if on_start is not None else {}
+    proc = _common.run_tool([str(script)] + argv, per_call=per_call, env=env, **started)
     stdout = proc.stdout.strip()
     text = stdout
     structured = None
@@ -179,9 +193,13 @@ def call_tool(name: str, args: Dict[str, Any]) -> Dict[str, Any]:
         failed: Dict[str, Any] = {"isError": True, "content": [{"type": "text", "text": f"{name} failed (exit {proc.returncode})\n{tail}"}]}
         # The child's own failure document (status, error.kind/code/hint, commands) is the
         # machine-readable half of the contract; dropping it here left an MCP caller regex-
-        # parsing prose to tell a timeout from a missing binary.
+        # parsing prose to tell a timeout from a missing binary. structuredContent is a field of
+        # protocol revisions after the 2024-11-05 this server negotiates, so a client of that
+        # revision reads only `content`: the document is also a second text block there (A22,
+        # #465), as a success's document is the text block.
         if isinstance(structured, dict):
             failed["structuredContent"] = structured
+            failed["content"].append({"type": "text", "text": stdout})
         return failed
     if structured is None:
         text = stdout or "\n".join(proc.stderr.strip().splitlines()[-5:])
@@ -206,7 +224,7 @@ def tool_list() -> List[Dict[str, Any]]:
     return [_contract.mcp_tool(all_specs[name]) for name in names]
 
 
-def handle(req: Dict[str, Any]) -> Dict[str, Any]:
+def handle(req: Dict[str, Any], on_start: Any = None) -> Dict[str, Any]:
     method = req.get("method")
     params = req.get("params") or {}
     if method == "initialize":
@@ -219,7 +237,7 @@ def handle(req: Dict[str, Any]) -> Dict[str, Any]:
     if method == "tools/list":
         return {"tools": tool_list()}
     if method == "tools/call":
-        return call_tool(params.get("name", ""), params.get("arguments") or {})
+        return call_tool(params.get("name", ""), params.get("arguments") or {}, on_start=on_start)
     if method == "prompts/list":
         # roadmap 1.20.0: the five workflow recipes (reel, podcast, multicam, delivery_check, hdr)
         return {"prompts": _contract.mcp_prompt_list()}
@@ -236,6 +254,101 @@ def handle(req: Dict[str, Any]) -> Dict[str, Any]:
     raise KeyError(method)
 
 
+# A24 (#465): tools/call runs on a worker thread, so the loop that reads requests keeps reading
+# while a tool runs -- a ping is answered at once, and `notifications/cancelled` stops the call it
+# names (its tool gets SIGTERM, stops its ffmpeg and removes its partial output, as on any SIGTERM)
+# and no response is sent for it, as the protocol asks. The tools still run one at a time, in the
+# order they were called, and answer in that order (one encode at a time, as before); a call
+# cancelled while it waits for its turn never starts.
+_QUEUE: "queue.Queue[Optional[Dict[str, Any]]]" = queue.Queue()
+_CALLS: Dict[str, Dict[str, Any]] = {}  # request id (as JSON) -> {"proc": Popen or None, "cancelled": bool}
+_CALLS_LOCK = threading.Lock()
+_WRITE_LOCK = threading.Lock()
+
+
+def _key(request_id: Any) -> str:
+    return json.dumps(request_id, sort_keys=True)
+
+
+def _write(out: Any, resp: Dict[str, Any]) -> None:
+    with _WRITE_LOCK:
+        out.write((json.dumps(resp) + "\n").encode("utf-8"))
+        out.flush()
+
+
+def _stop(proc: Any) -> None:
+    """Stop a cancelled call's tool: on POSIX SIGTERM, whose handler stops its ffmpeg and removes
+    the partial output and the lock; on Windows, where no handler runs, its whole process tree
+    (taskkill /T /F), so its ffmpeg does not go on encoding beside the next call. Returns once that
+    has been done (runner.terminate_tree())."""
+    try:
+        _common.runner.terminate_tree(proc)
+    except OSError:
+        pass
+
+
+def cancel(params: Any) -> None:
+    """notifications/cancelled: stop the named call if it is running, or keep it from starting."""
+    if not isinstance(params, dict) or "requestId" not in params:
+        return
+    with _CALLS_LOCK:
+        entry = _CALLS.get(_key(params["requestId"]))
+        if entry is None:
+            return  # finished already, or never seen: nothing to stop
+        entry["cancelled"] = True
+        proc = entry.get("proc")
+        if proc is None:
+            return  # not started: the worker never starts it
+        stopped = entry["stopped"] = threading.Event()
+    try:
+        _stop(proc)
+    finally:
+        stopped.set()  # the worker waits for this before it starts the next call
+
+
+def _respond(req: Dict[str, Any], on_start: Any = None) -> Dict[str, Any]:
+    try:
+        return {"jsonrpc": "2.0", "id": req["id"], "result": handle(req, on_start=on_start)}
+    except KeyError as exc:
+        return {"jsonrpc": "2.0", "id": req["id"], "error": {"code": -32601, "message": f"method not found: {exc}"}}
+    except Exception as exc:  # noqa: BLE001
+        return {"jsonrpc": "2.0", "id": req["id"], "error": {"code": -32000, "message": str(exc)}}
+
+
+def _call_worker(out: Any) -> None:
+    """Run the queued tools/call requests one at a time until the None that ends the input."""
+    while True:
+        item = _QUEUE.get()
+        if item is None:
+            return
+        req, entry = item["req"], item["entry"]
+
+        def started(proc: Any, entry: Dict[str, Any] = entry) -> None:
+            with _CALLS_LOCK:
+                entry["proc"] = proc
+                cancelled = entry["cancelled"]
+            if cancelled:
+                _stop(proc)
+
+        resp = None
+        try:
+            if not entry["cancelled"]:
+                resp = _respond(req, on_start=started)
+            # a call cancelled while it ran: the next one starts only once the stop is done (on
+            # Windows the tree kill may still be ending the tool's ffmpeg after the tool exited)
+            with _CALLS_LOCK:
+                stopped = entry.get("stopped")
+            if stopped is not None:
+                stopped.wait(_common.runner.TREE_KILL_TIMEOUT + 5)
+        finally:
+            with _CALLS_LOCK:
+                key = _key(req["id"])
+                if _CALLS.get(key) is entry:
+                    del _CALLS[key]
+        if resp is not None and not entry["cancelled"]:
+            _write(out, resp)
+
+
 def version() -> str:
     try:
         return json.loads((HERE.parent / "package.json").read_text())["version"]
@@ -256,6 +369,12 @@ def main() -> int:
         return 0
     stdin = sys.stdin.buffer
     stdout = sys.stdout.buffer
+    try:
+        specs()  # built here, once, before the worker thread can need it too (review of #530)
+    except Exception:  # noqa: BLE001
+        pass  # a contract that cannot be built fails each request that needs it (under the lock), not the server
+    worker = threading.Thread(target=_call_worker, args=(stdout,), daemon=True)
+    worker.start()
     for raw in stdin:
         line = raw.decode("utf-8", errors="replace").strip()
         if not line:
@@ -265,10 +384,9 @@ def main() -> int:
         except ValueError as exc:
             # JSON-RPC 2.0: a line that is not JSON is answered with -32700 and id null, not
             # dropped -- a client whose request was mangled in transit otherwise waits for an
-            # answer that never comes, with nothing to say why
-            resp = {"jsonrpc": "2.0", "id": None, "error": {"code": -32700, "message": f"parse error: {exc}"}}
-            stdout.write((json.dumps(resp) + "\n").encode("utf-8"))
-            stdout.flush()
+            # answer that never comes, with nothing to say why. Through _write(), as every
+            # response: the worker writes too, and a line written beside its own would split it
+            _write(stdout, {"jsonrpc": "2.0", "id": None, "error": {"code": -32700, "message": f"parse error: {exc}"}})
             continue
         # json.loads accepts any valid JSON value, not just an object -- a bare `42`, `null`,
         # `true` or `[1,2]` line parses fine but isn't a JSON-RPC request. Without this guard,
@@ -279,16 +397,20 @@ def main() -> int:
         if not isinstance(req, dict):
             continue
         if "id" not in req:  # notification
+            # only a JSON-RPC 2.0 notification cancels a call (review of #530: a "jsonrpc": "1.0"
+            # line stopped the running tool); anything else is ignored, as before
+            if req.get("jsonrpc") == "2.0" and req.get("method") == "notifications/cancelled":
+                cancel(req.get("params"))
             continue
-        try:
-            result = handle(req)
-            resp = {"jsonrpc": "2.0", "id": req["id"], "result": result}
-        except KeyError as exc:
-            resp = {"jsonrpc": "2.0", "id": req["id"], "error": {"code": -32601, "message": f"method not found: {exc}"}}
-        except Exception as exc:  # noqa: BLE001
-            resp = {"jsonrpc": "2.0", "id": req["id"], "error": {"code": -32000, "message": str(exc)}}
-        stdout.write((json.dumps(resp) + "\n").encode("utf-8"))
-        stdout.flush()
+        if req.get("method") == "tools/call":
+            entry = {"proc": None, "cancelled": False}
+            with _CALLS_LOCK:
+                _CALLS[_key(req["id"])] = entry
+            _QUEUE.put({"req": req, "entry": entry})
+            continue
+        _write(stdout, _respond(req))
+    _QUEUE.put(None)  # end of input: the calls already queued run and answer before the server exits
+    worker.join()
     return 0
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "3.8.16",
+  "version": "3.8.18",
   "mcpName": "io.github.kajisho5/ffmpeg-skill",
   "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": [

package/references/scripts.md

@@ -656,6 +656,7 @@ ends -- a cutaway, not a splice, so the output is exactly as long as A. One
 `--insert`/`--at` pair per cutaway (`--duration`, `--end`, `--from` are per
 cutaway too, or given once for all; defaults 4 s and 0); windows may not
 overlap or run past A's end, and B must have enough material from `--from`.
+A still picture as B is shown for the whole window.
 `--audio a` (default) keeps A's audio untouched and stream-copied; `b` replaces
 it inside each window with B's; `mix` plays both. The output's length is
 verified against A's.
@@ -717,7 +718,8 @@ bottom-right corner; `--label none` skips it. No audio unless `--audio-from`
 picks one input's track by index -- mixing every clip's audio together is
 rarely useful for a comparison grid, so this tool never does that silently.
 Runs only as long as the shortest clip by default; `--pad` instead holds
-each shorter clip's last frame (with silence) out to the longest.
+each shorter clip's last frame (with silence) out to the longest. A still
+picture fills its cell for the grid's length; a grid of stills only is refused.
 
 ### silence.py — remove dead air / jump cuts
 ```
@@ -1192,7 +1194,8 @@ hand-built step:
 and `check.py --platform podcast`. `--template all` renders `tiktok, reels, shorts, youtube, x,
 linkedin, facebook` (not the audio template, not the `youtube-shorts` alias) into
 `<stem>_<platform>.mp4`, runs each platform's check and writes `<stem>_pack.md` with one row per
-destination; `report.py --pack <stem>_pack.md` renders that table as a single HTML page. A pack
+destination; `report.py --pack <stem>_pack.md` renders that table (and refuses a file whose first
+table has other columns) as a single HTML page. A pack
 whose destinations did not all pass exits non-zero with the per-destination rows in `pack`.
 
 `audiogram` (1.16) is the one-call form of the podcast-to-video job: an `audiogram` stage runs
@@ -1607,7 +1610,9 @@ like column; `--margin PX` sets all four edges and wins over `--platform`.
 read by `caption.py` and, for `font` and `colour`, by `graphics.py`; it wins
 over the older top-level `caption` block where both set the same key, and that
 block still carries the burn-in-only defaults (`animate`, `karaoke`, `bold`,
-`outline`). `"lang"` is the script hint `--lang` would give. When a
+`outline`). `"lang"` is the script hint `--lang` would give. A key no tool
+reads is refused, naming it (`loudness`, read by none, gets a note), and a
+`font_file` that is not a font is refused where text is drawn with it. When a
 user mentions brand guidelines, colours, "our font" or a logo, ask for or
 write a brand.json once and reuse it across every output.
 

package/scripts/_common/alpha.py

@@ -122,6 +122,7 @@ def frame_means(cmd_head: List[str], path: str, chain: str) -> "Dict[str, object
     # Read frame by frame as ffmpeg writes them, not the whole pipe at once: the raw copy is 2304
     # bytes a frame (~250 MB for an hour at 30 fps), the per-frame means a float each. The same
     # wall-clock limit as run_analysis(), which this replaces here.
+    cmd = _runner.guard_still_patterns(cmd)  # a still named with a % is that one file (#465 A7)
     _runner._refuse_url_media(cmd)
     limit = _runner._limit_for(cmd)
     size = w * h

package/scripts/_common/color.py

@@ -372,11 +372,40 @@ def validate_color(value: str, flag: str = "--color") -> str:
     demonstrated filter-graph injection: --color "black,drawtext=text=..." renders arbitrary burnt-in
     text), not just an odd colour. This is the same "no filter graph accepted from the caller"
     invariant every other typed flag in this codebase already holds to."""
-    if not _COLOR_TOKEN_RE.match(value):
+    m = _COLOR_TOKEN_RE.match(value)
+    if not m:
         die(f"{flag} must be a plain colour (a name, 0xRRGGBB[AA], or #RRGGBB[AA], optionally @alpha), got '{value}'")
+    word = m.group(1)
+    if word[0] not in "#0" and word.lower() not in FFMPEG_COLOR_NAMES and not _BARE_HEX.match(word):
+        # A189 (#465): any word passed, and an unknown name failed inside ffmpeg ("Cannot find
+        # color") as kind ffmpeg, after a dry run that had said completed. ffmpeg reads a word as
+        # one of its names, or else as bare hex digits.
+        die(f"{flag} {value!r}: {word!r} is not a colour name ffmpeg knows (`ffmpeg -colors` lists them) "
+            "nor six or eight hex digits; use a name such as white, or 0xRRGGBB")
     return value
 
 
+# The names av_parse_color() looks up, case-insensitively (`ffmpeg -colors`, the same list in 6.1
+# through 8), plus the two it treats as a random colour. A word that is none of them is read as
+# hex digits without a prefix, which works for six or eight of them.
+FFMPEG_COLOR_NAMES = frozenset((
+    "aliceblue antiquewhite aqua aquamarine azure beige bisque black blanchedalmond blue blueviolet brown "
+    "burlywood cadetblue chartreuse chocolate coral cornflowerblue cornsilk crimson cyan darkblue darkcyan "
+    "darkgoldenrod darkgray darkgreen darkkhaki darkmagenta darkolivegreen darkorange darkorchid darkred "
+    "darksalmon darkseagreen darkslateblue darkslategray darkturquoise darkviolet deeppink deepskyblue dimgray "
+    "dodgerblue firebrick floralwhite forestgreen fuchsia gainsboro ghostwhite gold goldenrod gray green "
+    "greenyellow honeydew hotpink indianred indigo ivory khaki lavender lavenderblush lawngreen lemonchiffon "
+    "lightblue lightcoral lightcyan lightgoldenrodyellow lightgreen lightgrey lightpink lightsalmon "
+    "lightseagreen lightskyblue lightslategray lightsteelblue lightyellow lime limegreen linen magenta maroon "
+    "mediumaquamarine mediumblue mediumorchid mediumpurple mediumseagreen mediumslateblue mediumspringgreen "
+    "mediumturquoise mediumvioletred midnightblue mintcream mistyrose moccasin navajowhite navy oldlace olive "
+    "olivedrab orange orangered orchid palegoldenrod palegreen paleturquoise palevioletred papayawhip peachpuff "
+    "peru pink plum powderblue purple red rosybrown royalblue saddlebrown salmon sandybrown seagreen seashell "
+    "sienna silver skyblue slateblue slategray snow springgreen steelblue tan teal thistle tomato turquoise "
+    "violet wheat white whitesmoke yellow yellowgreen random bikeshed").split())
+_BARE_HEX = re.compile(r"^(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$")
+
+
 # The tonemap filter reads linear light in units of 100 nits (1.0 = SDR white; its default peak,
 # 10, is 1000 nits), so the linearising zscale uses npl=100. Through 3.6.0 it used npl=--peak:
 # a 1000-nit pixel came out as 1.0, which tonemap took as 100 nits, so nothing reached SDR white

package/scripts/_common/decision.py

@@ -16,7 +16,7 @@ from typing import Any, Dict, List, Optional, Sequence, Tuple
 from _common.color import (as_limited, bt709_label_filter, bt709_matrix_args, bt709_matrix_filter, bt709_tag_args, drawn_stream_format,
                            is_neutral_color, limited_range_filter, rgb_island, rgb_to_bt709_filter, _sdr_bt709)
 from _common.alpha import rgb_to_bt709_line
-from _common.emit import die, input_length, record_fallback, refuse, warn
+from _common.emit import die, input_length, note, record_fallback, refuse, warn
 from _common.runner import read_json
 from _common.runner import CODECS, STATE, ffmpeg_encoders, ffmpeg_list_error, ffmpeg_version, hw_platform_reason
 
@@ -1295,6 +1295,46 @@ BRAND_DEFAULTS: Dict[str, Any] = {
 }
 
 
+# Every key a tool reads from a brand file, per block (#510). `styles.caption` is merged over the
+# top-level `caption` block (brand_caption_style()), so the two take the same keys. `colors.accent`
+# is a palette entry BRAND_DEFAULTS and examples/brand.json carry; `loudness` is read by no tool
+# (A107) and is kept out of the refusal, since the example shipped it until 3.8.8: it gets a note.
+BRAND_KEYS: Dict[str, frozenset] = {
+    "": frozenset({"font", "font_file", "colors", "logo", "logo_position", "logo_scale", "logo_opacity",
+                   "safe_margin", "caption", "styles", "lang", "emoji_assets", "loudness"}),
+    "colors": frozenset({"primary", "text", "outline", "background", "accent", "upcoming"}),
+    "caption": frozenset({"size", "position", "animate", "karaoke", "bold", "outline", "box", "color", "colour",
+                          "font", "emoji_assets"}),
+    "styles": frozenset({"caption"}),
+}
+BRAND_KEYS["styles.caption"] = BRAND_KEYS["caption"]
+
+
+def check_brand_keys(data: Dict[str, Any], path: str) -> None:
+    """Refuse a brand file key no tool reads, as render.py refuses a project's (check_keys()): a
+    misspelt `"safe_margn"` or `"colours"` was dropped without a word and the defaults drawn."""
+    import difflib
+    import json
+    blocks = [("", data)]
+    for name in ("colors", "caption", "styles"):
+        if isinstance(data.get(name), dict):
+            blocks.append((name, data[name]))
+    if isinstance(data.get("styles"), dict) and isinstance(data["styles"].get("caption"), dict):
+        blocks.append(("styles.caption", data["styles"]["caption"]))
+    for block, obj in blocks:
+        for key in obj:
+            if key in BRAND_KEYS[block]:
+                continue
+            where = f"{block}.{key}" if block else str(key)
+            near = difflib.get_close_matches(str(key), sorted(BRAND_KEYS[block]), n=1)
+            # quoted as JSON: the key is the caller's text, and a quote or a line break in it stays one line
+            die(f"brand file {path}: unknown key {json.dumps(where)}" + (f' (did you mean "{near[0]}"?)' if near else ""),
+                kind="input", hint=f"the keys read{' in ' + block if block else ''}: " + ", ".join(sorted(BRAND_KEYS[block])))
+    if "loudness" in data:
+        note(f'brand file {path}: "loudness" is read by no tool and was ignored (a target is loudness.py -I, '
+             'export.py\'s preset, or a render project\'s "loudness")')
+
+
 def load_brand(path: Optional[str]) -> Dict[str, Any]:
     """Load brand.json (fonts, colours, logo, safe margins, caption defaults); missing keys fall back to defaults."""
     import copy
@@ -1322,6 +1362,7 @@ def load_brand(path: Optional[str]) -> Dict[str, Any]:
             die(f'brand file {path}: "{key}" must be an object {{...}}, got {type(value).__name__}', kind="input")
         if key in ("logo", "font_file", "font") and not isinstance(value, str):
             die(f'brand file {path}: "{key}" must be a string, got {type(value).__name__}', kind="input")
+    check_brand_keys(data, path)
     base = Path(path).resolve().parent
     for k, v in data.items():
         if v is None and isinstance(brand.get(k), dict):

package/scripts/_common/emit.py

@@ -8,10 +8,11 @@ from __future__ import annotations
 import json
 import math
 import os
+import shlex
 import stat
 import sys
 from typing import Any, Dict, List, Optional, Sequence, Tuple
-from _common.runner import Context, ERROR_CODE, ERROR_RETRYABLE, STATE
+from _common.runner import Context, ERROR_CODE, ERROR_RETRYABLE, STATE, same_file
 
 
 # Characters that never belong in a message a calling agent reads (#400): C0 controls (a line
@@ -977,7 +978,56 @@ def _brief(doc: Dict[str, Any], meta: Dict[str, Any]) -> Dict[str, Any]:
 PLAN_VERSION = 1
 
 
-_PLAN_STRIP = ("--plan", "--dry-run", "--json")
+_PLAN_STRIP = ("--plan", "--dry-run", "--json", "--json-brief")
+
+
+def is_output_shape_flag(token: str) -> bool:
+    """`--json-brief`, or an abbreviation argparse reads as it (`--json-b`): the flag that changes
+    the shape of the document a tool prints. A plan's argv and a plan's execution leave it out
+    (A181): render.py runs the planned tool with --json and reads its full document, whose
+    `commands` the brief form replaces with a count, and executing a plan recorded with it crashed
+    on that count."""
+    return token.startswith("--json-") and "--json-brief".startswith(token)
+
+
+def _command_complete(line: str) -> bool:
+    """Whether a `$ CMD` / `[dry-run] $ CMD` stderr line holds the whole command: run() prints it
+    shell-quoted, so a quote still open at the end of the line is an argument with a line break in
+    it (a `-metadata title=` with two lines), continued on the next stderr line."""
+    body = line[2:] if line.startswith("$ ") else line[len("[dry-run] $ "):]
+    try:
+        shlex.split(body)
+    except ValueError:
+        return False
+    return True
+
+
+def stderr_records(stderr: str) -> "List[Tuple[bool, str]]":
+    """A sibling tool's stderr as (is_command, text) records, in order, for a tool that ran it
+    (render.py's stages and plans): `$ CMD` is the command CMD, a `[dry-run]` line is kept whole as
+    a command record (what render.py has always listed for a dry run), anything else is a line to
+    pass on. A command whose quoted argument holds a line break spans several stderr lines; they
+    are one record again, joined with the break they had (A4: one ffmpeg command became two
+    records, the second passed on as prose). A quote that never closes leaves the lines as they
+    were."""
+    lines = stderr.splitlines(keepends=True)
+    out: "List[Tuple[bool, str]]" = []
+    i = 0
+    while i < len(lines):
+        line = lines[i].rstrip("\r\n")
+        i += 1
+        if not (line.startswith("$ ") or line.startswith("[dry-run]")):
+            out.append((False, line))
+            continue
+        if line.startswith("$ ") or line.startswith("[dry-run] $ "):
+            text, j = line, i
+            while not _command_complete(text) and j < len(lines):
+                text = text + lines[j - 1][len(lines[j - 1].rstrip("\r\n")):] + lines[j].rstrip("\r\n")
+                j += 1
+            if _command_complete(text):
+                line, i = text, j
+        out.append((True, line[2:] if line.startswith("$ ") else line))
+    return out
 
 
 def _plan_at_exit() -> None:
@@ -1074,7 +1124,7 @@ def write_plan(path: str, output: Optional[str], extra: Dict[str, Any], ctx: "Op
         if skip:
             skip = False
             continue
-        if a in _PLAN_STRIP:
+        if a in _PLAN_STRIP or is_output_shape_flag(a):
             skip = a == "--plan"
             continue
         if a.startswith("--plan="):
@@ -1090,11 +1140,10 @@ def write_plan(path: str, output: Optional[str], extra: Dict[str, Any], ctx: "Op
     if platform and output and tool != "check":
         verify.append({"tool": "check", "platform": platform})
     plan_inputs = _plan_inputs(ctx.commands, cleaned, ctx)
-    real = os.path.realpath(path)
     # every file the plan names (#413 review): its inputs, side inputs included (an SRT, a still),
     # and the output it promises, a default name too, which apply_common could not know
     for named in plan_inputs + ([output] if output else []):
-        if os.path.realpath(named) == real:
+        if same_file(named, path):
             refuse("input", "output_is_input" if named != output else "output_path_taken",
                    f"--plan {path!r} is also {'the output' if named == output else 'an input'} of this run "
                    f"({named!r}); give the plan its own path", output=path, other=named)
@@ -1102,7 +1151,7 @@ def write_plan(path: str, output: Optional[str], extra: Dict[str, Any], ctx: "Op
     # (loudness.py --versions, whose `output` is null; export.py's key file) names them only there,
     # and a plan written over one of them is refused as an existing output when it is executed
     for written in _planned_outputs(ctx.commands):
-        if os.path.realpath(written) == real:
+        if same_file(written, path):
             refuse("input", "output_path_taken", f"--plan {path!r} is also a file this run writes ({written!r}); "
                    "give the plan its own path", output=path, other=written)
     doc = {

package/scripts/_common/fonts.py

@@ -278,6 +278,37 @@ _SCRIPT_RANGES = (
 )
 
 
+# The first bytes of the font files FreeType opens (drawtext and libass both load through it):
+# TrueType, OpenType/CFF, Apple 'true'/'typ1', a collection, WOFF/WOFF2, PostScript Type 1 (PFA
+# text, PFB segment marker), BDF and PCF bitmap fonts.
+_FONT_MAGIC = (b"\x00\x01\x00\x00", b"OTTO", b"true", b"typ1", b"ttcf", b"wOFF", b"wOF2",
+               b"%!PS-AdobeFont", b"%!FontType1", b"\x80\x01", b"STARTFONT", b"\x01fcp")
+
+
+def require_font_file(path: str, label: str = "--font-file") -> str:
+    """Refuse a font file that is not there or is not a font, before anything is drawn with it
+    (#510). drawtext that cannot load its `fontfile=` asks fontconfig for a default face instead
+    and exits 0, and libass given the file's directory finds no face in it and does the same, so a
+    text file named `brand.ttf` drew DejaVu Sans with `font_used.substituted: false`. Read by the
+    first bytes, not the extension; a gzipped PCF (`.pcf.gz`) and a Mac `.dfont` (no signature)
+    pass by name."""
+    shown_path = str(path)
+    if not os.path.isfile(shown_path):
+        die(f"{label} {shown_path}: no such file", kind="input")
+    try:
+        with open(shown_path, "rb") as fh:
+            head = fh.read(16)
+    except OSError as exc:
+        die(f"{label} {shown_path} cannot be read: {exc.strerror or exc}", kind="input")
+    lower = shown_path.lower()
+    if head.startswith(_FONT_MAGIC) or lower.endswith(".dfont") or (lower.endswith(".pcf.gz") and head.startswith(b"\x1f\x8b")):
+        return shown_path
+    die(f"{label} {shown_path} is not a font file (it starts with {head[:8]!r}, which no TrueType, OpenType, "
+        "WOFF, Type 1, BDF or PCF font does): drawing with it would fall back to another face without a word",
+        kind="input", hint="name a .ttf, .otf or .ttc file (fc-list lists the installed ones), or --font FAMILY")
+    return shown_path
+
+
 def font_family_of_file(path: str) -> "Optional[str]":
     """The family name of a font FILE -- what libass wants, given a --font-file. `fc-scan` reads
     the file directly; without fontconfig the file stem is the honest best guess."""

package/scripts/_common/probe.py

@@ -14,7 +14,7 @@ import sys
 from array import array
 from fractions import Fraction
 from typing import Any, Dict, List, Optional, Sequence, Tuple
-from _common.emit import die, warn
+from _common.emit import die, refuse, warn
 from _common.runner import ffmpeg_failure_extra, STATE, dry_run_input_pending, require_tool, run, run_analysis, still_input_args
 
 # The streams probe() describes, as stream specifiers: its `video` is the first picture that is not
@@ -348,6 +348,18 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
         fps = float(avg_rate) if avg_rate else (float(r_rate) if r_rate else None)
         vfr = bool(r_rate and avg_rate and abs(float(r_rate) - float(avg_rate)) > 0.01)
         w, h = _to_int(video.get("width")), _to_int(video.get("height"))
+        if not (w and h) and _is_still(fmt, video):
+            # audit A184 (#465): a text file named .png reaches the image demuxer, which lists a
+            # png stream it could not decode as 0x0. That was reported as a measured picture
+            # (probe.py exit 0) and divided by in insert.py and check.py (tracebacks, no JSON).
+            # A video container's stream with no size is left to the tool that reads it.
+            msg = (f"{path} is not a picture ffmpeg can decode: its image demuxer ({fmt.get('format_name')}) found a "
+                   f"{video.get('codec_name') or 'picture'} stream with no frame size"
+                   + (f"\n{proc.stderr.strip()}" if proc.stderr.strip() else ""))
+            if role == "output":
+                _output_failed(path, msg)
+            refuse("input", "still_unreadable", msg, path=path, format=fmt.get("format_name"),
+                   codec=video.get("codec_name"))
         rotation = 0
         for sd in video.get("side_data_list", []) or []:
             if "rotation" in sd:
@@ -893,6 +905,20 @@ def refuse_not_a_still(path: str, meta: Dict[str, Any], flag: str, instead: str)
         + (f" ({length:.3f}s)" if length else "") + f", and {flag} is read as one picture", kind="input", hint=instead)
 
 
+def is_still_input(meta: Dict[str, Any]) -> bool:
+    """A probe document of one picture read by an image demuxer (_is_still()'s rule, on the
+    document): a still given where a clip is taken. Read with a plain `-i` it is one frame, so a
+    tool that shows it for a while opens it with still_loop_args() (#510)."""
+    fmt = str((meta or {}).get("format") or "")
+    return not (meta or {}).get("dry_run") and (fmt == "image2" or fmt.endswith("_pipe"))
+
+
+def still_loop_args(path: str, seconds: float) -> List[str]:
+    """The input options that show a still picture for `seconds`: `-loop 1` repeats its one frame
+    (the image demuxers' option) and `-t` ends the repeat, so the input is bounded."""
+    return ["-loop", "1", *still_input_args(path), "-t", f"{max(seconds, 0.001):.3f}"]
+
+
 def analyze_levels(path: str, seconds: float = 20.0) -> Dict[str, Any]:
     """Sample luma/saturation statistics (signalstats) and guess whether the picture is Log-encoded.
 
@@ -1459,6 +1485,7 @@ def change_tiles(path: str, reference: str, floor: int, grid: "Tuple[int, int]"
            "-filter_complex", graph, "-map", "[o]", "-fps_mode", "passthrough", "-f", "rawvideo", "-pix_fmt", "rgb24", "-"]
     # read frame by frame as ffmpeg writes them: 1728 bytes a frame is 187 MB for an hour at
     # 30 fps, and only the frames with a changed tile are kept. Same wall-clock limit as run_analysis()
+    cmd = _runner.guard_still_patterns(cmd)  # a still named with a % is that one file (#465 A7)
     _runner._refuse_url_media(cmd)
     limit = _runner._limit_for(cmd)
     size, tiles = gw * gh * 3, gw * gh