dovi_tool: inspecting and generating Dolby Vision metadata

Two families of command, and one object they all touch

dovi_tool is a CLI tool combining multiple utilities for working with Dolby Vision, and the whole thing is organised around a single file format.

That object is the RPU, the reference processing unit, the metadata blob that carries the dynamic tone mapping information alongside an HEVC stream. Everything in the metadata half of the tool reads or writes one.

The command line is a global options block followed by a subcommand.

dovi_tool [OPTIONS] <SUBCOMMAND>

The global options are --help, --version, --crop, --drop-hdr10plus, --mode, --edit-config and --start-code, and each subcommand has its own detailed help.

The subcommands fall into two families, and the split in the README is the fastest way to understand the tool. The metadata utilities are info, generate, editor, export and plot, which analyse, edit and generate Dolby Vision metadata. The HEVC parsing and handling commands are convert, demux, mux, extract-rpu and inject-rpu, which deal with the video stream itself and move RPU data in and out of it.

So the tool covers the whole path of a Dolby Vision file. You can pull the RPU out of a stream, look at it, change it, and put it back, and the metadata half of the command set is what you use between those steps.

info, editor, export and plot, and the frame index convention

The inspection commands are small and each does one thing.

info prints the parsed RPU information, with --summary or -s for the summary form, and --frame prints the RPU data as JSON for one specific frame. Frame indices start at 0, so the example in the README, dovi_tool info -i RPU.bin -f 123, is the frame whose index is 123.

editor edits a binary RPU according to a JSON config, and the index convention matters here: all indices start at 0 and are inclusive, so a range of 0-39 edits the first 40 frames.

export writes the RPU out to text files. By default it outputs the full RPU serialised to JSON, which is the same as --data all. The -d flag takes a comma separated list of key equals output pairs, with all exporting the list of RPUs as a JSON file, scenes exporting the frame indices at which scene_refresh_flag is set to 1, and level5 exporting the video's L5 metadata in the form of an editor config JSON. There is also -l to export specific extension metadata levels, where a path can be given per level, and -f to choose between csv and json for those exports.

plot renders the metadata as a graph and writes a PNG. You can set a title, a start and end frame range, the metadata level to plot with l1 as the default and l2, l8, l8-saturation and l8-hue as the alternatives, the target brightness in nits for the L2 and L8 plots with 100 as the default, and which trim parameters to include.

generate is where the four sources matter

The generate command builds a binary RPU from different sources, and the four of them are the reason this tool exists.

The first is an exported CMv2.9 or CMv4.0 Dolby Vision XML metadata file. The binary RPU can be created with support for the following metadata levels, and the two configuration management versions are nested rather than alternative. CMv2.9 covers L1, L2, L5 and L6, and CMv4.0 is CMv2.9 plus L3, L8, L9, L10 and L11. Both per-shot and per-frame trims are supported, and level 5 metadata requires both canvas-width and canvas-height to be set.

The second source is a generic profile 5, 8.1 or 8.4 configuration JSON file, documented in docs/generator.md with examples under assets/generator_examples.

The third is an existing HDR10+ metadata JSON file, and here the L1 metadata is derived from the HDR10+ metadata, which means the HDR10+ file must contain scene information for proper scene cuts. The --hdr10plus-peak-source flag decides how the peak brightness is extracted, with histogram as the default and histogram99, max-scl and max-scl-luminance as the alternatives.

The fourth is a madVR HDR measurement file, where the L1 metadata is derived from the madVR measurements, with support for custom targets in nits from Soulnight's madMeasureHDR Optimizer through the --use-custom-targets flag.

That last pair of sources is the practically interesting part. Deriving Dolby Vision metadata from HDR10+ or from a madVR measurement is a real workflow for people who do not have Dolby Vision authoring tools, and the tool does the derivation for them.

HEVC handling, and the library that sits underneath

The HEVC side of the tool is where the RPU meets the video, with convert, demux, mux, extract-rpu and inject-rpu doing the work of moving metadata in and out of a bitstream.

Underneath all of it is a library, and it is hosted in the same repository. The dolby_vision crate is also hosted here, with its own README, for use as a Rust or C library, and the C compatible library is known as libdovi, with the same document covering building and installing it.

The dependency list shows what the implementation leans on. The dolby_vision crate is a path dependency with the xml and serde features enabled, so the XML parsing and the serialisation live in the library rather than in the tool. hevc_parser at 0.6.12 with the hevc_io feature handles the bitstream side, bitvec_helpers with bitstream-io does the bit level work, and madvr_parse and hdr10plus at 2.1.5 are the two third party format libraries the generator reads.

The rest is ordinary Rust application plumbing: clap for the command line with derive and wrap_help, serde and serde_json with preserve_order so that the JSON output keeps its key order, thiserror for error types, anyhow at the application layer, indicatif for progress bars, itertools, csv for the CSV exports, and plotters for the PNG output.

The crate is on edition 2024, is MIT licensed, and the dev dependencies are assert_cmd, assert_fs and predicates, which is the standard stack for testing a CLI end to end, running the binary and asserting on its output and on the files it writes.

The font feature is the one build decision most people will hit

There is one build dependency in the README that is easy to miss and that bites on Linux.

On Linux systems, fontconfig is required. The alternative is to bypass system fonts by building with --no-default-features --features internal-font.

The reason is in the Cargo manifest. The default feature set is system-font, which enables plotters with the ttf feature, and the alternative is internal-font, which enables plotters with ab_glyph. The plot command renders text into the PNG, and a PNG renderer needs a font, and a font either comes from the operating system or from a font compiled into the binary.

The internal-font route is the portable one, since it removes a system dependency at the cost of a slightly larger binary, and it is the reason the feature exists as a switch rather than as a build flag.

The release profile is also interesting. There is a profile called release-deploy that inherits release, sets thin link time optimisation and strips symbols, which is a slightly unusual name for it but a sensible choice for a binary that gets distributed to users who do not need the symbol table.

Two different Rust versions, and the maintenance state

There is an inconsistency in the repository worth pointing out, because it is the kind of thing that wastes an afternoon.

The README says the minimum Rust version to build dovi_tool is 1.88.0. The Cargo manifest says rust-version is 1.95.0. The manifest is what the build will actually enforce, so if you are on 1.88 the build will refuse, and the README's number is out of date.

Otherwise the build is one command, and the result is a single binary.

cargo build --release

The release binary lands in target/release/dovi_tool, and the build is driven by a build.rs, with vergen-gitcl in the build dependencies, which is the usual way to bake the commit hash and build time into a binary so that --version can report them.

The maintenance picture is steady. The project is not archived, the last push was on 2026-09-13, and the releases are 2.3.4 from 2026-09-10, 2.3.3 from 2026-07-12 and 2.3.2 from 2026-04-05, which is a cadence of roughly every two months with the most recent release three days before the last commit. There is also a CI badge and an artefacts workflow in the README, so the binaries are built automatically rather than by hand.

Editorial conclusion

dovi_tool fits an engineer who needs to look at or change the Dolby Vision metadata in a file, particularly one generating dynamic metadata from HDR10+ or madVR measurements rather than from a Dolby XML profile, and who is comfortable with a command line and an HEVC bitstream. It does not fit a video editor that wants a graphical timeline, and it does not fit a team that cannot build a Rust project or that needs the metadata handled inside a player. Verify three things before you rely on it: which metadata level your content actually needs, because the generator supports CMv2.9 and CMv4.0 and they are not the same set of levels, whether your platform needs the internal-font feature, since the default build wants fontconfig and Linux is the case the README calls out, and that you build against the Rust version the manifest requires rather than the lower one the README mentions, because the two numbers in the repository disagree.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. quietvoid/dovi_tool on GitHub
4. README
5. Releases