Stream Mixing
Stream mixing refers to the on-demand combination of multiple audio and video streams in a room, controlling the output parameters of the mixed stream.
Using the server API for stream mixing, you can configure the following:
- Select anchor video streams for mixing, determining which anchors viewers can see or hear in the final output
- Configure the layout of the live stream, i.e., the arrangement of multiple video feeds on the viewer's end
- Manage the resolution of the mixed stream output
- Control the effect and positioning of watermarks (text or images)
Request Method
POST: https://data center domain/rtc/mcu/config.json
Signature Rule: All requests to RC's server API require signature verification. See API Request Signature for details.
Request Body Parameters
The HTTP request body contains a JSON object with the following structure:
| Parameter | Type | Description |
|---|---|---|
| sessionId | String | (Required) The conversation ID for stream mixing configuration, obtainable via server callback. See Room Status Update Callback. |
| config | Object | JSON-formatted data containing all layout-related parameters. |
| config.mode | Number | Stream mixing layout mode, controlling how multiple video feeds are arranged. Options:
|
| config.version | Number | Configuration version number, defaults to 1. |
| config.host_user_id | String | The user ID of the primary video stream publisher. Leave empty ("") when using custom layout (config.mode = 1).
|
| config.host_stream_id | String | The stream ID of the primary video. Leave empty ("") when using custom layout (config.mode = 1).
|
| config.output | Object | Specifies output parameters for the mixed stream, including video (video) and audio (audio) configurations. See config.output Object Details below. |
| config.customMode | Bool | (Deprecated) Use inputFilterMode instead. |
| config.inputFilterMode | Number | Controls MCU stream mixing resources.
|
| config.input | Object | Specifies input configurations for participant streams, including video (video) and audio (audio) arrays. See config.input Object Details below. |
| config.waterMark | Object | Configures watermarks for the mixed stream, supporting image/text/timestamp watermarks on the entire canvas or individual streams. See config.waterMark Object Details. |
-
config.output Object Details: Describes video/audio output parameters.
Parameter Type Description video Object Configures the mixed video output, including standard stream ( normal), small stream (tiny), cropping mode, background color, and background image settings.video.normal Object Standard video stream (HD) output configuration. video.normal.width Number Width of the standard mixed video output. video.normal.height Number Height of the standard mixed video output. video.normal.fps Number Frame rate of the standard mixed video output. video.normal.bitrate Number Bitrate of the standard mixed video output (kbps). Recommended values: - 640X360: 800
- 480X480: 800
- 640X480: 900
- 1280X720: 2500
- 1920X1080: 4000
video.tiny Object (Optional) Small video stream output configuration. Defaults to 180x320 if unspecified. video.tiny.width Number Width of the small mixed video output. video.tiny.height Number Height of the small mixed video output. video.tiny.fps Number Frame rate of the small mixed video output. video.tiny.bitrate Number Bitrate of the small mixed video output (kbps). video.exparams Object Additional video output settings, including cropping mode ( renderMode).video.exparams.renderMode Number 1: Crop;2: No crop.video.backgroundColor String Background color (e.g., "0xf1a2c3"). Retains last setting if unspecified. video.backgroundPicture Object Background image configuration. See video.backgroundPicture Object Details. audio Object Audio output configuration, including bitrate ( bitrate).audio.bitrate Number Audio bitrate (kbps). -
video.backgroundPicture Object Details: Background image settings.
Parameter Type Description enable String Enable/disable background image. offdisables;onor unspecified enables.fillMode String Image fill mode. 1: Crop proportionally.2: Compress proportionally without cropping.picture Array of Objects Background image settings array. picture[i].uri String Image URL (PNG format only; JPG conversions to PNG are invalid). picture[i].x Number X-coordinate (0.0-1.0) relative to canvas width. picture[i].y Number Y-coordinate (0.0-1.0) relative to canvas height. picture[i].w Number Display width (0.0-1.0), where 1 = full canvas width. picture[i].h Number Display height (0.0-1.0), where 1 = full canvas height. Images scale proportionally. Example: For a 500x500 PNG with w=0.5, h=0.2 on a 640x480 canvas, the display area is 320x96 pixels, showing a 96x96 watermark.
-
config.input Object Details: Specifies input streams and custom layout coordinates.
Parameter Type Description video Array of objects Array of video streams to mix, including base info and (for custom layout) view coordinates. video[i].user_id String (Required) Publisher's user ID. Must be valid. video[i].stream_id String (Required) Publisher's stream ID. Must be valid.
Obtainable via Room Status Update Callback. Corresponds tomsidwheremediaType= 1.video[i].x Number X-offset of sub-view's top-left corner (pixels). Cannot exceed canvas width.
Required only for custom layout (config.mode= 1).video[i].y Number Y-offset of sub-view's top-left corner (pixels). Cannot exceed canvas height.
Required only for custom layout (config.mode= 1).video[i].width Number Sub-view width (pixels). x + width ≤ canvas width.
Required only for custom layout (config.mode= 1).video[i].height Number Sub-view height (pixels). y + height ≤ canvas height.
Required only for custom layout (config.mode= 1).audio Array of objects Array of audio streams to mix. audio[i].user_id String Publisher's user ID. audio[i].stream_id String Audio stream ID.
Obtainable via Room Status Update Callback. Corresponds tomsidwheremediaType= 0. -
config.waterMark Object Details: Watermark configurations for pre/post-mixing.
Parameter Type Description waterMark.enable Bool Watermark toggle. waterMark.mixScreen Object Watermark settings for the entire mixed canvas. waterMark.mixScreen.timestamp Object Timestamp watermark for the mixed canvas. See Timestamp Watermark Details. waterMark.mixScreen.text Array of Objects Text watermark for the mixed canvas. See Text Watermark Details. waterMark.mixScreen.picture Array of Objects Image watermark for the mixed canvas. See Image Watermark Details. waterMark.singleScreen Array of Objects Per-stream watermark configurations. waterMark.singleScreen[i].steamId String Stream ID.
Obtainable via Room Status Update Callback. Corresponds tomsidwheremediaType= 1.waterMark.singleScreen[i].timestamp Object Timestamp watermark for a single stream. See Timestamp Watermark Details. waterMark.singleScreen[i].text Array of Objects Text watermark for a single stream. See Text Watermark Details. waterMark.singleScreen[i].picture Array of Objects Image watermark for a single stream. See Image Watermark Details. -
Timestamp Watermark Details:
timestampobject parameters.Parameter Type Description timestamp Object Timestamp watermark configuration. timestamp.timezone Number Timezone offset. timestamp.fontSize Number Font size (pixels). timestamp.color String Font color: blackorwhite.timestamp.alpha Number Opacity (0.0-1.0). timestamp.x Number X-coordinate (0.0-1.0), where 1 = full width. timestamp.y Number Y-coordinate (0.0-1.0), where 1 = full height. -
Text Watermark Details:
textarray parameters.Parameter Type Description text Array of Objects Text watermark configuration. text[i].content String Text content. text[i].fontSize Number Font size (pixels). text[i].color String Font color: blackorwhite.text[i].alpha Number Opacity (0.0-1.0). text[i].x Number X-coordinate (0.0-1.0). text[i].y Number Y-coordinate (0.0-1.0). -
Image Watermark Details:
picturearray parameters.Parameter Type Description picture Array of Objects Image watermark configuration. picture[i].uri String Image URL (PNG format only; JPG conversions to PNG are invalid). picture[i].x Number X-coordinate (0.0-1.0). picture[i].y Number Y-coordinate (0.0-1.0). picture[i].w Number Display width (0.0-1.0), where 1 = full width. picture[i].h Number Display height (0.0-1.0), where 1 = full height. Images scale proportionally. Example: For a 500x500 PNG with w=0.5, h=0.2 on a 640x480 canvas, the display area is 320x96 pixels, showing a 96x96 watermark.
-
JSON Example
{
"sessionId":"aaa",
"config":{
"version": 2,
"mode": 1/2/3, // 1: Custom, 2: Floating (default), 3: Adaptive
"host_user_id": "001",
"host_stream_id":"111_RongCloudRTC", // Primary stream for layout
"output": {
"video": {
"normal": {
"width": 360,
"height": 640,
"fps": 25,
"bitrate": 800, //kbps
},
"exparams": {
"renderMode":1 //1: Crop, 2: No crop
},
"backgroundColor":"0xf1a2c3", // Retains last setting if unspecified
"backgroundPicture" : { // Retains last setting if unspecified
"enable":"on", // off: Disable, on/unspecified: Enable
"fillMode" : 1, // 1: Crop proportionally, 2: Compress proportionally
"picture" : [
{
"uri" : "http://aaa.png", // PNG URL
"x" : 0.0, // X-coordinate
"y" : 0.0, // Y-coordinate
"w" : 1.0, // Width (0.0-1.0)
"h" : 1.0 // Height (0.0-1.0)
},
{
"uri" : "http://bbb.png",
"x" : 0.5,
"y" : 0.5,
"w" : 0.5,
"h" : 0.5
}
]
}
},
"audio": {
"bitrate": 200, //kbps
}
},
"inputFilterMode":4,
"input": {
"video": [
{
"user_id": "111",
"stream_id":"111_RongCloudRTC", // "RongCloudRTC" indicates standard camera stream
"x":0,
"y":0,
"width":180,
"height":320
},
{
"user_id": "2222",
"stream_id":"2222_screenshare",
"x":180,
"y":320,
"width":180,
"height":320
}
],
"audio":[
{
"user_id":"111",
"stream_id":"111_RongCloudRTC"
},
{
"user_id":"2222",
"stream_id":"2222_RongCloudRTC"
}
]
},
"waterMark": {
"enable":"on", // off: Disable, on/unspecified: Enable
"mixScreen": {
"timestamp": {
"fontSize": 30,
"timezone": 8,
"x": 0.1,
"y": 0.1,
"alpha": 0.8,
"color": "black"
},
"text": [{
"alpha": 1,
"color": "white",
"x": 0.1,
"y": 0.2,
"content": "abcde",
"fontSize": 30
},
{
"alpha": 0.2,
"color": "black",
"x": 0.3,
"y": 0.5,
"content": "hello, world",
"fontSize": 20
}
],
"picture": [{
"uri": "https://aaa",
"w": 0.1,
"h": 0.1,
"x": 0.1,
"y": 0.2
},
{
"uri": "https://ccc",
"w": 0.6,
"h": 0.6,
"x": 0.2,
"y": 0.2
}
]
},
"singleScreen": [{
"streamId": "stream1_RongCloudRTC",
"timestamp": {
"alpha": 0.8,
"color": "black",
"fontSize": 30,
"timezone": 8,
"x": 0.1,
"y": 0.1
}
},
{
"streamId": "stream2_RongCloudRTC",
"picture": [{
"uri": "https://ccc",
"w": 0.1,
"h": 0.1,
"x": 0.2,
"y": 0.3
}]
}
]
}
}
}
Response
The HTTP response body contains a JSON object with the following structure:
code: Business status code.200indicates success.
{
"code":404,
"errorMessage": "Not a valid API"
}