ApsaraVideo Live:Device detection before a call

1. Turn on the microphone

You can call the startAudioCaptureTest operation to enable audio collection from the microphone. The following describes the details.

/**
 * @brief Enable audio collection from the microphone before a voice or video call.
 * @details You can call this operation to enable audio collection from the microphone. 
 * - Check whether audio can be collected as expected based on {@link AliRtcAudioVolumeObserver::onTestAudioVolumeCallback}.
 * @return 
 * - 0: The request is successful.
 * - Values other than 0: An error code is returned.
 * @note You can call this operation only before joining the call {@link joinChannel}.
 */
public abstract int startAudioCaptureTest();

/**
 * @brief Enable audio collection from the microphone before a voice or video call.
 * @details You can call this operation to enable audio collection from the microphone.
 * - Check whether audio can be collected as expected based on {@link AliRtcAudioVolumeObserver::onTestAudioVolumeCallback}.
 * @note You can call this operation only before joining the call {@link joinChannel}.
 */
- (void)startAudioCaptureTest;

/**
 * @brief Enable audio collection from the microphone before a voice or video call.
 * @details You can call this operation to enable audio collection from the microphone.
 * - Check whether audio can be collected as expected based on {@link AliRtcAudioVolumeObserver::onTestAudioVolumeCallback}.
 * @return
 * - 0: The request is successful.
 * - Values other than 0: An error code is returned.
 * @note You can call this operation only before joining the call {@link joinChannel}.
 */
virtual int StartAudioCaptureTest() = 0;

2. Detect whether the microphone is abnormal

You can configure a callback to detect whether the microphone is abnormal. If no exceptions are detected on the microphone and the volume of collected audio is considered normal, the microphone can be used as expected. The following section describes the details about the callback.

/**
 * @brief The callback is invoked when a local device exception occurs.
 * @param deviceType The type of the device. For more information, see {@link AliRtcEngine.AliRtcEngineLocalDeviceType}
 * @param exceptionType The type of the device exception. For more information, see {@link AliRtcEngine.AliRtcEngineLocalDeviceExceptionType}
 * @param msg The information carried in the exception.
 * @note This callback identifies a device exception that cannot be resolved. After you receive the callback, check whether the device is available.
 */
public void OnLocalDeviceException(AliRtcEngine.AliRtcEngineLocalDeviceType deviceType, AliRtcEngine.AliRtcEngineLocalDeviceExceptionType exceptionType, String msg){}

/**
 * @brief The callback is invoked when a local device exception occurs.
 * @param deviceType The type of the device. For more information, see {@link AliRtcLocalDeviceType}
 * @param exceptionType The type of the device exception. For more information, see {@link AliRtcLocalDeviceExceptionType}
 * @param msg The information carried in the exception.
 * @note This callback identifies a device exception that cannot be resolved. After you receive the callback, check whether the device is available.
 */
- (void)onLocalDeviceException:(AliRtcLocalDeviceType)deviceType exceptionType:(AliRtcLocalDeviceExceptionType)exceptionType message:(NSString *_Nullable)msg;

/**
 * @brief The callback is invoked when a local device exception occurs.
 * @param deviceType The type of the device. For more information, see {@link AliEngineLocalDeviceType}
 * @param exceptionType The type of the device exception. For more information, see {@link AliEngineLocalDeviceExceptionType}
 * @param msg The information carried in the exception.
 * @note This callback identifies a device exception that cannot be resolved. After you receive the callback, check whether the device is available.
 */
virtual void OnLocalDeviceException(AliEngineLocalDeviceType deviceType, AliEngineLocalDeviceExceptionType exceptionType, const char* msg){};

3. Detect the volume of collected audio

You can configure a callback to detect the volume of collected audio. If no exceptions are detected, the microphone is considered normal and can be used as expected. The following section describes the details about the callback.

/**
 * @brief The callback is invoked to detect the volume of collected audio before a voice or video call.  
 * @param volume
 */
public void OnTestAudioVolume(int volume) {}

/**
 * @brief The callback is invoked to detect the volume of collected audio before a voice or video call.
 * @param volume
 */
- (void)onTestAudioVolumeCallback:(int)volume;

/**
 * @brief The callback is invoked to detect the volume of collected audio before a voice or video call.
 * @param volume
 */
virtual void OnTestAudioVolumeCallback(int volumn) {}

4. Stop the microphone detection

You can call the stopAudioCaptureTest operation to stop the microphone volume detection after you detect whether the microphone is abnormal.

/**
 * @brief Stop the volume detection of collected audio.
 * @return 
 * - 0: The request is successful.
 * - Values other than 0: An error code is returned.
 * @note You can call this operation only before joining the call {@link joinChannel}.
 */
public abstract int stopAudioCaptureTest();

/**
 * @brief Stop the volume detection of collected audio.
 * @note You can call this operation only before joining the call {@link joinChannel}.
 */
- (void)stopAudioCaptureTest;

/**
 * @brief Stop the volume detection of collected audio.
 * @return
 * - 0: The request is successful.
 * - Values other than 0: An error code is returned.
 * @note You can call this operation only before joining the call {@link JoinChannel}.
 */
virtual int StopAudioCaptureTest() = 0;

2. Detect a speaker

Play an audio file. If you can hear the corresponding audio, the speaker can be used as expected.

/**
 * @brief Play the audio file.
 * @param filePath The path of the file.
 * @return
 * - =0: The request is successful.
 * - <0: The request fails.
 * @note You can call this operation only before joining the call {@link joinChannel}.
 */
public abstract int playAudioFileTest(String filePath) ;

/**
 * @brief Play the audio file.
 * @param filePath The path of the file.
 * @return
 * - =0: The request is successful.
 * - <0: The request fails.
 * @note You can call this operation only before joining the call {@link joinChannel}.
 */
- (int)playAudioFileTest:(NSString *_Nonnull)filePath;

/**
 * @brief Play the audio file.
 * @param filePath The path of the file.
 * @return
 * - =0: The request is successful.
 * - <0: The request fails.
 * @note You can call this operation only before joining the call {@link JoinChannel}.
 */
virtual int PlayAudioFileTest(const char* filePath) = 0;

/**
 * @brief The callback is invoked when a local device exception occurs.
 * @param deviceType The type of the device. For more information, see {@link AliRtcEngine.AliRtcEngineLocalDeviceType}.
 * @param exceptionType The type of the device exception. For more information, see {@link AliRtcEngine.AliRtcEngineLocalDeviceExceptionType}.
 * @param msg The information carried in the exception.
 * @note This callback identifies a device exception that cannot be resolved. After you receive the callback, check whether the device is available.
 */
public void OnLocalDeviceException(AliRtcEngine.AliRtcEngineLocalDeviceType deviceType, AliRtcEngine.AliRtcEngineLocalDeviceExceptionType exceptionType, String msg){}

/**
 * @brief The callback is invoked when a local device exception occurs.
 * @param deviceType The type of the device. For more information, see {@link AliRtcLocalDeviceType}.
 * @param exceptionType The type of the device exception. For more information, see {@link AliRtcLocalDeviceExceptionType}.
 * @param msg The information carried in the exception.
 * @note This callback identifies a device exception that cannot be resolved. After you receive the callback, check whether the device is available.
 */
- (void)onLocalDeviceException:(AliRtcLocalDeviceType)deviceType exceptionType:(AliRtcLocalDeviceExceptionType)exceptionType message:(NSString *_Nullable)msg;

/**
 * @brief The callback is invoked when a local device exception occurs.
 * @param deviceType The type of the device. For more information, see {@link AliEngineLocalDeviceType}.
 * @param exceptionType The type of the device exception. For more information, see {@link AliEngineLocalDeviceExceptionType}.
 * @param msg The information carried in the exception.
 * @note This callback identifies a device exception that cannot be resolved. After you receive the callback, check whether the device is available.
 */
virtual void OnLocalDeviceException(AliEngineLocalDeviceType deviceType, AliEngineLocalDeviceExceptionType exceptionType, const char* msg){};

/**
 * @brief Stop playing the audio file.
 * @return
 * - =0: The request is successful.
 * - <0: The request fails.
 * @note You can call this operation only before joining the call {@link joinChannel}.
 */
public abstract int stopAudioFileTest();

/**
 * @brief Stop playing the audio file.
 * @return
 * - =0: The request is successful.
 * - <0: The request fails.
 * @note You can call this operation only before joining the call {@link joinChannel}.
 */
- (int)stopAudioFileTest;

/**
 * @brief Stop playing the audio file.
 * @return
 * - =0: The request is successful.
 * - <0: The request fails.
 * @note You can call this operation only before joining the call {@link JoinChannel}.
 */
virtual int StopAudioFileTest() = 0;

3. Detect a camera

Set the camera view for local preview and start the camera preview. If no callbacks are invoked because of errors and the camera view is displayed as expected, the camera can be used as expected.

/**
 * @brief Set the view for local preview.
 * @param viewConfig The display properties for the local video. For more information, see {@link com::alivc::rtc::AliRtcEngine::AliRtcVideoCanvas} for details
 * @param track  Only {@link AliRtcVideoTrack#AliRtcVideoTrackCamera} and {@link AliRtcVideoTrack#AliRtcVideoTrackScreen} are supported.
 * @return
 * - 0: The request is successful.
 * - < 0: The request fails.
 * @note You can switch a view before and after you call the joinChannel method. If you set canvas or {@link AliRtcVideoCanvas#view} to null, the camera stop displaying the view.
 *       If you want to reconfigure {@link AliRtcVideoCanvas#renderMode}, keep other properties in the canvas unchanged and modify only
 *       {@link AliRtcVideoCanvas#renderMode}.
 *       If you want to reconfigure {@link AliRtcVideoCanvas#mirrorMode}, keep other properties in the canvas unchanged and modify only
 *       {@link AliRtcVideoCanvas#mirrorMode}.
 */
public abstract int setLocalViewConfig(AliRtcVideoCanvas viewConfig, AliRtcVideoTrack track);

/**
 * @brief Set the view for local preview.
 * @param viewConfig The display properties for the local video. For more information, see {@link AliVideoCanvas} for details
 * @param track  Only {@link AliRtcVideoTrackCamera} and {@link AliRtcVideoTrackScreen} are supported.
 * @return
 * - 0: The request is successful.
 * - < 0: The request fails.
 * @note You can switch a view before and after you call the joinChannel method. If you set canvas or {@link AliVideoCanvas::view} to null, the camera stop displaying the view.
 *       If you want to reconfigure {@link AliVideoCanvas::renderMode}, keep other properties in the canvas unchanged and modify only
 *       {@link AliVideoCanvas::renderMode}.
 *       If you want to reconfigure {@link AliVideoCanvas::mirrorMode}, keep other properties in the canvas unchanged and modify only
 *       {@link AliVideoCanvas::mirrorMode}.
 */
- (int)setLocalViewConfig:(AliVideoCanvas *_Nullable)viewConfig forTrack:(AliRtcVideoTrack)track;

/**
 * @brief Set the view for local preview.
 * @param renderConfig The display properties for the local video. For more information, see {@link AliEngineVideoCanvas} for details
 * @param track  Only {@link AliEngineVideoTrackCamera} and {@link AliEngineVideoTrackScreen} are supported.
 * @return
 * - 0: The request is successful.
 * - Values other than 0: The request fails.
 * @note You can switch a view before and after you call the joinChannel method. If you set canvas or {@link AliEngineVideoCanvas::displayView} to null, the camera stop displaying the view.
 *       If you want to reconfigure {@link AliEngineVideoCanvas::renderMode}, keep other properties in renderConfig unchanged and only modify
 *       {@link AliEngineVideoCanvas::renderMode}.
 *       If you want to reconfigure {@link AliEngineVideoCanvas::mirrorMode}, keep other properties in renderConfig unchanged and only modify
 *       {@link AliEngineVideoCanvas::mirrorMode}.
 */
virtual int SetLocalViewConfig(AliEngineVideoCanvas renderConfig,
AliEngineVideoTrack track) = 0;

/**
 * @brief Start the local preview.
 * @details Start the local preview.. The camera is automatically turned on.
 * @return
 * - 0: The request is successful.
 * - < 0: The request fails.
 * @note If you do not call the {@link #setLocalViewConfig} operation to set the camera view, the preview fails. Stream ingest is not affected.
 * If you start the local preview before {@link #joinChannel}, the camera is automatically turned on.
 */
public abstract int startPreview();

/**
 * @brief Start the local preview.
 * @return
 * - 0: The request is successful.
 * - <0: The request fails.
 * @note If you do not call the {@link setLocalViewConfig:forTrack:} operation to set the camera view, the preview fails. Stream ingest is not affected.
 * If you start the local preview before {@link joinChannel:name:onResultWithUserId:}, the camera is automatically turned on.
 */
- (int)startPreview;

/**
 * @brief Start the local preview.
 * @return
 * - 0: The request is successful.
 * - Values other than 0: The request fails.
 * @note If you do not call the {@link SetLocalViewConfig} operation to set the camera view, the preview fails. Stream ingest is not affected.
 *       If you start the local preview before {@link JoinChannel}, the camera is automatically turned on.
 */
virtual int StartPreview(int width = 0, int height = 0) = 0;

/**
 * @brief The callback is invoked when a local device exception occurs.
 * @param deviceType The type of the device. For more information, see {@link AliRtcEngine.AliRtcEngineLocalDeviceType}.
 * @param exceptionType The type of the device exception. For more information, see {@link AliRtcEngine.AliRtcEngineLocalDeviceExceptionType}.
 * @param msg The information carried in the exception.
 * @note This callback identifies a device exception that cannot be resolved. After you receive the callback, check whether the device is available.
 */
public void OnLocalDeviceException(AliRtcEngine.AliRtcEngineLocalDeviceType deviceType, AliRtcEngine.AliRtcEngineLocalDeviceExceptionType exceptionType, String msg){}

/**
 * @brief The callback is invoked when a local device exception occurs.
 * @param deviceType The type of the device. For more information, see {@link AliRtcLocalDeviceType}.
 * @param exceptionType The type of the device exception. For more information, see {@link AliRtcLocalDeviceExceptionType}.
 * @param msg The information carried in the exception.
 * @note This callback identifies a device exception that cannot be resolved. After you receive the callback, check whether the device is available.
 */
- (void)onLocalDeviceException:(AliRtcLocalDeviceType)deviceType exceptionType:(AliRtcLocalDeviceExceptionType)exceptionType message:(NSString *_Nullable)msg;

/**
 * @brief The callback is invoked when a local device exception occurs.
 * @param deviceType The type of the device. For more information, see {@link AliEngineLocalDeviceType}.
 * @param exceptionType The type of the device exception. For more information, see {@link AliEngineLocalDeviceExceptionType}.
 * @param msg The information carried in the exception.
 * @note This callback identifies a device exception that cannot be resolved. After you receive the callback, check whether the device is available.
 */
virtual void OnLocalDeviceException(AliEngineLocalDeviceType deviceType, AliEngineLocalDeviceExceptionType exceptionType, const char* msg){};