StartMCUMixTranscode

Last updated: 2020-09-04 09:48:43

1. API Description

Domain name for API request: trtc.tencentcloudapi.com.

This API is used to enable On-Cloud MixTranscoding and specify the layout position of each channel of video image in the mixed video image.

There may be multiple channels of audio/video streams in a TRTC room. You can call this API to request the Tencent Cloud server to combine multiple channels of video images into one channel, specify the position of each channel, and mix the multiple channels of audio so as to output one channel of audio/video stream for easier recording and live streaming.

You can use this API to perform the following operations:

  • Set the image and audio quality parameters of the final live stream, including video resolution, video bitrate, video frame rate, and audio quality.
  • Set the image layout, i.e., positions of all channels of images. You only need to set the layout once when enabling On-Cloud MixTranscoding, and the layout engine will automatically arrange the video images in the configured layout in subsequent operations.
  • Set the recording file name for future playback.
  • Set the CDN live stream ID for live streaming over CDN.

Currently, the following layout templates are supported:

  • Floating template: the entire screen will be covered by the video image of the first user who enters the room, and the video images of other users will be displayed as small images in horizontal rows from the bottom-left corner in room entry sequence. The screen can contain up to 4 rows with 4 small images each row, which float over the big image. Up to 1 big image and 15 small images are supported. If a user sends audio only, the user will still use an image spot.
  • Grid template: the screen is divided into user video images with the same dimensions. The more the users, the smaller the image dimensions. Up to 16 images are supported. If a user sends audio only, the user will still use an image spot.
  • Screen sharing template: it is suitable for video conferencing and online education. The shared screen (or camera of the anchor) is always displayed in the big image on the left of the screen, and the video images of other users are vertically displayed on the right in up to 2 columns with up to 8 small images in each column. Up to 1 big image and 15 small images are supported. If width and height of the upstream image’s resolution don’t match those of the output image, the big image on the left will be scaled to display it as a whole, while the small images on the right will be cropped.
  • Picture-in-picture template: it is suitable for mixing a pair of big/small images or a big image with the audio of other users. The small image floats over the big image, and the users in the big/small images and the display position of the small image can be specified.

A maximum of 20 requests can be initiated per second for this API.

We recommend you to use API Explorer
Try it
API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

2. Input Parameters

The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

Parameter Name Required Type Description
Action Yes String Common parameter. The value used for this API: StartMCUMixTranscode.
Version Yes String Common parameter. The value used for this API: 2019-07-22.
Region Yes String Common parameter. For more information, please see the list of regions supported by the product.
SdkAppId Yes Integer SDKAppId of TRTC.
RoomId Yes Integer Room ID.
OutputParams Yes OutputParams On-Cloud MixTranscoding output control parameters.
EncodeParams Yes EncodeParams On-Cloud MixTranscoding output encoding parameters.
LayoutParams Yes LayoutParams On-Cloud MixTranscoding output layout parameters.

3. Output Parameters

Parameter Name Type Description
RequestId String The unique request ID, which is returned for each request. RequestId is required for locating a problem.

4. Example

Example1 Enabling On-Cloud MixTranscoding

This example shows you how to enable On-Cloud MixTranscoding for a specified room (ID: 3560) and specify the screen sharing template for the layout of each channel of video image.

Set the On-Cloud MixTranscoding parameters as follows:

  • CDN live stream ID: 1400188366_3560_mix.
  • Recording file name: 1400188366_3560_mix_file.
  • CDN live stream video parameters: set the video width to 1280, height to 720, bitrate to 1560 Kbps, frame rate to 15, and GOP to 2 seconds.
  • CDN live stream audio parameters: set the audio sample rate to 48 kHz, bitrate to 64 Kbps, and sound channel to dual-channel.
  • Each channel of video image is arranged according to the screen sharing template, and the video stream in the big image on the left of the screen is the video image shared by the main_pc user.

Input Example

https://trtc.tencentcloudapi.com/?Action=StartMCUMixTranscode
&SdkAppId=1400188366
&RoomId=3560
&OutputParams.StreamId=1400188366_3560_mix
&OutputParams.PureAudioStream=0
&OutputParams.RecordId=1400188366_3560_mix_file
&OutputParams.RecordAudioOnly=0
&EncodeParams.VideoWidth=1280
&EncodeParams.VideoHeight=720
&EncodeParams.VideoBitrate=1560
&EncodeParams.VideoFramerate=15
&EncodeParams.VideoGop=2
&EncodeParams.BackgroundColor=0
&EncodeParams.AudioSampleRate=48000
&EncodeParams.AudioBitrate=64
&EncodeParams.AudioChannels=2
&LayoutParams.Template=2
&LayoutParams.MainVideoUserId=main_pc
&LayoutParams.MainVideoStreamType=1
&<Common request parameters>

Output Example

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

5. Developer Resources

API Explorer

This tool allows online call, signature authentication, SDK code generation and quick search of APIs to greatly improve the efficiency of using TencentCloud APIs.

SDK

TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

Command Line Interface

6. Error Code

The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

Error Code Description
FailedOperation.RequestRejection The TencentCloud API On-Cloud MixTranscoding template conflicts with On-Cloud MixTranscoding settings in the SDK.
FailedOperation.RoomNotExist The room does not exist.
InternalError Internal error.
InvalidParameter.EncodeParams Invalid EncodeParams.
InvalidParameter.OutputParams Incorrect OutputParams parameter.
InvalidParameter.RecordId Incorrect RecordId parameter.
InvalidParameter.RoomId RoomId is incorrect.
InvalidParameter.SdkAppId SdkAppId is incorrect.
InvalidParameter.StreamId Incorrect StreamId parameter.
InvalidParameterValue.RoomId Invalid RoomId.
MissingParameter.AudioEncodeParams Audio output parameters are missing in EncodeParams.
MissingParameter.EncodeParams Missing EncodeParams parameter.
MissingParameter.OutputParams Missing OutputParams parameter.
MissingParameter.RoomId RoomId is missing.
MissingParameter.SdkAppId SdkAppId is missing.
MissingParameter.StreamId The StreamId parameter is missing in OutputParams.
MissingParameter.VideoEncodeParams Video output parameters are missing in EncodeParams.
UnauthorizedOperation.SdkAppId No permission to manipulate SdkAppId.

Was this page helpful?

Was this page helpful?

  • Not at all
  • Not very helpful
  • Somewhat helpful
  • Very helpful
  • Extremely helpful
Send Feedback
Help