Device Detection
Feature Introduction
To ensure real-time communication experience, device detection can be performed before calls or live streaming to identify and troubleshoot problems in advance. Device detection mainly checks whether the local microphone, camera, and speakers can work normally.
Prerequisites
Before implementing device detection, please make sure:
- A project has been created in the ZEGOCLOUD Console and valid AppID and AppSign have been applied for. For details, please refer to Console - Project Information.
- ZEGO Express SDK has been integrated into the project and basic audio and video publishing and playing functions have been implemented. For details, please refer to Quick Start - Integration and Quick Start - Implementation Process.
Device Detection
Microphone Detection
Detection Logic
The microphone device detection process is shown below:
Corresponding Interfaces
1. Start Microphone
Call the startPreview interface to start audio capture without publishing stream.
engine->startPreview(&canvas);2. Check Microphone Permission
ZEGO SDK will automatically check microphone permission. If the user has not authorized, it will request user consent; if the user refuses, the user needs to manually enable permission in system settings.
**3. Check if Microphone is Available
Check whether the device is abnormal through the following callback. If no abnormal feedback is detected (you can start "4. Check Microphone Recording Data" synchronously), and the microphone recording data detection is normal, the microphone device is available.
Listen to the onLocalDeviceExceptionOccurred callback to check whether the device is abnormal.
/**
* The callback triggered when a local device exception occurred.
*
* Available since: 2.15.0
* Description: The callback triggered when a local device exception occurs.
* Trigger: This callback is triggered when the function of the local audio or video device is abnormal.
*
* @param exceptionType The type of the device exception.
* @param deviceType The type of device where the exception occurred.
* @param deviceID Device ID. Currently, only desktop devices are supported to distinguish different devices; for mobile devices, this parameter will return an empty string.
*/
virtual void onLocalDeviceExceptionOccurred(ZegoDeviceExceptionType /*exceptionType*/, ZegoDeviceType /*deviceType*/, const std::string& /*deviceID*/) {
}4. Check Microphone Recording Data
Call the startSoundLevelMonitor interface to get the energy value of the sound collected by the microphone. If the data is normal, the microphone is normal and can be used for calls or live streaming.
engine->startSoundLevelMonitor();Camera Detection
Detection Logic
The camera device detection process is shown below:
Corresponding Interfaces
1. Start Camera
Call the startPreview interface to bind the camera preview view, and start video capture and preview without publishing stream.
ZegoCanvas canvas(ZegoView(ui->frame_Preview->winId()));
engine->startPreview(&canvas);2. Check Camera Permission
ZEGO SDK will automatically check camera permission. If the user has not authorized, it will request user consent; if the user refuses, the user needs to manually enable permission in system settings.
**3. Check if Camera is Available
Check whether the device is abnormal through the following callback. If no abnormal feedback is detected (you can start "4. Check if Screen is Normal" synchronously), and the screen display is normal, the device is available.
Listen to the onLocalDeviceExceptionOccurred callback to check whether the device is abnormal.
/**
* The callback triggered when a local device exception occurred.
*
* Available since: 2.15.0
* Description: The callback triggered when a local device exception occurs.
* Trigger: This callback is triggered when the function of the local audio or video device is abnormal.
*
* @param exceptionType The type of the device exception.
* @param deviceType The type of device where the exception occurred.
* @param deviceID Device ID. Currently, only desktop devices are supported to distinguish different devices; for mobile devices, this parameter will return an empty string.
*/
virtual void onLocalDeviceExceptionOccurred(ZegoDeviceExceptionType /*exceptionType*/, ZegoDeviceType /*deviceType*/, const std::string& /*deviceID*/) {
}4. Check if Screen is Normal
If the screen display is normal at this time, the camera is normal and can be used for calls or live streaming.
Speaker Detection
Detection Logic
The playback device detection process is shown below:
Corresponding Interfaces
1. Use Media Player to Play Audio File
Call the IZegoMediaPlayer interface to play your audio file for testing.
// 1. Create media player
IZegoMediaPlayer *mediaPlayer = engine->createMediaPlayer();
// 2. Load resource
std::string currentSelectPath = "xxx";
mediaPlayer->loadResource(currentSelectPath, nullptr);
// 3. Play resource
mediaPlayer->start();2. Check if Sound is Heard
If you can hear the corresponding audio, the playback device is normal and can be used for calls or live streaming. Call the onMediaPlayerStateUpdate interface to check the media player status:
/**
* Player playing state callback
* @param mediaPlayer The player instance of the callback
* @param state Player state
* @param errorCode Error code, please refer to the common error code document for details
*/
virtual void onMediaPlayerStateUpdate(IZegoMediaPlayer* /*mediaPlayer*/, ZegoMediaPlayerState /*state*/, int /*errorCode*/) { }API Reference List
| Method | Description |
|---|---|
| startPreview | Start local preview |
| onLocalDeviceExceptionOccurred | Local device exception notification |
| startSoundLevelMonitor | Start volume change monitoring |
| onMediaPlayerStateUpdate | Player playing state callback |
Common Error Codes
When the developer receives onLocalDeviceExceptionOccurred device callback not equal to 0, please refer to Common Error Codes for related error codes.