Pre-Call Diagnostics

Pre-Call Diagnostic APIs

The Pre-Call Diagnostic APIs provide two type of functionalities :

1. APIs to test the connected I/O devices like camera, mic and speaker functionality
2. APIs to test the connectivity to 100ms Servers - This can identify signaling and media connectivity issues and provide a report at the end of the test.

You can use these APIs in your application to detect issues before a Participant joins a video Room or as part of a troubleshooting page while already joined in the room or at a later stage to debug some issues at the end user's device/network

How to use the Pre-Call Diagnostic APIs

To use the diagnostic APIs first you need to get an instance of HMSDiagnostics from the HMSSDK instance.

            // get the HMSSDK instance
            var hmsSDK = HMSSDK.build()
            var diagnosticsSDK = hmsSDK.getDiagnosticsSDK()

If you are planning to use the connectivity checks while you have already joined a room, create a new instance of HMSSDK to get the HMSDiagnostics instance

Test Microphone

To test if the microphone is correctly working, call the startMicCheck API passing the preferred check duration as timeInMillis parameter. Diagnostics SDK will record the microphone input into a temporary file. completion callback will be called with the result of the check or error if any. onLevelChange is called every second with the decibel level detected by the microphone. This can be used on the UI to show an indication that mic is recording user's audio

Ensure app has NSMicrophoneUsageDescription set before running this check.

        diagnosticsSDK.startMicCheck(timeInMillis: 10000) { [weak self] result in
            switch result {
            case .success:
                // recording succeeded
            case .failure(let error):
                // error occured during recording
            }
        } onLevelChange: {  [weak self] level in
            self?.micLevel = level
        }

You can call stopMicCheck if you need to interrupt the check before the specified time has passed.

Test Speaker

To test the device speaker phone, call the startSpeakerCheck API. This will playback the file that was recorded while testing mic. If there is no recorded file present in the cache, either due to microphone issues or startMicCheck not being called, the speaker test API will play a pre-recorded file

You can check if the speaker is working correctly if you are able to properly listen to the recording from startMicCheck API or the pre recorded file

        diagnosticsSDK.startSpeakerCheck { [weak self] result in
            switch result {
            case .success:
                // playback succeeded
            case .failure(let error):
                // error occured during playback
            }
        }

To stop the speaker check, call the stopSpeakerCheck API.

Test Camera

To check if the camera on the device is working fine, call the startCameraCheck API. This API creates a local video track and returns it. Applications can use HMSVideoView to show the video track to users, using the same way any other HMSVideoTrack is shown. This API takes the device as a parameter, where you can specify either the front or back camera. By default front camera is chosen if nothing is specified

Ensure app has NSCameraUsageDescription set before running this check.

        var device: HMSVideoInputDevice
        
        switch selectedCamera {
        case "Back Camera":
            device = .backCamera
        default:
            device = .frontCamera
        }
        
        diagnosticsSDK.startCameraCheck(device: device) { [weak self] result in
            switch result {
            case .success(let track):
                // Use HMSVideoView to render the resulting track
            case .failure(let error):
                // Show error
            }
        }

To stop the camera check and release all the resources, call stopCameraCheck API

Test Connectivity to 100ms Servers

To test if there is proper connectivity to 100ms signalling and media servers, you have to call the startConnectivityCheck API. This API establishes connections to both the signalling and media server and publishes audio and video data to determine the network quality and generates a report of the connection. This API uses the local device's mic and camera to send audio-video data and receives back the same data to calculate network stats for both upload and download link of user's network. Please note that Camera and microphone permissions are needed to be provided by the app before making a call to this API This test runs for 20 seconds. It may finish earlier if connection cannot be established.

While the connectivity test is being performed, regular updates are sent by the SDK via the progress closure. The application can listen to these updates and notify the UI to show updates regarding the test. When the test is completed, completion closure is executed with the complete HMSConnectivityCheckResult that has details about all the reports generated.

        diagnosticsSDK.startConnectivityCheck(region: region) { [weak self] checkState in
            // Show state updates to the user
        } completion: { [weak self] result in
            // Show check results
        }

Understanding ConnectivityState updates

The startConnectivityCheck API sends regular updates while the test is going on. HMSConnectivityCheckState is an enum which has the following states:

           enum HMSConnectivityCheckState : Int {
            case starting
            case initFetched
            case signallingConnected
            case iceEstablished
            case mediaCaptured
            case mediaPublished
            case completed
           }

The above states can be used to show the progress of the test on UI

When the test completes - either successfully or un-successfully, the completion closure is executed with the test result in HMSConnectivityCheckResult which has the following fields:

HMSSignallingReport comprises of the following field

HMSMediaServerReport comprises of the following field:

In the stats, SDK reports the following stats for both audio and video separately in the stats field of HMSMediaServerReport