# Voice WebSocket 使用说明

基于 `src/voice` 产品语音管线与 `static/voice-demo` 浏览器示例整理。

## 概览

| 项目 | 说明 |
|------|------|
| WebSocket 路径 | `/ws-product` |
| 协议标识 | `va.ws.v1`（JSON + base64；音频上行也支持二进制 PCM） |
| 默认音频 | PCM16 小端（`pcm_s16le`）、16 kHz、单声道 |
| 会话 ID | 连接 URL 查询参数 `chatId` 或 `chat_id`；未传时服务端自动生成 |
| 健康检查 | `GET /voice/health` |
| 浏览器 Demo | 默认挂载于 `/voice-demo`（由 voice 配置 `server.serve_webpage` 控制） |

完整 URL 示例：

```
ws://127.0.0.1:8000/ws-product?chatId=voice_abc123
wss://your-host/ws-product?chatId=voice_abc123
```

## 连接流程

```mermaid
sequenceDiagram
    participant Client
    participant Server

    Client->>Server: WebSocket connect (?chatId=...)
    Server-->>Client: 101 Switching Protocols
    Client->>Server: session.start (JSON)
    Note over Client,Server: 可选：固定开场白 / FastGPT opener / LLM 生成问候
    loop 会话中
        Client->>Server: input.audio (binary 或 JSON)
        Client->>Server: input.text
        Server-->>Client: input.transcript.* / response.text.* / response.audio.*
        Server-->>Client: response.state（若启用状态标签）
    end
    Client->>Server: session.stop
    Server-->>Client: WebSocket close
```

推荐顺序（与 `voice-demo/app.js` 一致）：

1. 建立 WebSocket 连接（建议 `binaryType = "arraybuffer"`）。
2. 连接成功后立即发送 `session.start`。
3. 开始推送麦克风音频（二进制帧或 `input.audio` JSON）。
4. 处理服务端 JSON 事件（文本、转写、TTS 音频等）。
5. 断开前发送 `session.stop`，再关闭连接。

## 消息信封

除二进制音频外，所有消息均为 UTF-8 JSON 对象。服务端下发事件统一包含：

| 字段 | 类型 | 说明 |
|------|------|------|
| `type` | string | 事件类型 |
| `protocol` | string | 固定为 `va.ws.v1` |
| `seq` | number | 单调递增序号（仅服务端事件） |

## 客户端 → 服务端

### `session.start`

开始会话，必须在发送音频或文本输入之前调用。

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

`chatId` 也可写作 `chat_id`。若省略，服务端使用 URL 查询参数或自动生成 ID。

### `session.stop`

正常结束会话。

```json
{
  "type": "session.stop",
  "reason": "client_disconnect"
}
```

### `input.audio`（JSON 形式）

```json
{
  "type": "input.audio",
  "audio": "<base64 PCM16>",
  "sample_rate": 16000,
  "channels": 1
}
```

`audio` 字段也可命名为 `data`。`sample_rate` / `channels` 可省略，默认与服务端配置一致。

### 二进制音频（推荐）

直接发送 **原始 PCM16 小端** 字节流，无需 JSON 包装。`voice-demo` 通过 AudioWorklet 每 20 ms 发送一帧（16 kHz 单声道下约 640 字节/帧）。

服务端同时接受 JSON 与二进制两种上行格式。

### `input.text`

发送文本回合；默认会打断当前 bot 回复（`interrupt: true`）。

```json
{
  "type": "input.text",
  "text": "你好，我想报案",
  "interrupt": true
}
```

注意：文本输入**不会**以 `input.transcript.final` 回显，客户端需自行在 UI 中展示用户消息（Demo 即如此处理）。Demo 的相机步骤通过发送 `input.text`（如 `【拍摄完成】`）完成，不上传图片帧。

## 服务端 → 客户端

### 用户语音转写

| 事件 | 说明 |
|------|------|
| `input.transcript.interim` | ASR 中间结果（流式识别过程中） |
| `input.transcript.final` | 用户一句话结束后的最终转写 |

```json
{
  "type": "input.transcript.final",
  "protocol": "va.ws.v1",
  "seq": 12,
  "text": "发生了交通事故",
  "user_id": "product-user",
  "timestamp": "2026-06-01T10:00:00.000Z"
}
```

### 助手文本流

文本通常**早于**对应 TTS 音频到达，便于客户端先渲染字幕。

| 事件 | 说明 |
|------|------|
| `response.text.started` | 新一轮助手回复开始 |
| `response.text.delta` | 流式文本片段 |
| `response.text.final` | 本轮文本结束；`interrupted: true` 表示被打断 |

```json
{
  "type": "response.text.delta",
  "protocol": "va.ws.v1",
  "seq": 20,
  "text": "您好，"
}
```

```json
{
  "type": "response.text.final",
  "protocol": "va.ws.v1",
  "seq": 45,
  "text": "您好，请问发生了什么情况？",
  "interrupted": false
}
```

### 助手语音（TTS）

| 事件 | 说明 |
|------|------|
| `response.audio.started` | Bot 开始说话 |
| `response.audio.delta` | PCM16 音频块（base64） |
| `response.audio.stopped` | Bot 说完 |

```json
{
  "type": "response.audio.delta",
  "protocol": "va.ws.v1",
  "seq": 30,
  "audio": "<base64 PCM16>",
  "bytes": 640,
  "sample_rate": 16000,
  "channels": 1
}
```

客户端应将各 `delta` 块按序解码并无缝拼接播放（Demo 使用 Web Audio `AudioContext` 调度）。

### 助手状态（可选）

当 voice 配置启用 `agent.response_state` 时，LLM 输出开头的 `<state>...</state>` 标签会被剥离，并单独下发：

```json
{
  "type": "response.state",
  "protocol": "va.ws.v1",
  "seq": 18,
  "state": "2000"
}
```

Demo 根据状态码展示拍照引导（如 `2000`–`2015` 等车险场景状态）。

## 音频参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| 采样率 | 16000 Hz | 配置项 `audio.sample_rate_hz` |
| 声道 | 1（mono） | 配置项 `audio.channels` |
| 帧长 | 20 ms | 配置项 `audio.frame_ms`；每帧 640 字节 |
| 编码 | PCM signed 16-bit LE | 小端有符号 16 位整数 |

## 会话与打断行为

- **chatId**：同一 ID 用于 LLM（如 FastGPT）多轮上下文；连接时可写在 URL 或 `session.start` 中。
- **语音回合**：VAD + 静音超时判定用户说完；说完后触发 STT 最终转写与 LLM。
- **打断**：用户说话或 `input.text`（`interrupt: true`）可打断 bot；被打断的助手文本在 `response.text.final` 中带 `interrupted: true`。
- **空闲超时**：长时间无活动会断开（`session.inactivity_timeout_sec`，默认 60 秒）；可配置空闲提示语。
- **开场白**：由 `agent.greeting_mode` 控制（`fixed` / `fastgpt_opener` / `generated` 等）。

## 浏览器 Demo 参考实现

Demo 位于 `static/voice-demo/`，无构建步骤，核心文件：

| 文件 | 职责 |
|------|------|
| `app.js` | WebSocket 连接、事件处理、聊天 UI、TTS 播放 |
| `pcm-recorder.worklet.js` | 麦克风采集、重采样至 16 kHz、20 ms 二进制帧 |
| `index.html` / `styles.css` | 页面与样式 |

### 启动 Demo

1. 启动 API 服务并加载 voice 配置（环境变量 `VOICE_CONFIG` 指向 JSON，默认 `config/voice.json`）。
2. 浏览器打开 `http://127.0.0.1:8000/voice-demo/`（挂载路径见配置 `server.webpage_mount`）。
3. 点击 **Connect** → **Enable mic** 开始对话。

### Demo 关键实现要点

**连接与握手**

```javascript
const ws = new WebSocket("ws://127.0.0.1:8000/ws-product?chatId=voice_xxx");
ws.binaryType = "arraybuffer";

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: "session.start",
    protocol: "va.ws.v1",
    chatId: "voice_xxx",
    audio: { encoding: "pcm_s16le", sample_rate: 16000, channels: 1 },
  }));
};
```

**发送麦克风（二进制，与 Demo 一致）**

```javascript
// AudioWorklet 每 20ms postMessage { type: "frame", buffer: ArrayBuffer }
recorderNode.port.onmessage = (event) => {
  if (event.data?.type === "frame") {
    ws.send(event.data.buffer);
  }
};
```

**播放 TTS**

```javascript
function decodeBase64ToInt16(b64) {
  const binary = atob(b64);
  const bytes = new Uint8Array(binary.length);
  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
  return new Int16Array(bytes.buffer);
}

// 收到 response.audio.delta 后，将 Int16 转为 Float32 并调度到 AudioContext
```

**发送文本并打断**

```javascript
ws.send(JSON.stringify({
  type: "input.text",
  text: "【拍摄完成】",
  interrupt: true,
}));
// 客户端应停止本地 TTS 播放队列；服务端会发 response.text.final(interrupted=true)
```

### 跨域静态页

若 Demo 托管在其他端口，需在 voice 配置中设置 `server.cors_origins`，并将 WebSocket URL 指向 API 主机。

> 浏览器 `getUserMedia` 需要安全上下文：`https://` 或 `http://localhost` 可用；其他 HTTP 源需改用 HTTPS + `wss://`。

## 最小客户端示例（伪代码）

```javascript
const ws = new WebSocket(`${location.protocol === "https:" ? "wss" : "ws"}://${location.host}/ws-product?chatId=voice_demo_1`);
ws.binaryType = "arraybuffer";

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: "session.start",
    protocol: "va.ws.v1",
    audio: { encoding: "pcm_s16le", sample_rate: 16000, channels: 1 },
  }));
};

ws.onmessage = (event) => {
  if (typeof event.data !== "string") return;
  const msg = JSON.parse(event.data);
  switch (msg.type) {
    case "input.transcript.final":
      console.log("User:", msg.text);
      break;
    case "response.text.delta":
      process.stdout?.write?.(msg.text); // 流式打印助手文本
      break;
    case "response.audio.delta":
      playPcm16(decodeBase64(msg.audio));
      break;
    case "response.state":
      console.log("State:", msg.state);
      break;
  }
};

function disconnect() {
  ws.send(JSON.stringify({ type: "session.stop", reason: "done" }));
  ws.close(1000, "done");
}
```

## 健康检查响应示例

```bash
curl http://127.0.0.1:8000/voice/health
```

```json
{
  "status": "healthy",
  "config": "/path/to/config/voice.json",
  "protocols": {
    "/ws-product": "va.ws.v1.json_base64"
  },
  "features": {
    "product_text_input": true,
    "product_text_interrupt": true
  },
  "demo": "/voice-demo",
  "llm_provider": "fastgpt",
  "stt_provider": "xfyun",
  "tts_provider": "xfyun"
}
```

## 常见问题

| 现象 | 可能原因 |
|------|----------|
| 连接后立即断开 | 未发送 `session.start`；或超过 inactivity 超时 |
| 无 bot 语音 | 未处理 `response.audio.delta`；AudioContext 未在用户手势后 resume |
| 回声/啸叫 | 建议使用耳机；Demo 已开启浏览器 AEC，但扬声器外放仍可能串音 |
| 文本发送无用户气泡 | 设计如此，需客户端本地展示 `input.text` 内容 |
| 跨域 WebSocket 失败 | 检查 `cors_origins` 与 `wss` 证书 |