# 设置合流布局 (/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)