ComfyUI-ChatterBox-Turbo

ComfyUI-ChatterBox-Turbo

ComfyUI custom nodes for ChatterBox Turbo — a fast 350M-parameter text-to-speech model with paralinguistic emotion tag support by Resemble AI.

Features

• Fast generation — 1-step mel decoder, significantly faster than the original ChatterBox
• 19 emotion/paralinguistic tags — [dramatic], [sarcastic], [happy], [whispering], and more
• Voice cloning — pass a short WAV reference to clone any voice
• Multi-speaker dialogue — generate full conversations with automatic voice switching
• Auto model download — model weights download automatically from HuggingFace on first use

Nodes

ChatterBox Turbo TTS (ChatterboxTurboGenerate)

Single text-to-speech generation. Good for experimentation and manual workflows.

| Input | Type | Default | Notes | |-------|------|---------|-------| | text | STRING (multiline) | required | Supports emotion tags: [dramatic] Breaking news! | | audio_prompt_path | STRING | "" | Path to voice reference WAV inside the container | | reference_audio | AUDIO (optional) | — | Alternative: connect audio from another node | | temperature | FLOAT | 0.8 | 0.05–5.0 | | top_p | FLOAT | 0.95 | 0.0–1.0 | | repetition_penalty | FLOAT | 1.2 | 1.0–2.0 | | seed | INT | 0 | 0 = random |

Output: AUDIO (24 kHz)

ChatterBox Turbo Dialogue (ChatterboxTurboDialogue)

Multi-speaker dialogue generation. Designed for pipeline integration and batch scripts.

| Input | Type | Default | Notes | |-------|------|---------|-------| | script | STRING (multiline) | required | One Speaker: text per line | | voice_map | STRING | "{}" | JSON mapping speaker names to WAV paths | | pause_s | FLOAT | 0.35 | Pause between lines (seconds) | | temperature | FLOAT | 0.8 | | | top_p | FLOAT | 0.95 | | | repetition_penalty | FLOAT | 1.2 | | | seed | INT | 0 | |

Outputs: AUDIO (concatenated dialogue), STRING (generation info)

Script format:

Mac: [dramatic] Breaking news everyone!
Luna: [surprised] That's right Mac, incredible!
Mac: [sarcastic] Can you believe it?

Voice map example:

{
  "Mac": "/path/to/Mac.wav",
  "Luna": "/path/to/Luna.wav"
}

Emotion & Paralinguistic Tags

ChatterBox Turbo supports 19 special tokens trained into the model as added_tokens on top of the GPT-2 vocabulary (token IDs 50257–50275). The full list is defined in added_tokens.json in the model repo. The upstream ChatterBox README mentions [cough], [laugh], [chuckle] as examples — the complete set of 19 is listed below.

Place a tag at the start of a line to set the delivery style for that line.

Emotion Tags (affect the entire delivery)

| Tag | Best for | Example | |-----|----------|---------| | [dramatic] | Breaking news, reveals, cliffhangers | [dramatic] This changes everything! | | [sarcastic] | Irony, dry humor, deadpan delivery | [sarcastic] Oh sure, that went perfectly. | | [happy] | Upbeat, celebratory, good news | [happy] We just hit a million subscribers! | | [surprised] | Reactions, plot twists, disbelief | [surprised] Wait, are you serious right now? | | [angry] | Outrage, frustration, intensity | [angry] This is completely unacceptable! | | [fear] | Tension, warnings, alarm | [fear] Something is very wrong here. | | [crying] | Sadness, emotion, sympathy | [crying] I cannot believe they are gone. | | [whispering] | Secrets, asides, intimacy | [whispering] Nobody is supposed to know this. | | [narration] | Neutral storytelling, documentary tone | [narration] The year was nineteen sixty nine. | | [advertisement] | Sales pitch, promo, upbeat sell | [advertisement] Try it free for thirty days! |

Vocal Sound Effects (inject a specific sound)

| Tag | Effect | |-----|--------| | [laugh] | Full laugh | | [chuckle] | Soft/brief laugh | | [gasp] | Sharp intake of breath | | [sigh] | Exhalation, weariness | | [groan] | Displeasure, frustration | | [sniff] | Nasal sound | | [cough] | Cough | | [clear throat] | Throat clearing | | [shush] | Shushing sound |

Tips for Script Writing

• One tag per line. Place it at the start: [dramatic] The verdict is in.
• Emotion tags work best at sentence start. Sound effects can go mid-sentence: Well [chuckle] that was unexpected.
• Don't overuse. Not every line needs a tag — untagged lines get natural delivery from the voice reference.
• Match tag to content. [surprised] on mundane text sounds odd. Use it for genuine reveals.
• Best tags for news/TikTok scripts:
  • [dramatic] — opening lines, breaking news, reveals
  • [surprised] — reactions to the other speaker
  • [sarcastic] — commentary, humor, disbelief
  • [happy] — positive stories, celebrations
  • [narration] — factual context, transitions
  • [laugh] / [chuckle] — between speakers for natural feel

Installation

ComfyUI Manager

Search for "ChatterBox Turbo" in ComfyUI Manager and install.

Manual

cd ComfyUI/custom_nodes
git clone https://github.com/wobba/ComfyUI-ChatterBox-Turbo.git
pip install -r ComfyUI-ChatterBox-Turbo/requirements.txt

Restart ComfyUI after installation.

Model Download

The model (~700 MB) downloads automatically from ResembleAI/chatterbox-turbo on HuggingFace the first time either node runs. Files are stored in the standard ComfyUI models directory:

ComfyUI/models/TTS/chatterbox-turbo/

The folder is registered with ComfyUI's folder_paths system and respects extra_model_paths.yaml overrides. No manual download needed.

Runtime Patches

This node includes three compatibility patches applied at import time:

1. Perth watermarker — The perth audio watermarking library uses pkg_resources, which was removed in Python 3.13. If the real Perth module loads successfully, watermarking works normally. On Python 3.13+ where Perth fails to import, a no-op mock is installed so generation still works — but output audio will not be watermarked. This is logged at startup.

2. s3tokenizer float32 — On numpy 2.x, STFT operations return float64 instead of float32. The patch casts magnitudes back to float32 after STFT.

3. prepare_conditionals float32 — On numpy 2.x, librosa.load() returns float64 arrays. The patch ensures audio arrays are cast to float32 before being passed to the model.

Requirements

• ComfyUI with CUDA GPU
• Python 3.11+ (tested on 3.13)
• Dependencies: chatterbox-tts, soundfile, librosa, huggingface_hub, perth
• PyTorch, torchaudio, and numpy are expected from the ComfyUI environment

Credits

• Resemble AI for the ChatterBox model
• ChatterBox GitHub — upstream model repository

License

MIT