How to Configure HDR10 in FFmpeg with libx265

Encoding High Dynamic Range (HDR) video requires precise metadata signaling to ensure compatible displays render colors and brightness levels correctly. This article provides a straightforward guide on how to configure the HDR10 option using the libx265 encoder in FFmpeg, covering the necessary color space parameters, 10-bit pixel formatting, and mastering display metadata.

To encode a video in HDR10, you must configure three key components: 10-bit color depth, VUI (Video Usability Information) color parameters, and HDR10-specific metadata (Mastering Display Color Volume and Content Light Level) via libx265 parameters.

1. Set the Pixel Format to 10-bit

HDR10 requires a 10-bit color depth. In FFmpeg, this is specified using the -pix_fmt flag. For standard HDR10 compatibility, use:

-pix_fmt yuv420p10le

2. Configure VUI Color Parameters

You must tell the decoder how to interpret the color space. HDR10 uses the BT.2020 color primaries and the SMPTE ST 2084 (PQ) transfer characteristics. Add the following flags to your FFmpeg command:

-color_primaries bt2020 -color_trc smpte2084 -colorspace bt2020nc

3. Add HDR10 Metadata via libx265-params

The libx265 encoder requires specific mastering metadata to optimize the video for HDR displays. This is passed through the -x265-params argument.

The critical parameters are: * hdr10=1: Enables HDR10 routing and flags the stream as HDR10. * mastering-display: Defines the color primaries, white point, and luminance range of the mastering monitor. The values are expressed in increments of 0.00002 for coordinates, and 0.0001 cd/m² (nits) for luminance. * max-cll: Defines the Maximum Content Light Level (MaxCLL) and Maximum Frame-Average Light Level (MaxFALL) in nits.

Here is an example string for a standard 1000-nit DCI-P3 mastering monitor:

-x265-params "hdr10=1:mastering-display=G(13250,34500)B(7500,3000)R(34000,16000)WP(15635,16450)L(10000000,1):max-cll=1000,400"

Complete Command Example

Combining all these elements into a single FFmpeg command yields the following configuration:

ffmpeg -i input.mp4 -c:v libx265 -crf 18 \
-pix_fmt yuv420p10le \
-color_primaries bt2020 \
-color_trc smpte2084 \
-colorspace bt2020nc \
-x265-params "hdr10=1:mastering-display=G(13250,34500)B(7500,3000)R(34000,16000)WP(15635,16450)L(10000000,1):max-cll=1000,400" \
-c:a copy output.mp4

By applying these settings, the output file will contain the correct HDR10 flags and metadata, allowing HDR-compatible televisions, monitors, and media players to trigger HDR mode automatically.