ByteRTCRoom

@interface ByteRTCRoom : NSObject

成员变量

成员函数

变量说明

delegate

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

函数说明

destroy

- (void)destroy;

销毁房间

注意 退出并销毁调用 createRTCRoom: 所创建的房间。

setRtcRoomDelegate:

- (void)setRtcRoomDelegate:(id<ByteRTCRoomDelegate> _Nullable)roomDelegate;

通过设置 RTCRoomDelegateByteRTCRoomDelegate 代理，可以监听此 ByteRTCRoom 对象对应的回调事件。

传入参数

joinRoomByToken:userInfo:roomConfig:

- (int)joinRoomByToken:(NSString *_Nullable)token userInfo:(ByteRTCUserInfo *_Nonnull)userInfo roomConfig:(ByteRTCRoomConfig *_Nonnull)roomConfig;

加入房间。
调用 createRTCRoom: 创建房间后，调用此方法加入房间，同房间内其他用户进行音视频通话。

传入参数

返回值 方法调用结果。

• 0: 成功
• -1: 参数无效
• -2: 已经在房间内。接口调用成功后，只要收到返回值为 0 ，且未调用 leaveRoom 成功，则再次调用进房接口时，无论填写的房间 ID 和用户 ID 是否重复，均触发此返回值。
• -3: room 为空

注意

• 同一个 AppID 的同一个房间内，每个用户的用户 ID 必须是唯一的。如果两个用户的用户 ID 相同，则后加入房间的用户会将先加入房间的用户踢出房间，并且先加入房间的用户会收到 rtcEngine:onError: 回调通知，错误类型为重复登录 BRERR_DUPLICATE_LOGIN。
• 本地用户调用此方法加入房间成功后，会收到 rtcRoom:onRoomStateChanged:withUid:state:extraInfo: 回调通知。
• 本地用户调用 setUserVisibility: 将自身设为可见后加入房间，远端用户会收到 rtcRoom:onUserJoined:elapsed: 回调通知。
• 用户加入房间成功后，在本地网络状况不佳的情况下，SDK 可能会与服务器失去连接，此时 SDK 将会自动重连。重连成功后，本地会收到 rtcRoom:onUserJoined:elapsed: 回调通知。

setUserVisibility:

- (BOOL)setUserVisibility:(BOOL)enable;

设置用户可见性。默认可见。

传入参数

返回值

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

注意

• 该方法在加入房间前后均可调用。
• 在房间内调用此方法，房间内其他用户会收到相应的回调通知：
• 从 false 切换至 true 时，房间内其他用户会收到 rtcRoom:onUserJoined:elapsed: 回调通知；
• 从 true 切换至 false 时，房间内其他用户会收到 rtcRoom:onUserLeave:reason: 回调通知。
• 若调用该方法将可见性设为 false，此时尝试发布流会收到 ByteRTCWarningCodeSubscribeStreamForbiden 警告。

setMultiDeviceAVSync:

- (BOOL)setMultiDeviceAVSync:(NSString* _Nullable) audioUserId;

设置发流端音画同步。
当同一用户同时使用两个通话设备分别采集发送音频和视频时，有可能会因两个设备所处的网络环境不一致而导致发布的流不同步，此时你可以在视频发送端调用该接口，SDK 会根据音频流的时间戳自动校准视频流，以保证接收端听到音频和看到视频在时间上的同步性。

传入参数

返回值 方法调用结果：

• True：成功
• False：失败

注意

• 该方法在进房前后均可调用。
• 进行音画同步的音频发布用户 ID 和视频发布用户 ID 须在同一个 RTC 房间内。
• 调用该接口后音画同步状态发生改变时，你会收到 rtcRoom:onAVSyncStateChange: 回调。
• 同一 RTC 房间内允许存在多个音视频同步关系，但需注意单个音频源不支持与多个视频源同时同步。
• 如需更换同步音频源，再次调用该接口传入新的 audioUserId 即可；如需更换同步视频源，需先解除当前的同步关系，后在新视频源端开启同步。

leaveRoom

- (int)leaveRoom;

离开房间。
用户调用此方法离开房间，结束通话过程，释放所有通话相关的资源。

返回值 方法调用结果。

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

注意

• 用户离开房间后，本地会收到 onLeaveRoomWithStats:rtcRoom:onLeaveRoomWithStats: 的回调；
• 调用 setUserVisibility: 方法将自身设为可见的用户离开房间后，房间内其他用户会收到 rtcRoom:onUserLeave:reason: 回调通知。
• 调用 joinRoomByToken:userInfo:roomConfig: 方法加入房间后，必须调用此方法离开房间，否则无法进入下一个房间。无论当前是否在房间内，都可以调用此方法。重复调用此方法没有负面影响。

renewToken:

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

更新 Token。
用户调用 joinRoomByToken:userInfo:roomConfig: 方法加入房间时， 如果使用了过期的 Token 将导致加入房间失败，并会收到 rtcRoom:onRoomStateChanged:withUid:state:extraInfo: 回调， 回调错误码为 ByteRTCErrorCode 中的 ByteRTCErrorCodeInvalidToken。 此时需要重新获取 Token，并调用此方法更新 Token。更新 Token 后，SDK 会自动加入房间。

传入参数

返回值 方法调用结果。

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

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

setRemoteVideoConfig:remoteVideoConfig:

- (int) setRemoteVideoConfig:(NSString * _Nonnull) userId remoteVideoConfig:(ByteRTCRemoteVideoConfig *_Nonnull) remoteVideoConfig;

设置期望订阅的远端视频流的参数。

传入参数

注意

• 若使用 342 及以前版本的 SDK，调用该方法前请联系技术支持人员通过配置下发开启按需订阅功能。
• 该方法仅在发布端调用 enableSimulcastMode: 开启了发送多路视频流的情况下生效，此时订阅端将收到来自发布端与期望设置的参数最相近的一路流；否则订阅端只会收到一路参数为分辨率 640px × 360px、帧率 15fps 的视频流。
• 若发布端开启了推送多路流功能，但订阅端不对流参数进行设置，则默认接受发送端设置的分辨率最大的一路视频流。
• 该方法需在进房后调用，若想进房前设置，你需调用 joinRoomByToken:userInfo:roomConfig:，并对 roomConfig 中的 remoteVideoConfig 进行设置。
• SDK 会根据发布端和所有订阅端的设置灵活调整视频流的参数，具体调整策略详见推送多路流文档。

publishStream:

- (int)publishStream:(ByteRTCMediaStreamType)type;

在当前所在房间内发布本地通过摄像头/麦克风采集的媒体流

传入参数

返回值 方法调用结果：

• 0: 发布成功
• -1: 发布失败

注意

• 调用 setUserVisibility: 方法将自身设置为不可见后无法调用该方法，需将自身切换至可见后方可调用该方法发布摄像头音视频流。
• 如果你需要发布屏幕共享流，调用 publishScreen:。
• 如果你需要向多个房间发布流，调用 startForwardStreamToRooms:。
• 调用此方法后，房间中的所有远端用户会收到 rtcRoom:onUserPublishStream:type: 回调通知，其中成功收到了音频流的远端用户会收到 rtcEngine:onFirstRemoteAudioFrame: 回调，订阅了视频流的远端用户会收到 rtcEngine:onFirstRemoteVideoFrameDecoded:withFrameInfo: 回调。
• 调用 unpublishStream: 取消发布。

unpublishStream:

- (int)unpublishStream:(ByteRTCMediaStreamType)type;

停止将本地摄像头/麦克风采集的媒体流发布到当前所在房间中

传入参数

返回值

• 0: 停止发布成功
• -1: 停止发布失败

注意

• 调用 publishStream: 手动发布摄像头音视频流后，你需调用此接口停止发布。
• 调用此方法停止发布音视频流后，房间中的其他用户将会收到 rtcRoom:onUserUnpublishStream:type:reason: 回调通知。

publishScreen:

- (int)publishScreen:(ByteRTCMediaStreamType)type;

在当前所在房间内发布本地屏幕共享音视频流

传入参数

返回值

• 0: 发布成功
• -1: 发布失败

注意

• 调用 setUserVisibility: 方法将自身设置为不可见后无法调用该方法，需将自身切换至可见后方可调用该方法发布屏幕流。
• 调用该方法后，房间中的所有远端用户会收到 rtcRoom:onUserPublishScreen:type: 回调，其中成功收到音频流的远端用户会收到 rtcEngine:onFirstRemoteAudioFrame: 回调，订阅了视频流的远端用户会收到 rtcEngine:onFirstRemoteVideoFrameDecoded:withFrameInfo: 回调。
• 如果你需要向多个房间发布流，调用 startForwardStreamToRooms:。
• 调用 unpublishScreen: 取消发布。

unpublishScreen:

- (int)unpublishScreen:(ByteRTCMediaStreamType)type;

停止将本地屏幕共享音视频流发布到当前所在房间中

传入参数

返回值

• 0: 停止发布成功
• -1: 停止发布失败

注意

• 调用 publishScreen: 发布屏幕流后，你需调用此接口停止发布。
• 调用此方法停止发布屏幕音视频流后，房间中的其他用户将会收到 rtcRoom:onUserUnpublishScreen:type:reason: 回调。

subscribeStream:mediaStreamType:

- (void)subscribeStream:(NSString *_Nonnull)userId mediaStreamType:(ByteRTCMediaStreamType)mediaStreamType;

订阅房间内指定的通过摄像头/麦克风采集的媒体流。
该方法对自动订阅和手动订阅模式均适用。

传入参数

注意

• 你必须先通过 rtcRoom:onUserPublishStream:type: 回调获取当前房间里的远端摄像头音视频流信息，然后调用本方法按需订阅。
• 调用该方法后，你会收到 rtcRoom:onStreamSubscribed:userId:subscribeConfig: 通知方法调用结果。
• 关于其他调用异常，你会收到 rtcRoom:onRoomStateChanged:withUid:state:extraInfo:rtcRoom:onStreamStateChanged:withUid:state:extraInfo: 回调通知，具体异常原因参看 ByteRTCErrorCode。

unSubscribeStream:mediaStreamType:

- (void)unSubscribeStream:(NSString *_Nonnull)userId mediaStreamType:(ByteRTCMediaStreamType)mediaStreamType;

取消订阅房间内指定的通过摄像头/麦克风采集的媒体流。
该方法对自动订阅和手动订阅模式均适用。

传入参数

注意

• 调用该方法后，你会收到 rtcRoom:onStreamSubscribed:userId:subscribeConfig: 通知流的退订结果。
• 关于其他调用异常，你会收到 rtcRoom:onRoomStateChanged:withUid:state:extraInfo:rtcRoom:onStreamStateChanged:withUid:state:extraInfo: 回调通知，具体失败原因参看 ByteRTCErrorCode。

subscribeScreen:mediaStreamType:

- (void)subscribeScreen:(NSString *_Nonnull)userId mediaStreamType:(ByteRTCMediaStreamType)mediaStreamType;

订阅房间内指定的远端屏幕共享音视频流。
该方法对自动订阅和手动订阅模式均适用。

传入参数

注意

• 你必须先通过 rtcRoom:onUserPublishScreen:type: 回调获取当前房间里的远端屏幕流信息，然后调用本方法按需订阅。
• 调用该方法后，你会收到 rtcRoom:onStreamSubscribed:userId:subscribeConfig: 通知流的订阅结果。
• 关于其他调用异常，你会收到 rtcRoom:onRoomStateChanged:withUid:state:extraInfo:rtcRoom:onStreamStateChanged:withUid:state:extraInfo: 回调通知，具体异常原因参看 ByteRTCErrorCode。

unSubscribeScreen:mediaStreamType:

- (void)unSubscribeScreen:(NSString *_Nonnull)userId mediaStreamType:(ByteRTCMediaStreamType)mediaStreamType;

取消订阅房间内指定的远端屏幕共享音视频流。
该方法对自动订阅和手动订阅模式均适用。

传入参数

注意

• 调用该方法后，你会收到 rtcRoom:onStreamSubscribed:userId:subscribeConfig: 通知流的退订结果。
• 关于其他调用异常，你会收到 rtcRoom:onRoomStateChanged:withUid:state:extraInfo:rtcRoom:onStreamStateChanged:withUid:state:extraInfo: 回调通知，具体失败原因参看 ByteRTCErrorCode。

pauseAllSubscribedStream:

- (void)pauseAllSubscribedStream:(ByteRTCPauseResumControlMediaType) mediaType;

暂停接收来自远端的媒体流

传入参数

注意

• 该方法仅暂停远端流的接收，并不影响远端流的采集和发送；
• 该方法不改变用户的订阅状态以及订阅流的属性。
• 若想恢复接收远端流，需调用 resumeAllSubscribedStream:。
• 多房间场景下，仅暂停接收发布在当前所在房间的流。

resumeAllSubscribedStream:

- (void)resumeAllSubscribedStream:(ByteRTCPauseResumControlMediaType) mediaType;

恢复接收来自远端的媒体流

传入参数

注意

• 该方法仅恢复远端流的接收，并不影响远端流的采集和发送；
• 该方法不改变用户的订阅状态以及订阅流的属性。

sendUserMessage:message:config:

- (int64_t)sendUserMessage:(NSString *_Nonnull)userId message:(NSString *_Nonnull)message config:(ByteRTCMessageConfig)config;

给房间内指定的用户发送文本消息（P2P）。

传入参数

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

注意

• 在发送房间内文本消息前，必须先调用 joinRoomByToken:userInfo:roomConfig: 加入房间。
• 调用该函数后会收到一次 rtcRoom:onUserMessageSendResult:error: 回调，通知消息发送方发送成功或失败。
• 若文本消息发送成功，则 uid 所指定的用户会收到 rtcRoom:onUserMessageReceived:message: 回调。

sendUserBinaryMessage:message:config:

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

给房间内指定的用户发送二进制消息（P2P）。

传入参数

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

注意

• 在发送房间内二进制消息前，必须先调用 joinRoomByToken:userInfo:roomConfig: 加入房间。
• 调用该函数后会收到一次 rtcRoom:onUserMessageSendResult:error: 回调，通知消息发送方发送成功或失败；
• 若二进制消息发送成功，则 uid 所指定的用户会收到 rtcRoom:onUserBinaryMessageReceived:message: 回调。

sendRoomMessage:

- (int64_t)sendRoomMessage:(NSString *_Nonnull)message;

给房间内的所有其他用户发送文本消息。

传入参数

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

注意

• 在发送房间内文本消息前，必须先调用 joinRoomByToken:userInfo:roomConfig: 加入房间。
• 调用该函数后会收到一次 rtcRoom:onRoomMessageSendResult:error: 回调，通知消息发送方发送成功或失败；
• 若文本消息发送成功，则房间内所有远端用户会收到 rtcRoom:onRoomMessageReceived:message: 回调。

sendRoomBinaryMessage:

- (int64_t)sendRoomBinaryMessage:(NSData * _Nonnull)message;

给房间内的所有其他用户发送二进制消息。

传入参数

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

注意

• 在房间内广播二进制消息前，必须先调用 joinRoomByToken:userInfo:roomConfig: 加入房间。
• 调用该函数后会收到一次 rtcRoom:onRoomMessageSendResult:error: 回调，通知消息发送方发送成功或失败；
• 若二进制消息发送成功，则房间内所有用户会收到 rtcRoom:onRoomBinaryMessageReceived:message: 回调。

startForwardStreamToRooms:

- (int)startForwardStreamToRooms:(NSArray <ForwardStreamConfiguration *> * _Nullable)configurations;

开始跨房间转发媒体流。 在用户进入房间后调用本接口，实现向多个房间转发媒体流，适用于跨房间连麦等场景。

传入参数

返回值

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

注意

• 调用本方法后，将在本端触发 rtcRoom:onForwardStreamStateChanged: 回调。
• 调用本方法后，你可以通过监听 rtcRoom:onForwardStreamEvent: 回调来获取各个目标房间在转发媒体流过程中的相关事件。
• 开始转发后，目标房间中的用户将接收到本地用户进房 rtcRoom:onUserJoined:elapsed: 和发流 rtcRoom:onUserJoined:elapsed: 的回调。
• 调用本方法后，可以调用 updateForwardStreamToRooms: 更新目标房间信息，例如，增加或减少目标房间等。
• 调用本方法后，可以调用 stopForwardStreamToRooms 停止向所有房间转发媒体流。
• 调用本方法后，可以调用 pauseForwardStreamToAllRooms 暂停向所有房间转发媒体流。

updateForwardStreamToRooms:

- (int)updateForwardStreamToRooms:(NSArray <ForwardStreamConfiguration *> * _Nullable)configurations;

更新跨房间媒体流转发信息。
通过 startForwardStreamToRooms: 发起媒体流转发后，可调用本方法增加或者减少目标房间，或更新房间密钥。 调用本方法增加或删减房间后，将在本端触发 rtcRoom:onForwardStreamStateChanged: 回调，包含发生了变动的目标房间中媒体流转发状态。

传入参数

返回值

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

注意

• 增加目标房间后，新增目标房间中的用户将接收到本地用户进房 rtcRoom:onUserJoined:elapsed: 和发布 rtcRoom:onUserJoined:elapsed: 的回调。
• 删减目标房间后，原目标房间中的用户将接收到本地用户停止发布 rtcRoom:onUserUnpublishStream:type:reason: 和退房 rtcRoom:onUserLeave:reason: 的回调。

stopForwardStreamToRooms

- (void)stopForwardStreamToRooms;

停止跨房间媒体流转发。 通过 startForwardStreamToRooms: 发起媒体流转发后，可调用本方法停止向所有目标房间转发媒体流。

注意

• 调用本方法后，将在本端触发 rtcRoom:onForwardStreamStateChanged: 回调。
• 调用本方法后，原目标房间中的用户将接收到本地用户停止发布 rtcRoom:onUserUnpublishStream:type:reason: 和退房 rtcRoom:onUserLeave:reason: 的回调。
• 如果需要停止向指定的房间转发媒体流，请调用 updateForwardStreamToRooms: 更新房间信息。
• 如果需要暂停转发，请调用 pauseForwardStreamToAllRooms，并在之后随时调用 resumeForwardStreamToAllRooms 快速恢复转发。

pauseForwardStreamToAllRooms

- (void)pauseForwardStreamToAllRooms;

暂停跨房间媒体流转发。 通过 startForwardStreamToRooms: 发起媒体流转发后，可调用本方法暂停向所有目标房间转发媒体流。 调用本方法暂停向所有目标房间转发后，你可以随时调用 resumeForwardStreamToAllRooms 快速恢复转发。

注意 调用本方法后，目标房间中的用户将接收到本地用户停止发布 rtcRoom:onUserUnpublishStream:type:reason: 和退房 rtcRoom:onUserLeave:reason: 的回调。

resumeForwardStreamToAllRooms

- (void)resumeForwardStreamToAllRooms;

恢复跨房间媒体流转发。 调用 pauseForwardStreamToAllRooms 暂停转发之后，调用本方法恢复向所有目标房间转发媒体流。

注意 目标房间中的用户将接收到本地用户进房 rtcRoom:onUserJoined:elapsed: 和发布 rtcRoom:onUserJoined:elapsed: 的回调。

getRangeAudio

- (ByteRTCRangeAudio *_Nullable)getRangeAudio;

获取范围语音接口实例。

返回值 方法调用结果：

• ByteRTCRangeAudio：成功，返回一个 ByteRTCRangeAudio 实例。
• NULL：失败，当前 SDK 不支持范围语音功能。

注意 首次调用该方法须在创建房间后、加入房间前。

getSpatialAudio

- (ByteRTCSpatialAudio *_Nullable)getSpatialAudio;

获取空间音频接口实例。

返回值 方法调用结果：

• ByteRTCSpatialAudio：成功，返回一个 ByteRTCSpatialAudio 实例。
• NULL：失败，当前 SDK 不支持空间音频功能。

注意

• 首次调用该方法须在创建房间后、加入房间前。 空间音频相关 API 和调用时序详见空间音频。
• 只有在使用支持真双声道播放的设备时，才能开启空间音频效果；
• 机型性能不足可能会导致音频卡顿，使用低端机时，不建议开启空间音频效果；
• SDK 最多支持 30 个用户同时开启空间音频功能。

enableCloudRending:

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

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

传入参数

返回值 方法调用结果。

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

updateCloudRending:

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

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

传入参数

返回值 方法调用结果。

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

disableCloudRending

- (int)disableCloudRending;

停止云端渲染。

返回值 方法调用结果。

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

ByteRTCVideo

@interface ByteRTCVideo : NSObject

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

成员变量

静态函数

成员函数

变量说明

delegate

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

函数说明

destroyRTCVideo

+ (void)destroyRTCVideo;

销毁引擎实例对象

注意

• 请确保和需要销毁的 ByteRTCVideo 实例相关的业务场景全部结束后，才调用此方法
• 该方法在调用之后，会销毁所有和此 ByteRTCVideo 实例相关的内存，并且停止与媒体服务器的任何交互
• 调用本方法会启动 SDK 退出逻辑。引擎线程会保留，直到退出逻辑完成。因此，不要在回调线程中直接调用此 API，也不要在回调中等待主线程的执行，并同时在主线程调用本方法。不然会造成死锁。
• 可以通过 Objective-C 的ARC机制，在 dealloc 时自动触发销毁逻辑

getSdkVersion

+ (NSString * _Nonnull)getSdkVersion;

获取 SDK 当前的版本号。

返回值 SDK 当前的版本号。

getErrorDescription:

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

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

传入参数

返回值 描述文字。

createRTCVideo:delegate:parameters:

+ (ByteRTCVideo * _Nullable) createRTCVideo:(NSString * _Nonnull)appId delegate:(id<ByteRTCVideoDelegate> _Nullable)delegate parameters:(NSDictionary * _Nonnull)parameters;

创建引擎对象。
如果当前线程中未创建引擎实例，那么你必须先使用此方法，以使用 RTC 提供的各种音视频能力。
如果当前线程中已创建了引擎实例，再次调用此方法时，会返回已创建的引擎实例。

传入参数

返回值 可用的 ByteRTCVideo 实例

setAudioSourceType:

- (int)setAudioSourceType:(ByteRTCAudioSourceType) type;

切换音频采集方式

传入参数

返回值 方法调用结果：

• >0: 切换成功。
• -1：切换失败。

注意

• 进房前后调用此方法均有效。
• 如果你调用此方法由内部采集切换至自定义采集，SDK 会自动关闭内部采集。然后，调用 pushExternalAudioFrame: 推送自定义采集的音频数据到 RTC SDK 用于传输。
• 如果你调用此方法由自定义采集切换至内部采集，你必须再调用 startAudioCapture 手动开启内部采集。

setAudioRenderType:

- (int)setAudioRenderType:(ByteRTCAudioRenderType) type;

切换音频渲染方式

传入参数

返回值 方法调用结果：

• >0: 切换成功。
• -1：切换失败。

注意

• 进房前后调用此方法均有效。
• 如果你调用此方法切换至自定义渲染，调用 pullExternalAudioFrame: 获取音频数据。

startAudioCapture

- (void)startAudioCapture;

开启内部音频采集。默认为关闭状态。
内部采集是指：使用 RTC SDK 内置的视频采集机制进行视频采集。 调用该方法开启后，本地用户会收到 rtcEngine:onAudioDeviceStateChanged:device_type:device_state:device_error: 的回调。
非隐身用户进房后调用该方法，房间中的其他用户会收到 rtcEngine:onUserStartAudioCapture:uid: 的回调。

注意

• 若未取得当前设备的麦克风权限，调用该方法后会触发 rtcEngine:onWarning: 回调。
• 调用 stopAudioCapture 可以关闭音频采集设备，否则，SDK 只会在销毁引擎的时候自动关闭设备。
• 创建引擎后，无论是否发布音频数据，你都可以调用该方法开启音频采集，并且调用后方可发布音频。
• 尚未进房并且已使用自定义采集时，关闭自定义采集后并不会自动开启内部采集。你需调用此方法手动开启内部采集。
• 如果需要从自定义音频采集切换为内部音频采集，你必须先停止发布流，调用 disableExternalAudioDeviceRTCVideodisableExternalAudioDevice 关闭自定义采集，再调用此方法手动开启内部采集。

stopAudioCapture

- (void)stopAudioCapture;

关闭内部音频采集。默认为关闭状态。
内部采集是指：使用 RTC SDK 内置的视频采集机制进行视频采集。 调用该方法，本地用户会收到 rtcEngine:onAudioDeviceStateChanged:device_type:device_state:device_error: 的回调。
非隐身用户进房后调用该方法，房间中的其他用户会收到 rtcEngine:onUserStopAudioCapture:uid: 的回调。

注意

• 调用 startAudioCapture 可以开启音频采集设备。
• 如果不调用本方法停止内部视频采集，则只有当销毁引擎实例时，内部音频采集才会停止。

setAudioScenario:

- (void)setAudioScenario:(ByteRTCAudioScenarioType)audioScenario;

设置音频场景类型
你可以根据你的应用所在场景，选择合适的音频场景类型。
选择音频场景后，SDK 会自动根据客户端音频采集播放设备和状态，适用通话音量/媒体音量。
本方法在进房前和进房后设置均可生效。

传入参数

注意

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

setAudioProfile:

- (void)setAudioProfile:(ByteRTCAudioProfileType)audioProfile;

设置音质档位。当所选的 ByteRTCRoomProfile 中的音频参数无法满足你的场景需求时，调用本接口切换的音质档位。

传入参数

注意

• 该方法在进房前后均可调用；
• 支持通话过程中动态切换音质档位。

setVoiceChangerType:

- (void)setVoiceChangerType:(ByteRTCVoiceChangerType)voiceChanger;

设置变声特效类型

传入参数

注意

• 在进房前后都可设置。
• 对 RTC SDK 内部采集的音频和自定义采集的音频都生效。
• 只对单声道音频生效。
• 只在包含美声特效能力的 SDK 中有效。
• 与 setVoiceReverbType: 互斥，后设置的特效会覆盖先设置的特效。

setVoiceReverbType:

- (void)setVoiceReverbType:(ByteRTCVoiceReverbType)voiceReverb;

设置混响特效类型

传入参数

注意

• 在进房前后都可设置。
• 对 RTC SDK 内部采集的音频和自定义采集的音频都生效。
• 只对单声道音频生效。
• 只在包含美声特效能力的 SDK 中有效。
• 与 setVoiceChangerType: 互斥，后设置的特效会覆盖先设置的特效。

setCaptureVolume:volume:

- (void)setCaptureVolume:(ByteRTCStreamIndex)index volume:(int)volume;

调节音频采集音量

传入参数

注意 在开启音频采集前后，你都可以使用此接口设定采集音量。

setPlaybackVolume:

- (void)setPlaybackVolume:(NSInteger)volume;

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

传入参数

enableAudioPropertiesReport:

- (void)enableAudioPropertiesReport:(ByteRTCAudioPropertiesConfig* _Nonnull)config;

启用音频信息提示。

传入参数

注意 开启提示后，你可以：

• 通过 rtcEngine:onLocalAudioPropertiesReport: 回调获取本地麦克风和屏幕音频流采集的音频信息；
• 通过 rtcEngine:onRemoteAudioPropertiesReport:totalRemoteVolume: 回调获取订阅的远端用户的音频信息。

setRemoteAudioPlaybackVolume:remoteUid:playVolume:

- (void)setRemoteAudioPlaybackVolume:(NSString *_Nonnull)room_id remoteUid:(NSString *_Nonnull)uid playVolume:(NSInteger)volume;

调节来自远端用户的音频播放音量

传入参数

setEarMonitorMode:

- (void)setEarMonitorMode:(ByteRTCEarMonitorMode)mode;

开启/关闭耳返功能

传入参数

注意

• 你必须在使用 RTC SDK 提供的内部音频采集功能时，使用耳返功能。
• 耳返功能仅在连接了有线耳机时有效。
• 受 iOS 平台限制，RTC 仅支持软件耳返功能。

setEarMonitorVolume:

- (void)setEarMonitorVolume:(NSInteger)volume;

设置耳返的音量

传入参数

注意

• 设置耳返音量前，你必须先调用 setEarMonitorMode: 打开耳返功能。
• 耳返功能仅在使用 RTC SDK 提供的内部音频采集功能，并连接了有线耳机时有效。

setLocalVoicePitch:

- (void)setLocalVoicePitch:(NSInteger)pitch;

开启本地语音变调功能，多用于 K 歌场景。
使用该方法，你可以对本地语音的音调进行升调或降调等调整。

传入参数

enableVocalInstrumentBalance:

- (void)enableVocalInstrumentBalance:(BOOL)enable;

开启/关闭音量均衡功能。
开启音量均衡功能后，人声的响度会调整为 -16lufs。如果已调用 setAudioMixingLoudness:loudness: 传入了混音音乐的原始响度，此音乐播放时，响度会调整为 -20lufs。

传入参数

注意 该接口须在调用 startAudioMixing:filePath:config: 开始播放音频文件之前调用。

enablePlaybackDucking:

- (void)enablePlaybackDucking:(BOOL)enable;

打开/关闭音量闪避功能，适用于“一起看”等场景。
开启该功能后，当检测到远端人声时，本地的媒体播放音量会自动减弱，从而保证远端人声的清晰可辨；当远端人声消失时，本地媒体音量会恢复到闪避前的音量水平。

传入参数

setLocalVideoSink:withSink:withPixelFormat:

- (void)setLocalVideoSink:(ByteRTCStreamIndex)index withSink:(id<ByteRTCVideoSinkDelegate> _Nullable)videoSink withPixelFormat:(ByteRTCVideoSinkPixelFormat)requiredFormat;

将本地视频流与自定义渲染器绑定。

传入参数

注意

• RTC SDK 默认使用 RTC SDK 自带的渲染器（内部渲染器）进行视频渲染。
• 如果需要解除绑定，必须将 videoSink 设置为 null。进退房操作不会影响绑定状态。
• 一般在收到 rtcEngine:onFirstLocalVideoFrameCaptured:withFrameInfo: 回调通知完成本地视频首帧采集后，调用此方法为视频流绑定自定义渲染器；然后加入房间。

setRemoteVideoSink:withSink:withPixelFormat:

- (void)setRemoteVideoSink:(ByteRTCRemoteStreamKey* _Nonnull)streamKey withSink:(id<ByteRTCVideoSinkDelegate> _Nullable)videoSink withPixelFormat:(ByteRTCVideoSinkPixelFormat)requiredFormat;

将远端视频流与自定义渲染器绑定。

传入参数

注意

• RTC SDK 默认使用 RTC SDK 自带的渲染器（内部渲染器）进行视频渲染。
• 该方法进房前后均可以调用。若想在进房前调用，你需要在加入房间前获取远端流信息；若无法预先获取远端流信息，你可以在加入房间并通过 rtcRoom:onUserPublishStream:type: 回调获取到远端流信息之后，再调用该方法。
• 如果需要解除绑定，必须将 videoSink 设置为 null。进退房操作不会影响绑定状态。

enableSimulcastMode:

- (int) enableSimulcastMode:(BOOL) enabled;

该方法设置视频流发布端是否开启发布多路编码参数不同的视频流的模式。

传入参数

返回值 方法调用结果：

• 0: 成功
• <0: 失败

注意

• 你应在进房前或进房后但未发布流时，调用此方法。
• 开启推送多路视频流模式后，你可以调用 SetVideoEncoderConfig: 为多路视频流分别设置编码参数。
• 该功能关闭时，或该功能开启但未设置多路流参数时，默认只发一路视频流，该流的编码参数为：分辨率 640px × 360px，帧率 15fps。

SetMaxVideoEncoderConfig:

- (int)SetMaxVideoEncoderConfig:(ByteRTCVideoEncoderConfig * _Nullable) max_solution;

视频发布端设置期望发布的最大分辨率视频流参数，包括分辨率、帧率、码率、缩放模式、网络不佳时的回退策略等。
该接口支持设置一路视频流参数，设置多路参数请使用 SetVideoEncoderConfig:。

传入参数

返回值 方法调用结果：

• 0：成功
• !0：失败

注意

• 若调用该方法设置了期望发布的最大分辨率的流参数之前，已调用 enableSimulcastMode: 开启发布多路视频流的模式，SDK 会根据订阅端的设置自动调整发布的流数以及各路流的参数，其中最大分辨率为设置的分辨率，流数最多 4 条，具体参看推送多路流文档；否则仅发布该条最大分辨率的视频流。
• 调用该方法设置多路视频流参数前，SDK 默认仅发布一条分辨率为 640px × 360px，帧率为 15fps 的视频流。
• 该方法适用于摄像头采集的视频流，设置屏幕共享视频流参数参看 SetScreenVideoEncoderConfig:。

SetVideoEncoderConfig:

-(int)SetVideoEncoderConfig:(NSArray <ByteRTCVideoEncoderConfig *> * _Nullable) channel_solutions;

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

传入参数

返回值 方法调用结果：

• 0：成功
• !0：失败

注意

• 该方法是否生效取决于是否同时调用了 enableSimulcastMode: 开启发布多路参数不同的视频流模式。若未开启推送多路流模式，但调用本方法设置了多个分辨率，SDK 默认发布分辨率最大的一条流，多个分辨率的设置会在开启推送多路流模式之后生效。
• 调用该方法设置多路视频流参数前，SDK 默认仅发布一条分辨率为 640px × 360px，帧率为 15fps 的视频流。
• 调用该方法设置分辨率不同的多条流后，SDK 会根据订阅端设置的期望订阅参数自动匹配发送的流，具体规则参看推送多路流文档。
• 该方法适用于摄像头采集的视频流，设置屏幕共享视频流参数参看 SetScreenVideoEncoderConfig:。

SetScreenVideoEncoderConfig:

-(int)SetScreenVideoEncoderConfig:(ByteRTCVideoEncoderConfig * _Nullable) screen_solution;

为发布的屏幕共享视频流设置期望的编码参数，包括分辨率、帧率、码率、缩放模式、网络不佳时的回退策略等。

传入参数

返回值 方法调用结果： 0：成功
!0：失败

注意 调用该方法之前，屏幕共享视频流默认的编码参数为：分辨率 1920px × 1080px，帧率 15fps。

setVideoCaptureConfig:

- (int)setVideoCaptureConfig:(ByteRTCVideoCaptureConfig * _Nullable)captureConfig;

设置 RTC SDK 内部采集时的视频采集参数。
如果你的项目使用了 SDK 内部采集模块，可以通过本接口指定视频采集参数包括模式、分辨率、帧率。

传入参数

返回值

• 0: 成功；
• < 0: 失败；

注意

• 本接口在引擎创建后可调用，调用后立即生效。建议在调用 startVideoCapture 前调用本接口。
• 建议同一设备上的不同 Engine 使用相同的视频采集参数。
• 如果调用本接口前使用内部模块开始视频采集，采集参数默认为 Auto 模式。

setLocalVideoCanvas:withCanvas:

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

设置本地视频渲染时，使用的视图，并设置渲染模式。

传入参数

返回值

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

注意

• 你应在加入房间前，绑定本地视图。退出房间后，此设置仍然有效。
• 如果需要解除绑定，你可以调用本方法传入空视图。

updateLocalVideoCanvas:withRenderMode:withBackgroundColor:

- (int)updateLocalVideoCanvas:(ByteRTCStreamIndex)streamIndex withRenderMode:(ByteRTCRenderMode)renderMode withBackgroundColor:(NSUInteger)backgroundColor;

修改本地视频渲染模式和背景色。

传入参数

返回值

• 0: 成功
• -1: 失败。VideoCanvas 为空

注意 你可以在本地视频渲染过程中，调用此接口。调用结果会实时生效。

setRemoteVideoCanvas:withIndex:withCanvas:

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

渲染来自指定远端用户 uid 的视频流时，设置使用的视图和渲染模式。
如果需要解除视频的绑定视图，把 canvas 设置为空。

传入参数

返回值

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

注意

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

• 本地用户离开房间时，会解除调用此 API 建立的绑定关系；远端用户离开房间则不会影响。

updateRemoteVideoCanvas:withUserId:withIndex:withRenderMode:withBackgroundColor:

- (int)updateRemoteVideoCanvas:(NSString * _Nonnull)roomid withUserId:(NSString * _Nonnull)uid withIndex:(ByteRTCStreamIndex)streamIndex withRenderMode:(ByteRTCRenderMode)renderMode withBackgroundColor:(NSUInteger)backgroundColor;

startVideoCapture

- (void)startVideoCapture;

立即开启内部视频采集。默认为关闭状态。
内部视频采集指：使用 RTC SDK 内置视频采集模块，进行采集。
调用该方法后，本地用户会收到 rtcEngine:onVideoDeviceStateChanged:device_type:device_state:device_error: 的回调。
非隐身用户进房后调用该方法，房间中的其他用户会收到 rtcEngine:onUserStartVideoCapture:uid: 的回调。

注意

• 调用 stopVideoCapture 可以停止内部视频采集。否则，只有当销毁引擎实例时，内部视频采集才会停止。
• 创建引擎后，无论是否发布视频数据，你都可以调用该方法开启内部视频采集。只有当（内部或外部）视频采集开始以后视频流才会发布。
• 如果需要从自定义视频采集切换为内部视频采集，你必须先停止发布流，关闭自定义采集，再调用此方法手动开启内部采集。
• 内部视频采集使用的摄像头由 switchCamera: 接口指定。
• 自 v3.37.0 升级版本，你需要在应用中向用户申请摄像头权限后才能开始采集。

stopVideoCapture

- (void)stopVideoCapture;

立即关闭内部视频采集。默认为关闭状态。
内部视频采集指：使用 RTC SDK 内置视频采集模块，进行采集。
调用该方法后，本地用户会收到 rtcEngine:onVideoDeviceStateChanged:device_type:device_state:device_error: 的回调。
非隐身用户进房后调用该方法，房间中的其他用户会收到 rtcEngine:onUserStopVideoCapture:uid: 的回调。

注意

• 调用 startVideoCapture 可以开启内部视频采集。
• 如果不调用本方法停止内部视频采集，则只有当销毁引擎实例时，内部视频采集才会停止。

setLocalVideoMirrorType:

- (int)setLocalVideoMirrorType:(ByteRTCMirrorType) mirrorType;

为采集到的视频流开启镜像

传入参数

注意

• 切换视频源不影响镜像设置。
• 屏幕视频流始终不受镜像设置影响。
• 该接口调用前，各视频源的初始状态如下：

setVideoRotationMode:

- (int)setVideoRotationMode:(ByteRTCVideoRotationMode) rotationMode;

设置采集视频的旋转模式。默认以 App 方向为旋转参考系。
接收端渲染视频时，将按照和发送端相同的方式进行旋转。

传入参数

返回值 0:设置成功 <0:设置失败

注意

• 旋转仅对内部视频采集生效，不适用于外部视频源和屏幕源。
• 调用该接口时已开启视频采集，将立即生效；调用该接口时未开启视频采集，则将在采集开启后生效。
• 更多信息请参考视频采集方向。

switchCamera:

- (int)switchCamera:(ByteRTCCameraID) cameraId;

切换视频内部采集时使用的前置/后置摄像头
调用此接口后，在本地会触发 rtcEngine:onVideoDeviceStateChanged:device_type:device_state:device_error: 回调。

传入参数

返回值

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

注意

• 默认使用前置摄像头。
• 如果你正在使用相机进行视频采集，切换操作当即生效；如果相机未启动，后续开启内部采集时，会打开设定的摄像头。

checkVideoEffectLicense:

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

视频特效许可证检查

传入参数

返回值

• 0: 调用成功。
• 1000: 未集成特效 SDK。
• 1001: 特效 SDK 不支持该功能。
• < 0: 调用失败。具体错误码，参看 错误码表。

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

enableVideoEffect:

- (int)enableVideoEffect:(BOOL)enabled;

创建/销毁视频特效引擎

传入参数

返回值

• 0: 调用成功。
• 1000: 未集成特效 SDK。
• 1001: 特效 SDK 不支持该功能。
• < 0: 调用失败。具体错误码，参看 错误码表。

注意

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

setVideoEffectAlgoModelPath:

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

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

传入参数

setVideoEffectNodes:

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

设置视频特效素材包

传入参数

返回值

• 0: 调用成功。
• 1000: 未集成特效 SDK。
• 1001: 特效 SDK 不支持该功能。
• < 0: 调用失败。具体错误码，参看 错误码表。

注意 在调用这个方法之前，你须先调用 enableVideoEffect: 。

updateVideoEffectNode:nodeKey:nodeValue:

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

设置特效强度

传入参数

返回值

• 0: 调用成功。
• 1000: 未集成特效 SDK。
• 1001: 特效 SDK 不支持该功能。
• < 0: 调用失败。具体错误码，参看 错误码表。

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

setVideoEffectColorFilter:

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

设置颜色滤镜

传入参数

返回值

• 0: 调用成功。
• 1000: 未集成特效 SDK。
• 1001: 特效 SDK 不支持该功能。
• < 0: 调用失败。具体错误码，参看 错误码表。

setVideoEffectColorFilterIntensity:

- (int) setVideoEffectColorFilterIntensity:(float) intensity;

设置已启用的颜色滤镜强度

传入参数

返回值

• 0: 调用成功。
• 1000: 未集成特效 SDK。
• 1001: 特效 SDK 不支持该功能。
• < 0: 调用失败。具体错误码，参看 错误码表。

initVirtualBackground:withModel:

- (int) initVirtualBackground:(NSString* _Nonnull)licensePath withModel:(NSString* _Nonnull)modelPath;

虚拟背景功能初始化。

传入参数

返回值

• 0: 调用成功。
• 1000: 未集成特效 SDK。
• 1001: 特效 SDK 不支持该功能。
• > 40000: 调用失败，CV SDK 授权错误，具体错误码请参考 错误码表。
• < 0: 调用失败，CV SDK 内部错误，具体错误码请参考 错误码表。

enableVirtualBackground:

- (int) enableVirtualBackground:(ByteRTCVirtualBackgroundSource* _Nonnull)source;

开启虚拟背景。

传入参数

返回值

• 0: 调用成功。
• < 0: 调用失败，CV SDK 内部错误，具体错误码请参考 CV SDK 文档。
• -1: 调用失败，未调用 initVirtualBackground:withModel: 或调用失败，导致 license 验证失败。
• -4: 调用失败，自定义背景图片打开失败。
• -37: 调用失败，自定义背景图片解码失败。
• -38: 调用失败，图片格式不支持。支持的图片格式是 jpg、jpeg、和 png。

注意

• 调用此接口前，需要先调用 initVirtualBackground:withModel: 初始化 CV 环境；
• 虚拟背景仅支持摄像头采集的视频流，包括 RTC SDK 内部机制采集的方式和自定义采集的方式。虚拟背景不支持屏幕视频流。

disableVirtualBackground

- (int) disableVirtualBackground;

关闭虚拟背景。

返回值

• 0: 调用成功。
• < 0: 调用失败，具体错误码请参考 CV SDK 文档。

注意 调用 enableVirtualBackground: 开启虚拟背景后，可以调用此接口关闭虚拟背景。

enableEffectBeauty:

- (int) enableEffectBeauty:(BOOL)enable;

开启/关闭基础美颜

传入参数

返回值

• 0: 开启/关闭成功。
• 1000: 未集成特效 SDK。
• 1001: RTC SDK 版本不支持此功能。
• 1002: 特效 SDK 当前版本不支持此功能，建议使用特效 SDK V4.3.1 版本。
• 1003: 联系技术支持人员。
• 1004: 正在下载相关资源，下载完成后生效。
• <0: 调用失败，特效 SDK 内部错误，具体错误码请参考错误码表。

注意

• 本方法不能与高级视频特效接口共用。如已购买高级视频特效，建议调用 enableVideoEffect: 使用高级特效、贴纸功能等。
• 使用此功能需要集成特效 SDK，建议使用特效 SDK V4.3.1+ 版本。
• 调用 setBeautyIntensity:withIntensity: 设置基础美颜强度。若在调用本方法前没有设置美颜强度，则初始美白、磨皮、锐化强度均为 0.5。
• 本方法仅适用于视频源，不适用于屏幕源。

setBeautyIntensity:withIntensity:

- (int) setBeautyIntensity:(ByteRTCEffectBeautyMode) beautyMode withIntensity:(float)intensity;

调整基础美颜强度

传入参数

返回值

• 0: 开启成功。
• 1000: 未集成特效 SDK。
• 1001: RTC SDK 版本不支持此功能。
• <0: 调用失败，特效 SDK 内部错误，具体错误码请参考错误码表。

注意

• 若在调用 enableVideoEffect: 前设置美颜强度，则对应美颜功能的强度初始值会根据设置更新。
• 销毁引擎后，美颜功能强度恢复默认值。

setCameraZoomRatio:

- (int) setCameraZoomRatio: (float) zoom_val;

设置当前使用的摄像头（前置/后置）的变焦倍数

传入参数

返回值

• 0： 成功。
• < 0： 失败。

注意

• 必须已调用 startVideoCapture 使用 SDK 内部采集模块进行视频采集时，才能设置摄像头变焦倍数。
• 设置结果在调用 stopVideoCapture 关闭内部采集后失效。

getCameraZoomMaxRatio

- (float) getCameraZoomMaxRatio;

获取当前使用的摄像头（前置/后置）的最大变焦倍数

返回值 最大变焦倍数

注意 必须已调用 startVideoCapture 使用 SDK 内部采集模块进行视频采集时，才能检测摄像头最大变焦倍数。

isCameraZoomSupported

- (bool) isCameraZoomSupported;

检测当前使用的摄像头（前置/后置），是否支持变焦（数码/光学变焦）。

返回值

• true: 支持
• false: 不支持

注意 必须已调用 startVideoCapture 使用 SDK 内部采集模块进行视频采集时，才能检测摄像头变焦能力。

isCameraTorchSupported

- (bool) isCameraTorchSupported;

检测当前使用的摄像头（前置/后置），是否支持闪光灯。

返回值

• true: 支持
• false: 不支持

注意 必须已调用 startVideoCapture 使用 SDK 内部采集模块进行视频采集时，才能检测闪光能力。

setCameraTorch:

- (int) setCameraTorch: (ByteRTCTorchState)torch_state;

打开/关闭当前使用的摄像头（前置/后置）的闪光灯

传入参数

返回值

• 0： 成功。
• < 0： 失败。

注意

• 必须已调用 startVideoCapture 使用 SDK 内部采集模块进行视频采集时，才能设置闪光灯。
• 设置结果在调用 stopVideoCapture 关闭内部采集后失效。

isCameraFocusPositionSupported

- (bool)isCameraFocusPositionSupported;

检查当前使用的摄像头是否支持手动对焦。

返回值

• true: 支持。
• false: 不支持。

注意 必须已调用 startVideoCapture 使用 SDK 内部采集模块进行视频采集，才能检查摄像头是否支持手动对焦。

setCameraFocusPosition:

- (int)setCameraFocusPosition:(CGPoint)position;

设置当前使用的摄像头的对焦点。

传入参数

返回值

• 0: 成功。
• < 0: 失败。

注意

• 必须已调用 startVideoCapture 使用 SDK 内部采集模块进行视频采集，并且使用 SDK 内部渲染时，才能设置对焦点。
• 对焦点设置为画布中央（即x和y均取 0.5）时，恢复系统默认值。
• 调用 stopVideoCapture 关闭内部采集后，设置的对焦点失效。

isCameraExposurePositionSupported

- (bool)isCameraExposurePositionSupported;

检查当前使用的摄像头是否支持手动设置曝光点。

返回值

• true: 支持。
• false: 不支持。

注意 必须已调用 startVideoCapture 使用 SDK 内部采集模块进行视频采集时，才能检查曝光点设置能力。

setCameraExposurePosition:

- (int)setCameraExposurePosition:(CGPoint)position;

设置当前使用的摄像头的曝光点。

传入参数

返回值

• 0: 成功。
• < 0: 失败。

注意

• 必须已调用 startVideoCapture 使用 SDK 内部采集模块进行视频采集，并且使用 SDK 内部渲染时，才能设置曝光点。
• 曝光点设置为画布中央（即x和y均取 0.5）时，恢复系统默认值。
• 调用 stopVideoCapture 关闭内部采集后，设置的曝光点失效。

setCameraExposureCompensation:

- (int)setCameraExposureCompensation:(float)val;

设置当前使用的摄像头的曝光补偿。

传入参数

返回值

• 0: 成功。
• < 0: 失败。

注意

• 必须已调用 startVideoCapture 使用 SDK 内部采集模块进行视频采集时，才能设置曝光补偿。
• 调用 stopVideoCapture 关闭内部采集后，设置的曝光补偿失效。

registerFaceDetectionObserver:withInterval:

- (int) registerFaceDetectionObserver:(_Nullable id<ByteRTCFaceDetectionObserver>)faceDetectionObserver withInterval:(NSInteger)interval;

注册人脸检测结果回调观察者
注册此观察者后，你会周期性收到 onFaceDetectionResult: 回调。

传入参数

返回值

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

sendSEIMessage:andMessage:andRepeatCount:

- (int)sendSEIMessage:(ByteRTCStreamIndex)streamIndex andMessage:(NSData* _Nonnull)message andRepeatCount:(int)repeatCount;

在视频通信时，通过视频帧发送 SEI 数据。

传入参数

返回值

• >=0: 将被添加到视频帧中的 SEI 的数量
• < 0: 发送失败

注意

• 你可以通过此接口对 RTC SDK 内部采集的视频帧添加 SEI。对于采用自定义采集获得的视频帧：如果原视频帧中没有添加 SEI 数据，那么你可以调用此接口为其中添加 SEI 信息后，进行编码传输；如果原视频帧中已添加了 SEI 数据，那么，调用此接口不生效
• 如果调用此接口之后的 2s 内，没有可带 SEI 的视频帧（比如没有开启视频采集和传输），那么，SEI 数据不会被加进视频帧中。
• 消息发送成功后，远端会收到 rtcEngine:onSEIMessageReceived:andMessage: 回调。

registerLocalVideoProcessor:withConfig:

- (int)registerLocalVideoProcessor:(_Nullable id<ByteRTCVideoProcessorDelegate>) processor withConfig:(ByteRTCVideoPreprocessorConfig* _Nullable)config;

设置自定义视频前处理器。
使用这个视频前处理器，你能够调用 processVideoFrame: 对 RTC SDK 采集得到的视频帧进行前处理，并将处理后的视频帧用于 RTC 音视频通信。

传入参数

返回值

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

注意

• 重复调用此接口时，仅最后一次调用生效。效果不会叠加。
• 对于 iOS 平台，将 ByteRTCVideoPreprocessorConfig 中的 required_pixel_format 设置为 kVideoPixelFormatUnknown，可以通过避免格式转换带来一些性能优化。

registerLocalEncodedVideoFrameObserver:

- (void)registerLocalEncodedVideoFrameObserver:(_Nullable id<ByteRTCLocalEncodedVideoFrameObserver>) frameObserver;

注册本地视频帧监测器。
无论使用内部采集还是自定义采集，调用该方法后，SDK 每监测到一帧本地视频帧时，都会将视频帧信息通过 onLocalEncodedVideoFrame:Frame: 回调给用户

传入参数

注意 该方法可在进房前后任意时间调用，在进房前调用可保证尽可能早地监测视频帧并触发回调

setAudioRoute:

- (int)setAudioRoute:(ByteRTCAudioRoute)audioRoute;

设置当前音频播放路由。默认使用 setDefaultAudioRoute: 中设置的音频路由。
音频播放路由发生变化时，会收到 rtcEngine:onAudioRouteChanged: 回调。

传入参数

返回值

• 0: 方法调用成功
• < 0: 方法调用失败。失败原因参看 ByteRTCMediaDeviceWarning 回调。指定为 kAudioRouteUnknown 时将会失败。

注意

• 连接有线或者蓝牙音频播放设备后，音频路由将自动切换至此设备。
• 移除后，音频设备会自动切换回原设备。
• 不同音频场景中，音频路由和发布订阅状态到音量类型的映射关系详见 ByteRTCAudioScenarioType 。

getAudioRoute

- (ByteRTCAudioRoute)getAudioRoute;

获取当前使用的音频播放路由。

返回值 详见 ByteRTCAudioRoute

注意 要设置音频路由，详见 setAudioRoute:。

enableExternalSoundCard:

- (void)enableExternalSoundCard:(bool)enable;

启用匹配外置声卡的音频处理模式

传入参数

注意

• 当采用外接声卡进行音频采集时，建议开启此模式，以获得更好的音质。
• 开启此模式时，仅支持耳机播放。如果需要使用扬声器或者外置音箱播放，关闭此模式。

setDefaultAudioRoute:

- (int)setDefaultAudioRoute:(ByteRTCAudioRoute)audioRoute;

将默认的音频播放设备设置为听筒或扬声器。

传入参数

返回值 方法调用结果

• 0: 方法调用成功。立即生效。当所有音频外设移除后，音频路由将被切换到默认设备。
• < 0: 方法调用失败。指定除扬声器和听筒以外的设备将会失败。

注意

• 进房前后都可以调用。
• 更多注意事项参见音频路由。

startLiveTranscoding:transcoding:observer:

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

新增转推直播任务，并设置合流的图片、视频视图布局和音频属性。
同一个任务中转推多路直播流时，SDK 会先将多路流合成一路流，然后再进行转推。

传入参数

注意

• 调用该方法后，启动结果和推流过程中的错误均会通过回调 onStreamMixingEvent:taskId:error:mixType: 通知用户。
• 调用 stopLiveTranscoding: 停止转推直播

stopLiveTranscoding:

- (int)stopLiveTranscoding:(NSString *_Nonnull)task_id;

停止转推直播。

传入参数

返回值 方法调用结果。

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

updateLiveTranscoding:transcoding:

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

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

传入参数

返回值 方法调用结果。

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

startPushPublicStream:withLayout:

- (int)startPushPublicStream:(NSString * _Nonnull)publicStreamId withLayout:(ByteRTCPublicStreaming *_Nullable)publicStream;

发布一路公共流
公共流是指不属于任何房间，也不属于任何用户的媒体流。使用同一 appID 的用户，可以调用 startPlayPublicStream: 获取和播放指定的公共流。

传入参数

返回值

• 0: 成功。同时将收到 rtcEngine:onPushPublicStreamResult:publiscStreamId:errorCode: 回调。
• !0: 失败。当参数不合法或参数为空，调用失败。

注意

• 同一用户使用同一公共流 ID 多次调用本接口无效。如果你希望更新公共流参数，调用 updatePublicStreamParam:withLayout: 接口。
• 不同用户使用同一公共流 ID 多次调用本接口时，RTC 将使用最后一次调用时传入的参数更新公共流。
• 使用不同的 ID 多次调用本接口可以发布多路公共流。
• 调用 stopPushPublicStream: 停止发布公共流。

stopPushPublicStream:

- (int)stopPushPublicStream:(NSString * _Nonnull)publicStreamId;

停止发布当前用户发布的公共流
关于发布公共流，查看 startPushPublicStream:withLayout:。

传入参数

返回值

• 0: 成功
• !0: 失败

updatePublicStreamParam:withLayout:

- (int)updatePublicStreamParam:(NSString * _Nonnull)publicStreamId withLayout:(ByteRTCPublicStreaming *_Nullable)publicStream;

更新公共流参数
关于发布公共流，查看 startPushPublicStream:withLayout:。

传入参数

返回值

• 0: 成功
• !0: 失败

startPlayPublicStream:

- (int)startPlayPublicStream:(NSString * _Nonnull)publicStreamId;

订阅指定公共流
无论用户是否在房间内，都可以调用本接口获取和播放指定的公共流。

传入参数

返回值

• 0: 成功。同时将收到 rtcEngine:onPlayPublicStreamResult:errorCode: 回调。
• !0: 失败。当参数不合法或参数为空，调用失败。

注意

• 在调用本接口之前，建议先绑定渲染视图。
• 调用 setPublicStreamVideoCanvas:withCanvas: 绑定内部渲染视图：
• 调用 setPublicStreamVideoSink:withSink:withPixelFormat: 绑定自定义渲染视图：
• 调用本接口后，可以通过 rtcEngine:onFirstPublicStreamVideoFrameDecoded:withFrameInfo: 和 rtcEngine:onFirstPublicStreamAudioFrameDecoded:rtcEngine:onFirstPublicStreamAduioFrameDecoded: 回调公共流的视频和音频首帧解码情况。
• 调用本接口后，可以通过 rtcEngine:onPublicStreamSEIMessageReceived:andMessage: 回调公共流中包含的 SEI 信息。
• 订阅公共流之后，可以通过调用 stopPlayPublicStream: 接口取消订阅公共流。

stopPlayPublicStream:

- (int)stopPlayPublicStream:(NSString * _Nonnull)publicStreamId;

取消订阅指定公共流
关于订阅公共流，查看 startPlayPublicStream:。

传入参数

返回值

• 0：成功
• !0：失败

setPublicStreamVideoCanvas:withCanvas:

- (int)setPublicStreamVideoCanvas:(NSString *_Nonnull)publicStreamId withCanvas:(ByteRTCVideoCanvas * _Nullable)canvas;

为指定公共流绑定内部渲染视图。

传入参数

返回值

• 0：成功
• !0：失败

setPublicStreamVideoSink:withSink:withPixelFormat:

- (int)setPublicStreamVideoSink:(NSString *_Nonnull)publicStreamId withSink:(id<ByteRTCVideoSinkDelegate> _Nullable)videoSink withPixelFormat:(ByteRTCVideoSinkPixelFormat)requiredFormat;

为指定公共流绑定自定义渲染器。详见自定义视频渲染。

传入参数

返回值

• 0: 成功
• <0: 失败

pushExternalVideoFrame:time:

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

推送外部视频帧。

传入参数

返回值

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

注意 推送外部视频帧前，必须调用 setVideoSourceType:WithStreamIndex: 开启外部视频源采集。

pushExternalVideoFrame:time:rotation:

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

推送外部视频帧。

传入参数

返回值

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

注意 推送外部视频帧前，必须调用 setVideoSourceType:WithStreamIndex: 开启外部视频源采集。

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 推送失败

注意 推送外部视频帧前，必须调用 setVideoSourceType:WithStreamIndex: 开启外部视频源采集。

pushExternalByteVideoFrame:

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

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

传入参数

返回值

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

注意 推送外部视频帧前，必须调用 setVideoSourceType:WithStreamIndex: 开启外部视频源采集。

enableAudioFrameCallback:format:

- (void)enableAudioFrameCallback:(ByteRTCAudioFrameCallbackMethod) method format:(ByteRTCAudioFormat* _Nullable)format;

开启音频回调

传入参数

注意 开启音频回调并调用 setAudioFrameObserver: 后，ByteRTCAudioFrameObserver 会收到对应的音频回调。两者调用顺序没有限制且相互独立。

disableAudioFrameCallback:

- (void)disableAudioFrameCallback:(ByteRTCAudioFrameCallbackMethod) method;

关闭音频回调

传入参数

注意 该方法需要在调用 enableAudioFrameCallback:format: 之后调用。

setAudioFrameObserver:

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

注册音频数据回调观察者。

传入参数

返回值

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

注意 注册音频数据回调观察者并调用 enableAudioFrameCallback:format: 后，ByteRTCAudioFrameObserver 会收到对应的音频回调。

registerAudioProcessor:

- (BOOL)registerAudioProcessor:(_Nullable id<ByteRTCAudioFrameProcessor>)processor;

注册自定义音频处理器。
注册完成后，你可以调用 enableAudioProcessor:audioFormat:，对本地采集或接收到的远端音频进行处理。

传入参数

注意 重复调用此接口时，仅最后一次调用生效。

enableAudioProcessor:audioFormat:

- (void)enableAudioProcessor:(ByteRTCAudioFrameMethod)method audioFormat:(ByteRTCAudioFormat *_Nullable)format;

获取本地采集的音频帧或接收到的远端音频帧，进行自定义处理。

传入参数

注意

• 在调用此接口前，你需要调用 registerAudioProcessor: 注册自定义音频处理器。
• 要关闭音频自定义处理，调用 disableAudioProcessor:。

disableAudioProcessor:

- (void)disableAudioProcessor:(ByteRTCAudioFrameMethod)method;

关闭自定义音频处理。

传入参数

pushExternalAudioFrame:

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

推送自定义采集的音频数据到 RTC SDK。

传入参数

返回值 方法调用结果

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

注意

• 推送外部音频数据前，必须先调用 setAudioSourceType: 开启自定义采集。
• 你必须每隔 10 毫秒推送一次外部采集的音频数据。单次推送的 samples (音频采样点个数）应该为 audioFrame.sampleRate / 100。比如设置采样率为 48000 时， 每次应该推送 480 个采样点。
• 本方法中设置的 sampleRate（音频采样率） 和 channel（音频声道） 必须与 setAudioSourceType: 中设置的一致。
• 音频采样格式为 S16。音频缓冲区内的数据格式必须为 PCM 数据，其容量大小应该为 audioFrame.samples × audioFrame.channel × 2。

pullExternalAudioFrame:

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

拉取音频数据，用于自定义渲染。

传入参数

返回值 方法调用结果

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

注意

• 拉取外部音频数据前，必须先调用 setAudioRenderType: 开启自定义渲染。
• 你应当每隔 10 毫秒拉取一次音频数据。samples (音频采样点个数）应该为 audioFrame.sampleRate / 100。如设置采样率为 48000 时， 每次应该拉取 480 个采样点。
• 本方法中设置的 sampleRate（音频采样率） 和 channel（音频声道） 必须与 setAudioRenderType: 中设置的一致，和远端音频采集设置无关。
• 音频采样格式为 S16。音频缓冲区内的数据格式必须为 PCM 数据，其容量大小应该为 audioFrame.samples × audioFrame.channel × 2。

setBusinessId:

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

设置业务标识参数
可通过 businessId 区分不同的业务场景。businessId 由客户自定义，相当于一个“标签”，可以分担和细化现在 AppId 的逻辑划分的功能，但不需要鉴权。

传入参数

返回值

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

注意

• 需要在调用 joinRoomByToken:userInfo:roomConfig: 之前调用，joinRoomByToken:userInfo:roomConfig:之后调用该方法无效。

feedback:desc:

- (int)feedback:(NSArray<ByteRTCProblemOption *> * _Nullable)types desc:(NSString* _Nullable)desc;

通话结束，将用户反馈的问题上报到 RTC

传入参数

返回值

• 0: 上报成功
• -1: 上报失败，还没加入过房间
• -2: 上报失败，数据解析错误
• -3: 上报失败，字段缺失

注意 如果用户上报时在房间内，那么问题会定位到用户当前所在的一个或多个房间；如果用户上报时不在房间内，那么问题会定位到引擎此前退出的房间。

setPublishFallbackOption:

- (int)setPublishFallbackOption:(ByteRTCPublishFallbackOption)option;

设置发布的音视频流的回退选项。
你可以调用该接口设置网络不佳或设备性能不足时从大流起进行降级处理，以保证通话质量。

传入参数

返回值 方法调用结果：

• 0：成功
• < 0：失败

注意

• 该方法仅在调用 enableSimulcastMode: 开启了发送多路视频流的情况下生效。
• 该方法必须在进房前设置，进房后设置或更改设置无效。
• 设置回退后，本地发布的音视频流发生回退或从回退中恢复时，远端会收到 rtcEngine:OnSimulcastSubscribeFallback: 回调通知。
• 你可以调用客户端 API 或者在服务端下发策略设置回退。当使用服务端下发配置实现时，下发配置优先级高于在客户端使用 API 设定的配置。

setSubscribeFallbackOption:

- (int)setSubscribeFallbackOption:(ByteRTCSubscribeFallbackOption)option;

设置订阅的音视频流的回退选项。
你可调用该接口设置网络不佳或设备性能不足时允许订阅流进行降级或只订阅音频流，以保证通话流畅。

传入参数

返回值 方法调用结果：

• 0：成功
• < 0：失败

注意

• 你必须在进房前设置，进房后设置或更改设置无效。
• 设置回退选项后，订阅的音视频流发生回退或从回退中恢复时，会收到 rtcEngine:OnSimulcastSubscribeFallback: 和 rtcEngine:onRemoteVideoSizeChanged:withFrameInfo: 回调通知。
• 你可以调用 API 或者在服务端下发策略设置回退。当使用服务端下发配置实现时，下发配置优先级高于在客户端使用 API 设定的配置。

setRemoteUserPriority:InRoomId:uid:

- (int)setRemoteUserPriority:(ByteRTCRemoteUserPriority)priority InRoomId:(NSString *_Nonnull)roomId 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: 为互斥关系, 即按照调用顺序，最后一个调用的方法为最终生效的版本

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

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

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

createRTCRoom:

- ( ByteRTCRoom * _Nullable)createRTCRoom:(NSString * _Nonnull)roomId;

pushScreenCaptureFrame:time:rotation:

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

推送外部屏幕采集帧

传入参数

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

setExtensionConfig:

- (void)setExtensionConfig:(NSString *_Nullable)groupId;

设置 Extension 配置项。你必须在使用屏幕内部采集功能前，设置使用的 Extension。

传入参数

注意 必须在调用 createRTCVideo:delegate:parameters: 之后立即调用此方法。在引擎实例的生命周期中，此方法只需要调用一次。

startScreenCapture:bundleId:

- (void)startScreenCapture:(ByteRTCScreenMediaType) type bundleId:(NSString *_Nullable)bundleId;

使用 RTC SDK 内部采集模块开始采集屏幕音频流和（或）视频流。

传入参数

注意

• 当从 iOS 控制中心发起屏幕采集时无需调用本方法。
• 采集后，你还需要调用 publishScreen: 发布采集到的屏幕音视频。
• 开启屏幕音频/视频采集成功后，本地用户会收到 rtcEngine:onVideoDeviceStateChanged:device_type:device_state:device_error: 和 rtcEngine:onAudioDeviceStateChanged:device_type:device_state:device_error: 回调。

updateScreenCapture:

- (void)updateScreenCapture:(ByteRTCScreenMediaType) type;

更新内部屏幕采集时采集的媒体类型。

传入参数

注意

• 在 startScreenCapture:bundleId: 后调用该方法。
• 本地用户会收到 rtcEngine:onVideoDeviceStateChanged:device_type:device_state:device_error: 或 rtcEngine:onAudioDeviceStateChanged:device_type:device_state:device_error: 回调。

stopScreenCapture

- (void)stopScreenCapture;

在屏幕共享时，停止使用 RTC SDK 内部采集方式采集屏幕音视频。

注意

• 本方法只会停止本地屏幕采集，并不会影响屏幕流的发布状态，再次调用 startScreenCapture:bundleId: 开始屏幕音视频内部采集。
• 本地用户会收到 rtcEngine:onVideoDeviceStateChanged:device_type:device_state:device_error: 和 rtcEngine:onAudioDeviceStateChanged:device_type:device_state:device_error: 的回调。

sendScreenCaptureExtensionMessage:

- (void)sendScreenCaptureExtensionMessage:(NSData *_Nonnull) messsage;

向屏幕共享 Extension 发送自定义消息

传入参数

注意 在 startScreenCapture:bundleId: 后调用该方法。

setRuntimeParameters:

- (void)setRuntimeParameters:(NSDictionary * _Nullable)parameters;

设置运行时的参数

传入参数

startASR:handler:

- (void)startASR:(ByteRTCASRConfig *_Nonnull)asrConfig handler:(id<ByteRTCASREngineEventHandler> _Nonnull)handler ;

开启自动语音识别服务。该方法将识别后的用户语音转化成文字，并通过 onMessage: 事件回调给用户。

传入参数

stopASR

- (void)stopASR;

关闭语音识别服务

startFileRecording:withRecordingConfig:type:

- (int)startFileRecording:(ByteRTCStreamIndex)streamIndex withRecordingConfig:(ByteRTCRecordingConfig* _Nonnull)recordingConfig type:(ByteRTCRecordingType)recordingType;

该方法将通话过程中的音视频数据录制到本地的文件中。

传入参数

返回值

• 0: 正常
• -1: 参数设置异常
• -2: 当前版本 SDK 不支持该特性，请联系技术支持人员

注意

• 调用该方法后，你会收到 rtcEngine:onRecordingStateUpdate:state:error_code:recording_info: 回调。
• 如果录制正常，系统每秒钟会通过 rtcEngine:onRecordingProgressUpdate:process:recording_info: 回调通知录制进度。

stopFileRecording:

- (void)stopFileRecording:(ByteRTCStreamIndex)streamIndex;

停止本地录制

传入参数

注意

• 调用 startFileRecording:withRecordingConfig:type: 开启本地录制后，你必须调用该方法停止录制。
• 调用该方法后，你会收到 rtcEngine:onRecordingStateUpdate:state:error_code:recording_info: 回调提示录制结果。

getAudioMixingManager

- (ByteRTCAudioMixingManager *_Nullable)getAudioMixingManager;

混音管理接口创建

返回值 混音管理实例，详见ByteRTCAudioMixingManager

login:uid:

- (void)login:(NSString * _Nonnull)token uid:(NSString * _Nonnull)uid;

必须先登录，才能发送房间外点对点消息和向应用服务器发送消息
在调用本接口登录后，如果想要登出，需要调用 logout

传入参数

注意 本地用户调用此方法登录后，会收到 rtcEngine:onLoginResult:errorCode:elapsed: 回调通知登录结果，远端用户不会收到通知。

logout

- (void)logout;

调用本接口登出后，无法调用房间外消息以及端到服务器消息相关的方法或收到相关回调。

注意

• 调用本接口登出前，必须先调用 login:uid: 登录
• 本地用户调用此方法登出后，会收到 rtcEngineOnLogout: 回调通知结果，远端用户不会收到通知。

updateLoginToken:

- (void)updateLoginToken:(NSString * _Nonnull)token;

更新用户用于登录的 Token
Token 有一定的有效期，当 Token 过期时，需调用此方法更新登录的 Token 信息。
调用 login:uid: 方法登录时，如果使用了过期的 Token 将导致登录失败，并会收到 rtcEngine:onLoginResult:errorCode:elapsed: 回调通知，错误码为 ByteRTCLoginErrorCodeInvalidToken。此时需要重新获取 Token，并调用此方法更新 Token。

传入参数

注意

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

setServerParams:url:

- (void)setServerParams:(NSString * _Nonnull)signature url:(NSString * _Nonnull)url;

设置应用服务器参数
客户端调用 sendServerMessage: 或 sendServerBinaryMessage: 发送消息给应用服务器之前，必须需要设置有效签名和应用服务器地址。

传入参数

注意

• 用户必须调用 login:uid: 登录后，才能调用本接口。
• 调用本接口后，SDK 会使用 rtcEngine:onServerParamsSetResult: 返回相应结果。

getPeerOnlineStatus:

- (void)getPeerOnlineStatus:(NSString * _Nonnull)peerUserId;

查询对端用户或本端用户的登录状态

传入参数

注意

• 必须调用 login:uid: 登录后，才能调用本接口。
• 调用本接口后，SDK 会使用 rtcEngine:onGetPeerOnlineStatus:status: 回调通知查询结果。
• 在发送房间外消息之前，用户可以通过本接口了解对端用户是否登录，从而决定是否发送消息。也可以通过本接口查询自己查看自己的登录状态。

sendUserMessageOutsideRoom:message:config:

- (int64_t)sendUserMessageOutsideRoom:(NSString * _Nonnull)userId message:(NSString * _Nonnull)messageStr config:(ByteRTCMessageConfig)config;

给房间外指定的用户发送文本消息（P2P）

传入参数

返回值

• >0：发送成功，返回这次发送消息的编号，从 1 开始递增
• -1：发送失败，ByteRTCVideo 实例未创建
• -2：发送失败，userId 为空

注意

• 在发送房间外文本消息前，必须先调用 login:uid: 完成登录。
• 用户调用本接口发送文本信息后，会收到一次 rtcEngine:onUserMessageSendResultOutsideRoom:error: 回调，得知消息是否成功发送；
• 若文本消息发送成功，则 userId 所指定的用户会通过 rtcEngine:onUserMessageReceivedOutsideRoom:message: 回调收到该消息。

sendUserBinaryMessageOutsideRoom:message:config:

- (int64_t)sendUserBinaryMessageOutsideRoom:(NSString * _Nonnull)userId message:(NSData * _Nonnull)messageStr config:(ByteRTCMessageConfig)config;

给房间外指定的用户发送二进制消息（P2P）

传入参数

返回值

• >0：发送成功，返回这次发送消息的编号，从 1 开始递增
• -1：发送失败，ByteRTCVideo 实例未创建
• -2：发送失败，userId 为空

注意

• 在发送房间外二进制消息前，必须先调用 login:uid: 完成登录。
• 用户调用本接口发送二进制消息后，会收到一次 rtcEngine:onUserMessageSendResultOutsideRoom:error: 回调，通知消息是否发送成功；
• 若二进制消息发送成功，则 userId 所指定的用户会通过 rtcEngine:onUserBinaryMessageReceivedOutsideRoom:message: 回调收到该条消息。

sendServerMessage:

- (int64_t)sendServerMessage:(NSString * _Nonnull)messageStr;

客户端给应用服务器发送文本消息（P2Server）

传入参数

返回值

• >0：发送成功，返回这次发送消息的编号，从 1 开始递增
• -1：发送失败，ByteRTCVideo 实例未创建

注意

• 在向应用服务器发送文本消息前，必须先调用 login:uid: 完成登录，随后调用 setServerParams:url: 设置应用服务器。
• 调用本接口后，会收到一次 rtcEngine:onServerMessageSendResult:error:message: 回调，通知消息发送方是否发送成功。
• 若文本消息发送成功，则之前调用 setServerParams:url: 设置的应用服务器会收到该条消息。

sendServerBinaryMessage:

- (int64_t)sendServerBinaryMessage:(NSData * _Nonnull)messageStr;

客户端给应用服务器发送二进制消息（P2Server）

传入参数

返回值

• >0：发送成功，返回这次发送消息的编号，从 1 开始递增
• -1：发送失败，ByteRTCVideo 实例未创建

注意

• 在向应用服务器发送二进制消息前，先调用 login:uid: 完成登录，随后调用 setServerParams:url: 设置应用服务器。
• 调用本接口后，会收到一次 rtcEngine:onServerMessageSendResult:error:message: 回调，通知消息发送方发送成功或失败；
• 若二进制消息发送成功，则之前调用 setServerParams:url: 设置的应用服务器会收到该条消息。

startNetworkDetection:uplinkBandwidth:downlink:downlinkBandwidth:

- (ByteRTCNetworkDetectionStartReturn)startNetworkDetection:(bool)is_test_uplink uplinkBandwidth:(int)expected_uplink_bitrate downlink:(bool)is_test_downlink downlinkBandwidth:(int)expected_downlink_bitrate;

开始通话前网络探测

传入参数

返回值 开启通话前网络探测结果，详见 ByteRTCNetworkDetectionStartReturn

注意

• 成功调用本接口后，会在 3s 内收到一次 rtcEngine:onNetworkDetectionResult:quality:rtt:lostRate:bitrate:jitter: 回调，此后每 2s 会收到一次该回调，通知探测结果；
• 若探测停止，则会收到一次 rtcEngine:onNetworkDetectionStopped: 通知探测停止。

stopNetworkDetection

- (void)stopNetworkDetection;

停止通话前网络探测

注意 调用本接口后，会收到一次 rtcEngine:onNetworkDetectionStopped: 通知探测停止。

setScreenAudioSourceType:

- (void) setScreenAudioSourceType:(ByteRTCAudioSourceType)sourceType;

在屏幕共享时，设置屏幕音频的采集方式（内部采集/自定义采集）

传入参数

注意

• 默认采集方式是 RTC SDK 内部采集。
• 你应该在 publishScreen: 前，调用此方法。否则，你将收到 rtcEngine:onWarning: 的报错：ByteRTCWarningSetScreenAudioSourceTypeFailed。
• 如果设定为内部采集，你必须再调用 startScreenCapture:bundleId: 开始采集。
• 如果设定为自定义采集，你必须再调用 pushScreenAudioFrame: 将自定义采集到的屏幕音频帧推送到 RTC SDK。
• 无论是内部采集还是自定义采集，你都必须调用 publishScreen: 将采集到的屏幕音频推送到远端。

setScreenAudioStreamIndex:

- (void) setScreenAudioStreamIndex:(ByteRTCStreamIndex) index;

在屏幕共享时，设置屏幕音频流和麦克风采集到的音频流的混流方式

传入参数

注意 你应该在 publishScreen: 之前，调用此方法。否则，你将收到 rtcEngine:onWarning: 的报错：ByteRTCWarningSetScreenAudioStreamIndexFailed

pushScreenAudioFrame:

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

使用自定义采集方式，采集屏幕共享时的屏幕音频时，将音频帧推送至 RTC SDK 处进行编码等处理。

传入参数

返回值 方法调用结果

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

注意

• 调用此接口推送屏幕共享时的自定义采集的音频数据前，必须调用 setScreenAudioSourceType: 开启屏幕音频自定义采集。
• 你应每隔 10 毫秒，调用一次此方法推送一次自定义采集的音频帧。一次推送的音频帧中应包含 frame.sample_rate / 100 个音频采样点。比如，假如采样率为 48000Hz，则每次应该推送 480 个采样点。
• 音频采样格式为 S16。音频缓冲区内的数据格式必须为 PCM 数据，其容量大小应该为 samples × frame.channel × 2。
• 调用此接口将自定义采集的音频帧推送到 RTC SDK 后，你必须调用 publishScreen: 将采集到的屏幕音频推送到远端。在调用 publishScreen: 前，推送到 RTC SDK 的音频帧信息会丢失。

setVideoSourceType:WithStreamIndex:

- (void)setVideoSourceType:(ByteRTCVideoSourceType)type WithStreamIndex:(ByteRTCStreamIndex)streamIndex;

设置向 SDK 输入的视频源 默认使用内部采集。内部采集指：使用 RTC SDK 内置的视频采集机制进行视频采集。

传入参数

注意

• 该方法进房前后均可调用。
• 当你已调用 startVideoCapture 开启内部采集后，再调用此方法切换至自定义采集时，SDK 会自动关闭内部采集。
• 当你调用此方法开启自定义采集后，想要切换至内部采集，你必须先调用此方法关闭自定义采集，然后调用 startVideoCapture 手动开启内部采集。
• 当你需要向 SDK 推送自定义编码后的视频帧，你需调用该方法将视频源切换至自定义编码视频源。

setExternalVideoEncoderEventHandler:

- (void)setExternalVideoEncoderEventHandler:(id<ByteRTCExternalVideoEncoderEventHandler> _Nullable)handler;

注册自定义编码帧推送事件回调

传入参数

注意

• 该方法需在进房前调用。
• 引擎销毁前需取消注册，调用该方法将参数设置为 nullptr 即可。

pushExternalEncodedVideoFrame:withVideoIndex:withEncodedVideoFrame:

- (BOOL)pushExternalEncodedVideoFrame:(ByteRTCStreamIndex)streamIndex withVideoIndex:(NSInteger)videoIndex withEncodedVideoFrame:(ByteRTCEncodedVideoFrame* _Nonnull)videoFrame;

推送自定义编码后的视频流

传入参数

注意

• 目前仅支持推送 H264 和 ByteVC1 格式的视频帧，且视频流协议格式须为 Annex B 格式。
• 该函数运行在用户调用线程内
• 推送自定义编码视频帧前，必须调用 setVideoSourceType:WithStreamIndex: 将视频输入源切换至自定义编码视频源。

setVideoDecoderConfig:withVideoDecoderConfig:

- (void)setVideoDecoderConfig:(ByteRTCRemoteStreamKey * _Nonnull)key withVideoDecoderConfig:(ByteRTCVideoDecoderConfig)config;

在订阅远端视频流之前，设置远端视频数据解码方式

传入参数

注意

• 该方法近适用于手动订阅模式，并且在订阅远端流之前使用。
• 当你想要对远端流进行自定义解码时，你需要先调用 registerRemoteEncodedVideoFrameObserver: 注册远端视频流监测器，然后再调用该接口将解码方式设置为自定义解码。监测到的视频数据会通过 onRemoteEncodedVideoFrame:withEncodedVideoFrame: 回调出来。

requestRemoteVideoKeyFrame:

- (void)requestRemoteVideoKeyFrame:(ByteRTCRemoteStreamKey * _Nonnull)key;

在订阅远端视频流之后，向远端请求关键帧

传入参数

注意

• 该方法仅适用于手动订阅模式，并且在成功订阅远端流之后使用。
• 该方法适用于调用 setVideoDecoderConfig:withVideoDecoderConfig: 开启自定义解码功能后，并且自定义解码失败的情况下使用

registerRemoteEncodedVideoFrameObserver:

- (void)registerRemoteEncodedVideoFrameObserver:(id<ByteRTCRemoteEncodedVideoFrameObserver> _Nullable)observer;

注册远端编码后视频数据回調。
完成注册后，当 SDK 监测到远端编码后视频帧时，会触发 onRemoteEncodedVideoFrame:withEncodedVideoFrame: 回调

传入参数

注意

• 该方法需在进房前调用。
• 引擎销毁前需取消注册，调用该方法将参数设置为 nullptr 即可。

sendStreamSyncInfo:config:

- (int)sendStreamSyncInfo:(NSData* _Nonnull)data config:(ByteRTCStreamSycnInfoConfig * _Nonnull)config;

发送音频流同步信息。将消息通过音频流发送到远端，并实现与音频流同步，该接口调用成功后，远端用户会收到 rtcEngine:onStreamSyncInfoReceived:streamType:data: 回调。

传入参数

返回值

• >=0: 消息发送成功。返回成功发送的次数。
• -1: 消息发送失败。消息长度大于 16 字节。
• -2: 消息发送失败。传入的消息内容为空。
• -3: 消息发送失败。通过屏幕流进行消息同步时，此屏幕流还未发布。
• -4: 消息发送失败。通过用麦克风或自定义设备采集到的音频流进行消息同步时，此音频流还未发布，详见错误码 ByteRTCErrorCode。

注意 在采用 ByteRTCRoomProfileLiveBroadcasting 作为房间模式时，此消息一定会送达。在其他房间模式下，如果本地用户未说话，此消息不一定会送达。

muteAudioPlayback:

- (void)muteAudioPlayback:(ByteRTCMuteState)muteState;

控制本地音频流播放状态：播放/不播放

传入参数

注意 本方法仅控制本地收到音频流的播放状态，并不影响本地音频播放设备。

startEchoTest:playDelay:

- (int)startEchoTest:(ByteRTCEchoTestConfig *_Nullable)echoConfig playDelay:(NSInteger)delayTime;

开启音视频回路测试。
在进房前，用户可调用该接口对音视频通话全链路进行检测，包括对音视频设备以及用户上下行网络的检测，从而帮助用户判断是否可以正常发布和接收音视频流。
开始检测后，SDK 会录制你声音或视频。如果你在设置的延时范围内收到了回放，则视为音视频回路测试正常。

传入参数

返回值 方法调用结果：

• 0：成功
• -1：失败，当前用户已经在检测中
• -2：失败，用户已进房
• -3：失败，音视频均未采集
• -4：失败，参数异常
• -5：失败，已经存在相同 roomId 的房间

注意

• 调用该方法开始音视频回路检测后，你可以调用 stopEchoTest 立即结束测试，也可等待测试 60s 后自动结束，以更换设备进行下一次测试，或进房。
• 在该方法之前调用的所有跟设备控制、流控制相关的方法均在开始检测时失效，在结束检测后恢复生效。
• 在调用 startEchoTest:playDelay: 和 stopEchoTest 之间调用的所有跟设备采集、流控制、进房相关的方法均不生效，并会收到 rtcEngine:onWarning: 回调，提示警告码为 ByteRTCWarningCodeInEchoTestMode。
• 音视频回路检测的结果会通过 rtcEngine:onEchoTestResult: 回调通知。

stopEchoTest

- (int)stopEchoTest;

停止音视频回路测试。
调用 startEchoTest:playDelay: 开启音视频回路检测后，你必须调用该方法停止检测。

返回值 方法调用结果：

• 0：成功
• -1：失败，未开启回路检测

注意 音视频回路检测结束后，所有对系统设备及音视频流的控制均会恢复到开始检测前的状态。

SetVideoWatermark:WithImagePath:WithRtcWatermarkConfig:

- (void)SetVideoWatermark:(ByteRTCStreamIndex)streamIndex WithImagePath:(NSString * _Nullable)imagePath WithRtcWatermarkConfig:(ByteRTCVideoWatermarkConfig* _Nonnull)rtcWatermarkConfig;

在指定视频流上添加水印。

传入参数

注意

• 调用 ClearVideoWatermarkClearVideoWatermark: 移除指定视频流的水印。
• 同一路流只能设置一个水印，新设置的水印会代替上一次的设置。你可以多次调用本方法来设置不同流的水印。
• 进入房间前后均可调用此方法。
• 若开启本地预览镜像，或开启本地预览和编码传输镜像，则远端水印均不镜像；在开启本地预览水印时，本端水印会镜像。
• 开启大小流后，水印对大小流均生效，且针对小流进行等比例缩小。

ClearVideoWatermark:

- (void)ClearVideoWatermark:(ByteRTCStreamIndex)streamIndex;

移除指定视频流的水印。

传入参数

startCloudProxy:

- (void)startCloudProxy:(NSArray <ByteRTCCloudProxyInfo *> * _Nullable)cloudProxiesInfo;

开启云代理

传入参数

注意

• 在加入房间前调用此接口
• 在开启云代理后，进行通话前网络探测
• 开启云代理后，并成功链接云代理服务器后，会收到 rtcEngine:onCloudProxyConnected:。
• 要关闭云代理，调用 stopCloudProxy。

stopCloudProxy

- (void)stopCloudProxy;

关闭云代理

注意 要开启云代理，调用 startCloudProxy:

ByteRTCAudioMixingManager

@interface ByteRTCAudioMixingManager :NSObject

成员函数

函数说明

startAudioMixing:filePath:config:

-(void)startAudioMixing:(int)mixId filePath:(NSString * _Nullable)filePath config:(ByteRTCAudioMixingConfig * _Nullable)config;

开始播放音频文件。
可以通过传入不同的 mixId 和 filepath 多次调用本方法，以实现同时播放多个混音文件，实现混音叠加。

传入参数

注意

• 如果已经通过 preloadAudioMixing:filePath: 将文件加载至内存，确保此处的 ID 与预加载时设置的 ID 相同。
• 调用本方法播放音频文件后，关于当前的混音状态，会收到回调 onAudioMixingStateChanged。
• 开始播放音频文件后，可以调用 stopAudioMixing: 方法停止播放音频文件。
• 本方法的混音数据来源于外部文件，而 enableAudioMixingFrame:type: 的混音数据来源于外部缓存且音频格式为 PCM，这两种混音方式可以共存。

stopAudioMixing:

-(void)stopAudioMixing:(int)mixId;

停止播放音频文件及混音

传入参数

注意

• 调用 startAudioMixing:filePath:config: 方法开始播放音频文件及混音后，可以调用本方法停止播放音频文件及混音。
• 调用本方法停止播放音频文件后，SDK 会向本地回调通知已停止混音，见 onAudioMixingStateChanged。
• 调用本方法停止播放音频文件后，该音频文件会被自动卸载。

pauseAudioMixing:

-(void)pauseAudioMixing:(int)mixId;

暂停播放音频文件

传入参数

注意

• 调用 startAudioMixing:filePath:config: 方法开始播放音频文件及混音后，可以通过调用该方法暂停播放音频文件。
• 调用本方法暂停播放音频文件后，可调用 resumeAudioMixing: 方法恢复播放及混音。
• 调用本方法暂停播放音频文件后，SDK 会向本地回调通知已暂停混音，见 onAudioMixingStateChanged。

resumeAudioMixing:

-(void)resumeAudioMixing:(int)mixId;

恢复播放音频文件

传入参数

注意

• 调用 pauseAudioMixing: 方法暂停播放音频文件后，可以通过调用本方法恢复播放及混音。
• 调用本方法恢复播放音频文件后，SDK 会向本地回调通知音频文件正在播放中，见 onAudioMixingStateChanged。

preloadAudioMixing:filePath:

-(void)preloadAudioMixing:(int)mixId filePath:(NSString * _Nullable)filePath;

预加载指定音频文件到内存中，以避免频繁播放时的重复加载。

传入参数

注意

• 本方法只是预加载指定音频文件，只有调用 startAudioMixing:filePath:config: 方法才开始播放指定音频文件。
• 调用本方法预加载音频文件后，关于当前的混音状态，会收到回调 onAudioMixingStateChanged。
• 调用本方法预加载的指定音频文件可以通过 unloadAudioMixing: 卸载。

unloadAudioMixing:

-(void)unloadAudioMixing:(int)mixId;

卸载指定音频文件

传入参数

注意 不论音频文件是否播放，调用本方法卸载该文件后，SDK 会回调通知混音已停止，见 onAudioMixingStateChanged。

setAudioMixingVolume:volume:type:

-(void)setAudioMixingVolume:(int)mixId volume:(int)volume type:(ByteRTCAudioMixingType)type;

调节混音的音量大小，包括音频文件混音和 PCM 混音。

传入参数

getAudioMixingDuration:

-(int)getAudioMixingDuration:(int)mixId;

获取音频文件时长

传入参数

返回值

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

注意 调用本方法获取音频文件时长前，需要先调用 preloadAudioMixing:filePath: 或 startAudioMixing:filePath:config:。

getAudioMixingCurrentPosition:

-(int)getAudioMixingCurrentPosition:(int)mixId;

获取音频文件播放进度

传入参数

返回值

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

注意 调用本方法获取音频文件播放进度前，需要先调用 startAudioMixing:filePath:config: 开始播放音频文件。

setAudioMixingPosition:position:

-(void)setAudioMixingPosition:(int)mixId position:(int)position;

设置音频文件的起始播放位置

传入参数

注意 在播放在线文件时，调用此接口可能造成播放延迟的现象。

setAudioMixingDualMonoMode:mode:

-(void) setAudioMixingDualMonoMode:(int)mixId mode:(ByteRTCAudioMixingDualMonoMode)mode;

设置当前音频文件的声道模式

传入参数

注意

• 调用本方法设置音频文件的声道模式前，需要先调用 startAudioMixing:filePath:config: 开始播放音频文件。
• 此方法对 enableAudioMixingFrame:type: 播放的音乐无效。

setAudioMixingPitch:pitch:

-(void)setAudioMixingPitch:(int)mixId pitch:(int)pitch;

开启本地播放音乐文件变调功能，多用于 K 歌场景。
使用该方法，你可以对本地播放音乐文件的音调进行升调或降调等调整。

传入参数

注意 本方法需要在调用 startAudioMixing:filePath:config: 开始播放音频文件后、调用 stopAudioMixing: 停止播放音频文件前使用，否则会触发 onAudioMixingStateChanged 回调报错

setAudioMixingPlaybackSpeed:speed:

-(int)setAudioMixingPlaybackSpeed:(int)mixId speed:(int)speed;

设置混音时音频文件的播放速度

传入参数

注意

• 暂不支持对 PCM 音频数据进行变速调整。
• 你需要在调用 startAudioMixing:filePath:config: 开始混音，并且收到onAudioMixingStateChanged 回调提示 ByteRTCAudioMixingState 状态为 ByteRTCAudioMixingStatePlaying，ByteRTCAudioMixingError 错误码为 AUDIO_MIXING_ERROR_OK 之后调用该方法。
• 在 stopAudioMixing: 停止混音或 unloadAudioMixing: 卸载音频文件后调用该 API，会收到状态为 ByteRTCAudioMixingStateFailed 错误码为 ByteRTCAudioMixingErrorIdNotFound 的 onAudioMixingStateChanged 回调。

setAudioMixingLoudness:loudness:

-(void)setAudioMixingLoudness:(int)mixId loudness:(float)loudness;

如果你需要使用 enableVocalInstrumentBalance: 对混音使音频文件/PCM 音频数据进行音量调整，你必须通过此接口传入其原始响度。

传入参数

注意 建议在 startAudioMixing:filePath:config: 开始播放音频文件之前调用该接口，以免播放过程中的音量突变导致听感体验下降。

setAudioMixingProgressInterval:interval:

-(void) setAudioMixingProgressInterval:(int)mixId interval:(int64_t) interval;

设置混音时音频文件播放进度回调的间隔

传入参数

注意 本方法需要在调用 startAudioMixing:filePath:config: 开始播放音频文件后、调用 stopAudioMixing: 停止播放音频文件前使用，否则会触发 onAudioMixingStateChanged 回调报错。 若想在音乐文件开始播放前设置播放进度回调间隔，你需调用 startAudioMixing:filePath:config: 在 ByteRTCAudioMixingConfig 中设置时间间隔，开始播放后可以通过此接口更新回调间隔。

enableAudioMixingFrame:type:

-(void)enableAudioMixingFrame:(int)mixId type:(ByteRTCAudioMixingType)type;

启动 PCM 音频数据混音。
要实现多个 PCM 音频数据混音，多次调用本方法，并传入不同的 id。

传入参数

注意

• 必须先调用本方法启动 PCM 音频数据混音，随后调用 pushAudioMixingFrame:audioFrame: 方法，才会开始混音。
• 如要结束 PCM 音频数据混音，使用 disableAudioMixingFrame:。

disableAudioMixingFrame:

-(void)disableAudioMixingFrame:(int)mixId;

关闭 PCM 混音

传入参数

pushAudioMixingFrame:audioFrame:

-(int)pushAudioMixingFrame:(int)mixId audioFrame:(ByteRTCAudioFrame* _Nullable)audioFrame;

推送 PCM 音频帧数据用于混音

传入参数

返回值

• 0: 成功
• < 0: 失败

注意

• 调用该方法前，须通过 enableAudioMixingFrame:type: 启动外部音频流混音。
• 使用参考建议：首次推送数据，请在应用侧先缓存一定数据（如 200 毫秒），然后一次性推送过去；此后的推送操作定时 10 毫秒一次，并且每次的音频数据量为 10 毫秒数据量。要暂停播放，暂停推送即可。

getAudioTrackCount:

-(int)getAudioTrackCount:(int)mixId;

获取当前音频文件的音轨索引

传入参数

返回值 方法调用结果

• ≥ 0：成功，返回当前音频文件的音轨索引
• < 0：方法调用失败

注意

• 调用本方法获取音频文件的音轨前，需要先调用 startAudioMixing:filePath:config: 开始播放音频文件。
• 此方法对 enableAudioMixingFrame:type: 播放的音频无效。

selectAudioTrack:audioTrackIndex:

-(void)selectAudioTrack:(int)mixId audioTrackIndex:(int)audioTrackIndex;

指定当前音频文件的播放音轨

传入参数

注意

• 调用本方法设置音频文件的音轨前，需要先调用 startAudioMixing:filePath:config: 开始播放音频文件。
• 此方法对 enableAudioMixingFrame:type: 播放的音乐无效。

ByteRTCRangeAudio

@interface ByteRTCRangeAudio :NSObject

范围语音接口实例

成员函数

函数说明

enableRangeAudio:

- (void)enableRangeAudio:(BOOL)enable;

开启/关闭范围语音功能。
范围语音是指，在同一 RTC 房间中设定的音频接收距离范围内，本地用户收听到的远端用户音频音量会随着远端用户的靠近/远离而放大/衰减；若远端用户在房间内的位置超出设定范围，则本地用户无法接收其音频。音频接收范围设置参看 updateReceiveRange:。

传入参数

注意 该方法进房前后都可调用，为保证进房后范围语音效果的平滑切换，你需在该方法前先调用 updatePosition: 设置自身位置坐标，然后开启该方法收听范围语音效果。

updateReceiveRange:

- (int)updateReceiveRange:(ReceiveRange* _Nonnull) range;

更新本地用户的音频收听范围。

传入参数

返回值 方法调用结果：

• 0：成功；
• !0: 失败。

注意 若此前你已调用 registerRangeAudioObserver: 注册了范围语音衰减系数监测器，房间内有任何用户调用该接口更新音频收听范围后，你都会收到 onRangeAudioInfo: 回调。

updatePosition:

- (int)updatePosition:(Position* _Nonnull) pos;

更新本地用户在房间内空间直角坐标系中的位置坐标。

传入参数

返回值 方法调用结果：

• 0：成功；
• !0：失败。

注意

• 调用该接口更新坐标后，你需调用 enableRangeAudio: 开启范围语音功能以收听范围语音效果。
• 若此前你已调用 registerRangeAudioObserver: 注册了范围语音衰减系数监测器，房间内有任何用户调用该接口更新自身位置坐标后，你都会收到 onRangeAudioInfo: 回调。

registerRangeAudioObserver:

- (void)registerRangeAudioObserver:(_Nullable id<ByteRTCRangeAudioObserver>) observer;

设置范围语音衰减系数监测器。

传入参数

注意 该方法仅适用于手动订阅模式，自动订阅无需设置。

setAttenuationModel:coefficient:

- (int)setAttenuationModel:(AttenuationType) type coefficient:(float)coefficient;

设置范围语音的音量衰减模式。
衰减模式更改后，onRangeAudioInfo: 回调将根据最后设置的衰减模式进行计算并返回音量衰减数值

传入参数

返回值 调用是否成功

• 0:调用成功
• -1:调用失败。失败原因为，在调用 enableRangeAudio: 开启范围语音前或进房前调用本接口

注意 音量衰减范围通过 updateReceiveRange: 进行设置。

ByteRTCSpatialAudio

@interface ByteRTCSpatialAudio :NSObject

空间音频接口实例

成员函数

函数说明

enableSpatialAudio:

- (void)enableSpatialAudio:(BOOL)enable;

开启/关闭空间音频功能。

传入参数

注意 该方法仅开启空间音频功能，你须调用 updatePosition: 设置自身位置坐标后方可收听空间音频效果。空间音频相关 API 和调用时序详见空间音频。

updatePosition:

-(int)updatePosition:(Position* _Nonnull) pos;

更新本地用户在房间内空间直角坐标系中的位置坐标。

传入参数

返回值

• 0: 成功；
• !0: 失败。

注意 调用该接口更新坐标前，你需调用 enableSpatialAudio: 开启空间音频功能。 空间音频相关 API 和调用时序详见空间音频。

updateSelfOrientation:

-(int)updateSelfOrientation:(HumanOrientation* _Nonnull) orientation;

更新本地用户在空间音频坐标系下的朝向。

传入参数

返回值 方法调用结果：

• 0：成功
• !0：失败

注意

• 空间音频相关 API 和调用时序详见空间音频。
• 调用 disableRemoteOrientation 可忽略远端用户朝向。

disableRemoteOrientation

-(void)disableRemoteOrientation;

参与通话的各端调用本接口后，将忽略远端用户的朝向，认为所有远端用户都面向本地用户。
如果此后调用 updateSelfOrientation: 更新本地用户朝向，远端用户无法感知这些变化，但本地用户接收音频时可以感知自身朝向改变带来的音频效果变化。

注意

• 进房前后都可以调用该接口。
• 调用本接口关闭朝向功能后，在当前的空间音频实例的生命周期内无法再次开启。