Configure libx265 Color Description in FFmpeg

This guide explains how to configure color description parameters—specifically color primaries, transfer characteristics, and matrix coefficients—when encoding video using the libx265 HEVC encoder in FFmpeg. You will learn the specific FFmpeg flags and x265-params options required to tag your video correctly so media players display colors accurately for both SDR and HDR formats.

The Three Essential Color Parameters

To accurately define color space in a video container, you must set three parameters:

1. Color Primaries: Defines the color gamut (the range of colors, e.g., BT.709 for HD, BT.2020 for Ultra HD/HDR).
2. Transfer Characteristics: Defines the gamma curve/dynamic range (e.g., BT.709 for standard dynamic range, SMPTE 2084 for HDR10, ARIB STD-B67 for HLG).
3. Matrix Coefficients: Defines the transformation matrix used to convert RGB to YUV (e.g., BT.709 or BT.2020 non-constant luminance).

Method 1: Using Native FFmpeg Flags (Recommended)

The easiest way to configure these parameters is by using native FFmpeg flags. Modern versions of FFmpeg will automatically map these flags to the underlying libx265 encoder parameters.

ffmpeg -i input.mp4 -c:v libx265 -crf 22 \
-color_primaries bt2020 \
-color_trc smpte2084 \
-colorspace bt2020nc \
output.mp4

Method 2: Using the -x265-params Flag

If you want to pass the parameters directly to the libx265 encoder interface, you can use the -x265-params argument. In x265, these parameters are shortened to colorprim, transfer, and colormatrix.

Multiple parameters inside -x265-params must be separated by colons (:).

ffmpeg -i input.mp4 -c:v libx265 -crf 22 \
-x265-params colorprim=bt2020:transfer=smpte2084:colormatrix=bt2020nc \
output.mp4

Common Configurations

Depending on your source material and target delivery format, use one of the standard configurations below:

1. Standard HD Video (SDR BT.709)

Use this configuration for standard HD Web delivery. * FFmpeg Flags: -color_primaries bt709 -color_trc bt709 -colorspace bt709 * x265 Parameters: -x265-params colorprim=bt709:transfer=bt709:colormatrix=bt709

2. HDR10 Video (Ultra HD BT.2020 with PQ)

Use this configuration for standard HDR10 content. It requires the SMPTE 2084 transfer function. * FFmpeg Flags: -color_primaries bt2020 -color_trc smpte2084 -colorspace bt2020nc * x265 Parameters: -x265-params colorprim=bt2020:transfer=smpte2084:colormatrix=bt2020nc

3. HLG Video (Hybrid Log-Gamma BT.2020)

Use this configuration for broadcast-style HDR. * FFmpeg Flags: -color_primaries bt2020 -color_trc arib-std-b67 -colorspace bt2020nc * x265 Parameters: -x265-params colorprim=bt2020:transfer=arib-std-b67:colormatrix=bt2020nc

Verifying the Configuration

To confirm that the color metadata was successfully embedded into the output file, use ffprobe:

ffprobe -of default=noprint_wrappers=1 -show_entries stream=color_primaries,color_transfer,color_space output.mp4