布局参数说明

在使用RESTful API开启云端录制和CDN推流时都有一个layout参数，用于设置视频合流布局。
本文对该参数进行详细说明。

默认布局

layout参数为空时使用下面的默认布局：

{
  "mode": 0,
  "scale": 0,
  "canvas": {
    "width": 1280,
    "height": 720,
    "color": "#000000"
  }
}

布局参数

{
  "mode": <int>,            // 0-gallery, 1-floating, 2-speaker, 3-custom
  "scale": <int>,           // 0-aspectFit, 1-aspectFill, 2-fill
  "canvas": {               // background
    "width": 1280,
    "height": 720,
    "color": "#000000",     // RGB
  }
}

参数说明：

这些参数必须同时配置，如果缺失或配置错误，服务器将采用默认布局。

• mode - 值为int，用于表示布局模式，Pano预定义了3种布局，也支持客户自定义布局：
  • mode = 0，画廊模式，即两分格、四分格、九宫格等
  • mode = 1，悬浮模式，主画面全屏，小画面横排或竖排悬浮在主画面上
  • mode = 2，演讲者模式，主画面大图，小画面横排或竖排在画布侧面，与主画面不重叠
  • mode = 3，自定义布局
• scale - 值为int，表示图片缩放模式：
  • scale = 0，aspectFit，保持原有长宽比缩放，图片显示在目标区域中间
  • scale = 1，aspectFill，保持原有长宽比缩放，填满目标区域, 超出部分会被截断
  • scale = 2，fill，缩放图片，图片完整显示在目标区域，但是图片会被拉伸，长宽比会变
• canvas - 背景画布大小与底色，画布最大可以为1920*1080，超过的话Pano会使用1080P作为画布大小

画廊模式

参数示例：

{
  "mode": 0,
  "scale": <int>,
  "canvas": {
    "width": 1280,
    "height": 720,
    "color": "#000000",
  }
}

效果示意图：

说明：

• 纯音频参与者不占位。
• 竖屏最多支持9画面，横屏最多支持16画面，超过的画面不显示。
• 如果画面数不足以充满某一档位，则剩余的位置留空。例如，竖屏7画面，则8、9号位留空。

悬浮模式

参数示例：

{
  "mode": 1,
  "scale": <int>,
  "canvas": {
    "width": 1280,
    "height": 720,
    "color": "#000000",
  }
}

效果示意图：

说明：

• 纯音频参与者不占位。
• 1号位主画面始终全屏显示(画面数大于1时，主画面会被部分覆盖)。
• 竖屏最多支持9画面，横屏最多支持17画面，超过的画面不显示。
• 如果画面数不足以充满某一档位，则剩余的位置留空。例如，竖屏7画面，则8、9号位留空。
• 小画面尺寸：
  • 竖屏双画面：小画面的宽高是画布的1/3
  • 竖屏3-4画面：小画面的宽高是画布的1/3.5，水平和垂直间距是画布宽高的1/28
  • 竖屏5-9画面：小画面的宽高是画布的1/4
  • 横屏画面：小画面的宽高是画布的1/4.25，水平和垂直间距是画布宽高的1/85

演讲者模式

演讲者模式适用于横屏，主画面和小画面横向或纵向平铺，相互不重叠，并且保持宽高比一致。

参数示例：

{
  "mode": 2,
  "align": <int>,        // 0-right, 1-left, 2-top, 3-bottom, 默认为right;可缺省
  "scale": <int>,
  "canvas": {
    "width": 1280,
    "height": 720,
    "color": "#000000",
  }
}

效果示意图：

说明：

• 纯音频参与者不占位。
• 小画面不会覆盖1号位主画面(主画面显示在除小画面行列外的剩余区域)。
• 右侧/左侧对齐最多支持17画面，顶部/底部对齐最多支持8画面，超过的画面不显示。
• 右侧/左侧对齐时，如果画面数不足以充满某一档位，则剩余的位置留空。
  例如，共7画面，则8、9号位留空。
• 顶部/底部对齐时，所有小画面在行内水平居中分布。
• 小画面尺寸计算公式：
  • 左侧或右侧对齐时：
    • width = canvas_width /（cell_num_per_col + col_num）
    • height = canvas_height / (cell_num_per_col)
  • 顶部或底部对齐时：
    • width = canvas_width / cell_num_per_row
    • height = canvas_height / (cell_num_per_row + 1)
  • 其中：
    • canvas_width：画布宽度
    • canvas_height：画布高度
    • cell_num_per_col：单列小画面数量
    • col_num：小画面列数
    • cell_num_per_row：单行小画面数量

自定义布局

如果预定义的布局无法满足需要，可以使用自定义布局。layout参数里可包含多个小画面设置，参数示例：

{
  "mode": 3,
  "scale": <int>,
  "canvas": {
    "width": 1280,
    "height": 720,
    "color": "#000000",
  },
  "customModeCells":[
      {
          "userId": "123",
          "streamType": 0, 
          "x": 0,
          "y": 0,
          "width": 0.5,
          "height": 1,
          "zOrder": 0
      },
      {
          "sequence": 1,
          "streamType": 0, 
          "x": 0.5,
          "y": 0,
          "width": 0.5,
          "height": 1,
          "zOrder": 0
      }
  ]
}

参数说明：

• userId、sequence、whiteboardId - （三者选其一）通过指定用户userId、加入频道顺序或者白板id，确定画面待显示的用户和视频流类型
  • userId 值为string，表示显示在该画面上用户的userId，结合streamType可以具体对应到用户的某个特定视频流（视频或屏幕共享）
  • sequence 值为int，如果在设置布局的时候，无法确定画面要显示的用户userId，可以按照用户加入频道顺序自动排列。sequence是用户加会的顺序，从1开始递增。1表示第一个加入的用户，2表示第二个加入频道的用户。这种方式下，streamType只支持视频，也就是只能通过加会顺序排列用户的视频，显示屏幕共享可以仍通过userId+streamType。
  • whiteboardId 值为string，表示白板的唯一id，画面会显示对应白板渲染后的图像。
  • 单个画面不能同时设定userId、sequence和whiteboardId。多个画面可以用不同的方式显示，比如，画面1和2指定userId1和userId2，画面3和4指定sequence1和sequence2，最终画面1和2分别会显示userId1和userId2用户，画面3和4会按照其他用户加入频道顺序显示第一和第二的用户
• streamType - （可选）值为int，表示显示的视频流类型， 0-视频，1-屏幕共享, 2-白板, 3-任意类型，可以显示视频、屏幕共享和白板。默认为视频，可缺省。
• x - （必填）值为float，表示画面左上角在画布中的横坐标相对值，取值范围是[0.0, 1.0], 0.0表示画布的最左端，1.0是画布的最右端
• y - （必填）值为float，表示画面左上角在画布中的纵坐标相对值，取值范围是[0.0, 1.0], 0.0表示画布的最上端，1.0是画布的最底端
• width、height - （必填）值为float，画面宽高的相对值，取值范围是[0.0, 1.0]。比如，width值是0.5，该画面的实际宽度是画布宽度的一半
• zOrder - （可选）值为int，图层堆叠顺序。如果画面有重叠，通过zOrder可设置画面堆叠的顺序。拥有更大堆叠顺序的画面会覆盖堆叠顺序较小的画面。

上面示例的效果示意图如下：

我们在custom_layout_samples项目，提供了一些自定义布局实现示例，用户可以参考定制自己的布局。

画面排列顺序

1. 首先根据视频流类型排列，优先级：content share > whiteboard > video
2. 在录制、推流的RESTful API参数里有一个userId参数表示主讲人，如果userId不为空，则userId对应的画面为主画面，否则第一个加会的人为主画面
3. 如果有多个video，根据对应用户的加会顺序依次排列