vs-grain 2.1.0

Vapoursynth functions to generate realistic film grain (via fgrain) and for overlaying external grain clips.

Grain Overlay and Generate functions for VapourSynth

Installation

pip install -U vs_grain

For older vapoursynth versions below R74, follow the manual installation steps here.

Generate Realistic Film Grain

Helper function for the very realistic grain generator fgrain that animates the grain, adds opacity options, and support for YUV. Grain is only applied to luma. Requires an Nvidia GPU.

import vs_grain
clip = vs_grain.fgrain(clip, iterations=800, size=0.3, deviation=0.0, blur=0.8, opacity=[0.5, 0.5, 0.5], num_streams=1)

clip
Clip to apply grain to.
Must be in YUV or GRAY format.

iterations
Higher values look more realistic. Lower values are faster but result in grain that looks less natural.

size
Average size of grain particles.

deviation
Deviation of size, or how much variation there is in the size of grain particles. High values can cause bad outputs, use with caution.

blur
Generates smoother grain.

opacity
Opacity of generated grain. Can be a list [0.5, 1.0, 0.5] for shadows/midtones/highlights, or a single value for everything.

num_streams
Number of parallel GPU streams. For high end GPUs higher can be a bit faster, but requires more VRAM.

[!TIP] If fgrain is too slow for you, try generating a short grain clip on neutral mid-gray background and then use the overlay function to apply it to the whole clip.

Overlay Grain Clip

Bring your own grain clip and overlay it on top of your base clip. This automatically loops the grain clip, crops if too large or stacks if too small.

import vs_grain
clip = vs_grain.overlay(clip, grain, blend_mode="overlay", size=1.0, blur=0.0, opacity=[1.0, 1.0, 1.0], planes=[0, 1, 2])

clip
Clip to apply grain to.
Must be in YUV or GRAY format.

grain
Grain clip to overlay. This is expected to be grain on a neutral mid-gray background.
Must be the same format as the base clip.

blend_mode
Method used to blend the grain clip with the base clip. Available blend modes:

• grainshow Shows the grain without blending.
• grainmerge Grain is applied everywhere with the same impact.
• grainextract Inverse of grainmerge. Removes grain added via grainmerge.
• overlay Grain has strongest impact in midtones and fades toward shadows/highlights.
• hardlight Opposite of overlay, meaning grain gets stronger toward shadows/highlights.
• softlight Similar to overlay, but dark grains get weaker in shadows and bright grains get weaker in highlights.
• vividlight Dark grains get stronger in shadows and bright grains get stronger in highlights.

size
Multiplicator to resize grain clip. Will automatically crop if too large or repeat if too small.

blur
Smoothes the grain by blurring the grain clip.

opacity
Opacity of grain clip. Can be a list [0.5, 1.0, 0.5] for shadows/midtones/highlights, or a single value for everything.

planes
Which planes should be affected by the grain clip. Any unmentioned planes will simply be copied.
If nothing is set, the grain will be applied to all planes.