ZWMAP Thumbnail Type Specification

1. Overview

The thumbnail type is used to describe the sprite sheet configuration information for video progress bar preview images. Frames extracted from the video are stitched into a single large image, and combined with coordinate calculations, the preview image corresponding to a specific point in time is displayed when hovering over the progress bar.

2. ZWMAP Header

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

zwp_protocol and zwp_type are required fields. Backward compatibility is not supported; the ZWMAP protocol header must be included.

3. Data Structure

3.1 Root Level Fields

Field	Type	Required	Default	Description
`zwp_protocol`	string	Yes	—	Protocol identifier, fixed value `"ZWMAP/1.0"`
`zwp_type`	string	Yes	—	Fixed value `"thumbnail"`
`zwp_version`	string	No	`"1.0"`	Data format version
`thumbnail`	object	Yes	—	Sprite sheet configuration object

3.2 Sprite Sheet Configuration Object

Field	Type	Required	Default	Description
`url`	string	Yes	—	Sprite sheet access URL (JPG/PNG)
`width`	number	Yes	—	Single frame width (pixels)
`height`	number	Yes	—	Single frame height (pixels)
`col`	number	Yes	—	Column count (frames per row)
`row`	number	Yes	—	Row count
`total`	number	Yes	—	Total number of valid frames

3.3 Field Descriptions

url: The access URL of the sprite sheet file, supporting JPG and PNG formats.
width/height: Dimensions of a single frame (in pixels), used to calculate the backgroundPosition offset.
col: The number of frames contained in each row, used to calculate the horizontal offset.
row: The total number of rows in the sprite sheet, used to calculate the vertical offset.
total: The total number of valid frames; the last row may not be full.

3.4 Relationship with ZWPlayer Configuration

ZWPlayer’s thumbnails configuration object uses the row field as rowsize (number of columns per row), which is semantically equivalent to the col field in this protocol:

// ZWPlayer internal logic
thumbnails.rowsize = typeof thumbnails.row == 'number'
  ? thumbnails.row
  : Math.ceil(Math.sqrt(thumbnails.total));

// Offset calculation:
// tx = width * (pic_no % rowsize)   → Column direction offset
// ty = height * Math.floor(pic_no / rowsize)  → Row direction offset

Mapping relationship: ZWMAP protocol’s col → ZWPlayer configuration’s row (rowsize).

4. Complete Example

{
  "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
  }
}

This example describes a 10×10 sprite sheet containing 100 frames in total, with each frame being 160×90 pixels. The total video duration is evenly divided into 100 time points. When the mouse hovers over any position on the progress bar, ZWPlayer calculates the backgroundPosition based on the corresponding frame index to display the preview image.

5. Constraint Rules

The thumbnail object is required and cannot be empty.
url must be an accessible image address.
width, height, col, row, and total must all be positive integers.
total should be less than or equal to col × row.
Frames in the sprite sheet should be sampled uniformly along the video timeline.