tencent cloud

1. API Description

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

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

There may be multiple audio/video streams in a TRTC room. You can call this API to request the Tencent Cloud server to mix the audio and video and specify the position of each image to produce just one audio/video stream for recording and playback. The mixing stops automatically after a room is terminated.

You can use this API to perform the following operations:

• Set image and audio quality parameters of the final live stream, including video resolution, video bitrate, video frame rate, and audio quality.
• Set the layout, i.e., the position of each image. You only need to set it once when enabling On-Cloud MixTranscoding, and the layout engine will automatically arrange images as configured.
• Set the names of recording files for future playback.
• Set the stream ID for CDN live streaming.

Currently, On-Cloud MixTranscoding supports the following layout templates:

• Floating: The entire screen is covered by the video image of the first user who enters the room, and the images of other users are displayed as small images in rows in the bottom-left corner in room entry sequence. The screen allows up to 4 rows of 4 small images, which float over the big image. Up to 1 big image and 15 small images can be displayed. A user sending audio only will still occupy an image spot.
• Grid: The images of all users split the entire screen evenly. The more users, the smaller the image dimensions. Up to 16 images can be displayed. A user sending audio only will still occupy an image spot.
• Screen sharing: This is designed for video conferencing and online education. The shared screen (or camera image of the anchor) is always displayed as the big image, which occupies the left half of the screen, and the images of other users occupy the right half in up to 2 columns of up to 8 small images each. Up to 1 big image and 15 small images can be displayed. If the upstream aspect ratio does not match the output, the big image on the left will be scaled and displayed in whole, while the small images on the right will be cropped.
• Picture-in-picture: This template mixes the big and small images or big image of a user with the audio of other users. The small image floats over the big image. You can specify the user whose small and big images are displayed, as well as the position of the small image. This template can display at most 2 images.
• Custom: This is designed for cases where you want to specify the image positions of users in the mixed stream or preset image positions. If users are assigned to preset positions, the layout engine will reserve the positions for the users; if not, users will occupy the positions in room entry sequence. Once all preset positions are occupied, TRTC will stop mixing the audio and video of other users. If the place-holding feature is enabled for a custom template (by setting PlaceHolderMode in LayoutParams to 1) and a user for whom a place is held is not sending video, the position will show the specified placeholder image (PlaceImageId).

Notes:

1. **As On-Cloud MixTranscoding is a paid feature, you will be charged for calling this API.
2. You can call this API only if your application is created on or after January 9, 2020. Applications created before use the stream mixing service of CSS by default. If you want to switch to MCU On-Cloud MixTranscoding, please submit a ticket.
3. You cannot use the server and client stream mixing APIs at the same time.

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

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.

3. Output Parameters

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 image layout.

The On-Cloud MixTranscoding parameters are as follows:

• CDN live stream ID: 1400188366_3560_mix
• Recording file name: 1400188366_3560_mix_file
• Video parameters for CDN live stream: aspect ratio: 1280 x 720; bitrate: 1560 Kbps; frame rate: 15 FPS; GOP: 2 seconds
• Audio parameters for CDN live stream: audio sample rate: 48 kHz; bitrate: 64 Kbps; sound channel: dual
• Layout template: screen sharing. The screen sharing image of user main_pc occupies the left side of the screen as the big image.

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

SDK

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

• Tencent Cloud SDK 3.0 for Python
• Tencent Cloud SDK 3.0 for Java
• Tencent Cloud SDK 3.0 for PHP
• Tencent Cloud SDK 3.0 for Go
• Tencent Cloud SDK 3.0 for NodeJS
• Tencent Cloud SDK 3.0 for .NET
• Tencent Cloud SDK 3.0 for C++

Command Line Interface

• Tencent Cloud CLI 3.0

6. Error Code

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