mcpField
A
add-tts-engine

add-tts-engine

github.com/jamiepine开发58.9k74 次安装3 周前更新
代码仓库

关于 add-tts-engine

为 Voicebox 添加文本转语音引擎的端到端开发指南，供维护后端、前端和构建流程的开发者使用。内容涵盖依赖审查、引擎接入、PyInstaller 打包及本地验证。

主要功能

  1. 01审查模型库及其依赖
  2. 02实现后端 TTS 协议并注册引擎
  3. 03接入前端选项与语言配置
  4. 04配置依赖和 PyInstaller 打包
  5. 05验证开发模式及冻结构建

适用场景

  1. 01将新模型引擎集成到 Voicebox
  2. 02排查 PyInstaller 构建中的资源或依赖缺失
  3. 03验证模型下载、加载、生成与声音克隆

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/jamiepine/voicebox --skill add-tts-engine

安装后在 Claude Code 中输入/add-tts-engine确认已加载。

详细介绍

添加 TTS 引擎

目标

将新的文本转语音引擎端到端集成到 Voicebox 中：依赖调研、后端协议实现、前端 UI 接入、PyInstaller 打包以及冻结构建验证。用户只需在本地测试最终构建产物即可。

参考文档

完整的分阶段指南位于 docs/content/docs/developer/tts-engines.mdx。开始之前请完整阅读该文件。 其中包含：

  • 阶段 0：依赖调研（编写代码前必须完成）
  • 阶段 1：后端实现（TTSBackend 协议）
  • 阶段 2：路由与服务集成（通常无需改动）
  • 阶段 3：前端集成（5 个文件）
  • 阶段 4：依赖（requirements.txt、justfile、CI、Docker）
  • 阶段 5：PyInstaller 打包（build_binary.py + server.py）
  • 阶段 6：常见上游变通方案
  • 实施检查清单（各阶段之间的关卡）

工作流

1. 阅读指南
# Read the full TTS engines doc
cat docs/content/docs/developer/tts-engines.mdx

深入理解所有阶段，尤其是阶段 0 和阶段 5。v0.2.3 版本之所以连续发布了三个补丁版本，就是因为跳过了阶段 0。

2. 依赖调研（阶段 0）

将模型库克隆到临时目录并进行审查。切勿跳过此步骤。

mkdir /tmp/engine-research && cd /tmp/engine-research
git clone <model-library-url>

对克隆的源码及其传递依赖运行指南中阶段 0.2 的 grep 搜索。产出一份书面的依赖审查报告，涵盖：

  1. PyPI 与非 PyPI 包
  2. 所需的 PyInstaller 指令（--collect-all、--copy-metadata、--hidden-import）
  3. 必须打包的运行时数据文件
  4. 在冻结构建中需要通过环境变量覆盖的原生库路径
  5. 所需的 Monkey patch（torch.load、float64、MPS、HF token）
  6. 采样率
  7. 模型下载方式（from_pretrained 与 snapshot_download + from_local）

在继续之前，先在一次性 venv 中于 CPU 上测试模型加载与生成。

3. 实现（阶段 1–4）

按顺序遵循指南中的各阶段。需要修改的关键文件：

后端（阶段 1）：

  • 创建 backend/backends/<engine>_backend.py
  • 在 backend/backends/__init__.py 中注册（ModelConfig + TTS_ENGINES + factory）
  • 更新 backend/models.py 中的正则表达式

前端（阶段 3）：

  • app/src/lib/api/types.ts — 引擎联合类型
  • app/src/lib/constants/languages.ts — ENGINE_LANGUAGES
  • app/src/components/Generation/EngineModelSelector.tsx — ENGINE_OPTIONS、ENGINE_DESCRIPTIONS
  • app/src/lib/hooks/useGenerationForm.ts — Zod schema、模型名称映射
  • app/src/components/ServerSettings/ModelManagement.tsx — MODEL_DESCRIPTIONS

依赖（阶段 4）：

  • backend/requirements.txt
  • justfile（setup-python、setup-python-release 目标）
  • .github/workflows/release.yml
  • Dockerfile（如适用）
4. PyInstaller 打包（阶段 5）

在 backend/build_binary.py 中注册该引擎：

  • 为后端模块和模型包添加 --hidden-import
  • 为使用 inspect.getsource、附带数据文件或原生库的包添加 --collect-all
  • 为使用 importlib.metadata 的包添加 --copy-metadata

如果该引擎有原生数据路径，请在 backend/server.py 的 if getattr(sys, 'frozen', False): 块内添加 os.environ.setdefault()。

5. 在开发模式下验证
just dev

测试完整链路：模型下载 → 加载 → 生成 → 声音克隆。

6. 使用检查清单

逐项检查 tts-engines.mdx 底部的实施检查清单。在将构建产物交给用户之前，必须勾选每一项。

关键经验（来自 v0.2.3）

这些是最常见的失败模式。阶段 0 研究会捕获所有这些问题：

模式冻结构建中的症状修复
@typechecked / inspect.getsource()“could not get source code”--collect-all <package>
包附带预训练模型文件.pth.tar、.yaml 的 FileNotFoundError--collect-all <package>
硬编码系统路径的 C 库/usr/share/... 的 FileNotFoundError--collect-all + server.py 中的环境变量
importlib.metadata.version()“No package metadata found”--copy-metadata <package>
不带 map_location 的 torch.loadCPU 构建上 CUDA 设备不可用猴子补丁 torch.load
对 float64 数据调用 torch.from_numpydtype 不匹配 RuntimeError转换为 .float()
HF 下载调用中的 token=True未存储 HF token 时认证失败使用 snapshot_download(token=None) + from_local()

注意事项

  • 路由层和服务层没有任何按引擎分发的分派点。main.py 无需任何改动。
  • backends/__init__.py 中的模型配置注册表自动处理所有分派。
  • 使用 backends/base.py 中的 get_torch_device() 和 model_load_progress()——不要重新实现设备检测或进度跟踪。
  • 始终使用干净的 HuggingFace 缓存进行测试（没有来自开发环境的预下载模型）。
  • 不要推送或创建发布。将构建交给用户进行本地测试。

评论

支持 Markdown