Start stream mixing
1 Description
Starts or updates a stream mixing task.
For more information about the stream mixing feature, see Stream mixing.
For callbacks related to stream mixing, see Callback on stream mixing started and Callback on stream mixing ended.
Before using this interface for the first time, you need to contact ZEGO technical support to activate it.
2 Request method and endpoint
- Request method: POST/JSON
- Request endpoint: https://rtc-api.zego.im/?Action=StartMix
- Protocol: HTTPS
- Rate limit: 100 requests/second
3 Request parameters
Listed below are the parameters specific to this request and part of the public request parameters. For the complete list of public request parameters, see Server APIs public request parameters.
Only some parameters in this API support dynamic updates after the stream mixing starts. For details, refer to the description in the following table.
In the testing environment (For details, see the description of the isTest
parameter in Accessing server APIs - Public request parameters), the stream IDs need to be prefixed with zegotest-AppId-
. For example, if the unique part of the stream ID is test
and the AppID is 123456789
, then the full stream ID should be zegotest-123456789-test
.
Name | Type | Required | Description |
---|---|---|---|
TaskId |
String |
Yes |
Task ID, the unique identifier of a stream mixing task, which can be used to update a stream mixing task or determine whether a stream mixing task is newly added. |
Sequence |
Int |
Yes |
The sequence number of the stream mixing request, which is used to ensure the sequence of task operations. Requests must be sent with ascending sequence numbers. |
UserId |
String |
Yes |
User ID. The user ID of the operations on the same stream mixing task must be consistent. The user ID can be used as an identifier of the task owner, which means only the user with this user ID can update or stop the task. To use this feature, contact ZEGO technical support to enable it first. |
RoomId |
String |
No |
Room ID. |
UserData |
String |
No |
User data. On the client side, this custom-defined data is received through the callback onPlayerRecvSEI. The data length must be in the range of [1, 1000] bytes, and the recommended length is 850 bytes or less. You can update the user data in real time while the stream mixing task is running. This parameter supports dynamic updates after the stream mixing starts. |
SoundLevel |
Int |
No |
The sound level of the mixed stream. You can update this sound level value in real time while the stream mixing task is running.
|
ByPass |
Int |
No |
Switch of the single-stream passthrough feature. This switch controls whether to recode the stream according to the output settings when there is only one input stream. To use this feature, contact ZEGO technical support to enable it first.
|
SoundChannel |
String |
No |
The number of audio channels of the mixed stream. This configuration can be used when no output stream is specified.
|
BackgroundImage |
String |
No |
Background image of the mixed stream. You can use images in JPG and PNG formats as the background images and set up the background image using either one of these methods:
|
BackgroundColor |
Int64 |
No |
The background color of the mixed streams. The color value requires some handling before it is passed in. For example: for color to white, the corresponding hexadecimal RGB color code is "#FFFFFF", and you need to remove the "#" and add "00" at the end to get "FFFFFF00". Finally, convert "FFFFFF00" to a decimal value "4294967040", which is the color value to be used to set the background color to white. This parameter supports dynamic updates after the stream mixing starts. |
MixInput |
Array of Object |
Yes |
Input streams. By default, a stream mixing task can have up to 9 input streams. If you need to have more input streams, contact ZEGO Technical Support for assistance. |
└ StreamId |
String |
Yes |
Stream ID of the input stream. If an input stream has a stream ID, it comes from the ZEGO RTC service. |
└ StreamUrl |
String |
Yes |
URL of the input stream, which must be an RTMP or HTTP-FLV URL. You can use either StreamID or StreamUrl to specify an input stream. If StreamUrl is specified, StreamId doesn't take effect. |
└ ContentControl |
Int |
No |
Content control.
|
└ SoundLevelId |
Int |
Yes |
ID of the input stream's sound level data. |
└ RectInfo |
Object |
Yes |
Position information of the input stream. |
└ Layer |
Int |
No |
Picture layer level. 0 represents the lowest level. The higher the value, the higher the level. This parameter supports dynamic updates after the stream mixing starts. |
└ Top |
Int |
No |
Position of this input stream's top border. Pixel distance from the top border of the output stream's canvas. This parameter supports dynamic updates after the stream mixing starts. |
└ Left |
Int |
No |
Position of this input stream's left border. Pixel distance from the left border of the output stream's canvas. This parameter supports dynamic updates after the stream mixing starts. |
└ Bottom |
Int |
No |
Position of this input stream's bottom border. Pixel distance from the bottom border of the output stream's canvas. This parameter supports dynamic updates after the stream mixing starts. |
└ Right |
Int |
No |
Position of this input stream's right border. Pixel distance from the right border of the output stream's canvas. This parameter supports dynamic updates after the stream mixing starts. |
WaterMark |
Object |
No |
Watermark configuration. |
└ Image |
String |
No |
Watermark image. You can use images in JPG and PNG formats as watermark images and set up the watermark image the same way as you do for BackgroundImage. This parameter supports dynamic updates after the stream mixing starts. |
└ RectInfo |
Object |
No |
Position information of the watermark. This parameter supports dynamic updates after the stream mixing starts. |
└ Top |
Int |
No |
Position of the watermark's top border. Pixel distance from the top border of the output stream's canvas. |
└ Left |
Int |
No |
Position of the watermark's left border. Pixel distance from the left border of the output stream's canvas. |
└ Bottom |
Int |
No |
Position of the watermark's bottom border. Pixel distance from the bottom border of the output stream's canvas. |
└ Right |
Int |
No |
Position of the watermark's right border. Pixel distance from the right border of the output stream's canvas. |
MixOutput |
Array of Object |
Yes |
Output streams. A stream mixing task can have up to 3 mixing outputs. |
└ StreamId |
String |
Yes |
Stream ID of the output stream. By default, the mixed streams are sent to ZEGO's RTC servers or ZEGO's low-latency live streaming servers. You can also contact ZEGO Technical Support to configure the system to send the outputs to the CDNs supported by ZEGO, which will be applied to all mixing outputs in the entire scope of your AppID. If you want to specify the CDN destination for individual output streams, you must specify the streamURL accordingly instead. |
└ StreamUrl |
String |
Yes |
The destination URL of the output stream, which must be an RTMP URL. Users can receive and play the mixed stream directly from this URL. You can use either StreamId or StreamUrl to specify an output stream. If StreamUrl is specified, StreamId doesn't take effect. |
└ VideoBitrate |
Int |
Yes |
Video bitrate (bps) of the output stream. When mixing audio-only streams, set this value to 1. You can update this value in real time while the stream mixing task is running. This parameter supports dynamic updates after the stream mixing starts. |
└ Fps |
Int |
Yes |
Video frame rate. |
└ Width |
Int |
Yes |
Video frame Width of the output stream. This value must be in the range [0, 3000] and must be a multiple of 2. When mixing audio-only streams, set this value to 1. You can update this value in real time while the stream mixing task is running. This parameter supports dynamic updates after the stream mixing starts. |
└ Height |
Int |
Yes |
Video frame height of the output stream. This value must be in the range [0, 3000] and must be a multiple of 2. When mixing audio-only streams, set this value to 1. You can update this value in real time while the stream mixing task is running. This parameter supports dynamic updates after the stream mixing starts. |
└ AudioCodec |
Int |
No |
Audio coding format and sampling rate of the output stream. To modify the sampling rate, please contact ZEGO Technical Support.
|
└ AudioBitrate |
Int |
NO |
Audio bitrate of the output stream. The default value is 48000 bps. |
└ SoundChannel |
Int |
No |
The number of audio channels of the output stream, which takes precedence over the global parameter.
|
ExPara |
Array of Object |
No |
Extension parameters, which can be specified according to the actual situation. For regular mixing tasks, you can skip this parameter. |
└ Key |
String |
No |
The Key of the parameter (key-value pair). |
└ Value |
String |
No |
The Key of the parameter (key-value pair). |
4 Sample request
4.1 A sample URL request
https://rtc-api.zego.im/?Action=StartMix
&AppId=1234567890
&SignatureNonce=15215528852396
&Timestamp=1234567890
&Signature=7a2c0f11145fb760d607a07b54825013
&SignatureVersion=2.0
&IsTest=false
4.2 A sample request with all of the business parameters
{
'TaskId': '2213699902971205739',
'Sequence': 1,
'UserId': '123',
'RoomId': '321',
'UserData': 'DoraTest',
'SoundLevel': 1,
'BackgroundImage': 'http://47.101.46.7:8090/no_camera_icon.png',
'BackgroundColor': 4294967040,
'ByPass': 1,
'MixInput': [{
'StreamId': 'input5',
'StreamUrl': 'rtmp://ip/appname/streamid',
'SoundLevelId': 0,
'ContentControl': 2,
'RectInfo': { # The input stream's position in the canvas of the output stream.
'Layer': 0,
'Top': 0,
'Left': 0,
'Bottom': 650,
'Right': 380
# The origin of the cordinates is the upper-left corner. The top/bottom/left/right parameters are defined as follows:
#
# (left, top)-----------------------
# | |
# | |
# | |
# | |
# -------------------(right, bottom)
}
}
],
'WaterMark': {
'Image': 'http://47.101.46.7:8090/no_camera_icon.png',
'RectInfo': { # The watermark's position in the canvas of the output stream.
'Top': 0,
'Left': 0,
'Bottom': 200,
'Right': 150
# The origin of the cordinates is the upper-left corner. The top/bottom/left/right parameters are defined as follows:
#
# (left, top)-----------------------
# | |
# | |
# | |
# | |
# -------------------(right, bottom)
}
},
'MixOutput': [{
'StreamId': 'test',
#'StreamUrl': 'rtmp://ip/appname/streamid',
'VideoBitrate': 1200000,
'Fps': 15,
'Width': 1280,
'Height': 1080,
'AudioCodec': 0,
'AudioBitrate': 48000,
'SoundChannel': 2,
},
{
#'StreamId': 'test',
'StreamUrl': 'rtmp://domian/appname/test',
'VideoBitrate': 1200000,
'Fps': 18,
'Width': 1280,
'Height': 1080
}
],
#'ExPara': extension parameters (in JSON format). For example, you can use this parameter to set the video_encode/sei_mode, demonstrated as below.
'ExPara': [
{
"Key": "video_encode",
"Value": "vp8"
},
{
"Key": "sei_mode",
"Value": "1"
},
{
"Key": "mixowner_userid",
"Value": "[\"456\"]"
}
]
}
4.3 A sample request with part of the business parameters
- The stream mixing configuration
- Input stream 1:
- Stream ID:
test_bing1
- Position: the left half of the output stream canvas.
- Stream ID:
- Input stream 2:
- Stream ID:
test_bing2
- Position: the right half of the output stream canvas.
- Stream ID:
- The output stream:
- Stream ID:
test_mix_bing
- Video frame rate: 15 fps
- Video resolution: 640*480
- Video bitrate: 1200000 bps
- Audio bitrate: 48000 bps
- Stream ID:
- The layout of the output stream canvas
The origin is the upper-left corner. The top/bottom/left/right parameters of the input streams are defined as follows:
(0,0)---------(320,0)-----------------
| | |
| | |
| | |
| test_bing1 | test_bing2 |
| | |
| | |
| | |
-------------(320,480)--------(640,480)
- Sample parameters
{
"Sequence": 2,
"UserId": "admin",
"MixInput": [
{
"RectInfo": {
"Bottom": 480,
"Layer": 0,
"Left": 0,
"Right": 320,
"Top": 0
},
"SoundLevelId": 1,
"StreamId": "test_bing1"
},
{
"RectInfo": {
"Bottom": 480,
"Layer": 0,
"Left": 320,
"Right": 640,
"Top": 0
},
"SoundLevelId": 2,
"StreamId": "test_bing2"
}
],
"MixOutput": [
{
"Fps": 15,
"Width": 640,
"Height": 480,
"StreamId": "test_mix_bing",
"VideoBitrate": 1200
}
]
}
5 Response parameters
Parameter | Type | Description |
---|---|---|
Code |
Number |
Return code. |
Message |
String |
Description of the request execution result. |
RequestId |
String |
Request ID. |
Data |
Array of Object |
Returned data. |
└ UserId |
String |
User ID. |
└ Sequence |
Int |
Serial number. |
└ RoomId |
String |
Room ID. |
└ PlayInfo |
Array of Object |
Playback information of the mixed stream. |
└ StreamId |
String |
Stream ID. |
└ RTMP |
String |
The CDN URL for playback using the RTMP protocol (if the output destination is configured as a CDN URL for RTMP streaming). |
└ HLS |
String |
The CDN URL for playback using the HLS protocol (if the output destination is configured as a CDN URL for HLS streaming). |
└ FLV |
String |
The CDN URL for playback using the HTTP-FLV protocol (if the output destination is configured as a CDN URL for HTTP-FLV streaming). |
6 Sample response
{
"Code": 0,
"Data": {
"PlayInfo": [
{
"FLV": "http://domain/appname/test.flv",
"HLS": "http://domain/appname/test/playlist.m3u8",
"RTMP": "rtmp://domain/appname/test",
"Status": 0,
"StreamId": "test",
"UserName": ""
}
],
"RoomId": "",
"Sequence": 2,
"UserId": "admin"
},
"Message": "success",
"RequestId": "8472822294336370476"
}
7 Return codes
Listed below are the return codes related to this API. For the complete list of return codes, see Return codes.
Return code | Description |
---|---|
110200001 | Failed. |
110200002 | Input error. |
110200003 | Authentication failed. |
110200004 | Failed to parse the input parameter. |
110200005 | Failed to obtain distributed locks when starting the stream mixing. |
110200006 | Failed to obtain distributed locks when stoping the stream mixing. |
110200007 | Failed to update the stream mixing request. |
110200008 | Failed to transfer protocol when stream mixing started. |
110200009 | Failed to forward the request to start stream mixing. |
110200010 | Callback on stream mixing started failed. |
110200011 | Failed to bypass data when starting stream mixing. |
110200012 | Failed to close the other stream mixing tasks of the task owner. |
110200013 | Failed to bind the ownership between the user and the stream mixing task. |
110200014 | Failed to transfer protocol when stream mixing ended. |
110200015 | Failed to forward the request to stop stream mixing. |
110200016 | Callback on stream mixing ended failed. |
110200017 | Failed to clean the stream mixing status info. |
110200103 | SEQ error. |
110200150 | Input stream of the stream mixing task does not exist. |
110200151 | Stream mixing failed. |
110200152 | Failed to stop stream mixing. |
110200153 | Input stream error. |
110200154 | Output stream error. |
110200155 | Input stream format error. |
110200156 | Output stream format error. |
110200157 | Permission of stream mixing is not enabled. |
110200158 | The number of input streams has exceeded the limit. |
110200159 | Failed to dispatch stream mixing. |
110200160 | The stream mixing is stopped by a non-owner user of the stream mixing task. |
110200170 | Watermark parameter error. |
110200171 | Watermark parameter is empty. |
110200172 | Extended parameter error. |
110200173 | The number of background images has exceeded the limit. |
110200174 | The number of watermarks has exceeded the limit. |
110200175 | Input stream repeated. |
110200176 | Output stream repeated. |
110200177 | The number of focused audio streams has exceeded the limit. |
110200178 | The number of output streams has exceeded the limit. |
110200180 | The token for starting stream mixing is empty. |
110200181 | The token for starting stream mixing is invalid. |
110200182 | The token for stoping stream mixing is empty. |
110200183 | The token for stoping stream mixing is invalid. |
110200184 | Failed to parse parameters when starting stream mixing. |
110200185 | Failed to parse parameters when stoping stream mixing. |
110200190 | Request to start stream mixing overload. |
110200191 | Request to stop stream mixing overload. |
110200192 | Request to search stream mixing tasks overload. |
110200193 | Request to search stream mixing task overload. |
110200194 | Stream mixing request overload. |
110240002 | Token is invalid. |
110240003 | AppId is empty. |
110240004 | AppId is incorrect. |
110200901 | The parameter of the LiveRoom stream mixing command is empty. |
110200902 | The parameter of the LiveRoom stream mixing command does not exist. |
110208000 | Error occurred while forwarding the mixed stream. |
110208001 | Decoding error occurred while forwarding the mixed stream. |
110208002 | The address for forwarding the mixed stream is not configured. |
110208003 | Request to forward the mixed stream overload. |
110208004 | Error occurred while forwarding mixed stream. |
- 1 1 Description
- 2 2 Request method and endpoint
- 3 3 Request parameters
- 4 4 Sample request
- 4.1 4.1 A sample URL request
- 4.2 4.2 A sample request with all of the business parameters
- 4.3 4.3 A sample request with part of the business parameters
- 5 5 Response parameters
- 6 6 Sample response
- 7 7 Return codes