VapourSynth: A Beginner’s Guide to Video ProcessingVapourSynth is a powerful, scriptable video processing framework designed for automation, high-quality filtering, and complex workflows. Built with Python scripting at its core, it lets you apply filters, manipulate frames, and build reproducible processing chains for encoding, restoration, and creative effects. This guide introduces the core concepts, installation, basic scripts, common filters and plugins, workflow patterns, troubleshooting tips, and resources to learn more.
What is VapourSynth and why use it?
VapourSynth is a modern successor to Avisynth that:
- Is scriptable in Python, giving access to a full programming language and ecosystem.
- Uses a plugin architecture, allowing third-party filters and high-performance native code.
- Offers frame-accurate processing and multi-threaded performance for many operations.
- Separates processing from playback/encoding, making it well-suited for batch workflows and reproducible pipelines.
It’s popular for video restoration (denoising, deinterlacing, debanding), upscaling, color correction, and as a pre-processing step before encoding with x264/x265/AV1 encoders.
Installing VapourSynth
Installation varies by platform. Two main parts are required: the VapourSynth core (the runtime) and Python bindings/plugins.
- Windows: download the VapourSynth installer (recommended builds include the core, Python, and common plugins). Use the installer from the official project or a trusted distribution.
- macOS/Linux: use package managers (Homebrew on macOS, apt/pacman on Linux) or build from source. Many distros provide vapoursynth and vapoursynth-plugin packages.
- Python: VapourSynth exposes a module named vapoursynth; ensure the Python interpreter you run scripts with can import it. Many users run scripts with the VapourSynth-provided Python or configure their environment to include vapoursynth.
After installation, verify by running a minimal script (example below) or importing vapoursynth in Python.
Basic concepts
- Script-based: You write a .py script that constructs a processing graph. The graph is evaluated by players or encoders that support VapourSynth (e.g., mpv with vapoursynth, VapourSynth editor plugins, or command-line tools that use vsr).
- Core object: the core (usually accessed as core = vapoursynth.core) provides access to filters and functions.
- Clips: a Clip object represents a sequence of frames with format, dimensions, frame rate, and color properties. Filters return new Clip objects so you chain operations.
- Filters: functions or methods attached to core, like core.resize.Spline36 or plugin-specific filters.
- Format/color: VapourSynth supports named formats (e.g., YUV420P8, YUV420P16, RGB24). Understanding bit depth and chroma subsampling is important for color-safe operations.
A minimal VapourSynth script
Save as example.vpy:
import vapoursynth as vs core = vs.core # Load source (requires appropriate source plugin, e.g., FFMS2) clip = core.ffms2.Source(source="input.mkv") # Basic resize and convert to 10-bit YUV420P16 resized = core.resize.Bicubic(clip, 1280, 720) converted = core.resize.Point(resized, format=vs.YUV420P16) # Output the clip converted.set_output() Run this script by opening it in a player that supports VapourSynth (mpv configured with vapoursynth) or feed to an encoder via tools that accept .vpy input.
Common source plugins
- FFMS2 (ffms2) — robust demuxer/decoder using FFmpeg libraries; widely used for diverse container/codecs.
- L-SMASH Works (lsmas) — another popular demuxer/decoder, sometimes preferred for certain formats.
- avs importers — for loading Avisynth scripts.
- DirectShowSource (on Windows) — less common in modern workflows.
Example using FFMS2:
clip = core.ffms2.Source(source="input.mkv") Typical processing steps and filters
Most practical workflows use a chain of processing stages. Example stages and common filters/plugins:
- Input → Source plugin (ffms2/lsmas)
- Crop/resize → core.std.CropRel / core.resize.Bicubic / core.resize.Spline36
- Color space adjustments → core.resize.Point(format=…) or custom color transforms
- Noise reduction → DNx, SMTM, BM3D, DFTTest, or mvtools-based stabilizing denoising
- Debanding → f3kdb, Placebo deband, or custom operations
- Sharpening/detail synthesis → fmtc, sbr, sharpen filters
- Chroma handling → separate luma and chroma operations using core.std.ShufflePlanes or split/merge
- Frame rate conversion / inverse telecine → TFM + TDecimate (mvtools or separate plugins)
- Subtitle/chapter handling → external burn-in with plugin or manage during muxing
- Output → set_output() for preview, or write via encoder (x264/x265) using ffmpeg/CLI tools
Example chaining:
clip = core.ffms2.Source("input.mkv") luma = core.std.ShufflePlanes(clip, plane=0, colorfamily=vs.GRAY) denoised = core.knlm.KNLMeansCL(luma, d=3, a=2) merged = core.std.ShufflePlanes([denoised, clip], planes=[0,1,2], colorfamily=vs.YUV) final = core.resize.Spline36(merged, 1280, 720) final.set_output() Working with color and bit depth
- Always be explicit about formats when converting. Use format constants (vs.YUV420P8, vs.YUV420P16, vs.RGB24).
- Perform linear/lightness-sensitive operations in higher bit depth or linear color space when possible to avoid banding and precision loss.
- Example: convert to 16-bit for heavy filtering, then back to 8-bit for delivery.
Script structure and good practices
- Modularize: define functions for repeated tasks (e.g., crop_and_scale).
- Comment: explain non-obvious choices, especially filter parameters.
- Keep luma and chroma separate when applying luma-only denoising or sharpening.
- Use preview tools (mpv, VSEditor, or VapourSynth’s previewer) to check intermediate results.
- Version control scripts for reproducibility.
Example structure:
import vapoursynth as vs core = vs.core def load_source(path): return core.ffms2.Source(source=path) def denoise_luma(clip): l = core.std.ShufflePlanes(clip, plane=0, colorfamily=vs.GRAY) l = core.knlm.KNLMeansCL(l, d=3, a=2) return core.std.ShufflePlanes([l, clip], planes=[0,1,2], colorfamily=vs.YUV) src = load_source("input.mkv") proc = denoise_luma(src) proc.set_output() Plugins and noteworthy filters
- KNLMeansCL — GPU-accelerated denoising (requires OpenCL).
- f3kdb — popular debanding filter.
- fmtconv/fmtc — high-quality format conversions and resampling (often used for precise color handling).
- mvtools/flowframes — motion analysis for deinterlacing or motion-compensated filters.
- FFT3DFilter / BM3D — specialized denoisers.
- DFTTest — frequency-domain denoising.
Plugins often require additional dependencies (OpenCL, CUDA, FFT libs). Read documentation for installation and compatibility.
Debugging and troubleshooting
- “ImportError: No module named vapoursynth” — ensure you run the script with a Python that can see the vapoursynth package (use VapourSynth’s Python or adjust PYTHONPATH).
- Wrong colors/levels — check chroma placement, pixel format, and whether conversions (full/limited range) are handled.
- Crashes or segfaults — often caused by mismatched plugin versions; ensure core and plugins are compatible.
- Performance issues — consider using multithreaded filters, GPU-accelerated plugins, or profile filters to identify slow stages.
Encoding and using the output
Common approach: use VapourSynth for preprocessing, then feed to an encoder:
- Use ffmpeg to read the .vpy via libvapoursynth (ffmpeg supports vapoursynth input) and encode with x264/x265/AV1.
- Or use encoding GUIs that support VapourSynth as input.
Example FFmpeg command: ffmpeg -i script.vpy -c:v libx265 -preset medium -crf 18 output.mkv
Example end-to-end script (simple restoration + resize)
import vapoursynth as vs core = vs.core src = core.ffms2.Source(source="input.mkv") # Luma denoise luma = core.std.ShufflePlanes(src, plane=0, colorfamily=vs.GRAY) luma = core.knlm.KNLMeansCL(luma, d=2, a=1) src = core.std.ShufflePlanes([luma, src], planes=[0,1,2], colorfamily=vs.YUV) # Deband src = core.f3kdb.Deband(src, radius=16, threshold=24, sample=6) # Resize to 1920x1080 out = core.resize.Spline36(src, 1920, 1080) out.set_output() Resources to learn more
- Official VapourSynth documentation and API references.
- Plugin documentation pages (KNLMeansCL, f3kdb, fmtc, mvtools).
- Community forums and Discord/Reddit groups for practical recipes and troubleshooting.
- Example script repositories and anime/video restoration communities for real-world examples.
Final tips
- Start simple: small scripts to learn clip chaining and plugin usage.
- Preview often: check every major change on a short segment.
- Use version control for scripts and document parameter choices.
- Learn when to process luma-only vs full-color; many restoration steps should be luma-focused.
This guide gives you the foundation to start using VapourSynth. As you get comfortable, you’ll adopt plugins, custom filters, and workflow patterns that match the codecs and sources you work with.
Leave a Reply