ComfyUI Node

Index TTS 2.5

Local voice cloning with actual emotion dials, inside ComfyUI

By mailzwj·Created 3 months ago·Updated 20 days ago· 8
Index TTS 2.5
  • reference_audio
  • emo_ref_audio
  • audio
  • seed
  • subtitle
◄text你好,欢迎使用 IndexTTS 2.5 语音合成。►
◄languagezh►
◄duration_factor1.00►
◄seed0►
◄emo_alpha1.00►
◄emo_vector►
◄emo_text►
◄use_emo_textfalse►
◄use_qwen_emofalse►
◄use_randomfalse►
◄do_sampletrue►
◄temperature0.80►
◄top_p0.80►
◄top_k30►
◄repetition_penalty10.0►
◄length_penalty0.0►
◄num_beams3►
◄max_mel_tokens1500►
◄max_text_tokens_per_segment120►
◄interval_silence200►
◄strict_max_mel_tokensfalse►
◄text_normalizationtrue►
◄glossary_yaml►
◄subtitle_formatsrt►
◄subtitle_textsynthesized►
◄use_bf16true►
◄auto_free_memoryfalse►
◄speaker_cachetrue►

IndexTTS-2.5 is the open TTS model that finally gets the whole package in one node: zero-shot voice cloning, five languages, and controllable emotion. Most TTS in ComfyUI gives you "clone this voice, say this text." This one also lets you say "say it angry" - or feed it an 8-number emotion vector and watch the delivery change. That's the differentiator, and it's why you'd reach for it over the usual Kokoro or F5-TTS corners. Those are excellent, but they're mostly monotone-with-vibes; IndexTTS is a Chinese research release (IndexTeam) that shipped 2.5 with a big inference-speedup and multilingual expansion, and the community's standing verdict is that it clones well, with the caveat that it can read a little "robotic" next to the very best - the emotion control is what pulls it back into the genuinely useful column.

What it actually does

The node (IndexTTS2_5Node) takes your text plus a reference audio clip and produces a new clip of that voice saying your text, in zh, en, ja, es, or ar. Under the hood it's the official IndexTTS-2.5 stack vendored straight into the pack - autoregressive GPT backbone, a S2Mel acoustic stage, and the BigVGAN vocoder - so nothing extra to wire up. On first run it auto-downloads three auxiliary models (w2v-bert-2.0 semantic encoder, campplus_cn_common.bin speaker embedder, and bigvgan) into your models dir's hf_cache/. It also exports a subtitle string with rough >> timestamp lines if you want burned captions on a video.

The inputs that matter

The required set is small and you'll touch all of it:

  • text - what to say (multiline).
  • reference_audio - the voice to clone, as an AUDIO type, so load a clip with a video-loader node first. Quality here decides everything: loud, dynamic reference audio (podcast-style) clones far better than quiet, flat samples.
  • language - zh / en / ja / es / ar.
  • duration_factor - speaking speed, 0.5–2.0. This is your "faster/slower" knob.
  • seed - set it to lock a take; note that 0 means not fixed, so zero won't give you reproducible results.

Emotion is optional and has three mutually exclusive routes: emo_ref_audio (a clip of the target emotion - ignored if the others are set), emo_vector (exactly 8 comma-separated or JSON numbers in the fixed order happy/angry/sad/afraid/disgusted/melancholic/surprised/calm - if you give anything but exactly 8, it's silently ignored, no error), and emo_text (describe it in words, like "angry", which a QwenEmotion model converts to the same vector - needs the optional qwen0.6bemo4-merge model). emo_alpha scales the whole thing 0–1. The sampling knobs (do_sample, temperature, top_p, top_k, repetition_penalty, num_beams, max_mel_tokens) are the standard LLM-generation family; leave them alone until you have a reason not to.

It returns three things: audio (AUDIO - wire to a preview or save node), seed, and subtitle.

Installing it

Grab it from ComfyUI Manager (search "IndexTTS"), or:

cd ComfyUI/custom_nodes
git clone https://github.com/mailzwj/ComfyUI-IndexTTS-2.5
cd ComfyUI-IndexTTS-2.5
pip install -r requirements.txt

Then drop the weights where the loader looks for them:

hf download IndexTeam/IndexTTS-2.5 --local-dir="<ComfyUI>/models/TTS/IndexTTS-2.5"

That's the whole pack: main node plus the Emo Settings helper. The dependency list is long and unsexy (librosa, sentencepiece, tiktoken, whisper, modelscope, wetext, …) but the author deliberately skipped the official keras==2.9.0 legacy dependency, so it doesn't force you onto an old Python. One real gotcha: the vendored indextts source is patched (compatibility_patch.py) to work with transformers 4.57.x. If your environment has a different transformers, expect it to break until the patch catches up. Japanese TTS additionally wants fugashi + unidic-lite, and flash-attn is off by default to dodge CUDA ABI mismatches.

Troubleshooting

  • "IndexTTS-2.5 模型目录缺少文件" - models aren't in models/TTS/IndexTTS-2.5. Run the hf download command above.
  • Weird errors right after install - almost certainly the transformers version vs. the compatibility patch. Check what's installed; that's the first thing to suspect.
  • Slow HuggingFace downloads - set export HF_ENDPOINT="https://hf-mirror.com" before first run.
  • Clones sound flat or warbly - swap the reference clip for something louder and more dynamic. Community testing on IndexTTS models found reference quality is the single biggest lever, by far. Output is also modest sample-rate mono (the earlier IndexTTS wrapper's users measured ~22kHz), so don't chase studio fidelity on the output side.

The one trap that'll waste an hour: forgetting emo_vector must be exactly 8 numbers. Nine, or a typo, and it's dropped with zero feedback - the synthesis just runs emotionless.

Categoryaudio

Inputs (30)

NameTypeDefaultDescription
textSTRING你好,欢迎使用 IndexTTS 2.5 语音合成。—
reference_audioAUDIO—
languageCOMBOzh5 options: zh, en, ja, es, ar
duration_factorFLOAT1.000.5–2—
seedINT00–4294967295—
emo_ref_audiooptAUDIO情感参考音频:用一段带目标情绪的语音引导合成情感。 提供 emo_vector 或 emo_text 后此输入会被忽略。
emo_alphaoptFLOAT1.000–1情感强度(0~1):对 emo_vector 做整体缩放; 或控制情感参考音频与说话人音色的混合比例。
emo_vectoroptSTRING8 维情感向量,顺序固定:高兴/愤怒/悲伤/恐惧/反感/低落/惊讶/自然。 逗号分隔或 JSON 数组,如 0.8,0,0,0,0,0,0,0 或 [0,0,0,0,0,0,0,1](自然)。 必须恰好 8 个数字,否则忽略;提供后覆盖 emo_ref_audio。
emo_textoptSTRING情感文本:用自然语言描述情绪(如「高兴」「悲伤」「愤怒」),由 QwenEmotion 自动转为情感向量。 非空即自动启用,需 qwen0.6bemo4-merge 模型;提供后覆盖 emo_ref_audio。 留空但勾选 use_emo_text 时,直接用正文内容推断情绪。
use_emo_textoptBOOLEANfalse使用情感文本。emo_text 非空时自动启用;emo_text 留空则用正文内容推断情绪。
use_qwen_emooptBOOLEANfalse加载 QwenEmotion 情感模型(仅情感文本需要;使用 emo_text 时自动加载)。
use_randomoptBOOLEANfalse随机情感:随机挑选情感参考向量(需同时提供 emo_vector 或 emo_text 才生效)。
do_sampleoptBOOLEANtrue—
temperatureoptFLOAT0.800.1–2—
top_poptFLOAT0.800–1—
top_koptINT300–100—
repetition_penaltyoptFLOAT10.01–15—
length_penaltyoptFLOAT0.0-2–2—
num_beamsoptINT31–10—
max_mel_tokensoptINT150050–1815—
max_text_tokens_per_segmentoptINT12010–300每段最多合成的文本 token 数(上游按标点优先切分)。 长文本被截断(话说一半就停)时调小此值,逐段生成更稳; 调大则跨句韵律更连贯,但更容易撞上 max_mel_tokens。 可用 Text Preview 节点预览实际分段与各段 token 数。
interval_silenceoptINT2000–2000分段之间插入的静音时长(毫秒)。0 表示无缝拼接, 长文本听感更连贯;200~500 更接近自然句间停顿。
strict_max_mel_tokensoptBOOLEANfalse某段因超出 max_mel_tokens 被截断时: 勾选 = 直接报错(避免产出残缺音频还继续跑); 不勾选(默认)= 仅在控制台打印可操作的提示。
text_normalizationoptBOOLEANtrue文本归一化(读法转换):中/英走 wetext 规则,日/西语走 NeMo,阿拉伯语不处理。 「2026年3月5日」「M.2」这类内容依赖它才能读对,一般保持开启; 已经手工写好读法、或归一化把专有名词改坏时再关掉。 注意:术语表(glossary)只在归一化阶段生效,关闭后 glossary 不起作用。
glossary_yamloptSTRING内联术语表(YAML),叠加在模型目录的 glossary.yaml 之上,键为术语、值为读法: M.2: zh: M 二 en: M dot two NVMe: N-V-M-E 同名条目以这里为准;留空则只用文件术语。模型常驻期间改文件也会自动热重载。
subtitle_formatoptCOMBOsrtsubtitle 输出格式: srt = 标准 SubRip(可直接导入剪映/PR/达芬奇或字幕节点); vtt = WebVTT(网页播放器); plain = 旧的「>> 0:02.130-0:05.870」文本行。
subtitle_textoptCOMBOsynthesized字幕文字来源: synthesized = 模型实际朗读的文本(归一化后,如「二零二六年」),时间轴最准; original = 你的原始输入(措辞干净),段内按字符占比映射回原文,边界略有近似。
use_bf16optBOOLEANtrue以 bf16 加载 GPT 主干(显存约省一半、速度更快),仅在 CUDA 上生效。 需要 Ampere(RTX 30 系 / A 系列)及以上;显卡算力不足时会自动按 fp32 加载并在控制台提示。
auto_free_memoryoptBOOLEANfalse生成完成后自动回收内存/显存(卸载整套 IndexTTS-2.5 模型并执行 gc + CUDA empty_cache)。 勾选后:本次生成结束即释放,下次生成需重新加载模型(约 10~60 秒), 适合需要把显存腾给图像/视频等其它模型的场景; 不勾选(默认):模型常驻 GPU,连续多次生成更快。
speaker_cacheoptBOOLEANtrue按参考音频内容缓存说话人/情感条件张量(LRU 6 份): 同一音色再次生成时跳过 wav2vbert + s2mel + campplus 提特征,多人对话交替角色时提速最明显。 关闭可腾出这部分显存;模型卸载(auto_free_memory)时缓存随之释放。

Outputs (3)

NameTypeDescription
audioAUDIO—
seedINT—
subtitleSTRING—