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:

  • Max-CLL (Maximum Content Light Level): The highest luminance value (in nits) of any single pixel in the entire video.
  • Max-FALL (Maximum Frame-Average Light Level): The highest average luminance value (in nits) of any single frame in the video.

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.