ZWMAP 协议概述

1. 什么是 ZWMAP

ZWMAP（ZWPlayer Media Application Protocol）是 ZWPlayer 播放器的媒体数据交换协议，用于规范化播放列表、字幕、章节、缩略图和标注五种 JSON 数据格式。通过统一的协议头字段，实现数据类型的自动识别和版本管理。

当前版本：ZWMAP/1.0

2. 协议组成

数据类型	zwp_type 值	说明
播放列表	`playlist`	一组有序的媒体内容集合
字幕	`subtitle`	视频文本字幕数据
章节	`chapter`	视频结构化分段信息
缩略图	`thumbnail`	进度条预览图雪碧图配置
标注	`annotation`	视频画面交互区域和事件

3. 协议头字段

所有符合 ZWMAP 协议的 JSON 文档在根级别包含一组以 zwp_ 为前缀的协议头字段：

字段	类型	必填	默认值	说明
`zwp_protocol`	string	是	—	协议标识符，格式为 `"ZWMAP/<major>.<minor>"`，当前版本为 `"ZWMAP/1.0"`
`zwp_type`	string	是	—	数据类型标识，取值：`playlist` / `subtitle` / `chapter` / `annotation` / `thumbnail`
`zwp_version`	string	否	`"1.0"`	数据内容的语义版本号
`zwp_encoding`	string	否	`"utf-8"`	文档编码声明
`zwp_id`	string	否	—	文档唯一标识符，用于引用、缓存和去重

3.1 最小示例

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "playlist",
  "groups": []
}

3.2 字段命名规则

协议头字段统一使用 zwp_ 前缀，避免与业务数据字段冲突
业务数据字段保持原有的命名风格不变
新增的协议字段不得与现有业务字段重名

3.3 协议版本策略

zwp_protocol 的版本号遵循以下规则：

主版本号 (major)：不兼容的协议变更（如新增必填字段、删除字段）
次版本号 (minor)：向后兼容的协议变更（如新增可选字段）

播放器应检查 zwp_protocol 的主版本号是否支持，忽略无法识别的可选字段。

4. 检测逻辑

播放器通过以下步骤判断 JSON 是否为 ZWMAP 格式：

解析 JSON 对象
检查是否存在 zwp_protocol 字段
检查其值是否以 "ZWMAP/" 开头
读取 zwp_type 确定数据类型
路由到对应的类型处理器

5. 向后兼容规则

ZWPlayer 在加载 JSON 数据时，首先检查是否包含 ZWMAP 协议头。对于字幕和章节类型，若不存在协议头，则通过内容特征自动探测数据类型以保持向后兼容。播放列表、缩略图和标注不支持向后兼容，必须携带 ZWMAP 协议头。

5.1 兼容性策略

类型	向后兼容	说明
`playlist`	否	必须携带 `zwp_protocol` 和 `zwp_type`
`annotation`	否	必须携带 `zwp_protocol` 和 `zwp_type`
`thumbnail`	否	必须携带 `zwp_protocol` 和 `zwp_type`
`subtitle`	是	无头部时通过 `body` 字段探测，兼容 BCC JSON
`chapter`	是	无头部时通过内容特征探测，兼容纯数组格式

5.2 向后兼容探测流程

解析 JSON
    │
    ├─ 检查 zwp_protocol 字段
    │   │
    │   ├─ 存在且以 "ZWMAP/" 开头 → 读取 zwp_type，路由到对应处理器
    │   │
    │   └─ 不存在 → 进入向后兼容探测（仅 subtitle 和 chapter）
    │
    └─ 向后兼容探测规则（按优先级）：
        │
        ├─ 1. data.body 存在且是数组 → subtitle
        ├─ 2. data.chapters 存在且是数组 → chapter
        ├─ 3. Array.isArray(data) 且元素有 time+title → chapter
        │
        └─ 无法识别 → 报错

5.3 向后兼容示例

字幕旧格式（BCC JSON）：

{
  "font_size": 0.4,
  "font_color": "#FFFFFF",
  "body": [
    { "from": 1.0, "to": 5.0, "content": "字幕文本" }
  ]
}

章节旧格式（纯数组）：

[
  { "title": "章节1", "time": "00:00:00" },
  { "title": "章节2", "time": "00:02:00" }
]

6. 设计原则

最小侵入：协议头字段以 zwp_ 前缀命名，不与业务字段冲突
选择性兼容：字幕和章节保持向后兼容，播放列表和标注强制使用 ZWMAP 头部
版本可控：通过 zwp_protocol 的版本号支持未来协议升级
自描述性：任何 ZWMAP JSON 都可通过头部字段自我标识类型和版本