Discussion

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

Note

• 请确保在调用其他 API 前先调用该方法创建并初始化 AgoraRtcEngineKit。
• 调用该方法和 sharedEngineWithConfig 均能创建 AgoraRtcEngineKit 实例。该方法与 sharedEngineWithConfig 的区别在于，sharedEngineWithConfig 支持在创建 AgoraRtcEngineKit 实例时指定访问区域。
• 目前声网 RTC Native SDK 只支持每个 app 创建一个 AgoraRtcEngineKit 实例。

Discussion

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

Note

• 请确保在调用其他 API 前先调用该方法创建并初始化 AgoraRtcEngineKit。
• 调用该方法和 sharedEngineWithAppId 均能创建 AgoraRtcEngineKit 实例。该方法与 sharedEngineWithAppId 的区别在于，该方法支持在创建 AgoraRtcEngineKit 实例时指定访问区域。
• 目前声网 RTC Native SDK 只支持每个 app 创建一个 AgoraRtcEngineKit 实例。

Discussion

该方法释放 SDK 使用的所有资源。有些 app 只在用户需要时才进行实时音视频通信，不需要时则将资源释放出来用于其他操作，该方法适用于此类情况。调用 destroy 方法后，你将无法再使用 SDK 的其它方法和回调。如需再次使用实时音视频通信功能，你必须重新调用 sharedEngineWithAppId 方法创建一个新的 AgoraRtcEngineKit 实例。

Note:

• 该方法为同步调用，需要等待 AgoraRtcEngineKit 实例资源释放后才能执行其他操作，所以我们建议在子线程中调用该方法，避免主线程阻塞。此外，我们不建议 在 SDK 的回调中调用 destroy，否则由于 SDK 要等待回调返回才能回收相关的对象资源，会造成死锁。
• 如需在销毁后再次创建 AgoraRtcEngineKit 实例，需要等待destroy` 方法执行结束后再创建实例。

Discussion

SDK 初始化后默认的频道场景为通信场景，AgoraRtcEngineKit 会针对不同的使用场景采用不同的优化策略， 如通信场景偏好流畅，直播场景偏好画质。

Note:

• 为保证实时音视频质量，我们建议相同频道内的用户使用同一种频道场景。
• 该方法必须在加入频道前调用，进入频道后无法再设置频道场景。
• 不同的频道场景下，SDK 的默认音频路由和默认视频编码码率是不同的，详见 setDefaultAudioRouteToSpeakerphone 和 setVideoEncoderConfiguration 中的说明。

Discussion

调用 setChannelProfile(AgoraChannelProfileLiveBroadcasting) 后，SDK 会默认设置用户角色为观众，你可以调用 setClientRole 设置用户角色为主播。

该方法在加入频道前后均可调用。如果你在加入频道后调用该方法切换用户角色，调用成功后，SDK 会自动进行如下操作：

• 调用 muteLocalAudioStream 和 muteLocalVideoStream 修改发布状态。
• 本地触发 didClientRoleChanged 或 didClientRoleChangeFailed 。
• 远端触发 didJoinedOfUid 或 didOfflineOfUid(AgoraUserOfflineReasonBecomeAudience)。

Discussion

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

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

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

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

用户成功加入频道后，默认订阅频道内所有其他用户的音频流和视频流，因此产生用量并影响计费。如果想取消订阅，可以通过调用相应的 mute 方法实现。

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

Note:

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

Discussion

该方法允许本地用户使用 User Account 加入频道。成功加入频道后，会触发以下回调：

• 本地：didRegisteredLocalUser 和 didJoinChannel 回调
• 远端：通信场景下的用户和直播场景下的主播加入频道后，远端会依次触发 didJoinedOfUid 和 didUpdatedUserInfo 回调

用户成功加入频道后，默认订阅频道内所有其他用户的音频流和视频流，因此产生用量并影响计费。如果想取消订阅，可以通过调用相应的 mute 方法实现。

Note

• 请确保在使用 String 型用户名前阅读如何使用 String 型用户 ID，了解使用限制及实现方法。
• 为保证通信质量，请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Web SDK 加入频道，请确保 Web 加入的用户也是同样类型。

Discussion

该方法为本地用户注册一个 User Account。注册成功后，该 User Account 即可标识该本地用户的身份，用户可以使用它加入频道。成功注册 User Account 后，本地会触发 didRegisteredLocalUser 回调，告知本地用户的 UID 和 User Account。

该方法为可选。如果你希望用户使用 User Account 加入频道，可以选用以下两种方式：

• 先调用 registerLocalUserAccount 方法注册 User Account，再调用 joinChannelByUserAccount 方法加入频道
• 直接调用 joinChannelByUserAccount 方法加入频道

两种方式的区别在于，提前调用 registerLocalUserAccount，可以缩短使用 joinChannelByUserAccount 进入频道的时间。

Note：

• userAccount 不能为空，否则该方法不生效。
• 请确保在该方法中设置的 userAccount 在频道中的唯一性。
• 为保证通信质量，请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Web SDK 加入频道，请确保 Web 加入的用户也是同样类型。

Discussion

远端用户加入频道后，SDK 会获取到该用户的 UID 和 User Account，然后缓存一个包含了远端用户 UID 和 User Account 的映射表，并在本地触发 didUpdatedUserInfo 回调。

收到这个回调后，你可以调用该方法，通过传入 User Account 获取包含了指定用户 UID 的 AgoraUserInfo 对象。

Discussion

远端用户加入频道后，SDK 会获取到该用户的 UID 和 User Account，然后缓存一个包含了用户 UID 和 User Account 的映射表，并在本地触发 didUpdatedUserInfo 回调。

收到这个回调后，你可以调用该方法，通过传入 UID 获取包含了指定用户 User Account 的 AgoraUserInfo 对象。

Discussion

当直播频道中的观众想从一个频道切换到另一个频道时，可以调用该方法，实现快速切换。

成功调用该方切换频道后，本地会先收到离开原频道的回调 didLeaveChannelWithStats，再收到成功加入新频道的回调 didJoinChannel。

用户成功切换频道后，默认订阅频道内所有其他用户的音频流和视频流，因此产生用量并影响计费。如果想取消订阅，可以通过调用相应的 mute 方法实现。

Discussion

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

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

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

Note:

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

Discussion

Discussion

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

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

App 应重新获取 Token，然后调用该 API 更新 Token，否则 SDK 无法和服务器建立连接。

Discussion

该方法在加入频道前后都能调用。

Discussion

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

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

Note

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

Discussion

成功调用该方法后，SDK 会触发 didReceiveChannelMediaRelayEvent 回调，并在回调中报告状态码 AgoraChannelMediaRelayEventUpdateDestinationChannel(7)。

Note

• 请在成功调用 startChannelMediaRelay 方法并收到 channelMediaRelayStateDidChange (AgoraChannelMediaRelayStateRunning, AgoraChannelMediaRelayErrorNone) 后调用该方法；否则，方法调用会失败。
• 跨频道媒体流转发最多支持 4 个目标频道。如果直播间里已经有 4 个频道了，你可以在调用该方法之前，调用 AgoraChannelMediaRelayConfiguration 中的 removeDestinationInfoForChannelName 方法移除不需要的频道。

Discussion

Discussion

Discussion

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

Discussion

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

Note:

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

• 该方法开启整个音频模块，响应速度较慢，因此声网建议使用如下方法来控制音频模块：

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

Discussion

Note:

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

• 该方法关闭整个音频模块，响应速度较慢，因此声网建议使用如下方法来控制音频模块：

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

Discussion

Note:

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

Discussion

该方法在加入频道前后都能调用。

Discussion

Discussion

该方法在加入频道前后都能调用。

Note

• 该方法调节的是本地播放的所有远端用户混音后的音量。
• 从 v2.3.2 开始，静音本地音频需同时调用 adjustPlaybackSignalVolume 和 adjustAudioMixingPlayoutVolume 方法，并将 volume 参数设置为 0。

Discussion

该方法允许 SDK 定期向 app 报告本地发流用户和瞬时音量最高的远端用户（最多 3 位）的音量相关信息。启用该方法后，只要频道内有发流用户，SDK 会在加入频道后按设置的时间间隔触发 reportAudioVolumeIndicationOfSpeakers 回调。

该方法在加入频道前后都能调用。

Discussion

Discussion

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

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

语音功能关闭或重新开启后，会收到 localAudioStateChange 回调并报告 AgoraAudioLocalStateStopped(0) 或 AgoraAudioLocalStateRecording(1)。

Note:

• 该方法在加入频道前后均可调用。在加入频道前调用只能设置设备状态，在加入频道后才会立即生效。

• 该方法与 muteLocalAudioStream 的区别在于：

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

Discussion

自 v3.4.5 起，该方法仅设置用户在 AgoraRtcEngineKit 频道中的音频发布状态。

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

同一时间，本地的音视频流只能发布到一个频道。如果你创建了多个频道，请确保你只在一个频道中调用 muteLocalAudioStream(NO)，否则方法会调用失败并返回 -5 (AgoraErrorCodeRefused)。

Note：

• 该方法不会改变音频采集设备的使用状态。
• 该方法的调用是否生效受 joinChannelByToken 和 setClientRole 方法的影响，详见《设置发布状态》。

Discussion

Note

• 该方法需要在加入频道后调用。
• 该方法的推荐设置详见《设置订阅状态》。

Discussion

成功调用该方法后，本地用户会取消或恢复订阅所有远端用户的音频流， 包括在调用该方法后加入频道的用户的音频流。

Note

• 该方法需要在加入频道后调用。
• 自 v3.3.0 起，该方法包含了 setDefaultMuteAllRemoteAudioStreams 的功能。声网建议不要一起调用 muteAllRemoteAudioStreams 和 setDefaultMuteAllRemoteAudioStreams，否则设置可能会不生效。详见《设置订阅状态》。

Discussion

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

Note

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

Discussion

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

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

Note:

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

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

  • enableLocalVideo：是否启动摄像头采集并创建本地视频流
  • muteLocalVideoStream：是否发布本地视频流
  • muteRemoteVideoStream：是否接收并播放远端视频流
  • muteAllRemoteVideoStreams：是否接收并播放所有远端视频流

Discussion

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

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

Note:

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

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

  • enableLocalVideo：是否启动摄像头采集并创建本地视频流
  • muteLocalVideoStream：是否发布本地视频流
  • muteRemoteVideoStream：是否接收并播放远端视频流
  • muteAllRemoteVideoStreams：是否接收并播放所有远端视频流

Discussion

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

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

该方法在加入频道前后都能调用。

Note:

在 v2.3.0 版本中，如下接口已废弃，声网不再推荐使用:

• setVideoProfile
• setVideoResolution

Discussion

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

该方法在加入频道前后都能调用。

Note

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

Discussion

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

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

Discussion

自从 v3.0.0

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

Note

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

Discussion

自从 v3.0.0

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

Note

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

Discussion

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

调用该 API 前，必须

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

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

Discussion

调用 startPreview 后，如果你想关闭本地视频预览， 请调用 stopPreview。

Discussion

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

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

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

该方法在加入频道前后都能调用。

Note:

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

Discussion

自 v3.4.5 起，该方法仅设置用户在 AgoraRtcEngineKit 频道中的视频发布状态。

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

同一时间，本地的音视频流只能发布到一个频道。如果你创建了多个频道，请确保你只在一个频道中调用 muteLocalVideoStream(NO)，否则方法会调用失败并返回 -5 (AgoraErrorCodeRefused)。

Note：

• 该方法不会改变视频采集设备的使用状态。
• 该方法的调用是否生效受 joinChannelByToken 和 setClientRole 方法的影响，详见《设置发布状态》。

Discussion

成功调用该方法后，本地用户会取消或恢复订阅所有远端用户的视频流， 包括在调用该方法后加入频道的用户的视频流。

Note

• 该方法需要在加入频道后调用。
• 自 v3.3.0 起，该方法包含了 setDefaultMuteAllRemoteVideoStreams 的功能。声网建议不要一起调用 muteAllRemoteVideoStreams 和 setDefaultMuteAllRemoteVideoStreams，否则设置可能会不生效。详见《设置订阅状态》。

Discussion

Note

• 该方法需要在加入频道后调用。
• 该方法的推荐设置详见《设置订阅状态》。

Discussion

开启本地美颜功能，并设置美颜效果选项。

Note:

• 请在调用 enableVideo 方法后，调用该方法。
• 声网从 3.6.0 版起更新了基础美颜算法，能提升基础美颜效果并支持锐度调节功能。如果你想体验优化后的基础美颜效果或设置锐度，请在调用该方法前，将 AgoraVideoProcessExtension.xcframework 动态库集成到项目文件中。

Discussion

Discussion

自从: v3.0.1.

开启本地人脸检测后，SDK 会触发 facePositionDidChangeWidth 回调向你报告人脸检测的信息：

• 摄像头采集的画面大小
• 人脸在 View 中的位置
• 人脸距设备屏幕的距离

Note

• 该方法在加入频道前后都能调用。
• 该方法仅使用于 iOS 平台。

Discussion

如果 SDK 默认的音频路由（见《设置音频路由》）无法满足你的需求， 你可以调用该方法切换默认的音频路由。成功切换音频路由后，SDK 会触发 didAudioRouteChanged 回调提示音频路由已更改。

Note

• 该方法仅适用于 iOS 平台。
• 该方法需要在 joinChannelByToken 前调用。如需在加入频道后切换音频路由，请调用 setEnableSpeakerphone。
• 如果用户使用了蓝牙耳机、有线耳机等外接音频播放设备，则该方法的设置无效， 音频只会通过外接设备播放。当有多个外接设备时，音频会通过最后一个接入的设备播放。

Discussion

如果 SDK 默认的音频路由（见《设置音频路由》）或 setDefaultAudioRouteToSpeakerphone 的设置无法满足你的需求，你可以调用 setEnableSpeakerphone 切换当前的音频路由。 成功切换音频路由后，SDK 会触发 didAudioRouteChanged 回调提示音频路由已更改。

该方法只设置用户在当前频道内使用的音频路由，不会影响 SDK 默认的音频路由。 如果用户离开当前频道并加入新的频道，则用户还是会使用 SDK 默认的音频路由。

Note

• 该方法仅适用于 iOS 平台。
• 该方法需要在 joinChannelByToken 后调用。
• 如果用户使用了蓝牙耳机、有线耳机等外接音频播放设备，则该方法的设置无效， 音频只会通过外接设备播放。当有多个外接设备时，音频会通过最后一个接入的设备播放。

Discussion

该方法仅适用于 iOS。 该方法在加入频道前后都能调用。

Discussion

该方法在加入频道前后都能调用。

Note

• 该方法仅适用于 iOS 平台。
• 用户必须使用耳机（有线和蓝牙均可）才能听到耳返效果。

Discussion

该方法在加入频道前后都能调用。

Note

• 该方法仅适用于 iOS 平台。
• 用户必须使用耳机（有线和蓝牙均可）才能听到耳返效果。

Discussion

该方法改变本地说话人声音的音调。该方法在加入频道前后都能调用。

Discussion

该方法在加入频道前后都能调用。

Discussion

SDK 在 v3.2.0 版本中提供一个使用更为简便的方法 setAudioEffectPreset，直接实现流行、R&B、KTV 等预置的混响效果。

该方法在加入频道前后都能调用。

Discussion

如果想调用 setRemoteVoicePosition 实现听声辨位的功能，请确保在加入频道前调用本方法开启远端用户的语音立体声。

Discussion

设置远端用户声音的空间位置和音量，方便本地用户听声辨位。

通过调用该接口设置远端用户声音出现的位置，左右声道的声音差异会产生声音的方位感，从而判断出远端用户的实时位置。在多人在线游戏场景，如吃鸡游戏中，该方法能有效增加游戏角色的方位感，模拟真实场景。

Note:

• 该方法需要在加入频道后调用。使用该方法需要在加入频道前调用 enableSoundPositionIndication 开启远端用户的语音立体声

• 为获得最佳听觉体验，我们建议：

  • 在 iOS 使用该方法时佩戴有线耳机
  • 在 macOS 使用该方法时使用立体声外放

Discussion

Discussion

请在频道内调用该方法。

Discussion

请在频道内调用该方法。

Discussion

请在频道内调用该方法。

Discussion

该方法调节混音的音乐文件在本地和远端播放的音量大小。该方法需要在 startAudioMixing 后调用。

Note:

• 调用该方法不影响调用 playEffect 播放音效文件的音量。
• 你需要在调用 startAudioMixing 并收到 localAudioMixingStateDidChanged(AgoraAudioMixingStatePlaying) 回调后调用该方法。

Discussion

该方法调节混音的音乐文件在本地播放的音量大小。该方法需要在 startAudioMixing 后调用。

Discussion

该方法调节混音的音乐文件在远端播放的音量大小。该方法需要在 startAudioMixing 后调用。

Discussion

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

Discussion

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

Discussion

Note：

• 你需要在调用 startAudioMixing 并收到 localAudioMixingStateDidChanged(AgoraAudioMixingStatePlaying) 回调后调用该方法。
• 如需多次调用 getAudioMixingCurrentPosition，请确保调用间隔大于 500 ms。

Discussion

该方法可以设置音频文件的播放位置，这样你可以根据实际情况播放文件，而不是非得从头到尾播放一个文件。该方法需要在 startAudioMixing 后调用。

Discussion

自从： v3.0.1.

本地人声和播放的音乐文件混音时，调用该方法可以仅调节音乐文件的音调。

Discussion

该方法需要在 playEffect 后调用。

Discussion

该方法需要在 playEffect 后调用。

Discussion

该方法需要在 playEffect 后调用。

Discussion

你可以多次调用该方法，传入不同的 soundId 和 filePath，同时播放多个音效文件。为获得最佳用户体验，声网推荐同时播放的音效文件不超过 3 个。

音效文件播放结束后，SDK 会触发 rtcEngineDidAudioEffectFinish 回调。

Note

• 该方法需要在加入频道后调用。
• 该方法支持的音频文件格式见 声网 RTC SDK 支持播放哪些格式的音频文件。
• 如果你需要通过 playEffect 播放在线音效文件，声网建议你将在线音效文件缓存到本地设备，调用 preloadEffect 将音效加载至内存，确保这里设置的 soundId 与 preloadEffect 将缓存的音效文件预加载到内存中，再调用 playEffect 播放音效。否则，可能出现因在线音效文件加载超时、加载失败而导致的播放失败和无声的问题。

Discussion

Note

• 该方法不支持在线音效文件。
• 该方法支持的音频文件格式见 声网 RTC SDK 支持播放哪些格式的音频文件。
• 为保证通信畅通，请注意控制预加载音效文件的大小。
• 该方法在加入频道前后均可调用。

Discussion

Discussion

Discussion

Discussion

Discussion

启用声卡采集功能后，声卡播放的音频会被合到本地音频流中，从而可以发送到远端。

Note:

• 该方法在加入频道后调用。
• macOS 系统默认声卡不支持采集功能，如果你需要使用该功能，请启用一个虚拟声卡，并将该虚拟声卡的名字传入 deviceName 参数。声网推荐你启用 AgoraALD (Agora Audio Loopback Device) 并向该参数传入 "AgoraALD"。

Discussion

在默认情况下，SDK 和 app 对 Audio Session 都有操作权限。如果你只需使用 app 对 Audio Session 进行操作，你可以调用该方法限制 SDK 对 Audio Session 的操作权限。

该方法在加入频道前后都能调用。一旦调用该方法限制了 SDK 对 Audio Session 的操作权限，该限制会在 SDK 需要更改 Audio Session 时生效。

Note:

• 该方法仅适用于 iOS 平台。
• 该方法不会限制 app 对 Audio Session 的操作权限。

Discussion

SDK 默认开启传统降噪模式，以消除大部分平稳噪声。如果你还需要消除非平稳噪声，声网推荐你按如下步骤开启 AI 降噪模式：

1. 确保已集成 AgoraAIDenoiseExtension.xcframework 库：

2. 调用 enableDeepLearningDenoise(YES)。

AI 降噪模式对设备性能有要求。只有在设备性能良好的情况下，SDK 才会成功开启 AI 降噪模式。支持在如下设备及其之后的型号中开启 AI 降噪模式：

• iPhone 6S
• MacBook Pro 2015
• iPad Pro 第二代
• iPad mini 第五代
• iPad Air 第三代

成功开启 AI 降噪模式后，如果 SDK 检测到当前设备的性能不足，SDK 会自动关闭 AI 降噪模式，并开启传统降噪模式。

在频道内，如果你调用了 enableDeepLearningDenoise(NO) 或 SDK 自动关闭了 AI 降噪模式，当你需要重新开启 AI 降噪模式时， 你需要先调用 leaveChannel，再调用 enableDeepLearningDenoise(YES)。

Note

• 该方法需要动态加载 AgoraAIDenoiseExtension 库，所以声网推荐在加入频道前调用该方法。
• 该方法对人声的处理效果最佳，声网不推荐调用该方法处理含音乐的音频数据。

Discussion

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

Note:

• 请在加入频道前调用该方法。
• 调用该方法后必须调用 stopEchoTest 以结束测试，否则不能进行下一次回声测试，也无法加入频道。
• 直播场景下，该方法仅能由用户角色为主播的用户调用。

Discussion

调用 startEchoTestWithInterval 或 startEchoTestWithConfig 后，如果你想停止通话回路测试，请调用本方法。

Discussion

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

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

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

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

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

Note:

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

Discussion

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

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

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

该方法主要用于以下两种场景：

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

Note:

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

Discussion

停止通话前网络质量探测。

Discussion

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

该方法在加入频道前后都能调用。

Discussion

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

该方法在加入频道前后都能调用。

Discussion

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

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

Discussion

该方法获取远端视频渲染器。

Discussion

该方法适用于需要自行渲染音频的场景。开启外部音频渲染后，你可以通过调用 pullPlaybackAudioFrameRawData / pullPlaybackAudioFrameSampleBufferByLengthInByte 方法拉取远端音频数据App 可以对拉取到的原始音频数据进行处理后再渲染，获取想要的音频效果。

该方法需要在加入频道前调用。

Discussion

使用该方法前，你需要调用 enableExternalAudioSink 方法通知 app 开启并设置外部渲染。

调用该方法后，app 会采取主动拉取的方式获取远端已解码和混音后的音频数据，用于音频播放。

Note

• 该方法需要在加入频道后调用。
• 使用早于 3.5.0 版的 SDK 时，设置 Pull 方式的音频自渲染后，你将无法收到 onPlaybackAudioFrame 回调。
• 该方法和 onPlaybackAudioFrame 回调相比，区别在于：
  • onPlaybackAudioFrame：SDK 通过该回调将音频数据传输给 app。如果 app 处理延时，可能会导致音频播放抖动。
  • pullPlaybackAudioFrameRawData：app 主动拉取音频数据。通过设置音频帧的数据和字节数，SDK 可以调整缓存，帮助 app 处理延时，从而有效避免音频播放抖动。

Discussion

调用该方法前，你需要调用 enableExternalAudioSink 方法通知 app 开启并设置外部渲染。

调用该方法后，app 会采取主动拉取的方式获取远端已解码和混音后的音频数据，用于音频播放。

Note

• 该方法需要在加入频道后调用。
• 使用早于 3.5.0 版的 SDK 时，设置 Pull 方式的音频自渲染后，你将无法收到 onPlaybackAudioFrame 回调。

• 该方法和 onPlaybackAudioFrame 方法相比，区别在于：

  • onPlaybackAudioFrame：SDK 通过该回调将音频数据传输给 app。如果 app 处理延时，可能会导致音频播放抖动；
  • pullPlaybackAudioFrameSampleBufferByLengthInByte：app 主动拉取音频数据。通过设置音频帧的数据和字节数，SDK 可以调整缓存，帮助 app 处理延时，从而有效避免音频播放抖动。

Discussion

该方法必须在 joinChannelByToken 和 startPreview 前调用。

Discussion

Discussion

Discussion

Discussion

Discussion

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

Discussion

该方法设置 onRecordAudioFrame 回调数据的格式，详情请参考原始音频数据

该方法需要在加入频道前调用。

Note

SDK 会通过该方法的 samplesPerCall、sampleRate 和 channel 参数计算出采样间隔，计算公式为采样间隔 = samplesPerCall/(sampleRate * channel)。请确保采样间隔不得小于 0.01 (s)。SDK 会根据该采样间隔触发 onRecordAudioFrame 回调。

Discussion

该方法设置 onPlaybackAudioFrame 回调数据的格式，详情请参考原始音视频数据

该方法需要在加入频道前调用。

Note

SDK 会通过该方法的 samplesPerCall、sampleRate 和 channel 参数计算出采样间隔，计算公式为采样间隔 = samplesPerCall/(sampleRate * channel)。请确保采样间隔不得小于 0.01 (s)。SDK 会根据该采样间隔触发 onPlaybackAudioFrame 回调。

Discussion

该方法设置 onMixedAudioFrame 回调数据的格式，详情请参考原始音视频数据

该方法需要在加入频道前调用。

Note

SDK 会通过该方法的 samplesPerCall、sampleRate 和 channel 参数计算出采样间隔，计算公式为采样间隔 = samplesPerCall/(sampleRate * channel)。请确保采样间隔不得小于 0.01 (s)。SDK 会根据该采样间隔触发 onMixedAudioFrame 回调。

Discussion

该方法将一张 PNG 图片作为水印添加到本地发布的直播视频流上，同一直播频道中的观众、旁路直播观众和采集设备都能看到或采集到该水印图片。声网当前只支持在直播视频流中添加一个水印，后添加的水印会替换掉之前添加的水印。

水印坐标和 setVideoEncoderConfiguration 方法中的设置有依赖关系：

• 如果视频编码方向/orientationMode 固定为横屏或自适应模式下的横屏，那么水印使用横屏坐标。
• 如果视频编码方向/orientationMode 固定为竖屏或自适应模式下的竖屏，那么水印使用竖屏坐标。
• 设置水印坐标时，水印的图像区域不能超出 setVideoEncoderConfiguration 方法中设置的视频尺寸，否则超出部分将被裁剪。

Note

• 你需要在调用 enableVideo 方法之后再调用本方法。
• 如果你只是在旁路直播（推流到CDN）中添加水印，你可以使用本方法或 setLiveTranscoding 方法设置水印。
• 待添加水印图片必须是 PNG 格式。本方法支持所有像素格式的 PNG 图片：RGBA、RGB、Palette、Gray 和 Alpha_gray。
• 如果待添加的 PNG 图片的尺寸与你在本方法中设置的尺寸不一致，SDK 会对 PNG 图片进行缩放或裁剪，以与设置相符。
• 如果你已经使用 startPreview 方法开启本地视频预览，那么本方法的 visibleInPreview 可设置水印在预览时是否可见。
• 如果你已设置本地视频为镜像模式，那么此处的本地水印也为镜像。为避免本地用户看本地视频时的水印也被镜像，声网建议你不要对本地视频同时使用镜像和水印功能，请在应用层实现本地水印功能。

Discussion

如果将某个用户的优先级设为高，那么发给这个用户的音视频流的优先级就会高于其他用户。

弱网下 SDK 会优先保证高优先级用户收到的流的质量。

该方法需要在加入频道前调用。

Note:

目前仅支持将一名远端用户设为高优先级。

Discussion

网络不理想的环境下，发送音视频的质量都会下降。启用本地发布音视频流回退之后，SDK 会在上行弱网且音视频质量严重受影响时，自动关断视频流，从而保证或提高音频质量。同时 SDK 会持续监控网络质量，并在网络质量改善时恢复音视频流。 当本地发送的音视频流回退为音频流时，或由音频流恢复为音视频流时，SDK 会触发 本地发送的音视频流已回退为音频流 回调。

该方法需要在加入频道前调用。

Note:

旁路推流场景下，设置本地发布音视频流回退为仅音频流可能会导致远端的 CDN 用户听到音频的时间有所延迟。因此在有旁路推流的场景下，声网建议不要设置回退。

Discussion

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

该方法需要在加入频道前调用。

Discussion

使用该方法设置单流（默认）或者双流模式。发送端开启双流模式后，接收端可以选择接收大流还是小流。 其中，大流指高分辨率、高码率的视频流，小流指低分辨率、低码率的视频流。

该方法在加入频道前后都能调用。

Discussion

在网络条件受限的情况下，如果发送端没有调用 enableDualStreamMode(NO) 关闭双流模式，接收端可以选择接收大流还是小流。其中，大流可以接收高分辨率高码率的视频流，小流则是低分辨率低码率的视频流。

正常情况下，用户默认接收大流。如需节约带宽和计算资源，则可以调用该方法动态调整对应远端视频流的大小。SDK 会根据该方法中的设置，切换大小流。

视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比，系统会自动分配小流的分辨率、帧率及码率。

调用本方法的执行结果将在 didApiCallExecute 中返回。

Discussion

该方法设置远端视频默认为大流或小流。

Note

• 该方法只能在加入频道前调用。声网不支持你在加入频道后修改默认订阅的视频流类型。
• 如果你既调用了该方法，也调用了 setRemoteVideoStream，则 SDK 以 setRemoteVideoStream 中的设置为准。

Discussion

Discussion

Deprecated 该方法自 3.6.0 版废弃，替代方案请参考发版说明。

该方法用于添加旁路推流地址，调用该方法后，你可以向 CDN 推送 RTMP 或 RTMPS 协议的媒体流。SDK 会在本地触发 rtmpStreamingChangedToState 回调，报告增加旁路推流地址的状态。

Note:

• 该方法仅适用于直播场景。
• 请确保在成功加入频道后再调用该接口。
• 请确保已开通旁路推流的功能，详见前提条件。
• 该方法每次只能增加一路旁路推流地址。若需推送多路流，则需多次调用该方法。
• 声网目前仅支持转码时向 CDN 推送 RTMPS 协议的媒体流。

Discussion

Deprecated 该方法自 3.6.0 版废弃，替代方案请参考发版说明。

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

Note:

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

Discussion

Deprecated 该方法自 3.6.0 版废弃，替代方案请参考发版说明。

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

Note:

• 该方法需要在加入频道后调用。
• 该方法仅适用于直播场景。
• 请确保已开通 CDN 旁路推流的功能，详见前提条件。
• 首次调用该方法更新转码设置时，不会触发 rtcEngineTranscodingUpdated 回调。

Discussion

Discussion

该方法发送数据流消息到频道内所有用户。SDK 对该方法的实现进行了如下限制：频道内每秒最多能发送 30 个包，且每个包最大为 1 KB。 每个客户端每秒最多能发送 6 KB 数据。频道内每人最多能同时有 5 个数据通道。

成功调用该方法后，远端会触发 receiveStreamMessageFromUid 回调，远端用户可以在该回调中获取接收到的流消息；若调用失败，远端会触发 didOccurStreamMessageErrorFromUid 回调。

Note:

• 该方法仅适用于通信场景以及直播场景下的主播用户，如果直播场景下的观众调用此方法可能会造成观众变主播。
• 请确保在调用该方法前，已调用 createDataStream 创建了数据通道。