开始白板推流

最近更新时间:2024-03-12 01:56:22

我的收藏

1. 接口描述

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

发起一个白板推流任务

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

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

2. 输入参数

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

参数名称 必选 类型 描述
Action String 公共参数,本接口取值:StartWhiteboardPush。
Version String 公共参数,本接口取值:2019-09-19。
Region String 公共参数,详见产品支持的 地域列表
SdkAppId Integer 客户的SdkAppId
示例值:1400000001
RoomId Integer 需要推流的白板房间号,取值范围: (1, 4294967295)。

1. 在没有指定GroupId的情况下,白板推流默认以RoomId的字符串表达形式作为IM群组ID(比如RoomId为1234,则IM群组ID为"1234"),并加群进行信令同步,请在开始推流前确保相应IM群组已创建完成,否则会导致推流失败。
2. 在没有指定TRTCRoomIdTRTCRoomIdStr的情况下,默认会以RoomId作为白板流进行推流的TRTC房间号。
示例值:12345
PushUserId String 用于白板推流服务进入白板房间的用户ID。在没有额外指定IMAuthParamTRTCAuthParam的情况下,这个用户ID同时会用于IM登录、IM加群、TRTC进房推流等操作。
用户ID最大长度不能大于60个字节,该用户ID必须是一个单独的未同时在其他地方使用的用户ID,白板推流服务使用这个用户ID进入房间进行白板音视频推流,若该用户ID和其他地方同时在使用的用户ID重复,会导致白板推流服务与其他使用场景帐号互踢,影响正常推流。
示例值:tic_push_12345_xxx
PushUserSig String PushUserId对应的IM签名(usersig)。
示例值:eJwtjb0OgjAAhN*lK4a0tcVC4iDGkIg-g7K4NEiLViLUUsFgfHcRmS733eXuDY6b
Whiteboard Whiteboard 白板参数,例如白板宽高、背景颜色等
AutoStopTimeout Integer 自动停止推流超时时间,单位秒,取值范围[300, 259200], 默认值为1800秒。

当白板超过设定时间没有操作的时候,白板推流服务会自动停止白板推流。
示例值:300
AutoManageBackup Boolean 对主白板推流任务进行操作时,是否同时同步操作备份任务
示例值:false
Backup WhiteboardPushBackupParam 备份白板推流相关参数。

指定了备份参数的情况下,白板推流服务会在房间内新增一路白板画面视频流,即同一个房间内会有两路白板画面推流。
PrivateMapKey String TRTC高级权限控制参数,如果在实时音视频开启了高级权限控制功能,必须提供PrivateMapKey才能保证正常推流。
VideoFPS Integer 白板推流视频帧率,取值范围[0, 30],默认20fps
示例值:15
VideoBitrate Integer 白板推流码率, 取值范围[0, 2000],默认1200kbps。

这里的码率设置是一个参考值,实际推流的时候使用的是动态码率,所以真实码率不会固定为指定值,会在指定值附近波动。
示例值:1200
AutoRecord Boolean 在实时音视频云端录制模式选择为 指定用户录制 模式的时候是否自动录制白板推流。

默认在实时音视频的云端录制模式选择为 指定用户录制 模式的情况下,不会自动进行白板推流录制,如果希望进行白板推流录制,请将此参数设置为true。

如果实时音视频的云端录制模式选择为 全局自动录制 模式,可忽略此参数。
示例值:false
UserDefinedRecordId String 指定白板推流这路流在音视频云端录制中的RecordID,指定的RecordID会用于填充实时音视频云端录制完成后的回调消息中的 "userdefinerecordid" 字段内容,便于您更方便的识别录制回调,以及在点播媒体资源管理中查找相应的录制视频文件。

限制长度为64字节,只允许包含大小写英文字母(a-zA-Z)、数字(0-9)及下划线和连词符。

此字段设置后,不管AutoRecord字段取值如何,都将自动进行白板推流录制。

默认RecordId生成规则如下:
urlencode(SdkAppID_RoomID_PushUserID)

例如:
SdkAppID = 12345678,RoomID = 12345,PushUserID = push_user_1
那么:RecordId = 12345678_12345_push_user_1
示例值:12345678_12345_push_user_1
AutoPublish Boolean 在实时音视频旁路推流模式选择为指定用户旁路模式的时候,是否自动旁路白板推流。

默认在实时音视频的旁路推流模式选择为 指定用户旁路 模式的情况下,不会自动旁路白板推流,如果希望旁路白板推流,请将此参数设置为true。

如果实时音视频的旁路推流模式选择为 全局自动旁路 模式,可忽略此参数。
示例值:false
UserDefinedStreamId String 指定实时音视频在旁路白板推流这路流时的StreamID,设置之后,您就可以在腾讯云直播 CDN 上通过标准直播方案(FLV或HLS)播放该用户的音视频流。

限制长度为64字节,只允许包含大小写英文字母(a-zA-Z)、数字(0-9)及下划线和连词符。

此字段设置后,不管AutoPublish字段取值如何,都将自动旁路白板推流。

默认StreamID生成规则如下:
urlencode(SdkAppID_RoomID_PushUserID_main)

例如:
SdkAppID = 12345678,RoomID = 12345,PushUserID = push_user_1
那么:StreamID = 12345678_12345_push_user_1_main
示例值:12345678_12345_push_user_1_main
ExtraData String 内部参数,不需要关注此参数
TRTCRoomId Integer TRTC数字类型房间号,取值范围: (1, 4294967295)。

在同时指定了RoomIdTRTCRoomId的情况下,优先使用TRTCRoomId作为白板流进行推流的TRTC房间号。

当指定了TRTCRoomIdStr的情况下,此字段将被忽略。
示例值:12345
TRTCRoomIdStr String TRTC字符串类型房间号。

在指定了TRTCRoomIdStr的情况下,会优先使用TRTCRoomIdStr作为白板流进行推流的TRTC房间号。
示例值:wbpush-12345
IMAuthParam AuthParam IM鉴权信息参数,用于IM鉴权。
当白板信令所使用的IM应用与白板应用的SdkAppId不一致时,可以通过此参数提供对应IM应用鉴权信息。

如果提供了此参数,白板推流服务会优先使用此参数指定的SdkAppId作为白板信令的传输通道,否则使用公共参数中的SdkAppId作为白板信令的传输通道。
TRTCAuthParam AuthParam TRTC鉴权信息参数,用于TRTC进房推流鉴权。
当需要推流到的TRTC房间所对应的TRTC应用与白板应用的SdkAppId不一致时,可以通过此参数提供对应的TRTC应用鉴权信息。

如果提供了此参数,白板推流服务会优先使用此参数指定的SdkAppId作为白板推流的目标TRTC应用,否则使用公共参数中的SdkAppId作为白板推流的目标TRTC应用。
TRTCEnterRoomMode String 指定白板推流时推流用户进TRTC房间的进房模式。默认为 TRTCAppSceneVideoCall

TRTCAppSceneVideoCall - 视频通话场景,即绝大多数时间都是两人或两人以上视频通话的场景,内部编码器和网络协议优化侧重流畅性,降低通话延迟和卡顿率。
TRTCAppSceneLIVE - 直播场景,即绝大多数时间都是一人直播,偶尔有多人视频互动的场景,内部编码器和网络协议优化侧重性能和兼容性,性能和清晰度表现更佳。
示例值:TRTCAppSceneVideoCall
GroupId String 白板进行信令同步的 IM 群组 ID。
在没有指定GroupId的情况下,白板推流服务将使用 RoomId 的字符串形式作为同步白板信令的IM群组ID。
在指定了GroupId的情况下,白板推流将优先GroupId作为同步白板信令的群组ID。请在开始推流前确保指定的IM群组已创建完成,否则会导致推流失败。
示例值:12345

3. 输出参数

参数名称 类型 描述
TaskId String 推流任务Id
示例值:0c69baivvc3lp8t4f80b
Backup String 备份任务结果参数
注意:此字段可能返回 null,表示取不到有效值。
RequestId String 唯一请求 ID,由服务端生成,每次请求都会返回(若请求因其他原因未能抵达服务端,则该次请求不会获得 RequestId)。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 开始白板推流

创建一个白板推流任务

输入示例

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

{
    "PushUserId": "tic_push_user_1203_141551",
    "PushUserSig": "usersig_of_<tic_push_user_1203_141551>",
    "RoomId": "1203",
    "SdkAppId": "1400000001"
}

输出示例

{
    "Response": {
        "Backup": "{\"RequestId\":\"8e9b2bc4-ec7f-46cd-823b-66676e2375f8\",\"TaskId\":\"052lfmu5uc3lp0rrqvvb\"}",
        "RequestId": "eac6b301-a322-493a-8e36-83b295459397",
        "TaskId": "bj0mt2l23osdj300hl30"
    }
}

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签名/鉴权错误。
InvalidParameter.BodyParameterTypeUnmatched 参数类型不匹配。
InvalidParameter.InvalidExtra 额外指定的特殊功能不存在。
InvalidParameter.RecordParameter 实时录制参数格式不正确。
InvalidParameter.SdkAppIdNotFound SdkAppId不存在或格式错误。
LimitExceeded.TaskConcurrency 转码或录制任务并发数量超过限制,请参考错误描述或稍后重试。
ResourceInUse.RecordUserId 实时录制任务录制用户已被其他录制任务使用。
ResourceUnavailable.NotRegistered 未开通互动白板。
ResourceUnavailable.ServiceExpired 账户欠费或者互动白板服务已过期。
UnauthorizedOperation.SdkAppId SdkAppId不存在或者SdkAppId与当前腾讯云账号不对应。