ffmpeg-skill 1.5.0 → 1.5.2

package/SKILL.md

@@ -239,7 +239,7 @@ commands work with `talk.wav` in place of `talk.mp4`. What changes:
 
 ## Report format
 
-Reply in the language the user wrote their request in — a Japanese request gets a Japanese report, English gets English, Chinese gets Chinese, and so on for any other language. Keep the shape below and the field labels (`Done:`, `Steps:`, `Check:`, `Look:`, `Notes:`) in English (they read like log fields, not prose, and stay recognisable across languages); the sentences around them, any question asked, and any explanation of a judgement call are in the user's language. Never default to English because the tool names and flags happen to be English. A mid-conversation language switch follows the user's latest message, not the first one.
+Reply in the language the user wrote their request in — a Japanese request gets a Japanese report, English gets English, Chinese gets Chinese, and so on for any other language. Keep the shape below and the field labels (`Done:`, `Steps:`, `Check:`, `Look:`, `Notes:`) in English (they read like log fields, not prose, and stay recognisable across languages); the sentences around them, any question asked, and any explanation of a judgement call are in the user's language. Never default to English because the tool names and flags happen to be English. A mid-conversation language switch follows the user's latest message, not the first one. This holds for a one-command job too: a three-second audio trim answered with English labels, numbers and one Japanese word in `Notes:` is an English report; the `Done:` line's own description (what was cut, from where) and `Steps:` are written in the user's language even when the values are technical.
 
 Finish every job with this shape (numbers from `probe.py`/`check.py`, not memory):
 

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.5.0`) | any release |
+| `skill.version` | the npm / package.json version (`1.5.2`) | 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`
@@ -83,7 +83,7 @@ on, the line says so.
 ```json
 {
   "contract_version": "1.0",
-  "skill": {"id": "ffmpeg-skill", "version": "1.5.0", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "1.5.2", "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"},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "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

@@ -55,7 +55,9 @@ keyframes, instant, lossless); if the snapped result deviates more than
 `--tolerance` (0.5 s) from the request, that segment is re-encoded automatically
 (x264 CRF 18). `--accurate` always re-encodes; `--tolerance -1` never does.
 Multiple segments are concatenated in the order given. stderr reports whether
-the result was "lossless stream copy" or "re-encoded".
+the result was "lossless stream copy" or "re-encoded"; when the snap forced a
+re-encode, the result's `lossless_alternative` names the nearest keyframe
+`--start` that would stream-copy instead, so the trade can be offered.
 
 ### fit.py — target duration and/or aspect, rotate/flip
 ```
@@ -504,8 +506,9 @@ not — a timecode-shaped cue with no fps available is refused rather than misre
 Lines without a time run for `--auto-seconds` (3 s) after the previous cue. `|` is a line break.
 `--animate`/`--karaoke` generate a styled ASS (PlayRes = video size) from the
 SRT/text cues: `pop` is the short-form "bouncy" entrance, `--karaoke` fills each
-word from `--color` to `--highlight-color` evenly across the cue (word timing
-is distributed, not transcribed). The ASS is kept next to the output so the
+word from `--color` to `--highlight-color` across the cue; `--karaoke-timing
+energy` (default) follows the speech loudness in the audio, `even` splits the
+cue equally (word timing is derived, not transcribed). The ASS is kept next to the
 user can hand-tune timings and re-run with `--ass`.
 `--mode burn` (default) renders subtitles into the picture and always
 re-encodes both streams. `--mode mux` copies video and audio untouched and
@@ -533,6 +536,9 @@ playing. `--video` composites a second video as a picture-in-picture layer
 input's audio is kept, the PiP layer's own audio is dropped. `--chromakey`
 (with `--video`) keys out that colour first for green-screen compositing.
 
+`--fade S` fades the overlay in at `--start` (or 0); the fade-out happens
+only at `--end`, so a logo with no `--end` stays to the last frame.
+
 ### sync.py — offset detection, alignment, drift correction
 ```
 sync.py REFERENCE SECOND [--json] [--max-offset 30] [--analyze-seconds 120] [--fix-drift [--drift-window 60]]
@@ -628,7 +634,11 @@ export.py INPUT --preset youtube|youtube4k|reels|x|prores|h265|gif [--fit pad|cr
 export.py --list
 ```
 Scales into the preset frame (pad by default), tags BT.709, sets `+faststart`,
-trims to platform maximums (Reels 90 s, X 140 s) unless `--allow-long`.
+trims to platform maximums (Reels 90 s, X 140 s) unless `--allow-long`. It
+does not touch levels: for youtube / youtube4k / reels / x the written file is
+measured and the result's `loudness` (and a `notes` line) says when it is
+outside the platform's LUFS / true-peak spec, naming the `loudness.py` call
+that fixes it -- plan that pass instead of discovering it from `check.py`.
 
 ### proxy.py — low-bitrate proxy for analysis/preview
 ```

package/scripts/_contract.py

@@ -181,7 +181,8 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
     "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": "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"}, {"capability": "filter:boxblur", "when": "--pad-fill blur"}],
+                                          {"capability": "filter:palettegen", "when": "preset gif"}, {"capability": "encoder:gif", "when": "preset gif"}, {"capability": "filter:boxblur", "when": "--pad-fill blur"},
+                                          {"capability": "filter:loudnorm", "when": "preset youtube / youtube4k / reels / x with audio: the written file is measured against the platform's loudness target (result `loudness`)"}],
                    video_required=True, audio_only=False, visual=False, verify=["probe", "check"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "check": dict(role="verification", inputs=["media artifact"], outputs=["compliance rows JSON on stdout (no file)"],
                   required=["ffprobe"], optional=[{"capability": "ffmpeg", "when": "loudness rows (default)"}, {"capability": "filter:loudnorm", "when": "loudness rows (default)"}],
@@ -392,6 +393,9 @@ def output_schema(name: str, meta: Dict[str, Any]) -> Dict[str, Any]:
         extra = {"results": {"type": "array"}, "processed": {"type": "integer"}, "total": {"type": "integer"}}
     elif name == "report":
         extra = {"report": {"type": "string"}, "check": {"type": ["object", "null"]}}
+    elif name == "export":
+        extra = {"loudness": {"type": "object", "description": "platform presets with audio: the written file's lufs/tp against the platform's target_lufs/target_tp, ok true when inside the spec"},
+                 "notes": {"type": "array", "items": {"type": "string"}}}
     elif name == "loudness":
         extra = {"measured": {"type": "object", "description": "--measure-only prints the loudnorm measurement instead (input_i, input_tp, input_lra, input_thresh, target_offset)"}}
     elif name == "cut":
@@ -399,7 +403,8 @@ def output_schema(name: str, meta: Dict[str, Any]) -> Dict[str, Any]:
                  "duration_error_ms": {"type": ["number", "null"], "description": "written minus requested, measured by ffprobe (null under --dry-run)"},
                  "precision": {"enum": ["packet", "sample", "codec_frame", "frame"],
                                "description": "packet: stream copy on a packet/keyframe boundary; sample: decoded audio trimmed to the sample, lossless output; codec_frame: sample-trimmed then framed by a lossy encoder (priming delay adds to the length); frame: re-encoded video"},
-                 "reencoded": {"type": "boolean"}}
+                 "reencoded": {"type": "boolean"},
+                 "lossless_alternative": {"type": ["string", "null"], "description": "when a lossless cut re-encoded because of the keyframe snap: the --start that would stream-copy instead, and how far it is from the request"}}
     elif name == "join":
         extra = {"mode": {"enum": ["video", "audio"]}, "clips": {"type": "integer"}, "transition": {"type": "string"}, "expected_duration": {"type": "number"},
                  "sample_rate": {"type": "integer", "description": "audio mode only"}, "channels": {"type": "integer", "description": "audio mode only"},

package/scripts/batch.py

@@ -224,12 +224,20 @@ def main() -> int:
     results = one_pass()
     if args.watch:
         info(f"watching {folder} every {args.watch:g}s (Ctrl-C to stop)")
+        # the shared SIGINT handler (install_signal_handlers) exits 130 with "nothing was written",
+        # which is wrong for a watch that already processed files: while idle between passes,
+        # let Ctrl-C be a plain KeyboardInterrupt so the summary below prints (review 5)
+        import signal
         try:
             while True:
-                time.sleep(args.watch)
+                previous = signal.signal(signal.SIGINT, signal.default_int_handler)
+                try:
+                    time.sleep(args.watch)
+                finally:
+                    signal.signal(signal.SIGINT, previous)
                 results = one_pass()
         except KeyboardInterrupt:
-            pass
+            info("watch stopped")
     done = sum(1 for r in results if r["ok"])
     info(f"{done}/{len(results)} processed, {sum(1 for r in results if r.get('cached'))} from cache")
     if not args.json:

package/scripts/caption.py

@@ -487,9 +487,17 @@ def main() -> int:
     if args.transcribe:
         if not args.input:
             die("--transcribe needs the input video")
-        srt_path = args.write_srt or os.path.splitext(args.input)[0] + ".srt"
-        cues = transcribe(args.input, srt_path, args.language, args.model, args.audio_stream)
-        info(f"wrote {srt_path} ({len(cues)} cues)")
+        # the sidecar goes next to the output like the --text one, not into the source folder
+        # where it silently replaced a hand-written <input>.srt (review 5)
+        srt_path = args.write_srt or os.path.splitext(args.output or default_output(args.input, "captioned"))[0] + ".srt"
+        if STATE.dry_run:
+            cues = []
+            info(f"[dry-run] would transcribe {args.input} and write {srt_path}")
+        else:
+            if os.path.exists(srt_path) and not getattr(args, "overwrite", False):
+                info(f"warning: {srt_path} already exists and will be replaced by the transcript (pass --overwrite to confirm)")
+            cues = transcribe(args.input, srt_path, args.language, args.model, args.audio_stream)
+            info(f"wrote {srt_path} ({len(cues)} cues)")
         args.text = None
     if args.text:
         cues = parse_text_cues(args.text, args.auto_seconds, args.gap, fps_for_tc)
@@ -515,7 +523,7 @@ def main() -> int:
     output = args.output or default_output(args.input, "captioned")
 
     if args.mode == "mux":
-        if not srt_path or (not os.path.exists(srt_path) and not (STATE.dry_run and args.text)):
+        if not srt_path or (not os.path.exists(srt_path) and not (STATE.dry_run and (args.text or args.transcribe))):
             die(f"SRT file not found: {srt_path}")
         codec = mux_subtitle_codec(output)
         # Keep any subtitle track(s) the input already has (e.g. chaining --mode mux once per
@@ -543,7 +551,7 @@ def main() -> int:
         return 0
 
     if (args.animate != "none" or args.karaoke) and not args.ass:
-        cues_for_ass = cues if args.text else parse_srt(srt_path)
+        cues_for_ass = cues if (args.text or args.transcribe) else parse_srt(srt_path)
         ass_path = args.write_ass or os.path.splitext(output)[0] + ".ass"
         w, h = meta["video"]["width"], meta["video"]["height"]
         if meta["video"].get("rotation") in (90, -90, 270, -270):
@@ -563,7 +571,7 @@ def main() -> int:
         if args.fonts_dir:
             vf += f":fontsdir={escape_filter_path(args.fonts_dir)}"
     else:
-        if not srt_path or (not os.path.exists(srt_path) and not (STATE.dry_run and args.text)):
+        if not srt_path or (not os.path.exists(srt_path) and not (STATE.dry_run and (args.text or args.transcribe))):
             die(f"SRT file not found: {srt_path}")
         style = [
             f"FontName={ass_font_name(args.font)}",

package/scripts/check.py

@@ -127,7 +127,7 @@ def main() -> int:
             row("fps", "PASS" if fps <= spec["fps_max"] + 0.01 else "FAIL", f"{fps:g}", f"<= {spec['fps_max']}", "fit.py --fps 30 (drops half the frames of 60 fps motion; fine for talking heads, visible on sports/gaming)")
         row("vfr", "PASS" if not v.get("variable_frame_rate_suspected") else "WARN", "variable" if v.get("variable_frame_rate_suspected") else "constant", "constant", "fit.py --fps N (any re-encode conforms it)")
         if spec["codecs"]:
-            row("video codec", "PASS" if v.get("codec") in spec["codecs"] else "FAIL", v.get("codec"), "/".join(spec["codecs"]), "export.py --preset " + args.platform.replace("shorts", "reels").replace("tiktok", "reels").replace("linkedin", "youtube"),
+            row("video codec", "PASS" if v.get("codec") in spec["codecs"] else "FAIL", v.get("codec"), "/".join(spec["codecs"]), "export.py --preset " + args.platform.replace("shorts", "reels").replace("tiktok", "reels").replace("linkedin", "youtube").replace("broadcast", "prores"),
                 reason="the platform's player may refuse to decode this codec at all, not just look worse")
         pf = v.get("pix_fmt") or ""
         if args.platform in ("reels", "tiktok", "x", "linkedin"):

package/scripts/color.py

@@ -22,7 +22,7 @@ import os
 import sys
 from typing import List
 
-from _common import add_common, analyze_levels, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, info, probe, run, run_keeping_subtitles, x264_args, X264_PRESETS, fmt_secs
+from _common import STATE, add_common, analyze_levels, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, info, probe, run, run_keeping_subtitles, x264_args, X264_PRESETS, fmt_secs
 
 TONEMAPS = ["hable", "mobius", "reinhard", "bt2390", "clip", "linear", "gamma"]
 
@@ -293,7 +293,7 @@ def main() -> int:
         tag = "correct"
         # OBSERVED technical measurements (signalstats: luma / saturation distribution), never a
         # "looks better" judgement -- the same primitive probe.py --analyze uses for Log detection.
-        measurements = {"input": analyze_levels(args.input)}
+        measurements = None if STATE.dry_run else {"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 "

package/scripts/cut.py

@@ -245,7 +245,11 @@ def main() -> int:
          requested_duration=round(expected, 6), output_duration=round(got, 6) if got is not None else None,
          duration_delta_seconds=round(error_ms / 1000, 6) if error_ms is not None else None,
          mode=mode, keyframe_snapped=keyframe_snapped,
-         nearest_keyframes=sorted(NEAREST_KEYFRAMES) if NEAREST_KEYFRAMES else None)
+         nearest_keyframes=sorted(NEAREST_KEYFRAMES) if NEAREST_KEYFRAMES else None,
+         # the trade the caller can offer instead of a re-encode (eval e02: "without losing quality")
+         lossless_alternative=(f"--start {min(NEAREST_KEYFRAMES, key=lambda k: abs(k - segments[0][0])):.3f} lands on a keyframe: "
+                               f"stream copy with no re-encode, {abs(min(NEAREST_KEYFRAMES, key=lambda k: abs(k - segments[0][0])) - segments[0][0]):.2f}s off the requested start")
+         if mode == "hybrid" and NEAREST_KEYFRAMES and len(segments) == 1 else None)
     return 0
 
 

package/scripts/export.py

@@ -27,6 +27,7 @@ from pathlib import Path
 from typing import Dict, List
 
 from _common import STATE, add_common, apply_common, bt709_tag_args, emit, cfr_args, default_output, die, ffmpeg_base, info, probe, run, validate_color, pad_filters, add_pad_fill_args, fmt_secs
+from check import SPECS as PLATFORMS, measure_loudness
 PRESETS: Dict[str, Dict] = {
     "youtube": {"w": 1920, "h": 1080, "ext": "mp4", "video": ["-c:v", "libx264", "-preset", "slow", "-crf", "18", "-profile:v", "high", "-pix_fmt", "yuv420p"], "audio": ["-c:a", "aac", "-b:a", "192k", "-ar", "48000"], "max": None, "desc": "1080p H.264, AAC 192k"},
     "youtube4k": {"w": 3840, "h": 2160, "ext": "mp4", "video": ["-c:v", "libx264", "-preset", "slow", "-crf", "18", "-profile:v", "high", "-pix_fmt", "yuv420p"], "audio": ["-c:a", "aac", "-b:a", "192k", "-ar", "48000"], "max": None, "desc": "2160p H.264, AAC 192k"},
@@ -40,6 +41,10 @@ PRESETS: Dict[str, Dict] = {
 
 
 
+# which check.py platform a preset targets (its loudness spec is measured after the write)
+PLATFORM_OF = {"youtube": "youtube", "youtube4k": "youtube", "reels": "reels", "x": "x"}
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input", nargs="?")
@@ -123,7 +128,24 @@ 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, **({"notes": notes} if notes else {}))
+    extra: Dict[str, object] = {}
+    platform = PLATFORM_OF.get(args.preset)
+    if platform and has_audio and not STATE.dry_run:
+        # Every eval run that exported for a platform then had to come back with loudness.py: the
+        # preset scales and tags but does not touch levels, and only check.py said so. Measure the
+        # written file here so the result names the gap and the caller plans one pass, not two.
+        spec = PLATFORMS[platform]
+        m = measure_loudness(output)
+        if m:
+            ok = abs(m["lufs"] - spec["lufs"]) <= spec["lufs_tol"] and m["tp"] <= spec["tp"]
+            extra["loudness"] = {"lufs": m["lufs"], "tp": m["tp"], "target_lufs": spec["lufs"], "target_tp": spec["tp"], "ok": ok}
+            if not ok:
+                notes.append(f"loudness {m['lufs']:.1f} LUFS / {m['tp']:+.1f} dBTP is outside {platform}'s {spec['lufs']:g} LUFS / {spec['tp']:g} dBTP; "
+                             f"run loudness.py -I {spec['lufs']:g} --tp {spec['tp']:g} on this file (or before export)")
+                info("warning: " + notes[-1])
+    if notes:
+        extra["notes"] = notes
+    emit(output, **extra)
     return 0
 
 

package/scripts/fit.py

@@ -239,12 +239,13 @@ def main() -> int:
     else:
         cmd += ["-an"]
     cmd += post
-    if abs(factor - 1.0) > 1e-4:
+    if abs(factor - 1.0) > 1e-4 or "-ss" in pre_input:
         # A subtitle/data stream stream-copied by run_keeping_subtitles keeps the source's
         # original timestamps; --method speed retimes video (setpts) and audio (atempo) but has
         # no equivalent way to retime a copied subtitle track, so it would desync from the
         # now-faster/slower picture. Drop them here rather than ship a captions track that lies
-        # about when a line is spoken.
+        # about when a line is spoken. --method trim's -ss moves the timeline the same way: a copied
+        # track kept its cues at the source's times and doubled the output's length (review 5).
         run(cmd + [output])
         dropped_streams = bool(meta.get("subtitle_streams") or meta.get("data_streams"))
     else:

package/scripts/join.py

@@ -68,7 +68,7 @@ def join_audio(args: argparse.Namespace, metas: List[dict]) -> int:
     cmd += ["-filter_complex", ";".join(parts), "-map", "[aout]", "-vn"] + audio_codec_for(output) + [output]
     run(cmd)
     expected = sum(durs) - d * (n - 1)
-    r = probe(output)
+    r = probe(output, role="output")
     a = r.get("audio") or {}
     if not STATE.dry_run:
         if r.get("video"):

package/scripts/multicam.py

@@ -77,6 +77,8 @@ def main() -> int:
         die(f"--analyze-seconds {args.analyze_seconds:g}: the window is decoded into memory; 900 s is the ceiling")
     if args.fps is not None and args.fps <= 0:
         die(f"--fps must be positive, got {args.fps:g}")
+    if not 0 <= args.audio < len(args.inputs):
+        die(f"--audio {args.audio}: inputs are numbered 0..{len(args.inputs) - 1}")
 
     n = len(args.inputs)
     if n < 2:

package/scripts/overlay.py

@@ -103,7 +103,7 @@ def main() -> int:
     ap.add_argument("--margin", type=int, default=24, help="margin from the edges in px (default 24)")
     ap.add_argument("--start", help="show from this time (default: whole video)")
     ap.add_argument("--end", help="hide after this time")
-    ap.add_argument("--fade", type=float, default=0.0, help="fade in/out duration in seconds")
+    ap.add_argument("--fade", type=float, default=0.0, help="fade-in duration in seconds (at --start or 0); the fade-out happens only at --end")
     ap.add_argument("--opacity", type=float, default=1.0, help="0..1 (default 1)")
     img = ap.add_argument_group("image options")
     img.add_argument("--scale", type=int, help="scale the image to this width in px (keeps aspect)")
@@ -188,12 +188,13 @@ def main() -> int:
         if args.opacity < 1:
             chain.append(f"colorchannelmixer=aa={args.opacity:g}")
         if args.fade > 0:
-            # no --start/--end: fade in at 0 and out at the end of the video
+            # no --start: fade in at 0. The fade-out only exists when --end names a moment the
+            # overlay leaves; without --end it stays to the last frame ("fade in at the start" is
+            # the common ask, and a matching fade-out at the very end surprised every eval run)
             s = start if start is not None else 0.0
-            e = end if end is not None else (meta.get("duration") or 0.0)
             chain.append(f"fade=t=in:st={s:.3f}:d={args.fade:g}:alpha=1")
-            if e > args.fade:
-                chain.append(f"fade=t=out:st={e - args.fade:.3f}:d={args.fade:g}:alpha=1")
+            if end is not None and end > args.fade:
+                chain.append(f"fade=t=out:st={end - args.fade:.3f}:d={args.fade:g}:alpha=1")
         x, y = position_exprs(args.position, args.margin, text_mode=False)
         ov = f"overlay={x}:{y}:format=auto"
         if enable:
@@ -249,8 +250,7 @@ def main() -> int:
             opts.append(f"fontfile={escape_filter_path(args.font_file)}")
         else:
             opts.append(f"font='{escape_drawtext(args.font)}'")
-        alpha = alpha_expr(args.opacity, start if start is not None else (0.0 if args.fade > 0 else None),
-                           end if end is not None else ((meta.get("duration") or None) if args.fade > 0 else None), args.fade)
+        alpha = alpha_expr(args.opacity, start if start is not None else (0.0 if args.fade > 0 else None), end, args.fade)
         opts.append(f"fontcolor={args.font_color}")
         if alpha != "1":
             opts.append(f"alpha='{alpha}'")

package/scripts/render.py

@@ -55,7 +55,7 @@ import sys
 from pathlib import Path
 from typing import Any, Dict, List
 
-from _common import STATE, add_common, apply_common, child_args, die, emit, info, probe, run_tool, place_output
+from _common import STATE, add_common, apply_common, child_args, die, emit, info, probe, run_tool, place_output, refuse_output_is_input
 
 HERE = Path(__file__).resolve().parent
 
@@ -133,6 +133,8 @@ def main() -> int:
     if not clips:
         die("project.clips is empty")
     output = rel(proj.get("output") or "final.mp4")
+    # the final stage is a copy from the work dir, so run()'s own guard never sees the sources (review 5)
+    refuse_output_is_input(output, *[rel(c.get("src")) for c in clips if c.get("src")])
     # The default work dir name comes only from the output path, with no PID or timestamp --
     # two concurrent render.py runs targeting the same output (a batch.py "project" recipe
     # processing several files in parallel, or simply running render.py twice by mistake) shared
@@ -363,7 +365,7 @@ def main() -> int:
     else:
         if not STATE.dry_run:
             place_output(current, output)
-        info(f"copied final stage to {output}")
+        info(("[dry-run] would copy" if STATE.dry_run else "copied") + f" final stage to {output}")
     current = output
 
     # ---- check

package/scripts/sequence.py

@@ -1,4 +1,3 @@
-import re
 #!/usr/bin/env python3
 """Turn a numbered image sequence into a video.
 
@@ -16,6 +15,7 @@ Examples:
   python3 sequence.py --dir frames --pattern "*.png" --fps 30 --start-number 1
 """
 import argparse
+import re
 import sys
 import tempfile
 from pathlib import Path