全部產品
Search

搜尋本產品

    ApsaraVideo Live：通話前進行裝置檢測

    文件中心

    ApsaraVideo Live：通話前進行裝置檢測

    更新時間：Jan 22, 2026

    本文將為您介紹如何?在通話前對裝置進行檢測。

    功能介紹

    ARTC SDK提供了通話前裝置檢測功能，旨在對本地關鍵音頻與視頻裝置進行全面檢測，包括麥克風、擴音器和網路攝影機。在正式開啟通話之前，使用者能夠提前識別潛在的裝置異常狀況，從而避免在實際通話過程中因裝置突發故障而陷入難以迅速定位問題根源的困境，確保通話過程的流暢與高效穩定。

    範例程式碼

    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。

    功能實現

    一、麥克風檢測

    啟動麥克風，若未檢測到任何異常反饋，且麥克風採集音量檢測正常，則麥克風裝置正常可用。

    1. 啟動麥克風

    通過調用startAudioCaptureTest介面啟動麥克風採集。

    Android
    /**
 * @brief 通話前開啟音頻採集裝置檢測
 * @details 此介面可以控制開啟音頻採集檢測
 * - 通過{@link AliRtcAudioVolumeObserver::onTestAudioVolumeCallback}判斷採集是否正常
 * @return 
 * - 0: 成功
 * - 非0: 返回錯誤碼
 * @note 只能入會前{@link joinChannel}調用此介面
 */
public abstract int startAudioCaptureTest();
    iOS
    /**
 * @brief 通話前，開啟音頻採集裝置檢測
 * @details 此介面可以控制開啟音頻採集
 * - 通過{@link onTestAudioVolumeCallback}判斷採集是否正常
 * @note 只能入會前{@link joinChannel}調用此介面
 */
- (void)startAudioCaptureTest;
    Windows
    /**
 * @brief 通話前開啟音頻採集測試
 * @details 此介面可以控制開啟音頻採集測試
 * - 通過{@link AliEngineEventListener::OnTestAudioVolumeCallback}判斷採集是否正常
 * @return
 * - 0: 成功
 * - 非0: 返回錯誤碼
 * @note 只能入會前{@link JoinChannel}調用此介面
 */
virtual int StartAudioCaptureTest() = 0;

    2. 檢測麥克風裝置是否異常

    通過如下回調檢測裝置是否異常，若未檢測到任何異常反饋（可同步啟動“3. 檢測麥克風採集音量”），且麥克風採集音量檢測正常，則麥克風裝置可用。

    Android
    /**
 * @brief 本地裝置異常回調
 * @param deviceType 裝置類型, 參考{@link AliRtcEngine.AliRtcEngineLocalDeviceType}
 * @param exceptionType 裝置異常類型, 參考{@link AliRtcEngine.AliRtcEngineLocalDeviceExceptionType}
 * @param msg 異常時攜帶的資訊
 * @note 此回調標識了內部無法恢複了裝置異常，收到此回調時使用者需要檢查裝置是否可用
 */
public void OnLocalDeviceException(AliRtcEngine.AliRtcEngineLocalDeviceType deviceType, AliRtcEngine.AliRtcEngineLocalDeviceExceptionType exceptionType, String msg){}
    iOS
    /**
 * @brief 本地裝置異常回調
 * @param deviceType 裝置類型, 參考{@link AliRtcLocalDeviceType}
 * @param exceptionType 裝置異常類型, 參考{@link AliRtcLocalDeviceExceptionType}
 * @param msg 異常時攜帶的資訊
 * @note 此回調標識了內部無法恢複了裝置異常，收到此回調時使用者需要檢查裝置是否可用
 */
- (void)onLocalDeviceException:(AliRtcLocalDeviceType)deviceType exceptionType:(AliRtcLocalDeviceExceptionType)exceptionType message:(NSString *_Nullable)msg;
    Windows
    /**
 * @brief 本地裝置異常回調
 * @param deviceType 裝置類型, 參考{@link AliEngineLocalDeviceType}
 * @param exceptionType 裝置異常類型, 參考{@link AliEngineLocalDeviceExceptionType}
 * @param msg 異常時攜帶的資訊
 * @note 此回調標識了內部無法恢複了裝置異常，收到此回調時使用者需要檢查裝置是否可用
 */
virtual void OnLocalDeviceException(AliEngineLocalDeviceType deviceType, AliEngineLocalDeviceExceptionType exceptionType, const char* msg){};

    3. 檢測麥克風採集音量

    通過監聽如下回調，擷取麥克風採集到聲音的音量，如果資料無異常則麥克風正常，可用於通話。

    Android
    /**
 * @brief 通話前檢測，音量資訊回調
 * @param volume 音量
 */
public void OnTestAudioVolume(int volume) {}
    iOS
    /**
 * @brief 通話前音頻採集檢測的音量回調
 * @param volume 音量
 */
- (void)onTestAudioVolumeCallback:(int)volume;
    Windows
    /**
 * @brief 通話前音頻採集檢測的音量回調
 * @param volumn 音量
 */
virtual void OnTestAudioVolumeCallback(int volumn) {}

    4. 停止麥克風檢測

    使用者在確認麥克風是否正常後，需要調用stopAudioCaptureTest介面停止檢測。

    Android
    /**
 * @brief 關閉音頻採集檢測
 * @return 
 * - 0: 成功
 * - 非0: 返回錯誤碼
 * @note 只能入會前{@link joinChannel}調用此介面
 */
public abstract int stopAudioCaptureTest();
    iOS
    /**
 * @brief 關閉音頻採集檢測
 * @note 只能入會前{@link joinChannel}調用此介面
 */
- (void)stopAudioCaptureTest;
    Windows
    /**
 * @brief 關閉音頻採集測試
 * @return
 * - 0: 成功
 * - 非0: 返回錯誤碼
 * @note 只能入會前{@link JoinChannel}調用此介面
 */
virtual int StopAudioCaptureTest() = 0;

    二、擴音器檢測

    播放一個音頻檔案。如果可以聽到相應的音頻，則擴音器裝置正常，可用於通話。

    1. 播放音頻檔案

    調用playAudioFileTest播放一個使用者用於測試的音頻檔案。如果可以聽到相應的音頻，則擴音器裝置正常。

    Android
    /**
 * @brief 播放音頻檔案
 * @param filePath 檔案路徑
 * @return
 * - =0 成功
 * - <0 失敗
 * @note 只能入會前{@link joinChannel}調用此介面
 */
public abstract int playAudioFileTest(String filePath) ;
    iOS
    /**
 * @brief 播放音頻檔案
 * @param filePath 檔案路徑
 * @return
 * - =0 成功
 * - <0 失敗
 * @note 只能入會前{@link joinChannel}調用此介面
 */
- (int)playAudioFileTest:(NSString *_Nonnull)filePath;
    Windows
    /**
 * @brief 播放音頻檔案
 * @param filePath 檔案路徑
 * @return
 * - =0 成功
 * - <0 失敗
 * @note 只能入會前{@link JoinChannel}調用此介面
 */
virtual int PlayAudioFileTest(const char* filePath) = 0;

    2. 檢測擴音器是否異常

    通過如下回調檢測裝置是否異常，若未檢測到任何異常反饋，且可以聽到相應的音頻，則擴音器裝置正常。

    Android
    /**
 * @brief 本地裝置異常回調
 * @param deviceType 裝置類型, 參考{@link AliRtcEngine.AliRtcEngineLocalDeviceType}
 * @param exceptionType 裝置異常類型, 參考{@link AliRtcEngine.AliRtcEngineLocalDeviceExceptionType}
 * @param msg 異常時攜帶的資訊
 * @note 此回調標識了內部無法恢複了裝置異常，收到此回調時使用者需要檢查裝置是否可用
 */
public void OnLocalDeviceException(AliRtcEngine.AliRtcEngineLocalDeviceType deviceType, AliRtcEngine.AliRtcEngineLocalDeviceExceptionType exceptionType, String msg){}
    iOS
    /**
 * @brief 本地裝置異常回調
 * @param deviceType 裝置類型, 參考{@link AliRtcLocalDeviceType}
 * @param exceptionType 裝置異常類型, 參考{@link AliRtcLocalDeviceExceptionType}
 * @param msg 異常時攜帶的資訊
 * @note 此回調標識了內部無法恢複了裝置異常，收到此回調時使用者需要檢查裝置是否可用
 */
- (void)onLocalDeviceException:(AliRtcLocalDeviceType)deviceType exceptionType:(AliRtcLocalDeviceExceptionType)exceptionType message:(NSString *_Nullable)msg;
    Windows
    /**
 * @brief 本地裝置異常回調
 * @param deviceType 裝置類型, 參考{@link AliEngineLocalDeviceType}
 * @param exceptionType 裝置異常類型, 參考{@link AliEngineLocalDeviceExceptionType}
 * @param msg 異常時攜帶的資訊
 * @note 此回調標識了內部無法恢複了裝置異常，收到此回調時使用者需要檢查裝置是否可用
 */
virtual void OnLocalDeviceException(AliEngineLocalDeviceType deviceType, AliEngineLocalDeviceExceptionType exceptionType, const char* msg){};

    3. 停止播放音頻檔案

    使用者在確認擴音器是否正常後，需要調用stopAudioFileTest介面停止播放音頻檔案。

    Android
    /**
 * @brief 停止播放音頻檔案
 * @return
 * - =0 成功
 * - <0 失敗
 * @note 只能入會前{@link joinChannel}調用此介面
 */
public abstract int stopAudioFileTest();
    iOS
    /**
 * @brief 停止播放音頻檔案
 * @return
 * - =0 成功
 * - <0 失敗
 * @note 只能入會前{@link joinChannel}調用此介面
 */
- (int)stopAudioFileTest;
    Windows
    /**
 * @brief 停止播放音頻檔案
 * @return
 * - =0 成功
 * - <0 失敗
 * @note 只能入會前{@link JoinChannel}調用此介面
 */
virtual int StopAudioFileTest() = 0;

    三、網路攝影機檢測

    設定本地預覽顯示視圖，啟動網路攝影機開始預覽，若沒有異常回調，且畫面顯示正常，則網路攝影機正常，可用於通話。

    1. 設定本地預覽顯示視圖

    開啟網路攝影機預覽之前，需要調用setLocalViewConfig設定顯示視圖。

    Android
    /**
 * @brief 設定本地預覽顯示視圖
 * @param viewConfig 本地視頻顯示內容, 詳細見{@link com::alivc::rtc::AliRtcEngine::AliRtcVideoCanvas}
 * @param track  只支援 {@link AliRtcVideoTrack#AliRtcVideoTrackCamera} 和 {@link AliRtcVideoTrack#AliRtcVideoTrackScreen}
 * @return
 * - 0 : 成功
 * - < 0 : 失敗
 * @note 支援joinChannel之前和之後切換視窗。如果canvas或者{@link AliRtcVideoCanvas#view}為null，則停止顯示。
 *       如果需要重新設定{@link AliRtcVideoCanvas#renderMode}，請保持canvas中其他屬性不變，僅修改
 *       {@link AliRtcVideoCanvas#renderMode}。
 *       如果需要重新設定{@link AliRtcVideoCanvas#mirrorMode}，請保持canvas中其他屬性不變，僅修改
 *       {@link AliRtcVideoCanvas#mirrorMode}。
 */
public abstract int setLocalViewConfig(AliRtcVideoCanvas viewConfig, AliRtcVideoTrack track);
    iOS
    /**
 * @brief 設定本地預覽顯示視圖
 * @param viewConfig 本地視頻顯示內容, 詳細見 {@link AliVideoCanvas}
 * @param track  只支援 {@link AliRtcVideoTrackCamera} 和 {@link AliRtcVideoTrackScreen}
 * @return
 * - 0 : 成功
 * - < 0 : 失敗
 * @note 支援joinChannel之前和之後切換視窗。如果canvas或者 {@link AliVideoCanvas::view} 為nil，則停止顯示。
 *       如果需要重新設定 {@link AliVideoCanvas::renderMode}，請保持canvas中其他屬性不變，僅修改
 *       {@link AliVideoCanvas::renderMode}。
 *       如果需要重新設定 {@link AliVideoCanvas::mirrorMode}，請保持canvas中其他屬性不變，僅修改
 *       {@link AliVideoCanvas::mirrorMode}。
 */
- (int)setLocalViewConfig:(AliVideoCanvas *_Nullable)viewConfig forTrack:(AliRtcVideoTrack)track;
    Windows
    /**
 * @brief 設定本地預覽顯示視圖
 * @param renderConfig 本地視頻顯示內容, 詳細見 {@link AliEngineVideoCanvas}
 * @param track  只支援 {@link AliEngineVideoTrackCamera} 和 {@link AliEngineVideoTrackScreen}
 * @return
 * - 0: 成功
 * - 非0: 失敗
 * @note 支援joinChannel之前和之後切換視窗。如果 {@link AliEngineVideoCanvas::displayView} 為null，則停止顯示。
 *       如果需要重新設定{@link AliEngineVideoCanvas::renderMode}，請保持renderConfig中其他屬性不變，僅修改
 *       {@link AliEngineVideoCanvas::renderMode}。
 *       如果需要重新設定{@link AliEngineVideoCanvas::mirrorMode}，請保持renderConfig中其他屬性不變，僅修改
 *       {@link AliEngineVideoCanvas::mirrorMode}。
 */
virtual int SetLocalViewConfig(AliEngineVideoCanvas renderConfig,
AliEngineVideoTrack track) = 0;

    2. 開啟網路攝影機預覽

    調用startPreview開啟網路攝影機預覽。

    Android
    /**
 * @brief 開啟本地視頻預覽
 * @details 開啟本地視頻預覽並自動開啟網路攝影機
 * @return
 * - 0 : 成功
 * - < 0 : 失敗
 * @note 如果沒有調用{@link #setLocalViewConfig}設定顯示的view，則無法預覽，但不影響推流。
 * 可以在{@link #joinChannel}之前就開啟預覽會自動開啟網路攝影機。
 */
public abstract int startPreview();
    iOS
    /**
 * @brief 開啟本地視頻預覽
 * @return
 * - 0 : 成功
 * - <0 : 失敗
 * @note 如果沒有調用 {@link setLocalViewConfig:forTrack:} 設定顯示的view，則無法預覽。
 * 可以在 {@link joinChannel:name:onResultWithUserId:} 之前就開啟預覽會自動開啟網路攝影機。
 */
- (int)startPreview;
    Windows
    /**
 * @brief 開啟本地視頻預覽
 * @return
 * - 0: 成功
 * - 非0: 失敗
 * @note 如果沒有調用 {@link SetLocalViewConfig} 設定顯示的view，則無法預覽。
 *       可以在{@link JoinChannel}之前就開啟預覽會自動開啟網路攝影機。
 */
virtual int StartPreview(int width = 0, int height = 0) = 0;

    3. 檢測網路攝影機是否異常

    通過如下回調檢測裝置是否異常，如果沒有異常反饋，且預覽畫面顯示正常，則網路攝影機裝置正常。

    Android
    /**
 * @brief 本地裝置異常回調
 * @param deviceType 裝置類型, 參考{@link AliRtcEngine.AliRtcEngineLocalDeviceType}
 * @param exceptionType 裝置異常類型, 參考{@link AliRtcEngine.AliRtcEngineLocalDeviceExceptionType}
 * @param msg 異常時攜帶的資訊
 * @note 此回調標識了內部無法恢複了裝置異常，收到此回調時使用者需要檢查裝置是否可用
 */
public void OnLocalDeviceException(AliRtcEngine.AliRtcEngineLocalDeviceType deviceType, AliRtcEngine.AliRtcEngineLocalDeviceExceptionType exceptionType, String msg){}
    iOS
    /**
 * @brief 本地裝置異常回調
 * @param deviceType 裝置類型, 參考{@link AliRtcLocalDeviceType}
 * @param exceptionType 裝置異常類型, 參考{@link AliRtcLocalDeviceExceptionType}
 * @param msg 異常時攜帶的資訊
 * @note 此回調標識了內部無法恢複了裝置異常，收到此回調時使用者需要檢查裝置是否可用
 */
- (void)onLocalDeviceException:(AliRtcLocalDeviceType)deviceType exceptionType:(AliRtcLocalDeviceExceptionType)exceptionType message:(NSString *_Nullable)msg;
    Windows
    /**
 * @brief 本地裝置異常回調
 * @param deviceType 裝置類型, 參考{@link AliEngineLocalDeviceType}
 * @param exceptionType 裝置異常類型, 參考{@link AliEngineLocalDeviceExceptionType}
 * @param msg 異常時攜帶的資訊
 * @note 此回調標識了內部無法恢複了裝置異常，收到此回調時使用者需要檢查裝置是否可用
 */
virtual void OnLocalDeviceException(AliEngineLocalDeviceType deviceType, AliEngineLocalDeviceExceptionType exceptionType, const char* msg){};