How to Use VapourSynth Filter in FFmpeg

This article provides a practical guide on how to load and execute VapourSynth scripting inside FFmpeg using the vapoursynth video filter. You will learn how to verify your FFmpeg installation, write a compatible VapourSynth script, and run the command-line execution to process your videos.

Prerequisites

To use VapourSynth within FFmpeg, your FFmpeg build must be compiled with VapourSynth support. You must also have Python and VapourSynth installed on your system.

You can check if your FFmpeg installation supports the filter by running the following command in your terminal:

ffmpeg -filters | grep vapoursynth

If the output lists vapoursynth, you are ready to proceed.

Step 1: Create the VapourSynth Script

When using the vapoursynth filter in FFmpeg, the input video stream from FFmpeg is automatically passed into the Python script as a variable named video_in. Your script must process this variable and assign the final output clip to a variable named video_out.

Create a text file named script.vpy and add the following Python code as an example:

import vapoursynth as vs
core = vs.core

# 'video_in' is supplied automatically by the FFmpeg filter
# Apply a simple filter (e.g., Invert) to the video
video_out = core.std.Invert(video_in)

Step 2: Execute the FFmpeg Command

To run the script, use FFmpeg’s video filter flag (-vf or -filter:v) and call the vapoursynth filter, specifying the path to your .vpy script.

Run the following command in your terminal:

ffmpeg -i input.mp4 -vf "vapoursynth=script=script.vpy" output.mp4

Advanced Options

The vapoursynth filter accepts additional parameters to customize how the script is executed:

• script: The path to your VapourSynth script (required).
• buffered_frames: Sets the number of frames to buffer for the filter. Increasing this can improve performance for complex scripts at the cost of memory. Default is 4.

Example with buffered frames defined:

ffmpeg -i input.mp4 -vf "vapoursynth=script=script.vpy:buffered_frames=8" output.mp4