What does speed-ramp do?
All scripts live in this skill's base directory (shown as "Base directory for this skill" when loaded).
Call them by full path; write outputs to the user's project with -o (never into the skill folder).
python3 on macOS/Linux, python on Windows. Needs ffmpeg 7+ on PATH (velocity uses -/filter_complex; the
old -filter_complex_script is gone in newer ffmpeg). Python 3.10+, standard library only. Nothing here uses the
network or needs a key.
Pick the edit
| Footage / vibe | Tool | Why |
|---|---|---|
| Several different angles/shots + an energetic song | velocity.py | each shot slow, whips to peak on every beat, the CUT hides in the blur |
| One continuous take (or AI clips chained last frame to first frame), calm / cool | hero_whip.py | 1.0x → hero slow-down → ONE whip on a real beat; no jump cuts |
| One clip, a single smooth dip | speed_ramp.py | raised-cosine bell (e.g. 100% → 85% → 100%) |
| Try shapes by eye | ramp_ui.py → http://127.0.0.1:8765 | live preview in the browser, renders with ffmpeg |
Never velocity-cut one continuous take: overlapping in-points replay motion backwards and it reads as a glitch.
Rules that make it look good
- Slow-mo needs real frames. AI and phone clips are 30 fps; slowing by duplicating frames stutters
(40% ≈ 12 real fps).
hero_whip.pyinterpolates to 120 fps first (--interp 120, default). For velocity on 30 fps sources, keep--low≥ 0.5 or interpolate the source first withffmpeg -i in.mp4 -vf "minterpolate=fps=120:mi_mode=mci:mc_mode=aobmc:me_mode=bidir:vsbmc=1" in120.mp4. - Land whips on the song's real beats, not an invented BPM. Give beat times with
--beats-json(a JSON file with a list of seconds ataudio.music.beats, from any beat detector) or--bpm+--beat-offset.--sound-start= where in the song the video starts. - Less is cooler. One hero + one whip beats six whips for a calm vibe. Put the slow hold on the key moment (arms opening, a turn, a face), the whip into the next action.
- Outputs are silent: add the song in the editor afterwards, starting at 0.
- Check by eye: contact sheet
ffmpeg -i out.mp4 -vf "fps=4,scale=150:-1,tile=12x2" -frames:v 1 sheet.jpg.
Commands
# hero + whip on two chained clips, whip on the song's beat
python3 <skill>/hero_whip.py clip1.mp4 clip2.mp4 --chain --down-at 7.4 --hold-end 9.2 \
--beats-json beats.json --size 720x1280 -o renders/hero.mp4 # add --dry-run first
# velocity edit: shots as clip@in_seconds, 1 shot per N beats
python3 <skill>/velocity.py --bpm 129.2 --beats-per-shot 2 --low 0.5 --peak 3 \
a.mp4@0 [email protected] [email protected] --size 1080x1920 -o renders/velocity.mp4 # --dry-run / --quick
# preset shapes on one clip: hero, bullet, montage, flash_in, flash_out, jump
python3 <skill>/velocity.py clip.mp4@0 --preset hero --param slow=0.3 -o renders/hero_preset.mp4
# single bell dip
python3 <skill>/speed_ramp.py in.mp4 out.mp4 --min 0.85 --center 5 --width 4
The three edit scripts take --help and --dry-run (prints the plan without rendering).
hero_whip.py prints whip_peak_out, the matched beat and beat_error_ms - report them.
If the whip feels early or late, move it a beat with --hold-end ± (beat × slow).
The preview UI
python3 <skill>/ramp_ui.py serves a page on http://127.0.0.1:8765 (this machine only; change with PORT).
It lists video files from the top level of ~/Downloads, ~/Movies and ~/Desktop, takes any other path typed in,
previews the ramp live, and renders into a renders/ folder next to the script.
Extending it
The curves are plain Python: speed_at and the PRESETS shapes in velocity.py, the bell in speed_ramp.py.
A new look is a new speed function of time; the render path (integrate the curve, retime, shutter blur, exact frame
count) stays the same.