vs-temporalfix 2.2.0

Add Temporal Coherence to Single Image AI Upscaling Models in Vapoursynth

Add Temporal Coherence to AI Upscales in VapourSynth

When using SISR models (single image super resolution) on video, they tend to create slightly different results each frame. Temporalfix is a post filter that averages these results over multiple frames, removing temporal inconsistencies like fizzle or wiggly lines. Also known as stabilization, deshimmering, temporal denoising, or temporal fix.

https://github.com/user-attachments/assets/13f05267-cd61-4de9-ad7f-ce8030102465

Installation

pip install -U vs_temporalfix

• Temporalfix AI Model: To enable the CPU/CUDA backends, install PyTorch with CUDA. (optional)
• Temporalfix Classic: For tr > 6 support, install mvtools-sf and FFTW 3.3 to your plugin directory. (optional)

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

Temporalfix AI Model

The newest and most capable version of temporalfix. It is easy to use and can run very fast on Nvidia GPUs.

import vs_temporalfix
clip = vs_temporalfix.model(clip, strength=2.0, tiles=1, backend="tensorrt", num_streams=1, engine_folder=None, exclude=None)

clip
Temporally unstable upscaled clip. Must be in RGB format.

strength
Suppression strength of temporal inconsistencies in the 0.0-3.0 range. Higher means more aggressive.
Higher resolution tends to need higher strength. Too high may oversmooth small movements.

tiles (optional)
A higher amount of tiles will reduce VRAM usage at the cost of speed.
This should only be needed on low end hardware. Default tiles=1 uses the full frame, which is fastest.

backend (optional)
The backend used to run the model:

• cpu CPU mode using PyTorch (very slow).
• cuda GPU mode using PyTorch with CUDA support. Requires any Nvidia GPU (fast).
• tensorrt GPU mode using vs-mlrt with TensorRT support. Requires an Nvidia RTX GPU. On the first run, this mode will automatically build an engine, which may take a few minutes. Changing strength or input dimensions will trigger rebuilding, but previously build engines are stored (very fast).

num_streams (optional)
Number of parallel TensorRT streams. For high end GPUs higher can be faster, but requires more VRAM. Only effects the TensorRT backend.

engine_folder (optional)
Optional path to the TensorRT engine storage location. By default engines are stored in vs_temporalfix/engines. Only effects the TensorRT backend.

exclude (optional)
Optionally exclude scenes with intended temporal inconsistencies.
Brackets define excluded frame ranges. Example for two scenes: exclude="[10 20] [600 900]"

[!TIP] Feedback is much appreciated. If the model does not work well for you or causes issues, feel free to open an issue, or contact me via Discord (pifroggi or tepete) and provide a sample. That will help improve it over time.

Temporalfix Classic

The original CPU based version. It is slower, harder to use, may miss some areas, and only works well for 2D animation.

core.max_cache_size = 15000  # Add near top of vapoursynth script to increase frame cache, else temporalfix will be slow. High tr and resolution, or large filter scripts may need more.
import vs_temporalfix
clip = vs_temporalfix.classic(clip, strength=500, tr=6, denoise=False, exclude=None, debug=False)

clip
Temporally unstable upscaled clip. Any format.

strength
Suppression strength of temporal inconsistencies. Higher means more aggressive. 400-700 works great in most cases.
The best way to finetune is to find a static scene and adjust till lines and details are stable.
Reduce if you get blending/ghosting on small movements, especially in dark or hazy scenes.

tr
Temporal radius sets the number of frames to average over.
Higher means more stable, especially on slow pans and zooms, but is slower. 6 works great in most cases.
The best way to finetune is to find a slow pan or zoom and adjust till lines and details are stable.

denoise (optional)
Removes grain and low frequency noise/flicker left over by the main processing step. Only enable if these issues actually exist! It risks to remove some details like every denoiser, but is useful if you're planning to denoise anyway and has the benefit of almost no performance impact compared to using an additional denoising filter.

exclude (optional)
Optionally exclude scenes with intended temporal inconsistencies.
Brackets define excluded frame ranges. Example for two scenes: exclude="[10 20] [600 900]"

debug (optional)
Shows areas that will not be fixed in pink. This includes areas with high motion, scene changes and excluded scenes. Can help while tuning parameters to see if the area is even affected.

[!TIP]

• Crop any black borders on the input clip! In temporalfix classic they can cause ghosting on bright frames.
• There is a big drop in performance for tr > 6, due to switching from mvtools to mvtools-sf, which is slower.

Benchmarks

Model benchmarks were done on a RTX 4090 GPU and Classic benchmarks on a Ryzen 5900X CPU.

AI Model Resolution TensorRT CUDA 720x480 ~320 fps ~70 fps 1440x1080 ~80 fps ~32 fps 2880x2160 ~20 fps ~8 fps

Classic Resolution YUV444 YUV420 GRAY 720x480 ~45 fps ~60 fps ~85 fps 1440x1080 ~10 fps ~14 fps ~20 fps 2880x2160 ~5.5 fps ~8 fps ~11 fps

Third-Party Integrations

Several projects integrated temporalfix to simplify usage without the need for vapoursynth knowledge. Feel free to contact me if you want to be part of this list.

• Vapourkit (Windows only)
  Video filter and upscaling program with an easy GUI. This is the easiest way to use it. Just click on add filter and add one of the two Temporalfix versions.
• Hybrid (Windows and Linux)
  Video filter toolbox with a GUI. Can be a bit overwhelming due to the amount of features and filters, but Temporalfix is one of them.
• VSGAN-tensorrt-docker (Windows and Linux)
  Command line AI upscale and interpolation toolbox that comes with both versions of Temporalfix. Rudimentary knowledge of Docker and VapourSynth is recommended, but the readme also explains it.
• mpv-cHiDeNoise-AI (Windows only)
  AI upscaling video player based on mpv, which includes the Temporalfix AI Models and a lighter modified version of Temporalfix Classic for real-time playback. Mainly intended for japanese audience.