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:
This article describes how to implement these tests.
Agora provides an open-source macOS sample project on GitHub that implements pre-call detection in the PrecallTest.swift file. You can download the sample project to try it out or refer to the source code.
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.
Before proceeding, ensure that you have implemented basic real-time functions in your project.
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.lastmileQuality
: Triggered two seconds after startLastmileProbeTest
is called. This callback provides ratings of the uplink and downlink network quality and reflects the user experience.lastmileProbeResult
: Triggered 30 seconds after startLastmileProbeTest
is called. This callback provides real-time statistics of the network quality and is more objective.stopLastmileProbeTest
to stop the network probe test.The API call sequence is as follows:
Refer to the following sample code to implement this function in your project.
// Swift
let config = AgoraLastmileProbeConfig()
// Probes the uplink network.
config.probeUplink = true;
// Probes the downlink network.
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.
agoraKit.startLastmileProbeTest(config)
// Swift
// Receives the lastmileQuality callback two seconds after calling startLastmileProbeTest. This callback is triggered once every 2 seconds.
func rtcEngine(_ engine: AgoraRtcEngineKit, lastmileQuality quality: AgoraNetworkQuality) {
lastmileResultLabel.stringValue = "Quality: \(quality.description())"
}
// Receives the lastmileProbeResult callback 30 seconds after calling startLastmileProbeTest. This callback provides more detailed network quality statistics.
func rtcEngine(_ engine: AgoraRtcEngineKit, lastmileProbeTest result: AgoraLastmileProbeResult) {
// The round trip time delay.
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")
}
// Swift
// Stops the last-mile network probe test.
// You can call stopLastmileProbeTest either within the lastmileProbeResult callback, or at other time before joining a channel.
agoraKit.stopLastmileProbeTest()
To ensure smooth communications, we recommend conducting a media device test before joining a channel to check whether the microphone or camera works properly. This function applies to scenarios that have high-quality requirements, such as online education.
Before proceeding, ensure that you have implemented basic real-time functions in your project.
Refer to the following steps to start an echo test.
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 is [2,10], and the default value is 10 (in seconds).stopEchoTest
to stop the current test before joining a channel using joinChannelByToken
.Call the startEchoTestWithInterval
method to test if the audio devices, such as the microphone and the speaker, are working properly.
To conduct the test, call startEchoTestWithInterval
, and set the interval
parameter in this method to notify the SDK when to report the result of this test. The user speaks, and if the recording plays back within the set time interval, the audio devices and the network connection are working properly.
// Swift
// Start the echo test.
agoraKit.startEchoTestWithInterval(10)
// Wait and check if the user can hear the recorded audio.
// Stop the echo test.
agoraKit.stopEchoTest
Call the startRecordingDeviceTest
method to test whether the local audio recording device, such as the microphone, is working properly.
To conduct the test, call startRecordingDeviceTest
and set the indicationInterval
parameter in this method to notify the SDK when to report the result of this test. The user speaks, and the SDK reports the audio volume information in the reportAudioVolumeIndication
callback. A UID of 0
indicates the local user.
When the test finishes, call the stopRecordingDeviceTest
method to stop the current test.
indicationInterval
greater than 200 ms. Do not set the interval smaller than 10 ms, or the reportAudioVolumeIndication
callback will not be triggered.// Swift
agoraKit.startRecordingDeviceTest(1000)
agoraKit.stopRecordingDeviceTest()
Call the startPlaybackDeviceTest
method to test whether the local audio playback device, such as the speaker, is working properly.
To conduct the test, specify an audio file for playback and call startPlaybackDeviceTest
. If you can hear the audio file, the audio playback device works properly. The SDK triggers a reportAudioVolumeIndication
callback to report the audio volume information of the audio playback device with a UID of 1
When the test finishes, call the stopPlaybackDeviceTest
method to stop the current test.
// Swift
agoraKit.startPlaybackDeviceTest("audio file path")
agoraKit.stopPlaybackDeviceTest()
Call the startAudioDeviceLoopbackTest
method to test whether the local audio devices, including the microphones and speakers, are working properly.
To conduct the test, call startAudioDeviceLoopbackTest
and set the indicationInterval
parameter in this method to notify the SDK when to report the result of this test. The user speaks, then the microphone captures the local audio and plays it through the speaker. The SDK triggers two reportAudioVolumeIndication
callbacks. One callback reports the audio volume information of the microphone with a UID of 0
; the other callback reports the audio volume information of the speaker with a UID of 1
.
When the test finishes, call the stopAudioDeviceLoopbackTest
method to stop the current test.
indicationInterval
greater than 200 ms. Do not set the interval smaller than 10 ms, or the reportAudioVolumeIndication
callback will not be triggered.// Swift
agoraKit.startAudioDeviceLoopbackTest(50)
agoraKit.stopAudioDeviceLoopbackTest()
After calling the enableVideo
method, call the startCaptureDeviceTest
method to test whether the local video devices, such as the camera, are working properly.
To conduct the test, specify a window view that displays the image. If you can see the local video view, the video devices work properly.
When the test finishes, call the stopCaptureDeviceTest
method to stop the current test.
// Swift
agoraKit.startCaptureDeviceTest(videos[0])
agoraKit.stopCaptureDeviceTest()
startEchoTestWithInterval
stopEchoTest
startRecordingDeviceTest
stopRecordingDeviceTest
startPlaybackDeviceTest
stopPlaybackDeviceTest
startCaptureDeviceTest
stopCaptureDeviceTest
startAudioDeviceLoopbackTest
stopAudioDeviceLoopbackTest
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.lastmileQuality
callback may return Unknown
the first time it is triggered. Subsequent callbacks will return the test results.startEchoTestWithInterval
.stopEchoTest
to stop it. Otherwise, you cannot conduct another echo test or join a call using joinChannelByToken
.