MKVPriority is a command-line tool and Docker image that fixes default audio and subtitle track selection in MKV files. It scores every track in a file against rules you define in a TOML config (language, codec, channel count, subtitle format, track-name patterns) and then sets the default and forced flags on the highest-scoring tracks, so players open the right audio and subtitles instead of the first stream in the container. All changes are made in place with mkvpropedit, which rewrites Matroska metadata only: no remuxing, no re-encoding, and a whole library can be corrected in a single pass. The latest release is v1.5.1.

Key Features

• Configurable priority scores — TOML rules assign numeric scores to track properties, modelled on the custom-format system in Radarr and Sonarr.
• Automatic default and forced flags — The highest-scoring audio track gets default, and the highest-scoring subtitle track gets default or forced, with the rest cleared.
• Deprioritises unwanted tracks — Name filters push English dubs, commentary tracks, and signs/songs subtitle tracks down the order so players stop picking them.
• Metadata-only edits — Uses mkvpropedit from MKVToolNix, so streams are never decoded or re-encoded and the operation is fast and reversible.
• Radarr and Sonarr integration — Ships a custom script for the On File Import and On File Upgrade triggers, plus an API lookup that resolves the original language as the special org code.
• Cron scheduler and archive database — A built-in scheduler rescans the library on a schedule, while an SQLite archive database keeps each scan to files it has not already processed.
• Per-tag configurations — Append ::TAG to config and target paths to route different rules to different libraries, for example anime and western content in one stack.
• Safe operation — --dry-run simulates changes, --verbose dumps full track metadata and scores, and --restore rolls back previous edits from the archive database.
• Extension modules — Optional post-processors, including a subtitle extractor that writes the highest-priority embedded subtitle out as an external SRT or ASS file.

Why Use MKVPriority?

Radarr and Sonarr decide which release you download, but they never touch the track flags inside the file. A downloaded MKV can carry a stereo track flagged default while the 5.1 mix sits unused, or play an English dub instead of the original Japanese audio, and every playback starts with a manual switch. MKVPriority closes that gap: describe your preferences once, and it scores tracks per file and writes the flags, so Jellyfin, Emby, Plex, Kodi and mpv pick the right stream from the start. Because it only edits container metadata, the fix costs seconds per file and can be undone.

Use Cases

• Anime libraries where Japanese audio and ASS subtitles should be default, with English dubs deprioritised.
• Multi-language film collections that need forced subtitles for foreign dialogue.
• Homelab media stacks: run it as a Radarr/Sonarr custom script so new imports are corrected automatically.
• Scheduled library maintenance with the cron container and archive database, touching only new files.
• Bulk audits: score an entire library with --dry-run before writing anything.
• Rollback of a bad rule set with --restore, without re-downloading media.

source at github.com/kennethsible/mkvpriority