启动云端混流(旧)

最近更新时间:2024-03-12 10:45:14

我的收藏

1. 接口描述

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

接口说明:启动云端混流,并指定混流画面中各路画面的布局位置。

TRTC 的一个房间中可能会同时存在多路音视频流,您可以通过此 API 接口,通知腾讯云服务端将多路视频画面合成一路,并指定每一路画面的位置,同时将多路声音进行混音,最终形成一路音视频流,以便用于录制和直播观看。房间销毁后混流自动结束。

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

  • 设置最终直播流的画质和音质,包括视频分辨率、视频码率、视频帧率、以及声音质量等。
  • 设置各路画面的位置和布局,您只需要在启动时设置一次,排版引擎会自动完成后续的画面排布。
  • 设置录制文件名,用于二次回放。
  • 设置 CDN 直播流 ID,用于在 CDN 进行直播观看。

目前已经支持了如下几种布局模板:

  • 悬浮模板:第一个进入房间的用户的视频画面会铺满整个屏幕,其他用户的视频画面从左下角依次水平排列,显示为小画面,最多4行,每行4个,小画面悬浮于大画面之上。最多支持1个大画面和15个小画面,如果用户只发送音频,仍然会占用画面位置。
  • 九宫格模板:所有用户的视频画面大小一致,平分整个屏幕,人数越多,每个画面的尺寸越小。最多支持16个画面,如果用户只发送音频,仍然会占用画面位置。
  • 屏幕分享模板:适合视频会议和在线教育场景的布局,屏幕分享(或者主讲的摄像头)始终占据屏幕左侧的大画面位置,其他用户依次垂直排列于右侧,最多两列,每列最多8个小画面。最多支持1个大画面和15个小画面。若上行分辨率宽高比与画面输出宽高比不一致时,左侧大画面为了保持内容的完整性采用缩放方式处理,右侧小画面采用裁剪方式处理。
  • 画中画模板:适用于混合大小两路视频画面和其他用户混音,或者混合一路大画面和其他用户混音的场景。小画面悬浮于大画面之上,可以指定大小画面的用户以及小画面的显示位置,最多支持2个画面。
  • 自定义模板:适用于在混流中指定用户的画面位置,或者预设视频画面位置的场景。当预设位置指定用户时,排版引擎会为该用户预留位置;当预设位置未指定用户时,排版引擎会根据进房间顺序自动填充。预设位置填满时,不再混合其他用户的画面和声音。自定义模板启用占位图功能时(LayoutParams中的PlaceHolderMode设置成1),在预设位置的用户没有上行视频时可显示对应的占位图(PlaceImageId)。

注意:
1、混流转码为收费功能,调用接口将产生云端混流转码费用,详见云端混流转码计费说明
2、2020年1月9号及以后创建的应用才能直接调用此接口。2020年1月9日之前创建的应用默认使用云直播的云端混流,如需切换至MCU混流,请提交工单寻求帮助。
3、客户端混流和服务端混流不能混用。

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

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

2. 输入参数

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

参数名称 必选 类型 描述
Action String 公共参数,本接口取值:StartMCUMixTranscode。
Version String 公共参数,本接口取值:2019-07-22。
Region String 公共参数,详见产品支持的 地域列表,本接口仅支持其中的: ap-beijing, ap-guangzhou, ap-mumbai 。
SdkAppId Integer TRTC的SDKAppId。
示例值:1400188366
RoomId Integer 房间号。
示例值:3560
OutputParams OutputParams 混流输出控制参数。
示例值:OutputParams
EncodeParams EncodeParams 混流输出编码参数。
示例值:EncodeParams
LayoutParams LayoutParams 混流输出布局参数。
示例值:LayoutParams
PublishCdnParams PublishCdnParams 第三方CDN转推参数。如需转推至腾讯云云直播,此参数无需填写,会默认转推
示例值:PublishCdnParams

3. 输出参数

参数名称 类型 描述
RequestId String 唯一请求 ID,由服务端生成,每次请求都会返回(若请求因其他原因未能抵达服务端,则该次请求不会获得 RequestId)。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 启动云端混流

启动指定房间(房间号为3560)的云端混流,同时指定各路画面按屏幕分享模板排布。

设置云端混流参数如下:

  • CDN直播流ID:1400188366_3560_mix。
  • 录制文件名:1400188366_3560_mix_file。
  • CDN直播流视频参数:视频宽为1280、高为720,视频码率为1560kbps,视频帧率为15,gop为2秒。
  • CDN直播流音频参数:音频采样率为48kHz,音频码率为64kbps,音频声道数为双声道。
  • 各路画面按屏幕分享模板排布,占据屏幕左侧大画面的视频流为用户(main_pc)的屏幕分享。

输入示例

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

{
    "LayoutParams": {
        "MainVideoUserId": "main_pc",
        "Template": "2",
        "MainVideoStreamType": "1"
    },
    "EncodeParams": {
        "VideoFramerate": "15",
        "VideoGop": "2",
        "AudioBitrate": "64",
        "VideoBitrate": "1560",
        "AudioSampleRate": "48000",
        "AudioChannels": "2",
        "BackgroundColor": "0",
        "VideoWidth": "1280",
        "VideoHeight": "720"
    },
    "RoomId": "3560",
    "OutputParams": {
        "RecordId": "1400188366_3560_mix_file",
        "PureAudioStream": "0",
        "RecordAudioOnly": "0",
        "StreamId": "1400188366_3560_mix"
    },
    "SdkAppId": "1400188366"
}

输出示例

{
    "Response": {
        "RequestId": "eac6b301-a322-493a-8e36-83b295459397"
    }
}

5. 开发者资源

腾讯云 API 平台

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

API Inspector

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

SDK

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

命令行工具

6. 错误码

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

错误码 描述
FailedOperation 操作失败。
FailedOperation.RequestRejection 云API混流模板和SDK混流冲突。
FailedOperation.RoomNotExist 房间不存在。
FailedOperation.TaskFinished 调用接口时任务已结束。
InternalError 内部错误。
InternalError.GetRoomFromCacheError 获取房间信息失败。
InternalError.InternalError 内部错误,请重试。
InvalidParameter.AudioEncodeParams 音频编码参数错误。
InvalidParameter.BackgroundImageUrl BackgroundImageUrl参数错误。
InvalidParameter.EncodeParams EncodeParams参数错误。
InvalidParameter.MainVideoRightAlign 大画面居右显示参数错误。
InvalidParameter.MainVideoStreamType 大画面流类型错误。
InvalidParameter.OutputParams OutputParams参数错误。
InvalidParameter.PresetLayoutConfig 自定义布局参数错误。
InvalidParameter.PublishCdnUrls PublishCdnUrls参数校验失败。
InvalidParameter.PureAudioStream 纯音频推流参数错误。
InvalidParameter.RecordAudioOnly 纯音频录制参数错误。
InvalidParameter.RecordId RecordId参数错误。
InvalidParameter.RoomId RoomId参数错误。
InvalidParameter.SdkAppId SdkAppId参数错误。
InvalidParameter.SmallVideoLayoutParams 小画面布局参数错误。
InvalidParameter.SmallVideoStreamType 小画面布局中流类型参数错误。
InvalidParameter.StreamId StreamId参数错误。
InvalidParameter.VideoResolution 视频分辨率参数错误。
InvalidParameterValue.RoomId RoomId值错误。
MissingParameter.AudioEncodeParams EncodeParams中缺少音频输出参数。
MissingParameter.BizId 转推参数中缺少BizId。
MissingParameter.EncodeParams 缺少EncodeParams参数。
MissingParameter.OutputParams 缺少OutputParams参数。
MissingParameter.PresetLayoutConfig 缺少自定义布局参数。
MissingParameter.PublishCdnParams 缺少转推参数。
MissingParameter.PublishCdnUrls 转推参数中缺少转推目的地址。
MissingParameter.RoomId 缺少RoomId参数。
MissingParameter.SdkAppId 缺少SdkAppId参数。
MissingParameter.StreamId OutputParams中缺少StreamId参数。
MissingParameter.VideoEncodeParams EncodeParams中缺少视频输出参数。
ResourceInsufficient.RequestRejection 资源不足。
ResourceNotFound 资源不存在。
UnauthorizedOperation.SdkAppId 没有操作SdkAppId的权限。