seeduplex-client
火山引擎 豆包 / Seed 端到端实时语音大模型(Realtime Dialogue)与 双向流式 TTS 的异步 Rust WebSocket 客户端。
- 实时对话文档:https://www.volcengine.com/docs/6561/1594356
- 双向流式 TTS V3:https://docs.volcengine.com/docs/DoubaoVoice/WebSocketBidirectionalStreaming-V3
- API 文档(docs.rs):https://docs.rs/seeduplex-client
支持能力
- 端到端实时语音对话 WebSocket(
/api/v3/realtime/dialogue) - WebSocket 双向流式 TTS(
/api/v3/tts/bidirection,支持链接复用 / 流式送字) - WebSocket 双向流式 ASR(
/api/v3/sauc/bigmodel_async,可选说话人分离) - 新控制台
X-Api-Key鉴权 - 麦克风上行 ASR、打断检测(
ClearCache) - 文本 Query(
ChatTextQuery) - 自定义回复流式 TTS(
ChatTTSText,可分段) - 可选
opusfeature:OGG Opus 解码辅助
安装
[]
= "0.3"
= { = "1", = ["macros", "rt-multi-thread"] }
如需 OGG Opus 解码:
= { = "0.3", = ["opus"] }
最低支持的 Rust 版本为 1.85。
默认值
| 项 | 对话 | 双向流式 TTS | 双向流式 ASR |
|---|---|---|---|
| WebSocket URL | wss://openspeech.bytedance.com/api/v3/realtime/dialogue |
wss://openspeech.bytedance.com/api/v3/tts/bidirection |
wss://openspeech.bytedance.com/api/v3/sauc/bigmodel_async |
| Resource ID | volc.speech.dialog |
seed-tts-2.0 |
volc.seedasr.sauc.duration |
| 默认音色 | zh_female_vv_jupiter_bigtts |
zh_female_vv_uranus_bigtts |
— |
鉴权头(新控制台)
X-Api-Key— API Key(必填)X-Api-Resource-Id— 对话为volc.speech.dialog;TTS 按模型选seed-tts-2.0/seed-tts-1.0/seed-icl-2.0等X-Api-Connect-Id— UUID,由客户端自动添加
旧版 App-ID / Access-Key / App-Key 不再使用。
会话生命周期
- WebSocket 升级 + 鉴权头
StartConnection→ ackStartSession(SessionConfigJSON)→ ack- 上行:PCM /
ChatTextQuery/ChatTTSText/ interrupt - 下行:ASR、回复文本、TTS 音频、打断(
ClearCache) FinishSession→FinishConnection→ 关闭
音频约定
- 上行:16 kHz、mono、s16le、建议 20 ms 一帧(320 samples / 640 bytes)
- 下行(本 crate 默认配置):24 kHz
pcm_s16le
快速开始
设置 API Key:
模式 A:端到端对话(模型自己回复)
未持续推送麦克风音频时,需设置 input_mod = "text"(或 "keep_alive"),否则可能出现 52000042 DialogAudioIdleTimeoutError。
use ;
async
模式 B:只用 ASR + 打断,回复文本自己给(ChatTTSText)
send_audio持续上行麦克风 PCM- 处理
AsrText/AsrEnded/ClearCache - 在
AsrEnded之后调用chat_tts_text_segments([...])(事件 500) - 仅当
TtsSentenceStart.tts_type == "chat_tts_text"时播放音频
流式 ChatTTSText 帧格式:
{start:true, content:"", end:false}
{start:false, content:"句子一。", end:false} // 可多次
{start:false, content:"", end:true}
用户中途打断时,可以不发最后的 end 包。
# use SeeduplexClient;
# async
模式 C:双向流式 TTS(纯合成,无对话模型)
适合把大模型流式输出的文本边到边送进合成。同一 WebSocket 可串行复用多次 StartSession / FinishSession(不可并发)。
use ;
async
示例
需要环境变量 DOUBAO_API_KEY(或 SEEDUPLEX_API_KEY):
# 文本 query + cpal 播放
# 麦克风全双工对话(模型自己回复)
# SayHello 开场白
# 文本 query → 保存 24kHz pcm_s16le 文件(无需扬声器)
# 运行时 UpdateConfig 切换音色
# 麦克风 ASR + 自定义分段 ChatTTSText + cpal 播放
# 双向流式 TTS → cpal 播放 + 保存 pcm(可用 DOUBAO_TTS_RESOURCE_ID / DOUBAO_TTS_SPEAKER 覆盖)
# 双向流式 ASR(麦克风;加 --speakers 开启说话人分离)
示例启动时会安装 rustls 的 ring CryptoProvider。共用音频采集/播放逻辑在 examples/common/。
配置
库代码请优先使用 SessionConfig::new()(不读环境变量)。
二进制可用 SessionConfig::from_env() 叠加:
| 变量 | 说明 |
|---|---|
DOUBAO_API_KEY / SEEDUPLEX_API_KEY |
API Key(示例程序) |
DOUBAO_WS_URL / SEEDUPLEX_WS_URL |
覆盖对话 WebSocket URL |
DOUBAO_RESOURCE_ID / SEEDUPLEX_RESOURCE_ID |
覆盖对话 Resource ID |
DOUBAO_TTS_WS_URL / SEEDUPLEX_TTS_WS_URL |
覆盖双向 TTS WebSocket URL |
DOUBAO_TTS_RESOURCE_ID / SEEDUPLEX_TTS_RESOURCE_ID |
覆盖 TTS Resource ID(如 seed-tts-2.0) |
DOUBAO_TTS_SPEAKER / SEEDUPLEX_TTS_SPEAKER |
双向 TTS 音色 |
DOUBAO_ASR_WS_URL / SEEDUPLEX_ASR_WS_URL |
覆盖双向 ASR WebSocket URL |
DOUBAO_ASR_RESOURCE_ID / SEEDUPLEX_ASR_RESOURCE_ID |
覆盖 ASR Resource ID(如 volc.seedasr.sauc.duration) |
DOUBAO_SPEAKER / SEEDUPLEX_SPEAKER |
对话 / TTS 音色 |
DOUBAO_BOT_NAME / SEEDUPLEX_BOT_NAME |
机器人名称 |
DOUBAO_SYSTEM_ROLE / SEEDUPLEX_SYSTEM_ROLE |
system prompt |
DOUBAO_SPEAKING_STYLE / SEEDUPLEX_SPEAKING_STYLE |
说话风格 |
DOUBAO_USER_ID / SEEDUPLEX_USER_ID |
用户 uid |
DOUBAO_SESSION_CONFIG / SEEDUPLEX_SESSION_CONFIG |
完整 JSON(路径或内联) |
同名时 SEEDUPLEX_* 优先于 DOUBAO_*。
模块结构
| 模块 | 作用 |
|---|---|
client |
SeeduplexClient / DoubaoClient、SessionConfig、ServerEvent |
bidirectional_tts |
BidirectionalTtsClient、BidirectionalTtsConfig、BidirectionalTtsEvent |
bidirectional_asr |
BidirectionalAsrClient、BidirectionalAsrConfig、BidirectionalAsrEvent |
protocol |
二进制协议、发包、PCM 工具(opus feature 可选) |
DoubaoClient 是 SeeduplexClient 的类型别名。
测试
许可证
本项目采用 MIT 许可证。