Contents
A freeze frame stops a video on one moment and holds it there: a rider at the top of a jump, the ball crossing the line, a face just before the punchline. Then the video carries on.
This guide adds a freeze frame to a video with Python and Shotstack’s video editing API. One script freezes the moment you choose, holds it and shows a title over it. A second makes a set of highlight clips from a list of moments. The last part covers FFmpeg, and what it does to the sound.
TL;DR
- A video clip freezes while its
speedis0. Three speed tweens play the video, hold the frame, then play the rest. - The script below froze a 5.68 second BMX clip at 1.6 seconds for 2 seconds. The result is 7.68 seconds long.
- In a test clip with numbered frames, a 2 second hold at 30 fps added exactly 60 frames, and every frame of the source still played.
- A second script reads a list of videos, moments and titles. Its three highlight clips took 3 to 8 seconds each to render.
- FFmpeg’s
loopfilter freezes the picture only. An 8 second clip came out with 10 seconds of video and 8 seconds of sound.
How a freeze frame works with the API
In a Shotstack edit, a video clip has a speed setting. When it’s an array of tweens, the speed can change through the clip. The animations guide says what zero does: “A speed of 0 freezes the current frame and a negative speed plays the video backwards.”
A freeze frame takes three tweens, one after the other:
- Play at a speed of
1, up to the moment you want to hold. - Hold at a speed of
0, for as long as the frame should stay. - Play at
1again, for the rest of the video.
The tweens touch, so the speed jumps straight from one value to the next. The clip’s length is the video’s length plus the hold. This clip freezes a 10 second video at 3 seconds, for 2 seconds:
{
"asset": {
"type": "video",
"src": "https://example.com/video.mp4",
"speed": [
{ "from": 1, "to": 1, "start": 0, "length": 3 },
{ "from": 0, "to": 0, "start": 3, "length": 2 },
{ "from": 1, "to": 1, "start": 5, "length": 7 }
]
},
"start": 0,
"length": 12
}The sound follows the speed, so it’s silent while the frame holds. The script below mutes the clip and plays music under the whole video instead.
Add a freeze frame with Python
The script freezes a 5.68 second clip of a BMX rider, hosted by Shotstack, at the top of a jump. It holds that frame for 2 seconds with a title over it, then lets the rider land.
You need Python 3 and nothing else. Set SHOTSTACK_API_KEY to the key from your Shotstack dashboard before you run it. Each render draws credits from your plan, as the pricing page lists.
import json
import os
import sys
import time
import urllib.error
import urllib.parse
import urllib.request
API = "https://api.shotstack.io/edit/v1"
ASSETS = "https://shotstack-assets.s3.ap-southeast-2.amazonaws.com"
SOURCE = f"{ASSETS}/footage/bmx.mp4"
MUSIC = "https://shotstack-assets.s3.amazonaws.com/music/unminus/lit.mp3"
FREEZE_AT = 1.6 # the moment to freeze, in seconds from the start of the video
HOLD = 2 # how long the frozen frame stays on screen, in seconds
TITLE = "Hang time" # text shown during the freeze; "" for no text
FRAME_RATES = (12, 15, 24, 25, 30, 48, 50, 60)
def call(url, body=None):
data = json.dumps(body).encode() if body is not None else None
headers = {
"x-api-key": os.environ["SHOTSTACK_API_KEY"],
"Content-Type": "application/json",
}
try:
request = urllib.request.Request(url, data, headers)
with urllib.request.urlopen(request) as response:
return json.load(response)
except urllib.error.HTTPError as error:
sys.exit(f"HTTP {error.code}: {' '.join(error.read().decode().split())[:300]}")
def probe(url):
"""Return the duration in seconds and the frame rate of a video at a URL."""
encoded = urllib.parse.quote(url, safe="")
metadata = call(f"{API}/probe/{encoded}")["response"]["metadata"]
video = next(s for s in metadata["streams"] if s["codec_type"] == "video")
top, bottom = video["avg_frame_rate"].split("/")
return float(video["duration"]), int(top) / int(bottom)
def build_edit(duration, fps):
after = round(duration - FREEZE_AT, 3)
total = round(duration + HOLD, 3)
video = {
"type": "video",
"src": SOURCE,
"volume": 0,
"speed": [
{"from": 1, "to": 1, "start": 0, "length": FREEZE_AT},
{"from": 0, "to": 0, "start": FREEZE_AT, "length": HOLD},
{"from": 1, "to": 1, "start": round(FREEZE_AT + HOLD, 3), "length": after},
],
}
music = {"type": "audio", "src": MUSIC, "effect": "fadeOut"}
tracks = [
{"clips": [{"asset": video, "start": 0, "length": total}]},
{"clips": [{"asset": music, "start": 0, "length": total}]},
]
if TITLE:
title = {
"type": "rich-text",
"text": TITLE,
"font": {"family": "Montserrat", "size": 56, "color": "#ffffff"},
"background": {"color": "#000000", "opacity": 0.6},
}
clip = {"asset": title, "start": FREEZE_AT, "length": HOLD}
clip.update({"width": 560, "height": 120, "position": "bottom"})
clip["offset"] = {"y": 0.1}
tracks.insert(0, {"clips": [clip]})
return {
"timeline": {"tracks": tracks},
"output": {"format": "mp4", "resolution": "hd", "fps": fps},
}
if __name__ == "__main__":
if not os.environ.get("SHOTSTACK_API_KEY"):
sys.exit("Set SHOTSTACK_API_KEY first.")
duration, source_fps = probe(SOURCE)
if not 0 < FREEZE_AT < duration:
sys.exit(f"FREEZE_AT must be between 0 and {duration:.2f} seconds.")
fps = min(FRAME_RATES, key=lambda rate: abs(rate - source_fps))
print(f"Source: {duration:.2f} s at {source_fps:g} fps")
print(f"Freezing at {FREEZE_AT:.2f} s for {HOLD:.2f} s")
render_id = call(f"{API}/render", build_edit(duration, fps))["response"]["id"]
print("Render queued:", render_id)
while True:
time.sleep(5)
status = call(f"{API}/render/{render_id}")["response"]
if status["status"] == "done":
break
if status["status"] == "failed":
sys.exit(f"Render failed: {status.get('error')}")
seconds, _ = probe(status["url"])
print(f"Video: {seconds:.2f} s")
print(status["url"])Run python freeze_frame.py. It prints the source’s length and frame rate, the moment it freezes, the render ID, the length of the result and the URL of the video:
Source: 5.68 s at 25 fps
Freezing at 1.60 s for 2.00 s
Render queued: 7f5b2c83-111a-4964-a9a0-e4e9e2bf4c99
Video: 7.68 s
https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/m4x7q2k9tz/7f5b2c83-111a-4964-a9a0-e4e9e2bf4c99.mp4Here’s the result:
How the script works
probe()sends the video’s URL to the Probe endpoint and returns its length and frame rate.build_edit()writes the three speed tweens fromFREEZE_ATandHOLD, and makes the clipHOLDseconds longer than the video.- The video clip’s volume is
0, and a second track plays the music with afadeOuteffect. - When
TITLEhas text, arich-textclip goes on the top track. It starts atFREEZE_ATand lasts forHOLDseconds, so it’s on screen only while the frame is frozen. - The title sits in a box 560 pixels wide and 120 tall. Make the box wider for a long title.
- The render keeps the source’s frame rate when it’s a whole number: this 25 fps clip comes out at 25 fps.
Choose the frame to freeze
FREEZE_AT is a time in the source video, in seconds. To see what happens at the frame level, here’s a 30 fps video with its 360 frames numbered from 0, frozen at 4 seconds for 2 seconds:
| Output frames | What they show |
|---|---|
| 0 to 120 | Source frames 0 to 120, at normal speed |
| 121 to 181 | Source frame 121, held |
| 182 to 419 | Source frames 122 to 359, at normal speed |
The output has 420 frames: the source’s 360 plus 60 for the 2 second hold. No source frame is dropped.
The frame that holds is the one right after FREEZE_AT: frame 121 for 4 seconds at 30 fps. A second test agrees: 2.5 seconds held frame 76. So to hold one exact frame, counting from 0, set FREEZE_AT to its number minus one, divided by the frame rate.
Hold the last frame
To freeze the end of a video, you don’t need a tween at all. Leave speed out and make the clip longer than the video. The last frame stays on screen for the extra time.
A 12 second video on a 14 second clip plays through once, then holds its final frame for 2 seconds.
Add freeze frames at scale
Highlight clips come in sets: every goal of a match, every trick of a session, every speaker at an event. The moment and the caption change from clip to clip, and the edit stays the same.
freeze_many.py below imports the first script, so save that one as freeze_frame.py. It reads a list with one line for each video: its URL, the second to freeze and the title to show. A moment that falls outside its video is skipped with a message.
import os
import sys
import time
import freeze_frame
FOOTAGE = "https://shotstack-assets.s3.amazonaws.com/footage"
# One job for each video: its URL, the moment to freeze and the title to show.
JOBS = [
(freeze_frame.SOURCE, 1.6, "Hang time"),
(f"{FOOTAGE}/skier.mp4", 3.0, "Hard turn"),
(f"{FOOTAGE}/skater.hd.mp4", 5.5, "Cruising"),
]
if not os.environ.get("SHOTSTACK_API_KEY"):
sys.exit("Set SHOTSTACK_API_KEY first.")
began = time.time()
renders = {}
for source, freeze_at, title in JOBS:
freeze_frame.SOURCE, freeze_frame.FREEZE_AT = source, freeze_at
freeze_frame.TITLE = title
duration, source_fps = freeze_frame.probe(source)
if not 0 < freeze_at < duration:
print(f"Skipped {title}: {freeze_at} s is outside its {duration:.2f} s video")
continue
fps = min(freeze_frame.FRAME_RATES, key=lambda rate: abs(rate - source_fps))
edit = freeze_frame.build_edit(duration, fps)
response = freeze_frame.call(f"{freeze_frame.API}/render", edit)
renders[response["response"]["id"]] = title
print(f"Queued {len(renders)} renders")
while renders:
time.sleep(5)
for render_id in list(renders):
url = f"{freeze_frame.API}/render/{render_id}"
status = freeze_frame.call(url)["response"]
if status["status"] in ("done", "failed"):
title = renders.pop(render_id)
result = status.get("url") or status.get("error")
print(
f"{time.time() - began:3.0f} s {title}: {status['status']} {result}"
)Run python freeze_many.py. Each line of output is one finished video: the seconds since the start, its title and its URL:
Queued 3 renders
20 s Hang time: done https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/m4x7q2k9tz/8e1d3464-990f-442d-a60c-f191f45ab86d.mp4
22 s Hard turn: done https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/m4x7q2k9tz/a8240ede-8c31-4288-a83c-178c2cb5f081.mp4
29 s Cruising: done https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/m4x7q2k9tz/ada17caa-3e5d-4070-aa7f-7fa1cc15d764.mp4The batch made 53 seconds of video: clips of 7.68, 16.12 and 29.38 seconds. The renders took between 3 and 8 seconds each, and the script had collected the last one 29 seconds after it started. This video plays the three side by side:
In a real pipeline the list comes from your data: a timestamp an editor marks, a name from your database for the title.
You don’t have to wait in a loop, either. Add a callback URL to the edit, and Shotstack sends your server a request when each render completes or fails. The webhooks guide shows how to set it up.
Add a freeze frame with FFmpeg
FFmpeg can hold a frame on your own machine with its loop filter. The filter counts in frames, so work the numbers out from the frame rate first. For a 25 fps video, 1.6 seconds is frame 40, and 2 seconds is 50 frames:
ffmpeg -i input.mp4 -vf "loop=loop=50:size=1:start=40" -an output.mp4The FFmpeg filters documentation describes the three options:
loop: “Set the number of loops.”size: “Set maximal size in number of frames.”start: “Set first frame of loop.”
So this command takes one frame, starting at frame 40, and repeats it 50 times. On the BMX clip it gives the same 192 frames and 7.68 seconds as the script above.
The loop filter works on the picture only. On an 8 second clip with sound, a 2 second freeze gave 10 seconds of video and 8 seconds of sound, so the sound runs ahead of the picture after the hold.
That’s why the command has -an, which leaves the sound out. To keep the sound, the audio needs 2 seconds of silence added at the same point, in a filter chain of its own.
With the API, the hold is set in seconds, and the music is part of the same render.
Hold the moment with Shotstack
A freeze frame is one speed tween at 0 between two at 1. The hold adds exactly the frames you ask for, the title shows only while the picture is still, and a list of moments becomes a set of clips in one run. Put your own videos, moments and titles in JOBS to make yours.
Get a free Shotstack API key and freeze your first frame.
Frequently asked questions (FAQs)
Can I freeze more than one moment in a video?
Yes. Add a hold tween and a play tween for each moment, and make the clip longer by the total of the holds. Tween times count along the clip, so a hold pushes every later moment back: after a 1 second hold, the source’s 6 second mark arrives at 7 seconds.
Can the video slow down into the freeze?
Yes. Put a tween from 1 to 0 in front of the hold, and the video eases to a stop. Our guide on how to speed ramp a video with Python works out how much of the source a ramp plays.
Can I save the frozen frame as an image?
Yes, with a separate render that outputs a JPG or PNG of that moment. Our guide on how to extract frames from a video shows the request.
Can I show more than a title during the freeze?
Yes. Any clip that starts at FREEZE_AT and lasts for HOLD seconds appears only on the frozen frame. Add an image clip for a logo or an arrow on a track above the video, the same way the script adds the title.