vs-fgs

A VapourSynth plugin for applying Film Grain Synthesis' table (FGS) using the dav1d decoder.

Since dav1d is widely regarded as the best and fastest AV1 decoder available, its FGS engine is fully spec-compliant with AFGS1 (AOMedia Film Grain Synthesis 1), guaranteeing highly accurate, performant, and standardized grain generation.

vsfgs parses standard FGS text files and applies film grain to the input clip natively in 8-bit, 10-bit, or 12-bit YUV.

Why this plugin

Film Grain Synthesis (FGS) represents a massive step forward in video compression, allowing to model film grain mathematically rather than encoding random noise.

This plugin was built with two primary goals in mind:

• Visualizing and Fine-Tuning FGS: It serves as a "real-time" visualization tool during your encoding pipeline. By rendering the grain dynamically, you can preview, adjust, and perfectly tune your FGS tables in relation to the actual video content (especially when paired with tools like FGSE).
• Grain Baking: Not all target codecs (e.g. H.264, VP9, HEVC) support FGS playback, and you don't always want to distribute video files with separate grain metadata. vsfgs gives you the ability to bake the high-quality, standardized AFGS1 grain directly into the video stream before handing it off to your encoder.

Furthermore, this tool is future-proof for processing official AV1 streams (e.g. Netflix) that already have FGS embedded inside them, allowing you to seamlessly visualize or bake their grain during filtering and re-encoding.

Installation

pip install vsfgs

Usage

import vapoursynth as vs
import vsfgs

core = vs.core

# Load your video clip using your preferred source filter (e.g. BestSource, LSMASH, etc.)
clip = core.bs.VideoSource("source.mkv")

# Apply Film Grain Synthesis using a grain table (.bin or .txt):
# - ignore_chroma: If True, grain is only applied to Luma (Chroma is copied).
# - static: If True, uses the seed from the FGS table for all frames (if dynamic FGS, per event). If False, rotates the seed for each frame. Note: for `.bin` files, dynamic_seed is disabled automatically.
# - simd: Hardware SIMD architecture ('auto', 'avx512', 'avx2', 'sse41', 'sse3', 'sse2', or 'none'/'c' for plain C). Defaults to 'auto'.
clip = vsfgs.apply_fgs(clip, "grain_table.bin", ignore_chroma=False, static=False, simd="auto")

clip.set_output()

For detailed parameter types and descriptions, check the function docstrings.

Frame Properties

For each processed frame, vsfgs outputs the exact seed integer used during synthesis into the VapourSynth frame properties: FGS_Seed

Input Format & Advanced Customization

vsfgs supports input grain files in both standard .txt (AFGS1 textual format) and directly compiled .bin (Binary format). It allows for extreme and advanced customization of the film grain synthesis pattern.

For complete details on the required text syntax, binary packing parameters, and an advanced visual editor to create and fine-tune these tables, please refer to the FGSEditor wiki: https://github.com/PingWer/FGSEditor

Technical & Implementation Notes

High Bit-Depth & Precision Preservation

The underlying dav1d FGS synthesis engine strictly operates on 8-bit, 10-bit, or 12-bit integer YUV clips. To support higher bit-depths (>12-bit integer or Float formats) without quality loss:

• The input clip is temporarily converted to 12-bit integer using dither_type="none".
• Film grain is synthesized at 12-bit depth.
• The isolated grain pattern (delta) is extracted via MakeDiff, scaled back to match the original clip format, and applied onto the untouched original clip using MergeDiff.

This approach completely eliminates quantization and dithering alterations.

Performance & Compatibility

vsfgs uses dav1d's hand-written Assembly instructions (AVX-512, AVX2, SSE3 ...), resulting in extremely high throughput with almost zero overhead.

Platform Support:

Benchmark Comparison (2,000 frames of real 1080p source via BestSource): Tests compared vsfgs against Grainer.GAUSS (from vsjetpack). It also demonstrates the speedup of dav1d's hardware SIMD Assembly optimizations over unvectorized reference C code (simd='none').

Building from Source

To compile the plugin manually, you must have a working C++ toolchain and Meson setup. The plugin depends on dav1d, which will be built automatically as a Meson subproject.

Prerequisites

• Python 3.13+ (or newer)
• C++ Compiler: GCC/Clang (Linux/macOS) or MSVC (Windows)
• Meson & Ninja: Build system (pip install meson ninja)
• nasm: Highly recommended for x86/x64 systems to enable dav1d assembly optimizations (drastically improves grain synthesis performance).
  • Windows: choco install nasm
  • Linux: sudo apt-get install nasm or sudo dnf install nasm
  • macOS: brew install nasm

Build Steps

1. Clone the repository recursively to fetch the dav1d submodule:

   git clone --recursive https://github.com/PingWer/vs-fgs.git
   cd vs-fgs
   

2. Build and install the plugin directly into your active Python environment:

   pip install .
   

Standalone Build (Without Python Installation)

If you only want to compile the VapourSynth plugin binary (DLL/SO/DYLIB) without installing it via pip, you can use Meson directly:

meson setup build --buildtype=release --vsenv
meson compile -C build

TODO

Any suggestions are welcome! But, the plugin is basically feature complete.

Community & Support

For questions, feedback, or troubleshooting, feel free to join and reach out on the AV1 Weeb edition Discord server

License

This project is licensed under the MIT License.

Third-Party Licenses

This project includes and statically links code from dav1d (located in subprojects/dav1d), which is licensed under the BSD 2-Clause License:

Copyright © 2018-2025, VideoLAN and dav1d authors. All rights reserved.
Licensed under the BSD 2-Clause License.