ffmpeg-skill 0.12.0 → 0.16.12

package/scripts/_common.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 import json
 import os
 import platform
+import re
 import shutil
 import subprocess
 import sys
@@ -205,6 +206,10 @@ def _cleanup_partial_output(cmd: Sequence[str]) -> None:
     success path, so a failed run() call never routed through it. Remove whatever ffmpeg managed
     to write so a caller scanning the output directory after a failure never mistakes a partial
     artifact for a real (if unverified) one."""
+    # run() also executes ffprobe, whose last argument is an INPUT. Never
+    # interpret a read-only tool's failure as permission to remove that file.
+    if not _is_ffmpeg(cmd):
+        return
     output = cmd[-1]
     if output in ("-", "pipe:0", "pipe:1") or output.startswith("pipe:") or output.startswith("-"):
         return
@@ -269,6 +274,20 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subpr
     return _run_captured(list(cmd), check)
 
 
+def run_keeping_subtitles(cmd: List[str], output: str) -> bool:
+    """Run an ffmpeg command that already maps its video/audio, trying first to also
+    stream-copy any subtitle/data streams the source has (`-map 0:s?`/`0:d?` are no-ops when
+    there are none). A source whose subtitle codec cannot be copied into the target container
+    (e.g. a container change) makes that first attempt fail; retry the same command without the
+    extra maps rather than let a tool that never touched subtitles start hard-failing because of
+    them. `cmd` is the full argv *without* the output path. Returns True only when the
+    retry-without-subtitles path was actually needed (i.e. subtitle/data streams were dropped)."""
+    if run(cmd + ["-map", "0:s?", "-map", "0:d?", "-c:s", "copy", "-c:d", "copy", output], check=False).returncode == 0:
+        return False
+    run(cmd + [output])
+    return True
+
+
 def _run_captured(cmd: List[str], check: bool) -> subprocess.CompletedProcess:
     """Plain run with stdout/stderr captured."""
     proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
@@ -325,7 +344,7 @@ def _run_with_progress(cmd: List[str], check: bool) -> subprocess.CompletedProce
 
 
 def shell_quote(s: str) -> str:
-    if not s or any(ch in s for ch in " \t\"'\;|&<>()[]{}$*?"):
+    if not s or any(ch in s for ch in " \t\\\"';|&<>()[]{}$*?"):
         return "'" + s.replace("'", "'\\''") + "'"
     return s
 
@@ -387,7 +406,7 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
             return {"file": path, "dry_run": True, "format": None, "duration": 0.0, "size_bytes": 0, "bitrate": None,
                     "video": {"codec": None, "width": 0, "height": 0, "fps": 0.0, "pix_fmt": None, "hdr": False,
                               "color_transfer": None, "color_primaries": None, "rotation": 0, "variable_frame_rate_suspected": False},
-                    "audio": {"codec": None, "channels": 0, "sample_rate": 0}, "subtitle_streams": 0}
+                    "audio": {"codec": None, "channels": 0, "sample_rate": 0}, "subtitle_streams": 0, "data_streams": 0}
         die(f"input not found: {path}")
     ffprobe = require_tool("ffprobe")
     proc = run(
@@ -405,6 +424,7 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
     video = next((s for s in streams if s.get("codec_type") == "video" and s.get("disposition", {}).get("attached_pic", 0) == 0), None)
     audio = next((s for s in streams if s.get("codec_type") == "audio"), None)
     subs = [s for s in streams if s.get("codec_type") == "subtitle"]
+    data_stream_count = sum(1 for s in streams if s.get("codec_type") in ("data", "attachment"))
 
     duration = _to_float(fmt.get("duration"))
     if duration is None and video:
@@ -423,6 +443,7 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
         "video": None,
         "audio": None,
         "subtitle_streams": len(subs),
+        "data_streams": data_stream_count,
         # every subtitle stream in file order: index n here is `-map 0:s:n`
         "subtitle_stream_details": [{
             "index": n,
@@ -582,15 +603,84 @@ def escape_filter_path(path: str) -> str:
     return p
 
 
+def default_font_file(font_name: str) -> Optional[str]:
+    """Resolve `font_name` to a concrete on-disk font file, so a caller can tell drawtext
+    `fontfile=<path>` instead of `font=<name>`, when possible.
+
+    On some real Windows ffmpeg builds (winget's gyan.dev 9.x), drawtext's own fontconfig
+    resolution crashes with an access violation whenever it has to resolve a font by family name
+    -- with or without a valid fonts.conf on FONTCONFIG_FILE. `fontfile=` is the only form
+    confirmed not to crash (#100), since it never touches fontconfig at all. `font_name` itself is
+    ignored on Windows for that reason: a fixed, near-universally-present system font is used
+    instead of trying to resolve the requested family (which would crash the same way).
+
+    On Linux/macOS this is best-effort and uses the real requested family: `fc-match` reports the
+    same file fontconfig would resolve `font_name` to anyway, so a caller gets the identical font,
+    just already resolved to a path -- fontfile= skips a redundant fontconfig lookup and equally
+    sidesteps the same class of crash if it exists on some build there too, but the fallback below
+    (returning None) is exercised routinely there, not just on failure.
+
+    Returns None when nothing could be resolved (fc-match missing/unavailable, or no well-known
+    Windows font file present); the caller falls back to font=<font_name>, the prior behaviour.
+    """
+    if platform.system() == "Windows":
+        windir = os.environ.get("WINDIR", "C:\\Windows")
+        candidate = Path(windir) / "Fonts" / "arial.ttf"
+        return str(candidate) if candidate.exists() else None
+    exe = shutil.which("fc-match")
+    if not exe:
+        return None
+    try:
+        proc = subprocess.run([exe, "--format=%{file}\n", font_name], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=5)
+    except (subprocess.TimeoutExpired, OSError):
+        return None
+    if proc.returncode != 0:
+        return None
+    path = proc.stdout.splitlines()[0].strip() if proc.stdout.strip() else ""
+    return path if path and os.path.exists(path) else None
+
+
 def escape_drawtext(text: str) -> str:
+    """Escape `text` for use as a single-quoted drawtext option value (`text='<this>'`).
+
+    Every ffmpeg filter-graph special character (`\\ : % , [ ] ;`) needs a backslash
+    escape regardless of the surrounding quotes -- the graph parser still splits on an
+    unescaped `,`/`;` or ends an option list on an unescaped `:`/`[`/`]` even while
+    "inside" a quoted value. The quote character itself has no reliable backslash
+    escape at all: `\\'` and the POSIX shell `'\\''` close-insert-reopen trick both
+    parse fine in a simple `-vf` chain, but silently corrupt a `-filter_complex` chain
+    that uses explicit `[label]` pads -- confirmed by rendering the result: the text
+    value doesn't end where the quote closes it, and trailing option names/values
+    (fontfile=..., fontsize=...) leak into the rendered picture as literal text
+    instead of being parsed as options. A quote is therefore dropped outright rather
+    than escaped -- losing one apostrophe from a label is a fine trade for "the
+    filter graph parses the way the code intends, on every call shape this codebase
+    uses it in".
+
+    `%` has the same problem the quote character did: `\%` is not a real escape as
+    far as drawtext's own text-expansion scanner (on by default, `expansion=normal`,
+    for `%{pts}`/`%{localtime}`/etc.) is concerned -- a bare backslash-escaped `%`
+    always logs "Stray % near ..." (confirmed with the minimal case
+    `text='100\%done'`), which is merely noisy on one ffmpeg
+    build (the warning is printed, the file still gets written) but a hard filtering
+    failure that writes no output at all on another. Every caller of this function
+    only ever wants a literal label, never `%{...}` expansion, so `%` is dropped
+    outright rather than chasing a per-build-safe escape (`expansion=none` on the
+    filter would also fix it, but needs touching every drawtext= call site instead
+    of the one shared helper). Control characters (newline, tab, ...) are dropped
+    for the same reason: none are meaningful in a one-line burnt-in label, and
+    unlike the graph-special characters above, ffmpeg's own text-expansion scanner
+    -- not just the graph parser -- is involved in whether they're actually safe."""
+    text = re.sub(r"[\x00-\x1f\x7f]", "", text)
     return (
-        text.replace("\\", "\\\\")
+        text.replace("'", "")
+        .replace("%", "")
+        .replace("\\", "\\\\")
         .replace(":", "\\:")
-        .replace("'", "\\\\\\'")
-        .replace("%", "\\%")
         .replace(",", "\\,")
         .replace("[", "\\[")
         .replace("]", "\\]")
+        .replace(";", "\\;")
     )
 
 
@@ -762,6 +852,23 @@ 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-9.]+)?$")
+
+
+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
+    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,
+    demonstrated filter-graph injection: --color "black,drawtext=text=..." renders arbitrary burnt-in
+    text), not just an odd colour. This is the same "no filter graph accepted from the caller"
+    invariant every other typed flag in this codebase already holds to."""
+    if not _COLOR_TOKEN_RE.match(value):
+        die(f"{flag} must be a plain colour (a name, 0xRRGGBB[AA], or #RRGGBB[AA], optionally @alpha), got '{value}'")
+    return value
+
+
 def print_json(obj: Any) -> None:
     sys.stdout.write(json.dumps(obj, indent=2, ensure_ascii=False) + "\n")
 

package/scripts/_contract.py

@@ -79,6 +79,42 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
     "crop": dict(role="execution", inputs=["video asset"], outputs=["video artifact cropped to the given pixel rectangle"],
                  required=FF + [X264, AAC], optional=[HDR_X265],
                  video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
+    "deinterlace": dict(role="execution", inputs=["video asset"], outputs=["deinterlaced (progressive) video artifact"],
+                        required=FF + [X264, AAC, "filter:yadif"], optional=[HDR_X265],
+                        video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
+    "denoise": dict(role="execution", inputs=["video asset"], outputs=["denoised video artifact"],
+                    required=FF + [X264, AAC, "filter:hqdn3d"], optional=[HDR_X265],
+                    video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
+    "cropdetect": dict(role="analysis", inputs=["video asset"], outputs=["detected crop rectangle JSON on stdout (no file)"],
+                       required=FF + ["filter:cropdetect"], optional=[],
+                       video_required=True, audio_only=False, visual=False, verify=[], produces_artifact=False, idempotency="environment_dependent", deterministic=False),
+    "redact": dict(role="execution", inputs=["video asset"], outputs=["video artifact with the given pixel rectangle blurred or pixelated"],
+                   required=FF + [X264, AAC, "filter:boxblur"], optional=[HDR_X265],
+                   video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
+    "waveform": dict(role="execution", inputs=["audio or video asset (audio track only)"], outputs=["generated waveform or spectrum visualization video artifact"],
+                     required=FF + [X264, AAC, "filter:showwaves"], optional=[{"capability": "filter:showspectrum", "when": "--style spectrum"}],
+                     video_required=False, audio_only=True, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
+    "sphere": dict(role="execution", inputs=["360/spherical video asset"], outputs=["flat rectilinear video artifact of the chosen viewport"],
+                    required=FF + [X264, AAC, "filter:v360"], optional=[HDR_X265],
+                    video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
+    "grid": dict(role="execution", inputs=["cols*rows video assets, filled left-to-right top-to-bottom"], outputs=["composited grid video artifact"],
+                 required=FF + [X264, "filter:xstack"], optional=[{"capability": "filter:drawtext", "when": "--label auto (the default)"}, {"capability": AAC, "when": "--audio-from"}],
+                 video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
+    "straighten": dict(role="execution", inputs=["video asset"], outputs=["video artifact rotated by the given angle (horizon correction)"],
+                       required=FF + [X264, AAC, "filter:rotate"], optional=[HDR_X265],
+                       video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
+    "freeze": dict(role="execution", inputs=["video asset"], outputs=["video artifact with a frame held for the given duration"],
+                   required=FF + [X264, AAC, "filter:tpad"], optional=[HDR_X265],
+                   video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
+    "pad": dict(role="execution", inputs=["video asset"], outputs=["video artifact with black/silent padding added at the start/end"],
+                required=FF + [X264, AAC, "filter:tpad"], optional=[HDR_X265],
+                video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
+    "speedramp": dict(role="execution", inputs=["video asset"], outputs=["video artifact with a stepped speed ramp applied across segments"],
+                      required=FF + [X264, AAC], optional=[HDR_X265],
+                      video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
+    "loop": dict(role="execution", inputs=["video asset"], outputs=["video artifact repeated to the requested count or duration"],
+                 required=FF + [X264, AAC], optional=[],
+                 video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "insert": dict(role="execution", inputs=["still image"], outputs=["silent video artifact of the requested duration / frame size / fps"],
                    required=FF + [X264], optional=[{"capability": "filter:zoompan", "when": "--zoom / --pan"}],
                    video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
@@ -111,29 +147,32 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                      required=FF + [X264, AAC], optional=[HDR_X265],
                      video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "audio": dict(role="execution", inputs=["video or audio asset", "music bed (--music) or replacement track (--replace)"], outputs=["artifact with the processed audio (video stream-copied, or dropped when -o has an audio extension)"],
-                  required=FF + [AAC], optional=[{"capability": "filter:afftdn", "when": "--denoise / --voice"}, {"capability": "filter:sidechaincompress", "when": "--duck"},
-                                                {"capability": "filter:acompressor", "when": "--compress / --voice"}, {"capability": "filter:alimiter", "when": "--limit"}, {"capability": "filter:agate", "when": "--gate"}] + AUDIO_OUT,
+                  required=FF, optional=[{"capability": "filter:afftdn", "when": "--denoise / --voice"}, {"capability": "filter:sidechaincompress", "when": "--duck"},
+                                        {"capability": "filter:acompressor", "when": "--compress / --voice"}, {"capability": "filter:alimiter", "when": "--limit"}, {"capability": "filter:agate", "when": "--gate"},
+                                        {"capability": AAC, "when": "output extension isn't .mp3/.opus/.ogg/.flac (audio_codec_for()'s default)"}] + AUDIO_OUT,
                   video_required=False, audio_only=True, visual=False, verify=["probe"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "loudness": dict(role="analysis_and_execution", inputs=["video or audio asset"], outputs=["loudness measurement JSON (--measure-only)", "normalised artifact (video stream-copied)"],
-                     required=FF + ["filter:loudnorm", AAC], optional=AUDIO_OUT,
+                     required=FF + ["filter:loudnorm"], optional=[{"capability": AAC, "when": "output extension isn't .mp3/.opus/.ogg/.flac (audio_codec_for()'s default)"}] + AUDIO_OUT,
                      video_required=False, audio_only=True, visual=False, verify=["probe", "check"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "silence": dict(role="analysis_and_execution", inputs=["video or audio asset"], outputs=["silence list JSON (--list)", "artifact with silences removed", "EDL text (--edl)"],
                     required=FF + ["filter:silencedetect"], optional=[{"capability": X264, "when": "removing silences from a video"}, HDR_X265, {"capability": AAC, "when": "removing silences from a video"}] + AUDIO_OUT,
                     video_required=False, audio_only=True, visual=False, verify=["probe"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "join": dict(role="execution", inputs=["two or more video assets, or two or more audio-only assets"], outputs=["concatenated video artifact", "concatenated audio artifact (audio-only inputs, audio output extension)"],
-                 required=FF + [X264, AAC, "filter:xfade", "filter:acrossfade"], optional=[HDR_X265] + AUDIO_OUT,
+                 required=FF + ["filter:xfade", "filter:acrossfade"],
+                 optional=[{"capability": X264, "when": "joining video inputs"}, {"capability": AAC, "when": "joining video inputs, or an audio-only join whose output extension isn't .mp3/.opus/.ogg/.flac"}, HDR_X265] + AUDIO_OUT,
                  video_required=False, audio_only=True, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "color": dict(role="execution", inputs=["video asset", ".cube LUT (--lut)"], outputs=["video artifact with converted colour"],
                   required=FF, optional=[{"capability": X264, "when": "--to-sdr / --lut / --correct"}, {"capability": "filter:zscale", "when": "--to-sdr"}, {"capability": "filter:tonemap", "when": "--to-sdr"},
                                          {"capability": "filter:lut3d", "when": "--lut"}, {"capability": "bsf:filter_units", "when": "--strip-dovi"}, {"capability": X265, "when": "--lut on an HDR source"}, {"capability": AAC, "when": "re-encode"},
                                          {"capability": "filter:exposure", "when": "--correct"}, {"capability": "filter:eq", "when": "--correct"},
-                                         {"capability": "filter:colorbalance", "when": "--correct"}, {"capability": "filter:colortemperature", "when": "--correct"}],
+                                         {"capability": "filter:colorbalance", "when": "--correct"}, {"capability": "filter:colortemperature", "when": "--correct"},
+                                         {"capability": "filter:colorlevels", "when": "--correct with any --levels-*"}, {"capability": "filter:curves", "when": "--correct --curves"}],
                   video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "proxy": dict(role="execution", inputs=["video asset"], outputs=["low-resolution, low-bitrate proxy artifact for downstream analysis, preview or editing decisions"],
                   required=FF + [X264, AAC], optional=[HDR_X265],
                   video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "export": dict(role="execution", inputs=["video asset"], outputs=["delivery artifact in the preset's format"],
-                   required=FF, optional=[{"capability": X264, "when": "preset youtube / youtube4k / reels / x"}, {"capability": AAC, "when": "any preset except gif"},
+                   required=FF, optional=[{"capability": X264, "when": "preset youtube / youtube4k / reels / x"}, {"capability": AAC, "when": "preset youtube / youtube4k / reels / x / h265 (prores uses pcm_s16le, copy stream-copies, gif has no audio)"},
                                           {"capability": X265, "when": "preset h265"}, {"capability": "encoder:prores_ks", "when": "preset prores"},
                                           {"capability": "filter:palettegen", "when": "preset gif"}, {"capability": "encoder:gif", "when": "preset gif"}],
                    video_required=True, audio_only=False, visual=False, verify=["probe", "check"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
@@ -168,6 +207,7 @@ DRY_RUN_ANALYSIS = {
     "multicam": "audio is decoded to align the cameras; the switched output is not written",
     "scenes": "scene and audio-peak measurement runs; --sheet and --edl are not written",
     "report": "probe, loudness and contact-sheet measurements run; the HTML is not written",
+    "cropdetect": "the cropdetect filter runs over the sampled windows to measure bars; this tool never writes a file regardless of --dry-run",
 }
 DRY_RUN_NOTES = {
     "probe": "read-only tool; --dry-run changes nothing (ffprobe still runs)",
@@ -188,6 +228,18 @@ REENCODE_META: Dict[str, Dict[str, str]] = {
     "cut":       dict(video="conditional", audio="conditional", note="lossless -c copy preferred; re-encodes on --accurate, a VFR source, or a keyframe snap past --tolerance (see cut.py --json: mode, keyframe_snapped)"),
     "fit":       dict(video="always", audio="always", note="always re-encodes to AAC when audio is present, even if only --fps or --aspect was asked for"),
     "crop":      dict(video="always", audio="always", note="the crop filter always forces a re-encode of both streams"),
+    "deinterlace": dict(video="always", audio="always", note="the yadif filter always forces a re-encode of the video stream; audio is re-encoded to AAC when present"),
+    "denoise":   dict(video="always", audio="always", note="the hqdn3d filter always forces a re-encode of the video stream; audio is re-encoded to AAC when present"),
+    "cropdetect": dict(video="never", audio="never", note="analysis only, no artifact"),
+    "redact":    dict(video="always", audio="always", note="the boxblur/pixelate filter_complex always forces a re-encode of the video stream; audio is re-encoded to AAC when present"),
+    "waveform":  dict(video="always", audio="always", note="always encodes a fresh generated visualization clip; the source audio is always re-encoded to AAC"),
+    "sphere":   dict(video="always", audio="always", note="the v360 filter always forces a re-encode of the video stream; audio is passed through to AAC unchanged"),
+    "straighten": dict(video="always", audio="always", note="the rotate filter always forces a re-encode of the video stream; audio is re-encoded to AAC when present"),
+    "grid":      dict(video="always", audio="conditional", note="the xstack composite always forces a re-encode of the video stream; there is no audio at all unless --audio-from picks one input's track, which is then re-encoded to AAC"),
+    "freeze":   dict(video="always", audio="always", note="the tpad/concat filter graph always forces a re-encode of the video stream; audio is re-encoded to AAC when present"),
+    "pad":      dict(video="always", audio="always", note="the tpad filter always forces a re-encode of the video stream; audio is re-encoded to AAC when present"),
+    "speedramp": dict(video="always", audio="always", note="setpts/atempo per segment always forces a re-encode of both streams"),
+    "loop":     dict(video="always", audio="always", note="-stream_loop always re-encodes both streams; the audio codec is always AAC when present"),
     "insert":    dict(video="always", audio="never", note="always encodes a fresh silent clip from the still image; there is no audio stream to touch"),
     "background": dict(video="always", audio="never", note="always encodes a fresh generated clip; there is no input to copy from"),
     "reverse":   dict(video="always", audio="conditional", note="video always re-encodes (reverse buffers and re-emits every frame); audio re-encodes to AAC when present and not dropped by --no-audio"),
@@ -482,6 +534,50 @@ def _default_font() -> str:
     return str(BRAND_DEFAULTS["font"])
 
 
+def _drawtext_probe() -> Dict[str, Any]:
+    """Actually render one frame through drawtext, rather than trusting `-filters` alone.
+
+    `-filters` only reports whether this ffmpeg build was compiled with the filter; it never
+    proves drawtext can actually execute. On some real Windows ffmpeg builds (winget's gyan.dev
+    9.x), drawtext crashes with an access violation whenever it has to resolve a font through
+    fontconfig -- with or without a valid fonts.conf -- so `-filters` correctly reports drawtext
+    present and doctor used to report the capability `available` anyway; every tool that actually
+    used it (look, scenes --sheet, overlay --text, graphics) then crashed on first real use (#100).
+
+    This runs the cheapest real drawtext render there is: a one-frame synthetic clip, no font=
+    given at all (ffmpeg's own default resolution -- the same path that crashed). A clean exit
+    means drawtext genuinely works here. Anything that could not prove either way (no ffmpeg,
+    timeout, an ordinary nonzero exit with a real ffmpeg error) is `unknown`, same "unknown is not
+    missing" principle as every other capability here. A crash specifically -- killed by signal on
+    POSIX, or an unhandled access violation surfacing as a huge unsigned exit code on Windows -- is
+    the one case this function exists to catch, and folds into `missing`: the filter is present in
+    the build but cannot actually be used as ffmpeg's own default would use it.
+    """
+    exe = shutil.which("ffmpeg")
+    if not exe:
+        return {"status": "unknown", "detail": "ffmpeg not on PATH"}
+    try:
+        proc = subprocess.run(
+            [exe, "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "color=c=black:s=64x64:d=1",
+             "-vf", "drawtext=text=x", "-frames:v", "1", "-f", "null", "-"],
+            stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=_DETECT_TIMEOUT,
+        )
+    except subprocess.TimeoutExpired:
+        return {"status": "unknown", "detail": f"drawtext probe did not exit within {_DETECT_TIMEOUT}s"}
+    except OSError as e:
+        return {"status": "unknown", "detail": f"drawtext probe: {e}"}
+    if proc.returncode == 0:
+        return {"status": "available", "detail": "one-frame drawtext render succeeded"}
+    if proc.returncode < 0 or proc.returncode >= 0x80000000:
+        return {"status": "missing",
+                "detail": f"drawtext render crashed (exit {proc.returncode}) instead of failing cleanly -- "
+                           "the filter is present in this build but cannot be used as-is, likely a fontconfig "
+                           "resolution crash (see https://github.com/kajisho5/ffmpeg-skill/issues/100); "
+                           "pass an explicit --font-file to every drawtext tool as a workaround"}
+    tail = " ".join(proc.stderr.strip().splitlines()[-2:])
+    return {"status": "unknown", "detail": f"drawtext probe exited {proc.returncode}: {tail}"}
+
+
 def _font_available(font_name: str) -> Dict[str, Any]:
     """Whether `font_name` (a fontconfig family name, as passed to drawtext's `font=`) is actually
     installed, distinct from silently resolving to a substitute.
@@ -561,6 +657,7 @@ def doctor() -> Dict[str, Any]:
     sets = {k: set(v["names"]) for k, v in listings.items()}
     state: Dict[str, str] = {}  # capability -> available | missing | unknown
     wanted = required_capabilities()
+    drawtext_probe: Optional[Dict[str, Any]] = None
 
     def _from(kind: str, name: str) -> str:
         lst = listings[kind]
@@ -577,6 +674,23 @@ def doctor() -> Dict[str, Any]:
             state[cap] = "available" if shutil.which("ffprobe") else "missing"
         elif cap.startswith("encoder:"):
             state[cap] = _from("encoders", cap[8:])
+        elif cap == "filter:drawtext":
+            listing_state = _from("filters", "drawtext")
+            if listing_state == "available":
+                # Only escalate an "available" listing to "missing" on an unambiguous crash --
+                # an ordinary nonzero exit (a real ffmpeg's own -h/-filters-only build variance, or
+                # in tests a fake ffmpeg shim that only implements -filters/-encoders/-bsfs/-version)
+                # proves nothing either way, so it leaves the listing-based result standing rather
+                # than downgrading it; see _drawtext_probe()'s own docstring for why a crash alone
+                # is the one case this exists to catch.
+                probe = _drawtext_probe()
+                if probe["status"] == "missing":
+                    drawtext_probe = probe
+                    state[cap] = "missing"
+                else:
+                    state[cap] = "available"
+            else:
+                state[cap] = listing_state
         elif cap.startswith("filter:"):
             state[cap] = _from("filters", cap[7:])
         elif cap.startswith("bsf:"):
@@ -591,6 +705,8 @@ def doctor() -> Dict[str, Any]:
     unknown = sorted(c for c, st in state.items() if st == "unknown")
     unknown_required = [c for c in unknown if c in wanted["required"]]
     errors = [f"{k}: {v['detail']}" for k, v in listings.items() if v["status"] in ("unparsed", "failed")]
+    if drawtext_probe is not None and drawtext_probe["status"] != "available":
+        errors.append(f"filter:drawtext: {drawtext_probe['detail']}")
     return {
         "version": skill_version(),
         "python": ".".join(str(x) for x in sys.version_info[:3]),
@@ -630,6 +746,12 @@ def _capability_fix_hint(cap: str) -> str:
         full_hint = "install/build ffmpeg with it enabled"
     if cap.startswith("encoder:"):
         return f"this ffmpeg build has no {cap[8:]} encoder; {full_hint}"
+    if cap == "filter:drawtext":
+        return ("drawtext crashed instead of rendering a frame (see errors[] for the exit detail) -- "
+                 "every drawtext tool already resolves a concrete font file automatically when one can "
+                 "be found (#100); if it still crashes, use --no-timecode with look.py or scenes.py "
+                 "--sheet to skip drawtext entirely, or pass --font-file explicitly to overlay.py/"
+                 "graphics.py (the two that accept it) rather than relying on font= resolution")
     if cap.startswith("filter:"):
         return f"this ffmpeg build has no {cap[7:]} filter; {full_hint}"
     if cap.startswith("bsf:"):

package/scripts/background.py

@@ -14,7 +14,7 @@ import argparse
 import math
 import sys
 
-from _common import add_common, apply_common, die, emit, ffmpeg_base, info, parse_time, probe, run, video_args
+from _common import add_common, apply_common, die, emit, ffmpeg_base, info, parse_time, probe, run, validate_color, video_args
 
 
 def main() -> int:
@@ -49,11 +49,20 @@ def main() -> int:
             c0, c1 = args.gradient.split(":")
         except ValueError:
             die(f"--gradient needs two colours as C1:C2, got '{args.gradient}'")
+        validate_color(c0, "--gradient")
+        validate_color(c1, "--gradient")
         rad = math.radians(args.angle)
         x1 = round(args.width * math.cos(rad))
         y1 = round(args.width * math.sin(rad))
-        src_filter = f"gradients=size={args.width}x{args.height}:rate={args.fps:g}:c0={c0}:c1={c1}:x0=0:y0=0:x1={x1}:y1={y1}"
+        # gradients defaults to seed=-1 (a random seed picked fresh each run) and speed=0.01 (a
+        # slow rotation applied every frame), so without pinning both, this "static" background
+        # was neither reproducible between runs nor actually static across its own duration --
+        # violating the bit_exact/deterministic contract _contract.py declares for this tool.
+        # speed's own valid range bottoms out at 1e-05 (0 is refused), so that's the closest to
+        # motionless the filter allows.
+        src_filter = f"gradients=size={args.width}x{args.height}:rate={args.fps:g}:c0={c0}:c1={c1}:x0=0:y0=0:x1={x1}:y1={y1}:seed=0:speed=1e-05"
     else:
+        validate_color(args.color, "--color")
         src_filter = f"color=c={args.color}:size={args.width}x{args.height}:rate={args.fps:g}"
 
     output = args.output

package/scripts/batch.py

@@ -36,6 +36,13 @@ from _common import STATE, add_common, apply_common, die, emit, info
 
 HERE = Path(__file__).resolve().parent
 MEDIA_EXT = {".mp4", ".mov", ".m4v", ".mkv", ".webm", ".avi", ".mts", ".m2ts", ".mxf", ".wav", ".m4a", ".mp3", ".flac"}
+# recipe steps name the script to run as plain, untrusted JSON -- run_step() joins it onto HERE
+# with the `/` operator, which silently ignores the left side when the right side is itself an
+# absolute path (Path("/scripts") / "/tmp/evil.py" == Path("/tmp/evil.py")), and does nothing to
+# stop a "../" traversal either. Without this allowlist, a batch.json a caller didn't author
+# themselves (from a template, a shared config, anywhere) could name any Python file on disk and
+# have it executed with the caller's own privileges on every matching media file.
+ALLOWED_STEP_SCRIPTS = {p.name for p in HERE.glob("*.py") if not p.name.startswith("_")}
 
 
 def file_key(path: Path) -> str:
@@ -51,11 +58,27 @@ def file_key(path: Path) -> str:
 
 
 def recipe_key(recipe: Dict[str, Any]) -> str:
-    return hashlib.sha1(json.dumps(recipe, sort_keys=True).encode()).hexdigest()[:12]
+    # A "project" recipe is just {"project": "<path>", "clip_key": N} -- the actual settings
+    # (export preset, captions, everything) live in the file at that path, not in this dict.
+    # Hashing only `recipe` meant editing project.json's content (without touching batch.json
+    # itself) left the key, and so every cache hit, unchanged: a preset swapped from "copy" to
+    # "x" (a real re-encode) still served the old cached output. Fold the referenced file's own
+    # content into the key so a content change invalidates the cache like any other edit would.
+    project_content = ""
+    if recipe.get("project"):
+        try:
+            project_content = Path(recipe["project"]).read_text(encoding="utf-8")
+        except OSError:
+            pass
+    return hashlib.sha1((json.dumps(recipe, sort_keys=True) + "\0" + project_content).encode()).hexdigest()[:12]
 
 
 def run_step(argv: List[str]) -> bool:
-    cmd = [sys.executable, str(HERE / argv[0])] + argv[1:]
+    script = argv[0]
+    if script not in ALLOWED_STEP_SCRIPTS:
+        die(f"recipe step names a script that isn't one of this skill's own tools: {script!r} "
+            f"(must be a bare filename like 'silence.py', found in scripts/)")
+    cmd = [sys.executable, str(HERE / script)] + argv[1:]
     if STATE["fast"]:
         cmd.append("--fast")
     if STATE["dry_run"]:
@@ -68,10 +91,20 @@ def run_step(argv: List[str]) -> bool:
     return True
 
 
-def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path) -> Dict[str, Any]:
+def final_path(src: Path, recipe: Dict[str, Any], outdir: Path) -> Path:
     suffix = recipe.get("suffix", "_out")
+    # By default final_ext falls back to each source's OWN extension, so files that only differ
+    # by extension don't collide -- but a recipe that fixes "ext" (e.g. converting a folder of
+    # mixed .mp4/.mov masters to one format) makes every source with the same stem land on the
+    # same final path, e.g. clip.mp4 and clip.mov both -> clip_out.mp4. process() has no collision
+    # detection of its own; see one_pass()'s pre-flight check, which uses this same computation
+    # to catch that before any file is actually processed (and the earlier one silently clobbered).
     final_ext = recipe.get("ext") or src.suffix.lstrip(".") or "mp4"
-    final = outdir / f"{src.stem}{suffix}.{final_ext}"
+    return outdir / f"{src.stem}{suffix}.{final_ext}"
+
+
+def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path) -> Dict[str, Any]:
+    final = final_path(src, recipe, outdir)
     t0 = time.time()
     if recipe.get("project"):
         proj = json.loads(Path(recipe["project"]).read_text(encoding="utf-8"))
@@ -140,6 +173,18 @@ def main() -> int:
     def one_pass() -> List[Dict[str, Any]]:
         results = []
         files = sorted(p for p in folder.glob(glob) if p.is_file() and p.suffix.lower() in MEDIA_EXT and outdir not in p.parents)
+        # Two different sources can compute the same final path (most often a fixed recipe "ext"
+        # collapsing e.g. clip.mp4 and clip.mov to the same clip_out.mp4) -- catch that before
+        # processing anything, rather than letting the later one silently overwrite the earlier
+        # one's finished output with the cache still recording both as "ok".
+        by_final: Dict[Path, List[Path]] = {}
+        for src in files:
+            by_final.setdefault(final_path(src, recipe, outdir), []).append(src)
+        collisions = {dst: srcs for dst, srcs in by_final.items() if len(srcs) > 1}
+        if collisions:
+            detail = "; ".join(f"{dst.name} <- {', '.join(s.name for s in srcs)}" for dst, srcs in collisions.items())
+            die(f"{len(collisions)} output filename collision(s) in this batch -- rename the sources, "
+                f"or add a distinguishing \"suffix\"/\"ext\" per run, or split into separate globs: {detail}")
         for src in files:
             key = f"{file_key(src)}:{rkey}"
             hit = cache.get(key)
@@ -152,7 +197,15 @@ def main() -> int:
             results.append(r)
             if r["ok"] and not STATE["dry_run"]:
                 cache[key] = r
-                cache_path.write_text(json.dumps(cache, indent=2), encoding="utf-8")
+                # write_text isn't atomic -- a process killed mid-write (or a --watch loop racing
+                # a concurrent manual run) could leave a truncated file that json.loads() above
+                # then silently treats as "no cache" (a ValueError -> {}), discarding every prior
+                # entry. Write to a sibling temp file and rename into place: same-directory
+                # renames are atomic on POSIX and os.replace() is atomic on Windows too, so a
+                # reader only ever sees the old complete file or the new complete file.
+                tmp = cache_path.parent / f"{cache_path.name}.tmp{os.getpid()}"
+                tmp.write_text(json.dumps(cache, indent=2), encoding="utf-8")
+                os.replace(tmp, cache_path)
         return results
 
     results = one_pass()