# 设置合流布局 (/zh-CN/realtime-media/cloud-recording/build/recording-modes/mix-mode/set-composite-layout)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
[实现合流录制](/zh-CN/realtime-media/cloud-recording/build/recording-modes/mix-mode/set-composite)时，云端录制会将频道中指定用户的音视频流混合成一路，这个过程中会需要设置频道内用户**视窗**的大小及其在**画布**上的位置。如下图所示：
这个过程就是**设置合流布局**。在合流布局中，我们将视频的背景称为**画布**，每个用户的视频占据一个**视窗**。
## 功能介绍 [#功能介绍]
声网云端录制支持两种合流布局的方式：
- [选择预设的合流布局样式](#选择预设的合流布局)：云端录制提供悬浮布局、自适应布局和垂直布局三种布局样式，预设用户视窗的大小和位置，无需你自行设定。你只需选择其中一种样式，就能实现预设的布局效果。
- [自定义合流布局](#自定义合流布局)：灵活设置用户视窗的大小，指定用户视窗在视频画布上的相对位置。
:::warning[注意]
- 合流视频画布上最多显示 17 个用户视窗。
- 如果某用户只发送音频，不发送视频，仍然会占据一个视窗。
- 如果原视频的宽高比和布局中用户视窗的宽高比不一致，可能出现裁剪或压缩。用户视窗的宽高比取决于视频画布的长宽比以及合流布局方式。
:::
本文具体介绍这两种合流布局的样式，以及如何在使用云端录制服务时设置合流布局。
## 选择预设的合流布局 [#选择预设的合流布局]
如何选择预设的合流布局，在开始云端录制及录制过程中，你都可以通过 RESTful API 设置或更新合流布局：
- 开始云端录制时设置：通过 `start` 请求 Body 中 `clientRequest.recordingConfig.transcodingConfig` 里的 `mixedVideoLayout` 字段。
- 在录制过程中设置：通过 `updateLayout` 请求 Body 中 `clientRequest.mixedVideoLayout` 字段。
云端录制提供三种预设的合流布局样式：
- 悬浮布局：`mixedVideoLayout` 为 `0`。
- 自适应布局：`mixedVideoLayout` 为 `1`。
- 垂直布局：`mixedVideoLayout` 为 `2`。
各布局样式效果如下文。
:::info[信息]
下列布局示例中的数字表示用户加入频道的顺序。如果用户 1 退出频道，用户 2
会占据用户 1 的视窗，依次替补。
:::
### 悬浮布局 [#悬浮布局]
默认布局方式（`mixedVideoLayout` 设为 `0`）。第一个加入频道的用户在屏幕上会显示为大视窗，铺满整个画布；其他用户按照加入的顺序从画布左下角开始依次水平排列，显示为小视窗，最多 4 行，每行 4 个视窗。小视窗会悬浮在大视窗上面。
对于悬浮布局，有以下注意事项：
- 如果某用户只发送音频，仍然会占据布局位，显示大视窗。
- 如果实际视频流的宽高比与视窗的宽高比不一致，视频会裁剪以适配视窗的大小。
- 每个小视窗的宽和高分别为整个画布宽和高的 0.235，相邻小视窗的左右和上下间距分别为整个画布宽和高的 0.012。小视窗距离画布的水平和垂直边距也分别为整个画布宽和高的 0.012。
不同人数的实际布局效果如下所示。
### 自适应布局 [#自适应布局]
布局样式会根据频道人数自适应（`mixedVideoLayout` 设为 `1`）。每个用户视窗平铺在画布上，大小一致。
对于自适应布局，有以下注意事项：
- 在下面不同人数的合流布局下，如果频道中人数不足，则剩余的布局位置会空着，显示背景色。
- 如果某用户只发送音频，仍然会占据布局，显示背景色。
- 如果实际视频流的宽高比与视窗的宽高比不一致，视频视窗会裁剪以适配视窗的大小。
不同人数的实际布局效果如下所示。
17 人的视窗布局与上面的情况不同，用户视窗没有铺满整个画布：每个用户视窗的宽和高分别为总宽度和总高度的 0.2，前四行每行四个用户，画布左右边距均为总宽度的 0.1。第五行居中显示第 17 个用户视窗。
### 垂直布局 [#垂直布局]
如果你选择了垂直布局（`mixedVideoLayout` 设为 `2`），则需要指定一个用户 ID 作为大视窗。在开始云端录制时或调用 `updateLayout` 方法时传入 `maxResolutionUid` 字段指定。其中：
大视窗显示你在 `maxResolutionUid` 中指定的用户的视频。
- 如果未指定或者指定用户未进入频道，大视窗区域显示背景色。
- 如果实际视频流的宽高比与视窗的宽高比不一致，视频视窗会缩放以保证视频的完整性。
小视窗的排列顺序是按照加入频道的时间先后顺序。
- 如果用户 `small1` 退出频道，用户 `small2` 会占据用户 `small1` 的视窗，依次替补。
- 如果实际视频流的宽高比与视窗的宽高比不一致，视频会裁剪以适配视窗的大小。
不同人数下实际布局效果如下图所示。
:::info[信息]
- 下图中，若频道中人数不足，则剩余的布局位置会空着，显示背景色。
- 如果某用户只发送音频，仍然会占据布局位，显示背景色。
:::
| 人数（人） | 布局效果 | 说明 |
| --- | --- | --- |
| 1 |  | 若未设置 `maxResolutionUid`，1 人的布局样式是铺满全屏。若设置了 `maxResolutionUid`，但该用户还未加入频道，其他用户加入频道时按照 1-5 人的布局展示在右侧。 |
| 2-5 |  | 你可以指定用户作为大视窗 1，频道内其他用户按照加入频道的时间顺序显示为视窗 2-5。右侧小视窗宽度占总宽度的 1/5，高度占总高度的 1/4。 |
| 6-7 |  | 你可以指定用户作为大视窗 1，频道内其他用户按照加入频道的时间顺序显示为视窗 2-7。右侧小视窗宽度占总宽度的 1/7，高度占总高度的 1/6。 |
| 8-9 |  | 你可以指定用户作为大视窗 1，频道内其他用户按照加入频道的时间顺序显示为视窗 2-9。右侧小视窗宽度占总宽度的 1/9，高度占总高度的 1/8。 |
| 10-17 |  | 你可以指定用户作为大视窗 1，频道内其他用户按照加入频道的时间顺序显示为视窗 2-17。右侧小视窗宽度占总宽度的 1/10，高度占总高度的 1/8。 |
## 自定义合流布局 [#自定义合流布局]
除使用预设的合流布局外，你还可以根据业务场景自定义合流布局，灵活设置用户视窗的大小，指定用户视窗在视频画布上的相对位置。
### 开始录制时自定义合流布局 [#开始录制时自定义合流布局]
获取 Resource ID 后，调用 `start` 方法开始录制时在 `clientRequest.recordingConfig.transcodingConfig` 中传入 `mixedVideoLayout` 和 `layoutConfig` 字段。这两个字段的具体位置如下：
```json
{
......
"clientRequest": {
.......
"recordingConfig": {
........
"transcodingConfig": {
.......
"mixedVideoLayout": 3
"layoutConfig":[
{
........
}]
}
},
.......
}
}
```
其中：
- `mixedVideoLayout` 字段设为 `3`，表示使用自定义布局样式。
- `layoutConfig` 是一个由多个用户视窗设置组成的数组，最多可以设置 17 个用户视窗。`layoutConfig` 中可以传入的字段如下：
| 字段 | 类型 | 描述 |
| :------------ | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------ |
| `uid` | String | （选填）字符串内容为待显示在该视窗上的用户 ID，例如 `"527841"`。如果不指定用户 ID，会按照用户加入频道的顺序自动匹配 `layoutConfig` 中的视窗设置。 |
| `x_axis` | Float | （必填）画布上该视窗左上角的横坐标的相对值，范围是 [0.0,1.0]。从左到右布局，0.0 在最左端，1.0 在最右端。 |
| `y_axis` | Float | （必填）画布上该视窗左上角的纵坐标的相对值，范围是 [0.0,1.0]。从上到下布局，0.0 在最上端，1.0 在最下端。 |
| `width` | Float | （必填）视窗宽度的相对值，取值范围是 [0.0,1.0]。 |
| `height` | Float | （必填）视窗高度的相对值，取值范围是 [0.0,1.0]。 |
| `alpha` | Float | （选填）视窗的透明度。取值范围是 [0.0,1.0]。0.0 表示图像为透明的，1.0 表示图像为完全不透明的。默认值为 1.0。 |
| `render_mode` | Integer | （选填）视窗显示模式，0（默认）表示裁剪模式；1 表示缩放模式。 |
其中，`x_axis` 和 `y_axis` 字段是以**视频画布左上角为原点**，设置用户视窗在视频画布上的相对位置，分别代表用户视窗左上角到原点的水平相对距离和垂直相对距离。
`width` 和 `height` 字段用于设置用户视窗的相对宽度和相对高度，即用户视窗的宽度和高度占画布宽度和高度的比例。如下图所示：
:::warning[注意]
请确保 `x_axis + width <= 1`，且 `y_axis + height <= 1`。
:::
下面结合示例代码来介绍在实际场景中如何设置 `layoutConfig` 字段。
假设直播间中有 1 个主播，2 个连麦者。主播的用户 ID 是确定的，但连麦者的用户 ID 会经常变化。因此我们可以在开始录制时设置 3 个 `layoutConfig` 实现 1 大 2 小的布局，主播占据大视窗，连麦者按照时间顺序先后进入小视窗。
```json
{
"transcodingConfig": {
"mixedVideoLayout": 3,
"backgroundColor": "#505E72",
"layoutConfig": [
{
"uid": "1",
"x_axis": 0.0,
"y_axis": 0.0,
"width": 1.0,
"height": 0.5,
"alpha": 1.0,
"render_mode": 1
},
{
"x_axis": 0.0,
"y_axis": 0.5,
"width": 0.5,
"height": 0.5,
"alpha": 1.0,
"render_mode": 1
},
{
"x_axis": 0.5,
"y_axis": 0.5,
"width": 0.5,
"height": 0.5,
"alpha": 1.0,
"render_mode": 1
}]
}
}
```
上述示例代码的效果如下：
### 录制过程中更新合流布局 [#录制过程中更新合流布局]
在录制过程中，如果频道中的用户数量、大小流或用户角色发生变化，你可以随时调用 [`updateLayout`](/zh-CN/api-reference/api-ref/cloud-recording/update-layout) 方法更新录制合流布局。
需要注意的是，调用该方法传入字段会覆盖原来的布局设置。举例来说，如果你在开始录制时设置了 `backgroundColor` 为 `"#505E72"`（蓝灰色），调用该方法更新合流布局时如果不设置 `backgroundColor` 字段，背景色会变为默认值黑色。
要更新自定义合流布局，你需要将 `clientRequest` 中的 `mixedVideoLayout` 字段设为 `3`（自定义布局），然后设置 `layoutConfig` 数组。
```json
{
"clientRequest": {
"mixedVideoLayout": 3,
"backgroundColor": "#505E72",
"layoutConfig": [
{
"uid": "1",
"x_axis": 0.0,
"y_axis": 0.1,
"width": 0.1,
"height": 0.1,
"alpha": 1.0,
"render_mode": 1
},
{
"uid": "2",
"x_axis": 0.2,
"y_axis": 0.2,
"width": 0.1,
"height": 0.1,
"alpha": 1.0,
"render_mode": 1
}]
},
}
```
## 进阶：设置背景色或背景图 [#进阶设置背景色或背景图]
你可以在调用 `start` 或 `updateLayout` 方法时设置画布或用户视窗的背景色或背景图。当某用户停止发送视频流超过 3.5 秒，视窗将切换为该背景图/背景色。
示例代码如下：
```json
{
"transcodingConfig": {
...
"backgroundColor": "#505E72",
"defaultUserBackgroundImage": "https://xx.xxx/xxx.jpg",
"backgroundConfig": [{
"uid": "16",
"image_url": "https://xx.xxx.xxx/xxx.bmp",
"render_mode": 0
},
{
"uid": "17",
"image_url": "https://xx.xxx.xxx/xxx.bmp",
"render_mode": 0
}]
}
}
```
合图效果如下：
画布上：
- 整个画布使用 `backgroundColor` 设置的 `"#505E72"`（蓝灰色）作为背景色
- 1-15 用户视窗使用 `defaultUserBackgroundImage` 字段设置的默认用户视窗背景图
- 16 和 17 用户视窗使用 `image_url` 字段设置的用户视窗背景图
在使用背景色或背景图功能时，需要关注以下开发注意事项：
- 背景色和背景图相关字段的设置会按照优先级覆盖，字段按照优先级由高到低排列如下：
- `backgroundConfig` 中的 `image_url` 字段（某个用户 ID 的背景图）
- `defaultUserBackgroundImage` （默认的用户视窗背景图）
- `backgroundImage` （画布背景图）
- `backgroundColor` （画布背景色）
- 如果某个用户 ID 中途离开频道，该用户视窗的变化规则参考合流录制中的[开发注意事项](/zh-CN/realtime-media/cloud-recording/build/recording-modes/mix-mode/set-composite#开发注意事项)。
## 开发注意事项 [#开发注意事项]
- 选填的字段如果没有填写，会自动填入默认值。
- 字段 `mixedVideoLayout` 和 `layoutConfig` 的设置互相影响。
- `mixedVideoLayout` 不为 `3` 时，填入 `layoutConfig` 会报错。
- `mixedVideoLayout` 为 `3` 时，不填 `layoutConfig` 会报错。
## 参考信息 [#参考信息]
### 相关文档 [#相关文档]
在合流录制过程中，你还可以参考如下文档：
- [实现合流录制](/zh-CN/realtime-media/cloud-recording/build/recording-modes/mix-mode/set-composite)
- [设置输出视频属性](/zh-CN/realtime-media/cloud-recording/reference/api-reference#常用视频属性)
### API 参考 [#api-参考]
你可以参考以下方法了解字段详情：
- [`start`](/zh-CN/api-reference/api-ref/cloud-recording/start)
- [`updateLayout`](/zh-CN/api-reference/api-ref/cloud-recording/update-layout)