ffmpeg-skill 3.1.3 → 3.1.5

package/README.md

@@ -1,14 +1,7 @@
 <p align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="brand/app-icon-dark.png">
-    <img src="brand/app-icon.png" width="128" alt="ffmpeg-skill app icon">
-  </picture>
-</p>
-
-<p align="center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="brand/logo/ffmpeg-skill-wordmark-white.svg">
-    <img src="brand/logo/ffmpeg-skill-wordmark-black.svg" height="48" alt="ffmpeg-skill">
+    <source media="(prefers-color-scheme: dark)" srcset="brand/logo/ffmpeg-skill-horizontal-on-dark.svg">
+    <img src="brand/logo/ffmpeg-skill-horizontal.svg" height="72" alt="ffmpeg-skill">
   </picture>
 </p>
 
@@ -17,6 +10,7 @@ Claude Code, Cursor, Codex or any MCP client edits your footage with local FFmpe
 No cloud · No API keys · Python standard library</p>
 
 <p align="center">
+  <a href="https://kajisho5.github.io/ffmpeg-skill/"><b>Website</b></a> ·
   <a href="#quick-start"><b>Quick start</b></a> ·
   <a href="docs/demos.md">Demos</a> ·
   <a href="#tools">Tools</a> ·
@@ -32,6 +26,10 @@ No cloud · No API keys · Python standard library</p>
   <a href="https://github.com/sponsors/kajisho5"><img src="https://img.shields.io/badge/sponsor-%E2%9D%A4-ea4aaa?logo=githubsponsors" alt="Sponsor"></a>
 </p>
 
+<p align="center">
+  <a href="https://kajisho5.github.io/ffmpeg-skill/"><img src="brand/og.png" width="720" alt="ffmpeg-skill v3: give your coding agent a video editor. An agent runs probe, cut, fit, export and check, and the final file is measured: 59.98 s, 1080x1920, 30 fps."></a>
+</p>
+
 ```bash
 npx ffmpeg-skill
 ```

package/docs/contract.md

@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
 | Field | Meaning | Changes when |
 |---|---|---|
 | `contract_version` | shape of this document (`2.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`3.1.3`) | any release |
+| `skill.version` | the npm / package.json version (`3.1.5`) | 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`
@@ -149,7 +149,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.1.3", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "3.1.5", "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"},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "3.1.3",
+  "version": "3.1.5",
   "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 42 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
   "keywords": [
     "ffmpeg",

package/scripts/_common/__init__.py

@@ -59,7 +59,7 @@ from _common.runner import (
     ffmpeg_bsfs, ffmpeg_filters, ffmpeg_list_error, require_filter, filter_missing_hint, ffmpeg_release, ffmpeg_version, flush_drawtext_textfiles, INSTALL_HINTS, install_signal_handlers, _is_ffmpeg, _limit_for,
     _odd_dimension_retry, _on_signal, _OutputLock, _pid_dead, place_output, PROBE_TIMEOUT, _progress_line,
     read_text_or_die, refuse_output_is_input, _remember_output, require_tool, run, run_analysis, _run_captured,
-    run_keeping_subtitles, run_tool, _run_with_progress, shell_quote, sibling_temp, _SIGNALS_INSTALLED, _stage_existing_output,
+    run_keeping_subtitles, run_tool, _run_with_progress, shell_quote, sibling_temp, still_input_args, _SIGNALS_INSTALLED, _stage_existing_output,
     STATE, _timed_out, _unwatch, _watch, X264_PRESETS
 )
 from _common.emit import (
@@ -212,7 +212,7 @@ __all__ = [
     "decode_gray_frames", "frame_flow", "label_shot_flow", "MOTION_GRID", "MOTION_SEARCH", "MOTION_STATIC_PX", "MOTION_PAN_SPREAD",
     "_run_captured", "run_keeping_subtitles", "run_tool", "_run_with_progress", "_SCRIPT_FONT_CACHE",
     "_script_font_entry", "script_font_for_text", "script_font_status", "_script_font_uncached", "_SCRIPT_RANGES",
-    "SCRIPTS", "_sdr_bt709", "_set_current_ctx", "_SHAPING_BUILD_CACHE", "SHAPING_SCRIPTS", "shell_quote", "sibling_temp",
+    "SCRIPTS", "_sdr_bt709", "_set_current_ctx", "_SHAPING_BUILD_CACHE", "SHAPING_SCRIPTS", "shell_quote", "sibling_temp", "still_input_args",
     "_SIGNALS_INSTALLED", "signed_time_arg", "_stage_existing_output", "STATE", "SVT_PRESET", "text_width_em",
     "time_arg", "_timed_out", "_to_float", "_to_int", "_unwatch", "validate_color", "verify_output",
     "source_codec_video_args", "drawn_chain", "draws_chroma", "drawn_stream_format", "is_neutral_color", "rgb_island", "label_chain", "matrix_chain", "rgb_chain_to_bt709", "bt709_label_filter", "rgb_to_bt709_filter", "is_rgb", "video_args", "_VS15", "_VS16", "_watch", "WINDOWS_FONTS", "write_plan", "x264_args", "X264_PRESETS",

package/scripts/_common/decision.py

@@ -127,12 +127,18 @@ class MissingFpsError(ValueError):
     silently swallowing a mistyped/missing --fps as an auto-timed line of digits."""
 
 
+def _on_windows() -> bool:
+    """Whether a backslash in a path is a separator (Windows) or a character of the name."""
+    return os.name == "nt"
+
+
 def concat_list_line(path: str) -> str:
     """One `file '...'` line for the concat demuxer. The demuxer reads backslash as an escape
     inside the quoted form, so a Windows path (C:\\Users\\...\\part000.mp4) must be written
     with forward slashes -- ffmpeg opens either spelling on Windows -- and a single quote in the
     name is closed, escaped and reopened. Shared by cut.py (multi-segment) and sequence.py."""
-    escaped = str(path).replace("\\", "/").replace("'", "'\\''")
+    # only on Windows: on POSIX the quoted form takes a backslash literally, and it is part of the name (#408)
+    escaped = (str(path).replace("\\", "/") if _on_windows() else str(path)).replace("'", "'\\''")
     return f"file '{escaped}'"
 
 
@@ -252,8 +258,8 @@ def escape_filter_path(path: str, *, bind: bool = True) -> str:
     must survive both passes needs two levels of escaping, so a Windows drive letter `D:/x.srt` is
     written `D\\\\:/x.srt`; with a single backslash the second pass still splits at the colon and
     ffmpeg reads `/x.srt` as the next option (`Unable to parse "original_size" option value`).
-    Backslashes are turned into forward slashes first (ffmpeg accepts them on Windows), so a backslash
-    never has to be escaped itself; `,`, `;`, `[` and `]` are graph-level characters and survive with
+    On Windows backslashes are turned into forward slashes first (ffmpeg accepts them there); on
+    POSIX a backslash is part of the name and is escaped through both passes (#408); `,`, `;`, `[` and `]` are graph-level characters and survive with
     one backslash. `'` is special: the graph parser also treats a quote as the start of a quoted
     token, so a single `\\'` is consumed by the first pass and "Ryo's Mac/cues.srt" reaches the
     filter as "Ryos Mac/cues.srt" (Unable to open ...). Three backslashes survive both passes
@@ -265,11 +271,23 @@ def escape_filter_path(path: str, *, bind: bool = True) -> str:
     if bind and os.path.isfile(path) and path not in STATE.plan_inputs:
         STATE.plan_inputs.append(path)  # a plan binds subtitle/LUT/font files too (review 6)
     p = str(Path(path))
-    p = p.replace("\\", "/")
+    if _on_windows():
+        p = p.replace("\\", "/")
+    else:
+        # on POSIX a backslash is a character of the name (#408): turning it into `/` opened a
+        # different path, so it is escaped through both passes instead
+        p = p.replace("\\", "\\\\\\\\")
     p = p.replace(":", "\\\\:")
     p = p.replace("'", "\\\\\\'")
     for ch in (",", ";", "[", "]"):
         p = p.replace(ch, "\\" + ch)
+    # the graph parser trims unescaped whitespace at either end of a value (#408: a relative
+    # " lead.srt" opened "lead.srt"); both passes keep an escaped one
+    lead = len(p) - len(p.lstrip())
+    trail = len(p) - len(p.rstrip())
+    if lead or trail:
+        body = p[lead:len(p) - trail] if trail else p[lead:]
+        p = "".join("\\\\" + c for c in p[:lead]) + body + "".join("\\\\" + c for c in p[len(p) - trail:] if trail)
     return p
 
 
@@ -474,7 +492,7 @@ def _cpu_encoder_args(codec: str, crf: int, preset: str, meta: Optional[Dict[str
         return _x264_raw(crf, preset, keep_bt709)
     if codec == "hevc":
         if hdr:
-            x265 = f"log-level=error:colorprim={prim}:transfer={trc}:colormatrix={cs}:range=limited:hdr10-opt=1" if trc == "smpte2084" else f"log-level=error:colorprim={prim}:transfer={trc}:colormatrix={cs}"
+            x265 = f"log-level=error:colorprim={prim}:transfer={trc}:colormatrix={cs}:range=limited:hdr10-opt=1{hdr10_x265_params(v)}" if trc == "smpte2084" else f"log-level=error:colorprim={prim}:transfer={trc}:colormatrix={cs}"
             return ["-c:v", "libx265", "-preset", preset, "-crf", str(_clamped_crf("libx265", crf + 2, 51, crf)), "-pix_fmt", "yuv420p10le", "-tag:v", "hvc1",
                     "-x265-params", x265] + hdr_tags + ["-movflags", "+faststart"]
         params, extra = _sdr_bt709("libx265") if keep_bt709 else ("", [])
@@ -485,7 +503,8 @@ def _cpu_encoder_args(codec: str, crf: int, preset: str, meta: Optional[Dict[str
         if "libsvtav1" in ffmpeg_encoders():
             args = ["-c:v", "libsvtav1", "-preset", str(SVT_PRESET.get(preset, 6)), "-crf", str(_clamped_crf("libsvtav1", crf, 63, crf)), "-pix_fmt", pix]
             if hdr:
-                args += hdr_tags
+                svt = hdr10_svtav1_params(v)
+                args += (["-svtav1-params", svt] if svt else []) + hdr_tags
             elif keep_bt709:
                 params, extra = _sdr_bt709("libsvtav1")
                 args += (["-svtav1-params", params] if params else []) + extra
@@ -508,6 +527,42 @@ def _cpu_encoder_args(codec: str, crf: int, preset: str, meta: Optional[Dict[str
     return []
 
 
+def hdr10_x265_params(v: Dict[str, Any]) -> str:
+    """The source's HDR10 static metadata as x265 options (":master-display=...:max-cll=..."), or "".
+    FFmpeg before 7.0 does not pass the decoded frames' mastering-display / content-light side data
+    to libx265, so without these a 6.1 re-encode wrote PQ video with neither (#401). Given on 7+ too,
+    where they restate what FFmpeg would pass. x265 units: chromaticity 0.00002, luminance 0.0001 cd/m2."""
+    md, cl = _hdr10_parts(v)
+    out = ""
+    if md:
+        c = lambda k: round(md[k] * 50000)
+        out += (f":master-display=G({c('green_x')},{c('green_y')})B({c('blue_x')},{c('blue_y')})R({c('red_x')},{c('red_y')})"
+                f"WP({c('white_point_x')},{c('white_point_y')})L({round(md['max_luminance'] * 10000)},{round(md['min_luminance'] * 10000)})")
+    if cl:
+        out += f":max-cll={cl['max_content']},{cl['max_average']}"
+    return out
+
+
+def hdr10_svtav1_params(v: Dict[str, Any]) -> str:
+    """The same for SVT-AV1 (-svtav1-params), which takes chromaticities and cd/m2 as decimals."""
+    md, cl = _hdr10_parts(v)
+    parts = []
+    if md:
+        f = lambda k: f"{md[k]:.5f}".rstrip("0").rstrip(".")
+        parts.append(f"mastering-display=G({f('green_x')},{f('green_y')})B({f('blue_x')},{f('blue_y')})R({f('red_x')},{f('red_y')})"
+                     f"WP({f('white_point_x')},{f('white_point_y')})L({f('max_luminance')},{f('min_luminance')})")
+    if cl:
+        parts.append(f"content-light={cl['max_content']},{cl['max_average']}")
+    return ":".join(parts)
+
+
+def _hdr10_parts(v: Dict[str, Any]) -> "Tuple[Optional[Dict[str, float]], Optional[Dict[str, int]]]":
+    st = v.get("hdr10_static") or {}
+    if v.get("color_transfer") != "smpte2084":
+        return None, None
+    return st.get("mastering_display"), st.get("content_light")
+
+
 def _clamped_crf(encoder: str, value: int, top: int, requested: int) -> int:
     """`value` capped at the encoder's maximum CRF, the cap recorded (`crf_clamped`) when it
     bites: the HEVC HDR line asks x265 for CRF+2, so --quality 50 or 51 there is encoded at 51."""
@@ -667,7 +722,7 @@ def _x265_hdr_default(v: Dict[str, Any], crf: int, preset: str) -> List[str]:
     cs = v.get("color_space") or "bt2020nc"
     prim = v.get("color_primaries") or "bt2020"
     trc = v.get("color_transfer") or "arib-std-b67"
-    x265 = f"log-level=error:colorprim={prim}:transfer={trc}:colormatrix={cs}:range=limited:hdr10-opt=1" if trc == "smpte2084" else f"log-level=error:colorprim={prim}:transfer={trc}:colormatrix={cs}"
+    x265 = f"log-level=error:colorprim={prim}:transfer={trc}:colormatrix={cs}:range=limited:hdr10-opt=1{hdr10_x265_params(v)}" if trc == "smpte2084" else f"log-level=error:colorprim={prim}:transfer={trc}:colormatrix={cs}"
     return ["-c:v", "libx265", "-preset", preset, "-crf", str(min(51, crf + 2)), "-pix_fmt", "yuv420p10le", "-tag:v", "hvc1",
             "-x265-params", x265, "-colorspace", cs, "-color_primaries", prim, "-color_trc", trc, "-movflags", "+faststart"]
 

package/scripts/_common/emit.py

@@ -137,6 +137,30 @@ def _report_dropped_audio_tracks(meta: Dict[str, Any], ctx: "Context") -> None:
         ctx.notes.append(note_line)
 
 
+def _report_dropped_hdr10_metadata(meta: Dict[str, Any], ctx: "Context") -> None:
+    """A PQ source's mastering-display / content-light metadata that a PQ output came out without
+    (#401): measured on the written file, so whatever encoder or FFmpeg version dropped it is said.
+    An output that is no longer PQ (color.py --to-sdr, an HLG conversion) was converted on purpose."""
+    first = getattr(STATE, "first_input", None)
+    src = first[2] if first and len(first) > 2 else None
+    v = (meta or {}).get("video") or {}
+    if not src or v.get("color_transfer") != "smpte2084":
+        return
+    if len(getattr(STATE, "video_inputs", None) or ()) > 1:
+        return  # several pictures: the first input's metadata need not be the output's source
+    have = v.get("hdr10_static") or {}
+    lost = [k for k in ("mastering_display", "content_light") if src.get(k) and not have.get(k)]
+    if not lost:
+        return
+    names = {"mastering_display": "mastering display", "content_light": "content light level"}
+    warn("the source's HDR10 " + " and ".join(names[k] for k in lost) + " metadata did not come through to this output "
+         "(the encoder or this FFmpeg build did not write it); players may tone-map it differently",
+         "hdr10_metadata_dropped", ctx=ctx, dropped=lost, codec=v.get("codec"))
+    note_line = ctx.warnings[-1]["message"] if ctx.warnings else None
+    if note_line and note_line not in ctx.notes:
+        ctx.notes.append(note_line)
+
+
 def refuse(kind: str, reason: str, msg: str, *, hint: Optional[str] = None, code: int = 1,
            ctx: "Optional[Context]" = None, extra: "Optional[Dict[str, Any]]" = None, **details: Any) -> "None":
     """die() for a refusal a caller has to act on: `error.reason` is a stable snake_case code for
@@ -178,8 +202,9 @@ def record_skip(msg: str, code: str, *, ctx: "Optional[Context]" = None, **data:
 
 
 def note(msg: str, ctx: "Optional[Context]" = None) -> None:
-    """A plain `notes` line that also goes to stderr."""
+    """A plain `notes` line that also goes to stderr, made inert as messages are (#400)."""
     ctx = ctx or STATE
+    msg = neutralize(msg)
     if msg not in ctx.notes:
         ctx.notes.append(msg)
     sys.stderr.write(f"{msg}\n")
@@ -682,6 +707,7 @@ def emit(output: Optional[str], *, ctx: "Optional[Context]" = None, **extra: Any
     if output and not ctx.dry_run:
         meta = verify_output(output)  # dies (status: failed, kind: output) if the artifact is unusable
         _report_dropped_audio_tracks(meta, ctx)
+        _report_dropped_hdr10_metadata(meta, ctx)
     if ctx.json:
         doc: Dict[str, Any] = {"status": "completed", "output": output, "dry_run": ctx.dry_run, "commands": list(ctx.commands)}
         if meta:
@@ -889,13 +915,22 @@ def write_plan(path: str, output: Optional[str], extra: Dict[str, Any], ctx: "Op
         platform = {"youtube": "youtube", "youtube4k": "youtube", "reels": "reels", "x": "x"}.get(cleaned[cleaned.index("--preset") + 1])
     if platform and output and tool != "check":
         verify.append({"tool": "check", "platform": platform})
+    plan_inputs = _plan_inputs(ctx.commands, cleaned, ctx)
+    real = os.path.realpath(path)
+    # every file the plan names (#413 review): its inputs, side inputs included (an SRT, a still),
+    # and the output it promises, a default name too, which apply_common could not know
+    for named in plan_inputs + ([output] if output else []):
+        if os.path.realpath(named) == real:
+            refuse("input", "output_is_input" if named != output else "output_path_taken",
+                   f"--plan {path!r} is also {'the output' if named == output else 'an input'} of this run "
+                   f"({named!r}); give the plan its own path", output=path, other=named)
     doc = {
         "plan_version": PLAN_VERSION,
         "created": datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
         "tool": tool,
         "argv": cleaned,
         "cwd": os.getcwd(),
-        "inputs": [fingerprint(p) for p in _plan_inputs(ctx.commands, cleaned, ctx)],
+        "inputs": [fingerprint(p) for p in plan_inputs],
         # inputs that did not exist yet, so carry no fingerprint (render.py reports them on execution)
         "unbound_inputs": _plan_unbound_inputs(ctx.commands, ctx),
         "commands": list(ctx.commands),

package/scripts/_common/probe.py

@@ -13,7 +13,7 @@ import statistics
 from fractions import Fraction
 from typing import Any, Dict, List, Optional, Sequence, Tuple
 from _common.emit import die, warn
-from _common.runner import STATE, dry_run_input_pending, require_tool, run, run_analysis
+from _common.runner import STATE, dry_run_input_pending, require_tool, run, run_analysis, still_input_args
 
 
 def fingerprint(path: str) -> Dict[str, Any]:
@@ -187,7 +187,8 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
         die(f"input not found: {path}")
     ffprobe = require_tool("ffprobe")
     proc = run(
-        [ffprobe, "-v", "error", "-print_format", "json", "-show_format", "-show_streams", "-show_chapters", path],
+        [ffprobe, "-v", "error", *still_input_args(path),
+         "-print_format", "json", "-show_format", "-show_streams", "-show_chapters", path],
         quiet=True,
         check=False,
     )
@@ -317,6 +318,10 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
             "hdr_format": (("Dolby Vision %s" % (("profile %s" % dovi["profile"]) if dovi and dovi.get("profile") is not None else "")).strip() if dovi else
                            "HDR10/PQ" if trc == "smpte2084" else "HLG" if trc == "arib-std-b67" else "BT.2020 SDR" if hdr else None),
             "dolby_vision": dovi,
+            # HDR10 static metadata (mastering display, content light level) as the encoders take it:
+            # FFmpeg before 7 does not hand it from the decoded frames to libx265 / libsvtav1, so the
+            # tools pass it explicitly (decision.hdr10_x265_params). None when the source has none.
+            "hdr10_static": _hdr10_static(ffprobe, path, video) if trc == "smpte2084" else None,
             "color_space": video.get("color_space"),
             "color_primaries": video.get("color_primaries"),
             "color_transfer": video.get("color_transfer"),
@@ -355,13 +360,76 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
             "language": (a.get("tags") or {}).get("language"),
             "title": (a.get("tags") or {}).get("title"),
         } for n, a in enumerate(s for s in streams if s.get("codec_type") == "audio")]
+    if role == "input" and out.get("video") and out["video"].get("codec") \
+            and os.path.splitext(path)[1].lower() not in _STILL_EXT:
+        # a still (an overlay's logo, an insert card) is not a second picture source (#412 review)
+        STATE.video_inputs.add(os.path.realpath(path))
     if role == "input" and out.get("audio_streams"):
         STATE.audio_inputs.add(os.path.realpath(path))
     if role == "input" and getattr(STATE, "first_input", None) is None:
-        STATE.first_input = (path, len(out.get("audio_streams") or []))
+        STATE.first_input = (path, len(out.get("audio_streams") or []),
+                             (out.get("video") or {}).get("hdr10_static"))
     return out
 
 
+def _hdr10_static(ffprobe: str, path: str, stream: Dict[str, Any]) -> "Optional[Dict[str, Any]]":
+    """A PQ stream's mastering display and content light level, from the stream (an mdcv/clli box,
+    a Matroska colour element) or else its first frame (the HEVC SEI / AV1 metadata OBU): one
+    frame is decoded when either part is missing or incomplete in the stream. Each part is taken
+    from wherever it is complete first, the stream before the frame. Chromaticities are CIE 1931
+    x/y, luminances cd/m2. None when it has neither."""
+    out = _hdr10_parts(stream.get("side_data_list") or [])
+    if len(out) < 2:
+        # V:0, not v:0: an attached cover picture before the motion video has no HDR side data
+        proc = run([ffprobe, "-v", "error", "-select_streams", "V:0", "-read_intervals", "%+#1", "-show_frames",
+                    "-show_entries", "frame=side_data_list", "-of", "json", path], quiet=True, check=False)
+        frames: List[Dict[str, Any]] = []
+        if proc.returncode == 0:
+            try:
+                frames = json.loads(proc.stdout or "{}").get("frames") or []
+            except ValueError:
+                pass
+        for k, v in _hdr10_parts((frames[0].get("side_data_list") or []) if frames else []).items():
+            out.setdefault(k, v)
+    return out or None
+
+
+def _hdr10_parts(sides: Sequence[Dict[str, Any]]) -> Dict[str, Any]:
+    """The complete parts in one side-data list: a mastering display with every field, a content
+    light level with both values; an incomplete record counts as absent."""
+    out: Dict[str, Any] = {}
+    for sd in sides:
+        kind = _side_kind(sd)
+        if kind == "mastering" and "mastering_display" not in out:
+            vals = {k: _ratio(sd.get(k)) for k in ("red_x", "red_y", "green_x", "green_y", "blue_x", "blue_y",
+                                                    "white_point_x", "white_point_y", "min_luminance", "max_luminance")}
+            if all(v is not None for v in vals.values()):
+                out["mastering_display"] = {k: float(v) for k, v in vals.items()}
+        elif kind == "light" and "content_light" not in out:
+            mc, ma = _to_int(sd.get("max_content")), _to_int(sd.get("max_average"))
+            if mc is not None and ma is not None:
+                out["content_light"] = {"max_content": mc, "max_average": ma}
+    return out
+
+
+_STILL_EXT = (".png", ".jpg", ".jpeg", ".webp", ".bmp", ".tif", ".tiff", ".gif", ".avif", ".heic")
+
+
+def _ratio(v: Any) -> "Optional[Fraction]":
+    """A side-data value such as "34000/50000" or "0/10000". Unlike _fraction() a zero is a value
+    (a mastering display's minimum luminance may be 0 cd/m2); only a missing or malformed one is None."""
+    try:
+        f = Fraction(str(v))
+    except (ValueError, ZeroDivisionError, TypeError):
+        return None
+    return f if f >= 0 else None
+
+
+def _side_kind(sd: Dict[str, Any]) -> "Optional[str]":
+    t = str(sd.get("side_data_type") or "")
+    return "mastering" if t == "Mastering display metadata" else "light" if t == "Content light level metadata" else None
+
+
 def _bit_depth(pix_fmt: Optional[str]) -> int:
     """Bits per component from a pixel format name. `"10" in pix` used to read yuv410p (4:1:0
     chroma) as 10-bit; the depth is the number that ends the name (before an le/be suffix):

package/scripts/_common/runner.py

@@ -324,7 +324,7 @@ class Context:
 
     __slots__ = ("dry_run", "json", "json_brief", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written", "preexisting", "plan", "plan_written", "plan_inputs", "codec",
                  "hw", "hw_source", "hw_notes", "hw_swaps", "hw_fallback", "hw_env_ignored", "hw_stages", "hw_auto",
-                 "notes", "warnings", "fallbacks", "skipped", "audit_log", "stage_verification", "first_input", "audio_inputs")
+                 "notes", "warnings", "fallbacks", "skipped", "audit_log", "stage_verification", "first_input", "audio_inputs", "video_inputs")
 
     def __init__(self) -> None:
         self.reset()
@@ -333,6 +333,7 @@ class Context:
         self.dry_run = False      # print ffmpeg commands, run nothing (ffprobe still runs)
         self.json = False         # emit() prints a JSON document instead of the output path
         self.first_input = None   # (path, audio track count) of the first input probed: emit() reports tracks the output left out
+        self.video_inputs = set()  # real paths of the inputs probed that have a picture: with two or more, which one the output shows is the tool's choice (sync --trim-second, a join)
         self.audio_inputs = set()  # real paths of the inputs probed that have sound: with two or more, whose tracks an output should keep is the tool's choice (grid --audio-from, a mix)
         self.json_brief = False   # --json-brief: the same document trimmed to the fields a caller acts on
         self.progress = False     # run() streams percent / ETA to stderr for ffmpeg
@@ -440,6 +441,13 @@ def apply_common(args: "argparse.Namespace") -> None:
     STATE.progress = bool(getattr(args, "progress", False))
     STATE.fast = bool(getattr(args, "fast", False))
     STATE.overwrite = bool(getattr(args, "overwrite", False))
+    if STATE.plan:
+        # the plan is a file this run writes itself: the side-file guards apply (#408), so it
+        # never replaces an input, the output or an existing file without --overwrite
+        named = [getattr(args, k, None) for k in ("input", "inputs", "reference", "compare")]
+        inputs = [p for v in named for p in (v if isinstance(v, (list, tuple)) else [v]) if isinstance(p, str)]
+        out = getattr(args, "output", None)
+        guard_sidecar(STATE.plan, *inputs, siblings=(out,) if isinstance(out, str) else ())
     if getattr(args, "timeout", None) is not None:
         STATE.timeout = max(0.0, float(args.timeout))
     else:
@@ -682,11 +690,15 @@ def video_encoder_of(cmd: Sequence[str]) -> Optional[str]:
 # while every guard here reads it as a path. Two or more letters, so a Windows
 # drive letter (`C:\x.mp4`) is a path; `pipe:` is the skill's own stdout/stdin and stays allowed.
 _URL_SCHEME = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]+:")
+# Off Windows there are no drive letters, and ffmpeg reads a one-letter `x:y.mp4` as protocol `x`
+# too (#408: it then failed as "Protocol not found", with no hint that ./x:y.mp4 works)
+_URL_SCHEME_POSIX = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:")
 
 
 def looks_like_url(value: str) -> bool:
     """True for a value ffmpeg would open through a protocol rather than as a local file."""
-    return bool(_URL_SCHEME.match(value)) and not value.startswith("pipe:")
+    scheme = _URL_SCHEME if os.name == "nt" else _URL_SCHEME_POSIX
+    return bool(scheme.match(value)) and not value.startswith("pipe:")
 
 
 _PLAYLIST_SUFFIXES = (".m3u8", ".m3u", ".ffconcat")
@@ -1704,13 +1716,34 @@ def place_output(src: str, dst: str, move: bool = False) -> None:
     _remember_output(cmd)
 
 
+# extensions ffmpeg opens through the image2 demuxer, the only one that expands `%d` in a name
+# and the only one that has a `pattern_type` option (gif, avif, mp4... reject it: "Option
+# pattern_type not found")
+_IMAGE2_EXT = (".png", ".jpg", ".jpeg", ".webp", ".bmp", ".tif", ".tiff", ".dpx", ".exr", ".tga",
+               ".ppm", ".pgm", ".pbm", ".pam", ".sgi", ".jp2", ".j2k", ".xbm", ".xpm", ".pcx", ".qoi")
+
+
+def still_input_args(path: str) -> List[str]:
+    """`-pattern_type none` for a still read through image2 whose path has a `%` in it (#408):
+    image2 otherwise reads `logo%d.png` as a numbered sequence and opens `logo1.png`, a file the
+    run's guards and fingerprints never looked at. Empty for every other path, a video or a GIF
+    with a `%` in its name included: their demuxers never expand it and reject the option."""
+    p = str(path)
+    return ["-pattern_type", "none"] if "%" in p and os.path.splitext(p)[1].lower() in _IMAGE2_EXT else []
+
+
 def sibling_temp(dst: str, tag: str) -> str:
     """A hidden path next to `dst`, with its extension (the muxer is chosen by it), for a file
     place_output(..., move=True) renames into place: same directory, so the rename never
     crosses a filesystem."""
     d, base = os.path.split(dst)
     stem, ext = os.path.splitext(base)
-    return os.path.join(d, f".{stem}.ffskill-{tag}-{os.getpid()}{ext}")
+    path = os.path.join(d, f".{stem}.ffskill-{tag}-{os.getpid()}{ext}")
+    n = 1
+    while os.path.lexists(path):  # a leftover of an earlier run with this pid: not ours to replace
+        n += 1
+        path = os.path.join(d, f".{stem}.ffskill-{tag}-{os.getpid()}-{n}{ext}")
+    return path
 
 
 _DRAWTEXT_TMPDIR: "Optional[str]" = None

package/scripts/_contract.py

@@ -464,7 +464,8 @@ DIAGNOSTIC_CODES = {
     "crf_clamped": ("warnings", "the CRF handed to the encoder was above its maximum and was capped (the HEVC HDR line adds 2); {encoder, requested, asked, used}"),
     # fonts and text
     "emoji_not_drawn": ("warnings", "caption.py --emoji auto: no glyph, colour path or PNG asset draws these emoji here (doctor fonts.emoji mode none), so they were left out of the drawn text; {count, reason}"),
-    "audio_tracks_dropped": ("warnings", "the source has more audio tracks than the output kept (the tools write one; cut.py also reports dropped_audio_streams); {source, kept, dropped}"),
+    "hdr10_metadata_dropped": ("warnings", "a PQ output measured without the source's HDR10 mastering-display and/or content-light metadata (an encoder with no option for it, e.g. prores_ks or libaom on FFmpeg before 7); {dropped, codec}"),
+    "audio_tracks_dropped": ("warnings", "the source has more audio tracks than the output kept (the tools write one; cut.py also reports dropped_audio_streams). Not compared when two or more inputs have sound (grid --audio-from, a mix): which source the output carries is the tool's choice; {source, kept, dropped}"),
     "grid_no_drawtext": ("fallbacks", "grid.py --label auto on a build without the drawtext filter: the cells were not labelled, as with --label none"),
     "scenes_sheet_no_drawtext": ("fallbacks", "scenes.py --sheet on a build without the drawtext filter: the sheet was drawn without timecode stamps, as with --no-timecode"),
     "look_no_drawtext": ("fallbacks", "look.py on a build without the drawtext filter: the sheet was drawn without timecode stamps, as with --no-timecode"),

package/scripts/batch.py

@@ -34,7 +34,7 @@ from typing import Any, Dict, List, Optional
 
 from _common import STATE, add_common, apply_common, child_args, die, emit, info, run_tool, MEDIA_EXT as _MEDIA_EXT
 from _common.runner import HW_FORCED_ENV, add_hw_orchestrator_args, env_hw, stop_children
-from _common.emit import absorb_stage_hw, audit, note, steps_encoder_report, warn
+from _common.emit import absorb_stage_hw, audit, note, shown, steps_encoder_report, warn
 
 HERE = Path(__file__).resolve().parent
 MEDIA_EXT = {e for e in _MEDIA_EXT if e not in (".png", ".jpg", ".jpeg", ".webp")}  # one list (_common); a batch walks media, not stills
@@ -722,7 +722,7 @@ def main() -> int:
         why = (" (reencode_reason: " + ", ".join(f"{k} x{v}" for k, v in reasons.items()) + ")") if reasons else ""
         info(f"cut.py: {copied}/{len(all_cuts)} call(s) stayed fully lossless stream-copy "
              f"({cut_summary['stream_copy_rate']:.0%}), {len(all_cuts) - copied} re-encoded a range or its --segments join{why}")
-    unverified = [os.path.basename(r["file"]) for r in results if r.get("ok") and not r.get("verified")]
+    unverified = [shown(os.path.basename(r["file"])) for r in results if r.get("ok") and not r.get("verified")]
     if unverified and not STATE.dry_run:
         note(f"{len(unverified)} item(s) completed but did not verify everything they wrote (see each row's unverified): "
              + ", ".join(unverified[:5]) + (" ..." if len(unverified) > 5 else ""))

package/scripts/caption.py

@@ -44,7 +44,8 @@ from typing import Any, Dict, List, Optional, Tuple
 from _platforms import (PLATFORMS, PLATFORM_CHOICES, ASS_SCRIPT_HEIGHT, ass_units,
                         resolve as resolve_platform)
 from _ass_overlay import EMOJI_SENTINEL, emoji_placeholder, ass_escape
-from _common import require_filter, emoji_filter_chain, EMOJI_ASSET_HINT, emoji_asset_for, emoji_codepoint_name, emoji_support, resolve_emoji_assets, ADVANCE_EM, LATIN_EM, NO_SPACE_SCRIPTS, _char_em, char_script, text_width_em, emoji_clusters, has_emoji, detect_script, BIDI_SCRIPTS, STATE, brand_states_font, script_font_for_text, signed_time_arg, brand_caption_style, color_hex, drawn_chain, label_chain, load_brand, rgb_chain_to_bt709, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, fmt_smpte_time, info, MissingFpsError, parse_time, probe, run, x264_args, X264_PRESETS, read_text_or_die, fmt_secs, refuse_existing_outputs
+from _common.emit import refuse  # noqa: E402
+from _common import require_filter, emoji_filter_chain, EMOJI_ASSET_HINT, emoji_asset_for, emoji_codepoint_name, emoji_support, resolve_emoji_assets, ADVANCE_EM, LATIN_EM, NO_SPACE_SCRIPTS, _char_em, char_script, text_width_em, emoji_clusters, has_emoji, detect_script, BIDI_SCRIPTS, STATE, brand_states_font, script_font_for_text, signed_time_arg, brand_caption_style, color_hex, drawn_chain, label_chain, load_brand, rgb_chain_to_bt709, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, fmt_smpte_time, info, MissingFpsError, parse_time, probe, run, x264_args, X264_PRESETS, read_text_or_die, fmt_secs, refuse_existing_outputs, guard_sidecar
 # The line breaker, lifted into _common/text.py in 1.16.0 so graphics.py can use the same rules.
 # The ASR bridge and the SRT reader/writer live in _common.asr since 1.17 (silence.py --filler
 # shares them). They stay caption.py's public names -- every caller and test that reached for
@@ -1276,28 +1277,52 @@ def main() -> int:
     # next to the output was replaced on a re-run, even one ffmpeg's check then refused.
     # Side files whose existence depends on the cues (an _adjusted.srt, an emoji-forced ASS) are
     # checked again where they are written, still before that write.
-    claimed: set = set()
-
-    def claim(paths) -> None:
-        todo = [p for p in paths if p and os.path.realpath(p) not in claimed]
+    claimed: Dict[str, str] = {}  # real path -> which artifact of this run holds it
+
+    def claim(items) -> None:
+        """Reserve (path, artifact) pairs: the same artifact claiming its path again is a no-op,
+        another artifact of this run claiming it is refused (#413 review: --write-srt and
+        --write-ass naming one file, the SRT then replaced by the ASS)."""
+        todo = []
+        for path, owner in items:
+            if not path:
+                continue
+            real = os.path.realpath(path)
+            held = claimed.get(real)
+            if held is None and os.path.exists(real):
+                # a second name for the same file (a hard link) is the same path (#413 review)
+                held = next((o for r, o in claimed.items()
+                             if os.path.exists(r) and os.path.samefile(r, real)), None)
+            if held is None:
+                claimed[real] = owner
+                todo.append(path)
+            elif held != owner:
+                refuse("input", "output_path_taken",
+                       f"{path!r} is named for both the {held} and the {owner} this run writes; give each its own path",
+                       output=path, other=held)
         refuse_existing_outputs(todo)
-        claimed.update(os.path.realpath(p) for p in 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
+        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)]
+        for path in todo:
+            guard_sidecar(path, *side_inputs)
 
     planned_out = args.output or (default_output(args.input, "captioned") if args.input else None)
-    up_front: List[str] = []
+    up_front: List[Tuple[str, str]] = []
     if args.transcribe:
-        up_front.append(args.write_srt or os.path.splitext(planned_out)[0] + ".srt")
+        up_front.append((args.write_srt or os.path.splitext(planned_out)[0] + ".srt", "SRT"))
     elif args.text:
-        up_front.append(args.write_srt or (os.path.splitext(planned_out)[0] + ".srt" if args.input
-                                           else os.path.splitext(args.text)[0] + ".srt"))
+        up_front.append((args.write_srt or (os.path.splitext(planned_out)[0] + ".srt" if args.input
+                                            else os.path.splitext(args.text)[0] + ".srt"), "SRT"))
     if args.input:
         if (args.animate != "none" or args.karaoke) and not args.ass:
-            up_front.append(args.write_ass or os.path.splitext(planned_out)[0] + ".ass")
+            up_front.append((args.write_ass or os.path.splitext(planned_out)[0] + ".ass", "ASS"))
         if args.ass and args.offset and os.path.exists(args.ass):
-            up_front.append(os.path.splitext(planned_out)[0] + "_offset.ass")
+            up_front.append((os.path.splitext(planned_out)[0] + "_offset.ass", "offset ASS"))
         # -o naming the input itself keeps its own, more specific refusal (_check_no_overwrite_input)
         if os.path.realpath(planned_out) != os.path.realpath(args.input):
-            up_front.append(planned_out)
+            up_front.append((planned_out, "video"))
     claim(up_front)
     if args.transcribe:
         # the sidecar goes next to the output like the --text one, not into the source folder
@@ -1358,7 +1383,7 @@ def main() -> int:
         adjusted, changed = lay_out(parse_srt(srt_path))
         if changed:
             new_srt = os.path.splitext(output)[0] + "_adjusted.srt"
-            claim([new_srt])
+            claim([(new_srt, "adjusted SRT")])
             if STATE.dry_run:
                 info(f"[dry-run] would write {new_srt} ({len(adjusted)} cues, adjusted from {os.path.basename(srt_path)})")
             else:
@@ -1563,7 +1588,7 @@ def main() -> int:
         if args.karaoke and not getattr(args, "_word_timings", None):
             args._word_timings = whisper_word_timings(srt_path)
         ass_path = args.write_ass or os.path.splitext(output)[0] + ".ass"
-        claim([ass_path])
+        claim([(ass_path, "ASS")])
         w, h = meta["video"]["width"], meta["video"]["height"]
         if meta["video"].get("rotation") in (90, -90, 270, -270):
             w, h = h, w

package/scripts/graphics.py

@@ -32,7 +32,7 @@ import sys
 from typing import List, Optional, Tuple
 
 from _platforms import PLATFORMS, PLATFORM_CHOICES, safe_margins_px, resolve as resolve_platform
-from _common import (require_filter, aac_args, add_common, brand_caption_style, script_font_for_text, apply_common, cfr_args,
+from _common import (guard_sidecar, require_filter, aac_args, add_common, brand_caption_style, script_font_for_text, apply_common, cfr_args,
                      color_hex, default_output, die, draws_chroma, drawn_chain, emit, escape_drawtext, escape_filter_path,
                      ffmpeg_base, info, label_chain, load_brand, parse_time, probe, rgb_chain_to_bt709, run, run_keeping_subtitles, video_args,
                      drawtext_boxborderw, drawtext_center_align, X264_PRESETS, time_arg, fmt_secs, STATE, drawtext_text_opts,
@@ -648,6 +648,10 @@ def main(force_route: Optional[str] = None) -> int:
                             "overlays": len(emoji_overlays)}
         ass_path = args.write_ass or os.path.splitext(output)[0] + "_gfx.ass"
         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,))
         if STATE.dry_run:
             info(f"[dry-run] would write {ass_path} ({len(elements)} text elements)")
         else:

package/scripts/insert.py

@@ -27,6 +27,7 @@ import argparse
 import math
 import sys
 
+from _common import still_input_args  # noqa: E402
 from _common import add_common, apply_common, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, video_args, X264_PRESETS, time_arg, fmt_secs
 
 
@@ -115,7 +116,7 @@ def main() -> int:
         ]
 
     output = args.output or default_output(args.input, "insert", "mp4")
-    cmd = ffmpeg_base() + ["-loop", "1", "-i", args.input, "-t", f"{target:.3f}", "-vf", ",".join(vf)]
+    cmd = ffmpeg_base() + ["-loop", "1", *still_input_args(args.input), "-i", args.input, "-t", f"{target:.3f}", "-vf", ",".join(vf)]
     # the SDR line, whatever the image is; its RGB (PNG) or BT.601 (JPEG) pixels are converted to
     # the BT.709 that line is tagged with
     cmd += video_args(None, args.crf, args.preset, source=meta)

package/scripts/look.py

@@ -17,6 +17,7 @@ from pathlib import Path
 from typing import List, Optional
 
 from _platforms import PLATFORMS, PLATFORM_CHOICES, resolve as resolve_platform
+from _common import still_input_args  # noqa: E402
 from _common import STATE, require_tool, add_common, apply_common, default_font_file, die, emit, escape_drawtext, ffmpeg_base, info, parse_time, probe, run, run_analysis, time_arg
 from _common import drawtext_fontfile  # noqa: E402
 from _common import ffmpeg_filters, filter_missing_hint  # noqa: E402
@@ -239,8 +240,8 @@ def main() -> int:
             tcs = tc.replace("," + timecode_filter(font_prefix), "") + stamp
             fc = (f"[0:v]scale={half}:-2{tcs}[a];[1:v]scale={half}:-2{tcs}[b];"
                   f"[a][b]scale2ref=w=iw:h=ih[a2][b2];[a2][b2]hstack=inputs=2[out]")
-            cmd = ffmpeg_base() + ["-ss", f"{sec:.3f}", "-i", args.input, "-ss", f"{sec:.3f}", "-i", args.compare,
-                                   "-filter_complex", fc, "-map", "[out]", "-frames:v", "1", out]
+            cmd = ffmpeg_base() + ["-ss", f"{sec:.3f}", *still_input_args(args.input), "-i", args.input, "-ss", f"{sec:.3f}", *still_input_args(args.compare), "-i", args.compare,
+                                   "-filter_complex", fc, "-map", "[out]", "-frames:v", "1", "-update", "1", out]
             run(cmd)
             outputs.append(out)
     elif args.at:
@@ -254,7 +255,7 @@ def main() -> int:
                 # several frames, or -o given as a stem/prefix without an image extension
                 out = os.path.join(outdir, f"{args.output and Path(args.output).stem or stem}_{sec:.3f}s.png")
             stamp = "" if args.no_timecode else f",drawtext=text='{escape_drawtext(fmt_hms(sec))}':{font_prefix}{FONT}"
-            cmd = ffmpeg_base() + ["-ss", f"{sec:.3f}", "-i", args.input, "-vf", f"scale={args.width}:-2{tc.replace(',' + timecode_filter(font_prefix), '')}{stamp}", "-frames:v", "1", out]
+            cmd = ffmpeg_base() + ["-ss", f"{sec:.3f}", *still_input_args(args.input), "-i", args.input, "-vf", f"scale={args.width}:-2{tc.replace(',' + timecode_filter(font_prefix), '')}{stamp}", "-frames:v", "1", "-update", "1", out]
             run(cmd)
             outputs.append(out)
     else:
@@ -281,7 +282,7 @@ def main() -> int:
         tc_sheet = tc.replace(timecode_filter(font_prefix), timecode_filter(font_prefix, seek)) if seek else tc
         vf = (f"select='isnan(prev_selected_t)+gte(t-prev_selected_t\\,{step * 0.98:.6f})',scale={tile_w}:-2{tc_sheet},"
               f"tile={cols}x{rows}:padding=2:margin=2:color=0x202020")
-        cmd = ffmpeg_base() + ["-ss", f"{seek:.6f}", "-i", args.input, "-vf", vf, "-frames:v", "1", out]
+        cmd = ffmpeg_base() + ["-ss", f"{seek:.6f}", *still_input_args(args.input), "-i", args.input, "-vf", vf, "-frames:v", "1", "-update", "1", out]
         run(cmd)
         outputs.append(out)
         info(f"contact sheet: {n} frames every {step:.2f}s")

package/scripts/overlay.py

@@ -30,6 +30,7 @@ import sys
 from typing import List, Optional
 
 from _platforms import PLATFORMS, PLATFORM_CHOICES, safe_margins_px, resolve as resolve_platform
+from _common import still_input_args  # noqa: E402
 from _common import STATE, script_font_for_text, drawtext_clean, drawtext_line_metrics, drawtext_text_opts, drawtext_draws_newline_glyph, is_multiline, needs_shaping, LANGUAGE_NAMES, has_emoji, detect_script, emoji_clusters, load_brand, drawn_chain, label_chain, matrix_chain, rgb_chain_to_bt709, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_drawtext, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, X264_PRESETS, time_arg, fmt_secs
 from _common.emit import warn
 from _common.fonts import font_choice, record_font_choice
@@ -372,7 +373,7 @@ def main() -> int:
         if enable:
             ov += f":enable='{enable}'"
         # -loop 1 turns the still into a timed stream so fade/enable expressions see real timestamps
-        cmd = ffmpeg_base() + ["-i", args.input, "-loop", "1", "-i", args.image]
+        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
         # RGB-to-YUV step used BT.601), and an untagged main is labelled BT.709 (tags only) so
         # 7.1+'s negotiation does not convert one picture to the other's "unknown" matrix

package/scripts/render.py

@@ -342,6 +342,11 @@ def render_pack(names: List[str], args) -> int:
     and platform check), so the pack reports per-platform results rather than one verdict."""
     stem = Path(args.input).with_suffix("").name
     outdir = Path(args.output).parent if args.output else Path(args.input).resolve().parent
+    # the table is a file this run writes itself (#408): an existing one is refused without
+    # --overwrite, before the first destination renders
+    if outdir.is_dir():  # a missing folder is the destinations' own refusal (and a dry run's plan)
+        side = [v for k, v in vars(args).items() if k != "output" and isinstance(v, str) and os.path.isfile(v)]
+        guard_sidecar(str(outdir / f"{stem}_pack.md"), args.input, *side)
     dests = {name: str((load_template(name).get("check") or {}).get("platform") or name) for name in names}
     rows: List[Dict[str, Any]] = []
     outputs: List[str] = []
@@ -399,6 +404,9 @@ def render_pack(names: List[str], args) -> int:
     lines += ["", f"{len(rows)} destinations from one edit ({os.path.basename(args.input)}).",
               "Rendered by ffmpeg-skill; `report.py --pack` turns this table into an HTML report."]
     if not STATE.dry_run:
+        if not outdir.is_dir():
+            die(f"pack: the output folder {outdir} does not exist, so the table was not written", kind="input",
+                pack=rows, outputs=outputs)
         Path(pack).write_text("\n".join(lines) + "\n", encoding="utf-8")
     info(("[dry-run] would write " if STATE.dry_run else "wrote ") + pack)
     if failed:

package/scripts/scenes.py

@@ -302,7 +302,7 @@ def main() -> int:
             stamp = f",drawtext=text='%{{pts\\:hms}}':{font_prefix}fontcolor=white:fontsize=h/14:box=1:boxcolor=black@0.55:boxborderw=4:x=6:y=6"
         vf = (f"select='{expr}',scale={tile_w}:-2{stamp},"
               f"tile={cols}x{rows}:padding=2:margin=2:color=0x202020")
-        run(ffmpeg_base() + ["-i", args.input, "-vf", vf, "-frames:v", "1", "-fps_mode", "vfr", args.sheet])
+        run(ffmpeg_base() + ["-i", args.input, "-vf", vf, "-frames:v", "1", "-fps_mode", "vfr", "-update", "1", args.sheet])
         info(f"wrote {args.sheet}")
         result["sheet"] = args.sheet
 

package/scripts/verify.py

@@ -26,7 +26,7 @@ import time
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
-from _common import STATE, add_common, apply_common, die, emit, info, probe
+from _common import STATE, add_common, apply_common, die, emit, guard_sidecar, info, probe
 
 HERE = Path(__file__).resolve().parent
 MEDIA_EXT = {".mp4", ".mov", ".m4v", ".mkv", ".webm", ".avi", ".mts", ".m2ts", ".mxf", ".wav", ".m4a", ".mp3", ".flac", ".aac"}
@@ -160,9 +160,14 @@ def main() -> int:
     files = collect(args.paths)
     tmp = None
     if args.out:
+        # made first, so a --report inside a new --out folder passes the guard below (#413 review)
         outdir = Path(args.out)
         outdir.mkdir(parents=True, exist_ok=True)
-    else:
+    if args.report:
+        # a file this run writes itself (#408): not one of the media it verifies (a folder's
+        # files included), nor an existing file without --overwrite
+        guard_sidecar(args.report, *args.paths, *map(str, files))
+    if not args.out:
         tmp = tempfile.TemporaryDirectory(prefix="ffskill_verify_")
         outdir = Path(tmp.name)
 

package/scripts/waveform.py

@@ -36,9 +36,10 @@ import sys
 
 from _platforms import PLATFORMS, PLATFORM_CHOICES, resolve as resolve_platform
 from _common.probe import SILENT_PEAK_DBFS
+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,
                      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)
+                     fmt_secs, child_args, run_tool, measured_level_dbfs, sibling_temp)
 from _common.emit import absorb_stage_hw, warn
 
 WAVEFORM_MODES = ["point", "line", "p2p", "cline"]
@@ -207,14 +208,15 @@ def main() -> int:
     if args.title or args.srt or args.text:
         # the visualisation is rendered first and the label/captions are drawn on it by the tools
         # that own those code paths, so neither is re-implemented here
-        stem, ext = os.path.splitext(output)
-        render = stem + "_vis" + ext
+        # hidden, pid-named siblings (#408): a fixed `<out>_vis` name was removed afterwards
+        # whoever had written it, the input or another file of the caller's included
+        render = sibling_temp(output, "vis")
     cmd = ffmpeg_base() + ["-i", args.input]
     if args.image:
         # -framerate before -loop: a looped still defaults to 25 fps, and overlay takes its rate
         # from the FIRST input -- so without this the file came out 25 fps however loud --fps or
         # --platform said otherwise (the colour-plate path never had the bug: `color=` carries r=).
-        cmd += ["-framerate", f"{args.fps:g}", "-loop", "1", "-i", args.image]
+        cmd += ["-framerate", f"{args.fps:g}", "-loop", "1", *still_input_args(args.image), "-i", args.image]
     cmd += ["-filter_complex", vf]
     if args.image:
         cmd += ["-map", "[v]"]
@@ -227,15 +229,20 @@ def main() -> int:
     if meta.get("duration"):
         cmd += ["-t", f"{float(meta['duration']):.3f}"]
     cmd += ["-shortest", render]
-    stem, ext = os.path.splitext(output)
-    intermediates = [p for p in (render, stem + "_titled" + ext) if p != output]
+    titled_tmp = sibling_temp(output, "titled")
+    intermediates = [p for p in (render, titled_tmp) if p != output]
     try:
         run(cmd)
 
         stages = ["waveform"]
         current = render
         if args.title:
-            titled = stem + "_titled" + ext if (args.srt or args.text) else output
+            titled = titled_tmp if (args.srt or args.text) else output
+            if titled == titled_tmp:
+                # graphics.py's libass route writes <its output stem>_gfx.ass beside it (#413 review)
+                titled_ass = os.path.splitext(titled)[0] + "_gfx.ass"
+                if not os.path.exists(titled_ass):
+                    intermediates.append(titled_ass)
             # a dry run rendered no _vis file for graphics.py to probe, so its default --end (the
             # clip's end) came out 0 and the plan failed: give it the source's duration, which
             # is what -t caps the render at. A real run is unchanged.