tencent cloud

1. API Description

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

This API is used to start a relaying task.

1. To ensure the stability of relaying, you cannot switch between relaying audio only, relaying audio and video, and relaying video only for the same task.
2. To ensure the stability of relaying, you cannot change the video codec, audio codec, sample rate, or number of sound channels during relay.
3. The StartPublishCdnStream API will return a task ID, which uniquely identifies a relaying task. You need to pass this task ID when making a request to change the relaying parameters or stop the relaying task.
4. When you relay a single stream, specify both AudioParams and VideoParams to publish both audio and video, and specify only AudioParams to publish audio only. You cannot switch between the two modes during the relaying process. For VideoParams, set Width, Height, Fps, Bitrate, and Gop according to the actual settings used for publishing.
5. When you make a request to change the relaying parameters, set AudioParams.SubscribeAudioList to specify the audios to mix and set VideoParams.LayoutParams to specify the video layout.
6. The SequenceNumber parameter is required when you make a request to change the relaying parameters. It ensures that multiple requests for the same relaying task are in the correct order. The value of SequenceNumber increases each time a new request is made for the same task. If InternalError is returned, try again using the same SequenceNumber. You don’t need to handle the FailedOperation.OutdateRequest error.
7. In a request to change the relaying parameters, it is OK to pass only the parameters you want to change, but the value of each parameter you pass must be complete.
   For example, to change the destination URLs, you only need to pass PublishCdnParams plus the required parameters of the UpdatePublishCdnStream API, but make sure PublishCdnParams includes all the URLs you want to relay to.
   Pass the following parameters to change different relaying parameters:
   a. WithTranscoding: Pass this parameter to switch from not transcoding to transcoding (this parameter is required).
   b. AudioParams.UserInfoList: Pass this parameter to change the users whose audios you want to mix.
   c. VideoParams.VideoEncode: Pass this parameter to change video parameters other than the codec, including the output resolution, bitrate, frame rate, and GOP. This parameter is valid only if streams are transcoded.
   d. LayoutParams: Pass this parameter to change the video layout. This parameter is valid only if streams are transcoded.
   e. BackGroundColor and BackgroundImageUrl: Pass these two parameters to change the background image and color. They are valid only when streams are transcoded.
   f. WaterMarkList: Pass this parameter to change the watermarks. This parameter is valid only if streams are transcoded.
   g. PublishCdnParams: Pass this parameter to change the destination URLs.
8. You can create a relaying task even when there are no anchors in the room, but make sure you manually stop the task when relaying is finished. If you don’t, after all the users whose streams are mixed leave the room, the TRTC backend will wait for the timeout period to elapse before stopping the relaying task.
9. You can specify at most 10 destination URLs for each relaying task.
10. When making a request to switch from not transcoding to transcoding, you need to specify all the parameters of the relaying task.

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 Starting a task to mix streams and relay the result

Input Example

POST / HTTP/1.1
Host: trtc.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: StartPublishCdnStream
<Common request parameters>

{
    "AudioParams": {
        "SubscribeAudioList": [
            {
                "UserInfo": {
                    "RoomIdType": 0,
                    "RoomId": "195044",
                    "UserId": "Trtc_User_0"
                }
            },
            {
                "UserInfo": {
                    "RoomIdType": 0,
                    "RoomId": "195044",
                    "UserId": "Trtc_User_1"
                }
            },
            {
                "UserInfo": {
                    "RoomIdType": 0,
                    "RoomId": "195044",
                    "UserId": "Trtc_User_2"
                }
            },
            {
                "UserInfo": {
                    "RoomIdType": 0,
                    "RoomId": "195044",
                    "UserId": "Trtc_User_3"
                }
            }
        ],
        "AudioEncode": {
            "SampleRate": 48000,
            "Codec": 0,
            "BitRate": 64,
            "Channel": 2
        }
    },
    "AgentParams": {
        "MaxIdleTime": 30,
        "UserSig": "eJw1zV8LgjAUBfCvInsO2dStGfQSQUb2pFJvsnLJJZW1LekPffdc6X08v8O5b5Snmd9LjRYeCnyMZt4vgUp2Fi7wB6vtuVRC207q0kpjSzIVTXUVSkE11EiEMeE8ZGw0*VCg5SCcDeRuBAutiwkLeRRwOo*nMajduy5O*gIaus9qel9vX*lJbHJmyDMxuKFFI27tsT*I1S6pl*jzBb*IOTE_",
        "UserId": "trtc_partner_test_1"
    },
    "VideoParams": {
        "VideoEncode": {
            "Height": 720,
            "Width": 1280,
            "Fps": 15,
            "BitRate": 512,
            "Gop": 2
        },
        "LayoutParams": {
            "PureAudioHoldPlaceMode": 0,
            "MixLayoutMode": 4,
            "MixLayoutList": [
                {
                    "LocationX": 0,
                    "LocationY": 0,
                    "UserMediaStream": {
                        "StreamType": 0,
                        "UserInfo": {
                            "RoomIdType": 0,
                            "RoomId": "195044",
                            "UserId": "Trtc_User_0"
                        }
                    },
                    "ZOrder": 0,
                    "ImageHeight": 360,
                    "ImageWidth": 640,
                    "RenderMode": 0
                },
                {
                    "LocationX": 640,
                    "LocationY": 0,
                    "UserMediaStream": {
                        "StreamType": 0,
                        "UserInfo": {
                            "RoomIdType": 0,
                            "RoomId": "195044",
                            "UserId": "Trtc_User_1"
                        }
                    },
                    "ZOrder": 0,
                    "ImageHeight": 360,
                    "ImageWidth": 640,
                    "RenderMode": 0
                },
                {
                    "LocationX": 0,
                    "LocationY": 360,
                    "UserMediaStream": {
                        "StreamType": 0,
                        "UserInfo": {
                            "RoomIdType": 0,
                            "RoomId": "195044",
                            "UserId": "Trtc_User_2"
                        }
                    },
                    "ZOrder": 0,
                    "ImageHeight": 360,
                    "ImageWidth": 640,
                    "RenderMode": 0
                },
                {
                    "LocationX": 640,
                    "LocationY": 360,
                    "UserMediaStream": {
                        "StreamType": 0,
                        "UserInfo": {
                            "RoomIdType": 0,
                            "RoomId": "195044",
                            "UserId": "Trtc_User_3"
                        }
                    },
                    "ZOrder": 0,
                    "ImageHeight": 360,
                    "ImageWidth": 640,
                    "RenderMode": 0
                }
            ]
        },
        "BackGroundColor": "0xFF0000",
        "WaterMarkList": [
            {
                "WaterMarkImage": {
                    "LocationX": 64,
                    "LocationY": 64,
                    "WaterMarkHeight": 64,
                    "WaterMarkWidth": 64,
                    "WaterMarkUrl": "https://xkt-course-1304449343.cos.ap-beijing.myqcloud.com/test/mark/37f9eb62-ca72-430e-bfca-e700b59b20e0.png",
                    "ZOrder": 3
                }
            }
        ]
    },
    "PublishCdnParams": [
        {
            "PublishCdnUrl": "rtmp://3891.livepush.myqcloud.com/live/trtc_publishcdn_test1",
            "IsTencentCdn": 0
        },
        {
            "PublishCdnUrl": "rtmp://3891.livepush.myqcloud.com/live/trtc_publishcdn_test2",
            "IsTencentCdn": 0
        }
    ],
    "RoomIdType": 0,
    "SdkAppId": 1400188366,
    "WithTranscoding": 1,
    "RoomId": "195044"
}

Output Example

{
  "Response": {
    "TaskId": "-m97l2ZU7vxyBSmXYsRx1Xy9Kf4bVVfbbhSKC4K-4pycoZWKv542xbi139uTvGt1zAHoAQ..",
    "RequestId": "b934c535-8d82-4f52-bd52-a1cbb043c4be"
  }
}

Example2 Starting a task to relay the audio and video of a stream

Input Example

POST / HTTP/1.1
Host: trtc.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: StartPublishCdnStream
<Common request parameters>

{
    "AudioParams": {
        "AudioEncode": {
            "SampleRate": 48000,
            "Codec": 0,
            "BitRate": 64,
            "Channel": 2
        }
    },
    "AgentParams": {
        "MaxIdleTime": 30,
        "UserSig": "eJw1zV8LgjAUBfCvInsO2dStGfQSQUb2pFJvsnLJJZW1LekPffdc6X08v8O5b5Snmd9LjRYeCnyMZt4vgUp2Fi7wB6vtuVRC207q0kpjSzIVTXUVSkE11EiEMeE8ZGw0*VCg5SCcDeRuBAutiwkLeRRwOo*nMajduy5O*gIaus9qel9vX*lJbHJmyDMxuKFFI27tsT*I1S6pl*jzBb*IOTE_",
        "UserId": "trtc_partner_test_1"
    },
    "VideoParams": {
        "VideoEncode": {
            "Height": 720,
            "Width": 1280,
            "Fps": 15,
            "BitRate": 512,
            "Gop": 2
        }
    },
    "SingleSubscribeParams": {
        "UserMediaStream": {
            "StreamType": 0,
            "UserInfo": {
                "RoomIdType": 0,
                "RoomId": "195044",
                "UserId": "Trtc_User_0"
            }
        }
    },
    "PublishCdnParams": [
        {
            "PublishCdnUrl": "rtmp://3891.livepush.myqcloud.com/live/trtc_publishcdn_test1",
            "IsTencentCdn": 0
        }
    ],
    "RoomIdType": 0,
    "SdkAppId": 1400188366,
    "WithTranscoding": 0,
    "RoomId": "195044"
}

Output Example

{
  "Response": {
    "TaskId": "-m97l2ZU7tq6nEsHR89259B8aCDblqnbGhWKC4K-4pycoZWpyHnld1jC9aCD+EU7V8WRAQ..",
    "RequestId": "f23d95bf-ddaf-4d0c-86c0-6bf50c74c0a0"
  }
}

Example3 Starting a task to relay only the audio of a stream

Input Example

POST / HTTP/1.1
Host: trtc.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: StartPublishCdnStream
<Common request parameters>

{
    "AudioParams": {
        "AudioEncode": {
            "SampleRate": 48000,
            "Codec": 0,
            "BitRate": 64,
            "Channel": 2
        }
    },
    "AgentParams": {
        "MaxIdleTime": 30,
        "UserSig": "eJw1zV8LgjAUBfCvInsO2dStGfQSQUb2pFJvsnLJJZW1LekPffdc6X08v8O5b5Snmd9LjRYeCnyMZt4vgUp2Fi7wB6vtuVRC207q0kpjSzIVTXUVSkE11EiEMeE8ZGw0*VCg5SCcDeRuBAutiwkLeRRwOo*nMajduy5O*gIaus9qel9vX*lJbHJmyDMxuKFFI27tsT*I1S6pl*jzBb*IOTE_",
        "UserId": "trtc_partner_test_1"
    },
    "SingleSubscribeParams": {
        "UserMediaStream": {
            "StreamType": 0,
            "UserInfo": {
                "RoomIdType": 0,
                "RoomId": "195044",
                "UserId": "Trtc_User_0"
            }
        }
    },
    "PublishCdnParams": [
        {
            "PublishCdnUrl": "rtmp://3891.livepush.myqcloud.com/live/trtc_publishcdn_test1",
            "IsTencentCdn": 0
        }
    ],
    "RoomIdType": 0,
    "SdkAppId": 1400188366,
    "WithTranscoding": 0,
    "RoomId": "195044"
}

Output Example

{
  "Response": {
    "TaskId": "-m97l2ZU7r57nZBesMa84KgzxhH0OBbbCRaKC4K-4pycoZW7yFPtusNuZOen1Ca0qtQQAQ..",
    "RequestId": "ef089f8b-d0d1-4131-894d-4edd68d61605"
  }
}

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.