TRTC Web SDK v4 升级到 v5 指引

本文档提供从 TRTC Web SDK v4 升级到 v5 的完整迁移指引，包括架构变化、API 映射、事件映射以及迁移示例代码。

概述

架构变化

v4 SDK 采用 Client + Stream 分离的设计模式：

• TRTC.createClient() 创建客户端实例，负责进退房、发布/订阅等信令操作。
• TRTC.createStream() 创建音视频流实例，负责音视频采集、播放等媒体操作。

v5 SDK 采用统一的 TRTC 实例设计：

• TRTC.create() 创建唯一实例，所有操作（进退房、音视频采集播放、屏幕分享等）均通过该实例完成。

升级收益

按场景迁移索引

如果您希望先按功能场景快速定位迁移差异，可以先参考下表，再结合本文后续的 API / 事件映射与迁移示例完成改造。

基础教程

进阶教程

最佳实践

安装与引入

v4

// npm 安装
npm install trtc-js-sdk
// 引入
import TRTC from 'trtc-js-sdk';

v5

// npm 安装
npm install trtc-sdk-v5
// 引入
import TRTC from 'trtc-sdk-v5';

核心 API 映射

创建实例

v4： 需要分别创建 Client 和 Stream。

const client = TRTC.createClient({
  sdkAppId,
  userId,
  userSig,
  mode: 'rtc', // 或 'live'
});
const localStream = TRTC.createStream({
  userId,
  audio: true,
  video: true,
});

v5： 创建统一的 TRTC 实例。

const trtc = TRTC.create();

进房与退房

v4：

// 进房
await client.join({ roomId: 1234 });
// 退房
await client.leave();

v5：

// 进房
await trtc.enterRoom({
  sdkAppId,
  userId,
  userSig,
  roomId: 1234,
  scene: 'rtc', // 对应 v4 的 mode
});
// 退房
await trtc.exitRoom();

说明： v5 将 sdkAppId、userId、userSig 等参数从创建实例移到了 enterRoom 中传入。v4 的 mode 参数对应 v5 的 scene 参数（'rtc' 或 'live'）。

本地音视频

v4： 需要先初始化 Stream，再发布。

const localStream = TRTC.createStream({
  userId,
  audio: true,
  video: true,
});
// 初始化（采集）
await localStream.initialize();
// 播放
localStream.play('local-video-container');
// 发布
await client.publish(localStream);

v5： 采集、播放、发布一步完成。

// 开启本地视频（采集 + 播放 + 发布）
await trtc.startLocalVideo({
  view: 'local-video-container',
});
// 开启本地音频（采集 + 发布）
await trtc.startLocalAudio();

停止本地音视频：

// v4
client.unpublish(localStream);
localStream.close();
// v5
await trtc.stopLocalVideo();
await trtc.stopLocalAudio();

远端音视频

v4： 需要监听事件 → 订阅 → 播放。

client.on('stream-added', (event) => {
  const remoteStream = event.stream;
  // 订阅远端流
  client.subscribe(remoteStream);
});
client.on('stream-subscribed', (event) => {
  const remoteStream = event.stream;
  // 播放远端流
  remoteStream.play('remote-video-container');
});
client.on('stream-removed', (event) => {
  const remoteStream = event.stream;
  remoteStream.stop();
});

v5： 监听事件 → 直接播放。

// 远端用户进入房间
trtc.on(TRTC.EVENT.REMOTE_USER_ENTER, (event) => {
  // userId 进入房间
});
// 远端视频可用时，开始播放
trtc.on(TRTC.EVENT.REMOTE_VIDEO_AVAILABLE, (event) => {
  const { userId, streamType } = event;
  trtc.startRemoteVideo({
    userId,
    streamType,
    view: `remote-video-${userId}`,
  });
});
// 远端视频不可用时，自动停止，可选择移除 DOM
trtc.on(TRTC.EVENT.REMOTE_VIDEO_UNAVAILABLE, (event) => {
  // 视频已自动停止
});
// 远端音频默认自动订阅和播放，无需额外处理

说明： v5 中音频默认自动订阅（autoReceiveAudio 默认 true），视频需手动调用 startRemoteVideo() 播放。自 v5.6.0 起，autoReceiveVideo 默认值改为 false，需监听 REMOTE_VIDEO_AVAILABLE 事件后手动调用 startRemoteVideo()。

屏幕分享

v4.15+： 无需额外创建 Client，但仍需单独创建屏幕分享 Stream，并以辅流方式发布。

// 复用已进房的主 Client
const shareStream = TRTC.createStream({
  userId,
  audio: false,
  screen: true,
});
await shareStream.initialize();
await client.publish(shareStream, { isAuxiliary: true });

说明： 在 v4.15.0 之前，如需同时推摄像头和屏幕分享，通常需要额外创建 Client；v4.15.0+ 起可复用同一个 Client 同时推主流和辅流。

v5： 直接调用 API 即可。

await trtc.startScreenShare();

角色切换（直播场景）

// v4
await client.switchRole('anchor'); // 或 'audience'
// v5
await trtc.switchRole(TRTC.TYPE.ROLE_ANCHOR); // 或 TRTC.TYPE.ROLE_AUDIENCE

音视频参数设置

v4：

localStream.setVideoProfile('480p');
localStream.setAudioProfile('standard');

v5： 在 startLocalVideo / startLocalAudio 中通过 option 参数设置。

await trtc.startLocalVideo({
  view: 'local-video-container',
  option: {
    profile: '480p',
  },
});
await trtc.startLocalAudio({
  option: {
    profile: 'standard',
  },
});

设备管理

v4：

// 获取设备列表
const devices = await TRTC.getDevices();
const cameras = await TRTC.getCameras();
const microphones = await TRTC.getMicrophones();
const speakers = await TRTC.getSpeakers();
// 切换设备
await localStream.switchDevice('video', cameraId);
await localStream.switchDevice('audio', microphoneId);

v5：

// 获取设备列表
const cameras = await TRTC.getCameraList();
const microphones = await TRTC.getMicrophoneList();
const speakers = await TRTC.getSpeakerList();
// 切换设备（通过 updateLocalVideo / updateLocalAudio）
await trtc.updateLocalVideo({ option: { cameraId: newCameraId } });
await trtc.updateLocalAudio({ option: { microphoneId: newMicId } });

音量检测

// v4
client.enableAudioVolumeEvaluation(200);
client.on('audio-volume', (event) => {
  event.result.forEach(({ userId, audioVolume }) => {
    console.log(`用户 ${userId} 的音量: ${audioVolume}`);
  });
});
// v5
trtc.enableAudioVolumeEvaluation(200);
trtc.on(TRTC.EVENT.AUDIO_VOLUME, (event) => {
  event.result.forEach(({ userId, volume }) => {
    console.log(`用户 ${userId} 的音量: ${volume}`);
  });
});

统计信息

v4： 通过多个 API 主动获取。

const transportStats = await client.getTransportStats();
const localAudioStats = await client.getLocalAudioStats();
const localVideoStats = await client.getLocalVideoStats();
const remoteAudioStats = await client.getRemoteAudioStats();
const remoteVideoStats = await client.getRemoteVideoStats();

v5： 通过 STATISTICS 事件被动接收，每 2 秒触发一次。

trtc.on(TRTC.EVENT.STATISTICS, (event) => {
  const {
    rtt,        // 网络往返延迟 (ms)
    upLoss,     // 上行丢包率 (%)
    downLoss,   // 下行丢包率 (%)
    bytesSent,      // 发送字节数
    bytesReceived,   // 接收字节数
    localStatistics, // 本地音视频统计
    remoteStatistics // 远端音视频统计数组
  } = event;
  // 本地音频统计
  const { bitrate, audioLevel } = localStatistics.audio;
  // 本地视频统计（数组，可能包含大流和小流）
  localStatistics.video.forEach(({ width, height, frameRate, bitrate, videoType }) => {
    console.log(`本地视频: ${width}x${height} ${frameRate}fps ${bitrate}kbps`);
  });
  // 远端统计
  remoteStatistics.forEach(({ userId, audio, video }) => {
    console.log(`远端用户 ${userId}: 音频码率 ${audio.bitrate}kbps`);
    video.forEach(({ width, height, frameRate, bitrate, videoType }) => {
      console.log(`  视频: ${width}x${height} ${frameRate}fps ${bitrate}kbps`);
    });
  });
});

注意： v5 没有 getStatistics() 方法，统计信息通过 STATISTICS 事件被动接收。

SEI 消息

// v4
client.sendSEIMessage(buffer);
// v5
await trtc.sendSEIMessage(buffer);
// 接收 SEI 消息
trtc.on(TRTC.EVENT.SEI_MESSAGE, (event) => {
  const { userId, data } = event;
});

大小流

// v4
client.enableSmallStream();
client.setSmallStreamProfile({ width: 160, height: 120, bitrate: 100, frameRate: 15 });
client.setRemoteVideoStreamType(remoteStream, 'small');
// v5
// 推流端：在 startLocalVideo / updateLocalVideo 中通过 option.small 开启小流
await trtc.startLocalVideo({
  option: {
    small: { width: 160, height: 120, bitrate: 100, frameRate: 15 },
  },
});
// 拉流端：在 startRemoteVideo / updateRemoteVideo 中通过 option.small 订阅小流
await trtc.startRemoteVideo({
  userId,
  streamType: TRTC.TYPE.STREAM_TYPE_MAIN,
  option: { small: true },
});

注意： TRTC.TYPE.STREAM_TYPE_SUB 表示辅流（通常用于屏幕分享），不是小流。v5 中切换大小流通过 option.small 控制。

销毁实例

// v4：如后续不再使用 client，可在 leave 后调用 destroy 释放资源
await client.leave();
client.destroy();
// v5：如后续不再使用 trtc 实例，也可在 exitRoom 后调用 destroy 释放资源
await trtc.exitRoom();
trtc.destroy();

完整 API 映射表

事件映射表

v5 新增事件

迁移示例：基础音视频通话

v4 完整示例

import TRTC from 'trtc-js-sdk';
// 1. 创建 Client
const client = TRTC.createClient({
  sdkAppId: 1400000000,
  userId: 'user_1',
  userSig: 'xxx',
  mode: 'rtc',
});
// 2. 监听远端流事件
client.on('stream-added', (event) => {
  const remoteStream = event.stream;
  client.subscribe(remoteStream);
});
client.on('stream-subscribed', (event) => {
  const remoteStream = event.stream;
  remoteStream.play('remote-video-container');
});
client.on('stream-removed', (event) => {
  event.stream.stop();
});
client.on('peer-leave', (event) => {
  console.log(`${event.userId} 退出房间`);
});
// 3. 进房
await client.join({ roomId: 1234 });
// 4. 创建并初始化本地流
const localStream = TRTC.createStream({
  userId: 'user_1',
  audio: true,
  video: true,
});
await localStream.initialize();
localStream.play('local-video-container');
// 5. 发布本地流
await client.publish(localStream);
// 退出时
await client.unpublish(localStream);
localStream.close();
await client.leave();

v5 完整示例

import TRTC from 'trtc-sdk-v5';
// 1. 创建 TRTC 实例
const trtc = TRTC.create();
// 2. 监听远端事件
trtc.on(TRTC.EVENT.REMOTE_VIDEO_AVAILABLE, ({ userId, streamType }) => {
  trtc.startRemoteVideo({ userId, streamType, view: `remote-video-${userId}` });
});
trtc.on(TRTC.EVENT.REMOTE_USER_EXIT, ({ userId }) => {
  console.log(`${userId} 退出房间`);
});
// 3. 进房
await trtc.enterRoom({
  sdkAppId: 1400000000,
  userId: 'user_1',
  userSig: 'xxx',
  roomId: 1234,
  scene: 'rtc',
});
// 4. 开启本地音视频（采集 + 播放 + 发布）
await trtc.startLocalVideo({ view: 'local-video-container' });
await trtc.startLocalAudio();
// 退出时
await trtc.stopLocalVideo();
await trtc.stopLocalAudio();
await trtc.exitRoom();
trtc.destroy();

迁移示例：屏幕分享

v4.15+ 屏幕分享示例

// 复用已进房的主 Client，发布屏幕分享辅流
const shareStream = TRTC.createStream({
  userId,
  audio: false,
  screen: true,
});
await shareStream.initialize();
shareStream.play('screen-container');
await client.publish(shareStream, { isAuxiliary: true });
// 停止分享
await client.unpublish(shareStream);
shareStream.close();

说明： v4.15.0 之前，如需同时推摄像头和屏幕分享，通常需要额外创建 Client；v4.15.0+ 起可复用同一个 Client。

v5 屏幕分享示例

// 一行代码
await trtc.startScreenShare();
// 监听屏幕分享停止事件
trtc.on(TRTC.EVENT.SCREEN_SHARE_STOPPED, () => {
  console.log('屏幕分享已停止');
});
// 主动停止
await trtc.stopScreenShare();

迁移示例：统计信息获取

v4：定时器 + API 轮询

setInterval(async () => {
  const transportStats = await client.getTransportStats();
  console.log(`RTT: ${transportStats.rtt}ms`);
  const localAudioStats = await client.getLocalAudioStats();
  console.log('本地音频:', localAudioStats);
  const localVideoStats = await client.getLocalVideoStats();
  console.log('本地视频:', localVideoStats);
  const remoteAudioStats = await client.getRemoteAudioStats();
  console.log('远端音频:', remoteAudioStats);
  const remoteVideoStats = await client.getRemoteVideoStats();
  console.log('远端视频:', remoteVideoStats);
}, 2000);

v5：事件监听

trtc.on(TRTC.EVENT.STATISTICS, (event) => {
  console.log(`RTT: ${event.rtt}ms, 上行丢包: ${event.upLoss}%, 下行丢包: ${event.downLoss}%`);
  // 本地音频统计
  console.log(`本地音频码率: ${event.localStatistics.audio.bitrate}kbps`);
  // 本地视频统计
  event.localStatistics.video.forEach((stat) => {
    console.log(`本地视频: ${stat.width}x${stat.height} ${stat.frameRate}fps ${stat.bitrate}kbps`);
  });
  // 远端统计
  event.remoteStatistics.forEach(({ userId, audio, video }) => {
    console.log(`用户 ${userId} - 音频码率: ${audio.bitrate}kbps`);
    video.forEach((stat) => {
      console.log(`  视频: ${stat.width}x${stat.height} ${stat.frameRate}fps ${stat.bitrate}kbps`);
    });
  });
});

v5 新增能力

插件系统

v5 提供统一的插件系统，通过 startPlugin / updatePlugin / stopPlugin 操作插件。支持的插件包括：

• Beauty - 高级美颜
• BasicBeauty - 基础美颜
• VirtualBackground - 虚拟背景
• AIDenoiser - AI 降噪
• AudioMixer - 背景音乐混音
• Watermark - 水印
• CDNStreaming - CDN 推流
• CrossRoom - 跨房连麦
• DeviceDetector - 设备检测
• 更多…

import { Beauty } from 'trtc-sdk-v5/plugins/beauty';
const trtc = TRTC.create({ plugins: [new Beauty()] });
// 开启美颜
await trtc.startPlugin('Beauty', {
  beauty: 0.5,
  brightness: 0.5,
  ruddy: 0.5,
});
// 更新参数
await trtc.updatePlugin('Beauty', { beauty: 0.8 });
// 关闭美颜
await trtc.stopPlugin('Beauty');

switchRoom - 无缝房间切换

// v4 需要先退房再进房
await client.leave();
await client.join({ roomId: 5678 });
// v5 直接切换
await trtc.switchRoom({ roomId: 5678 });

sendCustomMessage - 自定义消息

await trtc.sendCustomMessage({
  cmdId: 1,
  data: new Uint8Array([1, 2, 3]),
});
trtc.on(TRTC.EVENT.CUSTOM_MESSAGE, (event) => {
  const { userId, cmdId, data } = event;
});

注意事项

1. autoReceiveVideo 默认值变化

自 v5.6.0 起，autoReceiveVideo 默认值从 true 改为 false。即视频不再自动订阅，需要监听 REMOTE_VIDEO_AVAILABLE 事件后调用 startRemoteVideo() 手动开始播放远端视频。

// 推荐：始终监听 REMOTE_VIDEO_AVAILABLE 事件来播放远端视频
trtc.on(TRTC.EVENT.REMOTE_VIDEO_AVAILABLE, ({ userId, streamType }) => {
  trtc.startRemoteVideo({ userId, streamType, view: document.getElementById(`video-${userId}`) });
});

2. roomId 类型

• v5 的 enterRoom 支持数字类型的 roomId 和字符串类型的 strRoomId，两者二选一。
• 数字 roomId 取值范围：[1, 4294967294]。

3. 统计信息为事件驱动

v5 没有 getStatistics() 方法，所有统计数据通过 TRTC.EVENT.STATISTICS 事件推送。如果需要统计信息，直接监听该事件即可。

4. 音频默认自动订阅

v5 中音频默认自动订阅和播放，无需像 v4 一样手动 subscribe 和 play。如需控制，可在 enterRoom 时设置 autoReceiveAudio: false。

5. 销毁实例

使用完毕后如不再复用实例，可调用 trtc.destroy() 释放资源。v4 也提供了 client.destroy()（v4.13.0+），只是销毁对象从 client 变成了 trtc 实例。

6. 屏幕分享 API 更简洁

v4.15.0+ 中屏幕分享已可复用同一个 client，但仍需手动创建 shareStream 并以 { isAuxiliary: true } 方式发布；v5 中则通过 startScreenShare() / stopScreenShare() 直接操作，无需显式创建屏幕分享 Stream。

7. 自动播放策略

v5 提供了 AUTOPLAY_FAILED 事件和 enableAutoPlayDialog 选项，可以更优雅地处理浏览器自动播放限制。

// 方式一：在 enterRoom 时开启自动播放引导对话框
await trtc.enterRoom({
  // ...
  enableAutoPlayDialog: true,
});
// 方式二：手动处理
trtc.on(TRTC.EVENT.AUTOPLAY_FAILED, () => {
  // 显示引导提示，引导用户进行交互操作以恢复音视频播放
});

更多参考

• TRTC Web SDK v5 API 文档
• v5 更新与 Breaking Change 说明
• 快速跑通 Demo