tdarr-plugs/PLUGIN_DOCUMENTATION.md

# Tdarr Plugin Suite Documentation

> **Version**: 2025-12-16  
> **Plugins**: misc_fixes v2.8 | stream_organizer v4.10 | audio_standardizer v1.15 | av1_converter v2.34

---

## Recommended Pipeline Order

```
1. Misc Fixes          → Fix containers, timestamps, clean streams
2. English First       → Organize streams, handle subtitles
3. Audio Standardizer  → Convert audio codecs
4. AV1 Converter       → Convert video codec (most intensive)
```

> [!TIP]
> Run plugins in this order to fail fast on cheap operations before expensive video encoding.

---

## Plugin 1: Misc Fixes (v2.6)

**Purpose**: First-in-pipeline cleanup for edge cases and container standardization.

### Features & Impact

| Feature | Quality | Filesize | Speed | Default | Why |
|---------|---------|----------|-------|---------|-----|
| `target_container` | — | — | Fast | `mkv` | MKV supports all codecs/subs, best compatibility |
| `force_conform` | — | ↓ Smaller | Fast | `true` | Drops incompatible streams to prevent mux errors |
| `remove_image_streams` | — | ↓ Smaller | Fast | `true` | Removes cover art spam (MJPEG/PNG/GIF) |
| `ensure_video_first` | — | — | Fast | `true` | Fixes player compatibility issues |
| `fix_ts_timestamps` | ↑ Better | — | Fast | `true` | Fixes playback issues in TS/AVI/MPG files |

### Container Compatibility Rules

**MKV Target** (drops):
- `mov_text` (Apple subtitle format)
- `eia_608` (closed captions)
- `timed_id3` (metadata)
- `data` streams

**MP4 Target** (drops):
- `hdmv_pgs_subtitle` (Blu-ray PGS)
- `eia_608` (closed captions)
- `subrip` (SRT subtitles)
- `timed_id3` (metadata)

---

## Plugin 2: English First Streams (v4.7)

**Purpose**: Stream organization and subtitle management.

### Features & Impact

| Feature | Quality | Filesize | Speed | Default | Why |
|---------|---------|----------|-------|---------|-----|
| `includeAudio` | — | — | Fast | `true` | English audio first improves player UX |
| `includeSubtitles` | — | — | Fast | `true` | English subs first improves accessibility |
| `standardizeToSRT` | ↑ Compat | ↓ Smaller | Medium | `true` | SRT is universally supported |
| `extractSubtitles` | — | — | Fast | `false` | External subs optional, not always wanted |
| `removeAfterExtract` | — | ↓ Smaller | Fast | `false` | Keep embedded subs by default |
| `skipCommentary` | — | — | — | `true` | Commentary tracks rarely desired |
| `setDefaultFlags` | — | — | Fast | `false` | Let player decide defaults |
| `customLanguageCodes` | — | — | — | `eng,en,...` | Covers all common English variants |
| `useCCExtractor` | — | — | Slow | `false` | CC extraction is optional extra step |
| `embedExtractedCC` | — | ↑ Larger | Fast | `false` | Only if you want CC in container |

### Subtitle Handling

| Source Codec | Action | Reason |
|--------------|--------|--------|
| ASS/SSA | → SRT | Universal compatibility |
| WebVTT | → SRT | Always converted (problematic in containers) |
| mov_text | → SRT | Apple format, limited support |
| PGS/VobSub | Copy | Image-based, cannot convert to SRT |
| eia_608/cc_dec | Skip | Requires CCExtractor |

---

## Plugin 3: Combined Audio Standardizer (v1.12)

**Purpose**: Audio codec and channel standardization.

### Features & Impact

| Feature | Quality | Filesize | Speed | Default | Why |
|---------|---------|----------|-------|---------|-----|
| `codec` | ↑ Opus better | ↓ Opus smaller | Medium | `opus` | Opus is more efficient than AAC |
| `skip_if_compatible` | — | — | ↑ Faster | `true` | Don't re-encode if already AAC/Opus |
| `bitrate_per_channel` | ↕ Varies | ↕ Varies | — | `auto` | Smart: min(64kbps/ch, source) |
| `channel_mode` | ↓ Stereo loses | ↓ Stereo smaller | — | `preserve` | Keep original channels by default |
| `create_downmix` | — | ↑ Larger | Slow | `true` | 2ch compatibility track |
| `create_6ch_downmix` | — | ↑ Larger | Slow | `false` | 5.1 from 7.1, rarely needed |
| `downmix_single_track` | — | ↓ Smaller | ↑ Faster | `false` | One downmix per language is enough |
| `force_transcode` | — | — | ↓ Slower | `false` | Only re-encode if needed |
| `opus_application` | ↕ Varies | — | — | `audio` | Best for music/movies |
| `opus_vbr` | ↑ VBR better | ↓ VBR smaller | — | `on` | VBR = best quality per bit |
| `opus_compression` | ↑ 10 best | — | ↓ 10 slowest | `10` | Max quality for archival |
| `aac_profile` | ↕ Varies | ↕ Varies | — | `aac_low` | AAC-LC: best quality/compatibility |
| `target_sample_rate` | ↓ Lower = worse | ↓ Lower = smaller | — | `original` | Preserve source quality |
| `preserve_metadata` | — | — | — | `true` | Keep language/title tags |
| `quality_preset` | ↕ Varies | ↕ Varies | — | `custom` | Manual control preferred |

### Quality Presets

| Preset | AAC kbps/ch | Opus kbps/ch | Use Case |
|--------|-------------|--------------|----------|
| `high_quality` | 128 | 96 | Archival, high-end audio |
| `balanced` | 80 | 64 | General streaming |
| `small_size` | 64 | 64 | Space-constrained |
| `custom` | (manual) | (manual) | Full control |

### Opus Compatibility Note

Incompatible layouts auto-downmix to stereo:
- `3.0(back/front)`, `4.0`, `5.0(side)`, `6.0`, `6.1`, `7.0`, `7.0(front)`

---

## Plugin 4: AV1 SVT Converter (v2.22)

**Purpose**: Video transcoding with modern AV1 codec using SVT-AV1.

### Core Settings Impact

| Feature | Quality | Filesize | Speed | Default | Why |
|---------|---------|----------|-------|---------|-----|
| `crf` | ↓ Higher = worse | ↓ Higher = smaller | ↑ Higher = faster | `26` | Sweet spot for 1080p |
| `preset` | ↓ Higher = worse | — | ↑ Higher = faster | `6` | Best speed/quality balance |
| `tune` | 0=VQ best | — | 0=VQ slowest | `0` | Visual Quality mode |
| `input_depth` | ↑ 10-bit better | ↓ 10-bit smaller | ↓ 10-bit slower | `10` | Prevents banding, minimal penalty |
| `rate_control_mode` | ↕ Varies | ↕ Varies | ↓ VMAF slowest | `crf` | CRF=quality-based, VBR=bitrate-based, VMAF=quality-targeted |
| `vmaf_target` | ↑ Higher better | ↑ Higher larger | — | `95` | Target quality score (VMAF mode only) |
| `vmaf_samples` | ↑ More accurate | — | ↓ More slower | `4` | Sample count for CRF analysis (VMAF mode only) |

### Advanced Settings Impact

| Feature | Quality | Filesize | Speed | Default | Why |
|---------|---------|----------|-------|---------|-----|
| `scd` | ↑ On better | — | ↓ On 5-10% slower | `1` | Better keyframe placement |
| `aq_mode` | ↑ 2 best | — | ↓ 2 is 10-20% slower | `2` | DeltaQ best quality |
| `lookahead` | ↑ Higher better | — | ↓ Higher slower | `-1` | Auto is good compromise |
| `enable_tf` | ↑ On better | — | ↓ On 15-25% slower | `1` | Temporal filtering = smoother |
| `film_grain` | ↑ Natural look | ↓ Smaller | ↓ Slower | `0` | Only for grainy sources |
| `fast_decode` | — | ↑ Larger | ↑ Faster decode | `0` | Off = best compression |

### Bitrate Control

| Strategy | Description | Use Case |
|----------|-------------|----------|
| `static` | Use `custom_maxrate` or unlimited | Manual control |
| `match_source` | 100% of source bitrate | Matching original quality |
| `75%_source` | 75% of source bitrate | Good compression |
| `50%_source` | 50% of source bitrate | **Recommended** balance |
| `33%_source` | 33% of source bitrate | Aggressive compression |
| `25%_source` | 25% of source bitrate | Maximum compression |

### Rate Control Modes

| Mode | Description | File Size | Speed | Use Case |
|------|-------------|-----------|-------|----------|
| `crf` | Constant Rate Factor - quality-based encoding | Unpredictable | Fast | General use, quality priority |
| `vbr` | Variable Bitrate - target average with peak limits | Predictable | Fast | Bandwidth constraints, streaming |
| `vmaf` | Quality-targeted - ab-av1 auto CRF selection | Optimized | Slowest | Consistent quality across content |

**VMAF Mode Requirements:**
- Requires ab-av1 binary installed and accessible
- Set via `ABAV1_PATH` environment variable or install to `/usr/local/bin/ab-av1`
- Docker: Volume mount binary with `-v /path/to/ab-av1:/usr/local/bin/ab-av1`
- Falls back to CRF mode if binary not found

**VMAF Mode Settings:**
- `vmaf_target`: Quality target (85-99). 95 = visually transparent, 90 = good quality, 85 = acceptable
- `vmaf_samples`: Analysis segments (2-8). More = accurate but slower. 4 is recommended balance

### Resolution CRF Adjustment

| Output Resolution | CRF Adjustment | Reason |
|-------------------|----------------|--------|
| 4K (≥2160p) | +2 CRF | Less visible artifacts at high res |
| 1080p | Baseline | Reference resolution |
| 720p or lower | -2 CRF | More visible artifacts, needs quality |

### Container Selection

| Container | Pros | Cons |
|-----------|------|------|
| `mp4` | Universal compatibility | Limited subtitle support |
| `mkv` | All features supported | Some devices don't support |
| `webm` | Web-native | Audio must be Opus/Vorbis |
| `original` | No remux | May have incompatibilities |

---

## Default Values Rationale

### Why These Defaults?

**Codec Choices:**
- **Opus over AAC**: 20-30% better compression at same quality
- **AV1 over HEVC**: 30-50% better compression, royalty-free
- **10-bit over 8-bit**: Eliminates banding with minimal speed penalty

**Quality Settings:**
- **CRF 26**: Visually transparent for most content at 1080p
- **Preset 6**: 2-3x faster than preset 3, only ~5% larger files
- **Tune 0 (VQ)**: Optimized for human perception over PSNR metrics

**Efficiency Settings:**
- **SCD On**: Better seeking, cleaner scene transitions
- **AQ Mode 2**: Allocates bits where human eye is most sensitive
- **Temporal Filtering On**: Reduces noise, improves compression

**Safety Settings:**
- **Skip HEVC enabled**: HEVC is already efficient, may not benefit from AV1
- **Force transcode disabled**: Don't re-encode already-optimal files
- **Preserve metadata**: Keep language tags and titles

---

## Changelog (This Update)

### v2.1 - misc_fixes
- Added input validation function
- Standardized boolean inputs to string type with star markers
- Normalized boolean checks to `=== 'true'` pattern

### v4.2 - english_first_streams
- Fixed CCExtractor error handling (now continues if CC extraction fails)

### v1.11 - combined_audio_standardizer
- Fixed `create_downmix_6ch` → `create_6ch_downmix` typo
- Fixed double backslash in log strings

### v2.21 - av1_svt_converter
- Version bump for documentation consistency