ZWMAP 缩略图类型规范

1. 概述

缩略图类型用于描述视频进度条预览图的雪碧图（Sprite Sheet）配置信息。将视频中提取的帧拼合成一张大图，配合坐标计算在进度条悬停时显示对应时间点的预览画面。

2. ZWMAP 头部

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

zwp_protocol 和 zwp_type 为必填字段。不支持向后兼容，必须携带 ZWMAP 协议头。

3. 数据结构

3.1 根级别字段

字段	类型	必填	默认值	说明
`zwp_protocol`	string	是	—	协议标识，固定 `"ZWMAP/1.0"`
`zwp_type`	string	是	—	固定 `"thumbnail"`
`zwp_version`	string	否	`"1.0"`	数据格式版本
`thumbnail`	object	是	—	雪碧图配置对象

3.2 雪碧图配置对象

字段	类型	必填	默认值	说明
`url`	string	是	—	雪碧图访问地址（JPG/PNG）
`width`	number	是	—	单帧宽度（像素）
`height`	number	是	—	单帧高度（像素）
`col`	number	是	—	列数（每行帧数）
`row`	number	是	—	行数
`total`	number	是	—	有效帧总数

3.3 字段说明

url：雪碧图文件的访问地址，支持 JPG 和 PNG 格式
width/height：单个帧的尺寸（像素），用于计算 backgroundPosition 偏移
col：每行包含的帧数，用于计算水平偏移
row：雪碧图的总行数，用于计算垂直偏移
total：有效帧的总数量，最后一行可能不满

3.4 与 ZWPlayer 配置的关系

ZWPlayer 的 thumbnails 配置对象使用 row 字段作为 rowsize（每行列数），语义等同于本协议的 col：

// ZWPlayer 内部逻辑
thumbnails.rowsize = typeof thumbnails.row == 'number'
  ? thumbnails.row
  : Math.ceil(Math.sqrt(thumbnails.total));

// 偏移计算：
// tx = width * (pic_no % rowsize)   → 列方向偏移
// ty = height * Math.floor(pic_no / rowsize)  → 行方向偏移

映射关系： ZWMAP 协议的 col → ZWPlayer 配置的 row（rowsize）。

4. 完整示例

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "thumbnail",
  "zwp_version": "1.0",
  "thumbnail": {
    "url": "https://cdn.example.com/thumbnails/sprite.jpg",
    "width": 160,
    "height": 90,
    "col": 10,
    "row": 10,
    "total": 100
  }
}

此示例描述了一个 10×10 的雪碧图，共 100 帧，每帧 160×90 像素。视频总时长被均匀分为 100 个时间点，鼠标悬停在进度条上的任意位置时，ZWPlayer 根据对应帧索引计算 backgroundPosition 显示预览图。

5. 约束规则

thumbnail 对象为必填，不可为空
url 必须为可访问的图片地址
width、height、col、row、total 均为正整数
total 应小于等于 col × row
雪碧图中的帧应按视频时间轴均匀抽取