StartMix
https://rtc-api.zego.im/
Overview
This interface is used to start/update Stream Mixing tasks.
For information about the client-side Stream Mixing feature, please refer to Multi-Stream Mixing. For related callbacks, please refer to Stream Mixing Started Callback and Stream Mixing Stopped Callback.
Prerequisites
Before implementing Stream Mixing, ensure that:
- 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 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 publish stream and play stream in the Room through your own client. For details, please refer to Implementing Video Call.
Example Code
ZEGOCLOUD provides example code in multiple programming languages. The following example demonstrates "mixing two audio/video streams (stream1, stream2) and outputting the mixed result to one stream (stream3)":
package main
import (
"bytes"
"crypto/md5"
"crypto/rand"
"encoding/hex"
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
"net/url"
"strconv"
"time"
)
// rtc-api.zego.im indicates the product used is the cloud communication product, including Real-time Audio/Video (Express Video), Real-time Audio (Express Audio), and Low-latency Live Streaming (L3)
const DOMAIN = "https://rtc-api.zego.im"
var (
//Please modify appId to your appId, appid is uint32
//For example: 1234567890
AppId uint32 = 1234567890
//Please modify serverSecret to your serverSecret, serverSecret is string
Secret = ""
)
type MixStartRequest struct {
Appid uint64 `json:"Appid"`
UserId string `json:"UserId"`
Sequence int64 `json:"Sequence"`
MixInput []*MixInput `json:"MixInput"`
MixOutput []*MixOutput `json:"MixOutput"`
MixTaskId string `json:"TaskId"`
}
type RectInfo struct {
Top int32 `json:"Top"`
Left int32 `json:"Left"`
Bottom int32 `json:"Bottom"`
Right int32 `json:"Right"`
}
type MixInput struct {
StreamId string `json:"StreamId"`
RectInfo *RectInfo `json:"RectInfo"`
}
type MixOutput struct {
StreamId string `json:"StreamId"`
VideoBitrate int32 `json:"VideoBitrate"`
Fps int32 `json:"Fps"`
Height int32 `json:"Height"`
Width int32 `json:"Width"`
}
func main() {
nonce := make([]byte, 8)
rand.Read(nonce)
hexNonce := hex.EncodeToString(nonce)
ts := time.Now()
signature := GenerateSignature(AppId, hexNonce, Secret, ts.Unix())
value := url.Values{}
value.Add("AppId", strconv.FormatUint(AppId, 10))
value.Add("SignatureNonce", hexNonce)
value.Add("Timestamp", strconv.FormatInt(ts.Unix(), 10))
value.Add("Signature", signature)
value.Add("Action", "StartMix")
value.Add("SignatureVersion", "2.0")
urlData, err := url.Parse(DOMAIN)
if err != nil {
fmt.Println(err)
return
}
urlData.RawQuery = value.Encode()
dataJson, _ := json.Marshal(GenerateStartMixData())
req, err := http.NewRequest("POST", urlData.String(), bytes.NewBuffer(dataJson))
if err != nil {
fmt.Println(err)
return
}
req.Header.Set("Content-Type", "application/json")
req.Close = true
client := &http.Client{}
r, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
if r.StatusCode != 200 {
fmt.Printf("status code is:%v", r.StatusCode)
}
defer r.Body.Close()
resp, err := ioutil.ReadAll(r.Body)
if err != nil {
return
}
fmt.Println(string(resp))
return
}
//The following example is to mix the audio/video stream with streamId "stream1" and the audio/video stream with streamId "stream2", and output the audio/video stream with streamId "stream3"
func GenerateStartMixData() *MixStartRequest {
inputs := make([]*MixInput, 0)
input1 := MixInput{
StreamId: "stream1",
RectInfo: &RectInfo{
Top: 70,
Left: 100,
Bottom: 160,
Right: 260,
},
}
inputs = append(inputs, &input1)
input2 := MixInput{
StreamId: "stream2",
RectInfo: &RectInfo{
Top: 200,
Left: 100,
Bottom: 290,
Right: 260,
},
}
inputs = append(inputs, &input2)
output := MixOutput{
StreamId: "stream3",
VideoBitrate: 12000,
Fps: 15,
Height: 360,
Width: 360,
}
outputs := append([]*MixOutput{}, &output)
req := &MixStartRequest{
Appid: AppId,
UserId: "123",
Sequence: 123,
MixInput: inputs,
MixOutput: outputs,
MixTaskId: "123",
}
return req
}
//Signature=md5(AppId + SignatureNonce + ServerSecret + Timestamp)
func GenerateSignature(appid uint64, nonce string, appSecret string, timestamp int64) (signature string) {
data := fmt.Sprintf("%d%s%s%d", appid, nonce, appSecret, timestamp)
h := md5.New() //Specifying the use of the MD5 algorithm in the hash algorithm
h.Write([]byte(data))
//hex.EncodeToString(h.Sum(nil)) outputs a hexadecimal string
return hex.EncodeToString(h.Sum(nil))
}# -*- coding: UTF-8 -*-
import hashlib
import secrets
import time
# Generate signature
# Signature=md5(AppId + SignatureNonce + ServerSecret + Timestamp)
from urllib.parse import urlencode
import requests
def GenerateSignature(appId, signatureNonce, serverSecret, timestamp):
str1 = str(appId) + signatureNonce + serverSecret + str(timestamp)
hash = hashlib.md5()
hash.update(str1.encode("utf8"))
signature = hash.hexdigest()
return signature
if __name__ == '__main__':
# Please modify appId to your appId, appid is a number
# For example: 1234567890
appId = 1234567890
# Please modify serverSecret to your serverSecret, serverSecret is string
serverSecret = ""
signatureNonce = secrets.token_hex(8)
timestamp = int(time.time())
sig = GenerateSignature(appId, signatureNonce, serverSecret, timestamp)
# The following example mixes the audio/video stream with StreamId "stream1" and the audio/video stream with StreamId "stream2", and outputs the audio/video stream with StreamId "stream3"
par = {
"Action": "StartMix",
"AppId": appId,
"Signature": sig,
"SignatureNonce": signatureNonce,
"SignatureVersion": "2.0",
"Timestamp": timestamp,
"IsTest": "False"
}
body = {
'TaskId': '123',
'Sequence': 123,
'UserId': '123',
'MixInput': [
{
'StreamId': 'stream1',
'RectInfo': {
"Top": 70,
"Bottom": 160,
"Left": 100,
"Right": 260,
},
},
{
'StreamId': 'stream2',
'RectInfo': {
"Top": 200,
"Bottom": 290,
"Left": 100,
"Right": 260,
},
}
],
'MixOutput': [{
'StreamId': 'stream3',
'Width': 360,
'Height': 360,
'VideoBitrate': 12000,
'Fps': 15
}]
}
url = 'https://rtc-api.zego.im/'
req = requests.post(url, params=par, json=body)
print("Url: ", req.url)
print("StatusCode", req.status_code)
print("Respone:", req.text)package org.example;
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.io.OutputStreamWriter;
import java.net.HttpURLConnection;
import java.net.MalformedURLException;
import java.net.URL;
import java.security.MessageDigest;
import java.security.SecureRandom;
import java.util.HashMap;
import java.util.Map;
/**
* Please first introduce com.alibaba.fastjson for easy construction of request body parameters
*/
import com.alibaba.fastjson.JSONArray;
import com.alibaba.fastjson.JSONObject;
public class StartMix {
//
public static void main(String[] args) {
// Get the number of users in the room
startMixStream();
}
/**
* Initiate Stream Mixing
*/
public static void startMixStream() {
// Please fill in your APP ID obtained from the console,
// For example: 1234567890L
Long APP_ID = 1234567890L;
// Please fill in your SERVER SECRET obtained from the console backend,
// For example: "abcde1234aaaaaaaabbbbbbb"
String SERVER_SECRET = ;
// Generate a random hexadecimal string (16 bits)
byte[] bytes = new byte[8];
SecureRandom sr = new SecureRandom();
sr.nextBytes(bytes);
String signatureNonce = bytesToHex(bytes);
// Set timestamp
long timestamp = System.currentTimeMillis() / 1000L;
// Generate signature Signature=md5(AppId + SignatureNonce + ServerSecret + Timestamp)
String signatue = generateSignature(APP_ID, signatureNonce, SERVER_SECRET, timestamp);
// Assemble request URL
//The following example mixes the audio/video stream with StreamId "stream1" and the audio/video stream with StreamId "stream2", and outputs the audio/video stream with StreamId "stream3"
Map<String, Object> params = new HashMap<String, Object>();
params.put("Action", "StartMix");
params.put("AppId", APP_ID);
params.put("SignatureNonce", signatureNonce);
params.put("Timestamp", timestamp);
params.put("Signature", signatue);
params.put("SignatureVersion", "2.0");
// rtc-api.zego.im indicates the product used is the cloud communication product, including Real-time Audio/Video (Express Video), Real-time Audio (Express Audio), and Low-latency Live Streaming (L3)
String url = buildAPIUrl("https://rtc-api.zego.im/", params);
JSONObject body = new JSONObject()
.fluentPut("TaskId", "123")
.fluentPut("Sequence", 123)
.fluentPut("UserId", "123");
JSONArray mixInputList = new JSONArray();
mixInputList.add(new JSONObject()
.fluentPut("StreamId", "stream1")
.fluentPut("RectInfo", new JSONObject()
.fluentPut("Top", 70)
.fluentPut("Bottom", 160)
.fluentPut("Left", 100)
.fluentPut("Right", 260)));
mixInputList.add(new JSONObject()
.fluentPut("StreamId", "stream2")
.fluentPut("RectInfo", new JSONObject()
.fluentPut("Top", 200)
.fluentPut("Bottom", 290)
.fluentPut("Left", 100)
.fluentPut("Right", 260)));
body.put("MixInput", mixInputList);
JSONArray mixOutputList = new JSONArray();
mixOutputList.add(new JSONObject()
.fluentPut("StreamId", "stream3")
.fluentPut("Width", 360)
.fluentPut("Height", 360)
.fluentPut("VideoBitrate", 12000)
.fluentPut("Fps", 15));
body.put("MixOutput", mixOutputList);
String result = sendPost(url, body.toString());
System.out.println(result);
}
/**
* Generate signature
* @param appId Application APPID
* @param signatureNonce Signature random code
* @param serverSecret Server-side API key
* @param timestamp Signature timestamp
* @return Generated signature string
*/
public static String generateSignature(long appId, String signatureNonce, String serverSecret, long timestamp){
String str = String.valueOf(appId) + signatureNonce + serverSecret + String.valueOf(timestamp);
String signature = "";
try{
//Create an object that provides the message digest algorithm, initialized as an MD5 algorithm object
MessageDigest md = MessageDigest.getInstance("MD5");
//Calculate to get byte array
byte[] bytes = md.digest(str.getBytes("utf-8"));
//Convert each byte of the array to hexadecimal and concatenate it into an MD5 string
signature = bytesToHex(bytes);
}catch (Exception e) {
e.printStackTrace();
}
return signature;
}
/**
* Convert byte array to hexadecimal
* @param bytes Byte array to be converted
* @return Converted Hex string
*/
public static String bytesToHex(byte[] bytes) {
StringBuffer md5str = new StringBuffer();
//Convert each byte of the array to hexadecimal and concatenate it into an MD5 string
int digital;
for (int i = 0; i < bytes.length; i++) {
digital = bytes[i];
if (digital < 0) {
digital += 256;
}
if (digital < 16) {
md5str.append("0");
}
md5str.append(Integer.toHexString(digital));
}
return md5str.toString();
}
/**
* Send HTTP-GET request
* @param httpurl Request path
* @return Response content
*/
public static String sendGet(String httpurl) {
HttpURLConnection connection = null;
InputStream is = null;
BufferedReader br = null;
String result = null;// Return result string
try {
// Create remote url connection object
URL url = new URL(httpurl);
// Open a connection through the remote url connection object, cast to HttpURLConnection class
connection = (HttpURLConnection) url.openConnection();
// Set connection method: get
connection.setRequestMethod("GET");
// Set connection host server timeout: 15000 milliseconds
connection.setConnectTimeout(15000);
// Set read remote return data timeout: 60000 milliseconds
connection.setReadTimeout(60000);
// Send request
connection.connect();
// Get input stream through connection connection
if (connection.getResponseCode() == 200) {
is = connection.getInputStream();
// Encapsulate input stream is, specify character set
br = new BufferedReader(new InputStreamReader(is, "UTF-8"));
// Store data
StringBuffer sbf = new StringBuffer();
String temp = null;
while ((temp = br.readLine()) != null) {
sbf.append(temp);
sbf.append("\r\n");
}
result = sbf.toString();
}
} catch (MalformedURLException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} finally {
// Close resources
if (null != br) {
try {
br.close();
} catch (IOException e) {
e.printStackTrace();
}
}
if (null != is) {
try {
is.close();
} catch (IOException e) {
e.printStackTrace();
}
}
connection.disconnect();// Close remote connection
}
return result;
}
/**
* Send HTTP-POST request
* @param param Message body parameter
* @return Response content
*/
public static String sendPost(String httpUrl, String param) {
HttpURLConnection connection = null;
InputStream is = null;
OutputStream os = null;
BufferedReader br = null;
String result = null;
try {
URL url = new URL(httpUrl);
// Open connection through remote url connection object
connection = (HttpURLConnection) url.openConnection();
// Set connection request method
connection.setRequestMethod("POST");
// Set connection host server timeout: 15000 milliseconds
connection.setConnectTimeout(15000);
// Set read host server return data timeout: 60000 milliseconds
connection.setReadTimeout(60000);
// Default value: false, when transmitting data/writing data to remote server, need to set to true
connection.setDoOutput(true);
// Default value: true, when reading data from remote service, set to true, this parameter is optional
connection.setDoInput(true);
// Set format of incoming parameters: request parameters should be in the form of name1=value1&name2=value2
connection.setRequestProperty("Content-Type", "application/json");
// Establish connection
connection.connect();
// Get an output stream object through the connection object
OutputStreamWriter writer = new OutputStreamWriter(connection.getOutputStream(),"UTF-8");
writer.write(param);
writer.flush();
// Get an input stream through the connection object to read remotely
if (connection.getResponseCode() == 200) {
is = connection.getInputStream();
// Wrap input stream object: charset is set according to project team requirements
br = new BufferedReader(new InputStreamReader(is, "UTF-8"));
StringBuffer sbf = new StringBuffer();
String temp = null;
// Loop to read data line by line
while ((temp = br.readLine()) != null) {
sbf.append(temp);
sbf.append("\r");
}
result = sbf.toString();
}
} catch (MalformedURLException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} finally {
// Close resources
if (null != br) {
try {
br.close();
} catch (IOException e) {
e.printStackTrace();
}
}
if (null != os) {
try {
os.close();
} catch (IOException e) {
e.printStackTrace();
}
}
if (null != is) {
try {
is.close();
} catch (IOException e) {
e.printStackTrace();
}
}
// Disconnect from remote address url
connection.disconnect();
}
return result;
}
/**
* Assemble API address string
* @param url API address
* @param params Request parameters
* @return Assembled API address string
*/
public static String buildAPIUrl(String url, Map<String, Object> params) {
if(params.isEmpty()) {
return url;
}
StringBuffer buffer = new StringBuffer(url).append("?");
for(String key : params.keySet()) {
buffer.append(key).append("=").append(params.get(key)).append("&");
}
String apiurl = buffer.toString();
if(apiurl.endsWith("&")) {
return apiurl.substring(0, apiurl.length()-1);
} else {
return apiurl;
}
}
}<?php
/**
* Simplest example code to initiate Stream Mixing
*/
//Please modify appId to your appId
//For example: 1234567890
$appId = 1234567890;
//Please modify serverSecret to your serverSecret, serverSecret is string
$serverSecret = "";
//Generate signature
//Signature=md5(AppId + SignatureNonce + ServerSecret + Timestamp)
function GenerateSignature($appId, $signatureNonce, $serverSecret, $timeStamp){
$str = $appId . $signatureNonce . $serverSecret . $timeStamp;
//Use the standard MD5 algorithm in PHP, which returns a 32-character hexadecimal number by default
return md5($str);
}
//Get random string and convert to hexadecimal value
$signatureNonce = bin2hex(random_bytes(8));
//Get millisecond-level timestamp
list($msec, $sec) = explode(' ', microtime());
$msecTime = (float)sprintf('%.0f', (floatval($msec) + floatval($sec)) * 1000);
//Round $msecTime to get second-level timestamp
$timeStamp = round($msecTime/1000);
$sig = GenerateSignature($appId, $signatureNonce, $serverSecret, $timeStamp);
//The following example mixes the audio/video stream with StreamId "stream1" and the audio/video stream with StreamId "stream2", and outputs the audio/video stream with StreamId "stream3"
$url = "https://rtc-api.zego.im/?Action=StartMix&AppId=$appId&SignatureNonce=$signatureNonce&Timestamp=$timeStamp&Signature=$sig&SignatureVersion=2.0&IsTest=false";
$body = [
"TaskId" => "123",
"Sequence" => 123,
"UserId" => "123",
"MixInput" => [
[
"StreamId" => "stream1",
"RectInfo" => [
"Top" => 70,
"Bottom" => 160,
"Left" => 100,
"Right" => 260,
],
],
[
"StreamId" => "stream2",
"RectInfo" => [
"Top" => 200,
"Bottom" => 290,
"Left" => 100,
"Right" => 260,
],
]
],
"MixOutput" => [
[
"StreamId" => "stream3",
"Width" => 360,
"Height" => 360,
"VideoBitrate" => 12000,
"Fps" => 15
]
]
];
$post_string = json_encode($body);
$ch = curl_init();
curl_setopt ($ch, CURLOPT_URL, $url);
curl_setopt ($ch, CURLOPT_POST, 1);
curl_setopt ($ch, CURLOPT_RETURNTRANSFER, 1);
//Set request connection timeout, unit: seconds
curl_setopt ($ch, CURLOPT_CONNECTTIMEOUT, 5);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_string);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json; charset=utf-8',
)
);
$response = curl_exec($ch);
curl_close($ch);
echo "Url:" . $url;
echo "\r\n";
echo "request body:" . $post_string;
echo "\r\n";
echo "response:" . $response;const crypto = require('crypto');
const request = require('request');
//Please modify appId to your appId, appid is number
var appId = ;
//Please modify serverSecret to your serverSecret, serverSecret is string
var serverSecret = "";
//Signature=md5(AppId + SignatureNonce + ServerSecret + Timestamp)
function GenerateSignature(appId, signatureNonce, serverSecret, timeStamp) {
const hash = crypto.createHash('md5'); //Specifying the use of the MD5 algorithm in the hash algorithm
var str = appId + signatureNonce + serverSecret + timeStamp;
hash.update(str);
//hash.digest('hex') indicates the output format is hexadecimal
return hash.digest('hex');
}
var signatureNonce = crypto.randomBytes(8).toString('hex');
var timeStamp = Math.round(Date.now() / 1000);
var sig = GenerateSignature(appId, signatureNonce, serverSecret, timeStamp)
//The following example mixes the audio/video stream with StreamId "stream1" and the audio/video stream with StreamId "stream2", and outputs the audio/video stream with StreamId "stream3"
var url = `https://rtc-api.zego.im/?Action=StartMix&AppId=${appId}&SignatureNonce=${signatureNonce}&Timestamp=${timeStamp}&Signature=${sig}&SignatureVersion=2.0&IsTest=false`
var body = {
'TaskId': '123',
'Sequence': 123,
'UserId': '123',
'MixInput': [
{
'StreamId': 'stream1',
'RectInfo': {
"Top": 70,
"Bottom": 160,
"Left": 100,
"Right": 260,
},
},
{
'StreamId': 'stream2',
'RectInfo': {
"Top": 200,
"Bottom": 290,
"Left": 100,
"Right": 260,
},
}
],
'MixOutput': [{
'StreamId': 'stream3',
'Width': 360,
'Height': 360,
'VideoBitrate': 12000,
'Fps': 15
}]
}
request({
url: url,
method: 'POST',
json: true,
headers: {
'content-type': 'application/json'
},
body: body
}, function (error, response, body) {
console.log(error)
console.log(response.statusCode)
if (!error && response.statusCode === 200) {
console.log(body.Data)
}
})Parameter Description
In the test environment (see IsTest common parameter description for details), for the Stream IDs of input streams and output streams:
- If the original Stream ID is entered by the developer, the "zegotest-AppId-" prefix must be added, otherwise Stream Mixing will fail (the Stream Mixing server cannot pull the input stream or pull the Stream Mixing output stream). For example, if the developer enters Stream ID "test", in the test environment with AppId "123456789", the Stream ID should be "zegotest-123456789-test".
- If obtained through SDK interfaces or server-side API interfaces, there is no need to add the "zegotest-AppId-" prefix.
For all request parameters below, parameters of type "String" only support numbers, English characters, and '~', '!', '@', '#', '$', '%', '^', '&', '*', '(', ')', '_', '+', '=', '-', '`', ';', ''', ',', '.', '<', '>', '/', ''.
The following parameter description includes all parameters for the Start Stream Mixing interface, including some advanced features (e.g., setting watermarks, background images, setting extended parameters, etc.).
If you want to quickly initiate a Stream Mixing task, please refer to the Example in the REQUEST panel on the right. Fill in the basic parameters to initiate the task.
FAQ
-
When mixing pure audio with a background image set, the background image cannot be displayed normally. How to handle this?
In this case, the customer needs to correctly set the width and height of the output layout according to their business requirements, and contact ZEGOCLOUD technical support to configure and enable black frame padding.
Request
Query Parameters
Possible values: [StartMix]
Interface prototype parameters
https://rtc-api.zego.im?Action=StartMix
💡Public parameter. Application ID, assigned by ZEGOCLOUD. Get it from the ZEGOCLOUD Admin Console.
💡Common parameter. A 16-character hexadecimal random string (hex-encoded 8-byte random number). For the generation algorithm, refer to the signature example.
💡Common parameter. Current Unix timestamp in seconds. For the generation algorithm, refer to the signature example. A maximum deviation of 10 minutes is allowed.
💡Common parameter. Signature used to verify the legitimacy of the request. Please refer to the signature mechanism to generate it.
Possible values: [2.0]
Default value: 2.0
💡Public parameter. Signature version number.
- application/json
Body
required
- Array[
- When the fields (Top, Left, Bottom, Right) under this parameter are not filled in, it defaults to pure audio Stream Mixing.
- When the input stream resolution does not match the corresponding input stream canvas width and height, rendering will be performed with reference to RenderMode.
- URI: Provide the image to ZEGOCLOUD technical support for configuration, and an image URI will be provided after configuration, e.g., preset-id://xxx.jpg
- URL: Supports HTTP/HTTPS protocol, image size must be limited to within 1MB
- 0: Default value. When URL is not empty, cover video content and display the image
- 1: Determine whether to display the image based on the camera status:
- Camera off: Display the image
- Camera on: Display video content (no need to manually clear the URL parameter)
- 2: Determine whether to display the image based on whether the input stream is an empty stream. When the input stream is continuously empty for 3 seconds, display the image
- 0: Take audio and video, default value
- 1: Take audio only
- 2: Take video only
- 0: Source Han Sans Regular, default value
- 1: Alibaba PuHuiTi
- 2: Pangmen Zhengdao Title Font
- 3: ZCOOL KuaiLe Font
- 0: Crop mode, default value, the image will be cropped to the set layout size.
- 1: Fill mode, the set RectInfo parameter becomes invalid, the input image is displayed completely, and the layout will be adjusted to adapt to the input stream aspect ratio.
- ]
- When outputting multiple video streams of different resolutions in the same Stream Mixing task, it is recommended that the resolution in the first Mixoutput be the maximum resolution.
- Array[
- 0: H264, default value
- 2: VP8
- 3: H265
- 4: H264 SVC, Scalable Video Coding
- Supports different output streams using different video encoding formats, with a maximum of two types. When using multiple video encoding formats, please contact ZEGOCLOUD technical support to enable the mutil_encode backend parameter first.
- When the value is 2 or 3, if you need to use the corresponding encoding format, please contact ZEGOCLOUD technical support.
- When the value is 4, you need to contact ZEGOCLOUD technical support to enable the mutil_encode backend parameter and fill in the ExtraLayers field for the H264 SVC format to take effect. If Stream Mixing output is to the CDN live streaming service, the output stream will automatically downgrade to H264 format.
- 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
- 1: Mono, default value
- 2: Stereo
- Array[
- ]
- 0: Default value, not enabled
- 1: Enabled
- Each output stream only supports joining one Room. Once added, the Room cannot be dynamically updated during Stream Mixing, but one Room can have multiple output streams.
- When starting Stream Mixing, if joining the Room fails, the Stream Mixing task fails, and the developer needs to re-initiate the Stream Mixing task.
- When the Room is closed, all stream states in the Room will be closed, but the Stream Mixing task will not stop.
- RoomId and UserId cannot be empty.
- ]
- 0: Not enabled, default value.
- 1: Enabled.
- URI: Provide the image to ZEGOCLOUD technical support for configuration, and an image URI will be provided after configuration, e.g., preset-id://xxx.jpg
- URL: Supports HTTP/HTTPS protocol. Under the same AppID, up to 20 URL addresses are supported; used URL addresses cannot be deleted. If you need to change the image, it is strongly recommended that you directly update the image file with the same name (same URL). The image size must be limited to within 5MB, and settings exceeding 5MB will not take effect.
- 0: Not enabled, default value
- 1: Enabled
- 1: Mono, default value
- 2: Stereo
- 0: Strictly validate the restrictions of the 3 image parameters, i.e., must meet the parameter's original "supported protocol and format", "image size", "image resource request successful" and other rules to initiate Stream Mixing normally, default value
- 1: Only validate the image path URI/URL format of the 3 image parameters, i.e., when the image path format is correct but the image resource request fails or the image size exceeds the limit, Stream Mixing can still be initiated normally
- 2: Do not validate any restrictions of the 3 image parameters, i.e., when the image path format is incorrect, the image resource request fails, or the image size exceeds the limit, Stream Mixing can still be initiated normally
- Array[
- ]
- 0: Not aligned, default value
- 1: Specified stream alignment
- 2: Force align all streams
- 0: No (default)
- 1: Yes. If video data cannot be pulled within 10 seconds, the Stream Mixing task will automatically end
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.
The User ID of the user who initiated the Stream Mixing task, customized by the developer.
The User ID for the same task must be consistent, and User IDs for different tasks must be different.
Through UserId, you can achieve user attribution of Stream Mixing tasks, meaning only this user can update or stop the Stream Mixing task corresponding to the TaskId. This feature requires contacting ZEGOCLOUD technical support to enable.
🔁Call this interface again to dynamically update this parameter.
MixInput object[]required
Stream Mixing input Stream ID, indicating that this Stream ID comes from the RTC service.
Either StreamId or StreamUrl can be used. If both StreamId and StreamUrl are filled in, StreamUrl will take effect.
🔁Call this interface again to dynamically update this parameter.
Stream Mixing input Stream URL, supporting both RTMP and HTTP-FLV protocols.
Either StreamId or StreamUrl can be used. If both StreamId and StreamUrl are filled in, StreamUrl will take effect.
🔁Call this interface again to dynamically update this parameter.
BlurInfo object
Possible values: >= 0
Default value: 0
Top margin blur pixel size, in pixels. Cannot exceed half of the RectInfo height.
Possible values: >= 0
Default value: 0
Left margin blur pixel size, in pixels. Cannot exceed half of the RectInfo width.
Possible values: >= 0
Default value: 0
Bottom margin blur pixel size, in pixels. Cannot exceed half of the RectInfo height.
Possible values: >= 0
Default value: 0
Right margin blur pixel size, in pixels. Cannot exceed half of the RectInfo width.
RectInfo objectrequired
Input stream position information. The position reference of the input stream is as follows:
Layer level. 0 indicates the bottom layer, and a larger value indicates a higher level.
Top border. The pixel size from the top border of the output canvas.
Left border. The pixel size from the left border of the output canvas.
Bottom border. The pixel size from the top border of the output canvas.
Right border. The pixel size from the left border of the output canvas.
Rounded corner size. Value range [0, 100], default is 0.
Image object
Image path, supporting JPG and PNG formats. Supports the following 2 usage methods:
When this parameter is empty, video content is displayed; otherwise, the corresponding image is displayed.
Possible values: [0, 1, 2]
Image display mode:
Possible values: [0, 1, 2]
Content control:
🔁Call this interface again to dynamically update this parameter.
Sound wave ID.
This parameter is required when the SoundLevel (Stream Mixing sound wave) parameter value is "1".
🔁Call this interface again to dynamically update this parameter.
Default value: 100
Volume, value range [0, 200], default is 100. 🔁Call this interface again to dynamically update this parameter.
Label object
Watermark content.
Maximum length is 100 Chinese characters or 300 English characters.
Text watermark position, the distance from the left border of the input stream.
Text watermark position, the distance from the top border of the input stream.
Font objectrequired
Font type. Only one type can be set, and modification during Stream Mixing is not supported. Different input streams cannot have different fonts:
Font size, value range [12, 100], default is 24.
Font color, default is RGB(255, 255, 255), i.e., white.
The calculation formula for this parameter is R + G × 256 + B × 65536, where R (red), G (green), and B (blue) have value ranges [0, 255].
Font transparency, value range [0, 100], default is 100.
The larger the parameter value, the more transparent it is, i.e., 0 means opaque, 100 means fully transparent.
Font outline color, default is no font outline. After filling in this parameter, the font will have an outline.
The calculation formula for this parameter is R + G × 256 + B × 65536, where R (red), G (green), and B (blue) have value ranges [0, 255].
Possible values: [0, 1]
Stream Mixing input fill mode.
🔁Call this interface again to dynamically update this parameter.
The User ID corresponding to the input stream, which will appear in the SEI. The length should be less than 64 bytes.
Before using this field, you need to contact ZEGOCLOUD technical support to enable the configuration of enable_layout_in_idr.
🔁Call this interface again to dynamically update this parameter.
MixOutput object[]required
Output Stream ID. By default, it indicates Stream Mixing output to the RTC or low-latency live streaming product. You can also contact ZEGOCLOUD technical support to configure Stream Mixing output to the ZEGOCLOUD proxy CDN live streaming product, with the effective scope being the entire AppId. If you wish to control the output of a specific stream to the CDN live streaming product, you cannot configure the default Stream Mixing output to ZEGOCLOUD proxy CDN, and should set StreamUrl as needed.
Either StreamId or StreamUrl can be used. If both StreamId and StreamUrl are filled in, StreamUrl will take effect.
🔁Call this interface again to dynamically update this parameter.
Only supports RTMP protocol, indicating Stream Mixing output to the CDN live streaming service. Viewers can pull the Stream Mixing stream from the CDN live streaming.
Either StreamId or StreamUrl can be used. If both StreamId and StreamUrl are filled in, StreamUrl will take effect.
🔁Call this interface again to dynamically update this parameter.
Video bitrate, value must be greater than 0, in bps. For example, when the input resolution is 360*640, this parameter for the output stream is set to 1200000 bps.
For pure audio Stream Mixing, it is recommended to fill in 1. Supports real-time updates during Stream Mixing.
🔁Call this interface again to dynamically update this parameter.
Output video encoding:
Please note:
🧊This parameter does not support dynamic updates after Stream Mixing has started.
Video frame rate. For pure audio Stream Mixing, it is recommended to fill in 1.
The maximum frame rate for Stream Mixing output is limited to within 20 frames by default. If you need to output a higher frame rate, please contact ZEGOCLOUD technical support for configuration.
🧊This parameter does not support dynamic updates after Stream Mixing has started.
Width, range [0, 3000], value must be a multiple of 2.
For pure audio Stream Mixing, it is recommended to fill in 1. Supports real-time updates during Stream Mixing.
🔁Call this interface again to dynamically update this parameter.
Height, range [0, 3000], value must be a multiple of 2.
For pure audio Stream Mixing, it is recommended to fill in 1. Supports real-time updates during Stream Mixing.
🔁Call this interface again to dynamically update this parameter.
Audio encoding and sample rate. To modify the sample rate, please contact ZEGOCLOUD technical support for configuration:
Attention
If using CDN recording, please select AAC-LC for audio encoding. This is because some browsers (such as Google Chrome and Microsoft Edge) are not compatible with the HE-AAC audio encoding format, which will cause the recording file to fail to play.
🧊This parameter does not support dynamic updates after Stream Mixing has started.
Stream Mixing output audio bitrate. When not filled in, the default value is 48000, in bps.
🧊This parameter does not support dynamic updates after Stream Mixing has started.
Output audio channel count, with higher priority than global parameters:
🧊This parameter does not support dynamic updates after Stream Mixing has started.
ExtraLayers object[]
When VideoEncId is 4 (H264 SVC), this field is required and must have a length of 1.
🔁Call this interface again to dynamically update this parameter and all sub-properties.
Video bitrate for the base layer (small resolution).
Value must be greater than 0, generally set to 25% of the video bitrate for the enhancement layer (large resolution), in bps.
Whether to enable the "HD low bitrate" feature:
Currently, the "HD low bitrate" feature requires contacting ZEGOCLOUD technical support to enable permission, and it only takes effect when VideoEncId is 3 (H265).
🧊This parameter does not support dynamic updates after Stream Mixing has started.
TargetRoom object
🧊This parameter does not support dynamic updates after Stream Mixing has started.
Target Room ID. If the Room ID does not exist, the addition will fail.
The User ID used when adding the output stream to the target Room.
The sequence number of the Stream Mixing request, used to ensure timing. Parameter modifications for the same task need to ensure the sequence number is incremented. 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.
🔁Call this interface again to dynamically update this parameter.
Room ID. 🔁Call this interface again to dynamically update this parameter.
Custom user data. When using this parameter, the content needs to be base64 encoded. Length limit is 4000 bytes, recommended not to exceed 850 bytes.
Custom user data will be transmitted to the pulling party as SEI information. The pulling party can obtain this data by listening to the client's onPlayerSyncRecvSEI callback.
🔁Call this interface again to dynamically update this parameter.
Possible values: [0, 1]
Attention
In video scenarios, it is not recommended to enable the sound wave switch, otherwise there may be compatibility issues when pulling HLS protocol streams on the web end
Stream Mixing sound wave, referring to the volume size of the Stream Mixing. Supports real-time updates during Stream Mixing.
🔁Call this interface again to dynamically update this parameter.
Background image, supporting JPG and PNG formats. Supports the following 2 usage methods:
🔁Call this interface again to dynamically update this parameter.
Stream Mixing background color. The color value corresponds to RGBA as 0xRRGGBBAA. Currently, setting the transparency of the background color is not supported. You can set AA in 0xRRGGBBAA to 00. For example, if the RGB color is #87CEFA, the corresponding value for this parameter is 0x87CEFA00.
🔁Call this interface again to dynamically update this parameter.
WaterMark object
Watermark image, supporting JPG and PNG formats. Usage is the same as the background image BackgroundImage.
🔁Call this interface again to dynamically update this parameter.
RectInfo object
Top border. The pixel size from the top border of the output canvas.
Left border. The pixel size from the left border of the output canvas.
Bottom border. The pixel size from the top border of the output canvas.
Right border. The pixel size from the left border of the output canvas.
Possible values: [0, 1]
Single stream pass-through switch, i.e., whether to re-encode according to output parameters when there is only one input stream. This feature requires contacting ZEGOCLOUD technical support to enable:
🧊This parameter does not support dynamic updates after Stream Mixing has started.
Possible values: [1, 2]
Output audio channel count. This configuration is used when no output stream is specified:
🧊This parameter does not support dynamic updates after Stream Mixing has started.
Possible values: [0, 1, 2]
Controls whether the Stream Mixing task can be initiated normally when validation fails for the 3 image parameters of background image (BackgroundImage), input stream placeholder image (MixInput.Image.Url), and watermark image (WaterMark.Image):
This parameter only affects whether the Stream Mixing task can be initiated normally when the image parameters are set incorrectly; whether the image itself can take effect normally still needs to meet all the rules of the corresponding parameter.
🔁Call this interface again to dynamically update this parameter.
ExPara object[]
Key value.
Value.
Controls whether the played real-time audio/video stream needs to be mixed after precise alignment according to NTP (Network Time Protocol). This parameter is mainly used in KTV scenarios and will increase a certain Stream Mixing delay; for non-KTV-like scenarios, setting this parameter is not recommended.
🧊This parameter does not support dynamic updates after Stream Mixing has started.
Used to control the minimum buffer time for pulling streams (unit: milliseconds), value range [0,4000], default minimum buffer time is 0.
🧊This parameter does not support dynamic updates after Stream Mixing has started.
Whether to start publishing stream only after pulling video data:
🧊This parameter does not support dynamic updates after Stream Mixing has started.
Responses
- 200
- application/json