Configure Master-Display Metadata in FFmpeg libx265

This article provides a straightforward guide on how to configure the master-display metadata parameters when encoding High Dynamic Range (HDR) video using the libx265 encoder in FFmpeg. You will learn the exact syntax for the master-display option and how to map color coordinates and luminance values to ensure accurate HDR10 metadata playback on compatible displays.

To write mastering display metadata (HDR10 static metadata) into a HEVC/H.265 stream using FFmpeg and libx265, you must use the -x265-params option. The mastering display metadata defines the color primaries, white point, and luminance range of the monitor used to master the video.

The Master-Display Parameter Syntax

The master-display parameter requires a specific format:

master-display=G(x,y)B(x,y)R(x,y)WP(x,y)L(max,min)

Within this syntax: * G(x,y): Green primary coordinates. * B(x,y): Blue primary coordinates. * R(x,y): Red primary coordinates. * WP(x,y): White Point coordinates. * L(max,min): Maximum and minimum luminance values.

Scaling the Values

The values used in the syntax cannot be entered as raw decimals or nits. They must be scaled according to the HEVC specification:

  1. Color Coordinates (G, B, R, WP): Multiply the chromaticity coordinates (which range from 0.0 to 1.0) by 50,000.
  2. Luminance (L): Multiply the candelas per square meter (cd/m² or nits) by 10,000.

Example: DCI-P3 (D65) 1000-Nit Mastering Display

A common mastering setup uses a DCI-P3 color space with a D65 white point, a maximum brightness of 1000 nits, and a minimum brightness of 0.005 nits.

The raw coordinates for this setup are: * Green: x = 0.265, y = 0.690 * Blue: x = 0.150, y = 0.060 * Red: x = 0.680, y = 0.320 * White Point: x = 0.3127, y = 0.3290 * Luminance: Max = 1000 nits, Min = 0.005 nits

Applying the scaling factors yields: * Green: x = 13250, y = 34500 * Blue: x = 7500, y = 3000 * Red: x = 34000, y = 16000 * White Point: x = 15635, y = 16450 * Luminance: Max = 10000000, Min = 50

The resulting parameter string is:

master-display=G(13250,34500)B(7500,3000)R(34000,16000)WP(15635,16450)L(10000000,50)

FFmpeg Command Example

To apply this metadata during an encode, pass the string to -x265-params. It is also recommended to include the max-cll parameter (Maximum Content Light Level and Maximum Frame-Average Light Level) when encoding HDR10 content.

ffmpeg -i input.mov -c:v libx265 -crf 18 -pix_fmt yuv420p10le \
-x265-params "master-display=G(13250,34500)B(7500,3000)R(34000,16000)WP(15635,16450)L(10000000,50):max-cll=1000,400:colorprim=bt2020:transfer=smpte2084:colormatrix=bt2020nc" \
output.mp4

Note that the individual parameters inside -x265-params must be separated by colons (:).