实践教程
有奖：腾讯混元大模型征文大赛邀您参加！> HOT
文档中心>实践教程>实时音视频>实现视频截图上传

实现视频截图上传

最近更新时间：2024-10-17 15:19:52

我的收藏

本页目录：

功能说明

实时音视频 TRTC 支持通过 SDK API 发起截图上传功能，用户可将截图用于第三方审核、封面图设置等场景，满足用户的使用需求。




前提条件

登录 TRTC 控制台，开通 TRTC 服务并 创建应用。
前往 控制台 > 功能配置 > 增值功能 开启视频截图上传功能，配置指定存储的对象存储 COS 桶。



说明：
视频截图上传功能需通过购买包月套餐-旗舰版或者领取包月套餐-体验版解锁。包月套餐相关说明请参见文档 包月套餐计费说明。
视频截图上传功能会根据产生的截图用量产生费用，更多请见费用详情。
使用视频截图上传功能，请提交工单联系我们获取最新版本 SDK（目前Android、iOS/Mac、Windows支持）.

功能说明

1. 参见 前提条件，开启功能开关并设置存储位置。
2. 通过 SDK 实验性接⼝ callExperimentalAPI 来使⽤此功能 ，传参要求为 JSON 字符串，参数说明如下：
{
    "api": "enableAutoSnapshotAndUpload",
    "params" : {
    "enable": 1, //启动/停止自动截图，int，必填。字段取值：0 停止、1 启动，传值不能为空，支持传入 bool 值（true 和 false）。
    "intervalS": 1,// 截图间隔，int，可选。间隔单位为秒，缺省值 3 秒，最小间隔 1秒。字段传值不能为空，小于 1 则取最小值 1 秒。
    "streamType": 0, // 流类型，int，可选。字段取值：0 主路、2辅路，传值不能为空。缺省行为：启动截图时若不传入此字段则启动不生效，停止截图时若不传入此字段任务全部停止。
    "extraInfo": "customized messages" // 截图上传附加信息，string，可选。此信息会通过服务端回调通知给您的业务后台。
    } 

}
注意：
截图上传任务在 enterRoom 成功后才会启动。
建议在 startLocalPreview 成功后调用此方法，避免截图上传任务失败。

接收服务端事件回调

配置信息

实时音视频 TRTC 控制台支持自助配置回调信息，配置完成后即可接收事件回调通知。详细操作指引请参见 回调配置。
注意：
您需要提前准备以下信息：
必要项：接收回调通知的 HTTP/HTTPS 服务器地址。
可选项：计算签名的 密钥 key，由您自定义一个最大32个字符的 key，以大小写字母及数字组成。

超时重试

事件回调服务器在发送消息通知后，5秒内没有收到您的服务器的响应，即认为通知失败。首次通知失败后会立即重试，后续失败会以10秒的间隔继续重试，直到消息存续时间超过1分钟，不再重试。

事件回调消息格式

事件回调消息以 HTTP/HTTPS POST 请求发送给您的服务器，其中：
字符编码格式：UTF-8。
请求：body 格式为 JSON。
应答：HTTP STATUS CODE = 200，服务端忽略应答包具体内容，为了协议友好，建议客户应答内容携带 JSON： {"code":0}。
包体示例：下述为“转推时间组-CDN 推流正在进行”事件的包体示例。

回调消息参数

事件回调消息的 header 中包含以下字段：
字段名
值
Content-Type
application/json
Sign
签名值
SdkAppId
sdk application id
事件回调消息的 body 中包含以下字段：
字段名
类型
含义
EventGroupId
Number
事件组 ID，截图事件（EVENT_GROUP_SCREEN_ SHOT）值为 6
EventType
Number
回调通知的事件类型，视频截图（EVENT_TYPE_VIDEO_SCREENSHOT）值为 601
CallbackTs
Number
事件回调服务器向您的服务器发出回调请求的 Unix 时间戳，单位为毫秒
EventInfo
JSON
Object
事件信息
事件信息说明：
字段名
类型
含义
eventId
String
当次回调的事件 ID
callbackData
String
截图上传附加信息，通过客户端的 extraInfo 上报
pictureURL
String
截图的 URL
code
Number
任务执⾏状态码，默认为 0 表示任务执⾏成功
msg
String
任务执⾏描述信息
roomID
String/Number
房间号
streamType
String
截图的流类型，主路（BigStream）或辅路
（SubStream）
userID
String
截图⽤户名
timestamp
Number
截图 UTC 时间戳，精确到毫秒

回调请求示例：

{
   "EventGroupId": 6,
   "EventType": 601,
    "CallbackTs": 1698410059705,
   "EventInfo": {
       "eventID": "ap-guangzhou-1400000000-1698410059243691647-60022-jpg.jpg",
       "callbackData": "test",
       "pictureURL": "https://sotest-1200000000.cos.ap-
guangzhou.myqcloud.com/1400000000/ap-guangzhou-1400000000-1698410059243691647-
60022-jpg.jpg",
       "code": 0,
       "msg": "",
       "roomID": "464884",
       "streamType": "BigStream",
       "userID": "dd",
       "timestamp": 1698410059693
    } 
}

计算签名：

签名由 HMAC SHA256 加密算法计算得出，您的事件回调接收服务器收到回调消息后，通过同样的⽅式计算出签名，相同则说明是腾讯云的实时⾳视频的事件回调，没有被伪造。签名的计算如下所示：
// 签名 Sign 计算公式中 key 为计算签名 Sign 用的加密秘钥。
Sign = base64 （hmacsha256(key, body)）
注意：
body 为您收到回调请求的原始包体，不要做任何转化，需要完整保留\\n\\t转义字符，示例如下：
body="{\\n\\t\\"EventGroupId\\":\\t1,\\n\\t\\"EventType\\":\\t103,\\n\\t\\"CallbackTs\\":\\t1615554923704,\\n\\t\\"EventInfo\\":\\t{\\n\\t\\t\\"RoomId\\":\\t12345,\\n\\t\\t\\"EventTs\\":\\t1608441737,\\n\\t\\t\\"UserId\\":\\t\\"test\\",\\n\\t\\t\\"UniqueId\\":\\t1615554922656,\\n\\t\\t\\"Role\\":\\t20,\\n\\t\\t\\"Reason\\":\\t1\\n\\t}\\n}"

签名校验示例（Java）

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;
//# 功能：第三方回调sign校验
//# 参数：
//# key：控制台配置的密钥key
//# body：腾讯云回调返回的body体
//# sign：腾讯云回调返回的签名值sign
//# 返回值：
//# Status OK 表示校验通过，FAIL 表示校验失败，具体原因参考Info
//# Info：成功/失败信息

		
									
public class checkSign {
    public static String getResultSign(String key, String body) throws
						
Exception {
        Mac hmacSha256 = Mac.getInstance("HmacSHA256");        
        SecretKeySpec secret_key = new SecretKeySpec(key.getBytes(),
"HmacSHA256");
        hmacSha256.init(secret_key);
		return					
Base64.getEncoder().encodeToString(hmacSha256.doFinal(body.getBytes()));
    }					
    public static void main(String[] args) throws Exception {
        String key = "123654";  
        String body = "{\\n" + "\\t\\"EventGroupId\\":\\t2,\\n" +	
"\\t\\"EventType\\":\\t204,\\n" + "\\t\\"CallbackTs\\":\\t1664209748188,\\n" +
"\\t\\"EventInfo\\":\\t{\\n" + "\\t\\t\\"RoomId\\":\\t8489,\\n" +
"\\t\\t\\"EventTs\\":\\t1664209748,\\n" + "\\t\\t\\"EventMsTs\\":\\t1664209748180,\\n" +
"\\t\\t\\"UserId\\":\\t\\"user_85034614\\",\\n" + "\\t\\t\\"Reason\\":\\t0\\n" + "\\t}\\n" +
"}";
						
        String Sign = "kkoFeO3Oh2ZHnjtg8tEAQhtXK16/KI05W3BQff8IvGA=";  
        String resultSign = getResultSign(key, body);
        
        
        if (resultSign.equals(Sign)) {
            System.out.println("{'Status': 'OK', 'Info': '校验通过'}");
        } else {
            System.out.println("{'Status': 'FAIL', 'Info': '校验失败''}");
        }
    }
}
说明：
更多签名示例说明可参见 签名校验示例。

回调不通的常见原因

如果遇到回调不通的情况，建议先依照如下清单排查设置的回调服务是否存在问题。
回调不通的现象
可能存在的原因
回调 URL 访问超时
1. ⽆法完成 DNS 解析，请确认该域名是否在公⽹⽣效。（例如，回调 HOST 为http://notexist.com，该域名不存在，⽆法完成 DNS 解析）
2. ⽆法访问到回调 URL 中配置的 IP，请确认该 IP 是否公⽹可达。（例如，回调 HOST 为http://10.0.0.1，该域名为内⽹ IP，⽆法访问到该 IP）
3. 回调服务防⽕墙策略限制，请检查防⽕墙配置。（例如，App 回调服务器拒绝了所有到达 80 端⼝的请求）
回调服务拒绝访问
可以访问到 HOST，但链接建⽴失败，请确认 WebServer 已经正确启动。（例如：回调服务器的 WebServer 并未启动，或者端⼝配置错误。）
回调服务 HTTPS 证书配置错误
回调⽅式为 HTTPS（或 HTTPS 双向认证），能够访问到回调服务器，但判定 WebServer 配置的证书⾮法。请确认 HTTPS 证书配置正确。
回调服务 HTTPS 双向认证配置错误
回调⽅式为 HTTPS 双向认证，校验回调服务器的证书合法，但回调服务器校验实时⾳视频 TRTC 的证书失败。
回调服务 HTTP 返回码⾮200
回调请求成功，但应答报⽂中的 HTTP 返回码⾮200。
回调应答包体解析失败
回调请求包体⾮ JSON 格式。
中国站
文档反馈
文档活动
message-icon联系我们
目录