TEN Framework 集成 Deepgram Aura 流式 TTS:deepgram_tts 扩展的配置、接口与原理详解
TEN Framework 集成 Deepgram Aura 流式 TTS:deepgram_tts 扩展的配置、接口与原理详解
Deepgram TTS Extension 是 TEN Framework 中基于 Deepgram Aura 流式 API 实现的 Text-to-Speech(TTS)扩展,通过 WebSocket 以线性16(Linear16)PCM 格式实时返回音频流。本文以该扩展的 README 为核心骨架,结合其源码与测试,完整讲解配置参数、支持的音色与采样率、标准 TTS 数据接口、TTFB 指标上报、音频 dump 调试以及测试运行方式,帮助你在 TEN 框架的语音 Agent 图(graph)中快速接入低延迟流式语音合成能力。
功能特性
从 README 和源码实现来看,该扩展的核心能力包括:
- 实时流式 TTS:通过 WebSocket 连接 Deepgram Aura 服务,边合成边返回音频,无需等待整段文本全部合成完毕;
- 多种音色模型:完整支持 Deepgram Aura-2 系列共 12 个音色(见下文列表);
- 可配置采样率:支持 8000、16000、24000、48000 Hz 四种输出采样率;
- Linear16 PCM 音频输出:16-bit、单声道(mono)裸 PCM 数据,便于下游直接播放或转发;
- TTFB(Time to First Byte)指标上报:记录从发送文本到收到第一段音频的时间,随
metrics数据输出; - 音频 dump 能力:开启后可将合成音频以
.pcm文件落盘,方便离线调试与质量检查。
工作原理:Speak + Flush 流式协议
扩展的核心是 deepgram_tts.py 中的 DeepgramTTSClient。它维护一条复用的 WebSocket 连接,每次调用 get(text) 时依次发送两条 JSON 控制消息:
{"type": "Speak", "text": text}—— 告诉 Deepgram 开始合成指定文本;{"type": "Flush"}—— 指示服务端在合成完当前文本后立即冲刷输出并返回Flushed消息。
随后客户端循环接收消息:二进制消息即为音频分片(bytes),JSON 文本消息则根据 type 字段区分 Flushed(结束)、Warning(警告)、Error(错误)。收到 Flushed 后本次请求结束,连接保持复用,下一次 get() 可以继续发送新文本。
连接并非一成不变,源码实现了三层保障:
- 预连接(preheat):
on_init阶段调用client.start()提前建立 WebSocket 连接,减少首包延迟; - 按需重连:
_ensure_connection()在连接不存在时建立连接,_reconnect()在出错或取消后重建连接; - 超时保护:接收音频时使用
WS_RECV_TIMEOUT = 8.0秒(deepgram_tts.py)的等待上限,超时后标记需要重连并向上层抛出错误事件。
此外,cancel() 会发送 Flush 并排空(drain)直到收到 Flushed,保证连接处于干净状态,可供下一次请求继续使用——这对应 README 中 tts_flush 输入的处理逻辑。
配置详解
扩展配置通过 TEN 框架的 property 机制注入,在 property.json 中给出默认值,并在 manifest.json 中声明了 schema(api 部分)。扩展在 on_init 时通过 ten_env.get_property_to_json("") 读取全部配置,并交给 pydantic 模型 DeepgramTTSConfig(config.py)解析校验。
属性一览
| Property | 类型 | 默认值 | 说明 |
|---|---|---|---|
params.api_key |
string | 必填 | Deepgram API key,支持 ${env:DEEPGRAM_API_KEY} 环境变量引用 |
params.model |
string | aura-2-thalia-en |
使用的音色模型 |
params.encoding |
string | linear16 |
音频编码格式 |
params.sample_rate |
int | 24000 |
输出采样率(Hz),取值范围见下文 |
params.base_url |
string | wss://api.deepgram.com/v1/speak |
WebSocket 端点 |
params.<deepgram_query_param> |
scalar | 可选 | 额外透传给 Deepgram 的 WebSocket 查询参数 |
dump |
bool | false |
是否开启音频落盘 |
dump_path |
string | /tmp |
dump 文件输出目录 |
参数归一化与透传
config.py 中的 update_params() 方法实现了一套“已知键归一化、未知键透传”的规则(config.py):
api_key、base_url、model、encoding、sample_rate这五个扩展自有的键会被从params中取出,赋值到配置模型对应的属性上(同时从params中删除,避免重复);params中剩余的标量键值对(如container、punctuate、smart_format等 Deepgram 支持的 WebSocket 查询参数)会原样保留;- 在 deepgram_tts.py 的
_build_ws_url()中,这些透传参数会同model、encoding、sample_rate一起通过urlencode拼接到 WebSocket 查询字符串上;而api_key、base_url永远不会进入查询串——API key 是通过Authorization: Token <api_key>请求头发送的(deepgram_tts.py)。
另外,配置对象在日志输出时会调用 to_str(sensitive_handling=True) 对 api_key 做脱敏加密处理(config.py),避免密钥明文出现在日志中。
配置示例
README 给出的标准配置如下,可直接复制使用:
{
"params": {
"api_key": "${env:DEEPGRAM_API_KEY}",
"model": "aura-2-thalia-en",
"encoding": "linear16",
"sample_rate": 24000,
"container": "none"
},
"dump": false,
"dump_path": "/tmp"
}
其中 container: "none" 就是一个典型的透传参数:Deepgram 默认会在某些场景下返回带容器格式的数据,显式传 "none" 可确保拿到的是裸 Linear16 PCM 流,与扩展下游 pcm_frame 输出格式保持一致。
on_init 阶段会做两项硬性校验(extension.py):配置为空或为 {} 时直接报错“Configuration is empty”;api_key 为空时抛出 ValueError("API key is required")。初始化失败会通过 send_tts_error 上报 FATAL_ERROR 级别的 ModuleError,其中 vendor 字段固定为 "deepgram"。
可用音色模型
Deepgram Aura-2 系列共 12 个英语音色,女声/男声各 6 个:
- 女声:
aura-2-thalia-en(默认)、aura-2-luna-en、aura-2-stella-en、aura-2-athena-en、aura-2-hera-en - 男声:
aura-2-orion-en、aura-2-arcas-en、aura-2-perseus-en、aura-2-angus-en、aura-2-orpheus-en、aura-2-helios-en、aura-2-zeus-en
通过修改 params.model 即可切换音色,无需改动代码或重启重建连接(新配置在下次建立 WebSocket 连接时生效)。
支持的采样率
| 采样率 | 说明 |
|---|---|
| 8000 Hz | 窄带电话场景 |
| 16000 Hz | 常见语音识别/通话场景 |
| 24000 Hz | 推荐值(默认) |
| 48000 Hz | 高保真场景 |
采样率由 params.sample_rate 控制,同时会影响音频时长计算。在 extension.py 的 _calculate_audio_duration_ms() 中,音频时长按“16-bit(2 字节/采样)× 单声道”计算:duration_ms = total_audio_bytes / (sample_rate × 2 × 1) × 1000。
标准 TTS 数据接口
该扩展实现的是 TEN 标准 TTS 接口(AsyncTTS2BaseExtension,声明于 manifest.json 引用的 ten_ai_base 的 tts-interface.json),在图中与其他 TEN 扩展通过命名数据(named data)通信:
输入数据(Data)
tts_text_input—— 待合成文本,携带request_id、text、text_input_end等字段;其中text_input_end=True表示该请求文本已全部送入,收到合成结束事件后即可完成请求;tts_flush—— 冲刷/打断当前请求:cancel_tts()会向客户端发送Flush并最终以INTERRUPTED原因结束请求。
输出数据(Data)
tts_audio_start—— 音频生成开始(在收到首个音频分片、TTFB 统计完成时发送);tts_audio_end—— 音频生成完成,携带request_event_interval_ms(流式耗时)与request_total_audio_duration_ms(音频总时长)等元数据;metrics—— 性能指标,核心字段为嵌套在metrics对象中的ttfb(毫秒)以及model等附加信息;error—— 错误信息,按ModuleError结构上报(含module=TTS、code、vendor_info)。
输出音频(AudioFrame)
pcm_frame—— 16-bit、单声道 PCM 音频数据,采样率与params.sample_rate一致。
TTFB 指标与错误处理
TTFB 上报流程
TTFB 的统计在客户端与扩展层协作完成(deepgram_tts.py):
- 发送
Speak前记录_sent_ts = datetime.now(); - 收到第一段二进制音频分片时,计算
ttfb_ms = (now - _sent_ts) × 1000; - 以
EVENT_TTS_TTFB_METRIC事件抛给扩展层; - 扩展层收到后发送
tts_audio_start与metrics数据(ttfb字段 +model元数据),随后正常转发音频分片。
扩展层的测试 test_metrics.py 用 mock 模拟了“延迟 0.2s 后先发 TTFB 指标、再发音频分片、最后发 END”的完整时序,并断言 metrics 数据中嵌套的 ttfb 值正确、音频帧与 tts_audio_end 均已收到——可作为理解该数据结构的直接参考。
错误处理策略
- 连接层错误:
DeepgramTTSConnectionException携带 HTTP 状态码;401 视为FATAL_ERROR,其余为NON_FATAL_ERROR,错误详情通过vendor_info(vendor=deepgram, code, message)上报; - 流式过程中的错误:Deepgram 返回
Error消息时标记需要重连;若错误发生在非末段文本(text_input_end=False),仅记录 warning 继续流式;若发生在末段,则以ERROR原因结束请求; - 超时/异常:8 秒未收到数据即上报
EVENT_TTS_ERROR并触发重连,保证连接状态自愈。
音频 dump 调试
当 dump 设为 true 时,扩展会为每个请求创建 PCMWriter,把收到的每个音频分片按顺序写入 {dump_path}/deepgram_dump_{request_id}.pcm(extension.py)。要点:
- 文件为裸 PCM 格式,可用支持 raw PCM 的播放器或 Audacity(按 16-bit、单声道、对应采样率导入)试听;
- 新请求开始时自动清理旧请求的 dump writer;
- 扩展停止(
on_stop)时会 flush 所有未写完的 dump 文件。
测试目录 tests/configs/property_dump.json 展示了开启 dump 的配置(输出到 ./tests/keep_dump_output/);而 tests/configs/property_invalid.json、tests/configs/property_miss_required.json 则分别覆盖了非法配置与缺少必填项(api_key)的失败路径。
运行测试
扩展自带基于 ExtensionTester 的单元测试(位于 tests 目录,覆盖基础合成、错误消息、指标、参数透传、鲁棒性、状态机等场景)。按 README 说明运行:
cd deepgram_tts
tman -y install --standalone
./tests/bin/start
tman -y install --standalone 会以 standalone 模式安装扩展及其依赖(ten_runtime_python 0.11、ten_ai_base 0.7,见 manifest.json),./tests/bin/start 启动测试套件。测试通过 mock 掉 DeepgramTTSClient 的方式运行,无需真实 API key 即可验证扩展层逻辑;需要真实联调时则通过环境变量注入密钥。
环境变量与依赖
DEEPGRAM_API_KEY—— Deepgram API key,配置中通过${env:DEEPGRAM_API_KEY}引用。- 运行依赖(requirements.txt):
websockets>=14.0(Python >= 3.10,见 pyproject.toml)。
许可证
Apache License, Version 2.0。