Extracting Thumbnails from Video — -vframes and the thumbnail Filter

There are several ways to generate thumbnail images from video. This page organizes and explains FFmpeg 6.1-verified commands by use case.

Basic: Extracting a Single Frame at a Specific Timestamp

The simplest method is to specify a seek position with -ss and limit the output to one frame with -vframes 1.

ffmpeg -i input.mp4 -ss 00:00:01 -vframes 1 thumbnail.jpg

• -ss 00:00:01 — Seek to 1 second from the start
• -vframes 1 — Limit output to 1 frame (equivalent to -frames:v 1)
• Output format is automatically determined by the file extension (JPEG here)

About -ss placement: Placing it before -i enables fast keyframe seeking but may be slightly less accurate. Placing it after -i seeks to the exact position but can take time for long videos. For thumbnail generation, placing it before -i is common.

To output as PNG:

ffmpeg -i input.mp4 -ss 00:00:01 -vframes 1 thumbnail.png

PNG uses lossless compression and produces higher quality but larger file sizes than JPEG.

Extracting Multiple Frames at Regular Intervals

Using the -vf fps=1 filter, you can extract one frame per second as sequentially numbered files.

ffmpeg -i input.mp4 -vf fps=1 frame%03d.jpg

Sequential numbering patterns like %03d are shown as text blocks since they are outside the CI output file rewrite rules.

Examples with different intervals:

# One frame every 5 seconds
ffmpeg -i input.mp4 -vf fps=1/5 frame%03d.jpg

# One frame every 10 seconds
ffmpeg -i input.mp4 -vf fps=1/10 frame%03d.jpg

To specify an output directory, include the path like frames/frame%03d.jpg (the directory must be created in advance).

The thumbnail Filter — Automatic Representative Frame Selection

The thumbnail filter automatically selects a “representative frame” with minimal histogram variation within a specified range. It generates a thumbnail that appropriately reflects the video content in a single command.

ffmpeg -i input.mp4 -vf thumbnail -vframes 1 thumbnail.jpg

By default, it analyzes 100 frames per group and selects the most representative frame within that group. To change the group size:

ffmpeg -i input.mp4 -vf thumbnail=300 -vframes 1 thumbnail.jpg

A larger value selects from a wider range but increases processing time.

Extracting Thumbnails with Resolution Specification

Combine -vf scale=width:height to resize at the same time as extraction.

ffmpeg -i input.mp4 -ss 00:00:05 -vframes 1 -vf scale=320:180 thumb.jpg

To specify only the width while maintaining the aspect ratio, use -1:

ffmpeg -i input.mp4 -ss 00:00:05 -vframes 1 -vf scale=320:-1 thumb.jpg

-1 means “calculate automatically while preserving aspect ratio”. However, if -1 results in an odd number of pixels, it may cause an encoder error. In that case, use -2 instead (rounds to an even number).

To combine the thumbnail filter with scale, connect them with a comma:

ffmpeg -i input.mp4 -vf "thumbnail,scale=320:180" -vframes 1 thumb.jpg

Choosing Between JPEG and PNG

JPEG compression quality can be controlled with -q:v (2–31, lower values mean higher quality):

ffmpeg -i input.mp4 -ss 00:00:01 -vframes 1 -q:v 2 thumbnail.jpg

Common Issues

Extracted frame is black or green
Depending on the codec, -ss may snap to a keyframe. Moving -ss to after -i may improve this.

ffmpeg -i input.mp4 -ss 00:00:05 -vframes 1 thumbnail.jpg

The thumbnail filter is slow
If the default 100-frame analysis is heavy, reduce the value, such as thumbnail=30.

Summary

Related Articles:

• Scaling Video
• Creating Slideshows and Timelapses

Tested with: ffmpeg 6.1.1 / Ubuntu 24.04 (GitHub Actions runner)
Primary sources: ffmpeg.org/ffmpeg.html / ffmpeg.org/ffmpeg-filters.html / trac.ffmpeg.org/wiki