Skip to main content

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. It also handles automatic dithering if the input bit depth is higher.

Installation

pip install vsfgs

Usage

import vapoursynth as vs
import vsfgs

core = vs.core

# 1. Load your video
clip = your_video_loader("source.mkv")

# 2. Apply Film Grain
# - 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'.
# - temporal_average: Apply temporal smoothing to the generated grain. Provide a float (weight) or a tuple (weight, radius).
clip = vsfgs.apply_fgs(clip, "grain_table.bin", ignore_chroma=False, static=False, simd="auto", temporal_average=0.5)

clip.set_output()

Frame Properties

For each processed frame, vsfgs outputs the exact seed integer used during synthesis into the VapourSynth frame properties map: 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

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:

OS Architecture Supported Tested
Windows x86_64, ARM64 ✅ ✅
Linux x86_64, aarch64 ✅ ❌
macOS x86_64, Apple Silicon ✅ ❌

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').

Format Baseline (BestSource + 16bit conversion) vsfgs (SIMD: Auto / AVX-512) vsfgs (SIMD: None / Plain C) Grainer.GAUSS (vsjetpack)
YUV420P16 ~1128 FPS ~557 FPS ~514 FPS ~347 FPS
YUV422P16 ~866 FPS ~434 FPS ~425 FPS ~322 FPS
YUV444P16 ~649 FPS ~305 FPS ~299 FPS ~279 FPS

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

  • Binary FGS Support: Support loading film grain synthesis tables directly from binary format.
  • Direct Video Extraction: Support direct extraction of FGS tables from encoded video files (will require grav1synth).

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.

Metadata

Release files for vsfgs 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vsfgs 0.6.0
File Size Uploaded
vsfgs-0.6.0.tar.gz 1.7 MB Details

Built distributions (wheels)

Table of built distributions (wheels) for vsfgs 0.6.0
File
vsfgs-0.6.0-cp314-cp314-win_amd64.whl CPython 3.14 CPython 3.14 Windows x86-64 Details
vsfgs-0.6.0-cp314-cp314-musllinux_1_2_x86_64.whl CPython 3.14 CPython 3.14 Linux musl 1.2+ x86-64 Details
vsfgs-0.6.0-cp314-cp314-musllinux_1_2_aarch64.whl CPython 3.14 CPython 3.14 Linux musl 1.2+ ARM64 Details
vsfgs-0.6.0-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl CPython 3.14 CPython 3.14 Linux glibc 2.24+ x86-64, Linux glibc 2.28+ x86-64 Details
vsfgs-0.6.0-cp314-cp314-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl CPython 3.14 CPython 3.14 Linux glibc 2.24+ ARM64, Linux glibc 2.28+ ARM64 Details
vsfgs-0.6.0-cp314-cp314-macosx_11_0_arm64.whl CPython 3.14 CPython 3.14 macOS 11.0+ ARM64 Details
vsfgs-0.6.0-cp314-cp314-macosx_10_15_x86_64.whl CPython 3.14 CPython 3.14 macOS 10.15+ x86-64 Details
vsfgs-0.6.0-cp313-cp313-win_amd64.whl CPython 3.13 CPython 3.13 Windows x86-64 Details
vsfgs-0.6.0-cp313-cp313-musllinux_1_2_x86_64.whl CPython 3.13 CPython 3.13 Linux musl 1.2+ x86-64 Details
vsfgs-0.6.0-cp313-cp313-musllinux_1_2_aarch64.whl CPython 3.13 CPython 3.13 Linux musl 1.2+ ARM64 Details
vsfgs-0.6.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl CPython 3.13 CPython 3.13 Linux glibc 2.24+ x86-64, Linux glibc 2.28+ x86-64 Details
vsfgs-0.6.0-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl CPython 3.13 CPython 3.13 Linux glibc 2.24+ ARM64, Linux glibc 2.28+ ARM64 Details
vsfgs-0.6.0-cp313-cp313-macosx_11_0_arm64.whl CPython 3.13 CPython 3.13 macOS 11.0+ ARM64 Details
vsfgs-0.6.0-cp313-cp313-macosx_10_13_x86_64.whl CPython 3.13 CPython 3.13 macOS 10.13+ x86-64 Details

Total release size: 6.8 MB

Release files / vsfgs-0.6.0.tar.gz

Download URL vsfgs-0.6.0.tar.gz
Size 1.7 MB
Tags Source
SHA-256 checksum
How to use checksums
022081df93ba0188f671da0e4273f8eb45b51d6d032e65fd0f2f012acc3336eb
BLAKE2b-256 checksum
How to use checksums
a864666427134b2ccb404695b5fe680485464130c8853b790a855029f448a153
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 31, 2026.

Transparency log

Release files / vsfgs-0.6.0-cp314-cp314-win_amd64.whl

Download URL vsfgs-0.6.0-cp314-cp314-win_amd64.whl
Size 79.5 kB
Tags CPython 3.14 Windows x86-64
SHA-256 checksum
How to use checksums
5c332591d0beb218b0884e0378ec892500c9ba4cc3051035248a5aea3708283f
BLAKE2b-256 checksum
How to use checksums
3b8d88df3ec3216c80011071aad999cc95254af21726642c43609bc5e69c8300
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 31, 2026.

Transparency log

Release files / vsfgs-0.6.0-cp314-cp314-musllinux_1_2_x86_64.whl

Download URL vsfgs-0.6.0-cp314-cp314-musllinux_1_2_x86_64.whl
Size 1.1 MB
Tags CPython 3.14 Linux musl 1.2+ x86-64
SHA-256 checksum
How to use checksums
ec846b10ade25eb7ef3061959733ccc9b9550711bd7aa722d6ac9f72aac85045
BLAKE2b-256 checksum
How to use checksums
60cd5e89ddf60e78711f603b2335d207a057b0042c3873a9e5e58c87cfdf24e8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 31, 2026.

Transparency log

Release files / vsfgs-0.6.0-cp314-cp314-musllinux_1_2_aarch64.whl

Download URL vsfgs-0.6.0-cp314-cp314-musllinux_1_2_aarch64.whl
Size 1.0 MB
Tags CPython 3.14 Linux musl 1.2+ ARM64
SHA-256 checksum
How to use checksums
c5cae3584ef93477e836e83cb14d628ba63e85362ce7f581721fb850ec6fad35
BLAKE2b-256 checksum
How to use checksums
157f0a0f7868a8a0b4ed8634434f90a9361cc8e0851e619a6aab689001a143c4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 31, 2026.

Transparency log

Release files / vsfgs-0.6.0-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl

Download URL vsfgs-0.6.0-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Size 96.4 kB
Tags CPython 3.14 Linux glibc 2.24+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
879e7b0ad29c9f59e281f7b1f77d76fba690d65721019b7f0ca840fbe714f393
BLAKE2b-256 checksum
How to use checksums
e38533a7a4023bba9f2793a78a5e38eee37007a16b22feef29bd97f672203032
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 31, 2026.

Transparency log

Release files / vsfgs-0.6.0-cp314-cp314-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl

Download URL vsfgs-0.6.0-cp314-cp314-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl
Size 56.9 kB
Tags CPython 3.14 Linux glibc 2.24+ ARM64 Linux glibc 2.28+ ARM64
SHA-256 checksum
How to use checksums
3b546a24ec85d060407f55597762e7ba9bd562eab5733306003d6ee7a8b4dbe7
BLAKE2b-256 checksum
How to use checksums
eefde408affae72f3da2b8d1e5b012875fdbf1d2aaca1ef5096a250b2819a69b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 31, 2026.

Transparency log

Release files / vsfgs-0.6.0-cp314-cp314-macosx_11_0_arm64.whl

Download URL vsfgs-0.6.0-cp314-cp314-macosx_11_0_arm64.whl
Size 53.7 kB
Tags CPython 3.14 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
8d1ac650b655615a7dfcafdc55db5990d059224a0221933c09d1dfef126eb91d
BLAKE2b-256 checksum
How to use checksums
823245b6d072e2c84153bf3f674f896ff26e2731251f2bfef17812ae627e8891
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 31, 2026.

Transparency log

Release files / vsfgs-0.6.0-cp314-cp314-macosx_10_15_x86_64.whl

Download URL vsfgs-0.6.0-cp314-cp314-macosx_10_15_x86_64.whl
Size 81.3 kB
Tags CPython 3.14 macOS 10.15+ x86-64
SHA-256 checksum
How to use checksums
166c7948c41d48894dbba2003366298c16e2feca45b56cad32922272ff494dea
BLAKE2b-256 checksum
How to use checksums
9217f433ac0617d172b7654ebc44258602efe78689b5aaee6b0cc2e23c7b95c1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 31, 2026.

Transparency log

Release files / vsfgs-0.6.0-cp313-cp313-win_amd64.whl

Download URL vsfgs-0.6.0-cp313-cp313-win_amd64.whl
Size 77.8 kB
Tags CPython 3.13 Windows x86-64
SHA-256 checksum
How to use checksums
17b2d31ca62f5294b962f26a87179625d745140e14540ff9065aa46071cd2043
BLAKE2b-256 checksum
How to use checksums
bc0e19373e7ecc51f419ea5884b1893c95a3dc522d542e37062cae9fb019f1fe
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 31, 2026.

Transparency log

Release files / vsfgs-0.6.0-cp313-cp313-musllinux_1_2_x86_64.whl

Download URL vsfgs-0.6.0-cp313-cp313-musllinux_1_2_x86_64.whl
Size 1.1 MB
Tags CPython 3.13 Linux musl 1.2+ x86-64
SHA-256 checksum
How to use checksums
0a70101efe37520f52bdf4f0e073c0cda8a9559b1133c2e90e117348d84da856
BLAKE2b-256 checksum
How to use checksums
1b9fcccb489091579ed99d11adee16e3751259acbcedb3e84674b08f1caefe2b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 31, 2026.

Transparency log

Release files / vsfgs-0.6.0-cp313-cp313-musllinux_1_2_aarch64.whl

Download URL vsfgs-0.6.0-cp313-cp313-musllinux_1_2_aarch64.whl
Size 1.0 MB
Tags CPython 3.13 Linux musl 1.2+ ARM64
SHA-256 checksum
How to use checksums
66cf98631a32e7901c5e757952955add12e4e0fed12780c0f43666a1dbd80380
BLAKE2b-256 checksum
How to use checksums
429cef94244bd06871a4a695481466df7686112b65d7b020b8732c70c372a104
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 31, 2026.

Transparency log

Release files / vsfgs-0.6.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl

Download URL vsfgs-0.6.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Size 96.4 kB
Tags CPython 3.13 Linux glibc 2.24+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
92e3d301fd47148d660f4a54c70396993ba2517be6a411b52f10cf8d76596ab5
BLAKE2b-256 checksum
How to use checksums
7d78abdc5c7d79c8cc61e8caf263d2a3b906ff28d05955eca7b1877668b48685
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 31, 2026.

Transparency log

Release files / vsfgs-0.6.0-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl

Download URL vsfgs-0.6.0-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl
Size 56.9 kB
Tags CPython 3.13 Linux glibc 2.24+ ARM64 Linux glibc 2.28+ ARM64
SHA-256 checksum
How to use checksums
3ddef2cec7d905a6288e0b4def3757a955b8c8b0d120ef090be6def231c8322a
BLAKE2b-256 checksum
How to use checksums
637e8fe5776316aaf6fff63d778a1b5fc6383e228663cbf7f72113981971d9a6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 31, 2026.

Transparency log

Release files / vsfgs-0.6.0-cp313-cp313-macosx_11_0_arm64.whl

Download URL vsfgs-0.6.0-cp313-cp313-macosx_11_0_arm64.whl
Size 53.7 kB
Tags CPython 3.13 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
edc377660f20fd1f36d1dc379ae5412b9b0da894b008469a5b5657e0da59240b
BLAKE2b-256 checksum
How to use checksums
8fe9d0742fdcd96e7a1a06b6945f647d6f125ace0ee9603c987e2da482922c78
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 31, 2026.

Transparency log

Release files / vsfgs-0.6.0-cp313-cp313-macosx_10_13_x86_64.whl

Download URL vsfgs-0.6.0-cp313-cp313-macosx_10_13_x86_64.whl
Size 81.2 kB
Tags CPython 3.13 macOS 10.13+ x86-64
SHA-256 checksum
How to use checksums
89ce42f3a45a8b3962aceb07aac6110f280510b85413f89e334ac369d73501f7
BLAKE2b-256 checksum
How to use checksums
12f587d89c43a6e1cd3041c102cab77cdec0c37cbae0a3583937956cb98fdeea
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 31, 2026.

Transparency log

Release history Release notifications | RSS feed

1.1.0

8 release files

0.7.0

8 release files

This release

0.6.0 This release

15 release files

0.5.1

15 release files

0.5.0

15 release files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page