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
"""Join clips with transitions, normalising resolution, frame rate and audio
layout so mismatched sources (phone + camera + screen recording) cut together.
Transitions (xfade): fade, dissolve, wipeleft, wiperight, wipeup, wipedown,
slideleft, slideright, circleopen, fadeblack, fadewhite, smoothleft, none.
Audio-only inputs (WAV, FLAC, MP3, M4A, ...) are joined as audio: every clip is
resampled to one rate and channel layout (the first clip's rate, the widest
layout; --sample-rate / --channels override), crossfaded with acrossfade or
butted with concat, and written in the codec the output extension names. The
output of an audio join must be an audio extension; mixing audio and video
inputs is refused.
Examples:
python3 join.py a.mp4 b.mp4 c.mp4 -o final.mp4 # 0.5 s crossfade, size/fps from the first clip
python3 join.py *.mp4 --transition fadeblack --duration 1 -o reel.mp4
python3 join.py a.mov b.mp4 --transition none --width 1920 --height 1080 --fps 30
python3 join.py intro.wav talk.m4a outro.wav -o episode.flac # audio join, 0.5 s crossfade
python3 join.py part1.wav part2.wav --transition none -o full.wav # butt join, sample rate of part1
python3 join.py --list parts.txt --transition none -o voice.wav # the segments a TTS step wrote, in order
python3 join.py --list parts.txt --on-missing skip -o voice.wav # join what is there, report the rest
Every input is checked before anything is joined: a missing, empty or unreadable segment is
refused with every problem named at once (kind input), never discovered one run at a time.
--on-missing skip joins the usable segments instead and lists the others under `skipped`.
Under --dry-run a segment that does not exist yet is an earlier step's output: it is planned
on and named under `pending` (never `skipped`), whichever --on-missing was given, and its
extension stands in for what it will hold (an audio extension: no picture).
Every input with an audio stream is also measured (one volumedetect pass): a segment whose peak
is at or below --silence-threshold (default -50 dBFS) is silent -- the trace of a TTS call that
wrote a valid but empty wav. --on-silent warn (default) joins it and names it under `silent`;
fail refuses it with the other input problems; skip drops it into `skipped`. A clip with no
audio stream is never silent.
"""
import argparse
import os
import sys
from typing import Any, Dict, List, Optional, Tuple
from _common import STATE, AUDIO_MEDIA_EXT, draws_chroma, drawn_chain, label_chain, matrix_chain, video_args, aac_args, add_common, apply_common, audio_codec_for, default_output, die, dry_run_input_pending, emit, ffmpeg_base, info, measured_level_dbfs, is_audio_output, probe, require_tool, run, validate_color, X264_PRESETS, fmt_secs
from _common.emit import warn
TRANSITIONS = ["fade", "dissolve", "wipeleft", "wiperight", "wipeup", "wipedown", "slideleft", "slideright",
"circleopen", "circleclose", "fadeblack", "fadewhite", "smoothleft", "smoothright", "radial", "none"]
LAYOUTS = {1: "mono", 2: "stereo", 6: "5.1", 8: "7.1"}
# inputs --on-missing skip dropped, reported in the success document (empty when nothing was)
STATE_SKIPPED: List[Dict[str, Any]] = []
# --dry-run: inputs that do not exist yet, planned on as an earlier step's output
STATE_PENDING: List[Dict[str, Any]] = []
STATE_NOTES: List[str] = []
# --on-silent warn: inputs whose audio peak is at or below --silence-threshold, joined anyway
STATE_SILENT: List[Dict[str, Any]] = []
# warnings, never refusals: a clip shorter than MIN_SEGMENT_FRAMES frames (audio-only: shorter than
# MIN_AUDIO_SEGMENT seconds) and a path listed more than once (repeating a clip can be intentional)
STATE_SHORT: List[Dict[str, Any]] = []
STATE_DUPES: List[Dict[str, Any]] = []
# original 0-based list position of each input still in args.inputs (after any skip)
STATE_KEPT: List[int] = []
MIN_SEGMENT_FRAMES = 2
MIN_AUDIO_SEGMENT = 0.05
def reported() -> Dict[str, Any]:
"""The input bookkeeping both success documents carry: `skipped` is what the join left out,
`pending` what a dry run planned on without it existing; `notes` says the same in words."""
extra: Dict[str, Any] = {"skipped": list(STATE_SKIPPED), "pending": list(STATE_PENDING), "silent": list(STATE_SILENT),
"short_segments": list(STATE_SHORT), "duplicates": list(STATE_DUPES)}
if STATE_NOTES:
extra["notes"] = list(STATE_NOTES)
return extra
def unpending_length(durs: List[float], d: float) -> Optional[float]:
"""The joined length the clip durations add up to, or None while an input is pending: its
dry-run stub says 0 s, which would count the clip as nothing and still subtract a transition
for it (a negative length when nothing exists yet)."""
if STATE_PENDING:
return None
return round(sum(durs) - d * (len(durs) - 1), 3)
def clip_length(meta: Dict[str, Any], fps: float) -> float:
"""The one length a clip holds in a join, for its picture and its sound alike: the
video stream's, or the audio stream's when the sound runs more than a frame past the picture
(narration is never cut; an AAC tail adds no frame). The container duration (audio priming,
a longer track) is only the fallback when a stream length is unknown (a pending input)."""
v = (meta.get("video") or {}).get("duration")
a = (meta.get("audio") or {}).get("duration")
if not v:
return meta.get("duration") or 0.0
if a and fps and a > v + 1.0 / fps:
return a
return v
def find_duplicates(paths: List[str]) -> List[Dict[str, Any]]:
"""Every path (compared by its resolved absolute form) listed more than once, with the 0-based
list positions it appears at. A warning, not a refusal: repeating a clip can be intentional."""
seen: Dict[str, List[int]] = {}
for i, p in enumerate(paths):
seen.setdefault(os.path.realpath(p), []).append(i)
return [{"path": paths[ix[0]], "indices": ix} for ix in seen.values() if len(ix) > 1]
def note_short_segments(paths: List[str], metas: List[dict], minimum: float, unit: str) -> None:
"""Record every measured input shorter than `minimum` seconds (a pending dry-run stub is not
measured): such a clip joins as a flash nobody sees -- usually a failed earlier step."""
for p, m, k in zip(paths, metas, STATE_KEPT or range(len(paths))):
dur = m.get("duration") or 0.0
if m.get("dry_run") or dur >= minimum:
continue
STATE_SHORT.append({"index": k, "path": p, "duration": round(dur, 4)})
if STATE_SHORT:
listing = ", ".join(f"#{s['index'] + 1} {s['path']} ({s['duration']:g}s)" for s in STATE_SHORT)
warn(f"{len(STATE_SHORT)} input(s) shorter than {unit}: {listing}", "short_inputs", count=len(STATE_SHORT))
STATE_NOTES.append(f"{len(STATE_SHORT)} input(s) are shorter than {unit} and were joined anyway: {listing}")
def expected_text(expected: Optional[float]) -> str:
"""unpending_length() as the stderr summary line puts it."""
return f"expected ~{expected:.3f}s" if expected is not None else "expected length unknown until the pending inputs exist"
def join_audio(args: argparse.Namespace, metas: List[dict]) -> int:
"""Concatenate audio-only inputs: one sample rate, one channel layout, acrossfade or concat."""
n = len(args.inputs)
durs = [m.get("duration") or 0.0 for m in metas]
d = args.duration if args.transition != "none" else 0.0
place_silent(durs, d)
note_short_segments(args.inputs, metas, MIN_AUDIO_SEGMENT, f"{MIN_AUDIO_SEGMENT:g}s")
for p, dur in zip(args.inputs, durs):
if d and dur <= d * 2 and not STATE.dry_run:
die(f"{p} is only {dur:.2f}s, too short for a {d:.2f}s crossfade; shorten --duration")
# a pending input's probe is the dry-run stub (rate and layout unmeasured): plan from the
# clips that exist, and fall back to 48 kHz stereo only when none does
known = [m for m in metas if not m.get("dry_run")] or metas
rates = [m["audio"].get("sample_rate") or 48000 for m in known]
chans = [m["audio"].get("channels") or 2 for m in known]
rate = args.sample_rate or rates[0]
channels = args.channels or max(chans)
layout = LAYOUTS.get(channels)
if layout is None:
die(f"{channels}-channel output has no standard layout here (1, 2, 6 or 8); pass --channels")
if len(set(rates)) > 1:
info(f"sample rates differ ({', '.join(str(r) for r in rates)} Hz); resampling every clip to {rate} Hz")
if len(set(chans)) > 1:
info(f"channel counts differ ({', '.join(str(c) for c in chans)}); every clip becomes {layout}")
output = args.output or default_output(args.inputs[0], "joined")
if not is_audio_output(output):
die(f"audio-only inputs cannot fill a video container: give -o an audio extension (.wav, .flac, .mp3, .m4a, .ogg, .opus), not {output}")
cmd = ffmpeg_base()
for p in args.inputs:
cmd += ["-i", p]
parts = [f"[{i}:a:0]aformat=sample_rates={rate}:channel_layouts={layout},asetpts=PTS-STARTPTS[a{i}]" for i in range(n)]
if args.transition == "none":
parts.append("".join(f"[a{i}]" for i in range(n)) + f"concat=n={n}:v=0:a=1[aout]")
else:
prev = "a0"
for i in range(1, n):
out = f"ax{i}" if i < n - 1 else "aout"
parts.append(f"[{prev}][a{i}]acrossfade=d={d:g}:c1=tri:c2=tri[{out}]")
prev = out
cmd += ["-filter_complex", ";".join(parts), "-map", "[aout]", "-vn"] + audio_codec_for(output) + [output]
run(cmd)
expected = unpending_length(durs, d)
r = probe(output, role="output")
a = r.get("audio") or {}
if not STATE.dry_run:
if r.get("video"):
die(f"{output} unexpectedly contains a video stream")
if a.get("sample_rate") != rate or a.get("channels") != channels:
die(f"{output} is {a.get('sample_rate')} Hz {a.get('channels')} ch, expected {rate} Hz {channels} ch")
info(f"wrote {output} ({fmt_secs(r['duration'])}, {expected_text(expected)}, audio {a.get('codec')} {channels}ch {rate}Hz, {n} clips, "
+ ("crossfade" if d else "butt join") + ")")
emit(output, mode="audio", **reported(), clips=n, transition=args.transition if d else "none", expected_duration=expected,
sample_rate=rate, channels=channels, video=False)
return 0
def read_list(path: str) -> List[str]:
"""--list FILE: one segment per line, in order, relative to the list file's own folder.
Blank lines and # comments are ignored, and ffmpeg's concat-demuxer spelling
(`file 'part 01.wav'`) is accepted, so a list written for `ffmpeg -f concat` works as is."""
try:
text = open(path, encoding="utf-8").read()
except OSError as exc:
die(f"cannot read --list {path}: {exc}")
base = os.path.dirname(os.path.abspath(path))
entries: List[str] = []
for line in text.splitlines():
line = line.strip()
if not line or line.startswith("#"):
continue
if line.startswith("file "):
line = line[5:].strip()
if len(line) >= 2 and line[0] == line[-1] and line[0] in "'\"":
line = line[1:-1].replace("'\\''", "'")
entries.append(line if os.path.isabs(line) else os.path.join(base, line))
if not entries:
# the failure this exists for: an upstream step produced nothing, and the join must
# say so plainly rather than hand ffmpeg an empty concat and die somewhere later
die(f"--list {path} names no segments (empty, or only blank lines and comments)",
hint="check the step that writes the list: it produced no files")
return entries
def preflight(paths: List[str], audible: Optional[List[int]] = None) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
"""Every problem with every input, found before anything runs: missing, empty (0 bytes,
the usual trace of a TTS or download step that failed after creating its file), or not
readable as media. One ffprobe per file; nothing is decoded. Under --dry-run a file that
does not exist yet is not a problem but pending (the second list, with a note): in a
planned pipeline it is an earlier step's output, and the plan keeps it. The index of every
readable input with an audio stream is appended to `audible` (for find_silent())."""
ffprobe = require_tool("ffprobe")
problems: List[Dict[str, Any]] = []
pending: List[Dict[str, Any]] = []
for i, p in enumerate(paths):
if dry_run_input_pending(p):
pending.append({"index": i, "path": p})
continue
if not os.path.exists(p):
problems.append({"index": i, "path": p, "reason": "missing"})
continue
if os.path.isdir(p):
problems.append({"index": i, "path": p, "reason": "a directory, not a file"})
continue
if os.path.getsize(p) == 0:
problems.append({"index": i, "path": p, "reason": "empty (0 bytes)"})
continue
proc = run([ffprobe, "-v", "error", "-show_entries", "stream=codec_type", "-of", "csv=p=0", p],
quiet=True, check=False)
kinds = {line.strip() for line in (proc.stdout or "").splitlines() if line.strip()}
if proc.returncode != 0 or not kinds & {"audio", "video"}:
first = ((proc.stderr or "").strip().splitlines() or ["no audio or video stream"])[-1]
problems.append({"index": i, "path": p, "reason": f"unreadable: {first}"})
elif "audio" in kinds and audible is not None:
audible.append(i)
return problems, pending
def find_silent(paths: List[str], audible: List[int], threshold: float) -> List[Dict[str, Any]]:
"""The audible inputs whose whole-file peak (volumedetect max_volume) is at or below
`threshold` dBFS: one decode of the audio per input. Not under --dry-run: join is a writing
tool, and a dry run of it (or of render.py, which joins through it) runs no ffmpeg -- the plan
notes that silence is measured on the real run. An input whose level cannot be measured is
left to the join itself."""
silent: List[Dict[str, Any]] = []
if STATE.dry_run:
if audible:
STATE_NOTES.append("silence is not measured under --dry-run; a real run measures every input with audio "
"for --on-silent")
return silent
for i in audible:
lv = measured_level_dbfs(paths[i], seconds=86400)
if lv is not None and lv["peak_dbfs"] <= threshold:
silent.append({"index": i, "path": paths[i], "peak_db": lv["peak_dbfs"]})
return silent
def place_silent(lens: List[float], d: float) -> None:
"""Where each joined silent input sits in the output: `at`/`end` in output seconds. Input k
(in kept order) starts after the kept inputs before it, each overlapped by the transition d."""
for sil in STATE_SILENT:
if sil["index"] not in STATE_KEPT:
continue
k = STATE_KEPT.index(sil["index"])
if k >= len(lens):
continue
at = sum(lens[:k]) - k * d
sil["at"], sil["end"] = round(at, 3), round(at + lens[k], 3)
def parse_allow_silent(value: Optional[str], n: int) -> List[int]:
"""--allow-silent 3,7 -> 0-based indices; each must name an input (1..n)."""
if not value:
return []
out = []
for tok in value.split(","):
tok = tok.strip()
if not tok.isdigit() or not 1 <= int(tok) <= n:
die(f"--allow-silent takes input numbers 1..{n} separated by commas, got {tok!r}")
out.append(int(tok) - 1)
return out
def main() -> int:
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("inputs", nargs="*", help="two or more clips in order (or --list FILE)")
ap.add_argument("--list", metavar="FILE", help="read the clips from FILE, one per line in order (paths relative to FILE; "
"ffmpeg concat lines `file 'x.wav'` also accepted); an empty list is refused")
ap.add_argument("--on-missing", choices=["fail", "skip"], default="fail",
help="a missing, empty or unreadable input: fail (default; every problem named at once) or skip "
"(join the rest; each skipped input is reported under `skipped`)")
ap.add_argument("--on-silent", choices=["warn", "fail", "skip"], default="warn",
help="an input whose audio peak is at or below --silence-threshold: warn (default; join it, "
"name it under `silent`), fail (refuse with the other input problems) or skip (leave it out, "
"under `skipped`); a clip with no audio stream is never silent")
ap.add_argument("--allow-silent", metavar="N[,N...]",
help="input numbers (1-based) whose silence is intended, e.g. a planned pause: always joined, "
"listed under `silent` with intended: true, no warning, whatever --on-silent says")
ap.add_argument("--silence-threshold", type=float, default=-50.0, metavar="DB",
help="peak level in dBFS at or below which an input counts as silent (default -50)")
ap.add_argument("-o", "--output", help="output file (default: <first>_joined.mp4)")
ap.add_argument("--transition", choices=TRANSITIONS, default="fade", help="transition between clips (default fade)")
ap.add_argument("--duration", type=float, default=0.5, help="transition length in seconds (default 0.5)")
ap.add_argument("--width", type=int, help="output width (default: first clip)")
ap.add_argument("--height", type=int, help="output height (default: first clip)")
ap.add_argument("--fps", type=float, help="output frame rate (default: first clip)")
ap.add_argument("--fit", choices=["pad", "crop"], default="pad", help="how clips of another aspect reach the frame (default pad)")
ap.add_argument("--pad-color", 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)
aud = ap.add_argument_group("audio-only inputs")
aud.add_argument("--sample-rate", type=int, help="output sample rate in Hz (default: first clip's)")
aud.add_argument("--channels", type=int, choices=[1, 2, 6, 8], help="output channel count (default: the widest clip)")
add_common(ap)
args = ap.parse_args()
apply_common(args)
if args.fps is not None and args.fps <= 0:
die(f"--fps must be positive, got {args.fps:g}")
if args.list:
if args.inputs:
die("give the clips either as arguments or with --list, not both")
args.inputs = read_list(args.list)
if not args.inputs:
die("give at least two clips (or --list FILE)")
if args.silence_threshold >= 0:
die(f"--silence-threshold is a peak level in dBFS and must be negative, got {args.silence_threshold:g}")
skipped: List[Dict[str, Any]] = []
orig_inputs = list(args.inputs)
audible: List[int] = []
problems, pending = preflight(args.inputs, audible)
allowed = parse_allow_silent(args.allow_silent, len(args.inputs))
found = find_silent(args.inputs, audible, args.silence_threshold)
intended = [dict(s, intended=True) for s in found if s["index"] in allowed]
silent = [s for s in found if s["index"] not in allowed]
silent_problems = [{"index": s["index"], "path": s["path"], "reason": f"silent (peak {s['peak_db']:.1f} dBFS)"}
for s in silent]
refused = sorted((problems if args.on_missing == "fail" else [])
+ (silent_problems if args.on_silent == "fail" else []), key=lambda p: p["index"])
if refused:
listing = "; ".join(f"#{p['index'] + 1} {p['path']}: {p['reason']}" for p in refused)
ways = []
if args.on_missing == "fail" and problems:
ways.append("--on-missing skip")
if args.on_silent == "fail" and silent:
ways.append("--on-silent skip (or warn)")
die(f"{len(refused)} of {len(args.inputs)} inputs cannot be joined: {listing}",
hint="fix or regenerate them, or pass " + " and ".join(ways) + " to join the rest", problems=refused)
dropped = sorted((problems if args.on_missing == "skip" else [])
+ (silent_problems if args.on_silent == "skip" else []), key=lambda p: p["index"])
if dropped:
bad = {p["index"] for p in dropped}
skipped = dropped
args.inputs = [p for i, p in enumerate(args.inputs) if i not in bad]
for p in dropped:
info(f"skipping #{p['index'] + 1} {p['path']}: {p['reason']}")
STATE_SILENT[:] = sorted(intended + (silent if args.on_silent == "warn" else []), key=lambda s: s["index"])
if silent and args.on_silent == "warn":
listing = ", ".join(f"#{s['index'] + 1} {s['path']} (peak {s['peak_db']:.1f} dBFS)" for s in silent)
warn(f"{len(silent)} input(s) silent at or below {args.silence_threshold:g} dBFS, joined anyway: {listing}",
"silent_inputs", count=len(silent))
STATE_NOTES.append(f"{len(silent)} input(s) have no audible sound (peak at or below {args.silence_threshold:g} dBFS) "
f"and were joined anyway: {listing}; pass --on-silent fail or skip to refuse or drop them")
STATE_SKIPPED[:] = skipped
STATE_KEPT[:] = [i for i in range(len(args.inputs) + len(skipped)) if i not in {p["index"] for p in skipped}]
dupes = [dd for dd in find_duplicates(orig_inputs)
if len([i for i in dd["indices"] if i in STATE_KEPT]) > 1]
for dd in dupes:
dd["indices"] = [i for i in dd["indices"] if i in STATE_KEPT]
STATE_DUPES[:] = dupes
if dupes:
listing = "; ".join(f"{dd['path']} at #" + ", #".join(str(i + 1) for i in dd["indices"]) for dd in dupes)
warn(f"input(s) listed more than once: {listing}", "duplicate_inputs", count=len(dupes))
STATE_NOTES.append(f"{len(dupes)} input(s) are listed more than once and joined each time: {listing}; "
"fine if the repeat is intended")
STATE_PENDING[:] = pending
if pending:
# a dry run cannot know whether the file will be there: it plans on it, and says what a
# real run does if it still is not (the same --on-missing rule as any missing input --
# including the refusal when skipping would leave fewer than two inputs)
left = len(args.inputs) - len(pending)
if args.on_missing == "fail":
then = "refuses the join if one is still missing"
elif left >= 2:
then = "skips one that is still missing"
else:
then = (f"skips one that is still missing and refuses the join if that leaves fewer than two inputs "
f"(only {left} exist{'s' if left == 1 else ''} now)")
STATE_NOTES.append(f"{len(pending)} of {len(args.inputs) + len(skipped)} inputs do not exist yet and were planned on "
"as an earlier step's output: " + ", ".join(f"#{p['index'] + 1} {p['path']}" for p in pending)
+ f"; a real run {then}")
if len(args.inputs) < 2:
die("give at least two clips" if not skipped else
f"only {len(args.inputs)} usable input(s) left after skipping {len(skipped)}; nothing to join",
skipped=skipped)
validate_color(args.pad_color, "--pad-color")
metas = [probe(p) for p in args.inputs]
# A pending input's probe is the dry-run stub, whose (0x0) video stream says nothing about the
# file an earlier step will write. Its extension stands in: a step names its output for what
# it holds, so an audio extension (.wav, .m4a, .aiff, ... -- every audio file this skill
# reads, not only the ones it writes) is taken for a file without a picture and any other for
# one with a picture. Measured and pending inputs then meet the same rules a real run
# applies: all without a picture is an audio join, a mix is refused.
pictured = [(os.path.splitext(p)[1].lower() not in AUDIO_MEDIA_EXT) if m.get("dry_run") else bool(m.get("video"))
for p, m in zip(args.inputs, metas)]
if all(m.get("dry_run") for m in metas):
STATE_NOTES.append(f"no input exists yet: {'a video' if any(pictured) else 'an audio'} join was planned from the file extensions")
if not any(pictured):
for p, m in zip(args.inputs, metas):
if not m.get("audio"):
die(f"{p} has neither a video nor an audio stream")
return join_audio(args, metas)
for p, m, pic in zip(args.inputs, metas, pictured):
if not pic:
# name an input measured to have a picture first; a pending one only as expected to
measured = [q for q, mm in zip(args.inputs, metas) if mm.get("video") and not mm.get("dry_run")]
planned = [q for q, mm, pc in zip(args.inputs, metas, pictured) if pc and mm.get("dry_run")]
other = (f"{measured[0]} has one" if measured else
f"{planned[0]}, which does not exist yet, is expected to have one (its extension is not an audio one)" if planned else "")
die((f"{p} does not exist yet, and its audio extension says it will have no video stream" if m.get("dry_run")
else f"{p} has no video stream")
+ (f" while {other}; join audio with audio or give every clip a picture" if other else ""))
first = metas[0]["video"]
fw, fh = first["width"], first["height"]
if first.get("rotation") in (90, -90, 270, -270):
fw, fh = fh, fw
if args.width and args.height:
w, h = args.width, args.height
elif args.width:
w = args.width
h = int(round(args.width * fh / fw)) if fw else args.width
elif args.height:
h = args.height
w = int(round(args.height * fw / fh)) if fh else args.height
else:
w, h = fw, fh
fps = args.fps or first.get("fps") or 30.0
fps = round(fps) if abs(fps - round(fps)) < 0.02 else fps
w, h = w - (w % 2), h - (h % 2)
note_short_segments(args.inputs, metas, MIN_SEGMENT_FRAMES / fps, f"{MIN_SEGMENT_FRAMES} frames at {fps:g} fps")
durs = [m.get("duration") or 0.0 for m in metas]
d = args.duration if args.transition != "none" else 0.0
# every clip gets one length for both streams, so whatever places the next clip -- xfade's
# offsets, or the concat filter, which starts it after the LONGER stream of this one -- places
# its picture and its sound together. The plain cut used to take the raw streams, and a sound
# past the picture (a music bed padded to the container, even a 20 ms AAC tail) left a hole in
# the video there.
lens = [clip_length(m, fps) for m in metas]
place_silent(lens, d)
for p, dur in zip(args.inputs, lens):
if d and dur <= d * 2 and not STATE.dry_run:
die(f"{p} is only {dur:.2f}s, too short for a {d:.2f}s transition; shorten --duration")
cmd = ffmpeg_base()
extra_inputs: List[str] = []
parts: List[str] = []
n = len(args.inputs)
for i, (p, m) in enumerate(zip(args.inputs, metas)):
cmd += ["-i", p]
# silent audio for clips without an audio track. `idx` is this ffmpeg input's position, i.e. n +
# how many synthetic inputs were already added -- not len(extra_inputs), which counts the six
# argv tokens ("-f", "lavfi", "-t", duration, "-i", "anullsrc=...") each synthetic input adds, not
# the input itself. With one no-audio clip both counts coincide (n + 0); from the second no-audio
# clip onward they diverge, and the previous `n + len(extra_inputs)` named a nonexistent, far-out-of-
# range ffmpeg input index -- found via a real multi-camera join where every clip lacked audio.
audio_src: List[str] = []
added = 0
for i, m in enumerate(metas):
if m.get("audio"):
audio_src.append(f"{i}:a:0")
else:
idx = n + added
extra_inputs += ["-f", "lavfi", "-t", f"{durs[i]:.3f}", "-i", "anullsrc=r=48000:cl=stereo"]
audio_src.append(f"{idx}:a:0")
added += 1
cmd += extra_inputs
# Any HDR input makes the join HDR (10-bit, HEVC via video_args on that clip's tags): an SDR
# first clip used to drag an HDR second clip down to 8-bit without a tone map.
hdr_meta = next((m for m in metas if (m.get("video") or {}).get("bt2020_or_hdr")), None)
pixfmt = "yuv420p10le" if hdr_meta else "yuv420p"
line = hdr_meta or metas[0]
# a BT.601 or RGB clip is converted to the BT.709 the join is tagged with, each clip by its own
# tags; 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 concat/xfade and pad have nothing to convert or misread
convert = [matrix_chain(m, line) for m in metas]
chroma_pad = args.fit != "crop" and draws_chroma([args.pad_color], line)
if any(convert) or chroma_pad:
convert = [c or label_chain(m, line) for c, m in zip(convert, metas)]
def geo(i: int) -> str:
if args.fit == "crop":
return f"scale={w}:{h}:force_original_aspect_ratio=increase,crop={w}:{h}"
pad = f"pad={w}:{h}:(ow-iw)/2:(oh-ih)/2:color="
return (f"scale={w}:{h}:force_original_aspect_ratio=decrease,"
+ drawn_chain(pad + args.pad_color, metas[i], [args.pad_color], pad + "black", line_meta=line,
tag=f"pad{i}", labelled=True))
# the audio-only join keeps the widest layout; the video join used to force stereo and
# silently dropped the centre/LFE of 5.1 material. A pending input's stub has no measured
# layout: plan from the inputs that exist, as join_audio() does.
chans = [(m.get("audio") or {}).get("channels") or 2 for m in ([m for m in metas if not m.get("dry_run")] or metas)]
channels = args.channels or max(chans)
layout = LAYOUTS.get(channels)
if layout is None:
die(f"{channels}-channel output has no standard layout here (1, 2, 6 or 8); pass --channels")
if len(set(chans)) > 1:
info(f"channel counts differ ({', '.join(str(c) for c in chans)}); every clip becomes {layout}")
for i in range(n):
parts.append(f"[{i}:v]{convert[i]}{geo(i)},setsar=1,setpts=PTS-STARTPTS,fps={fps:g},format={pixfmt},settb=AVTB[v{i}]")
parts.append(f"[{audio_src[i]}]aformat=sample_rates=48000:channel_layouts={layout},asetpts=PTS-STARTPTS[a{i}]")
# pad the shorter stream to the clip's length: the audio with silence, the picture by holding
# its last frame, then cut both there -- each clip boundary is then the same for both chains
for i in range(n):
vlen = (metas[i].get("video") or {}).get("duration") or lens[i]
hold = f"tpad=stop_mode=clone:stop_duration={lens[i] - vlen:.3f}," if lens[i] > vlen else ""
parts.append(f"[v{i}]{hold}trim=duration={lens[i]:.3f}[vp{i}]")
parts.append(f"[a{i}]apad=whole_dur={lens[i]:.3f},atrim=duration={lens[i]:.3f}[ap{i}]")
if args.transition == "none":
chain = "".join(f"[vp{i}][ap{i}]" for i in range(n))
parts.append(f"{chain}concat=n={n}:v=1:a=1[vout][aout]")
else:
vprev, aprev = "vp0", "ap0"
offset = 0.0
for i in range(1, n):
offset += lens[i - 1] - d
vout = f"vx{i}" if i < n - 1 else "vout"
aout = f"ax{i}" if i < n - 1 else "aout"
parts.append(f"[{vprev}][vp{i}]xfade=transition={args.transition}:duration={d:g}:offset={offset:.3f}[{vout}]")
parts.append(f"[{aprev}][ap{i}]acrossfade=d={d:g}:c1=tri:c2=tri[{aout}]")
vprev, aprev = vout, aout
# A pending input's stub is unmeasured (0x0, 0 fps, 0 s -- #77 keeps it honest rather than
# plausible), and the planned command is built on it: say which numbers are placeholders.
if metas[0].get("dry_run") and not (args.width and args.height and args.fps):
STATE_NOTES.append(f"the first input is pending, so the planned frame and rate ({w}x{h} @ {fps:g}fps) are "
"placeholders: a real run takes them from that file")
if d and any(m.get("dry_run") for m in metas[:-1]):
STATE_NOTES.append("the planned xfade offsets count each pending input as 0 s long: a real run offsets "
"by its measured length")
elif not d and any(m.get("dry_run") for m in metas):
# the plain cut trims/holds every clip to clip_length too (2.4.1), so a pending clip's
# planned trim=duration=0.000 is the stub's placeholder, not the cut
STATE_NOTES.append("the planned trim lengths count each pending input as 0 s long: a real run trims "
"or holds it to its measured length")
output = args.output or default_output(args.inputs[0], "joined", "mp4")
cmd += ["-filter_complex", ";".join(parts), "-map", "[vout]", "-map", "[aout]"]
# the fps filter already made the picture constant-rate, and the per-clip trims (then xfade or
# concat) place every frame: FFmpeg 5.1's default cfr output mode still duplicated the last one
# to meet the AAC tail (a 51-frame dissolve came out 52), which newer builds no longer do -- pass
# the frames through as built, for a plain cut as much as for a transition
cmd += ["-fps_mode", "passthrough"]
cmd += video_args(hdr_meta or metas[0], args.crf, args.preset, convert_matrix=False) + aac_args() + [output]
run(cmd)
expected = unpending_length(lens, d)
r = probe(output, role="output")
# the picture is what the offsets place: measure the video stream, not the container (whose
# length also counts the AAC tail), against the length the clips add up to
measured = (r.get("video") or {}).get("duration") or r.get("duration")
verification = []
if expected is not None and measured is not None and not STATE.dry_run:
tol = max(1.5 / fps, 0.05)
verification.append({"step": "duration", "ok": abs(measured - expected) <= tol,
"measured": round(measured, 3), "expected": expected, "tolerance": round(tol, 3)})
info(f"wrote {output} ({fmt_secs(measured)}, {expected_text(expected)}, {w}x{h} @ {fps:g}fps, {n} clips, {args.transition})")
emit(output, mode="video", **reported(), clips=n, transition=args.transition, expected_duration=expected,
verification=verification,
dropped_non_av_streams=any(m.get("subtitle_streams") or m.get("data_streams") for m in metas))
return 0
if __name__ == "__main__":
sys.exit(main())