sapient/tdarr-plugs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
tdarr-plugs/PLUGIN_REVIEW_AND_OUTLINE.md
Tdarr Plugin Developer ddc9d09c41 docs: Add historical reports and consolidated archives
2026-01-30 05:55:22 -08:00

8.0 KiB
Raw Permalink Blame History

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*
Reference in New Issue View Git Blame Copy Permalink