ffmpeg-skill 3.8.18 → 3.8.20

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

package/scripts/_common/color.py

@@ -360,12 +360,16 @@ def color_hex(value: str) -> str:
     return v.upper()
 
 
-_COLOR_TOKEN_RE = re.compile(r"^(0[xX][0-9A-Fa-f]{6,8}|#[0-9A-Fa-f]{6,8}|[A-Za-z][A-Za-z0-9]*)(@(?:0(?:\.\d+)?|1(?:\.0+)?|\.\d+))?$")  # alpha is 0..1; "red@2" used to reach ffmpeg
+# Six or eight hex digits, with 0x, with # or bare (#535: bare ones starting with a digit, 0B1D2A,
+# were refused, and seven passed with a prefix and failed inside ffmpeg), or a word that starts
+# with a letter; alpha is 0..1 ("red@2" used to reach ffmpeg). Nothing else reaches the graph.
+_HEX_DIGITS = r"(?:[0-9A-Fa-f]{8}|[0-9A-Fa-f]{6})"
+_COLOR_TOKEN_RE = re.compile(r"^((?:0[xX]|#)?%s|[A-Za-z][A-Za-z0-9]*)(@(?:0(?:\.\d+)?|1(?:\.0+)?|\.\d+))?$" % _HEX_DIGITS)
 
 
 def validate_color(value: str, flag: str = "--color") -> str:
-    """Refuse a colour argument that isn't a plain ffmpeg colour token (named colour, 0xRRGGBB[AA],
-    #RRGGBB[AA], optionally with an @alpha suffix). Every caller that string-formats a colour flag
+    """Refuse a colour argument that isn't a plain ffmpeg colour token (named colour, RRGGBB[AA],
+    0xRRGGBB[AA], #RRGGBB[AA], optionally with an @alpha suffix). Every caller that string-formats a colour flag
     straight into a filter graph (color=c=..., tpad=...:color=..., rotate=...:fillcolor=...) must
     validate it first -- ffmpeg filter options are comma/colon-delimited, so an unvalidated value
     containing those characters lets a caller splice in an entirely different filter (a real,
@@ -374,9 +378,10 @@ def validate_color(value: str, flag: str = "--color") -> str:
     invariant every other typed flag in this codebase already holds to."""
     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}'")
+        die(f"{flag} must be a plain colour (a name, or six or eight hex digits RRGGBB[AA], bare or after 0x or #, "
+            f"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):
+    if word[0].isalpha() 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.

package/scripts/_common/decision.py

@@ -21,6 +21,16 @@ 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="
@@ -1374,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/_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/caption.py

@@ -1574,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,
@@ -673,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":
@@ -754,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/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,7 +45,7 @@ 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 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
 
@@ -494,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]
 

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

package/scripts/waveform.py

@@ -38,7 +38,7 @@ import sys
 from _platforms import PLATFORMS, PLATFORM_CHOICES, resolve as resolve_platform
 from _common.probe import SILENT_PEAK_DBFS, refuse_not_a_still, square_pixels, square_pixels_note
 from _common import still_input_args  # noqa: E402
-from _common import (add_common, apply_common, aac_args, default_output, die, draws_chroma, emit, ffmpeg_base,
+from _common import (add_common, apply_common, aac_args, color_hex, default_output, die, draws_chroma, emit, ffmpeg_base,
                      info, load_brand, pad_filters, probe, rgb_chain_to_bt709, run, STATE, validate_color, video_args, X264_PRESETS,
                      fmt_secs, child_args, run_tool, measured_level_dbfs, sibling_temp)
 from _common.emit import absorb_stage_hw, note, warn
@@ -110,10 +110,12 @@ def main() -> int:
     brand = load_brand(args.brand) if args.brand else None
     if brand:
         bc = brand.get("colors") or {}
+        # read as caption.py, graphics.py and overlay.py read a brand colour (#535): a brand file
+        # writes six hex digits with or without # or 0x
         if args.color == "lime" and bc.get("primary"):
-            args.color = bc["primary"]
+            args.color = color_hex(bc["primary"])
         if args.background == "black" and bc.get("background"):
-            args.background = bc["background"]
+            args.background = color_hex(bc["background"])
     if args.image:
         if "://" in args.image:
             die("--image must be a readable local file; this skill has no network access, so save "