Skip to main content

​
Synopsis

dovi_convert convert [files|directories] [options]

​
Description

Converts Dolby Vision Profile 7 MKV files to Profile 8.1. The conversion strips the Enhancement Layer while injecting the RPU (dynamic metadata) into the Base Layer, creating a file compatible with devices that don’t support FEL. The convert command operates in two modes depending on the input:
  • File mode — When you pass only files, each file is converted immediately, one after another.
  • Batch mode — When you pass directories (or a mix of files and directories), the command first scans everything, shows a summary, asks for confirmation, then converts all eligible files.
The original file is automatically backed up as *.mkv.bak.dovi_convert before conversion.

​
Arguments

ArgumentRequiredDescription
`[filesdirectories]`NoOne or more MKV files or directories. If omitted, scans the current directory

​
Options

OptionShortDescription
--force-fOverride Complex FEL safety check and convert anyway
--safe-sForce Safe Mode (disk extraction). Slower but handles problematic files
--yes-ySkip confirmation prompts (for automation)
--recursive [N]-r [N]Scan directories recursively up to depth N (default: 5)
--output PATH-o PATHOutput directory for converted files
--temp PATH-t PATHWrite temporary files to a separate directory (e.g. fast SSD)
--delete—Delete backup file after successful conversion
--hdr10—Convert to HDR10 instead of Profile 8.1 (single file only)
--include-simple—Include Simple FEL files in batch conversions
--verbose-vShow detailed per-file output in batch mode (default is compact)
--debug—Generate dovi_convert_debug.log with detailed output
If Standard mode fails (common with Seamless Branching), Safe mode is triggered automatically. You don’t need to manually retry.

​
Behavioral Notes

​
Batch Mode Triggers

When directories are present in the input, batch mode activates automatically. This includes:
  • A single directory: convert /movies
  • Multiple directories: convert /movies /shows
  • Mixed files and directories: convert movie.mkv /shows
In batch mode, you see a summary of all eligible files before conversion begins.

​
Restrictions

**--hdr10 **requires a single file. HDR10 conversion is blocked when directories are present. --output with mixed inputs is blocked. When converting both files and directories, output paths could collide. Convert them separately or omit --output. **--yes **skips Simple FEL files by default. For unattended operations, Simple FEL files are skipped unless you also pass --include-simple. This prevents accidental conversions. **--recursive **without directories prints a warning. If you pass -r with only files, the flag is ignored and a warning is shown.

​
Examples

Convert a single file: 
dovi_convert convert movie.mkv
Convert multiple files: 
dovi_convert convert movie1.mkv movie2.mkv movie3.mkv
Convert a directory (batch mode): 
dovi_convert convert /movies
Shows a summary of eligible files, asks for confirmation, then converts. Convert directory recursively: 
dovi_convert convert /movies --recursive
dovi_convert convert /movies -r
Scans and converts up to 5 levels deep by default. Limit or expand recursion depth: 
dovi_convert convert /movies --recursive 2
dovi_convert convert /movies --recursive 10
Skip confirmation prompts: 
dovi_convert convert /movies --yes
dovi_convert convert /movies -y
Include Simple FEL files in automated batch:
With --yes, Simple FEL files are skipped unless you also pass --include-simple.
dovi_convert convert /movies --yes --include-simple
Convert to HDR10 (single file only): 
dovi_convert convert movie.mkv --hdr10
Strips all Dolby Vision metadata, leaving a clean HDR10 stream. Force conversion of Complex FEL file: 
dovi_convert convert movie.mkv --force
dovi_convert convert movie.mkv -f
Forcing conversion on Complex FEL files produces incorrect tone mapping. Only use this if you understand and accept the quality loss.
Use Safe Mode: 
dovi_convert convert movie.mkv --safe
dovi_convert convert movie.mkv -s
Delete backup after conversion: 
dovi_convert convert movie.mkv --delete
This removes your only copy of the original Profile 7 file. Use with caution.
Use a fast temp directory: 
dovi_convert convert movie.mkv --temp /mnt/ssd/temp
dovi_convert convert movie.mkv -t /mnt/ssd/temp
Useful when your media is on a slow HDD or NAS. Save converted files to a different directory: 
dovi_convert convert movie.mkv --output /converted
dovi_convert convert movie.mkv -o /converted
Enable debug logging: 
dovi_convert convert movie.mkv --debug

​
Conversion Process

  1. Analyzes the file to detect FEL complexity
  2. Creates backup (*.mkv.bak.dovi_convert)
  3. Strips Enhancement Layer from video
  4. Injects RPU metadata into Base Layer
  5. Remuxes everything into new MKV file
  6. Verifies frame count matches
All audio and subtitle tracks are preserved.

​
See Also

  • scan — Analyze files before conversion
  • cleanup — Remove backup files