Documentation
Documentation
Demo APP
Client APIs
Server APIs
FAQ
Console
Sign Up
Log In
中文站 English
Server APIs v2

Server APIs

  • Server APIs v2
  • Server APIs
Expand All
  • Server APIs overview
  • Accessing Server APIs
  • Room signaling
  • Stream mixing
  • Streaming moderation
  • Streaming control
  • Cloud recording
  • Server callbacks
  • Return codes
  • API testing

Start stream mixing

Last updated：2022-03-22 13:07

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.
  • 1: Enabled
  • 0: Disabled (by default)

    This parameter supports dynamic updates after the stream mixing starts.
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.
  • 1: Enabled
  • 0: Disabled (by default)
SoundChannel
String
No
The number of audio channels of the mixed stream. This configuration can be used when no output stream is specified.
  • 1: Mono (by default)
  • 2: Stereo
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:
  • Using URI: Provide the image to ZEGO Technical Support for configuration. Once the configuration is done, ZEGO Technical Support will provide you with the image URI, for example: "preset-id://xxx.jpg".
  • Using URLs: with this method, only HTTP protocol is supported. By default, the number of URLs allowed is 20. If you need to change the background image, we recommend you update the image file while keeping the file name (the same URL).

    This parameter supports dynamic updates after the stream mixing starts.
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.
  • 0: Use both audio and video (by default)
  • 2: Use video only.

    This parameter supports dynamic updates after the stream mixing starts.
└ 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.
  • 0: HE-AAC, sampling rate: 44100 KHz (the default value).
  • 1: LC-AAC, sampling rate: 44100 KHz.
  • 2: MP3, sampling rate: 44100 KHz.
  • 3: OPUS, sampling rate: 48000 KHz.
└ 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.
  • 1: Mono (the default value)
  • 2: Stereo
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

  1. The stream mixing configuration
  • Input stream 1:
    • Stream ID: test_bing1
    • Position: the left half of the output stream canvas.
  • Input stream 2:
    • Stream ID: test_bing2
    • Position: the right half of the output stream canvas.
  • 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
  1. 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)
  1. 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.
  • Free trial