StartAutoMix

POST

https://rtc-api.zego.im/

This document describes how to call the server-side API to specify a Room and automatically mix all audio Streams in the Room. It can be applied to scenarios such as voice chat rooms, chorus, etc.

In cross-room PK connection scenarios, it supports adding a Stream from another Room to participate in automatic Stream Mixing; or removing a Stream from the current Room to not participate in automatic Stream Mixing. For details, please refer to the ExtraMixInput parameter description in the request parameters.

Note

Currently only supports automatic mixing of audio Streams.
When Streams are added or removed in the Room later, you don't need to do any processing. ZEGOCLOUD server automatically updates Stream Mixing internally.

For the Stream Mixing function of the "client", please refer to Stream Mixing - Auto Stream Mixing; for related "server" callbacks, please refer to Stream Mixing Started Callback and Stream Mixing Stopped Callback.

Prerequisites

Before implementing Stream Mixing, please ensure:

You have created a project in the ZEGOCLOUD Console and applied for a valid AppId and ServerSecret. For details, please refer to Console - Project Information.
You have self-serviced enabled the "Stream Mixing" service permission in the ZEGOCLOUD Console. For details, please refer to Console - Service Configuration - Stream Mixing, or contact ZEGOCLOUD Technical Support to enable it.
You have initiated publishing and subscribing Streams in the Room through your own client. For details, please refer to Implementing Video Call.
If you want to automatically create the corresponding Room when it doesn't exist during auto Stream Mixing creation, please contact ZEGOCLOUD Technical Support to enable this feature.

Note

In the test environment (see IsTest common parameter description for details), the Stream IDs of input Streams and output Streams:

If it is the original Stream ID entered by the developer, you need to add the "zegotest-AppId-" prefix, otherwise the Stream Mixing will fail (the Stream Mixing server cannot pull the input Stream or pull the mixed output Stream). For example, if the developer enters the Stream ID as "test", in the test environment with AppId "123456789", the Stream ID should be "zegotest-123456789-test".
If it is obtained through SDK interfaces or server-side API interfaces, you don't need to add the "zegotest-AppId-" prefix at this time.

Rate Limit

100 requests/second

Only some parameters in this interface support dynamic updates after Stream Mixing starts. Parameters not marked do not support dynamic updates. For details, please refer to the parameter descriptions in the table below.

Request

Query Parameters

Action stringrequired

Possible values: [StartAutoMix]

API Prototype Parameter

https://rtc-api.zego.im?Action=StartAutoMix

AppId uint32required

💡Public parameter. Application ID, assigned by ZEGOCLOUD. Get it from the ZEGOCLOUD Admin Console.

SignatureNonce stringrequired

💡Common parameter. A 16-character hexadecimal random string (hex-encoded 8-byte random number). For the generation algorithm, refer to the signature example.

Timestamp int64required

💡Common parameter. Current Unix timestamp in seconds. For the generation algorithm, refer to the signature example. A maximum deviation of 10 minutes is allowed.

Signature stringrequired

💡Common parameter. Signature used to verify the legitimacy of the request. Please refer to the signature mechanism to generate it.

SignatureVersion stringrequired

Possible values: [2.0]

Default value: 2.0

💡Public parameter. Signature version number.

application/json

Body

required

TaskId stringrequired

Task ID, the unique identifier of the Stream Mixing task.

Repeatedly calling the "Start Stream Mixing" interface with the same TaskId can directly update the Stream Mixing task information.
When initiating "audio and video" Stream Mixing, if a "pure audio" Stream Mixing task with the corresponding TaskId has been initiated before, you need to stop this task first and then re-initiate the "audio and video" Stream Mixing task.

UserId stringrequired

User ID of the user initiating the Stream Mixing task, customized by the developer.

User IDs for the same task need to be consistent, and User IDs for different tasks need to be different.

Through UserId, you can implement user attribution of Stream Mixing tasks. That is, only this user can update or stop the Stream Mixing task corresponding to the TaskId. This function needs to be enabled by contacting ZEGOCLOUD Technical Support.

RoomId stringrequired

Room ID.

ExtraMixInput object[]

Additional input Stream list (Streams from other Rooms), supports up to 9 additional input Streams by default.
📌Note
When enabling automatic Stream Mixing, up to 9 input Streams are supported. That is, after adding or removing (determined by ModifyType value whether to add or delete a Stream) additional input Streams to the Streams in the Room, the total number of Streams cannot exceed 9.

Array[

StreamId string

Stream Mixing input Stream ID, this Stream ID comes from RTC service.

Only supports numbers, English characters, and "-", "_".

Note

StreamId and StreamUrl, choose one of the two. If both StreamId and StreamUrl are filled in:

When ModifyType is 0 (add), StreamUrl takes effect.

When ModifyType is 1 (remove), StreamId takes effect.

StreamUrl string

Stream Mixing input Stream URL, supports both RTMP and HTTP-FLV protocols.

Note

StreamId and StreamUrl, choose one of the two. If both StreamId and StreamUrl are filled in:

When ModifyType is 0 (add), StreamUrl takes effect.

When ModifyType is 1 (remove), StreamId takes effect.

ModifyType int

Possible values: [0, 1]

Type of input Stream list, indicating "add" or "remove" this input Stream in the current Stream Mixing task:

0: When enabling automatic Stream Mixing, add the current Stream to the input Stream list, default value
1: When enabling automatic Stream Mixing, remove the current Stream from the input Stream list. At this time, you only need to fill in StreamId and the value of this parameter

SoundLevelId int

Sound Level ID. When the parameter SoundLevel (Stream Mixing Sound Level) is set to "1", this parameter is required.

Volume int

Default value: 100

Volume, value range [0, 200], default is 100.

]

MixOutput object[]required

Output Stream information, currently supports up to 3. When the output target is in URL format, currently only RTMP URL format is supported: rtmp://xxxxxxxx, and two identical Stream Mixing output addresses cannot be passed in.

Array[

StreamId string

Output Stream ID. By default, it means the Stream Mixing output goes to RTC or low-latency live products. You can also contact ZEGOCLOUD Technical Support to configure Stream Mixing output to ZEGOCLOUD proxy CDN live products. The effective scope is the entire AppId. If you want to control the specified Stream output to CDN live products, you cannot configure Stream Mixing default output to ZEGOCLOUD proxy CDN, and should set StreamUrl as needed.

StreamId and StreamUrl, choose one of the two. If StreamId is filled in, StreamUrl will not take effect.

StreamUrl string

Only supports RTMP protocol, indicating Stream Mixing output to CDN live service. Audiences can pull Stream Mixing from CDN live.

StreamId and StreamUrl, choose one of the two. If StreamUrl is filled in, StreamId will not take effect.

AudioCodec int

Possible values: [0, 1, 2, 3]

Audio codec and sample rate. To modify the sample rate, please contact ZEGOCLOUD Technical Support to configure:

0: HE-AAC, sample rate: 44100 kHz, default value
1: AAC-LC, sample rate: 44100 kHz
2: MP3, sample rate: 44100 kHz
3: OPUS, sample rate: 48000 kHz

AudioBitrate int

Stream Mixing output audio bitrate. If not filled, the default value is 48000, unit is bps.

SoundChannel int

Possible values: [1, 2]

Output audio channel count, higher priority than global parameters:

1: Mono, default value
2: Stereo

]

Sequence int

Sequence number of the Stream Mixing request, used to ensure timing. Parameter modifications for the same task need to ensure the sequence number increases. For example: "Sequence": 1.

If the timing control of the Stream Mixing task is enabled (if needed, please contact ZEGOCLOUD Technical Support to enable), this parameter is required.

UserData string

Custom user data. When using, you need to base64 encode the content of this parameter. Length limit is 4000 bytes, recommended not to exceed 850 bytes.

Custom user data will be transmitted to the subscribing side as SEI information. The subscribing side can obtain the data by listening to the client's onPlayerSyncRecvSEI callback.

🔁Call this interface again to dynamically update this parameter.

SoundLevel int

Possible values: [0, 1]

Stream Mixing Sound Level, refers to the volume size of Stream Mixing. Supports real-time updates during Stream Mixing:

0: Disabled, default value
1: Enabled. After enabling, the client can receive notifications of automatic Stream Mixing sound level updates through the onAutoMixerSoundLevelUpdate callback

🔁Call this interface again to dynamically update this parameter.

ByPass int

Possible values: [0, 1]

Default value: 0

Single Stream passthrough switch, that is, whether to re-encode according to output parameters when there is only one input Stream. This function needs to be enabled by contacting ZEGOCLOUD Technical Support:

0: Disabled, default value
1: Enabled

SoundChannel int

Possible values: [1, 2]

Default value: 1

Output audio channel count, this configuration is used when no output Stream is specified:

1: Mono, default value
2: Stereo

AlignmentType int

Possible values: [0, 1, 2]

Control whether the real-time audio and video Streams being played need to be mixed after precise alignment according to NTP (Network Time). This parameter is mainly applied in KTV scenarios and will increase certain Stream Mixing latency; for non-KTV similar scenarios, it is not recommended to set this parameter.

0: No alignment, default value
1: Specified Stream alignment
2: Force all Streams to align

RecvBufferLevel int

Possible values: >= 0 and <= 4000

Control the minimum buffer time for subscribing Streams, value range [0, 4000], unit: milliseconds; default minimum buffer time is 0.

ExPara object[]

Extended parameters, fill in according to actual situation, regular tasks can be left blank.

Array[

Key string

Key value.

Value string

Value value.

]

Responses

Operation succeeded

application/json

Schema
Example (from schema)

Schema

Code int

The following only lists some return codes related to the interface business logic. For complete return codes, please refer to Global Return Codes.

Return Code	Description	Suggested Handling
110200001	Failed.	Please retry.
110200002	Input parameter error.	Please handle according to Message information.
110200003	Authentication failed.	Please confirm whether the authentication information is correct or expired. For details, please refer to "Signature Mechanism" in Calling Method.
110200004	Failed to parse input parameters.	Please check whether the Stream Mixing parameters are correct.
110200005	Failed to acquire distributed lock for Stream Mixing start.	The same UserId starts Stream Mixing requests too frequently, please try again later.
110200006	Failed to acquire distributed lock for Stream Mixing stop.	The same UserId stops Stream Mixing requests too frequently, please try again later.
110200151	Stream Mixing task failed.	Please retry, or contact ZEGOCLOUD Technical Support for handling.
110200194	Stream Mixing request overload.	Requests are too frequent, please try again later.

Message string

Operation result description.

RequestId string

Request ID.

Data object

Response data.

UserId string

User ID.

Sequence int

Sequence number.

RoomId string

Room ID.

PlayInfo object[]

Playback information.

Array[

StreamId string

Output Stream ID.

RTMP string

CDN playback address corresponding to RTMP protocol (if the specified Stream Mixing output address is CDN and this protocol's pull domain name is configured).

HLS string

CDN playback address corresponding to HLS protocol (if the specified Stream Mixing output address is CDN and this protocol's pull domain name is configured).

FLV string

CDN playback address corresponding to HTTP-FLV protocol (if the specified Stream Mixing output address is CDN and this protocol's pull domain name is configured).

Status integer

Stream status.

UserName string

User name.

]

{
  "Code": 0,
  "Message": "success",
  "RequestId": "8472822294336370476",
  "Data": {
    "UserId": "123",
    "Sequence": 1,
    "RoomId": "room123",
    "PlayInfo": [
      {
        "StreamId": "test",
        "RTMP": "rtmp://domain/appname/test",
        "HLS": "http://domain/appname/test/playlist.m3u8",
        "FLV": "http://domain/appname/test.flv",
        "Status": 0,
        "UserName": ""
      }
    ]
  }
}

{
  "Code": 0,
  "Message": "success",
  "RequestId": "8472822294336370476",
  "Data": {
    "UserId": "123",
    "Sequence": 1,
    "RoomId": "room123",
    "PlayInfo": [
      {
        "StreamId": "test",
        "RTMP": "rtmp://domain/appname/test",
        "HLS": "http://domain/appname/test/playlist.m3u8",
        "FLV": "http://domain/appname/test.flv",
        "Status": 0,
        "UserName": ""
      }
    ]
  }
}

StartAutoMix

https://rtc-api.zego.im/

Prerequisites

Request

Query Parameters

Body

Responses​

Responses