Pre-call Detection
Function Overview
To ensure a high-quality real-time communication experience, you can test devices before a call to identify and resolve potential issues in advance. Device testing primarily checks whether the local microphone, camera, and speaker are functioning properly.
Download Sample Source Code
Please refer to Download Sample Source Code to get the source code.
For related source code, please check the files in the "src/Examples/Others/DeviceDetection" directory.
Prerequisites
Before implementing pre-call device detection, ensure that:
- You have created a project in the ZEGOCLOUD Console and applied for a valid AppID and Server address. For details, refer to Console - Project Information.
- You have integrated ZEGO Express SDK into your project and implemented basic audio/video stream publishing and playing functionality. For details, refer to Quick Start - Integration and Quick Start - Implementation.
Implementation Methods
Click Online Experience to try the device detection feature.
Testing Microphone
The microphone device testing process is shown in the following diagram:
1. Check microphone device permissions and get microphone device list
Call the getMicrophones interface to get the list of microphone devices. getMicrophones will request microphone permission if no device permission is detected.
- Version 2.14.0 and later: Use getMicrophones to get devices.
- Version 2.13.0 and earlier: Use enumDevices to get the device list.
// Version 2.14.0 and later: Use getMicrophones to get devices.
const microphones = await zg.getMicrophones()2. Start and test microphone
When calling the createZegoStream interface to create a ZegoLocalStream stream instance object, use "deviceID" to start the microphone you want to test.
- Version 3.0.0 and later: After the microphone starts, the createZegoStream interface will check if the microphone is available and will throw an error code if it's not available.
- Versions before 3.0.0: After the microphone starts, the createStream interface will check if the microphone is available and will throw an error code if it's not available.
// Get the deviceID of the first microphone device
const { deviceID } = microphones[0]
// Create a media stream that collects microphone audio,
const micStream = await zg.createZegoStream({
camera: {
video: false,
audio: {
input: deviceID
}
}
})3. Test microphone audio data
Register the local captured audio sound level callback capturedSoundLevelUpdate, where "soundLevel" ranges from [0, 100].
zg.on("capturedSoundLevelUpdate", (soundLevel) => {
console.log(soundLevel)
})After starting the microphone, call the setSoundLevelDelegate interface to enable the sound level feature, which triggers the capturedSoundLevelUpdate event to get changes in microphone sound level. Determine if the microphone is working properly based on whether the "soundLevel" data in the capturedSoundLevelUpdate event callback fluctuates normally. Usually, when speaking into the microphone, "soundLevel" will fluctuate above 10.
// Enable sound level detection
zg.setSoundLevelDelegate(true);Testing Camera
The camera device testing process is shown in the following diagram:
1. Check camera device permissions and get camera device list
Call the getCameras interface to get the list of camera devices. getCameras will request camera permission if no device permission is detected.
- Version 2.14.0 and later: Use getCameras to get devices.
- Version 2.13.0 and earlier: Use enumDevices to get the device list.
// Version 2.14.0 and later: Use getCameras to get devices
const cameras = await zg.getCameras()2. Start and test camera
Call the createZegoStream interface to create a ZegoLocalStream stream instance object, use "deviceID" to start the camera you want to test.
- Version 3.0.0 and later: After the camera starts, the createZegoStream interface will check if the camera is available and will throw an error code if it's not available.
- Versions before 3.0.0: After the camera starts, the createStream interface will check if the camera is available and will throw an error code if it's not available.
// Get the deviceID of the first camera device
const { deviceID } = cameras[0]
// Create a media stream that collects camera video,
const cameraStream = await zg.createZegoStream({
camera: {
video: {
input: deviceID
},
audio: false
}
})3. Check if video is normal
Play the media stream that collects camera video through the html5 <video> tag element so that users can judge whether the camera device can capture video properly.
// Version 3.0.0 and later: Use createZegoStream to create stream preview
// Preview container div
<div id="camera-view" playsinline autoplay muted></div>
cameraStream.playVideo(document.querySelector("#camera-view"));Testing Speaker
The speaker device testing process is shown in the following diagram:
1. Check speaker device permissions and get speaker device list
Call the getSpeakers interface to get the list of microphone devices. getSpeakers will request audio output device permission if no device permission is detected.
- Version 2.14.0 and later: Use getSpeakers to get devices.
- Version 2.13.0 and earlier: Use enumDevices to get the device list.
// Version 2.14.0 and later: Use getSpeakers to get devices
const speakers = await zg.getSpeakers()2. Play audio files through <audio> tag
Use the html5 <audio> tag to play your test audio file by assigning the audio address to src.
<audio controls id="music-player" src="http://xxx.mp3" loop></audio>3. Specify speaker for audio playback
Call the useAudioOutputDevice interface to specify the audio player to play sound and listen to whether the corresponding speaker plays sound.
The useAudioOutputDevice interface only supports Chrome browser.
// Get the deviceID of the first speaker device
const { deviceID } = speakers[0]
// Get the audio player
player = document.getElementById("#music-player")
// Specify the speaker device used by the audio player
zg.useAudioOutputDevice(player, deviceID)
// Play music
player.play()Hot-plug of Audio and Video Capture Devices
ZEGO Express Web SDK provides videoDeviceStateChanged and audioDeviceStateChanged events to monitor and get the plug/unplug status of audio and video devices, which can be used to update the device list.
zg.on('videoDeviceStateChanged', (updateType, deviceInfo) => {
if(updateType === "ADD") {
cameras.push(deviceInfo)
} else if(updateType === "DELETE") {
cameras = cameras.filter(item=>(item.deviceID === deviceInfo.deviceID))
}
});
zg.on('audioDeviceStateChanged', (updateType, deviceType, deviceInfo) => {
if(updateType === "ADD") {
microphones.push(deviceInfo)
} else if(updateType === "DELETE") {
microphones = microphones.filter(item=>(item.deviceID === deviceInfo.deviceID))
}
});If you want to force the use of a new device when it's inserted, you need to use the on method to register the videoDeviceStateChanged or audioDeviceStateChanged event, and call useVideoDevice or useAudioDevice in the corresponding callback function to switch audio/video capture devices.