FFmpeg Tile Filter: Grid, Margin, and Padding Guide

This guide explains how to configure the tile filter in FFmpeg to arrange consecutive video frames or images into a structured mosaic. You will learn the exact syntax for defining the grid layout (columns and rows), adding outer margins, adjusting inner padding between frames, and setting the background color of the canvas.

Understanding the tile Filter Syntax

The FFmpeg tile filter places incoming video frames side by side into a single output frame. The core parameters controlling the layout geometry are:

  • layout: The grid dimensions specified as ColumnsxRows (e.g., 3x2 for 3 columns and 2 rows). If not fully specified, it defaults to 6x5.
  • margin: The outer border thickness around the entire grid, defined in pixels (default is 0).
  • padding: The space between individual tiles, defined in pixels (default is 0).
  • color: The color of the space created by margin and padding (default is black).

You can configure these parameters using key-value pairs or positional arguments.

Basic Layout Configuration

To create a simple 3-column, 2-row grid without any spacing:

ffmpeg -i input.mp4 -vf "tile=layout=3x2" output.png

This takes six consecutive frames from input.mp4 and renders them into a single image arranged in three columns across two rows.

Setting Margins, Padding, and Background Color

To add space between frames and around the border of the canvas, combine margin, padding, and color:

ffmpeg -i input.mp4 -vf "tile=layout=3x2:margin=30:padding=10:color=white" output.png

In this command:

  • layout=3x2 arranges 6 frames into a 3×2 grid.
  • margin=30 adds a 30-pixel border around the outer edges of the resulting image.
  • padding=10 creates a 10-pixel gap between each adjacent frame.
  • color=white sets the color of both the 30px margin and the 10px padding to white. You can specify standard color names (e.g., black, red, blue) or hexadecimal values (e.g., 0x1A1A1A).

Output Dimension Calculation

When you apply margins and padding, FFmpeg automatically expands the output dimensions to fit. The resulting canvas dimensions are calculated as follows:

  • Output Width = (Columns * Tile_Width) + ((Columns - 1) * Padding) + (2 * Margin)
  • Output Height = (Rows * Tile_Height) + ((Rows - 1) * Padding) + (2 * Margin)

For example, if each input frame is 640x360 pixels in a 3x2 grid with padding=10 and margin=20:

  • Width: (3 * 640) + (2 * 10) + (2 * 20) = 1920 + 20 + 40 = 1980 pixels.
  • Height: (2 * 360) + (1 * 10) + (2 * 20) = 720 + 10 + 40 = 770 pixels.

Scaling Down Tiles Before Tiling

Tiling full-resolution video frames can create very large output images. To control the final size, insert the scale filter before the tile filter:

ffmpeg -i input.mp4 -vf "scale=320:-1,tile=layout=4x3:margin=15:padding=5:color=0x333333" -frames:v 1 contact_sheet.png

This scales each frame down to a width of 320 pixels (preserving aspect ratio) before tiling them into a 4×3 grid with a 15-pixel dark gray border and 5-pixel dividers.