"""Composite several video clips into one COLSxROWS grid, e.g. a 4x2 wall of
takes, angles, or A/B renders side by side.
Every cell is letterboxed (not stretched) to a common --cell-width/--cell-height
so clips of different aspect ratios and resolutions line up cleanly. By default
each cell gets its source filename (extension stripped) burnt into the bottom
right corner -- --label none turns that off. The grid has no audio unless
--audio-from picks one input's track to carry through; mixing every clip's
audio together is rarely what a comparison grid is for, so this tool never
does it silently.
The grid runs only as long as its shortest clip by default, or is padded to
the longest clip's duration with --pad (each shorter cell holds its last
frame, and --audio-from's track is padded with silence, out to that length);
a mismatched frame rate across sources is conformed to --fps first so cells
stay in sync.
Examples:
python3 grid.py take1.mp4 take2.mp4 take3.mp4 take4.mp4 take5.mp4 take6.mp4 take7.mp4 take8.mp4 --cols 4 --rows 2
python3 grid.py a.mp4 b.mp4 c.mp4 d.mp4 --cols 2 --rows 2 --label none -o compare.mp4
python3 grid.py cam1.mp4 cam2.mp4 --cols 2 --rows 1 --audio-from 0 --pad
"""
import argparse
import os
import sys
from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, X264_PRESETS, fmt_secs, \
as_limited, draws_chroma, drawn_chain, drawtext_text_opts, escape_drawtext, ffmpeg_base, info, label_chain, matrix_chain, range_chain, probe, run, validate_color, video_args
from _common.fonts import font_choice, record_font_choice
from _common import drawtext_fontfile
from _common import ffmpeg_filters, filter_missing_hint
from _common.emit import note, record_fallback
from _common.fonts import script_font_for_text
from _common.probe import is_still_input, square_pixels, still_loop_args
from _common.wrap import text_width_em
from _common.emit import input_length
from _common.decision import conform_output_t, conform_to_length
LABEL_MARGIN = 10
def _fit_label(stem: str, cell_width: int, font_size: int) -> str:
"""The label as drawn: `stem` when it fits the cell (less the margin and the box's border on
each side), else its head with an ellipsis. It is right-aligned, so a label wider than the
cell used to lose its start off the left edge and show only its tail (#411). The width is the
averaged advance table's estimate."""
room = (cell_width - 2 * LABEL_MARGIN - 8) / float(max(1, font_size))
if text_width_em(stem) <= room:
return stem
if room <= 1:
return stem[:1]
head = stem
while head and text_width_em(head + "\u2026") > room:
head = head[:-1]
return (head.rstrip() + "\u2026") if head else stem[:1]
def main() -> int:
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("inputs", nargs="+", help="video clips, filled into the grid left-to-right, top-to-bottom")
ap.add_argument("-o", "--output", help="output file (default: <first name>_grid.<ext>)")
ap.add_argument("--cols", type=int, required=True, help="grid columns")
ap.add_argument("--rows", type=int, required=True, help="grid rows")
ap.add_argument("--cell-width", type=int, default=480, help="each cell's width in px, must be even (default 480)")
ap.add_argument("--cell-height", type=int, default=270, help="each cell's height in px, must be even (default 270)")
ap.add_argument("--fps", type=float, default=30.0, help="output frame rate every cell is conformed to (default 30)")
ap.add_argument("--label", choices=["auto", "none"], default="auto",
help="auto (default): burn each cell's filename (extension stripped) into its bottom-right corner; none: no label")
ap.add_argument("--font", default="DejaVu Sans", help="label font (fontconfig family name, default DejaVu Sans)")
ap.add_argument("--font-size", type=int, default=16, help="label font size (default 16)")
ap.add_argument("--font-color", default="white", help="label text colour (default white)")
ap.add_argument("--pad", action="store_true", help="hold each shorter cell's last frame (and pad --audio-from's track with silence) out to the longest clip's duration, instead of stopping at the shortest")
ap.add_argument("--audio-from", type=int, help="0-based index into inputs to take audio from (default: no audio)")
ap.add_argument("--gap", type=int, default=0, help="gap between cells in px, must be even (default 0, cells touch)")
ap.add_argument("--background", default="black", help="colour of the gap/pad borders (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)
if args.label == "auto" and ffmpeg_filters() and "drawtext" not in ffmpeg_filters():
args.label = "none"
record_fallback("this ffmpeg build has no drawtext filter, so the cells are not labelled "
"(the same as --label none)", "grid_no_drawtext")
note("no cell labels: this ffmpeg build has no drawtext filter (" + filter_missing_hint("drawtext") + ")")
n = args.cols * args.rows
if args.cols <= 0 or args.rows <= 0:
die(f"--cols/--rows must be > 0, got cols={args.cols} rows={args.rows}")
if n == 1:
die("--cols 1 --rows 1 is a single cell; a grid needs at least two (fit.py letterboxes one clip)")
if len(args.inputs) != n:
die(f"--cols {args.cols} --rows {args.rows} needs exactly {n} inputs, got {len(args.inputs)}")
if args.cell_width <= 0 or args.cell_height <= 0:
die(f"--cell-width/--cell-height must be > 0, got width={args.cell_width} height={args.cell_height}")
if args.cell_width % 2 or args.cell_height % 2:
die(f"--cell-width/--cell-height must be even (4:2:0 chroma), got width={args.cell_width} height={args.cell_height}")
if args.fps <= 0:
die(f"--fps must be > 0, got {args.fps:g}")
if args.gap < 0 or args.gap % 2:
die(f"--gap must be >= 0 and even, got {args.gap}")
validate_color(args.background, "--background")
if args.font_color:
validate_color(args.font_color, "--font-color")
if args.audio_from is not None and not 0 <= args.audio_from < n:
die(f"--audio-from {args.audio_from}: must be an input index 0..{n - 1}")
metas = [probe(p) for p in args.inputs]
for p, m in zip(args.inputs, metas):
if not m.get("video"):
die(f"{p}: input has no video stream")
if args.audio_from is not None and not metas[args.audio_from].get("audio"):
die(f"--audio-from {args.audio_from}: {args.inputs[args.audio_from]} has no audio stream")
stills = [is_still_input(m) for m in metas]
if all(stills):
die("every cell is a still picture, so the grid has no length to take from a clip", kind="input",
hint="give at least one video cell, or make a clip of a still first (insert.py STILL --duration T)")
durations = [input_length(m) for m, still in zip(metas, stills) if not still]
target_duration = max(durations) if args.pad else min(durations)
durations = [target_duration if still else input_length(m) for m, still in zip(metas, stills)]
stems = [os.path.splitext(os.path.basename(p))[0] for p in args.inputs]
font_explicit = args.font != ap.get_default("font")
label_fonts = []
for stem in (stems if args.label == "auto" else []):
_sc, script_file, script_family = script_font_for_text(stem, font=args.font, font_explicit=font_explicit)
label_fonts.append(font_choice(args.font, script_file=script_file, script_family=script_family))
font_used = label_fonts[0] if label_fonts else font_choice(args.font)
if args.label == "auto":
record_font_choice(font_used)
if len({f.get("file") for f in label_fonts}) > 1:
note("cell labels drawn with more than one font, by script: "
+ "; ".join(sorted({str(f.get("family") or f.get("file")) for f in label_fonts})))
labels = [_fit_label(stem, args.cell_width, args.font_size) for stem in stems]
cut = [stem for stem, lab in zip(stems, labels) if lab != stem]
if args.label == "auto" and cut:
note(f"{len(cut)} cell label(s) wider than the {args.cell_width} px cell at --font-size "
f"{args.font_size} were shortened from the end with an ellipsis")
output = args.output or default_output(args.inputs[0], "grid", "mp4" if stills[0] else None)
cmd = ffmpeg_base()
for p, still in zip(args.inputs, stills):
cmd += (still_loop_args(p, target_duration) if still else []) + ["-i", p]
colours = [args.background] + ([args.font_color] if args.label == "auto" else [])
chroma = draws_chroma(colours, None)
convert = [matrix_chain(m, None) for m in metas]
if any(convert) or chroma:
convert = [c or label_chain(m, None) for c, m in zip(convert, metas)]
convert = [c + range_chain(m, None) for c, m in zip(convert, metas)]
parts = []
for i, p in enumerate(args.inputs):
drawn = [
(f"pad={args.cell_width}:{args.cell_height}:(ow-iw)/2:(oh-ih)/2:color={args.background}",
f"pad={args.cell_width}:{args.cell_height}:(ow-iw)/2:(oh-ih)/2:color=black"),
("setsar=1",) * 2,
]
if args.pad and durations[i] < target_duration:
drawn.append((f"tpad=stop_mode=clone:stop_duration={target_duration - durations[i]:.3f}",) * 2)
elif not args.pad:
drawn.append((f"trim=duration={target_duration:.3f}",) * 2)
if args.label == "auto":
font_file = label_fonts[i]["file"]
font_opt = drawtext_fontfile(font_file) if font_file else f"font='{escape_drawtext(args.font)}'"
drawn.append((f"drawtext={drawtext_text_opts(labels[i])}:{font_opt}:fontsize={args.font_size}:"
f"fontcolor={args.font_color}:x=w-tw-{LABEL_MARGIN}:y=h-th-{LABEL_MARGIN}:"
f"box=1:boxcolor=black@0.5:boxborderw=4", "null"))
gap_r = args.gap if i % args.cols < args.cols - 1 else 0
gap_b = args.gap if i // args.cols < args.rows - 1 else 0
if chroma and (gap_r or gap_b):
drawn.append((f"pad=iw+{gap_r}:ih+{gap_b}:0:0:color={args.background}", f"pad=iw+{gap_r}:ih+{gap_b}:0:0:color=black"))
sq = (square_pixels(metas[i]["video"]) + ",") if square_pixels(metas[i]["video"]) else ""
chain = f"fps={args.fps:g},{sq}scale={args.cell_width}:{args.cell_height}:force_original_aspect_ratio=decrease,"
chain += drawn_chain(",".join(c for c, _n in drawn), as_limited(metas[i]), colours, ",".join(n for _c, n in drawn),
line_meta=None, tag=f"c{i}", labelled=True)
parts.append(f"[{i}:v]{convert[i]}{chain}[v{i}]")
cw, ch = args.cell_width + args.gap, args.cell_height + args.gap
layout = "|".join(f"{c * cw}_{r * ch}" for r in range(args.rows) for c in range(args.cols))
parts.append("".join(f"[v{i}]" for i in range(n)) + f"xstack=inputs={n}:layout={layout}:fill={args.background}[out]")
audio_rate = (metas[args.audio_from]["audio"].get("sample_rate") or 0) if args.audio_from is not None else 0
conformed = bool(audio_rate and target_duration > 0)
audio_source = None
if conformed:
parts.append(f"[{args.audio_from}:a:0]{conform_to_length(target_duration, audio_rate)}[aout]")
audio_source = "[aout]"
elif args.audio_from is not None and args.pad and durations[args.audio_from] < target_duration:
parts.append(f"[{args.audio_from}:a:0]apad,atrim=duration={target_duration:.3f}[aout]")
audio_source = "[aout]"
elif args.audio_from is not None:
audio_source = f"{args.audio_from}:a:0"
cmd += ["-filter_complex", ";".join(parts), "-map", "[out]"]
if audio_source:
cmd += ["-map", audio_source]
if any((m.get("video") or {}).get("bt2020_or_hdr") for m in metas):
info("note: an HDR input is composited into an 8-bit SDR grid (grid.py is a comparison artefact); use color.py --to-sdr first for a graded conversion")
cmd += video_args(None, args.crf, args.preset)
cmd += cfr_args(None, args.fps)
if args.audio_from is not None:
cmd += aac_args()
else:
cmd += ["-an"]
cmd += ["-t", conform_output_t(target_duration, audio_rate) if conformed else f"{target_duration:.3f}", output]
run(cmd)
result = probe(output, role="output")
v = result["video"]
info(f"wrote {output} ({fmt_secs(result['duration'])}, {v['width']}x{v['height']}, {args.cols}x{args.rows} grid, "
f"{n} clips, {'padded to longest' if args.pad else 'stopped at shortest'})")
emit(output, cols=args.cols, rows=args.rows, clips=n, **({"font_used": font_used} if args.label == "auto" else {}))
return 0
if __name__ == "__main__":
sys.exit(main())