ZWMAP 播放列表类型规范

1. 概述

播放列表类型用于描述一组有序的媒体内容集合，支持分组、自动播放和多种媒体格式。采用三层嵌套结构：播放列表 → 分组 → 视频项。

2. ZWMAP 头部

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

zwp_protocol 和 zwp_type 为必填字段。不支持向后兼容，必须携带 ZWMAP 协议头。

3. 数据结构

3.1 根级别字段

字段	类型	必填	默认值	说明
`zwp_protocol`	string	是	—	协议标识，固定 `"ZWMAP/1.0"`
`zwp_type`	string	是	—	固定 `"playlist"`
`zwp_version`	string	否	`"1.0"`	数据格式版本
`id`	string	否	标题转 Slug	播放列表唯一标识符，用于隔离进度和收藏
`title`	string	否	`""`	播放列表标题
`autoPlayNext`	boolean	否	`true`	是否自动播放下一项
`player_min_version`	string	否	—	最低播放器版本要求
`groups`	array	是	—	分组数组

3.2 分组对象 (Group)

字段	类型	必填	默认值	说明
`id`	string	否	自动生成	分组唯一标识符
`name`	string	是	—	分组显示名称
`expanded`	boolean	否	`true`	是否默认展开
`items`	array	是	—	视频项数组

3.3 视频项对象 (VideoItem)

字段	类型	必填	默认值	说明
`id`	string	否	自动生成	视频唯一标识符
`name`	string	是	—	视频显示名称
`url`	string	是	—	视频 URL
`type`	string	否	`"auto"`	视频类型
`isLive`	boolean	否	`false`	是否直播流
`poster`	string	否	—	海报图片 URL
`subtitle`	string\|array	否	—	字幕文件 URL（单个或数组）
`chapter`	string	否	—	章节 JSON 文件 URL
`annotation`	string	否	—	标注 JSON 文件 URL
`thumbnail`	string	否	—	缩略图 JSON 文件 URL
`watermark`	string	否	—	水印 JSON 文件 URL
`epg_now`	string	否	—	当前节目名称（EPG 信息）

3.4 支持的视频类型

type 值	说明	依赖
`mp4`	MP4 视频	浏览器原生支持
`hls`	HTTP Live Streaming	hls.js
`dash`	Dynamic Adaptive Streaming	dash.js
`flv`	HTTP FLV 流媒体	flv.js
`webrtc`	WebRTC 实时流	WebRTC API
`auto`	自动检测	根据文件特征判断

4. 完整示例

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "playlist",
  "zwp_version": "1.0",
  "id": "demo_list_001",
  "title": "演示播放列表",
  "autoPlayNext": true,
  "player_min_version": "3.2.2",
  "groups": [
    {
      "id": "g1",
      "name": "央视频道",
      "expanded": true,
      "items": [
        {
          "id": "cctv1",
          "name": "CCTV-1 综合",
          "url": "https://cdn.zwplayer.com/media/demo.mp4",
          "type": "mp4",
          "isLive": false,
          "poster": "https://cdn.zwplayer.com/poster/cctv1.jpg",
          "subtitle": [
            "https://cdn.zwplayer.com/sub/zh.bcc",
            "https://cdn.zwplayer.com/sub/en.bcc"
          ],
          "chapter": "https://cdn.zwplayer.com/chapter/demo.json",
          "annotation": "https://cdn.zwplayer.com/annotation/demo.json",
          "thumbnail": "https://cdn.zwplayer.com/thumbnail/demo.json",
          "watermark": "https://cdn.zwplayer.com/watermark/demo.json",
          "epg_now": "新闻联播"
        }
      ]
    },
    {
      "id": "g2",
      "name": "教育视频",
      "expanded": false,
      "items": [
        {
          "id": "edu01",
          "name": "数学基础",
          "url": "https://cdn.zwplayer.com/media/math.mp4",
          "type": "mp4"
        }
      ]
    }
  ]
}

5. 约束规则

zwp_protocol 和 zwp_type 为必填字段，缺少则拒绝加载
groups 为必填字段，必须包含至少一个分组
每个 VideoItem 的 url 必填
type 为 auto 时，播放器根据 URL 后缀和内容自动判断
subtitle 可以是字符串（单个字幕）或数组（多字幕）
chapter、annotation、thumbnail 和 watermark 引用的 JSON 文件也建议使用 ZWMAP 协议头