ZWMAP 章节类型规范

1. 概述

章节类型用于描述视频的结构化分段信息，支持时间点标记、缩略图和进度条上的彩色段标记。

2. ZWMAP 头部

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "chapter"
}

zwp_protocol 和 zwp_type 为必填字段。支持向后兼容，无头部时通过内容特征自动探测。

3. 数据结构

3.1 根级别字段

字段	类型	必填	默认值	说明
`zwp_protocol`	string	是	—	协议标识，固定 `"ZWMAP/1.0"`
`zwp_type`	string	是	—	固定 `"chapter"`
`zwp_version`	string	否	`"1.0"`	数据格式版本
`chapters`	array	是	—	章节条目数组

3.2 章节条目对象 (ChapterItem)

字段	类型	必填	默认值	说明
`title`	string	是	—	章节标题
`time`	string\|number	是	—	时间点，支持 `"HH:MM:SS"` 格式或秒数
`desc`	string	否	—	章节描述
`duration`	number	否	—	持续时间（秒），用于进度条彩色段标记
`style`	object	否	—	样式对象
`style.background`	string	否	—	进度条标记的背景颜色
`image`	string\|null	否	—	缩略图 URL
`thumb`	string	否	—	`image` 的别名

3.3 时间格式

time 字段支持以下格式：

格式	示例	说明
HH:MM:SS	`"00:01:30"`	时:分:秒
MM:SS	`"01:30"`	分:秒
纯数字	`90`	秒数

4. 完整示例

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "chapter",
  "zwp_version": "1.0",
  "chapters": [
    {
      "title": "开场白",
      "time": "00:00:00",
      "desc": "课程介绍",
      "duration": 30,
      "style": { "background": "#4CAF50" },
      "image": "https://cdn.zwplayer.com/thumb/intro.jpg"
    },
    {
      "title": "第一章 基础概念",
      "time": "00:00:30",
      "desc": "基本理论介绍",
      "duration": 120,
      "style": { "background": "#2196F3" },
      "image": "https://cdn.zwplayer.com/thumb/ch1.jpg"
    },
    {
      "title": "第二章 进阶内容",
      "time": "00:02:30",
      "desc": "深入理解",
      "duration": 180,
      "style": { "background": "#FF9800" },
      "image": null
    },
    {
      "title": "总结",
      "time": "00:05:30"
    }
  ]
}

5. 向后兼容

无 ZWMAP 头部时，播放器通过以下规则自动探测：

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

探测规则：

对象含 chapters 数组 → 章节格式
纯数组 + 元素有 time 和 title 字段 → 章节格式

6. 约束规则

chapters 数组不得为空
每个条目必须包含 title 和 time
章节应按 time 升序排列（播放器不强制排序，但建议按序）
duration 为可选字段，仅在需要在进度条上显示彩色段时提供
image 和 thumb 功能相同，thumb 为兼容别名