智能多媒体服务

    • 智能多媒体服务 > API 文档 > 音视频处理 >视频雪碧截图

    视频雪碧截图

    最近更新时间: 2025-03-12 14:06:04

    简介

    雪碧图功能作为vsample功能的扩展， 所谓 雪碧图 是指先用 vsample 接口截取一系列图片，并按照一定的排列规则拼成一张大图，而这张大图即为雪碧图。生成雪碧图的同时可以选择保存多张单帧截图。

    截取雪碧图的优势在于可降低图片的请求数量，从而可以通过请求雪碧图一次获取多张截图的信息，加强了客户端的性能。

    参数说明

    vsample/<Format>
       /spriteFormat/<SpriteFormat>
       /ss/<StartTime>
       /t/<Duration>
       /rotate/<Degree>
       /interval/<Interval>
       /frames/<Frames>
       /cellSize/<CellSize>
       /padding/<Padding>
       /margin/<Margin>
       /color/<Color>
       /lines/<Lines>
       /columns/<Columns>
       /savePattern/<savePattern>
       /saveSpritePattern/<saveSpritePattern>
    参数名称 必填 说明
    <Format> 是 指定单帧截图的图片格式，支持jpg、png等。
    /spriteFormat/<SpriteFormat> 指定雪碧图的图片格式，支持jpg、png等。
    不设置则和Format一致。
    /ss/<StartTime> 指定截取视频的开始时刻，单位：秒,精度为 100ms，例如 /ss/1.1；
    默认从片头开始。
    /t/<Duration> 采样总时长，单位：秒,精度为 100ms，例如 t/1.1；
    默认表示到片尾结束。
    /rotate/<Degree> 指定顺时针旋转的度数，可取值为90、180、270、auto。
    默认为不旋转。
    /interval/<Interval> 指定截帧间隔时间，单元：秒。
    默认为5秒,精度为 100ms，例如/interval/0.1指定平均截帧，截取的图片数量。 例如/frames/1。
    注意：
    1. 和 frames 参数不能同时设置。
    2. frames 和 interval 都不指定的情况，默认使用 interval。
    /frames/<Frames> 指定平均截帧，截取的图片数量。 例如/frames/10，截取10张图片。
    注意：
    1. 和 interval 参数不能同时设置。
    2. frames 和 interval 都不指定的情况，默认使用 interval。
    3. 当设置frames 值大于源视频帧数时，会按照源视频最大帧数来输出。
    4. 建议截帧频率是视频帧率的整数倍。
    /cellSize/<CellSize> 雪碧图中小图的分辨率，格式：WidthxHeight；长边取值范围 [20,3840]，短边取值范围 [20,2160]。
    1、Widthx，指定宽，高随宽等比缩放；
    2、xHeight，指定高，宽随高等比缩放。
    3、宽高为空时，则和源视频保持一致。
    4、宽高都不为空时，按指定宽高强制缩放。
    注意：不能超出源分辨率，超出会处理失败。
    /padding/<Padding> 雪碧图中小图内边距大小，取值范围[0,100]，单位：px；
    默认值为0。
    /margin/<Margin> 雪碧图中小图外边距大小，取值范围[0,100]，单位：px；
    默认值为0。
    /color/<Color> 雪碧图背景颜色，需要经过urlsafe_base64_encode。RGB格式，可以是颜色名称（例如红色）或十六进制（例如#FF0000），参考RGB颜色编码表；
    默认为黑色。
    /lines/<Lines> 雪碧图大图中小图行数，取值范围[1,100]；
    默认值为10。
    /columns/<Columns> 雪碧图大图中小图列数，取值范围[1,100]；
    默认值为10。
    注意：输出单张雪碧图大小不能超过 2147483647字节。
    /savePattern/<savePattern> 指定 单帧截图 的资源名格式，需要对设定值做URL安全的Base64编码。
    命名支持使用变量：
    1. 可以使用 $(变量名)或${变量名} 形式求值，魔法变量使用说明，参考 文件名变量 。
    2. 注意：$(count)为必填项，必须存在的六位占位符数字串。

    注意：
    1. 需要对设定值做 URL安全的Base64编码。
    2. 如果不指定该参数，则不保存雪碧图小图。
    3. 不能和 saveSpritePattern 资源名格式相同。
    /saveSpritePattern/<saveSpritePattern> 是 指定 雪碧图 的资源名格式，需要对设定值做URL安全的Base64编码。
    命名支持使用变量：
    1. 可以使用 $(变量名)或${变量名} 形式求值，魔法变量使用说明，参考 文件名变量 。
    2. 注意：$(count)为必填项，必须存在的六位占位符数字串。

    注意：
    1. 需要对设定值做 URL安全的Base64编码。
    2. 如果不指定该参数，则关闭雪碧图模式。
    3. 不能和 savePattern 资源名格式相同。

    操作方式

    您可以通过以下几种方式来创建任务：

    方式一：使用任务触发器

    • 对符合规则策略的上传文件自动触发：在具体空间下，选择任务与工作流，进入任务触发器页面，点击新建 任务触发器；创建完成后，需要开启 上传触发开关，然后通过左侧文件管理或 API/SDK 上传文件到触发器指定的输入路径；将对符合规则策略的上传文件自动触发多媒体处理，并将结果文件保存到目标路径。

      img

    方式二：使用对象存储控制台

    • 上传文件手动触发：在具体空间下， 上传文件 时，指定工作流模板 。

      img

    • 指定文件手动触发：有两种指定单个文件创建任务的入口

      • 第一个入口：在具体空间下，在文件列表中指定文件，在操作栏【更多】中点击【创建多媒体任务】。

        img

        注意：仅对音视频/gif动图/webp动图文件提供该操作。

      • 第二个入口：在具体空间下，选择任务与工作流，进入任务管理页面，点击【新建任务】。

        img

    方式三：使用API

    • 资源上传时手动触发：可以在构造上传凭证时在上传策略中，设置相关字段，在资源文件上传时触发处理。
    • 对已有资源手动触发：可以在调用 持久化数据处理(pfop) 时，设置相关字段，对已存在空间中的资源文件发起处理。

    方式四：使用SDK

    • 查看各语言 SDK 使用指南中 持久化数据处理 章节，可在七牛官方SDK 进行下载。

    操作示例

    示例1，参数如下：

    雪碧图输出格式(spriteFormat) 平均截帧图片数(frames) 小图大小(cellSize) 雪碧图背景色(color) 小图行数(lines) 小图列数(columns) 雪碧图大图命名(saveSpritePattern)
    jpg 10 960x540 I0ZGRkZGRg== 15 6 dmZyYW1lLSQoY291bnQp

    资源上传时自动触发：上传的token中指定persistentOps

    {
"scope":                "qiniu-ts-demo:thinking-in-go.mp4",
"deadline":             1390528576,
"persistentOps":          "vsample/png/spriteFormat/jpg/frames/10/s/960x540/color/I0ZGRkZGRg==/lines/15/columns/6/saveSpritePattern/dmZyYW1lLSQoY291bnQp",
"persistentNotifyUrl":  "http://fake.com/qiniu/notify"
}

    示例2，参数如下：

    雪碧图输出格式(spriteFormat) 截取开始时间(ss) 截取结束时间(t) 小图大小(cellSize) 雪碧图背景色(color) 小图行数(lines) 小图列数(columns) 雪碧图大图命名(saveSpritePattern)
    jpg 0 240 960x540 I0ZGRkZGRg== 15 6 dmZyYW1lLSQoY291bnQp

    资源上传时自动触发：上传的token中指定persistentOps

    {
"scope":                "qiniu-ts-demo:thinking-in-go.mp4",
"deadline":             1390528576,
"persistentOps":          "vsample/png/spriteFormat/jpg/ss/0/t/240/s/960x540/color/I0ZGRkZGRg==/lines/15/columns/6/saveSpritePattern/dmZyYW1lLSQoY291bnQp",
"persistentNotifyUrl":  "http://fake.com/qiniu/notify"
}

    对已有资源手动触发：

    POST /pfop/ HTTP/1.1
Host: api.qiniu.com  
Content-Type: application/x-www-form-urlencoded  
Authorization: Qiniu <AccessToken>  

bucket=qiniu-ts-demo&key=thinking-in-go.mp4&fops=vsample/png/spriteFormat/jpg/ss/0/t/240/s/960x540/color/I0ZGRkZGRg==/lines/15/columns/6/saveSpritePattern/dmZyYW1lLSQoY291bnQp

    以 Python Sdk 为例，具体可以看下音视频转码的示例。需要在音视频转码的示例的基础修改数据处理命令 fops ，将其修改为：

    fops = vsample/png/spriteFormat/jpg/ss/0/t/240/s/960x540/color/I0ZGRkZGRg==/lines/15/columns/6/saveSpritePattern/dmZyYW1lLSQoY291bnQp

    示例2，结果

    img

    计费说明

    视频雪碧截图，以 截取小图和拼接大图的总张数 来计量计费。比如视频截取了100张小图，最终生成的雪碧图是5张，则最终计量是105次。服务价格=视频截图价格，定价参考智能多媒体服务定价 。

    以上内容是否对您有帮助？
    • Close