一. 功能简介

  对于长视频业务，当用户想跳过历史观看数据或者寻找剧情高潮片段亦或快速浏览视频内容，一般都是通过视频拖拉实现，而且经常需要进行多次拖拉才能找到指定位置，用户体验比较差。另外，用户无谓的视频拖拉，也会导致客户加速带宽的浪费。

  对于短视频业务，内容更多是由用户主动上传，视频厂商经常需要从用户上传的视频中选出一张图，作为该视频的宣传封面，以吸引用户点击观看。另外，由于用户上传的视频质量参差不齐，可控性差，可能存在涉黄涉恐涉政等敏感信息，视频厂商也经常需要进行智能鉴定，及时发现违法内容并予以屏蔽，以免触发政策或法律风险。

  为帮助视频厂商提高用户体验，减少带宽浪费，以及规避政策或法律风险，网宿结合自身平台优势，推出了视频截图功能，支持视频封面、微窗预览、视频鉴定等多种应用场景，满足客户不同的业务需求。

二. 功能说明

  网宿支持对常见的视频封装格式和编码格式进行截图，如：

（1）封装格式：MP4、FLV、M3U8、TS、MKV、MOV、WMV、AVI、VP8、VP9、RealVideo、Windows Media Video等。

（2）编码格式：H.265、H.264、H.263、MPEG等。

  支持输出常见的图片格式，如：JPG、PNG、GIF，其中JPG和PNG可支持雪碧图方式输出。

  支持单张截图、间隔截图和平均截图三种模式：

（1）单张截图：指定截取视频的时间点，输出一张静态图片，支持输出GIF动图。

（2）间隔截图：指定截取视频的时间间隔，输出多张静态图片，支持指定多个时间点，如1:3:10:20，中间用“:”隔开。

（3）平均截图：指定截取视频的图片张数，输出一张或多张静态图片。

2.1. 基本原理

---

图1 视频截图基本原理图
 

  客户调用云存储的API接口上传视频文件和截图指令，云存储再将截图指令下发给云转码，云转码接收到截图指令后，会从云存储上下载指定的视频文件，然后按照客户要求进行截图、拼接等操作，最后生成指定格式的图片，并上传到云存储指定目录进行保存。云存储再将截图文件的URL信息回调给客户。

  注：云转码是网宿自主研发的专门用于处理视频文件的系统平台。

2.2. 场景说明

---

2.2.1 视频封面
  对于短视频业务，内容更多是由用户主动上传，视频厂商经常需要从用户上传的视频中选出一张图，用作该视频的宣传封面，以吸引用户点击观看。

  云存储将截图文件的URL信息回调给客户后，客户会将截图文件发布出去，当用户访问客户的视频页面时，会请求截图文件的URL，将截图文件加载到视频页面中，达到宣传视频、吸引用户的效果。

2.2.2 微窗预览
  对于长视频业务，当用户想跳过历史观看数据或者寻找剧情高潮片段亦或快速浏览视频内容，一般都是通过视频拖拉实现，而且经常需要进行多次拖拉才能找到指定位置，用户体验比较差。另外，用户无谓的视频拖拉，也会导致客户加速带宽的浪费。

  云存储将截图文件的URL信息回调给客户后，客户会将截图文件发布出去，用户在请求视频文件时，会同时请求视频文件对应的雪碧图，播放器将雪碧图拆解出来，并与播放器的进度条相对应，以达到鼠标在播放器的进度条上移动时，可以显示对应时间点截图的效果。

2.2.3 视频鉴定
  对于短视频业务，内容更多是由用户主动上传，视频质量参差不齐，可控性差，可能存在涉黄涉恐涉政等敏感信息，视频厂商经常需要进行智能鉴定，及时发现违法内容并予以屏蔽，以免触发政策或法律风险。

  云转码将截图文件发给云存储后，云存储会调用第三方接口进行视频鉴定，并将鉴定结果回调给客户，客户根据鉴定结果决定是否对外发布。

2.3. 接口说明

---

2.3.1 请求说明
  请求参数以如下格式组织，作为请求内容提交：

bucket=<Urlsafe_Base64_Encoded_Bucket>&key=<Urlsafe_Base64_Encoded_Key>&fops=<Urlsafe_Base64_Encoded_Fops>&notifyURL=<Urlsafe_Base64_Encoded_PersistentNotifyUrl>&force=<Force>&separate=<Separate>

2.3.2 参数说明

表1 请求参数说明

参数	必填	描述
bucket	是	空间名，即：原文件所在的空间
key	是	文件名，即：原文件的文件名
fops	是	视频转封装参数列表，支持同时请求多个处理，参数列表之间用; 分隔，即：fops=Urlsafe_Base64_Encode(操作1;操作2;……)
notifyURL	否	处理结果通知接收URL，通知数据详细说明处理后的内容信息，比如视频码率、时长等。请参考通知数据内容说明。
force	否	是否强制执行数据处理。支持设置以下数值： （1）0：指定的数据处理结果如果存在，返回文件已存在，不进行处理，避免重复处理浪费资源； （2）1：强制执行数据处理并覆盖已有文件； 默认为0。
separate	否	处理是否分开通知。支持设置以下数值： （1）0：表示所有转码指令执行完后再一次性通知notifyURL （2）1：表示每个转码指令执行完后都通知notifyURL 默认为0。

    使用以下格式填充参数后，并将其URL安全的Base64编码后的值填充到fops参数中：

<op>/<Format>

    /offset/<second>

    /offsets/<vframeList>

    /interval/<Interval>

    /vframeN/<vframeN>

    /t/<Duration>

    /sprite/<sprite>

    /mode/<mode>

    /w/<width>

    /h/<height>

    /autofill/<autofill>

    /rotate/<degree>

    /isZip/<isZip>

|saveas/<Urlsafe_Base64_Encode(bucket:filekey)>

表2 视频转封装参数表

参数	必填	描述
<op>	是	vframe（操作类型-视频截图）
<format>	是	输出的目标格式，支持jpg、png、gif等。
/offset/<second>	否	指定截取视频的时刻，单位：秒，支持到小数点后3位。
/offsets/<vframeList>	否	指定截取多张视频图片，单位：秒。格式：指定多张不同秒的图，用:间隔。例如，1:3:10:20。注：所有截图会统一放入一个zip文件中。当saveas参数指定为images:a.zip时，zip文件名为a.zip； 截图文件命名规则为序列号的形式，如：a_00001.jpg、a_00002.jpg。
/interval/<Interval>	否	指定连续截图的时间间隔，单位：秒。注：所有截图会统一放入一个zip文件中。当saveas参数指定为images:a.jpg时，zip文件名为a.zip；截图文件命名规则为：a_00001.jpg，依次类推。
/vframeN/<vframeN>	否	截图张数，范围是1,2,3,4等。注：所有截图会统一放入一个zip文件中。当saveas参数指定为images:a.jpg时，zip文件名为a.zip；截图文件命名规则为序列号的形式，如：a_00001.jpg、a_00002.jpg。
/t/<Duration>	否	指定截取视频为GIF图片的时长，单位：秒，默认为5s。
/sprite/<sprite>	否	拼图规格，如4x5，表示将连续截取的图片拼接为4行5列的一张大拼图，即雪碧图。注：该参数需要和interval参数一起使用才有效。当saveas参数指定为images:a.jpg时，拼图文件命名规则为：a_0000x.jpg。如果只生成一个拼图时，命名为a_00001.jpg；如果有多个拼图文件，则命名为a_00001.jpg、a_00002.jpg、a_00003.jpg，依次类推。
/mode/<mode>	否	缩放模式，主要用于等比缩放，避免画面被拉伸变形。详见下表。
/w/<width>	否	缩略图宽度，单位：像素（px），取值范围为1-1920。
/h/<height>	否	缩略图高度，单位：像素（px），取值范围为1-1080。
/autofill/<autofill>	否	配合参数/w/和/h/一起使用，指定为1时，把图片按原始比例缩放到/w/和/h/指定的矩形框内，空隙的部分以黑色填充；指定为0或者不指定时，会强制缩放到对应分辨率，可能造成视频变形。指定autofill参数时，不能与mode参数一起共用，且/w/和/h/都需要指定。
/rotate/<degree>	否	指定顺时针旋转的度数，可取值为90、180、270、auto，默认为不旋转。
/isZip/<isZip>	否	除雪碧图外的多张截图支持打包，且默认会打包；若不打包需要配置为0。
|saveas/<bucket:filekey>	否	视频截图另存为指定文件。参数中需要填入"空间:文件名"URL安全的Base64编码后的值。

表3 视频截图缩放模式参数说明

模式	说明
/mode/1	限定缩略图的宽最少为，高最少为，进行等比缩放，居中裁剪。转后的缩略图通常恰好是x的大小（有一个边缩放的时候会因为超出矩形框而被裁剪掉多余部分）。如果只指定width参数或只指定height参数，代表宽最少为或高最少为的等比缩放。
/mode/2	限定缩略图的宽度最多为，高度最多为，进行等比缩放，不裁剪。如果只指定width参数则表示限定宽度（高度自适应），只指定height参数则表示限定高度（宽度自适应）。
/mode/3	限定缩略图的宽最少为，高最少为，进行等比缩放，不裁剪。

2.3.3 响应说明
    如果请求成功，则返回如下内容的Json串：

{ "persistentId": <persistentId> }  

    如果请求失败，则返回如下内容的Json串：

{
  "code": "<code string>",
  "message":  "<ErrMsg string>"
} 

表4 响应参数说明

字段名	必填	描述
persistentId	是	上传预处理或者触发持久化处理的进程ID
code	是	HTTP请求响应码，参见HTTP响应状态码<返回码>
message	是	处理失败的提示信息

2.3.4 使用范例
    针对test-mp4-encrypt空间名下的test.mp4视频文件,截第5s的帧，并存为jpg格式，存到test-mp4-encrypt空间下，命名为test.jpg。

 curl -v -X POST –d "bucket=Urlsafe_Base64_Encode(test-mp4-encrypt)&key=Urlsafe_Base64_Encode(test.mp4)&fops=Urlsafe_Base64_Encode(vframe/jpg/offset/5|saveas/Urlsafe_Base64_Encode(test-mp4-encrypt:test.jpg))&force=1&separate=1" –H "Authorization:mgrAuthorization_A:mgrAuthorization_B" --url "http://mgrDomain/fops" 

  加密后为：

curl -v -X POST -d "bucket=dGVzdC1tcDQtZW5jcnlwdA==&key=dGVzdC5tcDQ=&fops=dmZyYW1lL2pwZy9vZmZzZXQvNXxzYXZlYXMvZEdWemRDMXRjRFF0Wlc1amNubHdkRHAwWlhOMExtcHdadzBL&force=1&separate=1" -H "Authorization: mgrAuthorization_A:mgrAuthorization_B" --url "http://mgrDomain/fops"

  其中：

  (1) mgrAuthorization_A:mgrAuthorization_B：管理凭证，由AK（访问密钥）、SK（安全密钥）、Path、Body通过管理凭证生成工具生成，其中AK、SK从“控制台-账号管理-用户信息管理-AccessKey管理”处获取，Path为/fops，Body为请求内容。

  (2) mgrDomain：管理域名，从“控制台-对象存储-对应存储空间-概览”处获取。

三. 适用场景

  适用于需要对视频文件进行截图操作，以便支持视频封面、微窗预览和智能鉴定等多种应用场景。

四. 注意事项

  (1)视频截图功能属于增值服务，若要使用需另行付费，按照截取的图片张数进行收费（单位：元/月/千张）;

  (2)视频处理相关功能只能对保存在云存储上的视频文件进行操作，如果要使用必须同时开通云存储服务。