"""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 math
import sys
from typing import Any, Dict, List
from _common.decision import (av_trim, conform_output_t, conform_to_length, frame_durations, frame_rate, frame_window,
grid_at_or_after, silence_filter, stream_starts, window_expr, windowed_overlay_x)
from _common import STATE, add_common, aac_args, apply_common, cfr_args, cfr_at_input, as_limited, default_output, die, draws_chroma, drawn_chain, emit, ffmpeg_base, info, time_arg, label_chain, matrix_chain, overlay_format, range_chain, probe, run, validate_color, video_args, X264_PRESETS, fmt_secs
from _common.emit import note, record_fallback
from _common.probe import display_size, is_still_input, square_pixels, square_pixels_note, still_loop_args
from _common.emit import input_length
MIX_RATE = 48000
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)
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 = input_length(meta_a)
w, h = display_size(meta_a["video"])
a_chain = square_pixels(meta_a["video"])
if a_chain:
note(square_pixels_note(meta_a["video"], "the A-roll"))
if (w % 2 or h % 2) and w and h:
ew, eh = max(2, w - w % 2), max(2, h - h % 2)
record_fallback(f"the A-roll is {w}x{h}, which 4:2:0 cannot hold: scaled to {ew}x{eh}",
"odd_dimensions_scaled_even", output=args.output or default_output(args.input, "broll"), scale=f"scale={ew}:{eh}")
a_chain = (a_chain + "," if a_chain else "") + f"scale={ew}:{eh},setsar=1"
w, h = ew, eh
fps = meta_a["video"].get("fps") or 30.0
grid = frame_window(0.0, None, meta_a) is not None
rate_a, v0a = frame_rate(meta_a), stream_starts(meta_a)[0]
fps_filter = frame_durations(meta_a, rate_a)
fps_filter = fps_filter[:-2] if fps_filter.endswith("/1") else fps_filter
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, source=meta_a)
start_b = time_arg(per(args.from_, i, "0"), "--from", fps, source=meta_b)
if args.end:
end = time_arg(per(args.end, i, "0"), "--end", fps, source=meta_a)
length = end - at
else:
length = time_arg(per(args.duration, i, "4"), "--duration", fps, source=meta_a)
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 = None if is_still_input(meta_b) else input_length(meta_b)
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")
v0b, rate_b = stream_starts(meta_b)[0], frame_rate(meta_b)
first = max(v0b, grid_at_or_after(start_b, v0b, rate_b))
on = span = None
if grid:
on = grid_at_or_after(at, v0a, rate_a)
span = grid_at_or_after(at + length, v0a, rate_a) - on
if round(span * rate_a) < 1:
die(f"cutaway {i + 1}: no frame of the A-roll starts between {at:g}s and {at + length:g}s "
f"(its frames are {1 / rate_a:.4f}s apart): nothing would be shown")
cutaways.append({"path": path, "at": at, "length": length, "from": start_b, "has_audio": bool(meta_b.get("audio")), "meta": meta_b,
"first": first, "rate": rate_b, "on": on, "span": span})
order = sorted(range(len(cutaways)), key=lambda k: cutaways[k]["at"])
for prev, k in zip(order, order[1:]):
end_prev = cutaways[prev]["at"] + cutaways[prev]["length"]
if cutaways[k]["at"] < end_prev:
die(f"cutaway {k + 1} at {cutaways[k]['at']:g}s overlaps cutaway {prev + 1} "
f"({cutaways[prev]['at']:g}s to {end_prev:g}s)")
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:
if is_still_input(c["meta"]):
frame_b = 1 / c["rate"] if c["rate"] else 0.04
cmd += still_loop_args(c["path"], max(c["from"], c["first"]) + max(c["length"], c["span"] or 0) + 2 * frame_b)
cmd += ["-i", c["path"]]
parts: List[str] = []
cur = "[0:v]"
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])]
convert = [cv + range_chain(m, meta_a) for cv, m in zip(convert, [meta_a] + [c["meta"] for c in cutaways])]
if convert[0] or a_chain:
parts.append(f"[0:v]{convert[0]}{a_chain or '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, as_limited(c["meta"]), [args.pad_color], pad + "black", line_meta=meta_a,
tag=f"pad{i}", labelled=True))
b_sq = (square_pixels(c["meta"]["video"]) + ",") if square_pixels(c["meta"]["video"]) else ""
pix = 'yuv420p10le' if (meta_a.get('video') or {}).get('bt2020_or_hdr') else 'yuv420p'
if c["on"] is None:
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]}{b_sq}{geo},setsar=1,fps={fps:g},format={pix}[b{i}]")
window = window_expr(c["at"], c["at"] + c["length"], None)
else:
half_b = 0.5 / c["rate"] if c["rate"] else 0.0
parts.append(f"[{i + 1}:v]trim=start={max(0.0, c['first'] - half_b):.6f}:end={max(c['first'] + c['span'], c['first'] + 2 * half_b) - half_b:.6f},"
f"setpts=PTS-STARTPTS+{math.floor(c['on'] * rate_a + 1e-6) / rate_a:.6f}/TB,"
f"{convert[i + 1]}{b_sq}{geo},setsar=1,{fps_filter},format={pix}[b{i}]")
window = window_expr(c["on"], c["on"] + c["span"], meta_a, half_open=True)
parts.append(f"{cur}[b{i}]overlay={windowed_overlay_x(0, window)}:0{overlay_format(meta_a)}:eof_action=repeat[v{i}]")
cur = f"[v{i}]"
vout = cur
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] = []
for c in cutaways:
c["s0"] = round((c["at"] if c["on"] is None else c["on"]) * MIX_RATE)
c["sn"] = round((c["length"] if c["on"] is None else c["span"]) * MIX_RATE)
if has_audio_a:
gate = ""
if args.audio == "b":
gate = ",aeval='val(ch)*not(" + "+".join(
f"between(t,{(c['s0'] - 0.5) / MIX_RATE:.9f},{(c['s0'] + c['sn'] - 0.5) / MIX_RATE:.9f})" for c in cutaways) + ")':c=same"
parts.append(f"[0:a:0]aformat=sample_rates=48000:channel_layouts=stereo{gate}[a0]")
layers.append("[a0]")
for i, c in enumerate(cutaways):
first, length = c["first"], c["length"] if c["on"] is None else c["span"]
lead = c["s0"] / MIX_RATE
delay = silence_filter(MIX_RATE, lead=lead)
if "S:" not in delay:
delay = f"adelay={round(lead * 1000)}|{round(lead * 1000)}"
exact = f"apad=whole_len={c['sn']},atrim=end_sample={c['sn']}," if args.audio == "b" else ""
parts.append(f"[{i + 1}:a:0]{av_trim(first, first + length)[1]},"
f"aformat=sample_rates=48000:channel_layouts=stereo,{exact}{delay}[ab{i}]")
layers.append(f"[ab{i}]")
tail = conform_to_length(dur_a, MIX_RATE) if dur_a > 0 else f"atrim=duration={dur_a:.3f}"
parts.append(f"{''.join(layers)}amix=inputs={len(layers)}:normalize=0:dropout_transition=0,{tail}[aout]")
aout = "[aout]"
graph = cfr_at_input(";".join(parts), meta_a)
cmd += ["-filter_complex", graph, "-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", conform_output_t(dur_a, MIX_RATE) if aout == "[aout]" and dur_a > 0 else 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())