ffmpeg-skill 1.4.6 → 1.4.7

package/package.json

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

@@ -1,6 +1,6 @@
 # Script reference
 
-Every script prints the same information with `--help`; this file exists so the agent can read several at once. All scripts accept `--dry-run`, `--json`, `--fast`, `--progress`, `--timeout SECONDS`, `--overwrite`, `-o OUT` -- but `--dry-run` only guarantees nothing is written for writing tools: `probe` (read-only, `--dry-run` changes nothing) and `check` (skips only the loudness-measurement pass) still run ffprobe/ffmpeg, `sync`/`multicam`/`scenes`/`cropdetect`/`report` still run ffmpeg/ffprobe to measure or analyse (they just don't write the final artifact), and `verify` accepts the flag but ignores it entirely. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`).
+Every script prints the same information with `--help`; this file exists so the agent can read several at once. All scripts accept `--dry-run`, `--json`, `--fast`, `--progress`, `--timeout SECONDS`, `--overwrite`, `-o OUT` -- but `--dry-run` only guarantees nothing is written for writing tools: `probe` (read-only, `--dry-run` changes nothing) still runs ffprobe, `check`/`sync`/`multicam`/`scenes`/`cropdetect`/`report`/`silence`/`loudness`/`stabilize` still run their ffmpeg/ffprobe measurements (a dry-run plan rests on real numbers; they just don't write the final artifact), and `verify` accepts the flag but ignores it entirely. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`).
 
 ## Contents
 - probe.py — inspect

package/scripts/_common.py

@@ -462,12 +462,17 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subpr
     return proc
 
 
-def run_analysis(cmd: Sequence[str], *, check: bool = True, text: bool = True) -> subprocess.CompletedProcess:
-    """Run an ffmpeg *measurement* (scene scores, crop rectangles, decoded PCM, signal stats):
-    output to `-f null` or a pipe, nothing written. These are not run() calls -- they run under
-    --dry-run too, since the analysis is the tool's whole job -- but they get the same wall-clock
-    limit as any other ffmpeg invocation and, with check=True, the same `kind: ffmpeg` failure
-    instead of an exit-0 "0 scenes found" over a file ffmpeg could not read."""
+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
+    file, no deliverable written. These are not run() calls -- they run under --dry-run too,
+    since a plan built on a fake measurement is not a plan (silence.py used to report "0
+    silences" and loudness.py a made-up -20 LUFS under --dry-run) -- but they get the same
+    wall-clock limit as any other ffmpeg invocation and, with check=True, the same `kind: ffmpeg`
+    failure instead of an exit-0 "0 scenes found" over a file ffmpeg could not read. record=True
+    lists the command in the --json `commands` like run() does."""
+    if record:
+        STATE.commands.append(_cmdline(cmd))
     limit = _limit_for(cmd)
     try:
         proc = subprocess.run(list(cmd), stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=text, timeout=limit)
@@ -479,6 +484,17 @@ def run_analysis(cmd: Sequence[str], *, check: bool = True, text: bool = True) -
     return proc
 
 
+def dry_run_input_pending(path: str) -> bool:
+    """True when a measurement cannot run because its input does not exist yet under --dry-run:
+    in a render.py/batch.py plan each stage's input is the previous stage's output, which a dry
+    run never wrote. The measurement is then skipped (with a note) rather than failing the plan;
+    on a real file the measurement runs even under --dry-run."""
+    if STATE.dry_run and not os.path.exists(path):
+        info(f"[dry-run] {path} does not exist yet (an earlier dry-run stage would write it); measurement skipped")
+        return True
+    return False
+
+
 def child_limit(per_call: Optional[float] = None) -> Optional[float]:
     """Wall-clock ceiling for running one sibling script as a subprocess (render/batch/report
     stages, the MCP server's dispatch). A tool runs a handful of ffmpeg/ffprobe calls, each
@@ -1142,6 +1158,9 @@ def db_to_linear(db: float) -> float:
 def read_text_or_die(path: str, flag: str) -> str:
     """Read a caller-supplied UTF-8 text file (a cue list, chapters, notes) or fail as kind input
     with the flag named, instead of a FileNotFoundError / UnicodeDecodeError traceback."""
+    if os.path.isdir(path):
+        # checked first: Windows raises PermissionError, not IsADirectoryError, for a directory
+        die(f"{flag}: {path} is a directory, not a text file")
     try:
         with open(path, "r", encoding="utf-8") as fh:
             return fh.read()

package/scripts/_contract.py

@@ -215,10 +215,13 @@ DRY_RUN_ANALYSIS = {
     "scenes": "scene and audio-peak measurement runs; --sheet and --edl are not written",
     "report": "probe, loudness and contact-sheet measurements run; the HTML is not written",
     "cropdetect": "the cropdetect filter runs over the sampled windows to measure bars; this tool never writes a file regardless of --dry-run",
+    "silence": "silencedetect runs so the reported silences and keep ranges are real; the cut output is not written",
+    "loudness": "the loudnorm measurement pass runs so input_i and the planned pass-2 command are real; the normalised output is not written",
+    "check": "read-only tool; the loudness measurement runs under --dry-run too, so every row is present",
+    "stabilize": "vidstabdetect (pass 1, into a temp file) runs; the stabilised output (pass 2) is not written",
 }
 DRY_RUN_NOTES = {
     "probe": "read-only tool; --dry-run changes nothing (ffprobe still runs)",
-    "check": "read-only tool; --dry-run skips the ffmpeg loudness measurement, so loudness rows are absent",
     "verify": "not supported: the flag is accepted but the steps run and outputs are written",
 }
 

package/scripts/batch.py

@@ -31,7 +31,7 @@ import time
 from pathlib import Path
 from typing import Any, Dict, List
 
-from _common import STATE, add_common, apply_common, child_args, die, emit, info, run_tool
+from _common import STATE, add_common, apply_common, child_args, die, emit, info, run_tool, read_text_or_die
 
 HERE = Path(__file__).resolve().parent
 MEDIA_EXT = {".mp4", ".mov", ".m4v", ".mkv", ".webm", ".avi", ".mts", ".m2ts", ".mxf", ".wav", ".m4a", ".mp3", ".flac"}
@@ -102,7 +102,10 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path) -> Dict
     final = final_path(src, recipe, outdir)
     t0 = time.time()
     if recipe.get("project"):
-        proj = json.loads(Path(recipe["project"]).read_text(encoding="utf-8"))
+        try:
+            proj = json.loads(read_text_or_die(str(recipe["project"]), "recipe.project"))
+        except ValueError as e:
+            die(f"recipe.project: {recipe['project']} is not valid JSON: {e}")
         idx = int(recipe.get("clip_key", 0))
         proj.setdefault("clips", [{}])
         while len(proj["clips"]) <= idx:

package/scripts/caption.py

@@ -36,7 +36,7 @@ import sys
 from pathlib import Path
 from typing import List, Optional, Tuple
 
-from _common import STATE, color_hex, load_brand, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, fmt_smpte_time, info, MissingFpsError, parse_time, probe, run, x264_args, X264_PRESETS
+from _common import STATE, color_hex, load_brand, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, fmt_smpte_time, info, MissingFpsError, parse_time, probe, run, x264_args, X264_PRESETS, read_text_or_die
 
 ALIGN = {"bottom": 2, "top": 8, "center": 5, "bottom-left": 1, "bottom-right": 3, "top-left": 7, "top-right": 9}
 
@@ -48,33 +48,32 @@ TIME_RE = re.compile(
 def parse_text_cues(path: str, auto_seconds: float, gap: float, fps: Optional[float] = None) -> List[Tuple[float, float, str]]:
     cues: List[Tuple[float, float, str]] = []
     cursor = 0.0
-    with open(path, encoding="utf-8") as fh:
-        for raw in fh:
-            line = raw.rstrip("\n")
-            if not line.strip():
-                continue
-            m = TIME_RE.match(line)
-            if m:
-                try:
-                    start, end = parse_time(m.group("a"), fps), parse_time(m.group("b"), fps)
-                except MissingFpsError as e:
-                    die(f"cue '{line}': {e} -- pass --fps, or --input's own fps is used automatically when given")
-                except ValueError:
-                    # TIME_RE matched (so m.group("text") is the real cue text, not the broken
-                    # timestamp), but one of the two timestamps itself failed to parse (e.g. a
-                    # malformed "00:00:03.15.999") -- falling back to `line.strip()` here used to
-                    # burn the whole raw line, broken timestamp included, into the caption instead
-                    # of just the text after it.
-                    start, end, text = cursor, cursor + auto_seconds, m.group("text").strip()
-                else:
-                    text = m.group("text").strip()
+    for raw in read_text_or_die(path, "--text").lstrip("\ufeff").splitlines(True):
+        line = raw.rstrip("\n")
+        if not line.strip():
+            continue
+        m = TIME_RE.match(line)
+        if m:
+            try:
+                start, end = parse_time(m.group("a"), fps), parse_time(m.group("b"), fps)
+            except MissingFpsError as e:
+                die(f"cue '{line}': {e} -- pass --fps, or --input's own fps is used automatically when given")
+            except ValueError:
+                # TIME_RE matched (so m.group("text") is the real cue text, not the broken
+                # timestamp), but one of the two timestamps itself failed to parse (e.g. a
+                # malformed "00:00:03.15.999") -- falling back to `line.strip()` here used to
+                # burn the whole raw line, broken timestamp included, into the caption instead
+                # of just the text after it.
+                start, end, text = cursor, cursor + auto_seconds, m.group("text").strip()
             else:
-                start, end, text = cursor, cursor + auto_seconds, line.strip()
-            if end <= start:
-                die(f"cue '{line}': end must be after start")
-            text = text.replace(" | ", "\n").replace("|", "\n")
-            cues.append((start, end, text))
-            cursor = end + gap
+                text = m.group("text").strip()
+        else:
+            start, end, text = cursor, cursor + auto_seconds, line.strip()
+        if end <= start:
+            die(f"cue '{line}': end must be after start")
+        text = text.replace(" | ", "\n").replace("|", "\n")
+        cues.append((start, end, text))
+        cursor = end + gap
     if not cues:
         die(f"no cues found in {path}")
     return cues
@@ -173,8 +172,7 @@ def _transcribe_in(tmpdir: str, video: str, out_srt: str, language: Optional[str
 def parse_srt(path: str) -> List[Tuple[float, float, str]]:
     cues: List[Tuple[float, float, str]] = []
     block: List[str] = []
-    with open(path, encoding="utf-8-sig") as fh:
-        content = fh.read().replace("\r\n", "\n") + "\n\n"
+    content = read_text_or_die(path, "--srt").lstrip("\ufeff").replace("\r\n", "\n") + "\n\n"
     for line in content.split("\n"):
         if line.strip():
             block.append(line)

package/scripts/check.py

@@ -25,7 +25,7 @@ import sys
 from fractions import Fraction
 from typing import Any, Dict, List
 
-from _common import STATE, add_common, apply_common, die, emit, info, probe, require_tool, run
+from _common import STATE, add_common, apply_common, die, emit, info, probe, require_tool, run, run_analysis, dry_run_input_pending
 
 SPECS: Dict[str, Dict[str, Any]] = {
     "youtube":   {"max_duration": 12 * 3600, "aspects": ["16:9", "9:16", "1:1", "4:3"], "min_height": 720, "fps_max": 60, "codecs": ["h264", "hevc", "prores", "av1", "vp9"], "max_bytes": 256 * 1024 ** 3, "lufs": -14, "lufs_tol": 2.0, "tp": -1.0, "sdr_only": False},
@@ -41,8 +41,10 @@ SPECS: Dict[str, Dict[str, Any]] = {
 
 
 def measure_loudness(path: str) -> Dict[str, float]:
+    if dry_run_input_pending(path):
+        return {}
     ffmpeg = require_tool("ffmpeg")
-    proc = run([ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-vn", "-af", "loudnorm=I=-14:TP=-1:LRA=11:print_format=json", "-f", "null", "-"], quiet=True, check=False)
+    proc = run_analysis([ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-vn", "-af", "loudnorm=I=-14:TP=-1:LRA=11:print_format=json", "-f", "null", "-"], check=False, record=True)
     m = re.search(r"\{[^{}]*\"input_i\"[^{}]*\}", proc.stderr, re.S)
     if not m:
         return {}

package/scripts/cropdetect.py

@@ -42,14 +42,22 @@ def detect(path: str, seconds: float, samples: int, limit: float, round_to: int,
     ffmpeg = require_tool("ffmpeg")
     per_window = max(0.5, seconds / max(1, samples))
     rects: List[Tuple[int, int, int, int]] = []
+    failures: List[List[str]] = []
     for i in range(samples):
         start = 0.0 if duration <= 0 else (duration - per_window) * i / max(1, samples - 1) if samples > 1 else 0.0
         start = max(0.0, start)
         cmd = [ffmpeg, "-hide_banner", "-nostdin", "-ss", f"{start:.3f}", "-i", path, "-t", f"{per_window:.3f}",
                "-vf", f"cropdetect=limit={limit:g}:round={round_to}:reset=1", "-f", "null", "-"]
-        proc = run_analysis(cmd)
+        proc = run_analysis(cmd, check=False)
+        if proc.returncode != 0:
+            # One window ffmpeg cannot decode (a damaged stretch) is skipped; the other windows
+            # still measure. Only when every window fails is there nothing to report.
+            failures.append(proc.stderr.strip().splitlines()[-1:] or ["?"])
+            continue
         for m in CROP_RE.finditer(proc.stderr):
             rects.append((int(m.group(1)), int(m.group(2)), int(m.group(3)), int(m.group(4))))
+    if failures and len(failures) == samples:
+        die(f"cropdetect could not decode any of the {samples} sampled windows: {failures[-1][0][:300]}", kind="ffmpeg")
     return rects
 
 

package/scripts/loudness.py

@@ -18,16 +18,18 @@ 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
+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
 
 
 
 def measure(path: str, I: float, tp: float, lra: float) -> dict:
-    if STATE.dry_run:
-        return {"input_i": "-20.0", "input_tp": "-3.0", "input_lra": "8.0", "input_thresh": "-30.0", "target_offset": "0.0", "silent": False}
+    if dry_run_input_pending(path):
+        return {"input_i": "-20.0", "input_tp": "-3.0", "input_lra": "8.0", "input_thresh": "-30.0", "target_offset": "0.0", "silent": False, "placeholder": True}
     ffmpeg = require_tool("ffmpeg")
     cmd = [ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-vn", "-af", f"loudnorm=I={I}:TP={tp}:LRA={lra}:print_format=json", "-f", "null", "-"]
-    proc = run(cmd, check=False)
+    # Pass 1 is a measurement: it runs under --dry-run too, so the planned pass-2 command and
+    # the reported input_i are real (before 1.4.6 a dry run returned a made-up -20 LUFS).
+    proc = run_analysis(cmd, check=False, record=True)
     m = re.search(r"\{[^{}]*\"input_i\"[^{}]*\}", proc.stderr, re.S)
     if proc.returncode != 0 or not m:
         die(f"loudness measurement failed:\n{proc.stderr.strip()[-1500:]}", kind="ffmpeg")
@@ -86,6 +88,10 @@ def main() -> int:
     cmd.append(output)
     run(cmd)
 
+    if STATE.dry_run:
+        # pass 1 measured the input for real; there is no output to measure
+        emit(output, measured={k: stats[k] for k in ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset", "silent")})
+        return 0
     after = measure(output, args.lufs, args.tp, args.lra)
     if not after.get("silent"):
         info(f"result:   {float(after['input_i']):.1f} LUFS, TP {float(after['input_tp']):.1f} dBTP (target {args.lufs} LUFS)")

package/scripts/render.py

@@ -358,7 +358,7 @@ def main() -> int:
     check_result = None
     exit_code = 0
     if ck and ck.get("platform") and not STATE.dry_run:
-        proc = run_tool([str(HERE / "check.py"), output, "--platform", ck["platform"], "--json"])
+        proc = run_tool([str(HERE / "check.py"), output, "--platform", ck["platform"], "--json"] + child_args())
         try:
             check_result = json.loads(proc.stdout)
         except ValueError:
@@ -386,7 +386,8 @@ def main() -> int:
         # spec (or the check itself could not run): a failed delivery, reported as one.
         failed_rows = [r["check"] for r in (check_result or {}).get("checks", []) if r.get("status") == "FAIL"]
         die(f"rendered {output} but the {ck['platform']} check failed" + (f": {', '.join(failed_rows)}" if failed_rows else ""),
-            kind="verification", output=output, dry_run=STATE.dry_run, stages=stages_done, check=check_result)
+            kind="verification", output=output, dry_run=STATE.dry_run, stages=stages_done, check=check_result,
+            probe=probe(output, role="output"))
     info(f"rendered {output} via {' → '.join(stages_done)}")
     emit(output, stages=stages_done, check=check_result)
     return 0

package/scripts/report.py

@@ -18,7 +18,7 @@ import tempfile
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
-from _common import STATE, add_common, apply_common, die, emit, info, probe, read_text_or_die, run_tool
+from _common import STATE, add_common, apply_common, child_args, die, emit, info, probe, read_text_or_die, run_tool
 
 HERE = Path(__file__).resolve().parent
 
@@ -26,14 +26,14 @@ HERE = Path(__file__).resolve().parent
 def sheet_b64(path: str, tiles: str = "4x2", width: int = 1200) -> Optional[str]:
     with tempfile.TemporaryDirectory(prefix="ffskill_report_") as tmp:
         png = os.path.join(tmp, "sheet.png")
-        proc = run_tool([str(HERE / "look.py"), path, "--tiles", tiles, "--width", str(width), "-o", png])
+        proc = run_tool([str(HERE / "look.py"), path, "--tiles", tiles, "--width", str(width), "-o", png] + child_args())
         if proc.returncode != 0 or not os.path.exists(png):
             return None
         return base64.b64encode(Path(png).read_bytes()).decode("ascii")
 
 
 def loudness(path: str) -> Dict[str, Any]:
-    proc = run_tool([str(HERE / "loudness.py"), path, "--measure-only"])
+    proc = run_tool([str(HERE / "loudness.py"), path, "--measure-only"] + child_args())
     try:
         d = json.loads(proc.stdout)
         return {"lufs": round(float(d["input_i"]), 1), "tp": round(float(d["input_tp"]), 1), "lra": round(float(d["input_lra"]), 1)}
@@ -42,7 +42,7 @@ def loudness(path: str) -> Dict[str, Any]:
 
 
 def check(path: str, platform: str) -> Optional[Dict[str, Any]]:
-    proc = run_tool([str(HERE / "check.py"), path, "--platform", platform, "--json"])
+    proc = run_tool([str(HERE / "check.py"), path, "--platform", platform, "--json"] + child_args())
     try:
         doc = json.loads(proc.stdout)
     except ValueError:

package/scripts/silence.py

@@ -12,20 +12,23 @@ Examples:
   python3 silence.py talk.mp4 --edl keep.txt                  # also save the kept ranges (START-END per line, cut.py --segments format)
 """
 import argparse
+import os
 import re
 import sys
 from typing import List, Tuple
 
-from _common import STATE, video_args, add_common, apply_common, audio_codec_for, cfr_args, default_output, die, emit, ffmpeg_base, info, is_audio_output, print_json, probe, require_tool, run, x264_args, X264_PRESETS, measured_level_dbfs
+from _common import STATE, video_args, add_common, apply_common, audio_codec_for, cfr_args, default_output, die, emit, ffmpeg_base, info, is_audio_output, print_json, probe, require_tool, run, x264_args, X264_PRESETS, measured_level_dbfs, run_analysis, dry_run_input_pending
 
 SIL_RE = re.compile(r"silence_(start|end): ([0-9.]+)")
 
 
 def detect(path: str, threshold: float, min_silence: float) -> List[Tuple[float, float]]:
+    if dry_run_input_pending(path):
+        return []
     ffmpeg = require_tool("ffmpeg")
     cmd = [ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-vn", "-af",
            f"silencedetect=noise={threshold}dB:d={min_silence}", "-f", "null", "-"]
-    proc = run(cmd, quiet=True, check=False)
+    proc = run_analysis(cmd, check=False, record=True)
     if proc.returncode != 0:
         die(f"silencedetect failed:\n{proc.stderr.strip()[-800:]}", kind="ffmpeg")
     silences: List[Tuple[float, float]] = []
@@ -86,7 +89,7 @@ def main() -> int:
         "removed_seconds": round(removed, 3),
     }
     info(f"{len(silences)} silences, keeping {len(keeps)} ranges: {kept:.2f}s of {duration:.2f}s (removing {removed:.2f}s)")
-    if not silences and not STATE.dry_run:
+    if not silences and not (STATE.dry_run and not os.path.exists(args.input)):
         # Nothing under the threshold is a valid result, not a failure -- but an agent that only
         # sees "0 silences" tends to reach for raw ffmpeg next. Say what the floor actually is and
         # what threshold would bite, so the retry is a flag change, not a workaround.

package/scripts/stabilize.py

@@ -27,7 +27,7 @@ import sys
 import tempfile
 from pathlib import Path
 
-from _common import STATE, add_common, apply_common, aac_args, cfr_args, default_output, die, emit, escape_filter_path, ffmpeg_base, info, probe, require_tool, run, video_args, X264_PRESETS
+from _common import STATE, add_common, apply_common, aac_args, cfr_args, default_output, die, emit, escape_filter_path, ffmpeg_base, info, probe, require_tool, run, video_args, X264_PRESETS, run_analysis, dry_run_input_pending
 
 
 def main() -> int:
@@ -62,18 +62,20 @@ def main() -> int:
         trf = str(Path(tmp) / "transforms.trf")
         trf_arg = escape_filter_path(trf)
 
-        if not STATE.dry_run:
-            ffmpeg = require_tool("ffmpeg")
-            detect_vf = f"vidstabdetect=shakiness={args.shakiness}:result={trf_arg}"
-            if args.tripod:
-                # A frame number, not a boolean: frame 1 is the standard reference for "lock to
-                # this fixed frame" (mirrors vidstabtransform's own tripod=1 below).
-                detect_vf += ":tripod=1"
-            detect_cmd = [ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-y", "-i", args.input,
-                          "-vf", detect_vf, "-f", "null", "-"]
-            proc = run(detect_cmd, check=False)
+        ffmpeg = require_tool("ffmpeg")
+        detect_vf = f"vidstabdetect=shakiness={args.shakiness}:result={trf_arg}"
+        if args.tripod:
+            # A frame number, not a boolean: frame 1 is the standard reference for "lock to
+            # this fixed frame" (mirrors vidstabtransform's own tripod=1 below).
+            detect_vf += ":tripod=1"
+        detect_cmd = [ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-y", "-i", args.input,
+                      "-vf", detect_vf, "-f", "null", "-"]
+        # Pass 1 is a measurement into a temp file (the transforms), so it runs under --dry-run
+        # as well; only pass 2, the write, is skipped there.
+        if not dry_run_input_pending(args.input):
+            proc = run_analysis(detect_cmd, check=False, record=True)
             if proc.returncode != 0:
-                die(f"stabilization analysis (pass 1) failed:\n{proc.stderr.strip()[-1500:]}")
+                die(f"stabilization analysis (pass 1) failed:\n{proc.stderr.strip()[-1500:]}", kind="ffmpeg")
 
         crop_mode = {"keep": 0, "black": 1}[args.crop]
         transform_vf = f"vidstabtransform=input={trf_arg}:smoothing={args.smoothing}:crop={crop_mode}:zoom={args.zoom:g}:optzoom=1"