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.
Python agent-skillsai-agentsaudio-processingcaptionsclaude-codecodexcoding-agentcursorffmpegloudness-normalizationmcpmcp-servermodel-context-protocolpythonsubtitlestranscodingvideovideo-editingvideo-processingwhisper
#!/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, draws_chroma, drawn_chain, emit, ffmpeg_base, info, time_arg, label_chain, matrix_chain, probe, run, validate_color, video_args, X264_PRESETS, fmt_secs
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.set_defaults(crf=18) # --quality's default (the --crf alias was removed in 2.0)
ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
add_common(ap)
args = ap.parse_args()
apply_common(args)
validate_color(args.pad_color, "--pad-color")
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"]
# the cutaway is scaled onto the frame ffmpeg has already rotated, not the stored one
if meta_a["video"].get("rotation") in (90, -90, 270, -270):
w, h = h, w
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 = time_arg(args.at[i], "--at", fps)
start_b = time_arg(per(args.from_, i, "0"), "--from", fps)
if args.end:
end = time_arg(per(args.end, i, "0"), "--end", fps)
length = end - at
else:
length = time_arg(per(args.duration, i, "4"), "--duration", 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")), "meta": meta_b})
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]"
# every clip is converted by its own colour tags to the BT.709 the output is tagged with; beside
# a converted clip (or under a --pad-color with chroma) an untagged one gets its BT.709 label,
# tags only, so 7.1+'s overlay and pad have nothing to convert or misread
convert = [matrix_chain(m, meta_a) for m in [meta_a] + [c["meta"] for c in cutaways]]
if any(convert) or draws_chroma([args.pad_color], meta_a):
convert = [cv or label_chain(m, meta_a) for cv, m in zip(convert, [meta_a] + [c["meta"] for c in cutaways])]
if convert[0]:
parts.append(f"[0:v]{convert[0]}null[a709]")
cur = "[a709]"
pad = f"pad={w}:{h}:(ow-iw)/2:(oh-ih)/2:color="
for i, c in enumerate(cutaways):
geo = (f"scale={w}:{h}:force_original_aspect_ratio=decrease,"
+ drawn_chain(pad + args.pad_color, c["meta"], [args.pad_color], pad + "black", line_meta=meta_a,
tag=f"pad{i}", labelled=True))
parts.append(f"[{i + 1}:v]trim=start={c['from']:.3f}:duration={c['length']:.3f},setpts=PTS-STARTPTS+{c['at']:.3f}/TB,"
f"{convert[i + 1]}{geo},setsar=1,fps={fps:g},format={'yuv420p10le' if (meta_a.get('video') or {}).get('bt2020_or_hdr') else '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, convert_matrix=False) + 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 {fmt_secs(result.get('duration'))} 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,
dropped_non_av_streams=bool(meta_a.get("subtitle_streams") or meta_a.get("data_streams")))
return 0
if __name__ == "__main__":
sys.exit(main())