# muxm Format Profiles

`muxm` ships ten opinionated profiles, listed below from highest fidelity to widest
compatibility. Each profile is a starting point — every variable it sets can be
overridden from a `.muxmrc` config file or from the CLI.

To inspect the exact variables a profile sets (including any overrides you've
applied), use:

```bash
muxm --profile <name> --print-effective-config
```

---

## Choosing a Profile

| Profile | Container | Codec | Audio | Use when… |
|---|---|---|---|---|
| `archive` | MKV | copy | lossless copy | You want a bit-perfect archive with DV + HDR10 intact. |
| `hdr10-hq` | MKV | HEVC | lossless | Your gear is HDR10 but not Dolby Vision. |
| `av1-hq` | MKV | AV1 (SVT) | lossless | High-quality AV1 archive for AV1-capable playback. |
| `atv-directplay-hq` | source ext | HEVC | E-AC-3 | Plex → Apple TV 4K and you never want transcoding. |
| `atv-directplay-animation` | source ext | HEVC | E-AC-3 | Anime/cartoons for Apple TV Direct Play. |
| `streaming-hevc` | MP4 | HEVC | E-AC-3 | Plex/Jellyfin on mixed modern clients; file size matters. |
| `streaming-av1` | MP4 | AV1 (SVT) | Opus 256k | Modern clients with AV1 decode; smaller than HEVC. |
| `animation` | MKV | HEVC | lossless | Anime or cartoons where banding and styled subs matter. |
| `universal` | MP4 | H.264 | AAC stereo (native preferred) | It has to play everywhere, including old Rokus and phones. |
| `youtube-upload` | MP4 | H.264 | best-scored source track (surround allowed) | Uploading to YouTube; give the re-encoder the cleanest source. |

---

## Profile Details

### `archive` — Lossless Archival

**For:** Collectors and Plex users with a Dolby Vision ecosystem (Apple TV 4K +
DV display, Shield, LG WebOS) who want to preserve original quality for long-term
storage.

**Goal:** Lossless remux only. Preserve Dolby Vision + HDR10 metadata, keep all
audio tracks (multi-track copy, no transcode), keep all subtitle tracks, keep
chapters and metadata. Skip processing entirely if the file already matches the
target. Generate a JSON report and SHA-256 checksum for archival integrity.

**Key behaviors:**

- Video is stream-copied, never re-encoded (unless the source is non-compliant
  and a re-encode is explicitly requested via CLI override).
- Container is always MKV — it can hold any codec losslessly, so an MP4/MOV
  source is re-muxed to MKV with bit-identical streams (nothing is re-encoded).
- All audio tracks matching the language filter are copied losslessly. Commentary
  tracks are excluded by default.
- All subtitle tracks are kept (up to `SUB_MAX_TRACKS`, default 99). Forced
  tracks are detected and flagged. Language tags are normalized.
- The skip-if-ideal heuristic avoids touching files that already conform.
- SHA-256 checksum is generated by default.

> The former name `dv-archival` is still accepted as a deprecated alias.

**CLI:** `muxm --profile archive input.mkv`  
**Script:** `apply_profile_archive()` — Section 11

---

### `hdr10-hq` — High Quality HDR10 (No Dolby Vision)

**For:** HDR10 displays and mixed-device setups where Dolby Vision causes playback
quirks (older streaming devices, non-DV TVs, varied Plex clients).

**Goal:** Maximum HDR10 quality. Strip DV layers, preserve HDR10 static metadata,
re-encode to HEVC Main10 at high quality (CRF 17 / slower), keep lossless audio.

**Key behaviors:**

- DV is stripped unconditionally. If the source is DV-only (no HDR10 fallback
  layer), `muxm` warns that the output may appear dim or washed out.
- Full HDR10 x265 parameter set is applied (colorimetry, mastering display,
  MaxCLL passthrough).
- Pixel format forced to `yuv420p10le`.

**CLI:** `muxm --profile hdr10-hq input.mkv`  
**Script:** `apply_profile_hdr10_hq()` — Section 11

---

### `av1-hq` — High-Quality AV1

**For:** Home media enthusiasts with AV1-capable playback hardware (Plex on
Shield Pro, Fire TV Stick 4K Max, Chromecast with Google TV, compatible smart
TVs) who want a high-fidelity, space-efficient archive encode.

**Goal:** Maximum AV1 quality. Encode to SVT-AV1 at preset 6 with a
**resolution-aware CRF** (28 for ≤1080p SDR, 24 for ≥4K or HDR — the calibrated
transparency points, see `AV1_CALIBRATION.md §4`), preserve HDR10 metadata, keep
lossless audio, generate a checksum for archival integrity. Dolby Vision is not
supported by the AV1 encode pipeline and is automatically disabled.

**Key behaviors:**

- Video codec is `libsvt-av1`; `SVT_AV1_PARAMS_BASE` is applied when set.
- CRF is resolution-aware: the profile bases at **CRF 28** (the 1080p-SDR
  transparency point) and `_apply_av1_resolution_crf` drops it to
  **`AV1_HQ_HDR_CRF`** (default **24**) for ≥4K or HDR sources, after the source
  is probed. An explicit `--crf` always wins. For measured HEVC-CRF-18 parity on
  4K/HDR (larger files), pass `--crf 20`, or set `AV1_HQ_HDR_CRF=20`.
- DISABLE_DV is forced to `1` — AV1 containers cannot carry DV metadata.
  muxm emits an informational note when a DV source is detected.
- Lossless audio codecs (TrueHD, DTS-HD MA, FLAC) are passed through
  untouched.
- SHA-256 checksum is generated by default.
- Always outputs MKV (MP4 has limited AV1 HDR10 support at this time).

**CLI:** `muxm --profile av1-hq input.mkv`  
**Script:** `apply_profile_av1_hq()` — Section 11

---

### `atv-directplay-hq` — Apple TV Direct Play (Plex) Optimized

**For:** Plex → Apple TV 4K setups aiming for true Direct Play with zero
transcoding.

**Goal:** Conform to tvOS and Plex playback constraints while keeping high
quality. HEVC Main10, DV Profile 8.1 when possible (with clean HDR10 fallback),
E-AC-3 audio (with Atmos JOC when present), and text-based subtitles.

**Key behaviors:**

- Container follows the source: MKV sources stay MKV, MP4 sources stay MP4.
  Unsupported source containers fall back to MKV.
- DV Profile 8.1 is preserved if the source is compliant; otherwise falls back
  to clean HDR10. Profile 7 FEL sources are not output as P7.
- Video is stream-copied when already compliant (bitrate and codec checks
  included); otherwise re-encoded at CRF 17 / slower with level 5.1 VBV
  constraints.
- Surround audio is transcoded to E-AC-3 (Apple TV cannot Direct Play TrueHD).
- Forced subtitles are embedded as soft subs (`mov_text` for MP4, native format
  for MKV); all others are also embedded as `mov_text`.
- For MKV output: native ASS/SSA formatting is preserved.
- The skip-if-ideal heuristic avoids re-processing compliant files.

**CLI:** `muxm --profile atv-directplay-hq input.mkv`  
**Script:** `apply_profile_atv_directplay_hq()` — Section 11

---

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

**For:** Anime and cartoon content destined for Apple TV 4K via Plex, where both
animation quality and true Direct Play matter.

**Goal:** Combine the animation-tuned encoder of the `animation` profile with the
Apple TV Direct Play constraints of `atv-directplay-hq`. High quality, no
transcoding on playback, styled subs preserved.

**Key behaviors:**

- CRF 16, `slower` preset, animation-tuned x265 parameters (`psy-rd=1.0`,
  `psy-rdoq=0.5`, `aq-mode=3`) to suppress ringing and eliminate banding.
- HEVC 10-bit unconditionally, even for 8-bit SDR sources.
- Lossless audio (TrueHD, DTS-HD MA, FLAC) is transcoded to E-AC-3 — Apple TV
  cannot Direct Play lossless codecs.
- Multi-track subtitles: all matching tracks stream-copied. Native ASS/SSA
  preserved for MKV output.
- Container follows the source (MKV in → MKV out; MP4 in → MP4 out).
- Forced subtitles are soft subs in any container. For MKV output: native ASS/SSA preservation.

**CLI:** `muxm --profile atv-directplay-animation show.mkv`  
**Script:** `apply_profile_atv_directplay_animation()` — Section 11

---

### `streaming-hevc` — Modern HEVC Streaming

**For:** Plex, Jellyfin, and Emby users targeting modern clients — Shield, Fire
TV, Roku Ultra, smart TVs, and web browsers. Balances quality with file size.

**Goal:** Smaller files with broad modern-device support. HEVC CRF 20 / medium,
HDR10 preserved, DV stripped, E-AC-3 surround at streaming-friendly bitrates.

**Key behaviors:**

- DV is stripped; HDR10 metadata is kept.
- Audio is transcoded to E-AC-3 at reduced bitrates (448k for 5.1, 640k for
  7.1).
- Subtitles are soft-embedded (forced + full, no SDH, no burn).
- Chapters and metadata are preserved.

> The former name `streaming` is still accepted as a deprecated alias.

**CLI:** `muxm --profile streaming-hevc input.mkv`  
**Script:** `apply_profile_streaming_hevc()` — Section 11

---

### `streaming-av1` — AV1 Streaming

**For:** Plex, Jellyfin, and Emby users whose clients support AV1 hardware
decode — Fire TV Stick 4K Max, Chromecast with Google TV, modern web browsers,
and AV1-capable smart TVs. Delivers smaller files than `streaming-hevc` at
equivalent perceptual quality on supported hardware.

**Goal:** Efficient AV1 encode for streaming. SVT-AV1 CRF 30 / preset 6,
HDR10 preserved, DV stripped, Opus audio at 256k. Always outputs MP4.

**Key behaviors:**

- Video codec is `libsvt-av1`; Dolby Vision is unconditionally disabled (the
  AV1 pipeline does not support DV muxing).
- HDR10 static metadata is preserved through the encode.
- Audio is encoded to Opus at 256k surround (`AUDIO_FORCE_BITRATE="256k"`).
  `AUDIO_FORCE_BITRATE` takes precedence over `EAC3_BITRATE_5_1` /
  `EAC3_BITRATE_7_1` when set.
- Subtitles are soft-embedded (forced + full, no SDH, no burn).
- Chapters and metadata are preserved.

**CLI:** `muxm --profile streaming-av1 input.mkv`  
**Script:** `apply_profile_streaming_av1()` — Section 11

---

### `animation` — Anime & Cartoon Optimized

**For:** Anime and cartoon content where banding-free gradients, clean hard edges,
and styled subtitle preservation matter. Ideal for archival-quality animation
encodes.

**Goal:** Artifact-free animation encoding. HEVC at CRF 16 / slower with
animation-tuned x265 parameters (reduced psy-rd, lowered aq-strength, adjusted
deblock, extra b-frames). 10-bit output unconditionally — even for 8-bit SDR
sources — to eliminate banding. MKV container to support styled ASS/SSA
subtitles and lossless audio.

**Key behaviors:**

- 10-bit pixel depth is forced for all sources regardless of input bit depth.
  This is the primary defense against gradient banding in flat-shaded animation.
- Lossless audio is copied through (FLAC-first codec preference for typical
  anime releases).
- Multi-track subtitles are kept (up to 6 tracks). Native ASS/SSA formatting
  is preserved instead of converting to SRT. Subtitles are never burned.
- Chapters are kept (OP/ED markers).

**CLI:** `muxm --profile animation input.mkv`  
**Script:** `apply_profile_animation()` — Section 11

---

### `universal` — Universal Compatibility

**For:** Playback anywhere — old Rokus, mobile devices, web browsers, non-HDR TVs.
Sharing with friends and family who shouldn't have to think about playback
capability.

**Goal:** Compatibility over fidelity. Tone-map HDR to SDR, encode to H.264, AAC
stereo audio, burn forced subtitles, export the rest as external `.srt` files,
strip chapters and non-essential metadata.

**Key behaviors:**

- HDR sources are tone-mapped to SDR via zscale + hable.
- Audio is output as a single AAC stereo track. The best native stereo (2ch)
  track is selected when one exists; otherwise the best-scored track is
  downmixed to stereo via `MAX_AUDIO_CHANNELS=2`.
- Forced subtitles are burned. Non-forced subs are exported as `.srt` sidecar
  files. SDH tracks are excluded.
- Chapters and non-essential metadata are stripped.

**CLI:** `muxm --profile universal input.mkv`  
**Script:** `apply_profile_universal()` — Section 11

---

### `youtube-upload` — YouTube Upload Prep

**For:** Uploading videos to YouTube where you want to give YouTube's encoder the
cleanest, highest-quality master possible.

**Goal:** High-quality H.264 in an MP4 container optimized for YouTube ingestion.
Because YouTube re-encodes every upload, the goal is source quality — not file
size.

**Key behaviors:**

- H.264 High profile, CRF 16, `slow` preset, with x264 params
  (`profile=high:rc-lookahead=60:aq-mode=2:aq-strength=1.0`).
- Best-scored audio track kept as-is (surround allowed). YouTube re-encodes
  all audio server-side, so the goal is the cleanest possible source.
- Dolby Vision disabled; HDR10 metadata preserved so YouTube can use it.
- Forced subtitles are embedded as soft subs (mov_text).
- All other dialogue subtitles (excluding SDH) exported as an external `.srt`
  file for upload to YouTube Studio.
- Non-essential metadata stripped; chapters preserved.

**CLI:** `muxm --profile youtube-upload movie.mkv`  
**Script:** `apply_profile_youtube_upload()` — Section 11

---

## Configuration Precedence

`muxm` reads configuration from multiple levels, applied in this order (each
layer overrides the one before it):

1. **Hardcoded defaults** — built into the script (Section 4)
2. **System config** — `/etc/.muxmrc`
3. **User config** — `~/.muxmrc`
4. **Project config** — `./.muxmrc` (in the current working directory)
5. **Profile** — `--profile <name>` (or `PROFILE_NAME` set in a config file)
6. **CLI flags** — command-line arguments (highest precedence)

### Setting a Default Profile

```bash
# In ~/.muxmrc
PROFILE_NAME="atv-directplay-hq"
```

`--profile` on the CLI always overrides a `PROFILE_NAME` set in a config file.

### Generating a Config File

```bash
muxm --create-config user streaming-hevc
```

This writes a `~/.muxmrc` pre-filled with the `streaming-hevc` profile's defaults.
Profile-specific variables are uncommented and active; everything else is
commented out for you to customize. Valid scopes are `system`, `user`, and
`project`.

### Verifying the Effective Configuration

```bash
muxm --profile atv-directplay-hq --crf 20 --print-effective-config
```

Shows every variable grouped by section, which profile is active, and each
value's source (`cli`, `config-file`, or `profile`).

### Override Example

```bash
# User config sets a default profile
# ~/.muxmrc: PROFILE_NAME="hdr10-hq"

# CLI overrides CRF and container
muxm --profile hdr10-hq --crf 20 --output-ext mp4 input.mkv
```

Result: `hdr10-hq` profile with `CRF_VALUE=20` and `OUTPUT_EXT=mp4`. The CLI
flags win.

---

## Conflict Warnings

`muxm` detects contradictory profile + flag combinations and prints warnings.
Warnings never block execution — the user's CLI flags always win.

Examples:

```
muxm --profile archive --no-dv input.mkv
# ⚠️  Profile 'archive' + --no-dv: DV archival without Dolby Vision is pointless.
#     Output will be a plain remux.

muxm --profile animation --sub-burn-forced input.mkv
# ⚠️  Profile 'animation' + --sub-burn-forced: Burning subs destroys ASS styling
#     (typesetting, signs, karaoke). Soft subs recommended.

muxm --profile universal --video-codec libx265 input.mkv
# ⚠️  Profile 'universal' + --video-codec libx265: HEVC is less widely supported
#     than H.264 for universal playback.
```

The full set of checked conflicts is in Section 13 of the script.

> **Note:** `--sub-burn-forced` (and the `universal` profile, which burns by default)
> forces a re-encode of the video stream — burning a subtitle into the picture is
> incompatible with a pure stream-copy. So combining `--sub-burn-forced` with a
> copy-compliant profile such as `atv-directplay-hq` overrides
> `VIDEO_COPY_IF_COMPLIANT`/skip-if-ideal and re-encodes (the forced track is burned
> in rather than silently dropped).

---