How to Use unsharp_opencl in FFmpeg

This article provides a quick overview and practical guide on how to use the unsharp_opencl filter in FFmpeg. You will learn how to leverage OpenCL hardware acceleration to apply sharpening or blurring effects to your videos, reducing CPU usage by offloading the processing to your graphics card (GPU).

The unsharp_opencl filter is the hardware-accelerated counterpart to FFmpeg’s standard unsharp filter. It uses OpenCL to perform image sharpening and blurring, which is highly beneficial for processing high-resolution video streams like 4K in real-time.

Prerequisites

Before using the filter, ensure your system meets the following requirements: 1. FFmpeg with OpenCL support: Your FFmpeg binary must be compiled with the --enable-opencl flag. You can verify this by running ffmpeg -protocols or ffmpeg -buildconf and looking for OpenCL. 2. GPU Drivers: You must have compatible OpenCL drivers installed for your Nvidia, AMD, or Intel GPU.

Basic Syntax and Command Structure

Because OpenCL operates on GPU memory, you cannot simply apply the filter directly to a standard CPU-decoded video stream. You must initialize the OpenCL hardware device, upload the video frames to the GPU, apply the filter, and then download the frames back to system memory (unless you are encoding using a hardware encoder).

Here is the template for a basic command using CPU decoding/encoding and OpenCL processing:

ffmpeg -init_hw_device opencl=gpu:0 -filter_hw_device gpu -i input.mp4 -vf "format=nv12,hwupload,unsharp_opencl=luma_amount=1.5,hwdownload,format=nv12" output.mp4

Command Breakdown:

• -init_hw_device opencl=gpu:0: Initializes the OpenCL hardware device. gpu:0 refers to the first available GPU.
• -filter_hw_device gpu: Instructs FFmpeg to use the newly initialized GPU device for filtering.
• format=nv12: Converts the input video to a compatible pixel format before uploading.
• hwupload: Uploads the video frames from system memory to GPU memory.
• unsharp_opencl=luma_amount=1.5: Applies the OpenCL sharpening filter to the luma channel.
• hwdownload: Downloads the processed frames from GPU memory back to system memory.
• format=nv12: Restores the appropriate software pixel format for the output encoder.

Filter Parameters

The unsharp_opencl filter accepts several parameters to fine-tune the sharpening or blurring effect:

• luma_msize_x / luma_msize_y: Sets the horizontal and vertical kernel size for the luma channel. Must be an odd integer between 3 and 23 (default is 5).
• luma_amount: The strength of the effect for the luma channel.
  • A positive value (e.g., 1.5) sharpens the image.
  • A negative value (e.g., -1.5) blurs the image.
  • Default is 1.0. Range is -2.0 to 5.0.
• chroma_msize_x / chroma_msize_y: Sets the horizontal and vertical kernel size for the chroma (color) channels. Must be an odd integer between 3 and 23 (default is 5).
• chroma_amount: The strength of the effect for the chroma channel (default is 0.0, which leaves color sharpening disabled).

Practical Examples

Strong Sharpening Example

To apply a strong sharpening effect to both the luma (brightness) and chroma (color) channels:

ffmpeg -init_hw_device opencl=gpu -filter_hw_device gpu -i input.mp4 -vf "format=nv12,hwupload,unsharp_opencl=luma_msize_x=7:luma_msize_y=7:luma_amount=2.0:chroma_msize_x=5:chroma_msize_y=5:chroma_amount=1.0,hwdownload,format=nv12" -c:v libx264 -c:a copy output.mp4

Soft Blur Example

To apply a slight blur effect instead of sharpening, use negative amount values:

ffmpeg -init_hw_device opencl=gpu -filter_hw_device gpu -i input.mp4 -vf "format=nv12,hwupload,unsharp_opencl=luma_amount=-1.0:chroma_amount=-1.0,hwdownload,format=nv12" -c:v libx264 -c:a copy output.mp4