# ComfyUI-Qwen-TTS: Qwen3-TTS as ComfyUI nodes, and the transformers version that decides whether it loads > This repository wraps Alibaba's Qwen3-TTS in seven ComfyUI custom nodes covering speech synthesis, zero-shot voice cloning, voice design, a role bank and multi-role dialogue. It is a node pack rather than a library, the dependency story is contradictory between pyproject.toml and the README, and fine-tuning is marked experimental with zero-shot cloning recommended instead. **flybirdxx/ComfyUI-Qwen-TTS** — A Simple Implementation of Qwen3-TTS's ComfyUI - Repository: https://github.com/flybirdxx/ComfyUI-Qwen-TTS - Stars: 1,972 · Forks: 221 - Language: Python - License: not declared - Published: 2026-10-16 · Updated: 2026-10-16 · Language: en - Canonical page: https://hysenlabs.com/projects/flybirdxx-comfyui-qwen-tts ## The transformers requirement contradicts the package metadata The README opens with a warning marked CRITICAL about the transformers version, and it is the first thing to resolve before anything else. Qwen3-TTS works on transformers 4.57.3 and on transformers 5 and above, with the v5 compatibility provided by `tools/transformers5_shim.py` and applied automatically on import. On transformers below 5 the shims are no-ops, so the 4.57.3 path is unchanged. ```bash pip install transformers==4.57.3 # v4 path (shims inactive) # or pip install "transformers>=5.0" # v5 path (shims applied) ``` The problem is that pyproject.toml declares a different constraint for the same dependency: ```toml dependencies = [ "torch", "torchaudio", "transformers>=4.57.0,<5.0.0", "librosa", "soundfile", "accelerate", "numpy", "einops", "tiktoken", "sentencepiece" ] ``` So the metadata says below 5.0.0 while the README documents a supported 5.x path. requirements.txt is looser again, asking only for `transformers>=4.57.0`. If you install the package from its metadata rather than following the README, you get a version range that excludes a path the README calls supported. Pin transformers yourself before installing anything else. The project version is 1.0.7 and requires-python is >=3.9. ## Seven nodes, and what each one is for `VoiceDesignNode` generates a voice from a text description, taking `text`, `instruct` (for example a gentle female voice with a high pitch), and a `model_choice` currently locked to 1.7B for voice design features. `VoiceCloneNode` clones from reference audio, taking `ref_audio` of 5 to 15 seconds, the `ref_text` spoken in that clip which helps improve quality, and the `target_text` you want said. Its `model_choice` is either 0.6B for speed or 1.7B for quality. `CustomVoiceNode` is ordinary TTS with preset speakers, taking `text`, a `speaker` selection from presets such as Aiden, Eric and Serena, and an optional `instruct` for style. `VoiceClonePromptNode` extracts voice features once from reference audio so the same prompt item can be reused across multiple `VoiceCloneNode` instances, which the README frames as faster and more consistent than cloning each time. `RoleBankNode` is a registry of up to 8 roles, each with a `role_name_N` and a `prompt_N` voice clone prompt. `DialogueInferenceNode` consumes a role bank and a script in the format "RoleName: Text" to synthesize multi-speaker audio in one node, with `pause_seconds` for silence between sentences, `merge_outputs` to concatenate segments into one long audio, and `batch_size` for parallel line processing where larger is faster but uses more VRAM. The README names audiobook narration and roleplay as the intended scenarios. `LoadSpeakerNode` loads saved voice features and metadata with zero configuration, which the README describes as a select and play experience over the voice persistence system added on 2026-01-26. ## Attention selection and the VRAM escape hatch Every generation node carries the same two optional inputs, and they are the ones that decide whether it runs on your machine. `attention` accepts auto, sage_attn, flash_attn, sdpa or eager, with auto-detection and graceful fallback. The choice selects among the listed attention implementations; the README does not rank their relative performance. `sdpa` is PyTorch's built-in scaled dot product attention. Leaving it on auto is the sane default; naming a specific one is for when auto picks badly on your combination of GPU and driver. `unload_model_after_generate` unloads the model after generation to free GPU memory, which the README frames as optional management for users with limited VRAM. The trade is reload time on the next generation. The model size choice compounds this. Voice clone and dialogue nodes let you pick 0.6B or 1.7B, while voice design is locked to 1.7B. So a low-VRAM machine can use cloning and dialogue at 0.6B but cannot run voice design at all. ## Languages, tokenizers, and the dialogue script format The README claims native support for 10 languages: Chinese, English, Japanese, Korean, German, French, Russian, Portuguese, Spanish and Italian. It also states that both 12Hz and 25Hz speech tokenizer architectures are supported, and that high-fidelity speech reconstruction is available with low-latency streaming. The dialogue node is the piece with a concrete input contract worth planning around. Its `script` is plain text in the format "RoleName: Text", and the role names must resolve against the `role_bank` you pass in. That is a string contract; the README describes the input format but does not specify validation or error handling. Voice cloning wants `ref_text` as well as `ref_audio`, described as highly recommended for better quality and as helping improve quality on the clone node. Skipping it is allowed, so the degradation is gradual rather than a hard failure. ## What changed, and what got removed The changelog is the most informative part of the README, and one entry is a removal rather than an addition. On 2026-04-12, version 1.0.7 removed `QwenTTSConfigNode` due to voice inconsistency, and fixed an MPS precision bug plus a CustomVoice channel mismatch. That is a compatibility note for anyone with saved workflows. ComfyUI graphs reference nodes by type, so a node that no longer exists produces a broken graph on load, and the workflows shipped in the example/ directory, including Custom Save Voice.json and Multi-character dialogue.json, may reference node types from before the removal. The rest of the history shows the shape of the project. On 2026-02-04 it added `extra_model_paths.yaml` support, which matters if you keep models outside the default ComfyUI directory. On 2026-01-29 it added support for loading custom fine-tuned models and speakers, with the explicit note that fine-tuning is currently experimental and that zero-shot cloning is recommended for best results. Earlier entries cover PyTorch 2.6+ compatibility fixes, the voice persistence system, attention selection, memory management, generation parameters (top_p, top_k, temperature, repetition_penalty) and Mac MPS support. ## Dependencies and the two requirements files requirements.txt is broader than pyproject.toml, which is normal for a ComfyUI node pack but worth seeing side by side. Beyond the common set of torch, torchaudio, transformers, librosa, soundfile, accelerate, numpy, einops, tiktoken and sentencepiece, requirements.txt adds sox, huggingface_hub, onnxruntime-openvino, safetensors and `scipy>=1.11.0`. Two lines in that file are commented out, `# onnxruntime` and `# onnxruntime-gpu`, while `onnxruntime-openvino` is active. The active `onnxruntime-openvino` line is the ONNX-related dependency installed by default; the device path it uses is not specified. The repository layout is a ComfyUI node pack rather than an installable library in the usual sense: `__init__.py` and `nodes.py` at the root, the implementation under qwen_tts/, helper modules like pause_utils.py and download_models.py, tools/ holding the transformers shim, tests/, doc/, and train.py for fine-tuning. There is also a `[tool.comfy]` block in pyproject.toml with a PublisherId marked TODO and a note to fill it in from the ComfyUI registry, plus a DisplayName and an icon path. ## Where this is the wrong tool It is not a library. There is no documented Python API, no published package on an index, and no GitHub releases, so version pinning means pinning a commit. For a service, pin a reviewed commit and test the ComfyUI graph integration before deployment. Fine-tuning is explicitly experimental, with the changelog recommending zero-shot cloning for best results, and there is no evaluation in the README comparing the two. If your requirement is a specific trained voice rather than a clone, custom fine-tuned model support is documented, but marked experimental. Voice design is locked to 1.7B, so there is no low-VRAM route to it. And the removal of `QwenTTSConfigNode` in 1.0.7 means any workflow you built earlier against that node is dead without editing. The dependency contradiction is the quiet risk. A package metadata range of `transformers>=4.57.0,<5.0.0` that disagrees with the README's supported 5.x path is exactly the kind of mismatch that produces an import error deep inside a shim, with an error message that will not name the version conflict as its cause. The maintenance picture is fine on activity, with the last push on 2026-09-22, but the repository reports no license while pyproject.toml declares Apache-2.0 in its text field. Check which is authoritative for your use before redistributing anything. ## Conclusion ComfyUI-Qwen-TTS fits a ComfyUI user on Python 3.9 or newer who wants Qwen3-TTS voice cloning or design inside an existing node graph, has a GPU that can hold a 0.6B or 1.7B model, and is willing to settle the transformers version question before installing. It is not a library to depend on in production: it has no GitHub releases, reports no license in the repository metadata despite an Apache-2.0 string in pyproject.toml, and ships train.py for fine-tuning that the changelog calls experimental. Before installing, read the transformers note at the top of the README, decide whether you are on the 4.57.3 path or the 5.x path, and use zero-shot cloning rather than the fine-tuning path until you have verified the latter yourself. ## FAQ ### Which version of transformers does ComfyUI-Qwen-TTS need? The README states Qwen3-TTS works on transformers 4.57.3 and on transformers 5 and above, with the v5 path using a shim from tools/transformers5_shim.py applied automatically on import. Note that pyproject.toml instead declares `transformers>=4.57.0,<5.0.0`, so pin the version yourself. ### How do I voice clone in ComfyUI-Qwen-TTS? Use the VoiceCloneNode, giving it a `ref_audio` clip of 5 to 15 seconds, the `ref_text` spoken in that clip to improve quality, and the `target_text` you want said. Pick `model_choice` between 0.6B for speed and 1.7B for quality. ### What languages does ComfyUI-Qwen-TTS support? The README states native support for 10 languages: Chinese, English, Japanese, Korean, German, French, Russian, Portuguese, Spanish and Italian. It also supports both 12Hz and 25Hz speech tokenizer architectures. ### Can ComfyUI-Qwen-TTS generate multi-speaker dialogue? Yes, through DialogueInferenceNode. It takes a `script` in the format "RoleName: Text", a `role_bank` from RoleBankNode holding up to 8 named voices, plus `pause_seconds`, `merge_outputs` and `batch_size`. The README names audiobook narration and roleplay as the target scenarios. ### How do I free GPU memory in ComfyUI-Qwen-TTS? Set `unload_model_after_generate` on the node, which unloads the model after generation for users with limited VRAM. Attention implementation is chosen separately through the `attention` input, which accepts auto, sage_attn, flash_attn, sdpa or eager with auto-detection and fallback. ## Sources - [flybirdxx/ComfyUI-Qwen-TTS on GitHub](https://github.com/flybirdxx/ComfyUI-Qwen-TTS) - [Issues](https://github.com/flybirdxx/ComfyUI-Qwen-TTS/issues) - [README](https://github.com/flybirdxx/ComfyUI-Qwen-TTS/blob/main/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/flybirdxx-comfyui-qwen-tts