ffmpeg -vf: Extract Frames and Thumbnails
ffmpeg -ss 00:00:05 -i in.mp4 -frames:v 1 thumb.png grabs one frame at 5 seconds as a thumbnail.
Generating a poster image or sampling frames for visual diffing is common in CI. The trick is combining a seek (-ss) with a frame count or fps filter.
What it does
ffmpeg decodes the video and writes image files instead of a video stream. -frames:v 1 stops after one frame (a thumbnail); a -vf fps= filter samples frames at an interval; a %d pattern in the output name produces a numbered sequence.
Common usage
# single thumbnail at 5s (fast seek before -i)
ffmpeg -ss 00:00:05 -i in.mp4 -frames:v 1 thumb.png
# one frame per second to a numbered sequence
ffmpeg -i in.mp4 -vf fps=1 frame_%04d.png
# smart thumbnail: the most representative frame in the first 100
ffmpeg -i in.mp4 -vf "thumbnail=100" -frames:v 1 poster.pngOptions
| Flag | What it does |
|---|---|
| -ss <time> | Seek to a timestamp (before -i = fast, after -i = accurate) |
| -frames:v <n> | Output only N video frames |
| -vf fps=<r> | Filter: keep r frames per second |
| -vf "thumbnail=<n>" | Pick the most representative frame from n |
| -vf scale=<w>:<h> | Resize the extracted frame |
| -q:v <n> | Quality for JPEG output (2 is high, 31 is low) |
In CI
Put -ss before -i for a fast keyframe seek when exact timing does not matter (poster images); put it after -i for frame-accurate seeking. Use a %04d pattern so frames sort correctly in later steps.
Common errors in CI
An empty or 0-byte output usually means -ss seeks past the end of the clip; check the duration with ffprobe. "Output file is empty, nothing was encoded" appears when -frames:v is 0 or the filter dropped every frame. "Could not open file" on a %d pattern means the output directory does not exist; mkdir -p it first.