ByteRtcEngineKit

@interface ByteRtcEngineKit : NSObject

ByteRtcEngineKit 类包含应用程序调用的主要方法。调用 ByteRtcEngineKit 的接口最好在同一个线程进行，不建议在不同的线程同时调用。

成员变量

静态函数

成员函数

变量说明

delegate

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

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

函数说明

sharedInstance

+ (ByteRtcEngineKit * _Nullable) sharedInstance;

获取 ByteRtcEngineKit 单例对象。

返回值

由 sharedEngineWithAppId:delegate: 创建的 ByteRtcEngineKit 对象

注意

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

destroy

+ (void)destroy;

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

注意

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

getSdkVersion

+ (NSString * _Nonnull)getSdkVersion;

获取 SDK 当前的版本号

返回值

NSString* 版本号

getErrorDescription:

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

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

传入参数

返回值

NSString* 描述文字

sharedEngineWithAppId:delegate:

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

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

传入参数

返回值

可用的 ByteRtcEngineKit 实例

注意

1. 该方法在第一次调用时初始化一个 RTCEngine 单例，除非调用 destroy 方法，否则后续的所有调用均 返回同一个内部实例
2. 连续多次调用该方法不会创建不同的 ByteRtcEngineKit，该方法应该与 destroy 成对使用
3. 必须使用相同的App ID，App间才能进行通话

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间才能进行通话

destroyEngine

- (void)destroyEngine;

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

注意

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

setupLocalVideo:

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

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

传入参数

返回值

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

注意

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

setLocalVideoMirrorMode:

- (int)setLocalVideoMirrorMode:(ByteVideoMirrorMode) mode;

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

传入参数

返回值

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

GetLocalVideoMirrorMode

- (bool)GetLocalVideoMirrorMode;

获得当前本地镜像状态

返回值

true：是镜像模式； false：不是镜像模式；

removeLocalVideo

- (void)removeLocalVideo;

解除绑定本地视频画布

setupRemoteVideo:

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

该方法绑定远程用户和显示视图，即设定 uid 指定的用户用哪个视图显示。

传入参数

返回值

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

注意

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

removeRemoteVideo:

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

去除特定远端视频。

传入参数

removeAllRemoteVideo

- (void)removeAllRemoteVideo;

去除所有远端视频。

setupRemoteScreen:

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

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

传入参数

返回值

0：方法调用成功；

注意

应用通常在收到远端 rtcEngine:firstRemoteScreenFrameOfUid:size:elapsed: 事件后调用该函数设置远端屏幕共享视图。

removeRemoteScreen:

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

去除特定远端屏幕。

传入参数

removeAllRemoteScreen

- (void)removeAllRemoteScreen;

去除所有远端屏幕。

joinChannelByKey:channelName:info:uid:

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

加入房间。 用户调用此方法加入房间，在一个房间内的用户可以相互通话。如果房间还未创建，将会自动为用户创建对应的房间。如果已在房间中，用户必 须调用 leaveChannel: 退出当前房间后，才能加入下一个房间。

传入参数

返回值

0: 方法调用成功 1: roomId 为空 2: userId 为空

注意

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

setVideoProfiles:

- (int) setVideoProfiles:(NSArray<ByteVideoSolution *> * _Nonnull)profiles;

该方法设置SimulCast发布的一组视频属性，每个属性对应一套视频参数，如分辨率、帧率、码率等。

传入参数

返回值

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

注意

给定的属性列表各项分辨率宽高比应保持一致，并按照从大到小的顺序排列

setClientRole:withKey:

- (int)setClientRole:(ByteRtcClientRole)role withKey:(NSString * _Nullable)permissionKey;

设置用户角色。 在加入房间前，用户可调用此方法设置用户角色（默认为主播）。加入房间后，用户也可通过此方法切换用户角色。

传入参数

返回值

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

注意

1.设置用户角色在房间模式（频道模式参考 setChannelProfile: ）为直播模式、游戏模式、云游戏模式时生效。 2.如果用户在加入房间成功后调用该方法切换用户角色，调用成功后，远端用户会收到相应的回调通知：用户角色从静默观众切换至观众或主播时会收到 rtcEngine:didJoinedOfUid:elapsed: 回调通知；用户角色从观众或主播切换至静默观众时会收到 rtcEngine:didOfflineOfUid:reason: 回调通知。 3.通信模式下，调用此接口不生效。

leaveChannel:

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

离开房间。 调用 joinChannelByKey:channelName:info:uid: 方法加入房间后，在通话结束时必须调用此方法结束通话，否则无法开始下一次通话。不管 当前是否在通话中，都可以调用此方法。此方法会将通话相关的所有资源释放掉。由于此方法是异步操作，调用返回时并没有真正退出房间。 真正退出房间后，会触发执行调用接口时传入的 Block。通信模式下的用户和其他房间模式下的主播、观众离开房间后，远端用户会收到 rtcEngine:didOfflineOfUid:reason: 回调通知。

传入参数

返回值

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

enableVideo

- (int)enableVideo;

该方法用于打开视频模块。

返回值

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

注意

可以在加入频道前或者通话中调用，在加入频道前调用，则自动开启视频模式，在通话中调用则由音频模式切换为视频模式。调用该方法后，房间中的其他用户会收到didVideoEnabled的回调。调用 disableVideo 方法可关闭视频模式。

disableVideo

- (int)disableVideo;

该方法用于关闭视频模块。

返回值

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

注意

可以在加入频道前或者通话中调用，在加入频道前调用，则自动开启纯音频模式，在通话中不可再切换为视频模式。在通话中调用则由视频模式切换为纯音频频模式。 只能进行语音通话，不能显示、发送自己的视频，也不能接收、显示别人的视频。 调用该方法后，房间中的其他用户会收到didVideoEnabled的回调。调用 enableVideo 方法可开启视频模式。

enableAudio

- (int)enableAudio;

打开音频模块。

返回值

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

注意

打开音频模块(默认为开启状态)。该方法为音频方法的总闸，设置引擎内部音频为开启状态，通过重置整个引擎响应，响应速度较慢。调用该方法后，房间中的其他用户会收到didAudioEnabled的回调。

disableAudio

- (int)disableAudio;

关闭音频模块。

返回值

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

注意

关闭音频没模块。该方法为音频方法的总闸，设置引擎内部音频为禁止状态，通过重置整个引擎响应，响应速度较慢。设置关闭音频后，只能进行视频通话，不能发送自己的语音，也不能听到别人的语音。调用该方法后，房间中的其他用户会收到didAudioEnabled的回调。

enableLocalVideo:

- (int)enableLocalVideo:(BOOL)enabled;

该方法开启或关闭本地视频采集。

传入参数

返回值

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

注意

请在 enableVideo后（或音视频模式下）调用该方法。使用该方法enable时打开摄像头并发送视频数据，disable时关闭摄像头且不发送视频数据，不影响接收远端视频。调用该方法后，房间中的其他用户会收到didLocalVideoEnabled的回调。

enableLocalAudio:

- (int)enableLocalAudio:(BOOL)enabled;

开启/关闭本地音频采集。

传入参数

返回值

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

注意

调用该方法后，房间中的其他用户会收到 rtcEngine:didLocalAudioEnabled:byUid: 事件回调。

renewChannelKey:

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

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

传入参数

返回值

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

注意

Token过期时，如果用户已经加入房间成功，则不会受到影响，Token 过期的错误会在用户下一次用过期的 Token 加入房间或由于本地网络状况不佳导致断网重连入房间时通知给用户。

startPreview

- (int)startPreview;

开启视频预览。

返回值

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

注意

此方法在进入频道前启动本地视频预览。启动本地视频预览后，如果调用 leaveChannel: 退出频道，本地预览仍然处于启动状态，如果需要关闭本地预览，需要调用stopPreview。调用该API前必须：调用setupLocalVideo设置预览窗口及属性；调用enableVideo开启视频功能。

stopPreview

- (int)stopPreview;

关闭视频预览，停止本地视频预览。

返回值

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

muteLocalAudioStream:

- (int)muteLocalAudioStream:(BOOL)mute;

静音本地音频流

传入参数

返回值

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

注意

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

muteRemoteAudioStream:mute:

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

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

传入参数

返回值

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

muteAllRemoteAudioStreams:

- (int)muteAllRemoteAudioStreams:(BOOL)mute;

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

传入参数

返回值

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

注意

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

muteLocalVideoStream:

- (int)muteLocalVideoStream:(BOOL)mute;

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

传入参数

返回值

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

注意

调用该方法后，房间中的其他用户会收到didVideoMuted的回调。

muteAllRemoteVideoStreams:

- (int)muteAllRemoteVideoStreams:(BOOL)mute;

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

传入参数

返回值

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

muteRemoteVideoStream:mute:

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

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

传入参数

返回值

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

publishScreen:frameRate:

- (int)publishScreen:(int)maxKbitrete frameRate:(int)frameRate;

发布本地共享屏幕流， 调用该方法后需要周期性调用 pushScreenFramepushScreenFrame: ，将要发送的屏幕数据送到 SDK 。

传入参数

返回值

0 :法调用成功；

注意

1.调用该方法后需要周期性调用 pushScreenFramepushScreenFrame: ，将要发送的屏幕数据送到 SDK 。 2.远端会收到 rtcEngine:firstRemoteScreenFrameOfUid:size:elapsed: 、rtcEngine:didStreamAdded: 事件。 3.通过 unpublishScreenunpublishScreen: 函数结束本地屏幕共享。

unpublishScreen

- (int)unpublishScreen;

取消共享本地屏幕流。

返回值

0 :方法调用成功；

注意

1.远端会收到 rtcEngine:didStreamRemoved: 事件

pushScreenFrame:

- (bool)pushScreenFrame:(ByteRtcVideoFrameData * _Nonnull)frame;

推送共享桌面的视频帧。

传入参数

返回值

YES: 推送成功; NO: 推送失败;

enableAutoSubscribe:

- (void)enableAutoSubscribe:(bool)enable;

开启/关闭自动订阅（手动订阅）功能。 此方法用于设置该房间中是否开启自动订阅（手动订阅）功能。

传入参数

注意

SDK 提供两种订阅功能：1.自动订阅功能，SDK 自动帮助用户订阅房间中所有其他用户发布的音视频流。 2.手动订阅功能，SDK 只通过 rtcEngine:didStreamAdded: 和 rtcEngine:didStreamRemoved: 回调通知用户 当前所在房间中有哪些音视频流，由用户根据自己的需要调用 subscribeStream:info: 方法手动订阅其他用户发布的音视频流。

unsubscribe:

- (void)unsubscribe:(NSString * _Nonnull)streamID;

停止订阅房间内指定的远端音视频流。

传入参数

注意

1.不管是否订阅了指定的远端音视频流，都可以调用此方法停止订阅。 2.此方法仅支持在开启手动订阅（关闭自动订阅）功能时调用，用户可通过调用 enableAutoSubscribe: 方法开启手动订阅功能。

subscribeStream:info:

- (void)subscribeStream:(NSString * _Nonnull)streamID info:(ByteSubscribeConfig* _Nonnull)info;

订阅指定的房间内远端音视频流。

传入参数

注意

1.用户调用 joinChannelByKey:channelName:info:uid: 方法加入房间后，当房间内有新的音视频流发布时，本端将会收到 rtcEngine:didStreamAdded: 回调通知。 此时用户可以根据需要选择性调用此方法订阅新的音视频流，或者保存流信息在将来需要时再调用此方法订阅该音视频流。 2.此方法仅支持订阅当前房间中的远端音视频流。如果指定的流在当前房间内不曾存在，则 SDK 不会订阅。 3.此方法仅支持在开启手动订阅（关闭自动订阅）功能时调用，用户可通过调用 enableAutoSubscribe: 方法开启手动订阅功能。 4.如果用户在未开启手动订阅（开启自动订阅）功能时调用此方法，SDK 不会订阅指定音视频流，同时会通过 rtcEngine:didOccurWarning: 回调通知用户订阅失败，回调警告码 ByteRtcWarningCode 。

enableAutoPublish:

- (void)enableAutoPublish:(bool) enable;

开启/关闭自动发布（手动发布）功能。 此方法用于设置该房间中是否开启自动发布（手动发布）功能。

传入参数

注意

SDK 提供两种发布功能：1.自动发布功能，SDK 在加入房间成功后会自动帮助用户发布本地音视频流到房间中。 2.手动发布功能，由用户根据自己的需求调用 publish 方法主动发布。

publish

- (void)publish;

发布本端音视频流到当前房间中。

注意

此方法仅支持在开启手动发布功能时调用，用户可通过调用 enableAutoPublish: 方法开启手动发布功能。

unpublish

- (void)unpublish;

停止向当前房间发布本端音视频流。

注意

此方法仅支持在开启手动发布功能时调用，用户可通过调用 enableAutoPublish: 方法开启手动发布功能。

getAudioMixingDuration

- (int)getAudioMixingDuration;

获取音乐文件时长

返回值

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

注意

请在房间内调用该方法。

getAudioMixingCurrentPosition

- (int)getAudioMixingCurrentPosition;

获取音乐文件播放进度

返回值

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

注意

请在房间内调用该方法。

stopAudioMixing

- (int)stopAudioMixing;

停止播放音乐文件及混音

返回值

0：成功 < 0：失败

注意

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

pauseAudioMixing

- (int)pauseAudioMixing;

暂停播放音乐文件

返回值

0: 成功 < 0: 失败

注意

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

resumeAudioMixing

- (int)resumeAudioMixing;

恢复播放音乐文件

返回值

0: 成功 < 0: 失败

注意

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

adjustAudioMixingVolume:

- (int)adjustAudioMixingVolume:(NSInteger)volume;

调节音乐文件的文件音量。

传入参数

返回值

0: 成功 < 0: 失败

注意

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

startAudioMixing:loopback:replace:cycle:

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

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

传入参数

返回值

0：成功 < 0：失败

注意

1. 该方法指定本地和麦克风采集的音频流进行混音或替换。替换是指用音频文件替换麦克风采集的音频流。
2. 该方法可以选择是否让对方听到本地播放的音频，并指定循环播放的次数。
3. 开始播放音乐文件及混音后，可以通过 stopAudioMixing 停止播放音乐文件。
4. 该方法混音数据来源外部文件，且支持的文件格式有: mp3，aac，m4a，3gp，wav。
5. 单个房间只支持一路音乐文件的播放，多次调用该函数后，只有最后一次调用会生效。
6. 请在房间内调用该方法。

setAudioMixingPosition:

- (int)setAudioMixingPosition:(NSInteger)pos;

设置音频文件的播放位置

传入参数

返回值

0: 成功 < 0: 失败

注意

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

adjustAudioMixingPlayoutVolume:

- (int)adjustAudioMixingPlayoutVolume:(NSInteger)volume;

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

传入参数

返回值

0: 成功 < 0: 失败

注意

1. 该方法调节混音的音乐文件在本地播放的音量大小。
2. 请在房间内调用该方法。

adjustAudioMixingPublishVolume:

- (int)adjustAudioMixingPublishVolume:(NSInteger)volume;

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

传入参数

返回值

0: 成功 < 0: 失败

注意

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

setVolumeOfEffect:withVolume:

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

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

传入参数

返回值

0: 成功 < 0: 失败

注意

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

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: 失败

注意

1. 可以多次调用该方法，通过传入不同的音效文件的 soundId 和 filePath，以实现同时播放多个音效文件，实现音效叠加。
2. 可以通过 stopEffectstopEffect: 方法停止播放指定音效文件。
3. 请在房间内调用该方法。

preloadEffect:filePath:

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

预加载指定音效文件

传入参数

返回值

0: 成功 < 0: 失败

注意

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

unloadEffect:

- (int)unloadEffect:(NSInteger)soundId;

卸载指定音效文件

传入参数

返回值

0: 成功 < 0: 失败

注意

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

pauseEffect:

- (int)pauseEffect:(NSInteger)soundId;

暂停播放指定音效文件

传入参数

返回值

0: 成功 < 0: 失败

注意

1. pauseEffectpauseEffect: 暂停播放指定音效文件可以通过该方法恢复播放。
2. pauseAllEffects 暂停所有音效文件的播放后，也可以通过该方法恢复单个音效文件播放。

resumeEffect:

- (int)resumeEffect:(NSInteger)soundId;

恢复播放指定音效文件

传入参数

返回值

0: 成功 < 0: 失败

注意

该方法恢复播放指定音效文件。

stopEffect:

- (int)stopEffect:(NSInteger)soundId;

停止播放指定音效文件

传入参数

返回值

0: 成功 < 0: 失败

注意

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

setEffectsVolume:

- (int)setEffectsVolume:(NSInteger)volume;

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

传入参数

返回值

0: 成功 < 0: 失败

注意

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

unloadAllEffects

- (int)unloadAllEffects;

卸载所有音效文件

返回值

0: 成功 < 0: 失败

注意

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

pauseAllEffects

- (int)pauseAllEffects;

暂停所有音效文件的播放

注意

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

resumeAllEffects

- (int)resumeAllEffects;

恢复所有音效文件的播放

返回值

0: 成功 < 0: 失败

注意

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

stopAllEffects

- (int)stopAllEffects;

停止所有音效文件的播放

返回值

0: 成功 < 0: 失败

注意

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

setChannelProfile:

- (int)setChannelProfile:(ByteChannelProfile)profile;

设置频道模式。 该方法用于设置房间频道模式。SDK 会针对不用的频道模式应用对应的优化策略。

传入参数

返回值

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

注意

1.用户必须在调用 joinChannelByKey:channelName:info:uid: 前设置频道模式，加入房间后设置不再生效。 2.为保证音视频质量和实时性，建议相同房间内的用户使用相同的频道模式。

enableAudioVolumeIndication:smooth:

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

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

传入参数

返回值

0： 代表方法调用成功

注意

开启或禁用发言者音量提示功能。功能开启时将以你设置的 interval 为间隔通过 rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume: 回调用户的音量。

setPublishFallbackOption:

- (int)setPublishFallbackOption:(BytePublishFallbackOption)option;

设置弱网条件下发布的音视频流回退选项

传入参数

返回值

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

setBusinessId:

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

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

传入参数

返回值

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

注意

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

replaceBackground:withDivideModel:

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

视频图像分割，替换背景

传入参数

返回值

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

disableBackground

- (void) disableBackground;

禁用视频图像分割，替换背景

setMediaMetadataObserver:

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

注册 metadata 观察者，用于接收或发送 metadata。 底层通过视频帧中添加 SEI 数据实现该功能。

传入参数

返回值

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

注意

使用视频自定义采集与渲染时，可以直接在视频帧中获取 metadata 。不建议使用本接口。

enableAudioVolumeIndication:smooth:

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

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

传入参数

返回值

0: 代表方法调用成功； <0: 代表方法调用失败

注意

开启或禁用发言者音量提示功能。功能开启时以一定时间间隔通过音量提示回调reportAudioVolumeIndicationOfSpeakers通知用户频道内音量较高的几个用户及他们的音量。

switchCamera

- (int)switchCamera;

切换摄像头。

返回值

0: 代表方法调用成功； <0: 代表方法调用失败

setDeviceId:

- (void)setDeviceId:(NSString*_Nullable)deviceId;

设置设备ID。

传入参数

返回值

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

setVideoResolution:andFrameRate:bitrate:

- (int)setVideoResolution: (CGSize)size andFrameRate: (NSInteger)frameRate bitrate: (NSInteger) bitrate;

设置本地视频属性。

传入参数

返回值

0: 代表方法调用成功； <0: 代表方法调用失败

注意

若设置的视频码率超出合理范围，SDK 会自动按照合理区间处理码率。

setExternalVideoSource:

- (void)setExternalVideoSource:(bool)enable;

设置外部视频输入源

传入参数

注意

1.该方法应该在startpreview和joinChannel之前调用

setEncryptType:key:

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

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

传入参数

注意

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

setCustomizeEncryptHandler:

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

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

传入参数

注意

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

enableCloudRending:

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

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

传入参数

返回值

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

updateCloudRending:

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

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

传入参数

返回值

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

disableCloudRending

- (int)disableCloudRending;

停止云端渲染。

返回值

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

ByteVideoSinkProtocol

@protocol ByteVideoSinkProtocol <NSObject>

视频外部渲染接口

成员函数

函数说明

shouldInitialize

- (BOOL)shouldInitialize;

通知外部渲染器实现，当前需要进行渲染器初始化工作

shouldStart

- (void)shouldStart;

通知外部渲染器实现，当前需要准备开始渲染

shouldStop

- (void)shouldStop;

通知外部渲染器实现，当前需要准备停止渲染

shouldDispose

- (void)shouldDispose;

通知外部渲染器实现，当前需要进行渲染器销毁工作

pixelFormat

- (ByteVideoPixelFormat)pixelFormat;

指定外部渲染器接收的视频帧格式类型

返回值

指定的返回格式类型，类型含义详见ByteVideoPixelFormat

renderPixelBuffer:rotation:extendedData:

- (void)renderPixelBuffer:(CVPixelBufferRef _Nonnull)pixelBuffer rotation:(ByteVideoRotation)rotation extendedData:(NSData * _Nullable)extendedData;

外部渲染视频帧数据回调接口

传入参数