前言¶
在 DSH Host 的开发场景中，文字转语音（TTS）通常需要绑定特定的引擎。dsh-tts 插件将这一逻辑拆分，专注于“合成”与“时间戳”的计算，将音频引擎（如微软 Edge 或本地命令行工具）留作外部依赖。它不负责决策哪条音频好听或如何拼接，只产出文件与数字，供调用方处理。
核心功能¶
插件提供三个主要工具，覆盖从合成到检查的全流程：
1、tts_speak：支持 speak（单段文字）和 dialogue（多人脚本）两种模式。speak 输出音频与逐词时间戳侧车文件；dialogue 则生成 manifest 与全局词级时间戳。
2、tts_setup：提供 status、voices、check 三个 action。用于检查引擎可用性、枚举音色列表以及合成一句自检。
3、tts_guide：提供 overview、tool、action、rules 四个 action。用于读取完整的参考文档，包括参数说明、实测数据与边界情况。
提供商与配置¶
插件支持两种 provider，通过配置选择：
1、edge（默认）：基于微软 Edge 朗读端点。无需 Key，依赖网络，且提供逐词时间戳（服务端 WordBoundary）。本机实测包含 322 个音色，其中中文（zh）开头的 14 个。
2、command：本地 TTS 命令行引擎。无需网络，引擎换代无需修改插件。使用模板占位符来传递参数，如 {out}、{text}、{timings} 等。
command 配置示例¶
command:
path: 'C:/tools/piper/piper.exe'
args: ['--model', 'C:/tools/piper/zh_CN-huayan-medium.onnx', '--output_file', '{out}']
textMode: 'stdin'
outFormat: 'wav'
voices: ['zh_CN-huayan-medium']
安装与启用¶
安装无需构建步骤，直接在 profile 中通过 link: 挂载即可。
- insert:
- id: dsh-tts
name: 'dsh-tts'
config: { provider: null, outDir: null, ffprobePath: null, edge: { voice: null }, command: null }
默认情况下，edge provider 可用即用。如果未配置本地引擎，tts_setup 会如实报告。
典型用法¶
使用 Node.js 运行 src/bin/tts.mjs：
1、检查环境与 ffprobe：
node src/bin/tts.mjs doctor
2、查看中文音色列表：
node src/bin/tts.mjs voices --locale zh
3、合成一段文字：
node src/bin/tts.mjs say "要念的话" --out a.mp3
4、检查合成质量（含尾部静音）：
node src/bin/tts.mjs check
5、多人对话脚本合成：
node src/bin/tts.mjs dialogue --script s.txt --voices host-a=...,host-b=...
6、查看规则文档：
node src/bin/tts.mjs rules
输出与契约¶
一次合成会生成两个文件：音频文件与同名的 .words.json 侧车文件。words 数组包含逐词的文本、起止时间，可直接供下游字幕流程（如 video_narrate）读取。
在 dialogue 模式下，除上述侧车文件外，还会生成 dialogue.manifest（包含 clips 与 verification）和 dialogue.words.json。verification 用于校验音频片段是否在文件边界内，其值为 true（已测量且在文件内）、false（超出）或 null（未测量）。
注意事项¶
1、商用授权：edge provider 的商用授权未明确，建议仅用于草稿与个人内容；如需商用，请切换至 command provider 并使用明确授权的本地引擎。
2、本地引擎限制：纯 Node 的本地引擎中文词级时间戳暂无现成方案；本地引擎速度约为 1.1x 实时，中文合成需要借助 Python 侧工具包。
3、集成依赖：video_narrate 对 dsh-video-audio 的集成依赖尚未重建（截至 2026-10-04），目前无法通过标准流程流转。
