Skip to main content

vs-fgs

A VapourSynth plugin for applying Film Grain Synthesis (FGS) using the dav1d engine.

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 = core.lsmas.LWLibavSource("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.
# - 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.txt", ignore_chroma=False, static=False, simd="auto")

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

Advanced Customization

vsfgs allows for extreme and advanced customization of the film grain pattern. The logic for synthesizing grain relies on a detailed parameter table. For an advanced visual editor to fine-tune these parameters and for more details on the grain configuration, 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 measure clean frame throughput and processor scaling across native chroma sub-samplings, comparing vsfgs against Grainer.GAUSS (from vsdeband). It also demonstrates the speedup of dav1d's hardware SIMD Assembly optimizations over unvectorized reference C code (simd='none').

Format Baseline (BestSource + 16b) vsfgs (SIMD: Auto / AVX-512) vsfgs (SIMD: None / Plain C) Grainer.GAUSS (vsdeband)
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
meson compile -C build

License

This project is licensed under the MIT License.

Metadata

Release files for vsfgs 0.5.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.5.0
File Size Uploaded
vsfgs-0.5.0.tar.gz 1.7 MB Details

Built distributions (wheels)

Table of built distributions (wheels) for vsfgs 0.5.0
File
vsfgs-0.5.0-cp314-cp314-win_amd64.whl CPython 3.14 CPython 3.14 Windows x86-64 Details
vsfgs-0.5.0-cp314-cp314-musllinux_1_2_x86_64.whl CPython 3.14 CPython 3.14 Linux musl 1.2+ x86-64 Details
vsfgs-0.5.0-cp314-cp314-musllinux_1_2_aarch64.whl CPython 3.14 CPython 3.14 Linux musl 1.2+ ARM64 Details
vsfgs-0.5.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.5.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.5.0-cp314-cp314-macosx_11_0_arm64.whl CPython 3.14 CPython 3.14 macOS 11.0+ ARM64 Details
vsfgs-0.5.0-cp314-cp314-macosx_10_15_x86_64.whl CPython 3.14 CPython 3.14 macOS 10.15+ x86-64 Details
vsfgs-0.5.0-cp313-cp313-win_amd64.whl CPython 3.13 CPython 3.13 Windows x86-64 Details
vsfgs-0.5.0-cp313-cp313-musllinux_1_2_x86_64.whl CPython 3.13 CPython 3.13 Linux musl 1.2+ x86-64 Details
vsfgs-0.5.0-cp313-cp313-musllinux_1_2_aarch64.whl CPython 3.13 CPython 3.13 Linux musl 1.2+ ARM64 Details
vsfgs-0.5.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.5.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.5.0-cp313-cp313-macosx_11_0_arm64.whl CPython 3.13 CPython 3.13 macOS 11.0+ ARM64 Details
vsfgs-0.5.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.9 MB

Release files / vsfgs-0.5.0.tar.gz

Download URL vsfgs-0.5.0.tar.gz
Size 1.7 MB
Tags Source
SHA-256 checksum
How to use checksums
4f804e8c22d27bc791bfb85e873267ce33cf88bb3c8714e58a9b49fea3115f6f
BLAKE2b-256 checksum
How to use checksums
d696e6f2ba75d33c114d4c1d93cd17594d131940934f7bca75b4c6d8db8d63c3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.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 25, 2026.

Transparency log

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

Download URL vsfgs-0.5.0-cp314-cp314-win_amd64.whl
Size 122.9 kB
Tags CPython 3.14 Windows x86-64
SHA-256 checksum
How to use checksums
77330642848033f2877b3fd173c4c6d20a55cfb5a1e298db59ceba189dc45f02
BLAKE2b-256 checksum
How to use checksums
e3debe293a1ddcc75e615d562a678413067c470af15e087ca9684e7cc0c184a5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.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 25, 2026.

Transparency log

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

Download URL vsfgs-0.5.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
105deb0c542f762df2656f64a264326bc137829ede44ff447593caa7111fbe87
BLAKE2b-256 checksum
How to use checksums
2ac8f34e6680418ad377c56774423210338281c82236db4af07d3f64c92218d5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.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 25, 2026.

Transparency log

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

Download URL vsfgs-0.5.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
0d705431e6ea06589d08c0bd4ab98c01a551363c2c7264e884594ad742f6e8d0
BLAKE2b-256 checksum
How to use checksums
0540e1d2aa4dae689b27bd56aafa145b39280f68cd0cc9adc82388cb91f4aa63
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.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 25, 2026.

Transparency log

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

Download URL vsfgs-0.5.0-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Size 94.6 kB
Tags CPython 3.14 Linux glibc 2.24+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
2253383d7180aa0ad906e0081fad2bc4c015e70b0886af4e5d8aa9c6fd540e09
BLAKE2b-256 checksum
How to use checksums
3b6b3b632f6e24fca78166ef7749f1faa729d8d0a2f7820da26f364b3b12b559
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.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 25, 2026.

Transparency log

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

Download URL vsfgs-0.5.0-cp314-cp314-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl
Size 55.2 kB
Tags CPython 3.14 Linux glibc 2.24+ ARM64 Linux glibc 2.28+ ARM64
SHA-256 checksum
How to use checksums
8f3fe241515819023b29997a340a73952a085b5b439013f24b4a9f955335fb43
BLAKE2b-256 checksum
How to use checksums
e223967f0cd8d6c74b65f2a966a41c3d6371b6c17ea858ea652ccaad422361da
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.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 25, 2026.

Transparency log

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

Download URL vsfgs-0.5.0-cp314-cp314-macosx_11_0_arm64.whl
Size 52.0 kB
Tags CPython 3.14 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
c0cbda0881a4bc118ecf0f9afae369ffed6d331ae76dcbb03c7d608982b5c50b
BLAKE2b-256 checksum
How to use checksums
67d180a04b32a52a36d597a2637c4603f6592cbfd8d83c550c3fd93e85dd1928
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.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 25, 2026.

Transparency log

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

Download URL vsfgs-0.5.0-cp314-cp314-macosx_10_15_x86_64.whl
Size 79.6 kB
Tags CPython 3.14 macOS 10.15+ x86-64
SHA-256 checksum
How to use checksums
f4b028309e65459cd2dc68d8da1e0d5dd1e8aa9aca356a34dd47cf6ca92f5590
BLAKE2b-256 checksum
How to use checksums
a8ec6f8c5c2019c783e81598c46e25717adf20a0788c927ff50e919d8f2be153
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.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 25, 2026.

Transparency log

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

Download URL vsfgs-0.5.0-cp313-cp313-win_amd64.whl
Size 119.5 kB
Tags CPython 3.13 Windows x86-64
SHA-256 checksum
How to use checksums
face6e41559d7aa7c44761781a7cdcd5c040d7b11781aa87ec79b70298d0276e
BLAKE2b-256 checksum
How to use checksums
37d8bc600e85ca899ce12a4fcc113c6d485b455f7256128e228f9937205a8b00
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.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 25, 2026.

Transparency log

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

Download URL vsfgs-0.5.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
b97ec0ad0c40da751043d71dd4da2fc05dd8387a0c21014d84cb1863286730b4
BLAKE2b-256 checksum
How to use checksums
02d7fb5ddf026bebaee3c8b2b7a7833d5fd6cd06cc2a05871a69db3677b2fbe5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.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 25, 2026.

Transparency log

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

Download URL vsfgs-0.5.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
7a8d1ad6e650c035d926238f0e973911c0cf194ef5f49400d6d7d8db5202c27b
BLAKE2b-256 checksum
How to use checksums
0c7d15e4ef043acd63d1c007e99c6163d22cefdaa2f35a4531b310505f6d1474
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.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 25, 2026.

Transparency log

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

Download URL vsfgs-0.5.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Size 94.6 kB
Tags CPython 3.13 Linux glibc 2.24+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
eb134049df0c27426aa1242eb44ec720061c705ebbd8b38579ce627f4b51ee33
BLAKE2b-256 checksum
How to use checksums
bf3b3893d448aefae8522f3ef787aeeaec5ed3155cc4bdb1e2a59022fd817192
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.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 25, 2026.

Transparency log

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

Download URL vsfgs-0.5.0-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl
Size 55.2 kB
Tags CPython 3.13 Linux glibc 2.24+ ARM64 Linux glibc 2.28+ ARM64
SHA-256 checksum
How to use checksums
3be4a60cdc77cd9bbd23a240bf6351a35810d9cbd6861cb257973b59f5e39005
BLAKE2b-256 checksum
How to use checksums
20bf0200dd175c42abb86905bbef332d7c7b6dd084e331cf05320a2e68f6d1c0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.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 25, 2026.

Transparency log

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

Download URL vsfgs-0.5.0-cp313-cp313-macosx_11_0_arm64.whl
Size 52.0 kB
Tags CPython 3.13 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
e931f669ba1738752b8b48e689fec4b78c4be9d0e6d97aec8e0d4bd1e032ea2c
BLAKE2b-256 checksum
How to use checksums
bfba6011e2ec6d924720bd2d966f0864e882d6ab60753b439a54aee179a858c7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.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 25, 2026.

Transparency log

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

Download URL vsfgs-0.5.0-cp313-cp313-macosx_10_13_x86_64.whl
Size 79.5 kB
Tags CPython 3.13 macOS 10.13+ x86-64
SHA-256 checksum
How to use checksums
d8bfbc6cea484b0522b628109d8d6d7f0ae2ab5b563f53169f42f27f0eb42834
BLAKE2b-256 checksum
How to use checksums
3a6f8365ada617d54c54bd3061e096f20806a1359f0dc9f386feb4811b5444e1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.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 25, 2026.

Transparency log

Release history Release notifications | RSS feed

1.1.0

8 release files

0.7.0

8 release files

0.6.0

15 release files

0.5.1

15 release files

This release

0.5.0 This release

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