153 lines
8.0 KiB
Markdown
153 lines
8.0 KiB
Markdown
# 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*` |
|