ComfyUI VoxCPMTTS Node

A clean, efficient ComfyUI custom node for VoxCPMTTS (Text-to-Speech) functionality. This implementation provides high-quality speech generation and voice cloning capabilities using the VoxCPM model.

Features

• 🎯 High-Quality TTS: Generate natural-sounding speech from text
• 🎭 Voice Cloning: Clone any voice using a reference audio sample
• 🔄 Auto-Transcription: Automatic speech recognition for reference audio
• ⚡ Multi-Device Support: CUDA, MPS, and CPU compatibility
• 🎛️ Fine-Tuned Control: Adjustable guidance scale, inference steps, and more
• 🔊 Audio Post-Processing: Built-in fade-in to reduce artifacts

Installation

Method 1: ComfyUI Manager (Recommended)

1. Open ComfyUI Manager
2. Search for "VoxCPMTTS"
3. Install the node

Method 2: Manual Installation

1. Navigate to your ComfyUI custom nodes directory:

cd ComfyUI/custom_nodes/

2. Clone this repository:

git clone https://github.com/1038lab/ComfyUI-VoxCPMTTS.git

3. Install dependencies:

cd ComfyUI-VoxCPMTTS
pip install -r requirements.txt

4. Restart ComfyUI

Dependencies

The node will automatically install required dependencies on first use:

• huggingface_hub>=0.20.0
• einops>=0.6.0
• pydantic>=2.0.0
• wetext>=0.1.0
• openai-whisper>=20231117

Optional dependencies for enhanced functionality:

• faster-whisper (preferred for ASR)
• openai-whisper (fallback for ASR)

Model Download

The VoxCPM-0.5B model (~1.2GB) will be automatically downloaded to ComfyUI/models/TTS/VoxCPM-0.5B/ on first use. https://huggingface.co/openbmb/VoxCPM-0.5B

Usage

Text-to-Speech

1. Add the VoxCPMTTS node to your workflow
2. Input your text in the text field
3. Adjust parameters as needed:
   • cfg_value: Controls adherence to prompt (1.0-10.0, default: 2.0)
   • inference_steps: Quality vs speed tradeoff (1-100, default: 10)
   • max_length: Maximum token length (256-8192, default: 4096)
4. Connect the audio output to your desired destination

Voice Cloning

1. Connect a reference audio to the reference_audio input
2. Optionally provide reference_text (transcript of the reference audio)
   • If left empty, the node will automatically transcribe the audio
3. The generated speech will mimic the reference voice characteristics

Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | text | STRING | "Hello, this is VoxCPMTTS." | Text to synthesize | | cfg_value | FLOAT | 2.0 | Guidance scale (higher = more prompt adherence) | | inference_steps | INT | 10 | Diffusion steps (higher = better quality) | | max_length | INT | 4096 | Maximum token length | | normalize | BOOLEAN | True | Enable text normalization | | seed | INT | -1 | Random seed (-1 for random) | | device | COMBO | auto | Device selection (auto/cuda/mps/cpu) | | reference_audio | AUDIO | - | Reference audio for voice cloning | | reference_text | STRING | "" | Reference audio transcript | | fade_in_ms | INT | 20 | Fade-in duration (0-1000ms) |

Outputs

• REFERENCE_TEXT: Transcribed or provided reference text
• AUDIO: Generated speech audio with 16kHz sample rate

Environment Variables

Set these environment variables to customize behavior:

# ASR model size (tiny, small, medium, large)
export VOXCPM_ASR_MODEL=small

# Maximum retry attempts for bad cases
export VOXCPM_RETRY_MAX=2

Device Selection

• auto: Automatically selects the best available device
• cuda: Force CUDA if available
• mps: Force MPS (Apple Silicon) if available
• cpu: Force CPU processing

Example Workflows

Basic TTS Workflow

[Text Input] → [VoxCPMTTS] → [Audio Output]

Voice Cloning Workflow

[Reference Audio] → [VoxCPMTTS] ← [Target Text]
                         ↓
                   [Cloned Audio]

Batch Processing Workflow

[Text List] → [VoxCPMTTS] → [Audio Batch] → [Save Audio]

Performance Tips

Memory Optimization

• Use lower inference_steps for faster generation
• Choose appropriate max_length for your text
• Use CPU device if GPU memory is limited

Quality Settings

• Fast: cfg_value=1.5, inference_steps=5
• Balanced: cfg_value=2.0, inference_steps=10 (default)
• High Quality: cfg_value=3.0, inference_steps=20

Voice Cloning Tips

• Use high-quality reference audio (16kHz+)
• Reference audio should be 3-30 seconds long
• Clear speech with minimal background noise works best
• Provide accurate reference text when possible

Troubleshooting

Common Issues

Model download fails

• Check internet connection
• Ensure sufficient disk space (~1.2GB)
• Try clearing the download cache

Out of memory errors

• Reduce max_length
• Lower inference_steps
• Switch to CPU device
• Close other GPU-intensive applications

Poor voice cloning quality

• Ensure reference audio is clear and high-quality
• Verify reference text accuracy
• Try different cfg_value settings
• Use reference audio from the same speaker

ASR transcription errors

• Install faster-whisper for better performance
• Provide manual reference_text instead
• Use clearer reference audio

Debug Mode

Enable verbose logging by setting:

export COMFYUI_LOG_LEVEL=DEBUG

Model Information

This node uses the VoxCPM-0.5B model developed by OpenBMB:

• Model Size: ~500M parameters
• Audio Quality: 16kHz sample rate
• Languages: Primarily optimized for English and Chinese
• License: Apache 2.0
• Paper: VoxCPM: A High-Quality Chinese Text-to-Speech Model

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Acknowledgments

• OpenBMB for the VoxCPM model
• ComfyUI community
• All contributors and users

Support

If you encounter any issues or have questions:

• Open an issue on GitHub
• Check the troubleshooting section above
• Join the ComfyUI community discussions

---

Star this repository if you find it useful! ⭐