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
"""Fit a video to a target duration and/or aspect ratio.
Duration: --duration N with --method speed (retime video+audio, pitch-preserving
via atempo chaining) or --method trim (keep the first N seconds, or a centred
window with --from-center). Aspect: --aspect 16:9|9:16|1:1|4:5|W:H with
--fit pad (letterbox/pillarbox with --pad-color, default black, or --pad-fill blur\nfor a blurred copy of the frame behind the picture), --fit crop, or --fit blur\n(the whole picture centred on a blurred, darkened copy of itself -- nothing\ncropped, no black bars).
--width and/or --height set the output size: give one and the other follows
the aspect (source aspect if --aspect is not also given); give both for an
exact frame. --rotate 90|180|270 (clockwise) and --flip h|v apply a new
rotation/mirror to the picture -- distinct from the rotation metadata a
source already carries (read automatically to compute the displayed size,
never altered by these flags unless asked). Both can be combined; rotate is
applied before flip.
Crop keeps the centre of the frame by default, which is a guess: going from
16:9 to 9:16 throws away most of the width, and whatever isn't in the middle
third (a person at the edge, a product held to one side) is cut off. Say what
to keep with --crop-x / --crop-y (0=left/top, 0.5=centre, 1=right/bottom, or
a decimal in between) rather than accepting the default silently when the
subject isn't centred; --fit pad never loses anything if you don't know yet.
Examples:
python3 fit.py input.mp4 --duration 60 # speed up/down to exactly 60s
python3 fit.py input.mp4 --duration 30 --method trim
python3 fit.py input.mp4 --aspect 9:16 --fit pad --width 1080
python3 fit.py input.mp4 --aspect 9:16 --fit pad --pad-fill blur # the phone-editor look: blurred frame behind the bars
python3 fit.py input.mp4 --aspect 9:16 --fit blur # same look in one word (blurred + darkened fill)
python3 fit.py input.mp4 --aspect 1:1 --fit crop --duration 15
python3 fit.py input.mp4 --aspect 9:16 --fit crop --crop-x 1 # keep the right edge (e.g. product held stage-right)
python3 fit.py input.mp4 --height 1080 # width follows the source aspect
python3 fit.py input.mp4 --width 1920 --height 1080 # exact frame, no aspect needed
python3 fit.py input.mp4 --rotate 90 # rotate 90 degrees clockwise
python3 fit.py input.mp4 --flip h # mirror horizontally
"""
import argparse
import math
import sys
from fractions import Fraction
from typing import List
from _common import video_args, STATE, add_common, apply_common, emit, aac_args, aspect_ratio, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, pad_filters, add_pad_fill_args, X264_PRESETS, time_arg, fmt_secs, frame_size
BLUR_DARKEN = 0.15 # how much --fit blur dims the blurred background copy (eq brightness)
def parse_aspect(value: str) -> Fraction:
# the one aspect grammar, shared with render.py's frame and --export-timeline's sequence
ratio = aspect_ratio(value)
if ratio is None:
die(f"bad aspect '{value}', use W:H like 16:9")
return ratio
def atempo_chain(factor: float) -> str:
"""atempo accepts 0.5..100 per instance; chain for extreme factors."""
parts: List[str] = []
remaining = factor
while remaining < 0.5:
parts.append("atempo=0.5")
remaining /= 0.5
while remaining > 100.0:
parts.append("atempo=100.0")
remaining /= 100.0
parts.append(f"atempo={remaining:.6f}")
return ",".join(parts)
def main() -> int:
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("input")
ap.add_argument("-o", "--output", help="output file (default: <name>_fit.<ext>)")
ap.add_argument("--audio-stream", type=int, default=0,
help="which audio stream of the input to keep, 0-based in file order (probe.py lists them under "
"audio_streams) -- matters on a multi-track input (dubbed languages, M&E stems); default 0, "
"the first track, same as leaving it unset always did")
d = ap.add_argument_group("duration")
d.add_argument("--duration", help="target duration (seconds or mm:ss)")
d.add_argument("--method", choices=["speed", "trim"], default="speed", help="how to reach the duration (default speed)")
d.add_argument("--from-center", action="store_true", help="with --method trim, keep the middle instead of the start")
d.add_argument("--max-speed", type=float, default=4.0, help="refuse speed factors above this (default 4x)")
d.add_argument("--smooth", choices=["none", "blend", "interpolate"], default="none",
help="slow-motion quality: blend (frame blending) or interpolate (motion-compensated, slow but fluid). default none = duplicate frames")
a = ap.add_argument_group("aspect")
a.add_argument("--aspect", help="target aspect ratio, e.g. 16:9, 9:16, 1:1, 4:5")
a.add_argument("--fit", choices=["pad", "crop", "blur"], default="pad",
help="how to reach the aspect: pad (letterbox), crop, or blur -- the whole picture centred on a "
"blurred, darkened copy of itself filling the rest (the phone-editor vertical, 1.14). "
"The darkening is applied to SDR sources only: on an HDR source the background is blurred "
"but left at its own levels, since an eq on PQ/HLG code values is not a -15%% perceptual dim")
a.add_argument("--width", type=int, help="output width in px (default: keep source width or the width implied by the aspect); with --height also given, both are used directly")
a.add_argument("--height", type=int, help="output height in px (default: keep source height or the height implied by the aspect); with --width also given, both are used directly")
a.add_argument("--pad-color", default="black", help="pad colour, e.g. black, white, 0x101010 (default black)")
add_pad_fill_args(a)
a.add_argument("--crop-x", type=float, default=0.5, help="with --fit crop, horizontal anchor 0=left, 0.5=centre (default), 1=right")
a.add_argument("--crop-y", type=float, default=0.5, help="with --fit crop, vertical anchor 0=top, 0.5=centre (default), 1=bottom")
r = ap.add_argument_group("rotate / flip")
r.add_argument("--rotate", type=int, choices=[90, 180, 270], help="rotate the picture clockwise by this many degrees")
r.add_argument("--flip", choices=["h", "v"], help="mirror the picture horizontally (h) or vertically (v)")
e = ap.add_argument_group("encoding")
e.set_defaults(crf=18) # --quality's default (the --crf alias was removed in 2.0)
e.add_argument("--preset", default="medium", choices=X264_PRESETS)
e.add_argument("--fps", type=float, help="force a constant output frame rate (recommended for VFR sources)")
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 not args.duration and not args.aspect and not args.width and not args.height and not args.fps and not args.rotate and not args.flip:
die("nothing to do: give --duration, --aspect, --width/--height, --rotate/--flip and/or --fps")
if not 0.0 <= args.crop_x <= 1.0:
die(f"--crop-x must be 0..1, got {args.crop_x}")
if not 0.0 <= args.crop_y <= 1.0:
die(f"--crop-y must be 0..1, got {args.crop_y}")
validate_color(args.pad_color, "--pad-color")
if args.pad_blur <= 0:
die(f"--pad-blur must be > 0, got {args.pad_blur}")
meta = probe(args.input)
if not meta.get("video"):
die("input has no video stream")
audio_streams = meta.get("audio_streams") or []
if audio_streams and not (0 <= args.audio_stream < len(audio_streams)):
die(f"--audio-stream {args.audio_stream}: input has {len(audio_streams)} audio stream(s), 0..{len(audio_streams) - 1}")
if args.audio_stream and not audio_streams:
die("--audio-stream needs an input with audio streams")
src_dur = meta["duration"] or 0.0
sw, sh = meta["video"]["width"], meta["video"]["height"]
if meta["video"].get("rotation") in (90, -90, 270, -270):
sw, sh = sh, sw
if args.rotate in (90, 270):
sw, sh = sh, sw
has_audio = bool(meta.get("audio"))
vf: List[str] = []
af: List[str] = []
pre_input: List[str] = []
post: List[str] = []
factor = 1.0
# ---- rotate / flip
if args.rotate == 90:
vf.append("transpose=1")
elif args.rotate == 270:
vf.append("transpose=2")
elif args.rotate == 180:
vf.append("transpose=2,transpose=2")
if args.flip == "h":
vf.append("hflip")
elif args.flip == "v":
vf.append("vflip")
# ---- duration
if args.duration:
target = time_arg(args.duration, "--duration", meta["video"].get("fps") if meta.get("video") else None)
if target <= 0:
die("target duration must be > 0")
if args.method == "speed":
if src_dur <= 0 and STATE.dry_run:
src_dur = target # planning against an intermediate that does not exist yet
factor = src_dur / target # >1 = speed up
if factor > args.max_speed or factor < 1 / args.max_speed:
die(f"required speed factor {factor:.2f}x exceeds --max-speed {args.max_speed}x; use --method trim or raise the limit")
if abs(factor - 1.0) > 1e-4:
vf.append(f"setpts={1/factor:.8f}*PTS")
src_fps = meta["video"].get("fps") or 30.0
if factor < 1.0 and args.smooth == "interpolate":
vf.append(f"minterpolate=fps={src_fps:g}:mi_mode=mci:mc_mode=aobmc:me_mode=bidir:vsbmc=1")
elif factor < 1.0 and args.smooth == "blend":
vf.append(f"fps={src_fps:g}")
vf.append("tblend=all_mode=average")
if has_audio:
af.append(atempo_chain(factor))
post += ["-t", f"{target:.3f}"]
STATE.duration_hint = target
else:
if target < src_dur:
start = (src_dur - target) / 2 if args.from_center else 0.0
pre_input += ["-ss", f"{start:.3f}"]
post += ["-t", f"{target:.3f}"]
else:
info(f"source ({src_dur:.2f}s) is already shorter than {target:.2f}s; trim does nothing")
# ---- aspect / size
if args.aspect or args.width or args.height:
# the one sizing rule, shared with render.py --export-timeline's sequence frame
out_w, out_h = frame_size(parse_aspect(args.aspect) if args.aspect else None, args.width, args.height, sw, sh)
if args.fit == "crop":
vf.append(f"scale={out_w}:{out_h}:force_original_aspect_ratio=increase")
vf.append(f"crop={out_w}:{out_h}:(in_w-out_w)*{args.crop_x:g}:(in_h-out_h)*{args.crop_y:g}")
elif args.fit == "blur":
# nothing is cropped and nothing is a black bar: the picture keeps its own aspect in
# the middle of a blurred, dimmed copy of itself (BLUR_DARKEN) filling the frame.
# The dimming is an eq on the code values, which is a -15 % perceptual dim on an SDR
# (gamma-encoded) signal and something else entirely on a PQ/HLG one -- so an HDR
# source keeps its blurred background undimmed rather than being silently altered
# (review 12). The blur itself is neutral either way, and no tone mapping happens.
darken = 0.0 if meta["video"].get("bt2020_or_hdr") else BLUR_DARKEN
if not darken:
info("--fit blur: HDR source, so the blurred background is not dimmed "
"(an eq on PQ/HLG code values is not the -15% dim it is on SDR); "
"run color.py --to-sdr first for the SDR look")
vf.append(pad_filters(out_w, out_h, "blur", args.pad_color, args.pad_blur, darken))
else:
vf.append(pad_filters(out_w, out_h, args.pad_fill, args.pad_color, args.pad_blur, meta=meta))
vf.append("setsar=1")
if args.fps:
vf.append(f"fps={args.fps:g}")
elif meta["video"].get("variable_frame_rate_suspected"):
info("source looks variable-frame-rate; conforming to constant fps automatically")
output = args.output or default_output(args.input, "fit")
cmd = ffmpeg_base() + pre_input + ["-i", args.input]
if vf:
cmd += ["-vf", ",".join(vf)]
if af:
cmd += ["-af", ",".join(af)]
cmd += ["-map", "0:v:0"]
if has_audio:
cmd += ["-map", f"0:a:{args.audio_stream}"]
cmd += video_args(meta, args.crf, args.preset)
cmd += cfr_args(meta, args.fps) if not args.fps else []
if has_audio:
cmd += aac_args()
else:
cmd += ["-an"]
cmd += post
if abs(factor - 1.0) > 1e-4 or "-ss" in pre_input:
# A subtitle/data stream stream-copied by run_keeping_subtitles keeps the source's
# original timestamps; --method speed retimes video (setpts) and audio (atempo) but has
# no equivalent way to retime a copied subtitle track, so it would desync from the
# now-faster/slower picture. Drop them here rather than ship a captions track that lies
# about when a line is spoken. --method trim's -ss moves the timeline the same way: a copied
# track kept its cues at the source's times and doubled the output's length (review 5).
run(cmd + [output])
dropped_streams = bool(meta.get("subtitle_streams") or meta.get("data_streams"))
else:
dropped_streams = run_keeping_subtitles(cmd, output)
result = probe(output, role="output")
msg = f"wrote {output} ({fmt_secs(result['duration'])}, {result['video']['width']}x{result['video']['height']})"
if abs(factor - 1.0) > 1e-4:
msg += f", speed {factor:.3f}x"
info(msg)
emit(output, dropped_non_av_streams=dropped_streams)
return 0
if __name__ == "__main__":
sys.exit(main())