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:
```javascript
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