ffmpeg-skill 3.1.4 → 3.1.5

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.4`) | 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.4", "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.4",
+  "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
 
 

package/scripts/_common/emit.py

@@ -915,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,
     )

package/scripts/_common/runner.py

@@ -441,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:
@@ -683,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")
@@ -1705,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/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.