ffmpeg-skill 1.4.8 → 1.4.9

package/README.md

@@ -316,6 +316,21 @@ npx ffmpeg-skill doctor --json   # available / missing / missing_optional / unkn
 
 `doctor --json`'s `gpu_encoders` reports which GPU-backed encoders (`nvenc`, `videotoolbox`, `qsv`, `vaapi`, `amf`) this ffmpeg *build* was compiled with — read from `-encoders` alone, so it proves the capability shipped, not that the GPU/driver on this machine will actually accept a job (that needs a real encode, which `doctor`'s introspection never runs). No tool here uses one yet — every tool still assumes CPU x264/x265 — so this is purely informational and never affects `ok` or any tool's `usable`. GPU-accelerated encoding stays deliberately off the roadmap until there's a real-hardware-verified design for it (build-presence alone is not proof a job will succeed) — not a promised feature, just an honest "not yet, and not without proof it actually works."
 
+## Gotchas and best practices
+
+The short list for humans. The agent-facing version, with the reasoning, is the "Things that look right but are wrong" and "Gotchas" sections of [SKILL.md](SKILL.md).
+
+- **Variable frame rate (phone and screen recordings).** `probe.py` flags it; every re-encoding tool conforms to a constant rate automatically, and `cut.py` switches to frame-accurate mode on its own because copy-cuts on VFR land on the wrong frame. Choose the rate yourself with `fit.py input.mp4 --fps 30` when the measured average is odd.
+- **Lossless cuts snap to keyframes.** A stream-copy cut can start up to one GOP earlier than asked. `cut.py` re-encodes when the snap exceeds 0.5 s (`--tolerance` changes the limit). For a strictly lossless file pass `--tolerance -1`, and expect the cut to land on the nearest earlier keyframe; the JSON result lists them under `nearest_keyframes`.
+- **HDR stays HDR.** When the probe reports HDR (HDR10, HLG, Dolby Vision, BT.2020), the tools keep it rather than flatten it. Convert deliberately with `color.py --to-sdr` before H.264 deliverables or LUT work. `export.py` platform presets are SDR and warn on HDR input.
+- **Loudness targets.** −14 LUFS / −1 dBTP for YouTube and social platforms (the `loudness.py` default), `-I -16 --tp -1.5` for podcasts, `-I -23` for broadcast. A clip measured at −40 LUFS or below is room tone, not content; raising it raises the noise. Check true peak as well as LUFS: `check.py file --platform podcast` measures both.
+- **Frame changes first, text second.** Captions and overlays burned before a crop or resize end up off-frame. Reframe, then caption.
+- **Cropping 16:9 to 9:16 discards 70 % of the width.** `fit.py --fit crop` centres by default; pass `--crop-x`/`--crop-y` toward the subject, or pad with `--fit pad --pad-fill blur`. Look at the contact sheet before deciding.
+- **Non-Latin captions need a font with the glyphs.** Without one you get boxes, not an error. Name it (`caption.py --font "Noto Sans CJK JP"`) or point at the file (`overlay.py --font-file /path/to/NotoSansCJK-Regular.ttc`).
+- **Silence detection finds nothing?** The default threshold is −35 dBFS. The tool prints a hint with the track's measured level; raise the threshold (`silence.py --threshold -25`) or shorten `--min-silence`.
+- **Sync results carry a confidence.** Below 0.3, or an offset near the edge of the analysis window, is probably wrong: enlarge `--analyze-seconds` or find a clap. Recordings over ten minutes from separate devices need `sync.py --fix-drift`.
+- **Long chains belong in a plan.** Three hand-chained re-encodes lose quality and are hard to change; `render.py` runs the whole edit from one JSON file, and `--dry-run` shows every ffmpeg command before anything is written.
+
 ## FFmpeg compatibility
 
 The tools need FFmpeg 5.0 or later and Python 3.9 or later (standard library only). What CI actually exercises on every pull request is FFmpeg 5.1.1 (static build), 6.1 (Ubuntu apt), 7.1 (Debian trixie apt), 8.x (macOS Homebrew) and 9.x (Windows gyan.dev), on Python 3.9 and 3.13 (the two ends of the supported range). The capability parser has been run against the listings of these builds:

package/SKILL.md

@@ -5,7 +5,7 @@ description: 'Edit video and audio with local FFmpeg from natural-language reque
 
 # ffmpeg-skill
 
-Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>/scripts/<name>.py`. Every script has `--help`, and all of them accept `--dry-run`, `--json` (structured result with a probe of the output), `--fast` (preview quality), `--progress`, `--timeout SECONDS` (a single ffmpeg run is killed past this and reported as `kind: timeout`; default 1800) and `--overwrite` (consent to replace an output that already exists; without it the tool warns today and refuses from 2.0). Writing tools run nothing under `--dry-run`; `probe`/`check`/`sync`/`multicam`/`scenes`/`cropdetect`/`report` may still run ffmpeg/ffprobe to measure or analyse — they just don't write their final artifact; `verify` accepts the flag but ignores it. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`). Details for every flag: `references/scripts.md`. Device-specific behaviour (iPhone HDR, GoPro, DJI, screen recordings, Zoom): `references/devices.md`.
+Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>/scripts/<name>.py`. Every script has `--help`, and all of them accept `--dry-run`, `--json` (structured result with a probe of the output), `--fast` (preview quality), `--progress`, `--timeout SECONDS` (a single ffmpeg run is killed past this and reported as `kind: timeout`; default 1800) and `--overwrite` (consent to replace an output that already exists; without it the tool warns today and refuses from 2.0). Writing tools run nothing under `--dry-run`; `probe`/`check`/`sync`/`multicam`/`scenes`/`cropdetect`/`report`/`silence`/`loudness`/`stabilize` may still run ffmpeg/ffprobe to measure or analyse — they just don't write their final artifact (nor side files such as `--edl`, `--sheet` or a generated `.ass`); `verify` accepts the flag but ignores it. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`). Details for every flag: `references/scripts.md`. Device-specific behaviour (iPhone HDR, GoPro, DJI, screen recordings, Zoom): `references/devices.md`.
 
 ## Workflow (always follow this order)
 

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.8`) | any release |
+| `skill.version` | the npm / package.json version (`1.4.9`) | 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.4.8", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "1.4.9", "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"},
@@ -156,9 +156,10 @@ with `--dry-run` behind a fake `ffmpeg` that records any call, and asserts that
 call happened and no file appeared. Under `--dry-run` a tool prints the command lines
 it would run, reports `dry_run: true`, and never reports an output probe. The
 exceptions are stated per tool in the contract's `dry_run` field: `probe` and `check` are
-read-only (ffprobe still runs), `sync`, `multicam`, `scenes`, `cropdetect` and `report` still
-run their ffmpeg/ffprobe measurements (the analysis is the tool's job; only the artifact is
-skipped), and `verify` does not support dry-run (its steps run). `SKILL.md` and
+read-only (ffprobe still runs); `sync`, `multicam`, `scenes`, `cropdetect`, `report`, `silence`,
+`loudness` and `stabilize` still run their ffmpeg/ffprobe measurements (the analysis is the
+tool's job; only the artifact is skipped, including side files such as `--edl`, `--sheet` or a
+generated `.ass`), and `verify` does not support dry-run (its steps run). `SKILL.md` and
 `references/scripts.md` repeat the same list; the contract is the authority.
 
 ### Repeatability

package/package.json

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

package/scripts/_common.py

@@ -356,6 +356,26 @@ def _check_no_overwrite_input(cmd: Sequence[str]) -> None:
                 continue
 
 
+def refuse_output_is_input(output: str, *inputs: str) -> None:
+    """Tool-level twin of the run() guard, for tools whose final ffmpeg command does not name
+    the user's input at all. `cut.py --segments` cuts each part into a temp dir and then concats
+    a list file: the last command's only `-i` is that list, so `-o` equal to the input sailed
+    through _check_no_overwrite_input() and replaced the source with the join (fourth audit,
+    P0). Call it once the output path is known, before any part of the input is consumed."""
+    try:
+        out_real = os.path.realpath(output)
+    except OSError:
+        return
+    for inp in inputs:
+        try:
+            same = os.path.realpath(inp) == out_real
+        except OSError:
+            continue
+        if same:
+            die(f"refusing to run: output {output!r} is the same file as input {inp!r} "
+                f"(the result would replace the source) -- choose a different --output/-o path", kind="input")
+
+
 def _check_existing_output(cmd: Sequence[str]) -> None:
     """An output path that already exists is someone's file: a previous result, a source the
     agent mis-named, a deliverable from another run. ffmpeg's -y (which every command carries so
@@ -954,6 +974,19 @@ def parse_time(value: str, fps: Optional[float] = None) -> float:
     return total
 
 
+def time_arg(value: str, flag: str, fps: Optional[float] = None) -> float:
+    """parse_time() for a command-line flag: SMPTE hh:mm:ss:ff resolves with the input's fps when
+    the caller has one, and every parse failure is a `kind: input` refusal naming the flag (so
+    `--json` callers get a failure document, never a traceback)."""
+    try:
+        return parse_time(value, fps)
+    except MissingFpsError as e:
+        die(f"{flag} {value!r}: {e}")
+    except ValueError as e:
+        die(f"{flag} {value!r}: {e} (use seconds, mm:ss, hh:mm:ss.ms or, with a known fps, hh:mm:ss:ff)")
+    return 0.0  # unreachable
+
+
 def fmt_srt_time(seconds: float) -> str:
     if seconds < 0:
         seconds = 0.0

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, validate_color, video_args, X264_PRESETS
+from _common import add_common, apply_common, die, emit, ffmpeg_base, info, parse_time, probe, run, validate_color, video_args, X264_PRESETS, time_arg
 
 
 def main() -> int:
@@ -34,7 +34,7 @@ def main() -> int:
     args = ap.parse_args()
     apply_common(args)
 
-    target = parse_time(args.duration)
+    target = time_arg(args.duration, "--duration", args.fps)
     if target <= 0:
         die("--duration must be > 0")
     if args.fps <= 0:

package/scripts/caption.py

@@ -200,7 +200,10 @@ def parse_srt(path: str) -> List[Tuple[float, float, str]]:
             if times:
                 a, b = times.split("-->")
                 text = "\n".join(block[block.index(times) + 1:]).strip()
-                cues.append((parse_time(a), parse_time(b), text))
+                try:
+                    cues.append((parse_time(a), parse_time(b), text))
+                except ValueError as e:  # includes MissingFpsError: SRT timings are hh:mm:ss,ms, never frames
+                    die(f"{path}: cannot read the timing line {times.strip()!r}: {e}")
             block = []
     if not cues:
         die(f"no cues found in {path}")
@@ -531,12 +534,16 @@ def main() -> int:
         w, h = meta["video"]["width"], meta["video"]["height"]
         if meta["video"].get("rotation") in (90, -90, 270, -270):
             w, h = h, w
-        write_ass(cues_for_ass, ass_path, args, w, h, video=args.input if meta.get("audio") else None)
+        if not STATE.dry_run:  # the generated ASS is an artifact of this run: a plan writes nothing
+            write_ass(cues_for_ass, ass_path, args, w, h, video=args.input if meta.get("audio") else None)
         info(f"wrote {ass_path} ({len(cues_for_ass)} cues, animate={args.animate}, karaoke={args.karaoke})")
         args.ass = ass_path
+        generated_ass = True
+    else:
+        generated_ass = False
 
     if args.ass:
-        if not os.path.exists(args.ass):
+        if not generated_ass and not os.path.exists(args.ass):
             die(f"ASS file not found: {args.ass}")
         vf = f"ass={escape_filter_path(args.ass)}"
         if args.fonts_dir:

package/scripts/cut.py

@@ -30,7 +30,7 @@ import sys
 import tempfile
 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
+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
 
 # 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)
@@ -192,6 +192,7 @@ def main() -> int:
     segments = [(s, min(e, total) if total else e) for s, e in segments]
 
     output = args.output or default_output(args.input, "cut")
+    refuse_output_is_input(output, args.input)
     ext = os.path.splitext(output)[1] or ".mp4"
 
     reencoded = False

package/scripts/fit.py

@@ -38,7 +38,7 @@ import sys
 from fractions import Fraction
 from typing import List
 
-from _common import video_args, STATE, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, pad_filters, add_pad_fill_args, X264_PRESETS
+from _common import video_args, STATE, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, pad_filters, add_pad_fill_args, X264_PRESETS, time_arg
 ASPECT_PRESETS = {"16:9": Fraction(16, 9), "9:16": Fraction(9, 16), "1:1": Fraction(1, 1), "4:5": Fraction(4, 5), "4:3": Fraction(4, 3), "21:9": Fraction(21, 9)}
 
 
@@ -155,7 +155,7 @@ def main() -> int:
 
     # ---- duration
     if args.duration:
-        target = parse_time(args.duration)
+        target = time_arg(args.duration, "--duration", meta["video"].get("fps") if meta.get("video") else None)
         if target <= 0:
             die("target duration must be > 0")
         if args.method == "speed":

package/scripts/graphics.py

@@ -21,7 +21,7 @@ import argparse
 import sys
 from typing import List, Optional
 
-from _common import aac_args, add_common, apply_common, cfr_args, color_hex, default_font_file, default_output, die, emit, escape_drawtext, escape_filter_path, ffmpeg_base, info, load_brand, parse_time, probe, run, run_keeping_subtitles, video_args, drawtext_boxborderw, X264_PRESETS
+from _common import aac_args, add_common, apply_common, cfr_args, color_hex, default_font_file, default_output, die, emit, escape_drawtext, escape_filter_path, ffmpeg_base, info, load_brand, parse_time, probe, run, run_keeping_subtitles, video_args, drawtext_boxborderw, X264_PRESETS, time_arg
 
 TEMPLATES = ["lower-third", "title", "chapter", "progress", "countdown", "bug"]
 
@@ -86,8 +86,9 @@ def main() -> int:
     if meta["video"].get("rotation") in (90, -90, 270, -270):
         W, H = H, W
     dur = meta.get("duration") or 0.0
-    s = parse_time(args.start) if args.start else 0.0
-    e = parse_time(args.end) if args.end else dur
+    fps = meta["video"].get("fps")
+    s = time_arg(args.start, "--start", fps) if args.start else 0.0
+    e = time_arg(args.end, "--end", fps) if args.end else dur
     if e <= s:
         die("--end must be after --start")
     en = f"enable='between(t,{s:.3f},{e:.3f})'"

package/scripts/insert.py

@@ -27,7 +27,7 @@ import argparse
 import math
 import sys
 
-from _common import add_common, apply_common, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, video_args, X264_PRESETS
+from _common import add_common, apply_common, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, video_args, X264_PRESETS, time_arg
 
 
 def even(n: float) -> int:
@@ -52,7 +52,7 @@ def main() -> int:
     args = ap.parse_args()
     apply_common(args)
 
-    target = parse_time(args.duration)
+    target = time_arg(args.duration, "--duration", args.fps)
     if target <= 0:
         die("--duration must be > 0")
     if args.fps <= 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
+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
 
 FONT = "fontcolor=white:fontsize=h/18:box=1:boxcolor=black@0.55:boxborderw=6:x=8:y=8"
 
@@ -69,7 +69,7 @@ def main() -> int:
             die("--compare needs --at TIME")
         probe(args.compare)
         for t in args.at:
-            sec = parse_time(t)
+            sec = time_arg(t, "--at", meta["video"].get("fps") if meta.get("video") else None)
             out = args.output or os.path.join(outdir, f"{stem}_vs_{Path(args.compare).stem}_{sec:.3f}s.png")
             half = args.width // 2
             stamp = "" if args.no_timecode else f",drawtext=text='{escape_drawtext(fmt_hms(sec))}':{font_prefix}{FONT}"
@@ -82,7 +82,7 @@ def main() -> int:
             outputs.append(out)
     elif args.at:
         for t in args.at:
-            sec = parse_time(t)
+            sec = time_arg(t, "--at", meta["video"].get("fps") if meta.get("video") else None)
             if dur and sec > dur:
                 die(f"--at {t} is beyond the duration ({dur:.2f}s)")
             if args.output and len(args.at) == 1 and Path(args.output).suffix.lower() in (".png", ".jpg", ".jpeg", ".webp"):

package/scripts/loop.py

@@ -18,7 +18,7 @@ import argparse
 import math
 import sys
 
-from _common import add_common, aac_args, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, video_args, X264_PRESETS
+from _common import add_common, aac_args, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, video_args, X264_PRESETS, time_arg
 
 
 def main() -> int:
@@ -49,7 +49,7 @@ def main() -> int:
         target = None
         stream_loop = args.times - 1
     else:
-        target = parse_time(args.duration)
+        target = time_arg(args.duration, "--duration", meta["video"].get("fps") if meta.get("video") else None)
         if target <= src_dur:
             die(f"--duration ({target:g}s) must be longer than the source ({src_dur:.3f}s) -- use cut.py to trim instead")
         stream_loop = math.ceil(target / src_dur) - 1

package/scripts/metadata.py

@@ -48,7 +48,7 @@ def parse_chapters(path: str, duration: float) -> List[Dict[str, Any]]:
         parts = line.split(None, 1)
         try:
             start = parse_time(parts[0])
-        except ValueError:
+        except ValueError:  # MissingFpsError is a ValueError: chapter files carry no fps
             die(f"{path}:{n}: cannot read the time in {line!r} (use seconds, mm:ss or hh:mm:ss.ms)")
         title = parts[1].strip() if len(parts) > 1 else f"Chapter {len(entries) + 1}"
         if entries and start <= entries[-1]["start"]:

package/scripts/overlay.py

@@ -24,7 +24,7 @@ import argparse
 import sys
 from typing import List, Optional
 
-from _common import STATE, load_brand, video_args, add_common, apply_common, default_font_file, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, X264_PRESETS
+from _common import STATE, load_brand, video_args, add_common, apply_common, default_font_file, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, X264_PRESETS, time_arg
 
 POS = {
     "top-left": ("{m}", "{m}"),
@@ -155,8 +155,9 @@ def main() -> int:
     if args.audio_stream and not audio_streams:
         die("--audio-stream needs an input with audio streams")
     vw = meta["video"]["width"]
-    start = parse_time(args.start) if args.start else None
-    end = parse_time(args.end) if args.end else None
+    fps = meta["video"].get("fps")
+    start = time_arg(args.start, "--start", fps) if args.start else None
+    end = time_arg(args.end, "--end", fps) if args.end else None
     if start is not None and end is not None and end <= start:
         die("--end must be after --start")
     if not 0 <= args.opacity <= 1:

package/scripts/pad.py

@@ -16,15 +16,15 @@ 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
+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
 
 
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
     ap.add_argument("-o", "--output", help="output file (default: <name>_pad.<ext>)")
-    ap.add_argument("--start", type=float, default=0.0, help="seconds of padding to add before the clip (default 0)")
-    ap.add_argument("--end", type=float, default=0.0, help="seconds of padding to add after the clip (default 0)")
+    ap.add_argument("--start", default="0", help="padding to add before the clip: seconds or mm:ss (default 0)")
+    ap.add_argument("--end", default="0", help="padding to add after the clip: seconds or mm:ss (default 0)")
     ap.add_argument("--color", default="black", help="padding colour (default black)")
     ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
     ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
@@ -32,6 +32,8 @@ def main() -> int:
     args = ap.parse_args()
     apply_common(args)
 
+    args.start = time_arg(args.start, "--start")
+    args.end = time_arg(args.end, "--end")
     if args.start < 0 or args.end < 0:
         die(f"--start/--end must be >= 0, got start={args.start:g} end={args.end:g}")
     if args.start == 0 and args.end == 0:

package/scripts/scenes.py

@@ -24,7 +24,7 @@ import re
 import sys
 from typing import Dict, List, Tuple
 
-from _common import add_common, apply_common, default_font_file, die, emit, escape_filter_path, ffmpeg_base, info, print_json, probe, require_tool, run, run_analysis, decode_pcm_mono, rms_envelope
+from _common import STATE, add_common, apply_common, default_font_file, die, emit, escape_filter_path, ffmpeg_base, info, print_json, probe, require_tool, run, run_analysis, decode_pcm_mono, rms_envelope
 
 SCORE_RE = re.compile(r"frame:(\d+)\s+pts:\d+\s+pts_time:([0-9.]+)")
 
@@ -168,9 +168,10 @@ def main() -> int:
         result["highlights_rank_by"] = args.rank_by
         info(f"proposed {len(picks)} highlight ranges totalling {result['highlights_total']:.1f}s")
         if args.edl:
-            with open(args.edl, "w", encoding="utf-8") as fh:
-                for s, e in picks:
-                    fh.write(f"{s:.2f}-{e:.2f}\n")
+            if not STATE.dry_run:  # the contract says --edl is not written under --dry-run
+                with open(args.edl, "w", encoding="utf-8") as fh:
+                    for s, e in picks:
+                        fh.write(f"{s:.2f}-{e:.2f}\n")
             info(f"wrote {args.edl}")
 
     if args.sheet:

package/scripts/silence.py

@@ -104,9 +104,10 @@ def main() -> int:
         info("hint: " + summary["hint"])
 
     if args.edl:
-        with open(args.edl, "w", encoding="utf-8") as fh:
-            for s, e in keeps:
-                fh.write(f"{s:.3f}-{e:.3f}\n")
+        if not STATE.dry_run:  # the EDL is an artifact like the cut itself: a plan writes nothing
+            with open(args.edl, "w", encoding="utf-8") as fh:
+                for s, e in keeps:
+                    fh.write(f"{s:.3f}-{e:.3f}\n")
         info(f"wrote {args.edl}")
 
     if args.list: