International
中国站
Console
PrevNext
search by keyword

Recent Pages

Documentation
Documentation

StartMCUMixTranscode

Last updated: 2021-01-26 14:43:05

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 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 and audio into one channel and specify the position of each image so as to produce just one channel of audio/video stream for recording and live streaming. The mixing stops automatically after a room is destroyed.

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 channel of 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 horizontal rows in the bottom-left corner in room entry sequence. The screen can accommodate 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 the users split the entire screen evenly. The more the 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 (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 aspect ratio of upstream images do not match that of output images, 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 is designed for mixing the dual-channel (small and big) image or big image with the audio of other users. The small images float over the big image. You can specify which users to be displayed as the big/small images as well as the positions of the small images. Up to 2 images are supported.
  • 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 images of other users. If the placeholding feature is enabled for a custom template (PlaceHolderMode in LayoutParams set to 1), but a user for whom a place is reserved is not sending video data, the position will show the corresponding placeholder image (PlaceImageId).

Note: only applications created on and after January 9, 2020 can call this API directly. Applications created before use the stream mixing service of LVB by default. If you want to switch to MCU On-Cloud MixTranscoding, please submit a ticket.

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.
PublishCdnParams No PublishCdnParams Relayed push parameters of a non-Tencent Cloud CDN

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 user main_pc.

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.

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.AudioEncodeParams Invalid audio codec parameter.
InvalidParameter.EncodeParams Invalid EncodeParams.
InvalidParameter.MainVideoStreamType Invalid stream type of the big image.
InvalidParameter.OutputParams Incorrect OutputParams parameter.
InvalidParameter.PresetLayoutConfig Incorrect parameters for custom layout.
InvalidParameter.PureAudioStream Incorrect parameters for audio-only stream pushing.
InvalidParameter.RecordAudioOnly Incorrect parameters for audio-only recording.
InvalidParameter.RecordId Incorrect RecordId parameter.
InvalidParameter.RoomId RoomId is incorrect.
InvalidParameter.SdkAppId SdkAppId is incorrect.
InvalidParameter.SmallVideoLayoutParams Invalid small image layout parameter.
InvalidParameter.StreamId Incorrect StreamId parameter.
InvalidParameterValue.RoomId Invalid RoomId.
MissingParameter.AudioEncodeParams Audio output parameters are missing in EncodeParams.
MissingParameter.BizId BizId missing in relayed push parameters.
MissingParameter.EncodeParams Missing EncodeParams parameter.
MissingParameter.OutputParams Missing OutputParams parameter.
MissingParameter.PresetLayoutConfig Custom layout parameter missing.
MissingParameter.PublishCdnUrls Destination missing in relayed push parameters.
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?

Confirm

Was this page helpful?

  • Not at all
  • Not very helpful
  • Somewhat helpful
  • Very helpful
  • Extremely helpful
Send Feedback
Hide
Submit a TicketContact Us
Help
tencent
Copyright © 2013-2021 Tencent Cloud. All Rights Reserved.
Privacy PolicyTerms of ServiceCookie Policy