How to Use xfade_opencl Filter in FFmpeg

This article provides a practical guide on how to use the xfade_opencl filter in FFmpeg to create hardware-accelerated video transitions. You will learn the required system prerequisites, the core syntax for command implementation, and a complete example of executing a GPU-accelerated transition between two video clips.

Prerequisites

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

  • FFmpeg compiled with OpenCL support: Verify this by running ffmpeg -protocols or ffmpeg -version and looking for --enable-opencl in the configuration flags.
  • Compatible GPU and Drivers: Ensure you have appropriate OpenCL drivers (Intel, AMD, or NVIDIA) installed on your system.

The Basic Command Structure

Because xfade_opencl operates directly on the GPU, you cannot pass standard system-memory video frames directly into it. You must initialize the OpenCL hardware device, upload the video frames to the GPU, apply the filter, and then download the processed frames back to system memory.

Here is the template for the command:

ffmpeg -init_hw_device opencl=gpu -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=5[v_out]; \
 [v_out]hwdownload,format=yuv420p[out]" \
-map "[out]" output.mp4

Parameter Breakdown

  • -init_hw_device opencl=gpu: Initializes the OpenCL hardware acceleration device and labels it as gpu.
  • -filter_hw_device gpu: Instructs the filter graph to use the initialized gpu device for hardware-accelerated filters.
  • format=yuv420p,hwupload: Converts the input video to a compatible pixel format (usually yuv420p or nv12) and uploads it to GPU memory.
  • xfade_opencl options:
    • transition: The type of transition effect (e.g., fade, wipeleft, wiperight, slideup).
    • duration: The length of the transition in seconds (e.g., 1 for one second).
    • offset: The timestamp (in seconds) in the first video where the transition should begin. If your first video is 6 seconds long and you want a 1-second transition at the end, the offset should be 5.
  • hwdownload,format=yuv420p: Retrieves the processed video frames from the GPU back to system memory and restores the pixel format for encoding.

Supported Transitions

The xfade_opencl filter supports a variety of transition effects similar to the CPU-based xfade filter. Common transition names include:

  • fade
  • wipeleft / wiperight / wipeup / wipedown
  • slideleft / slideright / slideup / slidedown
  • circlecrop

To see the full list of transitions supported by your specific FFmpeg build, you can run:

ffmpeg -h filter=xfade_opencl