ffmpeg-skill 1.4.13 → 1.4.15

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 (`1.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`1.4.13`) | any release |
+| `skill.version` | the npm / package.json version (`1.4.15`) | 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`
@@ -46,7 +46,7 @@ For the whole of 1.x:
 | Tool ids (`ffmpeg-skill/<name>`) and script names | never removed or renamed |
 | CLI arguments (`argparse` dests, flags, positionals) | never removed, renamed, or made newly required; new optional arguments may be added |
 | `--json` output keys, and the keys of `contract --json` / `doctor --json` | never removed or given a different type; new keys may be added |
-| Exit codes (0 success, 1 failure, 2 unknown/undecidable in `doctor`) | unchanged |
+| Exit codes (0 success, 1 failure incl. ffmpeg failures, 2 unknown/undecidable in `doctor`, 124 timeout, 127 missing tool, 128+signal interrupted) | unchanged |
 | `contract_version` (`1.0`) | unchanged; a ToolSpec shape change is a major |
 | MCP `tools/list` names and `inputSchema` property names | derived from the above, so covered by the same promise |
 | Behaviour of a tool for the same input and arguments | may change only to fix a defect or to track an FFmpeg change, and every such change gets a CHANGELOG line |
@@ -83,7 +83,7 @@ on, the line says so.
 ```json
 {
   "contract_version": "1.0",
-  "skill": {"id": "ffmpeg-skill", "version": "1.4.13", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "1.4.15", "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.9 (standard library only)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},
@@ -318,7 +318,8 @@ before, and, when `--json` was given, on stdout:
 `message` carries the script's own reason (missing input, ffprobe failure, the last
 stderr lines of ffmpeg, the verification that failed); an optional `error.hint` names the
 flag change that would make a retry meaningful (never a diagnosis of the media); `commands` lists what was planned
-or run so the caller can retry or report without re-deriving the command. `code` is a
+or run so the caller can retry or report without re-deriving the command; `kind: ffmpeg`
+failures add `ffmpeg_returncode` (ffmpeg's own exit code; the process exits 1). `code` is a
 purely additive, statically-mapped relabelling of `kind` (never a new distinction `kind`
 doesn't already make) for a caller that wants a stable enum instead of matching `kind`
 strings. `retryable` is currently always `false`: none of the kinds are distinguishable

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "1.4.13",
+  "version": "1.4.15",
   "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/references/scripts.md

@@ -281,6 +281,8 @@ rather than a continuous curve. `START`/`END` take seconds or `mm:ss`;
 0.5 = half speed). Picking exactly where a ramp should ease in or out is a
 judgement call for the calling agent, made concrete here as the segment
 boundaries it supplies.
+A subtitle/data track in the source is not carried into the retimed/concatenated
+output; the result says so with `dropped_non_av_streams: true`.
 
 ### loop.py — repeat a clip
 ```
@@ -308,6 +310,8 @@ overlap or run past A's end, and B must have enough material from `--from`.
 `--audio a` (default) keeps A's audio untouched and stream-copied; `b` replaces
 it inside each window with B's; `mix` plays both. The output's length is
 verified against A's.
+A subtitle/data track in the source is not carried into the retimed/concatenated
+output; the result says so with `dropped_non_av_streams: true`.
 
 ### metadata.py — chapter markers and container tags, streams copied
 ```
@@ -362,6 +366,8 @@ channel layout (the widest clip's -- a 5.1 clip keeps 5.1 -- or `--channels`;
 silent track generated for clips without audio), then chains `xfade` +
 `acrossfade`. Output length = sum of clips − transition × (n−1). Clips must be
 longer than 2 × the transition. Use `--transition none` for a plain cut.
+A subtitle/data track in the source is not carried into the retimed/concatenated
+output; the result says so with `dropped_non_av_streams: true`.
 
 ### render.py — the whole edit in one project.json
 ```
@@ -596,7 +602,8 @@ standard talking-head chain. `--duck` uses a sidechain compressor keyed by the
 speech so music dips under dialogue and swells in pauses. `--downmix` uses the
 ITU centre/LFE weights for 5.1/7.1 → stereo. `--mono` averages a stereo pair,
 leaves a 1-channel input untouched and downmixes >2 channels through
-swresample. Video is always stream-copied.
+swresample. Video is always stream-copied, and so is a subtitle/data track
+when the container can hold it (`dropped_non_av_streams` says when it could not).
 Run `loudness.py` after this for final levels.
 
 ### loudness.py — EBU R128 normalisation
@@ -604,7 +611,8 @@ Run `loudness.py` after this for final levels.
 loudness.py INPUT [-I -14] [--tp -1] [--lra 11] [--measure-only] [-o OUT]
 ```
 Two-pass `loudnorm`: measure, then apply with measured values (linear mode when
-the true-peak ceiling allows). Video is stream-copied; audio becomes AAC in
+the true-peak ceiling allows). Video and any subtitle/data track are
+stream-copied (`dropped_non_av_streams` reports a track the container refused); audio becomes AAC in
 video containers or the codec matching the extension (.wav → PCM, .flac, .mp3).
 The written file is measured again: a lossy encoder can push peaks past the
 ceiling loudnorm held (ffmpeg's AAC at 192k turned one transient from -2.4 to
@@ -629,6 +637,7 @@ proxy.py INPUT [--width W | --scale F] [--crf N] [--fps N] [--no-audio] [-o OUT]
 Not a delivery preset: resizes to `--width` (default 640) or by `--scale`
 factor, re-encodes at a proxy-grade `--crf` (default 30) with the fastest
 x264/x265 preset, keeps the source's own dynamic range (HDR stays HDR;
-run `color.py --to-sdr` first if SDR is wanted). Only executes the spec
+run `color.py --to-sdr` first if SDR is wanted) and keeps a subtitle/data
+track when the container can hold it (`dropped_non_av_streams`). Only executes the spec
 given — does not decide which asset to proxy or what for.
 

package/scripts/_common.py

@@ -398,8 +398,12 @@ def _cleanup_partial_output(cmd: Sequence[str]) -> None:
 def _fail(cmd: Sequence[str], returncode: int, stderr: str) -> None:
     # Partial-output cleanup already ran in the caller (_run_captured/_run_with_progress) for
     # every failed ffmpeg invocation, not just this check=True path -- see _cleanup_partial_output.
+    # The process exit code is always 1 for an ffmpeg failure: ffmpeg's own code (1, 69, 218, 234,
+    # a negative signal number...) varies by build and by the failing stage, and 124/127/130/143
+    # are reserved for timeout, missing tool and interrupts. The raw code is kept in the JSON
+    # document as `ffmpeg_returncode` for a caller that wants it. docs/design-decisions.md.
     tail = "\n".join(stderr.strip().splitlines()[-15:])
-    die(f"command failed ({returncode}): {cmd[0]}\n{tail}", code=returncode or 1, kind="ffmpeg")
+    die(f"command failed ({returncode}): {cmd[0]}\n{tail}", code=1, kind="ffmpeg", ffmpeg_returncode=returncode)
 
 
 def _check_no_overwrite_input(cmd: Sequence[str]) -> None:
@@ -461,6 +465,112 @@ def _check_output_path(cmd: Sequence[str]) -> None:
     parent = os.path.dirname(os.path.abspath(output))
     if not os.path.isdir(parent):
         die(f"output directory {parent!r} does not exist; create it first (this tool never creates directories)")
+    if not os.access(parent, os.W_OK):
+        die(f"output directory {parent!r} is not writable")
+
+
+EVEN_SCALE = "scale=trunc(iw/2)*2:trunc(ih/2)*2"
+
+
+def _pid_dead(pid: int) -> bool:
+    """True only when the process is known not to exist. POSIX: signal 0. Windows: OpenProcess
+    fails with ERROR_INVALID_PARAMETER (87) for a pid that is not in use; any other outcome
+    (a handle, or access denied) means it is live. Unknown is treated as live."""
+    if os.name != "nt":
+        try:
+            os.kill(pid, 0)
+        except ProcessLookupError:
+            return True
+        except OSError:
+            pass
+        return False
+    try:
+        import ctypes
+        k32 = ctypes.windll.kernel32  # type: ignore[attr-defined]
+        handle = k32.OpenProcess(0x1000, False, pid)  # PROCESS_QUERY_LIMITED_INFORMATION
+        if handle:
+            k32.CloseHandle(handle)
+            return False
+        return k32.GetLastError() == 87
+    except Exception:
+        return False
+
+
+class _OutputLock:
+    """Two runs writing the same output at once used to both report `completed` while one of
+    them described the other's file (sweep F1). A lock file next to the output, created with
+    O_EXCL and holding the writer's pid, makes the second run refuse as `kind: input`. A lock
+    whose pid is dead (POSIX) or older than an hour is stale and taken over."""
+    def __init__(self, output: str) -> None:
+        self.path: Optional[str] = None
+        self.fd: Optional[int] = None
+        if output == "-" or output.startswith("pipe:") or output.startswith("-"):
+            return
+        d, base = os.path.split(os.path.abspath(output))
+        self.path = os.path.join(d, f".{base}.ffskill-lock")
+
+    def __enter__(self) -> "_OutputLock":
+        if not self.path:
+            return self
+        for attempt in (0, 1):
+            try:
+                self.fd = os.open(self.path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o644)
+                os.write(self.fd, str(os.getpid()).encode())
+                return self
+            except FileExistsError:
+                if attempt == 0 and self._stale():
+                    try:
+                        os.remove(self.path)
+                    except OSError:
+                        pass
+                    continue
+                die(f"another run is writing {os.path.basename(self.path)[1:-len('.ffskill-lock')]!r} right now "
+                    f"(lock {self.path}); wait for it or choose a different --output/-o path")
+            except OSError:
+                return self  # unlockable location (read-only dir surfaces elsewhere): proceed without a lock
+        return self
+
+    def _stale(self) -> bool:
+        try:
+            pid = int(open(self.path).read().strip() or "0")
+            if pid > 0 and _pid_dead(pid):
+                return True
+            import time
+            return time.time() - os.path.getmtime(self.path) > 3600
+        except (OSError, ValueError):
+            return True
+
+    def __exit__(self, *exc: Any) -> None:
+        if self.fd is not None:
+            try:
+                os.close(self.fd)
+            except OSError:
+                pass
+        if self.path:
+            try:
+                os.remove(self.path)
+            except OSError:
+                pass
+
+
+def _odd_dimension_retry(cmd: List[str], stderr: str) -> Optional[List[str]]:
+    """An odd-sized source (641x359 screen captures, some 4:4:4 masters) fails every yuv420p
+    encode with "width/height not divisible by 2" (sweep F8, 15 tools). Return the same command
+    with an even-dimension scale prepended to its -vf chain (or a new -vf when the command had
+    none); None when the failure is something else or the graph is a -filter_complex the
+    caller has to fix itself."""
+    if "not divisible by 2" not in stderr or EVEN_SCALE in cmd or any(EVEN_SCALE in a for a in cmd):
+        return None
+    if "-filter_complex" in cmd:
+        return None
+    new = list(cmd)
+    if "-vf" in new:
+        i = new.index("-vf") + 1
+        new[i] = EVEN_SCALE + "," + new[i]
+        return new
+    if "-c:v" in new and new[new.index("-c:v") + 1] == "copy":
+        return None
+    return new[:-1] + ["-vf", EVEN_SCALE, new[-1]]
 
 
 def _check_existing_output(cmd: Sequence[str]) -> None:
@@ -555,24 +665,41 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subpr
         info(("[dry-run] $ " if STATE.dry_run and is_ffmpeg else "$ ") + _cmdline(cmd))
     if STATE.dry_run and is_ffmpeg:
         return subprocess.CompletedProcess(list(cmd), 0, "", "")
-    exec_cmd, final, tmp = _stage_existing_output(cmd) if is_ffmpeg else (list(cmd), None, None)
-    if STATE.progress and is_ffmpeg and exec_cmd[-1] != "-":
-        proc = _run_with_progress(exec_cmd, check)
-    else:
-        proc = _run_captured(exec_cmd, check)
-    if final and tmp:
-        if proc.returncode == 0:
-            try:
-                os.replace(tmp, final)
-            except OSError as e:
+    with _OutputLock(cmd[-1] if is_ffmpeg else "-"):
+        exec_cmd, final, tmp = _stage_existing_output(cmd) if is_ffmpeg else (list(cmd), None, None)
+        proc = _execute(exec_cmd)
+        if proc.returncode != 0 and is_ffmpeg:
+            retry = _odd_dimension_retry(exec_cmd, proc.stderr or "")
+            if retry is not None:
+                info("source has odd dimensions; scaling to even before encoding (yuv420p needs it)")
+                STATE.commands[-1] = _cmdline(retry[:-1] + [cmd[-1]])
+                proc = _execute(retry)
+            elif "not divisible by 2" in (proc.stderr or ""):
+                die("the source has odd dimensions (width or height not divisible by 2) and this tool's filter graph "
+                    "cannot pad them itself; make them even first, e.g. fit.py --width/--height, then retry",
+                    kind="input")
+        if proc.returncode != 0 and check:
+            _fail(exec_cmd, proc.returncode, proc.stderr or "")
+        if final and tmp:
+            if proc.returncode == 0:
+                try:
+                    os.replace(tmp, final)
+                except OSError as e:
+                    _cleanup_partial_output(exec_cmd)
+                    die(f"could not replace {final} with the new output: {e}", kind="output")
+                _remember_output(cmd)
+            else:
                 _cleanup_partial_output(exec_cmd)
-                die(f"could not replace {final} with the new output: {e}", kind="output")
-            _remember_output(cmd)
-        else:
-            _cleanup_partial_output(exec_cmd)
     return proc
 
 
+def _execute(exec_cmd: List[str]) -> subprocess.CompletedProcess:
+    """One attempt, never exiting on failure (run() decides after its retries)."""
+    if STATE.progress and _is_ffmpeg(exec_cmd) and exec_cmd[-1] != "-":
+        return _run_with_progress(exec_cmd, False)
+    return _run_captured(exec_cmd, False)
+
+
 def run_analysis(cmd: Sequence[str], *, check: bool = True, text: bool = True, record: bool = False) -> subprocess.CompletedProcess:
     """Run an ffmpeg *measurement* (scene scores, crop rectangles, decoded PCM, signal stats,
     silence detection, loudness, stabilisation pass 1): output to `-f null`, a pipe or a temp

package/scripts/audio.py

@@ -20,7 +20,7 @@ import argparse
 import sys
 from typing import List
 
-from _common import STATE, add_common, apply_common, audio_codec_for, db_to_linear, default_output, die, emit, ffmpeg_base, info, is_audio_output, probe, run, fmt_secs
+from _common import STATE, add_common, apply_common, audio_codec_for, db_to_linear, default_output, die, emit, ffmpeg_base, info, is_audio_output, probe, run, run_keeping_subtitles, fmt_secs
 
 VOICE_CHAIN = "highpass=f=80,deesser=i=0.4,afftdn=nf=-25:tn=1,acompressor=threshold=-18dB:ratio=3:attack=5:release=80:makeup=2"
 
@@ -226,8 +226,11 @@ def main() -> int:
     if not keep_video:
         # audio-only outputs: a looped music bed is infinite, -shortest ends the run with the main track
         cmd.append("-shortest")
-    cmd.append(output)
-    run(cmd)
+    if keep_video:
+        dropped_streams = run_keeping_subtitles(cmd, output)
+    else:
+        dropped_streams = bool(has_video and (meta.get("subtitle_streams") or meta.get("data_streams")))
+        run(cmd + [output])
     r = probe(output, role="output")
     a = r["audio"]
     if r.get("video") and audio_out and not STATE.dry_run:
@@ -235,7 +238,8 @@ def main() -> int:
     info(f"wrote {output} ({fmt_secs(r['duration'])}, audio {a['codec']} {a['channels']}ch {a['sample_rate']}Hz"
          + (", video stream-copied" if has_video and not audio_out else ", video dropped" if has_video else "") + ")")
     emit(output, video=bool(has_video and not audio_out), audio_stream=args.audio_stream,
-         dynamics=[f for f in (args.gate and "agate", args.compress and "acompressor", args.limit and "alimiter") if f])
+         dynamics=[f for f in (args.gate and "agate", args.compress and "acompressor", args.limit and "alimiter") if f],
+         dropped_non_av_streams=dropped_streams)
     return 0
 
 

package/scripts/batch.py

@@ -156,8 +156,23 @@ def main() -> int:
     if not outdir.is_absolute():
         outdir = folder / outdir
     work = Path(args.work) if args.work else outdir / ".work"
+    # the children refuse an output whose directory does not exist, under --dry-run too, so the
+    # directories are created for the plan as well -- and removed again afterwards when a dry
+    # run created them and left them empty (a plan leaves nothing behind, sweep F15)
+    created = [d for d in (outdir, work) if not d.exists()]
     outdir.mkdir(parents=True, exist_ok=True)
     work.mkdir(parents=True, exist_ok=True)
+    if STATE.dry_run and created:
+        import atexit
+
+        def _remove_empty_dirs() -> None:
+            for d in sorted(created, key=lambda p: len(str(p)), reverse=True):
+                try:
+                    if not any(d.iterdir()):
+                        d.rmdir()
+                except OSError:
+                    pass
+        atexit.register(_remove_empty_dirs)
     cache_path = outdir / ".ffskill_cache.json"
     cache: Dict[str, Any] = {}
     if cache_path.exists() and not args.force:

package/scripts/broll.py

@@ -145,7 +145,8 @@ def main() -> int:
     if not STATE.dry_run and dur_a and abs((result.get("duration") or 0.0) - dur_a) > max(0.1, 1.5 / fps):
         die(f"output is {fmt_secs(result.get('duration'))} but the A-roll is {dur_a:.3f}s -- a cutaway must not change the length", kind="output")
     info(f"wrote {output} ({result.get('duration', 0):.3f}s, {len(cutaways)} cutaway(s), audio={args.audio})")
-    emit(output, cutaways=[{"insert": c["path"], "at": c["at"], "end": c["at"] + c["length"], "from": c["from"]} for c in cutaways], audio=args.audio)
+    emit(output, cutaways=[{"insert": c["path"], "at": c["at"], "end": c["at"] + c["length"], "from": c["from"]} for c in cutaways], audio=args.audio,
+         dropped_non_av_streams=bool(meta_a.get("subtitle_streams") or meta_a.get("data_streams")))
     return 0
 
 

package/scripts/color.py

@@ -285,6 +285,9 @@ def main() -> int:
         output = args.output or default_output(args.input, "sdr")
         tag = "sdr"
     elif args.correct:
+        if v.get("hdr") and not args.force:
+            die(f"{args.input} is HDR ({v.get('hdr_format')}); --correct works on SDR pixels and would tag PQ/HLG data as BT.709 "
+                f"without a tone map (sweep F10). Run --to-sdr first, or --force to grade the raw values anyway")
         vf = correction_chain(args)
         output = args.output or default_output(args.input, "correct")
         tag = "correct"
@@ -292,6 +295,9 @@ def main() -> int:
         # "looks better" judgement -- the same primitive probe.py --analyze uses for Log detection.
         measurements = {"input": analyze_levels(args.input)}
     else:
+        if v.get("hdr") and not args.force:
+            die(f"{args.input} is HDR ({v.get('hdr_format')}); a LUT made for SDR applied to PQ/HLG pixels gives a wrong picture "
+                f"tagged BT.709 (sweep F10). Run --to-sdr first (or chain it), or --force if the LUT expects HDR input")
         if not os.path.exists(args.lut):
             die(f"LUT not found: {args.lut}")
         if not (0.0 <= args.lut_strength <= 1.0):

package/scripts/cut.py

@@ -32,6 +32,8 @@ from typing import List, Tuple
 
 from _common import video_args, STATE, add_common, apply_common, audio_codec_for, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, is_audio_output, parse_time, probe, run, X264_PRESETS, keyframes_near, MissingFpsError, concat_list_line, refuse_output_is_input, fmt_secs
 
+# outputs whose re-encode dropped a subtitle/data stream (reported as dropped_non_av_streams)
+DROPPED_STREAMS: List[str] = []
 # keyframe timestamps found next to a requested cut that the tolerance turned into a re-encode
 # (reported so the caller can choose a lossless cut at one of them next time)
 NEAREST_KEYFRAMES: list = []
@@ -115,6 +117,12 @@ def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: i
         cmd = ffmpeg_base() + ["-ss", f"{start:.6f}", "-i", src, "-t", f"{dur:.6f}"]
         if is_audio_output(dst) or not meta.get("video"):
             cmd += ["-af", f"atrim=end={dur:.6f},asetpts=PTS-STARTPTS"]
+        # ffmpeg's default stream selection also picks one subtitle stream; a re-encode cannot
+        # trim it (the cues kept their timestamps and the container grew to 2 s for a 1 s cut,
+        # sweep F2), so the re-encode carries video/audio only and the result says so
+        cmd += ["-sn", "-dn"]
+        if meta.get("subtitle_streams") or meta.get("data_streams"):
+            DROPPED_STREAMS.append(dst)
         cmd += encode_args(meta, dst, crf, preset) + ["-avoid_negative_ts", "make_zero", dst]
     elif audio_only:
         # output-side seek: an input seek on a video file lands on the previous video keyframe and on
@@ -130,7 +138,7 @@ def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: i
         die(f"ffmpeg failed:\n{proc.stderr.strip()}", kind="ffmpeg")
     if not reencode and tolerance >= 0 and not STATE.dry_run:
         got = probe(dst).get("duration") or 0.0
-        if abs(got - dur) > tolerance:
+        if abs(got - dur) >= tolerance:  # a snap of exactly the tolerance is not "within" it (sweep F20)
             near = keyframes_near(src, start)
             alt = ""
             if near:
@@ -230,6 +238,7 @@ def main() -> int:
     info(f"wrote {output} ({fmt_secs(got)}, expected ~{expected:.3f}s, "
          + ("re-encoded" if reencoded else "lossless stream copy") + f", {precision} precision)")
     emit(output, expected_duration=round(expected, 6), duration_error_ms=error_ms, precision=precision, reencoded=reencoded,
+         dropped_non_av_streams=bool(DROPPED_STREAMS),
          requested_start=round(segments[0][0], 6) if len(segments) == 1 else None,
          requested_end=round(segments[0][1], 6) if len(segments) == 1 else None,
          requested_segments=[[round(s, 6), round(e, 6)] for s, e in segments] if len(segments) > 1 else None,

package/scripts/export.py

@@ -68,8 +68,10 @@ def main() -> int:
     meta = probe(args.input)
     if not meta.get("video"):
         die("input has no video stream")
+    notes: List[str] = []
     if meta["video"].get("hdr") and args.preset not in ("prores", "copy"):
-        info("warning: source is HDR (%s). This preset outputs SDR BT.709 tags without tone mapping; run color.py --to-sdr first for correct colours." % meta["video"].get("hdr_format"))
+        notes.append("source is HDR (%s). This preset outputs SDR BT.709 tags without tone mapping; run color.py --to-sdr first for correct colours." % meta["video"].get("hdr_format"))
+        info("warning: " + notes[-1])
     has_audio = bool(meta.get("audio"))
     output = args.output or default_output(args.input, args.preset, p["ext"])
     out_ext = Path(output).suffix.lstrip(".").lower()
@@ -92,7 +94,7 @@ def main() -> int:
         cmd += ["-filter_complex", fc, "-loop", "0", output]
         run(cmd)
         info(f"wrote {output}")
-        emit(output)
+        emit(output, **({"notes": notes} if notes else {}))
         return 0
 
     if vf:
@@ -121,7 +123,7 @@ def main() -> int:
     result = probe(output, role="output")
     v = result["video"]
     info(f"wrote {output} ({fmt_secs(result['duration'])}, {v['width']}x{v['height']}, {v['codec']})")
-    emit(output)
+    emit(output, **({"notes": notes} if notes else {}))
     return 0
 
 

package/scripts/graphics.py

@@ -98,6 +98,8 @@ def main() -> int:
 
     extra_inputs: List[str] = []
     fc: List[str] = []  # filter_complex chains (used by templates that need animated boxes)
+    if 0 < min(W, H) < 64:  # 0x0 is a dry-run probe of an intermediate that does not exist yet
+        die(f"the frame is {W}x{H}; the templates are sized from it and need at least 64 px on the short side")
     if args.template == "lower-third":
         if not args.name:
             die("lower-third needs --name")

package/scripts/insert.py

@@ -65,6 +65,9 @@ def main() -> int:
     meta = probe(args.input)
     if not meta.get("video"):
         die("input has no image/video stream")
+    if (meta.get("duration") or 0) > 0.5 or meta.get("audio"):
+        die(f"{args.input} is a video, not a still image; insert.py animates a still (Ken Burns). "
+            f"For a clip use broll.py (cutaway) or cut.py/join.py")
     sw, sh = meta["video"]["width"], meta["video"]["height"]
     ratio = sw / sh
 

package/scripts/join.py

@@ -206,7 +206,8 @@ def main() -> int:
     expected = sum(durs) - d * (n - 1)
     r = probe(output, role="output")
     info(f"wrote {output} ({fmt_secs(r['duration'])}, expected ~{expected:.3f}s, {w}x{h} @ {fps:g}fps, {n} clips, {args.transition})")
-    emit(output, mode="video", clips=n, transition=args.transition, expected_duration=round(expected, 3))
+    emit(output, mode="video", clips=n, transition=args.transition, expected_duration=round(expected, 3),
+         dropped_non_av_streams=any(m.get("subtitle_streams") or m.get("data_streams") for m in metas))
     return 0
 
 

package/scripts/look.py

@@ -15,7 +15,7 @@ import sys
 from pathlib import Path
 from typing import List
 
-from _common import add_common, apply_common, default_font_file, die, emit, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, time_arg
+from _common import STATE, add_common, apply_common, default_font_file, die, emit, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, time_arg
 
 FONT = "fontcolor=white:fontsize=h/18:box=1:boxcolor=black@0.55:boxborderw=6:x=8:y=8"
 
@@ -102,19 +102,28 @@ def main() -> int:
         n = cols * rows
         if not dur:
             die("cannot build a contact sheet without a known duration")
+        frames_avail = int((meta["video"].get("fps") or 0) * dur) or 1
+        if n > frames_avail:
+            # a 2x2 sheet from a one-frame clip: tile waits for frames that never come and writes nothing
+            cols, rows = min(cols, frames_avail), 1
+            n = cols * rows
+            info(f"only {frames_avail} frame(s) available; sheet reduced to {cols}x{rows}")
         step = dur / n
         tile_w = max(2, (args.width // cols) // 2 * 2)
         out = args.output or os.path.join(outdir, f"{stem}_sheet.png")
         # sample at the middle of each slice so the first/last tiles are not black lead-in/out frames
         vf = (f"select='isnan(prev_selected_t)+gte(t-prev_selected_t\\,{step * 0.98:.6f})',scale={tile_w}:-2{tc},"
               f"tile={cols}x{rows}:padding=2:margin=2:color=0x202020")
-        cmd = ffmpeg_base() + ["-ss", f"{step / 2:.6f}", "-i", args.input, "-vf", vf, "-frames:v", "1", out]
+        # with only a handful of frames a mid-slice seek skips past them all: start at 0 instead
+        seek = 0.0 if frames_avail < 4 else step / 2
+        cmd = ffmpeg_base() + ["-ss", f"{seek:.6f}", "-i", args.input, "-vf", vf, "-frames:v", "1", out]
         run(cmd)
         outputs.append(out)
         info(f"contact sheet: {n} frames every {step:.2f}s")
 
     for o in outputs:
-        info(f"wrote {o}")
+        if STATE.dry_run or os.path.exists(o):
+            info(f"wrote {o}")
     emit(outputs[0] if len(outputs) == 1 else None, outputs=outputs)
     if len(outputs) > 1 and not args.json:
         for o in outputs:

package/scripts/loudness.py

@@ -18,7 +18,7 @@ import os
 import re
 import sys
 
-from _common import STATE, add_common, apply_common, emit, AUDIO_CODECS, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run, run_analysis, dry_run_input_pending
+from _common import STATE, add_common, apply_common, emit, AUDIO_CODECS, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run, run_analysis, run_keeping_subtitles, dry_run_input_pending
 
 
 
@@ -64,12 +64,19 @@ def main() -> int:
     if stats.get("silent"):
         info("audio is silent (integrated loudness -inf); nothing to normalise")
         if args.measure_only:
-            print(json.dumps({"silent": True, "input_i": "-inf"}, indent=2))
+            if STATE.json:
+                emit(None, measured={"silent": True, "input_i": "-inf"})
+            else:
+                print(json.dumps({"silent": True, "input_i": "-inf"}, indent=2))
             return 0
         die("input audio is silent; loudness normalisation is meaningless (use audio.py --replace to add a track)")
     info(f"measured: {float(stats['input_i']):.1f} LUFS, TP {float(stats['input_tp']):.1f} dBTP, LRA {float(stats['input_lra']):.1f} LU")
     if args.measure_only:
-        print(json.dumps({k: stats[k] for k in ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset")}, indent=2))
+        measured = {k: stats[k] for k in ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset")}
+        if STATE.json:
+            emit(None, measured=measured)  # the contract's document shape (status, commands), not a bare dict
+        else:
+            print(json.dumps(measured, indent=2))
         return 0
 
     output = args.output or default_output(args.input, "loudnorm")
@@ -83,7 +90,10 @@ def main() -> int:
     bitrate_pinned = args.audio_bitrate is not None
     bitrate = args.audio_bitrate or "192k"
 
+    dropped_streams = False
+
     def encode(tp: float, bitrate: str) -> None:
+        nonlocal dropped_streams
         af = (
             f"loudnorm=I={args.lufs}:TP={tp}:LRA={args.lra}"
             f":measured_I={stats['input_i']}:measured_TP={stats['input_tp']}:measured_LRA={stats['input_lra']}"
@@ -94,6 +104,8 @@ def main() -> int:
             cmd += ["-vn"] + audio_codec_for(output, bitrate)
         else:
             cmd += ["-map", "0:v:0", "-map", "0:a:0", "-c:v", "copy", "-c:a", "aac", "-b:a", bitrate]
+            dropped_streams = run_keeping_subtitles(cmd, output)
+            return
         cmd.append(output)
         run(cmd)
 
@@ -142,7 +154,7 @@ def main() -> int:
             f"the encoder overshoots more than the loudnorm ceiling can absorb at this bitrate",
             kind="verification", output=output, result=result,
             hint="raise --audio-bitrate (e.g. 256k) or deliver a lossless format (wav/flac) and let the platform encode")
-    emit(output, result=result)
+    emit(output, result=result, dropped_non_av_streams=dropped_streams)
     return 0
 
 

package/scripts/pad.py

@@ -16,7 +16,7 @@ Examples:
 import argparse
 import sys
 
-from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, validate_color, video_args, X264_PRESETS, time_arg, fmt_secs
+from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, validate_color, video_args, X264_PRESETS, time_arg, fmt_secs, run
 
 
 def main() -> int:
@@ -57,7 +57,13 @@ def main() -> int:
         cmd += aac_args()
     else:
         cmd += ["-an"]
-    dropped_streams = run_keeping_subtitles(cmd, output)
+    if args.start > 0:
+        # a stream-copied subtitle track keeps its timestamps and would fire --start seconds early
+        # (sweep F3); drop it and say so, as freeze --mode insert and fit --method speed do
+        run(cmd + [output])
+        dropped_streams = bool(meta.get("subtitle_streams") or meta.get("data_streams"))
+    else:
+        dropped_streams = run_keeping_subtitles(cmd, output)
 
     result = probe(output, role="output")
     v = result["video"]

package/scripts/proxy.py

@@ -25,7 +25,7 @@ Examples:
 import argparse
 import sys
 
-from _common import add_common, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run, video_args, fmt_secs
+from _common import add_common, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args, fmt_secs
 
 
 def even(n: float) -> int:
@@ -67,14 +67,13 @@ def main() -> int:
     cmd = ffmpeg_base() + ["-i", args.input, "-vf", f"scale={out_w}:-2"]
     cmd += video_args(meta, args.crf, "veryfast")
     cmd += cfr_args(meta, args.fps)
-    cmd += ["-c:a", "aac", "-b:a", "96k"] if has_audio else ["-an"]
-    cmd.append(output)
-    run(cmd)
+    cmd += ["-map", "0:v:0"] + (["-map", "0:a:0", "-c:a", "aac", "-b:a", "96k"] if has_audio else ["-an"])
+    dropped_streams = run_keeping_subtitles(cmd, output)
 
     result = probe(output)
     v = result["video"]
     info(f"wrote {output} ({fmt_secs(result['duration'])}, {v['width']}x{v['height']}, {v['codec']}, crf {args.crf})")
-    emit(output)
+    emit(output, dropped_non_av_streams=dropped_streams)
     return 0
 
 

package/scripts/redact.py

@@ -74,7 +74,11 @@ def main() -> int:
     output = args.output or default_output(args.input, "redact")
     crop = f"crop={args.width}:{args.height}:{args.x}:{args.y}"
     if args.mode == "blur":
-        region = f"{crop},boxblur={args.blur_strength}:{args.blur_strength}"
+        # boxblur refuses a radius above half the plane: the chroma planes of 4:2:0 are half-size,
+        # so they get their own (halved) radius; a 30 px region with the default 20 used to fail
+        radius = max(1, min(args.blur_strength, min(args.width, args.height) // 2 - 1))
+        chroma = max(1, min(radius // 2, min(args.width, args.height) // 4 - 1))
+        region = f"{crop},boxblur={radius}:{radius}:{chroma}:{radius}"
     else:
         region = f"{crop},scale={max(1, args.width // args.block_size)}:{max(1, args.height // args.block_size)}:flags=neighbor,scale={args.width}:{args.height}:flags=neighbor"
     fc = f"[0:v]split=2[base][region];[region]{region}[patched];[base][patched]overlay={args.x}:{args.y}[out]"

package/scripts/render.py

@@ -141,7 +141,16 @@ def main() -> int:
     # shared path, e.g. to inspect intermediates across runs); only the auto-derived default is
     # made unique per process, since it's the one that's also auto-deleted at the end.
     work = Path(args.work) if args.work else Path(f"{Path(output).with_suffix('')}_work_{os.getpid()}")
-    work.mkdir(parents=True, exist_ok=True)
+    try:
+        work.mkdir(parents=True, exist_ok=True)
+    except OSError as e:
+        die(f"cannot create the work directory {work}: {e}")
+    if not args.keep and not args.work:
+        # a failed or dry run used to leave <output>_work_<pid>/ behind (sweep F15): the
+        # auto-named directory is ours alone, so remove it on every exit path
+        import atexit
+        import shutil
+        atexit.register(lambda: shutil.rmtree(work, ignore_errors=True))
     frame = proj.get("frame") or {}
     trans = proj.get("transition") or {}
     brand_args: List[str] = ["--brand", rel(proj["brand"])] if proj.get("brand") else []
@@ -151,6 +160,8 @@ def main() -> int:
     parts: List[str] = []
     for i, c in enumerate(clips):
         src = rel(c["src"])
+        if not os.path.exists(src):
+            die(f"clip {i}: source not found: {src}")  # under --dry-run too: a plan for a missing file is no plan
         if not STATE.dry_run:
             probe(src)
         needs_cut = c.get("in") is not None or c.get("out") is not None

package/scripts/report.py

@@ -158,7 +158,10 @@ def main() -> int:
     if STATE.dry_run:
         info(f"wrote {output}")  # printed as "[dry-run] would write"; nothing is written
     else:
-        Path(output).write_text(doc, encoding="utf-8")
+        try:
+            Path(output).write_text(doc, encoding="utf-8")
+        except OSError as e:
+            die(f"cannot write {output}: {e}", kind="output")
         info(f"wrote {output} ({os.path.getsize(output) / 1024:.0f} KB)")
     emit(None, report=output, check=chk)
     if not args.json:

package/scripts/speedramp.py

@@ -115,7 +115,7 @@ def main() -> int:
     result = probe(output, role="output")
     v = result["video"]
     info(f"wrote {output} ({fmt_secs(result['duration'])}, {v['width']}x{v['height']}, {len(segments)} speed segments)")
-    emit(output)
+    emit(output, dropped_non_av_streams=bool(meta.get("subtitle_streams") or meta.get("data_streams")))
     return 0
 
 

package/scripts/verify.py

@@ -70,12 +70,15 @@ def collect(paths: List[str]) -> List[Path]:
 def step(name: str, argv: List[str], timeout: float) -> Dict:
     t0 = time.time()
     if argv[0] == "__check_hdr__":
+        was_json, STATE.json = STATE.json, False  # probe()'s die() would print a JSON document of its own
         try:
             v = probe(argv[1]).get("video") or {}
             ok = bool(v.get("hdr")) and v.get("bit_depth", 8) >= 10
             err = "" if ok else f"re-encode lost HDR: {v.get('color_transfer')}/{v.get('pix_fmt')}"
         except SystemExit:
             ok, err = False, "output missing"
+        finally:
+            STATE.json = was_json
         return {"step": name, "ok": ok, "seconds": round(time.time() - t0, 1), "error": err}
     try:
         proc = subprocess.run([sys.executable, str(HERE / argv[0])] + argv[1:], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=timeout)
@@ -113,12 +116,15 @@ def main() -> int:
     for f in files:
         info(f"=== {f}")
         entry: Dict = {"file": str(f), "steps": []}
+        was_json, STATE.json = STATE.json, False  # same: one JSON document per run, printed at the end
         try:
             meta = probe(str(f))
         except SystemExit:
             entry["steps"].append({"step": "probe", "ok": False, "seconds": 0, "error": "ffprobe failed"})
             results.append(entry)
             continue
+        finally:
+            STATE.json = was_json
         entry["probe"] = {k: meta.get(k) for k in ("duration", "format")}
         entry["probe"]["video"] = {k: (meta.get("video") or {}).get(k) for k in ("codec", "width", "height", "fps", "pix_fmt", "hdr_format", "rotation", "variable_frame_rate_suspected")}
         entry["probe"]["audio"] = {k: (meta.get("audio") or {}).get(k) for k in ("codec", "channels", "sample_rate")}