How to Use FFmpeg Tile Filter for Video Grids

This article explains how to use the FFmpeg tile filter to arrange consecutive video frames into a single grid layout. You will learn the basic syntax, key parameters for customizing grid dimensions, and practical examples for generating contact sheets or storyboard images from your video files.

Understanding the Tile Filter

The tile filter in FFmpeg takes a sequence of consecutive video frames and merges them into a single, larger frame styled as a grid. This is highly useful for creating video storyboards, preview thumbnails, or visual contact sheets.

Basic Syntax

The fundamental syntax for the tile filter is:

-vf "tile=columnsxrows"

For example, to create a grid with 3 columns and 2 rows, you would use:

-vf "tile=3x2"

By default, FFmpeg fills the grid from left to right, top to bottom, using successive frames from the input stream.

Practical Examples

1. Creating a Simple 3x3 Grid

To capture consecutive frames and output them into a single 3x3 grid image, run the following command:

ffmpeg -i input.mp4 -vf "tile=3x3" -frames:v 1 output.png
  • -vf "tile=3x3": Instructs FFmpeg to create a 3-column, 3-row grid.
  • -frames:v 1: Tells FFmpeg to stop processing once the first tiled output frame (which contains 9 input frames) is complete.

2. Spacing Out the Frames (Creating a Storyboard)

If you tile consecutive frames, the resulting grid images will look almost identical because video frames occur milliseconds apart. To create a meaningful storyboard, you should space out the frames using the select filter before tiling:

ffmpeg -i input.mp4 -vf "select='not(mod(n,100))',scale=320:-1,tile=4x3" -frames:v 1 output.png
  • select='not(mod(n,100))': Selects every 100th frame of the video.
  • scale=320:-1: Downscales each selected frame to a width of 320 pixels (while maintaining aspect ratio) so the final grid image is not excessively large.
  • tile=4x3: Places the 12 selected, scaled frames into a 4x3 grid.

Customizing Grid Appearance

You can further customize the layout of your grid using additional parameters inside the tile filter:

  • nb_frames: Limits the number of frames to render in the grid (useful if you want to stop before filling the entire grid).
  • margin: Adds an outer border (in pixels) around the entire grid.
  • padding: Adds spacing (in pixels) between the individual frames.
  • color: Defines the color of the margin and padding areas (default is black).

Advanced Grid Example

The following command creates a 5x5 grid, adds 10-pixel padding between frames, a 20-pixel outer margin, and sets the background color to white:

ffmpeg -i input.mp4 -vf "scale=200:-1,tile=5x5:padding=10:margin=20:color=white" -frames:v 1 output.png