ffmpeg-skill 3.8.17 → 3.8.19

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.17`) | any release |
+| `skill.version` | the npm / package.json version (`3.8.19`) | 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.17", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "3.8.19", "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), `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`,
+`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; for `sequence.py`, a frame of the sequence that does not decode, when its decode check completes; when the check cannot be made a note says so and the encode runs), `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/package.json

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

@@ -311,7 +311,8 @@ fit.py INPUT [--duration T --method speed|trim [--from-center] [--max-speed 4]]
 `speed` retimes video and audio together (pitch-preserving `atempo`); it
 refuses factors beyond `--max-speed`. For slow motion add `--smooth blend`
 (frame blending, fast) or `--smooth interpolate` (motion-compensated
-`minterpolate`, fluid but roughly 10-20x slower than realtime). `trim` keeps
+`minterpolate`, fluid but roughly 10-20x slower than realtime; its frames are
+made at `--fps` when given, else at the source's rate). `trim` keeps
 the head (or the middle with `--from-center`). `--width`/`--height` set the
 output size: give one and the other follows the aspect (source aspect if
 `--aspect` isn't also given); give both for an exact frame. `--rotate` applies
@@ -522,7 +523,12 @@ sequence.py --dir DIR --pattern "frame_%04d.png"|"*.png" --fps N
 Turns a numbered or glob-matched set of still images into a video. Glob
 matches are ordered naturally (`img2` before `img10`). The match
 is checked on disk before ffmpeg runs (an empty match or a missing first
-frame is refused here, not discovered from an opaque ffmpeg error).
+frame is refused here, not discovered from an opaque ffmpeg error), and every
+frame is decoded once (ffprobe) before the encode. When that check completes, a
+frame that is not an image it can decode (a text file named `.png`, a truncated
+PNG) is refused, `kind: input`, `reason: still_unreadable`, with the frames
+named. When ffprobe fails on the frame list or reads back no frame, the frames
+are not checked: a note says so and the encode runs.
 
 ### waveform.py — audio waveform/spectrum visualization video
 ```
@@ -656,6 +662,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 +724,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 +1200,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 +1616,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/decision.py

@@ -16,11 +16,21 @@ 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
 
 
+def boxblur_chroma_radius(want: int) -> str:
+    """boxblur's chroma radius as an expression boxblur evaluates on the chroma planes' own size
+    (cw x ch, so a 4:1:1 or 4:1:0 frame's quarter-width planes are what is measured, not an assumed
+    4:2:0): `want`, or the largest radius that plane holds, floor((min(cw, ch) - 1) / 2), or 0 on a
+    plane too small for 1. On 4:2:0 that is redact.py's earlier (min(w, h) // 2 - 1) // 2. boxblur
+    refuses a radius above half the plane (6.1); 7.1 also refuses 1 on a 2 px plane, which this
+    bound leaves out (#527)."""
+    return f"max(0\\,min({int(want)}\\,floor((min(cw\\,ch)-1)/2)))"
+
+
 def pad_filters(out_w: int, out_h: int, fill: str, color: str, blur: int, darken: float = 0.0,
                 meta: Optional[Dict[str, Any]] = None) -> str:
     """The letterbox/pillarbox step shared by fit.py and export.py, as one -vf segment.
@@ -41,9 +51,12 @@ def pad_filters(out_w: int, out_h: int, fill: str, color: str, blur: int, darken
         # boxblur rejects a radius larger than half the smaller dimension ("radius 20, must be
         # <= 8" on a 16 px target); clamp instead of failing an otherwise valid request
         radius = max(1, min(int(blur), max(1, min(out_w, out_h) // 2 - 1)))
+        # left unset, the chroma radius was the luma one, and a 4:2:0 68x120 frame's 34x60 chroma
+        # planes failed at 20 ("must be <= 17", #527). On a larger frame it is still the luma one
+        chroma = boxblur_chroma_radius(radius)
         return (f"split[__fitfg][__fitbg];"
                 f"[__fitbg]scale={out_w}:{out_h}:force_original_aspect_ratio=increase,crop={out_w}:{out_h},"
-                f"boxblur={radius}:2" + (f",eq=brightness=-{darken:g}" if darken else "") + "[__fitbgb];"
+                f"boxblur={radius}:2:{chroma}:2" + (f",eq=brightness=-{darken:g}" if darken else "") + "[__fitbgb];"
                 f"[__fitfg]scale={out_w}:{out_h}:force_original_aspect_ratio=decrease[__fitfgs];"
                 f"[__fitbgb][__fitfgs]overlay=(W-w)/2:(H-h)/2:format=auto")
     pad = f"pad={out_w}:{out_h}:(ow-iw)/2:(oh-ih)/2:color="
@@ -1295,6 +1308,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 +1375,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):
@@ -1333,6 +1387,10 @@ def load_brand(path: Optional[str]) -> Dict[str, Any]:
     for key in ("logo", "font_file"):
         if brand.get(key) and not os.path.isabs(brand[key]):
             brand[key] = str(base / brand[key])
+        # a file the run reads: a --plan binds it and is never written over it (review of #534's
+        # sweep: caption.py hands libass the font's folder, so its plan named neither)
+        if brand.get(key) and os.path.isfile(brand[key]) and brand[key] not in STATE.plan_inputs:
+            STATE.plan_inputs.append(brand[key])
     brand["_path"] = str(path)
     # What the FILE said, separate from BRAND_DEFAULTS' filler: a brand.json that never mentions
     # a font must not read as "the caller chose a font" (which would switch font-by-script off).

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

@@ -905,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.
 

package/scripts/_contract.py

@@ -261,6 +261,7 @@ DRY_RUN_ANALYSIS = {
 }
 DRY_RUN_NOTES = {
     "verify": "not supported: the flag is accepted but the steps run and outputs are written",
+    "sequence": "no ffmpeg runs; ffprobe decodes every frame of the sequence once, and when that check completes a frame that does not decode as an image is refused (still_unreadable) as in a real run; when ffprobe fails on the frame list or reads back no frame, a note says the frames were not checked and the dry run completes; the video is not written",
 }
 
 # Whether a tool re-encodes each stream *when that stream is present in the input* -- not whether
@@ -436,7 +437,7 @@ ERROR_REASONS = {
     "output_is_directory": "the output path is a directory; details: {output}",
     "media_path_is_playlist": "an input is a playlist that ffmpeg would follow to the files or URLs it names: HLS .m3u8/.m3u or an ffconcat list (by name or by its first bytes), a DASH manifest or an IMF composition playlist (by name or by the content ffmpeg's own probe looks for, whatever the file is called); the skill takes media files only; details: {path}",
     "media_path_has_line_break": "a path written into a concat list (loop.py, join.py --copy, sequence.py, multi-part cuts) contains a line break, which the concat format cannot hold: each line is a directive, so the name would add entries to the list; details: {path}",
-    "still_unreadable": "an input read by an image demuxer (a .png, .jpg, ... name) has a picture stream with no frame size: the file is not an image ffmpeg can decode (a text file named .png); details: {path, format, codec}",
+    "still_unreadable": "an input read by an image demuxer (a .png, .jpg, ... name) has a picture stream with no frame size: the file is not an image ffmpeg can decode (a text file named .png); details: {path, format, codec}. sequence.py: a frame of the sequence that does not decode (every frame is decoded once before the encode; when that check cannot be made, a note says so and nothing is refused); details: {path (the first), frames, frames_unreadable, frames_total}",
     "media_path_not_a_file": "an input exists but is not a regular file (a FIFO or a device), which ffmpeg would block on or read as a stream; details: {path}",
     "join_copy_mismatch": "join.py --copy: a clip's streams do not match the first clip's, it hides pre-roll frames with an edit list, or its picture and sound end more than 50 ms apart; details: {clips: [{index?, path, differs}]}",
     "output_path_taken": "two files one run writes (a side file and the output, or two side files) resolve to the same path, so the second would replace the first; details: {output, other}",

package/scripts/broll.py

@@ -26,7 +26,7 @@ from _common.decision import (av_trim, conform_output_t, conform_to_length, fram
                               grid_at_or_after, silence_filter, stream_starts, window_expr, windowed_overlay_x)
 from _common import STATE, add_common, aac_args, apply_common, cfr_args, cfr_at_input, as_limited, default_output, die, draws_chroma, drawn_chain, emit, ffmpeg_base, info, time_arg, label_chain, matrix_chain, overlay_format, range_chain, probe, run, validate_color, video_args, X264_PRESETS, fmt_secs
 from _common.emit import note, record_fallback
-from _common.probe import display_size, square_pixels, square_pixels_note
+from _common.probe import display_size, is_still_input, square_pixels, square_pixels_note, still_loop_args
 from _common.emit import input_length
 
 
@@ -109,7 +109,9 @@ def main() -> int:
             die(f"cutaway {i + 1}: --at {at:g}s is past the end of the A-roll ({dur_a:.3f}s)")
         if dur_a and at + length > dur_a + 0.01:
             die(f"cutaway {i + 1}: {at:g}s + {length:g}s runs past the end of the A-roll ({dur_a:.3f}s)")
-        dur_b = input_length(meta_b)
+        # a still has no material to run out of: it is looped for the window. image2 gives some (a
+        # TGA) a duration of one frame, which this refused as "only -0.460s from 0.5s" (review of #532)
+        dur_b = None if is_still_input(meta_b) else input_length(meta_b)
         if dur_b and start_b + length > dur_b + 0.01 and not STATE.dry_run:
             die(f"cutaway {i + 1}: {path} has only {dur_b - start_b:.3f}s from {start_b:g}s, {length:g}s asked for")
         # the cutaway in whole frames: `first` is B's first frame at or after --from, `on` the
@@ -139,6 +141,15 @@ def main() -> int:
     output = args.output or default_output(args.input, "broll")
     cmd = ffmpeg_base() + ["-i", args.input]
     for c in cutaways:
+        # a still B-roll is one frame to a plain -i: it showed for one frame of the cutaway and A
+        # came back under it (#510). Looped, it lasts the window it is trimmed to. The bound is past
+        # the trim's end, which runs from B's first frame at or after --from on the loop's own
+        # grid for the window's whole frames: --from + --duration cut that frame off a short window
+        # (--from 0.041 --duration 0.033 needs the frame at 0.08, review of #532). A frame of B
+        # past it costs nothing: the trim drops it.
+        if is_still_input(c["meta"]):
+            frame_b = 1 / c["rate"] if c["rate"] else 0.04
+            cmd += still_loop_args(c["path"], max(c["from"], c["first"]) + max(c["length"], c["span"] or 0) + 2 * frame_b)
         cmd += ["-i", c["path"]]
 
     # Picture: each B window is trimmed, normalised to A's frame and fps, shifted to start at its

package/scripts/caption.py

@@ -56,7 +56,7 @@ from _common.asr import ENGINE_CHOICES
 from _common.emit import warn
 from _common.probe import display_size, square_pixels, square_pixels_note
 from _common.runner import carried_stream_maps, refuse_output_is_input, same_file, subtitle_codec_for, subtitle_container_holds
-from _common.fonts import font_choice, record_font_choice
+from _common.fonts import font_choice, record_font_choice, require_font_file
 from _common import (ASR_INSTALL_HINT, die_no_engine, parse_srt, transcribe, whisper_word_timings,
                      write_srt)
 from _common.asr import srt_blocks
@@ -1327,6 +1327,11 @@ def main() -> int:
     if args.brand and bcap.get("karaoke") and not args.karaoke:
         args.karaoke = True
     if args.brand and brand.get("font_file") and not args.fonts_dir:
+        # the brand's face is found in its directory by libass, so a file there that is no font
+        # left libass to another face without a word (#510); a soft track (--mode mux) draws nothing,
+        # and nor does a run with no input video, which only writes the SRT (review of #532)
+        if args.mode != "mux" and args.input:
+            require_font_file(brand["font_file"], "the --brand file's font_file")
         args.fonts_dir = str(Path(brand["font_file"]).parent)
     if not (args.srt or args.ass or args.text or args.transcribe):
         die("give one of --srt, --ass, --text or --transcribe")
@@ -1569,8 +1574,11 @@ def main() -> int:
         refuse_existing_outputs(todo)
         # and the rest of the side-file guards (#408): never an input, the video, a missing
         # directory or an option-shaped name, even under --overwrite
+        # a brand file's font_file and logo are read too (review of #534's sweep: --write-srt or
+        # --write-ass naming the brand's font replaced it)
         side_inputs = [q for q in (args.input, getattr(args, "text", None), getattr(args, "ass", None),
-                                   getattr(args, "brand", None), *(t[0] for t in srt_tracks)) if isinstance(q, str)]
+                                   getattr(args, "brand", None), brand.get("font_file"), brand.get("logo"),
+                                   *(t[0] for t in srt_tracks)) if isinstance(q, str) and q]
         for path in todo:
             guard_sidecar(path, *side_inputs)
 

package/scripts/cut.py

@@ -1618,7 +1618,8 @@ def main() -> int:
                     + "; give every segment at least one frame", kind="input")
 
     output = args.output or default_output(args.input, "cut")
-    refuse_output_is_input(output, args.input)
+    # --snap-source is read for its beat grid and is never an -i of the cut (#522's sweep)
+    refuse_output_is_input(output, args.input, *([args.snap_source] if args.snap_source else []))
     ext = os.path.splitext(output)[1].lower() or ".mp4"  # an upper-case .MP4 is still faststart
 
     # A segment that runs past the end of the video, with a join after it: whatever joins it (the

package/scripts/fit.py

@@ -201,7 +201,10 @@ def main() -> int:
                 vf.append(f"setpts={1/factor:.8f}*PTS")
                 src_fps = meta["video"].get("fps") or 30.0
                 if factor < 1.0 and args.smooth == "interpolate":
-                    vf.append(f"minterpolate=fps={src_fps:g}:mi_mode=mci:mc_mode=aobmc:me_mode=bidir:vsbmc=1")
+                    # the new frames are made at the rate delivered: made at the source's 30 and
+                    # then put on --fps 60 by the fps filter below, every other frame of the slow
+                    # motion was a repeat (#527). Without --fps it is the source's rate, as before
+                    vf.append(f"minterpolate=fps={args.fps or src_fps:g}:mi_mode=mci:mc_mode=aobmc:me_mode=bidir:vsbmc=1")
                 elif factor < 1.0 and args.smooth == "blend":
                     vf.append(f"fps={src_fps:g}")
                     vf.append("tblend=all_mode=average")
@@ -259,11 +262,14 @@ def main() -> int:
     # A speed change without --fps has already been put on the delivered grid above
     if args.fps:
         vf.append(f"fps={args.fps:g}")
-    elif meta["video"].get("variable_frame_rate_suspected") and not regridded:
+    elif meta["video"].get("variable_frame_rate_suspected"):
+        # said whichever filter conforms it: a speed change's regrid above is that conform, and the
+        # line was missing there (#527)
         info("source looks variable-frame-rate; conforming to constant fps automatically")
-        # the conform is the fps filter, as --fps is: -fps_mode cfr alone let a frame run up to
-        # two frames late against the sound (#512)
-        vf.append(cfr_filter(meta))
+        if not regridded:
+            # the conform is the fps filter, as --fps is: -fps_mode cfr alone let a frame run up to
+            # two frames late against the sound (#512)
+            vf.append(cfr_filter(meta))
 
     # ---- aspect / size
     if args.aspect or args.width or args.height:

package/scripts/graphics.py

@@ -36,7 +36,7 @@ from typing import List, Optional, Tuple
 from _platforms import PLATFORMS, PLATFORM_CHOICES, safe_margins_px, resolve as resolve_platform
 from _common.emoji import emoji_missing_asset_note, emoji_mono_on_colour_note
 from _common.drawtext import shaping_refusal
-from _common import (guard_sidecar, require_filter, aac_args, add_common, brand_caption_style, script_font_for_text, apply_common, cfr_args, cfr_at_input, with_cfr,
+from _common import (guard_sidecar, refuse_output_is_input, require_filter, aac_args, add_common, brand_caption_style, script_font_for_text, apply_common, cfr_args, cfr_at_input, with_cfr,
                      color_hex, default_output, die, draws_chroma, drawn_chain, emit, escape_drawtext, escape_filter_path,
                      ffmpeg_base, info, layer_base_chain, load_brand, overlay_format, probe, rgb_chain_to_bt709, run_keeping_subtitles, video_args,
                      drawtext_boxborderw, drawtext_center_align, X264_PRESETS, time_arg, fmt_secs, STATE, drawtext_text_opts,
@@ -47,7 +47,7 @@ from _common import (guard_sidecar, require_filter, aac_args, add_common, brand_
 from _common.emit import note, warn
 from _common.alpha import (add_alpha_args, audio_line, check_alpha_args, decoder_args_for, default_ext, finish_chain,
                            report as alpha_report, source_alpha, source_format, tag_args, video_line)
-from _common.fonts import font_choice, record_font_choice
+from _common.fonts import font_choice, record_font_choice, require_font_file
 from _common.probe import display_size, square_pixels, square_pixels_note
 from _ass_overlay import text_overlay_ass, EMOJI_SENTINEL
 from _common import drawtext_fontfile  # noqa: E402
@@ -175,6 +175,9 @@ def main(force_route: Optional[str] = None) -> int:
     if args.brand and style.get("color") and not args.text_color:
         text_c = color_hex(style["color"])
     args.lang = args.lang or (brand.get("lang") if args.brand else None)
+    # checked where text is drawn with it: the progress template draws a bar only (review of #532)
+    if args.template != "progress" and (args.font_file or brand.get("font_file")):
+        require_font_file(args.font_file or brand["font_file"], "--font-file" if args.font_file else "the --brand file's font_file")
     # a font that covers the text before drawtext renders boxes instead of glyphs (1.12)
     _script, script_file, _family = script_font_for_text(
         " ".join(t for t in (args.name, args.title, args.subtitle, args.text, args.top, args.bottom) if t),
@@ -670,6 +673,9 @@ def main(force_route: Optional[str] = None) -> int:
              "through libass, or upgrade FFmpeg", "drawtext_newline_glyph", text_render="drawtext")
 
     output = args.output or default_output(args.input, "gfx", default_ext(alpha_codec) if alpha_codec else None)
+    # the brand file and the font file are read here and by drawtext's fontfile=, never as an -i, so
+    # run()'s guard did not see them (#522's sweep)
+    refuse_output_is_input(output, *[q for q in (args.brand, args.font_file or brand.get("font_file")) if isinstance(q, str) and q])
     ass_path = None
     emoji_result = None
     if route == "ass":
@@ -751,8 +757,10 @@ def main(force_route: Optional[str] = None) -> int:
         require_filter("ass", "drawing this text through libass")  # before the sidecar is written
         # a file this run writes itself: never the input or the video, a missing directory or an
         # existing file without --overwrite is refused before anything is written (#408)
-        guard_sidecar(ass_path, *[q for q in (args.input, getattr(args, "brand", None), getattr(args, "font_file", None))
-                                  if isinstance(q, str)], siblings=(output,))
+        # the font the text is drawn with, a brand file's font_file included (review of #534: only
+        # --font-file was here, and --write-ass naming the brand's font replaced it with ASS text)
+        guard_sidecar(ass_path, *[q for q in (args.input, getattr(args, "brand", None), args.font_file or brand.get("font_file"))
+                                  if isinstance(q, str) and q], siblings=(output,))
         if STATE.dry_run:
             info(f"[dry-run] would write {ass_path} ({len(elements)} text elements)")
         else:

package/scripts/grid.py

@@ -32,7 +32,7 @@ from _common import drawtext_fontfile  # noqa: E402
 from _common import ffmpeg_filters, filter_missing_hint  # noqa: E402
 from _common.emit import note, record_fallback  # noqa: E402
 from _common.fonts import script_font_for_text  # noqa: E402
-from _common.probe import square_pixels  # noqa: E402
+from _common.probe import is_still_input, square_pixels, still_loop_args  # noqa: E402
 from _common.wrap import text_width_em  # noqa: E402
 from _common.emit import input_length  # noqa: E402
 from _common.decision import conform_output_t, conform_to_length  # noqa: E402
@@ -116,8 +116,15 @@ def main() -> int:
     if args.audio_from is not None and not metas[args.audio_from].get("audio"):
         die(f"--audio-from {args.audio_from}: {args.inputs[args.audio_from]} has no audio stream")
 
-    durations = [input_length(m) for m in metas]
+    # a still picture has no length of its own: it lasts as long as the grid (#510). Counted as a
+    # clip of 0 s, it made the grid 0 s long, and the run ended in a traceback on the empty file.
+    stills = [is_still_input(m) for m in metas]
+    if all(stills):
+        die("every cell is a still picture, so the grid has no length to take from a clip", kind="input",
+            hint="give at least one video cell, or make a clip of a still first (insert.py STILL --duration T)")
+    durations = [input_length(m) for m, still in zip(metas, stills) if not still]
     target_duration = max(durations) if args.pad else min(durations)
+    durations = [target_duration if still else input_length(m) for m, still in zip(metas, stills)]
 
     # each label is drawn with a font that covers its own script, as every other text-drawing tool
     # picks one (through 3.1.3 a Japanese or Thai filename came out as tofu, #411); `font_used` is
@@ -139,11 +146,13 @@ def main() -> int:
     if args.label == "auto" and cut:
         note(f"{len(cut)} cell label(s) wider than the {args.cell_width} px cell at --font-size "
              f"{args.font_size} were shortened from the end with an ellipsis")
-    output = args.output or default_output(args.inputs[0], "grid")
+    # named after the first cell; a still there would give its own extension (white_grid.png), and
+    # the image muxer cannot write the grid's frames to one file name (review of #532)
+    output = args.output or default_output(args.inputs[0], "grid", "mp4" if stills[0] else None)
 
     cmd = ffmpeg_base()
-    for p in args.inputs:
-        cmd += ["-i", p]
+    for p, still in zip(args.inputs, stills):
+        cmd += (still_loop_args(p, target_duration) if still else []) + ["-i", p]
 
     # each cell converted by its own tags to the BT.709 the grid is tagged with (a BT.601 or an RGB
     # input): without it 5.1/6.1 relabelled them, and 7.1+ converted cells to one another's matrix.

package/scripts/join.py

@@ -45,7 +45,7 @@ from typing import Any, Dict, List, Optional, Tuple
 
 from _common.probe import SILENT_PEAK_DBFS, signatures_match, stream_signature
 from _common.runner import read_text_or_die
-from _common import STATE, AUDIO_MEDIA_EXT, concat_list_line, guard_sidecar, place_output, refuse, sibling_temp, as_limited, draws_chroma, drawn_chain, label_chain, matrix_chain, range_chain, video_args, aac_args, add_common, apply_common, audio_codec_for, default_output, die, dry_run_input_pending, emit, ffmpeg_base, info, measured_level_dbfs, is_audio_output, probe, require_tool, run, validate_color, X264_PRESETS, fmt_secs
+from _common import STATE, AUDIO_MEDIA_EXT, concat_list_line, guard_sidecar, refuse_output_is_input, place_output, refuse, sibling_temp, as_limited, draws_chroma, drawn_chain, label_chain, matrix_chain, range_chain, video_args, aac_args, add_common, apply_common, audio_codec_for, default_output, die, dry_run_input_pending, emit, ffmpeg_base, info, measured_level_dbfs, is_audio_output, probe, require_tool, run, validate_color, X264_PRESETS, fmt_secs
 from _common.emit import note, warn
 from _common.decision import av_clip_length, av_trim, stream_starts
 from _common.probe import display_size, square_pixels, square_pixels_note
@@ -245,6 +245,7 @@ def join_audio(args: argparse.Namespace, metas: List[dict]) -> int:
     if len(set(chans)) > 1:
         info(f"channel counts differ ({', '.join(str(c) for c in chans)}); every clip becomes {layout}")
     output = args.output or default_output(args.inputs[0], "joined")
+    refuse_list_as_output(args, output)
     if not is_audio_output(output):
         die(f"audio-only inputs cannot fill a video container: give -o an audio extension (.wav, .flac, .mp3, .m4a, .ogg, .opus), not {output}")
 
@@ -283,6 +284,13 @@ CONCAT_DIRECTIVES = frozenset({"inpoint", "outpoint", "duration", "stream", "exa
                                "file_packet_meta", "option", "stream_meta", "stream_codec", "stream_extradata", "chapter"})
 
 
+def refuse_list_as_output(args: argparse.Namespace, output: str) -> None:
+    """The --list file is read here and is never an -i of the join, so run()'s guard did not see
+    an output named like it (#522's sweep): refused once the output is known, before any write."""
+    if args.list:
+        refuse_output_is_input(output, args.list, why="the clip list would be replaced by the join")
+
+
 def read_list(path: str) -> List[str]:
     """--list FILE: one segment per line, in order, relative to the list file's own folder.
     Blank lines and # comments are ignored, and ffmpeg's concat-demuxer spelling
@@ -494,6 +502,7 @@ def join_copy(args, metas: List[Dict[str, Any]]) -> int:
         die(f"--copy keeps every clip's own encoding: {', '.join(encoder)} choose(s) an encode, so drop --copy")
     output = args.output or default_output(args.inputs[0], "joined", os.path.splitext(args.inputs[0])[1].lstrip(".") or "mp4")
     guard_sidecar(output, *args.inputs)
+    refuse_list_as_output(args, output)
     ext = os.path.splitext(output)[1].lower()
     n = len(args.inputs)
     pending = any(m.get("dry_run") for m in metas)
@@ -929,6 +938,7 @@ def main() -> int:
         STATE_NOTES.append("the planned trim lengths count each pending input as 0 s long: a real run trims "
                            "or holds it to its measured length")
     output = args.output or default_output(args.inputs[0], "joined", "mp4")
+    refuse_list_as_output(args, output)
     cmd += ["-filter_complex", ";".join(parts), "-map", "[vout]", "-map", "[aout]"]
     # the fps filter already made the picture constant-rate, and the per-clip trims (then xfade or
     # concat) place every frame: FFmpeg 5.1's default cfr output mode still duplicated the last one

package/scripts/metadata.py

@@ -35,7 +35,7 @@ from _common import (guard_sidecar, add_common, apply_common, default_output, de
                      die, emit, ffmpeg_base, fmt_chapter_time, info, propose_chapters, time_arg, probe, run,
                      STATE, read_text_or_die)
 from _common.emit import input_length
-from _common.runner import carried_stream_maps
+from _common.runner import carried_stream_maps, refuse_output_is_input
 
 CHAPTER_CONTAINERS = {".mp4", ".m4v", ".m4a", ".mov", ".mkv", ".mka", ".webm"}
 TAG_KEYS = ("title", "artist", "album", "comment", "date", "genre")
@@ -247,6 +247,9 @@ def main() -> int:
     output = args.output or default_output(args.input, "meta", Path(args.input).suffix.lstrip(".") or "mp4")
     if os.path.abspath(output) == os.path.abspath(args.input):
         die("output must differ from the input (metadata.py never rewrites a file in place)")
+    if args.chapters:
+        # the chapter list is read here and handed to ffmpeg as a metadata file of its own (#522's sweep)
+        refuse_output_is_input(output, args.chapters, why="the chapter file would be replaced by the output")
     out_ext = Path(output).suffix.lower()
     if (args.chapters or args.clear_chapters or args.auto_chapters) and out_ext not in CHAPTER_CONTAINERS:
         die(f"{out_ext or 'this'} container cannot hold chapter markers; write to one of "

package/scripts/overlay.py

@@ -45,8 +45,8 @@ from _common.alpha import (add_alpha_args, audio_line, check_alpha_args, decoder
 from _common.probe import display_size, refuse_not_a_still, square_pixels, square_pixels_note
 from _common.drawtext import shaping_refusal
 from _common.wrap import wrap_text
-from _common import text_width_em
-from _common.fonts import font_choice, record_font_choice
+from _common import text_width_em, refuse_output_is_input
+from _common.fonts import font_choice, record_font_choice, require_font_file
 from _common import drawtext_fontfile  # noqa: E402
 
 # Per-edge margins: a platform's UI does not cover the same fraction of every edge (TikTok's
@@ -361,6 +361,7 @@ def main() -> int:
     # at --font-size), so a project that asked for 200 px text completed with the 42 px default.
     if args.text and not (args.image or args.video) and (args.scale is not None or args.scale_percent is not None):
         die("--scale and --scale-percent size an image, logo or video layer; text size is --font-size", kind="input")
+    font_file_from = "--font-file"  # what the refusal of a font file that is not one names
     if args.brand:
         if args.margin == ap.get_default("margin"):
             args.margin = int(brand.get("safe_margin", args.margin))
@@ -368,6 +369,7 @@ def main() -> int:
             args.font = brand.get("font", args.font)
         if not args.font_file and brand.get("font_file"):
             args.font_file = brand["font_file"]
+            font_file_from = "the --brand file's font_file"
     if args.text:
         # 1.15: drawtext never reorders or re-clusters (no harfbuzz), so Devanagari matras and
         # Thai/Lao mark stacking come out wrong on EVERY build. A wrong frame is not a delivery:
@@ -393,6 +395,8 @@ def main() -> int:
                      "a font without the glyph draws an empty box (monochrome at best with one). --emoji none "
                      "leaves them out; caption.py/graphics.py composite colour PNGs with --emoji-assets",
                      "emoji_monochrome")
+    if args.text and args.font_file:
+        require_font_file(args.font_file, font_file_from)
     script_file = script_family = None
     if args.text and not args.font_file:
         # 1.12: non-Latin overlay text picks a font by script, so a title in Japanese, Korean,
@@ -490,6 +494,9 @@ def main() -> int:
             "from --start to --end without a fade", hint="drop --fade for the video layer")
 
     output = args.output or default_output(args.input, "overlay", default_ext(alpha_codec) if alpha_codec else None)
+    # the brand file and a text layer's font file are read here and by drawtext's fontfile=, never
+    # as an -i, so run()'s guard did not see them (#522's sweep)
+    refuse_output_is_input(output, *[q for q in (args.brand, args.font_file if args.text else None) if isinstance(q, str) and q])
     enable = enable_expr(start, end, meta)
     cmd = ffmpeg_base() + ["-i", args.input]
 
@@ -533,6 +540,11 @@ def main() -> int:
         # a --start/--end window is in the layer's position, which is evaluated on the main
         # picture's frames; overlay's enable is evaluated on the layer's frames too
         ov = f"overlay={windowed_overlay_x(x, enable) if enable else x}:{y}" + (overlay_format(meta) or ":format=auto")
+        if not meta.get("duration"):
+            # nothing to bound by -t: the overlay ends with the main picture. -shortest alone never
+            # ended a still main (one picture, no duration): overlay kept repeating it under the
+            # looped layer and the run went on until its timeout (#510)
+            ov += ":shortest=1"
         # -loop 1 turns the still into a timed stream so fade/enable expressions see real timestamps
         cmd = ffmpeg_base() + ["-i", args.input, "-loop", "1", *still_input_args(args.image), "-i", args.image]
         # the RGBA still is converted to the BT.709 the output is tagged with (overlay's own

package/scripts/redact.py

@@ -30,6 +30,7 @@ import sys
 from _common import add_common, overlay_format, apply_common, aac_args, cfr_args, cfr_at_input, with_cfr, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args, X264_PRESETS, fmt_secs
 from _common.emit import note
 from _common.probe import display_size, square_pixels, square_pixels_note
+from _common.decision import boxblur_chroma_radius
 
 
 def main() -> int:
@@ -118,7 +119,10 @@ def main() -> int:
             # --blur-strength 1, which left colour-only detail readable (review of #521). (FFmpeg
             # 7.1 refuses a chroma radius of 1 on a 2 px chroma plane, a 4 px wide region; 6.1
             # took it.) 0 is only a plane too small to blur: the luma still is
-            chroma = max(0, min(max(1, radius // 2), (min(args.width, args.height) // 2 - 1) // 2))
+            # On the chroma planes' own size, which boxblur measures: a 4:1:1 or 4:1:0 source's
+            # quarter-width planes failed at the 4:2:0 bound (a 30x30 region: "radius 7, must be
+            # <= 3", #527's sweep). On 4:2:0 the radius is the one it was
+            chroma = boxblur_chroma_radius(max(1, radius // 2))
             region = f"{crop},boxblur={radius}:{radius}:{chroma}:{radius}"
         else:
             region = f"{crop},scale={max(1, args.width // args.block_size)}:{max(1, args.height // args.block_size)}:flags=neighbor,scale={args.width}:{args.height}:flags=neighbor"

package/scripts/render.py

@@ -1602,7 +1602,11 @@ def main() -> int:
         # the project file and every clip it names are inputs the JSON must not replace
         where = Path(args.project).resolve().parent if args.project else Path.cwd()
         srcs = [c["src"] for c in proj.get("clips") or [] if isinstance(c, dict) and isinstance(c.get("src"), str)]
-        guard_sidecar(args.write_project, args.project, *[str(where / s) for s in srcs])
+        # every file the project reads, not only its clips: a template's brand, its font_file and
+        # logo, the cue or SRT file, the chapters (review of #534's sweep: --write-project naming
+        # the brand's font or logo replaced it with the JSON)
+        guard_sidecar(args.write_project, args.project, *[str(where / s) for s in srcs],
+                      *project_input_files(proj, lambda p: p if os.path.isabs(str(p)) else str(where / str(p))))
         try:
             Path(args.write_project).write_text(json.dumps(proj, indent=2) + "\n", encoding="utf-8")
         except OSError as exc:

package/scripts/report.py

@@ -14,6 +14,7 @@ import base64
 import html
 import json
 import os
+import re
 import sys
 import tempfile
 from pathlib import Path
@@ -145,6 +146,10 @@ def md_cells(line: str) -> List[str]:
     return cells
 
 
+# the columns of render.py's render_pack() table, in its order
+PACK_HEADER = ["platform", "file", "size", "duration", "check"]
+
+
 def pack_report(args) -> int:
     """render.py --template all writes <stem>_pack.md: one row per destination. This renders the
     same rows as HTML, so a pack can be handed over the way a single delivery report is -- no
@@ -152,19 +157,37 @@ def pack_report(args) -> int:
     text = read_text_or_die(args.pack, "--pack")
     rows: List[List[str]] = []
     header: List[str] = []
+    delimiter: Optional[List[str]] = None
     for line in text.split("\n"):
         line = line.strip()
         if not line.startswith("|"):
+            if header:
+                break  # the table ended: a later table in the file is not the pack's
             continue
         cells = md_cells(line)
-        if all(set(c) <= set("-: ") for c in cells):
-            continue
         if not header:
             header = cells
+        elif delimiter is None:
+            delimiter = cells  # the line under the header, whatever it is: checked below
         else:
+            # every later line is a row, a separator-like one too: `| | |` after a row was skipped
+            # as a delimiter and never counted (review of #532)
             rows.append(cells)
+    # the table render.py --template all writes, and only that one: any Markdown table was taken
+    # and handed over as a pack report with `verified: true` (#510)
+    if header and header != PACK_HEADER:
+        die(f"{args.pack}: its table's columns are {' | '.join(header)}, not the pack table's "
+            f"({' | '.join(PACK_HEADER)}) that render.py --template all writes", kind="input")
+    # a header with a row under it and no delimiter line is no Markdown table (review of #532)
+    if header and delimiter is not None and not (
+            len(delimiter) == len(PACK_HEADER) and all(re.fullmatch(r":?-+:?", c) for c in delimiter)):
+        die(f"{args.pack}: the line under the pack table's header is not its delimiter row "
+            f"(|---|---|---|---|---|), so it is no Markdown table", kind="input")
+    bad = next((i for i, r in enumerate(rows) if len(r) != len(PACK_HEADER)), None)
+    if bad is not None:
+        die(f"{args.pack}: row {bad + 1} of the pack table has {len(rows[bad])} cells, not {len(PACK_HEADER)}", kind="input")
     if not rows:
-        die(f"{args.pack}: no pack table found (expected the Markdown table render.py --template all writes)")
+        die(f"{args.pack}: no pack table found (expected the Markdown table render.py --template all writes)", kind="input")
     title = args.title or f"Social pack — {Path(args.pack).stem.replace('_pack', '')}"
     output = args.output or str(Path(args.pack).with_suffix(".html"))
     guard_sidecar(output, args.pack)

package/scripts/sequence.py

@@ -21,8 +21,8 @@ import tempfile
 from fractions import Fraction
 from pathlib import Path
 
-from _common import add_common, apply_common, default_output, die, emit, ffmpeg_base, info, probe, run, video_args, X264_PRESETS, concat_list_line, fmt_secs
-from _common.emit import note, warn
+from _common import add_common, apply_common, default_output, die, emit, ffmpeg_base, info, probe, require_tool, run, video_args, X264_PRESETS, concat_list_line, fmt_secs
+from _common.emit import note, refuse, warn
 from _common.probe import display_size, square_pixels_note
 from _common.timeline import TimelineError, exact_rate
 
@@ -60,6 +60,31 @@ def concat_list(frames: list, rate: Fraction) -> str:
     return "\n".join(lines)
 
 
+def undecodable_frames(list_path: Path, frames: list, rate: Fraction) -> "list | None":
+    """The frames of the list that do not decode to a picture, in order; None when the check could
+    not be made (ffprobe failed). ffprobe decodes the same concat list the encode reads, so a frame
+    is what the encode would get: frame i is decoded at the i-th start the list gives it. Only the
+    first frame was probed, and a later one that was not an image (a text file named .png, a
+    truncated PNG) was left out by the decoder while the fps filter repeated its neighbour: the run
+    completed with that frame missing (#529)."""
+    proc = run([require_tool("ffprobe"), "-v", "error", "-f", "concat", "-safe", "0", "-i", str(list_path),
+                "-select_streams", "v:0", "-show_entries", "frame=best_effort_timestamp_time", "-of", "csv=p=0"],
+               quiet=True, check=False)
+    if proc.returncode != 0:
+        return None
+    decoded = set()
+    for line in proc.stdout.splitlines():
+        try:
+            decoded.add(round(float(line.strip().rstrip(",")) * rate))
+        except ValueError:
+            continue
+    if not decoded:
+        # the first frame was probed as an image, so it decodes: nothing read back is a check that
+        # did not happen, not every frame missing
+        return None
+    return [f for i, f in enumerate(frames) if i not in decoded]
+
+
 def natural_key(name: str) -> list:
     """img2 < img10: digit runs compare as numbers, the rest case-insensitively."""
     return [int(t) if t.isdigit() else t.lower() for t in re.split(r"(\d+)", name)]
@@ -164,6 +189,18 @@ def main() -> int:
     with tempfile.TemporaryDirectory(prefix="ffmpeg-skill-sequence-") as tmp:
         list_path = Path(tmp) / "frames.txt"
         list_path.write_text(concat_list([f.resolve() for f in frames], rate), encoding="utf-8")
+        # every frame decodes, or the run is refused before the encode (a dry run too: ffprobe runs
+        # under --dry-run, as every probe does), naming the frames that do not
+        bad = undecodable_frames(list_path, frames, rate)
+        if bad is None:
+            note("the frames could not be checked before the encode (ffprobe failed on the frame list); "
+                 "a frame that does not decode would be left out of the video")
+        elif bad:
+            names = ", ".join(f.name for f in bad[:5]) + (f" and {len(bad) - 5} more" if len(bad) > 5 else "")
+            refuse("input", "still_unreadable",
+                   f"{len(bad)} of {len(frames)} frames do not decode as an image ({names}); they would be "
+                   "missing from the video. Replace or remove them",
+                   path=str(bad[0]), frames=[str(f) for f in bad], frames_unreadable=len(bad), frames_total=len(frames))
 
         cmd = ffmpeg_base() + ["-f", "concat", "-safe", "0", "-i", str(list_path)]
         vf = [f"scale={out_w}:{out_h}", "setsar=1", f"fps={rate.numerator}/{rate.denominator}"]

package/scripts/silence.py

@@ -679,6 +679,10 @@ def main() -> int:
         refuse_existing_outputs([args.timemap])
     media_out = None if (args.list or args.filler_list) else (args.output or default_output(args.input, "tight"))
     guard_sidecar(args.edl, args.input, args.words, args.filler_words, siblings=(media_out,))
+    if media_out:
+        # the word timings and the filler list are read here, never as an -i: run()'s guard did not
+        # see a cut named like one of them (#522's sweep). Before any decode, so a dry run says it too
+        refuse_output_is_input(media_out, *[p for p in (args.words, args.filler_words) if p])
 
     if not math.isfinite(args.margin) or args.margin < 0:
         # nan made inside_margin() drop every silence and re-encode the whole file unchanged

package/scripts/sync.py

@@ -32,7 +32,7 @@ import os
 import sys
 from typing import Dict, List
 
-from _common.runner import fail_if_classified
+from _common.runner import fail_if_classified, refuse_output_is_input
 from _common import STATE, video_args, add_common, apply_common, emit, aac_args, audio_codec_for, default_output, die, ffmpeg_base, info, probe, run, decode_pcm_mono, rms_envelope
 from _common.emit import record_skip, warn
 from _common.decision import SEEK_MARGIN, frame_rate, grid_at_or_after, length_output_t, silence_filter, stream_starts
@@ -365,6 +365,9 @@ def main() -> int:
 
     if args.replace_audio or args.trim_second:
         output = args.output or default_output(args.reference if args.replace_audio else args.second, "synced", "mp4")
+        # --trim-second's command takes only SECOND as -i, so run()'s guard never saw the reference:
+        # REF named SECOND_synced.mp4 (the default name) or `-o REF` was replaced (#522)
+        refuse_output_is_input(output, args.reference, args.second)
         # second started later (offset > 0)  -> delay it by `offset` (pad the head)
         # second started earlier (offset < 0) -> drop its first `-offset` seconds
         delay_ms = int(round(offset * 1000))

package/scripts/verify.py

@@ -18,6 +18,7 @@ import argparse
 import contextlib
 import io
 import json
+import os
 import subprocess
 import sys
 import tempfile
@@ -318,6 +319,7 @@ def main() -> int:
     # the run will write -- step outputs, caption's sidecars, the cue file -- against every input,
     # through a link or another case of the name included, before the first is written.
     every_input = [str(f) for f in files]
+    every_written: List[str] = []
     for f, _entry, plan, cues in jobs:
         written = [("cue file", str(cues))] if cues else []
         for name, argv in plan:
@@ -328,15 +330,33 @@ def main() -> int:
                     written += [(name, str(Path(out).with_suffix(ext))) for ext in (".srt", ".ass")]
         for name, out in written:
             refuse_output_is_input(out, *every_input, why=f"it is where verify writes the {name!r} step's output for {str(f)!r}")
+        every_written += [out for _name, out in written]
+    if args.report:
+        # the report is written last, over whatever is at its path: one of the names the steps write
+        # (`--report OUT/clip_cut.mp4`) was replaced by the Markdown after the steps had read it (#522)
+        guard_sidecar(args.report, siblings=every_written)
 
     results = []
     started["step"] = True
     for f, entry, plan, cues in jobs:
         info(f"=== {f}")
-        if cues:
+        # the cue file is verify's own write: an existing one is replaced only with --overwrite, as
+        # every step's output is. Without it the caption step fails on it, as a step fails on its
+        # existing output, and the file is left as it was (#522; it was replaced unasked)
+        # A link or a folder at its name is never written through, --overwrite or not.
+        odd = bool(cues and os.path.lexists(cues) and (os.path.islink(cues) or not os.path.isfile(cues)))
+        cues_taken = odd or bool(cues and os.path.lexists(cues) and not FORWARD["overwrite"])
+        if cues and not cues_taken:
             cues.write_text("0:00-0:02 Verification caption\n0:02-0:04 Second | line\n", encoding="utf-8")
         for name, argv in plan:
-            r = step(name, argv, args.timeout)
+            if cues_taken and argv[0] == "caption.py":
+                msg = (f"refusing to write the cue file the caption step reads through {str(cues)!r}: it is a link "
+                       "or not a regular file" if odd else
+                       f"refusing to overwrite the existing cue file {str(cues)!r} the caption step reads: pass --overwrite to replace it")
+                r = {"step": name, "ok": False, "seconds": 0.0, "error": _cell(msg), "kind": "input",
+                     "reason": "output_exists", "message": msg}
+            else:
+                r = step(name, argv, args.timeout)
             entry["steps"].append(r)
             info(f"  {'PASS' if r['ok'] else 'FAIL'}  {name:16s} {r['seconds']:6.1f}s  {r['error']}")
         results.append(entry)