Creating a video mosaic — a grid of multiple videos playing simultaneously — is a common need in video production. Security surveillance, video conferencing, sports broadcasts, and social media content all use multi‑video layouts.
Traditionally, FFmpeg users built these layouts by chaining overlay filters with a nullsrc canvas. It works, but it's tedious, error‑prone, and hard to maintain.
The xstack filter changes that. It was designed specifically for stacking multiple video inputs into a custom layout[reference:0]. You define where each video goes, and xstack handles the positioning — no nullsrc, no nested overlays[reference:1].
Key takeaways
xstackstacks video inputs into custom layouts — mosaics, grids, collages.- No
nullsrcor nestedoverlaychains — cleaner and simpler[reference:2]. - All streams must have the same pixel format (e.g., yuv420p)[reference:3].
- Layouts use column‑major order by default, but can be customized[reference:4].
- Newer versions support a
gridoption for quick matrix layouts[reference:5]. - Built-in scaling — you can scale each input before stacking.
The Gap: Complex Mosaics Without the Headache
FFmpeg provides more than one way to create a video mosaic[reference:6]. The traditional method uses a nullsrc canvas and chains overlay filters for each video. It works for two or three videos, but quickly becomes unmanageable with four or more.
As the FFmpeg wiki notes, xstack "takes the individual inputs along with a custom layout that you create, and positions the videos according to the layout"[reference:7]. It figures out the positioning automatically based on your layout specification[reference:8].
This gap — between "I need a grid of videos" and "I don't want to write a 50‑line filtergraph" — is exactly what xstack fills.
(No nullsrc, no nested overlays — just a clean layout)
The Symptom: "I Just Want a Grid of Videos"
You've got four video files. You want them in a 2×2 grid, playing simultaneously. You know FFmpeg can do it, but every tutorial shows a monster command with nullsrc and four overlay filters. You just want a simple, readable command.
That's exactly what xstack delivers.
Core Concepts: What Is xstack?
The xstack filter "stack video inputs into custom layout"[reference:9]. It takes multiple video streams and arranges them according to a layout specification.
Key characteristics:
- All streams must have the same pixel format — e.g.,
yuv420p[reference:10]. - Layouts are defined using coordinates —
xandypositions for each input[reference:11]. - Inputs can be scaled before stacking — use
scaleorsetsarto unify sizes. - Column‑major order by default, but row‑major is possible with custom layouts[reference:12].
The filter was added to FFmpeg in 2018[reference:13], and later enhanced with a grid option for even simpler layouts[reference:14].
xstack Syntax & Parameters
The basic syntax for xstack is:
[input0][input1]...[inputN]xstack=inputs=N:layout=LAYOUT[out]Parameters:
| Parameter | Description | Default |
|---|---|---|
inputs | Number of input streams[reference:15] | 2 |
layout | Position of each input (x_y format, separated by |)[reference:16] | 0_0|w0_0 for 2 inputs[reference:17] |
grid | Fixed‑size grid (rows x columns) — newer option[reference:18] | None |
shortest | Stop when the shortest input ends[reference:19] | 0 |
Layout coordinates:
w0,h0— width and height of the first inputw1,h1— width and height of the second input- You can use these variables to position inputs relative to each other[reference:20].
Important: xstack uses column‑major order by default[reference:21]. This means the first input goes to the top‑left, the second goes below it, the third goes to the right of the first, and so on. You can override this with a custom layout.
Examples: From Simple to Custom
Example 1: 2×2 Grid (Column‑Major)
This is the most common use case — four videos in a 2×2 grid.
# 2x2 grid with column-major layout
ffmpeg -i video1.mp4 -i video2.mp4 -i video3.mp4 -i video4.mp4 \
-filter_complex "[0:v]setpts=PTS-STARTPTS,scale=qvga[a0]; \
[1:v]setpts=PTS-STARTPTS,scale=qvga[a1]; \
[2:v]setpts=PTS-STARTPTS,scale=qvga[a2]; \
[3:v]setpts=PTS-STARTPTS,scale=qvga[a3]; \
[a0][a1][a2][a3]xstack=inputs=4:layout=0_0|0_h0|w0_0|w0_h0[out]" \
-map "[out]" -c:v libx264 -t 30 output_2x2.mkv
Explanation:
scale=qvga— scales each input to 320×240 (QVGA) for uniform size[reference:22].setpts=PTS-STARTPTS— resets timestamps to start at 0[reference:23].layout=0_0|0_h0|w0_0|w0_h0— positions: top‑left, bottom‑left, top‑right, bottom‑right[reference:24].
As the FFmpeg wiki explains: "When there are more than two images in a sequence (either vertical or horizontal), it becomes necessary to add widths or heights together"[reference:25].
Example 2: 1×4 Vertical Stack
Stack four videos vertically.
# Vertical stack (1x4) with column-major order ffmpeg -i video1.mp4 -i video2.mp4 -i video3.mp4 -i video4.mp4 \ -filter_complex "[0:v][1:v][2:v][3:v]xstack=inputs=4:layout=0_0|0_h0|0_h0+h1|0_h0+h1+h2[out]" \ -map "[out]" -c:v libx264 output_vertical.mkv
The Y coordinates accumulate: 0, h0, h0+h1, h0+h1+h2[reference:26].
Example 3: 1×4 Horizontal Stack
Stack four videos horizontally.
# Horizontal stack (4x1) with custom row-major layout ffmpeg -i video1.mp4 -i video2.mp4 -i video3.mp4 -i video4.mp4 \ -filter_complex "[0:v][1:v][2:v][3:v]xstack=inputs=4:layout=0_0|w0_0|w0+w1_0|w0+w1+w2_0[out]" \ -map "[out]" -c:v libx264 output_horizontal.mkv
This uses row‑major order: X coordinates accumulate, Y stays at 0.
Example 4: Using the grid Option (Newer FFmpeg)
In newer FFmpeg versions, you can use the grid option for even simpler layouts[reference:27].
# 2x3 grid using the grid option (requires FFmpeg 5.1+) ffmpeg -i video1.mp4 -i video2.mp4 -i video3.mp4 -i video4.mp4 -i video5.mp4 -i video6.mp4 \ -filter_complex "[0:v][1:v][2:v][3:v][4:v][5:v]xstack=inputs=6:grid=2x3[out]" \ -map "[out]" -c:v libx264 output_grid.mkv
The grid option is "of the form <rows>x<columns> (e.g. 2x4)"[reference:28]. When using this option, "all the input streams must have the same width and height"[reference:29].
Note: "Either grid or layout option can be specified at a time. Specifying both will result in an error"[reference:30].
Advanced: Custom Layouts & Sizing
The real power of xstack is its ability to handle custom layouts with videos of different sizes.
Custom Layout with Different Input Sizes
If your inputs have different sizes, you can scale them individually before stacking, or use the wN/hN variables in the layout to position them correctly.
# Custom layout with mixed sizes ffmpeg -i big.mp4 -i small.mp4 \ -filter_complex "[0:v]scale=1280:720[a0];[1:v]scale=640:360[a1];[a0][a1]xstack=inputs=2:layout=0_0|0_360[out]" \ -map "[out]" -c:v libx264 output_custom.mkv
This places the scaled small video below the big video, creating a picture‑in‑picture effect.
Adding Audio
xstack handles video only. For audio, use amix or amerge in the same filtergraph.
# Video mosaic + mixed audio
ffmpeg -i video1.mp4 -i video2.mp4 -i video3.mp4 -i video4.mp4 \
-filter_complex "[0:v][1:v][2:v][3:v]xstack=inputs=4:layout=0_0|0_h0|w0_0|w0_h0[out]; \
[0:a][1:a][2:a][3:a]amix=inputs=4[aout]" \
-map "[out]" -map "[aout]" -c:v libx264 -c:a aac output_with_audio.mkv
xstack vs. overlay – Which to Use?
Both xstack and overlay can create video mosaics, but they have different strengths.
✅ xstack Advantages
- Cleaner syntax — no
nullsrcor nested overlays[reference:31] - Built‑in layout handling — positions videos automatically
- Easier to maintain — especially with many inputs
gridoption — quick matrix layouts[reference:32]
✅ overlay Advantages
- More flexible — can overlay with transparency (alpha channel)
- Works with any pixel format — no format restrictions
- Better for PIP — one video on top of another
- More widely known — more examples online
Recommendation: Use xstack for grids and mosaics where all videos are equal. Use overlay for picture‑in‑picture or when you need transparency.
Troubleshooting Common Issues
| Issue | Likely Cause | Fix |
|---|---|---|
| "Pixel format mismatch" | Inputs have different pixel formats[reference:33] | Use format=yuv420p on all inputs before stacking |
| "Layout error: invalid coordinates" | Layout string syntax is wrong | Check the format: x_y separated by | |
| Black gaps appear | Inputs have different sizes[reference:34] | Scale all inputs to the same size before stacking |
| "Inputs count mismatch" | inputs=N doesn't match number of streams |
Ensure inputs=N matches the number of input labels |
| Audio out of sync | Audio not mixed or filtered correctly | Use amix or amerge with adelay if needed |
| Grid option not recognized | FFmpeg version too old | Use FFmpeg 5.1 or newer, or use layout instead |
Frequently Asked Questions (FAQ)
What is the xstack filter in FFmpeg?
xstack is an FFmpeg filter that stacks multiple video inputs into a custom layout[reference:35]. It creates video mosaics, split-screen grids, and collages without the complex overlay and nullsrc chains that older methods required[reference:36]. All streams must have the same pixel format[reference:37].
How do I create a 2x2 video grid with xstack?
Use: ffmpeg -i video1.mp4 -i video2.mp4 -i video3.mp4 -i video4.mp4 -filter_complex '[0:v][1:v][2:v][3:v]xstack=inputs=4:layout=0_0|0_h0|w0_0|w0_h0[out]' -map '[out]' output.mp4. The layout uses column-major order by default[reference:38].
What's the difference between xstack and overlay for video mosaics?
xstack simplifies video stacking by eliminating the need for a nullsrc filter and multiple overlay chains[reference:39]. It automatically calculates positions based on your layout specification, making it cleaner and less error‑prone for multi‑video layouts.
Can I use xstack to stack videos in a custom layout?
Yes. The layout parameter lets you define exact positions for each input using coordinates like w0, h0, w1, h1, etc. You can create any arrangement — side‑by‑side, stacked, or custom overlapping grids[reference:40].
Does xstack support the grid option for simpler layouts?
Yes. In newer FFmpeg versions (5.1+), xstack has a grid option[reference:41]. Instead of writing complex layouts, you can simply specify rows and columns (e.g., grid=2x4) and xstack will arrange the inputs automatically[reference:42].
Does xstack handle audio automatically?
No. xstack processes video only. To mix audio from multiple inputs, use amix or amerge in the same filtergraph and map the audio output separately.
Final Word
The xstack filter is one of FFmpeg's most elegant solutions for multi‑video layouts. It turns a traditionally complex operation — stacking videos into a grid or mosaic — into a clean, readable filtergraph.
Whether you're building a 2×2 surveillance grid, a 3×3 video conference layout, or a custom collage with mixed sizes, xstack gives you the control you need without the headache of nested overlays.
Key takeaways for your workflow:
- Use
scaleto unify input sizes - Use
formatto ensure matching pixel formats - Use
gridfor quick matrix layouts (FFmpeg 5.1+) - Mix audio separately with
amix
Next time you need a video mosaic, reach for xstack. Your filtergraphs will thank you.