通话前网络和设备检测

功能描述

在对质量要求高的场景下，进行通话前检测可以帮助提前识别并排查问题，保证实时通信体验。通话前检测通常可以从如下两个角度开展：

• 网络质量探测：通过探测当前的上下行 last mile 网络质量，判断或预测用户当前的网络状况是否良好。
• 设备质量检测：检测本地音频采集设备和播放设备是否能正常工作。

Agora SDK 提供了完备的网络探测及设备检测接口，帮助你实现如上功能，保证用户的使用体验。本文介绍如何使用相关 API 实现上述功能。

示例项目

Agora 在 GitHub 上提供已实现通话前检测功能的开源示例项目。你可以下载体验或查看其中的源代码。

网络质量探测

从 v2.4.0 起，Agora RTC Native SDK 提供了一个 startLastmileProbeTest 方法，支持用户在加入频道前进行网络质量探测，然后通过回调将当前网络质量的相关数据，包括往返时延、上下行丢包率、上下行网络带宽等返回给 app。

实现方法

开始检测网络质量前，请确保你已在项目中实现了基本的音视频通信或直播功能。详见开始音视频通话或开始互动直播。

参考如下步骤了解相关 API 的工作原理。

1. 在用户加入频道或上麦前，调用 startLastmileProbeTest 进行网络质量探测。调用该方法时，你需要指定期望的最大上下行码率。
2. 启用该方法后，SDK 会依次返回如下 2 个回调：

• onLastmileQuality：约 2 秒内返回。该回调通过打分反馈上下行网络质量，更贴近主观感受
• onLastmileProbeResult：约 30 秒内返回。该回调通过客观数据反馈上下行网络质量，更客观

3. 获取到网络质量数据后，调用 stopLastmileProbeTest 停止通话前网络质量探测。

各 API 的调用时序如下图所示：

示例代码

你可以参考如下示例代码实现网络质量探测功能。

// 注册回调接口
// 开始 Last-mile 网络探测后，约 2 秒后发生该回调
void onLastmileQuality(int quality) {
}

// 开始 Last-mile 网络探测后，约 30 秒后发生该回调
void onLastmileProbeResult(LastmileProbeResult) {
  // (1)可以选择在回调内部结束测试。在测试结束前，Agora 建议不要调用其他 API 方法
  lpAgoraEngine->stopLastmileProbeTest();
}

// 配置一个 LastmileProbeConfig 实例
LastmileProbeConfig config;
// 确认探测上行网络质量
config.probeUplink = true;
// 确认探测下行网络质量
config.probeDownlink = true;
// 期望的最高发送码率，单位为 bps，范围为 [100000,5000000]
config.expectedUplinkBitrate = 100000;
// 期望的最高接收码率，单位为 bps，范围为 [100000,5000000]
config.expectedDownlinkBitrate = 100000;
// 加入频道前开始 Last-mile 网络探测
lpAgoraEngine->startLastmileProbeTest(config);

// (2)也可以选择在其他时候结束测试。在测试结束前，Agora 建议不要调用其他 API 方法
lpAgoraEngine->stopLastmileProbeTest();

API 参考

• startLastmileProbeTest
• stopLastmileProbeTest
• onLastmileQuality
• onLastmileProbeResult

设备质量检测

为保证通话或直播质量，我们推荐进行音视频设备测试，检测麦克风、摄像头等音视频设备能否正常工作。该功能对于有高质量要求的场景，如在线教育等，尤为适用。

开始前请确保已在项目中实现了基本的音视频通话或直播功能。详见实现音视频通话或互动直播。

参考以下步骤测试音视频设备：

• 选择以下一种方式测试音频设备：
  • 调用 startEchoTest [2/3] 测试系统的音频设备（耳麦、扬声器等）和网络连接。
  • 调用 startRecordingDeviceTest 测试音频采集设备，调用 startPlaybackDeviceTest 测试音频播放设备。
  • 调用 startAudioDeviceLoopbackTest 测试音频设备回路（包括音频采集设备和音频播放设备）。
• 调用 startDeviceTest 方法测试视频采集设备。
• 调用 startEchoTest [3/3] 测试系统的音频设备、视频设备、网络连接。

音频通话回路测试

• 用途：测试系统的音频设备（耳麦、扬声器等）和网络连接，是否正常工作。
• 测试方法和原理：调用 startEchoTest [2/3]，并使用该方法的 intervalInSeconds 参数设置返回测试结果的时间间隔，然后让用户说话。SDK 在设定的时间间隔后，如果能正常播放该用户说的话，则说明音频设备及网络连接正常。

void CAgoraPreCallTestDlg::OnEchoTest1()
{
    m_lstInfo.InsertString(m_lstInfo.GetCount(), _T("Start Audio Call Loop Test."));
    m_lstInfo.InsertString(m_lstInfo.GetCount(), _T("You will hear your voice after 10 secs"));
    m_rtcEngine->startEchoTest(10);
}

音视频通话回路测试

• 用途：测试系统的音频设备、视频设备、网络连接是否正常。
• 测试方法和原理：调用 startEchoTest [3/3]，并使用该方法的 config 参数设置测试配置。引导用户发出声音或面对摄像头。如果音频设备和网络连接正常，音频会在约 2 秒后播放出来；如果视频设备和网络连接正常，视频会在约 2 秒后播放出来。

void CAgoraPreCallTestDlg::OnEchoTest2()
{
    if (!m_echoTest)
    {
        m_lstInfo.InsertString(m_lstInfo.GetCount(), _T("Start Audio and Video Call Loop Test."));
        EchoTestConfiguration config;
        config.channelId = "randomChannel";
        config.enableAudio = true;
        config.enableVideo = true;
        config.view = m_VideoTest.GetVideoSafeHwnd();
        m_rtcEngine->startEchoTest(config);
        m_echoTest = true;
        m_btnEchoTest2.SetWindowText(PerCallTestCtrlStopEchoTest);
    }
    else
    {
        m_lstInfo.InsertString(m_lstInfo.GetCount(), _T("Stop Audio and Video Call Loop Test."));
        m_rtcEngine->stopEchoTest();
        m_echoTest = false;
        m_btnEchoTest2.SetWindowText(PerCallTestCtrlStartEchoTest);
    }
}

音频采集设备测试

调用 startRecordingDeviceTest 方法可测试本地音频采集设备，如麦克风，是否正常工作，具体实现步骤如下：

1. 监听 onAudioDeviceTestVolumeIndication 回调。
2. 调用 startRecordingDeviceTest，并使用该方法的 indicationInterval 参数设置返回 onAudioDeviceTestVolumeIndication 的间隔。
3. 用户说话，SDK 使用音频采集设备采集本地音频并触发 onAudioDeviceTestVolumeIndication 回调报告采集设备的音量信息。
4. 完成测试后，调用 stopRecordingDeviceTest 停止采集设备测试。

以下示例代码展示使用 onAudioDeviceTestVolumeIndication 回调在加入频道前进行音频设备测试：

// 选择一个音频采集设备
lpDeviceManager->setRecordingDevice(strDeviceID);

// 实现音频音量回调接口
virtual void onAudioDeviceTestVolumeIndication(AudioDeviceTestVolumeType volumeType, int volume) {
 (void)volumeType;
 (void)volume;
 }

// 开始音频采集设备测试
(*lpDeviceManager)->startRecordingDeviceTest(1000);

// 停止音频采集设备测试
(*lpDeviceManager)->stopRecordingDeviceTest();

音频播放设备测试

调用 startPlaybackDeviceTest 方法可测试本地音频播放设备，如外放设备，是否正常工作，具体实现步骤如下：

1. 监听 onAudioDeviceTestVolumeIndication 回调。
2. 调用 startPlaybackDeviceTest 并指定播放的音频文件。
3. SDK 使用本地音频播放设备播放音频文件并触发 onAudioDeviceTestVolumeIndication 回调报告播放设备的音量信息。
4. 完成测试后，调用 stopPlaybackDeviceTest 停止播放设备测试。

以下示例代码展示使用 onAudioDeviceTestVolumeIndication 回调在加入频道前进行音频设备测试：

// 选择一个音频播放设备
lpDeviceManager->setPlaybackDevice(strDeviceID);

// 实现音频音量回调接口
virtual void onAudioDeviceTestVolumeIndication(AudioDeviceTestVolumeType volumeType, int volume) {
 (void)volumeType;
 (void)volume;
 }

// 指定音频文件的绝对路径，启动播放设备测试。
(*lpDeviceManager)->startPlaybackDeviceTest(filePath);

// 停止音频播放设备测试。
(*lpDeviceManager)->stopPlaybackDeviceTest();

音频设备回路测试

调用 startAudioDeviceLoopbackTest 测试本地音频设备回路是否正常工作，具体实现步骤如下：

1. 监听 onAudioDeviceTestVolumeIndication 回调。
2. 调用 startAudioDeviceLoopbackTest，并使用该方法的 indicationInterval 参数设置返回 onAudioDeviceTestVolumeIndication 的间隔。
3. 用户说话，麦克风会采集本地讲话声音，然后用扬声器播放，同时 SDK 会返回两个 onAudioDeviceTestVolumeIndication 回调，分别报告采集设备和播放设备的音量信息。
4. 完成测试后，需调用 stopAudioDeviceLoopbackTest 停止录制设备测试。

视频设备测试

• 用途：测试本地视频设备，如摄像头和显示器，是否正常功能。
• 测试方法及原理：调用 enableVideo 开启视频模块后，调用 startDeviceTest，并指定显示图像的窗口句柄，如果能看到本地采集的图像，则说明视频设备正常工作。完成测试后，需调用 stopDeviceTest 停止视频设备测试。

// 选择一个视频采集设备
lpDeviceManager->setDevice(strDeviceID); 

// 开始视频采集设备测试，如果正常的话，你将会看到画面预览
(*lpDeviceManager)->startDeviceTest(view); 

// 停止视频采集设备测试
(*lpDeviceManager)->stopDeviceTest();

API 参考

• startEchoTest [2/3]
• startEchoTest [3/3]
• stopEchoTest
• enableAudioVolumeIndication
• enumerateRecordingDevices
• setRecordingDevice
• enumeratePlaybackDevices
• setPlaybackDevice
• startRecordingDeviceTest
• stopRecordingDeviceTest
• startAudioDeviceLoopbackTest
• stopAudioDeviceLoopbackTest
• enumerateVideoDevices
• startDeviceTest
• stopDeviceTest
• onAudioDeviceTestVolumeIndication
• onAudioVolumeIndication

开发注意事项

• 调用 startLastmileProbeTest 进行通话前网络质量探测时，会消耗一定的网络流量。因此调用方法后，Agora 建议在收到 lastmileProbeResult 回调之前不要调用其他方法，避免因 API 操作过于频繁导致其他方法无法执行。
• lastmileQuality 回调第一次报告的结果有一定概率是 UNKNOWN，可通过之后的几次回调获得结果。
• 开启网络测试后，音频 SDK 使用 48 Kbps 的固定探测码率；视频 SDK 则会根据当前选定的视频属性调整探测码率。
• 请确保进行测试时，相应的音视频设备没有被其他应用程序占用。
• 直播场景下，只有角色为主播的用户才能调用 startEchoTest。
• 无论是网络探测，还是设备质量测试，测试停止后，必须调用对应的 stop 方法以结束测试，否则无法进行下一次测试，也不能加入频道。