视频缩略图雪碧图生成器 — 使用指南

快速入门

缩略图雪碧图生成器（又称"悬停预览图"或"进度条预览图"工具）是一款免费的在线工具，可以从视频中提取帧并将它们拼合为一张雪碧图。当用户将鼠标悬停在播放器进度条上时，即可看到对应时间点的预览画面——就像 B 站、腾讯视频、爱奇艺等主流平台那样的悬停预览效果。

快速上手步骤

1. 加载视频

   将本地视频文件（MP4、WebM）拖拽到窗口中，或者在地址栏中粘贴远程视频 URL 并按回车键。

2. 配置采样

   选择采样模式：固定间隔（例如每 5 秒）或指定帧数（例如均匀分布 100 帧）。调整帧尺寸和输出格式。

3. 生成雪碧图

   点击"生成雪碧图"按钮（或按 G 键）。工具将提取帧并将它们组合成一张网格图像。

4. 预览和导出

   使用 ZWPlayer 内置的缩略图预览功能预览结果（按 P 键）。下载雪碧图、导出 ZWMAP JSON，或同时获取两者的 ZIP 包。

键盘快捷键

使用以下键盘快捷键提高工作效率：

配置选项

采样模式

帧尺寸

网格布局

输出设置

输出格式

生成雪碧图后，您可以下载以下三种格式的结果：

1. 雪碧图

一张包含所有提取帧的网格图像文件（thumbnail.jpg 或 .png）。这是用于视频播放器在进度条上显示缩略图预览的主要输出。

2. ZWMAP JSON

遵循 ZWMAP/1.0 协议的 JSON 文件（{title}_thumbnail.json）。包含缩略图 URL、帧尺寸、网格布局和总帧数。用于服务端配置和 CMS 集成。

JSON 面板可直接编辑或粘贴配置，点击"应用"将宽/高/列数与输出格式回写到配置表单；"重置"恢复最近应用的内容。total 字段由已截取帧数派生，无法从文本应用。

3. ZIP 打包

包含缩略图和 ZWMAP JSON 文件的 ZIP 压缩包（{title}.zip）。方便一次性下载和部署。

ZWMAP 缩略图协议规范

ZWMAP（Z&W 媒体标注协议）缩略图类型定义了描述视频缩略图雪碧图的标准 JSON 格式。该协议实现了缩略图生成工具与视频播放器之间的互操作性。

协议头部

每个 ZWMAP 缩略图文档以协议标识符开头：

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

缩略图对象字段

完整示例

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

此示例描述了一个 10×10 的雪碧图，包含 100 帧，每帧 160×90 像素。当用户悬停在视频进度条上时，播放器根据悬停位置相对于总时长的比例来计算显示哪一帧。

ZWPlayer 集成

ZWPlayer 是一个功能丰富的 JavaScript 视频播放器，开箱即用支持缩略图预览。以下是如何将生成的雪碧图与 ZWPlayer 集成。

播放器配置

在 ZWPlayer 初始化配置中添加 thumbnails 属性：

var player = new ZWPlayer({
  playerElm: 'mse',
  url: 'https://cdn.example.com/video.mp4',
  thumbnails: {
    url: 'https://cdn.example.com/thumbnails/thumbnail.jpg',
    width: 160,
    height: 90,
    row: 10,      // rowsize = ZWMAP's "col" value
    total: 100
  }
});

从工具复制配置

生成完成后，JSON 面板中提供了可直接使用的 ZWPlayer 配置片段。点击复制按钮即可直接复制。

实时预览

按 P 键或点击预览按钮，打开一个完整的 ZWPlayer 实例并加载生成的雪碧图。将鼠标悬停在进度条上即可看到缩略图预览效果。按 Esc 键退出。

使用 ZWMAP JSON

如果将缩略图存储在服务器上，将 ZWMAP JSON 文件放在已知 URL。您的应用可以获取该 JSON 并将解析后的 thumbnail 对象直接传递给 ZWPlayer 配置（注意 col → row 映射）。

使用 JSON URL

除了传入对象，还可以直接将 ZWMAP JSON 文件的 URL 作为字符串传入，ZWPlayer 会自动获取并解析：

var player = new ZWPlayer({
  playerElm: 'mse',
  url: 'https://cdn.example.com/video.mp4',
  thumbnails: 'https://cdn.example.com/thumbnails/movie_thumbnail.json'
});

拖拽加载

您还可以通过将文件直接拖拽到 ZWPlayer 播放器上来加载缩略图：

• 单独拖拽缩略图 JSON：将 *_thumbnail.json 文件拖入播放器，为当前播放的视频加载缩略图。
• 同时拖拽视频和缩略图：将视频文件与对应的缩略图 JSON 及雪碧图一起拖入，播放器会自动按文件名匹配（例如 movie.mp4 匹配 movie_thumbnail.json）。
• 播放列表拖拽：拖入多个视频及对应的缩略图文件，自动创建带缩略图预览的播放列表。

常见问题