ZWMAP Protocol Overview

1. What is ZWMAP

ZWMAP (ZWPlayer Media Application Protocol) is the media data exchange protocol for the ZWPlayer player, used to standardize five JSON data formats: playlists, subtitles, chapters, thumbnails, and annotations. Through unified protocol header fields, it enables automatic identification of data types and version management.

Current version: ZWMAP/1.0

2. Protocol Composition

3. Protocol Header Fields

All JSON documents compliant with the ZWMAP protocol include a set of protocol header fields prefixed with zwp_ at the root level:

3.1 Minimal Example

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "playlist",
  "groups": []
}

3.2 Field Naming Rules

• Protocol header fields uniformly use the zwp_ prefix to avoid conflicts with business data fields
• Business data fields maintain their original naming style
• Newly added protocol fields must not duplicate existing business field names

3.3 Protocol Version Strategy

The version number of zwp_protocol follows these rules:

• Major version: Incompatible protocol changes (e.g., adding required fields, removing fields)
• Minor version: Backward compatible protocol changes (e.g., adding optional fields)

The player should check if the major version of zwp_protocol is supported and ignore unrecognized optional fields.

4. Detection Logic

The player determines if JSON is in ZWMAP format through the following steps:

1. Parse JSON object
2. Check if the zwp_protocol field exists
3. Check if its value starts with "ZWMAP/"
4. Read zwp_type to determine the data type
5. Route to the corresponding type handler

5. Backward Compatibility Rules

When loading JSON data, ZWPlayer first checks if it contains a ZWMAP protocol header. For subtitle and chapter types, if no protocol header exists, it automatically detects the data type based on content characteristics to maintain backward compatibility. Playlist, thumbnail, and annotation do not support backward compatibility and must carry the ZWMAP protocol header.

5.1 Compatibility Strategy

5.2 Backward Compatibility Detection Flow

Parse JSON
    │
    ├─ Check zwp_protocol field
    │   │
    │   ├─ Exists and starts with "ZWMAP/" → Read zwp_type, route to corresponding handler
    │   │
    │   └─ Does not exist → Enter backward compatibility detection (subtitle and chapter only)
    │
    └─ Backward compatibility detection rules (by priority):
        │
        ├─ 1. data.body exists and is an array → subtitle
        ├─ 2. data.chapters exists and is an array → chapter
        ├─ 3. Array.isArray(data) and elements have time+title → chapter
        │
        └─ Unrecognizable → Error

5.3 Backward Compatibility Examples

Subtitle Old Format (BCC JSON):

{
  "font_size": 0.4,
  "font_color": "#FFFFFF",
  "body": [
    { "from": 1.0, "to": 5.0, "content": "Subtitle text" }
  ]
}

Chapter Old Format (Pure Array):

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

6. Design Principles

1. Minimal Intrusion: Protocol header fields are named with the zwp_ prefix to avoid conflicts with business fields
2. Selective Compatibility: Subtitles and chapters maintain backward compatibility, while playlists and annotations require the ZWMAP header
3. Version Control: Support for future protocol upgrades via the zwp_protocol version number
4. Self-Descriptive: Any ZWMAP JSON can self-identify its type and version through header fields