# Update layout (/en/api-reference/api-ref/cloud-recording/update-layout)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

Updates the video mixing layout of an active composite recording.

- OpenAPI: /openapi/cloud-recording/cloud-recording.en.yaml
- Operation ID: update-cloud-recording-layout
- Method: POST
- Path: /v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/updateLayout
- Endpoint: https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/updateLayout

## Servers

- https://api.sd-rtn.com

After 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 `backgroundColor` to `"#FF0000"` when starting a recording and call `updateLayout` without setting `backgroundColor` again, 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 `updateLayout` multiple times in succession, wait for the previous response before sending the next request to avoid unexpected results.


## Authorization

This endpoint requires authentication.

- `basicAuth`

## Parameters

- `Content-Type` (header, optional, string) - `application/json`.
  - Default: `application/json`
- `appid` (path, required, string) - The App ID of your project.
- For web page recording mode, enter the App ID for which the cloud recording service is enabled.
- For individual and composite recording modes, use the same App ID as the channel to be recorded. Ensure that the cloud recording service has been enabled for this App ID.
- `resourceid` (path, required, string) - The resource ID obtained from the `acquire` endpoint.
- `sid` (path, required, string) - The recording ID obtained from the `start` endpoint.
- `mode` (path, required, string) - Must be `mix`. This endpoint only supports composite recording mode.
  - Allowed: `mix`

## Request body

- `cname` (string, required) - The name of the channel to record. Must match the `cname` used in the `acquire` request.
The name of the channel being recorded.
- `uid` (string, required) - The UID used by the cloud recording service in the channel. Must match the `uid` used in the `acquire` request.
The UID used by the cloud recording service in the RTC channel.
- `clientRequest` (object, required)
  - `clientRequest.maxResolutionUid` (string) - The 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`.
  - `clientRequest.mixedVideoLayout` (integer) - Composite 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. The `maxResolutionUid` user 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 using `layoutConfig`.
    - Default: `0`
  - `clientRequest.backgroundColor` (string) - Canvas background color as an RGB hex string (e.g., `"#FF0000"` for red).
    - Default: `#000000`
  - `clientRequest.backgroundImage` (string) - URL of the canvas background image. Displayed in cropped mode: the image is scaled proportionally until the canvas is filled, and excess edges are cropped.
  - `clientRequest.defaultUserBackgroundImage` (string) - URL 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`.
  - `clientRequest.layoutConfig` (array) - Per-user screen layout settings for custom layout. Supports up to 17 users. Only applicable when `mixedVideoLayout` is `3`.
    - Max items: `17`
    - `clientRequest.layoutConfig.items` (object)
      - `clientRequest.layoutConfig.items.uid` (string) - The UID of the user assigned to this layout region. If not specified, layout regions are assigned in the order users join the channel.
      - `clientRequest.layoutConfig.items.x_axis` (number, required) - Horizontal 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.
        - Range: `[0, 1]`
      - `clientRequest.layoutConfig.items.y_axis` (number, required) - Vertical 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.
        - Range: `[0, 1]`
      - `clientRequest.layoutConfig.items.width` (number, required) - Relative width of the region (6 decimal places).
        - Range: `[0, 1]`
      - `clientRequest.layoutConfig.items.height` (number, required) - Relative height of the region (6 decimal places).
        - Range: `[0, 1]`
      - `clientRequest.layoutConfig.items.alpha` (number) - Transparency of the user's video window. `0.0` is fully transparent, `1.0` is fully opaque.
        - Default: `1`
        - Range: `[0, 1]`
      - `clientRequest.layoutConfig.items.render_mode` (integer) - Display 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.
        - Default: `0`
  - `clientRequest.backgroundConfig` (array) - Per-user background image settings.
    - `clientRequest.backgroundConfig.items` (object)
      - `clientRequest.backgroundConfig.items.uid` (string, required) - The UID of the user.
      - `clientRequest.backgroundConfig.items.image_url` (string, required) - The 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.
      - `clientRequest.backgroundConfig.items.render_mode` (integer) - Display 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.
        - Default: `0`

### Request body example

```json
{
  "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
      }
    ]
  }
}
```

## Request examples

### curl

```bash
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
        }
      ]
    }
  }'
```

### Python

```python
import requests
  import json

  url = "https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/mix/updateLayout"
  headers = {
      "Authorization": "Basic <credentials>",
      "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 = requests.post(url, headers=headers, data=json.dumps(data))

  print(response.status_code)
  print(response.json())
```

### Node.js

```javascript
const axios = require('axios');

  const url = 'https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/mix/updateLayout';
  const headers = {
    'Authorization': 'Basic <credentials>',
    'Content-Type': 'application/json'
  };

  const 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
        }
      ]
    }
  };

  axios.post(url, data, { headers })
    .then(response => {
      console.log('Status:', response.status);
      console.log('Data:', response.data);
    })
    .catch(error => {
      console.error('Error:', error.response ? error.response.data : error.message);
    });
```


### 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](/en/api-reference/api-ref/cloud-recording/status-codes) for troubleshooting.


## Responses

### 200

The request succeeded.

- `resourceId` (string) - The cloud recording resource ID. Valid for five minutes; re-request from `acquire` if expired.

The resource ID used by cloud recording.
- `sid` (string) - The recording ID. Uniquely identifies a recording session. Generated after the cloud recording service starts successfully.

The recording ID, identifying the current recording session.
- `cname` (string) - The name of the channel to be recorded.

The name of the channel being recorded.
- `uid` (string) - The UID used by the cloud recording service in the RTC channel.
### default

The request failed. If the HTTP status code is not `200`, see the Cloud Recording response status codes for troubleshooting.

No schema.

## Response examples

### 200

```json
{
  "cname": "string",
  "uid": "string",
  "resourceId": "string",
  "sid": "string"
}
```

### Response example

```json
{
    "code": 404,
    "reason": "failed to find worker"
  }
```