How to Use xfade_opencl in FFmpeg for Transitions

This article provides a practical guide on using the xfade_opencl filter in FFmpeg to create hardware-accelerated video transitions. You will learn the necessary prerequisites, how to initialize an OpenCL device, the required filtergraph pipeline for processing frames on the GPU, and a complete working command-line example.

Prerequisites

To utilize xfade_opencl, your system must meet two requirements:

  1. An FFmpeg build compiled with OpenCL support (--enable-opencl). You can verify this by running ffmpeg -buildconf and checking for --enable-opencl.
  2. Working OpenCL drivers and runtimes installed for your GPU (Intel, AMD, or NVIDIA).

Understanding the OpenCL Pipeline

Unlike the software-based xfade filter, xfade_opencl requires frames to be located in OpenCL device memory. A standard workflow follows these steps:

  1. Initialize the OpenCL hardware device.
  2. Convert video frames into a pixel format supported by the OpenCL filter (typically yuv420p or nv12).
  3. Upload frames to the GPU using hwupload.
  4. Apply the xfade_opencl filter.
  5. Download frames back to system memory with hwdownload (or route them to a hardware encoder).

Command Syntax and Parameters

The primary parameters for xfade_opencl are identical to the standard xfade filter:

  • transition: The transition effect to apply (e.g., fade, wipeleft, wiperight, slideup, slidedown, circlecrop).
  • duration: The length of the transition in seconds.
  • offset: The timestamp (in seconds) in the first video where the transition begins.

Complete FFmpeg Example

The following command takes two 5-second videos, initiates an OpenCL device, and blends them using a 1-second fade starting at the 4-second mark:

ffmpeg -init_hw_device opencl=gpu:0.0 -filter_hw_device gpu \
  -i input1.mp4 -i input2.mp4 \
  -filter_complex \
  "[0:v]format=yuv420p,hwupload[v0]; \
   [1:v]format=yuv420p,hwupload[v1]; \
   [v0][v1]xfade_opencl=transition=fade:duration=1:offset=4[v_gpu]; \
   [v_gpu]hwdownload,format=yuv420p[vout]" \
  -map "[vout]" -c:v libx264 -pix_fmt yuv420p output.mp4

Breakdown of the Command

  • -init_hw_device opencl=gpu:0.0: Initializes OpenCL on the first platform and device, naming the context gpu.
  • -filter_hw_device gpu: Sets the default hardware device context for the filtergraph.
  • format=yuv420p,hwupload: Standardizes the pixel layout and pushes the input video frames into GPU VRAM.
  • [v0][v1]xfade_opencl=...: Executes the transition on the GPU hardware.
  • hwdownload,format=yuv420p: Retrieves the rendered frames from GPU memory and sets the pixel format for the software encoder (libx264).