Pre-call Network and Device Tests

For calls and events that require high quality audio and video, best practice is to ensure that both the hardware your app is running on and the last mile between the device and Agora Platform are good enough to assure the quality you require. This improves the user experience and helps you troubleshoot.

This page shows you how to implement network and device tests in your app.

Understand the tech

In telecommunications, a probe is an action taken or an object used for the purpose of learning something about the state of the network. For example, an empty message can be sent simply to see whether the destination exists.

The following measures are important:

• Bandwidth - the maximum rate that information can be transferred, commonly measured in bits/second
• Throughput - the actual rate that information is transferred
• Latency - the delay between the sender sending information and the receiver decoding it. This is mainly a function of the signal's travel time and the processing time at any nodes the information traverses
• Jitter - variation in packet delay at the receiver of the information
• Error rate - the number of corrupted bits expressed as a percentage or fraction of the total sent

A device test checks if the audio captured from a device can be played back after it has passed through a network. The test captures audio from the microphone of the device and sends it to Agora Platform with a defined wait time, such as 5 seconds. After the wait time, Agora Platform sends the audio back to the device, and it is played through the speaker of the device. You can then judge if the audio is of adequate quality.

Agora recommends that you perform a device test before starting a network probe test.

Device test

The startEchoTest method probes whether the network connection and the audio devices, such as the microphone and the speaker, are working properly.

Network probe test

The startLastmileProbeTest method probes the last-mile network before you join a channel and returns statistics about the network quality, including round-trip latency, packet loss rate, and network bandwidth.

The API call sequence is as follows:

When you conduct the last-mile network test, the Video SDK adjusts the actual bitrate according to the configuration file of the video.

Prerequisites

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

Implement channel connection management

To implement pre-call testing in your project, refer to the following steps.

Device test

Echo test

To start an echo test, refer to the following steps:

1. Call startEchoTest 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 (in seconds) is [[2,10]], and the default value is 10.
2. When the echo test starts, let the user speak for a while. If the recording plays back within the set time interval, the audio devices and the network connection are working properly.
3. Once you get the test result, call stopEchoTest to stop the current test, and call joinChannelByToken to join a channel.

Refer to the following code to implement the test in your project.

// Start the echo test
// Only a broadcaster can call startEchoTest.
   rtcEngine.startEchoTest(10);

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

// Stop the echo test.
// Once the echo test ends, you must call stopEchoTest to stop it.  Otherwise, you cannot conduct another echo test or join a channel.
    rtcEngine.stopEchoTest

Recording device test

To test the local recording devices, such as the microphone, refer to the following steps:

1. Call startRecordingDeviceTest, and set the indicationInterval parameter as the interval of triggering the callbacks.
2. Let the user speak for a while, and in the onAudioVolumeIndication callback, the SDK reports uid = 0 and the volume information of the devices.
3. When the test finishes, call the stopRecordingDeviceTest method to stop the current test.

// Choose an audio capturing device
lpDeviceManager->setRecordingDevice(strDeviceID);

// Implement the audio volume callback interface
virtual void onAudioVolumeIndication(const AudioVolumeInfo* speakers, unsigned int speakerNumber, int totalVolume) {
        (void)speakers;
        (void)speakerNumber;
        (void)totalVolume;
    }

// Start the audio capturing device test
(*lpDeviceManager)->startRecordingDeviceTest(1000);

// Stop the audio capturing device test.
(*lpDeviceManager)->stopRecordingDeviceTest();

Audio playback device test

To test the local audio playback devices, such as the speaker, refer to the following steps:

1. Call startPlaybackDeviceTest, and set the audioFileName parameter as the absolute path of the to-be-played audio file.
2. If you can hear the audio, the audio playback device is working properly. The SDK triggers an onAudioVolumeIndication callback, and reports uid= 1 and the volume information of the devices.
3. When the test finishes, call the stopPlaybackDeviceTest method to stop the current test.

// Choose an audio playback device
lpDeviceManager->setPlaybackDevice(strDeviceID);

// Specify an absolute path of the audio file, and start the playback device test.
(*lpDeviceManager)->startPlaybackDeviceTest(filePath);

// Stop the audio playback device test.
(*lpDeviceManager)->stopPlaybackDeviceTest();

Audio device loopback test

To start a local audio device loopback test, refer to the following steps:

1. Call startAudioDeviceLoopbackTest, and set the indicationInterval parameter as the interval of triggering the callbacks.
2. Let the user speak for a while, so that the voice is captured by the microphone and played by the speaker. The SDK returns two onAudioVolumeIndication callbacks and reports the volume information of the audio capturing device (uid= 0) and the audio playback device (uid= 1).
3. When the test finishes, call the stopAudioDeviceLoopbackTest method to stop the current test.

Network probe test

To implement the network probe test, refer to the following steps:

1. Call the startLastmileProbeTest method 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 this method is called, the SDK returns the following callbacks:

   • onLastmileQuality: Returned 2 seconds after calling startLastmileProbeTest. This callback rates the network quality with a score, so it is more closely linked to the user experience.
   • onLastmileProbeResult: Returned 30 seconds after calling startLastmileProbeTest. This callback returns the real-time statistics of the network quality, so it is more objective.

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

// Register the callback interface
// Triggered about 2 seconds after the last-mile network probe starts
void onLastmileQuality(int quality) {
}

// Triggered about 30 seconds after the last-mile network probe starts
void onLastmileProbeResult(LastmileProbeResult) {
  // (1) Choose to end the test in the callback. Agora recommends not calling any other API methods before the test ends.
  lpAgoraEngine->stopLastmileProbeTest();
}

// Configure a LastmileProbeConfi object
LastmileProbeConfig config;
// Check the uplink network quality probe test
config.probeUplink = true;
// Check the downlink network quality probe test
config.probeDownlink = true;
// The expected maximum sending bitrate (bps). The value range is [100000,5000000].
config.expectedUplinkBitrate = 100000;
// The expected maximum receiving bitrate (bps). The value range is [100000,5000000].
config.expectedDownlinkBitrate = 100000;
// Start the last-mile network probe test before joining a channel
lpAgoraEngine->startLastmileProbeTest(config);

// (2) or choose to end the test at another time. Agora recommends not calling any other API methods before the test ends.
lpAgoraEngine->stopLastmileProbeTest();

Reference

This section includes in-depth information about the methods used in this page and links to related pages.

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.

API reference

• startRecordingDeviceTest
• stopRecordingDeviceTest
• startPlaybackDeviceTest
• stopPlaybackDeviceTest
• startAudioDeviceLoopbackTest
• stopAudioDeviceLoopbackTest
• startEchoTest
• stopEchoTest
• startLastmileProbeTest
• stopLastmileProbeTest
• onlastmileQuality
• onlastmileProbeResult