ZWMAP Playlist Type Specification

1. Overview

The playlist type is used to describe an ordered collection of media content, supporting grouping, autoplay, and multiple media formats. It adopts a three-layer nested structure: Playlist → Group → VideoItem.

2. ZWMAP Header

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

zwp_protocol and zwp_type are required fields. Backward compatibility is not supported, the ZWMAP protocol header must be included.

3. Data Structure

3.1 Root Level Fields

Field	Type	Required	Default	Description
`zwp_protocol`	string	Yes	—	Protocol identifier, fixed `"ZWMAP/1.0"`
`zwp_type`	string	Yes	—	Fixed `"playlist"`
`zwp_version`	string	No	`"1.0"`	Data format version
`id`	string	No	Title to Slug	Unique playlist identifier, used for isolating progress and favorites
`title`	string	No	`""`	Playlist title
`autoPlayNext`	boolean	No	`true`	Whether to autoplay the next item
`player_min_version`	string	No	—	Minimum player version requirement
`groups`	array	Yes	—	Array of groups

3.2 Group Object

Field	Type	Required	Default	Description
`id`	string	No	Auto-generated	Unique group identifier
`name`	string	Yes	—	Group display name
`expanded`	boolean	No	`true`	Whether to expand by default
`items`	array	Yes	—	Array of video items

3.3 VideoItem Object

Field	Type	Required	Default	Description
`id`	string	No	Auto-generated	Unique video identifier
`name`	string	Yes	—	Video display name
`url`	string	Yes	—	Video URL
`type`	string	No	`"auto"`	Video type
`isLive`	boolean	No	`false`	Whether it is a live stream
`poster`	string	No	—	Poster image URL
`subtitle`	string\|array	No	—	Subtitle file URL (single or array)
`chapter`	string	No	—	Chapter JSON file URL
`annotation`	string	No	—	Annotation JSON file URL
`thumbnail`	string	No	—	Thumbnail JSON file URL
`watermark`	string	No	—	Watermark JSON file URL
`epg_now`	string	No	—	Current program name (EPG info)

3.4 Supported Video Types

type Value	Description	Dependency
`mp4`	MP4 Video	Native browser support
`hls`	HTTP Live Streaming	hls.js
`dash`	Dynamic Adaptive Streaming	dash.js
`flv`	HTTP FLV Streaming	flv.js
`webrtc`	WebRTC Live Stream	WebRTC API
`auto`	Auto Detect	Determined by file characteristics

4. Complete Example

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "playlist",
  "zwp_version": "1.0",
  "id": "demo_list_001",
  "title": "Demo Playlist",
  "autoPlayNext": true,
  "player_min_version": "3.2.2",
  "groups": [
    {
      "id": "g1",
      "name": "Satellite Channels",
      "expanded": true,
      "items": [
        {
          "id": "cctv1",
          "name": "CCTV-1 Comprehensive",
          "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": "Xinwen Lianbo"
        }
      ]
    },
    {
      "id": "g2",
      "name": "Educational Videos",
      "expanded": false,
      "items": [
        {
          "id": "edu01",
          "name": "Math Basics",
          "url": "https://cdn.zwplayer.com/media/math.mp4",
          "type": "mp4"
        }
      ]
    }
  ]
}

5. Constraints

zwp_protocol and zwp_type are required fields; loading will be rejected if missing
groups is a required field and must contain at least one group
url is required for every VideoItem
When type is auto, the player automatically determines the type based on URL extension and content
subtitle can be a string (single subtitle) or an array (multiple subtitles)
JSON files referenced by chapter, annotation, thumbnail, and watermark are also recommended to use the ZWMAP protocol header