实时语音转写(WebSocket 流式)

通过 WebSocket 上传实时音频流并实时返回识别结果。 后端使用豆包流式语音识别 2.0 (bigmodel_async)。完整协议见 docs/speech-to-text-stream.md。

帧类型约定

客户端 → 服务端

1) start (第一帧必须是它)

{
"type": "start",
"format": "pcm",
"disfluency": false
}

• format 可选,默认 pcm。支持 pcm / wav / ogg / mp3,单声道、16-bit、采样率固定 16000Hz
• pcm / wav 内部音频流必须是 pcm_s16le;ogg 必须为 opus 编码;mp3 由远端解码
• disfluency 可选,默认 false。true 时启用语义顺滑(过滤"嗯/啊"等口头禅、语义重复词)
• 服务端校验通过 → 与豆包建立 WSS → 收到首个响应后向客户端下发 ready 事件(带 logid)
• 客户端必须在收到 ready 之后才能发 Binary 音频帧
• 以下能力默认开启:中间结果(双向流式天然有)、标点预测、ITN(中文数字转阿拉伯数字)

2) Binary 音频帧

ready 之后,客户端持续发 Binary 帧。建议每帧 200ms(豆包推荐值,过碎会影响性能)。

3) stop (主动结束)

{ "type": "stop" }

服务端收到后向豆包发送"最后一包"标志,等待豆包最终响应后下发 done 事件并关闭 WS。客户端直接 close WS 亦可。

服务端 → 客户端

所有事件统一外层结构:

{ "type": "<event_type>", "timestamp": 1733299200000, ... }

ready — 远端已就绪

{ "type": "ready", "logid": "202407261553070FACFE6D19421815D605", "timestamp": 1733299200000 }

仅推送一次。客户端收到后开始发 Binary 音频帧。logid 是豆包返回的 X-Tt-Logid,排障必备, 建议前端在 session 期间一直打印它,跟后续 error 事件可以关联。

partial — 中间结果(实时滚动,会反复推送)

{ "type": "partial", "index": 1, "text": "今天天气真", "timestamp": 1733299201500 }

• 同一 index 的 partial 会反复推送,text 通常逐渐变长
• 客户端必须用 text 覆盖该句显示内容,不要追加

final — 一句话定稿

{ "type": "final", "index": 1, "text": "今天天气真不错。", "timestamp": 1733299202800 }

• 该句识别完成、内容固化,后续不会再变;客户端用 text 覆盖 index 对应位置
• final 之后可能立刻有下一句的 partial(index+1)

done — 整个 session 结束

{ "type": "done", "logid": "...", "timestamp": 1733299210000 }

• 服务端已收到豆包最后一包响应、释放资源,即将关闭 WS;done 之后不会再有任何事件

error — 错误

豆包远端错误:

{
"type": "error",
"logid": "202407261553070FACFE6D19421815D605",
"error": {
"code": 45000001,
"message": "请求参数无效",
"request_id": "67ee89ba-7050-4c04-a3d7-ac61a63499b3",
"logid": "202407261553070FACFE6D19421815D605"
},
"timestamp": 1733299205000
}

本服务前置校验错误(远端连接前):code=0,在 message 描述原因:

{
"type": "error",
"error": { "code": 0, "message": "first message must be a 'start' control message" },
"timestamp": 1733299205000
}

豆包常见错误码速查

时序示例

C → S: WS upgrade (带鉴权)
C → S: {"type":"start","format":"pcm"}
S → C: {"type":"ready","logid":"..."}
C → S: <binary 200ms> <binary 200ms> ...
S → C: {"type":"partial","index":1,"text":"今天"}
S → C: {"type":"partial","index":1,"text":"今天天气真"}
S → C: {"type":"final","index":1,"text":"今天天气真不错。"}
C → S: {"type":"stop"}
S → C: {"type":"done","logid":"..."}
WS close

与 POST /speech-to-text 的差异

• POST /speech-to-text:整段录音 → SSE 单段结果,适合短语音 ≤60s
• 本接口:WS 双向实时流,支持长语音、句级 final、可被打断,适合 Web/移动端边说边显示

{
  "format": "pcm",
  "type": "start"
}