Tutorial: 开启视频合流插件

功能描述

本文档详细介绍了如何使用 TRTC Web SDK 的 VideoMixer 插件，将摄像头、屏幕共享、文字、图片和视频等多个输入源合成为一个视频轨道，实现自定义布局的推流。开发者可以灵活控制每个源的布局（位置、大小、层级 zIndex）。

前提条件

• TRTC Web SDK version >= 5.12.0.

• 兼容性：

  浏览器	兼容性
  PC Chrome	✅
  PC Safari	✅
  PC Firefox	✅
  PC Edge	✅
  移动端	❌暂不支持合流功能

实现流程

1. 引入并注册插件

import { VideoMixer } from 'trtc-sdk-v5/plugins/video-effect/video-mixer';
const trtc = TRTC.create({ plugins: [VideoMixer] });

2. 开启合流

通过调用 trtc.startPlugin('VideoMixer', options) 开启合流插件。您必须在 options 中设置合流画布的宽高 canvasInfo，其余参数都是可选参数。

const options = {
  view: 'local_preview_div', // 预览
  canvasInfo: { width: 1920, height: 1080 },
  camera: [{ // 添加一个摄像头输入源
      id: 'camera1',
      layout: { x: 0, y: 0, width: 640, height: 480, zIndex: 1 }
    }]
  // ...
}
const { track } = await trtc.startPlugin('VideoMixer', options);
// track 即为合流输出的 MediaStreamTrack，可用于推流

3. 合流后推流

合流插件只负责生成合流后的视频轨道，推流操作仍由 TRTC SDK 控制。将 startPlugin 返回的 track 作为参数传入 startLocalVideo 接口即可进行推流。

await trtc.startLocalVideo({ option: { 
  videoTrack: track,
  profile: { width: 1920, height: 1080, bitrate: 2000 } // 设置编码参数
}});

4. 管理输入源（更新和移除）

通过调用 trtc.updatePlugin('VideoMixer', options) 动态添加、更新或移除合流输入源。

更新规则：

• 输入源说明： 输入源分为：camera, screen, text, image, video。都是数组，每一个数组元素代表一个输入源，通过 id 属性做唯一标识。
• 更新输入源： 传入相同 id，并修改其他参数。
• 添加输入源： 传入新的 id 对象。
• 移除输入源： 从对应的输入源数组中去掉该对象。

摄像头

可以控制摄像头的采集和布局。

// 更新 id 为 'camera1' 的摄像头布局  
await trtc.updatePlugin('VideoMixer', {
  camera: [
    {
      id: 'camera1',
      profile: { width: 640, height: 480, frameRate: 15 }, // 更新摄像头采集参数
      layout: { x: 100, y: 0, width: 640, height: 480, zIndex: 1, rotation: 90, mirror: true } // 更新摄像头布局参数
    }
  ]
});
// 移除所有摄像头  
await trtc.updatePlugin('VideoMixer', { camera: [] });
// 如果只是想临时隐藏画布上的输入源，而不是物理关闭采集，可以在 layout 参数中设置 hidden: true。其他输入源同理。

屏幕共享

// 添加屏幕共享
await trtc.updatePlugin('VideoMixer', {
  screen: [{
    id: 'screen1',
    profile: { width: 1920, height: 1080, frameRate: 15 }, // 屏幕共享采集参数
    layout: {
      x: 0,
      y: 0,
      width: 1920,
      height: 1080,
      zIndex: 0,      
    }
  }],
  // 如果用户未通过 SDK 而是通过浏览器按钮取消了屏幕共享，你可以通过该回调监听
  onScreenShareStop: (id: string) => console.log(`屏幕共享已停止，id: ${id}`);
});

文字

可以添加文字输入源，text参数数组中传入一个带有唯一 id 的对象代表合流一个文字源：

注：文字内容过多时超出 layout 区域的部分会被裁剪，业务侧需根据文字内容自行调整 layout 宽高。

await trtc.updatePlugin('VideoMixer', {
  text: [
    {
      id: 'text1',
      content: 'MultiLine\nTest',
      font: 'bold 60px SimHei',
      color: 'red',
      layout: {
        x: 200,
        y: 300,
        width: 300,
        height: 150,
        zIndex: 6,
      }
    }
  ]
});

图片和视频

可添加图片（如 Logo）或本地视频文件作为合流输入源。

await trtc.updatePlugin('VideoMixer', {
  image: [{ 
    id: 'img1', 
    url: './image.png',
    layout: { x: 0, y: 500, width: 800, height: 400, zIndex: 4 }
  }],
  video: [{ 
    id: 'video1', 
    url: './video.mp4',
    layout: { x: 0, y: 0, width: 1000, height: 500, zIndex: 5 }
  }]
});

5. 关闭合流

移除所有输入源并关闭合流：

await trtc.stopPlugin('VideoMixer');

错误处理

合流插件的错误处理策略旨在保障部分输入源错误时不会影响其他正常输入源的合流。

业务侧逻辑示例：

try {
  const { result } = await trtc.updatePlugin('VideoMixer', {
    camera: [/* ... */],
    screen: [/* ... */],
    text: [/* ... */],
    image: [/* ... */],
    video: [/* ... */],
  });
  // 场景一：部分失败时的错误处理
  result.failedDetails.forEach(({id, error}: {id: string, error: any}) => {
    console.error(`${id} mix failed`, error);
  })
  console.log(result.successOptions) // 本次更新成功应用的参数
} catch (error: any) {
  // 场景二：全部失败时的错误捕获 (捕获抛出的错误)  
  console.error(error);
  error?.data?.failedDetails.forEach(({ id, error }: { id: string, error: any }) => {
    console.error(`${id} mix failed`, error);
  })  
}

关于 successOptions 的详细说明

该返回值告知业务侧本次更新后合流底层真正应用的参数。当部分更新失败时，successOptions 会包括成功更新的部分和沿用旧配置的失败部分，便于业务侧同步 UI 或数据状态。

API 说明

trtc.startPlugin('VideoMixer', options)

用于开启合流插件并初始化画布和输入源。

Options

Returns: Promise<MixParseResult>

MixParseResult

MixFailedDetail

trtc.updatePlugin('VideoMixer', options)

更新合流输入源和布局。options 结构与 startPlugin 一致，update 时 canvasInfo 不是必填项。

trtc.stopPlugin('VideoMixer')

停止合流。

核心参数结构

CanvasInfo

CameraSource

ScreenSource

TextSource

ImageSource

VideoSource

LayerOption

最佳实践与常见问题

1. 帧率与性能优化

• 帧率设置：
  • 不推荐手动设置 canvasInfo.frameRate。
  • 推荐由插件内部自动计算：当存在摄像头或屏幕分享时，取两者中的最大帧率；否则固定为 15 帧。手动指定可能导致性能损失。
• 性能考量：
  • 画布分辨率越大、合流的输入源越多，渲染开销越大。业务侧应根据用户设备性能情况，决定合适的画布参数和输入源数量。

2. 分辨率、码率怎么设置？

• 分辨率就是画布宽高
• 码率不由合流插件控制，业务侧推流时通过 startLocalVideo/updateLocalVideo 设置。

3. 为什么输入源传参都是数组形式，如果只想更新数组中某一类输入源怎么做？

• 每种类型的输入源都是全量更新的方式，目的是为了支持批量更新以及删除（通过对比前后传入的数组）。

• 每种输入源参数都是可选的，比如只想更新 camera 时，updatePlugin 时只传入 camera 数组，其他类型输入源的数组不传，或者一并传入但是保留原参数。示例如下：

  await trtc.startPlugin('VideoMixer', { // 假设已经合流了摄像头和屏幕
    camera: [/* config */],
    screen: [/* config */]
  });
  

  此时如果只想更新 camera 而不更新 screen，可以仅传入 camera，不传入 screen

  await trtc.updatePlugin('VideoMixer', {
    camera: [/* newConfig */], // 只传入camera数组
  });
  

4. 传入数组的前提下，只想更新某一个输入源怎么办？

比如更新某一个摄像头(id = 1)，那么传入的 camera 数组只改动 id = 1 的元素的参数，其他元素虽然不用更新，但是参数需要保持原样传入。

5. 采集摄像头和屏幕时设置的码率为什么无效？

采集摄像头和屏幕时设置的码率会被忽略，上行码率由业务侧推流时调用的接口（start/updateLocalVideo）设置。

6. 设置旋转角度不是围绕中心旋转？

合流旋转的原理是将画面旋转后，画面左上角仍保持 layout 传入的坐标再绘制，如果要实现中心旋转，业务侧需自行调整坐标。

7. 如果合流屏幕共享期间用户不是通过sdk而是点击浏览器的按钮停止屏幕共享，业务侧如何感知？

startPlugin 的参数中提供了onScreenShareStop回调，使用示例：

await trtc.startPlugin('VideoMixer', {
  // ...
  onScreenShareStop: (id: string) => {
    console.log(`screen share stop, id: ${id}`);
  }
});