Introduction

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.

Implementation

Ensure that you understand how to start a call or start live interactive streaming. See details in the following quickstarts:

Choose either of the following ways to test the audio or video devices:

  • Call StartAudioRecordingDeviceTest or StartEchoTest to test the audio recording devices. When you want to stop the test, call StopAudioRecordingDeviceTest or StopEchoTest.
  • Call StartAudioPlaybackDeviceTest or StartEchoTest to test the audio playback devices. When you want to stop the test, call StopAudioPlaybackDeviceTest or StopEchoTest.
  • Call StartPreview to test the video devices. When you want to stop the test, call StopPreview.
Test the devices before joining a channel.

Recording device test

Call StartAudioRecordingDeviceTest or StartEchoTest to test whether the local audio recording device, such as the microphone, is working properly.

To conduct the test, the user speaks. If the SDK reports the audio volume information in the OnVolumeIndicationHandler callback, the audio recording device works properly. A UID of 0 indicates the local user.

When you want to stop the test, call StopAudioRecordingDeviceTest or StopEchoTest.

Sample code

// For Windows or macOS devices.
public void loadEngine(string appId)
{
    // Initializes the IRtcEngine.
    mRtcEngine = IRtcEngine.GetEngine (appId);
    mRtcEngine.OnVolumeIndication = OnVolumeIndicationHandler;
    // Retrieves the AudioRecordingDeviceManager object.
    AudioRecordingDeviceManager audioRecordingDeviceManager = (AudioRecordingDeviceManager)mRtcEngine.GetAudioRecordingDeviceManager();
    // Creates an AudioRecordingDeviceManager instance.
    audioRecordingDeviceManager.CreateAAudioRecordingDeviceManager();
    // Retrieves the total number of the indexed audio recording devices in the system.
    int count = audioRecordingDeviceManager.GetAudioRecordingDeviceCount();
    // Retrieves the device ID of the target audio recording device. The value of index should not more than the number retrieved from GetAudioRecordingDeviceCount.
    audioRecordingDeviceManager.GetAudioRecordingDevice(0, ref deviceNameA, ref deviceIdA);
    // Sets the audio recording device using the device ID.
    audioRecordingDeviceManager.SetAudioRecordingDevice(deviceIdA);
    // Enables the audio volume callback.
    mRtcEngine.EnableAudioVolumeIndication(300, 3, true);
    // Starts the audio recording device test.
    audioRecordingDeviceManager.StartAudioRecordingDeviceTest(300);
    // Stops the audio recording device test.
    audioRecordingDeviceManager.StopAudioRecordingDeviceTest();
    // Releases AudioRecordingDeviceManager instance.
    audioRecordingDeviceManager.ReleaseAAudioRecordingDeviceManager();
}

// Implements the audio volume callback. 
void OnVolumeIndicationHandler(AudioVolumeInfo[] speakers, int speakerNumber, int totalVolume)
{

}
// For Android or iOS devices.
public void loadEngine(string appId)
{
    // Initializes the IRtcEngine.
    mRtcEngine = IRtcEngine.GetEngine (appId);   
    // Starts an audio device test.
    mRtcEngine.StartEchoTest(10);
    // Stops the audio device test.
    mRtcEngine.StopEchoTest();
}

API reference

Playback device test

Call StartAudioPlaybackDeviceTest or StartEchoTest 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 you want to stop the test, call StopAudioPlaybackDeviceTest or StopEchoTest.

Sample code

// For Windows or macOS devices.
public void loadEngine(string appId)
{
    // Initializes the IRtcEngine.
    mRtcEngine = IRtcEngine.GetEngine (appId);
    mRtcEngine.OnVolumeIndication = OnVolumeIndicationHandler;
    // Retrieves the AudioPlaybackDeviceManager object.
    AudioPlaybackDeviceManager audioPlaybackDeviceManager = (AudioPlaybackDeviceManager)mRtcEngine.GetAudioPlaybackDeviceManager();
    // Creates an AudioPlaybackDeviceManager instance.
    audioPlaybackDeviceManager.CreateAAudioPlaybackDeviceManager();
    // Retrieves the total number of the indexed audio playback devices in the system.
    int count = audioPlaybackDeviceManager.GetAudioPlaybackDeviceCount();
    // Retrieves the device ID of the target audio playback device. The value of index should not more than the number retrieved from GetAudioPlaybackDeviceCount.
    audioPlaybackDeviceManager.GetAudioPlaybackDevice(0, ref deviceNameA, ref deviceIdA);
    // Sets the audio playback device using the device ID.
    audioPlaybackDeviceManager.SetAudioPlaybackDevice(deviceIdA);
    // Enables the audio volume callback.
    mRtcEngine.EnableAudioVolumeIndication(300, 3, true);
    // Starts the audio playback device test.
    audioPlaybackDeviceManager.StartAudioPlaybackDeviceTest(300);
    // Stops the audio playback device test.
    audioPlaybackDeviceManager.StopAudioPlaybackDeviceTest();
    // Releases AudioPlaybackDeviceManager instance.
    audioPlaybackDeviceManager.ReleaseAAudioPlaybackDeviceManager();
}

// Implements the audio volume callback. 
void OnVolumeIndicationHandler(AudioVolumeInfo[] speakers, int speakerNumber, int totalVolume)
{

}
// For Android or iOS devices.
public void loadEngine(string appId)
{
    // Initializes the IRtcEngine.
    mRtcEngine = IRtcEngine.GetEngine (appId);   
    // Starts an audio device test.
    mRtcEngine.StartEchoTest(10);
    // Stops the audio device test.
    mRtcEngine.StopEchoTest();
}

API reference

Video device test

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

After calling EnableVideo and EnableVideoObserver, call StartPreview to test whether the local video devices, such as the camera and renderer, are working properly. If you can see the local video view, the video devices work properly.

When you want to stop the test, call StopPreview.

  • To get video raw data, ensure that you call both EnableVideo and EnableVideoObserver methods.
  • You cannot get a window handler in Unity, so Agora doesn't recommend to use the StartVideoDeviceTest method to test a video device.
  • Sample code

    // For Windows or macOS devices.
    public void loadEngine(string appId)
    {
        // Initializes IRtcEngine.
        mRtcEngine = IRtcEngine.GetEngine (appId);
        // Retrieves the VideoDeviceManager object.
        VideoDeviceManager videoDeviceManager = (VideoDeviceManager)mRtcEngine.GetVideoDeviceManager();
        // Creates a VideoDeviceManager instance.
        videoDeviceManager.CreateAVideoDeviceManager();
        // Retrieves the total number of the indexed video devices in the system.
        videoDeviceManager.GetVideoDeviceCount();
        // Retrieves the device ID of the target video device. The value of index should not more than the number retrieved from GetVideoDeviceCount.
        videoDeviceManager.GetVideoDevice(0, deviceNameA, deviceIdA);
        // Sets the video device using the device ID.
        videoDeviceManager.SetVideoDevice(deviceIdA);
        // Enables the video module.
        int mRtcEngine.EnableVideo();
        // Enables the video observer.
        int mRtcEngine.EnableVideoObserver();
        // Starts the video preview.
        int mRtcEngine.StartPreview();
        // Stops the video preview.
        int mRtcEngine.StopPreview();
        // Releases the VideoDeviceManager instance.
        videoDeviceManager.ReleaseAVideoDeviceManager();
    }

    API Reference

    Considerations

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