智能多媒体服务

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

    视频雪碧截图

    最近更新时间: 2024-04-07 14:18:16

    简介

    雪碧图功能作为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>
       /pattern/<Pattern>
       /spritePattern/<SpritePatter>
    参数名称 必填 说明
    <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 值大于源视频帧数时，会按照源视频最大帧数来输出。
    /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字节。
    /pattern/<Pattern> 指定 单帧截图 的资源名格式。
    支持如下魔法变量：
    $(count)：必填，六个占位符的数字串，不足位的填充前导零即%06d，如 000001。
    $(fname)：非必填，上传的原始文件名。
    注意：
    1. 需要对设定值做 URL安全的Base64编码。
    2. 如果不指定该参数，则不保存雪碧图小图。
    3. 不能和 spritePattern 资源名格式相同。
    /spritePattern/<SpritePatter> 指定 雪碧图 的资源名格式，同时开启雪碧图模式。
    支持如下魔法变量：
    $(count)：必填，六个占位符的数字串，不足位的填充前导零即%06d，如 000001。
    $(fname)：非必填，上传的原始文件名。
    注意：
    1. 需要对设定值做 URL安全的Base64编码。
    2. 如果不指定该参数，则关闭雪碧图模式。
    3. 不能和 pattern 资源名格式相同。

    备注：建议截帧频率是视频帧率的整数倍。

    操作方式

    • API方式：可以通过 持久化处理 的方式来调用：

      • 资源上传时自动触发：可以在上传时指定persistentOps参数
      • 对已有资源手动手动触发：调用pfop命令

    • 控制台方式：您可以使用智能多媒体平台，可视化创建任务，使用详情请参考 任务。

    示例

    示例1，参数如下：

    雪碧图输出格式(spriteFormat) 平均截帧图片数(frames) 小图大小(cellSize) 雪碧图背景色(color) 小图行数(lines) 小图列数(columns) 雪碧图大图命名(spritePattern)
    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/spritePattern/dmZyYW1lLSQoY291bnQp",
"persistentNotifyUrl":  "http://fake.com/qiniu/notify"
}

    示例2，参数如下：

    雪碧图输出格式(spriteFormat) 截取开始时间(ss) 截取结束时间(t) 小图大小(cellSize) 雪碧图背景色(color) 小图行数(lines) 小图列数(columns) 雪碧图大图命名(spritePattern)
    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/spritePattern/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%2Fpng%2FspriteFormat%2Fjpg%2Fss%2F0%2Ft%2F240%2Fs%2F960x540%2Fcolor%2FI0ZGRkZGRg==%2Flines%2F15%2Fcolumns%2F6%2FspritePattern%2FdmZyYW1lLSQoY291bnQp

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

    fops = vsample%2Fpng%2FspriteFormat%2Fjpg%2Fss%2F0%2Ft%2F240%2Fs%2F960x540%2Fcolor%2FI0ZGRkZGRg==%2Flines%2F15%2Fcolumns%2F6%2FspritePattern%2FdmZyYW1lLSQoY291bnQp

    注意:
    其他语言 Sdk 可在官方 Sdks 下载，可以通过查看 Sdk 使用指南中触发持久化，预转持久化使用。

    示例2，结果

    img

    计费说明

    视频雪碧截图，以 截取小图和拼接大图的总张数 来计量计费。比如视频截取了100张小图，最终生成的雪碧图是5张，则最终计量是105次。

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