sherpa-tts-server

基于 sherpa-onnx 的 C++17 HTTP TTS 服务，支持普通 WAV 合成与实时 MP3 流式播放。 普通链路使用 POST /tts 并从 /wav/* 获取音频；流式链路使用 POST /tts-stream 创建 播放 URL，由 FreeSWITCH mod_shout 拉取 audio/mpeg。

专题导航

• 配置参考
• HTTP API
• 集成与运行
• callflow-esl TTS 对接
• 全仓服务目录

目录结构

sherpa-tts-server/
├── src/                    # HTTP、TTS、缓存、线程池与 MP3 编码
├── config.json             # 外置配置
├── request-tts.js          # 最小请求客户端
├── build.ps1 / build.sh    # Windows / Linux 构建入口
├── build/                  # 构建目录，不提交
└── target/                 # 可运行安装目录，不提交

构建

Windows PowerShell：

.\build.ps1

等价的核心步骤：

cmake -S . -B build/win_x64 -G "Visual Studio 17 2022" -A x64
cmake --build build/win_x64 --config Release --target sherpa_tts_server
cmake --install build/win_x64 --config Release --prefix target/win_x64

Linux x64：

./build.sh

流式 MP3 需要 ffmpeg；普通 WAV 合成不依赖它。

运行

仓库根目录：

bun run dev:tts

也可进入安装目录直接运行：

cd target\win_x64
.\sherpa_tts_server.exe

服务默认读取模块根目录 config.json。默认监听与健康检查见 服务目录。

配置

启动前至少校准：

• server.listenHost / listenPort / publicBaseUrl：监听与调用方可访问地址。
• server.startupScanCache / maxCacheEntries：启动扫描和 WAV 缓存 LRU 上限。
• concurrency / timeouts / transport：线程池、队列、流式并发和传输限制。
• mp3.encoderPath / bitrateKbps / volumeGainDb：MP3 编码器与输出参数。
• tts.activeModel / tts.models：当前模型与 profile 文件。

字段、默认值、模型后端和切换示例见配置参考。

健康检查

服务启动后请求服务目录列出的健康 URL。响应会报告当前模型、 采样率、说话人、队列与活跃流等信息。若 ffmpeg 探测失败，服务仍可健康启动，但流式 MP3 不可用；日志会明确记录功能受限原因。

最小合成验证

bun run .\request-tts.js "测试语音合成"

或使用 HTTP：

curl -s -X POST http://127.0.0.1:9080/tts \
  -H "Content-Type: application/json" \
  -d '{"text":"测试语音合成","speakerId":0,"speed":1.0}'

确认响应包含 wavUrl，并从 FreeSWITCH 所在主机验证该 URL 可访问。改动流式链路时还需验证 POST /tts-stream、GET /tts-stream/<id>.mp3、Content-Type: audio/mpeg，以及完整 WAV 最终仍落盘。

API

请求字段、响应、缓存语义、状态码和所有端点见HTTP API。

调用示例

Node / Bun、FreeSWITCH 配置、输出目录、并发模型与日志见 集成与运行。

注意事项

• 模型相对路径按配置文件位置解析，缺少模型文件会阻止启动。
• 服务无内置鉴权，建议只部署在可信网络或由反向代理保护。
• 修改 C++ 代码后至少重新构建，并实际验证受影响的 WAV / MP3 链路。
• 任务中启动的服务必须在结束前停止。

跨服务故障从故障排查进入。