ContextQMD
Back to Index Tts

IndexTTS2 CLI v2 使用文档

docs/cli_v2_usage.md

2.5.035.2 KB
Original Source

IndexTTS2 CLI v2 使用文档

本文档面向用户级 indextts2 命令行入口。CLI v2 是 IndexTTS2-first 的专用入口, 可安装到用户环境后从任意目录运行, 不依赖仓库根目录作为当前工作目录。它不会替换已有 indextts 命令。indextts 仍保留现有 IndexTTS1 行为。

功能范围

当前 CLI v2 提供以下子命令:

  • indextts2 init: 创建持久化配置和默认模型资源目录, 不下载模型资源。
  • indextts2 config: 查看或修改持久化配置。
  • indextts2 download: 显式下载 IndexTTS2 模型资源。
  • indextts2 check: 检查本地模型资源, Python 包和设备可用性。
  • indextts2 synth: 使用 IndexTTS2 合成单条文本音频。
  • indextts2 batch: 读取 JSON Lines 批量清单, 串行合成多条独立音频, 或合成后拼接为一个 WAV 文件。
  • indextts2 concat: 读取 JSON Lines 拼接清单, 将已有 WAV 片段拼接为一个 WAV 文件。

以后可能会提供，但暂不包括:

  • WebUI 子命令, WebUI 仍使用 uv run webui.py。
  • batch 的 --continue-on-error。
  • batch 的并发执行。
  • GPT 采样细节参数, 例如 top_p, top_k, temperature 等。
  • IndexTTS1/IndexTTS2 引擎选择器。

安装与入口

项目在 pyproject.toml 中注册了两个命令:

toml
indextts = "indextts.cli:main"
indextts2 = "indextts.cli_v2:main"

普通用户推荐使用用户级安装方式注册 CLI。当前仓库包如果尚未发布到 PyPI 或默认包 registry, 需要在仓库根目录从本地源码安装:

bash
uv tool install --python 3.10 .

也可以使用 pipx 从本地源码安装:

bash
pipx install .

在仓库开发和调试时, 可使用 editable 安装方式注册 CLI:

bash
uv tool install --python 3.10 -e .

安装后可查看帮助:

bash
indextts2 --help
indextts2 init --help
indextts2 config --help
indextts2 download --help
indextts2 check --help
indextts2 synth --help
indextts2 batch --help
indextts2 concat --help

未安装入口时, 也可以在仓库根目录用 Python 模块方式调用。该入口保留给开发和调试使用, 不作为普通用户主路径:

bash
python -m indextts.cli_v2 --help

首次初始化

indextts2 init 会创建平台标准配置目录, config.toml 和默认模型资源目录。它只准备本地状态, 不会自动联网下载模型资源。

bash
indextts2 init

指定模型资源目录并写入持久化配置（请将 D:/models/IndexTTS-2 替换为你的目标模型目录）:

bash
indextts2 init --model-dir D:/models/IndexTTS-2

check, synth 和 batch 在运行前也会执行首次初始化, 因此首次运行这些命令会创建配置文件和默认模型资源目录, 但仍不会自动下载模型资源。concat 不需要模型资源, 不执行模型资源检查。

模型资源目录

CLI v2 使用“模型资源目录”保存 IndexTTS2 的模型文件和配套资源。

平台默认模型资源目录:

平台默认模型资源目录
Windows%LOCALAPPDATA%\IndexTTS\models\IndexTTS-2
macOS~/Library/Application Support/IndexTTS/models/IndexTTS-2
Linux${XDG_DATA_HOME:-~/.local/share}/indextts/models/IndexTTS-2

持久化配置位置:

平台持久化配置
Windows%APPDATA%\IndexTTS\config.toml
macOS~/Library/Application Support/IndexTTS/config.toml
Linux${XDG_CONFIG_HOME:-~/.config}/indextts/config.toml

模型资源目录解析优先级:

  1. 命令行参数 --model-dir PATH。
  2. 环境变量 INDEXTTS2_MODEL_DIR。
  3. 持久化配置 model_dir。
  4. 平台默认模型资源目录。

CLI 内部固定使用:

text
{model-resource-directory}/config.yaml

模型资源目录必须包含以下关键资源:

text
config.yaml
bpe.model
gpt.pth
s2mel.pth
wav2vec2bert_stats.pt
feat1.pt
feat2.pt
qwen0.6bemo4-merge
hf_cache/w2v-bert-2.0
hf_cache/semantic_codec_model.safetensors
hf_cache/campplus_cn_common.bin
hf_cache/bigvgan/config.json
hf_cache/bigvgan/bigvgan_generator.pt

配置管理

查看持久化配置文件位置:

bash
indextts2 config path

查看当前持久化配置:

bash
indextts2 config get

写入模型资源目录:

bash
indextts2 config set model_dir D:/models/IndexTTS-2

可配置键:

键用途
model_dir持久化模型资源目录。
default_device持久化默认运行设备, 例如 cpu, cuda, cuda:0, mps, xpu。
use_fp16持久化是否启用 FP16, 值为 true 或 false。
use_deepspeed持久化是否启用 DeepSpeed, 值为 true 或 false。
use_cuda_kernel持久化是否启用 CUDA kernel, 值为 true 或 false。

普通 check, synth 和 batch 参数只覆盖本次运行, 不会写回持久化配置。配置写入只通过 indextts2 init --model-dir PATH, indextts2 config set KEY VALUE, 以及成功的 indextts2 download --model-dir PATH 完成。download --no-save 不写回。

模型下载

推荐通过 CLI 显式下载模型资源:

bash
indextts2 download

默认下载源是 HuggingFace。选择下载源:

bash
indextts2 download --source huggingface
indextts2 download --source modelscope

指定下载目标目录:

bash
indextts2 download --source huggingface --model-dir D:/models/IndexTTS-2

download --model-dir PATH 下载成功并通过资源检查后, 默认会把 PATH 写入持久化配置的 model_dir, 后续 check, synth 和 batch 会默认使用该目录。临时下载或预热其他目录时使用 --no-save:

bash
indextts2 download --source modelscope --model-dir D:/tmp/IndexTTS-2 --no-save

下载命令通过 Python API 下载资源, 不依赖外部 hf 或 modelscope 可执行文件在 PATH 中。目标目录已有文件时, CLI 不会清空目录, 下载器可以增量补齐。下载完成后, CLI 会复用模型资源检查判断目录是否可用。

环境检查

运行:

bash
indextts2 check

指定设备检查:

bash
indextts2 check --device cuda:0

check 会检查:

  • 解析后的模型资源目录是否存在。
  • 必需模型资源是否存在。
  • Python 包是否可导入: torch, torchaudio, indextts。
  • 设备可用性: cuda, xpu, mps, cpu。
  • 当传入 --device 时, 该设备是否可用。

示例成功输出:

text
Checking model directory: <resolved-model-resource-directory>
OK: model directory <resolved-model-resource-directory>
OK: required model files
OK: python packages
cuda: available
xpu: unavailable
mps: unavailable
cpu: available

单条文本合成

最小命令:

bash
indextts2 synth --text "你好, IndexTTS2。" --voice examples/voice_01.wav --output outputs/hello.wav

从 UTF-8 文本文件读取:

bash
indextts2 synth --text-file input.txt --voice examples/voice_01.wav --output outputs/hello.wav

从标准输入读取:

bash
echo "从标准输入读取文本。" | indextts2 synth --stdin --voice examples/voice_01.wav --output outputs/stdin.wav

文本来源必须三选一:

  • --text TEXT
  • --text-file PATH
  • --stdin

CLI 会去除文本首尾空白, 去除后不能为空。--text-file 按 UTF-8 读取。

输出文件

--output 必填。默认不覆盖已有文件:

bash
indextts2 synth --text "测试覆盖。" --voice examples/voice_01.wav --output outputs/hello.wav

如需覆盖已有输出, 使用 --force:

bash
indextts2 synth --text "测试覆盖。" --voice examples/voice_01.wav --output outputs/hello.wav --force

输出路径的父目录会自动创建。合成成功时, 标准输出会打印:

text
Generated: outputs/hello.wav

音色与情感控制

--voice 必填, 指向音色参考音频:

bash
indextts2 synth --text "保持音色。" --voice examples/voice_01.wav --output outputs/voice.wav

使用情感参考音频:

bash
indextts2 synth --text "使用情感参考音频。" --voice examples/voice_01.wav --emotion-audio examples/emo_sad.wav --emotion-weight 0.75 --output outputs/emotion_audio.wav

使用情感描述文本:

bash
indextts2 synth --text "使用情感描述文本。" --voice examples/voice_01.wav --emotion-text "warm and calm" --emotion-weight 0.6 --output outputs/emotion_text.wav

使用 8 维情感向量:

bash
indextts2 synth --text "使用情感向量。" --voice examples/voice_01.wav --emotion-vector 0,0,0.8,0,0,0,0,0 --emotion-weight 1.0 --output outputs/emotion_vector.wav

8 维情感向量的顺序固定为: 高兴, 愤怒, 悲伤, 害怕, 厌恶, 忧郁, 惊讶, 平静。

--emotion-vector 接受两种格式:

  • 逗号分隔格式: 0,0,0.8,0,0,0,0,0
  • 带方括号的列表格式: [0, 0, 0.8, 0, 0, 0, 0, 0]

规则:

  • --emotion-vector, --emotion-audio 和 --emotion-text 三者互斥, 每次只能选择一种情感来源。
  • --emotion-text 不能为空字符串。
  • --emotion-vector 必须正好包含 8 个数字。
  • --emotion-vector 每个值必须在 0.0..1.0 范围内。
  • --emotion-vector 的总和必须小于等于 0.8。
  • CLI 不会自动归一化, 裁剪, 重平衡或改写情感向量。
  • --emotion-weight 必须是浮点数, 默认值为 1.0。
  • --emotion-weight 会传给 IndexTTS2 的 emo_alpha。用于 --emotion-vector 时, 它会整体缩放 8 维情感向量的强度。

批量合成

indextts2 batch 是当前 CLI v2 的批量合成子命令。它读取一份 JSON Lines 批量清单, 先预检整份清单, 再只初始化一次模型。默认模式按清单顺序串行生成多份独立音频文件。传入 --concat 时, CLI 会先为每条任务生成临时 WAV 片段, 再按清单顺序拼接成一个最终 WAV 文件。

batch 是新增子命令, 不会改变 indextts2 synth 的单条合成契约。

基本命令

只校验批量清单和模型资源, 不加载模型, 不生成音频:

bash
indextts2 batch --batch-file examples/batch/demo.jsonl --voice examples/voice_01.wav --dry-run

--dry-run 成功时输出:

text
Batch file OK: 4 tasks

真实批量合成:

bash
indextts2 batch --batch-file examples/batch/demo.jsonl --voice examples/voice_01.wav --device cuda:0 --fp16

合成成功时会逐条输出生成路径, 最后输出汇总:

text
Generated: examples/batch/out/001.wav
Generated: examples/batch/out/002.wav
Generated: examples/batch/out/003.wav
Generated: examples/batch/out/004.wav
Batch complete: 4 tasks generated

输出模式

batch 支持三种输出模式。

逐行输出是默认模式。清单中每行必须提供 output:

bash
indextts2 batch --batch-file examples/batch/demo.jsonl --voice examples/voice_01.wav

自动命名输出使用 --output-dir, 清单中不能提供 output。输出文件按任务顺序命名为 0001.wav, 0002.wav:

bash
indextts2 batch --batch-file examples/batch/auto-output.jsonl --voice examples/voice_01.wav --output-dir examples/batch/out/auto --dry-run

如需文件名前缀, 加 --output-prefix。前缀不能包含路径分隔符或文件扩展名:

bash
indextts2 batch --batch-file examples/batch/auto-output.jsonl --voice examples/voice_01.wav --output-dir examples/batch/out/auto --output-prefix chapter --dry-run

上例真实执行时会生成:

text
examples/batch/out/auto/chapter-0001.wav
examples/batch/out/auto/chapter-0002.wav
examples/batch/out/auto/chapter-0003.wav

拼接输出使用 --concat --output <final.wav>, 清单中不能提供逐行 output:

bash
indextts2 batch --batch-file examples/batch/batch-concat.jsonl --voice examples/voice_01.wav --concat --output examples/batch/out/story.wav --dry-run

--dry-run 成功时输出:

text
Batch concat OK: 3 tasks

真实执行时, CLI 会创建内部临时目录, 逐条合成 WAV 片段, 拼接为 --output 指定的最终 WAV, 然后默认删除临时目录:

bash
indextts2 batch --batch-file examples/batch/batch-concat.jsonl --voice examples/voice_01.wav --concat --output examples/batch/out/story.wav

成功时输出:

text
Generated: <resolved-output.wav>

如需保留内部临时 WAV 片段用于排查问题, 加 --keep-temp:

bash
indextts2 batch --batch-file examples/batch/batch-concat.jsonl --voice examples/voice_01.wav --concat --output examples/batch/out/story.wav --keep-temp

成功时会额外输出临时目录:

text
Generated: <resolved-output.wav>
Temp dir: <resolved-temp-dir>

JSON Lines 批量清单

批量清单每个非空行是一条 JSON object。空行会被忽略, 不计入任务数。当前不支持注释行或行内注释。

示例 examples/batch/demo.jsonl:

jsonl
{"text": "第一句直接写在批量清单里。", "output": "out/001.wav"}
{"text_file": "texts/second.txt", "emotion_audio": "../emo_sad.wav", "emotion_weight": 0.75, "output": "out/002.wav"}
{"text": "第三句使用 JSON array 格式的情感向量。", "emotion_vector": [0, 0, 0.6, 0, 0, 0, 0, 0], "output": "out/003.wav"}
{"text": "第四句使用 CLI 字符串格式的情感向量。", "emotion_vector": "0,0,0,0,0,0,0,0.5", "emotion_weight": "0.4", "output": "out/004.wav"}

每行支持的字段:

字段必填说明
text与 text_file 二选一直接传入待合成文本, 去除首尾空白后不能为空。
text_file与 text 二选一从 UTF-8 文本文件读取待合成文本, 整个文件作为一条任务文本。
voice有命令级 --voice 时可省略音色参考音频路径。
output默认逐行输出模式必填输出音频路径。使用 --output-dir 或 --concat 时不能提供。
emotion_audio否情感参考音频路径。
emotion_text否情感描述文本。
emotion_vector否8 维情感向量, 支持 JSON array 或 CLI 风格字符串。
emotion_weight否情感权重, 必须可解析为浮点数。
silence_after_ms否拼接模式下, 在当前片段后追加的静音毫秒数。只能与 --concat 一起使用。

规则:

  • 未知字段会报错, 避免字段拼写错误被静默忽略。
  • text 和 text_file 必须二选一, 不能同时提供, 也不能都不提供。
  • 批量清单不支持逐行 stdin。
  • voice 可逐行提供, 也可用命令级 --voice 作为默认值。
  • 默认逐行输出模式下, output 必须解析为每条任务的唯一输出路径。
  • 使用 --output-dir 时, output 由 CLI 自动生成, 清单中不能出现 output。
  • 使用 --concat 时, 最终输出来自命令级 --output, 清单中不能出现逐行 output。
  • silence_after_ms 必须是非负整数, 默认值为 0。

路径解析

批量清单中的相对路径按批量清单文件所在目录解析, 包括 text_file, voice, 默认逐行输出模式下的 output 和 emotion_audio。

命令行参数路径仍按当前工作目录解析, 包括 --batch-file, 显式传入的 --model-dir, 命令级 --voice, 命令级 --emotion-audio, --output-dir 和拼接模式的 --output。

例如从仓库根目录运行:

bash
indextts2 batch --batch-file examples/batch/demo.jsonl --voice examples/voice_01.wav --dry-run

如果 examples/batch/demo.jsonl 某行写入 "output": "out/001.wav", 实际输出路径会解析为 examples/batch/out/001.wav。

如果使用:

bash
indextts2 batch --batch-file examples/batch/auto-output.jsonl --voice examples/voice_01.wav --output-dir examples/batch/out/auto --dry-run

自动输出目录 examples/batch/out/auto 会按当前工作目录解析, 不会按 auto-output.jsonl 所在目录再次拼接。

覆盖, 失败和输出

默认不覆盖已有输出文件。如果任一任务的输出文件已存在, 且没有传 --force, 命令会在模型初始化前失败:

bash
indextts2 batch --batch-file examples/batch/demo.jsonl --voice examples/voice_01.wav --force

覆盖规则:

  • --force 只允许覆盖批量运行开始前已经存在的外部输出文件。
  • 同一批量清单内部的重复 output 始终是输入错误, 即使传入 --force 也会失败。
  • 使用 --output-dir 时, 自动生成的输出文件如果已存在, 仍需传入 --force 才能覆盖。
  • 使用 --concat 时, 最终 --output 如果已存在, 仍需传入 --force 才能覆盖。
  • 使用 --output-dir 或 --concat 时, CLI 会拒绝把生成输出写到批量清单, text_file, voice 或 emotion_audio 等受保护输入路径上。
  • 批量合成当前采用失败即停止。没有 --continue-on-error。
  • 如果某条任务在推理阶段失败, 已经生成的前序输出文件不会回滚删除。
  • 批量拼接模式下, 推理失败或拼接失败会默认清理内部临时目录。传入 --keep-temp 时会保留临时目录并把路径写入输出。
  • 成功任务会逐条打印 Generated: <path>。
  • 全部任务成功后打印 Batch complete: <n> tasks generated。
  • 批量拼接成功后只打印最终文件 Generated: <path>, 不逐条打印临时片段。
  • 与具体行相关的错误会包含批量清单中的 1-based 行号。

批量情感字段

命令行可以提供公共默认值:

bash
indextts2 batch --batch-file examples/batch/demo.jsonl --voice examples/voice_01.wav --emotion-text "warm and calm" --emotion-weight 0.6

批量清单每行可以用同名 snake_case 字段覆盖命令级默认值:

  • 命令级 --voice 对应逐行 voice。
  • 命令级 --emotion-audio 对应逐行 emotion_audio。
  • 命令级 --emotion-text 对应逐行 emotion_text。
  • 命令级 --emotion-vector 对应逐行 emotion_vector。
  • 命令级 --emotion-weight 对应逐行 emotion_weight。

情感规则:

  • emotion_audio, emotion_text 和 emotion_vector 是互斥的情感来源, 每行最多提供一种。
  • 如果一行没有情感来源字段, 会继承命令级情感来源。
  • 如果一行提供了情感来源字段, 该行会覆盖命令级情感来源。
  • 如果一行没有 emotion_weight, 会继承命令级 --emotion-weight, 默认是 1.0。
  • 如果一行只提供 emotion_weight, 它会继承命令级情感来源并只覆盖强度。
  • 如果没有命令级情感来源, 单独提供逐行 emotion_weight 是输入错误。
  • 如果没有任何情感来源, 当前行为与 synth 一致, 情感跟随 voice 参考音频。

批量清单中的 emotion_vector 接受两种格式:

jsonl
{"text": "JSON array 格式。", "voice": "../voice_01.wav", "emotion_vector": [0, 0, 0.8, 0, 0, 0, 0, 0], "output": "out/vector-array.wav"}
{"text": "CLI 字符串格式。", "voice": "../voice_01.wav", "emotion_vector": "0,0,0.8,0,0,0,0,0", "output": "out/vector-string.wav"}

emotion_vector 的顺序和校验规则与 synth --emotion-vector 相同: 必须正好 8 个数字, 每个值在 0.0..1.0 范围内, 总和必须小于等于 0.8。

已有 WAV 拼接

indextts2 concat 用于拼接已经存在的 WAV 文件。它不会加载模型, 也不会执行 TTS 推理。它只读取拼接清单, 校验每个 WAV 片段, 再按清单顺序写出一个新的 WAV 文件。

基本命令

只校验拼接清单, 不创建输出文件:

bash
indextts2 concat --concat-file examples/batch/concat-audio.jsonl --output examples/batch/out/emotion_joined.wav --dry-run

--dry-run 成功时输出:

text
Concat file OK: 2 segments

真实拼接:

bash
indextts2 concat --concat-file examples/batch/concat-audio.jsonl --output examples/batch/out/emotion_joined.wav

成功时输出:

text
Generated: <resolved-output.wav>

默认不覆盖已有输出。如需覆盖, 加 --force:

bash
indextts2 concat --concat-file examples/batch/concat-audio.jsonl --output examples/batch/out/emotion_joined.wav --force

JSON Lines 拼接清单

拼接清单每个非空行是一条 JSON object。空行会被忽略, 不计入片段数。当前不支持注释行或行内注释。

示例 examples/batch/concat-audio.jsonl:

jsonl
{"audio": "../emo_hate.wav", "silence_after_ms": 300}
{"audio": "../emo_sad.wav", "silence_after_ms": 500}

每行支持的字段:

字段必填说明
audio是待拼接 WAV 文件路径。
silence_after_ms否当前片段后追加的静音毫秒数, 必须是非负整数, 默认 0。

规则:

  • 未知字段会报错。
  • audio 必须是非空字符串, 并且扩展名必须是 .wav, 大小写不敏感。
  • audio 相对路径按拼接清单文件所在目录解析。
  • --concat-file 和 --output 相对路径按当前工作目录解析。
  • --output 必须是 .wav 文件, 不能与 --concat-file 相同, 也不能与任何 audio 输入相同。
  • 清单必须至少包含一个片段。
  • 每个输入 WAV 必须存在, 可读取, 且至少包含一个音频帧。
  • 所有输入 WAV 的采样率, 声道数和采样宽度必须一致。
  • 拼接时会保留清单顺序, 并在每个片段后追加 silence_after_ms 指定的静音。

运行参数

单条合成示例:

bash
indextts2 synth --text "运行参数示例。" --voice examples/voice_01.wav --output outputs/runtime.wav --device cuda:0 --fp16 --deepspeed --cuda-kernel --verbose

批量合成示例:

bash
indextts2 batch --batch-file examples/batch/demo.jsonl --voice examples/voice_01.wav --device cuda:0 --fp16 --deepspeed --cuda-kernel --verbose

批量合成后拼接示例:

bash
indextts2 batch --batch-file examples/batch/batch-concat.jsonl --voice examples/voice_01.wav --concat --output examples/batch/out/story.wav --device cuda:0 --fp16

参数说明:

参数说明
--model-dir PATH本次运行使用的模型资源目录, 覆盖 INDEXTTS2_MODEL_DIR, 持久化配置和平台默认值。
--device DEVICE本次运行设备, 例如 cpu, cuda, cuda:0, mps, xpu; 未传时可使用持久化配置 default_device。
--fp16 / --no-fp16本次运行是否启用 FP16 半精度推理; 未传时可使用持久化配置 use_fp16。
--deepspeed / --no-deepspeed本次运行是否启用 DeepSpeed; 未传时可使用持久化配置 use_deepspeed。
--cuda-kernel / --no-cuda-kernel本次运行是否启用 CUDA kernel 路径; 未传时可使用持久化配置 use_cuda_kernel。
--verbose显示模型运行输出, 并向 IndexTTS2.infer 传入 verbose=True。

默认情况下, CLI 会隐藏模型初始化和推理过程中的普通标准输出。synth 成功后打印 Generated: <path>; batch 每条成功任务打印 Generated: <path>, 全部成功后再打印 Batch complete: <n> tasks generated。需要调试时使用 --verbose。

concat 不加载模型, 因此不支持 --model-dir, --device, --fp16, --deepspeed, --cuda-kernel 或 --verbose。

参数速查

indextts2 init

参数必填默认值说明
--model-dir PATH否平台默认模型资源目录创建本地状态并把模型资源目录写入持久化配置。

indextts2 config

命令说明
indextts2 config path输出持久化配置文件位置。
indextts2 config get输出当前持久化配置。
indextts2 config set KEY VALUE写入一个配置值。KEY 可为 model_dir, default_device, use_fp16, use_deepspeed, use_cuda_kernel。

indextts2 download

参数必填默认值说明
`--source huggingfacemodelscope`否huggingface
--model-dir PATH否解析后的模型资源目录下载目标目录。成功后默认写入持久化配置。
--no-save否False与 --model-dir 一起使用时, 禁止下载成功后写回 model_dir。

indextts2 check

参数必填默认值说明
--model-dir PATH否解析后的模型资源目录本次检查使用的 IndexTTS2 模型资源目录。
--device DEVICE否无要求可用的运行设备, 例如 cuda:0。

indextts2 synth

参数必填默认值说明
--text TEXT三选一无直接传入待合成文本。
--text-file PATH三选一无从 UTF-8 文本文件读取待合成文本。
--stdin三选一False从标准输入读取待合成文本。
--voice PATH是无音色参考音频路径。
--emotion-audio PATH否无情感参考音频路径, 与 --emotion-vector 和 --emotion-text 互斥。
--emotion-text TEXT否无情感描述文本, 与 --emotion-vector 和 --emotion-audio 互斥。
--emotion-vector VECTOR否无8 维情感向量, 支持逗号分隔或带方括号的列表格式, 与其他情感来源互斥。
--emotion-weight FLOAT否1.0情感权重, 映射到 emo_alpha, 可缩放情感向量强度。
--output PATH是无输出音频路径。
--force否False允许覆盖已有输出文件。
--model-dir PATH否解析后的模型资源目录本次合成使用的 IndexTTS2 模型资源目录。
--device DEVICE否持久化配置或无运行设备。
--fp16 / --no-fp16否持久化配置或 False启用或禁用 FP16 推理。
--deepspeed / --no-deepspeed否持久化配置或 False启用或禁用 DeepSpeed。
--cuda-kernel / --no-cuda-kernel否持久化配置或 False启用或禁用 CUDA kernel。
--verbose否False显示详细运行输出。

indextts2 batch

参数必填默认值说明
--batch-file PATH是无JSON Lines 批量清单路径。
--dry-run否False只校验批量清单和模型资源, 不加载模型, 不生成音频。
--output-dir PATH否无自动命名输出目录。传入后清单中不能提供逐行 output。
--output-prefix TEXT否无自动命名输出文件前缀, 需与 --output-dir 一起使用。
--concat否False合成后拼接为一个最终 WAV 文件。
--output PATH--concat 模式必填无拼接模式的最终 WAV 输出路径。只可与 --concat 一起使用。
--keep-temp否False拼接模式下保留内部临时 WAV 片段目录。
--voice PATH否无每条任务的默认音色参考音频, 可被逐行 voice 覆盖。
--emotion-audio PATH否无默认情感参考音频, 与 --emotion-vector 和 --emotion-text 互斥。
--emotion-text TEXT否无默认情感描述文本, 与 --emotion-vector 和 --emotion-audio 互斥。
--emotion-vector VECTOR否无默认 8 维情感向量, 支持逗号分隔或带方括号的列表格式, 与其他情感来源互斥。
--emotion-weight FLOAT否1.0默认情感权重, 可被逐行 emotion_weight 覆盖。
--force否False允许覆盖批量运行开始前已经存在的输出文件。
--model-dir PATH否解析后的模型资源目录本次批量合成使用的 IndexTTS2 模型资源目录。
--device DEVICE否持久化配置或无运行设备。
--fp16 / --no-fp16否持久化配置或 False启用或禁用 FP16 推理。
--deepspeed / --no-deepspeed否持久化配置或 False启用或禁用 DeepSpeed。
--cuda-kernel / --no-cuda-kernel否持久化配置或 False启用或禁用 CUDA kernel。
--verbose否False显示详细运行输出。

indextts2 concat

参数必填默认值说明
--concat-file PATH是无JSON Lines 拼接清单路径。
--output PATH是无拼接后的 WAV 输出路径。
--force否False允许覆盖已有输出文件。
--dry-run否False只校验拼接清单和输入 WAV, 不生成输出音频。

返回码

返回码含义常见场景
0成功初始化完成, 配置更新, 下载检查通过, 环境检查通过或合成成功。
1输入错误文本来源不唯一, 文本为空, 缺少 --output, 输出已存在但未传 --force, 情感参数冲突, 批量清单字段错误, 拼接清单字段错误, WAV 格式不匹配。
2本地资源缺失模型资源目录不存在, 必需模型资源缺失, 文本文件不存在, 音色参考音频不存在, 情感参考音频不存在, 批量清单不存在, 拼接清单不存在, 拼接音频不存在。
3运行环境不可用必需 Python 包缺失, 下载源 Python 包缺失, 指定设备不可用, IndexTTS2 runtime 导入失败。
4推理或拼接失败模型初始化, infer 执行或 WAV 写入替换过程中抛出异常。批量合成会停在第一条失败任务。

错误信息写入 stderr, 成功信息写入 stdout。

常见错误

文本来源冲突:

text
ERROR: provide exactly one text source: --text, --text-file or --stdin

处理方式: 只保留 --text, --text-file, --stdin 中的一个。

模型资源目录不存在:

text
ERROR: model directory does not exist: <resolved-model-resource-directory>
Model directory: <resolved-model-resource-directory>
Missing resources: model directory does not exist
Download with HuggingFace:
  huggingface-cli download IndexTeam/IndexTTS-2 --local-dir "<resolved-model-resource-directory>"
Download with ModelScope:
  modelscope download --model IndexTeam/IndexTTS-2 --local_dir "<resolved-model-resource-directory>"
Persist a different model resource directory:
  indextts2 config set model_dir <resolved-model-resource-directory>
Hint: rerun indextts2 download or choose a different model resource directory.

处理方式: 按输出中的目标目录下载模型资源。推荐先使用 CLI 下载:

bash
indextts2 download --model-dir <resolved-model-resource-directory>

如果模型资源已经在其他目录, 写入持久化配置:

bash
indextts2 config set model_dir <existing-model-resource-directory>

模型资源缺失:

text
ERROR: missing required model files: bpe.model, gpt.pth
Model directory: <resolved-model-resource-directory>
Missing resources: bpe.model, gpt.pth
Download with HuggingFace:
  huggingface-cli download IndexTeam/IndexTTS-2 --local-dir "<resolved-model-resource-directory>"
Download with ModelScope:
  modelscope download --model IndexTeam/IndexTTS-2 --local_dir "<resolved-model-resource-directory>"
Persist a different model resource directory:
  indextts2 config set model_dir <resolved-model-resource-directory>
Hint: rerun indextts2 download or choose a different model resource directory.

处理方式: 重新运行 indextts2 download --model-dir <resolved-model-resource-directory> 补齐资源, 或使用 indextts2 config set model_dir <existing-model-resource-directory> 指向已有完整模型资源目录, 然后重新运行 indextts2 check。

输出文件已存在:

text
ERROR: output file already exists: outputs/hello.wav

处理方式: 更换 --output 路径, 或确认可覆盖后加 --force。

情感向量数量错误:

text
ERROR: --emotion-vector must contain exactly 8 values; got 7

处理方式: 按高兴, 愤怒, 悲伤, 害怕, 厌恶, 忧郁, 惊讶, 平静的顺序传入 8 个数字。

批量清单字段错误:

text
ERROR: batch file line 2 has unknown fields: prompt_audio

处理方式: 使用 voice, emotion_audio, emotion_text, emotion_vector 等 CLI v2 字段名, 不要使用底层 API 或旧样例字段名。

批量输出重复:

text
ERROR: batch file line 3 has duplicate output path: examples/batch/out/001.wav

处理方式: 为同一批量清单中的每条任务设置不同的 output。--force 不允许批次内部互相覆盖。

批量拼接清单包含逐行输出:

text
ERROR: batch file line 1 field 'output' is not allowed with --concat

处理方式: 使用 --concat --output final.wav 指定最终输出, 并从批量清单中删除逐行 output。

未开启批量拼接却提供静音字段:

text
ERROR: batch file line 1 field 'silence_after_ms' is only valid with --concat

处理方式: 删除 silence_after_ms, 或在命令中加入 --concat --output final.wav。

拼接清单中的 WAV 格式不一致:

text
ERROR: concat file line 2 WAV format does not match baseline line 1

处理方式: 确认所有输入 WAV 的采样率, 声道数和采样宽度一致后再拼接。

拼接输出已存在:

text
ERROR: output file already exists: examples/batch/out/emotion_joined.wav

处理方式: 更换 --output 路径, 或确认可覆盖后加 --force。

设备不可用:

text
ERROR: requested device is not available: cuda:0

处理方式: 使用 indextts2 check 查看当前设备可用性, 或改用 --device cpu。如果希望长期使用某个设备, 可写入持久化配置:

bash
indextts2 config set default_device cuda:0

下载源 Python 包缺失:

text
ERROR: runtime unavailable for huggingface download source: No module named 'huggingface_hub'
Install download support with: pip install huggingface_hub

处理方式: 为当前环境安装提示中的 Python 包, 或改用另一个下载源:

bash
indextts2 download --source modelscope

推荐工作流

普通用户首次运行:

bash
indextts2 init
indextts2 download
indextts2 check
indextts2 synth --text "你好, IndexTTS2。" --voice examples/voice_01.wav --output outputs/hello.wav

使用已有模型资源目录:

bash
indextts2 config set model_dir D:/models/IndexTTS-2
indextts2 check

GPU 环境:

bash
indextts2 config set default_device cuda:0
indextts2 config set use_fp16 true
indextts2 check
indextts2 synth --text "GPU 推理测试。" --voice examples/voice_01.wav --output outputs/gpu.wav

一次性覆盖模型资源目录或运行参数:

bash
indextts2 check --model-dir D:/models/IndexTTS-2 --device cuda:0
indextts2 synth --text "GPU 推理测试。" --voice examples/voice_01.wav --output outputs/gpu.wav --device cuda:0 --fp16

调试模型输出:

bash
indextts2 synth --text "调试输出。" --voice examples/voice_01.wav --output outputs/debug.wav --verbose

批量合成:

bash
indextts2 check
indextts2 batch --batch-file examples/batch/demo.jsonl --voice examples/voice_01.wav --dry-run
indextts2 batch --batch-file examples/batch/demo.jsonl --voice examples/voice_01.wav

自动命名批量输出:

bash
indextts2 batch --batch-file examples/batch/auto-output.jsonl --voice examples/voice_01.wav --output-dir examples/batch/out/auto --dry-run
indextts2 batch --batch-file examples/batch/auto-output.jsonl --voice examples/voice_01.wav --output-dir examples/batch/out/auto --output-prefix chapter

批量合成后拼接:

bash
indextts2 batch --batch-file examples/batch/batch-concat.jsonl --voice examples/voice_01.wav --concat --output examples/batch/out/story.wav --dry-run
indextts2 batch --batch-file examples/batch/batch-concat.jsonl --voice examples/voice_01.wav --concat --output examples/batch/out/story.wav

拼接已有 WAV:

bash
indextts2 concat --concat-file examples/batch/concat-audio.jsonl --output examples/batch/out/emotion_joined.wav --dry-run
indextts2 concat --concat-file examples/batch/concat-audio.jsonl --output examples/batch/out/emotion_joined.wav

开发和调试 CLI v2:

bash
python -m indextts.cli_v2 --help
python -m indextts.cli_v2 check