NERtc iOS SDK  V4.6.61
构造函数 | 属性 | 所有成员列表
<INERtcEngine>协议 参考

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

#import <INERtcEngine.h>

类 <INERtcEngine> 继承关系图:
<INERtcEngineEx> NERtcEngine

构造函数

(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< NERtcEngineDelegateExengineDelegate
 

详细描述

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];
NERtcEngine 类
Definition: NERtcEngine.h:19
相关回调
相关接口
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];
相关回调
相关接口
若您希望开启辅流通道的视频采集,请调用 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];
@ kNERtcStreamChannelTypeMainStream
主流通道。
Definition: NERtcEngineEnum.h:1043
@ kNERtcStreamChannelTypeSubStream
辅流通道。
Definition: NERtcEngineEnum.h:1052
相关回调
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30001(kNERtcErrFatal):通用错误,一般表示引擎错误,尝试再次调用此接口即可。
    • 30005(kNERtcErrInvalidState):当前状态不支持的操作,比如已开启外部视频采集。
    • 30027(kNERtcErrDeviceOccupied): 所选设备已被占用。比如已通过主流通道开启了摄像头,无法再通过辅流通道开启摄像头。
    • 30300(kNERtcErrOSAuthorize):应用未获取到操作系统的摄像头权限。

◆ enableMediaPub:withMediaType:

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

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

自从
V4.6.10
注解
相关接口
  • 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
}
@ kNERtcNoError
没有错误。
Definition: NERtcEngineErrorCode.h:27
相关接口
相关回调
成功调用该方法加入房间后,远端会触发 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
}
相关接口
相关回调
成功调用该方法加入房间后,远端会触发 NERtcEngineDelegate#onNERtcEngineUserDidJoinWithUserID:userName: 回调。
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30005(kNERtcErrInvalidState):状态错误,比如引擎尚未初始化或正在进行网络探测。

◆ leaveChannel

- (int) leaveChannel

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

自从
V3.5.0
调用时机
请在初始化并成功加入房间后调用该方法。
注解
结束通话时必须调用此方法离开房间,否则无法开始下一次通话。
示例代码
[[NERtcEngine sharedEngine] leaveChannel];
int 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为语音场景
[[NERtcEngine sharedEngine] setAudioProfile:profile scenario:scenario];
NERtcAudioProfileType
音频质量能力概要 音频属性:设置采样率,码率,编码模式和声道数
Definition: NERtcEngineEnum.h:1448
@ kNERtcAudioProfileStandard
标准音质模式。采样率为 16 kHz、语音编码、单声道、编码码率最大值为 20 Kbps。
Definition: NERtcEngineEnum.h:1466
NERtcAudioScenarioType
音频应用场景。 不同的场景设置对应不同的音频采集模式(移动平台)、播放模式。
Definition: NERtcEngineEnum.h:1532
@ kNERtcAudioScenarioSpeech
语音场景。
Definition: NERtcEngineEnum.h:1550
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30001(kNERtcErrFatal):引擎尚未初始化或下发配置未更新。

◆ setChannelProfile:

- (int) setChannelProfile: (NERtcChannelProfileType channelProfile

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

自从
V3.6.0
调用时机
请在初始化后调用该方法,且该方法仅可在加入房间前调用。
参数说明
参数名称 类型 描述
channelProfile int 设置房间场景:
  • kNERtcChannelProfileCommunication:通话场景。
  • kNERtcChannelProfileLiveBroadcasting:直播场景。
示例代码
//设置房间场景为直播场景
[[NERtcEngine sharedEngine] setChannelProfile:kNERtcChannelProfileLiveBroadcasting];
@ kNERtcChannelProfileLiveBroadcasting
直播场景。该场景有主播和观众两种用户角色,可以通过setClientRole设置。主播可以发布和接收音视频流,观众直接接收流。适用于语聊房、视频直播、互动大班课等应用场景。
Definition: NERtcEngineEnum.h:1597
返回
  • 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];
@ kNERtcClientRoleBroadcaster
(默认)直播模式中的主播,可以操作摄像头等音视频设备、发布流、配置互动直播推流任务、上下线对房间内其他用户可见。
Definition: NERtcEngineEnum.h:215
@ kNERtcClientRoleAudience
直播模式中的观众,观众只能接收音视频流,不支持操作音视频设备、配置互动直播推流任务、上下线不通知其他用户。
Definition: NERtcEngineEnum.h:224
相关回调
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30001(kNERtcErrFatal):引擎未创建成功。

◆ setEngineEventDelegate:

- (int) setEngineEventDelegate: (nullable id< NERtcEngineDelegateEx >)  delegate

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

自从
V4.6.40
调用时机
请在引擎初始化后调用此接口,且该方法在加入房间前后均可调用。
注解
参数说明
参数名称 类型 描述
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];
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];
@ kNERtcVideoCropMode16_9
16:9
Definition: NERtcEngineEnum.h:875
@ kNERtcDegradationDefault
(默认)根据场景模式调整适应性偏好。
Definition: NERtcEngineEnum.h:552
@ kNERtcVideoFrameRateFps30
30 fps.
Definition: NERtcEngineEnum.h:507
NSInteger bitrate
视频编码的码率,单位为 Kbps。 您可以根据场景需要,手动设置想要的码率。详细码表请参考设置视频属性。
Definition: NERtcEngineBase.h:450
NERtcVideoFrameRate frameRate
视频编码的帧率。详细信息请参考 NERtcVideoFrameRate。
Definition: NERtcEngineBase.h:377
NSInteger minFrameRate
视频编码的最小帧率。默认为 0,表示使用默认最小帧率。
Definition: NERtcEngineBase.h:387
NSInteger minBitrate
视频编码的最小码率,单位为 Kbps。您可以根据场景需要,手动设置想要的最小码率,若设置为0,SDK 将会自行计算处理。
Definition: NERtcEngineBase.h:460
本地视频发送配置
Definition: NERtcEngineBase.h:527
int width
视频编码分辨率,衡量编码质量,以宽x高表示。与maxProfile属性二选一。推荐优先使用自定义宽高设置。 width表示视频帧在横轴上的像素,即自定义宽。
Definition: NERtcEngineBase.h:544
NERtcVideoCropMode cropMode
视频画面裁剪模式,默认为 kNERtcVideoCropDefault。自定义视频输入不支持设置裁剪模式。
Definition: NERtcEngineBase.h:572
NERtcDegradationPreference degradationPreference
带宽受限时的视频编码降级偏好。详细信息请参考 NERtcDegradationPreference。
Definition: NERtcEngineBase.h:594
int height
视频编码分辨率,衡量编码质量,以宽x高表示。与maxProfile属性二选一。推荐优先使用自定义宽高设置。 height表示视频帧在纵轴上的像素,即自定义高。
Definition: NERtcEngineBase.h:562
相关接口
若您希望为视频辅流通道设置编码属性,请调用 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];
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];
//设置本地视频辅流编码参数
subConfig.width = 640;
subConfig.height = 360;
subConfig.minFrameRate = mMinFrameRate;
subConfig.bitrate = mBitrate;
subConfig.minBitrate = mMinBitrate;
[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];
NERTC_EXTERN_API NSString *const kNERtcKeyVideoPreferHWEncode
是否优先使用硬件编码视频数据。 布尔值,默认值 YES。 请在初始化(setupEngineWithContext)之前设置该参数,否则该参数会在下次初始化之后生效。
Definition: NERtcEngineBase.h:48
返回
  • 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];
@ kNERtcLogLevelWarning
Warning 级别日志信息。默认级别。
Definition: NERtcEngineEnum.h:3267
初始化设置 NERtcEngine
Definition: NERtcEngineContext.h:22
NERtcLogSetting * logSetting
日志配置,详细信息请参考 NERtcLogSetting。
Definition: NERtcEngineContext.h:41
id< NERtcEngineDelegateEx > engineDelegate
NERtcEngine 的回调接口,由用户提供。
Definition: NERtcEngineContext.h:51
NSString * appKey
应用的 App Key。在云信控制台创建应用后,可以查看对应的 App Key。
Definition: NERtcEngineContext.h:31
日志相关设置。
Definition: NERtcEngineBase.h:2741
NSString * logDir
日志目录的完整路径,采用UTF-8 编码。
Definition: NERtcEngineBase.h:2750
NERtcLogLevel logLevel
打印的日志级别。默认为 info 级别。详细信息请参考 NERtcLogLevel。
Definition: NERtcEngineBase.h:2760
相关接口
若您不再使用 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;
[[NERtcEngine sharedEngine] setupLocalVideoCanvas:canvas];
@ kNERtcVideoMirrorModeAuto
(默认)由 SDK 决定镜像模式
Definition: NERtcEngineEnum.h:780
@ kNERtcVideoRenderScaleFit
适应视频,视频尺寸等比缩放。优先保证视频内容全部显示。若视频尺寸与显示视窗尺寸不一致,视窗未被填满的区域填充背景色。
Definition: NERtcEngineEnum.h:712
视频画布设置。
Definition: NERtcEngineBase.h:277
NERtcVideoRenderScaleMode renderMode
视频渲染模式。
Definition: NERtcEngineBase.h:306
VIEW_CLASS * container
视频窗口容器(SDK内部渲染)。
Definition: NERtcEngineBase.h:296
NERtcVideoMirrorMode mirrorMode
视频镜像模式。
Definition: NERtcEngineBase.h:320
相关接口
若您希望在通话中更新本地用户视图的渲染或镜像模式,请调用 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;
[[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];
int 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 回调
返回

◆ 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) {
}];
joinChannel 回调时的一些可选信息
Definition: NERtcEngineBase.h:2964
相关回调
成功调用此接口切换房间后:
返回
  • 0(kNERtcNoError): 方法调用成功。
  • 其他:方法调用失败。
    • 403(kNERtcErrChannelReservePermissionDenied):没有权限,比如主播无法切换房间。
    • 30004(kNERtcErrNotSupported):不支持的操作,比如当前是 1 对 1 模式。
    • 30005(kNERtcErrInvalidState):当前状态不支持的操作,比如引擎尚未初始化。
    • 30100(kNERtcErrChannelAlreadyJoined):重复加入房间。
    • 30103(kNERtcErrRequestJoinChannelFail):加入房间操作失败。
    • 30109(kNERtcErrSwitchChannelInvalidState):尚未加入房间。

属性说明

◆ engineDelegate

- (id<NERtcEngineDelegateEx>) engineDelegate
readnonatomicweak

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