一. 功能简介

  添加字幕功能，支持在视频指定时间和指定位置（注：视频画面的绝对位置）添加指定字幕内容，减少客户编辑操作。

二. 功能说明

  添加字幕的源文件支持常见的视频/音频封装格式和编码格式，如：

  (1) 视频格式： MP4、FLV、M3U8、TS、MKV、MOV、WMV、AVI、VP8、VP9、RealVideo、Windows Media Video等；

  (2) 音频格式：AAC、AC-3、MP1、MP2、MP3、PCM、RealAudio、Windows Media Audio（WMA）、OGG等；

  (3) 编码格式：H.265、H.264、H.263、MPEG等。

  客户上传视频文件的时候，可以同时配置添加字幕操作参数，也可以同时配合使用视频转封装、音视频操作等功能，即可通过同一条API命令实现多个功能。

2.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>

表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>

    /subtitle/<Urlsafe_Base64_Encode(bucket:filekey)>

    |saveas/<Urlsafe_Base64_Encode(bucket:filekey)>

表2 添加字幕参数表

参数	必填	描述
<op>	是	avthumb（操作类型-音视频处理）
<format>	是	输出的目标格式，如mp4、flv、m3u8等。
/subtitle/<Urlsafe_Base64_Encode(<bucket1>:<key1>), Urlsafe_Base64_Encode(<bucket2>:<key2>),......>	是	字幕文件，支持：srt格式字幕（uft-8编码）、带有字幕的mkv文件（需要提取mkv视频文件中的字幕再嵌入目标视频）、embed（将原视频的字幕流嵌入目标视频），其中： <bucket>：表示字幕文件所属空间，<key>：表示指定的字幕文件名。 需要经过URL安全的Base64编码。 支持多个字幕配置，且通过“,”进行分割，具体格式为：subtitle=<base64_encode>,<base64_encode>,...，具体示例如：subtitle=aHR0cDovL2VuY29kZS5jaGFodW8uY29tLw,aHR0cDovL2VuY29kZS5jaGFodW8uY29tLw
/subtitleType/<subtitleType>	否	用于显式指定字幕添加操作的类型，subtitleType=1 代表添加软字幕；subtitleType=2 代表添加硬字幕；默认subtitleType=0，即原程序自动识别的方式。
/subtitleAttr/<Urlsafe_Base64_Encode(<lang=xx1,name=yy1>), Urlsafe_Base64_Encode(<lang=xx2,name=yy2>),......>	否	用于指定字幕的属性信息，当前仅用于输出为多码率m3u8且添加vtt软字幕时使用。支持多个字幕属性的配置，且通过英文逗号“,”进行分割，具体格式为： subtitleAttr=base64_encode(lang=xx1,name=yy1),base64_encode(lang=xx2,name=yy2）…… 其中，lang指定字幕的语言属性，name指定字幕的名字属性。 注：subtitleAttr值个数需要和字幕文件个数匹配，否则报错
|saveas/<bucket:filekey>	否	保存为指定文件，参数中需要填入"空间: 文件名"URL安全的Base64编码后的值。

2.2. 响应说明

---

  如果请求成功，则返回如下内容的Json串：

{ "persistentId": <persistentId> }  

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

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

表3 响应参数说明

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

2.3. 使用范例

---

  实现将vod-wcs-test001空间名下的test.flv视频文件添加字幕（字幕位于vod-wcs-test001空间下名称为zimu.srt），并转为mp4格式，存到vod-wcs-test001空间下，命名为test_file.mp4。

 curl -v -X POST –d "bucket=Urlsafe_Base64_Encode(vod-wcs-test001)&key=Urlsafe_Base64_Encode(test.flv)&fops=Urlsafe_Base64_Encode(avthumb/mp4/subtitle/Urlsafe_Base64_Encode(vod-wcs-test001:zimu.srt)|saveas/Urlsafe_Base64_Encode(vod-wcs-test001:test_file.mp4))&force=1&separate=1" –H "Authorization:mgrAuthorization_A:mgrAuthorization_B" --url "http://mgrDomain/fops"

  加密后为：

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

  其中：

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

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

三. 应用场景

  实现对视频添加字幕，减少客户编辑成本。

四. 注意事项

  (1) 添加字幕功能只能对存储于云存储（WCS）上的视频文件进行操作，因此必须同时开通点播和云存储功能。

  (2) 添加字幕功能属于增值服务，若要使用需另行付费。