<INERtcEngine>协议 参考

NERtcEngine 的常用接口。 更多...

#import <INERtcEngine.h>

类 <INERtcEngine> 继承关系图:

构造函数
(NERtcConnectionStateType)	- connectionState
	获取当前房间连接状态。 更多...
(int)	- setupEngineWithContext:
	创建 NERtc 实例。 通过本接口可以实现创建 NERtc 实例并初始化 NERTC SDK 服务。 更多...
(int)	- setEngineEventDelegate:
	设置事件通知回调。 通过本接口可以实现根据自身业务场景，监听相应的主回调。 更多...
(int)	- joinChannelWithToken:channelName:myUid:completion:
	加入音视频房间。 通过本接口可以实现加入音视频房间，加入房间后可以与房间内的其他用户进行音视频通话。 更多...
(int)	- joinChannelWithToken:channelName:myUid:channelOptions:completion:
	加入音视频房间。 通过本接口可以实现加入音视频房间，加入房间后可以与房间内的其他用户进行音视频通话。 更多...
(int)	- leaveChannel
	离开音视频房间。 通过本接口可以实现挂断或退出通话，并释放本房间内的相关资源。 更多...
(int)	- switchChannelWithToken:channelName:completion:
	快速切换音视频房间。 通过此接口可以实现当房间场景为直播场景时，房间中角色为观众的成员从当前房间快速切换至另一个房间。 更多...
(int)	- switchChannelWithToken:channelName:channelOptions:completion:
	快速切换音视频房间。 房间场景为直播场景时，房间中角色为观众的成员可以调用该方法从当前房间快速切换至另一个房间。 成功调用该方切换房间后，本端会收到离开房间的回调 onNERtcEngineDidLeaveChannelWithResult；远端用户会收到 onNERtcEngineUserDidLeaveWithUserID 和 onNERtcEngineUserDidJoinWithUserID 的回调。 更多...
(int)	- enableLocalAudio:
	开启/关闭本地音频采集和发送。 通过本接口可以实现开启或关闭本地语音功能，进行本地音频采集及处理。 更多...
(int)	- enableLocalVideo:
	开启或关闭本地视频的采集与发送。 通过本接口可以实现开启或关闭本地视频，不影响接收远端视频。 更多...
(int)	- enableLocalVideo:streamType:
	开启或关闭本地视频的采集与发送。 通过主流或辅流视频通道进行本地视频流的采集与发送。 更多...
(int)	- enableMediaPub:withMediaType:
	开启或关闭本地媒体流（主流）的发送。 该方法用于开始或停止向网络发送本地音频或视频数据。 该方法不影响接收或播放远端媒体流，也不会影响本地音频或视频的采集状态。 更多...
(int)	- setChannelProfile:
	设置房间场景。 通过此接口可以实现设置房间场景为通话（默认）或直播场景。针对不同场景采取的优化策略不同，如通话场景侧重语音流畅度，直播场景侧重视频清晰度。 更多...
(int)	- setLocalVideoConfig:
	设置视频编码属性。 通过此接口可以设置视频主流的编码分辨率、裁剪模式、码率、帧率、带宽受限时的视频编码降级偏好、编码的镜像模式、编码的方向模式参数，详细信息请参考设置视频属性。 更多...
(int)	- setLocalVideoConfig:streamType:
	设置视频编码属性。 通过此接口可以设置视频主流或辅流的编码分辨率、裁剪模式、码率、帧率、带宽受限时的视频编码降级偏好、编码的镜像模式、编码的方向模式参数。 更多...
(int)	- setAudioProfile:scenario:
	设置音频编码属性。 通过此接口可以实现设置音频编码的采样率、码率、编码模式、声道数等，也可以设置音频属性的应用场景，包括聊天室场景、语音场景、音乐场景等。 更多...
(int)	- setupLocalVideoCanvas:
	设置本地用户视图。 通过本接口可以实现绑定本地用户和显示视图，并设置本地用户视图在本地显示时的镜像模式和裁减比例，只影响本地用户看到的视频画面。 更多...
(int)	- setupRemoteVideoCanvas:forUserID:
	设置远端用户视图。 通过本接口可以实现绑定远端用户和显示视图，并设置远端用户视图在本地显示时的镜像模式和裁减比例，只影响本地用户看到的视频画面。 更多...
(int)	- switchCamera
	切换前置或后置摄像头。 更多...
(int)	- setClientRole:
	设置直播场景下的用户角色。 通过本接口可以实现将用户角色在“主播”（kNERtcClientRoleBroadcaster）和“观众“（kNERtcClientRoleAudience）之间的切换，用户加入房间后默认为“主播”。 更多...
(int)	- setParameters:
	设置音视频通话的相关参数。 此接口提供技术预览或特别定制功能，详情请咨询技术支持。 更多...
(NSString *_Nullable)	- getParameter:extraInfo:
	以String 的形式获取一些内部参数，此接口为隐藏接口，需要特定参数及特定时机，详情联系技术支持。 更多...

属性
id< NERtcEngineDelegateEx >	engineDelegate

详细描述

NERtcEngine 的常用接口。

函数文档

connectionState

- (NERtcConnectionStateType) connectionState

获取当前房间连接状态。

返回

当前房间连接状态。

enableLocalAudio:

- (int) enableLocalAudio:

(BOOL)

enabled

开启/关闭本地音频采集和发送。
通过本接口可以实现开启或关闭本地语音功能，进行本地音频采集及处理。

自从

V3.5.0

调用时机

请在引擎初始化之后调用此接口，且该方法在加入房间前后均可调用。

注解

• 加入房间后，语音功能默认为开启状态。
• 该方法设置内部引擎为启用状态，在 leaveChannel 后仍然有效。
• 该方法不影响接收或播放远端音频流，enableLocalAudio(false) 适用于只下行不上行音频流的场景。
• 自 V4.4.0 版本起，开启或关闭本地音频采集的操作不会影响伴音/音效接口的使用，比如 enableLocalAudio(NO) 后仍可以调用 INERtcEngineEx#startAudioMixingWithOption: 方法播放音乐文件。
• 该方法会操作音频硬件设备，建议避免频繁开关，否则可能导致设备异常。

参数说明

参数名称	类型	描述
enabled	BOOL	是否启用本地音频的采集和发送： YES：开启本地音频采集。 NO：关闭本地音频采集。关闭后，远端用户会接收不到本地用户的音频流；但本地用户依然可以接收到远端用户的音频流。

示例代码

//打开音频采集
[[NERtcEngine sharedEngine] enableLocalAudio:YES];
//关闭音频采集
[[NERtcEngine sharedEngine] enableLocalAudio:NO];

相关回调

• 开启音频采集后，远端会触发 NERtcEngineDelegate#onNERtcEngineUserAudioDidStart: 回调。
• 关闭音频采集后，远端会触发 NERtcEngineDelegate#onNERtcEngineUserAudioDidStop: 回调。

相关接口

INERtcEngineEx#muteLocalAudio:：两者的差异在于，enableLocalAudio 用于开启本地语音采集及处理，而 muteLocalAudio 用于停止或继续发送本地音频流。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：引擎尚未初始化。
  • 30004（kNERtcErrNotSupported）：多房间场景下，在其他房间内已经开启了音频。
  • 30005（kNERtcErrInvalidState）：状态错误，比如引擎尚未初始化，或者正在进行网络测速。
  • 30101（kNERtcErrChannelNotJoined）：尚未加入房间。
  • 30300（kNERtcErrOSAuthorize）：未开启麦克风权限。

enableLocalVideo:

- (int) enableLocalVideo:

(BOOL)

enabled

开启或关闭本地视频的采集与发送。
通过本接口可以实现开启或关闭本地视频，不影响接收远端视频。

自从

V3.5.0

调用时机

请在初始化后调用该方法，且该方法在加入房间前后均可调用。

注解

该方法设置内部引擎为开启或关闭状态, 在 INERtcChannel#leaveChannel 后仍然有效。

参数说明

参数名称	类型	描述
enabled	BOOL	是否开启本地视频采集与发送： YES：开启本地视频采集。 NO：关闭本地视频采集。关闭后，远端用户无法接收到本地用户的视频流；但本地用户仍然可以接收到远端用户的视频流。

示例代码

//打开视频
[[NERtcEngine sharedEngine] enableLocalVideo:YES];
//关闭视频
[[NERtcEngine sharedEngine] enableLocalVideo:NO];

相关回调

• 开启本地视频采集后，远端会收到 NERtcEngineDelegate#onNERtcEngineUserAudioDidStart: 回调。
• 关闭本地视频采集后，远端会收到 NERtcEngineDelegate#onNERtcEngineUserAudioDidStop: 回调。

相关接口

若您希望开启辅流通道的视频采集，请调用 INERtcEngine#enableLocalVideo:streamType: 方法。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：通用错误，一般表示引擎错误，尝试再次调用此接口即可。
  • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如已开启外部视频采集。
  • 30300（kNERtcErrOSAuthorize）：应用未获取到操作系统的摄像头权限。

enableLocalVideo:streamType:

- (int) enableLocalVideo:		(BOOL)	enabled
streamType:		(NERtcStreamChannelType)	streamType

开启或关闭本地视频的采集与发送。
通过主流或辅流视频通道进行本地视频流的采集与发送。

自从

V4.6.20

调用时机

请在初始化后调用该方法，且该方法在加入房间前后均可调用。

注解

该方法设置内部引擎为开启或关闭状态, 在 INERtcEngine#leaveChannel 后仍然有效。

• 开启或关闭主流的设置，在切换房间（switchChannelWithToken）、主动离开房间（leaveChannel）、断网重连失败（onNERtcChannelDidDisconnectWithReason）或重新加入房间（onNERtcChannelRejoinChannel）后仍然有效。
• 开启或关闭辅流的设置，在切换房间（switchChannelWithToken）或重新加入房间（onNERtcChannelRejoinChannel）后仍然有效；但在主动离开房间（leaveChannel）或断网重连失败（onNERtcChannelDidDisconnectWithReason）后，该接口设置失效，将恢复至默认视频源输入。

参数说明

参数名称	类型	描述
streamType	NERtcStreamChannelType	视频通道类型： kNERtcStreamChannelTypeMainStream：主流。 kNERtcStreamChannelTypeSubStream：辅流。
enabled	BOOL	是否开启本地视频采集与发送： YES：开启本地视频采集。 NO：关闭本地视频采集。关闭后，远端用户无法接收到本地用户的视频流；但本地用户仍然可以接收到远端用户的视频流。

示例代码

//打开视频主流
[[NERtcEngine sharedEngine] enableLocalVideo:YES streamType:kNERtcStreamChannelTypeMainStream];
//关闭视频主流
[[NERtcEngine sharedEngine] enableLocalVideo:NO streamType:kNERtcStreamChannelTypeMainStream];
//打开视频辅流
[[NERtcEngine sharedEngine] enableLocalVideo:YES streamType:kNERtcStreamChannelTypeSubStream];
//关闭视频辅流
[[NERtcEngine sharedEngine] enableLocalVideo:NO streamType:kNERtcStreamChannelTypeSubStream];

相关回调

• streamType 为 kNERtcStreamChannelTypeMainStream（主流）时：
  • 开启本地视频采集后，远端会收到 NERtcEngineDelegate#onNERtcEngineUserAudioDidStart: 回调。
  • 关闭本地视频采集后，远端会收到 NERtcEngineDelegate#onNERtcEngineUserAudioDidStop: 回调。
• streamType 为 kNERtcStreamChannelTypeSubStream（辅流）时：
  • 开启本地视频采集后，远端会收到 NERtcEngineDelegate#onNERtcEngineUserSubStreamAudioDidStart: 回调。
  • 关闭本地视频采集后，远端会收到 NERtcEngineDelegate#onNERtcEngineUserSubStreamAudioDidStop: 回调。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：通用错误，一般表示引擎错误，尝试再次调用此接口即可。
  • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如已开启外部视频采集。
  • 30027（kNERtcErrDeviceOccupied）: 所选设备已被占用。比如已通过主流通道开启了摄像头，无法再通过辅流通道开启摄像头。
  • 30300（kNERtcErrOSAuthorize）：应用未获取到操作系统的摄像头权限。

enableMediaPub:withMediaType:

- (int) enableMediaPub:		(BOOL)	enabled
withMediaType:		(NERtcMediaPubType)	mediaType

开启或关闭本地媒体流（主流）的发送。
该方法用于开始或停止向网络发送本地音频或视频数据。
该方法不影响接收或播放远端媒体流，也不会影响本地音频或视频的采集状态。

自从

V4.6.10

注解

• 该方法暂时仅支持控制音频流的发送。
• 该方法在加入房间前后均可调用。
• 停止发送媒体流的状态会在通话结束后被重置为允许发送。
• 成功调用该方法切换本地用户的发流状态后，房间内其他用户会收到 NERtcEngineDelegate#onNERtcEngineUserAudioDidStart:（开启发送音频）或 NERtcEngineDelegate#onNERtcEngineUserAudioDidStop:（停止发送音频）的回调。

相关接口

• INERtcEngineEx#muteLocalAudio:：
  • 在需要开启本地音频采集（监测本地用户音量）但不发送音频流的情况下，您也可以调用 muteLocalAudio(YES) 方法。
  • 两者的差异在于， muteLocalAudio(YES) 仍然保持与服务器的音频通道连接，而 enableMediaPub(NO) 表示断开此通道，因此若您的实际业务场景为多人并发的大房间，建议您调用 enableMediaPub 方法。
    

参数

enabled	是否发布本地媒体流。 YES（默认）：发布本地媒体流。 NO：不发布本地媒体流。
mediaType	媒体发布类型，暂时仅支持音频。

返回

• 0：方法调用成功。
• 其他：方法调用失败。

getParameter:extraInfo:

- (NSString * _Nullable) getParameter:		(NSString *_Nonnull)	parameterKey
extraInfo:		(NSString *_Nullable)	extraInfo

以String 的形式获取一些内部参数，此接口为隐藏接口，需要特定参数及特定时机，详情联系技术支持。

参数

parameterKey	参数key
extraInfo	额外的信息

返回

如果查询到相关参数，以String 形式返回，否则返回nil

joinChannelWithToken:channelName:myUid:channelOptions:completion:

- (int) joinChannelWithToken:		(NSString *)	token
channelName:		(NSString *)	channelName
myUid:		(uint64_t)	uId
channelOptions:		(nullable NERtcJoinChannelOptions *)	channelOptions
completion:		(void(^)(NSError *_Nullable error, uint64_t channelId, uint64_t elapesd, uint64_t uid, NERtcJoinChannelExtraInfo *_Nullable info))	completion

加入音视频房间。
通过本接口可以实现加入音视频房间，加入房间后可以与房间内的其他用户进行音视频通话。

自从

V3.6.0

调用时机

请在初始化后调用该方法。

注解

• 同一个房间内的用户可以互相通话，多个用户加入同一个房间，可以群聊。使用不同 App Key 的 App 之间不能互通。
• 用户成功加入房间后，默认订阅房间内所有其他用户的音频流，可能会因此产生用量并影响计费；若您想取消自动订阅，可以在通话前通过调用 INERtcEngine#setParameters: 方法实现。
• 加入音视频房间时，如果指定房间尚未创建，云信服务器内部会自动创建一个同名房间。
• 传参中 uId 可选，若不指定则默认为 0，SDK 会自动分配一个随机 uId，并在 NERtcJoinChannelCompletion 回调方法中返回；App 层必须记住该返回值并维护，SDK 不对该返回值进行维护。
• 网络测速过程中无法加入房间。
• 若使用了云代理功能，uid 不允许传 0，请用真实的 uid。

参数说明

参数名称	类型	描述
token	NSString	安全认证签名（NERTC Token），可以设置为： null。调试模式下可设置为 null。安全性不高，建议在产品正式上线前在云信控制台中将鉴权方式恢复为默认的安全模式。 已获取的NERTC Token。安全模式下必须设置为获取到的 Token 。若未传入正确的 Token 将无法进入房间。推荐使用安全模式。
channelName	NSString	房间名称，设置相同房间名称的用户会进入同一个通话房间。 字符串格式，长度为 1 ~ 64 字节。 支持以下 89 个字符：a-z, A-Z, 0-9, space, !#$%&()+-:;≤.,>? @[]^_{|}~”
uId	uint64_t	用户的唯一标识 ID。
channelOptions	NERtcJoinChannelOptions *	加入房间时设置一些特定的房间参数。默认值为 NULL，详细信息请参考 NERtcJoinChannelOptions。
completion	NERtcJoinChannelCompletion	操作完成的 block 回调。

示例代码

int result = [[NERtcEngine sharedEngine] joinChannelWithToken:token channelName:channelName myUid:uid completion:^(NSError * _Nullable error, uint64_t channelId, uint64_t elapesd, uint64_t uid) {
                if (error) {
                   //join room failed
                }
                else {
               //join room success
                }
            }];
if(kNERtcNoError != result) {
    //join room failed
}

相关接口

• 您可以调用 INERtcEngine#leaveChannel 方法离开房间。
• 直播场景中，观众角色可以通过 INERtcEngine#switchChannelWithToken:channelName:completion: 接口切换房间。

相关回调

成功调用该方法加入房间后，远端会触发 NERtcEngineDelegate#onNERtcEngineUserDidJoinWithUserID:userName: 回调。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30005（kNERtcErrInvalidState)：状态错误，比如引擎尚未初始化或正在进行网络探测。

joinChannelWithToken:channelName:myUid:completion:

- (int) joinChannelWithToken:		(NSString *)	token
channelName:		(NSString *)	channelName
myUid:		(uint64_t)	uId
completion:		(NERtcJoinChannelCompletion)	completion

加入音视频房间。
通过本接口可以实现加入音视频房间，加入房间后可以与房间内的其他用户进行音视频通话。

自从

V3.6.0

调用时机

请在初始化后调用该方法。

注解

• 同一个房间内的用户可以互相通话，多个用户加入同一个房间，可以群聊。使用不同 App Key 的 App 之间不能互通。
• 用户成功加入房间后，默认订阅房间内所有其他用户的音频流，可能会因此产生用量并影响计费；若您想取消自动订阅，可以在通话前通过调用 INERtcEngine#setParameters: 方法实现。
• 加入音视频房间时，如果指定房间尚未创建，云信服务器内部会自动创建一个同名房间。
• 传参中 uId 可选，若不指定则默认为 0，SDK 会自动分配一个随机 uId，并在 NERtcJoinChannelCompletion 回调方法中返回；App 层必须记住该返回值并维护，SDK 不对该返回值进行维护。
• 网络测速过程中无法加入房间。
• 若使用了云代理功能，uid 不允许传 0，请用真实的 uid。

参数说明

参数名称	类型	描述
token	NSString	安全认证签名（NERTC Token），可以设置为： null。调试模式下可设置为 null。安全性不高，建议在产品正式上线前在云信控制台中将鉴权方式恢复为默认的安全模式。 已获取的NERTC Token。安全模式下必须设置为获取到的 Token 。若未传入正确的 Token 将无法进入房间。推荐使用安全模式。
channelName	NSString	房间名称，设置相同房间名称的用户会进入同一个通话房间。 字符串格式，长度为 1 ~ 64 字节。 支持以下 89 个字符：a-z, A-Z, 0-9, space, !#$%&()+-:;≤.,>? @[]^_{|}~”
uId	uint64_t	用户的唯一标识 ID。
completion	NERtcJoinChannelCompletion	操作完成的 block 回调。

示例代码

int result = [[NERtcEngine sharedEngine] joinChannelWithToken:token channelName:channelName myUid:uid completion:^(NSError * _Nullable error, uint64_t channelId, uint64_t elapesd, uint64_t uid) {
                if (error) {
                   //join room failed
                }
                else {
               //join room success
                }
            }];
if(kNERtcNoError != result) {
    //join room failed
}

相关接口

• 您可以调用 INERtcEngine#leaveChannel 方法离开房间。
• 直播场景中，观众角色可以通过 INERtcEngine#switchChannelWithToken:channelName:completion: 接口切换房间。

相关回调

成功调用该方法加入房间后，远端会触发 NERtcEngineDelegate#onNERtcEngineUserDidJoinWithUserID:userName: 回调。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30005（kNERtcErrInvalidState)：状态错误，比如引擎尚未初始化或正在进行网络探测。

leaveChannel

- (int) leaveChannel

离开音视频房间。
通过本接口可以实现挂断或退出通话，并释放本房间内的相关资源。

自从

V3.5.0

调用时机

请在初始化并成功加入房间后调用该方法。

注解

结束通话时必须调用此方法离开房间，否则无法开始下一次通话。

示例代码

[[NERtcEngine sharedEngine] leaveChannel];

相关回调

成功调用该方法离开房间后，本地会触发 NERtcEngineDelegate#onNERtcEngineDidLeaveChannelWithResult: 回调，远端会触发 NERtcEngineDelegate#onNERtcEngineUserDidLeaveWithUserID:reason: 回调。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：引擎尚未初始化。
  • 30005（kNERtcErrInvalidState)：状态错误，比如正在进行网络探测。

setAudioProfile:scenario:

- (int) setAudioProfile:		(NERtcAudioProfileType)	profile
scenario:		(NERtcAudioScenarioType)	scenario

设置音频编码属性。
通过此接口可以实现设置音频编码的采样率、码率、编码模式、声道数等，也可以设置音频属性的应用场景，包括聊天室场景、语音场景、音乐场景等。

自从

V3.5.0

调用时机

请在引擎初始化之后调用此接口，且该方法在加入房间前后均可调用。

注解

• 音乐场景下，建议将 profile 设置为 kNERtcAudioProfileHighQuality。
• 若您通过 INERtcEngine#setChannelProfile: 接口设置房间场景为直播模式，即 kNERtcChannelProfileLiveBroadcasting，但未调用此方法设置音频编码属性，或仅设置 profile 为 kNERtcAudioProfileDefault，则 SDK 会自动设置 profile 为 kNERtcAudioProfileHighQuality，且设置 scenario 为 kNERtcAudioScenarioMusic。

参数说明

参数名称	类型	描述
profile	NERtcAudioProfileType	设置采样率、码率、编码模式和声道数。
scenario	NERtcAudioScenarioType	设置音频应用场景。

示例代码

//设置profile为标准模式，scenario为语音场景
NERtcAudioScenarioType scenario = kNERtcAudioScenarioSpeech;
NERtcAudioProfileType profile = kNERtcAudioProfileStandard;
[[NERtcEngine sharedEngine] setAudioProfile:profile scenario:scenario];

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：引擎尚未初始化或下发配置未更新。

setChannelProfile:

- (int) setChannelProfile:

(NERtcChannelProfileType)

channelProfile

设置房间场景。
通过此接口可以实现设置房间场景为通话（默认）或直播场景。针对不同场景采取的优化策略不同，如通话场景侧重语音流畅度，直播场景侧重视频清晰度。

自从

V3.6.0

调用时机

请在初始化后调用该方法，且该方法仅可在加入房间前调用。

参数说明

参数名称	类型	描述
channelProfile	int	设置房间场景： kNERtcChannelProfileCommunication：通话场景。 kNERtcChannelProfileLiveBroadcasting：直播场景。

示例代码

//设置房间场景为直播场景
[[NERtcEngine sharedEngine] setChannelProfile:kNERtcChannelProfileLiveBroadcasting];

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30003（kNERtcErrInvalidParam）：参数错误。
  • 30005（kNERtcErrInvalidState)：当前状态不支持的操作，比如已经加入房间。

setClientRole:

- (int) setClientRole:

(NERtcClientRole)

role

设置直播场景下的用户角色。
通过本接口可以实现将用户角色在“主播”（kNERtcClientRoleBroadcaster）和“观众“（kNERtcClientRoleAudience）之间的切换，用户加入房间后默认为“主播”。

自从

V3.9.0

使用前提

该方法仅在通过 INERtcEngine#setChannelProfile: 方法设置房间场景为直播场景（kNERtcChannelProfileLiveBroadcasting ）时调用有效。

调用时机

请在初始化后调用该方法，且该方法在加入房间前后均可调用。

业务场景

适用于观众上下麦与主播互动的互动直播场景。

注解

用户切换为观众角色时，SDK 会自动关闭音视频设备。

参数说明

参数名称	类型	描述
role	NERtcClientRole	用户角色： kNERtcClientRoleBroadcaster（0）：设置用户角色为主播。主播可以开关摄像头等设备、可以发布流、可以操作互动直播推流相关接口、加入或退出房间状态对其他房间内用户可见。 kNERtcClientRoleAudience（1）：设置用户角色为观众。观众只能收流不能发流、加入或退出房间状态对其他房间内用户不可见。

示例代码

//切换用户角色为主播
[[NERtcEngine sharedEngine] setClientRole:kNERtcClientRoleAudience];
//切换用户角色为观众
[[NERtcEngine sharedEngine] setClientRole:kNERtcClientRoleBroadcaster];

相关回调

• 加入房间前调用该方法设置用户角色，不会触发任何回调，在加入房间成功后角色自动生效：
  • 设置用户角色为主播：加入房间后，远端用户触发 NERtcEngineDelegate#onNERtcEngineUserDidJoinWithUserID:userName: 回调。
  • 设置用户角色为观众：加入房间后，远端用户不触发任何回调。
• 加入房间后调用该方法切换用户角色：
  • 从观众角色切为主播：本端用户触发 NERtcEngineDelegate#onNERtcEngineDidClientRoleChanged:newRole: 回调，远端用户触发 NERtcEngineDelegate#onNERtcEngineUserDidJoinWithUserID:userName: 回调。
  • 从主播角色切为观众：本端用户触发 NERtcEngineDelegate#onNERtcEngineDidClientRoleChanged:newRole: 回调，远端用户触发 NERtcEngineDelegate#onNERtcEngineUserDidLeaveWithUserID:reason: 回调。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal)：引擎未创建成功。

setEngineEventDelegate:

- (int) setEngineEventDelegate:

(nullable id< NERtcEngineDelegateEx >)

delegate

设置事件通知回调。
通过本接口可以实现根据自身业务场景，监听相应的主回调。

自从

V4.6.40

调用时机

请在引擎初始化后调用此接口，且该方法在加入房间前后均可调用。

注解

• 调用此方法后会覆盖 INERtcEngine#setupEngineWithContext: 时传入的回调或上一次调用此方法设置的回调。
• 调用 INERtcEngine#destroyEngine 方法销毁引擎后，通过此接口设置的回调会失效，在下一次 INERtcEngine#setupEngineWithContext: 后需要重新设置。

参数说明

参数名称	类型	描述
delegate	nullable id<NERtcEngineDelegateEx>	SDK 主回调。设置为 nil 表示清空回调。

示例代码

//设置engineDelegate
[[NERtcEngine sharedEngine] setEngineEventDelegate:delegate];

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30005（kNERtcErrInvalidState)：引擎尚未初始化。

setLocalVideoConfig:

- (int) setLocalVideoConfig:

(NERtcVideoEncodeConfiguration *)

config

设置视频编码属性。
通过此接口可以设置视频主流的编码分辨率、裁剪模式、码率、帧率、带宽受限时的视频编码降级偏好、编码的镜像模式、编码的方向模式参数，详细信息请参考设置视频属性。

自从

V3.5.0

调用时机

请在初始化后调用该方法，且该方法在加入房间前后均可调用。

注解

• 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
• 每个属性对应一套视频参数，例如分辨率、帧率、码率等。所有设置的参数均为理想情况下的最大值。当视频引擎因网络环境等原因无法达到设置的分辨率、帧率或码率的最大值时，会取最接近最大值的那个值。
• 此接口为全量参数配置接口，重复调用此接口时，SDK 会刷新此前的所有参数配置，以最新的传参为准。所以每次修改配置时都需要设置所有参数，未设置的参数将取默认值。
• 自 V4.5.0 版本起，此方法设置实时生效；此前的版本中，此方法设置成功后，下次开启本端视频时生效。

参数说明

参数名称	类型	描述
config	NERtcVideoEncodeConfiguration	视频编码属性配置。

示例代码

//设置本地视频主流编码参数
NERtcEngine *coreEngine = [NERtcEngine sharedEngine];
NERtcVideoEncodeConfiguration *config = [[NERtcVideoEncodeConfiguration alloc] init];
config.width = 640;// 设置分辨率宽
config.height = 360;// 设置分辨率高
config.cropMode = kNERtcVideoCropMode16_9;      // 设置裁剪格式为16:9
config.frameRate = kNERtcVideoFrameRateFps30; //视频帧率
config.minFrameRate = mMinFrameRate; //视频最小帧率
config.bitrate = mBitrate; //视频编码码率
config.minBitrate = mMinBitrate; //视频编码最小码率
config.degradationPreference = kNERtcDegradationDefault; ;//带宽受限时的视频编码降级偏好
[coreEngine setLocalVideoConfig:config];

相关接口

若您希望为视频辅流通道设置编码属性，请调用 INERtcEngine#setLocalVideoConfig:streamType: 方法。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30003（kNERtcErrInvalidParam）：参数错误，比如 config 设置为空。
  • 30004（kNERtcErrNotSupported）：不支持的操作，比如当前使用的是纯音频 SDK。
  • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎未初始化成功。

setLocalVideoConfig:streamType:

- (int) setLocalVideoConfig:		(NERtcVideoEncodeConfiguration *)	config
streamType:		(NERtcStreamChannelType)	streamType

设置视频编码属性。
通过此接口可以设置视频主流或辅流的编码分辨率、裁剪模式、码率、帧率、带宽受限时的视频编码降级偏好、编码的镜像模式、编码的方向模式参数。

自从

V4.6.20

调用时机

请在初始化后调用该方法，且该方法在加入房间前后均可调用。

注解

• 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
• 每个属性对应一套视频参数，例如分辨率、帧率、码率等。所有设置的参数均为理想情况下的最大值。当视频引擎因网络环境等原因无法达到设置的分辨率、帧率或码率的最大值时，会取最接近最大值的那个值。
• 此接口为全量参数配置接口，重复调用此接口时，SDK 会刷新此前的所有参数配置，以最新的传参为准。所以每次修改配置时都需要设置所有参数，未设置的参数将取默认值。

参数说明

参数名称	类型	描述
config	NERtcVideoEncodeConfiguration	视频编码属性配置。
streamType	NERtcStreamChannelType	视频通道类型： kNERtcStreamChannelTypeMainStream：主流。 kNERtcStreamChannelTypeSubStream：辅流。

示例代码

//设置本地视频主流编码参数
NERtcEngine *coreEngine = [NERtcEngine sharedEngine];
NERtcVideoEncodeConfiguration *config = [[NERtcVideoEncodeConfiguration alloc] init];
config.width = 640;// 设置分辨率宽
config.height = 360;// 设置分辨率高
config.cropMode = kNERtcVideoCropMode16_9;      // 设置裁剪格式为16:9
config.frameRate = kNERtcVideoFrameRateFps30; //视频帧率
config.minFrameRate = mMinFrameRate; //视频最小帧率
config.bitrate = mBitrate; //视频编码码率
config.minBitrate = mMinBitrate; //视频编码最小码率
config.degradationPreference = kNERtcDegradationDefault; ;//带宽受限时的视频编码降级偏好
[coreEngine setLocalVideoConfig:config streamType:kNERtcStreamChannelTypeMainStream];
//设置本地视频辅流编码参数
NERtcVideoEncodeConfiguration *subConfig = [[NERtcVideoEncodeConfiguration alloc] init];
subConfig.width = 640;
subConfig.height = 360;
subConfig.cropMode = kNERtcVideoCropMode16_9;      
subConfig.frameRate = kNERtcVideoFrameRateFps30; 
subConfig.minFrameRate = mMinFrameRate; 
subConfig.bitrate = mBitrate;
subConfig.minBitrate = mMinBitrate; 
subConfig.degradationPreference = kNERtcDegradationDefault;
[coreEngine setLocalVideoConfig:config streamType:kNERtcStreamChannelTypeSubStream];

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30003（kNERtcErrInvalidParam）：参数错误，比如 config 设置为空。
  • 30004（kNERtcErrNotSupported）：不支持的操作，比如当前使用的是纯音频 SDK。
  • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎未初始化成功。

setParameters:

- (int) setParameters:

(NSDictionary *)

parameters

设置音视频通话的相关参数。
此接口提供技术预览或特别定制功能，详情请咨询技术支持。

自从

V3.5.0

调用时机

请在初始化后调用该方法，且该方法在加入房间前后均可调用。

参数说明

参数名称	类型	描述
parameters	NSDictionary	音视频通话的参数集合。详细信息请参考 NERtcEngineBase.h 中的定义。

示例代码

NSDictionary *paramDic = @{kNERtcKeyVideoPreferHWEncode : @(YES)};
...
[[NERtcEngine sharedEngine] setParameters:paramDic];

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrInvalidParam）：参数错误。

setupEngineWithContext:

- (int) setupEngineWithContext:

(NERtcEngineContext *)

context

创建 NERtc 实例。
通过本接口可以实现创建 NERtc 实例并初始化 NERTC SDK 服务。

自从

V3.5.0

调用时机

请确保在调用其他 API 前先调用该方法创建并初始化 NERtc 实例。

注解

• 使用同一个 App Key 的 App 才能进入同一个房间进行通话或直播。
• 一个 App Key 只能用于创建一个 NERtc 实例；若您需要更换 App Key，必须先调用 INERtcEngine#destroyEngine 方法销毁当前实例，再调用本方法重新创建实例。

参数说明

参数名称	类型	描述
context	NERtcEngineContext	传入的 RTC engine context 对象。

示例代码

NERtcEngineContext *context = [[NERtcEngineContext alloc] init];
context.appKey = appkey; //appkey
context.engineDelegate = delegate; //delegate处理对象        
NERtcLogSetting *logSetting = [[NERtcLogSetting alloc] init];
logSetting.logDir = logDir;//日志路径
logSetting.logLevel = kNERtcLogLevelWarning; //debug级别可选择kNERtcLogLevelInfo或者更高，有利于调试中的问题定位;release版本建议用warning级别
context.logSetting = logSetting;
[[NERtcEngine sharedEngine] setupEngineWithContext:context];

相关接口

若您不再使用 NERtc 实例，需要调用 INERtcEngine#destroyEngine 方法进行销毁。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30003（kNERtcErrInvalidParam）：参数错误。
  • 30005（kNERtcErrInvalidState)：状态错误，比如正在重连。

setupLocalVideoCanvas:

- (int) setupLocalVideoCanvas:

(NERtcVideoCanvas *_Nullable)

canvas

设置本地用户视图。
通过本接口可以实现绑定本地用户和显示视图，并设置本地用户视图在本地显示时的镜像模式和裁减比例，只影响本地用户看到的视频画面。

自从

V3.5.0

调用时机

请在初始化后调用该方法，且该方法在加入房间前后均可调用。

注解

• 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
• 在实际业务中，通常建议在初始化后即调用该方法进行本地视图设置，然后再加入房间或开启预览。

参数说明

参数名称	类型	描述
render	NERtcVideoCanvas	本地用户视频的画布。设置为 nil 表示取消并释放已设置的画布。

示例代码

UIView *localUserView = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 200, 200)];
NERtcVideoCanvas *canvas = [[NERtcVideoCanvas alloc] init];
canvas.container = localUserView;
canvas.renderMode = kNERtcVideoRenderScaleFit;
canvas.mirrorMode = kNERtcVideoMirrorModeAuto;
[[NERtcEngine sharedEngine] setupLocalVideoCanvas:canvas];

相关接口

若您希望在通话中更新本地用户视图的渲染或镜像模式，请调用 INERtcEngineEx#setLocalRenderScaleMode: 方法。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：引擎尚未初始化。
  • 30004（kNERtcErrNotSupported）：不支持的操作，比如纯音频 SDK 不支持该功能。
  • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎尚未初始化。

setupRemoteVideoCanvas:forUserID:

- (int) setupRemoteVideoCanvas:		(NERtcVideoCanvas *_Nullable)	canvas
forUserID:		(uint64_t)	userID

设置远端用户视图。
通过本接口可以实现绑定远端用户和显示视图，并设置远端用户视图在本地显示时的镜像模式和裁减比例，只影响本地用户看到的视频画面。

自从

V3.5.0

调用时机

请在初始化后调用该方法，且该方法在加入房间前后均可调用。

注解

您可以通过设置 canvas 参数为空（传 nil）以解除远端用户视图绑定；退出房间后，SDK 也会主动清除远端用户和视图的绑定关系。

参数说明

参数名称	类型	描述
canvas	NERtcVideoCanvas	远端用户视频的画布。
userID	uint64_t	远端用户的 ID。可以在 NERtcEngineDelegate#onNERtcEngineUserDidJoinWithUserID:userName: 回调中获取。

示例代码

- (void)onNERtcEngineUserDidJoinWithUserID:(uint64_t)userID userName:(NSString *)userName {
    UIView *remoteUserView = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 200, 200)];
    NERtcVideoCanvas *canvas = [[NERtcVideoCanvas alloc] init];
    canvas.container = remoteUserView;
    canvas.renderMode = kNERtcVideoRenderScaleFit;
    canvas.mirrorMode = kNERtcVideoMirrorModeAuto;
    [[NERtcEngine sharedEngine] setupRemoteVideoCanvas:canvas forUserID:userID];
}

相关接口

若您希望在通话中更新远端用户视图的渲染模式，请调用 INERtcEngineEx#setRemoteRenderScaleMode:forUserID:方法。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：引擎尚未初始化。
  • 30004（kNERtcErrNotSupported）：纯音频 SDK 不支持该功能。
  • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎尚未初始化。

switchCamera

- (int) switchCamera

切换前置或后置摄像头。

自从

V3.5.0

使用前提

请在调用 INERtcEngineEx#startPreview: 或 INERtcEngine#joinChannelWithToken:channelName:myUid:channelOptions:completion: 方法且开启摄像头之后调用此接口。

调用时机

请在引擎初始化之后调用此接口，且该方法在加入房间前后均可调用。

注解

• 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
• 该方法需要在相机启动后才可调用。

示例代码

[[NERtcEngine sharedEngine] switchCamera];

返回

• 0（kNERtcNoError）：方法调用成功。

• 其他：方法调用失败。
  • 30004（kNERtcErrNotSupported）：不支持的操作，比如纯音频 SDK 不支持该功能。
  • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎尚未初始化或者未开启摄像头。

switchChannelWithToken:channelName:channelOptions:completion:

- (int) switchChannelWithToken:		(NSString *)	token
channelName:		(NSString *)	channelName
channelOptions:		(nullable NERtcJoinChannelOptions *)	channelOptions
completion:		(void(^)(NSError *_Nullable error, uint64_t channelId, uint64_t elapesd, uint64_t uid, NERtcJoinChannelExtraInfo *_Nullable info))	completion

快速切换音视频房间。
房间场景为直播场景时，房间中角色为观众的成员可以调用该方法从当前房间快速切换至另一个房间。
成功调用该方切换房间后，本端会收到离开房间的回调 onNERtcEngineDidLeaveChannelWithResult；远端用户会收到 onNERtcEngineUserDidLeaveWithUserID 和 onNERtcEngineUserDidJoinWithUserID 的回调。

注解

• 房间成员成功切换房间后，默认订阅房间内所有其他成员的音频流，因此产生用量并影响计费。如果想取消订阅，可以通过调用相应的 subscribeRemoteAudio 方法实现。
• 该方法仅适用于直播场景中，角色为观众的音视频房间成员。即已通过接口 setchannelprofile 设置房间场景为直播，通过 setClientRole 设置房间成员的角色为观众。

参数

token	在服务器端生成的用于鉴权的安全认证签名（Token）。可设置为： null。调试模式下可设置为 null。安全性不高，建议在产品正式上线前在云信控制台中将鉴权方式恢复为默认的安全模式。 已获取的NERTC Token。安全模式下必须设置为获取到的 Token 。若未传入正确的 Token 将无法进入房间。推荐使用安全模式。
channelName	期望切换到的目标房间名称
channelOptions	加入房间时设置一些特定的房间参数
completion	操作完成的 block 回调

返回

• 0(NERtcEngineErrorCode.kNERtcNoError)：方法调用成功。
• 30001(NERtcEngineErrorCode.kNERtcErrFatal)：通用错误。
• 30003(NERtcEngineErrorCode.kNERtcErrInvalidParam)：参数错误。
• 30109(NERtcEngineErrorCode.kNERtcErrSwitchChannelInvalidState): 切换房间状态无效。
• 403(NERtcEngineErrorCode.KNERtcErrChannelReservePermissionDenied): 用户角色不是观众。
• 30100(NERtcEngineErrorCode.kNERtcErrChannelAlreadyJoined): 房间名无效，已在此房间中。

switchChannelWithToken:channelName:completion:

- (int) switchChannelWithToken:		(NSString *)	token
channelName:		(NSString *)	channelName
completion:		(NERtcJoinChannelCompletion)	completion

快速切换音视频房间。 通过此接口可以实现当房间场景为直播场景时，房间中角色为观众的成员从当前房间快速切换至另一个房间。

使用前提

请先通过 INERtcEngine#setChannelProfile: 接口设置房间模式为直播模式，并通过 INERtcEngine#setClientRole: 接口设置房间成员的角色为观众。

调用时机

请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。

注解

房间成员成功切换房间后，默认订阅房间内所有其他成员的音频流，因此会产生用量并产生计费；若想取消订阅，可以调用 INERtcEngineEx#subscribeRemoteAudio:forUserID: 方法，并设置 subscribe 参数为 NO。

参数说明

参数名称	类型	描述
token	NSString *	在服务器端生成的用于鉴权的安全认证签名（Token），可设置为： 已获取的 NERTC Token。安全模式下必须设置为获取到的 Token，默认 Token 有效期为 10min，也可以定期通过应用服务器向云信服务器申请 Token 或者申请长期且可复用的 Token。 null。调试模式下可设置为 null。安全性不高，建议在产品正式上线前在云信控制台中将鉴权方式恢复为默认的安全模式。
channelName	NSString *	期望切换到的目标房间名称。
completion	NERtcJoinChannelCompletion	操作完成的 block 回调。

示例代码

[self switchChannelWithToken:token channelName:channelName channelOptions:channelOption completion:^(NSError * _Nullable error, uint64_t channelId, uint64_t elapesd, uint64_t uid, NERtcJoinChannelExtraInfo * _Nullable info) {
}];

相关回调

成功调用此接口切换房间后：

• 本端用户会先收到 NERtcEngineDelegate#onNERtcEngineDidLeaveChannelWithResult: 回调，其中 result 参数为 NERtcEngineErrorCode.NERtcError#kNERtcErrChannelLeaveBySwitchAction；再收到成功加入新房间的回调 NERtcJoinChannelCompletion。
• 远端用户会收到 NERtcEngineDelegate#onNERtcEngineUserDidLeaveWithUserID:reason:leaveExtraInfo: 和 NERtcEngineDelegate#onNERtcEngineUserDidJoinWithUserID:userName:joinExtraInfo: 的回调。

返回

• 0（kNERtcNoError）： 方法调用成功。
• 其他：方法调用失败。
  • 403（kNERtcErrChannelReservePermissionDenied）：没有权限，比如主播无法切换房间。
  • 30004（kNERtcErrNotSupported）：不支持的操作，比如当前是 1 对 1 模式。
  • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎尚未初始化。
  • 30100（kNERtcErrChannelAlreadyJoined）：重复加入房间。
  • 30103（kNERtcErrRequestJoinChannelFail）：加入房间操作失败。
  • 30109（kNERtcErrSwitchChannelInvalidState）：尚未加入房间。

属性说明

engineDelegate

- (id<NERtcEngineDelegateEx>) engineDelegate

readnonatomicweak

---

该协议的文档由以下文件生成:

• exportHeaders/INERtcEngine.h