> ## Documentation Index
> Fetch the complete documentation index at: https://docs.doviconvert.com/llms.txt
> Use this file to discover all available pages before exploring further.

# File 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

<Callout icon="circle-info" iconType="solid" color="#8caaee">
  No video re-encoding happens. The bitstream is processed directly, so conversion is fast and quality is preserved exactly.
</Callout>

## 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
```

<Callout icon="circle-exclamation" iconType="solid" color="#ef9f76">
  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`.
</Callout>

```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
```

<Callout icon="circle-info" iconType="solid" color="#8caaee">
  If Standard mode fails (common with Seamless Branching or irregular file structures), Safe mode is triggered automatically. You don't need to manually retry.
</Callout>

## 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)).

<Callout icon="circle-exclamation" iconType="solid" color="#ef9f76">
  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.
</Callout>

### 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.

<Callout icon="circle-info" iconType="solid" color="#8caaee">
  **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.
</Callout>

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
```

<Callout icon="lightbulb" iconType="solid" color="#a6d189">
  Use an SSD or NVMe drive as your temp directory for best results.
</Callout>

### 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
```

<Callout icon="triangle-exclamation" iconType="solid" color="#e78284">
  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.
</Callout>

## 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

<CardGroup cols={2}>
  <Card title="File Scanning" icon="scanner-image" href="/essentials/scanning">
    Learn more about analyzing files before conversion
  </Card>

  <Card title="Backup and Restore" icon="clock-rotate-left" href="/essentials/backup-restore">
    Managing backup files and restoring originals
  </Card>
</CardGroup>