rtc_backend/hw_service_go/test/PLAN.md

hw_service_go 本地硬件通讯测试计划

目标：用浏览器模拟 ESP32 硬件，验证 hw_service_go WebSocket 服务能否正常接收指令、获取故事、推送 Opus 音频。

---

一、协议对比分析

1.1 小智（xiaozhi-server）vs 我们的服务

维度	xiaozhi-server	hw_service_go（本服务）
WebSocket URL	ws://host:port/xiaozhi/v1/?device-id=&client-id=	完全相同
连接参数	device-id（MAC）、client-id（UUID）	完全相同
握手消息	需要发送 hello JSON	不需要，连上即用
触发指令	listen（语音输入）	只需发 {"type":"story"}
音频方向	双向（硬件上传语音 + 服务下发 TTS）	单向下行（服务→硬件，推 Opus）
Opus 编解码	需要编码（麦克风）+ 解码（播放）	只需解码（浏览器只播放）
认证	token 参数	无需认证（仅 device-id 校验）
消息复杂度	hello/listen/stt/llm/tts/mcp	只有 tts 系列

1.2 我们服务的完整消息流

浏览器（模拟硬件）                     hw_service_go              Django
    │                                       │                        │
    │── WS 连接 ──────────────────────────→│                        │
    │   ?device-id=AA:BB:CC:DD:EE:FF       │                        │
    │   &client-id=test-001                 │                        │
    │                                       │                        │
    │── {"type":"story"} ────────────────→ │                        │
    │                                       │── GET /api/v1/devices/ │
    │                                       │   stories/?mac_address │
    │                                       │   =AA:BB:CC:DD:EE:FF → │
    │                                       │                        │
    │← {"type":"tts","state":"start"} ───── │                        │
    │                                       │← {title, audio_url} ── │
    │                                       │                        │
    │                                       │── 下载 MP3 ──────────→ CDN
    │                                       │← MP3 二进制流 ─────── │
    │                                       │                        │
    │                                       │  ffmpeg 转码 PCM→Opus  │
    │                                       │                        │
    │← {"type":"tts","state":"sentence_start","text":"故事标题"} ─── │
    │                                       │                        │
    │← [Opus帧1 二进制] ─────────────────── │  60ms/帧，前3帧预缓冲  │
    │← [Opus帧2 二进制] ─────────────────── │                        │
    │← [Opus帧3 二进制] ─────────────────── │                        │
    │← [Opus帧N 二进制] ─────────────────── │  按时序流控发送        │
    │                                       │                        │
    │← {"type":"tts","state":"stop"} ─────── │                        │
    │                                       │                        │

1.3 Opus 音频参数（与小智完全一致）

参数	值
采样率	16000 Hz
声道	1（单声道）
帧时长	60ms
每帧采样数	960
编码器	libopus（WASM）

---

二、前置条件检查

在开始测试之前，需要满足以下条件：

2.1 服务运行状态

• Django 后端运行在 http://localhost:8000
• hw_service_go 运行在 ws://localhost:8888
• 健康检查通过：curl http://localhost:8888/healthz 返回 200

2.2 Django 数据准备（关键！）

测试必须使用一个在 Django 数据库中真实存在的设备 MAC 地址。

Django API 查询逻辑（GET /api/v1/devices/stories/?mac_address=<MAC>）：

• 根据 MAC 查找设备 → 找到设备绑定的用户 → 查找该用户的故事
• 任何一步缺失，服务返回 null，硬件不会播放任何内容

需要在 Django Admin 或 API 中准备：

1. 注册一个设备，记下其 MAC 地址（格式：AA:BB:CC:DD:EE:FF）
2. 该设备需已绑定用户（owner）
3. 该用户名下有至少一个故事（有 audio_url 字段）

快速验证：curl "http://localhost:8000/api/v1/devices/stories/?mac_address=你的MAC" 应返回 {"code":0,"data":{"title":"...","audio_url":"..."}}

---

三、测试程序设计

3.1 技术选型

方案	优点	缺点
纯 HTML+JS（推荐）	零依赖，直接浏览器打开，与小智方案一致	-
Python 脚本	简单但无法播放音频	无法验证音频播放端到端
Go 命令行	需额外音频库	环境搭建复杂

选择方案：纯 HTML+JS 单文件，复用小智项目的 libopus.js（WASM）做解码。

3.2 文件结构

hw_service_go/test/
├── PLAN.md          ← 本文件
├── test.html        ← 测试主页面（待实现）
└── libopus.js       ← 复制自小智项目（Opus WASM 解码库）

libopus.js 来源：

/Users/maidong/Desktop/zyc/jikashe/xiaozhi-server/main/xiaozhi-server/test/libopus.js

3.3 测试页面功能

┌─────────────────────────────────────────────────────┐
│  hw_service_go 硬件通讯测试                          │
├─────────────────────────────────────────────────────┤
│  服务地址:  [ws://localhost:8888/xiaozhi/v1/      ] │
│  device-id: [AA:BB:CC:DD:EE:FF                   ] │
│  client-id: [test-browser-001          ] [随机生成] │
├─────────────────────────────────────────────────────┤
│  [连接]  [断开]    状态: ● 未连接                   │
├─────────────────────────────────────────────────────┤
│  [▶ 触发故事播放]   [⏹ 停止]                        │
├─────────────────────────────────────────────────────┤
│  消息日志                              [清空]        │
│  ┌───────────────────────────────────────────────┐  │
│  │ [10:23:01] → 已连接                           │  │
│  │ [10:23:02] → 发送: {"type":"story"}           │  │
│  │ [10:23:02] ← 收到: {"type":"tts","state":"start"} │
│  │ [10:23:03] ← 收到: {"type":"tts","state":"sentence_start","text":"..."} │
│  │ [10:23:03] ← 收到: [Binary] Opus帧 #1 (38 bytes) │
│  │ [10:23:03] 🔊 开始播放...                     │  │
│  │ [10:23:15] ← 收到: {"type":"tts","state":"stop"} │
│  │ [10:23:15] 🔊 播放完毕                        │  │
│  └───────────────────────────────────────────────┘  │
│                                                     │
│  统计: 已收到 85 个Opus帧 | 约 5.1s 音频           │
└─────────────────────────────────────────────────────┘

3.4 核心实现逻辑

连接流程

const ws = new WebSocket(
  `ws://localhost:8888/xiaozhi/v1/?device-id=${deviceId}&client-id=${clientId}`
);
ws.binaryType = 'arraybuffer';

触发故事

ws.send(JSON.stringify({ type: 'story' }));

接收消息处理

ws.onmessage = (event) => {
  if (event.data instanceof ArrayBuffer) {
    // 二进制：Opus 音频帧
    const opusFrame = new Uint8Array(event.data);
    const pcm = opusDecoder.decode(opusFrame);   // Int16Array
    schedulePlay(pcm);                            // 排队播放
  } else {
    // 文本：控制消息
    const msg = JSON.parse(event.data);
    handleTtsControl(msg);  // 处理 start/sentence_start/stop
  }
};

Opus 解码 + 播放（与小智方案完全一致）

• 使用 libopus.js（WASM）初始化解码器：16000Hz，单声道
• 解码：Int16Array → Float32Array
• 使用 AudioContext + AudioBufferSourceNode 按时序排队播放
• 使用 BlockingQueue 缓冲帧，避免播放卡顿

---

四、测试用例

Case 1：基础连接测试

• 输入正确的 device-id 和 client-id
• 期望：WebSocket 连接建立成功，状态变为"已连接"

Case 2：故事触发测试

• 发送 {"type":"story"}
• 期望：
  1. 收到 {"type":"tts","state":"start"}
  2. 收到 {"type":"tts","state":"sentence_start","text":"<故事标题>"}
  3. 陆续收到多个二进制 Opus 帧
  4. 最终收到 {"type":"tts","state":"stop"}

Case 3：音频播放验证

• 期望：浏览器实际播放出故事音频，声音正常无杂音、无卡顿

Case 4：设备不存在测试

• 使用未注册的 MAC 地址
• 期望：发送故事指令后立即收到 {"type":"tts","state":"stop"}（服务侧找不到故事，直接结束）

Case 5：重复触发测试

• 播放过程中再次点击"触发故事"
• 期望：旧播放被打断，新故事从头开始（hw_service_go 的 StartPlayback 会 close 旧 abortCh）

Case 6：断线重连测试

• 连接后断开，再重新连接
• 期望：可以正常重新发起故事请求

---

五、实现步骤

1. 复制 libopus.js

   cp /Users/maidong/Desktop/zyc/jikashe/xiaozhi-server/main/xiaozhi-server/test/libopus.js \
      /Users/maidong/Desktop/zyc/qy_gitlab/rtc_backend/hw_service_go/test/
   

2. 编写 test.html（单文件，嵌入所有 JS）

   • 参考小智 StreamingContext.js 和 BlockingQueue.js 的逻辑
   • 去掉录音/编码部分（我们只需解码）
   • 保留 Opus 解码 + AudioContext 播放部分
   • 添加连接配置 UI 和消息日志面板

3. 浏览器打开测试

   直接用浏览器打开 test.html（file:// 协议即可）
   

   注意：macOS Safari 对 WebSocket + file:// 可能有限制，建议用 Chrome

4. 按测试用例逐项验证

---

六、已知限制与注意事项

问题	说明
device-id 必须真实存在	MAC 地址若未在 Django 数据库注册，服务会静默返回无故事
ffmpeg 必须安装	hw_service_go 的转码依赖系统 ffmpeg，需提前安装
audio_url 必须可访问	故事的 MP3 链接需要能从本机下载（阿里云 OSS 等）
浏览器 AudioContext 限制	需要用户交互（点击）后才能创建 AudioContext，不能自动播放
WASM 加载	libopus.js 较大（844KB），首次加载需要等待约 1-2 秒