Pre-call Detection
Feature Overview
To ensure a real-time communication experience, network and device detection can be performed before the call to identify and troubleshoot issues in advance.
- Network detection: Detects the network environment to determine or predict whether it is suitable for publishing/playing streams with specified bitrates.
- Device detection: Detects whether the local microphone, camera, and speaker are working properly.
This document will introduce how to use the ZEGOCLOUD SDK interfaces to implement the above two types of detection.
Prerequisites
Before implementing pre-call network/device detection, ensure that:
- The ZEGO Express SDK has been integrated into your project and basic real-time audio and video functions have been implemented. For details, please refer to Quick Start - Integration and Quick Start - Implementation.
- A project has been created in the ZEGOCLOUD Console, and a valid AppID and AppSign have been obtained. For details, please refer to Console - Project Information.
Network Detection
Please refer to Network Testing for instructions.
Device Detection
Microphone Detection
Detection Logic
The microphone device detection process is shown in the following figure:
Corresponding Interfaces
1. Start Microphone
Call the startPreview interface to start audio capturing without publishing streams.
ZegoExpressEngine.instance.startPreview();2. Check Microphone Permissions
The ZEGO Express SDK automatically checks microphone permissions.
You need to first refer to Quick Start - Integration to set up permissions.
Android 6.0 requires dynamic permission requests for some important permissions. Static permissions cannot be requested only through the "AndroidMainfest.xml" file. Therefore, you also need to refer to the following code. The following method requires the Flutter project to install the permission_handler plugin.
Permission.microphone.request();3. Check if Microphone is Available
Detect device exceptions through the following callback. If no exception 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.
- Version 2.15.0 and later: Listen to the onLocalDeviceExceptionOccurred callback to detect device exceptions.
- Versions before 2.15.0: Listen to the
onDeviceErrorcallback to detect device exceptions.
class ZegoExpressEngine {
...
/**
* Local device exception notification.
*
* Supported versions: 2.15.0 and later.
* Description: Local device exception.
* Notification timing: This callback is triggered when local audio or video device functions malfunction.
*
* @param exceptionType Device exception type.
* @param deviceType The type of device where the exception occurred.
* @param deviceID Device ID. Currently only supports desktop devices, used to identify specific devices; for mobile devices, this parameter will return an empty string.
*/
static void Function(ZegoDeviceExceptionType exceptionType, ZegoDeviceType deviceType, String deviceID)? onLocalDeviceExceptionOccurred;
...
}4. Check Microphone Recording Data
Call the startSoundLevelMonitor interface to obtain the energy value of the sound captured by the microphone. If the data is normal, the microphone is working properly and can be used for calls.
ZegoExpressEngine.instance.startSoundLevelMonitor();Camera Detection
When only integrating the real-time voice SDK or in pure audio scenarios, camera detection is not required and this section can be ignored.
Detection Logic
The camera device detection process is shown in the following figure:
Corresponding Interfaces
1. Start Camera
Call the startPreview interface to bind the view for camera preview, start video capture and preview without publishing streams.
ZegoExpressEngine.instance.startPreview();2. Check Camera Permissions
The ZEGO SDK will automatically check camera permissions.
You need to first refer to Quick Start - Integration to set up permissions.
Because Android 6.0 requires dynamic permission requests for some important permissions. Static permissions cannot be requested only through the "AndroidMainfest.xml" file. Therefore, you also need to refer to the following code. The following method requires the Flutter project to install the permission_handler plugin.
Permission.camera.request();3. Check if Camera is Available
Detect device exceptions through the following callback. If no exception feedback is detected (you can start "4. Check if Display is Normal" synchronously), and the display is normal, the device is available.
- Version 2.15.0 and later: Listen to the onLocalDeviceExceptionOccurred callback to detect device exceptions.
- Versions before 2.15.0: Listen to the
onDeviceErrorcallback to detect device exceptions.
class ZegoExpressEngine {
...
/**
* Local device exception notification.
*
* Supported versions: 2.15.0 and later.
* Description: Local device exception.
* Notification timing: This callback is triggered when local audio or video device functions malfunction.
*
* @param exceptionType Device exception type.
* @param deviceType The type of device where the exception occurred.
* @param deviceID Device ID. Currently only supports desktop devices, used to identify specific devices; for mobile devices, this parameter will return an empty string.
*/
static void Function(ZegoDeviceExceptionType exceptionType, ZegoDeviceType deviceType, String deviceID)? onLocalDeviceExceptionOccurred;
...
}4. Check if Display is Normal
If the display is normal at this time, the camera is working properly and can be used for calls.
Speaker Detection
Detection Logic
The playback device detection process is shown in the following figure:
Corresponding Interfaces
1. Use Media Player to Play Audio Files
Call the ZegoMediaPlayer interface to play the audio file you use for testing.
// 1. Create a player object.
var mediaPlayer = await ZegoExpressEngine.instance.createMediaPlayer();
// 2. Load resources.
String resourcePath = "xxx";
await mediaPlayer?.loadResource(resourcePath);
// 3. Play resources.
mediaPlayer?.start();2. Check if Sound is Heard
If you can hear the corresponding audio, the playback device is working properly and can be used for calls. Call the onMediaPlayerStateUpdate callback to check the player status:
class ZegoExpressEngine {
...
/**
* Player playback status callback.
* @param mediaPlayer The callback player instance.
* @param state Player status.
* @param errorCode Error code, please refer to common error codes: /real-time-video-flutter/error-code#7.
*/
static void Function(ZegoMediaPlayer mediaPlayer, ZegoMediaPlayerState state, int errorCode)? onMediaPlayerStateUpdate;
...
}