ByteRtcEngineKit

@interface ByteRtcEngineKit : NSObject

SDK回调给应用层的delegate对象，详见 ByteRtcEngineDelegate

静态函数

成员函数

函数说明

sharedInstance

+ (ByteRtcEngineKit * _Nullable) sharedInstance;

获取 ByteRtcEngineKit 单例对象。

返回值

由 sharedEngineWithAppId:delegate: 创建的 ByteRtcEngineKit 对象。

注意

• 如果未调用 sharedEngineWithAppId:delegate: 或在调用 destroy 之后调用该方法，则会返回 nil 。

destroy

+ (void)destroy;

销毁由 sharedEngineWithAppId:delegate: 创建的引擎实例，并释放所有相关资源。

注意

• 请确保一定是在所有业务场景的最后阶段才调用该方法。
• 该方法在调用之后，会销毁所有 SDK 相关的内存，并且停止与媒体服务器的任何交互。
• 在上一次 sharedEngineWithAppId:delegate: 调用之后对SDK进行的任何设置， 将在下一次有效执行 sharedEngineWithAppId:delegate: 时生效。
• 本方法为阻塞调用，会阻塞当前线程直到 SDK 彻底完成退出逻辑，因而需要注意不要在回调线程中直接调用本方法， 也需要注意不要在回调方法中等待主线程的执行而同时在主线程调用本方法，从而造成死锁。

getSdkVersion

+ (NSString * _Nonnull)getSdkVersion;

获取 SDK 当前的版本号。

返回值

SDK 当前的版本号。

getErrorDescription:

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

获取 SDK 内各种错误码、警告码的描述文字。

传入参数

返回值

描述文字。

sharedEngineWithAppId:delegate:

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

创建 RTCEngine 实例。
此方法应该作为正常 SDK 流程中的第一步操作，通过创建一个 RTCEngine 实例，来使用 SDK 的其他能力。

传入参数

返回值

可用的 ByteRtcEngineKit 实例。

注意

• 该方法在第一次调用时初始化一个 RTCEngine 单例，除非调用 destroy 方法，否则后续的所有调用均 返回同一个内部实例。
• 连续多次调用该方法不会创建不同的 ByteRtcEngineKit，该方法应该与 destroy 成对使用
• 必须使用相同的App ID，App 间才能进行通话。
• 在调用 destroy 之后会销毁 ByteRtcEngineKit 实例，再次调用 sharedEngineWithAppId:delegate: 方法则会重新创建一个全新的 ByteRtcEngineKit 实例。

sharedEngineWithAppId:delegate:monitorDelegate:

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

创建 RTCEngine 实例。
此方法应该作为正常 SDK 流程中的第一步操作，通过创建一个 RTCEngine 实例，来使用 SDK 的其他能力。

传入参数

返回值

可用的 ByteRtcEngineKit 实例。

注意

• 该方法在第一次调用时初始化一个 RTCEngine 单例，除非调用 destroy 方法，否则后续的所有调用均 返回同一个内部实例。
• 连续多次调用该方法不会创建不同的 ByteRtcEngineKit，该方法应该与 destroy 成对使用
• 必须使用相同的App ID，App 间才能进行通话。
• 在调用 destroy 之后会销毁 ByteRtcEngineKit 实例，再次调用 sharedEngineWithAppId:delegate: 方法则会重新创建一个全新的 ByteRtcEngineKit 实例。

initWithAppId:delegate:parameters:

- (id _Nonnull)initWithAppId:(NSString * _Nonnull)appId delegate:(id<ByteRtcEngineDelegate> _Nullable)delegate parameters:(NSDictionary* _Nullable)parameters;

创建引擎对象，此方法应该作为正常 SDK 流程中的第一步操作，通过创建一个引擎实例，来使用 SDK 的其他能力

传入参数

返回值

可用的 ByteRtcEngineKit 实例

注意

1. 连续多次调用该方法会创建不同的 ByteRtcEngineKit
2. 必须使用相同的App ID，App间才能进行通话

initWithAppId:delegate:monitorDelegate:parameters:

- (id _Nonnull)initWithAppId:(NSString * _Nonnull)appId delegate:(id<ByteRtcEngineDelegate> _Nullable)delegate monitorDelegate:(id<ByteRtcMonitorDelegate> _Nullable)monitorDelegate parameters:(NSDictionary* _Nullable)parameters;

创建引擎对象，此方法应该作为正常 SDK 流程中的第一步操作，通过创建一个引擎实例，来使用 SDK 的其他能力

传入参数

返回值

可用的 ByteRtcEngineKit 实例

注意

1. 连续多次调用该方法会创建不同的 ByteRtcEngineKit
2. 必须使用相同的App ID，App间才能进行通话

destroyEngine

- (void)destroyEngine;

手动销毁引擎实例对象，如果当前的引擎对象是通过 sharedEngineWithAppId:delegate: 所创建的，则行为与 destroy 保持一致

注意

1. 请确保一定是在所有业务场景的最后阶段才调用该方法
2. 该方法在调用之后，会销毁所有SDK相关的内存，并且停止与媒体服务器的任何交互
3. 本方法为阻塞调用，会阻塞当前线程直到SDK彻底完成退出逻辑，因而需要注意不要在回调线程中 直接调用本方法，也需要注意不要在回调方法中等待主线程的执行，而同时在主线程调用本方法，从而 造成死锁
4. 可以通过 Objective-C 的ARC机制，在 dealloc 时自动触发销毁逻辑

setChannelProfile:

- (int)setChannelProfile:(ByteChannelProfile)profile;

设置房间模式。
通过设置房间模式，用户可以选择应用 SDK 针对不同房间模式场景的优化策略。
默认的房间模式为通信模式 ByteChannelProfileCommunication 。
房间模式必须在调用 joinChannelByKey:channelName:info:uid: 加入房间前设置，加入房间后设置不生效。设置用户角色（通过方法 setClientRole: ）建议在设置完房间模式后。

传入参数

返回值

方法调用结果。
+ 0: 方法调用成功
+ <0: 方法调用失败

注意

• 为保证音视频质量和实时性，建议相同房间内的用户使用相同的房间模式。

setClientRole:

- (BOOL)setClientRole:(ByteRtcClientRole)role;

设置用户角色。
用户可通过设置用户角色，控制：1.是否发布音视频流；2.用户自身是否在房间中隐身。用户角色详见 ByteRtcClientRole 枚举类型。
默认用户角色为主播角色 ByteRtc_ClientRole_Broadcaster 。
房间模式（通过调用接口 setChannelProfile: 可设置房间模式）为直播模式、游戏模式、云游戏模式时，设置用户角色生效。房间模式为通信模式时不区分用户角色。

传入参数

返回值

方法调用结果。
+ YES: 方法调用成功
+ NO: 方法调用失败

注意

• 在加入房间前，用户可调用此方法设置用户角色。加入房间后，用户也可通过此方法切换用户角色。
• 用户在加入房间成功后调用该方法切换用户角色，调用成功后，远端用户会收到相应的回调通知：1.本地用户角色从静默观众切换至观众或主播时，远端用户会收到 rtcEngine:didJoinedOfUid:elapsed: 回调通知；2.本地用户角色从观众或主播切换至静默观众时，远端用户会收到 rtcEngine:didOfflineOfUid:reason: 回调通知。

clientRole

- (ByteRtcClientRole)clientRole;

获取当前用户角色。

返回值

当前用户角色，详见 ByteRtcClientRole 枚举类型。

joinChannelByKey:channelName:info:uid:

- (int)joinChannelByKey:(NSString * _Nullable)token channelName:(NSString * _Nonnull)roomId info:(NSString * _Nullable)info uid:(NSString * _Nonnull)userId;

加入房间。用户调用此方法加入房间，在一个房间内的用户间可以相互通话。
用户调用 sharedEngineWithAppId:delegate: 创建 RTC 引擎后，需调用此方法加入房间实现同其他用户进行音视频通话。如果用户调用此方法加入房间，则后续重复调用此方法均会失败，用户必须调用 leaveChannel: 退出当前房间后，才能加入下一个房间。
用户调用此方法加入房间成功后，会收到 rtcEngine:didJoinedOfUid:elapsed: 回调通知。

传入参数

返回值

方法调用结果。
+ 0: 成功
+ -1: roomId 为空，失败
+ -2: userId 为空，失败

注意

• 使用不同 App ID 的 App 是不能互通的。
• 请务必保证生成 Token 使用的 App ID 和创建引擎时使用的 App ID 相同，否则会导致加入房间失败。
• 用户加入房间成功后，在本地网络状况不佳的情况下，SDK 可能会与服务器失去连接，此时 SDK 将会自动重连。重连成功后，本地会收到 rtcEngine:didRejoinChannel:withUid:elapsed: 回调通知。
• 房间模式（房间模式参考 setChannelProfile: ）为通话模式下的用户或直播、游戏、云游戏模式下用户角色（用户角色参考 setClientRole: ）为主播、观众的用户加入房间成功后，远端用户会收到 rtcEngine:didJoinChannel:withUid:elapsed: 回调通知。
• 同一个 App ID 的同一个房间内，每个用户的用户ID 必须是唯一的。如果两个用户的用户ID 相同，则后加入房间的用户会将先加入房间的用户踢出房间，并且先加入房间的用户会收到 rtcEngine:didOccurError: 回调通知，错误类型为重复登录 BRERR_DUPLICATE_LOGIN 。

leaveChannel:

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

离开房间。
用户调用此方法离开房间，结束通话过程，释放所有通话相关的资源。
调用 joinChannelByKey:channelName:info:uid: 方法加入房间后，在通话结束时必须调用此方法结束通话，否则无法开始下一次通话。无论当前是否在房间中，都可以调用此方法。重复调用此方法不会有负面影响。
此方法是异步操作，调用返回时并没有真正退出房间。真正退出房间后，SDK 会执行调用此方法时传入的 Block 块。

传入参数

返回值

方法调用结果。
+ 0: 方法调用成功
+ <0: 方法调用失败

注意

• 通信模式下的用户和其他房间模式下的主播、 观众角色的用户离开房间后，远端用户会收到 rtcEngine:didOfflineOfUid:reason: 回调通知。
• 如果调用 leaveChannel 后立即调用销毁引擎，SDK 将无法执行作为参数传入的 Block 块。

renewChannelKey:

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

更新 Token。
Token 有一定的有效期，当 Token 过期时，用户需调用此方法更新房间的 Token 信息。
用户调用 joinChannelByKey:channelName:info:uid: 方法加入房间时，如果使用了过期的 Token 将导致加入房间失败，并会收到 rtcEngine:didOccurError: 回调通知，回调错误码为 BRERR_INVALID_TOKEN 。此时需要重新获取 Token ，并调用此方法更新 Token。

传入参数

返回值

方法调用结果。
+ 0: 方法调用成功。
+ <0: 方法调用失败。

注意

• 如果用户因 Token 过期导致加入房间失败，则调用此方法更新 Token 后 SDK 会自动重新加入房间，而不需要用户自己调用 joinChannelByKey:channelName:info:uid: 方法。
• Token过期时，如果已经加入房间成功，则不会受到影响。Token 过期的错误会在下一次使用过期的 Token 加入房间或由于本地网络状况不佳导致断网重连入房间时通知给用户。

enableLocalAudio:

- (int)enableLocalAudio:(BOOL)enabled;

开启/关闭本地音频采集。
调用该方法后，房间中的其他用户会收到 rtcEngine:didLocalAudioEnabled:byUid: 事件回调。

传入参数

返回值

方法调用结果
+ 0：方法调用成功
+ <0：方法调用失败

注意

• 关闭本地音频采集后，依然会编码发送静音包，因此依然会有少量 CPU 和网络带宽开销。
• 该方法在 joinChannelByKey:channelName:info:uid: 前可以调用。
• 该方法设置的是内部引擎为启用或禁用状态，在 leaveChannel: 后仍然有效。

muteLocalAudioStream:

- (int)muteLocalAudioStream:(BOOL)mute;

静音本地音频流

传入参数

返回值

方法调用结果
+ 0：方法调用成功
+ <0：方法调用失败

注意

• 该方法静音本地音频流。调用该方法后，房间中的其他用户会收到 rtcEngine:didAudioMuted:byUid: 的回调。
• 本方法只是静音本地流，并未关闭本地音频采集设备。

muteRemoteAudioStream:mute:

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

静音/取消静音指定用户的音频流。

传入参数

返回值

方法调用结果
+ 0：方法调用成功
+ <0：方法调用失败

muteAllRemoteAudioStreams:

- (int)muteAllRemoteAudioStreams:(BOOL)mute;

静音/取消静音所有音频流

传入参数

返回值

方法调用结果
+ 0：方法调用成功
+ <0：方法调用失败

注意

本方法只控制本地是否静音远端音频流，并不能控制远端音频设备的采集发送功能

setDefaultMuteAllRemoteAudioStreams:

- (void)setDefaultMuteAllRemoteAudioStreams:(BOOL)mute;

设置是否默认静音所有远端音频流

传入参数

注意

• 如果在加入房间前调用此 API，进房后对所有远端用户音频流生效
• 如果在加入房间后调用此 API，则只对在调用 API 之后进房的远端用户的音频流生效
• 对于已静音的远端用户音频流，如果想要取消静音，请参考 muteRemoteAudioStreammuteRemoteAudioStream:mute:

enableAudioVolumeIndication:smooth:

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

开启/关闭发言者音量提示。

传入参数

返回值

方法调用结果
+ 0：方法调用成功
+ <0：方法调用失败

注意

开启或禁用发言者音量提示功能。功能开启时以一定时间间隔通过音量提示回调 tcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume:rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume: 通知房间内用户的音量。

adjustRecordingSignalVolume:

- (int)adjustRecordingSignalVolume:(NSInteger)volume;

调节录音音量。

传入参数

返回值

方法调用结果
+ 0：方法调用成功
+ <0：方法调用失败

注意

为保证更好的通话质量，建议将 volume 值设为 [0,100]

adjustPlaybackSignalVolume:

- (int)adjustPlaybackSignalVolume:(NSInteger)volume;

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

传入参数

返回值

方法调用结果
+ 0：方法调用成功
+ <0：方法调用失败

注意

• 该方法调节的是本地播放的所有远端用户混音后的音量
• 为保证更好的通话质量，建议将 volume 值设为 [0,100]

setLocalVideoRenderer:

- (int)setLocalVideoRenderer:(id<ByteVideoSinkProtocol> _Nullable)videoRenderer;

设置本地视频外部渲染器。

传入参数

返回值

• 0：方法调用成功
• <0：方法调用失败

setLocalVideoRenderer:forRoomId:forUserId:

- (int)setLocalVideoRenderer:(id<ByteVideoSinkProtocol> _Nullable)videoRenderer forRoomId:(NSString * _Nonnull)roomId forUserId:(NSString * _Nonnull)userId;

设置本地视频外部渲染器。

传入参数

返回值

• 0：方法调用成功
• <0：方法调用失败

setRemoteVideoRenderer:forRoomId:forUserId:

- (int)setRemoteVideoRenderer:(id<ByteVideoSinkProtocol> _Nullable)videoRenderer forRoomId:(NSString * _Nonnull)roomId forUserId:(NSString * _Nonnull)userId;

设置特定远端用户的外部渲染器。

传入参数

返回值

• 0：方法调用成功
• <0：方法调用失败

setRemoteVideoRenderer:forUserId:

- (int)setRemoteVideoRenderer:(id<ByteVideoSinkProtocol> _Nullable)videoRenderer forUserId:(NSString * _Nonnull)userId;

设置特定远端用户的外部渲染器。

传入参数

返回值

• 0：方法调用成功
• <0：方法调用失败

setupRemoteScreenRenderer:forRoomId:forUserId:

- (int)setupRemoteScreenRenderer:(id<ByteVideoSinkProtocol> _Nullable)screenRenderer forRoomId:(NSString * _Nonnull)roomId forUserId:(NSString * _Nonnull)userId;

设置远端屏幕共享的外部渲染器。

传入参数

返回值

• 0：方法调用成功
• -1：方法调用失败

注意

在应用开发中，通常在应用收到 rtcEngine:firstRemoteScreenFrameOfUid:size:elapsed: 事件后调用该方法进行远端视频设置。

setupRemoteScreenRenderer:forUserId:

- (int)setupRemoteScreenRenderer:(id<ByteVideoSinkProtocol> _Nullable)screenRenderer forUserId:(NSString * _Nonnull)userId;

设置远端屏幕共享的外部渲染器。

传入参数

返回值

• 0：方法调用成功
• -1：方法调用失败

注意

在应用开发中，通常在应用收到 firstRemoteScreenFrameOfUidrtcEngine:firstRemoteScreenFrameOfUid:size:elapsed: 事件后调用该方法进行远端视频设置

setVideoProfiles:

- (VideoStreamState)setVideoProfiles:(NSArray <VideoStreamDescription *> * _Nullable)videoStreamDescriptions;

设置本地视频属性。

传入参数

返回值

• 0：方法调用成功
• <0：方法调用失败

setVideoProfiles:orientationMode:

- (VideoStreamState)setVideoProfiles:(NSArray <VideoStreamDescription *> * _Nullable)videoStreamDescriptions orientationMode:(ByteVideoOutputOrientationMode)mode;

设置本地视频属性。

传入参数

返回值

• 0：方法调用成功
• <0：方法调用失败

setupLocalVideo:

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

该方法设置本地视频显示信息。

传入参数

返回值

• 0：方法调用成功
• <0：方法调用失败

注意

应用程序通过调用此接口绑定本地视频流的显示视窗 (view)，并设置视频显示模式。在应用程序开发中，通常在初始化后调用该方法进行本地视频设置，然后再加入频道。退出频道后，绑定仍然有效，如果需要解除绑定，可以指定空 (NULL) View 调用 setupLocalVideosetupLocalVideo:。

setupRemoteVideo:

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

设置远端视频显示属性。

传入参数

返回值

• 0：方法调用成功
• <0：方法调用失败

注意

该方法绑定远程用户和显示视图，即设定 uid 指定的用户用哪个视图显示。调用该接口时需要指定远程视频的 uid，一般可以在进频道前提前设置好。如果应用程序不能事先知道对方的 uid，可以在 APP 收到 rtcEngine:didJoinedOfUid:elapsed: 事件时设置。 如果启用了视频录制功能，视频录制服务会做为一个哑客户端加入频道，因此其他客户端也会收到它的 rtcEngine:didJoinedOfUid:elapsed: 事件。 APP 不应给它绑定视图（因为它不会发送视频流），如果 APP 不能识别哑客户端，可以在 firstRemoteVideoFrameOfUidrtcEngine:firstRemoteVideoFrameOfUid:size:elapsed: 事件时再绑定视图。解除某个用户的绑定视图可以把 view 设置为空。 退出频道后，SDK 会把远程用户的绑定关系清除掉。

setupRemoteScreen:

- (int)setupRemoteScreen:(ByteRtcVideoCanvas * _Nonnull)screen;

设置远端屏幕共享视图，即用户ID指定的用户用的屏幕视图显示。调用该接口时需要指定远程共享屏幕流的用户ID，一般可以在进频道前提前设置好。

传入参数

返回值

• 0：方法调用成功
• -1：方法调用失败

注意

在应用开发中，通常在应用收到 firstRemoteScreenFrameOfUidrtcEngine:firstRemoteScreenFrameOfUid:size:elapsed: 事件后调用该方法进行远端视频设置

startPreview

- (int)startPreview;

开启视频预览，视频预览默认为关闭状态。

返回值

• 0：方法调用成功
• <0：方法调用失败

注意

• 只有同时调用 enableLocalVideo:(true) 与 startPreview 才会打开视频采集设备。
• 只要调用 enableLocalVideo:(false) 或 stopPreview 的任意一个就会关闭视频采集设备。
• 该方法在 joinChannelByKey:channelName:info:uid: 前可以调用。
• 该方法设置的视频预览状态，在 leaveChannel: 后仍然有效。
• 调用 leaveChannel: 退出频道，并不会关闭视频预览。如需关闭视频预览，请调用 stopPreview

stopPreview

- (int)stopPreview;

关闭视频预览，视频预览默认为关闭状态。

返回值

• 0：方法调用成功
• <0：方法调用失败

注意

• 只有同时调用 enableLocalVideo:(true) 与 startPreview 才会打开视频采集设备。
• 只要调用 enableLocalVideo:(false) 或 stopPreview 的任意一个就会关闭视频采集设备。
• 该方法在 joinChannelByKey:channelName:info:uid: 前可以调用。
• 该方法设置的视频预览状态，在 leaveChannel: 后仍然有效。

enableLocalVideo:

- (int)enableLocalVideo:(BOOL)enabled;

该方法开启或关闭本地视频采集。默认为开启状态。
调用该方法后，房间中的其他用户会收到 rtcEngine:didLocalVideoEnabled:byUid: 的回调。

传入参数

返回值

• 0：方法调用成功
• <0：方法调用失败

注意

• 关闭本地视频采集后，不会编码发送视频数据。
• 只有同时调用 enableLocalVideo:(true) 与 startPreview 才会打开视频采集设备。
• 只要调用 enableLocalVideo:(false) 或 stopPreview 的任意一个就会关闭视频采集设备。
• 该方法在 joinChannelByKey:channelName:info:uid: 前可以调用。
• 该方法设置的是内部引擎为启用或禁用状态，在 leaveChannel: 后仍然有效。

muteLocalVideoStream:

- (int)muteLocalVideoStream:(BOOL)mute;

停止/开启本地视频流发送。调用该方法后，房间中的其他用户会收到rtcEngine:didVideoMuted:byUid: 回调

传入参数

返回值

• 0：方法调用成功
• <0：方法调用失败

muteRemoteVideoStream:mute:

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

停止/开启接收指定远端用户的视频流。

传入参数

返回值

• 0：方法调用成功
• <0：方法调用失败

muteAllRemoteVideoStreams:

- (int)muteAllRemoteVideoStreams:(BOOL)mute;

停止/开启接收所有远端用户的视频流。

传入参数

返回值

• 0：方法调用成功
• <0：方法调用失败

setDefaultMuteAllRemoteVideoStreams:

- (void)setDefaultMuteAllRemoteVideoStreams:(BOOL)mute;

设置默认禁止/开启远端用户的视频流。

传入参数

注意

设置的默认静音仅影响未来到达的视频流，对已订阅的远端流无影响

setLocalVideoMirrorMode:

- (int)setLocalVideoMirrorMode:(ByteVideoMirrorMode) mode;

设置本地视频镜像.该方法用于开启或关闭本地视频镜像，默认值为关闭（ByteVideoMirrorModeDisabled）。

传入参数

返回值

• 0：方法调用成功
• <0：方法调用失败

isLocalVideoMirrorOn

- (bool)isLocalVideoMirrorOn;

获取本地视频镜像状态

返回值

当前镜像状态
+ true：镜像为打开状态
+ false：镜像为关闭状态

switchCamera

- (int)switchCamera;

切换摄像头。

返回值

• 0：方法调用成功
• <0：方法调用失败

replaceBackground:withDivideModel:

- (int) replaceBackground:(BackgroundMode)mode withDivideModel:(DivideModel)divideModel;

视频图像分割，替换背景

传入参数

返回值

• 0：方法调用成功
• <0：方法调用失败

checkVideoEffectSupport

- (int) checkVideoEffectSupport;

检查当前版本是否支持视频特效

返回值

: 0: 不支持 >0: 支持视频特效

checkVideoEffectLicense:

- (int) checkVideoEffectLicense:(NSString * _Nonnull)licenseFile;

视频特效许可证检查

传入参数

返回值

0: 许可证验证成功 !0: 许可证验证验证失败

注意

enableVideoEffectenableVideoEffect:开始使用视频特效前，需要先调用这个方法进行许可证验证

enableVideoEffect:

- (int) enableVideoEffect:(BOOL)enabled;

开启关闭视频特效

传入参数

返回值

0: 成功 !0: 失败。

注意

checkVideoEffectLicensecheckVideoEffectLicense:setVideoEffectAlgoModelPathsetVideoEffectAlgoModelPath:后调用此方法

setVideoEffectAlgoModelPath:

- (void) setVideoEffectAlgoModelPath:(NSString * _Nonnull)modelPath;

设置视频特效算法模型路径

传入参数

setVideoEffectNodes:

- (void) setVideoEffectNodes:(NSArray <NSString *> *_Nonnull)effectNodePaths;

设置特效包，支持同时设置多个特效包

传入参数

addVideoEffectNodes:

- (void) addVideoEffectNodes:(NSArray <NSString *> *_Nonnull)effectNodePaths;

增加特效包，支持同时增加多个特效包

传入参数

removeVideoEffectNodes:

- (void) removeVideoEffectNodes:(NSArray <NSString *> *_Nonnull)effectNodePaths;

移除特效包，支持同时移除多个特效包

传入参数

updateVideoEffectNode:nodeKey:nodeValue:

- (void) updateVideoEffectNode:(NSString * _Nonnull)nodePath nodeKey:(NSString * _Nonnull)nodeKey nodeValue:(float) nodeValue;

设置特效强度

传入参数

注意

nodeKey 的取值请参考特效包的参数说明文件

setVideoEffectColorFilter:

- (void) setVideoEffectColorFilter:(NSString * _Nonnull)resPath;

设置颜色滤镜

传入参数

setVideoEffectColorFilterIntensity:

- (void) setVideoEffectColorFilterIntensity:(float) intensity;

设置颜色滤镜强度

传入参数

setMediaMetadataObserver:

- (BOOL)setMediaMetadataObserver:(_Nullable id<ByteRtcEngineMediaMetadataObserver>) metadataObserver;

注册 metadata 观察者，用于接收或发送 metadata，底层通过在视频帧中添加 SEI 数据实现该功能。
注册观察者后，发送的视频帧里面没有 SEI 信息， 会触发 videoFrameMediaMetaDataAtTime: 回调。
注册观察者后，接收的视频帧里面有 SEI 信息，会触发接收 receiveVideoFrameFromUID:withExtendedData:atTimestamp: 回调。

传入参数

返回值

• YES: 设置成功
• NO: 设置失败

注意

• 使用视频自定义采集与渲染时，可以直接在视频帧中添加与获取 metadata，不建议使用本接口。
• 本接口支持动态取消注册，将参数设置为 nullptr 取消注册。

enableAutoSubscribe:

- (BOOL)enableAutoSubscribe:(BOOL)autoSubscribe;

开启/关闭自动订阅功能。
用户调用此方法设置房间中是否开启自动订阅功能。SDK 默认开启自动订阅功能。
如需关闭自动订阅功能，建议在调用 joinChannelByKey:channelName:info:uid: 方法加入房间前设置完成。

传入参数

返回值

方法执行结果。
+ YES: 方法调用成功。
+ NO: 方法调用失败。

注意

• SDK 提供两种订阅模式：1.自动订阅模式，开启自动订阅功能时，SDK 自动帮助用户订阅房间中所有其他用户发布的音视频流；2.手动订阅模式，关闭自动订阅功能时，SDK不会自动订阅房间内的音视频流，只通过 rtcEngine:onStreamAdd: 和 rtcEngine:didStreamRemoved:stream:reason: 回调通知用户当前所在房间中有哪些音视频流，由用户根据自己的需要调用 subscribeStream:subscribeConfig: 方法手动订阅其他用户发布的音视频流。

subscribeStream:subscribeConfig:

- (void)subscribeStream:(NSString *_Nonnull)userId subscribeConfig:(SubscribeConfig *_Nonnull)info;

订阅指定的房间内远端音视频流。
关闭自动订阅功能，使用手动订阅模式时用户调用此方法按需订阅房间中的音视频流。
此方法仅在关闭自动订阅功能时生效。用户需在加入房间前调用 enableAutoSubscribe: 方法关闭自动订阅功能以使用手动订阅模式。
订阅流失败时，SDK 会按失败原因回调 rtcEngine:didOccurError: 通知用户，具体错误可参考错误码 ByteRtcErrorCode 描述。

传入参数

注意

• 此方法仅支持订阅当前房间中的远端音视频流。如果指定的流在当前房间内不曾存在，则 SDK 不会订阅。
• 用户调用 joinChannelByKey:channelName:info:uid: 方法加入房间后：1.当房间内有新的音视频流发布时，本地会收到 rtcEngine:onStreamAdd: 回调通知；2.当房间内音视频流停止发布时，本地会收到 rtcEngine:didStreamRemoved:stream:reason: 回调通知。通过这两个回调用户可以获得当前房间中的音视频流信息，并在需要时调用此方法订阅指定音视频流。

unSubscribeStream:isScreen:

- (void)unSubscribeStream:(NSString *_Nonnull)userId isScreen:(BOOL)isScreen;

停止订阅指定的房间内远端音视频流。
关闭自动订阅功能，使用手动订阅模式时用户调用此方法停止订阅已订阅的音视频流。
此方法仅在关闭自动订阅功能时生效。用户需在加入房间前调用 enableAutoSubscribe: 方法关闭自动订阅功能以使用手动订阅模式。

传入参数

注意

• 不管是否订阅了指定的远端音视频流，都可以调用此方法停止订阅。停止订阅的 streamId 无效或未订阅时，SDK不会做任何处理，没有负面影响。

setEnableSpeakerphone:

- (int)setEnableSpeakerphone:(BOOL)enableSpeaker;

设置音频播放设备为扬声器或者听筒，默认使用扬声器。 音频播放设备发生变化时，会收到 rtcEngine:didAudioRouteChanged: 回调。

传入参数

返回值

方法调用结果
+ 0: 方法调用成功
+ <0: 方法调用失败

注意

• 该 API 适用于移动设备
• 听筒是手机自带的音频播放设备，一般位于手机顶部，用于打电话。扬声器是手机自带的音频播放设备，一般用于外放。
• 连接有线或者蓝牙音频播放设备时，音频从有线或者蓝牙音频播放设备播放。没有连接有线或者蓝牙音频播放设备时，音频才会从扬声器或者听筒播放。
• 在通话过程中连接有线或者蓝牙音频播放设备时，会自动切换到有线或者蓝牙音频播放设备。
• 在通话过程中移除有线或者蓝牙音频播放设备时，会根据本接口设置，自动切换到听筒或者扬声器。
• 支持在通话前提前设置音频播放设备，也支持在通话过程中切换音频播放设备。

isSpeakerphoneEnabled

- (BOOL)isSpeakerphoneEnabled;

查询扬声器启用状态

返回值

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

enableLiveTranscoding:

- (int)enableLiveTranscoding:(ByteRtcLiveTranscoding * _Nonnull)transcoding;

开启直播推流转码功能。
此方法用于开启直播推流转码功能，并设置旁路推流的视频视图布局及音频属性等。
直播推流转码功能开启时，会根据设置的视频视图布局和音频属性进行合流转码转成 rtmp 流并推送到设置的 CDN 。
直播推流转码功能启动成功或失败时、推流过程中发生错误时，SDK 通过 rtcEngine:TransCodingWithUrl:errorCode: 回调事件通知用户对应的状态事件。

传入参数

返回值

方法调用结果。
+ 0：方法调用成功
+ <0：方法调用失败

注意

• 只有房间模式为直播模式，且用户角色为主播的用户才能调用此方法。

disableLiveTranscoding

- (int)disableLiveTranscoding;

关闭直播推流转码功能。

返回值

方法调用结果。
+ 0：方法调用成功
+ <0：方法调用失败

setVideoCompositingLayout:

- (int)setVideoCompositingLayout:(ByteRtcVideoCompositingLayout * _Nonnull)layout;

设置视频流合流布局。
此方法用于在直播推流转码功能开启时，更新旁路推流的视频合流布局属性。调用此方法前，用户需通过调用 enableLiveTranscoding: 方法开启直播推流转码功能。如果未开启直播推流转码功能，则调用此方法不生效。

传入参数

返回值

方法调用结果。
+ 0：方法调用成功
+ <0：方法调用失败

enableCloudRending:

- (int)enableCloudRending:(NSString *_Nonnull)rendingInfo;

按照传入的布局信息开启云端渲染。

传入参数

返回值

方法调用结果。
+ 0: 方法调用成功
+ <0: 方法调用失败

updateCloudRending:

- (int)updateCloudRending:(NSString *_Nonnull)rendingInfo;

按照传入的布局信息更新云端渲染。

传入参数

返回值

方法调用结果。
+ 0: 方法调用成功
+ <0: 方法调用失败

disableCloudRending

- (int)disableCloudRending;

停止云端渲染。

返回值

方法调用结果。
+ 0: 方法调用成功
+ <0: 方法调用失败

setExternalVideoSource:useTexture:pushMode:

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

配置外部视频源。

传入参数

注意

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

pushExternalVideoFrame:time:

- (BOOL)pushExternalVideoFrame:(CVPixelBufferRef _Nonnull )frame time:(CMTime)pts;

推送外部视频帧。

传入参数

返回值

• YES 推送成功
• NO 推送失败

注意

使用外部推送视频帧，调用 setExternalVideoSource 开启外部视频源功能，详见setExternalVideoSource:useTexture:pushMode:

pushExternalVideoFrame:time:rotation:

- (BOOL)pushExternalVideoFrame:(CVPixelBufferRef _Nonnull )frame time:(CMTime)pts rotation:(ByteVideoRotation)rotation;

推送外部视频帧。

传入参数

返回值

• YES 推送成功
• NO 推送失败

注意

使用外部推送视频帧，调用 setExternalVideoSource 开启外部视频源功能，详见setExternalVideoSource:useTexture:pushMode:

pushExternalVideoFrame:time:rotation:extendedData:supplementaryInfo:

- (BOOL)pushExternalVideoFrame:(CVPixelBufferRef _Nonnull )frame time:(CMTime)pts rotation:(ByteVideoRotation)rotation extendedData:(NSData* _Nullable)extendedData supplementaryInfo:(NSData* _Nullable)supplementoryInfo;

推送外部视频帧。

传入参数

返回值

• YES 推送成功
• NO 推送失败

pushExternalByteVideoFrame:

- (BOOL)pushExternalByteVideoFrame:(ByteVideoFrame * _Nonnull)frame;

推送外部视频帧，使用 ByteVideoFrame 进行封装。

传入参数

返回值

• YES 推送成功
• NO 推送失败

setExternalAudioDevice:sampleRate:recordChannelNum:playoutChannelNum:

- (BOOL)setExternalAudioDevice:(BOOL) enable sampleRate:(int) sampleRate recordChannelNum:(int) recordChannelNum playoutChannelNum:(int) playoutChannelNum;

设置是否启用外部音频采集渲染。

传入参数

返回值

方法调用结果
+ YES: 方法调用成功
+ NO: 方法调用失败

注意

• 该方法应该在 joinChannelByKey:channelName:info:uid: 前使用。
• 启用自定义音频采集渲染后，使用 pushExternalAudioFrame:frameNum: 推送音频数据。
• 启用自定义音频采集渲染后，使用 pullExternalAudioFrame:frameNum: 拉取音频数据。

setAudioPlayoutMixStream:sampleRate:channelNum:

- (BOOL)setAudioPlayoutMixStream:(BOOL) enable sampleRate:(int) sampleRate channelNum:(int) channelNum;

启动/停止外部音频流混音， 并设置混音数据格式

传入参数

返回值

• YES:成功
• NO:失败

注意

• 调用该方法设置外部音频混音的PCM格式，即 pushAudioMixingStreamData:frameNum: 的 audioFrame 的音频数据格式。
• 调用该方法混音的数据来源外部缓存，且音频格式为PCM； startAudioMixing:loopback:replace:cycle: 方法混音数据来源外部文件，且支持的文件格式有: mp3，aac，m4a，3gp，wav。这两种混音方式可以共存。
• enable 为 NO 时，停止外部音频流混音。 或者引擎释放时，SDK内部会停止混音。
• 该方法启动的外部音频流混音不支持音量调节，暂停，暂停恢复操作。

getAudioMixingStreamCachedFrameNum

- (int)getAudioMixingStreamCachedFrameNum;

获取SDK当前缓冲数据

返回值

• >0: 成功，缓冲的音频采样点个数。
• 0: 失败

注意

调用该方法可以实时获取缓存数据量，并以此数据为基准调整数据推送节奏来避免内存溢出

pushAudioMixingStreamData:frameNum:

- (BOOL)pushAudioMixingStreamData:(void* _Nonnull)audioFrame frameNum:(int)frameNum;

向SDK推送混音的音频数据

传入参数

返回值

• YES: 成功
• NO: 失败

注意

• 调用该方法前，必须通过 setAudioPlayoutMixStream:sampleRate:channelNum: 方法设置 audioFrame 的数据格式。
• 调用该方法前，先通过 getAudioMixingStreamCachedFrameNum 获取缓存的数据量，并调整推送数据的节奏以避免内部缓溢出导致推送失败。
• 使用参考建议：首次推送数据，请在应用侧先缓存一定数据（如 200 毫秒）， 然后一次性推送过去；此后的推送操作定时 10 毫秒一次，并且每次的音频数据量为 10 毫秒数据量。

setAudioDeviceObserver:

- (BOOL)setAudioDeviceObserver:(_Nullable id<ByteAudioDeviceObserver>) audioDeviceObserver;

启动音频外部源采集渲染时，添加音频外部设备事件监控

传入参数

返回值

方法调用结果
+ YES: 方法调用成功
+ NO: 方法调用失败

setRecordingAudioFrameParameters:channels:

- (BOOL)setRecordingAudioFrameParameters:(NSInteger)samplesPerSec channels:(NSInteger)channels;

设置本地麦克风录制的音频数据回调参数

传入参数

返回值

方法调用结果
+ YES: 方法调用成功
+ NO: 方法调用失败

注意

使用本方法设置参数，并使用setAudioFrameObserversetAudioFrameObserver:注册数据观察者，之后可以在ByteAudioFrameObserver的 onRecordAudioFrameonRecordAudioFrame:收到数据

setPlaybackAudioFrameParameters:channels:

- (BOOL)setPlaybackAudioFrameParameters:(NSInteger)samplesPerSec channels:(NSInteger)channels;

设置远端所有用户音频数据混音后的音频数据回调参数

传入参数

返回值

方法调用结果
+ YES: 方法调用成功
+ NO: 方法调用失败

注意

使用本方法设置参数，并使用setAudioFrameObserversetAudioFrameObserver:注册数据观察者，之后可以在ByteAudioFrameObserver的 onPlaybackAudioFrameonPlaybackAudioFrame:收到数据

setMixedAudioFrameParameters:channels:

- (BOOL)setMixedAudioFrameParameters:(NSInteger)samplesPerSec channels:(NSInteger)channels;

设置本地麦克风录制音频数据和远端所有用户音频数据混音后的音频数据回调参数

传入参数

返回值

方法调用结果
+ YES: 方法调用成功
+ NO: 方法调用失败

注意

使用本方法设置参数，并使用setAudioFrameObserversetAudioFrameObserver:注册数据观察者，之后可以在ByteAudioFrameObserver的 onMixedAudioFrameonMixedAudioFrame:收到数据

setAudioFrameObserver:

- (BOOL)setAudioFrameObserver:(_Nullable id<ByteAudioFrameObserver>) audioFrameObserver;

设置音频数据回调观察者

传入参数

返回值

方法调用结果
+ YES: 方法调用成功
+ NO: 方法调用失败

注意

本方法需要与下面3个方法配合使用：setRecordingAudioFrameParameters:channels:、 setPlaybackAudioFrameParameters:channels:、 setMixedAudioFrameParameters:channels:

pushExternalAudioFrame:frameNum:

- (BOOL)pushExternalAudioFrame:(void* _Nonnull)audioFrame frameNum:(int)frameNum;

推送外部音频数据。使用 setExternalAudioDevice:sampleRate:recordChannelNum:playoutChannelNum: 启用自定义音频采集渲染后，可以使用本方法推送外部音频数据。

传入参数

返回值

方法调用结果
+ YES: 方法调用成功
+ NO: 方法调用失败

注意

• 必须是pcm数据，推送间隔是10ms，音频采样格式为s16。
• 该函数运行在用户调用线程内

pullExternalAudioFrame:frameNum:

- (BOOL)pullExternalAudioFrame:(void* _Nonnull)audioFrame frameNum:(int)frameNum;

拉取远端音频数据。使用 setExternalAudioDevice:sampleRate:recordChannelNum:playoutChannelNum: 启用自定义音频采集渲染后，可以使用本方法拉取远端音频数据。

传入参数

返回值

方法调用结果
+ YES: 方法调用成功
+ NO: 方法调用失败

注意

• 必须是pcm数据，拉取间隔是10ms，音频采样格式为s16。
• 该函数运行在用户调用线程内

setAudioPerfProfile:

- (void)setAudioPerfProfile:(AudioPerfProfile) profile;

设置音频处理复杂度。对于希望性能占用较低，可设置较低的音频处理复杂度，如果更在意通话质量，可选择设置更高的音频处理复杂度。 加入房间时，会携带本接口传入的机型等级，然后从服务端拉起相应音频配置。如果传入的是 auto，服务端会查询数据库，获得机型等级，再下发配置。 不同复杂度会开关AEC、ANS、AGC算法，调整播放sample rate等, 进行性能和质量的控制。 默认为AUDIO_PERF_PROFILE_AUTO

传入参数

注意

• 需要在进房之前调用。
• 本次进房时下发的配置，需要下次进房发布才会应用。
• 支持自定义配置，详细操作方式请联系技术支持人员。

setBusinessId:

- (int)setBusinessId:(NSString* _Nullable)businessId;

设置业务标识参数。
可通过 businessId 区分不同的业务场景（角色/策略等）。businessId 由客户自定义，相当于一个“标签”，可以分担和细化现在 AppId 的逻辑划分的功能。

传入参数

返回值

• 0： 成功。
• <0： 失败。
• -6001： 用户已经在房间中。
• -6002： 输入非法，合法字符包括所有小写字母、大写字母和数字，除此外还包括四个独立字符分别是：英文句号，短横线，下划线和 @ 。

注意

• 需要在调用 joinChannelByKey:channelName:info:uid: 之前调用， joinChannelByKey:channelName:info:uid: 之后调用该方法无效。

adjustRemoteAudioVolume:ofUid:

- (int)adjustRemoteAudioVolume:(int)volume ofUid:(NSString* _Nonnull)uid;

调节远端用户音量，默认值为100

传入参数

返回值

方法调用结果
+ 0：方法调用成功
+ <0：方法调用失败

getAudioMixingDuration

- (int)getAudioMixingDuration;

获取音乐文件时长

返回值

• >0: 成功, 音乐文件时长，单位为毫秒。
• <0: 失败

注意

请在房间内调用该方法。

getAudioMixingCurrentPosition

- (int)getAudioMixingCurrentPosition;

获取音乐文件播放进度

返回值

• >0: 成功, 音乐文件播放进度，单位为毫秒。
• <0: 失败

注意

请在房间内调用该方法。

stopAudioMixing

- (int)stopAudioMixing;

停止播放音乐文件及混音

返回值

• 0：成功
• <0：失败

注意

• 调用 startAudioMixing:loopback:replace:cycle: 方法开始播放音乐文件及混音后，调用该方法可以停止播放音乐文件及混音。
• 请在房间内调用该方法。

pauseAudioMixing

- (int)pauseAudioMixing;

暂停播放音乐文件

返回值

• 0: 成功
• <0: 失败

注意

• 调用 startAudioMixing:loopback:replace:cycle: 方法开始播放音乐文件及混音后，可以通过调用该方法暂停播放音乐文件。
• 调用该方法暂停播放音乐文件后，可调用 resumeAudioMixing 方法恢复播放。
• 请在房间内调用该方法。

resumeAudioMixing

- (int)resumeAudioMixing;

恢复播放音乐文件

返回值

• 0: 成功
• <0: 失败

注意

• 调用 pauseAudioMixing 方法暂停播放音乐文件后，可以通过调用该方法恢复播放。
• 请在房间内调用该方法

adjustAudioMixingVolume:

- (int)adjustAudioMixingVolume:(NSInteger)volume;

调节音乐文件的文件音量。为保证更好的音质，建议将 volume 值设为 [0,100]。

传入参数

返回值

• 0: 成功
• <0: 失败

注意

• 调用该方法可同时调节的是本地和远端播放音量。仅调节本端音量可使用 adjustAudioMixingPlayoutVolume: ， 仅调节远端音量可使用 adjustAudioMixingPublishVolume: 。
• 该方法对 adjustAudioMixingPlayoutVolume: 和 adjustAudioMixingPublishVolume: 的音量调节影响是乘积关系
• 请在房间内调用该方法。

startAudioMixing:loopback:replace:cycle:

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

开始播放音乐文件及混音。

传入参数

返回值

• 0：成功
• <0：失败

注意

• 该方法指定本地和麦克风采集的音频流进行混音或替换。替换是指用音频文件替换麦克风采集的音频流。
• 该方法可以选择是否让对方听到本地播放的音频，并指定循环播放的次数。 调用本方法播放音乐文件及混音结束后，应用会收到 rtcEngineLocalAudioMixingDidFinish: 回调。
• 开始播放音乐文件及混音后，可以调用 stopAudioMixing 方法停止播放音乐文件。
• 该方法混音数据来源外部文件，且支持的文件格式有: mp3，aac，m4a，3gp，wav；而 setAudioPlayoutMixStream:sampleRate:channelNum: 混音的数据来源外部缓存且音频格式为PCM；这两种混音方式可以共存。
• 单个房间只支持一路音乐文件的播放，多次调用该函数后，只有最后一次调用会生效。
• 请在房间内调用该方法。

setAudioMixingPosition:

- (int)setAudioMixingPosition:(NSInteger)pos;

设置音频文件的播放位置

传入参数

返回值

• 0: 成功
• <0: 失败

注意

该方法可以设置音频文件的播放位置，这样你可以根据实际情况从指定的位置播放音乐文件，无需从头到尾完整播放一个音乐文件。

adjustAudioMixingPlayoutVolume:

- (int)adjustAudioMixingPlayoutVolume:(NSInteger)volume;

调节音乐文件的本地播放音量。为保证更好的音质，建议将 volume 值设为 [0,100]。

传入参数

返回值

• 0: 成功
• <0: 失败

注意

• 调用该方法可以调节混音的音乐文件在本地播放的音量大小。如果需要同时调节本地和远端播放音量可使用 adjustAudioMixingVolume: 方法。
• 请在房间内调用该方法。

adjustAudioMixingPublishVolume:

- (int)adjustAudioMixingPublishVolume:(NSInteger)volume;

调节音乐文件的远端播放音量。为保证更好的音质，建议将 volume 值设为 [0,100]。

传入参数

返回值

• 0: 成功
• <0: 失败

注意

• 该方法调节混音的音乐文件在远端播放的音量大小。如果需要同时调节本地和远端播放音量可使用 adjustAudioMixingVolume:adjustAudioMixingVolume 方法。
• 请在房间内调用该方法。

setVolumeOfEffect:withVolume:

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

调节指定音效文件的文件音量

传入参数

返回值

• 0: 成功
• <0: 失败

注意

• 该方法调节音效文件在本地和远端播放的音量大小。
• 请在房间内调用该方法。

getEffectVolume:

- (int)getEffectVolume:(NSInteger)soundId;

获取指定音效文件的文件音量

传入参数

返回值

• >0: 成功，文件音量，音量范围为 0~400。
• <0: 失败

注意

请在房间内调用该方法。

playEffect:filePath:loopback:cycle:withVolume:

- (int)playEffect:(NSInteger)soundId filePath:(NSString * _Nullable)filePath loopback:(BOOL)loopback cycle:(NSInteger)cycle withVolume:(NSInteger)volume;

开始播放指定音效文件。你可以在该方法中设置音效文件的播放次数、音量大小，以及远端用户是否能听到该音效。

传入参数

返回值

• 0: 成功
• <0: 失败

注意

• 调用该方法播放音效结束后，应用会收到 rtcEngineLocalAudioMixingDidFinish: 回调。
• 可以多次调用该方法，通过传入不同的音效文件的 soundId 和 filePath，以实现同时播放多个音效文件，实现音效叠加。
• 可以通过 stopEffect: 方法停止播放指定音效文件。
• 请在房间内调用该方法。

preloadEffect:filePath:

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

预加载指定音效文件

传入参数

返回值

• 0: 成功
• <0: 失败

注意

• 调用该方法预加载播放指定音效文件。预加载操作可以在进房间之前完成（所有混音相关接口，如果没有标注请在房间内调用都可在没有进入房间的时候调用）。如果音效文件很长，加载操作可能会耗时较长，建议应用开发者将预加载操作放在子线程进行。
• 该方法只是预加载播放指定音效文件，只有通过 playEffect:filePath:loopback:cycle:withVolume: 才开始播放指定音效文件。
• 该方法预加载指定音效文件可以通过 unloadEffect: 来卸载。

unloadEffect:

- (int)unloadEffect:(NSInteger)soundId;

卸载指定音效文件

传入参数

返回值

• 0: 成功
• <0: 失败

注意

• 该方法卸载指定音效文件。
• 如果调用 stopEffect: 方法时音效文件没有被卸载，SDK会自动调用该方法卸载音效文件。

pauseEffect:

- (int)pauseEffect:(NSInteger)soundId;

暂停播放指定音效文件

传入参数

返回值

• 0: 成功
• <0: 失败

注意

调用该方法暂停播放指定音效文件，可以调用 resumeEffect: 方法恢复播放。

resumeEffect:

- (int)resumeEffect:(NSInteger)soundId;

恢复播放指定音效文件

传入参数

返回值

• 0: 成功
• <0: 失败

注意

• 调用 pauseEffect: 方法暂停播放指定音效文件后， 可以通过该方法恢复播放。
• 调用 pauseAllEffects 方法暂停所有音效文件的播放后，也可以通过该方法恢复单个音效文件播放。

stopEffect:

- (int)stopEffect:(NSInteger)soundId;

停止播放指定音效文件

传入参数

返回值

• 0: 成功
• <0: 失败

注意

• 调用该方法停止播放指定音效文件。
• 该方法内部会主动调用 unloadEffect: 来卸载指定音效文。

setEffectsVolume:

- (int)setEffectsVolume:(NSInteger)volume;

调节所有音效文件的文件音量

传入参数

返回值

• 0: 成功
• <0: 失败

注意

• 该方法调节混音的所有音效文件在本地和远端播放的音量大小。
• 请在房间内调用该方法。

unloadAllEffects

- (int)unloadAllEffects;

卸载所有音效文件

返回值

• 0: 成功
• <0: 失败

注意

• 调用该方法卸载所有音效文件。如果引擎被销毁时有音效文件没有被卸载，SDK会自动调用该方法卸载所有音效文件。
• 调用 leaveChannel: 离开房间后，不会自动调用该方法卸载所有音效文件。如果需要在离开房间后卸载所有音效文件，需要应用主动调用该方法。

pauseAllEffects

- (int)pauseAllEffects;

暂停所有音效文件的播放

返回值

• 0: 成功
• <0: 失败

注意

该方法暂停所有音效文件的播放，可调用 resumeAllEffects 方法恢复播放。

resumeAllEffects

- (int)resumeAllEffects;

恢复所有音效文件的播放

返回值

• 0: 成功
• <0: 失败

注意

• 调用该方法恢复所有音效文件的播放。在调用 pauseAllEffects 暂停所有音效文件的播放后，可以调用该方法可恢复所有音效文件的播放。
• 调用 pauseEffect: 方法暂停单个指定音效文件的播放后，也可以调用该方法恢复播放，但是效率太低，不推荐这么使用。

stopAllEffects

- (int)stopAllEffects;

停止所有音效文件的播放

返回值

• 0: 成功
• <0: 失败

注意

该方法停止所有音效文件的播放。

setPublishFallbackOption:

- (int)setPublishFallbackOption:(BytePublishFallbackOption)option;

设置发布的音视频流回退选项

传入参数

返回值

• 0；方法调用成功；
• -1：方法调用失败；

注意

• 1. 在网络情况不理想、设备性能不足时，实时音视频的质量会下降。通过这个接口来设置网络情况不佳或性能不足时只发送小流，以保证通话质量。
• 1. 这个方法只在设置了发送多个流的情况下有效。
• 1. 必须在进房前设置，进房后设置或更改设置无效。
• 1. 设置回退选项后，本端发布的音视频流发生回退或从回退中恢复时，对端会收到 rtcEngine:OnRemoteStreamSwitch: 回调通知。

setSubscribeFallbackOption:

- (int)setSubscribeFallbackOption:(ByteSubscribeFallbackOption)option;

设置订阅的音视频流回退选项

传入参数

返回值

• 0：方法调用成功
• <0：方法调用失败

注意

• 在网络情况不理想、设备性能不足时，实时音视频的质量会下降。通过这个接口来设置网络情况不佳或性能不足时只订阅小流或音频流，以保证通话质量。
• 必须在进房前设置，进房后设置或更改设置无效。
• 设置回退选项后，本端订阅的音视频流发生回退或从回退中恢复时,会收到 rtcEngine: OnRemoteStreamSwitch:rtcEngine:OnRemoteStreamSwitch: 回调通知。
• 设置回退选项后，本端订阅的视频流因为回退分辨率发生变化时,会收到 rtcEngine:videoSizeChangedOfUid:size: 回调通知。

setRemoteUserPriority:uid:

- (int)setRemoteUserPriority:(ByteUserPriority)priority uid:(NSString *_Nonnull)uid;

设置用户优先级

传入参数

返回值

• 0：方法调用成功
• <0：方法调用失败

注意

• 该方法与 setSubscribeFallbackOption: 搭配使用。
• 如果开启了订阅流回退选项，弱网或性能不足时会优先保证收到的高优先级用户的流的质量。
• 该方法在进房前后都可以使用，可以修改远端用户的优先级。

setEncryptType:key:

- (void)setEncryptType:(ByteEncryptType)encrypt_type key:(NSString * _Nonnull)key;

设置AES加密算法和加密密钥
有四种内置的加密算法，详见 ByteEncryptType

传入参数

注意

• 该方法与 setCustomizeEncryptHandler: 为互斥关系, 即按照调用顺序，最后一个调用的方法为最终生效的版本。
• 该方法必须在调用 joinChannelByKey:channelName:info:uid: 之前调用，可重复调用，以最后调用的参数作为生效参数
• AES加密算法限制，超过36位的key会被截断，仅取前36位

setCustomizeEncryptHandler:

- (void)setCustomizeEncryptHandler:(id<ByteEncryptHandler> _Nullable)handler;

设置自定义加密和解密方式 需要实现对应的加密和解密方法。详情参考 ByteEncryptHandler

传入参数

注意

• 该方法与 setEncryptType:key: 为互斥关系, 即按照调用顺序，最后一个调用的方法为最终生效的版本
• 该方法必须在调用 joinChannelByKey:channelName:info:uid: 之前调用，可重复调用，以最后调用的参数作为生效参数
• 无论加密或者解密，其对原始数据的长度修改，需要控制在90%-120%之间，即如果输入数据为100字节，则处理完成后的数据必须在 90至120字节之间，如果加密或解密结果超出该长度限制，则该音视频桢会被丢弃
• 数据加密/解密为串行执行，因而视实现方式不同，可能会影响到最终渲染效率，是否使用该方法，需要由使用方谨慎评估

setScreenCapture:Rect:screenCaptureParam:

- (int)setScreenCapture:(BOOL)enable Rect:(CGRect)rect screenCaptureParam:(ScreenCaptureParam * _Nonnull)param;

配置外部屏幕采集

传入参数

返回值

0 :成功; -1 :失败;

注意

1.屏幕采集分为内部采集和外部采集，本方法属于外部采集。 内部采集：由 SDK 进行屏幕采集和后续所有流程 外部采集：用户负责采集屏幕数据帧，通过接口提供给 SDK 2.调用此方法发布本端屏幕共享流后，用户还需要通过设置定时任务周期性调用 pushScreenCaptureFrame:time:rotation: 方法，将需要发送的屏幕数据推送给 SDK。 3.调用该接口后远端能收到 rtcEngine:firstRemoteScreenFrameOfUid:size:elapsed: 和 rtcEngine:onStreamAdd: 事件。

pushScreenCaptureFrame:time:rotation:

- (void)pushScreenCaptureFrame:(CVPixelBufferRef _Nonnull )frame time:(CMTime)pts rotation:(int)rotation;

推送外部屏幕采集帧

传入参数

注意

1.屏幕采集分为内部采集和外部采集，本方法属于外部采集。

startScreenSharingWithParam:preferredExtension:groupId:

- (int)startScreenSharingWithParam:(ScreenCaptureParam *_Nonnull)param preferredExtension:(NSString *_Nullable)extension groupId:(NSString *_Nonnull)groupId API_AVAILABLE(ios(12));

开始内部屏幕采集

传入参数

返回值

0 :成功; -1 :失败;

注意

1.屏幕采集分为内部采集和外部采集，本方法属于内部采集。 内部采集：由 SDK 进行屏幕采集和后续所有流程 外部采集：用户负责采集屏幕数据帧，通过接口提供给 SDK 2.调用该接口后远端能收到 rtcEngine:firstRemoteScreenFrameOfUid:size:elapsed: 和 rtcEngine:onStreamAdd: 事件。 3.内部采集时，外部不需要屏幕采集帧。

API_AVAILABLE

- (void)stopScreenSharing API_AVAILABLE(ios(12));

停止内部屏幕采集

返回值

0 :成功; -1 :失败;

注意

屏幕采集分为内部采集和外部采集，本方法属于内部采集。

ByteRemoteStreamSwitchEvent

@interface ByteRemoteStreamSwitchEvent : NSObject

远端用户流切换的信息

成员变量

变量说明

uid

@property (nonatomic, copy) NSString * _Nonnull uid;

远端用户ID

isScreen

@property (nonatomic, assign) BOOL isScreen;

流是否是屏幕流

beforeVideoIndex

@property (nonatomic, assign) NSInteger beforeVideoIndex;

流切换前订阅视频流的分辨率对应的索引

afterVideoIndex

@property (nonatomic, assign) NSInteger afterVideoIndex;

流切换后订阅视频流的分辨率对应的索引

beforeVideoEnabled

@property (nonatomic, assign) BOOL beforeVideoEnabled;

流切换前是否有视频流

afterVideoEnabled

@property (nonatomic, assign) BOOL afterVideoEnabled;

流切换后是否有视频流

reason

@property (nonatomic, assign) ByteFallbackOrRecoverReason reason;

流切换原因