安装向导：IndexTTS 2.5 停顿控制补丁

把本文档给任意 AI 助手，它会指导你一步步安装。 （English version: INSTALL_GUIDE_EN.md）

前提：你已经有能正常跑通的官方 IndexTTS 2.5（能打开 webui 并生成音频）。本补丁不改任何官方逻辑，只是在生成后加一个后处理步骤。

0. 一键安装（推荐）

解压本仓库后执行（任意目录均可，脚本会自动探测官方仓库），两个版本二选一：

python install_cpu.py    # CPU 版：零显存占用，后处理每句稍慢 2~5 秒（推荐，稳）
python install_gpu.py    # GPU 版：后处理几乎不减速，额外显存约 1GB（需 NVIDIA + CUDA）

官方仓库不在当前目录附近时：python install_cpu.py D:\你的\官方仓库
指定 Python 解释器（推荐官方 venv）：python install_cpu.py --python D:\官方仓库\.venv\Scripts\python.exe
不要码级检测器组件：python install_cpu.py --no-detector

脚本自动完成：装依赖 → 复制模块 → 生成带 PAUSE_DEVICE 的启动脚本 start_webui.bat → 打补丁（git apply 优先，patch -p1 兜底）→ 冒烟自检。看到"安装完成"后，以后用 start_webui.bat 启动（它自带模式设置）；若你仍用官方原来的启动器，则需手动设环境变量 set PAUSE_DEVICE=cpu（或 cuda）。

GPU 版若启动时报 CUDA 错误，改用 install_cpu.py 重装即可。

下面第 1~6 节是手动方式（脚本失败时备用）。

1. 环境要求

Windows / Linux / macOS 均可；Python 3.10+（用官方仓库自带的虚拟环境最稳）
不需要 GPU（默认 CPU 模式，零显存增量）：whisper base 在 CPU 上即可跑（一段 10 秒音频定位约 2~5 秒）
磁盘：whisper base 模型约 140MB（首次运行自动下载到 ~/.cache/whisper/）
GPU 可选加速：想省时间可设环境变量 PAUSE_DEVICE=cuda（后处理几乎不减速，但 whisper 会额外占约 1GB 显存；检测器 LSTM 仅约 10MB）。默认 CPU 模式，零显存增量。

2. 准备 Python 环境

推荐直接用官方仓库自带的虚拟环境（依赖已兼容）。例如官方仓库目录下：

# Windows（官方整合包/uv 环境示例，按你的实际路径）
.venv\Scripts\python.exe -V
# Linux/macOS
.venv/bin/python -V

没有虚拟环境就建一个：

python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate

3. 安装依赖

pip install openai-whisper pypinyin librosa soundfile

openai-whisper：逐词时间戳定位（首次运行自动下载 base 模型，需联网一次；离线环境可提前把模型文件放到 ~/.cache/whisper/base.pt）
pypinyin：中文同音 fallback（只处理英文可不装，但建议装上）
librosa / soundfile：音频读写与重采样
numpy 会随依赖自动安装
只有用"码级检测器预检"时才需要额外装 torch（官方环境自带）、joblib、scikit-learn——普通用户跳过

4. 放置文件

把本仓库的 pause_control25.py 复制到官方 webui.py 同目录（即官方仓库根目录）。

可选（只有要用"码级检测器预检"时才需要）：把 detector_pause25.py 与整个 models/ 目录也放到同目录。权重默认按相对路径从 models/ 加载（无需改代码）；codec.pth（IndexTTS 2.5 官方权重）会自动从 checkpoints/codec.pth（官方仓库布局）或 models/codec.pth 探测，也可用环境变量 INDEXTTS_CODEC_PATH 显式指定。普通用户跳过这一步。

5. 先跑通核心模块（不打补丁也能验证）

python -c "import pause_control25; print(pause_control25.parse_pause_marks('你好[pause:500ms]世界'))"
# 期望输出：('你好，世界', [(2, 500)])

进一步做全链路自检（可选）：最简单的自检是生成一段带逗号的 wav，然后：

import pause_control25 as pc
pc.process('他推开门[pause:800ms]，屋里一片漆黑。',
           '你的生成.wav', '输出_停顿.wav')
# 英文：pc.process('He paused[pause:800ms], then left.', 'in.wav', 'out.wav', lang='en')

对比两个 wav 的波形/听感：标记处应多出约 800ms 静音。

6. 应用 webui 补丁

补丁基于官方 webui.py（commit a371df7，2026-08-12）。若官方后续更新导致打不上，用下面手动方式插入 7 行即可。

在官方仓库根目录（webui.py 所在处），推荐用 Git Bash（自带 git/patch）：

git apply patch_webui_pause.diff   # 首选（自动处理行尾，可 git apply -R 还原）
# 或：patch -p1 < patch_webui_pause.diff   # 兜底（可能把行尾统一为 LF，不影响运行）

没有 git/patch 就手动改：打开 webui.py，找到 gen_single() 里的

    output = tts.infer(**infer_kwargs)

在它后面插入这 7 行（注意 4 空格缩进，行尾保持与文件其他行一致）：

    # --- pause-control hook: [pause:Nms] waveform post-processing (pause_control25.py) ---
    if output and "[pause:" in (text or ""):
        try:
            import pause_control25
            pause_control25.process(text, output, output)  # in-place: locate + insert silence
        except Exception as e:
            print(f"[pause_control25] failed, keep original audio: {e}")

重启 webui，在文本里写 [pause:800ms] 生成，控制台无 [pause_control25] failed 即成功。

7. 常见问题

控制台打印 failed, keep original audio：读报错信息。常见是缺依赖（回到第 3 步）或 whisper 模型下载失败（检查网络/手动放模型）。
停顿位置偏了：whisper base 对个别字/词识别失败会走 fallback。换 WHISPER_MODEL = 'small'（常量区）更准但更慢。
停顿没生效：确认文本里是 [pause:800ms] 格式（半角方括号、ms 后缀）；确认生成用的是补丁后的 webui（重启过）。
英文文本里出现了全角逗号 ，：模块解析标记时统一替换为 ，。介意的话在生成前把 clean 文本里的 ， 换成 ,，或在调用 process 前自行处理文本；不影响停顿定位。
长停顿后有换气声：已知限制，模型自带的换气不是静音，本工具不处理。
运行变慢了 / CPU 占用高：停顿后处理默认 CPU 计算（不占 GPU 显存），每句约额外 2~5 秒，批量生成时明显，属正常现象。想提速：设环境变量 PAUSE_DEVICE=cuda（几乎不减速，额外显存约 1GB）。
部署在中文路径 / 系统是 GBK 编码：完全支持。分句稿等文本文件无论 UTF-8 还是 GBK（记事本默认）都能自动识别；打补丁请用 git apply 或 patch -p1（见第 6 节）。
检测器预检报"未找到 codec.pth"：按报错提示设置 INDEXTTS_CODEC_PATH 环境变量，或把官方 checkpoints/ 放在 webui.py 同级，或把 codec.pth 复制到 models/。

8. 正在用第三方整合包（yzy / rainfall 等）？

第三方整合包改过官方 webui.py（显存优化/多角色/UI 增强），本补丁针对官方原版生成，可能打不上。两种方案：

方案 A：手动插 7 行（推荐，生成时自动处理）

找到整合包 webui.py 里的生成调用点：搜索 tts.infer(（一般在 gen_single 或类似函数里）
在该调用之后插入 hook（和第 6 节手动方案相同）：

    # --- pause-control hook: [pause:Nms] waveform post-processing (pause_control25.py) ---
    if output and "[pause:" in (text or ""):
        try:
            import pause_control25
            pause_control25.process(text, output, output)  # in-place: locate + insert silence
        except Exception as e:
            print(f"[pause_control25] failed, keep original audio: {e}")

若整合包里变量名不同（如 result = model.infer(...)），把 hook 里的 output 换成实际变量名

方案 B：脚本后处理（完全不碰 webui，最通用）

生成时把文本里的 [pause:N] 手动替换成逗号（或先不写标记生成）
生成后用脚本处理 wav：

import pause_control25 as pc
pc.process('他推开门[pause:800ms]，屋里一片漆黑。',
           '你的生成.wav', '输出_停顿.wav')

把 pause_control25.py 放在 Python 能 import 到的位置（脚本同目录或整合包 python 环境）

方案 B 适合批量/脚本化生成，不依赖任何 webui 改动。

搞不定？

如果实在搞不定，后续会发布免安装整合包（网盘下载），链接见本仓库 Release。

FilesExpand file tree

INSTALL_GUIDE.md

Latest commit

History