开始云端录制

最近更新时间:2024-08-06 02:22:48

我的收藏

1. 接口描述

接口请求域名: trtc.tencentcloudapi.com 。

接口说明:
启动云端录制功能,完成房间内的音视频录制,并上传到指定的云存储。您可以通过此 API 接口把TRTC 房间中的每一路音视频流做单独的录制又或者多路视频画面合流混成一路。

您可以通过此接口实现如下目标:

  • 指定订阅流参数(RecordParams)来指定需要录制的主播的黑名单或者白名单。
  • 指定录制存储参数(StorageParams)来指定上传到您希望的云存储,目前支持腾讯云(云点播VOD、对象存储COS)和第三方AWS
  • 指定合流模式下的音视频转码详细参数(MixTranscodeParams),包括视频分辨率、视频码率、视频帧率、以及声音质量等
  • 指定合流模式各路画面的位置和布局或者也可以指定自动模板的方式来配置。

关键名词:

  • 单流录制:分别录制房间的订阅UserId的音频和视频,录制服务会实时将录制文件上传至您指定的云存储。
  • 合流录制:将房间内订阅UserId的音视频混录成一个视频文件,并将录制文件上传至您指定的云存储。(录制结束后可前往云点播控制台https://console.cloud.tencent.com/vod/media 或 对象存储COS控制台https://console.cloud.tencent.com/cos/bucket查看文件)。

默认接口请求频率限制:20次/秒。

推荐使用 API Explorer
点击调试
API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。

2. 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见 公共请求参数

参数名称 必选 类型 描述
Action String 公共参数,本接口取值:CreateCloudRecording。
Version String 公共参数,本接口取值:2019-07-22。
Region String 公共参数,详见产品支持的 地域列表,本接口仅支持其中的: ap-beijing, ap-guangzhou, ap-shanghai 。
SdkAppId Integer TRTC的SdkAppId,和录制的房间所对应的SdkAppId相同。
示例值:1234
RoomId String TRTC的RoomId,录制的TRTC房间所对应的RoomId。
注:房间号类型默认为整型,若房间号类型为字符串,请通过RoomIdType指定。

示例值:1234
UserId String 录制机器人的UserId,用于进房发起录制任务。
【*注意】这个UserId不能与当前房间内的主播观众UserId重复。如果一个房间发起多个录制任务时,机器人的userid也不能相互重复,否则会中断前一个录制任务。建议可以把房间ID作为UserId的标识的一部分,即录制机器人UserId在房间内唯一。
示例值:recorder_1234
UserSig String 录制机器人UserId对应的校验签名,即UserId和UserSig相当于录制机器人进房的登录密码,具体计算方法请参考TRTC计算UserSig的方案。
示例值:recorder_1234_sig
RecordParams RecordParams 云端录制控制参数。
StorageParams StorageParams 云端录制文件上传到云存储的参数(不支持同时设置云点播VOD和对象存储COS)
RoomIdType Integer TRTC房间号的类型。
【*注意】必须和录制的房间所对应的RoomId类型相同:
0: 字符串类型的RoomId
1: 32位整型的RoomId(默认)
示例值:1
MixTranscodeParams MixTranscodeParams 合流的转码参数,录制模式为合流的时候可以设置。
MixLayoutParams MixLayoutParams 合流的布局参数,录制模式为合流的时候可以设置。
ResourceExpiredHour Integer 接口可以调用的时效性,从成功开启录制并获得任务ID后开始计算,超时后无法调用查询、更新和停止等接口,但是录制任务不会停止。 参数的单位是小时,默认72小时(3天),最大可设置720小时(30天),最小设置6小时。举例说明:如果不设置该参数,那么开始录制成功后,查询、更新和停止录制的调用时效为72个小时。
PrivateMapKey String TRTC房间权限加密串,只有在TRTC控制台启用了高级权限控制的时候需要携带,在TRTC控制台如果开启高级权限控制后,TRTC 的后台服务系统会校验一个叫做 [PrivateMapKey] 的“权限票据”,权限票据中包含了一个加密后的 RoomId 和一个加密后的“权限位列表”。由于 PrivateMapKey 中包含 RoomId,所以只提供了 UserSig 没有提供 PrivateMapKey 时,并不能进入指定的房间。

3. 输出参数

参数名称 类型 描述
TaskId String 云录制服务分配的任务 ID。任务 ID 是对一次录制生命周期过程的唯一标识,结束录制时会失去意义。任务 ID需要业务保存下来,作为下次针对这个录制任务操作的参数。
示例值:test
RequestId String 唯一请求 ID,由服务端生成,每次请求都会返回(若请求因其他原因未能抵达服务端,则该次请求不会获得 RequestId)。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 启动云端录制

启动SdkAppId 为 1234 指定房间(房间号为3560)的云端录制。

房间空闲等待时间设置为1分钟。
录制模式为合流模式。
录制的流类型为音视频。
默认订阅所有用户的流。
录制视频的宽度360,录制视频的高度640,帧率15,比特率500,000bps,默认背景色。
录制视频布局模式为九宫格布局。
存储至腾讯云点播VOD

输入示例

POST / HTTP/1.1
Host: trtc.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateCloudRecording
<公共请求参数>

{
    "StorageParams": {
        "CloudVod": {
            "TencentVod": {
                "ExpireTime": 0
            }
        }
    },
    "UserSig": "11xx111",
    "UserId": "10001",
    "RecordParams": {
        "MaxIdleTime": 60,
        "StreamType": 0,
        "RecordMode": 2
    },
    "RoomIdType": 1,
    "MixTranscodeParams": {
        "VideoParams": {
            "Width": 360,
            "BitRate": 500000,
            "Fps": 15,
            "Height": 640,
            "Gop": 10
        }
    },
    "MixLayoutParams": {
        "MixLayoutMode": 3
    },
    "SdkAppId": 1234,
    "RoomId": "3560"
}

输出示例

{
    "Response": {
        "TaskId": "-gCTFWtU7t7DUlo7A8IswFszO9z2O-rbERqJAoK-4pycoZXKjIAAnasdcasdOEycyX4CnzhIm4RAQ..",
        "RequestId": "71993312-6ab8-4768-9124-118e0a20c45f"
    }
}

5. 开发者资源

腾讯云 API 平台

腾讯云 API 平台 是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台,方便您从同一入口查询及使用腾讯云提供的所有 API 服务。

API Inspector

用户可通过 API Inspector 查看控制台每一步操作关联的 API 调用情况,并自动生成各语言版本的 API 代码,也可前往 API Explorer 进行在线调试。

SDK

云 API 3.0 提供了配套的开发工具集(SDK),支持多种编程语言,能更方便的调用 API。

命令行工具

6. 错误码

以下仅列出了接口业务逻辑相关的错误码,其他错误码详见 公共错误码

错误码 描述
AuthFailure CAM签名/鉴权错误。
AuthFailure.UnRealNameAuthenticated 未完成实名认证,不允许此操作。
AuthFailure.UnauthorizedOperation CAM鉴权失败。
AuthFailure.UnsupportedOperation 不支持该操作。
FailedOperation 操作失败。
FailedOperation.CRUnsupportMethod 云端录制方法不支持。
FailedOperation.RestrictedConcurrency 单用户并发过载,请联系我们增大并发路数到合理值。
InternalError.CRInternalError 云端录制内部服务错误。
InvalidParameter.OutOfRange 参数超出范围。
InvalidParameter.SdkAppId SdkAppId参数错误。
MissingParameter.AccessKey 缺少AccessKey参数。
MissingParameter.Bucket 缺少Bucket参数。
MissingParameter.CloudStorage 缺少CloudStorage参数。
MissingParameter.RecordMode 缺少RecordMode参数。
MissingParameter.RecordParams 缺少RecordParams参数。
MissingParameter.Region 缺少Region参数。
MissingParameter.RoomId 缺少RoomId参数。
MissingParameter.SdkAppId 缺少SdkAppId参数。
MissingParameter.SecretKey 缺少SecretKey参数。
MissingParameter.StorageParams 缺少StorageParams参数。
MissingParameter.StreamType 缺少StreamType参数。
MissingParameter.TaskId 缺少TaskId参数。
MissingParameter.UserId 缺少UserId参数。
MissingParameter.UserSig 缺少UserSig参数。
MissingParameter.Vendor 缺少Vendor参数。
UnsupportedOperation 操作不支持。