すべてのプロダクト
Search

このプロダクト

    ApsaraVideo Live:通話前のデバイス検出

    ドキュメントセンター

    ApsaraVideo Live:通話前のデバイス検出

    最終更新日:Nov 27, 2025

    このトピックでは、通話前にデバイスを検出する方法について説明します。

    機能概要

    Alibaba Real-Time Communication (ARTC) SDK は、音声通話またはビデオ通話の前にデバイスを検出する機能を提供します。この機能により、マイク、スピーカー、カメラなどのローカルの主要なオーディオおよびビデオデバイスを検出できます。通話前に潜在的なデバイスの問題を特定することで、通話中の予期せぬデバイスの故障によるトラブルシューティングの遅延を回避し、スムーズで効率的、かつ安定した通話体験を保証します。

    サンプルコード

    Android でのネットワーク品質テスト： Android/ARTCExample/AdvancedUsage/src/main/java/com/aliyun/artc/api/advancedusage/PreJoinChannelTest/PreJoinChannelTestActivity.java

    iOS でのネットワーク品質テスト： iOS/ARTCExample/AdvancedUsage/PreJoinChannelTest/PreJoinChannelTestVC.swift

    実装

    1. マイクの検出

    マイクをオンにします。 マイクに例外が検出されず、収集されたオーディオの音量が正常と見なされる場合、マイクは期待どおりに使用できます。

    1. マイクをオンにする

    startAudioCaptureTest 操作を呼び出して、マイクからの音声収集を有効にできます。 以下に詳細を説明します。

    Android
    /**
 * @brief 音声またはビデオ通話の前に、マイクからの音声収集を有効にします。
 * @details この操作を呼び出して、マイクからの音声収集を有効にできます。
 * - {@link AliRtcAudioVolumeObserver::onTestAudioVolumeCallback} に基づいて、音声が期待どおりに収集されるかどうかを確認します。
 * @return 
 * - 0: リクエストは成功しました。
 * - 0 以外の値: エラーコードが返されます。
 * @note この操作は、通話 {@link joinChannel} に参加する前にのみ呼び出すことができます。
 */
public abstract int startAudioCaptureTest();
    IOS
    /**
 * @brief 音声またはビデオ通話の前に、マイクからの音声収集を有効にします。
 * @details この操作を呼び出して、マイクからの音声収集を有効にできます。
 * - {@link AliRtcAudioVolumeObserver::onTestAudioVolumeCallback} に基づいて、音声が期待どおりに収集されるかどうかを確認します。
 * @note この操作は、通話 {@link joinChannel} に参加する前にのみ呼び出すことができます。
 */
- (void)startAudioCaptureTest;
    Windows
    /**
 * @brief 音声またはビデオ通話の前に、マイクからの音声収集を有効にします。
 * @details この操作を呼び出して、マイクからの音声収集を有効にできます。
 * - {@link AliRtcAudioVolumeObserver::onTestAudioVolumeCallback} に基づいて、音声が期待どおりに収集されるかどうかを確認します。
 * @return
 * - 0: リクエストは成功しました。
 * - 0 以外の値: エラーコードが返されます。
 * @note この操作は、通話 {@link joinChannel} に参加する前にのみ呼び出すことができます。
 */
virtual int StartAudioCaptureTest() = 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. 収集されたオーディオの音量を検出する

    コールバックを設定して、収集されたオーディオの音量を検出できます。 例外が検出されない場合、マイクは正常と見なされ、期待どおりに使用できます。 次のセクションでは、コールバックの詳細について説明します。

    Android
    /**
 * @brief 音声またはビデオ通話の前に、収集されたオーディオの音量を検出するためにコールバックが呼び出されます。
 * @param volume 音量
 */
public void OnTestAudioVolume(int volume) {}
    IOS
    /**
 * @brief 音声またはビデオ通話の前に、収集されたオーディオの音量を検出するためにコールバックが呼び出されます。
 * @param volume 音量
 */
- (void)onTestAudioVolumeCallback:(int)volume;
    Windows
    /**
 * @brief 音声またはビデオ通話の前に、収集されたオーディオの音量を検出するためにコールバックが呼び出されます。
 * @param volume 音量
 */
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;

    2. スピーカーの検出

    音声ファイルを再生します。 対応する音声が聞こえる場合、スピーカーは期待どおりに使用できます。

    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;

    3. カメラの検出

    ローカル プレビューのカメラ ビューを設定し、カメラ プレビューを開始します。 エラーによってコールバックが呼び出されず、カメラ ビューが期待どおりに表示される場合、カメラは期待どおりに使用できます。

    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} を null に設定すると、カメラはビューの表示を停止します。
 *       {@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 メソッドを呼び出す前後にビューを切り替えることができます。 canvas または {@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} 操作を呼び出してカメラ ビューを設定しないと、プレビューは失敗します。 ストリームの取り込みは影響を受けません。
 * {@link #joinChannel} の前にローカル プレビューを開始すると、カメラは自動的にオンになります。
 */
public abstract int startPreview();
    IOS
    /**
 * @brief ローカル プレビューを開始します。
 * @return
 * - 0: リクエストは成功しました。
 * - <0: リクエストは失敗しました。
 * @note {@link setLocalViewConfig:forTrack:} 操作を呼び出してカメラ ビューを設定しないと、プレビューは失敗します。 ストリームの取り込みは影響を受けません。
 * {@link joinChannel:name:onResultWithUserId:} の前にローカル プレビューを開始すると、カメラは自動的にオンになります。
 */
- (int)startPreview;
    Windows
    /**
 * @brief ローカル プレビューを開始します。
 * @return
 * - 0: リクエストは成功しました。
 * - 0 以外の値: リクエストは失敗しました。
 * @note {@link SetLocalViewConfig} 操作を呼び出してカメラ ビューを設定しないと、プレビューは失敗します。 ストリームの取り込みは影響を受けません。
 *       {@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){};