How to Use the FFmpeg vstack Filter

This article provides a straightforward guide on how to use the vstack (vertical stack) filter in FFmpeg to merge multiple video inputs vertically into a single output file. You will learn the basic command syntax, how to stack three or more videos, how to handle inputs with different dimensions, and how to manage the accompanying audio tracks.

The vstack filter in FFmpeg allows you to position two or more video streams on top of each other. For this filter to work, all input videos must have the exact same width.

Basic Syntax for Two Videos

To stack two videos vertically, use the -filter_complex option and specify the number of inputs using the inputs parameter.

ffmpeg -i top.mp4 -i bottom.mp4 -filter_complex "vstack=inputs=2" output.mp4

In this command, top.mp4 will appear on the top half of the screen, and bottom.mp4 will appear on the bottom half.

Stacking Three or More Videos

You can stack more than two videos by increasing the inputs value and adding the additional input files. Here is how to stack three videos:

ffmpeg -i top.mp4 -i middle.mp4 -i bottom.mp4 -filter_complex "vstack=inputs=3" output.mp4

Handling Videos with Different Widths

If your input videos do not have the same width, FFmpeg will throw an error. To resolve this, you must scale the videos to a matching width before applying the vstack filter.

The following command scales both videos to a width of 1920 pixels while maintaining their aspect ratios (-1) before stacking them:

ffmpeg -i input1.mp4 -i input2.mp4 -filter_complex "[0:v]scale=1920:-1[v0]; [1:v]scale=1920:-1[v1]; [v0][v1]vstack=inputs=2" output.mp4

Combining Audio Streams

By default, the vstack filter only processes video streams. If you want to keep and combine the audio from both videos, you need to use the amix filter to merge the audio tracks:

ffmpeg -i top.mp4 -i bottom.mp4 -filter_complex "[0:v][1:v]vstack=inputs=2[v]; [0:a][1:a]amix=inputs=2[a]" -map "[v]" -map "[a]" output.mp4

This command merges the video streams vertically into [v], mixes the audio streams into [a], and maps both outputs to the final file.