hdr10plus_tool

quietvoid/hdr10plus_tool

CLI utility to work with HDR10+ in HEVC files.

Latest release

1.7.2Dec 27, 2025

Last commit

Apr 27, 2026

License

MIT

Stars

462

hdr10plus_tool is a command-line tool by quietvoid for HDR10+ metadata in HEVC. It extracts the per-frame SMPTE ST 2094-40 metadata to a JSON file, injects it into another HEVC stream, removes it, edits frame ranges and plots it. It was previously called hdr10plus_parser. It works on raw HEVC streams and on Matroska files with an HEVC track; it doesn’t handle AV1. See HDR formats for what HDR10+ is.

Install

Download a binary from the GitHub releases (x86-64 and ARM64 Linux, x64 and ARM64 Windows, universal macOS), or build with Rust 1.85 or newer. On Linux the build needs fontconfig, or use --no-default-features --features internal-font:

git clone https://github.com/quietvoid/hdr10plus_tool.git
cd hdr10plus_tool
cargo build --release

Keep HDR10+ through a re-encode

1. Extract the metadata. Matroska is read directly:

   hdr10plus_tool extract input.mkv -o metadata.json

   For MP4 or other containers, pipe the stream through FFmpeg:

   ffmpeg -i input.mp4 -c:v copy -f hevc - | hdr10plus_tool extract -o metadata.json -

2. Encode with x265 and give it the JSON. x265 writes the HDR10+ SEI for each frame, but only if it was built with ENABLE_HDR10_PLUS, which is off by default in x265’s CMake files:

   x265 --input video.y4m --output-depth 10 --crf 18 --preset slow --colorprim bt2020 --transfer smpte2084 --colormatrix bt2020nc \
     --master-display "G(13250,34500)B(7500,3000)R(34000,16000)WP(15635,16450)L(10000000,1)" --max-cll "1000,400" \
     --dhdr10-info metadata.json -o output.hevc

   From FFmpeg the same option goes through -x265-params dhdr10-info=metadata.json. Without it, FFmpeg’s libx265 encoder drops HDR10+.

3. Or inject into any finished HEVC stream:

   hdr10plus_tool inject -i output.hevc -j metadata.json -o injected.hevc

4. Confirm it worked with hdr10plus_tool --verify extract injected.hevc, which prints Dynamic HDR10+ metadata detected. and exits.

The JSON has one entry per frame. If the new encode has a different number of frames or a different start point, adjust the metadata with the editor first.

Commands

Command	What it does
extract INPUT -o metadata.json	Extract metadata to JSON, with scene information compatible with Samsung’s tools. Without -o it only checks for metadata.
inject -i in.hevc -j metadata.json -o out.hevc	Insert HDR10+ SEI messages before each frame’s slices
remove INPUT -o out.hevc	Remove HDR10+ SEI messages, leaving plain HDR10
editor metadata.json -j edits.json -o new.json	Remove or duplicate frames in the metadata
plot metadata.json -o plot.png	Plot brightness per frame; -p picks the peak source (histogram, histogram99, max-scl, max-scl-luminance), -s/-e a frame range

Global options: --verify only checks whether the input contains HDR10+; --skip-validation skips the profile-conformity check, for metadata that fails it but that you still want to extract.

The editor JSON uses inclusive frame ranges; removals run before duplications:

{
  "remove": ["0-39"],
  "duplicate": [{ "source": 100, "offset": 100, "length": 24 }]
}

Wrong metadata order on some discs

A few retail discs were authored with the metadata inserted in decode order instead of presentation order, so with B-frames the metadata ends up on the wrong frames. The tell-tale sign is in the extracted JSON: many scenes in SceneFrameNumbers only one to three frames long, and SceneFirstFrameIndex values that don’t line up with the cuts in the video. For those files extract with --skip-reorder. Don’t use it on correctly authored streams.

Related tools

dovi_tool can generate a Dolby Vision RPU from an HDR10+ JSON (dovi_tool generate --hdr10plus-json) and can strip HDR10+ from a stream while writing with --drop-hdr10plus.