add initial AI ball protocol docs

2026-06-18 18:22:20 +08:00
parent 40e184cc6c
commit 753a000eeb
7 changed files with 404 additions and 19 deletions
@@ -1,3 +1,58 @@
 # 演唱会播放同步协议

-用于定义 PC 同步播放器如何向 AI球同步 content_id、position_ms、state、speed。
+本文档定义 PC 同步播放器如何向 AI球设备同步 `content_id`、`position_ms`、`state` 和 `speed`。
+
+## 1. 目标
+
+- 支持多台 AI球在演唱会或活动现场按同一时间轴执行应援脚本。
+- 支持播放、暂停、停止、跳转和倍速等基础同步控制。
+- 允许设备端根据本地资源包和应援脚本独立执行动作。
+
+## 2. 同步消息
+
+```json
+{
+  "content_id": "concert-demo-001",
+  "state": "playing",
+  "position_ms": 30000,
+  "speed": 1.0,
+  "sent_at_ms": 1710000000000
+}
+```
+
+## 3. 字段说明
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `content_id` | string | 当前曲目、节目或应援内容 ID。 |
+| `state` | string | `playing`、`paused`、`stopped` 之一。 |
+| `position_ms` | integer | 当前内容播放进度，单位毫秒。 |
+| `speed` | number | 播放速度，默认 `1.0`。 |
+| `sent_at_ms` | integer | PC 上位机发送时间戳，用于延迟估计。 |
+
+## 4. 设备端处理流程
+
+1. 校验 `content_id` 是否存在于本地资源包和应援脚本中。
+2. 根据 `state` 进入播放、暂停或停止逻辑。
+3. 使用 `position_ms` 对齐本地脚本时间轴。
+4. 根据 `speed` 调整后续动作触发时间。
+5. 若资源缺失或状态冲突，返回错误码并保持安全状态。
+
+## 5. 同步策略初稿
+
+- PC 上位机应周期性发送同步消息，例如每 500ms 一次。
+- 设备端可根据最近一次消息校准本地播放进度。
+- 当进度跳变超过阈值时，设备端应跳转到新的 `position_ms`。
+- 当状态变为 `stopped` 时，设备端应停止当前表现并清理临时动作。
+
+## 6. 与应援脚本关系
+
+- 应援脚本定义 `time_ms` 和动作内容。
+- 同步协议只负责广播当前播放位置和状态。
+- 设备端根据同步位置选择应执行的脚本动作。
+
+## 7. 待确认问题
+
+- 多设备同步精度目标，例如 50ms、100ms 或 200ms。
+- 时钟同步方案是否需要 NTP、主机时间戳或设备本地校准。
+- 丢包、断连和重连后的补偿策略。