Update layout
Updated
Updates the video mixing layout of an active composite recording.
https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/updateLayoutAfter starting a composite recording, call this endpoint to update the video mixing layout.
- Each call to this endpoint overwrites all previous layout settings. For example, if you set
backgroundColorto"#FF0000"when starting a recording and callupdateLayoutwithout settingbackgroundColoragain, the background color reverts to the default value"#000000". - This endpoint is only valid within an active recording session. If the recording was not started successfully or has already ended, the request returns
404. - If you need to call
updateLayoutmultiple times in succession, wait for the previous response before sending the next request to avoid unexpected results.
Path Parameters
appidstringThe App ID of your project. Use the same App ID as the channel being recorded. Ensure that the cloud recording service has been enabled for this App ID.
resourceidstringThe resource ID obtained from the acquire endpoint.
sidstringThe recording ID obtained from the start endpoint.
modestringMust be mix. This endpoint only supports composite recording mode.
Header Parameters
Content-Typestringapplication/json.
Request Body
application/json
cnamestringThe name of the channel being recorded. Must match the cname used in the acquire request.
uidstringThe UID used by the cloud recording service in the channel. Must match the uid used in the acquire request.
clientRequestobjectmaxResolutionUidstringThe UID of the large video window in vertical layout. Must be an integer from 1 to (2³²−1), cannot be 0. Only required when mixedVideoLayout is 2.
mixedVideoLayoutintegerComposite video layout:
0: Floating layout. The first user to join fills the entire canvas; other users appear as small windows arranged horizontally from bottom to top, up to 4 rows of 4 windows (17 windows total).1: Adaptive layout. All user windows are equal in size, automatically adjusted based on user count. Supports up to 17 windows.2: Vertical layout. ThemaxResolutionUiduser appears in a large window on the left; other users are arranged in up to two columns on the right, 8 windows per column (17 windows total).3: Custom layout. Configure positions usinglayoutConfig.
backgroundColorstringCanvas background color as an RGB hex string (e.g., "#FF0000" for red).
backgroundImagestringURL of the canvas background image. Displayed in cropped mode: the image is scaled proportionally until the canvas is filled, and excess edges are cropped.
defaultUserBackgroundImagestringURL of the default background image shown when a user stops sending video for more than 3.5 seconds. Overridden if a per-UID background image is set in backgroundConfig.
layoutConfigarray<object>Per-user screen layout settings for custom layout. Supports up to 17 users. Only applicable when mixedVideoLayout is 3.
uidstringThe UID of the user assigned to this layout region. If not specified, layout regions are assigned in the order users join the channel.
x_axisnumberHorizontal coordinate of the region's upper-left corner as a relative value (6 decimal places). 0.0 is the far left, 1.0 is the far right.
y_axisnumberVertical coordinate of the region's upper-left corner as a relative value (6 decimal places). 0.0 is the top, 1.0 is the bottom.
widthnumberRelative width of the region (6 decimal places).
heightnumberRelative height of the region (6 decimal places).
alphanumberTransparency of the user's video window. 0.0 is fully transparent, 1.0 is fully opaque.
render_modeintegerDisplay mode for the user's video window:
0: Cropped mode. The window is filled; video is scaled proportionally and cropped at the edges if the aspect ratio differs.1: Fit mode. All video content is visible; the video is scaled proportionally and black borders may appear.
backgroundConfigarray<object>Per-user background image settings.
uidstringThe UID of the user.
image_urlstringThe URL of the user's background image, shown when the user stops sending video for more than 3.5 seconds. Supports HTTPS, JPG and BMP formats, maximum 6 MB. Settings take effect only after the image is successfully downloaded.
render_modeintegerDisplay mode for the background image:
0: Cropped mode. The window is filled; image is scaled proportionally and cropped at the edges if the aspect ratio differs.1: Fit mode. All image content is visible; the image is scaled proportionally and black borders may appear.
Response
-
If the returned status code is
200, the request was successful. -
If the returned status code is not
200, the request failed. See Response status codes for troubleshooting.
Response Body
The request succeeded.
cnamestringThe name of the channel to be recorded.
The name of the channel being recorded.
uidstringThe UID used by the cloud recording service in the RTC channel.
resourceIdstringThe cloud recording resource ID. Valid for five minutes; re-request from acquire if expired.
The resource ID used by cloud recording.
sidstringThe recording ID. Uniquely identifies a recording session. Generated after the cloud recording service starts successfully.
The recording ID, identifying the current recording session.
Response example
{
"code": 404,
"reason": "failed to find worker"
}
Request examples
curl --request POST \ --url https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/mix/updateLayout \ --header 'Authorization: Basic <credentials>' \ --header 'Content-Type: application/json' \ --data '{ "cname": "httpClient463224", "uid": "527841", "clientRequest": { "mixedVideoLayout": 3, "backgroundColor": "#FF0000", "layoutConfig": [ { "uid": "1", "x_axis": 0.1, "y_axis": 0.1, "width": 0.1, "height": 0.1, "alpha": 1, "render_mode": 1 }, { "uid": "2", "x_axis": 0.2, "y_axis": 0.2, "width": 0.1, "height": 0.1, "alpha": 1, "render_mode": 1 } ] } }'Response example
{ "cname": "string", "uid": "string", "resourceId": "string", "sid": "string"}