全部产品
Search

搜索本产品

    ApsaraVideo Live：Pendeteksian perangkat sebelum panggilan

    文档中心

    ApsaraVideo Live：Pendeteksian perangkat sebelum panggilan

    更新时间：Nov 27, 2025

    Topik ini menjelaskan cara mendeteksi perangkat sebelum melakukan panggilan.

    Ikhtisar fitur

    Alibaba Real-Time Communication (ARTC) SDK menyediakan fitur pendeteksian perangkat sebelum panggilan suara atau video. Fitur ini memungkinkan Anda mendeteksi perangkat audio dan video lokal utama, seperti microphone, speaker, dan kamera. Dengan demikian, Anda dapat mengidentifikasi potensi masalah perangkat sebelum panggilan dimulai, sehingga menghindari keterlambatan penanganan akibat kegagalan perangkat yang tidak terduga selama panggilan serta memastikan pengalaman panggilan yang lancar, efisien, dan stabil.

    Kode contoh

    Uji kualitas jaringan di Android: Android/ARTCExample/AdvancedUsage/src/main/java/com/aliyun/artc/api/advancedusage/PreJoinChannelTest/PreJoinChannelTestActivity.java.

    Uji kualitas jaringan di iOS: iOS/ARTCExample/AdvancedUsage/PreJoinChannelTest/PreJoinChannelTestVC.swift.

    Implementasi

    1. Mendeteksi mikrofon

    Aktifkan mikrofon. Jika tidak ada pengecualian yang terdeteksi pada mikrofon dan volume audio yang dikumpulkan dianggap normal, mikrofon dapat digunakan sesuai harapan.

    1. Aktifkan mikrofon

    Anda dapat memanggil operasi startAudioCaptureTest untuk mengaktifkan pengumpulan audio dari mikrofon. Berikut adalah rinciannya.

    Android
    /**
 * @brief Aktifkan pengumpulan audio dari mikrofon sebelum panggilan suara atau video.
 * @details Anda dapat memanggil operasi ini untuk mengaktifkan pengumpulan audio dari mikrofon.
 * - Periksa apakah audio dapat dikumpulkan sesuai harapan berdasarkan {@link AliRtcAudioVolumeObserver::onTestAudioVolumeCallback}.
 * @return 
 * - 0: Permintaan berhasil.
 * - Nilai selain 0: Kode kesalahan dikembalikan.
 * @note Anda hanya dapat memanggil operasi ini sebelum bergabung dengan panggilan {@link joinChannel}.
 */
public abstract int startAudioCaptureTest();
    IOS
    /**
 * @brief Aktifkan pengumpulan audio dari mikrofon sebelum panggilan suara atau video.
 * @details Anda dapat memanggil operasi ini untuk mengaktifkan pengumpulan audio dari mikrofon.
 * - Periksa apakah audio dapat dikumpulkan sesuai harapan berdasarkan {@link AliRtcAudioVolumeObserver::onTestAudioVolumeCallback}.
 * @note Anda hanya dapat memanggil operasi ini sebelum bergabung dengan panggilan {@link joinChannel}.
 */
- (void)startAudioCaptureTest;
    Windows
    /**
 * @brief Aktifkan pengumpulan audio dari mikrofon sebelum panggilan suara atau video.
 * @details Anda dapat memanggil operasi ini untuk mengaktifkan pengumpulan audio dari mikrofon.
 * - Periksa apakah audio dapat dikumpulkan sesuai harapan berdasarkan {@link AliRtcAudioVolumeObserver::onTestAudioVolumeCallback}.
 * @return
 * - 0: Permintaan berhasil.
 * - Nilai selain 0: Kode kesalahan dikembalikan.
 * @note Anda hanya dapat memanggil operasi ini sebelum bergabung dengan panggilan {@link joinChannel}.
 */
virtual int StartAudioCaptureTest() = 0;

    2. Mendeteksi apakah mikrofon abnormal

    Anda dapat mengonfigurasi callback untuk mendeteksi apakah mikrofon abnormal. Jika tidak ada pengecualian yang terdeteksi pada mikrofon dan volume audio yang dikumpulkan dianggap normal, mikrofon dapat digunakan sesuai harapan. Bagian berikut menjelaskan rincian tentang callback.

    Android
    /**
 * @brief Callback dipanggil ketika terjadi pengecualian perangkat lokal.
 * @param deviceType Jenis perangkat. Untuk informasi lebih lanjut, lihat {@link AliRtcEngine.AliRtcEngineLocalDeviceType}
 * @param exceptionType Jenis pengecualian perangkat. Untuk informasi lebih lanjut, lihat {@link AliRtcEngine.AliRtcEngineLocalDeviceExceptionType}
 * @param msg Informasi yang dibawa dalam pengecualian.
 * @note Callback ini mengidentifikasi pengecualian perangkat yang tidak dapat diselesaikan. Setelah Anda menerima callback, periksa apakah perangkat tersedia.
 */
public void OnLocalDeviceException(AliRtcEngine.AliRtcEngineLocalDeviceType deviceType, AliRtcEngine.AliRtcEngineLocalDeviceExceptionType exceptionType, String msg){}
    IOS
    /**
 * @brief Callback dipanggil ketika terjadi pengecualian perangkat lokal.
 * @param deviceType Jenis perangkat. Untuk informasi lebih lanjut, lihat {@link AliRtcLocalDeviceType}
 * @param exceptionType Jenis pengecualian perangkat. Untuk informasi lebih lanjut, lihat {@link AliRtcLocalDeviceExceptionType}
 * @param msg Informasi yang dibawa dalam pengecualian.
 * @note Callback ini mengidentifikasi pengecualian perangkat yang tidak dapat diselesaikan. Setelah Anda menerima callback, periksa apakah perangkat tersedia.
 */
- (void)onLocalDeviceException:(AliRtcLocalDeviceType)deviceType exceptionType:(AliRtcLocalDeviceExceptionType)exceptionType message:(NSString *_Nullable)msg;
    Windows
    /**
 * @brief Callback dipanggil ketika terjadi pengecualian perangkat lokal.
 * @param deviceType Jenis perangkat. Untuk informasi lebih lanjut, lihat {@link AliEngineLocalDeviceType}
 * @param exceptionType Jenis pengecualian perangkat. Untuk informasi lebih lanjut, lihat {@link AliEngineLocalDeviceExceptionType}
 * @param msg Informasi yang dibawa dalam pengecualian.
 * @note Callback ini mengidentifikasi pengecualian perangkat yang tidak dapat diselesaikan. Setelah Anda menerima callback, periksa apakah perangkat tersedia.
 */
virtual void OnLocalDeviceException(AliEngineLocalDeviceType deviceType, AliEngineLocalDeviceExceptionType exceptionType, const char* msg){};

    3. Mendeteksi volume audio yang dikumpulkan

    Anda dapat mengonfigurasi callback untuk mendeteksi volume audio yang dikumpulkan. Jika tidak ada pengecualian yang terdeteksi, mikrofon dianggap normal dan dapat digunakan sesuai harapan. Bagian berikut menjelaskan rincian tentang callback.

    Android
    /**
 * @brief Callback dipanggil untuk mendeteksi volume audio yang dikumpulkan sebelum panggilan suara atau video.
 * @param volume
 */
public void OnTestAudioVolume(int volume) {}
    IOS
    /**
 * @brief Callback dipanggil untuk mendeteksi volume audio yang dikumpulkan sebelum panggilan suara atau video.
 * @param volume
 */
- (void)onTestAudioVolumeCallback:(int)volume;
    Windows
    /**
 * @brief Callback dipanggil untuk mendeteksi volume audio yang dikumpulkan sebelum panggilan suara atau video.
 * @param volume
 */
virtual void OnTestAudioVolumeCallback(int volumn) {}

    4. Menghentikan pendeteksian mikrofon

    Anda dapat memanggil operasi stopAudioCaptureTest untuk menghentikan pendeteksian volume mikrofon setelah Anda mendeteksi apakah mikrofon abnormal.

    Android
    /**
 * @brief Hentikan pendeteksian volume audio yang dikumpulkan.
 * @return 
 * - 0: Permintaan berhasil.
 * - Nilai selain 0: Kode kesalahan dikembalikan.
 * @note Anda hanya dapat memanggil operasi ini sebelum bergabung dengan panggilan {@link joinChannel}.
 */
public abstract int stopAudioCaptureTest();
    IOS
    /**
 * @brief Hentikan pendeteksian volume audio yang dikumpulkan.
 * @note Anda hanya dapat memanggil operasi ini sebelum bergabung dengan panggilan {@link joinChannel}.
 */
- (void)stopAudioCaptureTest;
    Windows
    /**
 * @brief Hentikan pendeteksian volume audio yang dikumpulkan.
 * @return
 * - 0: Permintaan berhasil.
 * - Nilai selain 0: Kode kesalahan dikembalikan.
 * @note Anda hanya dapat memanggil operasi ini sebelum bergabung dengan panggilan {@link JoinChannel}.
 */
virtual int StopAudioCaptureTest() = 0;

    2. Mendeteksi speaker

    Putar file audio. Jika Anda dapat mendengar audio yang sesuai, speaker berfungsi seperti yang diharapkan.

    1. Putar file audio

    Anda dapat memanggil operasi playAudioFileTest untuk memutar file audio sebagai bagian dari pengujian. Jika Anda dapat mendengar audio yang sesuai, speaker berfungsi seperti yang diharapkan.

    Android
    /**
 * @brief Putar file audio.
 * @param filePath Jalur file.
 * @return
 * - =0: Permintaan berhasil.
 * - <0: Permintaan gagal.
 * @note Anda hanya dapat memanggil operasi ini sebelum bergabung dengan panggilan {@link joinChannel}.
 */
public abstract int playAudioFileTest(String filePath) ;
    IOS
    /**
 * @brief Putar file audio.
 * @param filePath Jalur file.
 * @return
 * - =0: Permintaan berhasil.
 * - <0: Permintaan gagal.
 * @note Anda hanya dapat memanggil operasi ini sebelum bergabung dengan panggilan {@link joinChannel}.
 */
- (int)playAudioFileTest:(NSString *_Nonnull)filePath;
    Windows
    /**
 * @brief Putar file audio.
 * @param filePath Jalur file.
 * @return
 * - =0: Permintaan berhasil.
 * - <0: Permintaan gagal.
 * @note Anda hanya dapat memanggil operasi ini sebelum bergabung dengan panggilan {@link JoinChannel}.
 */
virtual int PlayAudioFileTest(const char* filePath) = 0;

    2. Mendeteksi apakah speaker abnormal

    Anda dapat mengonfigurasi callback untuk mendeteksi apakah speaker mengalami masalah. Jika tidak ada pengecualian terdeteksi pada speaker dan Anda dapat mendengar audio yang sesuai, speaker berfungsi seperti yang diharapkan. Bagian berikut menjelaskan detail tentang callback.

    Android
    /**
 * @brief Callback dipanggil ketika terjadi pengecualian perangkat lokal.
 * @param deviceType Jenis perangkat. Untuk informasi lebih lanjut, lihat {@link AliRtcEngine.AliRtcEngineLocalDeviceType}.
 * @param exceptionType Jenis pengecualian perangkat. Untuk informasi lebih lanjut, lihat {@link AliRtcEngine.AliRtcEngineLocalDeviceExceptionType}.
 * @param msg Informasi yang dibawa dalam pengecualian.
 * @note Callback ini mengidentifikasi pengecualian perangkat yang tidak dapat diselesaikan. Setelah Anda menerima callback, periksa apakah perangkat tersedia.
 */
public void OnLocalDeviceException(AliRtcEngine.AliRtcEngineLocalDeviceType deviceType, AliRtcEngine.AliRtcEngineLocalDeviceExceptionType exceptionType, String msg){}
    IOS
    /**
 * @brief Callback dipanggil ketika terjadi pengecualian perangkat lokal.
 * @param deviceType Jenis perangkat. Untuk informasi lebih lanjut, lihat {@link AliRtcLocalDeviceType}.
 * @param exceptionType Jenis pengecualian perangkat. Untuk informasi lebih lanjut, lihat {@link AliRtcLocalDeviceExceptionType}.
 * @param msg Informasi yang dibawa dalam pengecualian.
 * @note Callback ini mengidentifikasi pengecualian perangkat yang tidak dapat diselesaikan. Setelah Anda menerima callback, periksa apakah perangkat tersedia.
 */
- (void)onLocalDeviceException:(AliRtcLocalDeviceType)deviceType exceptionType:(AliRtcLocalDeviceExceptionType)exceptionType message:(NSString *_Nullable)msg;
    Windows
    /**
 * @brief Callback dipanggil ketika terjadi pengecualian perangkat lokal.
 * @param deviceType Jenis perangkat. Untuk informasi lebih lanjut, lihat {@link AliEngineLocalDeviceType}.
 * @param exceptionType Jenis pengecualian perangkat. Untuk informasi lebih lanjut, lihat {@link AliEngineLocalDeviceExceptionType}.
 * @param msg Informasi yang dibawa dalam pengecualian.
 * @note Callback ini mengidentifikasi pengecualian perangkat yang tidak dapat diselesaikan. Setelah Anda menerima callback, periksa apakah perangkat tersedia.
 */
virtual void OnLocalDeviceException(AliEngineLocalDeviceType deviceType, AliEngineLocalDeviceExceptionType exceptionType, const char* msg){};

    3. Menghentikan pemutaran file audio

    Anda dapat memanggil operasi stopAudioFileTest untuk menghentikan pemutaran file audio setelah mendeteksi apakah speaker mengalami masalah.

    Android
    /**
 * @brief Hentikan pemutaran file audio.
 * @return
 * - =0: Permintaan berhasil.
 * - <0: Permintaan gagal.
 * @note Anda hanya dapat memanggil operasi ini sebelum bergabung dengan panggilan {@link joinChannel}.
 */
public abstract int stopAudioFileTest();
    IOS
    /**
 * @brief Hentikan pemutaran file audio.
 * @return
 * - =0: Permintaan berhasil.
 * - <0: Permintaan gagal.
 * @note Anda hanya dapat memanggil operasi ini sebelum bergabung dengan panggilan {@link joinChannel}.
 */
- (int)stopAudioFileTest;
    Windows
    /**
 * @brief Hentikan pemutaran file audio.
 * @return
 * - =0: Permintaan berhasil.
 * - <0: Permintaan gagal.
 * @note Anda hanya dapat memanggil operasi ini sebelum bergabung dengan panggilan {@link JoinChannel}.
 */
virtual int StopAudioFileTest() = 0;

    3. Mendeteksi kamera

    Tetapkan tampilan kamera untuk pratinjau lokal dan mulai pratinjau. Jika tidak ada callback yang dipanggil karena kesalahan dan tampilan kamera ditampilkan sesuai harapan, kamera dapat digunakan dengan normal.

    1. Tetapkan tampilan untuk pratinjau lokal

    Anda dapat memanggil operasi setLocalViewConfig untuk menetapkan tampilan kamera sebelum memulai pratinjau lokal.

    Android
    /**
 * @brief Tetapkan tampilan untuk pratinjau lokal.
 * @param viewConfig Properti tampilan untuk video lokal. Untuk informasi lebih lanjut, lihat {@link com::alivc::rtc::AliRtcEngine::AliRtcVideoCanvas} untuk detailnya
 * @param track  Hanya {@link AliRtcVideoTrack#AliRtcVideoTrackCamera} dan {@link AliRtcVideoTrack#AliRtcVideoTrackScreen} yang didukung.
 * @return
 * - 0: Permintaan berhasil.
 * - < 0: Permintaan gagal.
 * @note Anda dapat beralih tampilan sebelum dan sesudah Anda memanggil metode joinChannel. Jika Anda menyetel canvas atau {@link AliRtcVideoCanvas#view} ke null, kamera berhenti menampilkan tampilan.
 *       Jika Anda ingin mengonfigurasi ulang {@link AliRtcVideoCanvas#renderMode}, pertahankan properti lain di canvas tetap dan ubah hanya
 *       {@link AliRtcVideoCanvas#renderMode}.
 *       Jika Anda ingin mengonfigurasi ulang {@link AliRtcVideoCanvas#mirrorMode}, pertahankan properti lain di canvas tetap dan ubah hanya
 *       {@link AliRtcVideoCanvas#mirrorMode}.
 */
public abstract int setLocalViewConfig(AliRtcVideoCanvas viewConfig, AliRtcVideoTrack track);
    IOS
    /**
 * @brief Tetapkan tampilan untuk pratinjau lokal.
 * @param viewConfig Properti tampilan untuk video lokal. Untuk informasi lebih lanjut, lihat {@link AliVideoCanvas} untuk detailnya
 * @param track  Hanya {@link AliRtcVideoTrackCamera} dan {@link AliRtcVideoTrackScreen} yang didukung.
 * @return
 * - 0: Permintaan berhasil.
 * - < 0: Permintaan gagal.
 * @note Anda dapat beralih tampilan sebelum dan sesudah Anda memanggil metode joinChannel. Jika Anda menyetel canvas atau {@link AliVideoCanvas::view} ke null, kamera berhenti menampilkan tampilan.
 *       Jika Anda ingin mengonfigurasi ulang {@link AliVideoCanvas::renderMode}, pertahankan properti lain di canvas tetap dan ubah hanya
 *       {@link AliVideoCanvas::renderMode}.
 *       Jika Anda ingin mengonfigurasi ulang {@link AliVideoCanvas::mirrorMode}, pertahankan properti lain di canvas tetap dan ubah hanya
 *       {@link AliVideoCanvas::mirrorMode}.
 */
- (int)setLocalViewConfig:(AliVideoCanvas *_Nullable)viewConfig forTrack:(AliRtcVideoTrack)track;
    Windows
    /**
 * @brief Tetapkan tampilan untuk pratinjau lokal.
 * @param renderConfig Properti tampilan untuk video lokal. Untuk informasi lebih lanjut, lihat {@link AliEngineVideoCanvas} untuk detailnya
 * @param track  Hanya {@link AliEngineVideoTrackCamera} dan {@link AliEngineVideoTrackScreen} yang didukung.
 * @return
 * - 0: Permintaan berhasil.
 * - Nilai selain 0: Permintaan gagal.
 * @note Anda dapat beralih tampilan sebelum dan sesudah Anda memanggil metode joinChannel. Jika Anda menyetel canvas atau {@link AliEngineVideoCanvas::displayView} ke null, kamera berhenti menampilkan tampilan.
 *       Jika Anda ingin mengonfigurasi ulang {@link AliEngineVideoCanvas::renderMode}, pertahankan properti lain di renderConfig tetap dan ubah hanya
 *       {@link AliEngineVideoCanvas::renderMode}.
 *       Jika Anda ingin mengonfigurasi ulang {@link AliEngineVideoCanvas::mirrorMode}, pertahankan properti lain di renderConfig tetap dan ubah hanya
 *       {@link AliEngineVideoCanvas::mirrorMode}.
 */
virtual int SetLocalViewConfig(AliEngineVideoCanvas renderConfig,
AliEngineVideoTrack track) = 0;

    2. Mulai pratinjau kamera

    Anda dapat memanggil operasi startPreview untuk memulai pratinjau kamera.

    Android
    /**
 * @brief Mulai pratinjau lokal.
 * @details Mulai pratinjau lokal. Kamera secara otomatis dinyalakan.
 * @return
 * - 0: Permintaan berhasil.
 * - < 0: Permintaan gagal.
 * @note Jika Anda tidak memanggil operasi {@link #setLocalViewConfig} untuk menetapkan tampilan kamera, pratinjau gagal. Ingest stream tidak terpengaruh.
 * Jika Anda memulai pratinjau lokal sebelum {@link #joinChannel}, kamera secara otomatis dinyalakan.
 */
public abstract int startPreview();
    IOS
    /**
 * @brief Mulai pratinjau lokal.
 * @return
 * - 0: Permintaan berhasil.
 * - <0: Permintaan gagal.
 * @note Jika Anda tidak memanggil operasi {@link setLocalViewConfig:forTrack:} untuk menetapkan tampilan kamera, pratinjau gagal. Ingest stream tidak terpengaruh.
 * Jika Anda memulai pratinjau lokal sebelum {@link joinChannel:name:onResultWithUserId:}, kamera secara otomatis dinyalakan.
 */
- (int)startPreview;
    Windows
    /**
 * @brief Mulai pratinjau lokal.
 * @return
 * - 0: Permintaan berhasil.
 * - Nilai selain 0: Permintaan gagal.
 * @note Jika Anda tidak memanggil operasi {@link SetLocalViewConfig} untuk menetapkan tampilan kamera, pratinjau gagal. Ingest stream tidak terpengaruh.
 *       Jika Anda memulai pratinjau lokal sebelum {@link JoinChannel}, kamera secara otomatis dinyalakan.
 */
virtual int StartPreview(int width = 0, int height = 0) = 0;

    3. Mendeteksi apakah kamera abnormal

    Anda dapat mengonfigurasi callback untuk mendeteksi apakah kamera abnormal. Jika tidak ada pengecualian yang terdeteksi dan tampilan kamera ditampilkan sesuai harapan, kamera dapat digunakan dengan normal. Bagian berikut menjelaskan rincian callback.

    Android
    /**
 * @brief Callback dipanggil ketika terjadi pengecualian perangkat lokal.
 * @param deviceType Jenis perangkat. Untuk informasi lebih lanjut, lihat {@link AliRtcEngine.AliRtcEngineLocalDeviceType}.
 * @param exceptionType Jenis pengecualian perangkat. Untuk informasi lebih lanjut, lihat {@link AliRtcEngine.AliRtcEngineLocalDeviceExceptionType}.
 * @param msg Informasi yang dibawa dalam pengecualian.
 * @note Callback ini mengidentifikasi pengecualian perangkat yang tidak dapat diselesaikan. Setelah Anda menerima callback, periksa apakah perangkat tersedia.
 */
public void OnLocalDeviceException(AliRtcEngine.AliRtcEngineLocalDeviceType deviceType, AliRtcEngine.AliRtcEngineLocalDeviceExceptionType exceptionType, String msg){}
    IOS
    /**
 * @brief Callback dipanggil ketika terjadi pengecualian perangkat lokal.
 * @param deviceType Jenis perangkat. Untuk informasi lebih lanjut, lihat {@link AliRtcLocalDeviceType}.
 * @param exceptionType Jenis pengecualian perangkat. Untuk informasi lebih lanjut, lihat {@link AliRtcLocalDeviceExceptionType}.
 * @param msg Informasi yang dibawa dalam pengecualian.
 * @note Callback ini mengidentifikasi pengecualian perangkat yang tidak dapat diselesaikan. Setelah Anda menerima callback, periksa apakah perangkat tersedia.
 */
- (void)onLocalDeviceException:(AliRtcLocalDeviceType)deviceType exceptionType:(AliRtcLocalDeviceExceptionType)exceptionType message:(NSString *_Nullable)msg;
    Windows
    /**
 * @brief Callback dipanggil ketika terjadi pengecualian perangkat lokal.
 * @param deviceType Jenis perangkat. Untuk informasi lebih lanjut, lihat {@link AliEngineLocalDeviceType}.
 * @param exceptionType Jenis pengecualian perangkat. Untuk informasi lebih lanjut, lihat {@link AliEngineLocalDeviceExceptionType}.
 * @param msg Informasi yang dibawa dalam pengecualian.
 * @note Callback ini mengidentifikasi pengecualian perangkat yang tidak dapat diselesaikan. Setelah Anda menerima callback, periksa apakah perangkat tersedia.
 */
virtual void OnLocalDeviceException(AliEngineLocalDeviceType deviceType, AliEngineLocalDeviceExceptionType exceptionType, const char* msg){};