Set Color Primaries Transfer and Matrix in FFmpeg

This article explains how to configure the color primaries, transfer characteristics, and matrix coefficients in FFmpeg. You will learn the exact command-line parameters needed to tag your video files with the correct color metadata, ensuring accurate color reproduction and rendering across different media players, browsers, and devices.

The Core Command-Line Options

FFmpeg allows you to set color metadata directly using three primary encoder flags. These flags tell the player how to interpret the color space of the video stream:

• -color_primaries: Defines the color primaries (the color gamut, such as BT.709 or BT.2020).
• -color_trc: Defines the transfer characteristics (the gamma curve, such as BT.709, sRGB, or SMPTE 2084 for HDR10).
• -colorspace: Defines the matrix coefficients used to convert between YUV and RGB color spaces.

Example 1: Setting Standard HD Metadata (BT.709)

For standard high-definition (HD) video, you should set all three parameters to bt709. This is the standard for most web videos and Blu-ray discs.

ffmpeg -i input.mp4 -c:v libx264 -color_primaries bt709 -color_trc bt709 -colorspace bt709 output.mp4

Example 2: Setting HDR10 Metadata (BT.2020 / PQ)

For High Dynamic Range (HDR) video using the HDR10 standard, you must use the wide color gamut BT.2020 and the Perceptual Quantizer (PQ) transfer curve (smpte2084).

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

Note: bt2020nc stands for BT.2020 Non-Constant Luminance, which is the standard matrix coefficient for HDR10.

Example 3: Using the setparams Filter

If you want to set or override these parameters within the video filter graph during transcoding, you can use the setparams video filter instead of the global encoder flags.

ffmpeg -i input.mp4 -vf "setparams=color_primaries=bt709:color_trc=bt709:colmatrix=bt709" -c:v libx264 output.mp4

Common Supported Values

Below are the most commonly used values for each parameter depending on your target format:

Verifying the Output Metadata

After running your FFmpeg command, you can verify that the container and bitstream metadata have been correctly applied by using ffprobe:

ffprobe -visualize_format -show_streams output.mp4

Look for the following lines in the output to confirm your settings:

color_range=tv
color_space=bt709
color_transfer=bt709
color_primaries=bt709