Tutorial: Check Environment and Device Before Calls

Run Demo

Browser Environment Check

Before calling the communication capabilities of the SDK, we recommend you use the TRTC.isSupported API to check whether the SDK supports the current browser first, and if not, please recommend the user to use a supported browser(Chrome 56+, Edge 80+, Firefox 56+, Safari 11+).

TRTC.isSupported().then(checkResult => {
  // Not supported, guide the user to use a supported browser(Chrome 56+, Edge 80+, Firefox 56+, Safari 11+).
  if (!checkResult.result) {}
  // Not support to publish video
  if (!checkResult.detail.isH264EncodeSupported) {}
  // Not support to subscribe video
  if (!checkResult.detail.isH264DecodeSupported) {}
})

⚠️ If the check result returned by TRTC.isSupported is false, this may be because:

1. The web page uses the http protocol. Browsers do not allow http protocol sites to capture cameras and microphones, you need to deploy your page using the https protocol.
2. The current browser does not support WebRTC, you need to guide the user to use the recommended browser Browsers Supported.
3. Firefox browser needs to load H264 codec dynamically after installation, so the detection result will be false for a short period of time, please wait and try again or guide to use other browsers.

Media Device Test

Users join from very different environments: some computers have no camera, some use a virtual camera, some have not granted camera or microphone permission, and some are on a network too poor to sustain a high-quality call. Without detection, these problems only surface as an abnormal call after the user has already entered the room.

We therefore recommend detecting devices before the call, so that the user does not run into these problems after entering the room. Detection brings them forward to a point where the user can still do something about them:

• The user has no camera or microphone. They are told before entering, instead of joining the room and finding out that nobody can see or hear them.
• The camera or microphone does not work. A video preview and a real-time volume bar let the user confirm the device works, and switch to another one when it does not.
• Camera or microphone permission is not granted. The user is guided to grant the permission, rather than hitting a capture failure after entering the room.
• The network quality is poor. The user learns this before joining, so a bad call is understood as a network problem. See Network Quality Detection before enterRoom.

Option 1: Use Device Detector Plugin (including default UI)

The device detector plugin is used to test the user's media device(camera, microphone, speaker) and network which is recommended to be used before the user enters the room.

• Support TRTC Web SDK version >= v5.8.0
• The plugin includes a default UI. If the UI does not meet your product design requirements, you can refer to Option 2 for a custom UI implementation.

Usage

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);

Use the Devices that Passed Detection when Entering the Room

Detection is also where the user picks a camera and a microphone. Carry that choice into the room. If no deviceId is passed at capture time, the SDK captures from the system default device, which is not necessarily the one the user just confirmed, and the user may end up publishing from a device they never tested.

trtc.startPlugin('DeviceDetector') resolves with the detection result, and result.camera.device / result.microphone.device are the devices shown to the user during detection. Pass their deviceId when starting capture in the room:

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 });
// Capture from the camera and microphone that the user confirmed during detection.
await trtc.startLocalVideo({ option: { cameraId } });
await trtc.startLocalAudio({ option: { microphoneId } });

A step the user skipped, or that failed, reports isSuccess: false and may carry an empty deviceId. Check isSuccess first, and leave the option out so the SDK falls back to the default device. The same applies to a custom UI (Option 2): read the deviceId from TRTC.getCameraList() / TRTC.getMicrophoneList(), or track the device the user confirmed, and pass it the same way.

API Description

trtc.startPlugin('DeviceDetector', options)

options

options.mirror(optional)

Enable the mirror checkbox during camera detection

options.cameraDetect(optional)

options.networkDetect(optional)

Return value of trtc.startPlugin('DeviceDetector')

Plugin Demo

Option 2: Implement Device Detection Based on SDK API (Custom UI)

If the default UI of the device detection plugin in Option 1 does not meet your requirements, you can choose Option 2 to customize the UI.

1. Check Device Permission

Since v5.13.0+, SDK provides the TRTC.getPermissions interface, which is used to check, request, and listen to device permissions.

const { camera, microphone } = await TRTC.getPermissions({
  request: true, // If true, the interface may temporarily open the camera to obtain the camera permission, and then the SDK will automatically release the capture.
  types: ['camera', 'microphone'] // The types of permission to request.
});
console.log(camera, microphone); // 'granted' | 'denied' | 'prompt' | null. null means the permission is not supported query.
// Listen to device permission changes
trtc.on(TRTC.EVENT.PERMISSION_STATE_CHANGE, event => {
  console.log(event.camera, event.microphone);
});
// Release the listener
trtc.off(TRTC.EVENT.PERMISSION_STATE_CHANGE);

2. Device Connection

The device connection checks if the user's device has a camera, microphone, and speaker. It also verifies the network connection. If the camera and microphone are present, the system will attempt to access the audio/video streams and prompt the user to grant permission for camera and microphone access.

• Check whether the device has a camera, microphone device

  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 !== '');
  // Mobile devices do not support getting speaker devices, so mobile devices can skip getting speaker devices
  const speakerList = await TRTC.getSpeakerList();
  const hasSpeakerDevice = speakerList.some(speaker => speaker.deviceId !== '');
  

3. Camera Detection

Detection principle: Turn on the camera and render the camera image on the page. You can provide two buttons on the page to allow the user to confirm whether they can see the camera image.

• Turn on the camera

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

• Switch the camera

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

• Close the camera after detection is completed

  trtc.stopLocalVideo();
  

4. Microphone Detection

Detection principle: Open the microphone and obtain the microphone volume. Listen to the microphone volume event and render the real-time volume to the page, guide the user to speak, and confirm whether they can see the volume bar change.

• Turn on the microphone

  trtc.on(TRTC.EVENT.AUDIO_VOLUME, event => {
    event.result.forEach(({ userId, volume }) => {
        const isMe = userId === '';
        if (isMe) {
            console.log(`my volume: ${volume}`);
            // Render the microphone volume to your page.
        }
    })
  });
  // 开启音量回调，并设置每 200ms 触发一次事件
  trtc.enableAudioVolumeEvaluation(200);
  trtc.startLocalAudio({ publish: false });
  

• Switch the microphone

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

• Release the microphone usage after detection is completed

  trtc.stopLocalAudio();
  

5. Speaker Detection

Detection principle: Play an mp3 media file through an audio tag

• Create an audio tag, remind the user to turn up the playback volume, play the mp3 to confirm whether the speaker device is normal.

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

• Stop playback after detection is completed

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

6. Network Detection

Reference: Network Quality Detection before enterRoom

TRTC Capability Detection Page

You can use the TRTC Detection Page where you are currently using the TRTC SDK to detect the current environment. You can also click the "Generate Report" button to get a report of the current environment for environment detection or troubleshooting.