ffmpeg-skill 3.8.15 → 3.8.17

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.15`) | any release |
+| `skill.version` | the npm / package.json version (`3.8.17`) | 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.15", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "3.8.17", "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.15",
+  "version": "3.8.17",
   "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/gotchas.md

@@ -117,8 +117,18 @@ wrong frame — respect the automatic re-encode rather than forcing the copy.
 
 ### Variable frame rate
 `probe.py` sets `variable_frame_rate_suspected` when `r_frame_rate` and
-`avg_frame_rate` disagree (phone and screen recordings). Every re-encoding
-script then adds `-fps_mode cfr` at the source's average rate. That flag is a
+`avg_frame_rate` disagree (phone and screen recordings). On that flag `crop`, `denoise`,
+`deinterlace`, `proxy`, `sphere`, `stabilize`, `straighten`, `redact`, `overlay`, `caption`,
+`color`, `graphics`, `pad`, `freeze`, `loop`, `broll`, `cut` (a re-encode, `--segments`),
+`export`, `fit` and `speedramp` conform the picture with the `fps` filter (the nearest frame
+for each slot; `-fps_mode cfr` alone let a frame run up to two frames late against the sound,
+#512); `join`, `multicam` and `grid` put each input on the output's rate with their own `fps`
+filter. `reverse.py` is not changed: its `fps` filter comes after `reverse`, which hands the frames
+the forward timestamps in order, so a reversed VFR picture keeps its gaps where they were in
+forward time (each flash 0.19 s late on
+a 27 fps average clip; see docs/design-decisions.md). The rate is `cfr_args()`'s: the probed
+average, written as the nearest whole number when it is within 0.02 of one (29.98 is
+conformed to 30, 29.97 stays 29.97), and 30 when no average was probed. That flag is a
 whole-file average, and a phone clip at 29.98 against a nominal 30 trips it, so
 `cut.py` decides on packet timestamps sampled in up to five windows (`vfr_check`)
 instead: by default (`--vfr-guard sampled`, since 3.0.0) it switches to

package/scripts/_common/__init__.py

@@ -83,7 +83,7 @@ from _common.decision import (
     BEAT_REFRACTORY_S, BEAT_WINDOW_S, BEAT_SUPPORT_DIVISOR, BEAT_ALIGN_DIVISOR,
     BEAT_Z_FLOOR, BEAT_Z_SPAN,
     _onset_strength, _pick_onsets, _autocorrelation_peak, _grid_score,
-    brand_states_font, cfr_args, concat_list_line, db_to_linear, default_output, encoder_args, escape_filter_path,
+    brand_states_font, cfr_args, cfr_at_input, cfr_filter, graph_with_cfr, with_cfr, concat_list_line, db_to_linear, default_output, encoder_args, escape_filter_path,
     fmt_secs, fmt_smpte_time, fmt_srt_time, frame_size, is_audio_output, load_brand, MissingFpsError, pad_filters, parse_time,
     signed_time_arg, source_codec_video_args, drawn_chain, draws_chroma, label_chain, layer_base_chain, matrix_chain, overlay_format, range_chain, rgb_chain_to_bt709, SVT_PRESET, time_arg, video_args, x264_args, _x264_raw
 )
@@ -182,7 +182,7 @@ __all__ = [
     "platform", "re", "shutil", "subprocess", "sys", "unicodedata",
     "aac_args", "add_common", "add_pad_fill_args", "ADVANCE_EM", "analyze_levels", "LEGAL_RANGE_CHOICES", "LEGAL_RANGES", "legal_limits", "measure_signal_range", "apply_common", "detect_scenes", "detect_silences", "SCORE_RE", "SIL_RE", "_aspect_string",
     "audio_codec_for", "AUDIO_CODECS", "BIDI_SCRIPTS", "_bit_depth", "brand_caption_style", "BRAND_DEFAULTS",
-    "brand_states_font", "_brief", "_BRIEF_DROP", "_brief_summary", "bt709_matrix_args", "bt709_matrix_filter", "bt709_tag_args", "cfr_args", "_char_em",
+    "brand_states_font", "_brief", "_BRIEF_DROP", "_brief_summary", "bt709_matrix_args", "bt709_matrix_filter", "bt709_tag_args", "cfr_args", "cfr_at_input", "cfr_filter", "graph_with_cfr", "with_cfr", "_char_em",
     "char_script", "_check_existing_output", "refuse_existing_outputs", "guard_sidecar", "_check_no_overwrite_input", "_check_output_path", "child_args", "option_args",
     "child_limit", "_CHILDREN", "_cleanup_partial_output", "_cmdline", "CODECS", "color_hex", "_COLOR_TOKEN_RE",
     "concat_list_line", "Context", "_CURRENT_CTX", "db_to_linear", "decode_pcm_mono", "description_block", "_evidence_rank", "fmt_chapter_time", "propose_chapters",

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

@@ -655,6 +655,63 @@ def cfr_args(meta: Optional[Dict[str, Any]], fps: Optional[float] = None) -> Lis
     return ["-fps_mode", "cfr", "-r", f"{rate:g}"]
 
 
+def cfr_filter(meta: Optional[Dict[str, Any]], fps: Optional[float] = None) -> str:
+    """The `fps` filter that puts the picture on the grid cfr_args() delivers, as the last filter of
+    the video chain; "" when cfr_args() forces no rate. The encoder line's `-fps_mode cfr -r` alone
+    let a frame fall up to about two frames behind its slot before it dropped one, so a VFR clip
+    conformed at its average rate showed its picture up to 56 ms after its sound (#512); the
+    filter takes the nearest frame for every slot. The encoder line keeps cfr_args(), which then
+    moves no frame."""
+    args = cfr_args(meta, fps)
+    return f"fps={args[-1]}" if args else ""
+
+
+def with_cfr(chain: str, meta: Optional[Dict[str, Any]], fps: Optional[float] = None) -> str:
+    """`chain` (a -vf value or one filtergraph chain) with cfr_filter() appended when there is one.
+    A -vf value that is a graph of its own (drawn_chain()'s split/maskedmerge) gets it first
+    instead: maskedmerge, like overlay, ends its output at its last frame's start, and an fps
+    filter after it lost the last frame (graphics.py --template chapter: 3.963 s of 4)."""
+    return chain_with_rate(chain, cfr_filter(meta, fps))
+
+
+def chain_with_rate(chain: str, rate_filter: str) -> str:
+    """`chain` with an `fps` filter `rate_filter` placed as with_cfr() places cfr_filter(): last in
+    a plain chain, first in a -vf that is a graph of its own (fit/export's blur pad, a drawn pad
+    with chroma), whose overlay or maskedmerge ends its output at its last frame's start on FFmpeg
+    6.1 and lost the last frame to an fps filter after it. For a rate that is not cfr_args()'s
+    own (export.py's preset and platform rates)."""
+    if not rate_filter:
+        return chain
+    if ";" in chain:
+        return f"{rate_filter},{chain}"
+    return f"{chain},{rate_filter}" if chain else rate_filter
+
+
+def graph_with_cfr(graph: str, label: str, meta: Optional[Dict[str, Any]],
+                   fps: Optional[float] = None) -> Tuple[str, str]:
+    """A -filter_complex graph and the video output label to map, with cfr_filter() after that
+    label when there is one: (graph + ";[v]fps=R[vcfr]", "[vcfr]"), else both unchanged."""
+    f = cfr_filter(meta, fps)
+    if not f:
+        return graph, label
+    bare = label.strip("[]")
+    return f"{graph};[{bare}]{f}[{bare}cfr]", f"[{bare}cfr]"
+
+
+def cfr_at_input(graph: str, meta: Optional[Dict[str, Any]], fps: Optional[float] = None, src: str = "[0:v]") -> str:
+    """A -filter_complex graph with cfr_filter() on its main picture as it is decoded (`src`, which
+    the graph reads once), for a graph that composites onto that picture and moves no frame in
+    time. After an overlay the conform comes too late: FFmpeg 6.1's overlay ends its output at its
+    last frame's start, so an fps filter there lost the last frame (3.963 s of a 4 s picture)."""
+    f = cfr_filter(meta, fps)
+    if not f:
+        return graph
+    if graph.count(src) != 1:
+        # a graph that read the picture twice, or not at all, would go unconformed or not parse
+        raise ValueError(f"cfr_at_input: the graph reads {src} {graph.count(src)} times, not once")
+    return f"{src}{f}[cfrin];" + graph.replace(src, "[cfrin]")
+
+
 def delivered_rate(meta: Optional[Dict[str, Any]], fps: Optional[float] = None) -> Optional[float]:
     """The constant rate cfr_args() forces on the output (its -r), or None when it forces none and
     the output keeps the source's rate -- what a start timecode is counted at

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/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:
@@ -1459,6 +1471,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