# 设置合流布局 (/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。 不同人数的实际布局效果如下所示。 ![悬浮布局示意](https://web-cdn.agora.io/doc-cms/uploads/1715395027164-悬浮布局-all.svg) ### 自适应布局 [#自适应布局] 布局样式会根据频道人数自适应(`mixedVideoLayout` 设为 `1`)。每个用户视窗平铺在画布上,大小一致。 对于自适应布局,有以下注意事项: - 在下面不同人数的合流布局下,如果频道中人数不足,则剩余的布局位置会空着,显示背景色。 - 如果某用户只发送音频,仍然会占据布局,显示背景色。 - 如果实际视频流的宽高比与视窗的宽高比不一致,视频视窗会裁剪以适配视窗的大小。 不同人数的实际布局效果如下所示。 ![自适应布局示意](https://web-cdn.agora.io/doc-cms/uploads/1715395083965-自适应1-16人.svg) 17 人的视窗布局与上面的情况不同,用户视窗没有铺满整个画布:每个用户视窗的宽和高分别为总宽度和总高度的 0.2,前四行每行四个用户,画布左右边距均为总宽度的 0.1。第五行居中显示第 17 个用户视窗。 ### 垂直布局 [#垂直布局] 如果你选择了垂直布局(`mixedVideoLayout` 设为 `2`),则需要指定一个用户 ID 作为大视窗。在开始云端录制时或调用 `updateLayout` 方法时传入 `maxResolutionUid` 字段指定。其中: 大视窗显示你在 `maxResolutionUid` 中指定的用户的视频。 - 如果未指定或者指定用户未进入频道,大视窗区域显示背景色。 - 如果实际视频流的宽高比与视窗的宽高比不一致,视频视窗会缩放以保证视频的完整性。 小视窗的排列顺序是按照加入频道的时间先后顺序。 - 如果用户 `small1` 退出频道,用户 `small2` 会占据用户 `small1` 的视窗,依次替补。 - 如果实际视频流的宽高比与视窗的宽高比不一致,视频会裁剪以适配视窗的大小。 不同人数下实际布局效果如下图所示。 :::info[信息] - 下图中,若频道中人数不足,则剩余的布局位置会空着,显示背景色。 - 如果某用户只发送音频,仍然会占据布局位,显示背景色。 ::: | 人数(人) | 布局效果 | 说明 | | --- | --- | --- | | 1 | ![](https://web-cdn.agora.io/doc-cms/uploads/1715395183874-1r.svg) | 若未设置 `maxResolutionUid`,1 人的布局样式是铺满全屏。若设置了 `maxResolutionUid`,但该用户还未加入频道,其他用户加入频道时按照 1-5 人的布局展示在右侧。 | | 2-5 | ![](https://web-cdn.agora.io/doc-cms/uploads/1715395202904-2-5r.svg) | 你可以指定用户作为大视窗 1,频道内其他用户按照加入频道的时间顺序显示为视窗 2-5。右侧小视窗宽度占总宽度的 1/5,高度占总高度的 1/4。 | | 6-7 | ![](https://web-cdn.agora.io/doc-cms/uploads/1715395221824-6-7r.svg) | 你可以指定用户作为大视窗 1,频道内其他用户按照加入频道的时间顺序显示为视窗 2-7。右侧小视窗宽度占总宽度的 1/7,高度占总高度的 1/6。 | | 8-9 | ![](https://web-cdn.agora.io/doc-cms/uploads/1715395385699-8-9r.svg) | 你可以指定用户作为大视窗 1,频道内其他用户按照加入频道的时间顺序显示为视窗 2-9。右侧小视窗宽度占总宽度的 1/9,高度占总高度的 1/8。 | | 10-17 | ![](https://web-cdn.agora.io/doc-cms/uploads/1715395437866-10-17r.svg) | 你可以指定用户作为大视窗 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)