视频截图上传

在实时音视频场景下，声网 SDK 支持按照你设置的频率对频道内的视频流截图，并将图片上传至你指定的第三方云存储。

本文介绍如何实现视频截图上传功能。

信息

视频截图上传为收费服务，计费详情请咨询 sales@shengwang.cn。

技术原理

调用 API 开启视频截图上传功能后，SDK 会根据你设置频率对本地用户发送的视频进行截图和上传。截图完成后，声网云端服务器会以 HTTPS 请求的形式，向你的服务器发送回调通知，并将所有截图发送至你指定的第三方云存储。

前提条件

实现声网视频截图上传功能前，请确保满足以下条件：

• 已联系技术支持开启和配置声网视频截图上传服务。
• 已在你的项目中集成 RTC 4.x SDK（包含视频截图上传动态库），加入频道并发布视频流。详见实现音视频互动。

实现视频截图上传

调用 enableContentInspect 方法开启视频截图上传功能。成功开启视频截图上传功能后，SDK 会按照设定的频率进行截图，并上传截图至声网云端服务器。示例代码如下：

Android

Java

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);

iOS/macOS

Swift

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)

Windows

C++

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);
}

HTTP 消息通知

截图成功并上传至声网云端服务器后，声网服务会以 HTTPS POST 请求的形式向你的应用服务器发送消息通知回调。数据格式为 JSON，字符编码为 UTF-8。

收到消息通知后，你的应用服务器需要进行响应，响应的包体格式为 JSON。在以下任意一种情况下，声网服务都会认为通知失败：

• 发送消息通知后，5 秒内没有收到你的服务器的响应。
• 响应的 HTTP 状态码不是 200，或响应包体格式不是 JSON。

声网服务会在第一次通知失败后立即重试，再次发送消息通知，一共会尝试三次通知。

HTTP 请求

请求头

字段名	值
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 一致。

请求示例

JSON

{
    "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
}

相关信息

API 参考

enableContentInspect

视频截图上传动态库

各平台视频截图上传动态库名称及集成后 App 增加的体积详见减小 App 体积。

HTTP 状态码

应用服务器响应的 HTTP 状态码参考如下：

状态码	描述
200	请求成功。
201	成功请求并创建了新的资源。
206	整个截图过程中没有用户发流，或部分截图文件没有上传到第三方云存储。
400	请求的语法错误（如参数错误），服务器无法理解。
401	未经授权的（App ID/Customer Certificate 匹配错误）。
404	服务器无法根据请求找到资源（网页）。
500	服务器内部错误，无法完成请求。
504	服务器内部错误。充当网关或代理的服务器未从远端服务器获取请求。