How to Use the overlay_cuda Filter in FFmpeg

This article provides a straightforward guide on how to use the overlay_cuda filter in FFmpeg for hardware-accelerated video overlaying. You will learn the basic syntax, system requirements, and practical command-line examples to overlay videos or images using NVIDIA GPU acceleration.

Prerequisites

To use overlay_cuda, your system must meet the following requirements:

  • An NVIDIA GPU that supports NVDEC and NVENC.
  • NVIDIA graphic drivers installed.
  • A build of FFmpeg compiled with CUDA support (specifically enabling --enable-cuda-nvcc or --enable-ffnvcodec and --enable-libnpp).

Basic Command Structure

The overlay_cuda filter requires both input streams to reside in CUDA device memory. If your inputs are decoded on the CPU, you must upload them to the GPU using the hwupload_cuda filter. If they are decoded on the GPU, they are already in the correct memory space.

Here is the standard command for overlaying two hardware-decoded video streams:

ffmpeg -hwaccel cuda -hwaccel_output_format cuda -i background.mp4 \
-hwaccel cuda -hwaccel_output_format cuda -i overlay.mp4 \
-filter_complex "[0:v][1:v]overlay_cuda=x=100:y=50[out]" \
-map "[out]" -c:v h264_nvenc output.mp4

Key Parameters

  • x: The horizontal position of the overlay video (defaults to 0).
  • y: The vertical position of the overlay video (defaults to 0).

Unlike the CPU-based overlay filter, overlay_cuda does not support complex math expressions (like main_w - overlay_w) directly in the coordinates. You must specify absolute pixel values.

Overlaying a Static Image (CPU to GPU Upload)

When overlaying a static image or a software-decoded video onto a hardware-decoded background, you must convert the format and upload the overlay to the GPU memory:

ffmpeg -hwaccel cuda -hwaccel_output_format cuda -i background.mp4 \
-i logo.png \
-filter_complex "[1:v]format=nv12,hwupload_cuda[logo];[0:v][logo]overlay_cuda=x=10:y=10[out]" \
-map "[out]" -c:v h264_nvenc output.mp4

In this command:

  1. format=nv12 converts the image to a pixel format compatible with CUDA processing.
  2. hwupload_cuda uploads the converted image to the GPU.
  3. overlay_cuda merges the GPU-resident background and logo.