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

# 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:

# 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:

   from engines.processors.cosyvoice_processor import CosyVoiceProcessor
   

   To file-based import:

   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).