When you want a moment in a video to play in slow motion exactly at a chosen timestamp, you need more than a simple cut. A speed ramp gradually changes playback speed, keeping the flow natural and avoiding abrupt jumps. The challenge is aligning the slowed moment with the desired output time, because slowing stretches the clip. This article walks through the math behind the timing, demonstrates a Python script that plans the trim and speed tweens, and explains how to render the final clip with Shotstack’s Edit API. It also covers practical tweaks for frame rate, easing, and audio handling, so you can adapt the approach to any footage.
Context and practical value
The source explains how to use Python to calculate trim points and speed tweens for a speed ramp, then render the clip with Shotstack’s Edit API. It details the math for timing, provides a full script, and discusses testing, easing, frame rate, and audio considerations.
This article distills the source’s technical steps into a concise guide, adds a clear explanation of the underlying math, and expands on practical deployment tips such as environment setup, audio handling, and troubleshooting common timing issues. It also frames the discussion for a community forum, encouraging knowledge sharing beyond the original tutorial.
Key takeaways
- Speed ramps use an array of tweens that define from‑to rates, start times, and lengths.
- The trim point is calculated by subtracting the source seconds that will play before the target moment.
- Linear or symmetric easing (e.g., easeInOut) gives the same source‑to‑output mapping as a straight ramp.
- Shotstack’s Edit API keeps the clip length fixed; the speed array determines how much source is consumed.
- Python’s standard library is enough to build the plan and submit the render request.
- Testing frame‑by‑frame confirms the planned moment lands within one frame of the target.
- Audio pitch changes with speed; mute the source or add separate tracks if you need consistent sound.
Understanding Speed Ramps
A speed ramp is a gradual change in playback speed within a single clip. Instead of cutting from normal speed to slow motion, the ramp eases down over a fraction of a second, holds the slow rate, then eases back up. The Edit API represents a ramp as an array of tweens, each with a from‑rate, to‑rate, start time, length, and optional easing. The clip’s total length stays the same; the speed array determines how many source seconds are played in that time.
Timing the Moment
Two simple rules let you predict where a moment will land:
- A constant rate r for d seconds consumes r×d source seconds. 2. A ramp from a to b over d seconds consumes d×(a+b)/2 source seconds (the average rate). Using these, you can compute how much of the source will play before the desired output second, then set the trim so the target frame aligns exactly.
Python Planning Function
The core of the script is the plan() function. It receives the source moment, the desired output second, the before/slow/after rates, ramp and hold durations, and the source length. It calculates:
- When the ramp down starts. - How many source seconds are consumed before the moment. - The trim offset. - The total clip length. - The array of tweens, rounded to three decimals. The function raises clear errors if the requested timing is impossible (e.g., the moment is too early or the footage ends too soon).
Practical next steps
- 1. Install a Shotstack account and set
SHOTSTACK_API_KEYin your environment. 2. Run the script with the desired parameters; use--dry-runto inspect the JSON before rendering. 3. Verify the output by downloading the rendered MP4 and checking that the target frame appears at the expected timestamp. 4. For smoother slow motion, use higher‑fps footage (e.g., 60 fps) and set the output FPS accordingly. 5. If the clip contains audio, mute the source asset or add a separate audio track to avoid pitch shifts. - Open the original source and verify its prerequisites, workflow, and current product behavior before adopting it.
- Test the approach on a small non-production example and record the inputs, output quality, runtime, and failure modes.
Limits and verification
- The calculation assumes linear or symmetric easing; non‑symmetric easing (e.g., easeIn) can shift the moment by a frame. The script rounds the clip length to whole frames, which may truncate the last frame of the source. Shotstack’s Edit API does not support audio pitch correction, so audio will automatically change pitch with speed changes.
FAQ
How do I find the exact timestamp of the moment I want to slow down?
Scrub the video in any player, note the rough second, then extract a few frames around that point using Shotstack’s Probe endpoint or a local tool. Convert the frame number to seconds with the frame rate to pinpoint the exact moment.
Can I freeze the moment instead of slowing it?
Yes. Set the slow rate to 0 and the hold duration to the desired freeze length. The ramp from 1x to 0x will consume half its length in source seconds, keeping the frame on screen for the full hold.
What if I need multiple slow sections in one clip?
Add more tweens to the speed array. Each additional ramp will push later moments further back, so you must recalculate the trim and total length for the entire sequence.