Pre-call Network and Device Tests

Description

In real-time scenarios requiring high quality, conducting tests before joining a channel helps troubleshoot in advance and improve the overall user experience. You can perform the following pre-call tests:

• Network test: Detects the network quality by probing the uplink and downlink last-mile network quality.
• Device test: Checks if the local audio recording and playback devices work properly.

This article describes how to implement these tests.

Sample project

Agora provides an open-source sample project that implements pre-call tests on GitHub. You can download the sample project to try it out or refer to the source code.

Network probe test

As of v2.4.0, the Agora RTC Native SDK provides the startLastmileProbeTest method that probes the last-mile network before joining a channel and returns statistics about the network quality, including round-trip latency, packet loss rate, and network bandwidth.

Implementation

Before proceeding, ensure that you have implemented basic real-time functions in your project. See Start a Call or Start Interactive Live Streaming.

Refer to the following steps to implement the network probe test:

1. Call the startLastmileProbeTest to start the network probe test before joining a channel or switching the user role. You need to specify the expected upstream and downstream bitrate in this method.
2. After the method call, the SDK triggers the following callbacks:

• onLastmileQuality: Triggered two seconds after the startLastmileProbeTest method is called. This callback rates the network conditions with a score and is more closely linked to the user experience.
• onLastmileProbeResult: Triggered 30 seconds after the startLastmileProbeTest method is called. This callback returns the real-time statistics of the network conditions and is more objective.

3. After getting the network quality statistics, call the stopLastmileProbeTest method to stop the last-mile network probe test.

The API call sequence is as follows:

Sample code

Refer to the following code to implement the last-mile test in your project.

// Configure a LastmileProbeConfig instance.
LastmileProbeConfig config = new LastmileProbeConfig(){};
// Probe the uplink network quality.
config.probeUplink =  true;
// Probe the downlink network quality.
config.probeDownlink = true;
// The expected uplink bitrate (bps). The value range is [100000,5000000].
config.expectedUplinkBitrate = 100000;
// The expected downlink bitrate (bps). The value range is [100000,5000000].
config.expectedDownlinkBitrate = 100000;
// Start the last-mile network test before joining the channel.
rtcEngine.startLastmileProbeTest(config);

// Implemented in the global IRtcEngineEventHandler class.
// Triggered 2 seconds after starting the last-mile test.
public void onLastmileQuality(int quality){}

// Implemented in the global IRtcEngineEventHandler class.
// Triggered 30 seconds after starting the last-mile test.
public void onLastmileProbeResult(LastmileProbeResult) {
    // (1) Stop the test. Agora recommends not calling any other API method before the test ends.
    rtcEngine.stopLastmileProbeTest();
}

// (2) Stop the test in an alternate place. Agora recommends not calling any other API method before the test ends.
rtcEngine.stopLastmileProbeTest();

API reference

• startLastmileProbeTest
• stopLastmileProbeTest
• onLastmileQuality
• onLastmileProbeResult

Audio call loop test

As of v2.4.0, the Agora RTC Native SDK provides the startEchoTest [2/3] method that tests whether network connections and audio devices, such as the microphone and speaker, are working properly.

Implementation

Before proceeding, ensure that you have implemented basic real-time functions in your project. See Start a Call or Start Interactive Live Streaming.

1. Call startEchoTest [2/3] before joining a channel. You need to set the intervalInSeconds parameter in this method to notify the SDK when to report the result of this test. The value range is [2,10], and the default value is 10 (in seconds).

2. When the audio call loop test starts, let the user speak for a while. If the recording plays back within the set time interval, audio devices and network connections are working properly.

3. Once you get the test result, call stopEchoTest to stop the current test before joining a channel using joinChannel.

Sample code

// Start the echo test.
// Set the time interval between when you speak and when the recording plays back as 10 seconds.
rtcEngine.startEchoTest(10);

// Wait and check if the user can hear the recorded audio.

// Stop the echo test.
rtcEngine.stopEchoTest();

API reference

• startEchoTest [2/3]
• stopEchoTest

Audio and video call loop test

As of v3.5.2, the Agora RTC Native SDK provides the startEchoTest [3/3] method that tests whether the system's audio devices, video devices, and network connections are working properly.

Implementation

Before proceeding, ensure that you have implemented basic real-time functions in your project. See Start a Call or Start Interactive Live Streaming.

1. Call startEchoTest [3/3] before joining a channel. You need to set the config parameter in this method.
2. When the audio and video call loop test starts, let the user make a sound or face the camera. The audio or video is output after about two seconds. If the audio playback is normal, the audio device and the user's upstream and downstream network are working properly; if the video playback is normal, the video device and the user's upstream and downstream network are working properly.
3. Once you get the test result, call stopEchoTest to stop the current test before joining a channel using joinChannel.

Sample code

if (!echoTesting) {
    SurfaceView surfaceView = RtcEngine.CreateRendererView(getContext());
    // Add to the local container
    preview.addView(surfaceView, new FrameLayout.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT));
    EchoTestConfiguration config = new EchoTestConfiguration();
    config.enableAudio = true;
    config.enableVideo = true;
    config.channelId = "randomChannel";
    config.view = surfaceView;
    engine.startEchoTest(config);
    echoTesting = true;
    btn_echoVideo.setText(getText(R.string.stop_echo_video_audio_test));
} else {
    engine.stopEchoTest();
    if(preview.getChildCount() > 0)
    {
        preview.removeAllViews();
    }
    echoTesting = false;
    btn_echoVideo.setText(getText(R.string.start_echo_video_audio_test));
}

API reference

• startEchoTest [3/3]
• stopEchoTest

Considerations

• Calling startLastmileProbeTest for pre-call network quality detection consumes network traffic. Therefore, after calling this method, Agora recommends not calling any other method until you receive the onLastmileProbeResult callback.
• The onLastmileQuality callback may return UNKNOWN the first time it is triggered. Subsequent callbacks will return the test results.
• When conducting the last-mile probe test, the voice SDK uses a fixed bitrate of 48 Kbps. The video SDK adjusts the actual bitrate according to the video profile.
• In an interactive live streaming channel, only a host can call startEchoTest.
• Once the echo test ends, you must call stopEchoTest to stop it. Otherwise, you cannot conduct another echo test or join a call using joinChannel.