How to Use the xstack Filter in FFmpeg

The xstack filter in FFmpeg is a powerful tool used to combine multiple input video streams into a single, highly customizable grid or mosaic layout. Unlike the older hstack and vstack filters, which only allow simple horizontal or vertical stacking, xstack lets you position videos anywhere on a 2D coordinate system. This article provides a direct, step-by-step guide on how to use the xstack filter, explaining its layout syntax and providing practical command-line examples.

Understanding the Basic Syntax

The basic syntax for the xstack filter requires specifying the number of input streams and defining their exact spatial coordinates on the output canvas.

-filter_complex "[0:v][1:v]xstack=inputs=2:layout=0_0|w0_0[out]"
  • inputs: The number of input video streams (default is 2).
  • layout: The coordinate positions for each video, separated by a pipe (|) character. The coordinates for each video are defined as X_Y (horizontal and vertical positions), separated by an underscore (_).
  • w0, h0, w1, h1: Variables representing the width (w) and height (h) of the respective input streams (0 being the first input, 1 being the second, and so on).

Practical Examples

1. Side-by-Side (2 Videos)

To place two videos side-by-side, the first video is placed at the top-left corner (0_0). The second video is placed directly to the right of the first video (w0_0), meaning its X-coordinate starts where the width of the first video ends, and its Y-coordinate is 0.

ffmpeg -i input1.mp4 -i input2.mp4 -filter_complex "[0:v][1:v]xstack=inputs=2:layout=0_0|w0_0[out]" -map "[out]" output.mp4

2. 2x2 Grid (4 Videos)

To create a 2x2 grid using four videos of identical dimensions, you map them to the four corners of the canvas:

  • Top-Left: 0_0
  • Top-Right: w0_0 (starts after the width of the first video)
  • Bottom-Left: 0_h0 (starts below the height of the first video)
  • Bottom-Right: w0_h0 (starts after the width of the first video and below its height)
ffmpeg -i input1.mp4 -i input2.mp4 -i input3.mp4 -i input4.mp4 -filter_complex "[0:v][1:v][2:v][3:v]xstack=inputs=4:layout=0_0|w0_0|0_h0|w0_h0[out]" -map "[out]" output.mp4

3. Vertical Stack (3 Videos)

To stack three videos vertically on top of each other, keep the X-coordinate at 0 for all videos and stack their heights progressively:

  • Top: 0_0
  • Middle: 0_h0
  • Bottom: 0_h0+h1
ffmpeg -i input1.mp4 -i input2.mp4 -i input3.mp4 -filter_complex "[0:v][1:v][2:v]xstack=inputs=3:layout=0_0|0_h0|0_h0+h1[out]" -map "[out]" output.mp4

Important Usage Tips

  • Handling Different Resolutions: If your input videos have different resolutions, you must scale them to matching dimensions first (using the scale filter) or carefully calculate the layout offsets using specific w and h variables to avoid overlapping or empty black gaps.

  • Fill Color: You can use the fill option to set a background color for any empty spaces in your grid layout (e.g., fill=black).

  • Audio Mixing: The xstack filter only processes video streams. If you want to combine the audio from all inputs, you must use the amix filter:

    -filter_complex "[0:a][1:a]amix=inputs=2[a]" -map "[a]"