The Pain of GPU VMAF on Windows, Solved

Running GPU-accelerated Video Multimethod Assessment Fusion (VMAF) on Windows has been a notoriously difficult task. Developers have grappled with complex build processes, cryptic errors, and a general lack of clear documentation. The most reliable path to achieving significant speedups, often yielding around 15x faster analysis compared to CPU-bound methods, involves a specific stack: Windows Subsystem for Linux 2 (WSL2), Docker Desktop, the NVIDIA Container Toolkit, and a CUDA-enabled build of FFmpeg. This guide outlines how to leverage the easyVmaf project, which provides a pre-configured Dockerfile, to bypass the common pitfalls and achieve high-performance VMAF analysis.

The primary benefit of this setup is dramatic performance improvement. For instance, analyzing a 46-minute video can be reduced from an hour or more on a CPU to just about 3 minutes on an NVIDIA RTX 3060 Mobile GPU. This acceleration is critical for workflows involving frequent video quality assessments, such as during development, testing, or content production.

It's important to note that this solution is specifically tailored for NVIDIA GPUs. AMD and Intel GPUs are not supported by this particular setup due to the reliance on NVIDIA's CUDA ecosystem. This limitation underscores the vendor lock-in inherent in high-performance GPU computing, especially for specialized libraries like libvmaf_cuda.

Prerequisites for Setup

Before diving into the setup, ensure you have the following components installed and configured on your Windows machine:

  • Windows 11 or Windows 10 (version 21H2 or later): WSL2 requires a modern Windows version.
  • WSL2 Enabled: Install WSL2 and a Linux distribution (e.g., Ubuntu) from the Microsoft Store.
  • Docker Desktop for Windows: Download and install Docker Desktop, ensuring it's configured to use the WSL2 backend.
  • NVIDIA Drivers: Install the latest NVIDIA drivers for your GPU.
  • NVIDIA Container Toolkit: This is crucial for enabling GPU passthrough from Windows to the Docker container. Follow the official NVIDIA documentation for installation within your WSL2 Linux distribution.

Leveraging easyVmaf for Simplified Setup

The easyVmaf project, found on GitHub, simplifies this complex setup by providing a pre-built Dockerfile.cuda. This Dockerfile contains all the necessary dependencies and configurations to build and run libvmaf_cuda within a containerized environment. The project aims to abstract away the intricate build steps and environment management required for GPU-accelerated VMAF.

The core idea is to create a reproducible environment where VMAF can be executed without the host system needing direct installations of CUDA toolkits or specific FFmpeg versions. Docker handles the isolation, and the NVIDIA Container Toolkit ensures the container can access the host's GPU resources.

Step-by-Step Guide

Follow these steps to get GPU-accelerated VMAF running:

1. Clone the easyVmaf Repository

Start by cloning the easyVmaf repository to your WSL2 environment.

git clone https://github.com/gdavila/easyVmaf.git
cd easyVmaf

2. Build the Docker Image

The repository includes a Dockerfile.cuda. You will use this to build your Docker image. Ensure your Docker daemon is running and configured to use the WSL2 backend. Execute the following command in the cloned repository's root directory:

docker build --pull -t easyvmaf-cuda -f Dockerfile.cuda .

This command builds an image named easyvmaf-cuda. The --pull flag ensures that the base image is updated, and -f Dockerfile.cuda specifies the correct Dockerfile to use. The build process might take some time as it downloads dependencies and compiles FFmpeg with CUDA support.

Example terminal output showing Docker image build progress for easyVmaf-cuda

3. Prepare Input Files

You'll need a reference video and a test video for VMAF analysis. Place these files into a directory within your WSL2 filesystem that you intend to mount into the Docker container. For example, create a videos directory and place your files there.

mkdir videos
# Place your reference.mp4 and test.mp4 files into the ./videos directory

4. Run the VMAF Analysis

Now, run the Docker container, mounting your video directory and specifying the necessary NVIDIA runtime options. The --gpus all flag is essential for granting the container access to your GPU.

docker run --rm --gpus all -v $(pwd)/videos:/videos easyvmaf-cuda --reference /videos/reference.mp4 --test /videos/test.mp4 --output /videos/vmaf_results.json --model vmaf_4k --thread 0

Let's break down this command:

  • docker run: Command to run a Docker container.
  • --rm: Automatically remove the container when it exits.
  • --gpus all: Exposes all available GPUs to the container.
  • -v $(pwd)/videos:/videos: Mounts the local ./videos directory to /videos inside the container.
  • easyvmaf-cuda: The name of the Docker image you built.
  • --reference /videos/reference.mp4: Path to the reference video inside the container.
  • --test /videos/test.mp4: Path to the test video inside the container.
  • --output /videos/vmaf_results.json: Path for the output VMAF scores file.
  • --model vmaf_4k: Specifies the VMAF model to use (e.g., vmaf_4k, vmaf_4k_neg, vmaf_bt709).
  • --thread 0: Tells FFmpeg to use as many threads as possible, which, combined with GPU acceleration, can maximize performance.

The analysis will begin, and you should see output indicating the progress. The speed of this process is where the GPU acceleration truly shines. A simple test with a 1080p video might complete in seconds, while longer, higher-resolution videos will still be significantly faster than their CPU counterparts.

Troubleshooting Common Issues

Despite the simplified approach, you might encounter issues. Here are a few common ones:

  • NVIDIA Container Toolkit Not Found: Ensure the toolkit is correctly installed and configured within your WSL2 distribution. Verify that Docker Desktop is also set to use the WSL2 backend.
  • CUDA Errors during FFmpeg Build or Execution: This often points to driver mismatches or an incomplete CUDA installation. Double-check that your NVIDIA drivers are up-to-date and compatible with the CUDA toolkit version expected by the FFmpeg build.
  • Permission Denied Errors: When mounting volumes, ensure that the user running the Docker command has the necessary read/write permissions for the mounted directories.
  • Incorrect VMAF Model Specified: Make sure the --model argument corresponds to a valid VMAF model available in the FFmpeg build. Common models include vmaf_4k, vmaf_4k_neg, and vmaf_bt709.

Conclusion: A Viable Path for GPU VMAF on Windows

While the setup for GPU-accelerated VMAF on Windows remains complex, the combination of WSL2, Docker, and the NVIDIA Container Toolkit, as exemplified by the easyVmaf project, offers a practical and significantly faster solution. This approach allows developers and video professionals to harness the power of their NVIDIA GPUs for demanding video quality analysis tasks, drastically reducing processing times and enabling more efficient workflows. The key takeaway is that by containerizing the environment and leveraging NVIDIA's tools, the barrier to entry for high-performance VMAF on Windows is substantially lowered.