场景说明
在远程教育、秀场直播、视频会议、远程定损、金融双录、在线医疗等应用场景中,考虑取证、质检、审核、存档和回放等需求,常需要将整个视频通话或互动直播过程录制和存储下来的情况。
说明
下文将针对实时音视频最新推出的云端录制能力进行使用说明。自2022年08月01日起新创建的应用(SdkAppId)录制功能类型为新版云端录制。若您当前的 TRTC 应用(sdkappid)使用的是旧版云端录制,详情请参见 旧版云端录制。判断当前应用的云端录制的类型和旧版云端录制能力切换为新版的方式,详情请参见 控制台 > 云端录制说明。
功能说明
通过 TRTC 的云端录制功能,您可以将房间中的每一个用户的音视频流都录制成独立的文件(单流录制),或者把同一个房间的音视频媒体流合流录制成一个文件(合流录制)。
订阅流: 我们支持通过制定订阅用户的黑白名单的方式来指定您需要订阅的用户媒体流(仅支持 API 录制)。
转码参数:合流的场景下,我们支持通过设置编解码的参数来指定录制的视频文件的质量。
合流参数:合流的场景下,我们支持多种灵活可变的自动多画面布局模板和自定义布局模板。
文件存储:支持存储到云点播 VOD 或对象存储 COS。
回调通知:我们支持回调通知的能力,通过配置您的回调域名,云端录制的事件状态会通知到您的回调服务器。
单流录制和合流录制说明
单流录制
如下图所示为单流录制的场景,房间1234里面主播1和主播2都上行了音视频流,假设您订阅了主播1和主播2的音视频流,并设置录制模式为单流录制,录制后台会分别拉取主播1和主播2的音视频流,并把他们录制成独立的媒体文件包含:
主播1的一个音视频录制文件。
主播2的一个音视频录制文件。
录制后台会把这些文件上传到您指定的云存储平台(云点播 VOD 或对象存储 COS)。具体录制流程如下:
合流录制
如下图所示为合流录制的场景,房间1234里面有主播1和主播2都上行了音视频流,假设您订阅了主播1和主播2的音视频流,设置录制模式为合流录制,录制后台会分别拉取主播1和主播2的音视频流,并把他们的视频流按照您配置多画面模板进行合流,音频流进行混音,最后把媒体流混合成一路媒体文件。包含:合流后的一个音视频录制文件,具体发起方式请见API手动录制。
录制后台会把这些文件上传到您指定的云存储平台。具体录制流程如下:
录制文件命名和文件切分说明
录制 MP4/AAC 文件名命名规则
单流录制 MP4/AAC 文件名规则:
<SdkAppId>_<RoomId>_UserId_s_<UserId>_UserId_e_<MediaId>_<Index>.mp4/aac
合流录制 MP4/AAC 文件名规则:
<SdkAppId>_<RoomId>_<Index>.mp4/aac
录制 HLS 文件名命名规则
单流录制 HLS 文件名规则:
<SdkAppId>_<RoomId>_UserId_s_<UserId>_UserId_e_<MediaId>_<Type>.m3u8
合流录制 HLS 文件名规则:
<SdkAppId>_<RoomId>.m3u8
字段含义说明:
字段 | 含义 |
<SdkAppId> | 录制任务的 SdkAppId |
<RoomId> | 录制的房间号,如果这里 RoomId 如果是字符串房间号,我们会对房间号先做 base64 操作,再把 base64 后的字符串中符号'/'替换成 '-' (中划线),符号'='替换成 '.' |
<UserId> | 录制的用户 ID,UserId 会先做 base64 操作,再把base64后的字符串中符号'/'替换成 '-' (中划线),符号'='替换成 '.' |
<MediaId> | 主辅流标识,main 代表主流(摄像头),aux 代表辅流(屏幕分享) |
<Index> | 如果没有触发切片逻辑(大小超过2GB或超过设置的切片时长)则无该字段,否则为切片的索引号,从1开始递增 |
<Type> | 录制文件流类型,audio/video/audiovideo |
说明:
自定义设置文件名称前缀:使用 API 录制 存储至云点播 VOD 时,可通过 TencentVod 中的 UserDefineRecordId 参数自定义文件名称前缀,前缀与默认录制文件名之间用_UserIdu_分隔。
录制文件切分说明
录制 MP4/ACC 文件切分的条件:
录制切分时长可设置范围1-1440分钟,默认1440分钟。
单个 MP4/AAC 文件大小达到 2GB。
录制 HLS 文件切分的条件:
录制任务持续时间超过14天时,HLS 文件将会被切分。
录制上传云存储说明
录制后台会在录制结束后将录制的文件通过您指定的方式上传到云存储平台(云点播 VOD 或对象存储 COS),并通过回调的形式把播放地址发送给您。如果录制模式为单流录制模式,每一个订阅的主播都会有一个对应的播放地址;如果录制模式为合流录制模式,只有一个合流后媒体的播放地址。
1. 通过 API 发起录制:在存储参数 StorageParams 中必须指定 CloudVod(存储至云点播 VOD) 或 CloudStorage(存储至对象存储 COS 或第三方云存储)的参数,请确保已经开通对应的云存储服务且未欠费。
2. 上传任务的过程中使用 DescribeCloudRecording 只能查询到录制任务进行状态,不会携带录制文件的信息。
注意:
文件录制后会上传至您指定云存储平台(云点播 VOD 或对象存储 COS),为确保录制文件成功,请确保您指定的云点播 VOD 或对象存储 COS 服务可用。
API 接口和录制并发限制
录制接口的调用频率限制为20qps(如需提高 QPS 请 提交工单)。
单个接口超时时间为6秒。
单个应用下默认并发录制支持500路(全局自动录制和 API 录制任务的总和),超过并发限制的任务会失败,如需更多并发路数,请 提交工单 联系我们。
单次录制任务最大支持同时订阅的房间内主播数为25个,主播只上行音频也会单独占据一路。
录制控制方案
TRTC 提供了两种云端录制方案,分别是 全局自动录制 和 API 手动录制,这两种方案并不冲突,可以同时使用两种录制方案,但会产生两份录制文件和费用。API 录制相比全局自动录制的优点是录制灵活、功能完备,客户可以指定录制订阅房间内的主播,自定义合流布局,录制中途更新布局和订阅等。全局自动录制的优点是录制不需客户启动和停止,由 TRTC 后台管理录制任务。
方案一:全局自动录制
生效后(生效等待5-10分钟)TRTC 房间中的主播上行音视频后将触发启动录制任务,房间内主播都退房且超过设置的等待续录时间后将触发停止录制任务。
全局单流录制
配置项 | 说明 |
录制模式 | 单流录制:房间中的每个主播的视频画面都会单独保存成一份文件 |
录制格式 | 音视频格式:录制房间内的音频和视频流,适用于视频通话、互动直播场景 纯音频格式:只录制房间内的音频流 |
文件格式 | 支持 MP4 、HLS 和 AAC(纯音频格式下) |
单个录制文件时长 | 可用于指定录制文件切片时长,设置范围1-1440分钟,默认1440分钟 |
续录等待时长 | 设置续录超时时长,当打断间隔不超过设定的续录超时时长时,一次通话(或直播)只会生成一个文件,但需要等待续录时间超时后才能收到录制文件,单位:秒,取值范围1 - 86400(默认5s)。 注意:在续录等待期内,单流录制会按照音频时长收取录制费用,请合理设置。 |
录制文件存储 | |
回调地址与回调密钥 |
说明:
单流录制模式下房间内的音视频流将按照推流参数进行每一路单独录制,无需设置转码。
续录等待时长未到期内录制机器人会在房间内继续等待主播上行进而完成录制,并不会因为主播退房后就立即结束,请合理设置。
单流录制最多录制一个房间内的25个主播,如果超过25个主播将会按照进房时间由先到后排序,录制前25位主播(如需单流录制超过25位主播,请参见 API 录制)。
方案二:API 手动录制
启动录制
通过您的后台服务调用 REST API (CreateCloudRecording)来启动云端的录制,需要重点关注参数— 任务 ID(TaskId);这个参数是本次录制任务的唯一标识,您需要保存下这个任务 ID 作为后续针对这个录制任务接口操作的输入参数。
说明:
1. 发起云端录制任务的接口 CreateCloudRecording 中需要您指定分配录制机器人的进房参数 UserId 和 UserSig(如何获取 UserSig),请不要与您房间内的正常主播或观众使用的 UserId 重复且不可与正在录制中的房间内指定的录制机器人 UserId 一致,否则会导致录制任务失败。
2. 手动录制下,您可以前往控制台配置回调地址,以接受录制回调事件,请见 录制回调说明。
录制的模式(RecordMode)
单流录制:实时录制房间内每个主播的音频视频单录制为一个音视频文件上传到云存储平台(云点播 VOD 或对象存储 COS)。
合流录制:将房间内您所订阅所有主播的音视频流混录成一个音视频文件上传到云存储平台(云点播 VOD 或对象存储 COS)。
指定录制用户(SubscribeStreamUserIds)
默认情况下,云端录制会录制房间内所有的媒体流(最多25路),超过25个用户,默认录制最先进房的25位主播。您也可以通过参数 SubscribeStreamUserIds 指定想要录制或者不想录制的主播用户的黑白名单信息,当然我们也支持在录制的过程中进行更新操作。单流录制场景,如果房间内主播超过25人,可以通过设置订阅名单发起多次录制任务实现。
指定存储位置和录制格式(StorageParams)
录制格式:默认录制格式是 MP4, 如果需要录制成 HLS 格式, 可通过 CloudVod 下 TencentVod 内的 MediaType 设置为1来指定格式为 HLS;如果需要录制AAC 格式文件, 可通过 CloudVod 下 TencentVod 内的 MediaType 设置为2来指定格式为 AAC(仅在 StreamType=1纯音频录制时有效)
录制开始的时间的获取
通过订阅回调,监听录制回调事件。在事件类型311中的 StartTimeStamp 字段您可以获取到录制文件对应的录制起始时间戳,EndTimeStamp 字段可以获取到对应的录制结束时间戳。
{"EventGroupId": 3,"EventType": 311,"CallbackTs": 1622186289148,"EventInfo": {"RoomId": "xx","EventTs": "1622186289","UserId": "xx","TaskId": "xx","Payload": {"Status": 0,"TencentVod": {"UserId": "anchor1","TrackType": "video","MediaId": "main","FileId": "xxxxx","VideoUrl": "http://xxxxx","CacheFile": "xxxxxx","StartTimeStamp": 1622186279,"EndTimeStamp": 1622186811}}}}
合流录制的布局模式参数(MixLayoutMode)
悬浮布局
默认第一个进入房间的主播(也可以指定一个主播)的视频画面会铺满整个屏幕。其他主播的视频画面从左下角开始依次按照进房顺序水平排列,显示为小画面,小画面悬浮于大画面之上。当画面数量小于等于17个时,每行4个(4 × 4排列)。当画面数量大于17个时,重新布局小画面为每行5个(5 × 5)排列。最多支持25个画面,如果用户只发送音频,仍然会占用画面位置。
悬浮布局随着订阅的子画面增加按照下图进行变化:
子画面小于等于17个时 | 每个小画面的宽和高分别为整个画布宽和高的 0.235 相邻小画面的左右和上下间距分别为整个画布宽和高的 0.012 小画面距离画布的水平和垂直边距也分别为整个画布宽和高的 0.012 | |
子画面大于17个时 | 每个小画面的宽和高分别为整个画布宽和高的 0.188 相邻小画面的左右和上下间距分别为整个画布宽和高的 0.01 小画面距离画布的水平和垂直边距也分别为整个画布宽和高的 0.01
| |
指定一个主播在屏幕左侧的大画面位置(如果不指定,那么大画面位置为背景色),其他主播自上而下依次垂直排列于右侧。当画面数量少于17个的时候,右侧每列最多8人,最多占据两列。当画面数量多于17个的时候,超过17个画面的主播从左下角开始依次水平排列。最多支持24个画面,如果主播只发送音频,仍然会占用画面位置。
屏幕分享布局随着订阅的子画面增加按照下图进行变化:
子画面小于等于5个时 | 右侧小画面的宽为整个画布宽的1/5,右侧小画面的高为整个画布高的1/4 左侧大画面的宽为整个画布宽的4/5,左侧大画面的高为整个画布高 | |
子画面大于5且小于等于7个时 | 右侧小画面的宽为整个画布宽的1/7,右侧小画面的高为整个画布高的1/6 左侧大画面的宽为整个画布宽的6/7,左侧大画面的高为整个画布高 | |
子画面大于7且小于等于9个时 | 右侧小画面的宽为整个画布宽的1/9,右侧小画面的高为整个画布高的1/8 左侧大画面的宽为整个画布宽的8/9,左侧大画面的高为整个画布高 | |
子画面大于9小于等于17个时 | 右侧小画面的宽为整个画布宽的1/10,右侧小画面的高为整个画布高的1/8 左侧大画面的宽为整个画布宽的4/5,左侧大画面的高为整个画布高 | |
子画面大于17个时 | 右(下)侧小画面的宽为整个画布宽的1/10,右(下)侧小画面的高为整个画布高的1/8 左侧大画面的宽为整个画布宽的4/5,左侧大画面的高为整个画布高的7/8 | |
九宫格布局
根据主播的数量自动调整每个画面的大小,每个主播的画面大小一致,最多支持25个画面。
九宫格布局随着订阅的子画面增加按照下图进行变化:
子画面为1个时 | 每个小画面的宽和高分别为整个画布宽和高 | |
子画面为2个时 | 每个小画面的宽为整个画布宽的1/2 每个小画面的高为整个画布高 | |
子画面小于等于4个时 | 每个小画面的宽和高分别为整个画布宽和高的 1/2 | |
子画面小于等于9个时 | 每个小画面的宽和高分别为整个画布宽和高的 1/3 | |
子画面小于等于16个时 | 每个小画面的宽和高分别为整个画布宽和高的 1/4 | |
子画面大于16个时 | 每个小画面的宽和高分别为整个画布宽和高的1/5 | |
我们支持在合流录制中添加图片水印,最大支持个数为25个,可以在画布任意位置添加水印。
字段名 | 解释 |
Top | 水印相对左上角的垂直位移 |
Left | 水印相对左上角的水平位移 |
Width | 水印显示的宽度 |
Height | 水印显示的高度 |
url | 水印文件的存储 URL |
查询录制(DescribeCloudRecording)
如果需要,您可以调用该接口查询录制服务的状态。
注意:
只有录制任务存在的时候才能查询到信息,如果录制任务已经结束会返回错误。
如果是上传云点播 VOD 任务,该接口返回的 StorageFile 为空。
更新录制(ModifyCloudRecording)
如果需要,您可以调用该接口修改录制服务的参数,如订阅黑白名单 SubscribeStreamUserIds(单流和合流录制有效),录制的模板参数 MixLayoutParams(合流录制有效)。
注意:
更新操作是全量覆盖的操作,并不是增量更新的操作,您每次更新都需要携带全量的信息,包括模板参数 MixLayoutParams 和黑白名单 SubscribeStreamUserIds,因此您需要保存之前的启动录制的参数或者重新计算完整的录制相关参数。
停止录制(DeleteCloudRecording)
在录制结束之后需要调用停止录制(DeleteCloudRecording)的接口来结束录制任务,否则录制任务会等待到达预设的超时时间 MaxIdleTime 后自动结束。
注意:
MaxIdleTime 的定义是房间内持续没有主播的状态超过 MaxIdleTime 的时长,这里如果房间是存在有主播,但是主播没有上行数据是不会进入超时的计时状态的,此时后台录制会持续工作。建议业务在录制结束的时候调用此接口结束录制任务。
录制回调事件
录制文件管理
查找录制文件
结束房间完成录制任务后,TRTC 录制系统中录制下来的文件上传至您指定的云存储平台(云点播 VOD 或对象存储 COS)。您可以直接前往 云点播控制台 或 对象存储 COS 控制台 查找,也可以由您的后台服务器使用 REST API 进行定时筛选:
方式一:在点播控制台手动查找
1. 登录 云点播控制台,在左侧导航栏选择媒资管理。
2. 单击列表上方的前缀搜索,选择前缀搜索,在搜索框输入关键词,按照 录制文件命名规则 填入,例如合流录制下填入:
1400000123_1001
,单击
,将展示视频名称前缀相匹配的视频文件。
3. 登录 对象存储 COS 控制台,选择您指定的存储桶 Bucket 进行查找:
方式二:通过点播 REST API 查找
腾讯云点播系统提供了一系列 REST API 来管理其上的音视频文件,您可以通过 搜索媒体信息 这个 REST API 来查询您在点播系统上的文件。您可以通过
TrtcSdkAppIds(对应发起录制的应用 SdkAppid)
或TrtcRoomIds(对应发起录制的房间号 Roomid)
参数进行匹配查找。
REST API请求示例:https://vod.tencentcloudapi.com/?Action=SearchMedia&TrtcSdkAppIds=1400xxxx123&TrtcRoomIds=1234&Sort.Field=CreateTime&Sort.Order=Desc&<公共请求参数>
说明:
接收录制文件
除了 查找录制文件,您还可以通过在控制台 配置回调地址,让腾讯云主动把新录制文件的消息推送给您的服务器。
房间里的最后一路音视频流退出后,该过程大约默认需要30秒至数分钟(具体时间根据您所录制的文件大小而定,若您设置了续录时间为300秒,则等待时间将在默认基础上叠加300秒)。转存完成后,腾讯云会通过您在 设置录制回调 中设置的回调地址(HTTP/HTTPS)向您的服务器发送通知。
腾讯云会将录制和录制相关的事件都通过您设置的回调地址推送给您的服务器,您可以通过接收事件类型为311的上传成功回调来获取录制文件的播放地址 VideoUrl,具体回调信息见下方:
{"EventGroupId": 3,"EventType": 311,"CallbackTs": 1622191965320,"EventInfo": {"RoomId": "20015","EventTs": 1622191965,"UserId": "xx","TaskId": "xx","Payload": {"Status": 0,"TencentVod": {"UserId": "xx","TrackType": "audio_video","MediaId": "main","FileId": "xxxx","VideoUrl": "http://xxxx","CacheFile": "xxxx.mp4","StartTimeStamp": xxxx,"EndTimeStamp": xxxx}}}}
删除录制文件
https://vod.tencentcloudapi.com/?Action=DeleteMedia&FileId=52858907988664150587&<公共请求参数>
回放录制文件
在线教育等场景中,通常需要在直播结束后多次回放录制文件,以便充分利用教学资源。
获取点播地址(VideoUrl)
对接点播播放器
根据使用平台对接点播播放器,具体操作参考如下:
iOS 平台
Web 浏览器
注意:
建议使用 专业版 TRTC SDK,专业版集合了 播放器(Player+)、直播 SDK 等功能,由于底层模块的高度复用,集成专业版的体积增量要小于同时集成两个独立的 SDK,并且可以避免符号冲突(symbol duplicate)的困扰。
相关费用
云端录制与回放功能使用到的功能包括:云端录制服务、云点播 VOD 或对象存储 COS 的回放文件存储与处理、云点播 VOD 或对象存储 COS 的播放服务,以及终端 SDK 播放点播视频的能力。可能会根据实际需求产生以下费用。
云端录制费用
云端录制费用取决于您所录制的时长和画面分辨率,同时根据录制模式的不同(单流或者合流)进行区分定价,录制费用计算公式如下:
云端录制费用 = 录制音频费用 + 录制视频费用 = 录制音频输入时长用量 × 单路或多路对应的音频单价 + 录制视频各分辨率档位输入时长用量 × 单路或多路对应的相应视频分辨率档位单价
说明:
文件存储费用
录制出的视频文件存放于云点播 VOD 或对象存储 COS 服务,由于存储本身会产生磁盘资源的消耗,因此需要按照存储的资源占用进行收费。存储的时间越久费用也就越高,因此如无特殊需要,您可以将文件的存储时间设置的短一些来节省费用,或者将文件存放在自己的服务器上。云点播VOD存储费用可以选择 视频存储(日结)价格 进行日结计算,也可以购买 存储资源包;对象存储COS存储费用说明请见 按量计费(后付费)。
注意:
文件播放费用
如果您录制的视频文件要被用于回看播放,会使用云点播或对象存储的 CDN 播放功能。由于观看本身会产生 CDN 流量消耗,因此需要按照云点播或对象存储的价格进行计费,默认按流量收费。观看的人数越多费用越高,云点播播放费用可以选择 视频加速(日结)价格 进行日结计算,也可以购买 流量套餐包。对象存储 COS 播放费用请见 流量费用说明。
SDK 播放授权
音视频通话(TRTC)全功能版本 SDK 提供了功能全面性能强大的视频播放能力,可轻松配合云点播 VOD 或对象存储 COS 实现视频播放功能。移动端 SDK 在10.1及以上的版本可通过获取指定 License 以解锁视频播放能力。
注意:
TRTC 的音视频通话、直播的播放能力无需 License 授权。
您可直接 购买播放器 License,或通过 购买的云点播流量包 免费获赠播放器 License 或 短视频 License,两种 License 均可用于解锁 SDK 的视频播放功能。并且点播资源包可以抵扣云点播的播放产生的日结流量,详细说明请参见 云点播预付费资源包。
License 计费说明参见 腾讯云视立方 License,License 购买完成后可参考 License 操作指引 进行新增和续期等操作。
最佳实践
为了保障录制的高可用,建议客户在集成 REST ful API 的同时注意以下几点。
调用 CreateCloudRecording 请求后,请关注 HTTP response,如果请求失败,那么需要根据具体的状态码采取相应的重试策略。错误码是由“一级错误码”和“二级错误码”组合而成,例如:
InvalidParameter.SdkAppId
。如果返回的 Code 是
InValidParameter.xxxxx
,说明输入的参数有误,请根据提示检查参数。如果返回的 Code 是
InternalError.xxxxx
,说明遇到了服务端错误,可以使用相同的参数重试多次,直到返回正常,拿到 taskid 为止。建议使用退避重试策略,如第一次3s重试,第二次6s重试,第三次12s重试,以此类推。如果返回的 Code 是
FailedOperation.RestrictedConcurrency
,说明客户的并发录制任务数,超过了后台预留的资源(默认是500路),请联系腾讯云技术支持来调整最高并发路数限制。如果您有订阅录制回调,当收到 EVENT_TYPE_CLOUD_RECORDING_RECORDER_STOP 回调事件,LeaveCode 为500时,说明录制与主播数据长时间断开连接,请再次发起录制任务保证录制的可用性。
调用 CreateCloudRecording 接口时,指定的 UserId/UserSig 是录制作为单独的机器人用户加入房间的 ID,请不要和 TRTC 房间内的其他用户重复。同时,TRTC 客户端加入的房间类型必须和录制接口指定的房间类型保持一致,比如 SDK 创建房间用的是字符串房间号,那么云端录制的房间类型也需要相应设置成字符串房间号。
录制状态查询,客户可以通过以下几种方式来得到录制相应的文件信息:
成功发起 CreateCloudRecording 任务后15s左右,调用 DescribeCloudRecording 接口查询录制文件对应的信息,如果查询到状态为 idle 说明录制没有拉到上行的音视频流,请检查房间内是否有主播上行。
成功发起 CreateCloudRecording 后,在确保房间有上行音视频的情况下,可以按照录制文件名的生成规则来拼接录制文件名称。具体文件名规则请参见 录制文件名命名规则。
录制文件的状态会通过回调发送到客户的服务器,如果订阅了相关回调,将会收到录制文件的状态信息。具体回调信息请参见 回调接口。
录制用户(userid)的 UserSig 过期时间应该设置成比录制任务生命周期更长的时间,防止录制任务机器断网,在内部高可用生效的时候,恢复录制因为 UserSig 过期而失败。