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.

6.0 KB
Raw Blame
#!/usr/bin/env python3
"""Step through different constant speeds across a clip's timeline (a speed ramp).

Distinct from fit.py --duration --method speed, which applies one constant
factor to the whole clip. This tool takes a list of --segment START-END:FACTOR
pieces covering the clip start to end with no gaps or overlaps, each played
at its own constant speed (pitch-preserving audio, matching fit.py), then
concatenates them back together -- the classic "speed up, then slow way
down for the punch, then speed back up" edit, built from a few constant
segments rather than a continuous curve (which this tool does not attempt:
picking exactly where a ramp should ease in or out is a judgement call for
the calling agent, made concrete here as segment boundaries it supplies).

Examples:
  python3 speedramp.py action.mp4 --segment 0-3:1.0 --segment 3-4:0.25 --segment 4-8:2.0
  python3 speedramp.py clip.mp4 --segment 0-2:2.0 --segment 2-6:1.0
"""
import argparse
import sys
from typing import List, Tuple

from _common import add_common, apply_common, aac_args, default_output, die, emit, ffmpeg_base, info, probe, run, video_args, X264_PRESETS, fmt_secs, time_arg

MAX_SPEED = 20.0
MIN_SPEED = 0.05


def atempo_chain(factor: float) -> str:
    """atempo accepts 0.5..100 per instance; chain for factors outside that range."""
    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 parse_segment(raw: str) -> Tuple[float, float, float]:
    try:
        span, factor_s = raw.rsplit(":", 1)
        start_s, end_s = span.rsplit("-", 1)
        factor = float(factor_s)
    except ValueError:
        die(f"--segment must look like START-END:FACTOR, got '{raw}'")
    start, end = time_arg(start_s, f"--segment {raw!r} start"), time_arg(end_s, f"--segment {raw!r} end")
    if end <= start:
        die(f"--segment {raw}: END must be after START")
    if not MIN_SPEED <= factor <= MAX_SPEED:
        die(f"--segment {raw}: FACTOR must be {MIN_SPEED}..{MAX_SPEED}")
    return start, end, factor


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>_ramp.<ext>)")
    ap.add_argument("--segment", action="append", required=True, dest="segments",
                     help=f"START-END:FACTOR, repeatable; segments must cover 0..duration with no gaps or overlaps, in order. FACTOR is {MIN_SPEED}..{MAX_SPEED} (2.0 = twice as fast, 0.5 = half speed)")
    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)

    segments = [parse_segment(s) for s in args.segments]
    segments.sort(key=lambda s: s[0])
    meta = probe(args.input)
    if not meta.get("video"):
        die("input has no video stream")
    dur = meta.get("duration") or 0.0
    if abs(segments[0][0] - 0.0) > 0.01:
        die(f"segments must start at 0, first segment starts at {segments[0][0]:g}")
    if abs(segments[-1][1] - dur) > 0.5:
        die(f"segments must cover the whole clip (0..{dur:.3f}), last segment ends at {segments[-1][1]:g}")
    for i in range(len(segments) - 1):
        if abs(segments[i][1] - segments[i + 1][0]) > 0.01:
            die(f"segments must be contiguous with no gap/overlap: segment {i} ends at {segments[i][1]:g}, "
                f"segment {i + 1} starts at {segments[i + 1][0]:g}")
    has_audio = bool(meta.get("audio"))
    output = args.output or default_output(args.input, "ramp")

    vparts, aparts, labels = [], [], []
    # The coverage check above allows the last end to sit up to 0.5 s off the probed duration.
    # That slack is for a caller who rounded the duration, not a reason to redraw the tail at
    # the last factor. The end bound is omitted only when the stated end is the file's end
    # (within 50 ms): a trim a few milliseconds short of the last packet drops that packet.
    last_runs_to_eof = abs(segments[-1][1] - dur) <= 0.05
    for i, (start, end, factor) in enumerate(segments):
        vlabel, alabel = f"v{i}", f"a{i}"
        end_expr = f"{end:.3f}" if not (i == len(segments) - 1 and last_runs_to_eof) else None
        trim = f"trim=start={start:.3f}" + (f":end={end_expr}" if end_expr else "")
        vparts.append(f"[0:v]{trim},setpts=(PTS-STARTPTS)/{factor:.6f}[{vlabel}]")
        labels.append(f"[{vlabel}]")
        if has_audio:
            atrim = f"atrim=start={start:.3f}" + (f":end={end_expr}" if end_expr else "")
            aparts.append(f"[0:a]{atrim},asetpts=PTS-STARTPTS,{atempo_chain(factor)}[{alabel}]")

    if has_audio:
        concat_inputs = "".join(f"[v{i}][a{i}]" for i in range(len(segments)))
        fc = ";".join(vparts + aparts) + f";{concat_inputs}concat=n={len(segments)}:v=1:a=1[outv][outa]"
        maps = ["-map", "[outv]", "-map", "[outa]"]
    else:
        concat_inputs = "".join(f"[v{i}]" for i in range(len(segments)))
        fc = ";".join(vparts) + f";{concat_inputs}concat=n={len(segments)}:v=1:a=0[outv]"
        maps = ["-map", "[outv]"]

    cmd = ffmpeg_base() + ["-i", args.input, "-filter_complex", fc] + maps
    cmd += video_args(meta, args.crf, args.preset)
    cmd += ["-fps_mode", "cfr", "-r", f"{meta['video'].get('fps') or 30.0:g}"]
    if has_audio:
        cmd += aac_args()
    else:
        cmd += ["-an"]
    cmd.append(output)
    run(cmd)

    result = probe(output, role="output")
    v = result["video"]
    info(f"wrote {output} ({fmt_secs(result['duration'])}, {v['width']}x{v['height']}, {len(segments)} speed segments)")
    emit(output, dropped_non_av_streams=bool(meta.get("subtitle_streams") or meta.get("data_streams")))
    return 0


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