ApsaraVideo Live：AliRtcEngine介面

建立AliRtcEngine執行個體。

static AliEngine *Create(const char *extras);

調用時機

請確保在調用 ARTC SDK 其他 APi 前調用該方法建立 AliRtcEngine 執行個體。

調用限制

對於每個 App，SDK 僅支援建立一個 AliRtcEngine 執行個體。

參數說明

返回說明

返回一個 AliEngine 類的單例執行個體。

銷毀AliRtcEngine執行個體。

static void Destroy(AliEngineDestroyCompletionCallback *callback = nullptr);

銷毀AliRtcEngine 單例對象，調用該方法後將會釋放所有內部使用的資源，你將不能再使用AliRtcEngine的其他方法和任何回調，如需要再次使用需要重新調用Create 建立新的執行個體。

調用時機

當完成音視頻通訊之後都建議調用該方法釋放執行個體。

調用限制

為避免死結，不建議在任何SDK的回調中調用本方法。

參數說明

擷取功能介面執行個體。

virtual int QueryInterface(AliEngineInterfaceIdType iid, void** pInterface) = 0;

本介面用於擷取特定類型的功能介面執行個體。在開發音視頻相關應用時，windows 平台下許多進階功能（如音訊裝置管理AliEngineInterfaceAudioDeviceManager、視頻裝置管理AliEngineInterfaceVideoDeviceManager和媒體引擎AliEngineInterfaceMediaEngine）是通過對應的介面類提供的。但在調用相關方法之前，必須通過 QueryInterface 方法擷取這些介面的執行個體。

參數說明

返回說明

• 0：擷取成功。

• <0：擷取失敗。

設定是否相容H5。

static void SetH5CompatibleMode(bool comp);

參數說明

檢查是否設定了H5相容模式。

static bool GetH5CompatibleMode();

返回說明

YES表示相容H5，NO表示不相容H5。

設定相關監聽事件回調。

virtual int SetEngineEventListener(AliEngineEventListener *listener) = 0;

該方法為 SDK 用於設定回調監聽器的一個方法。通過設定該監聽器，開發人員可以接收引擎中的各種通知事件（如使用者加入、離開頻道、網路狀態變化、音視頻流狀態等）。

開發人員需要實現 AliEngineEventListener 類，來定製具體需要監聽的事件方法。預設所有介面都有空實現，開發人員不需要實現所有方法，可根據自身業務來實現對應的事件方法。

相關回調

在運行過程中如遇到異常情況，會優先嘗試內部重試機制以自動回復。對於無法自行解決的錯誤，SDK 會通過預定義的回調介面通知您的應用程式。以下是一些 SDK 無法處理、需由應用程式層監聽和響應的關鍵回調：

參數說明

返回說明

• 0：成功。

• 非 0：失敗，可能因為傳入的 listener 參數不合法或 SDK 未正確初始化。

查詢當前 SDK 版本。

static const char *GetSDKVersion();

返回說明

當前的SDK版本號碼，格式為字串，例："2.5.0.x"。

設定頻道模式。

virtual int SetChannelProfile(const AliEngineChannelProfile channelProfile) = 0;

該介面用於設定頻道模式，目前主要提供視訊通話情境和互動直播情境：

• 視訊通話模式：所有使用者都是主播角色，可以進行推流和拉流。

• 互動直播模式：需要調用SetClientRole（設定角色），在頻道內推流的使用者佈建主播角色（AliRTCSdkInteractive）；如果使用者只需要拉流，不需要推流，則設定觀眾角色（AliRTCSdkLive）。RTC 情境推薦設定為此模式。

調用時機

該介面只可以在加入頻道之前調用，會議中不可以重新設定，離開頻道後可以重新設定。

參數說明

返回說明

• 0：表示方法調用成功。

• 其他表示方法調用失敗。

  • -1：SDK未初始化或已銷毀。

設定音頻Profile。

virtual int SetAudioProfile(int audioProfile, int audioScene) = 0;

該介面用於設定音頻編碼模式以及音頻情境模式。詳情請參考音頻常用操作和配置。ARTC SDK 預設使用高音質模式（AliEngineHighQualityMode）和音樂情境模式（AliEngineSceneMusicMode）。如果預設設定無法滿足您的需求，您需要調用此介面進行設定。

調用時機

該介面只可以在加入頻道之前調用，加入頻道後不可以重新設定，離開頻道後可以重新設定。

參數說明

返回說明

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

檢查當前是否純音頻模式。

virtual bool IsAudioOnlyMode() = 0;

返回說明

YES表示純音頻模式，NO表示音視頻模式。

設定為純音頻模式還是音視頻模式。

virtual int SetAudioOnlyMode(bool audioOnly) = 0;

參數說明

返回說明

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

加入頻道。

virtual int JoinChannel(const char *token, const char *channelId, const char *userId, const char *userName) = 0;

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

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

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

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

調用時機

需要在建立引擎後調用。

調用限制

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

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

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

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

相關回調

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

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

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

參數說明

返回說明

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

加入頻道。

virtual int JoinChannel(const AliEngineAuthInfo &authInfo,
                                 const char *userName) = 0;

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

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

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

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

調用限制

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

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

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

相關回調

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

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

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

參數說明

加入頻道。

virtual int JoinChannel(const char *token, const char *channelId, const char *userId, const AliEngineChannelParam &userParam) = 0;

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

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

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

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

調用限制

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

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

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

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

相關回調

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

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

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

參數說明

返回說明

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

離開頻道。

virtual int LeaveChannel() = 0;

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

調用時機

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

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

相關回調

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

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

返回說明

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

檢查當前是否在頻道中。

virtual bool IsInCall() = 0;

返回說明

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

設定使用者角色。

virtual int SetClientRole(const AliEngineClientRole clientRole) = 0;

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

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

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

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

調用時機

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

調用限制

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

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

參數說明

返回說明

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

擷取目前使用者角色類型（主播/觀眾）。

virtual AliEngineClientRole GetClientRole() = 0;

返回說明

方法調用成功後，返回AliEngineClientRole對象，該對象為枚舉類型，表示角色類型為主播（0） 或者觀眾（1）。

重新整理鑒權資訊。

virtual int RefreshAuthInfo(const AliEngineAuthInfo &authInfo) = 0;

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

調用時機

在以下情況下：

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

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

參數說明

返回說明

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

重新整理鑒權資訊。

virtual int RefreshAuthInfo(const char *token) = 0;

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

調用時機

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

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

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

參數說明

返回說明

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

設定是否允許發布音頻流。

virtual int PublishLocalAudioStream(bool enabled) = 0;

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

調用時機

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

相關回調

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

參數說明

返回說明

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

查詢當前是否允許推音頻流。

virtual bool IsLocalAudioStreamPublished() = 0;

返回說明

true表示允許推送，false表示不允許推送。

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

virtual int SetDefaultSubscribeAllRemoteAudioStreams(bool sub) = 0;

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

調用時機

加入頻道前後均可調用。

• 加入頻道前：

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

• 加入頻道後：

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

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

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

參數說明

返回說明

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

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

virtual int SubscribeRemoteAudioStream(const char* uid, bool sub) = 0;

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

參數說明

返回說明

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

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

virtual int SubscribeAllRemoteAudioStreams(bool sub) = 0;

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

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

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

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

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

參數說明

返回說明

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

發布/停止發布相機流。

virtual int PublishLocalVideoStream(bool enabled) = 0;

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

調用時機

加入頻道前後均可調用。

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

相關回調

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

參數說明

返回說明

• 0：介面調用成功。

• <0：介面調用失敗。

設定是否允許發送視頻流。

virtual int PublishLocalVideoStream(bool enabled, AliEngineVideoTrack track) = 0;

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

調用時機

加入頻道前後均可調用。

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

相關回調

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

參數說明

返回說明

• 0：介面調用成功。

• <0：介面調用失敗。

查詢當前是否允許發布視頻流。

virtual bool IsLocalVideoStreamPublished() = 0;

返回說明

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

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

virtual int SetDefaultSubscribeAllRemoteVideoStreams(bool sub) = 0;

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

調用時機

入會前後均可調用。

• 入會前：

  • 可通過此介面取消預設訂閱設定。

• 入會後：

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

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

  • 停止預設訂閱後，調用SetDefaultSubscribeAllRemoteVideoStreams(false)僅恢複後續加入頻道的使用者的音頻流。

參數說明

返回說明

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

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

virtual int SubscribeRemoteVideoStream(const char* uid, AliEngineVideoTrack track, bool sub) = 0;

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

調用時機

入會前後均可調用。

參數說明

返回說明

• true：設定成功。

• false：設定失敗。

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

virtual int SubscribeAllRemoteVideoStreams(bool sub) = 0;

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

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

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

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

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

參數說明

返回說明

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

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

virtual int SubscribeRemoteMediaStream(const char* uid, AliEngineVideoTrack videoTrack, bool subVideo,  bool subAudio) = 0;

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

相關介面

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

參數說明

返回說明

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

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

virtual int SubscribeRemoteMediaStream(const char* uid, AliEngineVideoTrack videoTrack, AliEngineAudioTrack audioTrack) = 0;

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

相關介面

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

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

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

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

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

參數說明

返回說明

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

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

virtual int SubscribeRemoteDestChannelStream(const char* channelId, const char* uid, AliEngineVideoTrack track, bool sub_audio, bool sub) = 0;

參數說明

返回說明

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

調節本地播放的指定遠端使用者音量。

virtual int SetRemoteAudioVolume(const char *uid, int volume) = 0;

參數說明

返回說明

• 0：成功。

• 非 0：失敗。

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

virtual int MuteLocalMic(bool mute, AliEngineMuteLocalAudioMode mode = AliEngineMuteLocalAudioModeDefault) = 0;

調用時機

加入房間前後均可調用。

相關回調

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

參數說明

返回說明

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

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

virtual int MuteRemoteAudio(const char *uid,
                                    bool mute) = 0;

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

調用時機

加入頻道前後均可調用。

參數說明

返回說明

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

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

virtual int MuteAllRemoteAudio(bool mute) = 0;

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

調用時機

加入頻道前後均可設定。

參數說明

返回說明

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

開啟音頻採集。

virtual int StartAudioCapture() = 0;

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

調用時機

入會前後均可調用。

相關介面

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

相關回調

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

返回說明

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

開啟音頻採集。

virtual int StartAudioCapture(bool keepAlive) = 0;

靜音後關閉麥克風採集。

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

調用時機

入會前後均可調用。

相關介面

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

相關回調

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

參數說明

返回說明

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

關閉音頻採集。

virtual int StopAudioCapture() = 0;

調用StartAudioCapture開啟音訊裝置採集後，可以調用此方法停止採集。

相關回調

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

返回說明

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

設定音量回調頻率和平滑係數。

virtual int EnableAudioVolumeIndication(int interval, int smooth, int reportVad) = 0;

該介面允許 SDK 定期向 App 報告本地發流使用者和瞬時音量最高的遠端使用者的音量相關資訊。

調用時機

加入頻道前後均可調用。

相關回調

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

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

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

調用時機

入會前後均可調用。

參數說明

返回說明

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

開啟音頻播放裝置。

virtual int StartAudioPlayer() = 0;

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

返回說明

• 0：成功。

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

關閉音頻播放。

virtual int StopAudioPlayer() = 0;

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

參數說明

無。

返回說明

• 0：成功。

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

設定播放音量。

virtual int SetPlayoutVolume(int volume) = 0;

參數說明

返回說明

• 0：成功。

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

virtual int SetRecordingVolume(int volume) = 0;

參數說明

返回說明

• 0：成功。

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

播放音頻檔案。

virtual int PlayAudioFileTest(const char* filePath) = 0;

參數說明

返回說明

• 0：成功。

• <0：失敗。

停止播放音頻檔案。

virtual int StopAudioFileTest() = 0;

返回說明

• 0：成功。

• <0：失敗。

通話前開啟音頻採集測試。

virtual int StartAudioCaptureTest() = 0;

此介面可以控制開啟音頻採集測試,通過 AliEngineEventListener::OnTestAudioVolumeCallback 回調結果來判斷音頻採集是否正常。

返回說明

• 0：成功。

• <0：失敗。

關閉音頻採集測試。

virtual int StopAudioCaptureTest() = 0;

返回說明

• 0：成功。

• <0：失敗。

開啟/關閉系統聲音採集推送。

virtual int EnableSystemAudioRecording(bool enable, const char *path = nullptr, const char *device_id = nullptr) = 0;

此介面用於開啟或關閉系統聲音採集，如瀏覽器、應用播放的聲音等。

參數說明

返回說明

• 0：介面調用成功。

• <0：介面調用失敗。

當前是否開啟系統聲音採集推送。

virtual bool IsSystemAudioRecording() = 0;

返回說明

• true：開啟狀態。

• false：關閉狀態。

設定系統聲音採集推送音量。

virtual int SetSystemAudioRecordingVolume(int volume) = 0;

此介面僅在 Windows 和 macOS 平台上有效。

此介面需要開啟系統聲音採集推送後才能設定，否則設定無效。

參數說明

返回說明

• 0：成功。

• <0：失敗。

擷取當前設定系統聲音採集推送音量。

virtual int GetSystemAudioRecordingVolume() = 0;

此介面僅在 Windows 和 macOS 平台上有效。

返回說明

系統採集推流音量。

設定系統聲音播放音量。

virtual int SetSystemAudioPlayoutVolume(int volume) = 0;

此介面僅在 Windows 和 macOS 平台上有效。

此介面需要開啟系統聲音採集推送後才能設定，否則設定無效。

參數說明

返回說明

• 0：成功。

• <0：失敗。

擷取當前設定系統聲音播放音量。

virtual int GetSystemAudioPlayoutVolume() = 0;

此介面僅在 Windows 和 macOS 平台上有效。

返回說明

系統採集播放音量。

擷取系統中的錄音裝置列表。

virtual AliEngineDeviceInfoList* GetAudioCaptureList() = 0;

傳回值

AliEngineDeviceInfoList * 錄音裝置列表指標。

擷取使用的錄音裝置名稱。

virtual String GetCurrentAudioCaptureName() = 0;

傳回值

String 當前音頻採集裝置名稱。

擷取使用的錄音裝置ID。

virtual String GetCurrentAudioCaptureID() = 0;

傳回值

當前使用的錄音裝置ID。

選擇錄音裝置名稱。

virtual int SetCurrentAudioCaptureName(const char* captureName) = 0;

參數說明

傳回值

0成功，其他失敗。

選擇錄音裝置ID。

virtual int SetCurrentAudioCaptureID(const char* captureID) = 0;

參數說明

傳回值

0成功，其他失敗。

擷取系統中的擴音器列表。

virtual AliEngineDeviceInfoList* GetAudioPlayerList() = 0;

傳回值

系統中的擴音器列表對象指標 AliEngineDeviceInfoList *

擷取系統中的可錄製的擴音器列表（系統內錄使用）。

virtual AliEngineDeviceInfoList* GetSystemRecordAudioPlayerList() = 0;

傳回值

音頻播放裝置列表主要提供給EnableSystemAudioRecording作為最後一個參數使用，採集系統播放音頻使用。

擷取當前使用的擴音器名稱。

virtual String GetCurrentAudioPlayerName() = 0;

傳回值

當前音頻播放裝置名稱

擷取當前使用的擴音器ID。

virtual String GetCurrentAudioPlayerID() = 0;

傳回值

當前音頻播放裝置ID。

選擇擴音器名稱。

virtual int SetCurrentAudioPlayerName(const char* playerName) = 0;

傳回值

音頻播放裝置名稱。

選擇擴音器ID

virtual int SetCurrentAudioPlayerID(const char* playerID) = 0;

參數說明

傳回值

0成功，其他失敗。

設定音頻採集裝置音量，音量範圍[0, 100]。

virtual int SetRecordingDeviceVolume(int volume) = 0;

參數列表

傳回值

0成功，其他失敗。

擷取音頻採集裝置音量。

virtual int GetRecordingDeviceVolume() = 0;

傳回值

>=0返迴音量，其他失敗。

設定音頻播放裝置音量，音量範圍[0, 100]。

virtual int SetPlaybackDeviceVolume(int volume) = 0;

參數說明

傳回值

0成功，其他失敗。

擷取音頻播放裝置音量。

virtual int GetPlaybackDeviceVolume() = 0;

傳回值

>=0 系統音量，其他失敗。

靜音音頻採集裝置。

virtual int SetRecordingDeviceMute(bool mute) = 0;

參數說明

傳回值

0成功，其他失敗。

擷取音頻採集裝置靜音狀態

virtual bool GetRecordingDeviceMute() = 0;

傳回值

錄音是否靜音。

靜音音頻播放裝置

virtual int SetPlaybackDeviceMute(bool mute) = 0;

參數說明

傳回值

0成功，其他失敗。

擷取音頻播放裝置靜音狀態。

virtual bool GetPlaybackDeviceMute() = 0;

返回說明

播放裝置是否被靜音。

設定變聲音效模式。

virtual int SetAudioEffectVoiceChangerMode(const AliEngineAudioEffectVoiceChangerMode &mode) = 0;

參數說明

返回說明

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

設定變調參數。

virtual int SetAudioEffectPitchValue(double value) = 0;

參數說明

返回說明

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

設定混響音效模式。

virtual int SetAudioEffectReverbMode(const AliEngineAudioEffectReverbMode& mode) = 0;

參數說明

返回說明

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

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

virtual int SetAudioEffectReverbParamType(const AliEngineAudioEffectReverbParamType& type,
                                                  float value) = 0;

參數說明

返回說明

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

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

virtual int SetAudioEffectBeautifyMode(const AliEngineAudioEffectBeautifyMode& mode) = 0;

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

調用時機

加入頻道前後均可調用。

參數說明

返回說明

• 0：設定成功

• 非 0：設定失敗。

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

virtual int SetAudioEffectEqualizationParam(const AliEngineAudioEffectEqualizationBandFrequency &bandIndex, float gain) = 0;

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

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

調用限制

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

參數說明

返回說明

0：設定成功

非 0：設定失敗。

增加外部音頻流。

virtual int AddExternalAudioStream(const AliEngineExternalAudioStreamConfig& config) = 0;

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

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

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

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

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

參數說明

返回說明

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

輸入外部音頻流資料。

virtual int PushExternalAudioStreamRawData(int streamId, AliEngineAudioRawData& data) = 0;

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

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

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

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

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

參數說明

返回說明

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

設定外部音頻流推流音量。

virtual int SetExternalAudioStreamPublishVolume(int streamId, int vol) = 0;

參數說明

返回說明

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

設定外部音頻流推流音量。

virtual int SetExternalAudioStreamPlayoutVolume(int streamId, int vol) = 0;

參數說明

返回說明

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

擷取外部音頻流推流音量。

virtual int GetExternalAudioStreamPublishVolume(int streamId) = 0;

參數說明

返回說明

[0, 100]: 推流音量，小於0表示失敗。

擷取外部音頻流播放音量。

virtual int GetExternalAudioStreamPlayoutVolume(int streamId) = 0;

參數說明

返回說明

[0, 100]: 播放音量，小於0表示失敗。

移除外部音頻流。

virtual int RemoveExternalAudioStream(int streamId) = 0;

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

調用時機

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

參數說明

傳回值

0成功，其他失敗。

擷取音頻檔案資訊。

virtual int GetAudioFileInfo(const char *filePath) = 0;

非同步介面，可通過AliEngineEventListener::OnAudioFileInfo擷取音頻檔案資訊。

參數說明

返回說明

• 0：成功。

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

開始伴奏混音。

virtual int StartAudioAccompany(const char *filePath, const AliEngineAudioAccompanyConfig& config) = 0;

非同步介面，可通過AliEngineEventListener::OnAudioAccompanyStateChanged監聽音頻伴奏播放器狀態。

參數說明

返回說明

• 0：成功。

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

停止伴奏混音。

virtual int StopAudioAccompany() = 0;

返回說明

• 0：成功。

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

設定伴奏音量。

 virtual int SetAudioAccompanyVolume(int volume) = 0;

參數說明

返回說明

• 0：成功。

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

設定伴奏推流音量。

virtual int SetAudioAccompanyPublishVolume(int volume) = 0;

參數說明

返回說明

• 0：成功。

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

擷取伴奏推流音量。

virtual int GetAudioAccompanyPublishVolume() = 0;

返回說明

伴奏推流的音量，範圍為 [0-100]。

設定伴奏本地播放音量。

virtual int SetAudioAccompanyPlayoutVolume(int volume) = 0;

參數說明

返回說明

• 0：成功。

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

擷取伴奏本地播放音量。

virtual int GetAudioAccompanyPlayoutVolume() = 0;

返回說明

伴奏本地播放的音量，範圍為 [0-100]。

暫停伴奏混音。

virtual int PauseAudioAccompany() = 0;

返回說明

• 0：成功。

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

重新開始伴奏混音。

virtual int ResumeAudioAccompany() = 0;

返回說明

• 0：成功。

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

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

virtual int GetAudioAccompanyDuration() = 0;

返回說明

音頻伴奏檔案的時間長度，單位為毫秒。

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

virtual int GetAudioAccompanyCurrentPosition() = 0;

返回說明

音頻伴奏檔案當前播放位置，單位為毫秒。

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

virtual int SetAudioAccompanyPosition(int pos) = 0;

返回說明

• 0：成功。

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

預先載入音效檔案。

virtual int PreloadAudioEffect(unsigned int soundId,
                                       const char *filePath) = 0;

參數說明

返回說明

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

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

virtual int UnloadAudioEffect(unsigned int soundId) = 0;

參數說明

返回說明

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

開始播放音效。

virtual int PlayAudioEffect(unsigned int soundId, const char *filePath, const AliEngineAudioEffectConfig& config) = 0;

參數說明

返回說明

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

停止播放音效。

virtual int StopAudioEffect(unsigned int soundId) = 0;

參數說明

返回說明

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

停止播放所有音效。

- (int)StopAllAudioEffects;

返回說明

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

暫停音效。

virtual int PauseAudioEffect(unsigned int soundId) = 0;

參數說明

返回說明

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

暫停所有音效。

virtual int PauseAllAudioEffects() = 0;

返回說明

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

重新開始播放音效。

virtual int ResumeAudioEffect(unsigned int soundId) = 0;

參數說明

返回說明

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

重新開始播放所有音效。

virtual int ResumeAllAudioEffects() = 0;

返回說明

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

設定音效推流音量。

virtual int SetAudioEffectPublishVolume(unsigned int soundId, int volume) = 0;

參數說明

返回說明

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

擷取推流音效音量。

virtual int GetAudioEffectPublishVolume(unsigned int soundId) = 0;

參數說明

返回說明

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

設定所有音效本地播放音量。

virtual int SetAllAudioEffectsPublishVolume(int volume) = 0;

參數說明

返回說明

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

設定音效本地播放音量。

virtual int SetAudioEffectPlayoutVolume(unsigned int soundId, int volume) = 0;

參數說明

返回說明

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

擷取音效本地播放音量。

virtual int GetAudioEffectPlayoutVolume(unsigned int soundId) = 0;

參數說明

返回說明

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

設定所有音效播放音量。

virtual int SetAllAudioEffectsPlayoutVolume(int volume) = 0;

參數說明

返回說明

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

設定所有音效推流音量。

virtual int SetAllAudioEffectsPublishVolume(int volume) = 0;

參數說明

返回說明

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

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

virtual int SetLocalViewConfig(AliEngineVideoCanvas renderConfig,
                                         AliEngineVideoTrack track) = 0;

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

調用時機

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

參數說明

返回說明

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

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

virtual int SetCameraCapturerConfiguration(const AliEngineCameraCapturerConfiguration& config) = 0;

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

調用時機

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

• StartPreview（開始預覽）

• JoinChannel（加入頻道）

參數說明

返回說明

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

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

virtual int EnableLocalVideo(bool enabled) = 0;

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

調用時機

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

相關回調

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

參數說明

返回說明

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

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

virtual int MuteLocalCamera(bool mute, AliEngineVideoTrack track) = 0;

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

參數說明

返回說明

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

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

virtual int SetRemoteViewConfig(AliEngineVideoCanvas renderConfig,
                                          const char *uid,
                                          AliEngineVideoTrack track) = 0;

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

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

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

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

調用時機

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

參數說明

返回說明

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

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

virtual bool IsCameraOn() = 0;

返回說明

YES表示網路攝影機已開啟，NO表示網路攝影機沒有開啟。

設定視頻編碼屬性。

virtual void SetVideoEncoderConfiguration(const AliEngineVideoEncoderConfiguration& config) = 0;

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

調用時機

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

調用限制

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

參數說明

設定視頻解碼屬性。該方法用於設定相機流視頻解碼屬性，包含軟硬解設定、是否啟用 B 幀等。

virtual void SetVideoDecoderConfiguration(const AliEngineVideoDecoderConfiguration& config) = 0;

調用時機

推薦在入會拉流前調用。

參數說明

開始本地預覽（會自動開啟網路攝影機）。

virtual int StartPreview(int width = 0, int height = 0) = 0;

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

調用時機

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

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

返回說明

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

停止本地預覽。

virtual int StopPreview() = 0;

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

調用時機

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

返回說明

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

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

virtual int setVideoMirrorMode(AliEngineVideoPipelineMirrorMode mirrorMode) = 0;

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

調用時機

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

調用限制

此介面與 SetLocalViewConfig&SetVideoEncoderConfiguration裡面的mirrorMode 參數重合，建議僅使用本方法。

參數說明

返回說明

• 0：設定成功。

• <0：設定失敗。

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

設定採集縮放時機，視頻資料是採集的時候立即縮放還是編碼時才進行縮放。

virtual void SetCapturePipelineScaleMode(const AliEngineCapturePipelineScaleMode mode) = 0;

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

調用時機

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

參數說明

擷取網路攝影機列表。

virtual AliEngineDeviceInfoList* GetCameraList() = 0;

傳回值

網路攝影機列表對象指標 AliEngineDeviceInfoList*。

擷取當前使用的網路攝影機名稱。

virtual String GetCurrentCameraName() = 0;

傳回值

當前使用的網路攝影機裝置名稱。

擷取當前使用的網路攝影機ID

virtual String GetCurrentCameraID() = 0;

傳回值

當前使用的網路攝影機ID。

選擇網路攝影機名稱。

virtual int SetCurrentCameraName(const char* cameraName) = 0;

參數說明

傳回值

0成功，其他失敗。

選擇網路攝影機ID。

virtual int SetCurrentCameraID(const char* cameraID) = 0;

參數說明

傳回值

0成功，其他失敗。

擷取支援的解析度。

virtual AliEngineVideoResolutionList * GetCurrentCameraSupportedResolutionList(int source) = 0 ;

參數說明

傳回值

!=NULL 擷取支援的解析度列表，NULL失敗。

啟用外部視頻輸入源。

virtual int SetExternalVideoSource(bool enable,
        AliEngineVideoTrack type,
        AliEngineRenderMode renderMode) = 0;

參數說明

輸入視頻資料。

virtual int PushExternalVideoFrame(const AliEngineVideoRawData &frame,
        AliEngineVideoTrack type) = 0;

參數說明

返回說明

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

開啟旁路直播。

virtual int StartPublishLiveStream(const String& streamURL, const AliEngineLiveTranscodingParam &transcoding) = 0;

參數說明

返回說明

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

更新旁路直播相關參數。

virtual int UpdatePublishLiveStream(const String& streamURL, const AliEngineLiveTranscodingParam &transcoding) = 0;

參數說明

返回說明

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

停止旁路直播。

virtual int StopPublishLiveStream(const String& streamURL) = 0;

參數說明

返回說明

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

擷取旁路直播狀態。

virtual AliEngineLiveTranscodingState GetPublishLiveStreamState(const String& streamURL) = 0;

參數說明

返回說明

返回旁路直播狀態。

開始網路品質探測。本網的一些問題可能會導致音視訊通話失敗，通過調用此介面可以擷取上下行網路的頻寬、丟包率、抖動、鏈路 RTT 等資訊，協助定位和解決相關網路問題。

 virtual int StartLastmileDetect(bool uplink, bool downlink, int uplinkBandWidth, int downlinkBandWidth) = 0;

調用時機

該介面需要在JoinChannel前調用，探測結果會通過回調給出。一次網路探測可能耗時較長，可按需調用StopLastmileDetect終止網路探測。

調用限制

SDK 在同一時刻只能執行一個網路探測，在上一次探測結束前重複調用會失效。

相關回調

成功調用該方法後，會觸發兩個回調：

• OnLastmileDetectResultWithQuality：約3s後會觸發該回調，粗略的判斷網路等級。

• OnLastmileDetectResultWithBandWidth： 約30s後會觸發該回調，給出詳細的探測結果。

參數說明

返回說明

• 0: 調用本方法成功。

• <0: 調用本方法失敗，例如已經入會等。

停止網路品質探測。調用此介面可以停止網路品質探測。

virtual int StopLastmileDetect() = 0;

調用時機

需要在建立引擎後、入會前調用。

返回說明

• 0: 調用此介面成功。

• <0：調用此介面失敗。

發送媒體擴充資訊，內部使用SEI實現。

virtual int SendMediaExtensionMsg(const int8_t * message, uint32_t length, int32_t repeatCount, uint32_t delay, bool isKeyFrame) = 0;

SDK提供了發送和接收媒體擴充資訊的功能，接收端參考 AliEngineEventListener::OnMediaExtensionMsgReceived。使用媒體擴充資訊時需要複用音視頻資料通道，因此必須控制自訂訊息的發送頻率和訊息資料長度，使用限制如下：

• 每秒最多發送profile設定的fps條訊息。

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

• sendMediaExtensionMsg函數中repeatCount參數為自訂訊息冗餘度，若大於1，則會發送多次，防止網路丟包導致的訊息丟失，此時房間裡的其他人也會收到多次相同的訊息，需要去重。

• 發送的自訂訊息，在旁路直播時，房間裡的訂閱者也一樣會收到，設定為-1為永久發送data資料，除非重新設定sendMediaExtensionMsg。

• 同一時刻只有一個 sendMediaExtensionMsg 會被發送，意味著調用sendMediaExtensionMsg會覆蓋上一次調用的sendMediaExtensionMsg，如果上次的調用沒有發送或者沒有發送完成。

參數說明

返回說明

• 0：成功。

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

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

發送媒體擴充資訊，內部使用SEI實現。

virtual int SendMediaExtensionMsgEx(const int8_t * message, uint32_t length, int32_t repeatCount, uint32_t delay, bool isKeyFrame, int32_t payloadType) = 0;

SDK提供了發送和接收媒體擴充資訊的功能，接收端參考 AliEngineEventListener::OnMediaExtensionMsgReceived。使用媒體擴充資訊時需要複用音視頻資料通道，因此必須控制自訂訊息的發送頻率和訊息資料長度，使用限制如下：

• 每秒最多發送profile設定的fps條訊息；

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

• sendMediaExtensionMsg函數中repeatCount參數為自訂訊息冗餘度，若大於1，則會發送多次，防止網路丟包導致的訊息丟失，此時房間裡的其他人也會收到多次相同的訊息，需要去重；

• 發送的自訂訊息，在旁路直播時，房間裡的訂閱者也一樣會收到，設定為-1為永久發送data資料，除非重新設定sendMediaExtensionMsg；

• 同一時刻只有一個 sendMediaExtensionMsg 會被發送，意味著調用sendMediaExtensionMsg會覆蓋上一次調用的sendMediaExtensionMsg，如果上次的調用沒有發送或者沒有發送完成；

參數說明

返回說明

• 0：成功。

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

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

網路連接狀態改變的回調。

virtual void OnConnectionStatusChange(int status, int reason) {};

參數說明

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

virtual void OnLocalDeviceException(AliEngineLocalDeviceType deviceType, AliEngineLocalDeviceExceptionType exceptionType, const char* msg){};

參數說明

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

virtual void OnAuthInfoWillExpire() {};

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

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

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

觸發時機

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

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

virtual void OnAuthInfoExpired() {};

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

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

觸發時機

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

加入頻道結果回調（該回調等同於調用JoinChannel介面的block操作，即處理加入頻道之後的事件，選擇其一即可）。

virtual void OnJoinChannelResult(int result, const char *channel, const char *userId, int elapsed) {}

觸發條件

當應用調用 JoinChannel方法時，該回調錶示成功/失敗加入頻道，並且返回頻道加入的相關資訊以及加入頻道耗時。

參數說明

離開頻道結果回調。調用LeaveChannel介面後返回，如果調用後直接調用Destroy，將不會收到此回調。

virtual void OnLeaveChannelResult(int result, AliEngineStats stats) {}

觸發條件

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

參數說明

遠端使用者下線時的回調。

virtual void OnRemoteUserOffLineNotify(const char *uid, AliEngineUserOfflineReason reason) {}

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

觸發條件

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

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

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

參數說明

遠端使用者上線時的回調。

virtual void OnRemoteUserOnLineNotify(const char *uid, int elapsed) {}

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

觸發條件

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

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

參數說明

遠端使用者的流發生變化時回調。

virtual void OnRemoteTrackAvailableNotify(const char *uid,
                                                  AliEngineAudioTrack audioTrack,
                                                  AliEngineVideoTrack videoTrack) {}

當前回調在遠端使用者推流狀態發生變化時觸發，通過這個回調，開發人員可以即時瞭解遠端使用者是否推送音頻和視頻流，並據此在介面上顯示或隱藏遠端使用者的音視頻資訊。

觸發條件

該回調在以下情境會被觸發：

• 當遠端使用者從未推流變更為推流（包括音頻和視頻）

• 當遠端使用者從已推流變更為未推流（包括音頻和視頻）

• 互動模式下，遠端使用者調用 SetClientRole 從觀眾切換為主播角色，同時設定了推流時，會觸發該回調

以視頻為例，假設遠端使用者佈建不推流，那麼不會觸發此回調：

• 遠端使用者開始推送相機流（推流狀態：不推視頻流->僅推相機流)，則本端回調返回AliEngineVideoTrackCamera表示遠端使用者相機流可用。

• 遠端使用者又推送了螢幕畫面分享流（推流狀態：僅推相機流->推送相機流和螢幕畫面分享流），則本端回調AliEngineVideoTrackBoth表示遠端使用者相機流和螢幕畫面分享流均可用。

• 遠端使用者停止推送相機流僅保留螢幕畫面分享流（推流狀態：推送相機流和螢幕畫面分享流->僅推送螢幕畫面分享流），則本端回調AliEngineVideoTrackScreen表示當前僅有螢幕畫面分享流可用。

• 遠端使用者又停止了螢幕畫面分享流的推送（推流狀態：僅推送螢幕畫面分享流->不推視頻流），則本端回調AliEngineVideoTrackNo表示當前無視頻流可用。

參數說明

被伺服器踢出或者頻道關閉時回調。

virtual void OnBye(int code) {}

當使用者因某種原因被斷開或者會議結束，此回調便會被觸發，開發人員可以根據回調參數 code 來得知被斷開的原因並作出相應處理。

觸發條件

• 目前使用者被伺服器踢出。

• 會議結束（伺服器主動移除頻道）。

• 被動離開，需要用戶端嘗試恢複會話或重新串連。

參數說明

音頻推流變更回調。

virtual void OnAudioPublishStateChanged(AliEnginePublishState oldState, AliEnginePublishState newState, int elapseSinceLastState, const char *channel) {};

該回調用於監聽本機使用者音頻流推流狀態變化。

觸發條件

當使用者的音頻推流狀態發生變化時，例如：

• 停止推流。

• 調用SetClientRole切換為觀眾。

參數說明

音頻訂閱情況變更回調。

virtual void OnAudioSubscribeStateChanged(const char *uid,
                                                  AliEngineSubscribeState oldState, 
                                                  AliEngineSubscribeState newState,
                                                  int elapseSinceLastState,
                                                  const char *channel) {};

該回調用於通知本機使用者遠端使用者音頻流訂閱狀態發生變化。通過該回調，可以獲知某個遠端使用者相機流的訂閱狀態變化，以及從上一狀態到目前狀態的時間間隔。

參數說明

使用者muteAudio通知。

virtual void OnUserAudioMuted(const char* uid, bool isMute) {}

參數說明

使用者audio被中斷通知（一般使用者打電話等音頻被搶佔情境）。

virtual void OnUserAudioInterruptedBegin(const char* uid) {}

參數說明

使用者audio中斷結束通知（對應OnUserAudioInterruptedBegin）。

virtual void OnUserAudioInterruptedEnded(const char* uid) {}

參數說明

視頻推流變更回調。

virtual void OnVideoPublishStateChanged(AliEnginePublishState oldState, AliEnginePublishState newState, int elapseSinceLastState, const char *channel) {};

該回調用於監聽本機使用者視頻推流狀態的變化。

參數說明

相機流訂閱情況變更回調。

virtual void OnVideoSubscribeStateChanged(const char *uid, 
                                                  AliEngineSubscribeState oldState, 
                                                  AliEngineSubscribeState newState,
                                                  int elapseSinceLastState,
                                                  const char *channel) {};

該回調用於通知本機使用者遠端使用者相機流訂閱狀態發生變化。通過該回調，可以獲知某個遠端使用者相機流的訂閱狀態變化，以及從上一狀態到目前狀態的時間間隔。

相關回調

視頻流主要包含相機流和螢幕畫面分享流，本介面為相機流的訂閱狀態變化，螢幕畫面分享流的相關回道介面為OnScreenShareSubscribeStateChanged。

參數說明