MuxMaster

MuxMaster (muxm) — a single-command video repacking and encoding utility that handles Dolby Vision, HDR10, audio track selection, subtitle processing, and container muxing so you don't have to. Built for home media enthusiasts managing Plex, Jellyfin, or Emby libraries from disc rips and downloads. Pick a profile, point it at a file, and get a properly encoded output without memorizing ffmpeg flags.

# Install via Homebrew (macOS)
brew install TheBluWiz/muxm/muxm

# Encode for Apple TV Direct Play — that's it
muxm --profile atv-directplay-hq movie.mkv

<a id="why-muxmaster"></a>

💡 Why MuxMaster?

Getting a Blu-ray rip to direct-play correctly on an Apple TV, a Roku, or through Plex — without the server transcoding on the fly — is a surprisingly deep problem. The video might be Dolby Vision Profile 7 that needs conversion to Profile 8.1. The audio might be TrueHD, which your player can't direct-play, so you need E-AC-3 — but you also want a stereo AAC fallback for when you're watching on a phone. The forced subtitles need to be burned in because MP4 containers don't handle PGS bitmaps. And the color space metadata needs to survive the whole process.

You can solve all of this with raw ffmpeg, but the command will be 15+ flags long, different for every source file, and you'll need to inspect the source with ffprobe first to figure out what half those flags should even be. Every new file is a new puzzle.

HandBrake is the go-to GUI for video encoding, and it's excellent for what it does. But its preset system doesn't adapt to what's actually in the file. It can't detect that your source is already Apple TV-compliant and skip the encode. It doesn't extract Dolby Vision RPUs, convert between DV profiles, or inject them back into re-encoded video. It won't selectively OCR your PGS subtitles to SRT when the output container can't carry bitmaps. And it won't generate a JSON report of everything it did for your records. HandBrake gives you a good encode; MuxMaster gives you an opinionated pipeline that understands the relationship between your source, your target device, and every stream in the file.

Tdarr solves the batch-processing and automation problem well, especially at library scale. But it requires a server, a database, a web UI, and Node.js — it's infrastructure. If you want to process a single file, or a handful of files, with precise control over DV handling, audio track selection, and subtitle policy, Tdarr's plugin system means writing JavaScript to configure what muxm handles with a single --profile flag. Tdarr is a media library manager; MuxMaster is a per-file encoding tool that aims to make every decision correctly so you don't have to inspect the output.

MuxMaster sits in the gap between "I know ffmpeg well enough to do this manually" and "I need a server-based automation platform." It's a single Bash script with only three required packages (ffmpeg, jq, and bc) and optional tooling for Dolby Vision and subtitle OCR. It understands Dolby Vision at the RPU level, and its profile system encodes the tribal knowledge of what actually works on real hardware into repeatable, overridable presets.

Configuration is where the design philosophy comes together. Most CLI tools expect you to read the source code to learn which variables exist, then hand-build a dotfile from scratch. muxm --create-config generates a complete, commented config file pre-seeded with a real profile's values — you start from a working baseline and customize, not from a blank page. Configs cascade through three tiers (system, user, project) so an encoding team can lock organization defaults in /etc/.muxmrc while individuals override their preferred CRF or audio settings in ~/.muxmrc and specific project directories can pin a streaming profile. And --print-effective-config shows you the fully resolved result of all those layers before you commit to an encode, so you always know exactly what's about to happen.

---

Table of Contents

• Format Profiles
• How It Works
• Installation
  • Upgrading
• Usage
• Why MuxMaster?
• Configuration
• Additional Features
• FAQ
• License
• Bug Reports
• Contact
• Author
• Changelog

---

<a id="format-profiles"></a>

🎯 Format Profiles

Profiles are named presets that configure muxm for a specific use case in a single flag. Every setting a profile changes can be individually overridden with CLI flags.

muxm --profile <name> input.mkv

| Profile | Goal | Video | Audio | Subtitles | DV | | --- | --- | --- | --- | --- | --- | | archive | Lossless preservation | Copy (no re-encode) | All tracks, lossless passthrough | Multi-track stream-copy (all types, up to 99) | Preserve | | hdr10-hq | Max HDR10 quality | HEVC CRF 17 | Lossless + stereo fallback | Single-track per type, soft subs | Strip | | atv-directplay-hq | Apple TV Direct Play | HEVC Main10 (copy if compliant) | E-AC-3 + AAC stereo | Burn forced; others as mov_text; PGS→OCR | P8.1 auto | | streaming | Modern HEVC streaming | HEVC CRF 20 | E-AC-3 448k + AAC stereo | Soft forced + full (no SDH); PGS→OCR | Strip | | animation | Anime/cartoon optimized | HEVC CRF 16, 10-bit | Lossless + stereo fallback | Multi-track stream-copy (up to 6); preserve ASS/SSA | Strip | | atv-directplay-animation | Anime for Apple TV Direct Play | HEVC CRF 16, slower, animation psy params | E-AC-3 (lossless transcoded for ATV) | Multi-track; native ASS/SSA; soft forced (MKV) | Strip | | universal | Play anywhere | H.264 SDR (tone-map HDR) | AAC stereo | Burn forced; export others as external SRT | Strip | | youtube-upload | YouTube upload prep | H.264 High CRF 16, slow | AAC stereo 256k | Burn forced; export full subs as SRT | Disabled (HDR10 preserved) |

archive — Lossless Archival

For collectors who want bit-perfect preservation. Copies video without re-encoding, keeps all matching audio and subtitle tracks via lossless stream-copy, and generates a JSON report with SHA-256 checksum. Always outputs MKV. Commentary and descriptive audio tracks are dropped by default. Language filtering is controlled by AUDIO_LANG_PREF and SUB_LANG_PREF — when empty (the default), all languages pass. Skips processing entirely if the source already matches.

Formerly dv-archival, which is still accepted as a deprecated alias.

muxm --profile archive movie.mkv

hdr10-hq — High Quality HDR10

Strips Dolby Vision layers and re-encodes to clean HDR10 HEVC at CRF 17. Preserves lossless audio (TrueHD, DTS-HD MA, FLAC) and adds a stereo fallback track. MKV output.

muxm --profile hdr10-hq movie.mkv

atv-directplay-hq — Apple TV Direct Play

Targets true Direct Play on Apple TV 4K via Plex: MP4 container, HEVC Main10 with DV Profile 8.1 when possible, E-AC-3 surround (with Atmos JOC when present) with AAC stereo fallback, and forced subtitle burn-in. Copies compliant video without re-encoding. Skips processing if source is already ATV-compliant.

muxm --profile atv-directplay-hq movie.mkv

streaming — Modern HEVC Streaming

Optimized for Plex, Jellyfin, and Emby on modern clients: Shield, Fire TV, Roku Ultra, smart TVs, and web browsers. HEVC CRF 20 with E-AC-3 surround at streaming-friendly bitrates, AAC stereo fallback, and soft subtitles. Always outputs MP4. Strips DV and keeps HDR10. Balances quality with file size.

muxm --profile streaming movie.mkv

animation — Anime & Cartoon Optimized

Tuned for animation content: lower psy-rd/psy-rdoq to avoid ringing on hard cel edges, 10-bit even for SDR to eliminate banding in gradients, and lossless audio passthrough. MKV container preserves styled ASS/SSA subtitles. All matching subtitle tracks — including PGS bitmap streams — are stream-copied from source (up to 6). Chapter markers are preserved.

muxm --profile animation movie.mkv

atv-directplay-animation — Anime for Apple TV Direct Play

Combines the animation-tuned encoder settings of the animation profile with the Apple TV Direct Play constraints of atv-directplay-hq. Encodes at CRF 16 with the slower preset and animation-optimized psychovisual parameters (psy-rd=1.0, psy-rdoq=0.5, aq-mode=3) to suppress ringing on hard cel edges and eliminate banding in gradients. Audio is transcoded to E-AC-3 surround for ATV compatibility — lossless codecs (TrueHD, DTS-HD MA, FLAC) that cannot direct-play on Apple TV are re-encoded rather than passed through. All matching subtitle tracks are stream-copied in multi-track mode, with native ASS/SSA preserved when the output is MKV. Forced subtitles are embedded as soft subs in MKV output — no burn-in. Container follows the source: MKV in, MKV out; MP4 in, MP4 out.

muxm --profile atv-directplay-animation show.mkv

universal — Universal Compatibility

Plays on everything: old Rokus, mobile devices, web browsers, and non-HDR TVs. Tone-maps HDR to SDR, encodes to H.264, forces AAC stereo audio, burns forced subtitles, exports others as external SRT, and strips chapters and non-essential metadata. Always outputs MP4.

muxm --profile universal movie.mkv

youtube-upload — YouTube Upload Prep

Optimized for uploading to YouTube. Encodes to H.264 High profile at CRF 16 with the slow preset and AAC stereo at 256k in an MP4 container. Forced subtitles are burned into the video stream; all other dialog