This topic describes how to test your devices before a call.
Overview
The Alibaba Real-Time Communication (ARTC) SDK provides pre-call device detection features that you can use to test local audio and video devices, including the microphone, speaker, and camera. Testing for hardware issues beforehand helps prevent unexpected device failures and ensures a smooth communication experience.
Sample code
Android: Android/ARTCExample/AdvancedUsage/src/main/java/com/aliyun/artc/api/advancedusage/PreJoinChannelTest/PreJoinChannelTestActivity.java.
iOS: iOS/ARTCExample/AdvancedUsage/PreJoinChannelTest/PreJoinChannelTestVC.swift.
Harmony: Harmony/ARTCExample/entry/src/main/ets/pages/advancedusage/PreJoinChannelTestPage.ets.
Implementation
1. Microphone test
Start the microphone. If no exceptions are reported and the captured audio volume is normal, the microphone is working correctly.
1. Start microphone test
Call the startAudioCaptureTest method to start capturing audio from the microphone.
Android
/**
* @brief Starts the audio capture device test before a call.
* @details This method starts the audio capture test.
* - Use the {@link AliRtcAudioVolumeObserver::onTestAudioVolumeCallback} callback to check if audio capture is working properly.
* @return
* - 0: Success.
* - A non-zero value: An error code.
* @note This method must be called before joining a channel with {@link joinChannel}.
*/
public abstract int startAudioCaptureTest();iOS
/**
* @brief Starts the audio capture device test before a call.
* @details This method starts audio capture.
* - Use the {@link onTestAudioVolumeCallback} callback to check if audio capture is working properly.
* @note This method must be called before joining a channel with {@link joinChannel}.
*/
- (void)startAudioCaptureTest;Windows
/**
* @brief Starts the audio capture test before a call.
* @details This method starts the audio capture test.
* - Use the {@link AliEngineEventListener::OnTestAudioVolumeCallback} callback to check if audio capture is working properly.
* @return
* - 0: Success.
* - A non-zero value: An error code.
* @note This method must be called before joining a channel with {@link JoinChannel}.
*/
virtual int StartAudioCaptureTest() = 0;2. Check for microphone exceptions
Listen for the following callback to detect device exceptions. If no exceptions are reported and the microphone volume is normal, the device is available for use.
Android
/**
* @brief Callback for local device exceptions.
* @param deviceType The device type. For more information, see {@link AliRtcEngine.AliRtcEngineLocalDeviceType}.
* @param exceptionType The exception type. For more information, see {@link AliRtcEngine.AliRtcEngineLocalDeviceExceptionType}.
* @param msg The exception message.
* @note This callback is triggered when an unrecoverable internal device exception occurs. When this callback is triggered, check if the device is available.
*/
public void OnLocalDeviceException(AliRtcEngine.AliRtcEngineLocalDeviceType deviceType, AliRtcEngine.AliRtcEngineLocalDeviceExceptionType exceptionType, String msg){}iOS
/**
* @brief Callback for local device exceptions.
* @param deviceType The device type. For more information, see {@link AliRtcLocalDeviceType}.
* @param exceptionType The exception type. For more information, see {@link AliRtcLocalDeviceExceptionType}.
* @param msg The exception message.
* @note This callback is triggered when an unrecoverable internal device exception occurs. When this callback is triggered, check if the device is available.
*/
- (void)onLocalDeviceException:(AliRtcLocalDeviceType)deviceType exceptionType:(AliRtcLocalDeviceExceptionType)exceptionType message:(NSString *_Nullable)msg;Windows
/**
* @brief Callback for local device exceptions.
* @param deviceType The device type. For more information, see {@link AliEngineLocalDeviceType}.
* @param exceptionType The exception type. For more information, see {@link AliEngineLocalDeviceExceptionType}.
* @param msg The exception message.
* @note This callback is triggered when an unrecoverable internal device exception occurs. When this callback is triggered, check if the device is available.
*/
virtual void OnLocalDeviceException(AliEngineLocalDeviceType deviceType, AliEngineLocalDeviceExceptionType exceptionType, const char* msg){};3. Check the microphone volume
Listen for the following callback to get the captured audio volume. If the volume data is normal, the microphone is working correctly and can be used in a call.
Android
/**
* @brief Callback for the audio volume during the pre-call test.
* @param volume The audio volume.
*/
public void OnTestAudioVolume(int volume) {}iOS
/**
* @brief Callback for the captured audio volume during the pre-call test.
* @param volume The audio volume.
*/
- (void)onTestAudioVolumeCallback:(int)volume;Windows
/**
* @brief Callback for the captured audio volume during the pre-call test.
* @param volume The audio volume.
*/
virtual void OnTestAudioVolumeCallback(int volume) {}4. Stop the microphone test
After confirming the microphone is working correctly, call stopAudioCaptureTest to stop the test.
Android
/**
* @brief Stops the audio capture test.
* @return
* - 0: Success.
* - A non-zero value: An error code.
* @note This method must be called before joining a channel with {@link joinChannel}.
*/
public abstract int stopAudioCaptureTest();iOS
/**
* @brief Stops the audio capture test.
* @note This method must be called before joining a channel with {@link joinChannel}.
*/
- (void)stopAudioCaptureTest;Windows
/**
* @brief Stops the audio capture test.
* @return
* - 0: Success.
* - A non-zero value: An error code.
* @note This method must be called before joining a channel with {@link JoinChannel}.
*/
virtual int StopAudioCaptureTest() = 0;2. Speaker test
Play an audio file. If you can hear the audio, the speaker is working correctly.
1. Play an audio file
Call the playAudioFileTest method to play a test audio file. If you can hear the sound, the speaker is working correctly.
Android
/**
* @brief Plays an audio file for testing.
* @param filePath The path to the audio file.
* @return Returns 0 on success, or a negative value on failure.
* @note This method must be called before joining a channel with {@link joinChannel}.
*/
public abstract int playAudioFileTest(String filePath) ;iOS
/**
* @brief Plays an audio file for testing.
* @param filePath The path to the audio file.
* @return Returns 0 on success, or a negative value on failure.
* @note This method must be called before joining a channel with {@link joinChannel}.
*/
- (int)playAudioFileTest:(NSString *_Nonnull)filePath;Windows
/**
* @brief Plays an audio file for testing.
* @param filePath The path to the audio file.
* @return Returns 0 on success, or a negative value on failure.
* @note This method must be called before joining a channel with {@link JoinChannel}.
*/
virtual int PlayAudioFileTest(const char* filePath) = 0;2. Check for speaker exceptions
Listen for the following callback to detect device exceptions. If no exceptions are reported and you can hear the audio, the speaker is working correctly.
Android
/**
* @brief Callback for local device exceptions.
* @param deviceType The device type. For more information, see {@link AliRtcEngine.AliRtcEngineLocalDeviceType}.
* @param exceptionType The exception type. For more information, see {@link AliRtcEngine.AliRtcEngineLocalDeviceExceptionType}.
* @param msg The exception message.
* @note This callback is triggered when an unrecoverable internal device exception occurs. When this callback is triggered, check if the device is available.
*/
public void OnLocalDeviceException(AliRtcEngine.AliRtcEngineLocalDeviceType deviceType, AliRtcEngine.AliRtcEngineLocalDeviceExceptionType exceptionType, String msg){}iOS
/**
* @brief Callback for local device exceptions.
* @param deviceType The device type. For more information, see {@link AliRtcLocalDeviceType}.
* @param exceptionType The exception type. For more information, see {@link AliRtcLocalDeviceExceptionType}.
* @param msg The exception message.
* @note This callback is triggered when an unrecoverable internal device exception occurs. When this callback is triggered, check if the device is available.
*/
- (void)onLocalDeviceException:(AliRtcLocalDeviceType)deviceType exceptionType:(AliRtcLocalDeviceExceptionType)exceptionType message:(NSString *_Nullable)msg;Windows
/**
* @brief Callback for local device exceptions.
* @param deviceType The device type. For more information, see {@link AliEngineLocalDeviceType}.
* @param exceptionType The exception type. For more information, see {@link AliEngineLocalDeviceExceptionType}.
* @param msg The exception message.
* @note This callback is triggered when an unrecoverable internal device exception occurs. When this callback is triggered, check if the device is available.
*/
virtual void OnLocalDeviceException(AliEngineLocalDeviceType deviceType, AliEngineLocalDeviceExceptionType exceptionType, const char* msg){};3. Stop playing the audio file
After confirming the speaker is working correctly, call stopAudioFileTest to stop the playback.
Android
/**
* @brief Stops playing the test audio file.
* @return Returns 0 on success, or a negative value on failure.
* @note This method must be called before joining a channel with {@link joinChannel}.
*/
public abstract int stopAudioFileTest();iOS
/**
* @brief Stops playing the test audio file.
* @return Returns 0 on success, or a negative value on failure.
* @note This method must be called before joining a channel with {@link joinChannel}.
*/
- (int)stopAudioFileTest;Windows
/**
* @brief Stops playing the test audio file.
* @return Returns 0 on success, or a negative value on failure.
* @note This method must be called before joining a channel with {@link JoinChannel}.
*/
virtual int StopAudioFileTest() = 0;3. Camera test
Set up the local preview view and start the camera. If the preview displays correctly and no exception callbacks are triggered, the camera is working correctly.
1. Set up local preview
Before starting the camera preview, call setLocalViewConfig to configure the display view.
Android
/**
* @brief Configures the view for local preview.
* @param viewConfig The display properties for the local video. For more information, see {@link com.alivc.rtc.AliRtcEngine.AliRtcVideoCanvas}.
* @param track Only {@link AliRtcVideoTrack#AliRtcVideoTrackCamera} and {@link AliRtcVideoTrack#AliRtcVideoTrackScreen} are supported.
* @return
* - 0: Success.
* - < 0: Failure.
* @note You can switch the view before or after you join a channel. If canvas or {@link AliRtcVideoCanvas#view} is null, rendering stops.
* To change the {@link AliRtcVideoCanvas#renderMode} or {@link AliRtcVideoCanvas#mirrorMode}, call this method again with the new value
* while keeping all other canvas properties the same.
*/
public abstract int setLocalViewConfig(AliRtcVideoCanvas viewConfig, AliRtcVideoTrack track);iOS
/**
* @brief Configures the view for local preview.
* @param viewConfig The display properties for the local video. For more information, see {@link AliVideoCanvas}.
* @param track Only {@link AliRtcVideoTrackCamera} and {@link AliRtcVideoTrackScreen} are supported.
* @return
* - 0: Success.
* - < 0: Failure.
* @note You can switch the view before or after you join a channel. If canvas or {@link AliVideoCanvas::view} is nil, rendering stops.
* To change the {@link AliVideoCanvas::renderMode} or {@link AliVideoCanvas::mirrorMode}, call this method again with the new value
* while keeping all other canvas properties the same.
*/
- (int)setLocalViewConfig:(AliVideoCanvas *_Nullable)viewConfig forTrack:(AliRtcVideoTrack)track;Windows
/**
* @brief Configures the view for local preview.
* @param renderConfig The display properties for the local video. For more information, see {@link AliEngineVideoCanvas}.
* @param track Only {@link AliEngineVideoTrackCamera} and {@link AliEngineVideoTrackScreen} are supported.
* @return
* - 0: Success.
* - A non-zero value: Failure.
* @note You can switch the view before or after you join a channel. If {@link AliEngineVideoCanvas::displayView} is null, rendering stops.
* To change the {@link AliEngineVideoCanvas::renderMode} or {@link AliEngineVideoCanvas::mirrorMode}, call this method again with the new value
* while keeping all other renderConfig properties the same.
*/
virtual int SetLocalViewConfig(AliEngineVideoCanvas renderConfig,
AliEngineVideoTrack track) = 0;2. Start the camera preview
Call the startPreview method to start the camera preview.
Android
/**
* @brief Starts the local video preview.
* @details This method starts the local video preview and automatically turns on the camera.
* @return
* - 0: Success.
* - < 0: Failure.
* @note A preview is not displayed if a view has not been configured with {@link #setLocalViewConfig}, but this does not affect stream ingest.
* You can call this method before {@link #joinChannel} to start the preview, which automatically turns on the camera.
*/
public abstract int startPreview();iOS
/**
* @brief Starts the local video preview.
* @return
* - 0: Success.
* - <0: Failure.
* @note A preview is not displayed if a view has not been configured by using {@link setLocalViewConfig:forTrack:}.
* You can call this method before {@link joinChannel:name:onResultWithUserId:} to start the preview, which automatically turns on the camera.
*/
- (int)startPreview;Windows
/**
* @brief Starts the local video preview.
* @return
* - 0: Success.
* - A non-zero value: Failure.
* @note A preview is not displayed if a view has not been configured by using {@link SetLocalViewConfig}.
* You can call this method before {@link JoinChannel} to start the preview, which automatically turns on the camera.
*/
virtual int StartPreview(int width = 0, int height = 0) = 0;3. Check for camera exceptions
Listen for the following callback to detect device exceptions. If no exceptions are reported and the preview displays correctly, the camera is working correctly.
Android
/**
* @brief Callback for local device exceptions.
* @param deviceType The device type. For more information, see {@link AliRtcEngine.AliRtcEngineLocalDeviceType}.
* @param exceptionType The exception type. For more information, see {@link AliRtcEngine.AliRtcEngineLocalDeviceExceptionType}.
* @param msg The exception message.
* @note This callback is triggered when an unrecoverable internal device exception occurs. When this callback is triggered, check if the device is available.
*/
public void OnLocalDeviceException(AliRtcEngine.AliRtcEngineLocalDeviceType deviceType, AliRtcEngine.AliRtcEngineLocalDeviceExceptionType exceptionType, String msg){}iOS
/**
* @brief Callback for local device exceptions.
* @param deviceType The device type. For more information, see {@link AliRtcLocalDeviceType}.
* @param exceptionType The exception type. For more information, see {@link AliRtcLocalDeviceExceptionType}.
* @param msg The exception message.
* @note This callback is triggered when an unrecoverable internal device exception occurs. When this callback is triggered, check if the device is available.
*/
- (void)onLocalDeviceException:(AliRtcLocalDeviceType)deviceType exceptionType:(AliRtcLocalDeviceExceptionType)exceptionType message:(NSString *_Nullable)msg;Windows
/**
* @brief Callback for local device exceptions.
* @param deviceType The device type. For more information, see {@link AliEngineLocalDeviceType}.
* @param exceptionType The exception type. For more information, see {@link AliEngineLocalDeviceExceptionType}.
* @param msg The exception message.
* @note This callback is triggered when an unrecoverable internal device exception occurs. When this callback is triggered, check if the device is available.
*/
virtual void OnLocalDeviceException(AliEngineLocalDeviceType deviceType, AliEngineLocalDeviceExceptionType exceptionType, const char* msg){};