TTS 服务（sherpa-tts-server）

服务定位

sherpa-tts-server 是一个 C++ HTTP TTS 服务，基于 sherpa-onnx 离线 VITS 模型（vits-zh-aishell3）。直接调用仓库内 sherpa-onnx 预编译库，合成 wav 后落盘并通过 HTTP 暴露下载 URL。

设计目标：

• 固定大小 HTTP worker 线程池
• 多实例 OfflineTts 池并行合成
• 同 text + speakerId + speed 的请求去重：in-flight 共享 + 文件级缓存
• GET /wav/... 流式发送，避免大文件占内存
• HEAD /wav/... 支持，便于 FreeSWITCH playback 拉取前预检
• 启动时可选扫描 public/wav/ 重建文件索引

面向 callflow-esl 的 ctx.speak({ kind: "tts" }) 场景，但接口本身是通用 HTTP。

构建与运行

1
2
3
4
5

cd sherpa-tts-server
.\build.ps1
# 等价于：
# cmake -S . -B build -G "Visual Studio 17 2022" -A x64
# cmake --build build --config Release --target sherpa_tts_server

启动：

1
2
3
4

cd .\build\Release
.\sherpa_tts_server.exe
# 或显式指定配置：
# .\sherpa_tts_server.exe C:\path\to\config.json

模型目录解析顺序：

1. 当前工作目录的上三级 ../../../models（典型 build/Release 启动场景）
2. 否则回退到当前工作目录下的 ./models

只要找到 models/vits-zh-aishell3/ 即可启动。

依赖文件：

• vits-aishell3.onnx
• tokens.txt
• lexicon.txt

三个 HTTP 端点

所有响应带 Connection: close，错误统一 JSON：

1

{ "error": "<message>" }

POST /tts

请求：

1
2
3

curl -s -X POST http://127.0.0.1:9080/tts \
  -H "Content-Type: application/json" \
  -d '{"text":"欢迎进入会议","speakerId":0,"speed":1.0}'

成功响应（HTTP 200）：

1
2
3
4
5
6

{
  "wavUrl": "http://127.0.0.1:9080/wav/tts-3a1c7b9eaf0c1d72.wav",
  "fileName": "tts-3a1c7b9eaf0c1d72.wav",
  "sampleRate": 16000,
  "cached": false
}

错误响应：

缓存与去重

服务按以下 key 做 FNV-1a 64bit 哈希得到 tts-<16hex>.wav：

1

vits-zh-aishell3 | sid=<speakerId> | speed=<speed.fixed3> | text=<text>

同样的 {text, speakerId, speed} 永远命中同一文件：

1. 进程内已知 → 直接返回 cached=true
2. in-flight 合成中 → 共享同一个 future，等待其他请求完成后一起返回
3. 否则 → 当前请求成为 owner，调用 OfflineTtsWorker 实际生成

GET /wav/<fileName>

1
2
3
4
5
6

HTTP/1.1 200 OK
Content-Type: audio/wav
Content-Length: <bytes>
Connection: close

<wav binary stream，按 wavSendChunkBytes 分块发送>

约束：

• fileName 只取 path::filename，禁止 ..，否则 400
• 不在缓存索引中返回 404
• 仅返回 Content-Length 头，不支持 Range / 多段断点续传

HEAD /wav/<fileName>

与 GET 完全一致的状态码和头部，但不返回 body。FreeSWITCH playback 拉取 wav URL 时通常会先做 HEAD 检查，文件不存在直接放弃，避免下载半截。

关键配置

并发模型

1
2
3
4
5
6
7
8
9
10
11
12
13

accept thread (单线程)
   │
   ▼
   queue_  ────►  worker[0..workerThreads-1]
                     │ 解析 HTTP、路由
                     ▼
                  TtsService::Synthesize
                     │
                     ▼ Acquire / Release
                  OfflineTtsPool (ttsPoolSize 实例)
                     │
                     ▼
                  Generate + WriteWave

并发吞吐主要取决于：

• ttsPoolSize：实际并行合成度
• 模型本身的 RTF（输出 rtf= 日志可对比）
• workerThreads：HTTP 处理线程数，通常 >= ttsPoolSize 即可

缓存命中 / in-flight 复用时不占 TTS 实例，只做 I/O。

与 FreeSWITCH 集成

callflow-esl 配置：

1
2
3
4
5
6
7
8

{
  "tts": {
    "sherpaHttpEndpoint": "http://127.0.0.1:9081/tts",
    "playbackTarget": "wav-url",
    "speakerId": 0,
    "speed": 1
  }
}

业务调用 ctx.speak({ kind: "tts", text: "..." }) 时，runtime：

1. POST /tts 拿到 wavUrl
2. 通过 ESL 下发 playback shout://<wavUrl>（或本地路径，见下面 playbackTarget）

playbackTarget 两种模式

publicBaseUrl 在远端 FS 场景下的注意点

调用示例

curl

1
2
3

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

Node / Bun

仓库内 request-tts.js：

1
2
3

bun run .\request-tts.js
bun run .\request-tts.js "测试语音合成"
bun run .\request-tts.js "测试语音合成" http://127.0.0.1:9080/tts

等价：

1
2
3
4
5
6
7

const res = await fetch("http://127.0.0.1:9080/tts", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ text: "测试语音合成" }),
});
const result = await res.json();
console.log(result.wavUrl);

输出位置

1

build\Release\public\wav\tts-<hash>.wav

publicBaseUrl 对外暴露的 /wav/... 实际就读这个目录。

日志

所有日志以 [sherpa_tts_server] 前缀输出到 stdout。关键事件：

局限

参考

• 详细字段说明：仓库 sherpa-tts-server/README.md
• callflow-esl 集成：callflow-esl