ApsaraVideo Live：AliRtcEngine介面

建立AliRtcEngine執行個體（單例模式）。

+ (instancetype _Nonnull )sharedInstance:(id<AliRtcEngineDelegate>_Nullable)delegate extras:(NSString *_Nullable)extras;

調用時機

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

調用限制

• 該方法為同步調用，只能在主線程中調用。

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

相關回調

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

異常發生原因	回調及參數	解決方案	說明
鑒權失敗	onJoinChannelResult回調中的result返回AliRtcErrJoinBadToken	發生錯誤時App需要檢查Token是否正確。	在使用者主動調用API時，若鑒權失敗，系統將在調用API的回調中返回鑒權失敗的錯誤資訊。
網路連接異常	onConnectionStatusChange回調返回AliRtcConnectionStatusFailed。	發生該異常時APP需要重新入會。	SDK具備一定時間斷網自動回復能力，但若斷線時間超出預設閾值，會觸發逾時並中斷連線。此時，App應檢查網路狀態並指導使用者重新加入會議。
本地裝置異常	onLocalDeviceException	發生該異常時App需要檢測許可權、裝置硬體是否正常。	RTC服務支援裝置檢測和異常診斷的能力；當本地裝置發生異常時，RTC服務會通過回調的方式通知客戶本地裝置異常，此時，若SDK無法自行解決問題，則App需要介入以查看裝置是否正常。
被踢下線	onBye	AliRtcOnByeUserReplaced：當發生該異常時排查使用者userid是否相同。 AliRtcOnByeBeKickedOut：當發生該異常時，表示被業務踢下線，需要重新入會。 AliRtcOnByeChannelTerminated：當發生該異常時，表示房間被銷毀，需要重新入會。	RTC服務提供了管理員可以主動移除參與者的功能。
鑒權將要到期	onWillAuthInfoExpire	發生該異常時App需要重新擷取最新的鑒權資訊後，再調用refreshAuthInfo重新整理鑒權資訊。	鑒權到期錯誤在兩種情況下出現：使用者調用API或程式執行期間。因此，錯誤反饋將通過API回調或通過獨立的錯誤回調通知。
鑒權到期	onAuthInfoExpired	發生該異常時App需要重新入會。	鑒權到期錯誤在兩種情況下出現：使用者調用API或程式執行期間。因此，錯誤反饋將通過API回調或通過獨立的錯誤回調通知。

參數說明

名稱	類型	描述
delegate	id<AliRtcEngineDelegate>_Nullable	監聽回調的代理。
extras	NSString *_Nullable	用於接收來自客戶灰階下發的參數，通過JSON配置SDK的特別功能，可以是Null 字元串。

銷毀AliRtcEngine 執行個體。

+ (void)destroy;

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

該方法和destroy[2/2]均能銷毀引擎執行個體，區別在於 destroy[2/2] 允許傳入銷毀完成的監測器對象。

調用時機

當音視頻通訊結束後（即不再需要使用 AliRtcEngine 功能時），建議調用此方法釋放執行個體，減少不必要的資源佔用。

調用限制

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

銷毀AliRtcEngine執行個體。

+ (void)destroy:(id<AliRtcEngineDestroyDelegate>_Nullable)delegate;

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

調用時機

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

調用限制

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

參數說明

名稱	類型	描述
delegate	AliRtcEngineDestroyDelegate	釋放後回調對象

設定是否相容H5。

+ (void)setH5CompatibleMode:(BOOL)comp;

參數說明

名稱	類型	描述
comp	BOOL	YES表示相容H5，NO表示不相容H5。預設不相容H5。

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

+ (BOOL)getH5CompatibleMode;

返回說明

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

擷取SDK版本號碼。

+ (NSString *_Nonnull)getSdkVersion;

傳回值

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

說明

該函數為靜態方法，可以任意時候擷取版本號碼。

設定頻道模式。

- (int)setChannelProfile:(AliRtcChannelProfile)profile;

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

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

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

調用時機

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

參數說明

名稱	類型	描述
profile	AliRtcChannelProfile	頻道類型，RTC情境都建議設定為AliRtcChannelProfileInteractiveLive，即互動直播模式。

返回說明

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

設定音頻Profile。

- (int)setAudioProfile:(AliRtcAudioProfile)audio_profile audio_scene:(AliRtcAudioScenario)audio_scene;

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

調用時機

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

參數說明

名稱	類型	描述
audio_profile	AliRtcAudioProfile	音頻採集或編碼模式參數，建議使用高音質模式（AliRtcEngineHighQualityMode）。 說明 如果需要與 Web 互連，需要設定採樣率為 48k。 AliRtcEngineLowQualityMode：音頻低音質模式，預設8000Hz採樣率，單聲道，最大編碼碼率12kbps。 AliRtcEngineBasicQualityMode：標準音質模式，預設16000Hz採樣率，單聲道，最大編碼碼率24kbps。 AliRtcEngineHighQualityMode：預設48000Hz採樣率，單聲道，最大編碼碼率64kbps。 AliRtcEngineStereoHighQualityMode：立體聲高音質模式，預設48000Hz採樣率，雙聲道，最大編碼碼率80kbps。 AliRtcEngineSuperHighQualityMode：超高音質模式，預設48000Hz採樣率，單聲道，最大編碼碼率96kbps。 AliRtcEngineStereoSuperHighQualityMode：立體聲超高音質模式，預設48000Hz採樣率，雙聲道，最大編碼碼率128kbps。
audio_scene	AliRtcAudioScenario	音頻情境模式參數，主要包含： AliRtcSceneMusicMode（建議設定）：音樂情境，使用軟體 3A，從手機採集（音質更高）。 AliRtcSceneDefaultMode：使用硬體 3A，可以從藍牙裝置採集。 說明 ARTC SDK v6.21及之後的版本請不要設定為聊天室情境（AliRtcSceneChatroomMode）。

返回說明

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

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

- (BOOL)isAudioOnly;

返回說明

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

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

- (int)setAudioOnlyMode:(BOOL)audioOnly;

參數說明

名稱	類型	描述
audioOnly	BOOL	YES表示只有音頻推流和拉流。 NO表示音視頻都支援，預設值為NO。

返回說明

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

加入頻道（單參入會）。

- (int)joinChannel:(NSString *_Nonnull)token channelId:(NSString *_Nullable)channelId userId:(NSString *_Nullable)userId name:(NSString *_Nullable)userName onResultWithUserId:(void(^_Nullable)(NSInteger errCode, NSString * _Nonnull channel, NSString * _Nonnull userId, NSInteger elapsed))onResult;

該介面用於加入頻道。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 不能互連。

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

相關回調

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

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

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

參數說明

參數	類型	描述
token	String	單參數入會的鑒權資訊。
channelId	String	入會頻道，必須和產生Token的值一樣。
userId	String	入會的userid，必須和產生token的值一樣。
userName	String	使用者的顯示名稱（不是使用者ID）。
onResultWithUserId	void(^_Nullable)(NSInteger errCode, NSString * _Nonnull channel, NSString * _Nonnull userId, NSInteger elapsed)	當此介面執行結束後調用此回調。

返回說明

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

加入頻道（多參入會）。

- (int)joinChannel:(AliRtcAuthInfo *_Nonnull)authInfo name:(NSString *_Nullable)userName onResultWithUserId:(void(^_Nullable)(NSInteger errCode, NSString * _Nonnull channel, NSString * _Nonnull userId, NSInteger elapsed))onResult;

該介面用於加入頻道。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回調。

參數說明

名稱	類型	描述
authInfo	AliRtcAuthInfo	鑒權資訊。
userName	String	使用者的顯示名稱（不是使用者ID）。
onResultWithUserId	void(^_Nullable)(NSInteger errCode, NSString * _Nonnull channel, NSString * _Nonnull userId, NSInteger elapsed)	當此介面執行結束後調用此回調。

加入頻道。

- (int)joinChannel:(NSString *_Nonnull)token channelParam:(AliRtcChannelParam *_Nonnull)channelParam onResultWithUserId:(void(^_Nullable)(NSInteger errCode, NSString * _Nonnull channel, NSString * _Nonnull userId, NSInteger elapsed))onResult;

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

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

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

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

調用限制

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

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

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

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

相關回調

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

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

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

參數說明

名稱	類型	描述
token	NSString*	認證資訊，從App Server擷取。
channelParam	AliRtcChannelParam	入會參數
onResultWithUserId	void(^_Nullable)(NSInteger errCode,NSString * _Nonnull channel,NSInteger elapsed)	當此介面執行結束後調用此回調。

離開頻道。

- (int)leaveChannel;

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

調用時機

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

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

相關回調

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

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

返回說明

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

檢查當前是否在頻道中。

- (BOOL)isInCall;

返回說明

YES表示在頻道中，NO表示不在頻道中。

設定使用者角色。

- (int)setClientRole:(AliRtcClientRole)role;

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

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

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

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

調用時機

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

調用限制

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

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

參數說明

名稱	類型	描述
role	AliRtcClientRole	使用者角色類型，預設值為AliRtcClientRolelive（觀眾角色），非通訊模式下角色類型才有效。

返回說明

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

擷取使用者角色（僅iOS）。

- (AliRtcClientRole)getCurrentClientRole;

返回說明

返回目前使用者角色。

重新整理鑒權資訊。

- (int)refreshAuthInfo:(AliRtcAuthInfo *_Nonnull)authInfo;

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

調用時機

在以下情況下：

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

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

參數說明

名稱	類型	描述
authInfo	AliRtcAuthInfo *_Nonnull	鑒權資訊。

返回說明

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

重新整理鑒權資訊。

- (int)refreshAuthInfoWithToken:(NSString *_Nonnull)token;

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

調用時機

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

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

參數說明

名稱	類型	描述
token	NSString *_Nonnull	單參數入會的鑒權資訊。

返回說明

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

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

- (int)publishLocalAudioStream:(BOOL)enable;

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

調用時機

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

相關回調

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

參數說明

名稱	類型	描述
enable	boolean	YES表示發送本地音頻流。 NO表示停止推流，預設YES。

返回說明

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

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

- (BOOL)isLocalAudioStreamPublished;

返回說明

YES表示允許推送，NO表示不允許推送。

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

- (int)setDefaultSubscribeAllRemoteAudioStreams:(BOOL)sub;

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

調用時機

加入頻道前後均可調用。

• 加入頻道前：

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

• 加入頻道後：

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

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

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

參數說明

名稱	類型	描述
sub	BOOL	YES表示接收使用者的音頻流。 NO表示停止接收使用者的音頻流，預設值為YES。

返回說明

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

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

- (int)subscribeRemoteAudioStream:(NSString *_Nonnull)uid sub:(BOOL)sub;

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

參數說明

名稱	類型	描述
uid	NSString *_Nonnull	遠端使用者ID。
sub	BOOL	YES表示接收指定使用者的音頻流。 NO表示停止接收指定使用者的音頻流，預設值為YES。

返回說明

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

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

- (int)subscribeAllRemoteAudioStreams:(BOOL)sub;

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

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

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

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

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

參數說明

名稱	類型	描述
sub	BOOL	YES表示接收所有使用者的音頻流。 NO表示停止接收所有使用者的音頻流，預設值為YES。

返回說明

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

設定是否允許發布相機流。

- (int)publishLocalVideoStream:(BOOL)enable;

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

調用時機

加入頻道前後均可調用。

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

相關回調

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

參數說明

名稱	類型	描述
enable	boolean	YES表示發送視頻。 NO表示停止發送，預設YES。

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

- (BOOL)isLocalVideoStreamPublished;

返回說明

YES表示發布相機流，NO表示不發布相機流。

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

- (int)setDefaultSubscribeAllRemoteVideoStreams:(BOOL)sub;

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

調用時機

入會前後均可調用。

• 入會前：

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

• 入會後：

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

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

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

參數說明

名稱	類型	描述
sub	boolean	YES表示接收使用者的視頻流。 NO表示不接收使用者的視頻流，預設值為YES。

返回說明

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

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

- (int)subscribeRemoteVideoStream:(NSString *_Nonnull)uid track:(AliRtcVideoTrack)track sub:(BOOL)sub;

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

調用時機

入會前後均可調用。

參數說明

名稱	類型	描述
uid	NSString *	使用者ID，從App server分配的唯一標示符。
track	AliRtcVideoTrack	視頻流類型。
sub	BOOL	是否訂閱。

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

- (int)subscribeAllRemoteVideoStreams:(BOOL)sub;

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

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

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

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

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

參數說明

名稱	類型	描述
sub	BOOL	YES表示接收所有使用者的視頻流。 NO表示停止允許接收所有使用者的視頻流，預設值為YES。

返回說明

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

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

- (int)subscribeRemoteMediaStream:(NSString *_Nonnull)uid videoTrack:(AliRtcVideoTrack)videoTrack subVideo:(BOOL)subVideo subAudio:(BOOL)subAudio;

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

相關介面

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

注意：在該介面中 AliRtcVideoTrack 的AliRtcVideoTrackNo是無效的，設定不會有任何效果。

參數說明

參數	類型	描述
uid	String	遠端使用者ID。
videoTrack	AliRtcVideoTrack	視頻流類型。
subVideo	boolean	停止或恢複特定遠端使用者的視頻流拉取，取值： true（預設值）：恢複。 false：停止。
subAudio	boolean	停止或恢複特定遠端使用者的音頻流拉取，取值： true（預設值）：恢複。 false：停止。

返回說明

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

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

- (int)subscribeRemoteMediaStream:(NSString *_Nonnull)uid videoTrack:(AliRtcVideoTrack)videoTrack audioTrack:(AliRtcAudioTrack)audioTrack;

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

相關介面

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

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

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

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

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

參數說明

參數	類型	描述
uid	NSString *	遠端使用者ID。
videoTrack	AliRtcVideoTrack	視頻流類型。
audioTrack	AliRtcAudioTrack	音頻流類型。

返回說明

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

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

- (int)subscribeRemoteDestChannelStream:(NSString *_Nonnull)channelId uid:(NSString *_Nonnull)uid track:(AliRtcVideoTrack)track subAudio:(BOOL)subAudio sub:(BOOL)sub;

參數說明

參數	類型	描述
channelId	String	遠端頻道ID。
uid	String	遠端使用者ID。
track	AliRtcVideoTrack	需要訂閱的視頻流。
sub_audio	boolean	停止或恢複特定遠端使用者的音頻流拉取，取值： true（預設值）：恢複。 false：停止。
sub	boolean	停止或恢複跨頻道訂閱指定使用者的流。

返回說明

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

訂閱目標頻道，所有使用者的流

- (int)subscribeRemoteDestChannelAllStream:(NSString *_Nonnull)channelId track:(AliRtcVideoTrack)track subAudio:(BOOL)subAudio sub:(BOOL)sub;

參數說明

名稱	類型	描述
channelId	NSString *	目標頻道。
videotrack	AliRtcVideoTrack	視頻流類型。
audioTrack	AliRtcAudioTrack	音頻流類型。
subAudio	BOOL	是否訂閱音頻流。
sub	BOOL	是否訂閱遠端頻道使用者的視頻流。

傳回值

0 成功，其他失敗。

設定遠端音訊音量。

- (int)setRemoteAudioVolume:(NSString *_Nonnull)uid volume:(NSInteger)volume;

參數說明

名稱	類型	描述
uid	NSString *	使用者ID，從App server分配的唯一標示符。
volume	NSInteger	播放音量，取值範圍[0,100] 0：靜音；100：原始音量。

傳回值

0成功，非0失敗。

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

- (int)muteLocalMic:(BOOL)mute mode:(AliRtcMuteLocalAudioMode)mode;

調用時機

加入房間前後均可調用。

相關回調

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

參數說明

名稱	類型	描述
mute	BOOL	YES表示本地音頻發送空幀。 NO表示恢複正常，預設值為NO。
mode	AliRtcMuteLocalAudioMode	靜音，預設靜音全部。 AliRtcMuteAudioModeDefault：靜音全部，包括麥克風和外部輸入音頻。 AliRtcMuteAllAudioMode：靜音全部，包括麥克風和外部輸入音頻。 AliRtcMuteOnlyMicAudioMode：只靜音麥克風。

返回說明

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

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

- (int)muteRemoteAudioPlaying:(NSString *_Nonnull)uid mute:(BOOL)mute;- (int)muteRemoteAudioPlaying:(NSString *_Nonnull)uid mute:(BOOL)mute;- (int)muteRemoteAudioPlaying:(NSString *_Nonnull)uid mute:(BOOL)mute;

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

調用時機

加入頻道前後均可調用。

參數說明

名稱	類型	描述
uid	NSString *_Nonnull	使用者ID。
mute	BOOL	YES表示停止播放。 NO表示恢複播放，預設值為NO。

返回說明

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

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

- (int)muteAllRemoteAudioPlaying:(BOOL)mute;

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

調用時機

加入頻道前後均可設定。

參數說明

名稱	類型	描述
mute	BOOL	YES表示停止播放。 NO表示恢複播放，預設值為NO。

返回說明

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

開啟音頻採集。

- (void)startAudioCapture;

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

調用時機

入會前後均可調用。

相關介面

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

相關回調

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

返回說明

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

開啟音頻採集。

- (void)startAudioCapture:(BOOL)keepAlive;

靜音後關閉麥克風採集。

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

調用時機

入會前後均可調用。

相關介面

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

相關回調

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

參數說明

參數	類型	描述
keepAlive	boolean	離會後採集裝置的狀態，取值： true：離會後採集裝置保持開啟狀態。 false（預設值）：離會後採集裝置關閉。

返回說明

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

關閉音頻採集。

- (void)stopAudioCapture;

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

相關回調

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

返回說明

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

設定音訊輸出為耳機或擴音器（僅iOS）。

- (int)enableSpeakerphone:(BOOL)enable;

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

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

調用時機

加入頻道前後均可調用。

相關介面

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

參數說明

名稱	類型	描述
enable	BOOL	YES表示擴音器模式。 NO表示耳機模式，預設為YES。

返回說明

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

擷取當前音訊輸出為耳機或擴音器（僅iOS）。

- (BOOL)isEnableSpeakerphone;

返回說明

YES表示擴音器模式，NO表示耳機模式。

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

- (int)enableAudioVolumeIndication:(NSInteger)interval smooth:(NSInteger)smooth reportVad:(NSInteger)reportVad;

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

調用時機

加入頻道前後均可調用。

相關回調

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

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

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

參數說明

名稱	類型	描述
interval	NSInteger	時間間隔，單位為毫秒，最小值不得小於10ms，建議設定300~500ms，小於等於0表示不啟用音量提示和說話人提示功能。
smooth	NSInteger	平滑係數，取值範圍：[0,9]，數值越大平滑程度越高，反之越低，即時性越好，建議設定3。
reportVad	NSInteger	說話人檢測開關，取值： 1：開啟，通過onAudioVolumeCallback介面回調每一個說話人的狀態。 0：關閉。

返回說明

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

啟用耳返。

- (int)enableEarBack:(BOOL)enable;

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

調用時機

加入頻道前後均可調用。

參數說明

名稱	類型	描述
enable	BOOL	YES表示啟用耳返。 NO表示關閉耳返，預設值為NO。

返回說明

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

設定耳返音量。

- (int)setEarBackVolume:(NSInteger)volume;

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

調用時機

加入頻道前後均可調用。

參數說明

名稱	類型	描述
volume	NSInteger	取值範圍：[0,100]，預設100。

返回說明

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

開啟音頻播放。

- (void)startAudioPlayer;

停止音頻播放。

- (void)stopAudioPlayer;

設定播放音量。

- (int)setPlayoutVolume:(NSInteger)volume;

參數說明

名稱	類型	描述
volume	音量	範圍：[0..400] 其中 [0..100]是原始音量範圍[100..400]是音量放大

傳回值

0成功，其他失敗。

設定錄音音量

- (int)setRecordingVolume:(NSInteger)volume;

參數說明

名稱	類型	描述
volume	NSInteger	範圍：[0..400] [0..100]是原始音量[100..400]是音量放大

傳回值

0成功，其他失敗。

播放音頻檔案。

- (int)playAudioFileTest:(NSString *_Nonnull)filePath;

參數說明

參數	類型	描述
filePath	NSString *_Nonnull	播放檔案路徑

傳回值

0成功，其他失敗。

停止播放音頻檔案。

- (int)stopAudioFileTest;

傳回值

0成功，其他失敗。

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

- (void)startAudioCaptureTest;

停止通話前音頻採集裝置檢測。

- (void)stopAudioCaptureTest;

設定預設音訊輸出是否從擴音器出聲，預設從擴音器出聲。

- (int)setDefaultAudioRouteToSpeakerphone:(BOOL)defaultToSpeakerphone;

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

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

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

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

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

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

相關介面

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

調用時機

入會前後均可調用。

參數說明

名稱	類型	描述
defaultToSpeakerphone	BOOL	是否音頻路由到擴音器，YES擴音器，NO耳機。

傳回值

0 成功，其他失敗。

設定變聲音效模式。

- (int)setAudioEffectVoiceChangerMode:(AliRtcAudioEffectVoiceChangerMode)mode;

參數說明

名稱	類型	描述
mode	AliRtcAudioEffectVoiceChangerMode	模式值，預設值為AliRtcSdk_AudioEffect_Voice_Changer_OFF。

返回說明

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

設定變調參數。

- (int)setAudioEffectPitchValue:(double)value;

參數說明

名稱	類型	描述
value	double	取值範圍：[0.5,2.0]，預設為1.0，表示音調不變。

返回說明

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

設定混響音效模式。

- (int)setAudioEffectReverbMode:(AliRtcAudioEffectReverbMode)mode;

參數說明

名稱	類型	描述
mode	AliRtcAudioEffectReverbMode	音效模式，預設值為AliRtcAudioEffectReverb_Off。

返回說明

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

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

- (int)setAudioEffectReverbParamType:(AliRtcAudioEffectReverbParamType)type value:(float)value;

參數說明

名稱	類型	描述
type	AliRtcAudioEffectReverbParamType	音效混響模式。
value	float	具體參數值。

返回說明

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

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

- (int)setAudioEffectBeautifyMode:(AliRtcAudioEffectBeautifyMode)mode;

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

調用時機

加入頻道前後均可調用。

參數說明

參數	類型	描述
mode	AliRtcAudioEffectBeatifyMode	美聲音效模式，詳見枚舉定義。

返回說明

• 0：設定成功

• 非 0：設定失敗。

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

- (int)setAudioEffectEqualizationParam:(AliRtcAudioEffectEqualizationBandFrequency)bandIndex gain:(float)gain;

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

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

調用限制

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

參數說明

參數	類型	描述
bandIndex	AliRtcAudioEffectEqualizationBandFrequency	要調節的頻段索引，對應中心頻率（31Hz ~ 16kHz）中的某一段.
gain	float	增益值，單位為 dB，取值 [-15, 15] 。

返回說明

0：設定成功

非 0：設定失敗。

增加外部音頻流。

- (int)addExternalAudioStream:(AliRtcExternalAudioStreamConfig *_Nonnull)config;

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

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

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

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

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

參數說明

名稱	類型	描述
config	AliRtcExternalAudioStreamConfig	外部音頻流配置。

返回說明

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

輸入外部音頻流資料。

- (int)pushExternalAudioStream:(int)streamId rawData:(AliRtcAudioFrame * _Nonnull)audioFrame;

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

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

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

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

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

參數說明

名稱	類型	描述
streamId	int	外部音頻流Id。
audioFrame	AliRtcAudioFrame	音頻資料。

返回說明

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

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

- (int)setExternalAudioStream:(int)streamId
                publishVolume:(int)publishVolume;

參數說明

名稱	類型	描述
streamId	int	外部音頻流Id。
publishVolume	int	推流音量。

返回說明

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

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

- (int)getExternalAudioStreamPublishVolume:(int)streamId;

參數說明

名稱	類型	描述
streamId	int	外部音頻流Id。

返回說明

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

設定外部音頻流播放音量。

- (int)setExternalAudioStream:(int)streamId
                playoutVolume:(int)playoutVolume;

參數說明

名稱	類型	描述
streamId	int	外部音頻流Id。
playoutVolume	int	播放音量。

返回說明

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

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

- (int)getExternalAudioStreamPlayoutVolume:(int)streamId;

參數說明

名稱	類型	描述
streamId	int	外部音頻流Id。

返回說明

[0, 100]: 播放音量,< 0: 失敗。

刪除外部音頻流。

- (int)removeExternalAudioStream:(int)streamId;

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

調用時機

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

參數說明

名稱	類型	描述
streamId	int	外部音頻流Id。

傳回值

0成功，其他失敗。

擷取音頻檔案資訊

- (int)getAudioFileInfo:(NSString *_Nonnull)filePath;

參數說明

名稱	類型	描述
filePath	NSString *	檔案路徑。

開始伴奏混音。

- (int)startAudioAccompanyWithFile:(NSString *_Nonnull)filePath config:(AliRtcAudioAccompanyConfig *_Nonnull)config;

參數說明

名稱	類型	描述
filePath	NSString *	檔案路徑。
config	AliRtcAudioAccompanyConfig *	伴奏的配置。

傳回值

0成功，其他失敗

停止伴奏混音。

- (int)stopAudioAccompany;

傳回值

0成功，其他失敗。

設定伴奏音量

- (int)setAudioAccompanyVolume:(NSInteger)volume;

參數說明

名稱	類型	描述
volume	NSInteger	volume 伴奏音量，取值範圍[0,100]。

傳回值

0成功，其他失敗；

設定伴奏推流音量。

- (int)setAudioAccompanyPublishVolume:(NSInteger)volume;

參數說明

名稱	類型	描述
volume	NSInteger	volume 伴奏音量，取值範圍[0,100]。

傳回值

0成功，其他失敗。

擷取伴奏推流音量。

- (int)getAudioAccompanyPublishVolume;

傳回值

[0, 100]成功，其他失敗。

設定伴奏本地播放音量。

- (int)setAudioAccompanyPlayoutVolume:(NSInteger)volume;

參數說明

名稱	類型	描述
volume	NSInteger	volume 伴奏音量，取值範圍[0,100]。

傳回值

0成功，其他失敗。

擷取伴奏本地播放音量

- (int)getAudioAccompanyPlayoutVolume;

傳回值

[0, 100]: 成功，其他失敗。

暫停伴奏混音。

- (int)pauseAudioAccompany;

傳回值

0成功，其他失敗。

繼續伴奏混音。

- (int)resumeAudioAccompany;

傳回值

0成功，其他失敗。

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

- (int)getAudioAccompanyDuration;

傳回值

>=0擷取伴奏檔案時間長度, 單位為毫秒；<0失敗。

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

- (int)getAudioAccompanyCurrentPosition;

傳回值

>=0: 伴奏檔案播放進度；<0失敗。

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

- (int)setAudioAccompanyPosition:(int)pos;

參數說明

名稱	類型	描述
pos	int	pos 進度條位置，單位為毫秒。

傳回值

0成功，其他失敗。

預先載入音效檔案。

- (int)preloadAudioEffectWithSoundId:(NSInteger)soundId filePath:(NSString *_Nonnull)filePath;

參數說明

名稱	類型	描述
soundId	NSInteger	使用者給該音效檔案分配的ID。
filePath	NSString *_Nonnull	音效檔案路徑。

返回說明

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

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

- (int)unloadAudioEffectWithSoundId:(NSInteger)soundId;

參數說明

名稱	類型	描述
soundId	NSInteger	使用者給該音效檔案分配的ID。

返回說明

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

開始播放音效。

- (int)playAudioEffectWithSoundId:(NSInteger)soundId filePath:(NSString *_Nonnull)filePath cycles:(NSInteger)cycles publish:(BOOL)publish;

參數說明

名稱	類型	描述
soundId	NSInteger	使用者給該音效檔案分配的ID。
filePath	NSString *_Nonnull	音效檔案路徑。
cycles	NSInteger	迴圈次數（可以設定-1或者正整數）。
publish	BOOL	是否發布。

返回說明

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

停止播放音效。

- (int)stopAudioEffectWithSoundId:(NSInteger)soundId;

參數說明

名稱	類型	描述
soundId	NSInteger	使用者給該音效檔案分配的ID。

返回說明

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

停止播放所有音效。

- (int)stopAllAudioEffects;

返回說明

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

暫停音效。

- (int)pauseAudioEffectWithSoundId:(NSInteger)soundId;

參數說明

名稱	類型	描述
soundId	NSInteger	使用者給該音效檔案分配的ID。

返回說明

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

暫停所有音效。

- (int)pauseAllAudioEffects;

返回說明

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

重新開始播放音效。

- (int)resumeAudioEffectWithSoundId:(NSInteger)soundId;

參數說明

名稱	類型	描述
soundId	NSInteger	使用者給該音效檔案分配的ID。

返回說明

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

重新開始播放所有音效。

- (int)resumeAllAudioEffects;

返回說明

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

設定音效推流音量。

- (int)setAudioEffectPublishVolumeWithSoundId:(NSInteger)soundId volume:(NSInteger)volume;

參數說明

名稱	類型	描述
soundId	NSInteger	使用者給該音效檔案分配的ID。
volume	NSInteger	混音音量，取值範圍：[0,100]，預設值為50。

返回說明

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

擷取推流音效音量。

- (int)getAudioEffectPublishVolumeWithSoundId:(NSInteger)soundId;

參數說明

名稱	類型	描述
soundId	NSInteger	使用者給該音效檔案分配的ID。

返回說明

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

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

- (int)setAllAudioEffectsPublishVolume:(NSInteger)volume;

參數說明

名稱	類型	描述
volume	NSInteger	混音音量，取值範圍：[0,100]，預設值為50。

返回說明

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

設定音效本地播放音量。

- (int)setAaudioEffectPlayoutVolumeWithSoundId:(NSInteger)soundId volume:(NSInteger)volume;

參數說明

名稱	類型	描述
soundId	NSInteger	使用者給該音效檔案分配的ID。
volume	NSInteger	混音音量，取值範圍：[0,100]，預設值為50。

返回說明

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

擷取音效本地播放音量。

- (int)getAudioEffectPlayoutVolumeWithSoundId:(NSInteger)soundId;

參數說明

名稱	類型	描述
soundId	NSInteger	使用者給該音效檔案分配的ID。

返回說明

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

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

- (int)setAllAudioEffectsPlayoutVolume:(NSInteger)volume;

參數說明

名稱	類型	描述
volume	NSInteger	混音音量，取值範圍：[0,100]，預設值為50。

返回說明

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

開啟媒體檔案錄製。

- (BOOL)startRecord:(AliRtcRecordType)recordType recordFormat:(AliRtcRecordFormat)recordFormat filePath:(NSString*)filePath audioConfig:(AliRtcRecordAudioConfig*)audioConfig videoConfig:(AliRtcRecordVideoConfig*)videoConfig;

參數說明

參數	類型	描述
recordType	AliRtcRecordType	錄製類型。
recordFormat	AliRtcRecordFormat	錄製格式。
filePath	NSString *	錄製檔案名稱和路徑。
audioConfig	AliRtcRecordAudioConfig *	音頻配置。
videoConfig	AliRtcRecordVideoConfig *	視頻配置。

返回說明

TRUE成功，其他失敗。

停止錄製媒體檔案。

- (void)stopRecord 

參數說明

無。

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

- (int)setLocalViewConfig:(AliVideoCanvas *_Nullable)viewConfig forTrack:(AliRtcVideoTrack)track;

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

調用時機

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

參數說明

名稱	類型	描述
viewConfig	AliVideoCanvas *_Nullable	渲染參數，包含渲染視窗以及渲染方式。
track	AliRtcVideoTrack	視頻Track的類型。

返回說明

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

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

- (int)setCameraCapturerConfiguration:(AliRtcCameraCapturerConfiguration* _Nonnull)config;

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

調用時機

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

• startPreview（開始預覽）

• joinChannel（加入頻道）

參數說明

名稱	類型	描述
config	AliRtcCameraCapturerConfiguration * _Nonnull	網路攝影機採集偏好，預設值： preference：0 cameraDirection：0 fps: 0 cameraCaptureProfile: 0 disableVideoCaptureReverse: -1 enableCameraMacroFocus: -1 captureObserverOriginal: -1 nativeBufferObserver: -1 captureCallbackCvpixelbufferToRaw: -1 以上-1表示使用SDK內部預設設定；

返回說明

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

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

- (int)enableLocalVideo:(BOOL)enable;

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

調用時機

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

相關回調

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

參數說明

名稱	類型	描述
enable	BOOL	YES表示恢複正常，NO表示停止視頻採集，預設YES。

返回說明

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

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

- (int)muteLocalCamera:(BOOL)mute forTrack:(AliRtcVideoTrack)track;

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

參數說明

名稱	類型	描述
mute	BOOL	YES表示視頻資料發送黑幀，NO表示恢複正常，預設值為NO。
track	AliRtcVideoTrack	需要改變發布狀態的視頻Track類型。

返回說明

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

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

- (int)setRemoteViewConfig:(AliVideoCanvas *_Nullable)canvas uid:(NSString *_Nonnull)uid forTrack:(AliRtcVideoTrack)track;

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

• 如果AliVideoCanvas：渲染畫布。中的view參數為空白，則停止渲染。

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

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

調用時機

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

參數說明

名稱	類型	描述
canvas	AliVideoCanvas *_Nullable	渲染參數，包含渲染視窗以及渲染方式。
uid	NSString *_Nonnull	使用者ID。
track	AliRtcVideoTrack	需要設定的視頻Track類型。

返回說明

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

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

- (BOOL)isCameraOn;

返回說明

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

設定視頻編碼屬性。

- (void)setVideoEncoderConfiguration:(AliRtcVideoEncoderConfiguration* _Nonnull)config;

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

調用時機

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

調用限制

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

參數說明

名稱	類型	描述
config	AliRtcVideoEncoderConfiguration * _Nonnull	預定義的編碼屬性，預設值： dimensions：[640,480] frameRate：15 bitrate：0 mirrorMode：0 keyFrameInterval：主要畫面格間隔，單位為毫秒，預設為 0，表示由 SDK 內部控制。 forceStrictKeyFrameInterval：是否強制編碼器嚴格按照設定的主要畫面格間隔產生主要畫面格。預設值false。 orientationMode：0 rotation：0 codecType：AliRtcVideoCodecTypeDefault encoderType:AliRtcVideoEncodeCodecTypeDefault seiForceFrontIFrame: -1 enableDynamicEncode: -1 disableDipenseResolutionChange: -1 enableDowngrade: -1 enableH264BFrame: -1 enableHevcBFrame: -1 backgroundHardwareToSoftware: -1 以上-1表示使用SDK內部預設設定；

設定視頻解碼屬性。

- (void)setVideoDecoderConfiguration:(AliRtcVideoDecoderConfiguration* _Nonnull)config;

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

調用時機

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

參數說明

名稱	類型	描述
config	AliRtcVideoDecoderConfiguration * _Nonnull	預定義的解碼屬性，預設值： codecType：AliRtcVideoCodecTypeDefault enableDecoderBframe：-1 backgroundHardwareToSoftware：-1 以上-1表示使用SDK內部預設設定；

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

- (int)switchCamera;

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

調用時機

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

調用限制

僅 Android 和 iOS 平台可用。

返回說明

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

擷取當前網路攝影機方向，預設自拍（僅iOS）。

- (AliRtcCameraDirection)getCurrentCameraDirection;

返回說明

返回camera方向枚舉值。

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

- (int)startPreview;

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

調用時機

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

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

返回說明

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

停止本地預覽。

- (int)stopPreview;

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

調用時機

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

返回說明

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

設定網路攝影機縮放。

 - (int)setCameraZoom:(float)zoom;

參數說明

名稱	類型	描述
zoom	float	縮放層級，範圍從 1 到 camera支援的最大 zoom值。

傳回值

0 成功，其他失敗。

擷取網路攝影機最大縮放比例。

 - (float)GetCameraMaxZoomFactor;

傳回值

網路攝影機最大縮放比例。

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

- (float)GetCurrentZoom;

傳回值

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

設定網路攝影機曝光度。

- (int)SetExposure:(float)exposure;

參數說明

名稱	類型	描述
exposure	float	曝光度

傳回值

0 成功，其他失敗。

擷取網路攝影機曝光度。

- (float)GetCurrentExposure;

傳回值

網路攝影機曝光度。

擷取網路攝影機最小曝光度

- (float)GetMinExposure;

傳回值

網路攝影機曝光最小曝光度。

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

- (float)GetMaxExposure;

傳回值

網路攝影機曝光最大曝光度。

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

- (int)setCameraFlash:(BOOL)flash;

參數說明

名稱	類型	描述
flash	BOOL	是否允許開閃光燈。

傳回值

0成功，其他失敗。

網路攝影機是否支援手動聚焦。

- (BOOL)isCameraFocusPointSupported;

傳回值

TRUE支援手動聚焦 FALSE不支援手動聚焦。

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

- (BOOL)isCameraExposurePointSupported;

傳回值

TRUE支援設定曝光點FALSE不支援設定曝光點。

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

- (int)setCameraFocusPoint:(CGPoint)point;

參數說明

名稱	類型	描述
point	CGPoint	設定的對焦點座標，一直保持

傳回值

0成功，其他失敗。

設定曝光點曝光值。

- (int)setCameraExposurePoint:(CGPoint)point;

參數說明

名稱	類型	描述
point	CGPoint	設定的對焦點座標，一直保持。

傳回值

0成功，其他失敗。

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

- (BOOL)isCameraAutoFocusFaceModeSupported;

傳回值

TRUE 支援人臉聚焦 FALSE 不支援人臉聚焦。

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

- (BOOL)setCameraAutoFocusFaceModeEnabled:(BOOL)enable;

參數說明

名稱	類型	描述
point	CGPoint	設定的對焦點座標，一直保持。

傳回值

TRUE 成功 FALSE 失敗。

設定視頻鏡像模式。

- (int)setVideoMirrorMode:(AliRtcVideoPipelineMirrorMode)mirrorMode;

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

調用時機

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

調用限制

此介面與setLocalViewConfig&setVideoEncoderConfiguration裡面的mirrorMode重合，建議僅使用本方法。

參數說明

名稱	類型	描述
mirrorMode	AliRtcVideoPipelineMirrorMode	鏡像類型。

設定視頻鏈路縮放模式。

-(void)setCapturePipelineScaleMode:(AliRtcCapturePipelineScaleMode)mode;

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

調用時機

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

參數說明

名稱	類型	描述
mode	AliRtcCapturePipelineScaleMode	縮放類型。

傳回值

0成功，其他失敗；

註冊視頻資料輸出對象。

- (void)registerVideoFrameWithObserver:(id<AliRtcVideoFrameDelegate> _Nullable)observer;

該介面用於註冊視頻資料的輸出對象。如果要取消註冊，請調用unregisterVideoSampleWithObserver介面。

調用時機

如果你需要擷取原始音頻資料（如 YUV 或 RGBA 格式），可以調用此介面註冊一個視頻資料監測器來擷取各階段的視頻資料。

相關回調

成功註冊視頻資料輸出監測器後，SDK 會在捕捉到每個視訊框架時，觸發你實現的回調，請根據業務需要實現對應回調：

• onCaptureVideoSample：本地採集視頻資料回調。

• onRemoteVideoSample：遠端視頻資料回調。

• onPreEncodeVideoSample：本地編碼前視頻資料回調。

參數說明

名稱	類型	描述
observer	AliRtcVideoFrameDelegate	視頻資料輸出對象。

取消視頻資料輸出對象。

- (void)unregisterVideoSampleWithObserver:(id<AliRtcVideoFrameDelegate> _Nullable)observer;

此介面與registerVideoSampleObserver介面相對應，負責取消註冊視頻資料輸出對象。

參數說明

名稱	類型	描述
observer	AliRtcVideoFrameDelegate	視頻資料輸出對象。

註冊本地相機流視頻OpenGL紋理資料觀測器。

- (void)registerLocalVideoTextureObserver:(id<AliRtcTextureDelegate> _Nullable)observer;

如果您想擷取原始視頻資料，請調用registerVideoSampleObserver介面註冊相關回調；如果你希望擷取內部紋理資料，請調用本介面。如果希望取消註冊，請調用unRegisterLocalVideoTextureObserver介面。

相關回調

成功註冊本地相機流視頻OpenGL紋理資料觀測器後，SDK 會在捕捉到每個視訊框架時，觸發你在 AliRtcTextureObserver 介面中實現的回調，請根據業務需要實現對應回調：

• onTextureCreate：該回調是在SDK內部OpenGL上下文建立的時候觸發。

• onTextureUpdate：該回調會在每一幀視頻資料上傳到OpenGL紋理之後觸發，當外部註冊了OpenGL紋理資料觀測器，在該回調中可以對紋理進行處理，並返回處理後的紋理ID。該回調傳回值必須為有效紋理ID，如果不做任何處理必須返回參數textureId

• onTextureDestroy：該回調是在SDK內部OpenGL上下文銷毀的時候觸發。

參數說明

名稱	類型	描述
observer	AliRtcTextureDelegate	OpenGL紋理資料觀測器。

取消註冊本地相機流視頻OpenGL紋理資料觀測器。

- (void)unregisterLocalVideoTextureObserver:(id<AliRtcTextureDelegate> _Nullable)observer;

該介面與registerLocalVideoTextureObserver相對應，負責取消註冊。

參數說明

名稱	類型	描述
observer	AliRtcTextureDelegate	OpenGL紋理資料觀測器。

視頻截圖功能。

- (int)snapshotVideo:(NSString*_Nullable)userId type:(AliRtcVideoTrack)type;

參數說明

名稱	類型	描述
userId	NSString *	使用者ID，userId 為nil或者為""代表本機使用者。
type	AliRtcVideoTrack	視頻流類型，只支援 {@link AliRtcVideoTrack::AliRtcVideoTrackCamera} 和 {@link AliRtcVideoTrack::AliRtcVideoTrackScreen}。

傳回值

0成功，其他失敗。

啟用外部視頻輸入源。

- (int)setExternalVideoSource:(BOOL)enable sourceType:(AliRtcVideoSource)type renderMode:(AliRtcRenderMode)renderMode;

參數說明

名稱	類型	描述
enable	BOOL	YES表示開啟，NO表示關閉。
type	AliRtcVideoSource	流類型。
renderMode	AliRtcRenderMode	渲染模式。

輸入視頻資料。

- (int)pushExternalVideoFrame:(AliRtcVideoDataSample *_Nonnull)frame sourceType:(AliRtcVideoSource)type;

參數說明

名稱	類型	描述
frame	AliRtcVideoDataSample *_Nonnull	幀資料。
type	AliRtcVideoSource	流類型。

返回說明

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

開啟旁路直播。

- (int)startPublishLiveStreamWithURL:(NSString *_Nonnull)streamURL liveTranscoding:(AliRtcLiveTranscodingParam *_Nonnull)trancoding;

參數說明

名稱	類型	描述
streamUrl	NSString *	推流地址。
transcoding	AliRtcLiveTranscodingParam *	推流所需參數。

返回說明

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

更新旁路直播相關參數。

- (int)updatePublishLiveStreamWithURL:(NSString *_Nonnull)streamURL liveTranscoding:(AliRtcLiveTranscodingParam *_Nonnull)trancoding;

參數說明

名稱	類型	描述
streamUrl	NSString *	推流地址。
transcoding	AliRtcLiveTranscodingParam *	推流所需參數。

返回說明

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

停止旁路直播。

- (int)stopPublishLiveStreamWithURL:(NSString *_Nonnull)streamURL;

參數說明

名稱	類型	描述
streamUrl	NSString *_Nonnull	推流地址。

返回說明

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

擷取旁路直播狀態。

- (AliRtcLiveTranscodingState)GetPublishLiveStreamStateWithURL:(NSString *_Nonnull)streamURL;

參數說明

參數	類型	說明
streamURL	NSString *	推流地址。

返回說明

返回旁路直播狀態。

開啟網路品質探測。

- (int)startLastmileDetect:(AliRtcNetworkQualityProbeConfig *_Nonnull)config;

參數說明

參數	類型	說明
config	AliRtcNetworkQualityProbeConfig	探測配置的參數。

返回說明

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

停止網路品質探測。

- (int)stopLastmileDetect;

返回說明

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

發送SEI資訊。

- (int)sendMediaExtensionMsg:(NSData *_Nonnull)data repeatCount:(int)repeatCount delay:(int)delay isKeyFrame:(bool)isKeyFrame;

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

常見使用情境包括：

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

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

調用時機

在開始推流後調用。

調用限制

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

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

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

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

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

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

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

相關回調

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

參數說明

名稱	類型	描述
data	NSData *	擴充資訊內容, 長度限制為最大4K 位元組
repeatCount	int	重複次數，代表訊息冗餘度，用於防止網路丟包導致的訊息丟失-1表示無限重發，除非再一次調用sendMediaExtensionMs
delay	int	延遲多少毫秒發送。用來延遲多少毫秒之後再發送SEI，因SEI是附在編碼之後的h264/h265流，所以實際的延遲會比設定的延遲略大
isKeyFrame	bool	是否只給主要畫面格加SEI 設定為true，則只給主要畫面格加SEI資訊

傳回值

0成功，其他失敗；

發送媒體擴充資訊，底層使用SEI實現。

- (int)sendMediaExtensionMsgEx:(NSData *_Nonnull)data repeatCount:(int)repeatCount delay:(int)delay isKeyFrame:(bool)isKeyFrame payloadType:(int)payloadType;

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

常見使用情境包括：

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

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

調用時機

在開始推流後調用。

調用限制

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

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

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

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

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

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

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

參數說明

名稱	類型	描述
data	NSData *	擴充資訊內容, 長度限制為最大4K 位元組
repeatCount	int	重複次數，代表訊息冗餘度，用於防止網路丟包導致的訊息丟失-1表示無限重發，除非再一次調用sendMediaExtensionMs
delay	int	延遲多少毫秒發送。用來延遲多少毫秒之後再發送SEI，因SEI是附在編碼之後的h264/h265流，所以實際的延遲會比設定的延遲略大
isKeyFrame	bool	是否只給主要畫面格加SEI 設定為true，則只給主要畫面格加SEI資訊
payloadType	int	類型，帶UUID的請用5，範圍是[5,100..254]

返回說明

• 0：調用成功。

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

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

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

- (void)onConnectionStatusChange:(AliRtcConnectionStatus)status reason:(AliRtcConnectionStatusChangeReason)reason;

參數說明

參數	類型	描述
status	AliRtcConnectionStatus	目前狀態值。
reason	AliRtcConnectionStatusChangeReason	引起狀態變化的具體原因。

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

- (void)onLocalDeviceException:(AliRtcLocalDeviceType)deviceType exceptionType:(AliRtcLocalDeviceExceptionType)exceptionType message:(NSString *_Nullable)msg;

參數說明

參數	類型	描述
deviceType	AliRtcLocalDeviceType	裝置類型
exceptionType	AliRtcLocalDeviceExceptionType	裝置異常類型
msg	NSString	異常時攜帶的資訊

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

- (void)onAuthInfoWillExpire;

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

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

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

觸發時機

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

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

- (void)onAuthInfoExpired;

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

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

觸發時機

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

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

- (void)onJoinChannelResult:(int)result channel:(NSString *_Nonnull)channel elapsed:(int) elapsed;

觸發條件

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

參數說明

參數	類型	描述
result	int	加入頻道結果，成功返回0，失敗返回錯誤碼。
channel	NSString *_Nonnull	加入的頻道ID。
elapsed	int	加入頻道耗時。

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

- (void)onLeaveChannelResult:(int)result stats:(AliRtcStats)stats;

參數說明

參數	類型	描述
result	int	離開頻道結果，成功返回0，失敗返回錯誤碼。
stats	AliRtcStats	本次頻道內會話的資料統計匯總。

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

- (void)onRemoteUserOffLineNotify:(NSString *_Nonnull)uid offlineReason:(AliRtcUserOfflineReason)reason;

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

觸發條件

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

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

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

參數說明

參數	類型	描述
uid	NSString *_Nonnull	使用者ID從App server分配的唯一標示符。
reason	AliRtcUserOfflineReason	使用者離線的原因。

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

- (void)onRemoteUserOnLineNotify:(NSString *_Nonnull)uid elapsed:(int)elapsed;

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

觸發條件

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

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

參數說明

參數	類型	描述
uid	NSString *_Nonnull	使用者ID從App server分配的唯一標示符。
elapsed	int	使用者加入頻道時的耗時。

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

- (void)onRemoteTrackAvailableNotify:(NSString *_Nonnull)uid audioTrack:(AliRtcAudioTrack)audioTrack videoTrack:(AliRtcVideoTrack)videoTrack;

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

觸發條件

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

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

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

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

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

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

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

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

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

參數說明

參數	類型	描述
uid	NSString *_Nonnull	使用者ID從App server分配的唯一標示符。
audioTrack	AliRtcAudioTrack	遠端使用者發生變化後的音頻流。
videoTrack	AliRtcVideoTrack	遠端使用者發生變化後的視頻流。

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

- (void)onBye:(int)code;

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

觸發條件

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

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

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

參數說明

參數	類型	描述
code	int	訊息類型。取值： 1：被伺服器踢出。 2：頻道關閉。 3：同一個使用者ID在其他端登入，被伺服器踢出。

音頻推流變更回調。

- (void)onAudioPublishStateChanged:(AliRtcPublishState)oldState newState:(AliRtcPublishState)newState elapseSinceLastState:(NSInteger)elapseSinceLastState channel:(NSString *_Nonnull)channel;

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

觸發條件

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

• 停止推流。

• 調用setClientRole切換為觀眾。

參數說明

參數	類型	描述
oldState	AliRtcPublishState	之前的推流狀態。
newStat	AliRtcPublishState	當前的推流狀態。
elapseSinceLastState	NSInteger	狀態變更時間間隔，單位：毫秒。
channel	NSString *_Nonnull	目前通道ID。

音頻訂閱情況變更回調。

- (void)onAudioSubscribeStateChanged:(NSString *_Nonnull)uid oldState:(AliRtcSubscribeState)oldState newState:(AliRtcSubscribeState)newState elapseSinceLastState:(NSInteger)elapseSinceLastState channel:(NSString *_Nonnull)channel;

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

參數說明

參數	類型	描述
uid	NSString *_Nonnull	訂閱情況變更的使用者ID。
oldState	AliRtcSubscribeState	之前的訂閱狀態。
newState	AliRtcSubscribeState	當前的訂閱狀態。
elapseSinceLastState	NSInteger	狀態變更時間間隔，單位：毫秒。
channel	NSString *_Nonnull	目前通道ID。

使用者muteAudio通知。

- (void)onUserAudioMuted:(NSString *_Nonnull)uid audioMuted:(BOOL)isMute;

參數說明

參數	類型	描述
uid	NSString *_Nonnull	執行muteAudio的使用者ID。
isMute	BOOL	YES表示靜音，NO表示未靜音。

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

- (void)onUserAudioInterruptedBegin:(NSString *_Nonnull)uid;

參數說明

參數	類型	描述
uid	NSString *_Nonnull	audio被中斷的使用者ID。

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

- (void)onUserAudioInterruptedEnded:(NSString *_Nonnull)uid;

參數說明

參數	類型	描述
uid	NSString *_Nonnull	audio中斷結束的使用者ID。

視頻推流變更回調。

- (void)onVideoPublishStateChanged:(AliRtcPublishState)oldState newState:(AliRtcPublishState)newState elapseSinceLastState:(NSInteger)elapseSinceLastState channel:(NSString *_Nonnull)channel;

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

參數說明

參數	類型	描述
oldState	AliRtcPublishState	之前的推流狀態。
newState	AliRtcPublishState	當前的推流狀態。
elapseSinceLastState	NSInteger	狀態變更時間間隔，單位：毫秒。
channel	NSString *_Nonnull	目前通道ID。

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

- (void)onVideoSubscribeStateChanged:(NSString *_Nonnull)uid oldState:(AliRtcSubscribeState)oldState newState:(AliRtcSubscribeState)newState elapseSinceLastState:(NSInteger)elapseSinceLastState channel:(NSString *_Nonnull)channel;

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

相關回調

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

參數說明

參數	類型	描述
uid	NSString *_Nonnull	訂閱情況變更的使用者ID。
oldState	AliRtcSubscribeState	之前的訂閱狀態。
newState	AliRtcSubscribeState	當前的訂閱狀態。
elapseSinceLastState	NSInteger	狀態變更時間間隔，單位：毫秒。
channel	NSString *_Nonnull	目前通道ID。

使用者muteVideo通知。

- (void)onUserVideoMuted:(NSString *_Nonnull)uid videoMuted:(BOOL)isMute;

參數說明

參數	類型	描述
uid	NSString *_Nonnull	執行muteVideo的使用者ID。
isMute	BOOL	YES表示推流黑幀，NO表示正常推流。