How to Use the FFmpeg unsharp_opencl Filter

This article provides a quick guide on how to use the hardware-accelerated unsharp_opencl filter in FFmpeg to sharpen or blur your videos. You will learn the system prerequisites, the core parameters of the filter, and how to construct a working FFmpeg command that utilizes OpenCL GPU acceleration to process video frames efficiently.

Prerequisites for OpenCL in FFmpeg

To use the unsharp_opencl filter, your system must meet the following requirements:

  1. GPU Drivers: You must have compatible graphics drivers installed (NVIDIA, AMD, or Intel) that support OpenCL.
  2. FFmpeg Build: Your FFmpeg binary must be compiled with OpenCL support enabled (configured with --enable-opencl). You can verify this by running ffmpeg -protocols or checking the configuration banner of your FFmpeg output.

Syntax and Key Parameters

The unsharp_opencl filter accepts several parameters to control the sharpening or blurring effect. The most commonly used options include:

  • luma_msize_x / luma_msize_y: Set the horizontal and vertical kernel size for the luma channel. These must be odd integers between 3 and 23 (default is 5).
  • luma_amount: Set the strength of the effect for the luma channel. It ranges from -1.5 to 1.5. Positive values sharpen the image, while negative values blur it (default is 0.0).
  • chroma_msize_x / chroma_msize_y: Set the horizontal and vertical kernel size for the chroma channels (default is 5).
  • chroma_amount: Set the strength of the effect for the chroma channels, ranging from -1.5 to 1.5 (default is 0.0).

Example Command

Because unsharp_opencl runs on the GPU, you must initialize the OpenCL device and upload the video frames to the GPU memory (hwupload) before applying the filter. If you are encoding back to a standard CPU-based codec, you must download the frames back to system memory (hwdownload) and format them correctly.

Below is a standard command to sharpen a video using unsharp_opencl:

ffmpeg -init_hw_device opencl=gpu -filter_hw_device gpu -i input.mp4 -filter_complex "[0:v]format=yuv420p,hwupload,unsharp_opencl=luma_msize_x=5:luma_msize_y=5:luma_amount=1.0,hwdownload,format=yuv420p" -c:v libx264 -c:a copy output.mp4

Command Breakdown:

  • -init_hw_device opencl=gpu: Initializes an OpenCL hardware device named "gpu".
  • -filter_hw_device gpu: Instructs the filter graph to use the initialized "gpu" device for filtering.
  • format=yuv420p,hwupload: Converts the input video to a compatible pixel format and uploads the frames to GPU memory.
  • unsharp_opencl=luma_msize_x=5:luma_msize_y=5:luma_amount=1.0: Applies a 5x5 sharpening matrix to the luma channel with a strength of 1.0.
  • hwdownload,format=yuv420p: Downloads the processed frames back to system memory and restores the standard YUV 4:2:0 pixel format for software encoding.
  • -c:v libx264 -c:a copy: Encodes the output video using the H.264 codec while copying the audio without re-encoding.