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 SDK provides the following methods for device test:

• The startEchoTestWithInterval method, which tests whether the network connection and the audio devices, such as the microphone and the speaker, are working properly.
• The startRecordingDeviceTest method, which tests whether the local audio recording devices, such as the microphone, are working properly.
• The startPlaybackDeviceTest method, which tests whether the local audio playing devices, such as the external audio player, are working properly.
• The startAudioDeviceLoopbackTest method, which tests whether the local audio device loopback is 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 pre-call testing

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 startEchoTestWithInterval before joining a channel. You need to set the interval 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.

// swift
// Start the echo test
// Only a broadcaster can call startEchoTestWithInterval.
agoraKit.startEchoTestWithInterval(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 using joinChannelByToken.
agoraKit.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 reportAudioVolumeIndicationOfSpeakers 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.

// swift
agoraKit.startRecordingDeviceTest(1000)

agoraKit.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 a reportAudioVolumeIndicationOfSpeakers callback, and reports uid = 1 and the volume information of the devices.
3. When the test finishes, call the stopPlaybackDeviceTest method tostop the current test.

// swift
agoraKit.startPlaybackDeviceTest("audio file path")

agoraKit.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 reportAudioVolumeIndicationOfSpeakers callbacks and reports the volume information of the audio capture device (uid= 0) and the audio playback device (uid= 1).
3. When the test finishes, call the stopAudioDeviceLoopbackTest method to stop the current test.

// swift
agoraKit.startAudioDeviceLoopbackTest(1000)

agoraKit.stopAudioDeviceLoopbackTest()

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 uplink and downlink bitrate in this method.

   // swift
   let config = AgoraLastmileProbeConfig()
   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;
   
   // Call startLastmileProbeTest to start the network probe test
   // 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 lastmileProbeTest callback.
   agoraKit.startLastmileProbeTest(config)

2. After this method is called, the SDK returns the following callbacks:

   • lastmileQuality: 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.
   • lastmileProbeResult: Returned 30 seconds after calling startLastmileProbeTest. This callback returns the real-time statistics of the network quality, so it is more objective.

   // swift
   // Return the lastmileQuality callback about 2 seconds after calling startLastmileProbeTest. This callback reports once every two seconds.
   // lastmileQuality might return Unknown the first time it is triggered. Subsequent callbacks return the test results.
   func rtcEngine(_ engine: AgoraRtcEngineKit, lastmileQuality quality: AgoraNetworkQuality) {
       lastmileResultLabel.stringValue = "Quality: \(quality.description())"
   }
   
   // Return the lastmileProbeResult callback about 30 seconds after calling startLastmileProbeTest. This callback offers more detailed statistics of the network quality.
   func rtcEngine(_ engine: AgoraRtcEngineKit, lastmileProbeTest result: AgoraLastmileProbeResult) {
     // The round-trip latency
     let rtt = "Rtt: \(result.rtt)ms"
     // The downlink network bandwidth
     let downlinkBandWidth = "DownlinkAvailableBandwidth: \(result.downlinkReport.availableBandwidth)Kbps"
     // The downlink jitter buffer
     let downlinkJitter = "DownlinkJitter: \(result.downlinkReport.jitter)ms"
     // The downlink packet loss rate
     let downlinkLoss = "DownlinkLoss: \(result.downlinkReport.packetLossRate)%"
   
     // The uplink network bandwidth
     let uplinkBandwidth = "UplinkAvailableBandwidth: \(result.uplinkReport.availableBandwidth)Kbps"
     // The uplink jitter buffer
     let uplinkJitter = "UplinkJitter: \(result.uplinkReport.jitter)ms"
     // The uplink packet loss rate
     let uplinkLoss = "UplinkLoss: \(result.uplinkReport.packetLossRate)%"
   
    lastmileProbResultLabel.stringValue = [rtt, downlinkBandwidth, downlinkJitter, downlinkLoss,uplinkBandwidth,uplinkJitter,uplinkLoss].joined(separator: "\n")
   }

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

   // swift
   // Stop the last-mile network probe test.
   // You can call stopLastmileProbeTest to stop the test in the lastmileProbeResult method, or before you join the channel.
   agoraKit.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 PrecallTest.swift 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
• startEchoTestWithInterval
• stopEchoTest
• startLastmileProbeTest
• stopLastmileProbeTest
• lastmileQuality
• lastmileProbeResult