# Tdarr Plugin Suite: Comprehensive Review & Outline

This document provides a full review of the modular plugin suite located in `@Local`. These plugins are designed with a **Single Responsibility Principle** to ensure stability, modularity, and ease of troubleshooting.

---

## 1. Pipeline Architecture

The suite is designed to be executed in a specific order to maximize efficiency (cheap operations first) and prevent logic conflicts.

1.  **[00] File Audit**: Read-only pre-check that logs file info and flags potential issues.
2.  **[01] Container Remux**: Standardizes container and fixes hardware-level timestamp issues.
3.  **[02] Stream Cleanup**: Purges bloat and incompatible streams.
4.  **[03] Stream Ordering**: Organizes tracks for better compatibility and user experience.
5.  **[04] Subtitle Conversion**: Standardizes all embedded text subtitles to SRT.
6.  **[05] Subtitle Extraction**: Handles external file creation for subtitles.
7.  **[06] CC Extraction**: Specialized handling for Closed Captions via CCExtractor.
8.  **[07] Audio Standardizer**: High-quality audio normalization and downmixing.
9.  **[08] AV1 Converter**: Intensive video transcoding (Final Step).

---

## 2. Plugin Breakdown

### [00] File Audit
**Logic**: Read-only audit plugin that runs first. Analyzes file structure and logs comprehensive information including all streams, codecs, and potential issues. Never modifies files.
- **Type**: Filter (pass-through)
- **Checks Performed**:
    - Container format and timestamp issues (TS/AVI/MPG/etc.)
    - Legacy video codecs (MPEG-4, XviD/DivX, WMV, RealVideo)
    - XviD/DivX packed bitstream detection
    - Corrupt audio streams (0 channels)
    - Container-incompatible subtitle codecs
    - HDR/color space metadata
    - Interlaced content detection
    - Cover art/image streams
    - Problematic data streams
- **Default Settings**:
    - `log_level`: `detailed` (minimal=issues only, verbose=all metadata)
- **Output Tags**: Issues tagged `[MKV only]`, `[MP4 only]`, or `[BOTH]` for container-specific guidance

### [01] Container Remux
**Logic**: Remuxes the file to a target container (MKV/MP4) without changing codecs. It specifically targets "broken" formats like TS/AVI to fix timestamps before any other processing occurs.
- **Subfunctions**:
    - `stripStar`: Utility to clean UI-selected default markers.
- **Default Settings**:
    - `target_container`: `mkv` (**Authoritative** - all subsequent plugins inherit this)
    - `fix_ts_timestamps`: `true` (Applies `-fflags +genpts+igndts -avoid_negative_ts make_zero -copyts`)
    - `ts_audio_recovery`: `false` (Transcodes corrupt TS audio to AAC)

### [02] Stream Cleanup
**Logic**: Evaluates every stream against the current container's capabilities (auto-detected from file). It removes image streams (cover art), corrupt audio (0 channels), and data streams that cause muxing errors.
- **Container**: Inherited from input file (set by Plugin 01)
- **Subfunctions**:
    - `stripStar`: Utility to clean UI-selected default markers.
- **Default Settings**:
    - `remove_image_streams`: `true` (Removes MJPEG/PNG/GIF)
    - `force_conform`: `true` (Removes codecs like `mov_text` from MKV or `PGS` from MP4)
    - `remove_corrupt_audio`: `true` (Removes 0-channel/unknown audio)
    - `remove_data_streams`: `true` (Removes `bin_data`/`timed_id3`)

### [03] Stream Ordering
**Logic**: Reorganizes the internal stream index. Ensures Video is first, followed by Audio, then Subtitles. Within Audio/Subtitles, it prioritizes a list of language codes.
- **Subfunctions**:
    - `validateLanguageCodes`: Validates and sanitizes the CSV input.
    - `isPriorityLanguage`: Checks if a stream matches the priority list.
    - `partitionStreams`: Splits streams into priority and non-priority groups.
- **Default Settings**:
    - `ensure_video_first`: `true`
    - `reorder_audio`: `true`
    - `reorder_subtitles`: `true`
    - `priority_languages`: `eng,en,english,en-us,en-gb,en-ca,en-au`
    - `set_default_flags`: `false` (Set disposition to 'default' for top priority tracks)

### [04] Subtitle Conversion
**Logic**: **Container-aware** subtitle conversion. Converts text-based subtitles to the appropriate format for the current container (inherited from Plugin 01).
- **Container Behavior**:
    - MKV → Converts to SRT (universal text format)
    - MP4 → Converts to mov_text (native MP4 format)
- **Converts**: ASS/SSA, WebVTT, mov_text, SRT (cross-converts as needed)
- **Image subs** (PGS/VobSub): Copied as-is (cannot convert to text)
- **Default Settings**:
    - `enable_conversion`: `true`
    - `always_convert_webvtt`: `true` (WebVTT is problematic in most containers)

### [05] Subtitle Extraction
**Logic**: Extracts embedded SRT-compatible subtitles to external `.srt` files. It includes robust logic to detect if it's already in a Tdarr cache cycle to prevent infinite "Extract -> Re-queue -> Extract" loops.
- **Subfunctions**:
    - `sanitizeFilename`: Cleans language tags and titles for filesystem safety.
    - `sanitizeForShell`: Prevents shell injection in extraction commands.
    - `fileExistsValid`: Checks if an extracted file already exists and has data.
- **Default Settings**:
    - `extract_subtitles`: `true`
    - `remove_after_extract`: `false`
    - `skip_commentary`: `true`
    - `extract_languages`: `""` (Extracts all)

### [06] CC Extraction
**Logic**: Uses the `CCExtractor` binary to pull EIA-608/708 captions. It uses a `.lock` file system to prevent multiple workers from trying to extract the same CC stream simultaneously.
- **Subfunctions**:
    - `hasClosedCaptions`: Checks for specific CC codec tags.
    - `sanitizeForShell`: Prevents shell injection.
- **Default Settings**:
    - `extract_cc`: `false`
    - `embed_extracted_cc`: `false`

### [07] Audio Standardizer
**Logic**: Sophisticated audio engine. It handles codec conversion (AAC/Opus), bitrate calculation (automatic per-channel limits), and multi-channel downmixing (7.1 -> 5.1 -> 2.0).
- **Subfunctions**:
    - `calculateBitrate`: Smart logic to ensure quality while keeping files small.
    - `applyQualityPreset`: Provides `high_quality`, `balanced`, and `small_size` presets.
    - `buildDownmixArgs`: Generates specific FFmpeg maps for new downmixed tracks.
    - `isOpusIncompatibleLayout`: Handles Opus layout corner cases.
- **Default Settings**:
    - `codec`: `opus`
    - `skip_if_compatible`: `true`
    - `bitrate_per_channel`: `auto` (Min 64kbps/ch)
    - `channel_mode`: `preserve`
    - `create_downmix`: `true` (Creates stereo if missing)
    - `quality_preset`: `custom`

### [08] AV1 Converter (SVT-AV1)
**Logic**: Optimized for SVT-AV1 v3.0+. It features resolution-tailored CRF (auto-adjusts quality based on 4K vs 1080p), HDR metadata preservation, and intelligent tiling for parallel encoding.
- **Container**: Defaults to `original` (inherits from Plugin 01)
- **Subfunctions**:
    - `stripStar`: Utility to clean UI-selected default markers.
- **Default Settings**:
    - `crf`: `26`
    - `preset`: `6` (Balanced)
    - `rate_control_mode`: `crf`
    - `input_depth`: `10` (Prevents banding)
    - `resolution_crf_adjust`: `enabled` (+2 for 4K, -2 for 720p)
    - `skip_hevc`: `enabled`
    - `container`: `original` (inherits from input file)

---

## 3. Summary of Default Settings (*)

Items marked with `*` in the UI are the "Golden Defaults" for this stack:

| Plugin | Key Settings |
| :--- | :--- |
| **00 Audit** | log_level: `detailed*` (checks both MKV+MP4) |
| **01 Remux** | target: `mkv` (**authoritative**), fix_ts: `true*` |
| **02 Cleanup** | remove_image: `true*`, force_conform: `true*`, remove_corrupt: `true*` (container inherited) |
| **03 Ordering** | video_first: `true*`, reorder_audio/sub: `true*` |
| **04 Sub Conv** | enable: `true*`, convert_webvtt: `true*` (container-aware: MKV→SRT, MP4→mov_text) |
| **05 Sub Ext** | extract: `true*`, skip_commentary: `true*` |
| **06 CC Ext** | extract: `false`, embed: `false` |
| **07 Audio** | codec: `opus*`, skip_compatible: `true*`, create_downmix: `true*` |
| **08 AV1** | crf: `26*`, preset: `6*`, mode: `crf*`, res_adjust: `enabled*`, container: `original*` |