How to Set Max-CLL and Max-FALL in FFmpeg x265

This article provides a straightforward guide on how to configure the max-cll (Maximum Content Light Level) and max-fall (Maximum Frame-Average Light Level) metadata parameters when encoding High Dynamic Range (HDR) video using the libx265 encoder in FFmpeg. You will learn the exact command-line syntax and parameter formats required to correctly embed this HDR10 metadata into your video output.

Understanding the Parameters

When encoding HDR10 video, max-cll and max-fall are crucial metadata values that tell the playback display how to map the video’s brightness to the display’s actual physical capabilities:

The FFmpeg Command Syntax

In FFmpeg, these parameters are passed directly to the libx265 encoder using the -x265-params option. In x265, both values are configured together using the max-cll argument, formatted as max-cll=CLL,FALL.

To ensure the encoder actually writes this metadata into the video bitstream, you must also enable the hdr10=1 parameter.

Here is the basic structure of the command:

ffmpeg -i input.mp4 -c:v libx265 -x265-params "hdr10=1:max-cll=1000,400" output.mp4

Full Practical Example

In a real-world HDR10 encoding scenario, you must also define the color space, transfer characteristics, and color matrix (typically BT.2020 and SMPTE ST 2084 for HDR10).

Here is a complete command that sets Max-CLL to 1000 nits, Max-FALL to 400 nits, and configures the correct color metadata:

ffmpeg -i input.mp4 -c:v libx265 -pix_fmt yuv420p10le \
-color_primaries bt2020 \
-color_trc smpte2084 \
-colorspace bt2020 \
-x265-params "hdr10=1:max-cll=1000,400" \
-c:a copy output.mp4

Verification

After encoding, you can verify that the metadata was successfully embedded by using ffprobe:

ffprobe -select_streams v:0 -show_frames -read_intervals %+1 output.mp4 | grep -E "side_data|max_content|max_average"

This will display the active side data, confirming that the display device will read the max-cll and max-fall values during playback.