How to Use tonemap_vaapi Filter in FFmpeg

This article explains how to use the tonemap_vaapi filter in FFmpeg to perform hardware-accelerated High Dynamic Range (HDR) to Standard Dynamic Range (SDR) tone mapping. You will learn the required command-line syntax, key parameters, and a practical example to convert HDR videos using Intel VAAPI hardware acceleration.

Understanding tonemap_vaapi

The tonemap_vaapi filter is a hardware-accelerated filter in FFmpeg designed for Intel graphics processors. It converts HDR video (typically BT.2020 color space) to SDR video (typically BT.709 color space) directly on the GPU. This process significantly reduces CPU usage and increases conversion speed compared to software-based tone mapping filters like zscale or tonemap.

Prerequisites

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

  • An Intel processor with integrated graphics or a dedicated Intel GPU supporting VAAPI.
  • FFmpeg compiled with VAAPI support (--enable-vaapi).
  • Appropriate graphics drivers (such as intel-media-driver or libva-intel-driver on Linux).

Basic Command Syntax

To use tonemap_vaapi, you must decode the input video in hardware, apply the filter, and then encode the output using a VAAPI encoder (such as h264_vaapi or hevc_vaapi).

Here is a standard command to perform the conversion:

ffmpeg -init_hw_device vaapi=gpu:/dev/dri/renderD128 -hwaccel vaapi -hwaccel_output_format vaapi -i input_hdr.mp4 -filter_hw_device gpu -vf "tonemap_vaapi=format=nv12:matrix=bt709:transfer=bt709:primaries=bt709" -c:v h264_vaapi -c:a copy output_sdr.mp4

Command Breakdown

  • -init_hw_device vaapi=gpu:/dev/dri/renderD128: Initializes the VAAPI hardware device using the specified render node.
  • -hwaccel vaapi: Enables VAAPI hardware acceleration for decoding.
  • -hwaccel_output_format vaapi: Keeps the decoded video frames in GPU memory to avoid overhead.
  • -filter_hw_device gpu: Directs the filter graph to use the initialized hardware device.
  • -vf "tonemap_vaapi=...": Applies the tone mapping filter with the following parameters:
    • format=nv12: Converts the pixel format from 10-bit (P010) to 8-bit (NV12) for standard compatibility.
    • matrix=bt709: Sets the output color matrix to BT.709.
    • transfer=bt709: Sets the output transfer characteristics (gamma curve) to BT.709.
    • primaries=bt709: Sets the output color primaries to BT.709.
  • -c:v h264_vaapi: Encodes the output video using the VAAPI H.264 hardware encoder.
  • -c:a copy: Copies the audio stream without re-encoding to save time.

Customizing Tone Mapping Parameters

The tonemap_vaapi filter allows you to fine-tune the output image quality using additional parameters inside the filter chain:

  • brightness: Adjusts the brightness of the output (range: -100.0 to 100.0, default: 0.0).
  • contrast: Adjusts the contrast of the output (range: -100.0 to 100.0, default: 0.0).
  • saturation: Adjusts the color intensity (range: -100.0 to 100.0, default: 0.0).

Example with adjustments:

ffmpeg -init_hw_device vaapi=gpu:/dev/dri/renderD128 -hwaccel vaapi -hwaccel_output_format vaapi -i input_hdr.mp4 -filter_hw_device gpu -vf "tonemap_vaapi=format=nv12:matrix=bt709:transfer=bt709:primaries=bt709:contrast=10:saturation=5" -c:v h264_vaapi output_sdr.mp4