tencent cloud

Feedback

StartPublishCdnStream

Last updated: 2022-07-04 11:02:14

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.

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 Params. The value used for this API: StartPublishCdnStream.
Version Yes String Common Params. The value used for this API: 2019-07-22.
Region Yes String Common Params. For more information, please see the list of regions supported by the product. This API only supports: ap-singapore
SdkAppId Yes Integer The SDKAppID of the TRTC room whose streams are relayed.
RoomId Yes String The ID of the room whose streams are relayed (the main room).
RoomIdType Yes Integer The type of the RoomId parameter, which must be the same as the ID type of the room whose streams are relayed. 0: integer; 1: string.
AgentParams Yes AgentParams The information of the relaying robot in the room.
WithTranscoding Yes Integer Whether to transcode the streams. 0: No; 1: Yes.
AudioParams No McuAudioParams The audio encoding parameters for relaying.
VideoParams No McuVideoParams The video encoding parameters for relaying. If you do not pass this parameter, only audio will be relayed.
SingleSubscribeParams No SingleSubscribeParams The information of a single stream relayed. When you relay a single stream, set WithTranscoding to 0.
PublishCdnParams.N No Array of McuPublishCdnParam The CDN information.

3. Output Parameters

Parameter Name Type Description
TaskId String The task ID, which is generated by the Tencent Cloud server. You need to pass in the task ID when making a request to update or stop a relaying task.
RequestId String The unique request ID, which is returned for each request. RequestId is required for locating a problem.

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.

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
AuthFailure CAM signature/authentication error.
AuthFailure.UnRealNameAuthenticated Identity verification has not been completed, so this operation is not allowed.
AuthFailure.UnauthorizedOperation CAM authentication failed.
AuthFailure.UnsupportedOperation Unsupported operation.
FailedOperation Operation failed.
FailedOperation.CRUnsupportMethod Unsupported on-cloud recording method.
FailedOperation.RestrictedConcurrency Maximum number of concurrent on-cloud recording tasks reached. Contact us to raise the limit.
InternalError Internal error.
InternalError.CRInternalError On-cloud recording internal error.
InvalidParameter Parameter error.
MissingParameter Missing parameter.
Contact Us

Contact our sales team or business advisors to help your business.

Technical Support

Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

7x24 Phone Support