convert command converts Dolby Vision Profile 7 files to Profile 8.1. The process strips the Enhancement Layer, injects the dynamic metadata (RPU) into the Base Layer, and produces a file compatible with most Dolby Vision devices.
You can convert individual files or entire directories. When you pass directories, the command enters batch mode — scanning everything first, showing a summary, then converting all eligible files.
How Conversion Works
The conversion process:- Extracts the video stream from your MKV file
- Strips the Enhancement Layer (EL)
- Injects the RPU metadata into the Base Layer
- Remuxes everything back into a new MKV file
No video re-encoding happens. The bitstream is processed directly, so conversion is fast and quality is preserved exactly.
Safety Features
dovi_convert is designed to be non-destructive:- Automatic backup — Your original file is renamed to
*.bak.dovi_convertbefore any changes - Scan before convert — Each file is analyzed to detect Complex FEL
- Safe defaults — Complex FEL files are skipped unless you explicitly override
Converting Files
Single Files
Convert a file:- Analyzes the file for FEL complexity
- Creates a backup (
movie.mkv.bak.dovi_convert) - Converts to Profile 8.1
- Replaces the original with the converted file
Directories
When you pass directories instead of files, dovi_convert switches to batch mode:- All directories are scanned for Profile 7 files
- A summary shows what will be converted
- You confirm before conversion begins
- Each eligible file is converted
--verbose (or -v) to see detailed per-file output instead.
Recursive Conversion
By default, only the top level of each directory is scanned and converted. Use--recursive (or -r) to scan and convert subdirectories:
Skipping Confirmation
For automated workflows, use--yes (or -y) to skip the confirmation prompts:
With
--yes, Simple FEL files are automatically skipped. This prevents unattended conversions from processing files that might need manual review. To include them, add --include-simple.Processing Modes
dovi_convert has two processing modes:Standard Mode (Default)
Pipes video data directly from ffmpeg to dovi_tool. Fast and efficient — requires no temporary disk space for the video stream.Safe Mode
Extracts the video stream to disk first, then processes it. Slower, but handles files that Standard mode can’t process.If Standard mode fails (common with Seamless Branching or irregular file structures), Safe mode is triggered automatically. You don’t need to manually retry.
What Gets Converted
Complex FEL
Complex FEL files are skipped by default because converting them produces incorrect tone mapping. To override this safety check, use--force (see Conversion Options).
Forcing conversion on Complex FEL files produces incorrect tone mapping. The picture may appear dark, have flickering, or show other artifacts. Only use this if you understand and accept the quality loss.
Simple FEL
When converting a Simple FEL file, dovi_convert prompts for confirmation:inspect first.
Conversion Options
Force Mode (--force)
Override the Complex FEL safety check:
HDR10 Mode (--hdr10)
Convert to HDR10 instead of Dolby Vision Profile 8.1:
When to use this: Some devices like the Nvidia Shield convert Profile 7 files to Profile 8.1 automatically during playback — even when they shouldn’t. For Complex FEL files, this produces incorrect tone mapping. Converting to HDR10 upfront prevents the device from attempting its own conversion. You lose the dynamic metadata, but the picture displays correctly. HDR10 is better than broken Dolby Vision.
Output Directory (--output)
Place converted files in a different directory:
.bak.dovi_convert and stays in the source location. The output directory is created automatically if it doesn’t exist.
Temp Directory (--temp)
If your source files are on a mechanical hard drive or network storage, conversion can be slow. Use --temp to write temporary files to a separate, faster drive:
Use an SSD or NVMe drive as your temp directory for best results.
Delete Backup (--delete)
Automatically delete the backup file after successful conversion:
This removes your only copy of the original Profile 7 file. Use with caution. If something goes wrong or you later want to restore the original, you can’t.
What Happens to Your Files
| Before | After |
|---|---|
movie.mkv (Profile 7) | movie.mkv (Profile 8.1) |
| — | movie.mkv.bak.dovi_convert (original backup) |
Troubleshooting
If conversion fails:-
Run with
--debugto generate a log: -
Check
dovi_convert_debug.logfor errors from ffmpeg, dovi_tool, or mkvmerge -
Common issues:
- Seamless Branching — Try with
--safemode - Corrupted files — Verify the original file plays correctly
- Disk space — Safe mode needs space for the extracted video stream
- Seamless Branching — Try with