ApsaraVideo Live：AliRtcEngine介面

加入頻道（多參入會）。

public abstract int joinChannel(AliRtcAuthInfo authInfo, String userName);

該介面用於加入頻道。ARTC 通過頻道組織使用者，使用者需要加入頻道才能“發布”或“訂閱”音視頻流。本介面與 joinChannel[1/3]和介面joinChannel[3/3]均可以加入頻道，區別在於通過的認證方式和傳遞的使用者資訊，具體如下：

• joinChannel[1/3]為單參入會介面，傳入Token鑒權產生單參入會的Token 即可入會。RTC 情境推薦使用該介面加入頻道。

• 本介面為多參入會介面，需要傳入Token鑒權產生多參入會Token，並傳入產生 Token 使用的使用者資訊入會。

• joinChannel[3/3]為 AI 即時互動情境使用，傳入單參入會 Token，並根據情境設定使用者屬性capabilityProfile。

調用限制

• 加入頻道成功後，如果中途需要加入其他頻道，必須先調用leaveChannel離開目前通道，並確保收到AliRtcEngineEventListener中的onLeaveChannelResult回調，之後才能再次調用入會。

• 該方法僅支援使用者一次加入一個頻道。

• 使用不同 App ID 的 App 不能互連。

相關回調

成功調用該介面後會觸發以下回調：

• 本端加入頻道的結果會通過AliRtcEngineEventListener中的onJoinChannelResult 回調進行通知加入頻道的結果

• 成功加入頻道後，遠端會觸發onRemoteUserOnLineNotify回調。

參數說明

返回說明

0表示方法調用成功，非0表示方法調用失敗。

加入頻道（單參入會）。

public abstract int joinChannel(String token, AliRTCSdkChannelParam channelParam);

該介面用於加入頻道。ARTC 通過頻道組織使用者，使用者需要加入頻道才能“發布”或“訂閱”音視頻流。本介面與 joinChannel[1/3]和介面joinChannel[2/3]均可以加入頻道，區別在於通過的認證方式和傳遞的使用者資訊，具體如下：

• joinChannel[1/3]為 RTC 情境單參入會介面，傳入Token鑒權產生單參入會的 Token 即可入會。RTC 情境推薦使用該介面加入頻道。

• joinChannel[2/3]為多參入會介面，需要傳入Token鑒權產生多參入會的 Token，並傳入產生 Token 使用的使用者資訊入會。

• 本介面為 AI 即時互動情境使用，傳入單參入會 Token，並根據情境設定使用者屬性capabilityProfile，如果要與 AI 智能體通話時設定為AliCapabilityProfileAiHuman。

調用限制

• 加入頻道成功後，如果中途需要加入其他頻道，必須先調用leaveChannel離開目前通道，並確保收到AliRtcEngineEventListener中的onLeaveChannelResult回調，之後才能再次調用加入頻道。

• 該方法僅支援使用者一次加入一個頻道。

• 使用不同 App ID 的 App 不能互連。

• 加入頻道失敗重試時無需調用。

相關回調

成功調用該介面後會觸發以下回調：

• 本端加入頻道的結果會通過AliRtcEngineEventListener中的onJoinChannelResult 回調進行通知加入頻道的結果

• 成功加入頻道後，遠端會觸發onRemoteUserOnLineNotify回調。

參數說明

返回說明

0表示方法調用成功，非0表示方法調用失敗。

離開頻道。調用該方法後，SDK 會終止音視頻互動、離開目前通道。

public abstract int leaveChannel();

調用時機

• 應該在加入頻道後需要離開頻道時調用該方法。

• 如果已經加入頻道且需要加入其他頻道需要調用此介面先退出頻道。

相關回調

• 本端：調用本方法後會觸發onLeaveChannelResult 回調通知離會結果。

• 遠端：調用該介面成功後遠端使用者會觸發onRemoteUserOffLineNotify 回調。

返回說明

0表示方法調用成功，非0表示方法調用失敗。

檢查當前是否在頻道中。

public abstract boolean isInCall();

返回說明

true表示在頻道中，false表示不在頻道中。

設定使用者角色。

public abstract int setClientRole(AliRTCSdkClientRole clientRole);

該方法用於設定使用者角色為主播/觀眾。

互動模式下，加入頻道前：

• 設定使用者角色為主播：SDK預設會自動推送本地音視頻流，並接收其他主播的音視頻流

• 設定使用者角色為觀眾：SDK不會推送本地的音視頻流，但會接收其他主播的音視頻流。

調用時機

該方法在加入頻道前後均可調用，可以在入會前調用設定使用者角色，也可以在入會後調用進行使用者角色切換。

調用限制

該方法在互動模式下才有效，即調用setChannelProfile介面設定為AliRTCSdkInteractiveLive時才有效。

互動模式下建議入會前顯式調用設定使用者角色。

參數說明

擷取使用者角色。

public abstract AliRTCSdkClientRole getCurrentClientRole();

返回說明

返回目前使用者角色。

重新整理鑒權資訊。

public abstract int refreshAuthInfo(AliRtcAuthInfo authInfo);

該方法用於更新鑒權資訊。Token 會在一定時間後失效，此時 SDK 將無法和伺服器建立串連。

調用時機

在以下情況下：

• 當收到onAuthInfoWillExpire回調報告鑒權資訊即將到期時，推薦你在你的服務端重建 Token，然後調用該方法傳入新的 Token。

• 如果沒有及時更新 Token，會觸發onAuthInfoExpired通告鑒權已經到期，此時需要重建 Token 然後調用joinChannel重新加入頻道。

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

重新整理鑒權資訊。

public abstract int refreshAuthInfo(String token);

該方法用於更新 Token。Token 會在一定時間後失效，此時 SDK 將無法和伺服器建立串連。

調用時機

在以下情況下，推薦你在你的服務端重建 Token，然後調用該方法傳入新的 Token：

• 當收到onAuthInfoWillExpire回調報告鑒權資訊即將到期時。

• 如果沒有及時更新 Token，會觸發onAuthInfoExpired通告鑒權已經到期，此時需要調用joinChannel重新加入頻道。

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

停止或恢複發布本地視頻流。

public abstract int publishLocalAudioStream(boolean enable);

該方法用於控制是否發布本地採集的音頻流。SDK預設設定推送音頻流，如果您不想預設推送音頻流，可以在入會前調用publishLocalAudioStream(false)關閉音頻流的推送。

調用時機

加入頻道前後均可調用。加入頻道前調用可修改預設配置，在加入頻道時生效。

相關回調

本地音頻推流結果發生變化時，本端會觸發onAudioPublishStateChanged回調通知音頻推流最新狀態，遠端會觸發onRemoteTrackAvailableNotify通知遠端使用者的音視頻流發生變化。

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

查詢當前是否發布音頻流。

public abstract boolean isLocalAudioStreamPublished();

返回說明

true表示發布音頻流，false表示不發布音頻流。

設定是否預設接收音頻流。

public abstract int setDefaultSubscribeAllRemoteAudioStreams(boolean sub);

該介面用於配置系統是否預設訂閱遠端使用者的音頻流，該設定將影響新加入頻道使用者的音頻流訂閱行為。無特殊情境需求建議設定為 true。

調用時機

加入頻道前後均可調用。

• 加入頻道前：

  • SDK 加入頻道時預設訂閱遠端使用者的音頻流，如果希望修改此行為，可在加入頻道前調用該介面。

• 加入頻道後：

  • 如果希望停止預設訂閱，可調用setDefaultSubscribeAllRemoteAudioStreams(false)，則不會訂閱後續加入頻道的使用者的音頻流。

  • 停止預設訂閱後，如果希望恢複訂閱指定使用者的音頻流，請調用subscribeRemoteAudioStream 介面，如果希望恢複多個使用者請多次調用。

  • 停止預設訂閱後，調用setDefaultSubscribeAllRemoteAudioStreams(true)僅恢複後續加入頻道的使用者的音頻流，對於停止期間加入的遠端使用者不會訂閱。

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

停止或恢複特定遠端使用者的音頻流拉取。

public abstract int subscribeRemoteAudioStream(String uid, boolean sub);

該介面用於停止或恢複訂閱特定遠端使用者的音頻流，無特殊情境需求建議設定為 true。

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

設定是否接收所有遠端音頻流。

public abstract int subscribeAllRemoteAudioStreams(boolean sub);

該介面為訂閱遠端音頻流的總開關，建議設為 true。 如果設定為 false，則會導致：

• 當前會議中所有遠端音頻停止訂閱；

• 後續入會的新使用者也不再訂閱；

• 無法通過subscribeRemoteAudioStream單獨操控指定使用者的音頻流。

如果需要重新訂閱，請再次調用本介面並設定為 true 恢複訂閱。

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

設定是否發布相機流。

public abstract int publishLocalVideoStream(boolean enable);

該方法用於控制是否發布本地採集的視頻流。

調用時機

加入頻道前後均可調用。

加入頻道前調用可修改預設配置，在加入頻道時生效。

相關回調

本地音頻推流結果發生變化時，本端會觸發onVideoPublishStateChanged回調通知音頻推流最新狀態，遠端會觸發onRemoteTrackAvailableNotify通知遠端使用者的音視頻流發生變化

參數說明

返回說明

0表示介面調用成功，其他表示方法調用失敗。

查詢當前是否發布相機流。

public abstract boolean isLocalVideoStreamPublished();

返回說明

true表示發布相機流，false表示不發布相機流。

設定是否預設接收視頻流。

public abstract int setDefaultSubscribeAllRemoteVideoStreams(boolean sub);

該介面用於設定是否預設訂閱視頻流，SDK 預設訂閱。

調用時機

加入頻道前後均可調用。如果在加入頻道後調用 setDefaultSubscribeAllRemoteVideoStreams(false)，會接收不到設定後加入頻道的使用者的視頻流。

停止接收視頻流後，如果想要恢複接收，請調用subscribeRemoteVideoStream，並指定你想要接收的遠端使用者ID；如果想恢複接收多個使用者的視頻流，則需要多次調用subscribeRemoteVideoStream；setDefaultSubscribeAllRemoteVideoStreams(true) 只能恢複接收後面加入頻道的使用者的視頻流。

該介面用於設定是否預設訂閱遠端使用者的視頻流。

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

停止或恢複訂閱指定的遠端視頻流。

public abstract int subscribeRemoteVideoStream(String uid, AliRtcVideoTrack track, boolean sub);

對指定使用者的視頻流進行訂閱和取消訂閱的操作。

調用時機

入會前入會後均可調用。

參數說明

返回說明

• 0: 執行此介面成功。

• 非 0: 執行此介面失敗。

停止或恢複接收所有遠端視頻流。

public abstract int subscribeAllRemoteVideoStreams(boolean sub);

該介面為訂閱遠端視頻流的總開關，如果設定為 false，則會導致：

• 當前會議中所有遠端視頻流停止訂閱；

• 後續入會的新使用者也不再訂閱（即使設定了setDefaultSubscribeAllRemoteVideoStreams(true)預設訂閱）；

• 無法通過subscribeRemoteVideoStream單獨操控指定使用者的視頻流。

如果需要重新訂閱，請再次調用本介面並設定為 true 恢複訂閱。

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

停止或恢複特定遠端使用者的媒體流。

public abstract int subscribeRemoteMediaStream(String uid, AliRtcVideoTrack videoTrack, boolean subVideo, boolean subAudio);

該介面用於合并訂閱遠端音視頻流。

相關介面

相比subscribeRemoteMediaStream[2/2]，本介面通過兩個布爾型別參數 subVideo、subAudio 決定是否訂閱遠端音視頻流，videoTrack 用於控制拉取哪一路視頻流。

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

停止/恢複訂閱遠端使用者的音視頻流。

public abstract int subscribeRemoteMediaStream(String uid, AliRtcVideoTrack videoTrack, AliRtcAudioTrack audioTrack) ;

該介面用於合并訂閱遠端音視頻流。

相關介面

相比於subscribeRemoteMediaStream[1/2]，這個介面通過 videoTrack、audioTrack 兩個參數在一個介面中把想要訂閱的狀態告知SDK，例如：

• 希望訂閱相機流和麥克風流，則在調用時將 videoTrack 和 audioTrack 分別置為 AliRtcVideoTrackCamera和AliRtcAudioTrackMic。

• 希望取消訂閱相機流但保留麥克風，則在再次調用時將 videoTrack 和 audioTrack 分別置為AliRtcVideoTrackNo和AliRtcAudioTrackMic。

• 如果希望都取消，則在再次調用時將 videoTrack 和 audioTrack 分別置為AliRtcVideoTrackNo和AliRtcAudioTrackNo。

• 如果希望同時訂閱相機流和螢幕畫面分享流兩路視頻流，將 videoTrack 設定為AliRtcVideoTrackBoth，音頻同理。

參數說明

返回說明

• 0：設定成功。

• <0：設定失敗。

跨頻道訂閱指定使用者的流。

public abstract int subscribeRemoteDestChannelStream(String channelId, String uid, AliRtcVideoTrack track, boolean sub_audio, boolean sub);

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

停止或恢複訂閱跨頻道所有使用者的流。

public abstract int subscribeRemoteDestChannelAllStream(String channelId, AliRtcVideoTrack track, boolean sub_audio, boolean sub);

參數說明

返回說明

• 0：調用此方法成功。

• 非 0：調用此方法失敗。

調節拉流的播放音量。

public abstract int setRemoteAudioVolume(String uid, int volume);

通過此介面，本端使用者調節指定使用者的音頻流在本裝置上的播放音量。

參數說明

返回說明

• 0：執行此方法成功。

• 非 0：執行此方法失敗，例如音量值為無效值等。

停止或恢複本地音頻資料發送。

public abstract int muteLocalMic(boolean mute, AliRtcMuteLocalAudioMode mode);

調用時機

加入頻道前後均可調用。

相關回調

調用成功後，遠端使用者觸發onUserAudioMuted通知該使用者是否靜音。

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。mute只是發送音頻資料為靜音幀，採集和編碼模組仍然在工作。

停止或恢複遠端的音頻播放。

public abstract int muteRemoteAudioPlaying(String uid, boolean mute);

該介面僅用於停止或者恢複遠端指定使用者的音訊播放，但是不影響對遠端音訊拉流和解碼，如果希望取消訂閱某個使用者的音頻流，請調用subscribeRemoteAudioStream 完成。

調用時機

入會前後均可設定。

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

停止或恢複遠端所有的音頻播放。

public abstract int muteAllRemoteAudioPlaying(boolean mute);

該介面用於停止或恢複遠端所有音頻播放。

調用時機

加入頻道前後均可設定。

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

開啟音頻採集。

public abstract int startAudioCapture();

此介面用於控制開啟音頻採集。此外在入會前調用可以控制提前開啟音頻採集，如果不設定，則SDK會自動控制音頻採集裝置。調用stopAudioCapture關閉音頻採集後如果想要開啟，請調用此介面。

調用時機

入會前後均可調用。

相關介面

startAudioCapture[2/2]介面通過參數可以控制離會後音頻採集裝置是否保持開啟狀態。

相關回調

調用此介面修改本地音頻採集狀態後，可通過onLocalAudioStateChanged 回調來擷取狀態變化。

返回說明

0表示方法調用成功，其他表示方法調用失敗。

開啟音頻採集。

public abstract int startAudioCapture(boolean keepAlive);

靜音後關閉麥克風採集。

此介面用於控制開啟音頻採集。此外在入會前調用可以控制提前開啟音頻採集，如果不設定，則SDK會自動控制音頻採集裝置。

調用時機

入會前後均可調用。

相關介面

相比startAudioCapture[1/2]，本介面允許通過 keepAlive 參數控制離會後採集裝置是否保持開啟。

相關回調

調用此介面修改本地音頻採集狀態後，可通過onLocalAudioStateChanged 回調來擷取狀態變化。

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

關閉音頻採集。

public abstract int stopAudioCapture();

SDK預設開啟音頻採集，如果沒有特殊配置，啟動預覽、加入頻道等行為會自動啟動音頻採集，如果希望停止音訊裝置採集，請調用本介面。

相關回調

調用此介面修改本地音頻採集狀態後，可通過onLocalAudioStateChanged 回調來擷取狀態變化。

返回說明

0表示方法調用成功，其他表示方法調用失敗。

設定預設音訊輸出是否為擴音器。

public abstract int setDefaultAudioRoutetoSpeakerphone(boolean defaultToSpeakerphone);

該介面用於在入會前設定預設的音頻路由裝置，可選擇預設輸出到耳機或擴音器，SDK 內部預設為擴音器，如果您希望修改該預設配置可在入會前調用本介面。

音頻路由的優先順序在 SDK 內部已經定義好，並會根據當前外設串連狀態自動切換，優先順序如下：有線耳機>藍芽耳機>使用者佈建>預設設定，因此如果沒有串連外設且沒有通過enableSpeakerphone進行設定，則會使用預設設定。

更多有關音頻路由設定相關細節請參考音頻路由設定。

手機裝置一般有兩個音頻路由裝置，分別是耳機和擴音器：

• 當音頻路由為耳機時，聲音比較小，只有將耳朵湊近才能聽清楚，隱私性較好，適合用於電話中。

• 當音頻路由為擴音器時，聲音比較大，不用將手機貼臉也能聽清，因此可以實現“免提”的功能。

相關介面

該介面用於修改預設音頻路由設定，enableSpeakerphone介面用於設定當前路由裝置。

調用時機

入會前後均可調用。

參數說明

返回說明

• 0: 該方法調用成功。

• <0: 該方法調用失敗。

設定音訊輸出為耳機還是擴音器。

public abstract int enableSpeakerphone(boolean enable);

該介面用於在入會後設定當前播放的音訊裝置，在耳機和擴音器之間選擇。如果沒有設定該功能，將使用預設音頻路由所設定的裝置進行播放。

音頻路由的優先順序在 SDK 內部已經定義好，並會根據當前外設串連狀態自動切換，優先順序如下：有線耳機>藍芽耳機>使用者佈建>預設設定，因此當串連外設時，該介面調用不生效。更多有關音頻路由設定相關細節請參考音頻路由設定。

調用時機

加入頻道前後均可調用。

相關介面

setDefaultAudioRoutetoSpeakerphone用於修改預設音頻路由設定，本介面用於設定當前路由裝置。

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

擷取當前音訊輸出為耳機還是擴音器。

public abstract boolean isSpeakerOn();

返回說明

true為擴音器，false為耳機。

開啟使用者音量提示。

public abstract int enableAudioVolumeIndication(int interval, int smooth, int reportVad);

該介面允許 SDK 定期向 App 報告本地發流使用者和瞬時音量最高的遠端使用者的音量相關資訊。如果想使用該功能，請實現AliRtcAudioVolumeObserver類，並調用registerAudioVolumeObserver介面註冊接收對象。

調用時機

加入頻道前後均可調用。

相關回調

成功調用該方法後，如果頻道記憶體在發流使用者時，SDK 會按照設定的時間間隔觸發下面兩個回調：

• 說話人的音頻音量會通過AliRtcAudioVolumeObserver#onAudioVolume 回調通知，回調頻率會根據 interval 決定。

• 語音激勵，當監測到活躍使用者時，說話人uid會通過AliRtcAudioVolumeObserver#onActiveSpeaker回調。

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

啟用耳返。

public abstract int enableEarBack(boolean enable);

該方法用於啟用或關閉耳返功能。建議在戴耳機（有線或藍芽均可）的情況下開啟耳返，效果更好。

調用時機

加入頻道前後均可調用。

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

設定耳返音量。

public abstract int setEarBackVolume(int volume) ;

該介面用於設定耳返的音量， 通過enableEarBack開啟耳返功能後才生效。

調用時機

加入頻道前後均可調用。

參數說明

返回說明

• 0: 方法調用成功。

• <0: 方法調用失敗。

開啟音頻播放裝置。

public abstract int startAudioPlayer();

此介面可以控制提前開啟音頻播放，如果不設定，則SDK會在訂閱到音頻流後自動開啟音頻播放。

返回說明

• 0：調用成功。

• 非 0：調用失敗，返回錯誤碼。

關閉音頻播放裝置。

 public abstract int stopAudioPlayer();

此介面可以控制關閉音頻播放，與startAudioPlayer對應。

返回說明

• 0：調用成功。

• 非 0：調用失敗，返回錯誤碼。

設定本地播放音量。

public abstract int setPlayoutVolume(int volume);

參數說明

返回說明

• 0：調用成功。

• 非 0：調用失敗。

設定錄音音量。

public abstract int setRecordingVolume(int volume);

參數說明

返回說明

• 0：調用成功。

• 非 0：調用失敗。

播放音頻檔案。

public abstract int playAudioFileTest(String filePath) ;

該方法用於在入會前播放一個音頻檔案來進行音頻播放測試。

調用時機

只能在入會前調用此介面。

調用限制

多次調用會相互覆蓋，調用時會停止現正播放的檔案（如果存在）。

參數說明

返回說明

• 0：調用成功。

• 非 0：調用失敗。

停止播放音頻檔案。

public abstract int stopAudioFileTest();

本介面與 playAudioFileTest 相對應，用於停止播放音頻檔案。

調用限制

只能在入會前調用此介面。

返回說明

• 0：調用成功。

• 非 0：調用失敗。

通話前開啟音頻採集裝置檢測。

public abstract int startAudioCaptureTest();

此介面可以控制開啟音頻採集檢測，用於在通話前測試本地音頻採集裝置能否正常工作。調用此方法後，SDK 通過AliRtcAudioVolumeObserver::OnTestAudioVolume 回調向開發人員報告採集裝置的音量資訊。

調用時機

該方法需要在加入頻道前調用。測試完成後，請確保調用stopAudioCaptureTest 停止檢測裝置檢測，防止裝置佔用問題。

返回說明

• 0：調用成功。

• 非 0：調用失敗，返回錯誤碼。

關閉音頻採集檢測。

public abstract int stopAudioCaptureTest();

該方法用於停止音頻採集裝置檢測，調用startAudioCaptureTest 後必須調用該方法停止測試。

調用時機

加入頻道前調用。

返回說明

• 0：調用成功。

• 非 0：調用失敗，返回錯誤碼。

設定變聲音效模式。

public abstract int setAudioEffectVoiceChangerMode(AliRtcAudioEffectVoiceChangerMode mode);

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

設定變調參數。

public abstract int setAudioEffectPitchValue(double value);

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

設定混響音效模式。

public abstract int setAudioEffectReverbMode(AliRtcAudioEffectReverbMode mode);

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

設定混響音效類型和具體參數。

public abstract int setAudioEffectReverbParamType(AliRtcAudioEffectReverbParamType type, float value);

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

設定預設的美聲音效模式。

public abstract int setAudioEffectBeautifyMode(AliRtcAudioEffectBeautifyMode mode);

該介面用於設定 SDK 內部預設的一些美聲模式，適用於語音直播、K歌、語音社交等對人聲音質有美化需求的情境。通過選擇不同的美聲模式，可以改變人聲的聽感效果，如增強磁性、提升清晰度等，從而改善遠端使用者的收聽體驗。

調用時機

加入頻道前後均可調用。

參數說明

返回說明

• 0：設定成功

• 非 0：設定失敗。

設定音頻均衡器參數（EQ），調節指定頻段的增益。

public abstract int setAudioEffectEqualizationParam(AliRtcAudioEffectEqualizationBandFrequency bandIndex, float gain);

該介面用於對本地採集的人聲或音頻訊號進行圖形均衡器（Graphic Equalizer）調節，通過調整 10 個固定頻段中某一頻段的增益（單位：dB），實現音色定製化處理。適用於語音清晰度最佳化、人聲突出、降噪輔助等情境。

均衡器支援從 31 Hz 到 16 kHz 的完整音頻頻譜調節，共 10 個標準頻段，每個頻段可獨立設定增益值，範圍為 [-15, 15] dB，預設為 0 dB（即無增強或衰減）。

調用限制

• 不支援在未開啟美聲模式前單獨使用均衡器，必須在調用 setAudioEffectBeautifyMode 之後調用此介面。

參數說明

返回說明

0：設定成功

非 0：設定失敗。

新增外部音頻流

public abstract int addExternalAudioStream(AliRtcExternalAudioStreamConfig config);

該介面用於新增一個外部音頻流。以下為相關步驟：

1. 調用addExternalAudioStream介面添加一個外部音頻流並擷取外部音頻流 ID。

2. 調用pushExternalAudioStreamRawData向建立的音頻流中傳入音頻資料。

3. 結束通話時，需要調用removeExternalAudioStream移除外部音頻流。

如需在頻道中發布自訂採集音頻，可參考文檔自訂音頻採集。

參數說明

返回說明

>0表示方法調用成功，傳回值為外部音頻流ID，其他表示方法調用失敗。

輸入外部音頻流資料。

public abstract int pushExternalAudioStreamRawData(int streamId, AliRtcAudioFrame rawData);

該介面用於向指定的音頻流傳入資料。以下為相關步驟：

1. 調用addExternalAudioStream介面添加一個外部音頻流並擷取外部音頻流 ID。

2. 調用pushExternalAudioStreamRawData向建立的音頻流中傳入音頻資料。

3. 結束通話時，需要調用removeExternalAudioStream移除外部音頻流。

如需在頻道中發布自訂採集音頻，可參考文檔自訂音頻採集。

調用時機

加入頻道後調用。

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

設定外部音頻流推流音量

public abstract int setExternalAudioStreamPublishVolume(int streamId, int publishVolume);

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

擷取外部音頻流推流音量

public abstract int getExternalAudioStreamPublishVolume(int streamId);

參數說明

返回說明

[0, 100]推流音量，< 0: 失敗。

設定外部音頻流播放音量

public abstract int setExternalAudioStreamPlayoutVolume(int streamId, int playoutVolume);

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

擷取外部音頻流播放音量

public abstract int getExternalAudioStreamPlayoutVolume(int streamId);

參數說明

返回說明

[0, 100] 播放音量,< 0表示調用失敗。

刪除外部音頻流。

public abstract int removeExternalAudioStream(int streamId);

該方法負責根據傳入的 streamId 移除對應的外部音頻流，與addExternalAudioStream 方法相對應，

調用時機

如果您想要使用自訂音頻輸入功能，需要調用addExternalAudioStream 方法添加一個音頻流並擷取外部音頻流 Id，之後調用pushExternalAudioStreamRawData 介面向 sdk 輸入您的音頻資料。在您想要停止自訂音頻輸入時，調用當前介面移除對應的外部音頻流並清理資源。

參數說明

返回說明

• 0：調用成功。

• <0：調用失敗，返回錯誤碼。

擷取音頻檔案資訊。

public abstract int getAudioFileInfo(String fileName);

開發人員可調用此介面非同步擷取檔案的時間長度資訊。此介面為非同步介面，可通過 onAudioFileInfo擷取音頻檔案資訊。

參數介紹

返回介紹

• 0：調用成功。

• 非 0：返回錯誤碼。

開始伴奏混音。

public abstract int startAudioAccompany(String fileName, AliRtcAudioAccompanyConfig config) ;

本介面用於播放本地或線上的伴奏檔案。非同步介面，調用此介面後可通過AliRtcEngineNotify#onAudioAccompanyStateChanged監聽伴奏播放狀態。

調用時機

入會後方可調用。

調用限制

與音效不同，伴奏某一時刻只能播放一個，重複調用會覆蓋上一首伴奏的播放。

參數說明

返回說明

• 0：調用成功。

• 非 0：調用失敗，返回錯誤碼。

停止伴奏混音。

public abstract int stopAudioAccompany() ;

該介面與 startAudioAccompany 對應，用於停止伴奏播放。

調用時機

入會前後均可調用。

返回說明

• 0：調用成功。

• 非 0：調用失敗，返回錯誤碼。

設定伴奏音量，包含伴奏的本地播放音量和推流音量。

public abstract int setAudioAccompanyVolume( int volume) ;

本介面用於設定伴奏音量，同時設定伴奏本地播放音量與伴奏推流音量。此外，setAudioAccompanyPlayoutVolume 和 setAudioAccompanyPublishVolume 分別僅設定本地播放音量和伴奏推流的音量。

參數說明

返回說明

• 0：調用成功。

• 非 0：調用失敗，返回錯誤碼。

設定伴奏推流音量。

public abstract int setAudioAccompanyPublishVolume(int volume) ;

參數說明

返回說明

• 0：調用成功。

• 非 0：調用失敗，返回錯誤碼。

擷取伴奏推流音量。

public abstract int getAudioAccompanyPublishVolume() ;

返回說明

伴奏音樂的推流音量。

• [0-100]：成功。

• 其他：錯誤碼。

設定伴奏本地播放音量。

public abstract int setAudioAccompanyPlayoutVolume(int volume) ;

參數說明

返回說明

• 0：調用成功。

• 非 0：調用失敗，返回錯誤碼。

擷取伴奏本地播放音量。

public abstract int getAudioAccompanyPlayoutVolume() ;

返回說明

伴奏音樂的本地播放音量。

• [0-100]：成功。

• 其他：錯誤碼。

暫停伴奏混音。

public abstract int pauseAudioAccompany();

返回說明

• 0：調用成功。

• 非 0：調用失敗，返回錯誤碼。

重新開始伴奏混音。

public abstract int resumeAudioAccompany();

返回說明

• 0：調用成功。

• 非 0：調用失敗，返回錯誤碼。

擷取伴奏檔案時間長度, 單位為毫秒

public abstract int getAudioAccompanyDuration();

該介面用於擷取當前伴奏檔案的時間長度。

返回說明

• >=0：伴奏檔案時間長度。

• <0：調用失敗，返回錯誤碼。

擷取伴奏檔案播放進度，單位為毫秒。

public abstract int getAudioAccompanyCurrentPosition();

該方法用於擷取當前伴奏檔案的播放進度，單位為毫秒。

返回說明

• >=0: 伴奏檔案播放進度

• <0：調用失敗，返回錯誤碼。

設定伴奏檔案的播放位置。

public abstract int setAudioAccompanyPosition(int posMs);

該方法用於主動設定伴奏的播放進度，用於實現進度條拖動等功能。調用該方法成功後，伴奏檔案將從 posMs 對應位置播放。

參數說明

返回說明

• 0：調用成功。

• 非 0：調用失敗，返回錯誤碼。

預先載入音效檔案。

public abstract int preloadAudioEffect(int soundId, String filePath);

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

刪除預先載入的音效檔案。

public abstract int unloadAudioEffect(int soundId);

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

開始播放音效。

public abstract int playAudioEffect(int soundId, String filePath, int cycles, boolean publish);

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

停止播放音效。

public abstract int stopAudioEffect(int soundId);

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

停止播放所有音效。

public abstract int stopAllAudioEffects();

返回說明

0表示方法調用成功，其他表示方法調用失敗。

設定音效推流音量。

public abstract int setAudioEffectPublishVolume(int soundId, int volume);

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

擷取推流音效音量。

public abstract int getAudioEffectPublishVolume(int soundId);

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

設定音效本地播放音量。

public abstract int setAudioEffectPlayoutVolume(int soundId, int volume);

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

擷取音效本地播放音量（Android和iOS）。

public abstract int getAudioEffectPlayoutVolume(int soundId);

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

設定所有音效推流混音音量。

public abstract int setAllAudioEffectsPublishVolume(int volume);

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

設定所有音效本地播音量（Android和iOS）。

public abstract int setAllAudioEffectsPlayoutVolume(int volume);

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

開啟媒體檔案錄製。

public abstract boolean startRecord(AliRtcRecordType recordType, AliRtcRecordFormat recordFormat, String filePath, AliRtcRecordAudioConfig audioConfig, AliRtcRecordVideoConfig videoConfig, long maxSize, long maxDuration);

參數說明

返回說明

TRUE成功，其他失敗。

停止錄製媒體檔案。

  public abstract void stopRecord();

參數說明

無。

暫停音效。

public abstract int pauseAudioEffect(int soundId);

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

暫停所有音效。

public abstract int pauseAllAudioEffects();

返回說明

0表示方法調用成功，其他表示方法調用失敗。

重新開始播放音效。

public abstract int resumeAudioEffect(int soundId);

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

重新開始播放所有音效。

public abstract int resumeAllAudioEffects();

返回說明

0表示方法調用成功，其他表示方法調用失敗。

建立SurfaceView渲染視圖。

public abstract SophonSurfaceView createRenderSurfaceView(Context context);

顯示視頻視圖必須調用該方法，而不是直接建立 SurfaceView。調用方式如下：

• 將傳回值賦值AliRtcVideoCanvas#view

• 調用setLocalViewConfig設定本地預覽顯示視圖或者調用setRemoteViewConfig設定遠程預覽顯示視圖。

調用時機

加入頻道前後均可調用。

調用限制

請在主線程調用該方法。

參數說明

為本地預覽設定渲染視窗以及繪製參數。

public abstract int setLocalViewConfig(AliRtcVideoCanvas viewConfig, AliRtcVideoTrack track);

該方法用於設定本地預覽視圖，調用該方法會綁定本地視頻流的顯示視窗 (view)，並設定本機使用者視圖的渲染模式、鏡像模式和旋轉角度等，隻影響本機使用者預覽畫面，不影響推流視頻。如果需要設定遠端使用者介面視圖請調用setRemoteViewConfig。

調用時機

該方法在加入頻道前後均可調用。

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

為遠端的視頻設定渲染視窗以及繪製參數。

public abstract int setRemoteViewConfig(AliVideoCanvas canvas, String uid,AliRtcVideoTrack track);

該方法會綁定遠端使用者指定視頻流的顯示視圖，並設定遠端使用者視圖在本地顯示時的渲染模式、鏡像模式和旋轉角度等，隻影響本機使用者看到的視頻畫面。如果需要設定本地預覽視圖，請調用setLocalViewConfig。

• 如果AliRtcVideoCanvas中的view參數為空白，則停止渲染。

• 如果在播放過程中需要重新設定AliRtcVideoCanvas的參數renderMode，請保持其他參數不變，僅修改renderMode。

• 如果在播放過程中需要重新設定AliRtcVideoCanvas的參數mirrorMode，請保持其他參數不變，僅修改mirrorMode。

調用時機

建議在收到onRemoteTrackAvailableNotify 回調時調用，即遠端使用者視頻可用時設定。

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

設定網路攝影機採集偏好。

public abstract int setCameraCapturerConfiguration(AliEngineCameraCapturerConfiguration cameraCapturerConfiguration);

該介面用於配置網路攝影機採集時的偏好，例如網路攝影機方向、採集幀率等。

調用時機

必須在開啟網路攝影機之前設定，例如在以下操作前調用：

• startPreview（開始預覽）

• joinChannel（加入頻道）

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

禁用或重新啟用本地視頻採集。

public abstract int enableLocalVideo(boolean enable);

該方法用於控制本地視頻採集的開啟和關閉，當關閉本地視頻採集時，本地預覽和推流均沒有視頻資料，但是並不影響接收遠端視頻。如果調用此介面關閉了本地網路攝影機採集，那麼本端預覽和遠端推流都會停留在最後一幀。

調用時機

該方法在加入頻道前後均可調用。

相關回調

成功調用本介面後會通過onUserVideoEnabled 回調通知遠端使用者。

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

停止或恢複本地視頻資料發送。

public abstract int muteLocalCamera(boolean mute, AliRtcVideoTrack track);

推流時可調用此介面實現推送全黑色的視訊框架，本地預覽正常，採集，編碼，發送模組仍然工作，只是視頻內容是黑色幀。

參數說明

返回說明

0表示方法調用成功。

檢查網路攝影機是否開啟。

public abstract boolean isCameraOn();

返回說明

true表示網路攝影機已開啟，false表示網路攝影機未開啟。

設定視頻編碼屬性。

public abstract void setVideoEncoderConfiguration(AliRtcVideoEncoderConfiguration config);

該方法用於設定視頻流編碼屬性對應的視頻參數，如解析度、幀率、碼率、視頻方向等。有視頻情境都建議調用此介面。

調用時機

該方法在入會前和入會後都可以調用。如果每次入會只需要設定一次相機流視頻編碼屬性，建議在入會前調用。

調用限制

該方法的 mirrorMode 和 setVideoMirrorMode 均可設定視頻推流鏡像，建議只使用一種，同時使用多種會導致鏡像效果疊加從而造成設定鏡像失敗或錯亂。

參數說明

設定視頻解碼屬性。

    public abstract void setVideoDecoderConfiguration(AliRtcVideoDecoderConfiguration config);

該方法用於設定視頻流視頻解碼屬性對應的視頻參數。

調用時機

該方法建議在入會前調用。

參數說明

切換前後網路攝影機（預設為自拍）。

public abstract int switchCamera();

此介面用於控制使用前置/後置網路攝影機，預設採用自拍，可以在 App 運行期間根據可用網路攝影機實際情況來動態切換網路攝影機，而無需重啟視頻流或重新設定視頻源。

調用時機

該方法必須在網路攝影機成功開啟後調用。

調用限制

僅 Android 和 iOS 平台可用。

返回說明

0表示方法調用成功，其他表示方法調用失敗。

擷取當前網路攝影機方向。

public abstract AliRTCCameraDirection getCurrentCameraDirection();

返回說明

• 返回CAMERA_REAR(0)表示後置網路攝影機。

• 返回CAMERA_FRONT(1)表示自拍。

• 返回CAMERA_INVALID(-1)表示無效。

開始本地預覽。

public abstract int startPreview();

該介面用於開啟本地視頻預覽並自動開啟網路攝影機，如果需要停止本地預覽，可以調用stopPreview 介面。

調用時機

• 調用前需要通過 setLocalViewConfig 為本地預覽設定視圖，否則無法預覽，但不影響推流。

• 如有需要可以在 joinChannel 加入頻道前調用此介面開啟預覽，會自動開啟網路攝影機。

返回說明

0表示方法調用成功，其他表示方法調用失敗。

停止本地預覽。

public abstract int stopPreview();

該介面用於關閉本地視頻預覽並關閉網路攝影機，停止預覽後本端將保持在最後一幀，不影響推流。

調用時機

開啟預覽後如果需要關閉預覽則可以調用此方法。

返回說明

0表示方法調用成功，其他表示方法調用失敗。

設定網路攝影機縮放比例。

public abstract int setCameraZoom(float zoom);

設定網路攝影機的縮放比例。

調用限制

只有iOS和android提供這個介面。

調用時機

網路攝影機開啟後設定才有效，每次網路攝影機重啟後縮放也會重設。

參數說明

返回說明

• 0: 調用該方法成功。

• 非 0: 調用該方法失敗。

擷取網路攝影機支援最大縮放（變焦）比例。

public abstract float GetCameraMaxZoomFactor();

返回說明

裝置網路攝影機支援的最大縮放比例。

擷取當前網路攝影機縮放比例設定。

public abstract float GetCurrentZoom();

返回說明

裝置網路攝影機當前縮放比例。

設定網路攝影機曝光度。

public abstract int SetExposure(float exposure);

當拍攝環境光線不足或過於明亮時，會影響視頻採集的畫質。為了獲得更好的視頻效果，你可以使用該方法調節正在使用的網路攝影機的曝光度。可通過GetMinExposure 和GetMaxExposure 擷取當前裝置支援的曝光度範圍。

參數說明

返回說明

• 0: 調用此方法成功。

• 非 0：調用此方法失敗。

擷取網路攝影機曝光度。

public abstract float GetCurrentExposure();

擷取當前正在使用的網路攝影機的曝光度設定。

返回說明

當前網路攝影機曝光度。

擷取網路攝影機支援的最小曝光度。

public abstract float GetMinExposure();

返回說明

網路攝影機最小曝光度。

擷取網路攝影機支援的最大曝光度。

public abstract float GetMaxExposure();

返回說明

網路攝影機最大曝光度。

設定網路攝影機閃光燈開關。

public abstract int setCameraFlash(boolean flash);

開啟或關閉閃光燈。

調用限制

只有iOS和android提供這個介面。

參數說明

返回說明

• 0: 設定成功。

• 非 0： 設定失敗。

當前裝置是否支援手動聚焦。

public abstract boolean isCameraFocusPointSupported();

用來檢查當前攝像機是否可以設定聚焦點以支援手動聚焦功能。

調用限制

只有iOS和android提供這個介面。

返回說明

• true：裝置支援手動對焦功能。

• false：裝置不支援手動對焦功能。

是否支援設定網路攝影機曝光點。

public abstract boolean isCameraExposurePointSupported();

用於檢查當前裝置是否支援設定曝光點。

調用限制

只有iOS和android提供這個介面。

返回說明

• true：支援設定網路攝影機曝光點。

• false：不支援設定網路攝影機曝光點。

設定網路攝影機手動聚焦點。

public abstract int setCameraFocusPoint(float x, float y);

設定當前網路攝影機的聚焦點。調用後camera對所設點做一次曝光調整，後面一直保持這個對焦值。調用此介面前建議調用isCameraFocusPointSupported 檢查裝置是否支援手動聚焦功能。

調用限制

只有iOS和android提供這個介面。

參數說明

返回說明

• 0：此方法調用成功。

• 非 0：此方法調用失敗。

設定網路攝影機曝光點。

public abstract int setCameraExposurePoint(float x, float y);

設定網路攝影機曝光點。調用後camera對所設點做一次曝光調整，後面一直保持這個曝光值。調用此介面前建議調用isCameraExposurePointSupported 檢查裝置是否支援手動設定聚焦功能。

調用限制

只有iOS和android提供這個介面。

參數說明

返回說明

• 0：此方法調用成功。

• 非 0：此方法調用失敗。

是否支援網路攝影機自動人臉聚焦。

public abstract boolean isCameraAutoFocusFaceModeSupported();

是否支援網路攝影機自動人臉聚焦。

調用時機

相機開啟後調用才有效。如果在調用時相機沒有開啟會預設返回 false。在相機開啟的情況下，如果當前相機同時支援Face Service和對焦功能則返回true。

調用限制

只有iOS和android提供這個介面。

返回說明

• true：支援自動人臉聚焦。

• false：不支援自動人臉聚焦。

設定網路攝影機人臉聚焦。

public abstract boolean setCameraAutoFocusFaceModeEnabled(boolean enable);

調用此介面可以設定攝像機即時對焦到人臉上。在調用該方法前，請調用isCameraAutoFocusFaceModeSupported 驗證裝置是否支援此功能。

調用限制

只有iOS和android提供這個介面。

參數說明

返回說明

• true：調用成功。

• false：調用失敗。

設定預覽和推流視頻鏡像能力。

public abstract int setVideoMirrorMode(AliRtcVideoPipelineMirrorMode mirrorMode);

設定本地預覽視頻和推送的視頻流是否開啟鏡像模式。

調用時機

此介面在入會前和入會後均可以動態設定，SDK內部會選項組，並在可以操作預覽及編碼（推流）的時候對視頻進行操作。

調用限制

此介面與setLocalViewConfig&setVideoEncoderConfiguration裡面的mirrorMode重合，建議只使用一個方式。

參數說明

返回說明

• 0：設定成功。

• <0：設定失敗。

  • AliRtcErrInner: SDK內部狀態錯誤，需檢查是否建立SDK執行個體成功。

設定視頻採集縮放時機。

public abstract void setCapturePipelineScaleMode(AliRtcCapturePipelineScaleMode mode);

設定視頻資料擷取縮放時機是採集的時候立即縮放還是編碼時才進行縮放。例如當採集的解析度與編碼解析度不一致時可以通過設定縮放的時機來決定預覽資料與推流資料是否一致。

調用時機

此方法需要在開啟網路攝影機之前進行設定，例如在 startPreview 開始預覽、joinChannel 加入頻道之前進行設定。

參數說明

返回說明

無。

啟用外部視頻輸入源。

public abstract void setExternalVideoSource(boolean enable,boolean useTexture,
 AliRtcVideoTrack streamType,AliRtcRenderMode renderMode);

參數說明

輸入視頻資料。

public abstract int pushExternalVideoFrame(AliRtcRawDataFrame aliRawDataFrame,AliRtcVideoTrack streameType);

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

開啟旁路直播。

public abstract int startPublishLiveStream(String streamUrl,AliRtcLiveTranscodingParam transcodingParam);

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

更新旁路直播相關參數。

public abstract int updatePublishLiveStream(String streamUrl,AliRtcLiveTranscodingParam transcodingParam);

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

停止旁路直播。

public abstract int stopPublishLiveStream(String streamUrl);

參數說明

返回說明

0表示方法調用成功，其他表示方法調用失敗。

擷取旁路直播狀態。

public abstract AliRtcEngine.AliRtcLiveTranscodingState getPublishLiveStreamState(String streamUrl);

參數說明

返回說明

返回旁路直播狀態。

開啟網路品質探測。

public abstract int startNetworkQualityProbeTest(AlirtcNetworkQualityProbeConfig config);

參數說明

返回說明

0表示成功，其他表示失敗。

停止網路品質探測。

public abstract int stopNetworkQualityProbeTest();

返回說明

0表示成功，其他表示失敗。

發送媒體擴充資訊。

public abstract int sendMediaExtensionMsg(byte[]message, int repeatCount, int delay, boolean isKeyFrame);

SDK提供了發送和接收媒體擴充資訊的功能，當前方法實現了發送媒體擴充資訊的功能，內部使用SEI擴充協議來實現。接收方可通過監聽onMediaExtensionMsgReceived 擷取資訊。

常見使用情境包括：

• 使用媒體擴充資訊傳遞時間戳記，計算端到端的網路延遲，或者跟自身其他業務做資料同步

• 使用媒體擴充資訊傳遞描述資訊。目前可以傳遞最多 4k Byte資料，可以用來傳輸少量資料，建議使用Json或者純字串

調用時機

在開始推流後調用。

調用限制

使用媒體擴充資訊時需要複用音視頻資料通道，因此必須控制自訂訊息的發送頻率和訊息資料長度，使用限制如下：

• 每秒最多發送profile 中設定的 fps 條訊息，因為sei資訊是放到h264/h265流中傳輸，有視訊框架編碼才能附加擴充資訊；

• 為了不影響媒體資料的傳輸品質，自訂訊息體長度限制為4k Byte，可以用來傳輸少量資訊；

• sendMediaExtensionMsg函數中repeatCount參數為自訂訊息冗餘度，若大於1，則會發送多次，

• 防止網路丟包導致的訊息丟失，此時房間裡的其他人也會收到多次相同的訊息，需要去重;

• 發送的自訂訊息，在旁路直播時，房間裡的訂閱者也一樣會收到

• 同一時間只有一條MediaExtensionMsg在傳輸，多次調用sendMediaExtensionMsg，新調用的資料會覆蓋前一次的資料。

相關回調

當推流方發送了媒體擴充資訊後，拉流方可通過監聽onMediaExtensionMsgReceived 回調擷取資訊。

參數說明

返回說明

• 0：調用成功。

• <0：調用失敗，返回錯誤碼。

  • ERR_INNER(-1): SDK內部錯誤，可能的情況為SDK未初始化或者SDK銷毀後調用。

發送媒體擴充資訊。

public abstract int sendMediaExtensionMsgEx(byte[]message, int repeatCount, int delay, boolean isKeyFrame, int payloadType);

SDK提供了發送和接收媒體擴充資訊的功能，當前方法實現了發送媒體擴充資訊的功能，內部使用SEI擴充協議來實現。接收方可通過監聽onMediaExtensionMsgReceived 擷取資訊。當payloadType 為 5 時等於使用sendMediaExtensionMsg 介面。

常見使用情境包括：

• 使用媒體擴充資訊傳遞時間戳記，計算端到端的網路延遲，或者跟自身其他業務做資料同步

• 使用媒體擴充資訊傳遞描述資訊。目前可以傳遞最多 4k Byte資料，可以用來傳輸少量資料，建議使用JSON或者純字串

調用時機

在開始推流後調用。

調用限制

使用媒體擴充資訊時需要複用音視頻資料通道，因此必須控制自訂訊息的發送頻率和訊息資料長度，使用限制如下：

• 每秒最多發送profile 中設定的 fps 條訊息，因為sei資訊是放到h264/h265流中傳輸，有視訊框架編碼才能附加擴充資訊；

• 為了不影響媒體資料的傳輸品質，自訂訊息體長度限制為4k Byte，可以用來傳輸少量資訊；

• sendMediaExtensionMsg函數中repeatCount參數為自訂訊息冗餘度，若大於1，則會發送多次，

• 防止網路丟包導致的訊息丟失，此時房間裡的其他人也會收到多次相同的訊息，需要去重;

• 發送的自訂訊息，在旁路直播時，房間裡的訂閱者也一樣會收到

• 同一時間只有一條MediaExtensionMsg在傳輸，多次調用sendMediaExtensionMsg，新調用的資料會覆蓋前一次的資料。

參數說明

返回說明

• 0：調用成功。

• <0：調用失敗，返回錯誤碼。

  • ERR_INNER(-1): SDK內部錯誤，可能的情況為SDK未初始化或者SDK銷毀後調用。

網路連結狀態回調；客戶需要關心此回調。

public void onConnectionStatusChange(AliRtcEngine.AliRtcConnectionStatus status,
 AliRtcEngine.AliRtcConnectionStatusChangeReason reason);

參數說明

本地裝置異常回調；客戶需要關心此回調。

public void OnLocalDeviceException(AliRtcEngine.AliRtcEngineLocalDeviceType deviceType, AliRtcEngine.AliRtcEngineLocalDeviceExceptionType exceptionType, String msg)

參數說明

使用者鑒權資訊即將到期通知，收到後30秒鑒權到期;客戶需要關心此回調。

public void onAuthInfoWillExpire();

該回調錶示使用者的鑒權資訊即將失效，收到此回調後 30 秒鑒權到期，你需要重新擷取新的 Token，然後通過下列任意一種方式更新鑒權資訊：

• 調用refreshAuthInfo介面更新鑒權資訊。

• 調用leaveChannel離開目前通道，然後再調用joinChannel重新加入頻道。

觸發時機

SDK 會在使用者鑒權資訊到期前 30s 觸發此回調，收到該回調後應該及時更新鑒權資訊。

使用者調用需要鑒權的介面，服務端返回資訊到期。

public void onAuthInfoExpired();

該回調錶示使用者鑒權資訊已到期，如果想繼續在會中，需要在服務端產生新的 Token，然後通過下列方法更新鑒權資訊：

• 調用leaveChannel離開目前通道，然後再調用joinChannel重新加入頻道。

觸發時機

當使用者鑒權資訊到期時會觸發此回調。

加入頻道結果回調。

public void onJoinChannelResult(int result, String channel, String userId, int elapsed);

參數說明

離開頻道結果回調。

public void onLeaveChannelResult(int result, AliRtcEngine.AliRtcStats stats);

觸發條件

當應用成功調用leaveChannel離會時會觸發此回調返回離會的結果和本次頻道會話的統計資訊。

參數說明

遠端使用者下線回調。

public void onRemoteUserOffLineNotify(String uid, AliRtcUserOfflineReason reason);

該回調用於通知本機使用者，遠端使用者因各種原因離開頻道。當遠端使用者離線，該介面將被觸發。

觸發條件

• 當遠端使用者角色主動離開頻道時，觸發回調。

• 當遠端主播調用setClientRole切換為觀眾角色（調用 AliRtcEngine#setClientRole 設定為 AliRTCSdkLive）時，觸發回調。

• 當長時間未收到遠端主播資料並認為其掉線時，觸發回調。

參數說明

遠端使用者上線回調。

public void onRemoteUserOnLineNotify(String uid, int elapsed);

該介面用於通知本地用戶端遠端使用者加入頻道。

觸發條件

• 遠端使用者成功加入頻道。

• 目前使用者加入頻道後，會收到頻道中已有使用者的加入回調，用於顯示之前已加入的使用者。

參數說明