Reel speed ramps
One project file, five commands, all local (ffmpeg + Python). The script is scripts/reel.py; the example is examples/project.json.
Rules that make it work
- The voice-over is sacred: always 1x. Measure where the voice is on the Demucs vocal stem of each scene. The ramp blends back to 1x 0.35 s around it.
- Ramp the shots without voice, never the whole clip at once. Use one mode per shot:
c: fast in the middle (default, 2–3.2x peak).k: fast at the edges and 1x at the key moment (jumps, tricks, impacts).n: real speed. Use it for people walking: walking looks broken when sped up.
- The song decides the cuts. Pick cut times on the beat grid, put
target_frameson each scene and let the script scale the ramp intensity until the scene lands on that exact frame. - Lyrics never on top of the voice. AI music tools (Flow Music, Suno, Dreamina) ignore requested timing and "no vocals here" sections. So:
- Split the song with Demucs.
- Get word timings with Whisper.
- Move each sung line by a whole number of beats into a gap between voice lines. Whole beats keep it on time.
- Duck the music 14 dB under the voice-over (6 dB is not enough on a phone). Mix to −14 LUFS and add a limiter, because AAC encoding pushes peaks over 0 dBFS.
Workflow
-
python scripts/reel.py measure scene1.mp4: prints the voice windows and the detected shots (with a suggested peak per shot) as JSON for the project file. Look at a contact sheet and fix the modes (kfor jumps,nfor walking). Check the voice windows by ear, because sound effects can sneak in. -
python scripts/reel.py ramps project.json: first pass withouttarget_frames, to see the new length. Show it to the user without music before going on. -
Write the song prompt from the new timeline: BPM chosen so 4 bars ≈ one scene, sections, the drop on the edit's hit, and lyrics in the language asked. Generate it (ask before spending credits).
-
python scripts/reel.py song song.wav --lyrics: gives the tempo, the beat, drop candidates, the stems and each line with its time. -
Fill
musicin the project:song_drop: the drop's second in the song.beat.lines, each withstart,end,shift_beats.
Set
target_framesso every cut lands on a beat: cut time = drop − k × beat. -
rampsagain, thenmusic. It warnsCLASHES WITH VOICEif a line overlaps a voice; changeshift_beatsuntil it doesn't. Thenassemble project.json out.mp4. -
Check the result:
- a contact sheet;
- Whisper on the final mix (every voice line must come out clean);
- −14 LUFS and the peak below −1 dBFS.
Tail pieces
After the ramped scenes, tail adds pieces in order:
- part of a clip at 1x with its own sound (
volume); - a clip slowed down with a push-in (
slow,push_in); - a PNG sequence (an end card rendered in Remotion, After Effects…).
Requirements
Python 3.10+, ffmpeg on PATH, pip install -r requirements.txt (numpy, scipy, soundfile, opencv-python, librosa, demucs, openai-whisper).
Case: Nike spec reel (2026)
- Scenes: four AI scenes of 10 s plus a sneaker burst; each scene ends on an avatar voice line.
- Ramps: the scenes went from 40 s to 28.3 s with every voice line untouched, and the reel from 48 s to 36.3 s. Walking shots stayed at 1x after the client's note.
- Song: generated in Flow Music, 150 BPM, 5 credits, English lyrics. It came back 67 s long and rapping non-stop. Five lines were moved by whole beats into the voice gaps. The chorus lands on the drop, which is the cut to the product burst.
- Client verdict: «much better».