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

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

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

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

<Callout icon="circle-exclamation" iconType="solid" color="#ef9f76">
  With `--yes`, Simple FEL files are skipped unless you also pass `--include-simple`.
</Callout>

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

<Callout icon="circle-exclamation" iconType="solid" color="#ef9f76">
  Forcing conversion on Complex FEL files produces incorrect tone mapping. Only use this if you understand and accept the quality loss.
</Callout>

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

<Callout icon="triangle-exclamation" iconType="solid" color="#e78284">
  This removes your only copy of the original Profile 7 file. Use with caution.
</Callout>

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