设置合流布局

实现合流录制时，云端录制会将频道中指定用户的音视频流混合成一路，这个过程中会需要设置频道内用户视窗的大小及其在画布上的位置。如下图所示：

这个过程就是设置合流布局。在合流布局中，我们将视频的背景称为画布，每个用户的视频占据一个视窗。

功能介绍

声网云端录制支持两种合流布局的方式：

• 选择预设的合流布局样式：云端录制提供悬浮布局、自适应布局和垂直布局三种布局样式，预设用户视窗的大小和位置，无需你自行设定。你只需选择其中一种样式，就能实现预设的布局效果。
• 自定义合流布局：灵活设置用户视窗的大小，指定用户视窗在视频画布上的相对位置。

注意

• 合流视频画布上最多显示 17 个用户视窗。
• 如果某用户只发送音频，不发送视频，仍然会占据一个视窗。
• 如果原视频的宽高比和布局中用户视窗的宽高比不一致，可能出现裁剪或压缩。用户视窗的宽高比取决于视频画布的长宽比以及合流布局方式。

本文具体介绍这两种合流布局的样式，以及如何在使用云端录制服务时设置合流布局。

选择预设的合流布局

如何选择预设的合流布局，在开始云端录制及录制过程中，你都可以通过 RESTful API 设置或更新合流布局：

• 开始云端录制时设置：通过 start 请求 Body 中 clientRequest.recordingConfig.transcodingConfig 里的 mixedVideoLayout 字段。
• 在录制过程中设置：通过 updateLayout 请求 Body 中 clientRequest.mixedVideoLayout 字段。

云端录制提供三种预设的合流布局样式：

• 悬浮布局：mixedVideoLayout 为 0。
• 自适应布局：mixedVideoLayout 为 1。
• 垂直布局：mixedVideoLayout 为 2。

各布局样式效果如下文。

信息

下列布局示例中的数字表示用户加入频道的顺序。如果用户 1 退出频道，用户 2 会占据用户 1 的视窗，依次替补。

悬浮布局

默认布局方式（mixedVideoLayout 设为 0）。第一个加入频道的用户在屏幕上会显示为大视窗，铺满整个画布；其他用户按照加入的顺序从画布左下角开始依次水平排列，显示为小视窗，最多 4 行，每行 4 个视窗。小视窗会悬浮在大视窗上面。

对于悬浮布局，有以下注意事项：

• 如果某用户只发送音频，仍然会占据布局位，显示大视窗视窗。
• 如果实际视频流的宽高比与视窗的宽高比不一致，视频会裁剪以适配视窗的大小。
• 每个小视窗的宽和高分别为整个画布宽和高的 0.235，相邻小视窗的左右和上下间距分别为整个画布宽和高的 0.012。小视窗距离画布的水平和垂直边距也分别为整个画布宽和高的 0.012。

不同人数的实际布局效果如下所示。

自适应布局

布局样式会根据频道人数自适应（mixedVideoLayout 设为 1）。每个用户视窗平铺在画布上，大小一致。

对于自适应布局，有以下注意事项：

• 在下面不同人数的合流布局下，如果频道中人数不足，则剩余的布局位置会空着，显示背景色。
• 如果某用户只发送音频，仍然会占据布局，显示背景色。
• 如果实际视频流的宽高比与视窗的宽高比不一致，视频视窗会裁剪以适配视窗的大小。

不同人数的实际布局效果如下所示。

17 人的视窗布局与上面的情况不同，用户视窗没有铺满整个画布：每个用户视窗的宽和高分别为总宽度和总高度的 0.2，前四行每行四个用户，画布左右边距均为总宽度的 0.1。第五行居中显示第 17 个用户视窗。

垂直布局

如果你选择了垂直布局（mixedVideoLayout 设为 2），则需要指定一个 UID 作为大视窗视窗。在开始云端录制时或调用 updateLayout 方法时传入 maxResolutionUid 字段指定。其中：

大视窗视窗显示你在 maxResolutionUid 中指定的用户的视频。

• 如果未指定或者指定用户未进入频道，大视窗视窗区域显示背景色。
• 如果实际视频流的宽高比与视窗的宽高比不一致，视频视窗会缩放以保证视频的完整性。

小视窗视窗的排列顺序，是按照加入频道的时间先后顺序。

• 如果用户 small1 退出频道，用户 small2 会占据用户 small1 的视窗，依次替补。
• 如果实际视频流的宽高比与视窗的宽高比不一致，视频会裁剪以适配视窗的大小。

不同人数下实际布局效果如下图所示。

信息

• 下图中，若频道中人数不足，则剩余的布局位置会空着，显示背景色。
• 如果某用户只发送音频，仍然会占据布局位，显示背景色。

人数（人）	布局效果	说明
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	（选填）字符串内容为待显示在该视窗上的用户的 UID，例如 "527841"。如果不指定 UID，会按照用户加入频道的顺序自动匹配 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 设字段设置用户视窗的相对宽度和相对高度，即用户视窗的宽度和高度占画布的宽度和高度的比例。如下图所示：

  
  注意

  请确保 x_axis + width <= 1，且 y_axis + height <= 1。

下面结合示例代码来介绍在实际场景中如何设置 layoutConfig 字段。

假设直播间中有 1 个主播，2 个连麦者。主播的 UID 是确定的，但连麦者的 UID 会经常变化。因此我们可以在开始录制时设置 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 方法更新录制合流布局。

需要注意的是，调用该方法传入字段会覆盖原来的布局设置。举例来说，如果你在开始录制时设置了 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 字段（某个 UID 的背景图）
  • defaultUserBackgroundImage （默认的用户视窗背景图）
  • backgroundImage （画布背景图）
  • backgroundColor （画布背景色）
• 如果某个 UID 中途离开频道，该用户视窗的变化规则参考合流录制中的开发注意事项。

开发注意事项

• 选填的字段如果没有填写，会自动填入默认值。
• 字段 mixedVideoLayout 和 layoutConfig 的设置互相影响。
  • mixedVideoLayout 不为 3 时，填入 layoutConfig 会报错。
  • mixedVideoLayout 为 3 时，不填 layoutConfig 会报错。

参考信息

相关文档

在合流录制过程中，你还可以参考如下文档：

• 实现合流录制
• 设置输出视频属性

API 参考

你可以参考以下方法了解字段详情：

• start
• updateLayout