nodes/diodiogod-TTS-Audio-Suite
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
da223f49f7e07ef2a94de0d4b075a9d5b049cf20
diodiogod-TTS-Audio-Suite/docs/Dev reports/REFACTORING_PLAN.md
T

8.2 KiB
Raw Blame History

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.

Reference in New Issue View Git Blame Copy Permalink