How to Use unsharp_opencl in FFmpeg

This article provides a complete guide on how to hardware-accelerate video sharpening and blurring using FFmpeg's unsharp_opencl filter. You will learn the prerequisites for running OpenCL with FFmpeg, the available parameters for controlling luma and chroma sharpness, and practical command-line examples to process your media efficiently on a GPU.

Prerequisites

To use unsharp_opencl, your FFmpeg build must be compiled with OpenCL support (--enable-opencl). You also need a compatible GPU (Intel, AMD, or NVIDIA) with the proper OpenCL runtime drivers installed on your operating system.

You can check if your FFmpeg build supports OpenCL by running:

ffmpeg -filters | grep unsharp_opencl

If unsharp_opencl appears in the output, your installation is ready.

Understanding the Filter Parameters

The unsharp_opencl filter works similarly to the standard software unsharp filter. It applies a Gaussian blur to a copy of the frame and subtracts it from the original to either sharpen or blur the image.

The primary parameters are:

  • lx / luma_msize_x: Horizontal matrix size for luma (odd integer between 3 and 23, default is 5).
  • ly / luma_msize_y: Vertical matrix size for luma (odd integer between 3 and 23, default is 5).
  • la / luma_amount: The strength of the luma effect (float from -1.5 to 1.5, default is 1.0).
    • Positive values sharpen the image.
    • Negative values blur the image.
    • 0.0 leaves the luma untouched.
  • cx / chroma_msize_x: Horizontal matrix size for chroma (odd integer between 3 and 23, default is 5).
  • cy / chroma_msize_y: Vertical matrix size for chroma (odd integer between 3 and 23, default is 5).
  • ca / chroma_amount: The strength of the chroma effect (float from -1.5 to 1.5, default is 0.0).

Command-Line Implementation

Because unsharp_opencl processes frames on the GPU, you must initialize an OpenCL device, upload the video frames from system memory to GPU memory, apply the filter, and then download them back (unless using a full hardware pipeline).

Here is a standard command to sharpen a video:

ffmpeg -init_hw_device opencl=ocl:0.0 -filter_hw_device ocl -i input.mp4 \
-vf "hwupload,unsharp_opencl=lx=5:ly=5:la=1.0,hwdownload,format=yuv420p" \
-c:v libx264 -crf 18 -c:a copy output.mp4

Breakdown of the Command

  • -init_hw_device opencl=ocl:0.0: Initializes the OpenCL device. 0.0 typically refers to the first platform and first device.
  • -filter_hw_device ocl: Sets the default hardware device for the filter graph to the initialized OpenCL context.
  • -vf "...": Defines the filter chain:
    • hwupload: Transfers standard CPU frames to OpenCL memory surfaces.
    • unsharp_opencl=lx=5:ly=5:la=1.0: Applies a 5x5 sharpening filter to the luma channel with an intensity of 1.0.
    • hwdownload: Retrieves the processed frames from GPU memory back to CPU memory.
    • format=yuv420p: Restores the pixel format to standard YUV420p to ensure compatibility with encoders like libx264.

Blurring Example

To blur instead of sharpen, set the amount parameters to negative values. The following command blurs both the luma and chroma planes using a larger 7x7 matrix:

ffmpeg -init_hw_device opencl=ocl:0.0 -filter_hw_device ocl -i input.mp4 \
-vf "hwupload,unsharp_opencl=lx=7:ly=7:la=-1.5:cx=7:cy=7:ca=-1.5,hwdownload,format=yuv420p" \
-c:v libx264 -c:a copy output.mp4