拉流及布局

从小鱼易连Web SDK v2.x 版本开始，SDK 的拉流方式和画面布局简化，支持翻页查看更多画面功能，方便第三方实现更丰富的布局展示效果；

此篇文档会告知你如何处理请流和控制画面布局，请详细阅读；

功能说明

SDK提供两种会议画面布局方式：自动布局（AUTO）和自定义布局（CUSTOM），方便开发者更方便自由的选择布局方式。

AUTO 模式

自动布局是指Web SDK内置了一套桌面端浏览器下布局模版配置，会实时基于人员数量和内容进行请求画面数据流和计算画面的位置和大小，通过layout 事件上报最终的数据，业务层直接使用此数据做最终的渲染即可；

从 v3.9.1 版本开始，移动端浏览器也支持自动布局模版，详细见下方模版描述；

说明

自动布局下支持的布局模式和功能：

宫格模式
演讲者模式
Content模式：缩略试图、缩略共享、共享试图、共享全试图、共享+演讲
翻页查看更多画面
主会场模式
支持桌面端和移动端不同的布局模式

桌面浏览器布局模型

桌面端浏览器布局模型如图所示：

黑色字体的 L 标识本地画面，P 标识参会者画面，红色字体的 Q 标识视频质量，P 标识优先级。

布局每页支持最多 9 人的画面显示，SDK会自动处理语音激励、主会场、基础的 Layout 成员的位置、大小、媒体流数据及其展示容器的大小计算，业务层直接监听layout事件消息使用数据即可；

移动端浏览器布局模型

移动端浏览器布局模型如图所示：

优点

可以快捷实现一页最多9画面的布局展示，超过9人只接收声音(移动端布局最多7画面)；
支持翻页查看更多参会者画面；
支持多种布局模型，可以自定义控制使用哪一种布局模型；
支持设置 Layout 展示 Container 容器配置，支持大小变化响应，可以通过 XYRTC.createClient 配置 container 容器信息；
通过 XYRTCClient.switchLayout 快速切换宫格布局和演讲者布局模式；
通过 XYRTCClient.setLayoutOrientation 设置移动端Layout画面横/竖屏布局方式；

CUSTOM 模式

说明

自定义布局此布局模式会上报会议相关的数据，第三方自行处理会议数据进行自定义布局计算，设置参会者的位置、设置画面视频分辨率、质量等；

优点

可以自定义控制人员位置、画面、分辨率、质量等数据
自定义控制参会者成员布局形式
支持翻页请求画面

实现方法

自动布局

1. 配置布局模式

在通过 XYRTC.createClient 创建客户端时，可以配置 layout 字段为 AUTO，即开启自动布局模式

const XYClient = XYRTC.createClient({
  ...
  layout: 'AUTO'
});

2. 配置布局容器

在通过 XYRTC.createClient 创建客户端时，可以配置 container 字段指定自动布局 Layout 容器信息，可选配置：

elementId：指定 Layout 显示容器，默认使用html body元素，可以指定一个 id，sdk 内部会使用此 id 所对应的元素以 16:9 比例计算 Layout 容器大小
offset：Layout 容器相对于 elementId 元素空间的偏移量，四个值分别对应：[上、下、左、右]，单位是 px

3. Layout 容器 Size 回调

监听 screen-info 回调事件，实时获取 Layout 显示容器的大小，支持屏幕和容器大小 resize 变化。CUSTOM 布局不需要监听此数据。

// AUTO模式回调数据，推送最新的Layout容器大小信息
XYClient.on('screen-info', (e: IScreenInfo) => {
  console.log('demo get screen info: ', e);
  // 更新到显示画面的容器上
})

4. Layout List 数据回调

监听 layout 回调事件，实时返回参会者布局数据。返回的列表数据直接渲染即可。 CUSTOM 布局不需要监听此数据

// 参会成员布局列表数据，包含参会者基本信息、位置、尺寸、旋转等数据
XYClient.on('layout', (e: ILayout[]) => {
  console.log('layout: ', e);
});

回调参数类型：ILayout

5. 分页查看

调用 XYRTCClient.setPageInfo 方法，用于获取翻页的画面数据

XYClient.setPageInfo(1)

函数参数类型：number

6. 分页数据监听

监听 page-info 事件，SDK 上报参会者分页数据

XYClient.on('page-info', (pageInfo: IPageInfo) => {})

回调参数类型：IPageInfo

自定义布局

如果需要进行自定义布局，处理流程如下：

1. 配置布局模式

在通过 XYRTC.createClient 创建客户端时，可以配置 layout 字段为 CUSTOM，即开启自定义布局模式。

2. 监听 conf-change-info 数据

监听 conf-change-info 事件，此数据会提供：会议成员数量、主会场uri、content uri、active speaker uri 等信息。

基于上面的数据，我们需要向小鱼媒体服务器请求指定参会者的画面数据，包含：分辨率、质量，以及控制翻页数据；

需要做如下处理：

1、基于人员总数量业务分页处理后计算一组 reqList数据，包含指定人员分辨率、质量；

2、发起 XYRTCClient.requestNewLayout 请求流操作，等待服务器响应请流结果（通过第三步监听获取结果）；

XYClient.on('conf-change-info', (e: IConfInfo) => {
  // participantCount：人员总数
  // chairManUrl：主会场uri数据
  // contentUri：分享Content的uri数据
  const { chairManUrl, contentUri, participantCount } = e;
  // 此处没有动态基于总人员和每页数量计算每次分页的实际数量，固定配置了9人
  const len = participantCount > 9 ? 9 : participantCount;

  for (let i = 0; i < len; i++) {
    const reqObj = {
      mediagroupid: 0,
      // calluri指定为空即可，如果是content共享内容，需要指定contentUri
      calluri: "",
      // content内容请求1080分辨率画面，其他画面最大请求720P
      // 此处可以根据自己的业务自控制每个人的分辨率数据，例如大屏画面可以请求高分辨画面，缩略图画面请求低分辨率画面
      resolution: 2,
      // 质量
      quality: 1,
    };

    reqList.push(reqObj);
  }

  // 调用请求流接口
  XYClient.requestNewLayout(reqList, 9, 1, [], {
    uiShowLocalWhenPageMode: false,
  });
})

回调参数类型：IConfInfo

3. 监听 custom-layout 数据

在完成第二步 XYRTCClient.requestNewLayout 请流步骤后，会触发 layout 事件回调，此列表数据是最终请求的拉流结果数据，开发者可以使用此列表数据计算每个参会者的位置、大小、旋转角度等信息，然后渲染此列表数据完成画面渲染。

// CUSTOM 自定义布局，通过 custom-layout 回调布局结果数据
// 第一步：根据【conf-change-info】回调消息的列表数据请求对应参会人员的画面数据
// 第二步：在【layout】回调消息里面，获取请求的参会人最新的布局列表数据
// 第三步：基于最新的布局列表数据，计算 position/size/rotate 等信息，计算完成后，直接渲染即可
XYClient.on('layout', (e: ILayout[]) => {
  // 此示例程序通过配置一个一组 TEMPLATE 模版数据，来计算layout container容器大小和layout item position/size/rotate 信息
  // 如果不想通过此方式实现，第三方获取到customLayoutList数据后，自行处理数据即可
  const nextTemplateRate = TEMPLATE.rate[e.length] || 0.5625;
  const { rateWidth, rateHeight } = getScreenInfo(elementId, nextTemplateRate);

  // 设置layout container容器的大小
  setScreenInfo({ rateWidth, rateHeight });

  // 计算初始layoutList数据
  // 包含计算每个参会成员的大小，位置，详见 sdk demo 程序
  nextLayoutListRef.current = calculateBaseLayoutList(e, rateWidth, rateHeight);
  // 计算屏幕旋转信息
  nextLayoutListRef.current = calculateRotate();

  // 处理完数据，执行渲染即可；
  // 此处可以参考Demo提供的Video组件展示画面；
  setLayout(nextLayoutListRef.current);
})

回调参数类型：ILayout

4. 渲染Layout

在第三步生成 Layout 列表数据后，通过框架（React/Vue等）渲染画面数据即可，此处建议使用SDK提供的Video组件进行渲染画面，方便快速集成。具体内容参见SDK Demo项目；

提示

如需快速验证功能，参考快速开始-快速通话的集成步骤，使用H5的方式集成SDK；

API 参考

2024-07-17 17:49:26

导出PDF文档