How to Inject HDR10+ Metadata into HEVC with FFmpeg

This article provides a straightforward guide on how to insert HDR10+ dynamic metadata into an HEVC (H.265) video stream using FFmpeg. You will learn how to prepare your HDR10+ JSON metadata file and construct the precise FFmpeg command required to encode your video with active dynamic metadata, ensuring compatible displays can render scene-by-scene luminance adjustments.

Prerequisites

To inject HDR10+ metadata, you need:

  1. FFmpeg compiled with libx265 support.
  2. An HDR10+ Metadata JSON file: This file contains the frame-by-frame HDR10+ dynamic metadata. You can extract this from an existing HDR10+ video using tools like hdr10plus_parser.
  3. The Source Video: Your raw or high-quality video source (usually 10-bit YUV 4:2:0).

Step 1: Prepare the HDR10+ JSON File

Ensure your dynamic metadata is formatted as a JSON file. If you are extracting it from an existing HDR10+ HEVC file, you can run:

hdr10plus_parser -o metadata.json input_video.hevc

Step 2: The FFmpeg Command

To encode a video and inject the HDR10+ metadata, you must pass the JSON file to the libx265 encoder using the -x265-params argument.

Run the following command:

ffmpeg -i input.mp4 -c:v libx265 -pix_fmt yuv420p10le -x265-params dhdr10-info=metadata.json:colorprim=bt2020:transfer=smpte2084:colormatrix=bt2020nc:hdr10-opt=1 -c:a copy output.mp4

Parameter Breakdown

  • -c:v libx265: Uses the x265 encoder, which is required for HEVC HDR10+ encoding.
  • -pix_fmt yuv420p10le: Sets the pixel format to 10-bit YUV 4:2:0, which is mandatory for HDR10 and HDR10+.
  • dhdr10-info=metadata.json: This is the crucial parameter that tells the x265 encoder to read the frame-by-frame dynamic metadata from your JSON file and inject it into the HEVC bitstream as SEI messages.
  • colorprim=bt2020:transfer=smpte2084:colormatrix=bt2020nc: Defines the color space (BT.2020) and the transfer characteristics (PQ / SMPTE ST 2084) required for HDR.
  • hdr10-opt=1: Enables x265 to optimize the block-level chroma and luma QP based on HDR10 intensity.

Verifying the Output

After the encoding process is complete, you can verify if the HDR10+ metadata was successfully injected using MediaInfo or ffprobe.

Look for the following line in the video track metadata:

HDR format: HDR10+ Compatible