# 演唱会播放同步协议

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