Qwen3-TTS Loader

The Qwen3-TTS Loader is the front door to the whole ComfyUI-Qwen3-TTS pack. Nothing else in the suite generates a single waveform until you've placed this node and picked a model, because every generator - Custom Voice, Voice Design, Voice Clone, even the fine-tuning chain - consumes its model output. Think of it as the equivalent of a CheckpointLoader for TTS: one node, one output, and the single most important decision you make is which of the five model variants you load.

Here's the part people get burned on: the variants are not interchangeable, and the pack will not quietly pick a compatible one for you. There are three flavors - CustomVoice, VoiceDesign, and Base - and each only works with its matching generator node. Load CustomVoice and wire it into Voice Clone and you'll get a deliberate, helpful error telling you to load a Base model instead. The mapping to remember:

• -CustomVoice → Qwen3-TTS Custom Voice (preset speakers)
• -VoiceDesign → Qwen3-TTS Voice Design (text-described voices)
• -Base → Qwen3-TTS Voice Clone, Prompt Maker, and fine-tuning

Each flavor comes in 1.7B and 0.6B sizes. The 1.7B is the quality pick and the default; the 0.6B is noticeably lighter if VRAM is tight or you want faster generation, and you can feel the gap in expressiveness. There's no 0.6B VoiceDesign variant, which tells you Alibaba doesn't think that job scales down well.

How it works

The node pulls the model from HuggingFace (or ModelScope, via the source dropdown) straight into ComfyUI/models/Qwen3-TTS/ - that's the pack's nice touch, models live alongside your checkpoints instead of in the HF cache. It only downloads the exact repo you select, on first run, and it will even migrate an existing model out of ~/.cache/huggingface/hub or the ModelScope cache if you'd already grabbed one. After that it loads with whatever precision you chose (bf16 default - fp32 only if your GPU predates Ampere and lacks bf16 support) and sets up attention.

The attention field is worth one honest sentence. auto tries Flash Attention 2 and falls back to sdpa if the flash_attn package isn't importable. On Windows that fallback basically always fires, because building Flash Attention there is a chore - so if you're on Windows, just pick sdpa and skip the failed-import noise in the logs.

The inputs that matter

• repo_id - the five-model dropdown described above. This is the one you'll actually touch.
• local_model_path - the escape hatch for fine-tuned models. Point it at your output_dir/epoch_X folder from Qwen3-TTS Finetune and the loader will load that checkpoint and layer it on top of the matching base model. This is how you use the voice you just trained.
• source, precision, attention - set-and-forget for most people.

The single output, model (type QWEN3_MODEL), wires into Custom Voice, Voice Design, Voice Clone, or Prompt Maker.

Installing the pack

Through ComfyUI Manager, search "ComfyUI-Qwen3-TTS" and install. Manually:

cd ComfyUI/custom_nodes
git clone https://github.com/DarioFT/ComfyUI-Qwen3-TTS.git
cd ComfyUI-Qwen3-TTS
pip install -r requirements.txt

Portable installs use .\python_embeded\python.exe -m pip install ... instead of pip. Two real gotchas: ComfyUI does not auto-install requirements.txt, so that pip install is mandatory; and the upstream qwen-tts package pins transformers==4.57.3, which can downgrade your existing transformers - the pack's own README suggests a separate Python environment if other nodes demand a newer one. People do hit this; a node that worked yesterday silently breaking after the TTS install is the classic symptom.

Troubleshooting

First run looks like a hang because the model downloads before anything renders - a multi-gigabyte 1.7B download on a slow pipe can sit there for a while. Watch the console. If generation itself hangs later with the GPU pegged at 100%, that's the known upstream Qwen3-TTS loop problem, and it's usually a max_new_tokens or reference-audio-length issue rather than something the loader did wrong.

If you want the full picture of the pack's other nodes before wiring anything, the generators are Qwen3CustomVoice, Qwen3VoiceDesign, and Qwen3VoiceClone - the loader is just the power supply for all three.