Extract HDR10 Metadata to Text File with FFmpeg

This guide provides a straightforward method for extracting HDR10 metadata—specifically mastering display color volume and content light level data—from an HEVC (H.265) video file and saving it directly to a text file using the FFmpeg suite.

To extract HDR10 metadata, you will use ffprobe, a command-line tool for analyzing multimedia streams that comes bundled with FFmpeg. Static HDR10 metadata is typically stored in the side data of the video’s first frame.

Run the following command in your terminal or command prompt:

ffprobe -v error -select_streams v:0 -show_frames -read_intervals "%+#1" -show_entries frame=side_data_list -of default=noprint_wrappers=1 input.mp4 > hdr_metadata.txt

Command Breakdown

• ffprobe: Invokes the FFmpeg probe tool.
• -v error: Suppresses unnecessary log output, showing only errors if they occur.
• -select_streams v:0: Selects the first video stream (ignoring audio and subtitles).
• -show_frames: Instructs the tool to analyze and display frame information.
• -read_intervals "%+#1": Limits the analysis to only the first frame. This speeds up the process significantly because static HDR10 metadata is declared at the beginning of the stream.
• -show_entries frame=side_data_list: Filters the output to display only the side data list, which contains the HDR10 metadata.
• -of default=noprint_wrappers=1: Formats the output as a clean list of key-value pairs without standard wrapper tags.
• input.mp4: Replace this with the path to your source HEVC video file.
• > hdr_metadata.txt: Redirects the output from the terminal screen into a text file named hdr_metadata.txt.

Understanding the Output

Once the command finishes, open the newly created hdr_metadata.txt file. You will see two primary blocks of HDR10 data:

1. Mastering Display Metadata: This defines the color primaries (red, green, and blue coordinates), white point, and the minimum/maximum luminance of the monitor used to master the video.
2. Content Light Level Metadata: This contains the MaxCLL (Maximum Content Light Level) and MaxFALL (Maximum Frame-Average Light Level) values, measured in nits.