ffmpeg-skill 1.3.1 → 1.4.1

package/README.md

@@ -13,9 +13,13 @@
 
 <p align="center">
   <a href="https://github.com/kajisho5/ffmpeg-skill/actions/workflows/ci.yml"><img src="https://github.com/kajisho5/ffmpeg-skill/actions/workflows/ci.yml/badge.svg" alt="tests"></a>
+  <a href="https://github.com/kajisho5/ffmpeg-skill/actions/workflows/codeql.yml"><img src="https://github.com/kajisho5/ffmpeg-skill/actions/workflows/codeql.yml/badge.svg" alt="CodeQL"></a>
   <a href="https://www.npmjs.com/package/ffmpeg-skill"><img src="https://img.shields.io/npm/v/ffmpeg-skill" alt="npm"></a>
-  <img src="https://img.shields.io/badge/python-3.9%2B-blue" alt="Python 3.9+">
-  <img src="https://img.shields.io/badge/ffmpeg-5.0%2B-orange" alt="FFmpeg 5.0+">
+  <a href="https://www.npmjs.com/package/ffmpeg-skill"><img src="https://img.shields.io/npm/dm/ffmpeg-skill" alt="npm downloads"></a>
+  <a href="https://github.com/kajisho5/ffmpeg-skill/stargazers"><img src="https://img.shields.io/github/stars/kajisho5/ffmpeg-skill" alt="GitHub stars"></a>
+  <a href="https://github.com/kajisho5/ffmpeg-skill/commits/main"><img src="https://img.shields.io/github/last-commit/kajisho5/ffmpeg-skill" alt="last commit"></a>
+  <img src="https://img.shields.io/badge/python-3.9%20%7C%203.13-blue" alt="Python 3.9 and 3.13 tested">
+  <a href="#ffmpeg-compatibility"><img src="https://img.shields.io/badge/ffmpeg-5.1%20%7C%206.1%20%7C%207.1%20%7C%208%20%7C%209%20tested-orange" alt="FFmpeg 5.1, 6.1, 7.1, 8 and 9 tested in CI"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT"></a>
   <a href="https://github.com/sponsors/kajisho5"><img src="https://img.shields.io/badge/sponsor-%E2%9D%A4-ea4aaa?logo=githubsponsors" alt="Sponsor"></a>
 </p>
@@ -26,7 +30,7 @@ npx ffmpeg-skill
 
 ![before / after demo](assets/demo.gif)
 
-`ffmpeg-skill` is an [Agent Skill](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills) for Claude Code, Cursor, Codex and any agent that reads `SKILL.md`. It teaches the agent a fixed workflow (probe → edit losslessly where possible → check → verify) and ships **41 tools** that do the actual work with `ffmpeg` / `ffprobe`: cut, join, silence removal, fit to duration and aspect, captions and karaoke, overlays and motion graphics, HDR → SDR and LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, whole-edit project rendering, batch folders. Every tool is also an MCP tool, and the whole set is described by a machine-readable contract.
+`ffmpeg-skill` is an [Agent Skill](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills) for Claude Code, Cursor, Codex and any agent that reads `SKILL.md`. It teaches the agent a fixed workflow (probe → edit losslessly where possible → check → verify) and ships **42 tools** that do the actual work with `ffmpeg` / `ffprobe`: cut, join, silence removal, fit to duration and aspect, captions and karaoke, overlays and motion graphics, HDR → SDR and LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, whole-edit project rendering, batch folders. Every tool is also an MCP tool, and the whole set is described by a machine-readable contract.
 
 If `ffmpeg` and `python3` are on your PATH, it works: offline, on footage you would rather not upload.
 
@@ -139,8 +143,8 @@ These are the rules the skill file gives the agent and the code enforces. Togeth
 
 1. **Probe first.** No tool decides from the file name. `probe.py` measures duration, fps (with variable-frame-rate detection), resolution, rotation, bit depth, HDR format including Dolby Vision, colour tags and every audio stream before anything is cut.
 2. **Lossless when possible.** `cut.py`, `join.py` and `loudness.py` stream-copy what they do not need to touch. Re-encoding happens only when it must: frame-accurate cuts, filters, format changes, or a keyframe farther than the tolerance.
-3. **Plan before render.** Every tool takes `--dry-run` (print the ffmpeg command lines, write nothing), `--json` (structured result with a probe of the output), `--fast` (preview quality) and `--progress` (percent and ETA). A test runs every tool under `--dry-run` behind a fake ffmpeg and asserts that no ffmpeg call happened and no file appeared.
-4. **Machine-readable contract.** `contract --json` describes all 41 tools: input schema generated from the parser, output schema, role, required and conditional FFmpeg capabilities, dry-run support, the verification tools to run afterwards, whether a visual check is required, `mutates_input: false`. `provides` lists all 40 by a cross-repository Capability id (`ffmpeg-skill.cut`, `ffmpeg-skill.loudness`, ...) for [`kajisho5/AI-video-production-OS`](https://github.com/kajisho5/AI-video-production-OS)'s `CapabilityContract.provides` — see `docs/contract.md`.
+3. **Plan before render.** Every tool takes `--dry-run` (print the ffmpeg command lines, write nothing), `--json` (structured result with a probe of the output), `--fast` (preview quality), `--progress` (percent and ETA), `--timeout` (a hung ffmpeg is killed and reported, never waited on forever) and `--overwrite` (explicit consent before an existing output is replaced). A test runs every tool under `--dry-run` behind a fake ffmpeg and asserts that no ffmpeg call happened and no file appeared.
+4. **Machine-readable contract.** `contract --json` describes all 42 tools: input schema generated from the parser, output schema, role, required and conditional FFmpeg capabilities, dry-run support, the verification tools to run afterwards, whether a visual check is required, `mutates_input: false`. `provides` lists all 40 by a cross-repository Capability id (`ffmpeg-skill.cut`, `ffmpeg-skill.loudness`, ...) for [`kajisho5/AI-video-production-OS`](https://github.com/kajisho5/AI-video-production-OS)'s `CapabilityContract.provides` — see `docs/contract.md`.
 5. **Contract-derived MCP.** `mcp/server.py` builds its `tools/list` from the contract. Tool names, order and `inputSchema` cannot drift from the scripts; a test keeps the two byte-identical.
 6. **Capability detection.** `doctor` reads `ffmpeg -encoders / -filters / -bsfs` and reports which of the components the tools need are present on this build (libx264, libass, zscale, loudnorm, xfade, …), before a job fails inside ffmpeg.
 7. **Unknown is not missing.** When a listing cannot be read (a layout the parser does not know, ffmpeg exiting non-zero) the affected capabilities are `unknown`: never `missing`, never silently `available`. An installed filter is not reported absent; a failed detection is not a pass.
@@ -149,7 +153,7 @@ These are the rules the skill file gives the agent and the code enforces. Togeth
 
 ## Tools
 
-41 public tools, all Python 3.9 standard library, all with `--help`, `--dry-run`, `--json`, non-zero exit and a reason on stderr on failure.
+42 public tools, all Python 3.9 standard library, all with `--help`, `--dry-run`, `--json`, non-zero exit and a reason on stderr on failure.
 
 **Analysis and inspection**
 
@@ -184,6 +188,7 @@ These are the rules the skill file gives the agent and the code enforces. Togeth
 | `pad.py` | Add black/silent padding at the start and/or end of the timeline (`--start`, `--end`) — distinct from `fit.py --fit pad`'s per-frame letterbox bars |
 | `speedramp.py` | Step through different constant speeds across a clip via `--segment START-END:FACTOR` (repeatable) — distinct from `fit.py`'s single whole-clip speed factor |
 | `loop.py` | Repeat a clip `--times` N or to a target `--duration` — for background loops and filling a fixed slot length |
+| `broll.py` | Cut away to a B-roll clip over the A-roll for a window (`--insert B --at T --duration D`, repeatable) and come back; A's length and audio untouched by default |
 | `metadata.py` | Write container chapter markers from a `TIME TITLE` text file and title/artist/comment tags, every stream copied bit for bit |
 | `grid.py` | Composite `--cols`x`--rows` clips into one grid, each cell letterboxed and labelled with its filename by default (`--label none` to skip) |
 
@@ -273,7 +278,7 @@ npx ffmpeg-skill contract --json            # or: python3 scripts/_contract.py -
 npx ffmpeg-skill contract --json --static   # without environment detection
 ```
 
-The contract is generated from the code that runs, not maintained beside it. For each of the 41 tools (`ffmpeg-skill/<name>`) it states:
+The contract is generated from the code that runs, not maintained beside it. For each of the 42 tools (`ffmpeg-skill/<name>`) it states:
 
 | Field | Meaning |
 |---|---|
@@ -335,6 +340,7 @@ FFmpeg 8 shortened the flag column of `ffmpeg -filters`. A parser anchored on th
 | **F1 0.97** | `scenes.py`, 53 hard cuts between single takes, precision 0.95, recall 1.00 at the default threshold |
 | **exact to the sample** | `cut.py --accurate` on WAV, FLAC (44.1 kHz) and AAC → WAV; WAV stream copy within 2 ms; AAC output +21 ms of encoder priming, reported as `codec_frame` (0.9.1) |
 | **72 / 72** | agent runs of 24 prompts (12 English edits, 8 Japanese, 4 that must be declined), three repeats, graded by an independent model: routing, honest refusals and user's language 72/72, report format 71/72, visual check whenever the picture changed 24/24 (0.8.4) |
+| **36 / 36** | 1.4.0 re-run (2026-09-11, one pass per prompt, Sonnet agent, regex grader + manual review): 24-prompt set routing 20/20, honest refusals 5/5, visual check 8/8, user's language 8/9; exec set real execution 6/6, honest failure on bad inputs 5/5 with 0 false successes, audio-as-audio 3/3; trigger set 22/22. Details and the six findings in `evals/results/iteration-5.json` |
 | **6 / 6** | 0.9.1 audio evals (audio join, extraction, track selection, sample-accurate trim, typed dynamics; 2 in Japanese): routing, report format and audio-as-audio handling 6/6 |
 
 ```bash

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) and `--progress`. 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` 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`.
 
 ## Workflow (always follow this order)
 
@@ -41,7 +41,9 @@ Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>
    be a placeholder, not a computed preview — see `docs/contract.md`). Use
    them to confirm a plan before long encodes and to report exact facts.
    `--fast` gives a quick preview-quality render (x264 veryfast), `--progress`
-   prints percent and ETA on stderr for long encodes.
+   prints percent and ETA on stderr for long encodes. Never point `-o` at a file
+   you did not create in this job unless the user asked for it to be replaced;
+   pass `--overwrite` only then.
 4. **Chain operations in a sensible order.** Colour (HDR→SDR / LUT) → cut →
    join → silence → fit → caption/overlay → sync → audio → loudness → export.
    Do frame changes (fit/crop) before captions and overlays so text is sized
@@ -118,7 +120,7 @@ This skill cuts, joins, measures, syncs, exports and checks files — it execute
 
 The line in general: if the same input and the same explicit parameters always produce the same, verifiable output, it belongs here. If the "right" answer depends on taste, content understanding, or what looks or sounds good, it belongs to whichever skill or agent makes that judgement — this skill only ever executes parameters it's given, never infers them from what something looks or sounds like.
 
-If a request needs an FFmpeg feature none of the 41 scripts expose, say so and name the closest built-in option (`--dry-run` to show what would run, or a documented limitation) — never fall back to guessing a raw `ffmpeg`/`ffprobe` invocation or a hand-built filter graph outside `scripts/*.py`. A raw command bypasses every guarantee this skill makes (no shell, typed arguments, verification afterwards); it is exactly the failure mode this skill exists to prevent, so it is never the fallback when a script's flag doesn't cover something.
+If a request needs an FFmpeg feature none of the 42 scripts expose, say so and name the closest built-in option (`--dry-run` to show what would run, or a documented limitation) — never fall back to guessing a raw `ffmpeg`/`ffprobe` invocation or a hand-built filter graph outside `scripts/*.py`. A raw command bypasses every guarantee this skill makes (no shell, typed arguments, verification afterwards); it is exactly the failure mode this skill exists to prevent, so it is never the fallback when a script's flag doesn't cover something.
 
 ## Request → script
 
@@ -149,6 +151,7 @@ If a request needs an FFmpeg feature none of the 41 scripts expose, say so and n
 | "add some black at the start before the title card" | `pad.py clip.mp4 --start 1.5` |
 | "speed up here, slam into slow-mo there, then speed back up" (known segments) | `speedramp.py action.mp4 --segment 0-3:1.0 --segment 3-4:0.25 --segment 4-8:2.0` |
 | "loop this background clip to fill 30 seconds" | `loop.py bg_loop.mp4 --duration 30` |
+| "cut to the product shot from 0:12 to 0:16, keep my voice underneath", "B-roll over this bit" | `broll.py talk.mp4 --insert product.mp4 --at 12 --end 16` (repeat `--insert/--at` per cutaway; `--audio b|mix` to hear B) |
 | "add chapters at 0:00 Intro, 2:15 Setup, …", "chapter markers for YouTube" | `metadata.py episode.mp4 --chapters chapters.txt` (one `TIME TITLE` per line; streams are copied, nothing re-encodes) |
 | "set the title / artist / comment on the file" | `metadata.py episode.mp4 --title "Episode 12" --artist "Studio"` |
 | "put these videos in a 4x2 grid with the filename on each" | `grid.py t1.mp4 t2.mp4 t3.mp4 t4.mp4 t5.mp4 t6.mp4 t7.mp4 t8.mp4 --cols 4 --rows 2` |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ffmpeg-skill",
-  "version": "1.3.1",
-  "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 41 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.",
+  "version": "1.4.1",
+  "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",
     "video",

package/references/process-pitfalls.md

@@ -158,3 +158,25 @@ inputs (or `Unexpected input(s)` in the first log) before trusting a parameter,
 any step whose output decides an irreversible action as something to unit-test with fixed
 inputs, not something to confirm by reading its YAML. And watch the first real run's
 *effect* (tags, npm), which is how both incidents were actually noticed.
+
+### The release bump step required the literal `(nothing yet)` line under `## Unreleased`
+
+Found on the first run after #163 (2026-09-11). `release.yml`'s auto-bump located the CHANGELOG
+insertion point with `assert "## Unreleased\n\n(nothing yet)\n\n" in changelog`. #163 did the
+natural thing and wrote its notes under Unreleased, so the bump step failed on the assert
+before the push, the tag or the publish -- a clean no-op, but a red run and no release. The
+script now takes whatever sits under Unreleased into the new version's section and puts the
+placeholder back, so hand-written notes are welcome there. Lesson: an anchor that is also
+prose will be edited; anchor on the heading, not on the placeholder text.
+
+### The built-in GITHUB_TOKEN cannot push the release bump through a ruleset
+
+Found on the first release after the main ruleset went active (2026-09-11, run for #166):
+`git push origin HEAD:main` from release.yml was declined with GH013 ("Changes must be made
+through a pull request", "8 of 8 required status checks are expected"). GitHub Actions cannot
+be added as a ruleset bypass actor (the import rejects the actor, the UI does not list it), so
+the bump push now uses the `RELEASE_PUSH_TOKEN` secret -- a fine-grained PAT of a repository
+admin with Contents: read/write on this repo -- whose "Repository admin" bypass applies. A PAT
+push triggers workflows (GITHUB_TOKEN's do not), so the bump commit carries `[skip ci]`; the
+tag, Release and npm publish all happen in the originating run. Rotate the PAT before it
+expires or the next release fails at the same step, cleanly, before anything is published.

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`, `-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) 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`).
 
 ## Contents
 - probe.py — inspect
@@ -8,6 +8,8 @@ Every script prints the same information with `--help`; this file exists so the
 - fit.py — target duration and/or aspect, rotate/flip
 - crop.py — crop to an exact pixel rectangle
 - insert.py — still image to a timed silent clip, with Ken Burns zoom/pan
+- broll.py — cut away to a B-roll clip for a window and come back
+- metadata.py — chapter markers and title/artist/comment tags, streams copied
 - background.py — generate a solid-colour or gradient clip
 - reverse.py — reverse playback
 - stabilize.py — motion stabilisation (vidstab)
@@ -287,6 +289,21 @@ loop point (no crossfade at the seam) -- a clip that doesn't already loop
 cleanly will show a visible cut/pop at each repeat, which is a property of
 the source material this tool cannot fix.
 
+### broll.py — cut away to a B-roll clip and come back
+```
+broll.py A.mp4 --insert B.mp4 --at T [--duration D | --end T2] [--from T3]
+               [--insert ... --at ...] [--audio a|b|mix] [--pad-color black] [-o OUT]
+```
+A plays as it is; during each window B's picture is shown instead (scaled and
+padded to A's frame, A's fps), and A resumes at its own time when the window
+ends -- a cutaway, not a splice, so the output is exactly as long as A. One
+`--insert`/`--at` pair per cutaway (`--duration`, `--end`, `--from` are per
+cutaway too, or given once for all; defaults 4 s and 0); windows may not
+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.
+
 ### metadata.py — chapter markers and container tags, streams copied
 ```
 metadata.py INPUT [--chapters chapters.txt | --clear-chapters]

package/scripts/_common.py

@@ -62,8 +62,25 @@ ERROR_CODE = {
     "missing_tool": "DEPENDENCY_MISSING",
     "ffmpeg": "FFMPEG_EXECUTION_FAILED",
     "output": "OUTPUT_INVALID",
+    "timeout": "TIMEOUT",
 }
 
+# Wall-clock ceiling for one ffmpeg/ffprobe invocation, in seconds. A hung ffmpeg (a build
+# that deadlocks on a filter combination, a stalled network mount, an input that never ends)
+# used to hang the calling agent with it, with no error document and no way out short of
+# killing the process by hand. The ceiling is generous on purpose: it exists to turn a hang
+# into a reported failure, not to police slow encodes. --timeout and FFMPEG_SKILL_TIMEOUT
+# override it; 0 disables it.
+DEFAULT_TIMEOUT = 1800.0
+PROBE_TIMEOUT = 120.0
+
+
+def _env_timeout() -> float:
+    try:
+        return max(0.0, float(os.environ.get("FFMPEG_SKILL_TIMEOUT", DEFAULT_TIMEOUT)))
+    except ValueError:
+        return DEFAULT_TIMEOUT
+
 # None of the four kinds above are retryable in practice: an "input"/"missing_tool" failure is
 # always deterministic (the same bad path or absent binary fails identically every time), and a
 # "ffmpeg"/"output" failure -- while it COULD in principle be caused by a transient environment
@@ -182,8 +199,8 @@ class Context:
     it obvious what run()/emit() depend on and lets tests reset it with ``STATE.reset()``.
     """
 
-    __slots__ = ("dry_run", "json", "progress", "fast", "duration_hint", "commands")
-    _KEYS = ("dry_run", "json", "progress", "fast", "duration_hint", "commands")
+    __slots__ = ("dry_run", "json", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written")
+    _KEYS = ("dry_run", "json", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written")
 
     def __init__(self) -> None:
         self.reset()
@@ -195,6 +212,9 @@ class Context:
         self.fast = False         # x264 preset forced to veryfast
         self.duration_hint: Optional[float] = None  # expected output length, for the progress percent
         self.commands: List[str] = []               # every ffmpeg command line, for --json and --dry-run
+        self.timeout: float = _env_timeout()         # seconds per ffmpeg invocation, 0 = none
+        self.overwrite = False                       # --overwrite: an existing output may be replaced
+        self.written: set = set()                    # output paths this process has written itself
 
     # mapping-style access kept for backwards compatibility
     def __getitem__(self, key: str) -> Any:
@@ -221,6 +241,11 @@ def add_common(ap: "argparse.ArgumentParser") -> None:
     g.add_argument("--json", action="store_true", help="print a JSON result (output, probe, commands) on stdout instead of the path")
     g.add_argument("--progress", action="store_true", help="show percent / ETA on stderr while ffmpeg encodes")
     g.add_argument("--fast", action="store_true", help="preview quality: x264 preset veryfast (overrides --preset) for quick iterations")
+    if "--timeout" not in ap._option_string_actions:  # verify.py defines its own per-step --timeout; apply_common reads either
+        g.add_argument("--timeout", type=float, default=None, metavar="SECONDS",
+                       help=f"kill any single ffmpeg run that exceeds this many seconds and report kind=timeout (default {DEFAULT_TIMEOUT:.0f}, or FFMPEG_SKILL_TIMEOUT; 0 = no limit)")
+    g.add_argument("--overwrite", action="store_true",
+                   help="allow replacing an output file that already exists (without it a warning is printed today; from 2.0 an existing output is refused, and FFMPEG_SKILL_NO_OVERWRITE=1 opts into that now)")
 
 
 def apply_common(args: "argparse.Namespace") -> None:
@@ -228,6 +253,9 @@ def apply_common(args: "argparse.Namespace") -> None:
     STATE.json = bool(getattr(args, "json", False))
     STATE.progress = bool(getattr(args, "progress", False))
     STATE.fast = bool(getattr(args, "fast", False))
+    STATE.overwrite = bool(getattr(args, "overwrite", False))
+    if getattr(args, "timeout", None) is not None:
+        STATE.timeout = max(0.0, float(args.timeout))
     if STATE.fast and getattr(args, "preset", None) in X264_PRESETS:
         args.preset = "veryfast"
 
@@ -312,6 +340,46 @@ def _check_no_overwrite_input(cmd: Sequence[str]) -> None:
                 continue
 
 
+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
+    a run never blocks on a y/N prompt) would replace it without a word. Until 2.0 this only
+    warns, per docs/contract.md's deprecation policy; FFMPEG_SKILL_NO_OVERWRITE=1 opts into the
+    2.0 behaviour (refuse) today, and --overwrite is the explicit consent either way. Paths this
+    process wrote itself (a two-pass tool, a copy-then-re-encode fallback) are never in question."""
+    output = cmd[-1]
+    if STATE.overwrite or output in ("-",) or output.startswith("pipe:") or output.startswith("-"):
+        return
+    try:
+        exists = os.path.isfile(output)
+        real = os.path.realpath(output)
+    except OSError:
+        return
+    if not exists or real in STATE.written:
+        return
+    if os.environ.get("FFMPEG_SKILL_NO_OVERWRITE", "") not in ("", "0"):
+        die(f"refusing to overwrite existing output {output!r}: pass --overwrite to replace it, or choose another -o path", kind="input")
+    info(f"warning: {output} already exists and will be overwritten (pass --overwrite to confirm; "
+         f"from 2.0 an existing output is refused without it, FFMPEG_SKILL_NO_OVERWRITE=1 enables that now)")
+
+
+def _remember_output(cmd: Sequence[str]) -> None:
+    output = cmd[-1]
+    if output == "-" or output.startswith("pipe:") or output.startswith("-"):
+        return
+    try:
+        STATE.written.add(os.path.realpath(output))
+    except OSError:
+        pass
+
+
+def _timed_out(cmd: Sequence[str], seconds: float) -> "None":
+    _cleanup_partial_output(cmd)
+    die(f"{os.path.basename(cmd[0])} exceeded the {seconds:.0f} s time limit and was killed; nothing was written. "
+        f"Raise --timeout (or FFMPEG_SKILL_TIMEOUT) if the job is genuinely that long, or check the input for a stall",
+        code=124, kind="timeout")
+
+
 def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subprocess.CompletedProcess:
     """Run a command, echoing it to stderr unless quiet. Exits on failure when check=True.
 
@@ -322,6 +390,7 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subpr
     is_ffmpeg = _is_ffmpeg(cmd)
     if is_ffmpeg:
         _check_no_overwrite_input(cmd)
+        _check_existing_output(cmd)
         STATE.commands.append(_cmdline(cmd))
     if not quiet:
         info(("[dry-run] $ " if STATE.dry_run and is_ffmpeg else "$ ") + _cmdline(cmd))
@@ -346,9 +415,23 @@ def run_keeping_subtitles(cmd: List[str], output: str) -> bool:
     return True
 
 
+def _limit_for(cmd: Sequence[str]) -> Optional[float]:
+    """The wall-clock ceiling for this command: ffprobe (and other read-only probes) get a fixed
+    short one, ffmpeg the configured one; None means unlimited."""
+    if not _is_ffmpeg(cmd):
+        return PROBE_TIMEOUT if STATE.timeout else None
+    return STATE.timeout or None
+
+
 def _run_captured(cmd: List[str], check: bool) -> subprocess.CompletedProcess:
     """Plain run with stdout/stderr captured."""
-    proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    limit = _limit_for(cmd)
+    try:
+        proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=limit)
+    except subprocess.TimeoutExpired:
+        _timed_out(cmd, limit or 0)
+    if proc.returncode == 0 and _is_ffmpeg(cmd):
+        _remember_output(cmd)
     if proc.returncode != 0:
         # Cleanup happens for every failed ffmpeg invocation, not just the check=True/_fail()
         # path: a handful of scripts (cut.py, loudness.py, silence.py, sync.py) call run() with
@@ -377,10 +460,17 @@ def _run_with_progress(cmd: List[str], check: bool) -> subprocess.CompletedProce
     total = STATE.duration_hint or 0.0
     full = cmd[:1] + ["-progress", "pipe:1", "-nostats"] + cmd[1:]
     t0 = time.time()
+    limit = _limit_for(cmd)
     proc = subprocess.Popen(full, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
     last = ""
     assert proc.stdout is not None
     for line in proc.stdout:
+        if limit and time.time() - t0 > limit:
+            proc.kill()
+            proc.communicate()
+            if last:
+                sys.stderr.write("\r" + " " * len(last) + "\r")
+            _timed_out(cmd, limit)
         if line.startswith("out_time_us=") or line.startswith("out_time_ms="):
             try:
                 done = int(line.split("=")[1]) / 1_000_000
@@ -391,9 +481,16 @@ def _run_with_progress(cmd: List[str], check: bool) -> subprocess.CompletedProce
                 sys.stderr.write(msg)
                 sys.stderr.flush()
                 last = msg
-    _, err = proc.communicate()
+    try:
+        _, err = proc.communicate(timeout=(max(5.0, limit - (time.time() - t0)) if limit else None))
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        proc.communicate()
+        _timed_out(cmd, limit or 0)
     if last:
         sys.stderr.write("\r" + " " * len(last) + "\r")
+    if proc.returncode == 0:
+        _remember_output(cmd)
     if proc.returncode != 0:
         _cleanup_partial_output(cmd)
         if check:

package/scripts/_contract.py

@@ -113,6 +113,9 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
     "speedramp": dict(role="execution", inputs=["video asset"], outputs=["video artifact with a stepped speed ramp applied across segments"],
                       required=FF + [X264, AAC], optional=[HDR_X265],
                       video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
+    "broll": dict(role="execution", inputs=["A-roll video asset", "one or more B-roll video assets (--insert)"], outputs=["video artifact of exactly the A-roll's length with the B-roll shown during each cutaway window"],
+                  required=FF + [X264, AAC, "filter:overlay", "filter:amix"], optional=[HDR_X265],
+                  video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "metadata": dict(role="execution", inputs=["video or audio asset", "chapters text file (--chapters)"], outputs=["the same streams, stream-copied, with chapter markers and/or title/artist/comment tags written"],
                      required=FF, optional=[],
                      video_required=False, audio_only=True, visual=False, verify=["probe"], produces_artifact=True, idempotency="bit_exact", deterministic=True),
@@ -243,6 +246,7 @@ REENCODE_META: Dict[str, Dict[str, str]] = {
     "freeze":   dict(video="always", audio="always", note="the tpad/concat filter graph always forces a re-encode of the video stream; audio is re-encoded to AAC when present"),
     "pad":      dict(video="always", audio="always", note="the tpad filter always forces a re-encode of the video stream; audio is re-encoded to AAC when present"),
     "speedramp": dict(video="always", audio="always", note="setpts/atempo per segment always forces a re-encode of both streams"),
+    "broll":    dict(video="always", audio="conditional", note="the overlay graph always re-encodes the video stream; A's audio is stream-copied under --audio a and re-encoded to AAC under --audio b/mix"),
     "metadata": dict(video="never", audio="never", note="-c copy on every stream; only the container's chapters and tags change"),
     "loop":     dict(video="always", audio="always", note="-stream_loop always re-encodes both streams; the audio codec is always AAC when present"),
     "insert":    dict(video="always", audio="never", note="always encodes a fresh silent clip from the still image; there is no audio stream to touch"),
@@ -325,7 +329,7 @@ def input_schema(parser: argparse.ArgumentParser) -> Dict[str, Any]:
     props: Dict[str, Any] = {}
     required: List[str] = []
     positional: List[str] = []
-    common = {"dry_run", "json", "progress", "fast"}
+    common = {"dry_run", "json", "progress", "fast", "timeout", "overwrite"}
     for action in parser._actions:
         if isinstance(action, argparse._HelpAction):
             continue
@@ -1033,7 +1037,7 @@ def build(detect: bool = True) -> Dict[str, Any]:
         "json_output": {
             "success": {"status": "completed", "exit_code": 0, "stdout": "one JSON document (output_schema)"},
             "failure": {"status": "failed", "exit_code": "non-zero (127 when ffmpeg/ffprobe is missing)", "stdout": "{\"status\": \"failed\", \"exit_code\": N, \"error\": {\"kind\": ..., \"message\": ...}, \"commands\": [...]} when --json was given", "stderr": "human-readable message"},
-            "error_kinds": {"input": "missing or unsuitable input, bad arguments", "ffmpeg": "ffmpeg/ffprobe returned an error (message carries the last stderr lines)", "output": "ffmpeg exited 0 but the artifact is missing, empty or unreadable (an empty file is removed)", "missing_tool": "ffmpeg or ffprobe not on PATH"},
+            "error_kinds": {"input": "missing or unsuitable input, bad arguments", "ffmpeg": "ffmpeg/ffprobe returned an error (message carries the last stderr lines)", "output": "ffmpeg exited 0 but the artifact is missing, empty or unreadable (an empty file is removed)", "missing_tool": "ffmpeg or ffprobe not on PATH", "timeout": "one ffmpeg/ffprobe run exceeded --timeout (default 1800 s, FFMPEG_SKILL_TIMEOUT) and was killed; partial output removed; exit 124"},
             "success_criterion": "exit 0 AND the output exists AND is non-empty AND ffprobe reads a stream from it; only then is status completed printed and the output probe attached",
         },
         "capabilities": caps,

package/scripts/audio.py

@@ -196,18 +196,29 @@ def main() -> int:
         post.append(f"afade=t=in:st=0:d={args.fade_in:g}")
     if args.fade_out and dur:
         post.append(f"afade=t=out:st={max(0.0, dur - args.fade_out):.3f}:d={args.fade_out:g}")
-    if args.replace and dur:
+    # The audio track is conformed to the source duration whenever it is known: padded with
+    # silence if the graph came out short, trimmed if long. A mixed track can come out a few
+    # hundredths short (amix's dropout_transition, a looped bed's atrim boundary), and with
+    # -shortest below that used to shorten the *video* to match: 12.00 s in, 11.925 s out, four
+    # frames of a stream-copied picture gone (#164). Padding the audio, not cutting the picture,
+    # is the only correct answer for a tool whose contract says the video is never touched.
+    keep_video = has_video and not audio_out
+    if dur and (args.replace or args.music or keep_video):
         post.append(f"apad,atrim=0:{dur:.3f}")
     if post:
         graph.append(f"[{last}]{','.join(post)}[out]")
         last = "out"
 
     cmd = ffmpeg_base() + inputs + ["-filter_complex", ";".join(graph), "-map", f"[{last}]"]
-    if has_video and not audio_out:
+    if keep_video:
         cmd += ["-map", "0:v:0", "-c:v", "copy"]
     elif has_video:
         cmd += ["-vn"]  # audio extension: the picture is dropped, not copied into a container that cannot hold it
-    cmd += audio_codec_for(output, args.bitrate) + ["-shortest", output]
+    cmd += audio_codec_for(output, args.bitrate)
+    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)
     r = probe(output, role="output")
     a = r["audio"]

package/scripts/broll.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+"""Cut away to clip B over clip A for a while, then come back -- A's timeline unchanged.
+
+"Cut to the product shot from 0:12 to 0:16, keep my voice underneath" is the
+classic B-roll instruction. A plays as it is; during each window B's picture is
+shown instead (scaled/padded to A's frame like join.py normalises), and A resumes
+at its own time when the window ends. This is a cutaway, not a splice: the output
+is exactly as long as A, and A is re-encoded once.
+
+--insert/--at come in pairs, once per cutaway; --duration (or --end) and --from
+(where in B to start) are per cutaway too and default to 4 s and 0. --audio says
+what plays under a cutaway: `a` (default, A's own audio untouched, stream-copied),
+`b` (B's audio replaces A's inside the window), or `mix` (both).
+
+Examples:
+  python3 broll.py talk.mp4 --insert product.mp4 --at 12 --duration 4
+  python3 broll.py talk.mp4 --insert shot1.mp4 --at 12 --end 16 --insert shot2.mp4 --at 40 --from 2
+  python3 broll.py talk.mp4 --insert demo.mp4 --at 30 --duration 8 --audio mix
+"""
+import argparse
+import sys
+from typing import Any, Dict, List
+
+from _common import STATE, add_common, aac_args, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, video_args
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("input", help="the A-roll (its timeline and length are kept)")
+    ap.add_argument("-o", "--output", help="output file (default: <name>_broll.<ext>)")
+    ap.add_argument("--insert", action="append", required=True, metavar="B", help="B-roll clip (repeat with --at for several cutaways)")
+    ap.add_argument("--at", action="append", required=True, metavar="TIME", help="where in A the cutaway starts (seconds or mm:ss); one per --insert")
+    ap.add_argument("--duration", action="append", metavar="T", help="cutaway length (default 4); one per --insert, or omit")
+    ap.add_argument("--end", action="append", metavar="TIME", help="where in A the cutaway ends, instead of --duration")
+    ap.add_argument("--from", dest="from_", action="append", metavar="TIME", help="where in B to start from (default 0); one per --insert, or omit")
+    ap.add_argument("--audio", choices=["a", "b", "mix"], default="a", help="under a cutaway: A's audio (default), B's audio, or both mixed")
+    ap.add_argument("--pad-color", default="black", help="pad colour when B's aspect differs from A's (default black)")
+    ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+    ap.add_argument("--preset", default="medium", help="x264 preset")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+
+    n = len(args.insert)
+    if len(args.at) != n:
+        die(f"{n} --insert but {len(args.at)} --at: give one --at per --insert")
+    for name, values in (("--duration", args.duration), ("--end", args.end), ("--from", args.from_)):
+        if values and len(values) not in (1, n):
+            die(f"{name} given {len(values)} times for {n} cutaways: give it once per --insert, or once for all, or not at all")
+    if args.duration and args.end:
+        die("--duration and --end exclude each other")
+
+    meta_a = probe(args.input)
+    if not meta_a.get("video"):
+        die("A-roll has no video stream")
+    dur_a = meta_a.get("duration") or 0.0
+    w, h = meta_a["video"]["width"], meta_a["video"]["height"]
+    fps = meta_a["video"].get("fps") or 30.0
+    has_audio_a = bool(meta_a.get("audio"))
+
+    def per(values: List[str], i: int, default: str) -> str:
+        if not values:
+            return default
+        return values[i] if len(values) == n else values[0]
+
+    cutaways: List[Dict[str, Any]] = []
+    for i, path in enumerate(args.insert):
+        meta_b = probe(path)
+        if not meta_b.get("video"):
+            die(f"{path} has no video stream")
+        at = parse_time(args.at[i], fps)
+        start_b = parse_time(per(args.from_, i, "0"), fps)
+        if args.end:
+            end = parse_time(per(args.end, i, "0"), fps)
+            length = end - at
+        else:
+            length = parse_time(per(args.duration, i, "4"), fps)
+        if length <= 0:
+            die(f"cutaway {i + 1}: length must be > 0 (at {at:g}s, got {length:g}s)")
+        if dur_a and at >= dur_a:
+            die(f"cutaway {i + 1}: --at {at:g}s is past the end of the A-roll ({dur_a:.3f}s)")
+        if dur_a and at + length > dur_a + 0.01:
+            die(f"cutaway {i + 1}: {at:g}s + {length:g}s runs past the end of the A-roll ({dur_a:.3f}s)")
+        dur_b = meta_b.get("duration") or 0.0
+        if dur_b and start_b + length > dur_b + 0.01 and not STATE["dry_run"]:
+            die(f"cutaway {i + 1}: {path} has only {dur_b - start_b:.3f}s from {start_b:g}s, {length:g}s asked for")
+        if cutaways and at < cutaways[-1]["at"] + cutaways[-1]["length"]:
+            die(f"cutaway {i + 1} at {at:g}s overlaps the previous one (ends {cutaways[-1]['at'] + cutaways[-1]['length']:g}s)")
+        cutaways.append({"path": path, "at": at, "length": length, "from": start_b, "has_audio": bool(meta_b.get("audio"))})
+    if args.audio != "a" and not all(c["has_audio"] for c in cutaways):
+        die("--audio b/mix needs audio on every B-roll clip")
+
+    output = args.output or default_output(args.input, "broll")
+    cmd = ffmpeg_base() + ["-i", args.input]
+    for c in cutaways:
+        cmd += ["-i", c["path"]]
+
+    # Picture: each B window is trimmed, normalised to A's frame and fps, shifted to start at its
+    # --at time, and overlaid on A; before its first frame and after its last (eof_action=pass)
+    # A shows through unchanged, so A's timeline is never touched.
+    parts: List[str] = []
+    cur = "[0:v]"
+    for i, c in enumerate(cutaways):
+        geo = f"scale={w}:{h}:force_original_aspect_ratio=decrease,pad={w}:{h}:(ow-iw)/2:(oh-ih)/2:color={args.pad_color}"
+        parts.append(f"[{i + 1}:v]trim=start={c['from']:.3f}:duration={c['length']:.3f},setpts=PTS-STARTPTS+{c['at']:.3f}/TB,"
+                     f"{geo},setsar=1,fps={fps:g},format=yuv420p[b{i}]")
+        parts.append(f"{cur}[b{i}]overlay=0:0:eof_action=pass:enable='between(t,{c['at']:.3f},{c['at'] + c['length']:.3f})'[v{i}]")
+        cur = f"[v{i}]"
+    vout = cur
+
+    # Audio: `a` stream-copies A's track; `b`/`mix` build A (muted inside the windows for `b`)
+    # plus each B window delayed to its --at time.
+    aout = None
+    if has_audio_a or args.audio != "a":
+        if args.audio == "a":
+            aout = "0:a:0" if has_audio_a else None
+        else:
+            layers: List[str] = []
+            if has_audio_a:
+                gate = "".join(f",volume=0:enable='between(t,{c['at']:.3f},{c['at'] + c['length']:.3f})'" for c in cutaways) if args.audio == "b" else ""
+                parts.append(f"[0:a:0]aformat=sample_rates=48000:channel_layouts=stereo{gate}[a0]")
+                layers.append("[a0]")
+            for i, c in enumerate(cutaways):
+                parts.append(f"[{i + 1}:a:0]atrim=start={c['from']:.3f}:duration={c['length']:.3f},asetpts=PTS-STARTPTS,"
+                             f"aformat=sample_rates=48000:channel_layouts=stereo,adelay={int(c['at'] * 1000)}|{int(c['at'] * 1000)}[ab{i}]")
+                layers.append(f"[ab{i}]")
+            parts.append(f"{''.join(layers)}amix=inputs={len(layers)}:normalize=0:dropout_transition=0,atrim=duration={dur_a:.3f}[aout]")
+            aout = "[aout]"
+
+    cmd += ["-filter_complex", ";".join(parts), "-map", vout]
+    if aout:
+        cmd += ["-map", aout]
+    cmd += video_args(meta_a, args.crf, args.preset) + cfr_args(meta_a, None)
+    if aout == "0:a:0":
+        cmd += ["-c:a", "copy"]
+    elif aout:
+        cmd += aac_args()
+    else:
+        cmd += ["-an"]
+    cmd += ["-t", f"{dur_a:.3f}", output]
+    run(cmd)
+
+    result = probe(output, role="output")
+    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 {result.get('duration'):.3f}s 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)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())