前言¶
在 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），目前無法通過標準流程流轉。
