ByteRTCEngineKit

@interface ByteRTCEngineKit : NSObject

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

成员变量

静态函数

成员函数

变量说明

__deprecated_msg

__deprecated_msg("Will be removed in new version");

函数说明

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 内各种错误码、警告码的描述文字。

传入参数

返回值 描述文字。

feedbackGrade:type:desc:

+ (int)feedbackGrade:(NSInteger)grade type:(NSInteger)type desc:(NSString* _Nullable)desc;

通话结束，用户反馈上报

传入参数

返回值 0: 成功

-1: 还没加入过房间，上报失败 -2: 数据解析错误
-3: 字段缺失
-4: grade不合法

sharedEngineWithAppId:delegate:

+ (instancetype _Nonnull)sharedEngineWithAppId:(NSString * _Nonnull)appId delegate:(id<ByteRTCEngineDelegate> _Nullable)delegate __deprecated_msg("Will be removed in new version");

创建 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 __deprecated_msg("Will be removed in new version");

创建 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 __deprecated_msg("Will be removed in new version");

创建引擎对象，此方法应该作为正常 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 时自动触发销毁逻辑

setUserRole:

- (BOOL)setUserRole:(ByteRTCUserRoleType)role;

设置用户角色。
通过设置不同的用户角色，可以控制用户在房间内的行为：

• 能否发布音视频流；
  
• 用户自身是否在房间中隐身。
  

传入参数

返回值 方法调用结果。

• YES: 方法调用成功
• NO: 方法调用失败

注意

• 在加入房间前后，用户均可调用此方法设置用户角色。
• 在房间内，调用此方法成功切换角色后，房间内其他用户会收到相应的回调通知：
• 从静默观众切换至主播时，房间内其他用户会收到 rtcEngine:onUserJoined:elapsed:；
• 从主播切换至静默观众时，房间内其他用户会收到 rtcEngine:onUserLeave:reason: 。

clientRole

- (ByteRTCUserRoleType)clientRole;

获取当前用户角色。

返回值 当前用户角色，详见 ByteRTCUserRoleType 枚举类型。

joinRoomByKey:roomId:roomProfile:userInfo:

- (int)joinRoomByKey:(NSString *_Nullable)token roomId:(NSString *_Nonnull)roomId roomProfile:(ByteRTCRoomProfile)roomProfile userInfo:(ByteRTCUserInfo *_Nonnull)userInfo;

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

传入参数

返回值 方法调用结果。

• 0: 成功
• -1: roomId 为空，失败
• -2: userId 为空，失败

注意

• 使用不同 App ID 的 App 是不能互通的。
• 请务必保证生成 Token 使用的 App ID 和创建引擎时使用的 App ID 相同，否则会导致加入房间失败。
• 用户加入房间成功后，在本地网络状况不佳的情况下，SDK 可能会与服务器失去连接，此时 SDK 将会自动重连。重连成功后，本地会收到 rtcEngine:onUserJoined:elapsed: 回调通知。
• 同一个 App ID 的同一个房间内，每个用户的用户 ID 必须是唯一的。如果两个用户的用户 ID 相同，则后加入房间的用户会将先加入房间的用户踢出房间，并且先加入房间的用户会收到 rtcEngine:onError: 回调通知，错误类型为重复登录 BRERR_DUPLICATE_LOGIN。

leaveRoom:

- (int)leaveRoom:(void (^_Nullable)(ByteRTCRoomStats *_Nonnull stat))leaveRoomBlock;

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

传入参数

返回值 方法调用结果。

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

注意

• 主播角色用户离开房间后，房间内其他用户会收到 rtcEngine:onUserLeave:reason: 回调通知。
• 如果调用此方法后立即销毁引擎，SDK 将无法执行作为参数传入的 Block 块。

updateToken:

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

更新 Token。
Token 有一定的有效期，当 Token 过期时，用户需调用此方法更新房间的 Token 信息。
用户调用 joinRoomByKey:roomId:roomProfile:userInfo: 方法加入房间时，如果使用了过期的 Token 将导致加入房间失败，并会收到 rtcEngine:onJoinRoomResult:withUid:errorCode:joinType:elapsed: 回调通知，回调错误码为 ByteRtcErrorCode.ByteRTCErrorCodeInvalidTokenByteRtcErrorCode。此时需要重新获取 Token，并调用此方法更新 Token。

传入参数

返回值 方法调用结果。

• 0: 方法调用成功。
• <0: 方法调用失败。

注意

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

startAudioCapture

- (void)startAudioCapture;

开启内部音频采集。默认为关闭状态。
进房前调用该方法，本地用户会收到 rtcEngine:onMediaDeviceStateChanged:device_type:device_state:device_error:rtcEngine:onMediaDeviceStateChanged:device_type:device_state:device_error 的回调。
进房后调用该方法，房间中的其他用户会收到 rtcEngine:onUserStartAudioCapture: 的回调。

注意

• 调用 stopAudioCapture 可以关闭音频采集设备，否则，SDK 只会在销毁引擎的时候自动关闭设备。
• 无论是否发布音频数据，你都可以调用该方法开启音频采集，并且调用后方可发布音频。
• 尚未进房并且已使用自定义采集时，关闭自定义采集后并不会自动开启内部采集。你需调用此方法手动开启内部采集。

stopAudioCapture

- (void)stopAudioCapture;

关闭内部音频采集。默认为关闭状态。
进房前调用该方法，本地用户会收到 rtcEngine:onMediaDeviceStateChanged:device_type:device_state:device_error:rtcEngine:onMediaDeviceStateChanged:device_type:device_state:device_error 的回调。
进房后调用该方法，房间中的其他用户会收到 rtcEngine:onUserStopAudioCapture: 的回调。

注意

• 调用 startAudioCapture 可以开启音频采集设备。
• 设备开启后若一直未调用该方法关闭，则 SDK 会在销毁引擎的时候自动关闭音频采集设备。

setAudioScenario:

- (void)setAudioScenario:(ByteRTCAudioScenarioType)audioScenario;

设置音频场景类型。
你可以根据你的应用所在场景，选择合适的音频场景类型。
选择音频场景后，RTC 会自动根据客户端音频路由和发布订阅状态，适用通话音量/媒体音量。
本方法在进房前和进房后设置均可生效。

传入参数

注意

• 通话音量更适合通话、会议等对信息准确度更高的场景。通话音量会激活系统硬件信号处理，使通话声音更清晰。同时，音量无法降低到 0。
• 媒体音量更适合娱乐场景，因其声音的表现力会更强。媒体音量下，最低音量可以为 0。

muteLocalAudio:

- (void)muteLocalAudio:(ByteRTCMuteState)muteState;

控制本地音频流的发送状态：发送/不发送。
使用此方法后，房间中的其他用户会收到回调 rtcEngine:onUserMuteAudio:muteState:。

传入参数

返回值 方法调用结果

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

注意 本方法仅控制本地音频流的发送状态，并不影响本地音频采集状态。

muteRemoteAudio:muteState:

- (void)muteRemoteAudio:(NSString * _Nonnull)uid muteState:(ByteRTCMuteState)muteState;

设置对来自指定远端用户的音频流的接收状态。默认为接收。

传入参数

muteAllRemoteAudio:

- (void)muteAllRemoteAudio:(ByteRTCMuteState)muteState;

设置对来自远端的所有音频流的接收状态。默认为接收。

传入参数

注意 本方法只影响本地是否接收远端音频流，并不影响远端音频设备的采集发送功能。

setAudioVolumeIndicationInterval:

- (void)setAudioVolumeIndicationInterval:(NSInteger)interval;

开启/关闭音量提示。默认关闭。
开启音量提示后，将按设置的时间间隔收到本地采集音量或订阅的远端用户的音量信息回调。 关于回调的具体信息，参看 rtcEngine:onAudioVolumeIndication:totalRemoteVolume:。

传入参数

setRecordingVolume:

- (void)setRecordingVolume:(NSInteger)volume;

调节音频采集音量。

传入参数

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

setPlaybackVolume:

- (void)setPlaybackVolume:(NSInteger)volume;

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

传入参数

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

setLocalVideoRenderer:

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

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

传入参数

返回值

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

setLocalVideoRenderer:forRoomId:forUserId:

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

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

传入参数

返回值

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

setRemoteVideoRenderer:forRoomId:forUserId:

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

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

传入参数

返回值

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

setRemoteVideoRenderer:forUserId:

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

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

传入参数

返回值

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

setupRemoteScreenRenderer:forRoomId:forUserId:

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

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

传入参数

返回值

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

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

setupRemoteScreenRenderer:forUserId:

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

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

传入参数

返回值

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

注意 在应用开发中，通常在应用收到 rtcEngine:onFirstRemoteVideoFrameRendered:withFrameInfo: 事件后调用该方法进行远端视频设置

setVideoEncoderConfig:

- (int)setVideoEncoderConfig:(NSArray <ByteRTCVideoSolution *> * _Nullable)videoSolutions;

启动推送多路视频流，设置推送多路流时的各路视频参数， 包括分辨率、帧率、码率、缩放模式、网络不佳时的回退策略等。

传入参数

返回值

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

setLocalVideoCanvas:withCanvas:

- (int)setLocalVideoCanvas:(ByteRTCStreamIndex)streamIndex withCanvas:(ByteRTCVideoCanvas * _Nullable)canvas;

设置本地视频渲染时，使用的视图，并设置渲染模式。
你应在加入房间前，绑定本地视图。退出房间后，此设置仍然有效。 如果需要解除绑定，你可以调用本方法绑定空视图。

传入参数

返回值

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

setRemoteVideoCanvas:withIndex:withCanvas:

- (int)setRemoteVideoCanvas:(NSString * _Nonnull)uid withIndex:(ByteRTCStreamIndex)streamIndex withCanvas:(ByteRTCVideoCanvas * _Nullable)canvas;

设置来自指定远端用户 user_id 的视频渲染时，使用的视图，并设置渲染模式。
你应在加入房间前，绑定视图。退出房间后，此设置失效。
如果需要解除某个用户的绑定视图，你可以把 view 设置为空。

传入参数

返回值

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

注意

• 实际使用时，你可以在收到回调 rtcEngine:onUserJoined:elapsed: 或 onFirstRemoteVideoFrameonfirstremotevideoframe 时获得远端用户 user_id。
• 这两个回调的差别是：如果启用了视频录制功能，视频录制服务会作为一个哑客户端加入房间，因此其他客户端会收到对应的 rtcEngine:onUserJoined:elapsed: 回调；
• 而不会收到 onFirstRemoteVideoFrameonfirstremotevideoframe 回调。你不应给录制的亚客户端绑定视图（因为它不会发送视频流）。

startVideoCapture

- (void)startVideoCapture;

开启内部视频采集。默认为关闭状态。
进房前调用该方法，本地用户会收到 rtcEngine:onMediaDeviceStateChanged:device_type:device_state:device_error:rtcEngine:onMediaDeviceStateChanged:device_type:device_state:device_error 的回调。
进房后调用该方法，房间中的其他用户会收到 rtcEngine:onUserStartVideoCapture: 的回调。

注意

• 调用 stopVideoCapture 可以关闭视频采集设备，否则，SDK 只会在销毁引擎的时候自动关闭设备。
• 无论是否发布视频数据，你都可以调用该方法开启视频采集，并且调用后方可发布视频。
• 已使用自定义采集时，关闭自定义采集后并不会自动开启内部采集。你需调用此方法手动开启内部采集。

stopVideoCapture

- (void)stopVideoCapture;

关闭内部视频采集。默认为关闭状态。
进房前调用该方法，本地用户会收到 rtcEngine:onMediaDeviceStateChanged:device_type:device_state:device_error:rtcEngine:onMediaDeviceStateChanged:device_type:device_state:device_error 的回调。
进房后调用该方法，房间中的其他用户会收到 rtcEngine:onUserStopVideoCapture: 的回调。

注意

• 调用 startVideoCapture 可以开启视频采集设备。
• 设备开启后若一直未调用该方法关闭，则 SDK 会在销毁引擎的时候自动关闭音频采集设备。

muteLocalVideo:

- (int)muteLocalVideo:(ByteRTCMuteState)mute_state;

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

传入参数

返回值

• 0：成功
• <0：失败

muteRemoteVideo:withMuteState:

- (int)muteRemoteVideo:(NSString * _Nonnull)uid withMuteState:(ByteRTCMuteState)muteState;

设置是否播放远端视频流

传入参数

返回值

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

muteAllRemoteVideo:

- (int)muteAllRemoteVideo:(ByteRTCMuteState)muteState;

设置是否播放所有远端视频流

传入参数

返回值

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

setLocalVideoMirrorMode:

- (int)setLocalVideoMirrorMode:(ByteRTCMirrorMode) mode;

设置采用前置摄像头采集时，是否开启镜像模式。默认为关闭状态。
调用后，你会收到回调：rtcEngine:didMirrorStateChanged:

传入参数

返回值

• 0：成功
• <0：失败

isLocalVideoMirrorOn

- (bool)isLocalVideoMirrorOn;

获取本地视频镜像状态

返回值 当前镜像状态

• true：镜像为打开状态
• false：镜像为关闭状态

switchCamera:

- (int)switchCamera:(ByteRTCCameraID) cameraId;

切换移动端前置/后置摄像头

传入参数

返回值

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

replaceBackground:withDivideModel:

- (int) replaceBackground:(ByteRTCBackgroundMode)mode withDivideModel:(ByteRTCDivideModel)divideModel;

视频图像分割，替换背景

传入参数

返回值

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

checkVideoEffectSupport

- (int) checkVideoEffectSupport;

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

返回值 : 0: 不支持 >0: 支持视频特效

checkVideoEffectLicense:

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

视频特效许可证检查

传入参数

返回值 0: 许可证验证成功 !0: 许可证验证验证失败

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

enableVideoEffect:

- (int) enableVideoEffect:(BOOL)enabled;

创建/销毁视频特效引擎

传入参数

注意

• 该方法须在调用 checkVideoEffectLicense: 和 setVideoEffectAlgoModelPath: 后调用。
• 该方法不直接开启/关闭视频特效，你须在调用该方法后，调用 setVideoEffectNodes: 开启视频特效。
• 通用场景下，特效引擎会随 RTC 引擎销毁而销毁。当你对性能有较高要求时，可在不使用特效相关功能时调用该方法中 false 单独销毁特效引擎。

setVideoEffectAlgoModelPath:

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

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

传入参数

setVideoEffectNodes:

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

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

传入参数

注意 你须在调用 enableVideoEffect: 后调用该方法。

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;

设置特效强度

传入参数

注意 该接口仅适用于同时含有上述三个参数的特效资源，对于如大部分贴纸类等没有强度参数的特效，该接口调用无效。

setVideoEffectColorFilter:

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

设置颜色滤镜

传入参数

setVideoEffectColorFilterIntensity:

- (void) setVideoEffectColorFilterIntensity:(float) intensity;

设置颜色滤镜强度

传入参数

setMediaMetadataObserver:

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

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

传入参数

返回值

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

注意

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

enableAutoSubscribe:videoMode:

- (BOOL)enableAutoSubscribe:(ByteRTCSubscribeMode)audioMode videoMode:(ByteRTCSubscribeMode)videoMode;

设置订阅模式。
用户调用此方法设置房间中是音视频流的订阅模式。默认自动订阅。
如需开启手动订阅功能，建议在调用 joinRoomByKey:roomId:roomProfile:userInfo:方法加入房间前完成设置。

传入参数

返回值 方法执行结果。

• YES: 方法调用成功。
• NO: 方法调用失败。

subscribeStream:subscribeConfig:

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

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

传入参数

注意

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

unSubscribeStream:isScreen:

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

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

传入参数

注意

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

setAudioPlaybackDevice:

- (int)setAudioPlaybackDevice:(ByteRTCAudioPlaybackDevice)audioPlaybackDevice;

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

传入参数

返回值 方法调用结果

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

注意

• 该方法适用于手机等移动设备。
• 听筒和扬声器为移动设备自带的音频播放设备。听筒一般用于通话，扬声器一般用于外放。
• 连接有线或者蓝牙音频播放设备后，音频路由将切换至有线耳机或者蓝牙耳机。不同音频场景中，音频路由和发布订阅状态到音量类型的映射关系详见 ByteRTCAudioScenarioType 。
• 进房前和进房后，均可调用此方法设置音频播放设备。

startLiveTranscoding:observer:

- (int)startLiveTranscoding:(ByteRTCLiveTranscoding *_Nonnull)transcoding observer:(id<LiveTranscodingDelegate> _Nonnull)observer;

开启合流转推，并设置合流的视频视图布局和音频属性。

传入参数

注意

• 启用服务端转推时，设置 observer 为 null。
• 调用该方法后，启动结果和推流过程中的错误均会通过回调 rtcEngine:onLiveTranscodingResult:errorCode: 通知用户。

stopLiveTranscoding

- (int)stopLiveTranscoding;

停止合流转推。

返回值 方法调用结果。

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

updateLiveTranscoding:

- (int)updateLiveTranscoding:(ByteRTCLiveTranscoding *_Nonnull)transcoding;

更新合流转推参数。
启用合流转推功能后，你可以使用此方法更新合流转推功能配置参数。

传入参数

返回值 方法调用结果。

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

enableCloudRending:

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

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

传入参数

返回值 方法调用结果。

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

updateCloudRending:

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

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

传入参数

返回值 方法调用结果。

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

disableCloudRending

- (int)disableCloudRending;

停止云端渲染。

返回值 方法调用结果。

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

setVideoInputType:

- (void)setVideoInputType:(ByteRTCMediaInputType)type;

配置视频采集源。

传入参数

注意

• 1. 该方法在进房前后均可以调用。
• 1. 当你已调用 startVideoCapture 开启内部采集后，再调用此方法切换至自定义采集时，SDK 会自动关闭内部采集。
• 1. 当你已开启自定义采集后，想要切换至内部采集，你必须先调用此方法指定使用内部采集，然后调用 startVideoCapture 手动开启内部采集。

pushExternalVideoFrame:time:

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

推送外部视频帧。

传入参数

返回值

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

注意 使用外部推送视频帧，调用 setVideoInputType 开启外部视频源功能，详见 setVideoInputType:

pushExternalVideoFrame:time:rotation:

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

推送外部视频帧。

传入参数

返回值

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

注意 使用外部推送视频帧，调用 setVideoInputType: 开启外部视频源功能，详见 setVideoInputType:

pushExternalVideoFrame:time:rotation:extendedData:supplementaryInfo:

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

推送外部视频帧。

传入参数

返回值

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

pushExternalByteVideoFrame:

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

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

传入参数

返回值

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

enableExternalAudioDevice:playbackFormat:

- (void)enableExternalAudioDevice:(ByteRTCAudioFormat * _Nonnull) recordingFormat playbackFormat:(ByteRTCAudioFormat * _Nonnull) playbackFormat;

启用自定义音频采集渲染

传入参数

注意

• 此方法需要在进房前调用。
• 启用自定义音频采集渲染的状态在离开房间后仍然有效，会一直持续到调用 disableExternalAudioDevice 关闭自定义音频采集渲染为止。
• 启用自定义音频采集渲染后，仍需要使用 pushExternalAudioFrame:，推送外部音频数据，再使用 pullExternalAudioFrame: 拉取外部音频数据。
• 使用该方法启用自定义音频采集渲染后，SDK 会自动关闭内部采集使用的音频设备。
• 当你已调用 startAudioCapture 开启内部采集后，再调用此方法切换至自定义采集时，SDK 会自动关闭内部采集。
• 当你调用此方法开启自定义采集后，想要切换至内部采集，你必须先调用 disableExternalAudioDevice 关闭自定义采集，然后调用 startVideoCapture 手动开启内部采集。

disableExternalAudioDevice

- (void)disableExternalAudioDevice;

禁用已开启的自定义音频采集渲染，将音频采集渲染由自定义模块切换至内部模块。

注意

• 如果你已开启自定义音频采集渲染，你可以在进房前，使用本接口将音频采集渲染由自定义模块切换至内部模块。
• 使用该 API 禁用自定义音频采集渲染后， SDK 不会自动开启内部的音频采集，需要开启 SDK 内部采集请使用 startAudioCapture。
• 启用自定义音频采集渲染请使用 enableExternalAudioDevice:playbackFormat:。此方法需要在进房前调用。

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 毫秒数据量。

setRecordingAudioFrameParameters:channels:

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

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

传入参数

返回值 方法调用结果

• YES: 方法调用成功
• NO: 方法调用失败

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

setPlaybackAudioFrameParameters:channels:

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

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

传入参数

返回值 方法调用结果

• YES: 方法调用成功
• NO: 方法调用失败

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

setMixedAudioFrameParameters:channels:

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

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

传入参数

返回值 方法调用结果

• YES: 方法调用成功
• NO: 方法调用失败

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

setAudioFrameObserver:

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

设置音频数据回调观察者

传入参数

返回值 方法调用结果

• YES: 方法调用成功
• NO: 方法调用失败

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

pushExternalAudioFrame:

- (int)pushExternalAudioFrame:(ByteRTCAudioFrame * _Nonnull) audioFrame;

推送外部音频数据。

传入参数

返回值 方法调用结果

• 0: 设置成功
• <0: 设置失败

注意

• 推送外部音频数据前，必须开启自定义采集。
• 本方法中设置的 sampleRate（音频采样率） 和 channel（音频声道） 必须与 enableExternalAudioDevice:playbackFormat: 中设置的 sampleRate 和 channel 保持一致。

• 此方法推送音频数据的间隔为 10 毫秒。 samples (音频采样点个数）应该为 audioFrame.sampleRate / 100， 如设置采样率为 48000 时， 每次应该推送 480 个采样点。

• 音频采样格式为 S16。音频缓冲区内的数据格式必须为 PCM 数据，其容量大小应该为 audioFrame.samples

• 该函数运行在用户级线程内。若同时运行其他进程，将导致本进程中断。

pullExternalAudioFrame:

- (int)pullExternalAudioFrame:(ByteRTCAudioFrame * _Nonnull) audioFrame;

拉取外部音频数据。

传入参数

返回值 方法调用结果

• 0: 设置成功
• <0: 设置失败

注意

• 拉取外部音频数据前，必须开启自定义采集。
• 本方法中设置的 sampleRate（音频采样率） 和 channel（音频声道） 必须与 enableExternalAudioDevice:playbackFormat: 中设置的 sampleRate 和 channel 保持一致。

• 此方法拉取音频数据的间隔为 10 毫秒，音频采样格式为 S16。 samples (音频采样点个数）应该为 audioFrame.sampleRate / 100， 如设置采样率为 48000 时， 每次应该拉取 480 个采样点。

• 音频采样格式为 S16。音频缓冲区内的数据格式必须为 PCM 数据，其容量大小应该为 audioFrame.samples

• 该函数运行在用户级线程内。若同时运行其他进程，将导致本进程中断。

sendRoomMessage:

- (int)sendRoomMessage:(NSString * _Nonnull)msg;

给房间内的所有其他用户发送广播文本消息。（Broadcast），返回这次发送消息的编号。

传入参数

返回值 这次发送消息的编号，从 1 开始递增。

注意 1. 调用该函数后会收到一次 rtcEngine:onRoomMessageSendResult:error: 回调，通知消息发送方发送成功或失败；
2. 若文本消息发送成功，则房间内所有用户会收到 rtcEngine:onRoomMessageReceived:message:rtcEngine: onRoomMessageReceived:message: 回调。

sendRoomBinaryMessage:

- (int)sendRoomBinaryMessage:(NSData * _Nonnull)msg;

给房间内的所有其他用户发送广播二进制消息（Broadcast），返回这次发送消息的编号。

传入参数

返回值 这次发送消息的编号，从 1 开始递增。

注意 1. 调用该函数后会收到一次 rtcEngine:onRoomMessageSendResult:error:回调，通知消息发送方发送成功或失败；
2. 若二进制消息发送成功，则 房间内所有用户会收到 rtcEngine:onRoomBinaryMessageReceived:message: 回调。

setAudioPerformanceProfile:

- (void)setAudioPerformanceProfile:(ByteRTCAudioPerformanceProfile) profile;

通过设置音频处理策略等级，获得不同的音频处理质量，默认为 auto 模式。
auto 模式下，SDK 会根据应用所在机型等级，自动适配音频处理策略。一般情况下，使用 auto 模式就可满足你的音视频通话需求。
你应使用此方法，实现音频体验和系统性能占用之间的平衡:
如果你希望系统性能占用较低，你应设置较低的策略等级；如果你更在意音频质量，你应选择设置更高的策略等级。
音频处理策略详见 ByteRTCAudioPerformanceProfile。

传入参数

注意

• 如果你希望在此次音视频通话中设置音频处理策略等级，你必须在进房前调用此方法。
• 此设置会影响音频采集端在音频采集后，发送前对音频的处理策略，也会影响音频接收端在音频流接收后，播放前对音频的处理策略，达成不同的处理效果。
• 如果在进房后调用此方法，下次进房时才会应用你设置的策略等级。
• 如果以下策略无法满足需求，请联系技术支持人员实现自定义配置。

setBusinessId:

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

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

传入参数

返回值

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

注意

• 需要在调用 joinRoomByKey:roomId:roomProfile:userInfo: 之前调用， joinRoomByKey:roomId:roomProfile:userInfo:之后调用该方法无效。

sendUserMessage:message:

- (int64_t)sendUserMessage:(NSString * _Nonnull)uid message:(NSString * _Nonnull)message;

给房间内指定的用户发送文本消息（P2P），返回这次发送消息的编号。

传入参数

返回值 这次发送消息的编号，从 1 开始递增。

注意 1. 调用该函数后会收到一次 rtcEngine:onUserMessageSendResult:error: 回调，通知消息发送方发送成功或失败；
2. 若文本消息发送成功，则 uid 所指定的用户会收到 rtcEngine:onUserMessageReceived:message: 回调。

sendUserBinaryMessage:message:

- (int64_t)sendUserBinaryMessage:(NSString * _Nonnull)uid message:(NSData * _Nonnull)message;

给房间内指定的用户发送二进制消息（P2P），返回这次发送消息的编号。

传入参数

返回值 这次发送消息的编号，从 1 开始递增。

注意 1. 调用该函数后会收到一次 rtcEngine:onUserMessageSendResult:error:回调，通知消息发送方发送成功或失败；
2. 若二进制消息发送成功，则 uid 所指定的用户会收到 rtcEngine: onUserBinaryMessageReceived:message:rtcEngine:onUserBinaryMessageReceived:message:回调。

setRemoteAudioPlaybackVolume:volume:

- (void)setRemoteAudioPlaybackVolume:(NSString* _Nonnull)uid volume:(int)volume;

调节来自指定远端用户的音频播放音量，默认为 100。

传入参数

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会自动调用该方法卸载所有音效文件。
• 调用 leaveRoom: 离开房间后，不会自动调用该方法卸载所有音效文件。如果需要在离开房间后卸载所有音效文件，需要应用主动调用该方法。

pauseAllEffects

- (int)pauseAllEffects;

暂停所有音效文件的播放

返回值

• 0: 成功
• <0: 失败

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

resumeAllEffects

- (int)resumeAllEffects;

恢复所有音效文件的播放

返回值

• 0: 成功
• <0: 失败

注意

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

stopAllEffects

- (int)stopAllEffects;

停止所有音效文件的播放

返回值

• 0: 成功
• <0: 失败

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

setPublishFallbackOption:

- (int)setPublishFallbackOption:(ByteRTCPublishFallbackOption)option;

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

传入参数

返回值

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

注意

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

setSubscribeFallbackOption:

- (int)setSubscribeFallbackOption:(ByteRTCSubscribeFallbackOption)option;

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

传入参数

返回值

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

注意

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

setRemoteUserPriority:uid:

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

设置用户优先级

传入参数

返回值

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

注意

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

setEncryptType:key:

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

设置传输时使用内置加密的方式

传入参数

注意

• 使用传输时内置加密时，使用此方法；如果需要使用传输时自定义加密，参看 ByteRTCEncryptRawData:。 内置加密和自定义加密互斥，根据最后一个调用的方法确定传输加密的方案。

• 该方法必须在进房之前调用，可重复调用，以最后调用的参数作为生效参数。

setCustomizeEncryptHandler:

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

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

传入参数

注意

• 该方法与 setEncryptType:key: 为互斥关系, 即按照调用顺序，最后一个调用的方法为最终生效的版本

• 该方法必须在调用 joinRoomByKey:roomId:roomProfile:userInfo: 之前调用，可重复调用，以最后调用的参数作为生效参数

• 无论加密或者解密，其对原始数据的长度修改，需要控制在90%-120%之间，即如果输入数据为100字节，则处理完成后的数据必须在 90至120字节之间，如果加密或解密结果超出该长度限制，则该音视频桢会被丢弃

• 数据加密/解密为串行执行，因而视实现方式不同，可能会影响到最终渲染效率，是否使用该方法，需要由使用方谨慎评估

setScreenCapture:Rect:screenCaptureParam:

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

配置外部屏幕采集

传入参数

返回值 0 :成功;

-1 :失败;

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

pushScreenCaptureFrame:time:rotation:

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

推送外部屏幕采集帧

传入参数

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

startScreenSharingWithParam:preferredExtension:groupId:

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

开始内部屏幕采集

传入参数

返回值 0 :成功;

-1 :失败;

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

API_AVAILABLE

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

停止内部屏幕采集

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