human: 如何处理七牛云的智能多媒体服务视频雪碧截图

gpt: [智能多媒体服务](https://developer.qiniu.com/dora) > API 文档 > 音视频处理 >视频雪碧截图

#  视频雪碧截图

最近更新时间: 2024-06-28 17:22:18

# **简介**

雪碧图功能作为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编码
__](https://developer.qiniu.com/kodo/manual/appendix#urlsafe-base64)。  
2\. 如果不指定该参数，则不保存雪碧图小图。  
3\. 不能和 `spritePattern` 资源名格式相同。  
`/spritePattern/<SpritePatter>` |  | 指定 **雪碧图** 的资源名格式，同时开启雪碧图模式。  
支持如下魔法变量：  
`$(count)`：必填，六个占位符的数字串，不足位的填充前导零即%06d，如 000001。  
`$(fname)`：非必填，上传的原始文件名。  
**注意：**  
1\. 需要对设定值做 [URL安全的Base64编码
__](https://developer.qiniu.com/kodo/manual/appendix#urlsafe-base64)。  
2\. 如果不指定该参数，则关闭雪碧图模式。  
3\. 不能和 `pattern` 资源名格式相同。  
  
**备注** ：建议截帧频率是视频帧率的整数倍。

# **操作方式**

  * **API方式** ：可以通过 [持久化处理 __](https://developer.qiniu.com/dora/1291/persistent-data-processing-pfop)的方式来调用：

    * `资源上传时自动触发`：可以在上传时指定[persistentOps](https://developer.qiniu.com/kodo/manual/put-policy#put-policy-persistent-ops-explanation)参数
    * `对已有资源手动手动触发`：调用[pfop __](https://developer.qiniu.com/dora/1291/persistent-data-processing-pfop)命令
  * **控制台方式** ：您可以使用[智能多媒体平台 __](https://portal.qiniu.com/dora/media-gate)，可视化创建任务，使用详情请参考[任务 __](https://developer.qiniu.com/dora/6488/task-01)。

# **示例**

**示例1，参数如下：**

雪碧图输出格式(spriteFormat) | 平均截帧图片数(frames) | 小图大小(cellSize) | 雪碧图背景色(color) | 小图行数(lines) | 小图列数(columns) | 雪碧图大图命名(spritePattern)  
---|---|---|---|---|---|---  
jpg | 10 | 960x540 | I0ZGRkZGRg== | 15 | 6 | dmZyYW1lLSQoY291bnQp  
  
[资源上传时自动触发](https://developer.qiniu.com/dora/12439/video-sprite-
screenshots)：上传的`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  
  
[资源上传时自动触发](https://developer.qiniu.com/dora/12439/video-sprite-
screenshots)：上传的`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"
    }
    

[对已有资源手动触发](https://developer.qiniu.com/dora/12439/video-sprite-screenshots)：

    
    
    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 为例，具体可以看下[音视频转码的示例](https://developer.qiniu.com/dora/api/audio-
and-video-transcoding-avthumb)。需要在音视频转码的示例的基础修改数据处理命令 `fops` ，将其修改为：

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

**注意** :  
其他语言 Sdk 可在[官方 Sdks ](https://developer.qiniu.com/sdk)下载，可以通过查看 Sdk
使用指南中`触发持久化`，`预转持久化`使用。

**示例2，结果**

![img](https://dora-doc.qiniu.com/xuebitu.jpg)

# **计费说明**

视频雪碧截图，以 截取小图和拼接大图的总张数
来计量计费。比如视频截取了100张小图，最终生成的雪碧图是5张，则最终计量是105次。服务价格=视频截图价格，定价参考[智能多媒体服务定价
__](https://www.qiniu.com/prices/dora)。

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