diodiogod-TTS-Audio-Suite/docs/Dev reports/REFACTORING_PLAN.md

# TTS Audio Suite Refactoring Plan - Complete Implementation Document

## Original Vision

Transform "ChatterBox Voice" into "TTS Audio Suite" - a universal multi-engine TTS extension for ComfyUI with unified architecture supporting ChatterBox, F5-TTS, and future engines like RVC.

## Core Problem Addressed

The original extension had separate nodes for each engine (ChatterBox TTS, F5-TTS, ChatterBox SRT, F5-TTS SRT, etc.), making the interface cluttered and making it difficult to add new engines without creating even more separate nodes.

## Solution: Unified Architecture with Engine Delegation

Create a modular system where:
1. **Engine nodes** provide engine-specific configuration  
2. **Unified nodes** work with any engine through delegation
3. **Character management** is centralized and engine-agnostic

## Implementation Strategy: Smart Delegation Pattern

**Key Decision**: Instead of rewriting all functionality, preserve existing tested code and create unified nodes that delegate to original implementations based on selected engine.

**Benefits**:
- Zero functionality loss
- All existing features preserved (SRT timing, crash protection, caching, etc.)
- Clean user interface
- Future-ready architecture

## Architecture Overview

### New Node Structure

```
TTS Audio Suite/
├── 🎤 TTS Text              # Main generation (replaces 2 engine-specific nodes)
├── 📺 TTS SRT               # SRT timing (replaces 2 engine-specific nodes) 
├── 🔄 Voice Changer         # Voice conversion (engine-agnostic)

TTS Audio Suite/Engines/
├── ⚙️ ChatterBox TTS Engine # ChatterBox configuration
└── ⚙️ F5 TTS Engine         # F5-TTS configuration

TTS Audio Suite/Tools/
├── 🎭 Character Voices      # Voice reference management
├── 🎙️ Voice Capture         # Audio recording
├── 🌊 Audio Wave Analyzer   # Audio analysis
└── 👄 F5-TTS Speech Editor  # Specialized F5 editing
```

## Detailed Implementation

### Phase 1: Project Transformation ✅
- **Renamed**: "ChatterBox Voice" → "TTS Audio Suite v4.0.0"
- **Updated metadata**: pyproject.toml, README.md, CLAUDE.md
- **Created new directory structure**: `nodes/engines/`, `nodes/unified/`, `nodes/shared/`

### Phase 2: Engine Nodes ✅

#### ChatterBox TTS Engine Node
- **Location**: `nodes/engines/chatterbox_engine_node.py`
- **Parameters**: language, device, exaggeration, temperature, cfg_weight
- **Output**: Engine adapter configuration
- **Function**: Provides ChatterBox-specific settings to unified nodes

#### F5 TTS Engine Node  
- **Location**: `nodes/engines/f5tts_engine_node.py`
- **Parameters**: language (model), device, temperature, speed, target_rms, cross_fade_duration, nfe_step, cfg_strength
- **Output**: Engine adapter configuration
- **Function**: Provides F5-TTS-specific settings to unified nodes

### Phase 3: Support Infrastructure ✅

#### Character Voices Node
- **Location**: `nodes/shared/character_voices_node.py`
- **Purpose**: Centralized voice reference management
- **Features**:
  - Voice folder selection
  - Reference text input (for F5-TTS)
  - Audio upload capability
  - Flexible output (audio-only for ChatterBox, audio+text for F5-TTS)
- **Replaces**: Individual `opt_reference_text` widgets scattered across nodes

### Phase 4: Unified Nodes ✅

#### TTS Text Node (Unified)
- **Location**: `nodes/unified/tts_text_node.py`  
- **Replaces**: ChatterBox TTS + F5-TTS text nodes
- **Architecture**: Delegation wrapper that:
  1. Receives engine configuration from engine nodes
  2. Creates instance of original engine-specific node
  3. Delegates generation to original tested code
  4. Returns unified results

#### TTS SRT Node (Unified)
- **Location**: `nodes/unified/tts_srt_node.py`
- **Replaces**: ChatterBox SRT + F5-TTS SRT nodes  
- **Preserves**: All complex SRT functionality:
  - Multiple timing modes (stretch_to_fit, pad_with_silence, smart_natural, concatenate)
  - Overlap detection and handling
  - Timing reports and adjusted SRT output
  - Smart language grouping
  - Character switching integration

#### Voice Changer Node (Unified)
- **Location**: `nodes/unified/voice_changer_node.py`
- **Replaces**: ChatterBox VC node
- **Future-ready**: Prepared for RVC engine support
- **Current**: Delegates to original ChatterBox VC code

### Phase 5: System Integration ✅

#### Updated Main Registration
- **File**: `nodes.py`
- **Changes**:
  - Registers only new unified nodes (old nodes hidden from users)
  - Clean startup messages with node list
  - Proper error handling and diagnostics
  - Legacy support for existing voice/model discovery

#### Updated Extension Entry Point  
- **File**: `__init__.py`
- **Changes**: Simplified to import node mappings from `nodes.py`
- **Result**: Clean delegation of all node management to main system

## User Experience Transformation

### Before Refactor
- 8+ separate engine-specific nodes
- Confusing interface with duplicate functionality
- Difficult to add new engines (would create more nodes)

### After Refactor
- 6 main nodes (3 generation + 2 engines + 1 voice management)
- Clean, intuitive workflow
- Easy to add new engines (just one new engine node)

### Workflow Example
1. **Setup**: Connect ChatterBox Engine or F5 Engine node
2. **Voice**: Optionally connect Character Voices for voice reference
3. **Generate**: Use TTS Text or TTS SRT with any engine
4. **Convert**: Use Voice Changer for voice conversion (ChatterBox only, RVC coming)

## Technical Implementation Details

### Engine Connection Pattern
- **Data Flow**: Engine Node → `TTS_engine` connection → Unified Node
- **Contents**: Engine type + configuration dictionary  
- **Processing**: Unified node creates original engine node instance with config
- **Execution**: Delegates to original tested generation code

### Delegation Implementation
```python
# In unified nodes
def generate_speech(self, TTS_engine, ...):
    engine_type = TTS_engine.get("engine_type") 
    config = TTS_engine.get("config", {})
    
    # Create original node instance
    if engine_type == "chatterbox":
        engine_instance = ChatterboxTTSNode()
        result = engine_instance.generate_speech(
            # Map unified parameters to original parameters
        )
    elif engine_type == "f5tts":
        engine_instance = F5TTSNode() 
        result = engine_instance.generate_speech(
            # Map unified parameters to original parameters
        )
    
    return result  # All original functionality preserved
```

### Voice Reference System
- **Priority**: Character Voices input > voice dropdown selection
- **Flexibility**: Supports both audio-only (ChatterBox) and audio+text (F5-TTS)
- **Centralization**: Single place to manage all voice references

## Future Engine Integration

### Adding RVC (or any new engine)
1. **Create Engine Node**: `nodes/engines/rvc_engine_node.py`
2. **Update Unified Nodes**: Add RVC delegation cases  
3. **Done**: All existing workflows work with new engine

### No Breaking Changes
- Existing workflows continue working
- Original functionality preserved
- Clean upgrade path for users

## Results Achieved

### ✅ Architecture Goals Met
- Unified interface reducing 8+ nodes to 6 main nodes
- Engine-agnostic design ready for RVC and future engines
- Zero functionality loss through smart delegation
- Clean separation of concerns

### ✅ User Experience Improved  
- Intuitive workflow (Engine → Voice → Generate)
- Reduced complexity and confusion
- Future-proof design
- Maintains all advanced features

### ✅ Developer Benefits
- Easy to add new engines
- Preserves existing tested code  
- Modular, maintainable architecture
- Clear upgrade path

## Conclusion

The refactoring successfully transformed a collection of engine-specific nodes into a unified, extensible architecture while preserving all existing functionality. The smart delegation pattern ensures zero feature loss while providing a clean foundation for future engine integrations.

**Next Steps**: Test thoroughly, add RVC engine support, and potentially submit to ComfyUI Manager as the new universal TTS solution.

---

## Future Refactoring Tasks

### Architecture Inconsistency: Processor Location

**Issue Identified**: 2025-01-28

CosyVoice and IndexTTS have TTS processors in a different location than all other engines, causing inconsistent import patterns and architecture confusion.

**Current State:**

**Standard Pattern (9 engines):**
- TTS processor location: `nodes/engine_name/engine_processor.py`
- Import pattern: File-based import using `importlib.util.spec_from_file_location()`
- Examples:
  - `nodes/qwen3_tts/qwen3_tts_processor.py`
  - `nodes/step_audio_editx/step_audio_editx_processor.py`
  - `nodes/vibevoice/vibevoice_processor.py`
  - `nodes/higgs_audio/higgs_audio_tts_processor.py`
  - `nodes/chatterbox_official_23lang/chatterbox_official_23lang_processor.py`

**Inconsistent Pattern (2 engines):**
- TTS processor location: `engines/processors/`
- Import pattern: Package import (`from engines.processors import`)
- Examples:
  - `engines/processors/cosyvoice_processor.py`
  - `engines/processors/index_tts_processor.py`

**Why This Is a Problem:**

1. **Confusing Architecture**: Why are some TTS processors in `engines/processors/` and some in `nodes/engine_name/`?
2. **Inconsistent Import Patterns**: Some use package imports, some use file-based imports
3. **Documentation Mismatch**: The implementation guide assumes processors are in `nodes/`
4. **Harder to Maintain**: New developers don't know which pattern to follow
5. **Breaks Conventions**: All other engines follow the standard pattern

**Proposed Fix:**

Move TTS processors to match the standard architecture:

```bash
# Move CosyVoice processor
engines/processors/cosyvoice_processor.py → nodes/cosyvoice/cosyvoice_processor.py

# Move IndexTTS processor
engines/processors/index_tts_processor.py → nodes/index_tts/index_tts_processor.py
```

**Files to Update:**

1. **Move processor files** to `nodes/engine_name/`

2. **Update imports in SRT processors:**
   - `nodes/cosyvoice/cosyvoice_srt_processor.py` line 34
   - `nodes/index_tts/index_tts_srt_processor.py` (if exists)

   Change from:
   ```python
   from engines.processors.cosyvoice_processor import CosyVoiceProcessor
   ```

   To file-based import:
   ```python
   import importlib.util
   processor_path = os.path.join(current_dir, "cosyvoice_processor.py")
   processor_spec = importlib.util.spec_from_file_location("cosyvoice_processor_module", processor_path)
   processor_module = importlib.util.module_from_spec(processor_spec)
   processor_spec.loader.exec_module(processor_module)
   CosyVoiceProcessor = processor_module.CosyVoiceProcessor
   ```

3. **Update any other imports** that reference `engines.processors.cosyvoice_processor` or `engines.processors.index_tts_processor`

4. **Update PROJECT_INDEX.md** to reflect new locations

5. **Test thoroughly** to ensure no import breakage

**Priority**: Medium - Not breaking functionality, but important for maintainability and consistency

**Estimated Effort**: 1-2 hours (move files, update imports, test)

**Benefits:**
- Consistent architecture across all engines
- Easier to understand and maintain
- Matches documentation and implementation guide
- Clearer separation of concerns (engines/ = low-level, nodes/ = high-level orchestration)

**Note**: The `engines/processors/` directory can be removed after this refactoring, or kept for future use if there's a valid architectural reason (currently unclear).