Tutorial: 插件系统总览

功能简介

TRTC Web SDK v5 提供了插件系统，支持按需加载各种音视频增强能力。插件系统的优势：

• 模块化设计：按需引入，减少主包体积
• 独立升级：插件版本独立管理，便于迭代
• 统一接口：所有插件使用相同的启动、更新、停止 API
• 灵活组合：可同时使用多个插件，满足复杂业务场景

插件列表

视频增强类

音频增强类

推流与混流类

功能扩展类

说明：

• 版本要求：使用该插件所需的 TRTC SDK 最低版本
• 套餐要求：使用该插件需开通的 TRTC 包月套餐版本，详见 包月套餐计费说明
• 静态资源：插件是否需要部署 node_modules/trtc-sdk-v5/assets 目录到 CDN

统一使用流程

1. 引入并注册插件

在创建 TRTC 实例时通过 plugins 数组注册需要使用的插件：

import TRTC from 'trtc-sdk-v5';
import { VirtualBackground } from 'trtc-sdk-v5/plugins/video-effect/virtual-background';
import { AIDenoiser } from 'trtc-sdk-v5/plugins/ai-denoiser';
const trtc = TRTC.create({ 
  plugins: [VirtualBackground, AIDenoiser],
  assetsPath: 'https://your-cdn/assets' // 如果插件需要静态资源
});

2. 开启插件

使用 trtc.startPlugin(pluginName, options) 开启插件：

// 不需要用户认证的插件
await trtc.startPlugin('BasicBeauty', {
  beauty: 0.5,
  brightness: 0.5,
  ruddy: 0.5
});
// 需要用户认证的插件
await trtc.startPlugin('VirtualBackground', {
  sdkAppId: 123456,
  userId: 'user_123',
  userSig: 'XXXXXXXX',
  type: 'blur',
  blurLevel: 3
});

3. 更新参数（可选）

使用 trtc.updatePlugin(pluginName, options) 动态更新插件参数：

await trtc.updatePlugin('BasicBeauty', {
  beauty: 0.8,
  brightness: 0.6
});

4. 停止插件

使用 trtc.stopPlugin(pluginName) 停止插件：

await trtc.stopPlugin('BasicBeauty');

特殊用法说明

AudioMixer（背景音乐）- 按 ID 分组

AudioMixer 通过唯一的 id 标识每个背景音乐，每个 id 都有独立的生命周期：

// 开启第一个背景音乐
await trtc.startPlugin('AudioMixer', {
  id: 'bgm1',
  url: './music1.mp3',
  loop: true,
  volume: 0.5
});
// 同时开启第二个背景音乐（不同 id）
await trtc.startPlugin('AudioMixer', {
  id: 'bgm2',
  url: './music2.mp3',
  volume: 0.3
});
// 更新第一个背景音乐
await trtc.updatePlugin('AudioMixer', {
  id: 'bgm1',
  volume: 0.8,
  operation: 'pause' // pause | resume
});
// 停止第一个背景音乐
await trtc.stopPlugin('AudioMixer', {
  id: 'bgm1'
});

特点：

• 按 id 分组，每个 id 独立管理一个背景音乐
• 支持同时开启多个背景音乐（不同 id）
• 同一个 id 不能连续 start 两次，需先 stop
• 支持暂停、恢复、跳转等操作

CDNStreaming（CDN 转推）- 按 Mode 分组

CDNStreaming 按 publishMode 分组，每个模式都有独立的生命周期。支持四种推流模式：

import { PublishMode } from 'trtc-sdk-v5/plugins/cdn-streaming';
// 模式 1：转推摄像头流
await trtc.startPlugin('CDNStreaming', {
  target: {
    publishMode: PublishMode.PublishMainStreamToCDN,
    streamId: 'stream001'
  }
});
// 模式 2：转推屏幕分享流（可与模式 1 同时进行）
await trtc.startPlugin('CDNStreaming', {
  target: {
    publishMode: PublishMode.PublishSubStreamToCDN,
    streamId: 'stream002'
  }
});
// 模式 3：转推混流
await trtc.startPlugin('CDNStreaming', {
  target: {
    publishMode: PublishMode.PublishMixStreamToCDN,
    streamId: 'mix-stream'
  },
  encoding: { videoWidth: 1280, videoHeight: 720 },
  mix: {
    audioMixUserList: [{ userId: 'user_123' }],
    videoLayoutList: [/* 布局参数 */]
  }
});
// 模式 4：回推混流到 TRTC 房间
await trtc.startPlugin('CDNStreaming', {
  target: {
    publishMode: PublishMode.PublishMixStreamToRoom,
    robotUser: { userId: 'robot_001', roomId: 1234 }
  },
  encoding: { videoWidth: 1280, videoHeight: 720 },
  mix: { /* 混流参数 */ }
});
// 更新模式 1 的参数
await trtc.updatePlugin('CDNStreaming', {
  target: {
    publishMode: PublishMode.PublishMainStreamToCDN,
    streamId: 'stream001_new'
  }
});
// 停止模式 1（只需传 publishMode）
await trtc.stopPlugin('CDNStreaming', {
  target: {
    publishMode: PublishMode.PublishMainStreamToCDN
  }
});

特点：

• 按 publishMode 分组，每个模式独立管理
• 四种模式可以同时运行（不同 publishMode）
• 同一个 publishMode 遵循 start-update-stop 生命周期
• 停止时只需传入 publishMode 参数

VideoMixer（视频合流）- 多输入源管理

VideoMixer 插件支持动态管理多个输入源，通过 id 标识每个输入源：

// 开启合流，返回合流后的 track
const { track } = await trtc.startPlugin('VideoMixer', {
  canvasInfo: { width: 1920, height: 1080 },
  camera: [{ id: 'camera1', layout: { x: 0, y: 0, width: 640, height: 480, zIndex: 1 } }]
});
// 动态添加屏幕共享
await trtc.updatePlugin('VideoMixer', {
  screen: [{ id: 'screen1', layout: { x: 640, y: 0, width: 1280, height: 1080, zIndex: 0 } }]
});
// 移除摄像头（传空数组）
await trtc.updatePlugin('VideoMixer', {
  camera: []
});
// 使用合流后的 track 推流
await trtc.startLocalVideo({ 
  option: { 
    videoTrack: track,
    profile: { width: 1920, height: 1080, bitrate: 2000 }
  }
});

特点：

• 支持多次 start/update
• 返回 track 用于自定义推流
• 通过数组管理多个输入源（camera、screen、text、image、video）
• 注意：仅支持 PC 端浏览器

TRTCVideoDecoder（视频解码）- 自动启动

TRTCVideoDecoder 插件注册后会自动在解码失败时启动降级逻辑，无需手动调用 startPlugin：

import TRTCVideoDecoder from 'trtc-sdk-v5/plugins/video-decoder';
const trtc = TRTC.create({ 
  plugins: [TRTCVideoDecoder],
  assetsPath: 'https://your-cdn/assets'
});
// 无需手动 startPlugin，插件会在解码失败时自动启动

SmallStreamAutoSwitcher（大小流切换）- 无参数更新

SmallStreamAutoSwitcher 启动后自动运行，不支持 updatePlugin：

// 使用默认策略
trtc.startPlugin('SmallStreamAutoSwitcher');
// 自定义策略（仅在 start 时设置）
trtc.startPlugin('SmallStreamAutoSwitcher', {
  maxAutoSwitchToSmallCount: 1, // 只允许切换 1 次
  poorDuration: 5000,            // 网络差持续 5 秒才切换
  goodDuration: 30000            // 网络好持续 30 秒才切回
});

特点：

• 不支持 updatePlugin
• 自动根据网络状况切换大小流
• 注意：需配合大小流功能使用

FaceDetection（人脸检测）- 回调驱动

FaceDetection 通过回调函数获取检测结果，采用智能防抖逻辑：

await trtc.startPlugin('FaceDetection', {
  onFaceDetectionStateChanged: (hasFace) => {
    if (hasFace) {
      console.log('检测到人脸出现');
    } else {
      console.log('检测到人脸消失'); // 延迟触发，避免误报
    }
  },
  detectionInterval: 300,    // 检测间隔（ms）
  minConfidence: 0.8,        // 最小置信度
  missingTimeout: 1000       // 人脸消失确认时间（ms）
});

特点：

• 智能防抖：人脸出现立即触发，消失延迟确认
• 自动同步视频流状态（Mute/Unmute）
• 注意：需先开启摄像头

DeviceDetector（设备检测）- 返回检测结果

DeviceDetector 提供默认 UI，检测完成后返回设备和网络检测结果：

import { DeviceDetector } from 'trtc-sdk-v5/plugins/device-detector';
const trtc = TRTC.create({ plugins: [DeviceDetector] });
// 仅检测设备
const result = await trtc.startPlugin('DeviceDetector');
// 检测设备 + 网络
const resultWithNetwork = await trtc.startPlugin('DeviceDetector', {
  networkDetect: { sdkAppId, userId, userSig }
});
// 返回结果示例
// result.camera: { isSuccess: boolean, device: {...} }
// result.microphone: { isSuccess: boolean, device: {...} }
// result.speaker: { isSuccess: boolean, device: {...} }
// result.network: { isSuccess: boolean, result: { quality, rtt } }

特点：

• 提供默认的检测 UI，支持中英文
• 返回检测结果，可用于后续逻辑判断
• 支持仅检测设备或同时检测网络

Debug（调试模式）- 自动启动

Debug 插件用于日志上传/导出和音视频转储，v5.8.4 起已内置 SDK：

// v5.8.4+：无需引入插件，URL 添加 ?trtcDebug=1 自动开启弹窗
// v5.8.3 及以下：需引入插件
import { Debug } from 'trtc-sdk-v5/plugins/debug';
const trtc = TRTC.create({ plugins: [Debug] });
// 开发环境自动开启，部署环境需 URL 添加 ?trtcDebug=1
// 关闭调试模式
trtc.stopPlugin('Debug');

特点：

• v5.8.4+ 内置 SDK，无需外部引入
• 开发环境自动开启弹窗
• 支持日志上传/导出、音视频转储

静态资源部署

部分插件需要部署静态资源文件（WebAssembly、模型文件等），操作步骤：

1. 发布资源文件

将 node_modules/trtc-sdk-v5/assets 目录发布到 CDN 或静态资源服务器：

# 示例：复制到 public 目录
cp -r node_modules/trtc-sdk-v5/assets ./public/assets
# 或上传到 CDN
# https://your-cdn.com/assets/

2. 配置 assetsPath

创建 TRTC 实例时传入资源路径：

const trtc = TRTC.create({ 
  plugins: [VirtualBackground, AIDenoiser],
  assetsPath: 'https://your-cdn.com/assets'
});

3. 注意事项

• 如果资源文件域名与应用域名不一致，需开启 CORS 策略
• 资源文件必须部署在 HTTPS 服务下（HTTP 会被浏览器安全策略禁止）
• SDK 版本低于 v5.10.0 可能需要额外部署特定文件（参考各插件文档）

相关链接

• TRTC Web SDK API 文档
• 包月套餐计费说明
• 在线 Demo 体验