Configure Search Window in FFmpeg Thumbnail Filter

The FFmpeg thumbnail filter selects the most representative frame from a sequence of video frames by analyzing color histograms. This guide explains how to configure the search window size parameter (n), which determines the number of consecutive frames analyzed before a single representative frame is chosen and output.

The Window Size Parameter

The thumbnail filter accepts a single parameter, n, which specifies the search window size. The default value is 100 frames. When processing a stream, the filter buffers n frames, calculates the color histogram for each, selects the frame with the smallest distance from the average histogram, and drops the rest.

The basic syntax is:

thumbnail=n

Alternatively, you can use the named key-value syntax:

thumbnail=n=300

Practical Usage Examples

1. Extract One Thumbnail Every 300 Frames

To increase the search window from the default 100 frames to 300 frames and output all selected frames as an image sequence:

ffmpeg -i input.mp4 -vf "thumbnail=300" -vsync 0 output_%03d.png

In this command:

  • thumbnail=300 sets the search window size to 300 frames.
  • -vsync 0 prevents frame duplication or dropping, ensuring only the selected frames are written to disk.

2. Extract a Single Representative Frame for the Whole Video

To pick one representative frame from a larger block of time (for instance, a 500-frame window) and stop processing after writing the first match:

ffmpeg -i input.mp4 -vf "thumbnail=500" -frames:v 1 best_thumbnail.jpg

Here, -frames:v 1 halts the encoding process after the first frame selected from the 500-frame window is written.

3. Combining Window Size with Specific Time Intervals

If you want to evaluate a specific number of frames sampled at a specific frame rate, combine the fps filter with thumbnail:

ffmpeg -i input.mp4 -vf "fps=10,thumbnail=50" -vsync 0 thumb_%03d.jpg

This first downsamples the video to 10 frames per second, then analyzes a window of 50 frames (representing 5 seconds of real-time video) to choose the best frame.

Configuration Considerations

  • Memory Usage: The filter stores n frame histograms and references in memory. Setting an excessively large value (e.g., thousands of frames) will increase RAM consumption.
  • Accuracy vs. Variety: A smaller n (e.g., 25 or 50) produces more frequent thumbnails that capture rapid scene changes. A larger n (e.g., 300 to 1000) provides a broader statistical sample to avoid blurry transition frames or blank screens, but generates fewer output images.