How to Use vmaf_cuda in FFmpeg

This article explains how to use the vmaf_cuda filter in FFmpeg to perform hardware-accelerated video quality evaluation using Nvidia GPUs. You will learn the prerequisites, the basic command syntax, and how to configure the filter to utilize your graphics card for faster VMAF score calculations.

Prerequisites

Before using the vmaf_cuda filter, ensure your system meets the following requirements:

• Nvidia GPU: A CUDA-enabled Nvidia graphics card.
• Nvidia CUDA Toolkit: Installed and configured on your system.
• FFmpeg with CUDA and VMAF support: FFmpeg must be compiled with --enable-cuda-llvm (or --enable-nvcc), --enable-libvmaf, and --enable-ffnvcodec.
• VMAF Model File: You need the official VMAF model file (usually in .json format, such as vmaf_v0.6.1.json), which can be downloaded from the official VMAF repository.

Basic Command Syntax

The vmaf_cuda filter requires both the reference video and the distorted video to be loaded into CUDA memory. To achieve the best performance, you should decode both videos on the GPU using hardware acceleration.

Here is the standard command template for running vmaf_cuda:

ffmpeg -hwaccel cuda -hwaccel_output_format cuda -i distorted.mp4 \
-hwaccel cuda -hwaccel_output_format cuda -i reference.mp4 \
-filter_complex "[0:v]scale_cuda=format=yuv420p[dist]; [1:v]scale_cuda=format=yuv420p[ref]; [dist][ref]vmaf_cuda=model=vmaf_v0.6.1.json" \
-f null -

Command Breakdown

• -hwaccel cuda: Tells FFmpeg to use Nvidia GPU hardware acceleration to decode the input videos.
• -hwaccel_output_format cuda: Ensures the decoded frames remain in CUDA device memory instead of being copied back to system RAM.
• scale_cuda=format=yuv420p: Converts the pixel format of the decoded frames on the GPU to yuv420p, which is the format expected by the VMAF model.
• vmaf_cuda=model=vmaf_v0.6.1.json: Invokes the CUDA-accelerated VMAF filter and points it to your local VMAF model file.
• -f null -: Discards the visual output since you only need the text-based VMAF scores.

Saving VMAF Scores to a File

To analyze the frame-by-frame or summary results later, you can instruct the filter to write the scores to an external log file (such as XML, JSON, or CSV).

Use the following command to output the results to a JSON file:

ffmpeg -hwaccel cuda -hwaccel_output_format cuda -i distorted.mp4 \
-hwaccel cuda -hwaccel_output_format cuda -i reference.mp4 \
-filter_complex "[0:v]scale_cuda=format=yuv420p[dist]; [1:v]scale_cuda=format=yuv420p[ref]; [dist][ref]vmaf_cuda=model=vmaf_v0.6.1.json:log_path=vmaf_results.json:log_fmt=json" \
-f null -

Key Parameters for Logging

• log_path: Specifies the file path where the results will be saved.
• log_fmt: Sets the output format. You can choose xml, json, csv, or sub (for subtitles).

Scaling and Resolution Matching

VMAF requires the distorted and reference videos to have the exact same resolution. If your distorted video has been downscaled, you must scale it back to the reference resolution using scale_cuda before passing it to the vmaf_cuda filter:

ffmpeg -hwaccel cuda -hwaccel_output_format cuda -i distorted_720p.mp4 \
-hwaccel cuda -hwaccel_output_format cuda -i reference_1080p.mp4 \
-filter_complex "[0:v]scale_cuda=1920:1080:format=yuv420p[dist]; [1:v]scale_cuda=format=yuv420p[ref]; [dist][ref]vmaf_cuda=model=vmaf_v0.6.1.json" \
-f null -

By keeping the entire pipeline (decoding, scaling, and VMAF calculation) on the GPU, you avoid CPU bottlenecks and PCI-Express bandwidth limitations, resulting in much faster quality assessment.