ARtcEngineKit

概览

提供所有可供 App 调用的方法

anyRTC 通过全球部署的虚拟网络专为 WebRTC 以及移动端到移动端的 App 进行过优化。可以为全世界的音视频通信提供质量保证的体验（QoE）。

ARtcEngineKit 是 anyRTC SDK 的入口类。它为 App 提供了快速搭建音视频通信的 API。

核心方法

sharedEngineWithAppId

+ (instancetype _Nonnull)sharedEngineWithAppId:(NSString *_Nonnull)appId delegate:(id<ARtcEngineDelegate> _Nullable)delegate;

实例化ARtcEngineKit对象

ARtcEngineKit 类的所有接口函数，如无特殊说明，都是异步调用，对接口的调用建议在同一个线程进行。

返回值

一个ARtcEngineKit 实例对象。

注意事项： 请确保在调用其他 API 前先调用该方法创建并初始化 ARtcEngineKit。 一个 ARtcEngineKit 实例对象只能使用一个 App ID。如需更换 App ID，必须先调用 destroy 销毁当前实例，再调用本方法重新创建实例。

destroy

+ (void)destroy;

销毁 RtcEngine 实例

该方法用于释放SDK 使用的所有对象资源。帮助偶尔使用音视频通话的 App 在无需通话时释放资源。一旦 App 调用了 destroy 接口销毁创建的 ARtcEngineKit 实例，将无法调用 SDK 内的任何方法也不再会有任何回调产生。如需重启通话，请调用初始化方法sharedEngineWithAppId 创建一个新的 ARtcEngineKit 实例。

注意事项：

• 该方法需要在子线程中操作
• 该方法为同步调用。 App 不得在 SDK 生成的回调中调用该方法，不然 SDK 只能等候该回调返回才能重新获取相应的对象资源造成死锁。

setChannelProfile

- (int)setChannelProfile:(ARChannelProfile)profile;

设置频道使用场景

ARtcEngineKit会针对不同的使用场景采用不同的优化策略，如通信场景偏好流畅，直播场景偏好画质。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

• 为保证实时音视频质量，我们建议相同频道内的用户使用同一种频道场景。
• 该方法必须在加入频道前调用，进入频道后无法再设置频道场景。

setClientRole

- (int)setClientRole:(ARClientRole)role;

设置用户角色

在加入频道前，用户需要通过本方法设置观众(默认)或主播角色。在加入频道后，用户可以通过本方法切换用户角色。 如果你在加入频道后调用该方法切换用户角色，调用成功后，本地会触发 didClientRoleChanged 回调；远端会触发 didJoinedOfUid 或 didOfflineOfUid(ARUserOfflineReasonBecomeAudience) 回调。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

该方法仅适用于直播场景。

joinChannelByToken

- (int)joinChannelByToken:(NSString * _Nullable)token channelId:(NSString * _Nonnull)channelId uid:(NSString * _Nullable)uid joinSuccess:(void(^ _Nullable)(NSString * _Nonnull channel, NSString * _Nonnull uid, NSInteger elapsed))joinSuccessBlock;

加入频道

该方法让用户加入通话频道，在同一个频道内的用户可以互相通话，多个用户加入同一个频道，可以群聊。 使用不同 App ID 的 App 是不能互通的。如果已在通话中，用户必须调用 leaveChannel 退出当前通话，才能进入下一个频道。SDK 在通话中使用 iOS 系统的 AVAudioSession 共享对象进行录音和播放， App 对该对象的操作可能会影响 SDK 的音频相关功能。

调用该 API 后会触发 joinSuccessBlock 或 didJoinChannel 回调。block 比 delegate 优先级高，如果两种回调都实现了，只有 block 会触发。

我们建议你将 joinSuccessBlock 设置为 nil，使用 delegate 回调。

加入频道后，本地会触发 didJoinChannel回调；通信场景下的用户和直播场景下的主播加入频道后，远端会触发 didJoinedOfUid 回调。

在网络状况不理想的情况下，客户端可能会与 ar云平台 的服务器失去连接；SDK 会自动尝试重连，重连成功后，本地会触发didRejoinChannel回调。

返回值

0方法调用成功，<0方法调用失败。

• ARErrorCodeInvalidArgument(-2)
• ARErrorCodeNotReady(-3)
• ARErrorCodeRefused(-5)

注意事项：

• 频道内每个用户的 UID 必须是唯一的。如果将 UID 设为 nil，系统将自动分配一个 UID。如果想要从不同的设备同时接入同一个频道，请确保每个设备上使用的 UID 是不同的。
• 在加入频道时，SDK 调用 setCategory(AVAudioSessionCategoryPlayAndRecord) 将 AVAudioSession 设置到 PlayAndRecord 模式， App 不应将其设置到其他模式。设置该模式时，正在播放的声音会被打断（比如正在播放的响铃声）。

switchChannelByToken

- (int)switchChannelByToken:(NSString * _Nullable)token channelId:(NSString * _Nonnull)channelId joinSuccess:(void(^ _Nullable)(NSString * _Nonnull channel, NSString *_Nonnull uid, NSInteger elapsed))joinSuccessBlock;

快速切换直播频道

当直播频道中的观众想从一个频道切换到另一个频道时，可以调用该方法，实现快速切换。成功调用该方切换频道后，本地会先收到离开原频道的回调didLeaveChannelWithStats，再收到成功加入新频道的回调 didJoinChannel 。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

该方法仅适用直播频道中的观众用户。

leaveChannel

- (int)leaveChannel:(void (^ _Nullable) (ARChannelStats *_Nonnull stat))leaveChannelBlock;

离开频道

离开频道，即挂断或退出通话。

当调用 joinChannelByToken 方法后，必须调用 leaveChannel 结束通话，否则无法开始下一次通话。不管当前是否在通话中，都可以调用本方法，没有副作用。该方法会把会话相关的所有资源释放掉。该方法是异步操作，调用返回时并没有真正退出频道。

• 成功调用该方法离开频道后，本地会触发 didLeaveChannelWithStats 回调；
• 通信场景下的用户和直播场景下的主播离开频道后，远端会触发 didOfflineOfUid(ARUserOfflineReasonBecomeAudience) 回调。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

• 如果你调用了本方法后立即调用 destroy 方法，SDK 将无法触发 didLeaveChannelWithStats 回调。
• 如果你在旁路推流时调用本方法， SDK 将自动调用 removePublishStreamUrl 方法。
• 在调用本方法时，iOS 默认情况下 SDK 会停用 audio session，可能会对其他应用程序造成影响。如果想改变这种默认行为，可以通过setAudioSessionOperationRestriction 方法设置 ARAudioSessionOperationRestrictionDeactivateSession，这样在 leaveChannel 时，SDK 不会停用 audio session。

renewToken

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

更新 Token

该方法用于更新 Token。如果启用了 Token 机制，过一段时间后使用的 Token 会失效。当以下任意一种情况发生时：

• tokenPrivilegeWillExpire 回调。
• connectionChangedToState 回调的 reason 参数报告 ARConnectionChangedTokenExpired(9)。

返回值

0方法调用成功，<0方法调用失败。

getConnectionState

- (ARConnectionStateType)getConnectionState;

获取当前网络连接状态

返回值

当前的网络连接状态，详见 ARConnectionStateType。

音频核心方法

enableAudio

- (int)enableAudio;

启用音频模块

本方法可以启用音频模块，默认开启状态。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

• 该方法设置的是内部引擎为开启状态，在频道内和频道外均可调用，且在 leaveChannel 后仍然有效。

• 该方法重置整个引擎，响应速度较慢，因此 ar云平台 建议使用如下方法来控制音频模块：

  • enableLocalAudio：是否启动麦克风采集并创建本地音频流
  • muteLocalAudioStream：是否发布本地音频流
  • muteRemoteAudioStream：是否接收并播放远端音频流
  • muteAllRemoteAudioStreams：是否接收并播放所有远端音频流

disableAudio

- (int)disableAudio;

关闭音频模块

返回值

0方法调用成功，<0方法调用失败。

注意事项：

• 该方法设置的是内部引擎为禁用状态，在频道内和频道外均可调用，且在 leaveChannel 后仍然有效。

• 该方法重置整个引擎，响应速度较慢，因此建议使用如下方法来控制音频模块：

  • enableLocalAudio：是否启动麦克风采集并创建本地音频流
  • muteLocalAudioStream：是否发布本地音频流
  • muteRemoteAudioStream：是否接收并播放远端音频流
  • muteAllRemoteAudioStreams：是否接收并播放所有远端音频流

请确保在调用其他 API 前先调用该方法创建并初始化 ARtcEngineKit。 一个 ARtcEngineKit 实例对象只能使用一个 App ID。如需更换 App ID，必须先调用 destroy 销毁当前实例，再调用本方法重新创建实例。

setAudioProfile

- (int)setAudioProfile:(ARAudioProfile)profile scenario:(ARAudioScenario)scenario;

设置音频编码配置

返回值

0方法调用成功，<0方法调用失败。

注意事项：

• 该方法需要在 joinChannelByToken 之前设置好，joinChannelByToken之后设置不生效。
• 通信场景下，该方法设置 profile 生效，设置 scenario 不生效。
• 通信和直播场景下，音质（码率）会有网络自适应的调整，通过该方法设置的是一个最高码率。
• 在有高音质需求的场景（例如音乐教学场景）中，建议将 profile 设置为 ARAudioProfileMusicHighQuality(4)，scenario 设置为 ARAudioScenarioGameStreaming(3)

adjustRecordingSignalVolume

- (int)adjustRecordingSignalVolume:(NSInteger)volume;

调节录音音量

返回值

0方法调用成功，<0方法调用失败。

adjustPlaybackSignalVolume

- (int)adjustPlaybackSignalVolume:(NSInteger)volume;

调节本地播放的所有远端用户音量

返回值

0方法调用成功，<0方法调用失败。

enableAudioVolumeIndication

- (int)enableAudioVolumeIndication:(NSInteger)interval smooth:(NSInteger)smooth report_vad:(BOOL)report_vad;

启用说话者音量提示

返回值

0方法调用成功，<0方法调用失败。

enableLocalAudio

- (int)enableLocalAudio:(BOOL)enabled;

开关本地音频采集

当用户加入频道时，它的语音功能默认是开启的。该方法可以关闭或重新开启本地语音功能，即停止或重新开启本地音频采集。

该方法不影响接收或播放远端音频流，enableLocalAudio(NO) 适用于只听不发的用户场景。

语音功能关闭或重新开启后，会收到回调 didMicrophoneEnabled。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

该方法与 muteLocalAudioStream 的区别在于：

• enableLocalAudio：开启或关闭本地语音采集及处理。使用 enableLocalAudio 关闭或开启本地采集后，本地听远端播放会有短暂中断。
• muteLocalAudioStream：停止或继续发送本地音频流。

muteLocalAudioStream

- (int)muteLocalAudioStream:(BOOL)mute;

开关本地音频发送

该方法用于允许/禁止往网络发送本地音频流。成功调用该方法后，远端会触发 remoteAudioStateChangedOfUid 回调。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

• 该方法不影响录音状态，并没有禁用麦克风。
• 如果你在该方法后调用 setChannelProfile 方法，SDK 会根据你设置的频道场景以及用户角色，重新设置是否停止发送本地音频。因此我们建议在 setChannelProfile 后调用该方法。

muteRemoteAudioStream

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

停止/恢复接收指定用户的音频流

返回值

0方法调用成功，<0方法调用失败。

注意事项：

如果之前有调用过 muteAllRemoteAudioStreams(YES) 对所有远端音频进行静音，在调用本 API 之前请确保你已调用 muteAllRemoteAudioStreams(NO)。 muteAllRemoteAudioStreams 是全局控制，muteRemoteAudioStream 是精细控制。

muteAllRemoteAudioStreams

- (int)muteAllRemoteAudioStreams:(BOOL)mute;

停止/恢复接收所有远端音频流

返回值

0方法调用成功，<0方法调用失败。

setDefaultMuteAllRemoteAudioStreams

- (int)setDefaultMuteAllRemoteAudioStreams:(BOOL)mute;

设置是否默认接收音频流

该方法在加入频道前后都可调用。如果在加入频道后调用 setDefaultMuteAllRemoteAudioStreams (YES)，会接收不到设置后加入频道的用户的音频流。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

停止接收音频流后，如果想要恢复接收，请调用 muteRemoteAudioStream(NO)，并指定你想要接收的远端用户 uid；如果想恢复接收多个用户的音频流，则需要多次调用muteRemoteAudioStream。setDefaultMuteAllRemoteAudioStreams(NO) 只能恢复接收后面加入频道的用户的音频流。

adjustUserPlaybackSignalVolume

- (int)adjustUserPlaybackSignalVolume:(NSString *_Nonnull)uid volume:(int)volume;

调节本地播放的指定远端用户音量

加入频道后，你可以多次调用该方法调节不同远端用户在本地播放的音量，或对某个远端用户在本地播放的音量调节多次。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

• 该方法要在加入频道后调用。
• 该方法调节的是本地播放的指定远端用户混音后的音量。
• 该方法每次只能调整一位远端用户在本地播放的音量。若需调整多位远端用户在本地播放的音量，则需多次调用该方法。

视频核心方法

enableVideo

- (int)enableVideo;

启用视频模块

该方法用于打开视频模式。可以在加入频道前或者通话中调用，在加入频道前调用，则自动开启视频模式，在通话中调用则由音频模式切换为视频模式。调用 disableVideo 方法可关闭视频模式。

成功调用该方法后，远端会触发 didVideoEnabled(YES) 和 remoteVideoStateChangedOfUid 回调。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

• 该方法设置的是内部引擎为启用状态，在 leaveChannel 后仍然有效。
• 该方法重置整个引擎，响应速度较慢，因此建议使用如下方法来控制视频模块：
  • enableLocalVideo：是否启动摄像头采集并创建本地视频流
  • muteLocalVideoStream：是否发布本地视频流
  • muteRemoteVideoStream：是否接收并播放远端视频流
  • muteAllRemoteVideoStreams：是否接收并播放所有远端视频流

disableVideo

- (int)disableVideo;

关闭视频模块

该方法用于关闭视频。可以在加入频道前或者通话中调用，在加入频道前调用，则自动开启纯音频模式，在通话中调用则由视频模式切换为纯音频模式。调用 enableVideo 方法可开启视频模式。

成功调用该方法后，远端会触发remoteVideoStateChangedOfUid回调。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

• 该方法设置的是内部引擎为启用状态，在 leaveChannel 后仍然有效。
• 该方法重置整个引擎，响应速度较慢，因此建议使用如下方法来控制视频模块：
  • enableLocalVideo：是否启动摄像头采集并创建本地视频流
  • muteLocalVideoStream：是否发布本地视频流
  • muteRemoteVideoStream：是否接收并播放远端视频流
  • muteAllRemoteVideoStreams：是否接收并播放所有远端视频流

setVideoEncoderConfiguration

- (int)setVideoEncoderConfiguration:(ARVideoEncoderConfiguration *_Nonnull)config;

设置视频编码配置

该方法设置视频编码配置。每个配置对应一套视频参数，如分辨率、帧率、码率、视频方向等。 所有设置的参数均为理想情况下的最大值。当视频引擎因网络环境等原因无法达到设置的分辨率、帧率或码率的最大值时，会取最接近最大值的那个值。

如果加入频道后不需要重新设置视频编码配置，建议在 enableVideo 之前调用该方法，可以加快首帧出图时间。

返回值

0方法调用成功，<0方法调用失败。

setupLocalVideo

- (int)setupLocalVideo:(ARtcVideoCanvas *_Nullable)local;

初始化本地视图

该方法初始化本地视图并设置本地用户视频显示信息，只影响本地用户看到的视频画面，不影响本地发布视频。调用该方法绑定本地视频流的显示视窗(view)，并设置本地用户视图的渲染模式和镜像模式。在 App 开发中，通常在初始化后调用该方法进行本地视频设置，然后再加入频道。退出频道后，绑定仍然有效，如果需要解除绑定，可以指定空 (nil) view 调用本方法。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

• 请在加入频道前调用该方法。
• 如果你希望在通话中更新本地用户视图的渲染或镜像模式，请使用 setLocalRenderMode 方法。

setupRemoteVideo

- (int)setupRemoteVideo:(ARtcVideoCanvas *_Nonnull)remote;

初始化远端用户视图

该方法绑定远端用户和显示视图，并设置远端用户视图在本地显示时的渲染模式和镜像模式，只影响本地用户看到的视频画面。调用该接口时需要指定远端用户的 uid，一般可以在进频道前提前设置好。

如果 App 不能事先知道对方的 uid，可以在 APP 收到 didJoinedOfUid 事件时设置。如果启用了视频录制功能，视频录制服务会做为一个哑客户端加入频道，因此其他客户端也会收到它的 didJoinedOfUid 事件，App 不应给它绑定视图（因为它不会发送视频流），如果 App 不能识别哑客户端，可以在 firstRemoteVideoDecodedOfUid 事件时再绑定视图。解除某个用户的绑定视图可以把 view 设置为空。退出频道后，SDK 会把远端用户的绑定关系清除掉。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

如果你希望在通话中更新远端用户视图的渲染或镜像模式，请使用 setRemoteRenderMode 方法。

setLocalRenderMode

- (int)setLocalRenderMode:(ARVideoRenderMode)renderMode mirrorMode:(ARVideoMirrorMode)mirrorMode;

更新本地视图显示模式。

初始化本地用户视图后，你可以调用该方法更新本地用户视图的渲染和镜像模式。该方法只影响本地用户看到的视频画面，不影响本地发布视频。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

• 如果你使用前置摄像头，默认启动本地用户视图镜像模式；如果你使用后置摄像头，默认关闭本地视图镜像模式。
• 请在调用 setupLocalVideo 方法初始化本地视图后，调用该方法。
• 你可以在通话中多次调用该方法，多次更新本地用户视图的显示模式。

setRemoteRenderMode

- (int)setRemoteRenderMode:(NSString *_Nonnull)uid renderMode:(ARVideoRenderMode)renderMode mirrorMode:(ARVideoMirrorMode)mirrorMode;

更新远端视图显示模式。

初始化远端用户视图后，你可以调用该方法更新远端用户视图在本地显示时的渲染和镜像模式。该方法只影响本地用户看到的视频画面。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

• 请在调用 setupRemoteVideo 方法初始化远端视图后，调用该方法。
• 你可以在通话中多次调用该方法，多次更新远端用户视图的显示模式。

startPreview

- (int)startPreview;

开启视频预览

该方法用于在进入频道前启动本地视频预览。本地预览默认开启镜像功能。

调用该 API 前，必须：

• 调用 setupLocalVideo 设置预览窗口及属性
• 调用 enableVideo 开启视频功能

返回值

0方法调用成功，<0方法调用失败。

注意事项：

启用了本地视频预览后，如果调用 leaveChannel退出频道，本地预览依然处于启动状态，如需要关闭本地预览，需要调用stopPreview。

stopPreview

- (int)stopPreview;

停止本地视频预览

返回值

0方法调用成功，<0方法调用失败。

enableLocalVideo

- (int)enableLocalVideo:(BOOL)enabled;

开关本地视频采集

该方法禁用或重新启用本地视频采集，不影响接收远端视频。

调用 enableVideo 后，本地视频即默认开启。你可以调用 enableLocalVideo(NO)关闭本地视频采集。关闭后如果想要重新开启，则可调用 enableLocalVideo(YES)。

成功禁用或启用本地视频采集后，远端会触发 didLocalVideoEnabled 回调。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

该方法设置的是内部引擎为启用/禁用状态，在leaveChannel后仍然有效。

muteLocalVideoStream

- (int)muteLocalVideoStream:(BOOL)mute;

开关本地视频发送

成功调用该方法后，远端会触发 didVideoMuted 回调。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

• 调用该方法时，SDK 不再发送本地视频流，但摄像头仍然处于工作状态。相比于 enableLocalVideo 用于控制本地视频流发送的方法，该方法响应速度更快。该方法不影响本地视频流获取，没有禁用摄像头。
• 如果你在该方法后调用 setChannelProfile 方法，SDK 会根据你设置的频道场景以及用户角色，重新设置是否停止发送本地视频。因此我们建议在 setChannelProfile 后调用该方法。

muteAllRemoteVideoStreams

- (int)muteAllRemoteVideoStreams:(BOOL)mute;

停止/恢复接收所有视频流

返回值

0方法调用成功，<0方法调用失败。

muteRemoteVideoStream

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

停止/恢复接收指定视频流

返回值

0方法调用成功，<0方法调用失败。

注意事项：

如果之前有调用过 muteAllRemoteVideoStreams(YES) 暂停接收所有远端视频，在调用本 API 之前请确保你已调用muteAllRemoteVideoStreams(NO)。 muteAllRemoteVideoStreams是全局控制，muteRemoteVideoStream是精细控制。

setDefaultMuteAllRemoteVideoStreams

- (int)setDefaultMuteAllRemoteVideoStreams:(BOOL)mute;

设置是否默认接收视频流

该方法在加入频道前后都可调用。如果在加入频道后调用setDefaultMuteAllRemoteVideoStreams(YES)，会接收不到设置后加入频道的用户的视频流。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

停止接收视频流后，如果想要恢复接收，请调用muteRemoteVideoStream (NO)，并指定你想要接收的远端用户 uid；如果想恢复接收多个用户的视频流，则需要多次调用muteRemoteVideoStream。setDefaultMuteAllRemoteVideoStreams (NO) 只能恢复接收后面加入频道的用户的视频流。

音频播放路由

setDefaultAudioRouteToSpeakerphone

- (int)setDefaultAudioRouteToSpeakerphone:(BOOL)defaultToSpeaker;

设置默认的语音路由

该方法设置接收到的语音从听筒或扬声器出声。如果用户不调用本方法，语音默认从听筒出声。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

• 该方法仅使用于通信场景。
• 该方法只在纯音频模式下工作，在有视频的模式下不工作。

各频道场景下默认的语音路由：

• 通信：听筒。
• 直播：扬声器。

setEnableSpeakerphone

- (int)setEnableSpeakerphone:(BOOL)enableSpeaker;

启用/关闭扬声器播放

该方法设置是否将语音路由到扬声器（外放）。调用该方法后，SDK 将返回 didAudioRouteChanged 回调提示状态已更改。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

• 请确保在调用此方法前已调用过joinChannelByToken 方法。
• SDK 会调用 setCategory(AVAudioSessionCategoryPlayAndRecord) 并配置耳麦或者外放，所以调用该方法后所有声音的路由都会按照该方法设置。

isSpeakerphoneEnabled

- (BOOL)isSpeakerphoneEnabled;

查询扬声器启用状态

返回值

• YES: 扬声器已开启，语音会输出到扬声器
• NO: 扬声器未开启，语音会输出到非扬声器（听筒、耳机等）

耳返设置

enableInEarMonitoring

- (int)enableInEarMonitoring:(BOOL)enabled;

开启耳返功能

返回值

0方法调用成功，<0方法调用失败。

setInEarMonitoringVolume

- (int)setInEarMonitoringVolume:(NSInteger)volume;

设置耳返音量

返回值

0方法调用成功，<0方法调用失败。

startChannelMediaRelay

- (int)startChannelMediaRelay:(ARChannelMediaRelayConfiguration * _Nonnull)config;

开始跨频道媒体流转发。该方法可用于实现跨频道连麦等场景。

成功调用该方法后，SDK 会触发 channelMediaRelayStateDidChange和 didReceiveChannelMediaRelayEvent回调，并在回调中报告当前的跨频道媒体流转发状态和事件。

如果 channelMediaRelayStateDidChange 回调报告 ARChannelMediaRelayStateRunning(2) 和 ARChannelMediaRelayStateIdle(0)，且 didReceiveChannelMediaRelayEvent 回调报告 ARChannelMediaRelayEventSentToDestinationChannel(4)，则表示 SDK 开始在源频道和目标频道之间转发媒体流。 如果 channelMediaRelayStateDidChange 回调报告 ARChannelMediaRelayStateFailure(3)，则表示跨频道媒体流转发出现异常。

注意事项：

• 请在成功加入频道后调用该方法。
• 该方法仅对直播场景下的主播有效。
• 成功调用该方法后，若你想再次调用该方法，必须先调用 stopChannelMediaRelay 方法退出当前的转发状态。
• 跨频道媒体流转发功能需要提交工单联系技术支持开通。

返回值

0方法调用成功，<0方法调用失败。

updateChannelMediaRelay

- (int)updateChannelMediaRelay:(ARChannelMediaRelayConfiguration * _Nonnull)config;

####更新媒体流转发的频道。 成功开始跨频道转发媒体流后，如果你希望将流转发到多个目标频道，或退出当前的转发频道，可以调用该方法。成功调用该方法后，SDK 会触发 didReceiveChannelMediaRelayEvent 回调，并在回调中报告状态码 ARChannelMediaRelayEventUpdateDestinationChannel(7)。

注意事项：

• 请在 startChannelMediaRelay 方法后调用该方法，更新媒体流转发的频道。
• 跨频道媒体流转发最多支持 4 个目标频道。如果直播间里已经有 4 个频道了，你可以在调用该方法之前，调用 ARChannelMediaRelayConfiguration 中的 removeDestinationInfoForChannelName 方法移除不需要的频道。

返回值

0方法调用成功，<0方法调用失败。

stopChannelMediaRelay

- (int)stopChannelMediaRelay;

停止跨频道媒体流转发。一旦停止，主播会退出所有目标频道。

成功调用该方法后，SDK 会触发 channelMediaRelayStateDidChange 回调。如果报告 ARChannelMediaRelayStateIdle(0) 和 ARChannelMediaRelayErrorNone(0)，则表示已停止转发媒体流。

注意事项：

• 如果该方法调用不成功，SDK 会触发 channelMediaRelayStateDidChange 回调，并报告状态码 ARChannelMediaRelayErrorServerNoResponse(2) 或 ARChannelMediaRelayEventUpdateDestinationChannelRefused(8)。你可以调用 leaveChannel 方法离开频道，跨频道媒体流转发会自动停止。

返回值

0方法调用成功，<0方法调用失败。

音乐文件播放及混音设置

startAudioMixing

- (int)startAudioMixing:(NSString *  _Nonnull)filePath loopback:(BOOL)loopback replace:(BOOL)replace cycle:(NSInteger)cycle;

开始播放音乐文件

指定本地或在线音频文件来和麦克风采集的音频流进行混音或替换。替换是指用指定的音频文件替换麦克风采集到的音频流。该方法可以选择是否让对方听到本地播放的音频，并指定循环播放的次数。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

• 使用本方法前请确保你的 iOS 设备版本不低于 9.0。
• 请在频道内调用该方法，如果在频道外调用该方法可能会出现问题。
• 如果播放的是在线音乐文件，请确保重复调用该 API 的间隔超过 100 ms，否则 SDK 会返回 AudioFileOpenTooFrequent（702）警告码，表示音乐文件打开过于频繁。
• 如果本地音乐文件不存在、文件格式不支持、无法访问在线音乐文件 URL 都会返回警告码 ARWarningCodeAudioMixingOpenError = 701。

stopAudioMixing

- (int)stopAudioMixing;

停止播放音乐文件

返回值

0方法调用成功，<0方法调用失败。

注意事项： 请在频道内调用该方法。

pauseAudioMixing

- (int)pauseAudioMixing;

暂停播放音乐文件

返回值

0方法调用成功，<0方法调用失败。

注意事项： 请在频道内调用该方法。

resumeAudioMixing

- (int)resumeAudioMixing;

恢复播放音乐文件

返回值

0方法调用成功，<0方法调用失败。

注意事项： 请在频道内调用该方法。

adjustAudioMixingVolume

- (int)adjustAudioMixingVolume:(NSInteger)volume;

调节音乐文件的播放音量

返回值

0方法调用成功，<0方法调用失败。

注意事项： 该方法调节混音的音乐文件在本地和远端播放的音量大小。请在频道内调用该方法。

adjustAudioMixingPlayoutVolume

- (int)adjustAudioMixingPlayoutVolume:(NSInteger)volume;

调节音乐文件在本地播放的音量

返回值

0方法调用成功，<0方法调用失败。

注意事项： 该方法调节混音的音乐文件在本地播放的音量大小。请在频道内调用该方法。

adjustAudioMixingPublishVolume

- (int)adjustAudioMixingPublishVolume:(NSInteger)volume;

调节音乐文件在远端播放的音量

返回值

0方法调用成功，<0方法调用失败。

注意事项： 该方法调节混音的音乐文件在远端播放的音量大小。请在频道内调用该方法。

getAudioMixingPlayoutVolume

- (int)getAudioMixingPlayoutVolume;

获取音乐文件的本地播放音量

该方法获取混音的音乐文件本地播放音量，方便排查音量相关问题。

返回值

方法调用成功则返回音量值，范围为 [0,100]。<0：方法调用失败

getAudioMixingPublishVolume

- (int)getAudioMixingPublishVolume;

获取音乐文件的远端播放音量

该方法获取混音的音乐文件远端播放音量，方便排查音量相关问题。

返回值

方法调用成功则返回音量值，范围为 [0,100]。<0：方法调用失败

音效文件播放管理

getEffectsVolume

- (double)getEffectsVolume;

获取音效文件播放音量

返回值

方法调用成功返回音效的音量值，范围为 [0.0,100.0]，< 0: 方法调用失败

setEffectsVolume

- (int)setEffectsVolume:(double)volume;

设置音效文件播放音量

返回值

0方法调用成功，<0方法调用失败。

setVolumeOfEffect

- (int)setVolumeOfEffect:(int)soundId withVolume:(double)volume;

实时调整音效文件播放音量

返回值

0方法调用成功，<0方法调用失败。

playEffect

- (int)playEffect:(int)soundId filePath:(NSString *_Nullable)filePath loopCount:(int)loopCount pitch:(double)pitch pan:(double)pan gain:(double)gain publish:(BOOL)publish

播放指定音效文件

该方法可以播放指定的本地或在线音效文件来给应用增加音效，比如游戏中特定操作的音效。

你可以在该方法中设置音效文件的播放次数、音调、音效的空间位置和增益，以及远端用户是否能听到该音效。你可以多次调用该方法，通过传入不同的音效文件的 soundID 和 filePath，同时播放多个音效文件，实现音效叠加。为获得最佳用户体验，我们建议同时播放的音效文件不要超过 3 个。

调用该方法播放音效结束后，会触发 rtcEngineDidAudioEffectFinish 回调。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

macOS 上不支持同时播放多个在线音效文件。

stopEffect

- (int)stopEffect:(int)soundId;

停止播放指定音效文件

返回值

0方法调用成功，<0方法调用失败。

stopAllEffects

- (int)stopAllEffects;

停止播放所有音效文件

返回值

0方法调用成功，<0方法调用失败。

preloadEffect

- (int)preloadEffect:(int)soundId filePath:(NSString * _Nullable)filePath;

将指定音效文件预加载至内存

为保证通信畅通，请注意控制预加载音效文件的大小，并在joinChannelByToken 前就使用该方法完成音效预加载。

音效文件支持以下音频格式: mp3，aac，m4a，3gp，wav类的所有接口函数，如无特殊说明，都是异步调用，对接口的调用建议在同一个线程进行。

返回值

0方法调用成功，<0方法调用失败。

注意事项： 该方法不支持在线音效文件。

unloadEffect

- (int)unloadEffect:(int)soundId;

从内存释放某个预加载的音效文件

返回值

0方法调用成功，<0方法调用失败。

pauseEffect

- (int)pauseEffect:(int)soundId;

暂停音效文件播放

返回值

0方法调用成功，<0方法调用失败。

pauseAllEffects

- (int)pauseAllEffects;

暂停所有音效文件播放

返回值

0方法调用成功，<0方法调用失败。

resumeEffect

- (int)resumeEffect:(int)soundId;

恢复播放指定音效文件

返回值

0方法调用成功，<0方法调用失败。

resumeAllEffects

- (int)resumeAllEffects;

恢复播放所有音效文件

返回值

0方法调用成功，<0方法调用失败。

enableDeepLearningDenoise

- (int)enableDeepLearningDenoise:(BOOL)enabled;

开启/关闭降噪

返回值

0方法调用成功，<0方法调用失败。

音频录制

startAudioRecording

- (int)startAudioRecording:(NSString * _Nonnull)filePath sampleRate:(NSInteger)sampleRate quality:(ARAudioRecordingQuality)quality;

开始客户端录音

SDK 支持通话过程中在客户端进行录音。调用该方法后，你可以录制频道内所有用户的音频，并得到一个包含所有用户声音的录音文件。录音文件格式可以为:

• .wav: 文件大，音质保真度较高。
• .aac: 文件小，音质保真度较低。

注意事项：

• 请确保你在该方法中指定的路径存在并且可写。
• 该接口需在 joinChannelByToken 之后调用。如果调用 leaveChannel 时还在录音，录音会自动停止。
• 为保证录音效果，当 sampleRate 设为 44100 Hz 或 48000 Hz 时，建议将 quality 设为 ARAudioRecordingQualityMedium 或 ARAudioRecordingQualityHigh 。

返回值

0方法调用成功，<0方法调用失败。

stopAudioRecording

- (int)stopAudioRecording;

停止客户端录音

注意事项： 该接口需要在 leaveChannel 之前调用，不然会在调用 leaveChannel 时自动停止。

返回值

0方法调用成功，<0方法调用失败。

自定义视频模块

setVideoSource

- (void)setVideoSource:(id<ARVideoSourceProtocol> _Nullable)videoSource;

设置自定义视频源

该方法设置视频源。实时通讯过程中，ar云平台 SDK 通常会启动默认的视频输入设备，即内置的摄像头，进行视频推流。当需要自定义视频设备时，App 可以先通过 ARVideoSourceProtocol 自定义视频源，然后调用该方法将自定义的视频源加入到 SDK 中。

videoSource

- (id<ARVideoSourceProtocol> _Nullable)videoSource;

获取当前视频源

返回值

ARVideoSourceProtocol。

setLocalVideoRenderer

- (void)setLocalVideoRenderer:(id<ARVideoSinkProtocol> _Nullable)videoRenderer;

本地自定义视频渲染器

该方法设置本地视频渲染器。实时通讯过程中， SDK 通常会启动默认的视频渲染器进行视频渲染。当需要自定义视频渲染设备时，App 可以先通过 ARVideoSinkProtocol 自定义渲染器，然后调用该方法将视频渲染器加入到 SDK 中。

setRemoteVideoRenderer

- (void)setRemoteVideoRenderer:(id<ARVideoSinkProtocol> _Nullable)videoRenderer forUserId:(NSString * _Nonnull)uid;

远端自定义视频渲染器

实时音视频互动过程中，SDK 通常会启动默认的视频渲染器进行视频渲染。当需要自定义视频渲染设备时，App 可以先通过 ARVideoSinkProtocol 自定义渲染器，然后调用该方法将视频渲染器加入到 SDK 中。

该方法在加入频道前后都能调用。如果在加入频道前调用，需要自行维护远端用户的 uid。

音频自采集 (仅适用于 push 模式)

enableExternalAudioSourceWithSampleRate

- (void)enableExternalAudioSourceWithSampleRate:(NSUInteger)sampleRate channelsPerFrame:(NSUInteger)channelsPerFrame;

开启外部音频采集

该方法必须在加入频道前调用

disableExternalAudioSource

关闭外部音频采集

pushExternalAudioFrameRawData

- (BOOL)pushExternalAudioFrameRawData:(void *_Nonnull)data samples:(NSUInteger)samples timestamp:(NSTimeInterval)timestamp;

推送外部音频帧

返回值

YES方法调用成功，NO方法调用失败

pushExternalAudioFrameSampleBuffer

- (BOOL)pushExternalAudioFrameSampleBuffer:(CMSampleBufferRef _Nonnull)sampleBuffer type:(ARAudioType)type;

推送外部 CMSampleBuffer 音频帧

返回值

YES方法调用成功，NO方法调用失败

视频自采集 (仅适用于 push 模式)

setExternalVideoSource

- (void)setExternalVideoSource:(BOOL)enable useTexture:(BOOL)useTexture pushMode:(BOOL)pushMode;

配置外部视频源

如果使用了外部视频源，请在调用 enableVideo 或 startPreview 之前调用此 API。

返回值

0方法调用成功，<0方法调用失败。

pushExternalVideoFrame

- (BOOL)pushExternalVideoFrame:(ARVideoFrame * _Nonnull)frame;

推送外部视频帧

该方法主动将视频帧数据用 ARVideoFrame 类封装后传递给 SDK。请确保在你调用本方法前已调用setExternalVideoSource，并将参数 pushMode 设为 YES，不然调用本方法后会一直报错。

返回值

YES: 该帧推送成功 NO: 该帧推送不成功

直播视频水印

addVideoWatermark

- (int)addVideoWatermark:(ARImage* _Nonnull)watermark;

添加本地视频水印

该方法将一张 PNG 图片作为水印添加到本地发布的直播视频流上，同一直播频道中的用户，旁路推流观众，甚至采集设备都能看到或采集到该水印图片。如果你仅仅希望在旁路直播推流中添加水印，请参考 setLiveTranscoding 中描述的用法。

返回值

0方法调用成功，<0方法调用失败。

clearVideoWatermarks

- (int)clearVideoWatermarks;

删除已添加的视频水印

返回值

0方法调用成功，<0方法调用失败。

直播音视频流回退

setRemoteSubscribeFallbackOption

- (int)setRemoteSubscribeFallbackOption:(ARStreamFallbackOptions)option;

开关视频双流模式

网络不理想的环境下，订阅音视频的质量都会下降。使用该接口开启订阅音视频流的回退选项后，SDK会在下行弱网且音视频质量严重受影响时，将视频流切换为小流，或关断视频流，从而保证或提高通信质量。同时 SDK 会持续监控网络质量，并在网络质量改善时恢复音视频流。当远端订阅流回退为音频流时，或由音频流恢复为音视频流时，SDK 会触发远端订阅流已回退为音频流回调。

返回值

0方法调用成功，<0方法调用失败。

视频双流模式

enableDualStreamMode

- (int)enableDualStreamMode:(BOOL)enabled;

开关视频双流模式

返回值

0方法调用成功，<0方法调用失败。

setRemoteVideoStream

- (int)setRemoteVideoStream:(NSString *_Nonnull)uid type:(ARVideoStreamType)streamType;

设置订阅的视频流类型

如果发送端选择发送视频双流（大流或小流），接收端可以选择接收大流还是小流。其中大流可以理解为高分辨率高码率的视频流，小流则是低分辨率低码率的视频流。该方法可以根据视频窗口的大小动态调整对应视频流的大小，以节约带宽和计算资源。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

请确保在调用其他 API 前先调用该方法创建并初始化 ARtcEngineKit。 一个 ARtcEngineKit 实例对象只能使用一个 App ID。如需更换 App ID，必须先调用 destroy 销毁当前实例，再调用本方法重新创建实例。

setRemoteDefaultVideoStreamType

- (int)setRemoteDefaultVideoStreamType:(ARVideoStreamType)streamType;

设置默认订阅的视频流类型

返回值

0方法调用成功，<0方法调用失败。

直播输入在线媒体流

addInjectStreamUrl

- (int)addInjectStreamUrl:(NSString * _Nonnull)url config:(ARLiveInjectStreamConfig * _Nonnull)config;

输入在线媒体流 URL

该方法通过在服务端拉取视频流并发送到频道中，将正在播放的视频输入到正在进行的直播中。可主要应用于赛事直播、多人看视频互动等直播场景。 调用该方法后，SDK 会在本地触发 streamInjectedStatusOfUrl 回调，报告输入在线媒体流的状态。 成功输入媒体流后，该音视频流会出现在频道中，频道内所有用户都会收到 didJoinedOfUid 回调，其中 uid 为 "share666"。

注意事项：

• 频道内同一时间只允许输入一个在线媒体流。
• 请确保已开通旁路推流的功能，详见前提条件。

返回值

0方法调用成功，<0方法调用失败。

• ARErrorCodeInvalidArgument(-2)：输入的 URL 为空。请重新调用该方法，并确认输入的媒体流的 URL 是有效的。
• ARErrorCodeNotInitialized(-7)：引擎没有初始化。请确认调用该方法前已创建 RtcEngine 对象并完成初始化。
• ARErrorCodeNotSupported(-4)：频道非直播场景。请调用 setChannelProfile 并将频道设置为直播场景再调用该方法。
• ARErrorCodeNotReady(-3)：用户没有加入频道。

removeInjectStreamUrl

- (int)removeInjectStreamUrl:(NSString * _Nonnull)url;

删除输入的在线媒体流

成功删除后会触发 didOfflineOfUid(ARUserOfflineReasonBecomeAudience) 回调，UID 为 "share666"。

返回值

0方法调用成功，<0方法调用失败

其它视频控制

setCameraCapturerConfiguration

- (int)setCameraCapturerConfiguration:(ARCameraCapturerConfiguration * _Nullable)configuration;

设置摄像头采集偏好

一般的视频通话或直播中，默认由 SDK 自动控制摄像头的输出参数。在如下特殊场景中，默认的参数通常无法满足需求，或可能引起设备性能问题，我们推荐调用该方法设置摄像头的采集偏好：

• 使用原始音视频数据自采集接口时，如果 SDK 输出的分辨率和帧率高于setVideoEncoderConfiguration 中指定的参数，在后续处理视频帧的时候，比如美颜功能时，会需要更高的 CPU 及内存，容易导致性能问题。在这种情况下，我们推荐将摄像头采集偏好设置为 ARCameraCaptureOutputPreferencePerformance(1)，避免性能问题。
• 如果没有本地预览功能或者对预览质量没有要求，我们推荐将采集偏好设置为 ARCameraCaptureOutputPreferencePerformance(1)，以优化 CPU 和内存的资源分配。
• 如果用户希望本地预览视频比实际编码发送的视频清晰，可以将采集偏好设置为 ARCameraCaptureOutputPreferencePreview(2)。

返回值

0方法调用成功，<0方法调用失败。

摄像头控制

switchCamera

- (int)switchCamera;

切换前置/后置摄像头

返回值

0方法调用成功，<0方法调用失败。

注意事项： 本方法仅适用于 iOS 平台，不适用于 macOS。

isCameraZoomSupported

- (BOOL)isCameraZoomSupported;

检测设备是否支持摄像头缩放功能

返回值

YES: 设备支持摄像头缩放功能; NO: 设备不支持摄像头缩放功能。

isCameraTorchSupported

- (BOOL)isCameraTorchSupported;

检测设备是否支持闪光灯常开

返回值

YES: 设备支持闪光灯常开; NO: 设备不支持闪光灯常开。

注意事项：

• 本方法仅适用于 iOS 平台，不适用于 macOS。
• 一般情况下，App 默认开启前置摄像头，因此如果你的前置摄像头不支持闪光灯常开，直接使用该方法会返回 NO。如果需要检查后置摄像头是否支持闪光灯常开，需要先使用 switchCamera 切换摄像头，再使用该方法。

isCameraFocusPositionInPreviewSupported

- (BOOL)isCameraFocusPositionInPreviewSupported;

检测设备是否支持手动对焦功能

返回值

YES: 设备支持手动对焦功能; NO: 设备不支持手动对焦功能。

注意事项：

• 本方法仅适用于 iOS 平台，不适用于 macOS。

isCameraExposurePositionSupported

- (BOOL)isCameraExposurePositionSupported;

检测设备是否支持手动曝光功能

返回值

YES: 设备支持手动曝光功能；NO: 设备不支持手动曝光功能。

注意事项：

• 本方法仅适用于 iOS 平台，不适用于 macOS。

isCameraAutoFocusFaceModeSupported

- (BOOL)isCameraAutoFocusFaceModeSupported;

检测设备是否支持人脸对焦功能

返回值

YES: 设备支持人脸对焦功能；NO: 设备不支持人脸对焦功能。

注意事项：

• 本方法仅适用于 iOS 平台，不适用于 macOS。

setCameraZoomFactor

- (CGFloat)setCameraZoomFactor:(CGFloat)zoomFactor;

设置摄像头缩放比例

返回值

设置成功返回设置的 factor 值，设置失败返回 < 0

注意事项： 本方法仅适用于 iOS 平台，不适用于 macOS。

setCameraFocusPositionInPreview

- (BOOL)setCameraFocusPositionInPreview:(CGPoint)position;

设置手动对焦位置，并触发对焦

返回值

YES方法调用成功，NO方法调用失败

注意事项： 本方法仅适用于 iOS 平台，不适用于 macOS。成功调用该方法后，本地会触发 cameraFocusDidChangedToRect 回调。

setCameraExposurePosition

- (BOOL)setCameraExposurePosition:(CGPoint)positionInView;

设置摄像头曝光位置

返回值

YES方法调用成功，NO方法调用失败

注意事项： 本方法仅适用于 iOS 平台，不适用于 macOS。成功调用该方法后，本地会触发 cameraExposureDidChangedToRect 回调。

setCameraTorchOn

- (BOOL)setCameraTorchOn:(BOOL)isOn;

设置是否打开闪光灯

返回值

YES方法调用成功，NO方法调用失败

setCameraAutoFocusFaceModeEnabled

- (BOOL)setCameraAutoFocusFaceModeEnabled:(BOOL)enable;

设置是否开启人脸对焦功能

返回值

YES方法调用成功，NO方法调用失败

网络相关测试

startEchoTestWithInterval

- (int)startEchoTestWithInterval:(NSInteger)interval successBlock:(void(^ _Nullable)(NSString * _Nonnull channel, NSString * _Nonnull uid, NSInteger elapsed))successBlock;

开始语音通话回路测试

该方法启动语音通话测试，目的是测试系统的音频设备（耳麦、扬声器等）和网络连接是否正常。在测试过程中，用户先说一段话，声音会在设置的时间间隔后回放出来。如果用户能正常听到自己刚才说的话，就表示系统音频设备和网络连接都是正常的。

Note:

• 请在加入频道前调用该方法。

• 调用该方法后必须调用 stopEchoTest 以结束测试，否则不能进行下一次回声测试，也无法加入频道。

• 直播场景下，该方法仅能由用户角色为主播的用户调用。

返回值

0方法调用成功，<0方法调用失败

stopEchoTest

- (int)stopEchoTest;

停止语音通话回路测试

返回值

0方法调用成功，<0方法调用失败,如 ERR_REFUSED (-5)：不能停止测试，可能语音通话测试没有成功启动。

enableLastmileTest

- (int)enableLastmileTest;

启动网络测试

该方法启用网络连接质量测试，用于检测用户网络接入质量。默认该功能为关闭状态。

该方法主要用于以下场景:

• 用户加入频道前，可以调用该方法判断和预测目前的上行网络质量是否足够好。
• 直播场景下，当用户角色想由观众切换为主播时，可以调用该方法判断和预测目前的上行网络质量是否足够好。

启用该方法会消耗一定的网络流量，影响通话质量，因此我们建议不要和 startLastmileProbeTest 同时使用。

在收到 lastmileQuality 回调后须调用 disableLastmileTest 停止测试，再加入频道或切换用户角色。

Note:

• 调用该方法后，在收到 lastmileQuality 回调之前请不要调用其他方法，否则可能会由于 API 操作过于频繁导致此回调无法执行。
• 直播场景下，主播在加入频道后请勿调用该方法。
• 加入频道前调用该方法检测网络质量后，SDK 会占用一路视频的带宽，码率与 setVideoEncoderConfiguration 中设置的码率相同。加入频道后，无论是否调用了 disableLastmileTest，SDK 均会自动停止带宽占用。

返回值

0方法调用成功，<0方法调用失败

disableLastmileTest

- (int)disableLastmileTest;

关闭网络测试

返回值

0方法调用成功，<0方法调用失败

startLastmileProbeTest

- (int)startLastmileProbeTest:(ARLastmileProbeConfig *_Nullable)config;

开始通话前网络质量探测

开始通话前网络质量探测，向用户反馈上下行网络的带宽、丢包、网络抖动和往返时延数据。

启用该方法后，SDK 会依次返回如下 2 个回调：

lastmileQuality，视网络情况约 2 秒内返回。该回调通过打分反馈上下行网络质量，更贴近用户的主观感受。 lastmileProbeResult，视网络情况约 30 秒内返回。该回调通过具体数据反馈上下行网络质量，更加客观。 该方法主要用于以下两种场景：

• 用户加入频道前，可以调用该方法判断和预测目前的上行网络质量是否足够好。
• 直播场景下，当用户角色想由观众切换为主播时，可以调用该方法判断和预测目前的上行网络质量是否足够好。

Note:

• 该方法会消耗一定的网络流量，影响通话质量，因此我们建议不要和 enableLastmileTest 同时使用。
• 调用该方法后，在收到 lastmileQuality 和 lastmileProbeResult 回调之前请不要调用其他方法，否则可能会由于 API 操作过于频繁导致此方法无法执行。
• 直播场景下，如果本地用户为主播，请勿在加入频道后调用该方法。

返回值

0方法调用成功，<0方法调用失败

stopLastmileProbeTest

- (int)stopLastmileProbeTest;

停止通话前网络质量探测

返回值

0方法调用成功，<0方法调用失败

加密

enableEncryption

- (int)enableEncryption:(bool)enabled encryptionConfig:(AREncryptionConfig *)config;

在安全要求较高的场景下，建议你在加入频道前，调用 enableEncryption 方法开启内置加密。

同一频道内所有用户必须使用相同的加密模式和密钥。一旦所有用户都离开频道，该频道的加密密钥会自动清除。

Note

• 如果开启了内置加密，则不能使用 RTMP/RTMPS 推流功能。
• anyRTC 支持 4 种加密模式。除 SM4_128_ECB 模式外，其他加密模式都需要在集成 iOS SDK 时，额外添加加密库文件。详见《媒体流加密》。

返回值

0方法调用成功，<0方法调用失败

-2 (ARErrorCodeInvalidArgument): 调用了无效的参数。需重新指定参数。 -7 (ARErrorCodeNotInitialized): SDK 尚未初始化。需在调用 API 之前已创建 ARRtcEngineKit 对象并完成初始化。 -4 (ARErrorCodeNotSupported): 设置的加密模式不正确或加载外部加密库失败。需检查枚举值是否正确或重新加载外部加密库。

CDN 旁路推流

addPublishStreamUrl

- (int)addPublishStreamUrl:(NSString * _Nonnull)url transcodingEnabled:(BOOL)transcodingEnabled;

增加旁路推流地址

该方法用于添加旁路推流地址，调用该方法后，SDK 会在本地触发 rtmpStreamingChangedToState 回调，报告增加旁路推流地址的状态。

Note:

• 该方法仅适用于直播场景。
• 请确保在成功加入频道后再调用该接口。
• 请确保已开通旁路推流的功能
• 该方法每次只能增加一路旁路推流地址。若需推送多路流，则需多次调用该方法

返回值

0方法调用成功，<0方法调用失败

• ARErrorCodeInvalidArgument(-2)：参数无效，一般是 URL 为空或是长度为 0 的的字符串
• ARErrorCodeNotInitialized(-7)：推流时未初始化引擎

removePublishStreamUrl

- (int)removePublishStreamUrl:(NSString * _Nonnull)url;

删除旁路推流地址

该方法用于删除旁路推流过程中已经设置的 RTMP 推流地址。调用该方法后，SDK 会在本地触发 rtmpStreamingChangedToState 回调，报告删除旁路推流地址的状态。

Note:

• 该方法仅适用于直播场景。
• 该方法每次只能删除一路旁路推流地址。若需删除多路流，则需多次调用该方法。
• URL 不支持中文等特殊字符。

返回值

0方法调用成功，<0方法调用失败

setLiveTranscoding

- (int)setLiveTranscoding:(ARLiveTranscoding *_Nullable)transcoding;

设置直播转码

该方法用于旁路推流的视图布局及音频设置等。调用该方法更新转码设置后本地会触发 rtcEngineTranscodingUpdated 回调。

Note

• 该方法仅适用于直播场景。
• 请确保已开通 CDN 旁路推流的功能
• 首次调用该方法更新转码设置时，不会触发 rtcEngineTranscodingUpdated 回调。

返回值

0方法调用成功，<0方法调用失败

其它方法

takeSnapshot

- (NSInteger)takeSnapshot:(NSString* _Nonnull)uid filePath:(NSString* _Nonnull)filePath;

获取视频截图

该方法用于对指定用户的视频流进行截图，生成一张 JPG 格式的图片，并保存至指定的路径。

该方法是异步操作，调用返回时 SDK 并没有真正获取截图。成功调用该方法后，SDK 会触发 snapshotTaken 回调报告截图是否成功和获取截图的详情。

Note

• 该方法需要在加入频道后调用。
• 该方法对 ARtcChannelMediaOptions 中指定发布的视频流进行截图。
• 如果用户的视频经过前处理，例如，添加了水印或美颜，生成的截图会包含前处理效果。

返回值

0方法调用成功，<0方法调用失败

getCallId

- (NSString * _Nullable)getCallId;

获取通话 ID

客户端在每次 joinChannelByToken 后会生成一个对应的 CallId，标识该客户端的此次通话。有些方法如 rate，complain需要在通话结束后调用，向 SDK 提交反馈，这些方法必须指定 CallId 参数。使用这些反馈方法，需要在通话过程中调用 getCallId 方法获取 CallId，在通话结束后在反馈方法中作为参数传入。

返回值

当前通话 ID

enableMainQueueDispatch

- (int)enableMainQueueDispatch:(BOOL)enabled;

分发／不分发回调至主队列

如果不分发回调方法到主队列， App 应将 UI 操作分发到主队列。

返回值

0方法调用成功，<0方法调用失败。

getSdkVersion

+ (NSString * _Nonnull)getSdkVersion;

查询 SDK 版本号

返回值

当前的 SDK 版本号，格式为字符串，如 4.0.0

getErrorDescription

+ (NSString * _Nullable)getErrorDescription:(NSInteger)code;

获取警告或错误描述

如果不分发回调方法到主队列， App 应将 UI 操作分发到主队列。

返回值

警告或错误描述。

setLogFile

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

设置日志文件路径

设置 SDK 的输出 log 文件。SDK 运行时产生的所有 log 将写入该文件。 App 必须保证指定的目录存在而且可写。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

• 日志文件的默认地址如下:
  • iOS: App Sandbox/Library/caches/ar_sdk.log
  • macOS
    • 开启沙盒: App Sandbox/Library/Logs/ar_sdk.log, 例如 /Users/<username>/Library/Containers/<App Bundle Identifier>/Data/Library/Logs/ar_sdk.log.
    • 关闭沙盒: ～/Library/Logs/ar_sdk.log.
• 如需调用本方法，请在调用 sharedEngineWithAppId 方法初始化 ARtcEngineKit 对象后立即调用，否则可能造成输出日志不完整。

setLogFileSize

- (int)setLogFileSize:(NSUInteger)fileSizeInKBytes;

设置日志文件大小

设置 SDK 输出的日志文件大小，单位为 KB。

SDK 设有 2 个日志文件，每个文件大小为 512 KB。如果你将 fileSizeInKByte 设置为 1024 KB， SDK 会最多输出 2 MB 的日志文件。如果日志文件大小超出设置值，新的日志会覆盖之前的日志。

返回值

0方法调用成功，<0方法调用失败。有可能是因为传入的参数无效。

setLogFilter

- (int)setLogFilter:(ARLogFilter)filter;

设置日志输出等级

返回值

0方法调用成功，<0方法调用失败。

getNativeHandle

- (void *_Nullable)getNativeHandle;

获取 Native SDK Engine Handle

该方法获取 native SDK engine 的 C++ handle，用于包括注册音视频帧观测器在内的特殊场景。

返回值

0方法调用成功，<0方法调用失败。

delegate

@property (nonatomic, weak) id<ARtcEngineDelegate> _Nullable delegate;

设置／获取 ARtcEngineDelegate

ar云平台 Native SDK 通过指定的 delegate 通知 App 引擎运行时的事件。Delegate 中定义的所有方法都是可选实现的。

定制方法

setParameters:

- (int)setParameters:(NSString * _Nonnull)options;

通过 JSON 配置 SDK 提供技术预览或特别定制功能

返回值

0方法调用成功，<0方法调用失败。

注意事项： JSON 选项默认不公开。

getParameter

- (NSString * _Nullable)getParameter:(NSString * _Nonnull)parameter args:(NSString * _Nullable)args;

获取 ar云平台 SDK 可供自定义的参数

注意事项： 该方法未公开，请联系ar云平台支持 hi@dync.cc 获取详情。