ZWMAP 字幕类型规范

1. 概述

字幕类型用于描述视频的文本字幕数据，基于 BCC (Bilibili Closed Caption) JSON 格式扩展。仅适用于 JSON 格式的字幕，VTT/SRT 等文本格式不在本规范范围内。

2. ZWMAP 头部

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

zwp_protocol 和 zwp_type 为必填字段。支持向后兼容，无头部时通过内容特征自动探测。

3. 数据结构

3.1 根级别字段

字段	类型	必填	默认值	说明
`zwp_protocol`	string	是	—	协议标识，固定 `"ZWMAP/1.0"`
`zwp_type`	string	是	—	固定 `"subtitle"`
`zwp_version`	string	否	`"1.0"`	数据格式版本
`font_size`	number	否	`0.4`	字体大小（相对值）
`font_color`	string	否	`"#FFFFFF"`	字体颜色
`background_alpha`	number	否	`0.5`	背景透明度（0-1）
`background_color`	string	否	`"#000000"`	背景颜色
`Stroke`	string	否	`"none"`	描边样式（大写首字母为 BCC 格式历史遗留命名）
`body`	array	是	—	字幕条目数组

3.2 字幕条目对象 (SubtitleCue)

字段	类型	必填	默认值	说明
`from`	number	是	—	开始时间（秒）
`to`	number	是	—	结束时间（秒）
`content`	string	是	—	字幕文本内容
`location`	number	否	`2`	显示位置：`1`=顶部，`2`=底部

4. 完整示例

{
  "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": "这是第一段字幕",
      "location": 2
    },
    {
      "from": 5.5,
      "to": 10.0,
      "content": "这是第二段字幕",
      "location": 2
    },
    {
      "from": 10.5,
      "to": 16.1,
      "content": "最后一段字幕",
      "location": 1
    }
  ]
}

5. 向后兼容

无 ZWMAP 头部时，播放器通过检测 body 字段存在且为数组来识别 BCC JSON 旧格式：

{
  "font_size": 0.4,
  "font_color": "#FFFFFF",
  "body": [
    { "from": 1.0, "to": 5.0, "content": "字幕文本" }
  ]
}

6. 与其他格式的关系

ZWPlayer 同时支持以下字幕格式（不使用 ZWMAP 协议头）：

格式	文件扩展名	说明
BCC JSON	`.bcc`	Bilibili 字幕格式，与 ZWMAP subtitle 兼容
WebVTT	`.vtt`	W3C 标准字幕格式
SubRip	`.srt`	通用字幕格式

当文件以 .bcc 扩展名提供时，播放器按 JSON 格式解析。ZWMAP 格式是 BCC JSON 的超集。

7. 约束规则

body 数组不得为空
每个条目的 from 必须小于 to
条目之间的时间范围可以重叠（用于多位置显示）
content 支持纯文本，不支持 HTML 标签
location 仅支持 1（顶部）和 2（底部）
时间精度为浮点数秒，支持小数