How to Use the unsharp_opencl Filter in FFmpeg

This article provides a quick, step-by-step guide on how to accelerate video sharpening in FFmpeg using the GPU-powered unsharp_opencl filter. You will learn how to initialize OpenCL, upload video frames to your graphics hardware, apply the sharpening filter, and download the processed frames back for final encoding.

To run the unsharp_opencl filter, your version of FFmpeg must be compiled with OpenCL enabled (typically configured with the --enable-opencl flag). Because OpenCL runs on the GPU, you must explicitly initialize your hardware device and transfer the video frames to GPU memory before applying the filter.

1. The Basic Command Structure

Below is the standard command template used to run the unsharp_opencl filter:

ffmpeg -init_hw_device opencl=gpu:0 -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:a copy output.mp4

2. Command Breakdown

  • -init_hw_device opencl=gpu:0: Initializes the OpenCL hardware device. gpu:0 selects the first available graphics card on your system.
  • -filter_hw_device gpu: Instructs FFmpeg to use the newly initialized GPU device for processing hardware filters.
  • format=yuv420p,hwupload: Converts the input video to a compatible pixel format and uploads the frames from system memory (RAM) to GPU memory (VRAM).
  • unsharp_opencl=...: Applies the hardware-accelerated sharpening filter.
  • hwdownload,format=yuv420p: Downloads the processed frames from GPU memory back to system memory and restores the pixel format for the encoder.

3. Adjusting Filter Parameters

You can fine-tune the sharpening effect by modifying the parameters of the unsharp_opencl filter. The most common parameters include:

  • luma_msize_x and luma_msize_y: Sets the horizontal and vertical kernel size for the luma (brightness) matrix. This must be an odd integer between 3 and 23 (default is 5).
  • luma_amount: Controls the strength of the sharpening effect for luma. A positive float (e.g., 1.5) sharpens the image, while a negative float blurs it (default is 1.0).
  • chroma_msize_x and chroma_msize_y: Sets the horizontal and vertical kernel size for chroma (color) channels.
  • chroma_amount: Controls the sharpening or blurring strength for the color channels.

Example with custom parameters:

ffmpeg -init_hw_device opencl=ocl -filter_hw_device ocl -i input.mp4 -filter_complex "[0:v]format=yuv420p,hwupload,unsharp_opencl=luma_msize_x=7:luma_msize_y=7:luma_amount=1.5:chroma_msize_x=3:chroma_msize_y=3:chroma_amount=0.5,hwdownload,format=yuv420p" output.mp4