tdarr-plugs/agent_notes/plugin_organization_plan.md

Tdarr Plugin Organization Strategy

Overview

Organize plugins into 4 logical categories based on their primary function, creating a clear processing pipeline.

Plugin Categories

1. Misc Fixes (First in Flow)

File: Tdarr_Plugin_misc_fixes.js
Purpose: Handle edge cases and format-specific issues that prevent normal processing

Current Fixes:

• TS/MPEGTS timestamp issues (-fflags +genpts+igndts)
• BMP attached picture exclusion (integrated into English First)

Future Additions:

• VOB subtitle fixes
• Corrupt metadata repair
• Unusual codec/container combinations
• Frame rate detection issues
• Aspect ratio corrections
• DTS-MA audio compatibility

Design Philosophy:

• Runs first to normalize problematic files
• Should be lightweight - only process when issues detected
• Each fix should have a clear detection method
• Log which specific fix was applied

---

2. Order/Subtitle Standardizer (Second)

File: Tdarr_Plugin_english_first_streams.js
Purpose: Stream reordering and subtitle format standardization

Responsibilities:

• Reorder audio streams (English first)
• Reorder subtitle streams (English first)
• Convert subtitles to SRT format
• Extract subtitles to external files
• Remove commentary/description tracks
• Set default disposition flags
• Handle closed captions

Why Second:

• Needs clean streams from Misc Fixes
• Must run before audio/video processing
• Doesn't modify audio/video codecs

---

3. Audio Standardizer (Third)

File: Tdarr_Plugin_combined_audio_standardizer.js
Purpose: Audio codec and channel standardization

Responsibilities:

• Convert to AAC or Opus
• Handle channel modes (preserve/stereo/mono)
• Create downmix tracks (2ch, 6ch)
• Apply quality presets
• Bitrate management
• Sample rate conversion
• Metadata preservation

Why Third:

• Stream order is already correct
• Can work independently of video processing
• Faster than video encoding

---

4. Video Standardizer (Last)

File: Tdarr_Plugin_av1_svt_converter.js
Purpose: Video codec standardization and optimization

Responsibilities:

• Convert to AV1 (SVT-AV1)
• Resolution/scaling
• Bitrate control strategies
• HDR preservation
• Container selection
• Quality presets (CRF)

Why Last:

• Most resource-intensive
• Benefits from clean audio/subtitle streams
• Final output format

---

Recommended Flow Order

1. Misc Fixes          → Fix edge cases
   ↓
2. Order/Subtitle      → Organize streams, standardize subs
   ↓
3. Audio Standardizer  → Convert audio codecs
   ↓
4. Video Standardizer  → Convert video codec (most intensive)

Optimization Logic

1. Stream Index Stability

Problem: Plugins like Order/Subtitle change the number and order of streams. Optimization:

• Run Reordering Early: By placing Order/Subtitle second (after fixing edge cases), we establish a stable stream layout early.
• Subsequent Reliability: The Audio and Video plugins can rely on the stream indices established by the order plugin, or reliably find streams by language/codec without fighting against shifting indices.
• Avoid Rescanning: Running reordering first prevents downstream plugins from processing streams that might be deleted or moved later.

2. Processing Cost Hierarchy

Strategy: Execute plugins from Lowest Cost to Highest Cost.

• Misc Fixes: (Fastest) Remux only.
• Order/Subtitle: (Fast) Remux only.
• Audio: (Medium) CPU audio encoding.
• Video: (Slowest) Heavy CPU/GPU video encoding.
• Why: If a file fails at the "Misc Fixes" or "Order" stage, we fail fast before wasting hours of CPU time on video encoding.

3. I/O Optimization

Problem: Multiple plugins = multiple file reads/writes. Optimization:

• Tdarr executes plugins sequentially. Each plugin reads source -> processes -> writes temp file.
• Consolidation Potential: In the future, combining Audio and Video into a single valid FFmpeg command could save one I/O cycle, but keeping them separate offers modularity.
• Current Flow: The proposed 4-step flow is the best compromise between modularity and efficiency.

Benefits of This Organization

✅ Clear Separation of Concerns

Each plugin has a single, well-defined purpose

✅ Optimal Processing Order

Fixes flow from least to most intensive

✅ Easier Maintenance

Know exactly where to add new features

✅ Better Error Handling

Issues caught early in the pipeline

✅ Modular Design

Can enable/disable categories independently

---

File Naming Convention

Pattern: Tdarr_Plugin_<category>_<specifics>.js

Examples:

• Tdarr_Plugin_misc_fixes.js
• Tdarr_Plugin_english_first_streams.js → Consider renaming to Tdarr_Plugin_order_subtitle_standardizer.js
• Tdarr_Plugin_combined_audio_standardizer.js → Already good
• Tdarr_Plugin_av1_svt_converter.js → Consider renaming to Tdarr_Plugin_video_standardizer_av1.js

---

Future Enhancements

Misc Fixes Candidates

• AVI index repair: -fflags +genpts for broken AVI files
• M2TS handling: Special flags for Blu-ray sources
• MKV attachment limits: Handle files with too many attachments
• Null audio handling: Detect and fix silent audio streams
• Interlace detection: Auto-deinterlace when needed

Smart Detection

Add input option to enable/disable specific fixes:

Inputs: [
  {
    name: 'fix_ts_timestamps',
    defaultValue: 'true*',
    tooltip: 'Fix timestamp issues in TS files'
  },
  {
    name: 'fix_broken_index',
    defaultValue: 'true*',
    tooltip: 'Repair broken file indexes'
  }
]

Metrics & Reporting

Each plugin logs which category it belongs to:

ℹ️ [Misc Fixes] Applied TS timestamp fix
✅ [Order/Subtitle] Reordered 2 English audio streams
✅ [Audio Standardizer] Converted to AAC @ 128kbps
✅ [Video Standardizer] Encoded to AV1 (CRF 28)

---

Implementation Notes

Not to be implemented immediately - this is a strategic plan for future organization.

When implementing:

1. Start with Misc Fixes expansion (add more edge cases)
2. Consider renaming English First plugin for clarity
3. Create unified logging format across all plugins
4. Document plugin load order in README
5. Create example Tdarr flows for common use cases