ZWMAP Subtitle Type Specification

1. Overview

The subtitle type is used to describe text subtitle data for video, extending the BCC (Bilibili Closed Caption) JSON format. It is applicable only to JSON format subtitles; text formats such as VTT/SRT are outside the scope of this specification.

2. ZWMAP Header

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

zwp_protocol and zwp_type are mandatory fields. Backwards compatibility is supported; if the header is absent, automatic detection is performed based on content characteristics.

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 `"subtitle"`
`zwp_version`	string	No	`"1.0"`	Data format version
`font_size`	number	No	`0.4`	Font size (relative value)
`font_color`	string	No	`"#FFFFFF"`	Font color
`background_alpha`	number	No	`0.5`	Background opacity (0-1)
`background_color`	string	No	`"#000000"`	Background color
`Stroke`	string	No	`"none"`	Stroke style (capitalized first letter is a BCC format legacy naming)
`body`	array	Yes	—	Array of subtitle entries

3.2 Subtitle Entry Object (SubtitleCue)

Field	Type	Required	Default	Description
`from`	number	Yes	—	Start time (seconds)
`to`	number	Yes	—	End time (seconds)
`content`	string	Yes	—	Subtitle text content
`location`	number	No	`2`	Display position: `1`=Top, `2`=Bottom

4. Complete Example

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "subtitle",
  "zwp_version": "1.0",
  "font_size": 0.4,
  "font_color": "#FFFFFF",
  "background_alpha": 0.5,
  "background_color": "#000000",
  "Stroke": "none",
  "body": [
    {
      "from": 1.0,
      "to": 5.0,
      "content": "This is the first subtitle",
      "location": 2
    },
    {
      "from": 5.5,
      "to": 10.0,
      "content": "This is the second subtitle",
      "location": 2
    },
    {
      "from": 10.5,
      "to": 16.1,
      "content": "The last subtitle",
      "location": 1
    }
  ]
}

5. Backward Compatibility

When there is no ZWMAP header, the player identifies the legacy BCC JSON format by detecting that the body field exists and is an array:

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

6. Relationship with Other Formats

ZWPlayer also supports the following subtitle formats (which do not use the ZWMAP protocol header):

Format	File Extension	Description
BCC JSON	`.bcc`	Bilibili subtitle format, compatible with ZWMAP subtitle
WebVTT	`.vtt`	W3C standard subtitle format
SubRip	`.srt`	Common subtitle format

When a file is provided with a .bcc extension, the player parses it as JSON format. ZWMAP format is a superset of BCC JSON.

7. Constraints

The body array must not be empty
The from value of each entry must be less than to
Time ranges between entries may overlap (for multi-position display)
content supports plain text only; HTML tags are not supported
location only supports 1 (top) and 2 (bottom)
Time precision is in floating-point seconds; decimals are supported