Skip to content

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.

4.5 KB
Raw Blame
#!/usr/bin/env python3
"""Generate a solid-colour or two-colour gradient background clip.

No input file: a silent, fixed-duration, exact-size clip generated entirely
by ffmpeg's own source filters (`color` for solid, `gradients` for a
two-colour gradient) -- for a title card background, a placeholder behind a
logo, or a base layer for overlay.py to composite onto.

Examples:
  python3 background.py --duration 3 --width 1920 --height 1080 --color 0x101010
  python3 background.py --duration 5 --width 1080 --height 1920 --gradient 0xff6a00:0x0057ff --angle 45
"""
import argparse
import math
import sys

from _common import add_common, apply_common, die, draws_chroma, emit, ffmpeg_base, info, parse_time, probe, rgb_chain_to_bt709, run, validate_color, video_args, X264_PRESETS, time_arg, fmt_secs


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("-o", "--output", required=True, help="output file")
    ap.add_argument("--duration", required=True, help="clip duration (seconds or mm:ss)")
    ap.add_argument("--width", type=int, required=True, help="output width in px (must be even)")
    ap.add_argument("--height", type=int, required=True, help="output height in px (must be even)")
    ap.add_argument("--fps", type=float, default=30.0, help="output frame rate (default 30)")
    src = ap.add_mutually_exclusive_group()
    src.add_argument("--color", default="black", help="solid background colour, e.g. black, 0x101010 (default black)")
    src.add_argument("--gradient", help="two colours as C1:C2 for a linear gradient, e.g. 0xff6a00:0x0057ff")
    ap.add_argument("--angle", type=float, default=0.0, help="gradient angle in degrees (with --gradient, default 0 = left to right)")
    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)

    target = time_arg(args.duration, "--duration", args.fps)
    if target <= 0:
        die("--duration must be > 0")
    if args.fps <= 0:
        die("--fps must be > 0")
    if args.width <= 0 or args.height <= 0:
        die(f"--width/--height must be > 0, got width={args.width} height={args.height}")
    if args.width % 2 or args.height % 2:
        die(f"--width/--height must be even (4:2:0 chroma), got width={args.width} height={args.height}")

    if args.gradient:
        try:
            c0, c1 = args.gradient.split(":")
        except ValueError:
            die(f"--gradient needs two colours as C1:C2, got '{args.gradient}'")
        validate_color(c0, "--gradient")
        validate_color(c1, "--gradient")
        rad = math.radians(args.angle)
        x1 = round(args.width * math.cos(rad))
        y1 = round(args.width * math.sin(rad))
        # gradients defaults to seed=-1 (a random seed picked fresh each run) and speed=0.01 (a
        # slow rotation applied every frame), so without pinning both, this "static" background
        # was neither reproducible between runs nor actually static across its own duration --
        # violating the bit_exact/deterministic contract _contract.py declares for this tool.
        # speed's own valid range bottoms out at 1e-05 (0 is refused), so that's the closest to
        # motionless the filter allows.
        src_filter = f"gradients=size={args.width}x{args.height}:rate={args.fps:g}:c0={c0}:c1={c1}:x0=0:y0=0:x1={x1}:y1={y1}:seed=0:speed=1e-05"
        colours = [c0, c1]
    else:
        validate_color(args.color, "--color")
        src_filter = f"color=c={args.color}:size={args.width}x{args.height}:rate={args.fps:g}"
        colours = [args.color]
    if draws_chroma(colours, None):
        # the colours are made in RGB and converted to the BT.709 the output is tagged with: left to
        # the encoder line's own conversion (or `color`'s YUV), they were BT.601 under that tag
        # (pure red decoded as (255,24,0)); a grey is the same under every matrix
        src_filter += (",format=rgb24" if not args.gradient else "") + rgb_chain_to_bt709(None, "yuv420p")

    output = args.output
    cmd = ffmpeg_base() + ["-f", "lavfi", "-i", src_filter, "-t", f"{target:.3f}"]
    cmd += video_args(None, args.crf, args.preset)
    cmd += ["-an", output]
    run(cmd)

    result = probe(output, role="output")
    v = result["video"]
    info(f"wrote {output} ({fmt_secs(result['duration'])}, {v['width']}x{v['height']}, {v['fps']:g}fps)")
    emit(output)
    return 0


if __name__ == "__main__":
    sys.exit(main())