protocol-docs/docs/concert_sync_protocol.md

演唱会播放同步协议

本文档定义 PC 同步播放器如何向 AI球设备同步 content_id、position_ms、state 和 speed。

1. 目标

• 支持多台 AI球在演唱会或活动现场按同一时间轴执行应援脚本。
• 支持播放、暂停、停止、跳转和倍速等基础同步控制。
• 允许设备端根据本地资源包和应援脚本独立执行动作。

2. 同步消息

{
  "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、主机时间戳或设备本地校准。
• 丢包、断连和重连后的补偿策略。