T5Gemma-TTS Model Loader

T5GemmaTTS_ModelLoader is the unglamorous half of the comfyui-t5gemma-tts pack, and it deserves more respect than it gets, because it's where the whole workflow either starts smoothly or dies on the first run. It loads the T5Gemma-TTS model and its tokenizers from a HuggingFace repo ID or a local path, and hands a T5GEMMA_MODEL object to T5GemmaTTS_Generate. Everything heavy - the 2B T5Gemma encoder-decoder, the XCodec2 audio codec, and a Whisper model for auto-transcribing reference clips - comes down in this one node.

T5Gemma-TTS is Aratako's multilingual text-to-speech model (EN/JA/ZH) built on Google's T5Gemma-2B, wrapped here by negaga53. In the ComfyUI audio ecosystem, this is the "heavier but more multilingual" corner: it's a long way from the Kokoro/Piper CPU-lightweight tier, and it isn't trying to be Chatterbox's ElevenLabs rival - its selling point is that it does English and Japanese and Chinese out of one model, which most open TTS simply won't.

The inputs that matter

• model_dir - default Aratako/T5Gemma-TTS-2b-2b. An HF repo ID or a local path. This is where the quantized variants come in:
  • T5Gemma-TTS-2b-2b → ~10.6 GB VRAM
  • ...-encoder-8bit → ~8.6 GB
  • ...-encoder-4bit → ~7.6 GB
• device - auto (default), cuda, or cpu. auto picks CUDA, then Apple Silicon (MPS), then CPU in that order. cpu is technically an option; realistically you'll want a GPU.
• cpu_codec / cpu_whisper - the two VRAM pressure valves. Each offloads a component (the XCodec2 codec, or Whisper) to system RAM, saving ~3.5 GB and ~5 GB respectively. If you're hovering at the edge of your card, tick these before you buy a smaller model.
• use_torch_compile - torch.compile for faster repeat inference, CUDA only. Leave off until you're rendering the same voice a lot; the first call pays a compile cost.
• xcodec2_model_name - blank by default; only reach for it if you've installed a specific codec checkpoint and want to override the config default.

Output: one model (T5GEMMA_MODEL), which connects only to the Generate node's model input. There's also a class-level cache, so re-running the same configuration doesn't re-download - change any of the settings above and it'll reload.

Install

The loader pulls a lot of its dependencies through pip, so the install step matters:

cd ComfyUI/custom_nodes
git clone https://github.com/negaga53/comfyui-t5gemma-tts
cd comfyui-t5gemma-tts
pip install -r requirements.txt

That's transformers, huggingface_hub, sentencepiece, safetensors, soundfile, plus the phoneme-counting libraries. But the loader will also raise ImportError: xcodec2 module not found unless you install the codec separately - the README offers two flavors: the Anime-XCodec2 variant (44.1 kHz, recommended for Japanese) or the original XCodec2 at 16 kHz (English/Chinese). For Japanese support, pip install pyopenjtalk-plus[onnxruntime] is optional but recommended. Restart ComfyUI afterward, or pick it up through ComfyUI Manager (search "T5Gemma-TTS").

Common issues

• Gated model, 401 on first load. Aratako/T5Gemma-TTS-2b-2b is gated on HuggingFace - the loader uses trust_remote_code=True and tries to download on first run, but anonymous downloads are refused until you log in and accept the license agreement on the model's page. One-time, then it works.
• "xcodec2 module not found." The most common failure by far - the codec isn't in requirements.txt, it's the manual pip line. Check that before blaming VRAM.
• Torch version whiplash. The engine handles torch 2.9+ by switching to soundfile for audio saving, and the upstream project pins older torch for CUDA. If you hit weird save errors, that's the seam.
• The README mentions a third node that doesn't exist. It describes a "T5Gemma-TTS Reference Audio" node, but the pack only ships these two classes. Load reference clips with ComfyUI's built-in Load Audio instead - the Generate node accepts plain AUDIO input.

One license note so it isn't a surprise later: the pack code is MIT, but the model weights are CC-BY-NC-4.0 + Gemma Terms of Use - non-commercial. The code is free to fork; the voice it produces isn't free to sell.