Skip to content

feat(tts): 科普视频管线支持 IndexTTS-2.5 声音克隆配音（双引擎 + 风格控制 + 操作手册） - #1104

Merged
ThreeFish-AI merged 7 commits into
feature/1.x.xfrom
ThreeFish-AI/tts-voice-clone-index
Aug 17, 2026
Merged

feat(tts): 科普视频管线支持 IndexTTS-2.5 声音克隆配音（双引擎 + 风格控制 + 操作手册）#1104
ThreeFish-AI merged 7 commits into
feature/1.x.xfrom
ThreeFish-AI/tts-voice-clone-index

Conversation

@ThreeFish-AI

@ThreeFish-AI ThreeFish-AI commented Aug 17, 2026

Copy link
Copy Markdown
Owner

概述

科普视频管线（media/pipeline/）新增用自己的声音配音能力：通过本地部署 IndexTTS-2.5 零样本克隆用户音色，并支持轻快 / 自信 / 正能量等风格控制。edge-tts 无法克隆声音（仅微软预置音色），故保留为默认引擎（行为字节级不变），新增 --engine indextts 声音克隆模式。

调研结论（多方案对比）

方案 声音克隆 风格控制 Mac 部署 结论
edge-tts（现状） ❌ 仅预置 仅 rate 无需 默认引擎，零成本回退
IndexTTS-2.5 ✅ 单样本零样本 ✅ 8 维情感向量 + 强度 + 语速 ✅ MPS fp32（v2 构造器无 use_fp16，源码核实） 主方案
IndexTTS-2 ✅ ✅ 向量（无语速） ✅ fp16 成熟 服务端 --indextts-version 2 一键回退
mlx-indextts / GPT-SoVITS / CosyVoice 2 / 云端 — — — 手册 §九 对比说明，不落地

架构

管线轻依赖与重型推理环境完全解耦：tts.py --engine indextts（stdlib urllib 客户端，零新增依赖）→ HTTP → 本地 tts_server.py（FastAPI，运行于仓库外 ~/tools/index-tts 的 uv 环境内，模型常驻 MPS 串行推理）→ MP3。下游契约零改动：输出仍为 {id}.mp3 + manifest.json，Remotion 时间轴/字幕/抽帧 QA 自动适配。

改动清单

  • media/pipeline/scripts/tts.py — 双引擎改造；edge 路径 digest 公式/CLI/manifest 序列化字节级不变；indextts 路径含缓存摘要（engine_tag/ref_sha1/style/vec/alpha/df/lang）、4xx 不可重试、5xx 指数退避
  • media/pipeline/scripts/tts_server.py — 新增；lifespan 模型常驻、串行推理锁、NaN 后置检测、soundfile→lameenc MP3 编码链、v2/v2.5 双版本
  • media/pipeline/scripts/prepare_ref.py — 新增；长录音裁剪/峰值归一化为 5–15s 干净 16-bit 单声道 WAV
  • media/pipeline/VOICE-CLONING.md — 新增九节操作手册（部署/录音/风格调参/排障/许可/备选对比 + IEEE 引用）
  • media/pipeline/voices/ — 样本目录约定 + 隐私规范；根 .gitignore 目录级忽略个人声纹
  • media/pipeline/README.md / docs/.agents/knowledge-map.md — 脚本表、引擎说明、许可、索引同步

风格预设（8 维情感向量，双端校验有效和 ≤0.8）

预设 向量 alpha 语速
neutral 中性（默认） 不注入 — 1.0
lively 轻快 happy .55 + surprised .15 + calm .15 0.6 0.95
confident 自信 calm .65 + happy .25 0.7 1.05
positive 正能量 happy .75 + calm .20 0.7 1.0

E2E 验证（本机 M4/24GB 实测）

  • ✅ 部署：index-tts clone + uv sync + 模型下载（HF 主权重 + ModelScope 补齐 gpt/codec + 首跑自动下载辅助模型）
  • ✅ Server：/health → {version: 2.5, device: mps, dtype: fp32, encoder: soundfile}；单句冒烟 MP3 时长与 X-Duration-Sec 头一致（±0.05s）
  • ✅ 用户真实声音样本（me-1.mp3 264s → prepare_ref 裁剪 14s）克隆合成：neutral/lively/confident/positive 四风格各出样本，时长梯度符合风格特征（lively 3.41s < positive 3.51s < neutral 3.78s）
  • ✅ 缓存幂等：同命令重跑 manifest 字节级一致；失败句重跑仅补缺（断点续传）
  • ✅ manifest 契约：键集合 {id, scene, text, durationSec}、顺序、序列化格式与 edge 引擎完全一致
  • ✅ edge 回归：digest 公式与历史逐字一致（sidecar 比对 MATCH）；CLI 向后兼容
  • ✅ 草渲冒烟：完整 P0 幕（15 句）→ 2403 帧 → draft.mp4 4.4MB
  • ✅ 参数矩阵：--list-styles、互斥校验、缺 ref 报错、服务未启动友好指引、NaN/Inf/有效和拦截
  • ✅ 代码审查（对抗验证）2 Critical + 6 Warning 全部修复：--device auto 崩溃、向量校验语义（改为有效和 Σvec×alpha≤0.8，对齐 v2.5 源码 alpha 缩放行为）、dtype 误报、摘要精度、尾斜杠 URL、422 详情解析、负数 start、gitignore 漏网格式、knowledge-map 措辞回退

回归定义：edge 模式不要求全新合成 mp3 字节一致（网络合成非确定性）；契约 = CLI 兼容 + digest 不变 + 缓存命中时 manifest 字节一致 + 形状不变。

许可

IndexTTS-2.5 按 bilibili Model Use License 发布（个人/研究可用，商用联系 indexspeech@bilibili.com）；个人声纹样本已被 gitignore 隔绝入库。

🤖 Generated with Claude Code, CodeX, Gemini

@ThreeFish-AI
feat(tts): 科普视频管线支持 IndexTTS-2.5 声音克隆双引擎配音;
ff9f765 
- tts.py 双引擎改造：edge（默认，digest/CLI/manifest 字节级不变）+ indextts（HTTP 客户端逐句克隆合成）；
- 新增 tts_server.py：运行于 index-tts checkout 环境的 FastAPI 推理服务（lifespan 模型常驻、串行锁、v2/v2.5 双版本、NaN 后置检测、soundfile→lameenc MP3 编码链）；
- 新增 prepare_ref.py：长录音裁剪/归一化为 5–15s 干净 16-bit 单声道参考样本；
- 风格预设（中性/轻快/自信/正能量）映射 8 维情感向量 + emo_alpha + duration_factor，双端校验（非负有限值 + 有效和 ≤0.8）；
- 缓存摘要覆盖 engine_tag/ref_sha1/style/vec/alpha/df/lang，4xx 不可重试、5xx 指数退避重试；

🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist)
Co-Authored-By: Aurelius Huang<threefish.ai@gmail.com>
@ThreeFish-AI
docs(pipeline): 新增声音克隆操作手册 VOICE-CLONING.md 并同步索引;
32febc1 
- VOICE-CLONING.md 九节操作手册：部署（磁盘预算/断点续传/下载假死处置）/参考样本录制要求/风格预设与调参/逐集使用/缓存幂等语义/MPS 排障/bilibili 许可边界/备选方案对比 + IEEE 引用；
- voices/README.md：样本目录约定与隐私提醒；根 .gitignore 目录级忽略个人声纹（仅白名单 README）；
- media/pipeline/README.md：脚本表补 tts_server/prepare_ref、§五 引擎可选说明、§八 许可补充；
- knowledge-map：管线条目追加声音克隆手册链接；

🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist)
Co-Authored-By: Aurelius Huang<threefish.ai@gmail.com>
@ThreeFish-AI
fix(tts): indextts 客户端并发降为 1 并提升超时，消除排队超时根因;
b70afc3 
- CONCURRENCY_INDEXTTS 2→1：服务端为串行推理锁，>1 的并发请求在锁后排队，排队时长计入客户端 HTTP 超时，长句场景连续超时（实测 p0-08/p0-12/p0-12b 三次命中）；
- HTTP_TIMEOUT 300→600：覆盖 MPS fp32 长句（33 字句实测可达 5 分钟）；
- 手册 §五 同步并发语义说明；

🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist)
Co-Authored-By: Aurelius Huang<threefish.ai@gmail.com>
@ThreeFish-AI
docs(pipeline): 修正声音克隆手册与 prepare_ref 三处失实声明（评审修订）;
0da1413 
- 渲染命令补 cd video &&（render 脚本定义在 video/package.json，照抄原命令会报 Missing script）
- 故障排查表 HTTP_TIMEOUT 300s→600s 并同步 §五 超时描述（对齐 commit b70afc3 与 tts.py:41）
- 移除 m4a 可转换声明：libsndfile 1.2.2 无 MP4 容器支持，改为注明先经 ffmpeg 转 wav

🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist)
Co-Authored-By: Aurelius Huang<threefish.ai@gmail.com>
@ThreeFish-AI
docs(pipeline): 修正评审指出的三处失实描述与隐性拦截写法;
86b165c 
- VOICE-CLONING.md §4.2 与 tts.py 顶部注释：情感向量约束实为有效和（Σ分量×emo-alpha）≤0.8，
  而非分量总和 ≤0.8（positive 预设总和 0.95 即为反例），补 happy:1.0@alpha=0.6 放行示例；
- tts.py parse_emo_vector：NaN/Inf 拦截改为显式 math.isfinite（与服务端写法对齐，
  拒绝/放行语义经 10 用例回归验证不变）；
- README.md 公共脚本表：prepare_ref.py 无工程薄包装，改为仓库根全路径调用指引。

🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist)
Co-Authored-By: Aurelius Huang<threefish.ai@gmail.com>
@ThreeFish-AI
Merge remote-tracking branch 'origin/feature/1.x.x' into ThreeFish-AI…
84c63bc 
…/tts-voice-clone-index

# Conflicts:
#	.gitignore
#	docs/.agents/knowledge-map.md
@ThreeFish-AI
fix(tts): 评审修订——server 尾斜杠归一收口与情感键重复显式报错;
040fa62 
- --server 尾部斜杠原仅 synthesize 拼接处 rstrip、health 检查拼出 //health 致 404 误报「服务不可用」；改为解析参数后统一归一化一处收口；
- parse_emo_vector 原对重复情感键静默 last-wins 丢弃首个权重；改为显式报「情感键重复」，与未知键/负值/NaN 同级校验。

🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist)
Co-Authored-By: Aurelius Huang<threefish.ai@gmail.com>
@ThreeFish-AI
ThreeFish-AI merged commit 8502a5e into feature/1.x.x Aug 17, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@ThreeFish-AI