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.

3.7 KB
Raw Blame
#!/usr/bin/env python3
"""Generate a small, low-bitrate proxy of a video: cheap for a machine to decode,
not meant for delivery. Intended for downstream AI analysis, preview or
editing-decision workflows that only need to look at (or feed a model) a
much smaller stand-in for the original.

Resizes to --width (default 640px, height follows the source aspect) or by
--scale factor, re-encodes at a proxy-grade --quality (default 30 - well above any
delivery preset's 18-24 in export.py, since a proxy trades visual quality for
size and speed), and always uses the fastest x264/x265 preset. Keeps the
source's own dynamic range (an HDR source proxies to HEVC10, same as every
other re-encoding tool here) rather than guessing whether SDR is wanted -
run color.py --to-sdr first if it is.

This tool only executes the spec it is given: it does not decide which asset
should be proxied, what resolution or bitrate is "right" for a given
downstream use, or what the proxy will be used for - those are the calling
agent's call.

Examples:
  python3 proxy.py input.mov                          # 640px wide, CRF 30, keeps audio
  python3 proxy.py input.mov --width 480 --no-audio    # smaller, video-only
  python3 proxy.py input.mov --scale 0.25 --fps 10     # quarter-size, 10fps (e.g. for a vision model)
"""
import argparse
import sys

from _common import add_common, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args, fmt_secs


def even(n: float) -> int:
    v = int(round(n))
    return v if v % 2 == 0 else v + 1


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>_proxy.<ext>)")
    ap.add_argument("--width", type=int, default=640, help="output width in px, height follows the source aspect (default 640)")
    ap.add_argument("--scale", type=float, help="scale factor applied to the source dimensions instead of --width (0 < scale <= 1)")
    ap.set_defaults(crf=30)  # --quality's default (the --crf alias was removed in 2.0)
    ap.add_argument("--fps", type=float, help="force a constant output frame rate")
    ap.add_argument("--no-audio", action="store_true", help="drop audio entirely (default: keep it)")
    add_common(ap)
    args = ap.parse_args()
    apply_common(args)

    if args.scale is not None and not 0.0 < args.scale <= 1.0:
        die(f"--scale must be > 0 and <= 1, got {args.scale}")
    if args.width <= 0:
        die(f"--width must be > 0, got {args.width}")
    if args.fps is not None and args.fps <= 0:
        die(f"--fps must be > 0, got {args.fps}")

    meta = probe(args.input)
    if not meta.get("video"):
        die("input has no video stream")
    sw, sh = meta["video"]["width"], meta["video"]["height"]
    if meta["video"].get("rotation") in (90, -90, 270, -270):
        sw = sh
    has_audio = bool(meta.get("audio")) and not args.no_audio

    out_w = even(sw * args.scale) if args.scale is not None else even(args.width)
    output = args.output or default_output(args.input, "proxy")

    cmd = ffmpeg_base() + ["-i", args.input, "-vf", f"scale={out_w}:-2"]
    cmd += video_args(meta, args.crf, "veryfast")
    cmd += cfr_args(meta, args.fps)
    cmd += ["-map", "0:v:0"] + (["-map", "0:a:0", "-c:a", "aac", "-b:a", "96k"] if has_audio else ["-an"])
    dropped_streams = run_keeping_subtitles(cmd, output)

    result = probe(output)
    v = result["video"]
    info(f"wrote {output} ({fmt_secs(result['duration'])}, {v['width']}x{v['height']}, {v['codec']}, crf {args.crf})")
    emit(output, dropped_non_av_streams=dropped_streams)
    return 0


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