TS CosyVoice Model Loader

Every TS CosyVoice graph starts here. You drop in TS CosyVoice Model Loader, and on first run it goes off and fetches the Fun-CosyVoice3-0.5B model (~1.5 GB) into ComfyUI/models/cosyvoice/, checks every file's sha256 against the pack's manifest, then hands you a model output to plug into any of the six synthesis nodes. First run is the slow one. After that it loads from cache and you're usually seconds from a voice.

This loader is quietly doing real work, because the gap it fills is real. Alibaba's official ComfyUI wrapper for CosyVoice was written for CosyVoice 1 and never kept up - in the thread announcing CosyVoice 3 someone complained the official nodes "haven't been updated for over a year," with no CosyVoice 2 support at all. This pack wraps CosyVoice 3 properly, and the loader is where that happens: model download, integrity verification, device handling, and weight management are all its job.

How it works

The loader pulls the model from HuggingFace by default, or ModelScope if you switch download_source - same files, same hashes, so ModelScope is a mirror rather than a second source of truth. It verifies each file against model_manifest.json (sha256, pinned revision) before loading, which is a nicer failure mode than a silently corrupted checkpoint. Then it resolves the device CUDA-first with CPU fallback, loads the model, and caches it in memory for the rest of the session.

The inputs that matter

Most of these you will not touch. The two that earn a look:

• device (default auto) - picks CUDA when present, CPU otherwise. Here's the thing people get burned on: the CosyVoice runtime only implements CUDA and CPU. There is no Metal/MPS path, so on Apple Silicon you're on CPU no matter what you pick, and auto will log that it reduced an unsupported accelerator to CPU. That's an upstream limitation, not you misconfiguring.
• fp16 (default off) - saves roughly 30% VRAM on CUDA with almost no quality cost. Turn it on if you're memory-bound. It's forced off anywhere the runtime can't do it, including macOS.
• llm_checkpoint (default standard) - switch to reinforcement-learning to load the GRPO post-trained llm.rl.pt variant from the same model folder. The pack's tooltip claims better metrics; it also reloads the model when you flip it. Worth an A/B if you care about the last bit of quality.
• download_source and model_version - leave them alone. Fun-CosyVoice3-0.5B is the only model shipped, and HuggingFace is the right default unless you're behind a network that can't reach it.

Output

One output, model - a custom COSYVOICE_MODEL type that only the other TS CosyVoice nodes accept. Wire it into Text to Voice, Speaker Text To Voice, Cross-Language, Voice To Voice, Dialog, or Save Speaker. Nothing else in ComfyUI will take it, and that's fine.

Installing

cd ComfyUI/custom_nodes
git clone https://github.com/AlexYez/comfyui-ts-cosyvoice.git
cd comfyui-ts-cosyvoice
pip install -r requirements.txt

Or just search TS CosyVoice in ComfyUI Manager and let it do the work. Two things the README insists on, and both are easy to skip:

• You must install one ONNX Runtime yourself. pip install onnxruntime-gpu on NVIDIA, pip install onnxruntime on CPU or Apple Silicon. It's deliberately not in requirements.txt because ONNX Runtime only tolerates one build per environment and the pack refuses to guess. If it's missing, the loader says exactly that instead of failing obscurely.
• Make sure your CUDA torch is installed before the pack's deps, or pip can quietly pull a CPU torch.

Troubleshooting

• Loader won't start and says ONNX Runtime is missing - install one variant, not both.
• You have a GPU but reference encoding runs on CPU anyway - check the log for a warning that torch sees CUDA while ORT has no CUDAExecutionProvider.
• Model downloads are crawling or failing - switch download_source to ModelScope.
• Nothing at all appears in the Add Node menu - this pack is ComfyUI V3 schema only, so you need ComfyUI >= 0.3.40.

The model is the expensive download; the node itself is simple. Treat it as infrastructure: set it, wire it, forget it.