中文
Docs / ZWMAP Playlist Specification

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. Use the Online Playlist Editor to visually manage and export playlist data.

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
music object No — Global music configuration defaults (see field table below); applies to mediaKind:"audio" items only
groups array Yes — Array of groups

music object fields (root-level, list defaults):

Sub-field Type Default Description
panel 'full' | 'bar' 'full' Panel style: full-screen panel or compact bottom bar
visualizer 'classic' | 'vintage' | 'mountain' | 'bars' | 'circular' | 'mirror' | false 'classic' Spectrum visualizer shape
theme 'auto' | 'vintage' | 'classic' | '#hex' 'auto' Theme skin
vinyl bool true Vinyl rotation animation
blurBackground bool true Frosted glass background
mediaSession bool true System media key integration

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 media items

3.3 Media Item Object (VideoItem / AudioItem)

Field Type Required Default Description
id string No Auto-generated Unique item identifier
name string Yes — Display name
url string Yes — Media playback URL
type string No "auto" Media container format (mp4/hls/flv/dash/webrtc/auto)
mediaKind string No "video" Media kind: "video" (video, default) / "audio" (audio, triggers music mode)
isLive boolean No false Whether it is a live stream
poster string No — Poster image URL (album cover for audio items)
artist string No — Artist / Performer (displayed when mediaKind: "audio")
lyrics string|array No — Lyrics file URL or text lines array (used when mediaKind: "audio")
music object No — Single-track music config (e.g. theme track theme color)
subtitle string|array No — Subtitle file URL (single or array)
audioTracks string|array No — Dubbing audio track URL (single or array). Elements can be URL strings or {url, language, label, default} objects; see Audio Tracks
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"
          ],
          "audioTracks": [
            { "url": "https://cdn.zwplayer.com/dub/ja.m4a", "language": "ja", "label": "Japanese dubbing", "default": true },
            { "url": "https://cdn.zwplayer.com/dub/zh.m4a", "language": "zh", "label": "Chinese dubbing" }
          ],
          "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

  1. zwp_protocol and zwp_type are required fields; loading will be rejected if missing
  2. groups is a required field and must contain at least one group
  3. url is required for every VideoItem
  4. When type is auto, the player automatically determines the type based on URL extension and content
  5. subtitle can be a string (single subtitle) or an array (multiple subtitles)
  6. audioTracks can be a string (single dubbing URL), an array (multiple tracks), or an array of objects ({url, language, label, default}). The track with default: true is automatically activated when switching to that video item
  7. JSON files referenced by chapter, annotation, thumbnail, and watermark are also recommended to use the ZWMAP protocol header
Previous Annotation Next Watermark