⚙️ Qwen3-TTS Engine
Preset voices, text-to-voice design, and cloning in one node
- TTS_engine
Qwen3-TTS is Alibaba's entry, and the reason it's interesting is that it's really three tools wearing one node. It can talk in nine ready-made preset speakers, it can invent a voice from a text description, and it can clone a voice from a reference clip. Plus it doubles as the front half of the suite's ASR (speech-to-text) path. If you don't know exactly which voice you want yet, this is a great engine to poke around in.
As with all the engine nodes, this one configures a model and outputs a TTS_engine - the actual speaking happens in 🎤 TTS Text or 📺 TTS SRT (or, for transcription, the ✏️ ASR Transcribe node). The model_variant dropdown is where you pick which of the three personalities you're using.
How it works
The model_variant decides the mode:
- CustomVoice (0.6B / 1.7B) - 9 built-in multilingual speakers (Vivian, Serena, Uncle_Fu, Dylan, and friends). Pick one in
voice_preset. Supports style instructions. - VoiceDesign (1.7B) - describe a voice in words and get it. "A cheerful young woman with a bright, energetic tone" in and a matching voice out. Supports style instructions.
- Base (0.6B / 1.7B) - zero-shot cloning from a 3–30s reference. Best quality needs the reference audio plus its transcript (ICL mode); the 🎭 Character Voices node supplies both.
One trap worth burning into memory: style instructions only work with CustomVoice and VoiceDesign. In Base (cloning) mode the instruct field is silently ignored - the README says so plainly. If you typed "speak angrily" into a cloning setup and nothing happened, that's why.
The inputs and outputs that matter
model_variant- the mode selector. This is the decision that shapes everything else.voice_preset- the 9 named speakers, used in CustomVoice mode (leave itNonefor cloning/design).language-Autoor one of 10 (Chinese, English, Japanese, Korean, German, French, Russian, Portuguese, Spanish, Italian). Unlike some engines here, Qwen3 does use an explicit language parameter.instruct- your style instruction ("Speak cheerfully") or, in VoiceDesign, the voice description. Remember: ignored by Base cloning.
The generation set - temperature, top_k, top_p, repetition_penalty, max_new_tokens - behaves the way you'd expect. In the optional group, x_vector_only_mode switches Base cloning to embed-from-audio-only (faster, lower quality, no transcript needed), and use_torch_compile / use_cuda_graphs / compile_mode are opt-in speedups (torch.compile can give ~1.7x but wants a recent PyTorch). The asr_* fields configure translation when you use this engine for transcription. Keep runtime_mode on Shared Runtime.
Output: TTS_engine → TTS Text, TTS SRT, or ASR Transcribe.
Installing it
Bundled with the pack. ComfyUI Manager → "TTS Audio Suite" → install → restart. Manual:
cd ComfyUI/custom_nodes
git clone https://github.com/diodiogod/TTS-Audio-Suite.git
cd TTS-Audio-Suite
python install.py
Per-variant weights (3–6GB) auto-download to ComfyUI/models/TTS/qwen3_tts/ on first use - so switching variants triggers a fresh download the first time.
Common issues & troubleshooting
Your instruction did nothing. You're in Base cloning mode. Switch to CustomVoice or VoiceDesign, or accept that cloning ignores style text.
The clone is weak. Base's best mode (ICL) needs the reference transcript. Use 🎭 Character Voices to supply audio + text together instead of feeding raw audio, or flip x_vector_only_mode on if you deliberately want the faster transcript-free path and can live with the drop.
torch.compile crashes or is slower the first run. Compilation has warm-up cost and needs a new-enough PyTorch. If it errors, just leave use_torch_compile off - it's a bonus, not a requirement.
Model keeps re-downloading. Each variant is a separate checkpoint; the dropdown marks installed ones with a local: prefix. Sticking to variants you've already pulled avoids surprise downloads.
Inputs (20)
| Name | Type | Default | Description |
|---|---|---|---|
| model_variant | COMBO | TTS - Base 1.7B (Voice Clone) | Explicit Qwen3-TTS checkpoint. Local installations use the local: prefix. Base models clone a reference voice, CustomVoice models use preset speakers, and VoiceDesign works only with Voice Designer. |
| device | COMBO | auto | Device to run Qwen3-TTS model on: • auto: Automatically select best available • cuda: NVIDIA GPU (requires CUDA) • cpu: CPU-only processing (very slow) |
| voice_preset | COMBO | None (Zero-shot / Custom) | Preset speaker for CustomVoice checkpoints. Ignored by Base and VoiceDesign models. |
| language | COMBO | Auto | Target language for speech generation: • Auto: Automatically detect from text • Portuguese: European Portuguese only for Base model - Brazilian Portuguese: Only available with CustomVoice presets + instruction - Example instruction: 'Speak with Brazilian Portuguese accent' |
| instruct | STRING | Delivery instruction for the 1.7B CustomVoice checkpoint. Voice Designer owns the voice description when a VoiceDesign checkpoint is selected, so this field is disabled there. Base and 0.6B CustomVoice models ignore it. | |
| top_k | INT | 501–100 | Top-K sampling: • Lower (10-30): More focused, consistent • Default (50): Balanced • Higher (80-100): More varied output |
| top_p | FLOAT | 1.000–1 | Top-P (nucleus) sampling: • Lower (0.7-0.9): More focused • Default (1.0): All tokens considered • Combine with top_k for fine control |
| temperature | FLOAT | 0.90.1–2 | Sampling temperature: • Lower (0.5-0.7): More predictable • Default (0.9): Balanced • Higher (1.2+): More creative, potentially unstable |
| repetition_penalty | FLOAT | 1.051–2 | Repetition penalty: • 1.0: No penalty • 1.05: Slight penalty (default) • 1.2+: Strong penalty (may affect quality) |
| max_new_tokens | INT | 204864–8192 | Maximum tokens to generate: • 64-512: Very short • 2048: Standard (default) • 4096-8192: Long generation Higher = more VRAM + longer generation |
| dtypeopt | COMBO | auto | Model precision: • auto: Selects bfloat16 if GPU supports it (SM 8.0+), else float16 • bfloat16: Best quality, stable (RTX 30xx+, A100+) • float16: Good quality, wider compatibility • float32: Maximum precision, 2x VRAM |
| attn_implementationopt | COMBO | auto | Attention mechanism: • auto: Best available (priority: sage_attn > flash_attention_2 > sdpa > eager) • sage_attn: Fastest (requires sageattention package) • flash_attention_2: Very fast (requires flash-attn installed) • sdpa: Good balance (PyTorch native) • eager: Slowest, most compatible |
| x_vector_only_modeopt | BOOLEAN | false | X-vector only mode (Base model only): • False: Full voice cloning (high quality, requires ref_text) • True: Fast speaker embedding only (lower quality, no ref_text needed) Only applies when voice_preset = None |
| use_torch_compileopt | BOOLEAN | false | Enable torch.compile for decoder (~1.5-2x speedup): • False: Standard inference (RECOMMENDED - works with all PyTorch versions) • True: Compiled decoder (REQUIRES PyTorch 2.10+ and triton-windows 3.6+) ⚠️ REQUIREMENTS: PyTorch 2.10.0+cu130, triton-windows 3.6.0+, and Visual Studio C++ Build Tools on Windows ⚠️ Shared/Dedicated Runtime will try to detect the toolchain automatically, but it still must be installed ⚠️ See docs/qwen3_tts_optimizations.md for installation First generation slower due to compilation, then ~1.5-2x faster |
| use_cuda_graphsopt | BOOLEAN | false | Enable manual CUDA graph capture: • False: RECOMMENDED (reduce-overhead mode already has auto CUDA graphs) • True: Manual capture - minimal gain (~0.1 it/s), only works with mode='default' Note: reduce-overhead/max-autotune include CUDA graphs automatically |
| compile_modeopt | COMBO | default | torch.compile mode (if use_torch_compile enabled): • default: RECOMMENDED - Standard torch.compile, ~1.7x speedup, works on Windows • reduce-overhead: Auto CUDA graphs, ~2-3x speedup, LINUX ONLY (fails on Windows) • max-autotune: Best optimization, longest compile, LINUX ONLY ⚠️ Windows: Only 'default' works - reduce-overhead/max-autotune fail with cudaMallocAsync error ⚠️ Model must be reloaded to test different modes (cache reuse otherwise) |
| asr_use_forced_aligneropt | BOOLEAN | true | Enable Qwen3 forced aligner (required for word timestamps + accurate SRT). Turn OFF to save VRAM and skip downloading the extra aligner model if you only need text (no timestamps). |
| asr_translate_target_languageopt | COMBO | English | Experimental ASR translation target for ✏️ ASR Transcribe when task=translate. This is ASR-only and does NOT affect Qwen TTS generation language. Important: • Qwen translation in this integration is prompt-driven through the ASR wrapper, not a dedicated native target-language API • Translation quality currently depends heavily on language pair and backend behavior • English is the safest default • Non-English targets should be treated as experimental until you validate them on real audio |
| asr_translate_instruction_overrideopt | STRING | Translate the speech from {source_language} into {target_language} text. Return only the translated text. | Qwen ASR-only experimental translation instruction template for ✏️ ASR Transcribe when task=translate. This field shows the actual default instruction used by this integration. Edit it if you want to experiment. Available placeholders: • {source_language}: Replaced with the unified ASR source language, or 'the spoken source language' when ASR language is Auto • {target_language}: Replaced with this engine node's ASR translation target Important: • This does NOT affect Qwen TTS generation or the TTS 'instruct' field • Qwen translation here is prompt-driven through the ASR wrapper context • Results can vary a lot by language pair, and some pairs may not behave reliably at all • Weak or malformed custom instructions can produce worse translations or unexpected output |
| runtime_modeopt | COMBO | ⚠️ Shared Runtime | IMPORTANT: Qwen3-TTS is fragile on Transformers 5 in the main environment. Runtime Isolation: • Main Environment: Use the main ComfyUI Python environment • Shared Runtime: Use the shared secondary legacy runtime already used by compatible engines • Dedicated Runtime: Create a separate secondary runtime just for Qwen3-TTS Why this matters: • The main ComfyUI env is on Transformers 5 • Qwen3-TTS is more stable on the legacy Transformers 4 stack • Runtime isolation keeps Qwen3-TTS working without downgrading the whole app ⚠️ Shared/Dedicated runtimes currently reuse heavy base packages from the main env (like PyTorch) and install pinned Qwen3-TTS-specific packages on top. ⚠️ First run may create the secondary runtime and take a while. |
Outputs (1)
| Name | Type | Description |
|---|---|---|
| TTS_engine | TTS_ENGINE | — |