Skip to content

Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.

Add broll.py: cut away to a B-roll clip for a window and come back, A's timeline untouched (#158)

Shogo Kajiyamab7bd74ca0c8a
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 86d2ac0..f585e78 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "ffmpeg-skill",
- "description": "Local FFmpeg video/audio editing for coding agents: 41 tools with a machine-readable contract, capability detection, probe-first / verify-last workflow. No cloud, no API keys.",
+ "description": "Local FFmpeg video/audio editing for coding agents: 42 tools with a machine-readable contract, capability detection, probe-first / verify-last workflow. No cloud, no API keys.",
"version": "1.3.1",
"author": {
"name": "kajisho5",
diff --git a/README.md b/README.md
index 97c3c5c..6c68fc6 100644
--- a/README.md
+++ b/README.md
@@ -26,7 +26,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.
@@ -140,7 +140,7 @@ 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`.
+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 +149,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 +184,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 +274,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 |
|---|---|
diff --git a/SKILL.md b/SKILL.md
index 8fba2e3..43a4376 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -118,7 +118,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 +149,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` |
diff --git a/docs/contract.md b/docs/contract.md
index 0bfe797..e70bd48 100644
--- a/docs/contract.md
+++ b/docs/contract.md
@@ -173,7 +173,7 @@ gives you:
## `provides`
-`provides` lists these 41 tools by a cross-repository Capability id, for
+`provides` lists these 42 tools by a cross-repository Capability id, for
`kajisho5/AI-video-production-OS`'s `CapabilityContract.provides`
(`docs/SPEC.md` there), matching the ids already assigned to this Skill in
that project's own `docs/CAPABILITY_MATRIX.md` section 9 ("ffmpeg-skill's
diff --git a/package.json b/package.json
index c8e52e0..160f5fb 100644
--- a/package.json
+++ b/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.",
+ "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",
diff --git a/references/scripts.md b/references/scripts.md
index 442ec71..910bf58 100644
--- a/references/scripts.md
+++ b/references/scripts.md
@@ -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]
diff --git a/scripts/_contract.py b/scripts/_contract.py
index 79008d3..5347e38 100644
--- a/scripts/_contract.py
+++ b/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"),
diff --git a/scripts/broll.py b/scripts/broll.py
new file mode 100755
index 0000000..db374ac
--- /dev/null
+++ b/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())
diff --git a/tests/fixtures/mcp_tools.json b/tests/fixtures/mcp_tools.json
index e1620ae..065c9e9 100644
--- a/tests/fixtures/mcp_tools.json
+++ b/tests/fixtures/mcp_tools.json
@@ -85,6 +85,28 @@
],
"required": []
},
+ {
+ "name": "broll",
+ "properties": [
+ "argv",
+ "at",
+ "audio",
+ "crf",
+ "dry_run",
+ "duration",
+ "end",
+ "fast",
+ "from_",
+ "input",
+ "insert",
+ "json",
+ "output",
+ "pad_color",
+ "preset",
+ "progress"
+ ],
+ "required": []
+ },
{
"name": "caption",
"properties": [
diff --git a/tests/test_all.py b/tests/test_all.py
index a9886cf..19749d1 100644
--- a/tests/test_all.py
+++ b/tests/test_all.py
@@ -215,6 +215,46 @@ class FFmpegSkillTests(unittest.TestCase):
self.assertClose(m["duration"], 6.0, 0.15)
self.assertEqual((m["video"]["width"], m["video"]["height"]), (540, 960))
+ def test_broll_cutaway_shows_b_in_the_window_and_keeps_a_elsewhere(self):
+ """#141: broll.py shows B's picture over A for a window and returns to A at A's own time;
+ the output is exactly A's length. Checked frame by frame: inside the window a frame
+ matches B (at --from + offset) and not A; outside it matches A. --audio a stream-copies
+ A's audio; two cutaways in one call; overlapping or past-the-end windows are refused."""
+ def frame_luma(path, t):
+ proc = sh("ffmpeg", "-hide_banner", "-loglevel", "error", "-ss", str(t), "-i", path, "-frames:v", "1",
+ "-vf", "signalstats,metadata=print:file=-", "-f", "null", "-")
+ return float(re.search(r"lavfi\.signalstats\.YAVG=([0-9.]+)", proc.stdout).group(1))
+ b = OUT / "broll_b.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "smptebars=size=960x540:rate=25:d=8",
+ "-f", "lavfi", "-i", "sine=frequency=880:sample_rate=48000:duration=8", "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", b)
+ out = OUT / "broll_out.mp4"
+ data = json.loads(script("broll.py", self.src, "--insert", b, "--at", "4", "--end", "7", "--from", "1", "--fast", "--json", "-o", out).stdout)
+ self.assertEqual(data["cutaways"], [{"insert": str(b), "at": 4.0, "end": 7.0, "from": 1.0}])
+ m = probe(str(out))
+ self.assertClose(m["duration"], probe(str(self.src))["duration"], 0.1)
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (1280, 720))
+ self.assertEqual(m["audio"]["codec"], probe(str(self.src))["audio"]["codec"], "--audio a stream-copies A's audio")
+ inside_out, inside_b, inside_a = frame_luma(str(out), 5.5), frame_luma(str(b), 2.5), frame_luma(str(self.src), 5.5)
+ self.assertLess(abs(inside_out - inside_b), 6, f"inside the window the frame must be B's: out {inside_out} b {inside_b} a {inside_a}")
+ self.assertGreater(abs(inside_out - inside_a), 6, "inside the window the frame must not be A's")
+ for t in (2.0, 9.0):
+ self.assertLess(abs(frame_luma(str(out), t) - frame_luma(str(self.src), t)), 3, f"outside the window ({t}s) A must show unchanged")
+ # two cutaways, B's audio mixed in, per-cutaway durations
+ out2 = OUT / "broll_out2.mp4"
+ script("broll.py", self.src, "--insert", b, "--at", "1", "--duration", "2", "--insert", b, "--at", "8", "--duration", "3", "--audio", "mix", "--fast", "-o", out2)
+ m2 = probe(str(out2))
+ self.assertClose(m2["duration"], 12.0, 0.1)
+ self.assertEqual(m2["audio"]["codec"], "aac")
+ self.assertLess(abs(frame_luma(str(out2), 9.5) - frame_luma(str(b), 1.5)), 6)
+ # refusals: overlap, past the end, B too short, missing --at
+ script("broll.py", self.src, "--insert", b, "--at", "1", "--duration", "3", "--insert", b, "--at", "2", "-o", OUT / "broll_bad1.mp4", expect_fail=True)
+ script("broll.py", self.src, "--insert", b, "--at", "10", "--duration", "5", "-o", OUT / "broll_bad2.mp4", expect_fail=True)
+ script("broll.py", self.src, "--insert", b, "--at", "1", "--duration", "5", "--from", "5", "-o", OUT / "broll_bad3.mp4", expect_fail=True)
+ script("broll.py", self.src, "--insert", b, "--insert", b, "--at", "1", "-o", OUT / "broll_bad4.mp4", expect_fail=True)
+ dry = OUT / "broll_dry.mp4"
+ script("broll.py", self.src, "--insert", b, "--at", "4", "--dry-run", "-o", dry)
+ self.assertFalse(dry.exists())
+
def test_metadata_writes_chapters_and_tags_with_streams_copied(self):
"""#140: metadata.py writes container chapter markers from a `TIME TITLE` file and the
common tags, with every stream copied bit for bit; probe reports both back. Chapters on a
diff --git a/tests/test_contract.py b/tests/test_contract.py
index e695493..5ec3f53 100644
--- a/tests/test_contract.py
+++ b/tests/test_contract.py
@@ -540,7 +540,7 @@ class ContractTests(unittest.TestCase):
def test_visual_verification_metadata(self):
picture = {"fit", "crop", "sphere", "insert", "background", "reverse", "stabilize", "sequence", "caption", "overlay", "graphics", "color", "join", "multicam", "render", "proxy",
- "deinterlace", "denoise", "redact", "waveform", "straighten", "freeze", "pad", "speedramp", "loop", "grid"}
+ "deinterlace", "denoise", "redact", "waveform", "straighten", "freeze", "pad", "speedramp", "loop", "grid", "broll"}
# join and waveform are the picture tools that also accept audio-only inputs (audio
# concat; audio-track visualization); look applies to their video output only, which
# SKILL.md states next to "Look: not needed"