seeduplex-client 0.3.0

Async Rust client for Volcengine Doubao/Seed realtime dialogue, bidirectional TTS, and streaming ASR
Documentation

seeduplex-client

Crates.io 文档 CI License

中文 | English

火山引擎 豆包 / Seed 端到端实时语音大模型(Realtime Dialogue)与 双向流式 TTS 的异步 Rust WebSocket 客户端。

支持能力

  • 端到端实时语音对话 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,可分段)
  • 可选 opus feature:OGG Opus 解码辅助

安装

[dependencies]
seeduplex-client = "0.3"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

如需 OGG Opus 解码:

seeduplex-client = { version = "0.3", features = ["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 不再使用。

会话生命周期

  1. WebSocket 升级 + 鉴权头
  2. StartConnection → ack
  3. StartSession(SessionConfig JSON)→ ack
  4. 上行:PCM / ChatTextQuery / ChatTTSText / interrupt
  5. 下行:ASR、回复文本、TTS 音频、打断(ClearCache)
  6. FinishSession → FinishConnection → 关闭

音频约定

  • 上行:16 kHz、mono、s16le、建议 20 ms 一帧(320 samples / 640 bytes)
  • 下行(本 crate 默认配置):24 kHz pcm_s16le

快速开始

设置 API Key:

export DOUBAO_API_KEY="your-api-key"

模式 A:端到端对话(模型自己回复)

未持续推送麦克风音频时,需设置 input_mod = "text"(或 "keep_alive"),否则可能出现 52000042 DialogAudioIdleTimeoutError。

use seeduplex_client::{DoubaoClient, ServerEvent, SessionConfig};

#[tokio::main]
async fn main() -> seeduplex_client::Result<()> {
    let api_key = std::env::var("DOUBAO_API_KEY")?;
    let config = SessionConfig::new().with_input_mod("text".into());
    let (client, mut events) = DoubaoClient::connect_with_config(&api_key, config).await?;

    client.send_text("你好").await?;
    while let Some(ev) = events.recv().await {
        match ev {
            ServerEvent::ChatText(t) => println!("{t}"),
            ServerEvent::AudioData(pcm) => { let _ = pcm; /* 播放 24kHz s16le */ }
            ServerEvent::TtsEnded | ServerEvent::SessionFinished => break,
            _ => {}
        }
    }
    client.close().await?;
    Ok(())
}

模式 B:只用 ASR + 打断,回复文本自己给(ChatTTSText)

  1. send_audio 持续上行麦克风 PCM
  2. 处理 AsrText / AsrEnded / ClearCache
  3. 在 AsrEnded 之后调用 chat_tts_text_segments([...])(事件 500)
  4. 仅当 TtsSentenceStart.tts_type == "chat_tts_text" 时播放音频

流式 ChatTTSText 帧格式:

{start:true,  content:"",     end:false}
{start:false, content:"句子一。", end:false}   // 可多次
{start:false, content:"",     end:true}

用户中途打断时,可以不发最后的 end 包。

# use seeduplex_client::SeeduplexClient;
# async fn demo(client: &SeeduplexClient) -> anyhow::Result<()> {
client.chat_tts_text_segments(["第一句。", "第二句。"]).await?;
# Ok(())
# }

模式 C:双向流式 TTS(纯合成,无对话模型)

适合把大模型流式输出的文本边到边送进合成。同一 WebSocket 可串行复用多次 StartSession / FinishSession(不可并发)。

use seeduplex_client::{
    BidirectionalTtsClient, BidirectionalTtsConfig, BidirectionalTtsEvent,
};

#[tokio::main]
async fn main() -> seeduplex_client::Result<()> {
    let api_key = std::env::var("DOUBAO_API_KEY")?;
    // One-shot:
    // let pcm = BidirectionalTtsClient::synthesize(&api_key, "你好").await?;

    let config = BidirectionalTtsConfig::new().with_format("pcm");
    let (client, mut events) = BidirectionalTtsClient::connect_with_config(&api_key, config).await?;

    client.start_session().await?;
    while let Some(ev) = events.recv().await {
        match ev {
            BidirectionalTtsEvent::SessionStarted { .. } => {
                client.send_text("你好,这是双向流式合成。").await?;
                client.finish_session().await?;
            }
            BidirectionalTtsEvent::AudioData(pcm) => { let _ = pcm; }
            BidirectionalTtsEvent::SessionFinished { .. } => break,
            _ => {}
        }
    }
    client.close().await?;
    Ok(())
}

示例

需要环境变量 DOUBAO_API_KEY(或 SEEDUPLEX_API_KEY):

# 文本 query + cpal 播放
cargo run --example text_query -- "你好"

# 麦克风全双工对话(模型自己回复)
cargo run --example mic_dialog

# SayHello 开场白
cargo run --example say_hello -- "你好,我是语音助手"

# 文本 query → 保存 24kHz pcm_s16le 文件(无需扬声器)
cargo run --example text_to_file -- "用一句话介绍火山引擎" reply.pcm

# 运行时 UpdateConfig 切换音色
cargo run --example update_config -- "你好" zh_male_M392_conversation_wvae_bigtts

# 麦克风 ASR + 自定义分段 ChatTTSText + cpal 播放
cargo run --example asr_chat_tts -- "你好。你说的是:{asr}。我说完了。"

# 双向流式 TTS → cpal 播放 + 保存 pcm(可用 DOUBAO_TTS_RESOURCE_ID / DOUBAO_TTS_SPEAKER 覆盖)
cargo run --example bidirectional_tts -- "你好,这是双向流式语音合成。" tts.pcm

# 双向流式 ASR(麦克风;加 --speakers 开启说话人分离)
cargo run --example bidirectional_asr
cargo run --example bidirectional_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 的类型别名。

测试

cargo test
cargo test --features opus
cargo clippy --all-targets --all-features -- -D warnings
cargo doc --no-deps --all-features

许可证

本项目采用 MIT 许可证。