在实时音视频场景下,声网 SDK 支持按照你设置的频率对频道内的视频流截图,并将图片上传至你指定的第三方云存储。
本文介绍如何实现视频截图上传功能。
调用 API 开启视频截图上传功能后,SDK 会根据你设置频率对本地用户发送的视频进行截图和上传。截图完成后,声网云端服务器会以 HTTPS 请求的形式,向你的服务器发送回调通知,并将所有截图发送至你指定的第三方云存储。
实现声网视频截图上传功能前,请确保满足以下条件:
调用 enableContentInspect
方法开启视频截图上传功能,并将 ContentInspectConfig
中的 type
设置为 SUPERVISE
。成功开启视频截图上传功能后,SDK 会按照设定的频率进行截图,并上传截图至声网云端服务器。示例代码如下:
ContentInspectConfig config = new ContentInspectConfig();
config.extraInfo = "YourExtraInfo";
config.moduleCount = 1;
// 功能模块的类型为视频截图上传。
config.modules[0].type = ContentInspectConfig.CONTENT_INSPECT_SUPERVISE;
// 视频截图上传的频率为 2 秒一次。
config.modules[0].interval = 2;
mRtcEngine.enableContentInspect(true, config);
let inspectExtraConfig = AgoraContentInspectConfig()
inspectExtraConfig.extraInfo = "YourExtraInfo"
var modules = [AgoraContentInspectModule]()
let module1 = AgoraContentInspectModule()
// 功能模块的类型为视频截图上传。
module1.type = .supervise
// 视频截图上传的频率为 2 秒一次。
module1.interval = 2
modules.append(module1)
inspectExtraConfig.modules = modules
agoraKit.enableContentInspect(true, config:inspectExtraConfig)
void CMainFrame::OnBtnEnableContentInspect() {
if (CAgoraObject::GetEngine() == NULL) {
return;
}
ContentInspectConfig config;
ContentInspectModule module1;
// 功能模块的类型为视频截图上传。
module1.type = kContentInspectSupervise;
// 视频截图上传的频率为 2 秒一次。
module1.interval = 2;
config.moduleCount = 1;
config.modules[0] = module1;
CAgoraObject::GetEngine()->enableContentInspect(true, config);
}
截图成功并上传至声网云端服务器后,声网服务会以 HTTPS POST 请求的形式向你的应用服务器发送消息通知回调。数据格式为 JSON,字符编码为 UTF-8。
收到消息通知后,你的应用服务器需要进行响应,响应的包体格式为 JSON。在以下任意一种情况下,声网服务都会认为通知失败:
200
,或响应包体格式不是 JSON。声网服务会在第一次通知失败后立即重试,再次发送消息通知,一共会尝试三次通知。
字段名 | 值 |
---|---|
Content-Type |
application/json;charset=utf-8 |
请求包体为 JSON Object 类型,包含以下字段:
字段 | 类型 | 描述 |
---|---|---|
requestId |
String | 回调通知 ID,标识来自声网业务服务器的一次事件通知。 |
callbackParam |
JSON Object | 在回调中自定义传入的字段,目前仅包括 cname 字段,即频道名。 |
callbackData |
String | SDK 视频截图上传模块透传的字符串数据。 |
checksum |
String | 由 callbackAddr 、code 、object 和 requestId 四个参数值计算出的 MD5 值,用于校验此次回调通知是否来自于视频截图上传服务。 |
object |
String | 截图文件的名称。该文件的命名规则为:<OSS前缀>/<年月日>/<sid>_<cname>__uid_s_<uid>__uid_e_<type>_utc.jpg 。文件名中各字段含义如下:<sid> :截图 ID。该 ID 是一次截图的唯一标识。<cname> :被截图用户所属的频道名。<uid> :用户 ID。加入频道时设置的 user ID。<type> : 文件类型,只支持 video 。<utc> :此次截图的 Unix 时间戳。UTC 时间,由年、月、日、小时、分钟、秒和毫秒组成。例如,utc 等于 20190611073246073 ,表示该切片文件的开始时间为 UTC 2019 年 6 月 11 日 7 点 32 分 46 秒 73 毫秒。 |
code |
Number | 此次截图的状态码。200 表示截图完成。 |
msg |
String | 此次截图的状态。"Supervise complete" 表示此次截图完成。 |
channelName |
String | 此次被截图用户所属的频道名。与 object.cname 一致。 |
userId |
String | 此次被截图用户的 user ID。与 object.uid 一致。 |
timestamp |
Int | 此次截图 Unix 时间戳(毫秒)。UTC 时间,与 object.utc 一致。 |
{
"requestId": "38f8e3cfdcXXXXXXXXX1ceba380d7e1a_1652693284_b5813fe2ae4fa5cdfe5abd8fef82526f",
"callbackParam": {
"cname": "httpClient463224"
},
"callbackData": "",
"checksum": "75ee988XXXXXXc2ad4ec2aef58f178fd8",
"object": "test/20201216/38f8e3cfdc474cd56fc1ceba380d7e1a_httpClient463224__uid_s_91__uid_e_video_20200413081128672.jpg",
"code": 200,
"msg": "Supervise complete",
"channelName": "httpClient463224",
"userId": "91",
"timestamp": 20190611073246070
}
各平台视频截图上传动态库名称及集成后 app 增加的体积详见如何减少集成 v4.x SDK 后的 app 体积?。
应用服务器响应的 HTTP 状态码参考如下:
状态码 | 描述 |
---|---|
200 |
请求成功。 |
201 |
成功请求并创建了新的资源。 |
206 |
整个截图过程中没有用户发流,或部分截图文件没有上传到第三方云存储。 |
400 |
请求的语法错误(如参数错误),服务器无法理解。 |
401 |
未经授权的(App ID/Customer Certificate 匹配错误)。 |
404 |
服务器无法根据请求找到资源(网页)。 |
500 |
服务器内部错误,无法完成请求。 |
504 |
服务器内部错误。充当网关或代理的服务器未从远端服务器获取请求。 |