Tutorial: 通话前环境与设备检测

体验在线 Demo

浏览器环境检测

在开始音视频通话之前，建议您先使用 TRTC.isSupported 接口检测 SDK 是否支持当前网页。如果 SDK 不支持当前浏览器，建议用户使用最新版的 Chrome 浏览器、Edge 浏览器、Safari 浏览器、Firefox 浏览器。

TRTC.isSupported().then(checkResult => {
  // 不支持使用 SDK，引导用户使用最新版的 Chrome 浏览器。
  if (!checkResult.result) {}
  // 不支持发布视频
  if (!checkResult.detail.isH264EncodeSupported) {}
  // 不支持拉视频
  if (!checkResult.detail.isH264DecodeSupported) {}
})

⚠️ TRTC.isSupported 返回的检测结果为 false 时，可能是以下原因：

1. 网页使用了 http 协议。浏览器不允许 http 协议的网站采集摄像头和麦克风，您需要使用 https 协议部署您的网页。
2. 当前浏览器不支持 WebRTC 相关能力，您需要引导用户使用推荐的浏览器 兼容性说明
3. Firefox 浏览器安装完成后需要动态加载 H264 编解码器，因此会出现短暂的检测结果为 false 的情况，请稍等再试或引导使用其他浏览器。

通话前设备检测

用户的设备环境各不相同：有的电脑没有摄像头，有的使用了虚拟摄像头，有的没有授权，也有的网络质量差难以支撑完成一次高质量的通话。如果不提前检测，就只能等用户进了房才暴露成通话异常。

因此我们建议您在通话前进行设备检测，以避免用户进入房间后遇到问题。把这些问题提前到用户还能自己处理的时间点：

• 用户没有摄像头或麦克风。进房前就告知用户，而不是进了房才发现别人看不到、听不到自己。
• 摄像头或麦克风异常。摄像头画面预览和实时音量条可以让用户确认设备是否正常，不正常时可以切换到其他设备。
• 没有摄像头或麦克风权限。引导用户完成权限授予，而不是进房后碰到采集失败。
• 网络质量差。用户在进房前就能了解自己的网络质量，通话体验不好时也能理解是网络的原因。参见通话前的网络质量检测。

方案一：使用设备检测插件（包括默认 UI）

检测用户的媒体设备（摄像头、麦克风、扬声器）以及网络，建议在用户进房之前使用，支持移动端适配。

• 该插件需要：TRTC Web SDK 版本 >= 5.8.0。
• 该插件包括默认的 UI，若 UI 不符合您的产品设计需求，可以参考方案二自定义 UI 实现。

实现流程

import { DeviceDetector } from 'trtc-sdk-v5/plugins/device-detector';
const trtc = TRTC.create({ plugins: [DeviceDetector] });
// 1. Test Media Device Only
const result = await trtc.startPlugin('DeviceDetector');
// 2. Test Media Device & Network Quality
const options = { 
    networkDetect: { sdkAppId, userId, userSig }
}
const resultWithNetwork = await trtc.startPlugin('DeviceDetector', options);

进房时使用检测通过的摄像头和麦克风

设备检测的过程也是用户挑选摄像头和麦克风的过程，进房时要沿用这个选择。采集时不传 deviceId，SDK 会使用系统默认设备，而默认设备不一定就是用户刚刚确认过的那一台，用户可能会用一个自己没验证过的设备发布音视频。

trtc.startPlugin('DeviceDetector') 的返回值就是检测结果，其中 result.camera.device 和 result.microphone.device 是用户在检测过程中看到并确认的设备，进房采集时把它们的 deviceId 传进去：

const result = await trtc.startPlugin('DeviceDetector');
const cameraId = result.camera?.device?.deviceId;
const microphoneId = result.microphone?.device?.deviceId;
await trtc.enterRoom({ roomId, sdkAppId, userId, userSig });
// 使用用户在设备检测中确认过的摄像头和麦克风采集
await trtc.startLocalVideo({ option: { cameraId } });
await trtc.startLocalAudio({ option: { microphoneId } });

用户在检测中跳过或检测失败的步骤，返回结果里 isSuccess 为 false，deviceId 可能为空串。先判断 isSuccess，为空时不传该参数，让 SDK 使用默认设备。方案二自定义 UI 同理：从 TRTC.getCameraList() / TRTC.getMicrophoneList() 拿到 deviceId，或者记录用户在检测中选择的设备，用同样的方式传入。

API

trtc.startPlugin('DeviceDetector', options)

第一个参数为'DeviceDetector'字符串，用于开启设备检测插件。

options

options.cameraDetect(optional)

options.networkDetect(optional)

startPlugin 返回结果

插件 Demo

方案二：基于 SDK API 自行实现设备检测（自定义 UI）

若方案一的设备检测插件的默认 UI 不符合您的需求，你可以选择方案二来自定义 UI。

1. 检查设备权限

从 v5.13.0+ 开始，SDK 提供了 TRTC.getPermissions 接口，用于检查、请求和监听设备权限。

const { camera, microphone } = await TRTC.getPermissions({
  request: true, // 如果为 true，调用该接口可能会短暂打开摄像头来获取摄像头权限，以保证正常获取摄像头列表，随后 SDK 会自动释放采集。
  types: ['camera', 'microphone'] // 请求获取的设备类型。
});
console.log(camera, microphone); // 'granted' | 'denied' | 'prompt' | null. null 表示不支持查询。
// 监听设备权限变化
trtc.on(TRTC.EVENT.PERMISSION_STATE_CHANGE, event => {
  console.log(event.camera, event.microphone);
});
// 释放监听
trtc.off(TRTC.EVENT.PERMISSION_STATE_CHANGE);

2. 设备连接

设备连接的目的是检测用户使用的机器是否有摄像头、麦克风或扬声器，是否在联网状态。如果有摄像头，麦克风或扬声器设备，尝试获取音视频流并引导用户授予摄像头，麦克风的访问权限。

• 判断设备是否有摄像头，麦克风或扬声器

  import TRTC from 'trtc-sdk-v5';
  const cameraList = await TRTC.getCameraList();
  const micList = await TRTC.getMicrophoneList();
  const hasCameraDevice = cameraList.some(camera => camera.deviceId !== '');
  const hasMicrophoneDevice = micList.some(mic => mic.deviceId !== '');
  // 移动端设备不支持获取扬声器设备，移动端检测扬声器可以不获取扬声器
  const speakerList = await TRTC.getSpeakerList();
  const hasSpeakerDevice = speakerList.some(speaker => speaker.deviceId !== '');
  

3. 摄像头检测

​检测原理：打开摄像头，并在页面中渲染摄像头画面。您可以在页面中提供 2 个按钮，让用户确认是否能看到摄像头画面。

• 打开摄像头

  trtc.startLocalVideo({ view: 'camera-video', publish: false });
  

• 切换摄像头

  trtc.updateLocalVideo({ option: { cameraId } });
  

• 检测完成后关闭摄像头

  trtc.stopLocalVideo();
  

4. 麦克风检测

​检测原理：打开麦克风，并获取麦克风音量。监听麦克风音量事件，并将实时音量渲染到页面中，引导用户说话，确认是否能看到音量条变化。

• 打开麦克风

  trtc.on(TRTC.EVENT.AUDIO_VOLUME, event => {
    event.result.forEach(({ userId, volume }) => {
        const isMe = userId === ''; // 当 userId 为空串时，代表本地麦克风音量。
        if (isMe) {
            console.log(`my volume: ${volume}`);
            // 将麦克风音量渲染到页面中
        }
    })
  });
  // 开启音量回调，并设置每 200ms 触发一次事件
  trtc.enableAudioVolumeEvaluation(200);
  trtc.startLocalAudio({ publish: false });
  

• 切换麦克风

  trtc.updateLocalAudio({ option: { microphoneId }});
  

• 检测完成后释放麦克风占用

  trtc.stopLocalAudio();
  

5. 扬声器检测

​ 检测原理：通过 audio 标签播放一个 mp3 媒体文件

• 创建 audio 标签，提醒用户调高播放音量，播放 mp3 确认扬声器设备是否正常。

  <audio id="audio-player" src="xxxxx" controls></audio>
  

• 检测结束后停止播放

  const audioPlayer = document.getElementById('audio-player');
  if (!audioPlayer.paused) {
      audioPlayer.pause();
  }
  audioPlayer.currentTime = 0;
  

6. 网络检测

参考：通话前的网络质量检测

TRTC 能力检测页面

您可以在当前使用 TRTC SDK 的地方，使用 TRTC 检测页面 ，可用于探测当前环境，还可以点击生成报告按钮，得到当前环境的报告，用于环境检测，或者问题排查。