Test a Media Device

Introduction

To ensure smooth communications, Agora recommends 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.

Implementation

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

• Choose either of the following ways to test the audio devices:
  • Call the startEchoTest method to test if the audio devices and network connection are working properly.
  • Call the startRecordingDeviceTest method to test the audio recording devices, and call the startPlaybackDeviceTest method to test the audio playback devices.
  • Call the startAudioDeviceLoopbackTest method to test the audio device loopback (including the recording and playback devices).
• Call the startCaptureDeviceTest method to test the video capture devices.

Echo test

Call the startEchoTest method to test if the audio devices, such as the microphone and the speaker, are working properly.

To conduct the test, call startEchoTest, 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.

// Start an echo test.
rtcEngine.startEchoTest(10);

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

// Stop the echo test.
rtcEngine.stopEchoTest;

Recording device test

Call the startRecordingDeviceTest method to test whether the local audio recording device, such as the microphone, is working properly.

To conduct the test, the user speaks, and the SDK reports the audio volume information in the onAudioVolumeIndication callback. A UID of 0 indicates the local user.

When the test finishes, call the stopRecordingDeviceTest method to stop the current test.

// Select an audio capture device.
lpDeviceManager->setRecordingDevice(strDeviceID); // device ID chosen

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

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

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

Playback device test

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. If you can hear the audio file, the audio playback device works properly.

When the test finishes, call the stopPlaybackDeviceTest method to stop the current test.

// Select an audio playback device.
lpDeviceManager->setPlaybackDevice(strDeviceID); // device ID chosen

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

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

Audio device loopback test

Call the startAudioDeviceLoopbackTest method to test whether the local audio devices, including the microphones and speakers, are working properly.

To conduct the test, the user speaks, then the microphone captures the local audio and plays it through the speaker. The SDK reports the audio volume information in the onAudioVolumeIndication callback. A UID of 0 indicates the local user.

When the test finishes, call the stopAudioDeviceLoopbackTest method to stop the current test.

Video device test

The video device tests check the video capture device and the video rendering device.

After calling the enableVideo method, call the startDeviceTest method to test whether the local video devices, such as the camera and renderer, are working properly.

To conduct the test, specify a window handle that displays the image. If you can see the local video view, the video devices work properly.

When the test finishes, call the stopDeviceTest method to stop the current test.

// Select a video capture device.
lpDeviceManager->setDevice(strDeviceID); // device ID chosen

// Start the video capture device test. If it succeeds, you will see a preview of the screen.
(*lpDeviceManager)->startDeviceTest(view); // Pass a window handler to it.

// Stop the video capture device test.
(*lpDeviceManager)->stopDeviceTest();

API Reference

• enableAudioVolumeIndication
• enumerateRecordingDevices
• setRecordingDevice
• enumeratePlaybackDevices
• setPlaybackDevice
• startRecordingDeviceTest
• stopRecordingDeviceTest
• startAudioDeviceLoopbackTest
• stopAudioDeviceLoopbackTest
• enumerateVideoDevices
• startDeviceTest
• stopDeviceTest

Considerations

• Ensure that your audio or video device is not being used by any third-party app when you conduct the test.
• After the test finishes, ensure that you call the corresponding stop method to stop the current test before calling the joinChannel method.