To make an FFmpeg contact sheet fit a review canvas, choose the cell size and grid first, then calculate the outer margin and space between cells. Set nb_frames to control how many frames the tile filter renders in the grid, decide how unused area should look, and check frame-rate handling so duplicated output frames are not mistaken for distinct samples. The tile filter arranges successive frames into a static grid; it is not a layout for playing several video inputs side by side.
Plan the canvas and build the sheet
Use these steps when the output has a maximum canvas size or the reviewer needs a fixed grid:
- Set the review goal and canvas limit. Decide whether each cell should show composition, action detail, or both. Pick a cell width and height that retain the detail you need; the
scalefilter can set those dimensions, but forcing both dimensions may change the displayed proportions. Check the FFmpeg scale documentation before choosing a resizing approach. - Choose columns and rows. Capacity is columns multiplied by rows. For N planned frames, choose a capacity at least N, unless you intentionally want to omit frames. Calculate canvas width as columns × cell width + 2 × margin + (columns − 1) × padding. Calculate height the same way using rows and cell height. Here,
marginis the outer border;paddingis the gap between frames. - Set the frame budget.
nb_framesis the maximum number of frames rendered in the grid and must not exceed its cell capacity. A value below capacity leaves unused area; the filter'scoloroption controls that area, with black as the documented default. Choose a contrasting color if empty cells must be easy to distinguish, but do not treat color alone as proof that a cell is unused. - Decide how frames enter the filter. FFmpeg's documented keyframe example uses
-skip_frame nokey, scales frames, and then appliestile. Its example also uses-fps_mode passthroughbecause ordinary frame-rate adaptation can duplicate output frames to match the detected input rate. Select the mode for the intended sampling, then verify the resulting image sequence and frame content rather than assuming every tile is a unique moment. See the FFmpeg tile documentation.
For example, suppose a hypothetical review needs 35 frames, with a 6 × 6 grid, 160 × 90-pixel cells, a 2-pixel outer margin, and 4-pixel gaps. Capacity is 36, so one cell is unused. The planned canvas is 6 × 160 + 2 × 2 + 5 × 4 = 978 pixels wide, and 6 × 90 + 2 × 2 + 5 × 4 = 558 pixels high. This is arithmetic for the stated assumptions, not a measurement of FFmpeg output. If the unused cell blends into a dark scene, select a more visible fill color and record that the final cell is intentionally empty.
Acceptance worksheet
Use this hypothetical worksheet to compare the intended layout with the delivered files. It records observations and decisions; it does not guarantee a particular output count or image appearance.
| Check | Hypothetical observation | Decision |
|---|---|---|
| Grid capacity | 6 × 6 = 36 cells; 35 frames requested | One cell is available for unused area |
| Canvas calculation | 978 × 558 pixels from the stated cells, margin, and gaps | Compare the exported image dimensions against the planned canvas |
| Frame budget | nb_frames planned as 35 | Record the setting and inspect whether the last cell is visibly unused |
| Output sequence | Record file names, image numbers, and selected frame-rate mode | Check for repeated-looking frames before calling them distinct samples |
| Empty area | Fill color recorded as a chosen contrast color | Treat the fill as a visual cue; confirm the cell contains no frame |
Limits and next steps
A grid that fits the canvas does not establish that its samples represent the whole clip. Keyframe selection, frame-rate conversion, and the input itself affect what appears. If adjacent tiles look identical, compare their visible content and timestamps or frame identifiers where available; label duplicates as possible repeats until checked. Do not report them as distinct keyframes merely because they occupy different cells.
If the canvas dimensions differ from the plan, recheck cell dimensions, grid dimensions, margin, and padding, then inspect the actual exported image. The documentation defines the options and constraints, but does not promise that a particular encode, pixel format, or output workflow will meet a separate delivery specification. If empty cells are hard to recognize, change the fill color or choose a grid whose capacity matches the intended frame count. tile makes a still contact sheet from successive frames; it does not synchronize multiple inputs or guarantee even temporal sampling.
Does `nb_frames` mean the number of grid cells?
No. It is a maximum frame count for the tiled area and cannot exceed the grid capacity. If it is lower than capacity, the remaining area is unused.
Will each cell show a unique keyframe?
Not necessarily. Check frame selection and output frame-rate behavior. FFmpeg documents passthrough mode in its keyframe example to avoid duplicating output frames for frame-rate accommodation.
What if the planned canvas is too large?
Reduce cell dimensions, columns or rows, or the margins and gaps, then recalculate both dimensions. Keep enough detail for the review task; there is no universally suitable cell size.
Sources and next step
This guide interprets public documentation and uses explicitly hypothetical acceptance examples, not application tests. Controls and availability can change; verify the cited manual against your installed version.
For work created in Imagild, carry the input requirements and acceptance checklist into the film workspace. The external software controls discussed above belong to their respective products.