# Stream Organizer Refactoring Plan

## Current State Analysis

**File:** `Tdarr_Plugin_stream_organizer.js` (v4.8)
**Total Lines:** 777
**Main Function Lines:** ~500 (lines 251-772)

### Problems Identified
1. **Monolithic Function:** The `plugin` function handles too many responsibilities
2. **Deep Nesting:** Multiple levels of conditionals and loops
3. **Difficult Testing:** Cannot test sub-components in isolation
4. **Hard to Maintain:** Changes require understanding entire 500-line function

## Refactoring Strategy

### Phase 1: Extract Stream Analysis Logic
**New Functions:**
- `analyzeStreams(file)` → Returns categorized streams (video, audio, subtitle, other)
- `reorderStreamsByLanguage(streams, languageCodes, includeAudio, includeSubtitles)` → Returns reordered streams
- `detectConversionNeeds(subtitleStreams, inputs)` → Returns conversion analysis

### Phase 2: Extract Subtitle Processing
**New Functions:**
- `processSubtitleExtraction(subtitleStreams, inputs, otherArguments, fs, path)` → Returns extraction command + metadata
- `processCCExtraction(subtitleStreams, inputs, otherArguments, fs)` → Returns CC extraction plan
- `buildSubtitleMapping(reorderedStreams, inputs, customEnglishCodes)` → Returns subtitle map commands

### Phase 3: Extract FFmpeg Command Building
**New Functions:**
- `buildFFmpegCommand(analysis, inputs)` → Main orchestrator
- `buildBaseMapping(reorderedStreams, inputs)` → Returns base -map commands
- `buildCodecArgs(includedSubtitles, inputs)` → Returns codec arguments
- `buildDispositionArgs(audioIdx, subIdx)` → Returns default flag arguments

### Phase 4: Simplify Main Plugin Function
**New Structure:**
```javascript
const plugin = (file, librarySettings, inputs, otherArguments) => {
  const { lib, fs, path } = initDependencies();
  const response = initResponse(file);
  
  try {
    inputs = validateAndSanitizeInputs(inputs, lib, details);
    
    const analysis = analyzeStreams(file, inputs, otherArguments, fs, path);
    
    if (!needsProcessing(analysis)) {
      return skipResponse(analysis.message);
    }
    
    const command = buildFFmpegCommand(analysis, inputs);
    
    return buildSuccessResponse(command, analysis, inputs);
  } catch (error) {
    return buildErrorResponse(error, file);
  }
};
```

## Implementation Checklist

- [ ] Create helper module structure at top of file
- [ ] Extract `analyzeStreams()` family
- [ ] Extract subtitle processing functions
- [ ] Extract FFmpeg command builders
- [ ] Refactor main `plugin()` function
- [ ] Test equivalence (commands should be identical)
- [ ] Update version to 4.9
- [ ] Add inline documentation

## Benefits

1. **Testability:** Each function can be unit tested
2. **Readability:** Functions have clear, single purposes
3. **Maintainability:** Changes are localized to specific functions
4. **Debuggability:** Stack traces show which component failed
5. **Reusability:** Logic can be shared/adapted for other plugins

## Risk Mitigation

- **No Behavior Changes:** All existing logic preserved exactly
- **Incremental Approach:** Refactor in phases, test after each
- **Version Bump:** Clear signal this is a refactored version
- **Git History:** Commit shows before/after for rollback

## Next Steps

1. Create backup/branch point
2. Begin Phase 1: Stream analysis extraction
3. Validate output equivalence with test files
4. Continue with subsequent phases