Pre-call Diagnostics

Pre-call Diagnostic APIs

The Pre-call Diagnostic APIs provide two types of functionalities :

1. APIs to test the connected input and output 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 initialize an instance of HMSDiagnostics from the HMSActions instance.

// get the HMSSDK instance
const diagnostics = hmsActions.initDiagnostics();

Request Permissions

If you want a list of devices to choose from before testing your devices you'll need to request corresponding permissions using

diagnostics?.requestPermission({ audio: true, video: true }).catch((error) => setError(error));

Test Microphone

To test if the microphone is correctly working, call the startMicCheck API passing the preferred check duration as the timeInMillis parameter. Diagnostics SDK will record the microphone input into a temporary file.

You can use the selectTrackAudioByID selector to get the input audio level during recording

hmsDiagnostics?.startMicCheck({
    inputDevice,
    onError,
    onStop,
    time, // in ms, default 10 seconds
});

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

Test Speaker

You can check if the speaker is working correctly if you are able to properly play audio using the HTMLAudioElement by using the pre-recorded audio file from startMicCheck using the getRecordedAudio API or using the test audio from https://100ms.live/test-audio.wav if such pre-recorded audio is not available.

const element = new HTMLAudioElement();
element.src = hmsDiagnostics?.getRecordedAudio() || 'https://100ms.live/test-audio.wav';
if (typeof element.setSinkId !== 'undefined') {
    // @ts-ignore
    const { audioOutputDeviceId } = hmsStore.getState(selectLocalMediaSettings);
    element.setSinkId(audioOutputDeviceId);
}
element.play();

You can set the audio output device ID using HMSActions like hmsActions.setAudioOutputDevice(deviceId);

Refer to this file for a full working example to test the microphone and speaker in React: https://github.com/100mslive/web-sdks/blob/main/packages/roomkit-react/src/Diagnostics/AudioTest.tsx

Test Camera

Similar to testing the microphone, to check if the camera on the device is working fine, call the startCameraCheck API. This API creates a local video track and sets it on the local peer. Applications can use the hmsStore in conjunction with selectLocalVideoTrackID to fetch the video track and use HTMLVideoElement 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.

await diagnostics?.startCameraCheck(deviceId);
const track = hmsStore.getState(selectLocalVideoTrackID);
await hmsActions.attachVideo(track.id, videoElement);

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

To try a different camera, you can stop and start the camera check again with a different device ID.

Refer to this file for a full working example to test the microphone and speaker in React: https://github.com/100mslive/web-sdks/blob/main/packages/roomkit-react/src/Diagnostics/VideoTest.tsx

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 the upload and download bandwidth of the user's network. Please note that Camera and microphone permissions need to be provided by the app before making a call to this API This test runs for 20 seconds. It may finish earlier if the connection cannot be established.

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

hmsDiagnostics
    ?.startConnectivityCheck(
        (state) => {
            setProgress(state);
        },
        (result) => {
            setResult(result);
        },
        region
    )
    .catch((error) => {
        setError(error);
    });

Understanding ConnectivityState updates

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

enum ConnectivityState {
    STARTING = 0,
    INIT_FETCHED = 1,
    SIGNAL_CONNECTED = 2,
    ICE_ESTABLISHED = 3,
    MEDIA_CAPTURED = 4,
    MEDIA_PUBLISHED = 5,
    COMPLETED = 6
}

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 callback is executed with the test result in ConnectivityCheckResult 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