Files

Xin Wang 7267c06552 Add Chinese docs for product WebSocket usage.

Document va.ws.v1 protocol, client messages, server events, and interrupted flag behavior for product clients.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-05-22 15:10:15 +08:00

3.8 KiB

Raw Blame History

Product WebSocket 使用说明

Product WebSocket（/ws-product）面向浏览器、移动端等产品客户端，使用稳定的 JSON/base64 协议 va.ws.v1。

连接地址

ws://<host>:<port>/ws-product

生产环境请使用 wss://。可通过 GET /health 查看当前支持的协议与能力。

音频参数

参数	默认值
编码	PCM signed 16-bit little-endian（`pcm_s16le`）
采样率	16000 Hz
声道	1（单声道）

基本流程

建立 WebSocket 连接
发送 session.start 握手
持续发送音频或文本输入
接收服务端事件（转写、回复文本、TTS 音频等）
结束时发送 session.stop

1. 启动会话

{
  "type": "session.start",
  "protocol": "va.ws.v1",
  "audio": {
    "encoding": "pcm_s16le",
    "sample_rate": 16000,
    "channels": 1
  }
}

2. 发送音频

JSON + base64（便于调试）：

{
  "type": "input.audio",
  "audio": "<base64 编码的 pcm_s16le 数据>",
  "sample_rate": 16000,
  "channels": 1
}

二进制帧：也可直接发送原始 PCM16 字节，延迟和带宽更优。字段 audio 与 data 均可作为 base64 字段名。

建议按约 20 ms 一帧分片发送（16 kHz 单声道下每帧约 640 字节）。

3. 发送文本（可选）

{
  "type": "input.text",
  "text": "你好",
  "interrupt": true
}

interrupt 默认为 true，会打断当前正在播放的 bot 语音。

4. 取消当前回复

{"type": "response.cancel"}

5. 结束会话

{"type": "session.stop", "reason": "done"}

服务端事件

所有出站消息均为 JSON，包含 type、protocol（va.ws.v1）和递增的 seq 字段。

事件类型	说明
`input.transcript.interim`	用户语音中间转写（流式 ASR 时）
`input.transcript.final`	用户语音最终转写
`response.text.started`	助手开始回复
`response.text.delta`	助手文本流式片段（通常早于 TTS 音频）
`response.text.final`	助手本轮回复结束，见下方 `interrupted` 说明
`response.audio.started`	开始播放 TTS
`response.audio.delta`	TTS 音频片段（base64 PCM16）
`response.audio.stopped`	TTS 播放结束

音频事件示例：

{
  "type": "response.audio.delta",
  "protocol": "va.ws.v1",
  "seq": 1,
  "audio": "<base64>",
  "bytes": 6400,
  "sample_rate": 16000,
  "channels": 1
}

`response.text.final` 与 `interrupted`

每轮助手回复结束时都会发送一条 response.text.final：

{
  "type": "response.text.final",
  "text": "今天北京天气晴朗，",
  "interrupted": true
}

interrupted: false — 助手正常说完本轮内容（文本流与 TTS 自然结束）。
interrupted: true — 本轮被打断，text 只包含已流式输出、尚未说完的部分，不是完整原定回复。

以下情况会置 interrupted 为 true，并停止当前 TTS：

文本打断 — 发送 input.text 且 interrupt 为 true（默认值）。
主动取消 — 发送 response.cancel。
语音插话（barge-in） — 助手正在说话时，用户开口且满足打断条件：转写文本达到最短字数门槛，或命中常见短答词（如「是的」「行」「可以」）。过短的背景噪声通常不会触发打断。

客户端可用 interrupted 区分「完整回复」与「说到一半被截断」，例如在 UI 上对未说完的气泡做标记。

浏览器示例

引擎可在 config.json 中开启内置演示页：

"server": {
  "serve_webpage": true,
  "webpage_mount": "/demo"
}

启动服务后访问 http://localhost:8000/demo/，默认连接同源的 /ws-product。参考实现见 examples/webpage/。

3.8 KiB Raw Blame History Unescape Escape