进度条预览图设置

1. 功能概述

zwplayer 支持在播放进度条上显示视频预览图。当鼠标在进度条上移动时，会显示对应时间点的视频帧缩略图，方便用户快速预览视频内容。

2. 缩略图准备

2.1 缩略图生成要求

要实现预览图，必须提前从视频中抽取视频帧缩略图，并将每个视频帧缩略图拼合成一张大图，如下图所示：

如上图所示的示例缩略图，提取的每个视频帧缩略图被拼合成一张大图，每行8个小图（视频帧），共8行。注意：不同的视频抽取的缩略图都是不一样的，行数与列数可能都不相同。

注意事项：

• 缩略图需按视频时间轴均匀抽取
• 每帧间隔时间 = 视频总时长 ÷ 抽取帧数
• 不按规则抽帧可能导致预览时间点不准确
• 缩略图间隔越短，预览越精准，但文件尺寸越大

2.2 缩略图参数格式

缩略图支持以下三种传入格式：

格式一：直接传入对象

按照以下 JavaScript 对象格式配置缩略图信息：

var thumbnailInfo = {
    "url": "http://example.com/images/movie_thumbnail.jpg",
    "width": 128,
    "height": 72,
    "col": 8,
    "row": 8,
    "total": 60
}

格式二：传入 JSON URL 地址

将缩略图配置保存为 JSON 文件，通过 URL 地址引用：

var info = {
    playerElm: 'mse',
    url: 'http://example.com/vod/movie.mp4',
    useProgressTooltip: true,
    thumbnails: 'http://example.com/thumbnails/movie_thumbnail.json'
};
new ZWPlayer(info);

JSON 文件需遵循 ZWMAP 协议格式（见下方 2.4 节）。

格式三：传入 ZWMAP JSON 对象

直接传入 ZWMAP 协议格式的 JSON 对象：

var thumbnailInfo = {
    "zwp_protocol": "ZWMAP/1.0",
    "zwp_type": "thumbnail",
    "zwp_version": "1.0",
    "thumbnail": {
        "url": "http://example.com/images/movie_thumbnail.jpg",
        "width": 128,
        "height": 72,
        "col": 8,
        "row": 8,
        "total": 60
    }
};

2.3 参数说明

基础对象参数：

ZWMAP 协议附加字段：

2.4 导出文件命名

使用缩略图生成工具导出文件时，命名格式为：

• 缩略图雪碧图：thumbnail.jpg 或 thumbnail.png
• ZWMAP JSON 文件：{视频标题}_thumbnail.json
• ZIP 打包文件：{视频标题}.zip（包含雪碧图和 JSON 文件）

3. 使用方法

方法一：通过构造函数配置

在 zwplayer 初始化时直接设置 thumbnails 参数：

<script language="javascript">
    window.mainplayer = new ZWPlayer({
    url: 'http://example.com/vod/movie.mp4',
    playerElm: '#player-holder',
    useProgressTooltip: true,   //是否启用播放进度条上的提示
    thumbnails: {
        url: 'http://example.com/images/thumbnail.jpg',
        col: 21,
        row: 20,
        width: 128,
        height: 72,
        total: 418
    }
});
</script>

方法二：通过 JSON URL 配置

将缩略图配置托管为 JSON 文件，通过 URL 引用：

<script language="javascript">
    window.mainplayer = new ZWPlayer({
    url: 'http://example.com/vod/movie.mp4',
    playerElm: '#player-holder',
    useProgressTooltip: true,
    thumbnails: 'http://example.com/thumbnails/movie_thumbnail.json'
});
</script>

方法三：通过媒体信息对象配置

用 JavaScript 对象格式 url 参数的属性**thumbnails**来设置，支持直接对象、JSON URL 或 ZWMAP 对象：

<script language="javascript">
    var thumbnailInfo = {
        url: 'http://example.com/images/thumbnail.jpg',
        col: 21,
        row: 20,
        width: 128,
        height: 72,
        total: 418
    };
    var movieInfo = {
    "type": "dvr",
    "http": "http://example.com/vod/mp4/uh01.mp4",
    thumbnails: thumbnailInfo
};
    window.mainplayer = new ZWPlayer({
    url: movieInfo,
    playerElm:'#player-holder',
    useProgressTooltip: true,   //是否启用播放进度条上的提示
});
</script>

方法四：拖拽文件加载

将缩略图 JSON 文件直接拖拽到播放器上即可加载缩略图。支持以下拖拽方式：

• 单独拖拽缩略图 JSON：将 _thumbnail.json 文件拖入播放器，为当前播放的视频加载缩略图
• 同时拖拽视频和缩略图：将视频文件与对应的缩略图 JSON + 缩略图雪碧图一起拖入，播放器自动匹配并加载
• 播放列表拖拽：拖入多个视频及对应的缩略图文件，自动按文件名匹配（如 video.mp4 匹配 video_thumbnail.json）

文件名匹配规则：

注意：当 JSON 中 url 字段为相对路径（如 thumbnail.jpg）时，需同时拖入对应的图片文件，播放器会自动解析并使用本地图片。

4. 重要提示

• 设置 useProgressTooltip 为 true, 才会在进度条上显示缩略图
• 确保缩略图按时间轴均匀分布，以保证预览准确性
• 根据实际需求平衡缩略图数量（精度）与文件大小
• ZWMAP JSON 格式中的 col 字段对应 ZWPlayer 内部的 row（rowsize），播放器会自动处理转换
• 缩略图生成工具可通过 在线缩略图生成工具 访问