# Before You Start
Source: https://docs.doviconvert.com/before-you-start
Understand the technical background, caveats, and why dovi_convert exists
Before converting your files, take a few minutes to understand what dovi\_convert does, why it exists, and when conversion is — or isn't — appropriate.
## The Problem
Dolby Vision Profile 7 was designed for UHD Blu-ray, exclusively. Blu-ray discs contain two video layers:
* **Base Layer (BL)** — HDR10-compatible video
* **Enhancement Layer (EL)** — Additional data that improves picture quality
Blu-ray players have dual decoders to handle both layers. Most media players and streaming devices only have one — they can't decode the Enhancement Layer. When they encounter Profile 7 content, they either:
1. **Fall back to HDR10** — You lose all Dolby Vision benefits
2. **Fail to play** — The file won't work at all
3. **Convert blindly** — Strip the Enhancement Layer without checking if it's safe
The third option is what devices like Nvidia Shield and software like Kodi (with Dolby Vision Compatibility Mode) do. They convert on-the-fly, but they don't check whether the Enhancement Layer contains critical brightness data. If it does, the conversion produces a broken picture.
## What dovi\_convert Does Differently
**The key difference:** dovi\_convert analyzes your files *before* conversion.
It examines the Enhancement Layer to determine whether stripping it is safe. If the layer contains brightness expansion data — meaning it actively increases brightness beyond the base video — the tool warns you and skips the file by default.
The conversion process:
1. Strips the Enhancement Layer from the video
2. Injects the RPU (dynamic metadata) into the Base Layer
3. Creates a Profile 8.1 file that works on nearly any Dolby Vision device
All audio and subtitle tracks are preserved. Your original file is backed up automatically.
## What You Lose (and Why It Usually Doesn't Matter) — and What You Gain
The Enhancement Layer can contain more than brightness data. Some titles include reconstructive information like film grain, noise patterns, or color corrections. When you convert to Profile 8.1, this data is discarded.
However, this is only a concern if your playback device supports FEL — and if it did, you wouldn't need this tool. Devices that lack FEL support do either of these two things:
1. **Fall back to plain HDR10** — Lose all Dolby Vision benefits, including dynamic metadata (almost all devices)
2. **Convert to Profile 8.1 on the fly** — Keep the dynamic metadata, lose only the Enhancement Layer (this is what the Nvidia Shield does). However, devices that do this convert any profile 7 content to 8.1, which can be unsafe (explained above).
The dynamic metadata (RPU) is the core of what makes Dolby Vision valuable. It contains scene-by-scene tone mapping instructions that tell your TV how to display each frame. Profile 8.1 preserves this entirely. HDR10 fallback gives you none of it.
Converting to Profile 8.1 is almost always better than falling back to HDR10. You retain the dynamic tone mapping that makes Dolby Vision look good — you just lose enhancements your device couldn't use anyway.
## Understanding the Enhancement Layer
The Enhancement Layer in Profile 7 files comes in different forms. dovi\_convert classifies them into three categories:
| Type | What it means | Safe to convert? |
| --------------- | ---------------------------------------------- | ---------------- |
| **MEL** | Minimal Enhancement Layer with no actual data | Yes |
| **Simple FEL** | Full Enhancement Layer, but no brightness data | Usually yes |
| **Complex FEL** | Enhancement Layer with brightness expansion | No |
### MEL (Minimal Enhancement Layer)
Very common. The Enhancement Layer exists in the file structure but contains no useful data. Converting is completely safe — you lose nothing.
### Simple FEL (No Brightness Expansion)
The Enhancement Layer contains some data (like film grain or minor color adjustments), but does not expand brightness. Converting is generally safe. You lose the minor enhancements, but retain the Dolby Vision dynamic metadata.
If you're uncertain about a Simple FEL verdict, use the `inspect` command for a definitive frame-by-frame analysis.
### Complex FEL (Brightness Expansion)
The Enhancement Layer actively elevates brightness beyond what the Base Layer contains. Some films are mastered at 4000 nits but have an HDR10 Base Layer trimmed to 1000 nits — the Enhancement Layer provides the missing brightness.
Converting Complex FEL files produces incorrect results. The retained metadata was designed for the combined layers. Without the Enhancement Layer, tone mapping is incorrect — causing a darker picture, flickering, and other issues.
**What to do with Complex FEL files:**
* Watch the HDR10 fallback
* Most devices automatically fall back to playing the HDR10 Base Layer
* Some devices, like the Shield, will not fallback, but try to convert to 8.1, no matter what. You can use `dovi_convert` to convert to HDR10 in those situations. Watching the HDR10 Base Layer is always better than watching a force-converted 8.1 file that should not be converted (incorrect tonemapping).
* Use a device that supports Profile 7 FEL playback (e.g., Ugoos AM6B+)
* Do not convert unless you understand and accept the quality loss
R3S3t999, author of [DoVi\_Scripts](https://github.com/R3S3t9999/DoVi_Scripts), maintains a spreadsheet of known Complex FEL titles. Check the [FEL List](https://docs.google.com/spreadsheets/d/15i0a84uiBtWiHZ5CXZZ7wygLFXwYOd84/edit?gid=828864432#gid=828864432) if you want another source of information.
## Device-Specific Notes
### Nvidia Shield
The Shield handles Profile 7 files by stripping the Enhancement Layer and injecting the RPU in real-time — the same process dovi\_convert does offline.
However, the Shield has limitations:
* **High bitrate struggles** — Real-time conversion during playback can cause stuttering on high-bitrate files
* **No safety checks!** — The Shield converts everything, including Complex FEL files
dovi\_convert gives you control. You analyze files in advance, identify problematic titles, and only convert what's safe.
### Apple TV with Plex
If you use Plex on Apple TV 4K, you may encounter "Fake Dolby Vision" regardless of which Dolby Vision profile your file uses.
* **The issue:** Plex displays the Dolby Vision logo on your TV, but fails to apply the dynamic metadata. The result is HDR10 in a Dolby Vision container.
* **Why it happens:** Plex uses Apple's AVPlayer, which has inconsistent Dolby Vision support despite Apple adding Profile 8.1 support in tvOS 17.
* **The solution:** Use [Infuse](https://firecore.com/infuse) instead of Plex. Infuse uses a custom player that correctly applies Dolby Vision metadata. It integrates with Plex servers (the free version doesn't support Dolby Vision).
This is a Plex player issue, not a file format problem. Apple TV hardware supports Profile 8.1 correctly — Plex's implementation doesn't.
## What Conversion Cannot Fix
Converting to Profile 8.1 does not solve format incompatibility issues unrelated to the Enhancement Layer:
* **TrueHD Atmos audio** — Apple TV can't decode TrueHD. You need EAC3 Atmos or AAC fallback tracks.
* **Multi-angle or Picture-in-Picture** — Secondary video streams are dropped during conversion.
* **Subtitle compatibility** — Some devices have issues with PGS subtitles; conversion doesn't change this.
## Next Steps
Install dovi\_convert on your system
Learn how to analyze your files
# backup
Source: https://docs.doviconvert.com/command-reference/backup
Create a restorable Enhancement Layer archive from a Profile 7 file
## Synopsis
```shellscript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert backup [options]
```
## Description
Creates a `.dovi` archive containing the Enhancement Layer from a Profile 7 MKV file. This archive can later be used with the `restore` command to rebuild the original Profile 7 file.
The archive is a compact representation of the recoverable data - typically 10-25% of the original file size for Full Enhancement Layer content, or about 1-2 GB for Minimal Enhancement Layer content.
## Arguments
| Argument | Required | Description |
| -------- | -------- | --------------------------- |
| `` | Yes | A single Profile 7 MKV file |
## Options
| Option | Short | Description |
| --------------- | --------- | ------------------------------------------------------ |
| `--output PATH` | `-o PATH` | Output directory for the archive |
| `--temp PATH` | `-t PATH` | Write temporary files to a separate directory |
| `--debug` | — | Generate `dovi_convert_debug.log` with detailed output |
## Examples
**Create an archive in the same directory:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert backup movie.mkv
```
Creates `movie.dovi` alongside the source file.
**Save the archive to a backup drive:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert backup movie.mkv --output /Volumes/Backups/
dovi_convert backup movie.mkv -o /Volumes/Backups/
```
**Use a fast temp directory:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert backup movie.mkv --temp /mnt/ssd/temp
```
## Output
```
Analyzing: movie.mkv
Creating backup...
Extracting Enhancement Layer... Done.
Backup created successfully.
Archive: movie.dovi
Size: 1.24 GB (2.4% of original)
```
## Restrictions
* **Single file only.** The `backup` command does not accept directories. For batch operations, use `convert --backup` instead.
* **Profile 7 only.** The source file must be Dolby Vision Profile 7 (FEL). Profile 8.1 files don't have an Enhancement Layer to archive.
## See Also
* [restore](restore) — Rebuild Profile 7 from an archive
* [convert](convert) — Convert with `--backup` flag for batch operations
# cleanup
Source: https://docs.doviconvert.com/command-reference/cleanup
Remove backup files created during conversion
## Synopsis
```shellscript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert cleanup [options]
```
## Description
Scans for and removes `*.mkv.bak.dovi_convert` backup files in the current directory. Includes orphan protection — only deletes backups where the corresponding converted file exists in the same directory.
## Options
| Option | Short | Description |
| ------------- | ----- | ------------------------------------------------------ |
| `--recursive` | `-r` | Scan recursively through subdirectories |
| `--yes` | `-y` | Skip confirmation prompt |
| `--debug` | — | Generate `dovi_convert_debug.log` with detailed output |
This is irreversible. Your original Profile 7 files are gone permanently unless you have other backups. Only use this if storage space is a concern and you're confident in the conversion results.
## Examples
**Clean up current directory:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert cleanup
```
**Clean up recursively:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert cleanup --recursive
dovi_convert cleanup -r
```
**Auto-confirm cleanup:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert cleanup --yes
dovi_convert cleanup -y
```
**Recursive cleanup without prompts:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert cleanup --recursive --yes
dovi_convert cleanup -r -y
```
## Orphan Protection
The cleanup command has a safety check: it only deletes backups where the corresponding converted file exists in the same directory as the original.
**Example:**
* Backup exists: `movie.mkv.bak.dovi_convert`
* Converted file missing: `movie.mkv` (deleted or moved)
* **Result:** Backup is kept
This prevents data loss if you've deleted a converted file due to quality issues.
## See Also
* [convert](convert) — Convert files or directories
# convert
Source: https://docs.doviconvert.com/command-reference/convert
Convert Profile 7 files or directories to Profile 8.1
## Synopsis
```shellscript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
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
| Argument | Required | Description | |
| --------- | -------------- | ----------- | ----------------------------------------------------------------------------- |
| \`\[files | directories]\` | No | One or more MKV files or directories. If omitted, scans the current directory |
## Options
| Option | Short | Description |
| ------------------ | --------- | ----------------------------------------------------------------------- |
| `--force` | `-f` | Override Complex FEL safety check and convert anyway |
| `--safe` | `-s` | Force Safe Mode (disk extraction). Slower but handles problematic files |
| `--yes` | `-y` | Skip confirmation prompts (for automation) |
| `--recursive [N]` | `-r [N]` | Scan directories recursively up to depth N (default: 5) |
| `--output PATH` | `-o PATH` | Output directory for converted files |
| `--temp PATH` | `-t PATH` | Write temporary files to a separate directory (e.g. fast SSD) |
| `--delete` | — | Delete backup file after successful conversion |
| `--backup` | `-b` | Create a backup of the Enhancement Layer (EL) before conversion |
| `--hdr10` | — | Convert to HDR10 instead of Profile 8.1 (single file only) |
| `--include-simple` | — | Include Simple FEL files in batch conversions |
| `--verbose` | `-v` | Show 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:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert convert movie.mkv
```
**Convert multiple files:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert convert movie1.mkv movie2.mkv movie3.mkv
```
**Convert a directory (batch mode):**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert convert /movies
```
Shows a summary of eligible files, asks for confirmation, then converts.
**Convert directory recursively:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
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:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert convert /movies --recursive 2
dovi_convert convert /movies --recursive 10
```
**Skip confirmation prompts:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
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`.
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert convert /movies --yes --include-simple
```
**Convert to HDR10 (single file only):**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert convert movie.mkv --hdr10
```
Strips all Dolby Vision metadata, leaving a clean HDR10 stream.
**Force conversion of Complex FEL file:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
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:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert convert movie.mkv --safe
dovi_convert convert movie.mkv -s
```
**Delete backup after conversion:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
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:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
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:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert convert movie.mkv --output /converted
dovi_convert convert movie.mkv -o /converted
```
**Enable debug logging:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
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](scan) — Analyze files before conversion
* [cleanup](cleanup) — Remove backup files
# inspect
Source: https://docs.doviconvert.com/command-reference/inspect
Perform full frame-by-frame analysis of FEL brightness metadata
## Synopsis
```shellscript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert inspect [options]
```
## Description
Performs a definitive frame-by-frame analysis of the entire file to verify whether the Enhancement Layer contains active brightness expansion. Use this to verify Simple FEL verdicts from `scan`, or when you need absolute certainty before conversion.
## Arguments
| Argument | Required | Description |
| -------- | -------- | ------------------------------- |
| `` | Yes | Path to the MKV file to inspect |
## Options
| Option | Short | Description |
| --------- | ----- | --------------------------------------------------------------------------------- |
| `--safe` | `-s` | Force Safe Mode (disk extraction). Extracts video stream to disk before analyzing |
| `--debug` | — | Generate `dovi_convert_debug.log` with detailed output |
`inspect` reads the entire file frame-by-frame. For a typical 50-80 GB movie, this takes several minutes. It's not suitable for batch operations.
## Examples
**Inspect a file:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert inspect movie.mkv
```
**Inspect with Safe Mode:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert inspect movie.mkv --safe
dovi_convert inspect movie.mkv -s
```
## Output
After analysis, `inspect` reports:
* Whether **brightness expansion** was detected
* The **peak brightness** values found in the metadata
* **FEL verdict** — Simple FEL (safe) or Complex FEL (skip)
## See Also
* [scan](scan) — Fast sampling analysis
* [convert](convert) — Convert files or directories
# restore
Source: https://docs.doviconvert.com/command-reference/restore
Rebuild a Profile 7 file from a converted file and its archive
## Synopsis
```shellscript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert restore [options]
```
## Description
Restores a Profile 7 file by combining a converted file (Profile 8.1 or HDR10) with its `.dovi` archive. The command automatically detects the current file format and handles the restoration process accordingly.
The output file is named `.restored.mkv` and contains the rebuilt Profile 7 video with all original audio and subtitle tracks.
## Arguments
| Argument | Required | Description |
| -------- | -------- | ------------------------------------------- |
| `` | Yes | A converted MKV file (Profile 8.1 or HDR10) |
## Options
| Option | Short | Description |
| --------------- | --------- | -------------------------------------------------------------- |
| `--source PATH` | — | Path to the `.dovi` archive (if not in same directory as file) |
| `--temp PATH` | `-t PATH` | Write temporary files to a separate directory |
| `--debug` | — | Generate `dovi_convert_debug.log` with detailed output |
## Examples
**Restore using archive in the same directory:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert restore movie.mkv
```
Looks for `movie.dovi` in the same directory as `movie.mkv`.
**Restore using archive from a backup drive:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert restore movie.mkv --source /Volumes/Backups/movie.dovi
```
**Use a fast temp directory:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert restore movie.mkv --temp /mnt/ssd/temp
```
## Output
```
Restoring: movie.mkv
Using backup: movie.dovi
Restoring Profile 7... Done.
Restore completed successfully.
Restored file: movie.restored.mkv
Size: 52.33 GB
Format: Profile 7 (Dolby Vision, Version 1.0, dvhe.07.06, BL+EL+RPU)
```
## Restoration Process
1. **Locate archive** — Finds `.dovi` in the same directory, or uses `--source`
2. **Extract Base Layer** — Pulls the video stream from the current file
3. **Detect format** — Checks if the file is Profile 8.1 or HDR10
4. **Sanitize** — If Profile 8.1, strips the injected RPU to get a clean Base Layer
5. **Unpack archive** — Extracts the original Enhancement Layer
6. **Rebuild** — Muxes Base Layer + Enhancement Layer into Profile 7
7. **Remux** — Combines restored video with original audio and subtitles
8. **Verify** — Confirms the output is valid Profile 7
## Error Handling
**Missing archive:**
```
No backup found.
Expected: /path/to/movie.dovi
Hint: Use --source to specify an alternate backup location.
```
Use `--source` to specify the correct path to the archive.
## Restrictions
* **Single file only.** There is no batch restore mode.
* **Requires matching archive.** The `.dovi` archive must be from the same source file. Using an archive from a different file produces invalid output.
## See Also
* [backup](backup) — Create archives for later restoration
* [Backup & Restore concept](/essentials/backup-restore) — How archiving works
# scan
Source: https://docs.doviconvert.com/command-reference/scan
Analyze files to identify video format and FEL complexity
## Synopsis
```shellscript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert scan [files|directories] [options]
```
## Description
Scans MKV files to identify their video format (HDR10, Dolby Vision Profile) and analyzes Profile 7 files to determine FEL complexity.
You can scan individual files, directories, or any combination. If no path is specified, scans all MKV files in the current directory.
The scan samples 10 timestamps across each file and analyzes the RPU metadata to detect brightness expansion, which indicates Complex FEL.
## Options
| Option | Short | Description |
| ----------------- | -------- | ---------------------------------------------------------- |
| `--recursive [N]` | `-r [N]` | Scan subdirectories recursively up to depth N (default: 5) |
| `--candidates` | — | Show only Profile 7 files that can be converted |
| `--debug` | — | Generate `dovi_convert_debug.log` with detailed output |
## Examples
**Scan current directory:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert scan
```
**Scan specific file:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert scan movie.mkv
```
**Scan a directory:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert scan /movies
```
**Scan multiple directories:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert scan /movies /tv
```
**Mixed files and directories:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert scan /movies movie.mkv /tv
```
**Scan recursively:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert scan --recursive
dovi_convert scan -r
```
Scans up to 5 levels deep by default.
**Limit or expand recursion depth:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert scan --recursive 2
dovi_convert scan -r 2
dovi_convert scan --recursive 10
```
**Directory with recursion:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert scan /movies --recursive 3
dovi_convert scan /movies -r 3
```
**Show only conversion candidates:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert scan --candidates
```
## Output
The scan displays:
* **Video format** — HDR10, Dolby Vision Profile 5/7/8, etc.
* **FEL type** (for Profile 7) — MEL, Simple FEL, or Complex FEL
* **Color-coded verdict** — Green (safe), yellow (verify), red (skip)
## See Also
* [inspect](inspect) — Full frame-by-frame analysis
* [convert](convert) — Convert files or directories
# update-check
Source: https://docs.doviconvert.com/command-reference/update-check
Check for newer versions of dovi_convert
## Synopsis
```
dovi_convert update-check
```
## Description
Checks if a newer version of dovi\_convert is available on GitHub. Displays the current version, latest available version, and a link to the releases page if an update is found.
## Options
| Option | Description |
| --------- | ------------------------------------------------------ |
| `--debug` | Generate `dovi_convert_debug.log` with detailed output |
## Examples
**Check for updates:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert update-check
```
## Automatic Update Checks
dovi\_convert automatically performs background update checks:
* When you run dovi\_convert without any command (shows usage)
* After successful completion of any command
These checks are non-blocking and don't delay command execution.
## Manual Installation
To update dovi\_convert:
1. Download the latest version from [GitHub Releases](https://github.com/cryptochrome/dovi_convert/releases)
2. Replace your existing `dovi_convert.py` file
3. Run `dovi_convert --help` to verify the new version
# Backup & Restore
Source: https://docs.doviconvert.com/essentials/backup-restore
Create space-efficient archives and restore original Profile 7 files
When you convert a Profile 7 file to Profile 8.1 or HDR10, the Enhancement Layer is discarded. The backup feature lets you save this Enhancement Layer as a compact `.dovi` archive before conversion. Later, you can combine this archive with your converted file to rebuild the original Profile 7 file.
## Why Back Up?
By default, `convert` renames the original file to `.bak.dovi_convert` as a safety backup. This works, but it doubles your storage - a 60 GB movie creates a 60 GB backup.
A `.dovi` archive stores only the Enhancement Layer, typically 10-25% of the original size. With this archive, you can delete the large `.bak.dovi_convert` file and still restore the original Profile 7 later.
**Typical archive sizes:**
| FEL Type | Archive Size | Example (60 GB source) |
| ------------------------------- | ------------------ | ---------------------- |
| MEL (Minimal Enhancement Layer) | Very small | 1 GB - 2 GB |
| FEL (Full Enhancement Layer) | 10-25% of original | 6 - 15 GB |
## Creating Backups
You can create a backup either as a standalone operation or during conversion.
### Standalone Backup
Create an archive without modifying the source file:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert backup movie.mkv
```
This creates `movie.dovi` in the same directory as the source.
To save the archive elsewhere:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert backup movie.mkv --output /backups/
```
The `backup` command works on single files only. For batch operations, use `convert --backup` instead.
### Backup During Conversion
Create a backup automatically when you convert:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert convert movie.mkv --backup
```
This creates `movie.dovi` before converting to Profile 8.1. The archive is saved in the same directory as the source file. You can combine this with the `--output` flag, which moves both the converted file as well as the backup archive to the specified output folder.
The `--backup` flag works with both single files and batch mode (directories):
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert convert /movies --recursive --backup
```
Batch backups can consume significant disk space. For example, backing up 50 movies creates around 500 GB of archives. Make sure you have enough free space before running batch operations with `--backup`.
### Combining with `--delete`
If you want to remove the original file after conversion but still have a way to restore:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert convert movie.mkv --backup --delete
```
The `.dovi` archive is preserved even when `--delete` removes the `.bak.dovi_convert` backup.
With `--backup --delete`, your only way to restore the original Profile 7 file is through the `.dovi` archive. Make sure the archive was created successfully before relying on this workflow. Verify before trust.
## Restoring Files
The `restore` command rebuilds a Profile 7 file from a converted file and its `.dovi` archive.
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert restore movie.mkv
```
The command:
1. Locates `movie.dovi` in the same directory
2. Extracts the Base Layer from your current file
3. Detects whether the file is Profile 8.1 or HDR10
4. Sanitizes the Base Layer (removes any injected RPU if present)
5. Rebuilds Profile 7 using the Enhancement Layer from the archive
6. Remuxes with all original audio and subtitle tracks
7. Verifies the result is valid Profile 7
The output is saved as `movie.restored.mkv`. The converted profile 8.1 file is not modified or deleted - you can remove it manually after verifying the restoration.
\*\*Restore is a multi-step remux that processes a substantial amount of data. It can take several minutes, even on fast SSDs (and much longer on HDDs)
### Using Archives from Another Location
If you moved your `.dovi` archive to a backup drive:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert restore movie.mkv --source /Volumes/Backups/movie.dovi
```
### What Gets Restored
The restore process works on both Profile 8.1 and HDR10 files:
| Current File | Process |
| ------------ | ------------------------------------------------------------------- |
| Profile 8.1 | Strips injected RPU from Base Layer, then rebuilds with original EL |
| HDR10 | Rebuilds directly with original EL (no sanitization needed) |
The `restore` command works on single files only. There is no batch restore mode.
## Archive Format
The `.dovi` archive is an uncompressed TAR file containing a single `el.hevc` file (the Enhancement Layer). The format is intentionally simple:
* No compression overhead (the video is already heavily compressed)
* Fast extraction
* Standard format readable by any TAR tool
## Troubleshooting
### Missing Backup Error
If the archive can't be found:
```
No backup found.
Expected: /path/to/movie.dovi
Hint: Use --source to specify an alternate backup location.
```
Use `--source` to point to the correct location.
### Verification Failure
If restore completes but verification shows the file is not Profile 7, the archive may be corrupted or from a different source file.
## Next Steps
Full command reference for creating archives
Full command reference for restoring files
# File Conversion
Source: https://docs.doviconvert.com/essentials/conversion
Convert Dolby Vision Profile 7 files to Profile 8.1
The `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:
1. **Extracts** the video stream from your MKV file
2. **Strips** the Enhancement Layer (EL)
3. **Injects** the RPU metadata into the Base Layer
4. **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_convert` before any changes
* **Scan before convert** — Each file is analyzed to detect Complex FEL
* **Safe defaults** — Complex FEL files are skipped unless you explicitly override
All audio and subtitle tracks are preserved in the converted file.
## Converting Files
### Single Files
Convert a file:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert convert movie.mkv
```
The command:
1. Analyzes the file for FEL complexity
2. Creates a backup (`movie.mkv.bak.dovi_convert`)
3. Converts to Profile 8.1
4. Replaces the original with the converted file
Convert multiple files:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert convert movie1.mkv movie2.mkv movie3.mkv
```
Each file is processed immediately, one after another.
### Directories
When you pass directories instead of files, dovi\_convert switches to batch mode:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert convert /movies
```
In batch mode:
1. All directories are scanned for Profile 7 files
2. A summary shows what will be converted
3. You confirm before conversion begins
4. Each eligible file is converted
Batch mode displays a compact, table-based progress view by default. Use `--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:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert convert /movies --recursive
dovi_convert convert /movies -r
```
This scans up to 5 levels deep. Specify a number to limit or expand the depth:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert convert /movies --recursive 2 # scans and converts 2 levels deep
dovi_convert convert /movies --recursive 10 # scans and converts 10 levels deep
```
#### Skipping Confirmation
For automated workflows, use `--yes` (or `-y`) to skip the confirmation prompts:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert convert /movies --yes
```
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`.
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert convert /movies --yes --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.
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert convert movie.mkv
```
### Safe Mode
Extracts the video stream to disk first, then processes it. Slower, but handles files that Standard mode can't process.
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert convert movie.mkv --safe
dovi_convert convert movie.mkv -s
```
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](#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:
```wrap theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
Simple FEL detected. This file likely converts safely, but verify with inspect if uncertain.
Continue? [y/N]
```
This is a precaution — Simple FEL files usually convert correctly, but the scan might have missed isolated brightness spikes. If you want certainty, run `inspect` first.
## Conversion Options
### Force Mode (`--force`)
Override the Complex FEL safety check:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert convert movie.mkv --force
dovi_convert convert movie.mkv -f
```
### HDR10 Mode (`--hdr10`)
Convert to HDR10 instead of Dolby Vision Profile 8.1:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert convert movie.mkv --hdr10
dovi_convert convert movie.mkv --hdr10 --force # if Complex FEL
```
This strips all Dolby Vision metadata from the file, leaving a clean HDR10 stream. If the source contains HDR10+ metadata, it is preserved.
**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](/before-you-start#complex-fel-brightness-expansion) 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.
HDR10 mode is only available for single file conversions. This is intentional — stripping Dolby Vision entirely is a more significant decision than converting to Profile 8.1.
### Output Directory (`--output`)
Place converted files in a different directory:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert convert movie.mkv --output /converted
dovi_convert convert movie.mkv -o /converted
```
The original file is renamed to `.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:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert convert movie.mkv --temp /mnt/ssd/temp
dovi_convert convert movie.mkv -t /mnt/ssd/temp
```
Use an SSD or NVMe drive as your temp directory for best results.
### Delete Backup (`--delete`)
Automatically delete the backup file after successful conversion:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert convert movie.mkv --delete
```
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) |
The backup contains your complete original file. Restore it by:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
mv "movie.mkv.bak.dovi_convert" "movie.mkv"
```
## Troubleshooting
If conversion fails:
1. Run with `--debug` to generate a log:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert convert movie.mkv --debug
```
2. Check `dovi_convert_debug.log` for errors from ffmpeg, dovi\_tool, or mkvmerge
3. Common issues:
* **Seamless Branching** — Try with `--safe` mode
* **Corrupted files** — Verify the original file plays correctly
* **Disk space** — Safe mode needs space for the extracted video stream
## Next Steps
Learn more about analyzing files before conversion
Managing backup files and restoring originals
# File Scanning & Analysis
Source: https://docs.doviconvert.com/essentials/scanning
Identify video formats and analyze FEL complexity before conversion
Before converting files, you should analyze them to understand their format and whether conversion is safe. dovi\_convert provides two commands for this: `scan` for quick analysis and `inspect` for deep verification.
## Why Scan First?
Not every Dolby Vision Profile 7 file should be converted. Some contain Enhancement Layers with brightness expansion data — converting these produces incorrect results (dark picture, flickering).
Scanning identifies:
* **Video format** — HDR10, HDR10+, Dolby Vision (and which profile)
* **FEL classification** — MEL, Simple FEL, or Complex FEL
* **Conversion safety** — Whether the file is safe to convert
The `convert` command automatically scans files before processing and warns you about risky conversions. Running `scan` separately gives you an overview without starting any conversion.
## The `scan` Command
Scans files to identify their video format and FEL status. You can scan individual files, entire directories, or any combination.
### Basic Usage
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert scan # All MKV files in current directory
dovi_convert scan movie.mkv # Specific file
```
### Scan Directories
Point `scan` at any directory instead of navigating there first:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert scan /movies
```
Scan multiple directories or mix files and directories:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert scan /movies /tv
dovi_convert scan /movies movie.mkv
```
### Recursive Scanning
Scan subdirectories with the `--recursive` (or `-r`) flag:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert scan --recursive # Recursive (default depth: 5)
dovi_convert scan -r # Same, short form
dovi_convert scan --recursive 2 # Recursive (depth: 2 folders)
dovi_convert scan /movies --recursive 3 # Directory with recursion
```
### Show Only Conversion Candidates
If you only want to see files that can be converted (Profile 7), use the `--candidates` flag to filter out SDR, HDR10, Profile 8, and other non-convertible formats:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert scan --candidates
dovi_convert scan /movies --candidates
dovi_convert scan --candidates --recursive 3
```
This is useful when scanning large libraries where most files are already in the correct format.
## Understanding the Output
The scan displays color-coded results for each file:
| Color | Classification | Meaning |
| --------- | -------------- | -------------------------------------------------------- |
| **Green** | MEL | No enhancement data. Safe to convert. |
| **Blue** | Simple FEL | No brightness expansion detected. Usually safe. |
| **Red** | Complex FEL | Active brightness expansion. Conversion not recommended. |
Non-Profile 7 files (HDR10, SDR, etc.) are also identified but cannot be converted by this tool.
### How `scan` Works
The scan samples 10 timestamps across the file and analyzes the RPU (Reference Processing Unit) metadata at each point. It checks for brightness values that exceed the Base Layer's capability — an indicator of Complex FEL.
Sampling is fast but not exhaustive. A file might have brightness spikes in sections the scan didn't sample. For definitive results, use `inspect`.
## Terminology
### MEL (Minimal Enhancement Layer)
The Enhancement Layer exists but contains no useful data. This is the most common type. Converting is completely safe — you lose nothing.
### Simple FEL (No Brightness Expansion)
The Enhancement Layer contains some data (film grain, minor color adjustments), but does not expand brightness. Converting is generally safe — you lose minor enhancements, but the picture remains correct.
### Complex FEL (Brightness Expansion)
The Enhancement Layer actively elevates brightness beyond the Base Layer. Converting produces incorrect tone mapping. These files are skipped by default.
For more details on FEL types and their implications, see [Before You Start](/before-you-start#understanding-the-enhancement-layer).
## The `inspect` Command
Performs a full frame-by-frame analysis of the entire file. Use this when you need definitive confirmation.
### When to Use `inspect`
* Verify a **Simple FEL** verdict from `scan`
* Check if a Complex FEL verdict might be a false positive
* Get absolute certainty before converting a file
* Investigate files that `scan` couldn't fully classify
### Basic Usage
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert inspect movie.mkv
```
### How `inspect` Differs from `scan`
| Aspect | `scan` | `inspect` |
| ----------------- | ------------------------------- | ------------------------ |
| **Speed** | Fast (samples 10 points) | Slow (reads entire file) |
| **Accuracy** | High (may miss isolated spikes) | Definitive |
| **Batch support** | Yes | No (single file only) |
`inspect` reads the entire file frame-by-frame. For a typical 50-80 GB movie, this takes several minutes. It's not suitable for batch operations.
### Interpreting Results
After analysis, `inspect` reports:
* Whether **brightness expansion** was detected (the primary concern)
* The **peak brightness** values found in the metadata
* A **verdict** confirming if the file is safe to convert
If `inspect` says the file is safe but `scan` said Complex FEL, trust `inspect` — it analyzed the entire file rather than sampling.
## Automatic Scanning in Convert
You don't always need to run `scan` manually. The `convert` command performs the same analysis automatically:
* **Complex FEL files** are skipped by default (use `--force` to override)
* **Simple FEL files** trigger a confirmation prompt
This means you can safely run `convert` on any file — the tool warns you before doing anything risky.
## Next Steps
Convert individual files or directories to Profile 8.1
Managing backup files and restoring originals
# Introduction
Source: https://docs.doviconvert.com/index
Convert Dolby Vision Profile 7 to Profile 8.1 safely and automatically
dovi\_convert automates the conversion of Dolby Vision Profile 7 MKV files (typically UHD Blu-ray rips) into Profile 8.1. This ensures compatibility with media players that don't support the Profile 7 Enhancement Layer.
This is the documentation for dovi\_convert. For source code, releases, and issue tracking, visit the GitHub repository.
## Why Convert?
Many popular devices — including Apple TV 4K, Nvidia Shield, Zidoo players, and Plex clients — cannot process the Enhancement Layer in Profile 7 files. Without proper handling, these devices fall back to HDR10, losing Dolby Vision benefits entirely.
Converting to Profile 8.1 strips the Enhancement Layer while preserving the dynamic metadata (RPU), giving you a file that works on virtually any Dolby Vision-capable device.
Not every Profile 7 file should be converted. Some use the Enhancement Layer for brightness expansion — converting these causes visual issues. dovi\_convert analyzes files before conversion and warns you when conversion is risky.
## What You Need to Know
Before using dovi\_convert, you should understand what it does and when conversion is appropriate.
Understand the technical background, caveats, and device-specific considerations
Learn about MEL, Simple FEL, and Complex FEL — and why it matters
## Platform Support
dovi\_convert runs on:
* **macOS** (tested on macOS 26)
* **Linux** (any modern distribution)
* **Windows** (via WSL)
* **Docker** (with web terminal access)
The conversion process does not re-encode video. Your CPU only needs to handle metadata extraction and remuxing — no powerful hardware required.
## Installation
Install directly on macOS, Linux, or Windows (WSL)
Run in a container with a web-based terminal
## Core Concepts
Once installed, familiarize yourself with the main features:
Identify video formats and analyze FEL complexity with `scan` and `inspect`
Convert individual files or directories with `convert`
Archive original layers for future restoration (coming soon)
# Docker
Source: https://docs.doviconvert.com/installation/docker
Run dovi_convert in a container with a web-based terminal
The dovi\_convert Docker container provides a self-contained environment with all dependencies pre-installed. It includes a web-based terminal, so you can access the tool from any browser without installing anything on your host system.
## Features
* **Web terminal** — Access dovi\_convert through your browser at `http://your-host:7681`
* **Pre-configured environment** — All dependencies (ffmpeg, dovi\_tool, mkvtoolnix, mediainfo) included
* **NAS-friendly** — Designed for network storage devices and servers
* **User mapping** — Run with your own UID/GID and set UMASK to avoid file permission issues
* **Persistent sessions** — The container has `tmux` for session management installed
## Quick Start Examples
Save this as `docker-compose.yml`:
```yaml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
services:
dovi_convert:
image: cryptochrome/dovi_convert:latest
container_name: dovi_convert
hostname: dovi-convert
environment:
- PUID=1000 # Your user ID (run 'id' to find)
- PGID=1000 # Your group ID
- TZ=UTC # Your timezone
- TMUX_HISTORY_LIMIT=50000 # Number of lines to reserve for `tmux` buffer
volumes:
# Mount your media folder(s) here
- /mnt/media/movies:/data/movies
- /mnt/media/tv:/data/tv
# - /path/to/ssd:/cache # Optional: fast temp storage
ports:
- 7681:7681
restart: unless-stopped
```
Then start the container:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
docker compose up -d
```
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
docker run -d \
--name=dovi_convert \
-e PUID=1000 \
-e PGID=1000 \
-e TZ=Europe/Berlin \
-p 7681:7681 \
-v /path/to/media:/data \
--restart unless-stopped \
cryptochrome/dovi_convert:latest
```
Then open `http://your-docker-host:7681` in your browser.
## Configuration
### User and Group IDs
The `PUID` and `PGID` environment variables control which user the container runs as. Set these to match your host user to avoid permission problems when accessing files.
To find your user and group IDs:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
id
```
This outputs something like `uid=1000(yourname) gid=1000(yourname)`. Use these values for `PUID` and `PGID`.
### Environment Variables
| Variable | Default | Description |
| -------------------- | ------- | -------------------------------------------- |
| `PUID` | `1000` | User ID for file permissions |
| `PGID` | `1000` | Group ID for file permissions |
| `TZ` | `UTC` | Timezone for log timestamps |
| `UMASK` | `022` | Set file permission UMASK if necessary |
| `TMUX_HISTORY_LIMIT` | `50000` | Number of lines to reserve for `tmux` buffer |
### Volume Mounts
Mount your media directories to `/data` inside the container. You can mount multiple paths, or just your root media folder (subdirectories are automatically included):
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
-v /mnt/movies:/data/movies \
-v /mnt/tv:/data/tv
```
Inside the container, access your files at `/data/movies`, `/data/tv`, etc.
### Temp Directory for Faster Conversions
If your media is on slow storage (mechanical HDDs), you can bind-mount a faster drive for temporary files:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
-v /path/to/ssd:/cache
```
Then use the `--temp` flag when converting:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert convert /data/movie.mkv --temp /cache
```
Temporary files are written to the fast drive while the source and final output stay on your media volume.
### Port Configuration
The web terminal runs on port 7681 inside the container. Map it to any available port on your host:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
-p 8080:7681 # Access at http://your-host:8080
```
## Using the Web Terminal
Once the container is running, open `http://your-docker-host:7681` in your browser. You'll see a terminal session with dovi\_convert ready to use.
The container includes a `dovi` alias for convenience - for example:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi help # Same as dovi_convert --help
dovi scan # Same as dovi_convert scan
# etc.
```
## Session Persistence
If you run longer, unattended conversions and close your browser window, the session will be terminated and the conversion interrupted. To avoid this, you can use `tmux` to create persistent sessions. This allows you to close your browser and later re-attach to the session to check on status or continue working where you left off.
`tmux` sessions persist as long as the container is running, unless you manually terminate them.
### Using `tmux`
This will start a new `tmux` session. You are automatically attached to it and can start working with dovi\_convert.
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
tmux new -s mysession
```
You can simply close your browser and the session will continue running in the background. For a more graceful exit, you can use this keyboard shortcut to detach: Press `Ctrl+b` followed by `d`.
When you later come back and login to the container again, you can re-attach to the existing session with:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
tmux attach -t mysession
```
To list all running sessions, use:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
tmux ls
```
To kill a detached session, use:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
tmux kill-session -t mysession
```
To end a session you are currently attached to, simply exit the shell by typing:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
exit
```
To scroll through the session history after re-attaching, use `Ctrl+b` followed by `[`, then use the arrow or Page Up/Down keys to scroll. Press `q` to exit scroll mode.
For more info on how to use `tmux`, see the [official tmux documentation](https://github.com/tmux/tmux/wiki).
### Session Buffer
By default, the container reserves a buffer of 50,000 lines of text for `tmux`. This should be plenty for scrolling back in sessions after you re-attach (to check on progress, for example). However, 50k lines consume about 50-100 MB of RAM. If you are memory constrained, or want an even larger buffer, you can change the buffer size by setting the `TMUX_HISTORY_LIMIT` environment variable for the Docker container. An example is provided in the Docker Compose file on this page.
***
## Next Steps
Analyze your files to identify formats and FEL status
Convert files or directories to Profile 8.1
# Terminal / Shell
Source: https://docs.doviconvert.com/installation/terminal
Install dovi_convert directly on macOS, Linux, or Windows
This guide covers installing dovi\_convert on your system without Docker. If you prefer a containerized setup with a web terminal, see the [Docker installation](/installation/docker) instead.
## Platform Support
dovi\_convert runs on:
* **macOS** (tested on macOS 26)
* **Linux** (any modern distribution with Python 3.8+)
* **Windows** (via WSL - Windows Subsystem for Linux)
Windows native support is not available. You must use WSL to run dovi\_convert on Windows.
## Dependencies
Before installing dovi\_convert, you need the following tools:
| Dependency | Purpose |
| --------------- | --------------------------------------- |
| **Python 3.8+** | Runtime for the script |
| **ffmpeg** | Video extraction |
| **dovi\_tool** | Dolby Vision metadata processing |
| **mkvtoolnix** | MKV handling (`mkvmerge`, `mkvextract`) |
| **mediainfo** | Media file analysis |
**macOS users:** You must use the command-line versions of these tools, not the `.app` bundles.
GUI applications like MKVToolNix.app or MediaInfo.app are sandboxed differently and don't work correctly with dovi\_convert. Install via [Homebrew](https://brew.sh) or [MacPorts](https://www.macports.org/) instead.
### Automatic Dependency Installation
When you run dovi\_convert, it checks for missing dependencies and offers to install them automatically, using your system's packet manager. It supports:
* **Homebrew** (macOS)
* **apt** (Ubuntu, Debian)
* **dnf** (Fedora)
* **pacman** (Arch Linux)
dovi\_tool may not be available in all package managers. If automatic installation fails, download it manually from the [dovi\_tool GitHub releases](https://github.com/quietvoid/dovi_tool/releases).
## Installation
### Homebrew
```shellscript Install theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
brew install dovi_convert
```
```shellscript Update theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
brew update && brew upgrade dovi_convert
```
### Manual
If you don't have Homebrew, you can manually install it by downloading from Github, making the script executable and moving it into your path:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
curl -sSLO https://github.com/cryptochrome/dovi_convert/releases/latest/download/dovi_convert.py
chmod +x dovi_convert.py
sudo mv dovi_convert.py /usr/local/bin/dovi_convert
```
After installation, run `dovi_convert --help` to verify everything works. To update, simply repeat the same process.
### From Source
If you want to stay updated with development changes:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
git clone https://github.com/cryptochrome/dovi_convert.git
cd dovi_convert
```
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
sudo ln -s "$(pwd)/dovi_convert.py" /usr/local/bin/dovi_convert
```
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
cd /path/to/dovi_convert
git pull
```
## Verify Installation
Run the help command to confirm dovi\_convert is installed correctly:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
dovi_convert help
```
If any dependencies are missing, the script prompts you to install them.
## Next Steps
Now that you've installed dovi\_convert, learn how to use it:
Analyze your files to identify formats and FEL status
Convert individual files or directories to Profile 8.1