Skip to content

dovi_tool is a CLI tool combining multiple utilities for working with Dolby Vision.

License

Notifications You must be signed in to change notification settings

quietvoid/dovi_tool

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

dovi_tool CI Artifacts

dovi_tool is a CLI tool combining multiple utilities for working with Dolby Vision.

The dolby_vision crate is also hosted in this repo, see README for use as a Rust/C lib.
The C compatible library is also known as libdovi, refer to the same document for building/installing.

 

Building

Toolchain

The minimum Rust version to build dovi_tool is 1.79.0.

Dependencies

On Linux systems, fontconfig is required.
Alternatively, system fonts can be bypassed by building with --no-default-features --features internal-font.

Release binary

To build release binary in target/release/dovi_tool run:

cargo build --release

 

Usage

dovi_tool [OPTIONS] <SUBCOMMAND>

To get more detailed options for a subcommand

dovi_tool <SUBCOMMAND> --help

All options

  • --help, --version, --crop, --drop-hdr10plus, --mode, --edit-config, --start-code

All subcommands

  • Metadata utilities: info, generate, editor, export, plot
  • HEVC parsing & handling: convert, demux, mux, extract-rpu, inject-rpu

More information and detailed examples for the subcommands below.

 

Dolby Vision metadata utilities

dovi_tool provides an important set of tools for analyzing, editing and generating Dolby Vision metadata.

Commands

  • info

    Prints the parsed RPU information. To get the summary, use --summary or -s.

    Using --frame: prints the RPU data as JSON for a specific frame.

    • Frame indices start at 0.

    Example to get metadata for frame 124:

    dovi_tool info -i RPU.bin -f 123

 

  • generate

    Allows generating a binary RPU from different sources.
     

    From 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:

      • CMv2.9: L1, L2, L5, L6
      • CMv4.0: CMv2.9 + L3, L8, L9, L10, L11

       

      Both per-shot and per-frame trims are supported.
      Level 5 metadata requires both canvas-width and canvas-height to be set.

      Example:

      dovi_tool generate --xml dolbyvision_metadata.xml -o RPU_from_xml.bin

     

    From a generic profile 5/8.1/8.4 configuration JSON file

    • See documentation: generator.md or examples

      Example:

      dovi_tool generate -j assets/generator_examples/default_cmv40.json -o RPU_generated.bin

     

    From an existing HDR10+ metadata JSON file

    • The metadata is generated from a configuration JSON file, and the L1 metadata is derived from HDR10+ metadata.
      The HDR10+ metadata must contain scene information for proper scene cuts.

      Flags:

      • --hdr10plus-peak-source How to extract the peak brightness for the metadata [default: histogram]
        Possible values: histogram, histogram99, max-scl, max-scl-luminance

      Example:

      dovi_tool generate -j assets/generator_examples/default_cmv40.json --hdr10plus-json hdr10plus_metadata.json -o RPU_from_hdr10plus.bin

     

    From a madVR HDR measurement file

    • The metadata is generated from a configuration JSON file, and the L1 metadata is derived from the madVR measurements.
      Supports using custom targets nits from Soulnight's madMeasureHDR Optimizer, with flag --use-custom-targets.

      Example:

      dovi_tool generate -j assets/generator_examples/default_cmv40.json --madvr-file madmeasure-output.bin -o RPU_from_madVR.bin

 

  • editor

    Allows editing a binary RPU according to a JSON config. See documentation: editor.md or examples.
    All indices start at 0, and are inclusive. For example, using "0-39" edits the first 40 frames.

    Example:

    dovi_tool editor -i RPU.bin -j assets/editor_examples/mode.json -o RPU_mode2.bin

 

  • export

    Allows exporting a binary RPU file to text files containing relevant information.
    The command allows specifying the desired data to export as file.
    Default: export outputs the full RPU serialized to JSON (equivalent to --data all).

    • -d, --data: List of key-value export parameters formatted as key=output,key2...
      • all - Exports the list of RPUs as a JSON file
      • scenes - Exports the frame indices at which scene_refresh_flag is set to 1
      • level5 - Exports the video's L5 metadata in the form of an editor config JSON

     

    Example to export the whole RPU list to JSON:

    dovi_tool export -i RPU.bin -d all=RPU_export.json

    Example to export both scene change frames and L5 metadata (with specific path)

    dovi_tool export -i RPU.bin -d scenes,level5=L5.json

 

  • plot

    Allows plotting the RPU L1 metadata into a graph.
    The output is a PNG image.

    Flags:

    • -t, --title The title to set at the top of the plot

    Example:

    dovi_tool plot RPU.bin -t "Dolby Vision L1 plot" -o L1_plot.png

 

HEVC parsing & handling

For working with an HEVC source file, there are multiple options that apply to most commands:

Conversion modes

  • -m, --mode Sets the mode for RPU processing.
    • Default (no mode) - Copies the RPU untouched.
    • 0 - Parses the RPU, rewrites it untouched.
    • 1 - Converts the RPU to be MEL compatible.
    • 2 - Converts the RPU to be profile 8.1 compatible.
      • Removes luma/chroma mapping for profile 7 FEL.
    • 3 - Converts profile 5 to 8.1.
    • 4 - Converts to profile 8.4.
    • 5 - Converts to profile 8.1, preserving mapping.
      • Old mode 2.

Other options

  • -c, --crop Set active area offsets to 0 (meaning no letterbox bars).
  • --drop-hdr10plus Ignore HDR10+ metadata when writing the output HEVC.
  • --edit-config Path to editor config JSON file.
    • Limited editing capabilities when working with HEVC. See documentation.
  • --start-code HEVC NALU start code to use when writing HEVC.
    • Options: four (default), annex-b
    • four is the default, writing a 4-byte start code all the time.
    • annex-b varies the start code, according to spec. Almost matches x265 behaviour.

Commands

  • convert

    Converts RPU within a single layer HEVC file.
    The enhancement layer can be discarded using --discard.

    Examples to convert to profile 8.1 and discard EL:

    dovi_tool -m 2 convert --discard file.hevc
    ffmpeg -i input.mkv -c:v copy -bsf:v hevc_mp4toannexb -f hevc - | dovi_tool -m 2 convert --discard -

 

  • demux

    Rust port of yusesope's python tool. Credits goes to them.
    Demuxes single track dual layer Dolby Vision into Base layer and Enhancement layer files.
    The base layer file output is equivalent to using the remove subcommand.

    Flags:

    • --el-only Output the EL file only.

    Examples:

    dovi_tool demux file.hevc
    ffmpeg -i input.mkv -c:v copy -bsf:v hevc_mp4toannexb -f hevc - | dovi_tool demux -

    Example to convert RPU to profile 8.1 while demuxing:

    dovi_tool -m 2 demux file.hevc

 

  • mux

    Interleaves the enhancement layer into a base layer HEVC bitstream.
    This is the inverse of demux.

    Muxing supports the base layer input as both raw HEVC bitstream and piped/streamed.

    Flags:

    • --eos-before-el Write the EOS/EOB NALUs before the EL. Defaults to false.
      This flag enables the same behaviour yusesope's mux script.
      Enabling this therefore results in identical output using dovi_tool.

      In recent versions of MakeMKV, EOS/EOB NALUs are removed.

    • --no-add-aud Disable adding AUD NALUs between frames

    • --discard Discard the EL while muxing. This is equivalent to injecting the RPU, but without extracting first.

    Examples:

    dovi_tool mux --bl BL.hevc --el EL.hevc
    ffmpeg -i input.mkv -c:v copy -bsf:v hevc_mp4toannexb -f hevc - | dovi_tool mux --bl - --el EL.hevc

    Example to convert RPU to profile 8.1 while muxing:

    dovi_tool -m 2 mux --bl BL.hevc --el EL.hevc --discard

 

  • extract-rpu

    Extracts Dolby Vision RPU from an HEVC file.
    This can be either a single track (BL + RPU), single track dual layer (BL+EL+RPU) or an enhancement layer (EL+RPU) video file.

    Supports profiles 4, 5, 7, and 8.

    Flags:

    • -l, --limit Number of frames to process from the input. Processing stops after N frames.

    Examples:

    dovi_tool extract-rpu video.hevc
    ffmpeg -i input.mkv -c:v copy -bsf:v hevc_mp4toannexb -f hevc - | dovi_tool extract-rpu - -o RPU.bin

    FEL to MEL example:

    dovi_tool -m 1 extract-rpu video.hevc

 

  • inject-rpu

    Interleaves RPU NAL units between slices in an HEVC encoded bitstream.
    Global options have no effect when injecting.

    Flags:

    • --no-add-aud Disable adding AUD NALUs between frames

    Example:

    dovi_tool inject-rpu -i video.hevc --rpu-in RPU.bin -o injected_output.hevc

 

  • remove

    Removes the enhancement layer and RPU data from the video.
    Outputs to a BL.hevc file by default.

    Examples:

    dovi_tool remove file.hevc
    ffmpeg -i input.mkv -c:v copy -bsf:v hevc_mp4toannexb -f hevc - | dovi_tool remove -

 

Build artifacts can be found in the Github Actions.
More features may or may not be added in the future.