文档中心

雪碧图

最近更新时间：2023.12.04 19:17:04

首次发布时间：2023.12.04 19:17:04

本文为您介绍视频点播配置雪碧图的功能、适用场景、前提条件、使用流程、操作步骤等全链路说明。

功能介绍

雪碧图（缩略图）可以将多张截图拼接为一张图片，用于播放器进度条拖动时效果预览，实现一次性获取多张截图。

减少 HTTP 请求：将多个小图标合并到一张雪碧图中，可以减少网页加载时需要发送的 HTTP 请求数量，从而提高页面加载速度。
提高性能：通过减少 HTTP 请求和优化图片加载，雪碧图可以提升网页性能，减少页面加载时间，提供更好的用户体验。
图片压缩：合并多个小图标到一张雪碧图中，可以使用更高效的压缩算法进行压缩，减小图片文件的大小，从而减少网络传输的数据量。
精灵动画：将动画的每一帧放置在雪碧图的不同位置上，通过控制背景图位置的变化，可以实现帧动画效果。

效果展示：

适用场景

网页开发：在网页中使用雪碧图可以减少页面的 HTTP 请求数量，提高网页加载速度，特别是在移动设备上具有更大的优势。
游戏开发：在游戏中使用雪碧图可以管理游戏中的角色、道具、特效等图标，减少资源加载时间，提高游戏性能。
移动应用开发：在移动应用中使用雪碧图可以减少图片资源的大小，减少应用包的体积，提高应用的加载速度和性能。

前提条件

请您先完成火山引擎账号注册。
如果您首次登录火山引擎控制台，请先完成实名认证。
已开通火山引擎视频点播服务。若未开通，请前往开通视频点播。
在视频点播控制台完成空间创建。
在视频点播的空间下，完成域名配置。

使用流程

在同一个工作流模板中添加转码和截图任务。雪碧图（缩略图）一般是在转码阶段生成，过程说明如下：

按一定的间隔从片源中抽取 N 帧。
然后按顺序排列拼接为多张大图，并记录下图片 URI。
生成完成后，即可通过点播接口获取到这多张大图的地址，根据一定的偏移量即可获取对应时刻的截图。

步骤一：配置截图模板

您可以通过视频点播控制台配置截图模板，截图类型选择雪碧图。具体操作如下：

登录视频点播控制台，进入空间。
单击左侧导航栏媒体处理设置 > 媒体处理模板，进入媒体处理模板页面。
选择截图模板页签，单击添加截图模板按钮，进入创建截图模板页面。

根据页面提示完成参数配置。截图类型选择雪碧图。详细的参数说明请见截图参数参考。

具体的参数配置说明如下：

参数	说明
模板名称	必填项。长度不能超过 64 个字符。建议使用可以标识模板内容的名称。
模板描述	选填项。长度不能超过 140 个字符。模板的详细描述。
截图类型	必选项。选择雪碧图。
图片格式	图片格式为 `jpeg`。
图片尺寸	设置宽和高的像素值。取值范围为 [0,4096]。例如 *240 360** 说明当像素值为 0 时，则使用该边在原图中的像素。
截图数量	设置截图总张数。例如：10 张。
截图间隔	设置两张截图的时间间隔。例如：4 s。具体要求如下：填 0 或者不填时，按视频时长平均截图。截图数量和截图间隔不能同时为 0。仅设置截图数量时，按照截图数量平均间隔截图。仅设置截图间隔时，按照固定截图间隔截图，截图数量不固定。同时设置截图数量、截图间隔时，按照固定截图间隔截图，截图张数最多为设置的截图张数值。
小图排列（行*列）	设置单张雪碧图中截图的排列方式。例如，*2 2*。结合设置的截图数量具体说明如下：截图数量设置为 10 张。小图排列设置为 2 行 2 列排列。则会生成 3 张雪碧图小图，包含截图数量为 4、4、2。其中，最后一张雪碧图 2 个空位会由黑色背景填充。

步骤二：配置工作流模板

您可以通过视频点播控制台配置工作流模板，勾选截图任务，选择雪碧图模板。具体操作如下：

单击左侧导航栏媒体处理设置 > 工作流模板，进入工作流模板页面。
根据页面提示完成参数配置。详细的参数说明请见新建工作流模板。

步骤三：触发媒体处理任务

您可以通过视频点播控制台和 OpenAPI 触发媒体处理任务，生成雪碧图。具体操作如下：

点播控制台

单击左侧导航栏媒资管理 > 视频管理，进入视频管理页面。
根据业务需求，选择 Vid 模式或者 DirectUrl 模式。
切换模式后，选择列表中指定媒资文件处理视频。具体操作请参见 Vid 模式 > 视频处理和 DirectUrl 模式 > 视频处理。

服务端 API：调用触发工作流 API，发起视频处理任务。

步骤四：查看处理结果

发起视频处理后，您可以通过视频点播控制台和 OpenAPI 查看处理结果，具体操作如下：

点播控制台：单击左侧导航栏任务管理 > 工作流任务，进入工作流任务页面，查看任务状态。
服务端 API：调用获取工作流执行结果 API ，查看处理结果。
通过工作流执行完成事件：在回调设置的记录中查看回调状态为成功。在系统设置 > 回调设置，配置工作流执行完成事件。具体操作请见回调设置。

步骤五：获取雪碧图地址

查看处理结果为成功后，您可以通过视频点播控制台和 OpenAPI 获取播放地址，具体操作如下：

点播控制台

单击左侧导航栏媒资管理 > 视频管理，进入视频管理页面。
选择处理的文件，在操作列表下单击详情按钮，进入视频详情页面。
切换截图结果页签，可以复制链接或者预览图片。

雪碧图链接：https://w*j-c*n-c0.byte-test.com/tos-vod-cn-v-03e4***3112705/48f0b9e130374ed6b***4b8be~noop.image

雪碧图样式如下：

服务端 API：调用获取截图结果 API，获取截图地址。
通过工作流执行完成事件：获取雪碧图的 StoreUri。在系统设置 > 回调设置，配置工作流执行完成事件。具体操作请见回调设置。

说明

通过自行拼接方式获取地址，详细说明如下：

规则：http(s)://{domain}/{StoreUri}~tplv-vod-noop.image
说明：http(s)://点播封面加速域名/截图存储地址～模板配置.图片输出格式。其中模板配置详情请参见封面图处理模板。
示例：http://www.example.com/tos-cn-v-abcd/example~tplv-vod-noop.image

{
  "EventType": "WorkflowComplete",
  "EventTime": "2023-11-22T08:55:50Z",
  "RequestId": "2023112216***1E9D292BA151A80B1",
  "Version": "1.0",
  "Data": {
    "Code": "Success",
    "Message": "Success",
    "Vid": "v0dc24g1000***41s1v0o317k3r0g",
    "SpaceName": "vod_test_typea",
    "RunId": "lb:bbd195***089de87a59ecbf8253",
    "CallbackArgs": "",
    "TemplateId": "4fd7aacee1***83f0f0232b6bc4c2",
    "SourceInfo": {
      "FileId": "v0dc24g1000***1v0o317k3r0g",
      "Md5": "c3d63db1b64***aa24796558944ee",
      "FileType": "video",
      "Codec": "h264",
      "Format": "MP4",
      "StoreUri": "tos-vod-cn-v-03e4d54ef3112705/测试视频01.mp4",
      "FileName": "测试视频01.mp4",
      "Duration": 17.68,
      "Width": 1920,
      "Height": 1080,
      "Bitrate": 1243199,
      "Size": 2747470,
      "Definition": "unknown",
      "Fps": 25,
      "Inspection": {
        "Quality": {}
      },
      "SourceAdjustResult": {},
      "RepairResult": {},
      "CreateTime": "2023-11-22T08:55:46Z"
    },
    "TranscodeInfos": [],
    "AdaptBitrateTranscodeInfos": [],
    "PosterUri": "tos-vod-cn-v-03e4d54ef3112705/测试视频01_cover",
    "Snapshots": [
      {
        "Type": "Sprite",
        "Params": {
          "Format": "jpeg",
          "StoreUris": [
            "tos-vod-cn-v-03e4***3112705/48f0b9e130374ed6b***4b8be" // 复制雪碧图的 StoreUri
          ],
          "ImgXLen": 2,
          "ImgYLen": 2,
          "CellWidth": 360,
          "CellHeight": 202,
          "Interval": 4,
          "CaptureNum": 4
        }
      }
    ]
  }
}

步骤六：Web 端展示雪碧图

通过服务端提供雪碧图作为预览图资源，并在前端根据鼠标指针的位置计算并显示对应时间点的预览图，可以实现进度条上方显示视频预览图的功能。能够提高性能、减少请求次数，并提升用户体验。

我们为您提供了在线 Demo 和示例代码。您可进入体验功能效果，获取接入方法。

Vid 模式

集成 Veplayer 时，需要设置 needThumbs 参数取值为 true 。具体说明详见Web 点播 SDK > 基础功能。示例代码如下：

const playerSdk = new VePlayer({
  id: 'mse',
  width: 800,
  height: 500,
  getVideoByToken: {
    playAuthToken: '临时playAuthToken', // 需要从服务端临时获取
    ....
    needThumbs: true
});

参数类型 默认值 描述

参数	类型	默认值	描述
needThumbs	Boolean	否	是否启用控制台设置的雪碧图。取值如下： `false`：否。 `true`：是。说明前提是已转码并生成雪碧图。可在点播控制台，媒资管理的视频详情的截图结果中查看是否有雪碧图转码产物。

needThumbs

Boolean

否

是否启用控制台设置的雪碧图。取值如下：

false：否。
true：是。

说明

前提是已转码并生成雪碧图。可在点播控制台，媒资管理的视频详情的截图结果中查看是否有雪碧图转码产物。

DirectUrl 模式

集成 VePlayer 时，您需要设置 thumbnail 参数，通过 urls 参数传入雪碧图地址。示例代码如下：

var playerSdk = new VePlayer({
        id: 'mse',
        url: "https://vod-typea.byte-test.com/%E6%B5%8B%***%E8%A7%86%E9%A2%9101.mp4?auth_key=1700723919-0fa7dcfbfce141f89f6***4920703c14d485f569ebf4670d69e", // 视频地址
        width: 640,
        height: 360,
        thumbnail: {
            pic_num: 38,
            width: 240,
            height: 136,
            col: 10,
            row: 10,
            urls: ["http://p6-vedit-sign.byteimg.com/tos-cn-v-d67d0e/7ea3f6dbc4a049599945e9f96d106c7b_1659088327~tplv-noop.image?x-expires=1690624695&x-signature=q7VjLGZMLehRrN1j9uIgfvIfwMY%3D"]。//雪碧图地址
        }
    });

配置项	说明
pic_num	缩略图总数。该视频资源所需预览小图数量（雪碧图截出的小图总数）
width	每个缩略图的宽度。
height	每个缩略图的高度。
col	每张雪碧图的缩略图行数。
row	每张雪碧图的缩略图列数。
urls	雪碧图地址列表。

说明

生成的缩略图越多，进度条预览越精确，而缩略图越多，图片越大加载越慢，需要根据自身业务需求设置缩略图。

其他相关文档

雪碧图的费用，截取的张数是按照小图计算，具体详见按量计费。

截图费用： 0.1 元/千张（正常任务）、0.03 元/千张（闲时任务）
公式：截图费用 = 截图张数 × 单价

例如：假设用户 A 于 09 月 15 日使用视频点播截图功能，截取 20,000 张小图，则产生的截图费用如下：
截图费用 = 0.1 (元/千张) x 20,000 /1,000 = 2 (元)