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	否	—	最低播放器版本要求
`music`	object	否	—	全局音乐配置默认值（字段详见下表），仅 `mediaKind:"audio"` 的 item 播放时生效
`groups`	array	是	—	分组数组

music 对象字段（根级，列表级默认值）：

子字段	类型	默认值	说明
`panel`	`'full'` \| `'bar'`	`'full'`	面板形态：`'full'`（全屏面板）或 `'bar'`（紧凑底条）
`visualizer`	`'classic'` \| `'vintage'` \| `'mountain'` \| `'bars'` \| `'circular'` \| `'mirror'` \| `false`	`'classic'`	频谱可视化形态
`theme`	`'auto'` \| `'vintage'` \| `'classic'` \| `'#hex'`	`'auto'`	主题皮肤
`vinyl`	bool	`true`	唱片旋转动效
`blurBackground`	bool	`true`	毛玻璃背景
`mediaSession`	bool	`true`	系统媒体键集成

3.2 分组对象 (Group)

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

3.3 媒体项对象 (VideoItem / AudioItem)

字段	类型	必填	默认值	说明
`id`	string	否	自动生成	唯一标识符
`name`	string	是	—	节目显示名称
`url`	string	是	—	媒体播放 URL
`type`	string	否	`"auto"`	媒体容器格式（`mp4`/`hls`/`flv`/`dash`/`webrtc`/`auto`）
`mediaKind`	string	否	`"video"`	媒体种类：`"video"`（视频，默认） / `"audio"`（音频，触发音乐播放形态）
`isLive`	boolean	否	`false`	是否直播流
`poster`	string	否	—	海报图片 URL（音频项即唱片封面）
`artist`	string	否	—	艺人/歌手（仅 `mediaKind: "audio"` 显示）
`lyrics`	string\|array	否	—	歌词文件 URL 或文本行数组（仅 `mediaKind: "audio"` 生效）
`music`	object	否	—	单曲级音乐参数（如 `theme` 单曲主题色）
`subtitle`	string\|array	否	—	字幕文件 URL（单个或数组）
`audioTracks`	string\|array	否	—	配音音轨 URL（单个或数组）。元素为 URL 字符串或 `{url, language, label, default}` 对象，详见音轨设置
`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"
          ],
          "audioTracks": [
            { "url": "https://cdn.zwplayer.com/dub/ja.m4a", "language": "ja", "label": "日语配音", "default": true },
            { "url": "https://cdn.zwplayer.com/dub/zh.m4a", "language": "zh", "label": "中文配音" }
          ],
          "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 可以是字符串（单个字幕）或数组（多字幕）
audioTracks 可以是字符串（单个配音 URL）、数组（多配音）或对象数组（{url, language, label, default}）。default: true 的音轨会在切换到该视频项时自动激活
chapter、annotation、thumbnail 和 watermark 引用的 JSON 文件也建议使用 ZWMAP 协议头