ZWMAP Chapter Type Specification

1. Overview

The chapter type is used to describe structured segmentation information of videos, supporting timestamp markers, thumbnails, and colored segment markers on the progress bar.

2. ZWMAP Header

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

zwp_protocol and zwp_type are required fields. Backward compatibility is supported; in the absence of a header, the format is automatically detected based on content characteristics.

3. Data Structure

3.1 Root Level Fields

Field	Type	Required	Default	Description
`zwp_protocol`	string	Yes	—	Protocol identifier, fixed as `"ZWMAP/1.0"`
`zwp_type`	string	Yes	—	Fixed as `"chapter"`
`zwp_version`	string	No	`"1.0"`	Data format version
`chapters`	array	Yes	—	Array of chapter entries

3.2 Chapter Entry Object (ChapterItem)

Field	Type	Required	Default	Description
`title`	string	Yes	—	Chapter title
`time`	string\|number	Yes	—	Timestamp, supports `"HH:MM:SS"` format or seconds
`desc`	string	No	—	Chapter description
`duration`	number	No	—	Duration (seconds), used for progress bar colored segment markers
`style`	object	No	—	Style object
`style.background`	string	No	—	Background color of the progress bar marker
`image`	string\|null	No	—	Thumbnail URL
`thumb`	string	No	—	Alias of `image`

3.3 Time Format

The time field supports the following formats:

Format	Example	Description
HH:MM:SS	`"00:01:30"`	Hours:Minutes:Seconds
MM:SS	`"01:30"`	Minutes:Seconds
Pure number	`90`	Seconds

4. Complete Example

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "chapter",
  "zwp_version": "1.0",
  "chapters": [
    {
      "title": "Opening Remarks",
      "time": "00:00:00",
      "desc": "Course introduction",
      "duration": 30,
      "style": { "background": "#4CAF50" },
      "image": "https://cdn.zwplayer.com/thumb/intro.jpg"
    },
    {
      "title": "Chapter 1 Basic Concepts",
      "time": "00:00:30",
      "desc": "Introduction to basic theory",
      "duration": 120,
      "style": { "background": "#2196F3" },
      "image": "https://cdn.zwplayer.com/thumb/ch1.jpg"
    },
    {
      "title": "Chapter 2 Advanced Content",
      "time": "00:02:30",
      "desc": "In-depth understanding",
      "duration": 180,
      "style": { "background": "#FF9800" },
      "image": null
    },
    {
      "title": "Summary",
      "time": "00:05:30"
    }
  ]
}

5. Backward Compatibility

When no ZWMAP header is present, the player automatically detects via the following rules:

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

Detection rules:

Object contains a chapters array → Chapter format
Pure array + elements have time and title fields → Chapter format

6. Constraints

The chapters array must not be empty
Each entry must contain title and time
Chapters should be sorted in ascending order by time (the player does not enforce sorting, but it is recommended to keep them in order)
duration is an optional field; it should only be provided when colored segments are required on the progress bar
image and thumb serve the same function; thumb is a compatibility alias