NERtc iOS SDK V5.6.20
载入中...
搜索中...
未找到
构造函数 | 所有成员列表
<INERtcChannel>协议 参考

INERtcChannel 类在指定房间中实现实时音视频功能。通过创建多个 NERtcChannel 对象,用户可以同时加入多个房间。 更多...

#include <INERtcChannel.h>

类 <INERtcChannel> 继承关系图:
NERtcChannel

构造函数

(int) - destroy
 
(int) - setChannelDelegate:
 设置 channel 的回调。
 
(int) - setDelegateQueue:
 设置驱动 NERtcChannelDelegate 事件回调队列
 
(NSString *) - getChannelName
 获取当前房间名。
 
(NERtcConnectionStateType- connectionState
 获取当前房间连接状态。
 
(int) - joinChannelWithToken:completion:
 加入音视频房间。
通过本接口可以实现加入音视频房间,加入房间后可以与房间内的其他用户进行音视频通话。
 
(int) - joinChannelWithToken:myUid:completion:
 加入音视频房间。
通过本接口可以实现加入音视频房间,加入房间后可以与房间内的其他用户进行音视频通话。
 
(int) - joinChannelWithToken:myUid:channelOptions:completion:
 加入音视频房间。
通过本接口可以实现加入音视频房间,加入房间后可以与房间内的其他用户进行音视频通话。
 
(int) - leaveChannel
 离开音视频房间。
通过本接口可以实现挂断或退出通话,并释放本房间内的相关资源。
 
(int) - enableLocalAudio:
 开启/关闭本地音频采集和发送。
通过本接口可以实现开启或关闭本地语音功能,进行本地音频采集及处理。
 
(int) - enableLocalVideo:
 开启或关闭本地视频的采集与发送。
通过本接口可以实现开启或关闭本地视频,不影响接收远端视频。
 
(int) - enableLocalVideo:streamType:
 开启或关闭本地视频的采集与发送。
通过主流或辅流视频通道进行本地视频流的采集与发送。
 
(int) - enableMediaPub:withMediaType:
 开启或关闭本地媒体流(主流)的发送。
该方法用于开始或停止向网络发送本地音频或视频数据。
该方法不影响接收或播放远端媒体流,也不会影响本地音频或视频的采集状态。
 
(int) - enableDualStreamMode:
 设置是否开启视频大小流模式。
通过本接口可以实现设置单流或者双流模式。发送端开启双流模式后,接收端可以选择接收大流还是小流。其中,大流指高分辨率、高码率的视频流,小流指低分辨率、低码率的视频流。
 
(int) - setCameraCaptureConfig:
 设置本地摄像头的视频主流采集配置。
通过此接口可以设置本地摄像头采集的主流视频宽度、高度、旋转角度等。
 
(int) - setCameraCaptureConfig:streamType:
 设置本地摄像头的视频主流或辅流采集配置。
通过此接口可以设置本地摄像头采集的主流或辅流视频宽度、高度、旋转角度等。
 
(int) - setLocalVideoConfig:
 设置视频编码属性。
通过此接口可以设置视频主流的编码分辨率、裁剪模式、码率、帧率、带宽受限时的视频编码降级偏好、编码的镜像模式、编码的方向模式参数,详细信息请参考 设置视频属性
 
(int) - setLocalVideoConfig:streamType:
 设置视频编码属性。
通过此接口可以设置视频主流或辅流的编码分辨率、裁剪模式、码率、帧率、带宽受限时的视频编码降级偏好、编码的镜像模式、编码的方向模式参数。
 
(int) - switchCamera
 切换前置/后置摄像头。
该方法需要在相机启动后调用,例如调用 startPreview 或 joinChannel 后。
 
(int) - switchCameraWithPosition:
 指定前置/后置摄像头。
该方法需要在相机启动后调用,例如调用 startPreview 或 joinChannel 后。
 
(int) - subscribeRemoteAudio:forUserID:
 取消或恢复订阅指定远端用户的音频主流。
加入房间时,默认订阅所有远端用户的音频主流,您也可以通过此方法取消或恢复订阅指定远端用户的音频主流。
 
(int) - subscribeAllRemoteAudio:
 取消或恢复订阅所有远端用户的音频主流。
加入房间时,默认订阅所有远端用户的音频主流,即 INERtcEngine#setParameters: 方法的 kNERtcKeyAutoSubscribeAudio 参数默认设置为 YES;只有当该参数的设置为 NO 时,此接口的调用才会生效。
 
(int) - setAudioSubscribeOnlyBy:
 设置自己的音频只能被房间内指定的人订阅。
默认房间所有其他人都可以订阅自己的音频。
 
(int) - muteLocalAudio:
 开启或关闭本地音频主流的发送。
该方法用于向网络发送或取消发送本地音频数据,不影响本地音频的采集状态,也不影响接收或播放远端音频流。
 
(int) - enableAudioVolumeIndication:interval:vad:
 启用说话者音量提示。
该方法允许 SDK 定期向 App 反馈本地发流用户和瞬时音量最高的远端用户(最多 3 位)的音量相关信息,即当前谁在说话以及说话者的音量。
启用该方法后,只要房间内有发流用户,无论是否有人说话,SDK 都会在加入房间后根据预设的时间间隔触发 NERtcEngineDelegateEx#onRemoteAudioVolumeIndication:totalVolume: 回调。
 
(int) - setupLocalVideoCanvas:
 设置本地用户视图。
通过本接口可以实现绑定本地用户和显示视图,并设置本地用户视图在本地显示时的镜像模式和裁减比例,只影响本地用户看到的视频画面。
 
(int) - setLocalRenderScaleMode:
 设置画布中本地视频画面的显示模式。
通过本接口可以实现设置本地视频画面的适应性,即是否裁剪或缩放。
 
(int) - setupRemoteVideoCanvas:forUserID:
 设置远端用户视图。
通过本接口可以实现绑定远端用户和显示视图,并设置远端用户视图在本地显示时的镜像模式和裁减比例,只影响本地用户看到的视频画面。
 
(int) - setRemoteRenderScaleMode:forUserID:
 设置画布中远端视频画面的显示模式。
通过本接口可以实现设置远端视频画面的适应性,即是否裁剪或缩放。
 
(int) - subscribeRemoteVideo:forUserID:streamType:
 订阅或取消订阅指定远端用户的视频主流。
加入房间后,默认不订阅所有远端用户的视频主流;若您希望看到指定远端用户的视频,可以在监听到对方加入房间或发布视频流之后,通过此方法订阅该用户的视频主流。
 
(int) - muteLocalVideo:
 取消或恢复发布本端视频主流。
调用该方法取消发布本地视频主流后,SDK 不再发送本地视频主流。
 
(int) - muteLocalVideo:streamType:
 取消或恢复发布本地视频。
调用该方法取消发布本地视频主流或辅流后,SDK 不再发送本地视频流。
 
(int) - setExternalVideoSource:streamType:
 开启或关闭外部视频源数据输入。
通过本接口可以实现创建自定义的外部视频源,您可以选择通过主流或辅流通道传输该外部视频源的数据,但暂不支持同时开启。
 
(int) - pushExternalVideoFrame:streamType:
 推送外部视频帧。
该方法主动将视频帧数据用 NERtcVideoFrame 类封装后传递给 SDK。
 
(int) - setClientRole:
 设置直播场景下的用户角色。
通过本接口可以实现将用户角色在“主播”(kNERtcClientRoleBroadcaster)和“观众“(kNERtcClientRoleAudience)之间的切换,用户加入房间后默认为“主播”。
 
(int) - adjustUserPlaybackSignalVolume:forUserID:
 调节本地播放的指定远端用户的信号音量。
通过此接口可以实现在通话过程中随时调节指定远端用户在本地播放的混音音量。
 
(int) - adjustChannelPlaybackSignalVolume:
 调节本地播放的指定房间的所有远端用户的信号音量。
通过此接口可以实现在通话过程中随时调节指定房间内的所有远端用户在本地播放的混音音量。
 
(int) - enableLocalSubStreamAudio:
 开启或关闭音频辅流。
开启时远端会收到 NERtcChannelDelegate#onNERtcChannelUserSubStreamAudioDidStart: 回调,关闭时远端会收到 NERtcChannelDelegate#onNERtcChannelUserSubStreamAudioDidStop: 回调。
 
(int) - subscribeRemoteSubStreamAudio:forUserID:
 设置是否订阅指定远端用户的音频辅流。
 
(int) - muteLocalSubStreamAudio:
 静音或解除静音本地上行的音频辅流。
 
(int) - setupLocalSubStreamVideoCanvas:
 设置本端用户的视频辅流画布。
通过此接口可以实现设置本端用户的辅流显示视图。
 
(int) - startScreenCapture:
 开启屏幕共享。
通过此接口开启屏幕共享后,屏幕共享内容以视频辅流的形式发送。
 
(int) - stopScreenCapture
 关闭屏幕共享。
通过此接口可以实现关闭屏幕共享辅流。
 
(int) - setLocalRenderSubStreamScaleMode:
 设置画布中本地屏幕共享辅流视频画面的显示模式。
通过本接口可以实现设置本地发布的屏幕共享视频画面的适应性,即是否裁剪或缩放。
 
(int) - setupRemoteSubStreamVideoCanvas:forUserID:
 设置远端用户的视频辅流画布。
通过此接口可以实现绑定远端用户和对应辅流的显示视图,即指定某个 uid 使用对应的画布显示。
 
(int) - subscribeRemoteSubStreamVideo:forUserID:
 订阅或取消订阅远端用户的视频辅流。
 
(int) - setRemoteRenderSubStreamVideoScaleMode:forUserID:
 设置画布中远端屏幕共享视频画面的显示模式。
通过本接口可以实现设置远端发布的屏幕共享视频画面的适应性,即是否裁剪或缩放。
 
(int) - setRemoteHighPriorityAudioStream:forUserID:streamType:
 设置远端用户音频流的高优先级。 支持在音频自动订阅的情况下,设置某一个远端用户的音频为最高优先级,可以优先听到该用户的音频。
 
(int) - setRangeAudioMode:
 设置范围语音模式
 
(int) - setRangeAudioTeamID:
 设置范围语音小队
 
(int) - setAudioRecvRange:conversationalDistance:rollOff:
 引擎 3D 音效算法距离范围设置
 
(int) - updateSelfPosition:
 设置空间音效中说话者和接收者的空间位置信息。SDK 会根据该方法中的参数计算接收者和说话者之间的相对位置,进而渲染出空间音效。
 
(int) - enableSpatializerRoomEffects:
 开启或关闭空间音效的房间混响效果
 
(int) - setSpatializerRoomProperty:
 设置空间音效的房间混响属性
 
(int) - setSpatializerRenderMode:
 设置空间音效的渲染模式
 
(int) - initSpatializer
 初始化引擎 3D 音效算法
 
(int) - enableSpatializer:applyToTeam:
 开启或关闭空间音效
 
(int) - setSubscribeAudioBlocklist:uidArray:
 您可以调用该方法指定不订阅的音频流。
 
(int) - setSubscribeAudioAllowlist:
 您可以调用该方法指定只订阅的音频流。
 
(int) - takeLocalSnapshot:callback:
 本地视频画面截图。
调用 takeLocalSnapshot 截取本地主流或本地辅流的视频画面,并通过 NERtcTakeSnapshotCallback 的回调返回截图画面的数据。
 
(int) - takeRemoteSnapshot:forUserID:callback:
 远端视频画面截图。
调用 takeRemoteSnapshot 截取指定 uid 远端主流和远端辅流的视频画面,并通过 NERtcTakeSnapshotCallback 的回调返回截图画面的数据。
 
(int) - sendSEIMsg:streamChannelType:
 指定主流或辅流通道发送媒体增强补充信息(SEI)。
在本端推流传输音视频流数据同时,发送流媒体补充增强信息来同步一些其他附加信息。当推流方发送 SEI 后,拉流方可通过监听 onRecvSEIMsg 的回调获取 SEI 内容。
 
(int) - sendSEIMsg:
 通过主流通道发送媒体增强补充信息(SEI)。
在本端推流传输音视频流数据同时,发送流媒体补充增强信息来同步一些其他附加信息。当推流方发送 SEI 后,拉流方可通过监听 onRecvSEIMsg 的回调获取 SEI 内容。
 
(int) - addLiveStreamTask:compeltion:
 添加房间内推流任务。 通过此接口可以实现增加一路旁路推流任务;若需推送多路流,则需多次调用该方法。
 
(int) - updateLiveStreamTask:compeltion:
 更新房间内指定推流任务。 通过此接口可以实现调整指定推流任务的编码参数、画布布局、推流模式等。
 
(int) - removeLiveStreamTask:compeltion:
 删除房间内指定推流任务。
 
(int) - addChannelMediaStatsObserver:
 注册媒体统计信息观测器。
 
(int) - removeChannelMediaStatsObserver:
 移除指定媒体统计信息观测器。
 
(int) - cleanupChannelMediaStatsObserver
 清除全部媒体统计信息观测器。
 
(int) - startChannelMediaRelay:
 开始跨房间媒体流转发。
 
(int) - updateChannelMediaRelay:
 更新媒体流转发的目标房间。
成功开始跨房间转发媒体流后,如果您希望将流转发到多个目标房间,或退出当前的转发房间,可以调用该方法。
 
(int) - stopChannelMediaRelay
 停止跨房间媒体流转发。
通常在主播离开房间时,跨房间媒体流转发会自动停止;您也可以根据需要随时调用该方法,此时主播会退出所有目标房间。
 
(int) - setLocalMediaPriority:preemptive:
 设置本地用户的媒体流优先级。
通过此接口可以实现设置某用户的媒体流优先级为高,从而弱网环境下 SDK 会优先保证其他用户收到的该用户媒体流的质量。
 
(int) - setLocalPublishFallbackOption:
 设置弱网条件下发布的音视频流回退选项。
在网络不理想的环境下,发布的音视频质量都会下降。使用该接口并将 option 设置为 kNERtcStreamFallbackOptionAudioOnly 后:
 
(int) - setRemoteSubscribeFallbackOption:
 设置弱网条件下订阅的音视频流回退选项。
弱网环境下,订阅的音视频质量会下降。通过该接口设置订阅音视频流的回退选项后:
 
(int) - updatePermissionKey:
 更新权限密钥。
 
(int) - reportCustomEvent:customIdentify:param:
 上报自定义事件
 

详细描述

INERtcChannel 类在指定房间中实现实时音视频功能。通过创建多个 NERtcChannel 对象,用户可以同时加入多个房间。

自从
V4.5.0

函数文档

◆ addChannelMediaStatsObserver:

- (int) addChannelMediaStatsObserver: (id< NERtcChannelMediaStatsObserver >) observer

注册媒体统计信息观测器。

自从
V4.5.0
参数
observer统计信息观测器。详细信息请参考 NERtcChannelMediaStatsObserver
返回
操作返回值,成功则返回 0

◆ addLiveStreamTask:compeltion:

- (int) addLiveStreamTask: (NERtcLiveStreamTaskInfo *) taskInfo
compeltion: (NERtcLiveStreamCompletion) completion 

添加房间内推流任务。 通过此接口可以实现增加一路旁路推流任务;若需推送多路流,则需多次调用该方法。

自从
V3.5.0
使用前提
请先通过 INERtcEngine#setChannelProfile: 接口设置房间模式为直播模式。
调用时机
请在引擎初始化之后调用此接口,且该方法仅可在加入房间后调用。
注解
  • 仅角色为主播的房间成员能调用此接口,观众成员无相关推流权限。
  • 同一个音视频房间(即同一个 channelId)可以创建 6 个不同的推流任务。
参数说明
参数名称 类型 描述
taskInfo NERtcLiveStreamTaskInfo * 推流任务信息。详细信息请参考 {@ NERtcLiveStreamTaskInfo}。
compeltion NERtcLiveStreamCompletion 操作结果回调,方法调用成功后会触发对应的 NERtcEngineLiveStreamObserver#onNERTCEngineLiveStreamState:taskID:url: 回调。
示例代码
//info 的具体参数参考 NERtcLiveStreamTaskInfo 的定义
[channel addLiveStreamTask:info compeltion:^(NSString * _Nonnull taskId, kNERtcLiveStreamError errorCode){
}];
kNERtcLiveStreamError
LiveStream Error Code。 Will be deprecated, please use NERtcError instead
Definition NERtcEngineErrorCode.h:879
直播推流任务的配置。
Definition NERtcEngineBase.h:1308
相关回调
调用此接口成功后会触发 NERtcEngineLiveStreamObserver#onNERTCEngineLiveStreamState:taskID:url: 回调,通知推流任务状态已更新。
返回
  • 0(kNERtcNoError):方法调用成功;
  • 其他:方法调用失败。
    • 403(kNERtcErrChannelReservePermissionDenied):权限不足,观众模式下不支持此操作。
    • 30003(kNERtcErrInvalidParam): 参数错误,比如推流任务 ID 参数为空。
    • 30005(kNERtcErrInvalidState):状态错误,比如引擎尚未初始化。

◆ adjustChannelPlaybackSignalVolume:

- (int) adjustChannelPlaybackSignalVolume: (uint32_t) volume

调节本地播放的指定房间的所有远端用户的信号音量。
通过此接口可以实现在通话过程中随时调节指定房间内的所有远端用户在本地播放的混音音量。

自从
V4.6.50
调用时机
请在引擎初始化之后调用此接口,该方法可在加入房间前后调用。
注解
  • 该方法设置内部引擎为启用状态,在 leaveChannel 后失效,但在本次通话过程中有效
参数说明
参数名称 类型 描述
volume uint64_t 播放音量,取值范围为 [0,400]。
  • 0:静音。
  • 100:原始音量。
  • 400:最大可为原始音量的 4 倍(自带溢出保护)。
示例代码
//调整该房间内的的用户在本地的播放音量为 50
[channel adjustChannelPlaybackSignalVolume:50];
//调整该房间内的用户在本地的播放音量为 0,静音该房间
[channel adjustChannelPlaybackSignalVolume:0];
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30001(kNERtcErrFatal):状态错误,比如引擎未初始化。

◆ adjustUserPlaybackSignalVolume:forUserID:

- (int) adjustUserPlaybackSignalVolume: (uint32_t) volume
forUserID: (uint64_t) userID 

调节本地播放的指定远端用户的信号音量。
通过此接口可以实现在通话过程中随时调节指定远端用户在本地播放的混音音量。

自从
V4.2.1
调用时机
请在引擎初始化之后调用此接口,且该方法仅可在加入房间后调用。
注解
  • 该方法设置内部引擎为启用状态,在 leaveChannel 后失效,但在本次通话过程中有效,比如指定远端用户中途退出房间,则再次加入此房间时仍旧维持该设置。
  • 该方法每次只能调整一位远端用户的播放音量,若需调整多位远端用户在本地播放的音量,则需多次调用该方法。
参数说明
参数名称 类型 描述
userID uint64_t 远端用户 ID。
volume uint64_t 播放音量,取值范围为 0 ~ 400。
  • 0:静音。
  • 100(默认):原始音量。
  • 400:最大音量值(自带溢出保护)。
示例代码
//调整 uid 为 12345 的用户在本地的播放音量为 50
[channel adjustUserPlaybackSignalVolume:50 forUserID:12345];
//调整 uid 为 12345 的用户在本地的播放音量为 0,静音该用户
[channel adjustUserPlaybackSignalVolume:0 forUserID:12345];
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30001(kNERtcErrFatal):状态错误,比如引擎未初始化。

◆ cleanupChannelMediaStatsObserver

- (int) cleanupChannelMediaStatsObserver

清除全部媒体统计信息观测器。

自从
V4.5.0
返回
操作返回值,成功则返回 0

◆ connectionState

- (NERtcConnectionStateType) connectionState

获取当前房间连接状态。

自从
V4.5.0
返回
当前房间连接状态。

◆ destroy

- (int) destroy

自从
V4.5.0 销毁 IRtcChannel 实例,释放资源。

◆ enableAudioVolumeIndication:interval:vad:

- (int) enableAudioVolumeIndication: (BOOL) enable
interval: (uint64_t) interval
vad: (BOOL) enableVad 

启用说话者音量提示。
该方法允许 SDK 定期向 App 反馈本地发流用户和瞬时音量最高的远端用户(最多 3 位)的音量相关信息,即当前谁在说话以及说话者的音量。
启用该方法后,只要房间内有发流用户,无论是否有人说话,SDK 都会在加入房间后根据预设的时间间隔触发 NERtcEngineDelegateEx#onRemoteAudioVolumeIndication:totalVolume: 回调。

自从
V4.6.10
参数
enable是否启用说话者音量提示。
  • YES:启用说话者音量提示。
  • NO:关闭说话者音量提示。
interval指定音量提示的时间间隔。单位为毫秒。必须设置为 100 毫秒的整数倍值,建议设置为 200 毫秒以上。
enableVad是否启用本地采集人声监测。
  • YES:启用本地采集人声监测。
  • NO:关闭本地采集人声监测。
返回
  • 0:方法调用成功。
  • 其他:方法调用失败。

◆ enableDualStreamMode:

- (int) enableDualStreamMode: (BOOL) enable

设置是否开启视频大小流模式。
通过本接口可以实现设置单流或者双流模式。发送端开启双流模式后,接收端可以选择接收大流还是小流。其中,大流指高分辨率、高码率的视频流,小流指低分辨率、低码率的视频流。

自从
V3.5.0
调用时机
请在初始化后调用该方法,且该方法在加入房间前后均可调用。
注解
  • 纯音频 SDK 禁用该接口,如需使用请前往云信官网下载并替换成视频 SDK。
  • 该方法只对摄像头数据生效,对自定义输入、屏幕共享等视频流无效。
  • 该接口的设置会在摄像头重启后生效。
参数说明
参数名称 类型 描述
enable BOOL 是否开启双流模式:
  • YES:开启双流模式。
  • NO:关闭双流模式。
示例代码
[channel enableDualStreamMode:YES];
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30004(kNERtcErrNotSupported):不支持的操作,比如当前使用的是纯音频 SDK。
    • 30005(kNERtcErrInvalidState):当前状态不支持的操作,比如引擎尚未初始化。

◆ enableLocalAudio:

- (int) enableLocalAudio: (BOOL) enabled

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

自从
V3.5.0
调用时机
请在引擎初始化之后调用此接口,且该方法在加入房间前后均可调用。
注解
  • 加入房间后,语音功能默认为开启状态。
  • 该方法设置内部引擎为启用状态,在 leaveChannel 后仍然有效。
  • 该方法不影响接收或播放远端音频流,enableLocalAudio(false) 适用于只下行不上行音频流的场景。
  • 自 V4.4.0 版本起,开启或关闭本地音频采集的操作不会影响伴音/音效接口的使用,比如 enableLocalAudio(NO) 后仍可以调用 INERtcEngineEx#startAudioMixingWithOption: 方法播放音乐文件。
  • 该方法会操作音频硬件设备,建议避免频繁开关,否则可能导致设备异常。
参数说明
参数名称 类型 描述
enabled BOOL 是否启用本地音频的采集和发送:
  • YES:开启本地音频采集。
  • NO:关闭本地音频采集。关闭后,远端用户会接收不到本地用户的音频流;但本地用户依然可以接收到远端用户的音频流。

示例代码
//打开音频采集
[channel enableLocalAudio:YES];
//关闭音频采集
[channel enableLocalAudio:NO];
相关回调
相关接口
INERtcChannel#muteLocalAudio::两者的差异在于,enableLocalAudio 用于开启本地语音采集及处理,而 muteLocalAudio 用于停止或继续发送本地音频流。
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30001(kNERtcErrFatal):引擎尚未初始化。
    • 30004(kNERtcErrNotSupported):多房间场景下,在其他房间内已经开启了音频。
    • 30005(kNERtcErrInvalidState):状态错误,比如引擎尚未初始化,或者正在进行网络测速。
    • 30101(kNERtcErrChannelNotJoined):尚未加入房间。
    • 30300(kNERtcErrOSAuthorize):未开启麦克风权限。

◆ enableLocalSubStreamAudio:

- (int) enableLocalSubStreamAudio: (BOOL) enabled

开启或关闭音频辅流。
开启时远端会收到 NERtcChannelDelegate#onNERtcChannelUserSubStreamAudioDidStart: 回调,关闭时远端会收到 NERtcChannelDelegate#onNERtcChannelUserSubStreamAudioDidStop: 回调。

自从
V4.6.10
参数
enabled是否开启音频辅流。
  • YES:开启音频辅流。
  • NO:关闭音频辅流。
返回
  • 0 :方法调用成功。
  • 其他:方法调用失败。

◆ enableLocalVideo:

- (int) enableLocalVideo: (BOOL) enabled

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

自从
V3.5.0
调用时机
请在初始化后调用该方法,且该方法在加入房间前后均可调用。
注解
该方法设置内部引擎为开启或关闭状态, 在 INERtcChannel#leaveChannel 后仍然有效。
参数说明
参数名称 类型 描述
enabled BOOL 是否开启本地视频采集与发送:
  • YES:开启本地视频采集。
  • NO:关闭本地视频采集。关闭后,远端用户无法接收到本地用户的视频流;但本地用户仍然可以接收到远端用户的视频流。
示例代码
//打开视频
[channel enableLocalVideo:YES];
//关闭视频
[channel enableLocalVideo:NO];
相关回调
相关接口
若您希望开启辅流通道的视频采集,请调用 INERtcChannel#enableLocalVideo:streamType: 方法。
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30001(kNERtcErrFatal):通用错误,一般表示引擎错误,尝试再次调用此接口即可。
    • 30005(kNERtcErrInvalidState):当前状态不支持的操作,比如已开启外部视频采集。
    • 30300(kNERtcErrOSAuthorize):应用未获取到操作系统的摄像头权限。

◆ enableLocalVideo:streamType:

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

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

自从
V4.6.20
调用时机
请在初始化后调用该方法,且该方法在加入房间前后均可调用。
注解
该方法设置内部引擎为开启或关闭状态, 在 INERtcEngine#leaveChannel 后仍然有效。
参数说明
参数名称 类型 描述
streamType NERtcStreamChannelType 视频通道类型:
  • kNERtcStreamChannelTypeMainStream:主流。
  • kNERtcStreamChannelTypeSubStream:辅流。
enabled BOOL 是否开启本地视频采集与发送:
  • YES:开启本地视频采集。
  • NO:关闭本地视频采集。关闭后,远端用户无法接收到本地用户的视频流;但本地用户仍然可以接收到远端用户的视频流。
示例代码
//打开视频主流
[channel enableLocalVideo:YES streamType:kNERtcStreamChannelTypeMainStream];
//关闭视频主流
[channel enableLocalVideo:NO streamType:kNERtcStreamChannelTypeMainStream];
//打开视频辅流
[channel enableLocalVideo:YES streamType:kNERtcStreamChannelTypeSubStream];
//关闭视频辅流
[channel enableLocalVideo:NO streamType:kNERtcStreamChannelTypeSubStream];
@ kNERtcStreamChannelTypeMainStream
主流通道。
Definition NERtcEngineEnum.h:1072
@ kNERtcStreamChannelTypeSubStream
辅流通道。
Definition NERtcEngineEnum.h:1081
相关回调
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30001(kNERtcErrFatal):通用错误,一般表示引擎错误,尝试再次调用此接口即可。
    • 30005(kNERtcErrInvalidState):当前状态不支持的操作,比如已开启外部视频采集。
    • 30027(kNERtcErrDeviceOccupied): 所选设备已被占用。比如已通过主流通道开启了摄像头,无法再通过辅流通道开启摄像头。
    • 30300(kNERtcErrOSAuthorize):应用未获取到操作系统的摄像头权限。

◆ enableMediaPub:withMediaType:

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

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

自从
V4.6.10
注解
相关接口
  • INERtcChannel#muteLocalAudio:
    • 在需要开启本地音频采集(监测本地用户音量)但不发送音频流的情况下,您也可以调用 muteLocalAudio(YES) 方法。
    • 两者的差异在于, muteLocalAudio(YES) 仍然保持与服务器的音频通道连接,而 enableMediaPub(NO) 表示断开此通道,因此若您的实际业务场景为多人并发的大房间,建议您调用 enableMediaPub 方法。
参数
enabled是否发布本地媒体流。
  • YES(默认):发布本地媒体流。
  • NO:不发布本地媒体流。
mediaType媒体发布类型,暂时仅支持音频。
返回
  • 0:方法调用成功。
  • 其他:方法调用失败。

◆ enableSpatializer:applyToTeam:

- (int) enableSpatializer: (BOOL) enabled
applyToTeam: (BOOL) applyToTeam 

开启或关闭空间音效

自从
V5.4.0
调用时机
请在引擎初始化后调用此接口,且该方法在加入房间前才可调用。
注解
开启空间音效后,通话结束时仍保留该开关状态,不重置。
参数
enabled是否打开 3D 音效算法功能,默认为关闭状态。
apply_to_team是否仅本小队开启 3D 音效。true: 仅仅和接收端同一个小队的人有 3D 音效;false: 接收到所有的语音都有 3d 音效
  • YES:: 开启空间音效
  • NO: 关闭空间音效
返回
  • 0: 方法调用成功
  • 其他: 调用失败

◆ enableSpatializerRoomEffects:

- (int) enableSpatializerRoomEffects: (BOOL) enabled

开启或关闭空间音效的房间混响效果

自从
V5.4.0
调用时机
请在引擎初始化后调用此接口,且该方法在加入房间前后均可调用。
注解
请先调用 enableSpatializer() 接口后,再调用本接口。
参数
enabled混响效果开关,默认值关闭
返回
  • 0: 方法调用成功
  • 其他: 调用失败

◆ getChannelName

- (NSString *) getChannelName

获取当前房间名。

自从
V4.5.0
返回
  • 成功:当前 IRtcChannel 房间名。
  • 失败:返回空。

◆ initSpatializer

- (int) initSpatializer

初始化引擎 3D 音效算法

注解
此接口在加入房间前调用,退出房间后不重置
返回
  • 0: 方法调用成功
  • 其他: 调用失败

◆ joinChannelWithToken:completion:

- (int) joinChannelWithToken: (NSString *) token
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 将无法进入房间。推荐使用安全模式。
completion NERtcJoinChannelCompletion 操作完成的 block 回调。
示例代码
NERtcChannel *channel = [NERtcEngine sharedEngine] createChannel:@"secondChannel"];
int result = [channel joinChannelWithToken:token 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
Definition NERtcChannel.h:14
NERtcEngine 类
Definition NERtcEngine.h:15
相关接口
相关回调
成功调用该方法加入房间后,远端会触发 NERtcEngineDelegate#onNERtcEngineUserDidJoinWithUserID:userName: 回调。
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30005(kNERtcErrInvalidState):状态错误,比如引擎尚未初始化或正在进行网络探测。

◆ joinChannelWithToken:myUid:channelOptions:completion:

- (int) joinChannelWithToken: (NSString *) token
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 将无法进入房间。推荐使用安全模式。
channelOptions NERtcJoinChannelOptions * 加入房间时设置一些特定的房间参数。默认值为 NULL,详细信息请参考 NERtcJoinChannelOptions
completion NERtcJoinChannelCompletion 操作完成的 block 回调。
示例代码
NERtcChannel *channel = [NERtcEngine sharedEngine] createChannel:@"secondChannel"];
int result = [channel joinChannelWithToken:token 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):状态错误,比如引擎尚未初始化或正在进行网络探测。

◆ joinChannelWithToken:myUid:completion:

- (int) joinChannelWithToken: (NSString *) token
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 将无法进入房间。推荐使用安全模式。
uId uint64_t 用户的唯一标识 ID。
completion NERtcJoinChannelCompletion 操作完成的 block 回调。
示例代码
NERtcChannel *channel = [NERtcEngine sharedEngine] createChannel:@"secondChannel"];
int result = [channel joinChannelWithToken:token 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
调用时机
请在初始化并成功加入房间后调用该方法。
注解
结束通话时必须调用此方法离开房间,否则无法开始下一次通话。
示例代码
[channel leaveChannel];
int leaveChannel()
离开音视频房间。 通过本接口可以实现挂断或退出通话,并释放本房间内的相关资源。
相关回调
成功调用该方法离开房间后,本地会触发 NERtcEngineDelegate#onNERtcEngineDidLeaveChannelWithResult: 回调,远端会触发 NERtcEngineDelegate#onNERtcEngineUserDidLeaveWithUserID:reason: 回调。
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30001(kNERtcErrFatal):引擎尚未初始化。
    • 30005(kNERtcErrInvalidState):状态错误,比如正在进行网络探测。

◆ muteLocalAudio:

- (int) muteLocalAudio: (BOOL) muted

开启或关闭本地音频主流的发送。
该方法用于向网络发送或取消发送本地音频数据,不影响本地音频的采集状态,也不影响接收或播放远端音频流。

自从
V3.5.0
调用时机
请在引擎初始化之后调用此接口,且该方法在加入房间前后均可调用。
参数说明
参数名称 类型 描述
mute BOOL 是否关闭本地音频的发送:
  • YES:不发送本地音频。
  • NO:发送本地音频。
示例代码
//不发送本地音频
[channel muteLocalAudio:YES];
//发送本地音频
[channel muteLocalAudio:NO];
相关回调
若本地用户在说话,成功调用该方法后,房间内其他用户会收到 NERtcEngineDelegateEx#onNERtcEngineUser:audioMuted: 回调。
相关接口
INERtcChannel#enableMediaPub:withMediaType:
  • 在需要开启本地音频采集(监测本地用户音量)但不发送音频流的情况下,您也可以调用 enableMeidaPub(NO) 方法。
  • 两者的差异在于, muteLocalAudio(YES) 仍然保持与服务器的音频通道连接,而 enableMediaPub(NO) 表示断开此通道,因此若您的实际业务场景为多人并发的大房间,建议您调用 enableMediaPub 方法。
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30001(kNERtcErrFatal):引擎未初始化。

◆ muteLocalSubStreamAudio:

- (int) muteLocalSubStreamAudio: (BOOL) muted

静音或解除静音本地上行的音频辅流。

注解
静音状态会在通话结束后被重置为非静音。
自从
V4.6.10
参数
muted是否静音本地音频辅流发送。
  • YES(默认):静音本地音频辅流。
  • NO:取消静音本地音频辅流。
返回
  • 0:方法调用成功。
  • 其他:方法调用失败。

◆ muteLocalVideo:

- (int) muteLocalVideo: (BOOL) muted

取消或恢复发布本端视频主流。
调用该方法取消发布本地视频主流后,SDK 不再发送本地视频主流。

自从
V3.5.0
使用前提
一般在通过 INERtcChannel#enableLocalVideo:streamType: 接口开启本地视频采集并发送后调用该方法。
调用时机
请在初始化后调用该方法,且该方法在加入房间前后均可调用。
注解
  • 调用该方法取消发布本地视频流时,设备仍然处于工作状态。
  • 该方法设置内部引擎为启用状态,在 INERtcChannel#leaveChannel 后设置失效,将恢复至默认,即默认发布本地视频流。
  • 该方法与 INERtcChannel#enableLocalVideo:streamType:(NO) 的区别在于,后者会关闭本地摄像头设备,该方法不禁用摄像头,不会影响本地视频流采集且响应速度更快。
参数说明
参数名称 类型 描述
muted BOOL 是否取消发布本地视频流:
  • YES:取消发布本地视频流。
  • NO(默认):恢复发布本地视频流。
示例代码
[channel muteLocalVideo:YES];
相关回调
取消发布本地视频主流或辅流后,远端会收到 NERtcChannelDelegate#onNERtcChannelUser:videoMuted:streamType: 回调。
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30001(kNERtcErrFatal):状态错误,比如引擎尚未初始化。
    • 30004(kNERtcErrNotSupported):不支持的操作,比如当前使用的是纯音频 SDK。

◆ muteLocalVideo:streamType:

- (int) muteLocalVideo: (BOOL) muted
streamType: (NERtcStreamChannelType) streamType 

取消或恢复发布本地视频。
调用该方法取消发布本地视频主流或辅流后,SDK 不再发送本地视频流。

自从
V4.6.20
使用前提
一般在通过 INERtcEngine#enableLocalVideo:streamType: 接口开启本地视频采集并发送后调用该方法。
调用时机
请在初始化后调用该方法,且该方法在加入房间前后均可调用。
注解
  • 调用该方法取消发布本地视频流时,设备仍然处于工作状态。
  • 若调用该方法取消发布本地视频流,通话结束后会被重置为默认状态,即默认发布本地视频流。
  • 该方法与 INERtcEngine#enableLocalVideo:streamType:(NO) 的区别在于,后者会关闭本地摄像头设备,该方法不禁用摄像头,不会影响本地视频流采集且响应速度更快。
参数说明
参数名称 类型 描述
streamType NERtcStreamChannelType 视频通道类型:
  • kNERtcStreamChannelTypeMainStream:主流。
  • kNERtcStreamChannelTypeSubStream:辅流。
muted BOOL 是否取消发布本地视频流:
  • YES:取消发布本地视频流。
  • NO(默认):恢复发布本地视频流。
示例代码
//取消发布本地视频主流
[channel muteLocalVideo:YES streamType:kNERtcStreamChannelTypeMainStream];
//恢复发布本地视频主流
[channel muteLocalVideo:NO streamType:kNERtcStreamChannelTypeMainStream];
//取消发布本地视频辅流
[channel muteLocalVideo:YES streamType:kNERtcStreamChannelTypeSubStream];
//恢复发布本地视频辅流
[channel muteLocalVideo:NO streamType:kNERtcStreamChannelTypeSubStream];
相关回调
取消发布本地视频主流或辅流后,远端会收到 NERtcEngineDelegateEx#onNERtcEngineUser:videoMuted:streamType: 回调。
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30004(kNERtcErrNotSupported):不支持的操作,比如当前使用的是纯音频 SDK。

◆ pushExternalVideoFrame:streamType:

- (int) pushExternalVideoFrame: (NERtcVideoFrame *) frame
streamType: (NERtcStreamChannelType) streamType 

推送外部视频帧。
该方法主动将视频帧数据用 NERtcVideoFrame 类封装后传递给 SDK。

注解
  • 该方法设置内部引擎为启用状态,在 leaveChannel 后不再有效。
  • 请确保在您调用本方法前已调用 setExternalVideoSource,并将参数设为 YES,否则调用本方法后会一直报错。
  • 纯音频 SDK 禁用该接口,如需使用请前往云信官网下载并替换成视频 SDK。
参数
frame外部视频帧的数据信息。详细信息请参考 NERtcVideoFrame
streamType视频流通道类型,默认为主流 kNERtcStreamChannelTypeMainStream。
返回
  • 0:方法调用成功;
  • 其他:方法调用失败。

◆ removeChannelMediaStatsObserver:

- (int) removeChannelMediaStatsObserver: (id< NERtcChannelMediaStatsObserver >) observer

移除指定媒体统计信息观测器。

自从
V4.5.0
参数
observer统计信息观测器
返回
操作返回值,成功则返回 0

◆ removeLiveStreamTask:compeltion:

- (int) removeLiveStreamTask: (NSString *) taskId
compeltion: (NERtcLiveStreamCompletion) completion 

删除房间内指定推流任务。

自从
V3.5.0
使用前提
请先调用 INERtcChannel#addLiveStreamTask:compeltion: 方法添加推流任务。
调用时机
请在引擎初始化之后调用此接口,且该方法仅可在加入房间后调用。
注解
  • 仅角色为主播的房间成员能调用此接口,观众成员无相关推流权限。
  • 通话结束,房间成员全部离开房间后,推流任务会自动删除;如果房间内还有用户存在,则需要创建推流任务的用户删除推流任务。
参数说明
参数名称 类型 描述
taskId NSString * 推流任务 ID。
completion NERtcLiveStreamCompletion 操作结果回调,方法调用成功后会触发对应的 NERtcEngineLiveStreamObserver#onNERTCEngineLiveStreamState:taskID:url: 回调。
示例代码
[channel removeLiveStreamTask:task_id compeltion:^(NSString * _Nonnull taskId, kNERtcLiveStreamError errorCode){
}];
相关回调
调用此接口成功后会触发 NERtcEngineLiveStreamObserver#onNERTCEngineLiveStreamState:taskID:url: 回调,通知推流任务已删除。
返回
  • 0(kNERtcNoError):方法调用成功;
  • 其他:方法调用失败。
    • 403(kNERtcErrChannelReservePermissionDenied):权限不足,观众模式下不支持此操作。
    • 30003(kNERtcErrInvalidParam): 参数错误,比如推流任务 ID 参数为空。
    • 30005(kNERtcErrInvalidState):状态错误,比如引擎尚未初始化。

◆ reportCustomEvent:customIdentify:param:

- (int) reportCustomEvent: (NSString *) eventName
customIdentify: (NSString *) customIdentify
param: (NSDictionary *) param 

上报自定义事件

参数
eventName事件名 不能为空
customIdentify自定义标识,比如产品或业务类型,如不需要填 null
param参数键值对,参数值支持 String 及 java 基本类型(int 、bool....), 如不需要填 null
返回
操作返回值,成功则返回 0

◆ sendSEIMsg:

- (int) sendSEIMsg: (NSData *) data

通过主流通道发送媒体增强补充信息(SEI)。
在本端推流传输音视频流数据同时,发送流媒体补充增强信息来同步一些其他附加信息。当推流方发送 SEI 后,拉流方可通过监听 onRecvSEIMsg 的回调获取 SEI 内容。

  • 调用时机:视频流(主流、辅流)开启后,可调用此函数。
  • 数据长度限制: SEI 最大数据长度为 4096 字节,超限会发送失败。如果频繁发送大量数据会导致视频码率增大,可能会导致视频画质下降甚至卡顿。
  • 发送频率限制:最高为视频发送的帧率,建议不超过 10 次/秒。
  • 生效时间:调用本接口之后,最快在下一帧视频数据帧之后发送 SEI 数据,最慢在接下来的 5 帧视频之后发送。
注解
  • SEI 数据跟随视频帧发送,由于在弱网环境下可能丢帧,SEI 数据也可能随之丢失,所以建议在发送频率限制之内多次发送,保证接收端收到的概率。
  • 调用本接口时,默认使用主流通道发送 SEI。
  • 纯音频 SDK 禁用该接口,如需使用请前往云信官网下载并替换成视频 SDK。
自从
V4.5.0
参数
data自定义 SEI 数据。
返回
操作返回值,成功则返回 0。
  • 成功: 成功进入待发送队列,会在最近的视频帧之后发送该数据。
  • 失败: 数据被限制发送,可能发送的频率太高,队列已经满了,或者数据大小超过最大值 4k。

◆ sendSEIMsg:streamChannelType:

- (int) sendSEIMsg: (NSData *) data
streamChannelType: (NERtcStreamChannelType) type 

指定主流或辅流通道发送媒体增强补充信息(SEI)。
在本端推流传输音视频流数据同时,发送流媒体补充增强信息来同步一些其他附加信息。当推流方发送 SEI 后,拉流方可通过监听 onRecvSEIMsg 的回调获取 SEI 内容。

  • 调用时机:视频流(主流、辅流)开启后,可调用此函数。
  • 数据长度限制: SEI 最大数据长度为 4096 字节,超限会发送失败。如果频繁发送大量数据会导致视频码率增大,可能会导致视频画质下降甚至卡顿。
  • 发送频率限制:最高为视频发送的帧率,建议不超过 10 次/秒。
  • 生效时间:调用本接口之后,最快在下一帧视频数据帧之后发送 SEI 数据,最慢在接下来的 5 帧视频之后发送。
注解
  • SEI 数据跟随视频帧发送,由于在弱网环境下可能丢帧,SEI 数据也可能随之丢失,所以建议在发送频率限制之内多次发送,保证接收端收到的概率。
  • 指定通道发送 SEI 之前,需要提前开启对应的数据流通道。
  • 纯音频 SDK 禁用该接口,如需使用请前往云信官网下载并替换成视频 SDK。
自从
V4.5.0
参数
data自定义 SEI 数据。
type发送 SEI 时,使用的流通道类型。详细信息请参考 NERtcStreamChannelType
返回
操作返回值,成功则返回 0
  • 成功: 成功进入待发送队列,会在最近的视频帧之后发送该数据。
  • 失败: 数据被限制发送,可能发送的频率太高,队列已经满了,或者数据大小超过最大值 4k。

◆ setAudioRecvRange:conversationalDistance:rollOff:

- (int) setAudioRecvRange: (int) audibleDistance
conversationalDistance: (int) conversationalDistance
rollOff: (NERtcDistanceRolloffModel) rollOff 

引擎 3D 音效算法距离范围设置

注解
依赖 enableSpatializer:applyToTeam 接口开启,通话前调用
参数
audibleDistance监听器能够听到扬声器并接收其文本消息的距离扬声器的最大距离。[0,1000] 默认值为 32。
conversationalDistance控制扬声器音频保持其原始音量的范围,超出该范围时,语音聊天的响度在被听到时开始淡出。 默认值为 1。
rollOff:距离衰减模式#NERtcDistanceRolloffModel,默认值 kNERtcDistanceRolloffNone
返回
  • 0: 方法调用成功
  • 其他: 调用失败

◆ setAudioSubscribeOnlyBy:

- (int) setAudioSubscribeOnlyBy: (NSArray< NSNumber * > *) uidArray

设置自己的音频只能被房间内指定的人订阅。
默认房间所有其他人都可以订阅自己的音频。

注解
  • 此接口需要在加入房间成功后调用。
  • 对于调用接口时不在房间的 uid 不生效。
自从
V4.6.10
参数
uidArray可订阅自己音频的用户 uid 列表。
注解
此列表为全量列表。如果列表为空或 null,表示其他所有人均可订阅自己的音频。
返回
  • 0:方法调用成功。
  • 其他:方法调用失败。

◆ setCameraCaptureConfig:

- (int) setCameraCaptureConfig: (NERtcCameraCaptureConfiguration *) config

设置本地摄像头的视频主流采集配置。
通过此接口可以设置本地摄像头采集的主流视频宽度、高度、旋转角度等。

自从
V4.5.0
调用时机
请在初始化后调用该方法,且该方法在加入房间前后均可调用。
业务场景
在视频通话或直播中,SDK 自动控制摄像头的输出参数。默认情况下,SDK 会根据用户该接口的配置匹配最合适的分辨率进行采集。但是在部分业务场景中,如果采集画面质量无法满足实际需求,可以调用该接口调整摄像头的采集配置。
注解
  • 纯音频 SDK 禁用该接口,如需使用请前往云信官网下载并替换成视频 SDK。
  • 该方法仅适用于视频主流,若您希望为辅流通道设置摄像头的采集配置,请调用 INERtcChannel#setCameraCaptureConfig:streamType: 方法。
  • 该方法支持在加入房间后动态调用,设置成功后,会自动重启摄像头采集模块。
  • 若系统相机不支持您设置的分辨率,会自动调整为最相近一档的分辨率,因此建议您设置为常规标准的分辨率。
  • 设置较高的采集分辨率会增加性能消耗,例如 CPU 和内存占用等,尤其是在开启视频前处理的场景下。
参数说明
参数名称 类型 描述
config NERtcCameraCaptureConfiguration 本地摄像头采集配置。
示例代码
config.captureWidth = 1280;
config.captureHeight = 720;
[channel setCameraCaptureConfig:config];
摄像头采集配置。
Definition NERtcEngineBase.h:488
int captureWidth
本地采集的视频宽度,单位为 px。 视频编码分辨率以宽 x 高表示,用于设置视频编码分辨率,以衡量编码质量。
Definition NERtcEngineBase.h:509
int captureHeight
本地采集的视频高度,单位为 px。 视频编码分辨率以宽 x 高表示,用于设置视频编码分辨率,以衡量编码质量。
Definition NERtcEngineBase.h:530
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30003(kNERtcErrInvalidParam):参数错误,比如 config 设置为空。
    • 30004(kNERtcErrNotSupported):不支持的操作,比如当前使用的是纯音频 SDK。
    • 30005(kNERtcErrInvalidState):当前状态不支持的操作,比如引擎未初始化成功。

◆ setCameraCaptureConfig:streamType:

设置本地摄像头的视频主流或辅流采集配置。
通过此接口可以设置本地摄像头采集的主流或辅流视频宽度、高度、旋转角度等。

自从
V4.6.20
调用时机
请在初始化后调用该方法,且该方法在加入房间前后均可调用。
业务场景
在视频通话或直播中,SDK 自动控制摄像头的输出参数。默认情况下,SDK 会根据用户该接口的配置匹配最合适的分辨率进行采集。但是在部分业务场景中,如果采集画面质量无法满足实际需求,可以调用该接口调整摄像头的采集配置。
注解
调用该接口设置成功后,会自动重启摄像头采集模块。
参数说明
参数名称 类型 描述
config NERtcCameraCaptureConfiguration 本地摄像头采集配置。
streamType NERtcStreamChannelType 视频通道类型:
  • kNERtcStreamChannelTypeMainStream:主流。
  • kNERtcStreamChannelTypeSubStream:辅流。
示例代码
//设置本地摄像头主流采集配置
capConfig.captureWidth = 1280;
capConfig.captureHeight = 720;
[channel setCameraCaptureConfig:capConfig streamType:kNERtcStreamChannelTypeMainStream];
//设置本地摄像头辅流采集配置
subCapConfig.captureWidth = 1280;
subCapConfig.captureHeight = 720;
[channel setCameraCaptureConfig:subCapConfig streamType:kNERtcStreamChannelTypeSubStream];
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30003(kNERtcErrInvalidParam):参数错误,比如 config 设置为空。
    • 30004(kNERtcErrNotSupported):不支持的操作,比如当前使用的是纯音频 SDK。
    • 30005(kNERtcErrInvalidState):当前状态不支持的操作,比如引擎未初始化成功。

◆ setChannelDelegate:

- (int) setChannelDelegate: (nullable id< NERtcChannelDelegate >) channelDelegate

设置 channel 的回调。

自从
V4.5.0
参数
channelDelegatechannel 的回调对象。
返回
操作返回值,成功则返回 0

◆ setClientRole:

- (int) setClientRole: (NERtcClientRole) role

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

自从
V3.9.0
使用前提
该方法仅在通过 INERtcEngine#setChannelProfile: 方法设置房间场景为直播场景(kNERtcChannelProfileLiveBroadcasting )时调用有效。
调用时机
请在初始化后调用该方法,且该方法在加入房间前后均可调用。
业务场景
适用于观众上下麦与主播互动的互动直播场景。
注解
用户切换为观众角色时,SDK 会自动关闭音视频设备。
参数说明
参数名称 类型 描述
role NERtcClientRole 用户角色:
  • kNERtcClientRoleBroadcaster(0):设置用户角色为主播。主播可以开关摄像头等设备、可以发布流、可以操作互动直播推流相关接口、加入或退出房间状态对其他房间内用户可见。
  • kNERtcClientRoleAudience(1):设置用户角色为观众。观众只能收流不能发流、加入或退出房间状态对其他房间内用户不可见。
示例代码
//切换用户角色为主播
[channel setClientRole:kNERtcClientRoleAudience];
//切换用户角色为观众
[channel setClientRole:kNERtcClientRoleBroadcaster];
@ kNERtcClientRoleBroadcaster
(默认)直播模式中的主播,可以操作摄像头等音视频设备、发布流、配置互动直播推流任务、上下线对房间内其他用户可见。
Definition NERtcEngineEnum.h:215
@ kNERtcClientRoleAudience
直播模式中的观众,观众只能接收音视频流,不支持操作音视频设备、配置互动直播推流任务、上下线不通知其他用户。
Definition NERtcEngineEnum.h:224
相关回调
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30001(kNERtcErrFatal):引擎未创建成功。

◆ setDelegateQueue:

- (int) setDelegateQueue: (nullable dispatch_queue_t) delegateQueue

设置驱动 NERtcChannelDelegate 事件回调队列

自从
V5.5.10
调用时机
请在引擎初始化后调用此接口,且该方法在加入房间前后均可调用。
注解
  • 如果您不指定自己的 delegateQueue 或者设置为 NULL, 默认会采用 MainQueue 作为驱动 NERtcCallback 事件回调的队列。
  • 如果您指定了自己的 delegateQueue,请不要直接 NERtcEngineDelegateEx 回调函数中操作 UI,会引发线程安全问题。且需要考虑线程的生命周期,如果线程提前终止,将无法收到 NERtcChannelDelegate 的回调。

◆ setExternalVideoSource:streamType:

- (int) setExternalVideoSource: (BOOL) enable
streamType: (NERtcStreamChannelType) streamType 

开启或关闭外部视频源数据输入。
通过本接口可以实现创建自定义的外部视频源,您可以选择通过主流或辅流通道传输该外部视频源的数据,但暂不支持同时开启。

自从
V4.6.20
使用前提
请在通过 INERtcEngineEx#startPreview: 接口开启本地视频预览、通过 INERtcEngine#enableLocalVideo:streamType: 接口开启本地视频采集或通过 INERtcEngineEx#startScreenCapture: 接口开启屏幕共享之前调用该方法,且必须使用同一种视频通道,即同为主流或辅流。
调用时机
请在初始化后调用该方法,且该方法在加入房间前后均可调用。
业务场景
实现由应用层而非 SDK 采集视频数据,适用于对输入的视频数据做水印、美颜、马赛克等前处理的场景。
注解
  • 纯音频 SDK 禁用该接口,如需使用请前往云信官网下载并替换成视频 SDK。
  • 该方法设置开启主流外部视频源输入时,内部引擎为启用状态,在切换房间(switchChannelWithToken)、主动离开房间(leaveChannel)、触发断网重连失败回调(onNERtcChannelDidDisconnectWithReason)或触发重新加入房间回调(onNERtcChannelRejoinChannel)后仍然有效。如果需要关闭该功能,请在下次通话前调用接口关闭该功能。
  • 该方法设置开启辅流外部视频源输入时,在切换房间或触发重新加入房间回调后仍然有效;但在主动离开房间或触发断网重连失败回调后,该接口设置失效,将恢复至默认。
  • 请务必保证视频主流和辅流输入通道各最多只能有一种视频输入源,其中屏幕共享只能通过辅流通道开启,因此:
    • 若您开启了辅流形式的屏幕共享,请使用主流通道输入外部视频源数据,即设置 streamType 参数为 kNERtcStreamChannelTypeMainStream。
    • 若您已调用 INERtcEngine#enableLocalVideo:streamType: 方法开启本地主流视频采集,请勿再调用此接口创建主流形式的外部视频源输入,辅流通道同理。
参数说明
参数名称 类型 描述
streamType NERtcStreamChannelType 视频通道类型:
  • kNERtcStreamChannelTypeMainStream:主流。
  • kNERtcStreamChannelTypeSubStream:辅流。
enable BOOL 是否使用外部视频源:
  • YES:开启。
  • NO(默认):关闭。
示例代码
//通过主流通道输入外部视频源数据
[channel setExternalVideoSource:YES streamType:kNERtcStreamChannelTypeMainStream];
[channel enableLocalVideo:YES streamType:kNERtcStreamChannelTypeMainStream];
[channel pushExternalVideoFrame:frame];
//通过辅流通道输入外部视频源数据
[channel setExternalVideoSource:YES streamType:kNERtcStreamChannelTypeSubStream];
[channel startScreenCapture:config];
//屏幕共享视频帧回调,此方法来自屏幕共享的 framework NERtcReplayKit.framework
- (void)onReceiveVideoFrame:(NEScreenShareVideoFrame *)videoFrame
{
NERtcVideoFrame *frame = [[NERtcVideoFrame alloc] init];
frame.width = videoFrame.width;
frame.height = videoFrame.height;
frame.buffer = (void *)[videoFrame.videoData bytes];
frame.timestamp = videoFrame.timeStamp;
frame.rotation = rotation;
channel pushExternalVideoFrame:frame];
}
@ kNERtcVideoFormatI420
I420 视频格式。
Definition NERtcEngineEnum.h:1034
@ kNERtcVideoProfileHD720P
HD (1280 x 720 @ 30 fps)
Definition NERtcEngineEnum.h:451
@ kNERtcVideoFrameRateFps15
15 fps.
Definition NERtcEngineEnum.h:518
NERtcVideoFrameRate frameRate
视频编码的帧率。详细信息请参考 NERtcVideoFrameRate。
Definition NERtcEngineBase.h:392
NERtcVideoProfileType maxProfile
视频编码的分辨率,用于衡量编码质量。详细信息请参考 NERtcVideoProfileType。
Definition NERtcEngineBase.h:374
视频帧信息。
Definition NERtcEngineBase.h:1607
NERtcVideoRotationType rotation
视频顺时针旋转角度。详细信息请参考 NERtcVideoRotationType。
Definition NERtcEngineBase.h:1657
uint32_t width
视频高,即视频帧在横轴上的像素。
Definition NERtcEngineBase.h:1637
NERtcVideoFormatType format
视频帧格式,详细信息请参考 NERtcVideoFormatType。 视频外部渲染场景下,仅支持 kNERtcVideoFormatI420。
Definition NERtcEngineBase.h:1617
uint64_t timestamp
视频时间戳,单位为毫秒。
Definition NERtcEngineBase.h:1627
void * buffer
视频数据指针。 视频外部输入场景下,按照不同的格式,可支持 CVPixelBuffer、NSData 的 bytes; 对于 I420 格式,代表 Y 分量的指针; 对于 NV12 和 BGRA 格式,...
Definition NERtcEngineBase.h:1671
uint32_t height
视频宽,即视频帧在纵轴上的像素。
Definition NERtcEngineBase.h:1647
本地辅流发送配置。
Definition NERtcEngineBase.h:648
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30001(kNERtcErrFatal):通用错误,比如已通过主流通道开启本地视频采集,又创建了主流通道的外部视频源。
    • 30004(kNERtcErrNotSupported):不支持的操作,比如当前使用的是纯音频 SDK。

◆ setLocalMediaPriority:preemptive:

- (int) setLocalMediaPriority: (NERtcMediaPriorityType) priority
preemptive: (BOOL) preemptive 

设置本地用户的媒体流优先级。
通过此接口可以实现设置某用户的媒体流优先级为高,从而弱网环境下 SDK 会优先保证其他用户收到的该用户媒体流的质量。

自从
V4.2.0
调用时机
请在引擎初始化之后调用此接口,且该方法仅可在加入房间前调用。
注解
  • 一个音视频房间中只有一个高优先级的用户。建议房间中只有一位用户调用 setLocalMediaPriority 将本端媒体流设为高优先级,否则需要开启抢占模式,保证本地用户的高优先级设置生效。
  • 调用 INERtcEngine#switchChannelWithToken:channelName:channelOptions:completion: 方法快速切换房间后,媒体优先级会恢复为默认值,即普通优先级。
参数说明
参数名称 类型 描述
priority NERtcMediaPriorityType 本地用户的媒体流优先级,默认为 kNERtcMediaPriorityNormal,即普通优先级。
preemptive BOOL 是否开启抢占模式:
  • YES:开启抢占模式。抢占模式开启时,本地用户可以抢占其他用户的高优先级,被抢占的用户的媒体优先级变为普通优先级,在抢占者退出房间后,其他用户的优先级仍旧维持普通优先级。
  • NO:关闭抢占模式。抢占模式关闭时,如果房间中已有高优先级用户,则本地用户的高优先级设置不生效,仍旧为普通优先级。
示例代码
[channel setLocalMediaPriority:kNERtcMediaPriorityHigh preemptive:YES];
@ kNERtcMediaPriorityHigh
高优先级。
Definition NERtcEngineEnum.h:1971
返回
  • 0(kNERtcNoError):方法调用成功。

◆ setLocalPublishFallbackOption:

- (int) setLocalPublishFallbackOption: (NERtcStreamFallbackOptions) option

设置弱网条件下发布的音视频流回退选项。
在网络不理想的环境下,发布的音视频质量都会下降。使用该接口并将 option 设置为 kNERtcStreamFallbackOptionAudioOnly 后:

  • SDK 会在上行弱网且音视频质量严重受影响时,自动关断视频流,尽量保证音频质量。
  • 同时 SDK 会持续监控网络质量,并在网络质量改善时恢复音视频流。
  • 当本地发布的音视频流回退为音频流时,或由音频流恢复为音视频流时,SDK 会触发本地发布的媒体流已回退为音频流 onLocalPublishFallbackToAudioOnly 回调。
注解
请在加入房间(joinChannel)前调用此方法。
自从
V4.5.0
参数
option发布音视频流的回退选项,默认为不开启回退。 详细信息请参考 NERtcStreamFallbackOptions
返回
操作返回值,成功则返回 0

◆ setLocalRenderScaleMode:

- (int) setLocalRenderScaleMode: (NERtcVideoRenderScaleMode) mode

设置画布中本地视频画面的显示模式。
通过本接口可以实现设置本地视频画面的适应性,即是否裁剪或缩放。

自从
V3.5.0
调用时机
请在初始化后调用该方法,且该方法仅可在加入房间后调用。
注解
纯音频 SDK 禁用该接口,如需使用请前往云信官网下载并替换成视频 SDK。
参数说明
参数名称 类型 描述
mode NERtcVideoRenderScaleMode 视频显示模式类型:
  • kNERtcVideoRenderScaleFit(0):适应视频,视频尺寸等比缩放。优先保证视频内容全部显示。若视频尺寸与显示视窗尺寸不一致,视窗未被填满的区域填充背景色。
  • kNERtcVideoRenderScaleFullFill(1):视频尺寸非等比缩放。保证视频内容全部显示,且填满视窗。
  • kNERtcVideoRenderScaleCropFill(2):适应区域,视频尺寸等比缩放。保证所有区域被填满,视频超出部分会被裁剪。
示例代码
[channel setLocalRenderScaleMode:kNERtcVideoRenderScaleFit];
@ kNERtcVideoRenderScaleFit
适应视频,视频尺寸等比缩放。优先保证视频内容全部显示。若视频尺寸与显示视窗尺寸不一致,视窗未被填满的区域填充背景色。
Definition NERtcEngineEnum.h:741
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30004(kNERtcErrNotSupported):不支持的操作,比如当前使用的是纯音频 SDK。
    • 30005(kNERtcErrInvalidState):当前状态不支持的操作,比如引擎尚未初始化。

◆ setLocalRenderSubStreamScaleMode:

- (int) setLocalRenderSubStreamScaleMode: (NERtcVideoRenderScaleMode) mode

设置画布中本地屏幕共享辅流视频画面的显示模式。
通过本接口可以实现设置本地发布的屏幕共享视频画面的适应性,即是否裁剪或缩放。

自从
V3.9.0
使用前提
请先调用 INERtcChannel#setupLocalSubStreamVideoCanvas: 方法设置本地辅流画布。
调用时机
请在初始化后调用该方法,且该方法仅可在加入房间后调用。
注解
纯音频 SDK 禁用该接口,如需使用请前往云信官网下载并替换成视频 SDK。
参数说明
参数名称 类型 描述
mode NERtcVideoRenderScaleMode 视频显示模式类型:
  • kNERtcVideoRenderScaleFit(0):适应视频,视频尺寸等比缩放。优先保证视频内容全部显示。若视频尺寸与显示视窗尺寸不一致,视窗未被填满的区域填充背景色。
  • kNERtcVideoRenderScaleFullFill(1):视频尺寸非等比缩放。保证视频内容全部显示,且填满视窗。
  • kNERtcVideoRenderScaleCropFill(2):适应区域,视频尺寸等比缩放。保证所有区域被填满,视频超出部分会被裁剪。
示例代码
[channel setLocalRenderSubStreamScaleMode:kNERtcVideoRenderScaleFit];
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30004(kNERtcErrNotSupported):不支持的操作,比如当前使用的是纯音频 SDK。
    • 30005(kNERtcErrInvalidState):当前状态不支持的操作,比如引擎尚未初始化。

◆ setLocalVideoConfig:

- (int) setLocalVideoConfig: (NERtcVideoEncodeConfiguration *) config

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

自从
V3.5.0
调用时机
请在初始化后调用该方法,且该方法在加入房间前后均可调用。
注解
  • 纯音频 SDK 禁用该接口,如需使用请前往云信官网下载并替换成视频 SDK。
  • 每个属性对应一套视频参数,例如分辨率、帧率、码率等。所有设置的参数均为理想情况下的最大值。当视频引擎因网络环境等原因无法达到设置的分辨率、帧率或码率的最大值时,会取最接近最大值的那个值。
  • 此接口为全量参数配置接口,重复调用此接口时,SDK 会刷新此前的所有参数配置,以最新的传参为准。所以每次修改配置时都需要设置所有参数,未设置的参数将取默认值。
  • 自 V4.5.0 版本起,此方法设置实时生效;此前的版本中,此方法设置成功后,下次开启本端视频时生效。
参数说明
参数名称 类型 描述
config NERtcVideoEncodeConfiguration 视频编码属性配置。
示例代码
//设置本地视频主流编码参数
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; ;//带宽受限时的视频编码降级偏好
[channel setLocalVideoConfig:config];
@ kNERtcVideoCropMode16_9
16:9
Definition NERtcEngineEnum.h:904
@ kNERtcDegradationDefault
(默认)根据场景模式调整适应性偏好。
Definition NERtcEngineEnum.h:581
@ kNERtcVideoFrameRateFps30
30 fps.
Definition NERtcEngineEnum.h:536
NSInteger bitrate
视频编码的码率,单位为 Kbps。 您可以根据场景需要,手动设置想要的码率。详细码表请参考 设置视频属性。
Definition NERtcEngineBase.h:465
NSInteger minFrameRate
视频编码的最小帧率。默认为 0,表示使用默认最小帧率。
Definition NERtcEngineBase.h:402
NSInteger minBitrate
视频编码的最小码率,单位为 Kbps。您可以根据场景需要,手动设置想要的最小码率,若设置为 0,SDK 将会自行计算处理。
Definition NERtcEngineBase.h:475
本地视频发送配置
Definition NERtcEngineBase.h:542
int width
视频编码分辨率,衡量编码质量,以宽 x 高表示。与 maxProfile 属性二选一。推荐优先使用自定义宽高设置。 width 表示视频帧在横轴上的像素,即自定义宽。
Definition NERtcEngineBase.h:559
NERtcVideoCropMode cropMode
视频画面裁剪模式,默认为 kNERtcVideoCropDefault。自定义视频输入不支持设置裁剪模式。
Definition NERtcEngineBase.h:587
NERtcDegradationPreference degradationPreference
带宽受限时的视频编码降级偏好。详细信息请参考 NERtcDegradationPreference。
Definition NERtcEngineBase.h:609
int height
视频编码分辨率,衡量编码质量,以宽 x 高表示。与 maxProfile 属性二选一。推荐优先使用自定义宽高设置。 height 表示视频帧在纵轴上的像素,即自定义高。
Definition NERtcEngineBase.h:577
相关接口
若您希望为视频辅流通道设置编码属性,请调用 INERtcChannel#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:辅流。
示例代码
//设置本地视频主流编码参数
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; //带宽受限时的视频编码降级偏好
[channel setLocalVideoConfig:config streamType:kNERtcStreamChannelTypeMainStream];
//设置本地视频辅流编码参数
subConfig.width = 640;
subConfig.height = 360;
subConfig.minFrameRate = mMinFrameRate;
subConfig.bitrate = mBitrate;
subConfig.minBitrate = mMinBitrate;
[channel setLocalVideoConfig:subConfig streamType:kNERtcStreamChannelTypeSubStream];
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30003(kNERtcErrInvalidParam):参数错误,比如 config 设置为空。
    • 30004(kNERtcErrNotSupported):不支持的操作,比如当前使用的是纯音频 SDK。
    • 30005(kNERtcErrInvalidState):当前状态不支持的操作,比如引擎未初始化成功。

◆ setRangeAudioMode:

- (int) setRangeAudioMode: (NERtcRangeAudioMode) mode

设置范围语音模式

注解
此接口在加入房间前后均可调用。
参数
[in]mode范围语音模式
返回
  • 0: 方法调用成功
  • 其他: 调用失败

◆ setRangeAudioTeamID:

- (int) setRangeAudioTeamID: (int32_t) teamId

设置范围语音小队

注解
此接口在加入房间前后均可调用。
参数
teamId小队 ID
返回
  • 0: 方法调用成功
  • 其他: 调用失败

◆ setRemoteHighPriorityAudioStream:forUserID:streamType:

- (int) setRemoteHighPriorityAudioStream: (BOOL) enable
forUserID: (uint64_t) userID
streamType: (NERtcAudioStreamType) streamType 

设置远端用户音频流的高优先级。 支持在音频自动订阅的情况下,设置某一个远端用户的音频为最高优先级,可以优先听到该用户的音频。

注解
  • 该接口需要通话中设置,并需要自动订阅打开(默认打开)。
  • 该接口只能设置一个用户的优先级,后设置的会覆盖之前的设置。
  • 该接口通话结束后,优先级设置重置。
自从
V4.6.0
参数
enable是否设置音频订阅优先级。
  • true:设置音频订阅优先级。
  • false:取消设置音频订阅优先级。
userID用户 ID
streamType订阅音频流的类型。默认为 kNERtcAudioStreamMain。
返回
操作返回值,成功则返回 0。

◆ setRemoteRenderScaleMode:forUserID:

- (int) setRemoteRenderScaleMode: (NERtcVideoRenderScaleMode) mode
forUserID: (uint64_t) userID 

设置画布中远端视频画面的显示模式。
通过本接口可以实现设置远端视频画面的适应性,即是否裁剪或缩放。

自从
V3.5.0
使用前提
请先调用 INERtcChannel#subscribeRemoteVideo:forUserID:streamType: 方法订阅指定远端用户的视频流。
调用时机
请在初始化后调用该方法,且该方法仅可在加入房间后调用。
注解
纯音频 SDK 禁用该接口,如需使用请前往云信官网下载并替换成视频 SDK。
参数说明
参数名称 类型 描述
mode NERtcVideoRenderScaleMode 视频显示模式类型:
  • kNERtcVideoRenderScaleFit(0):适应视频,视频尺寸等比缩放。优先保证视频内容全部显示。若视频尺寸与显示视窗尺寸不一致,视窗未被填满的区域填充背景色。
  • kNERtcVideoRenderScaleFullFill(1):视频尺寸非等比缩放。保证视频内容全部显示,且填满视窗。
  • kNERtcVideoRenderScaleCropFill(2):适应区域,视频尺寸等比缩放。保证所有区域被填满,视频超出部分会被裁剪。
userID uint64_t 远端用户 ID。
示例代码
[channel setRemoteRenderScaleMode:kNERtcVideoRenderScaleFit forUserID:userID];
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30004(kNERtcErrNotSupported):不支持的操作,比如当前使用的是纯音频 SDK。
    • 30005(kNERtcErrInvalidState):当前状态不支持的操作,比如尚未加入房间。

◆ setRemoteRenderSubStreamVideoScaleMode:forUserID:

- (int) setRemoteRenderSubStreamVideoScaleMode: (NERtcVideoRenderScaleMode) mode
forUserID: (uint64_t) userID 

设置画布中远端屏幕共享视频画面的显示模式。
通过本接口可以实现设置远端发布的屏幕共享视频画面的适应性,即是否裁剪或缩放。

自从
V3.5.0
使用前提
请先调用 INERtcChannel#subscribeRemoteSubStreamAudio:forUserID: 方法订阅指定远端用户的屏幕共享流。
调用时机
请在初始化后调用该方法,且该方法仅可在加入房间后调用。
注解
纯音频 SDK 禁用该接口,如需使用请前往云信官网下载并替换成视频 SDK。
参数说明
参数名称 类型 描述
mode NERtcVideoRenderScaleMode 视频显示模式类型:
  • kNERtcVideoRenderScaleFit(0):适应视频,视频尺寸等比缩放。优先保证视频内容全部显示。若视频尺寸与显示视窗尺寸不一致,视窗未被填满的区域填充背景色。
  • kNERtcVideoRenderScaleFullFill(1):视频尺寸非等比缩放。保证视频内容全部显示,且填满视窗。
  • kNERtcVideoRenderScaleCropFill(2):适应区域,视频尺寸等比缩放。保证所有区域被填满,视频超出部分会被裁剪。
userID uint64_t 远端用户 ID。
示例代码
[channel setRemoteRenderSubStreamVideoScaleMode:kNERtcVideoRenderScaleFit forUserID:userID];
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30004(kNERtcErrNotSupported):不支持的操作,比如当前使用的是纯音频 SDK。
    • 30005(kNERtcErrInvalidState):当前状态不支持的操作,比如尚未加入房间。

◆ setRemoteSubscribeFallbackOption:

- (int) setRemoteSubscribeFallbackOption: (NERtcStreamFallbackOptions) option

设置弱网条件下订阅的音视频流回退选项。
弱网环境下,订阅的音视频质量会下降。通过该接口设置订阅音视频流的回退选项后:

  • SDK 会在下行弱网且音视频质量严重受影响时,将视频流切换为小流,或关断视频流,从而保证或提高通信质量。
  • SDK 会持续监控网络质量,并在网络质量改善时自动恢复音视频流。
  • 当远端订阅流回退为音频流时,或由音频流恢复为音视频流时,SDK 会触发远端订阅流已回退为音频流回调。
注解
请在加入房间(joinChannel)前调用此方法。
自从
V4.5.0
参数
option订阅音视频流的回退选项,默认为弱网时回退到视频小流。详细信息请参考 NERtcStreamFallbackOptions
返回
操作返回值,成功则返回 0

◆ setSpatializerRenderMode:

- (int) setSpatializerRenderMode: (NERtcSpatializerRenderMode) mode

设置空间音效的渲染模式

自从
V5.4.0
调用时机
请在引擎初始化后调用此接口,且该方法在加入房间前才可调用。
注解
请先调用 enableSpatializer: 接口启用空间音效,再调用本接口。
参数
mode渲染模式,具体请参考 #NERtcSpatializerRenderMode,默认值 kNERtcSpatializerRenderBinauralHighQuality
返回
  • 0: 方法调用成功
  • 其他: 调用失败

◆ setSpatializerRoomProperty:

- (int) setSpatializerRoomProperty: (NERtcSpatializerRoomProperty *) roomProperty

设置空间音效的房间混响属性

自从
V5.4.0
调用时机
请在引擎初始化后调用此接口,且该方法在加入房间前才可调用。
注解
请先调用 enableSpatializer: 接口启用空间音效,再调用本接口。
参数
roomProperty房间属性,具体请参考 NERtcSpatializerRoomProperty
返回
  • 0: 方法调用成功
  • 其他: 调用失败

◆ setSubscribeAudioAllowlist:

- (int) setSubscribeAudioAllowlist: (NSArray< NSNumber * > *) uidArray

您可以调用该方法指定只订阅的音频流。

注解
  • 此接口需要在加入房间成功后调用。
  • 对于调用接口时不在房间的 uid 不生效。
自从
V5.4.101
参数
[in]uid_array只订阅此 用户 uid 列表 的音频。
注解
此列表为全量列表。如果列表为空或 null,取消订阅白名单。
返回
  • 0:方法调用成功。
  • 其他:方法调用失败。

◆ setSubscribeAudioBlocklist:uidArray:

- (int) setSubscribeAudioBlocklist: (NERtcAudioStreamType) type
uidArray: (NSArray< NSNumber * > *) uidArray 

您可以调用该方法指定不订阅的音频流。

注解
  • 此接口需要在加入房间成功后调用。
  • 对于调用接口时不在房间的 uid 不生效。
自从
V5.4.101
参数
[in]type音频流类型。
[in]uid_array不订阅此 用户 uid 列表 的音频。
注解
此列表为全量列表。如果列表为空或 null,取消订阅黑名单。
返回
  • 0:方法调用成功。
  • 其他:方法调用失败。

◆ setupLocalSubStreamVideoCanvas:

- (int) setupLocalSubStreamVideoCanvas: (NERtcVideoCanvas *_Nullable) canvas

设置本端用户的视频辅流画布。
通过此接口可以实现设置本端用户的辅流显示视图。

自从
V3.9.0
调用时机
请在引擎初始化之后调用此接口,且该方法建议在加入房间前调用。
参数说明
参数名称 类型 描述
canvas NERtcVideoCanvas * 视频画布。详细信息请参考 NERtcVideoCanvas
示例代码
UIView *localSubStreamView = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 200, 200)];
NERtcVideoCanvas *canvas = [[NERtcVideoCanvas alloc] init];
canvas.container = localSubStreamView;
[channel setupLocalSubStreamVideoCanvas:canvas];
@ kNERtcVideoMirrorModeAuto
(默认)由 SDK 决定镜像模式
Definition NERtcEngineEnum.h:809
视频画布设置。
Definition NERtcEngineBase.h:296
NERtcVideoRenderScaleMode renderMode
视频渲染模式。
Definition NERtcEngineBase.h:325
VIEW_CLASS * container
视频窗口容器(SDK 内部渲染)。
Definition NERtcEngineBase.h:315
NERtcVideoMirrorMode mirrorMode
视频镜像模式。
Definition NERtcEngineBase.h:339
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30001(kNERtcErrFatal):状态错误,比如引擎尚未初始化。
    • 30004(kNERtcErrNotSupported):纯音频 SDK 不支持该功能。

◆ 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;
[channel setupLocalVideoCanvas:canvas];
相关接口
若您希望在通话中更新本地用户视图的渲染或镜像模式,请调用 INERtcEngineEx#setLocalRenderScaleMode: 方法。
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30001(kNERtcErrFatal):引擎尚未初始化。
    • 30004(kNERtcErrNotSupported):不支持的操作,比如纯音频 SDK 不支持该功能。
    • 30005(kNERtcErrInvalidState):当前状态不支持的操作,比如尚未加入房间。

◆ setupRemoteSubStreamVideoCanvas:forUserID:

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

设置远端用户的视频辅流画布。
通过此接口可以实现绑定远端用户和对应辅流的显示视图,即指定某个 uid 使用对应的画布显示。

自从
V3.9.0
使用前提
建议在收到远端用户加入房间的 NERtcChannelDelegate#onNERtcChannelUserDidJoinWithUserID:userName:joinExtraInfo: 回调后,再调用此接口通过回调返回的 uid 设置对应视图。
调用时机
请在引擎初始化之后调用此接口,且该方法在加入房间前后均可调用。
注解
  • 纯音频 SDK 禁用该接口,如需使用请前往云信官网下载并替换成视频 SDK。
  • 退出房间后,SDK 会清除远端用户和画布的的绑定关系,该设置自动失效。
参数说明
参数名称 类型 描述
canvas NERtcVideoCanvas * 视频画布。详细信息请参考 NERtcVideoCanvas
userID uint64_t 远端用户 ID。
示例代码
- (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;
[channel setupRemoteSubStreamVideoCanvas:canvas forUserID:userID];
}
相关接口
可以调用 INERtcChannel#setRemoteRenderScaleMode:forUserID: 方法在通话过程中更新远端用户视图的渲染模式。
返回
  • 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;
[channel setupRemoteVideoCanvas:canvas forUserID:userID];
}
相关接口
若您希望在通话中更新远端用户视图的渲染模式,请调用 INERtcChannel#setRemoteRenderScaleMode:forUserID:方法。
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30001(kNERtcErrFatal):引擎尚未初始化。
    • 30004(kNERtcErrNotSupported):纯音频 SDK 不支持该功能。
    • 30005(kNERtcErrInvalidState):当前状态不支持的操作,比如尚未加入房间。

◆ startChannelMediaRelay:

- (int) startChannelMediaRelay: (NERtcChannelMediaRelayConfiguration *_Nonnull) config

开始跨房间媒体流转发。

  • 该方法可用于实现跨房间连麦等场景。支持同时转发到 4 个房间,同一个房间可以有多个转发进来的媒体流。
  • 成功调用该方法后,SDK 会触发 onNERtcEngineChannelMediaRelayStateDidChange 和 onNERtcEngineDidReceiveChannelMediaRelayEvent 回调,并在回调中报告当前的跨房间媒体流转发状态和事件。
注解
  • 请在成功加入房间后调用该方法。调用此方法前需要通过 config 中的 setDestinationInfo 设置目标房间。
  • 该方法仅对直播场景下的主播角色有效。
  • 成功调用该方法后,若您想再次调用该方法,必须先调用 stopChannelMediaRelay 方法退出当前的转发状态。
  • 成功开始跨房间转发媒体流后,如果您需要修改目标房间,例如添加或删减目标房间等,可以调用方法 updateChannelMediaRelay 更新目标房间信息。
自从
V4.5.0
参数
config跨房间媒体流转发参数配置信息。详细信息请参考 NERtcChannelMediaRelayConfiguration
返回
成功返回 0,其他则失败

◆ startScreenCapture:

- (int) startScreenCapture: (NERtcVideoSubStreamEncodeConfiguration *) config

开启屏幕共享。
通过此接口开启屏幕共享后,屏幕共享内容以视频辅流的形式发送。

自从
V3.5.0
调用时机
请在引擎初始化之后调用此接口,且该方法仅可在加入房间后调用。
参数说明
参数名称 类型 描述
config NERtcVideoSubStreamEncodeConfiguration * 本地辅流发送配置,详细信息请参考 NERtcVideoSubStreamEncodeConfiguration
示例代码
config.maxProfile = 视频编码的分辨率;
config.minBitrate = 最小编码码率
config.minFrameRate = 最小编码帧率
config.frameRate = 帧率
config.bitrate = 最小编码码率
config.contentPrefer = 屏幕共享功能的编码策略倾向;
[channel startScreenCapture:config];
NERtcSubStreamContentPrefer contentPrefer
屏幕共享功能的编码策略倾向,默认为 kNERtcSubStreamContentPreferMotion。详细信息请参考 NERtcSubStreamContentPrefer。
Definition NERtcEngineBase.h:657
相关回调
成功开启屏幕共享辅流后,远端会触发 NERtcChannelDelegate#onNERtcChannelUserSubStreamDidStartWithUserID:subStreamProfile: 回调。
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30005(kNERtcErrInvalidState):状态错误,比如引擎尚未初始化。
    • 50001(kNERtcRuntimeErrVDMNotScreenUseSubStream):当前使用的非屏幕共享形式的辅流。

◆ stopChannelMediaRelay

- (int) stopChannelMediaRelay

停止跨房间媒体流转发。
通常在主播离开房间时,跨房间媒体流转发会自动停止;您也可以根据需要随时调用该方法,此时主播会退出所有目标房间。

自从
V4.2.1
使用前提
请在调用 INERtcChannel#startChannelMediaRelay: 方法开启跨房间媒体流转发之后调用此接口。
调用时机
请在引擎初始化之后调用此接口,且该方法仅可在加入房间后调用。
示例代码
int stopChannelMediaRelay()
停止跨房间媒体流转发。 通常在主播离开房间时,跨房间媒体流转发会自动停止;您也可以根据需要随时调用该方法,此时主播会退出所有目标房间。
相关回调
NERtcChannelDelegate#onNERtcChannelMediaRelayStateDidChange:channelName::跨房间媒体流转发状态发生改变回调。成功调用该方法后会返回 NERtcChannelMediaRelayStateIdle,否则会返回 NERtcChannelMediaRelayStateFailure。 NERtcChannelDelegate#onNERtcChannelDidReceiveChannelMediaRelayEvent:channelName:error::跨房间媒体流相关转发事件回调。成功调用该方法后会返回 NERtcChannelMediaRelayEventDisconnect,否则会返回 NERtcChannelMediaRelayEventFailure。
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30001(kNERtcErrFatal):通用错误。
    • 30005(kNERtcErrInvalidState):状态错误,比如引擎未初始化。

◆ stopScreenCapture

- (int) stopScreenCapture

关闭屏幕共享。
通过此接口可以实现关闭屏幕共享辅流。

自从
V3.5.0
调用时机
请在引擎初始化之后调用此接口,且该方法仅可在加入房间后调用。
示例代码
int stopScreenCapture()
关闭屏幕共享。 通过此接口可以实现关闭屏幕共享辅流。
相关回调
成功调用此方法后,远端会触发 NERtcChannelDelegate#onNERtcChannelUserSubStreamDidStop: 回调。
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30005(kNERtcErrInvalidState):当前状态不支持的操作,比如引擎尚未初始化。
    • 50001(kNERtcRuntimeErrVDMNotScreenUseSubStream):当前使用的非屏幕共享形式的辅流。

◆ subscribeAllRemoteAudio:

- (int) subscribeAllRemoteAudio: (BOOL) subscribe

取消或恢复订阅所有远端用户的音频主流。
加入房间时,默认订阅所有远端用户的音频主流,即 INERtcEngine#setParameters: 方法的 kNERtcKeyAutoSubscribeAudio 参数默认设置为 YES;只有当该参数的设置为 NO 时,此接口的调用才会生效。

自从
V3.5.0
调用时机
请在引擎初始化之后调用此接口,且该方法在加入房间前后均可调用。
业务场景
适用于重要会议需要一键全体静音的场景。
注解
  • 设置该方法的 subscribe 参数为 YES 后,对后续加入房间的用户同样生效。
  • 在开启自动订阅(默认)时,设置该方法的 subscribe 参数为 NO 可以实现取消订阅所有远端用户的音频流,但此时无法再调用 INERtcEngineEx#subscribeRemoteAudio:forUserID: 方法单独订阅指定远端用户的音频流。
参数说明
参数名称 类型 描述
subscribe BOOL 是否订阅所有用户的音频主流:
  • YES:订阅音频主流。
  • NO:取消订阅音频主流。
示例代码
//订阅所有远端用户的音频主流
[channel subscribeAllRemoteAudio:YES];
//取消订阅所有远端用户的音频主流
[channel subscribeAllRemoteAudio:NO];
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30001(kNERtcErrFatal):引擎未创建成功。

◆ subscribeRemoteAudio:forUserID:

- (int) subscribeRemoteAudio: (BOOL) subscribe
forUserID: (uint64_t) userID 

取消或恢复订阅指定远端用户的音频主流。
加入房间时,默认订阅所有远端用户的音频主流,您也可以通过此方法取消或恢复订阅指定远端用户的音频主流。

自从
V3.5.0
调用时机
该方法仅在加入房间后收到远端用户开启音频主流的回调 NERtcEngineDelegate#onNERtcEngineUserAudioDidStart: 后可调用。
业务场景
适用于需要手动订阅指定用户音频流的场景。
注解
该方法设置内部引擎为启用状态,在 leaveChannel 后设置失效,将恢复至默认。 在开启音频自动订阅且未打开服务端 ASL 自动选路的情况下,调用该接口无效。 退出房间后,此接口的设置将恢复至默认。
参数说明
参数名称 类型 描述
userID uint64_t 指定用户的 ID。
subscribe BOOL 是否订阅指定用户的音频主流:
  • YES:订阅音频主流。
  • NO:取消订阅音频主流。
示例代码
//订阅对方 uid 为 12345 的音频主流
[channel subscribeRemoteAudio:YES forUserID:12345];
//取消订阅对方 uid 为 12345 的音频主流
[channel subscribeRemoteAudio:NO forUserID:12345];
相关接口
若您希望订阅指定远端用户的音频辅流,请调用 INERtcChannel#subscribeRemoteSubStreamAudio:forUserID: 方法。
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30001(kNERtcErrFatal):引擎未创建成功。
    • 30005(kNERtcErrInvalidState):当前状态不支持的操作,比如尚未加入房间。
    • 30105(kNERtcErrFatal):未找到指定用户。

◆ subscribeRemoteSubStreamAudio:forUserID:

- (int) subscribeRemoteSubStreamAudio: (BOOL) subscribe
forUserID: (uint64_t) userID 

设置是否订阅指定远端用户的音频辅流。

自从
V4.6.10
调用时机
请在引擎初始化之后调用此接口,且该方法仅可在加入房间且收到远端用户开启音频辅流的回调 NERtcChannelDelegate#onNERtcChannelUserSubStreamAudioDidStart: 后调用。
注解
  • 加入房间时,默认订阅所有远端用户的音频流。
  • 请在指定远端用户加入房间后再调用此方法。
参数说明
参数名称 类型 描述
uid uint64_t 远端用户 ID。
subscribe BOOL 是否订阅指定音频辅流:
  • YES:订阅指定音频辅流。
  • NO:取消订阅指定音频辅流。
示例代码
//订阅 userId 用户的音频辅流
[channel subscribeRemoteSubStreamAudio:YES forUserID:userId];
//取消订阅 userId 用户的音频辅流
[channel subscribeRemoteSubStreamAudio:NO forUserID:userId];
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30001(kNERtcErrFatal):操作不支持,比如已开启自动订阅音频辅流。
    • 30005(kNERtcErrInvalidState):状态错误,比如引擎未初始化。
    • 30105(kNERtcErrUserNotFound):指定用户尚未加入房间。

◆ subscribeRemoteSubStreamVideo:forUserID:

- (int) subscribeRemoteSubStreamVideo: (BOOL) subscribe
forUserID: (uint64_t) userID 

订阅或取消订阅远端用户的视频辅流。

自从
V3.9.0
使用前提
调用时机
请在引擎初始化之后调用此接口,且该方法仅可在加入房间后调用。
注解
纯音频 SDK 禁用该接口,如需使用请前往云信官网下载并替换成视频 SDK。
参数说明
参数名称 类型 描述
userID uint64_t 远端用户 ID。
subsribe BOOL 是否订阅远端的视频辅流:
  • YES:订阅远端视频辅流。
  • NO:取消订阅远端视频辅流。
示例代码
[channel subscribeRemoteSubStreamVideo:YES forUserID:userID];
相关回调
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30001(kNERtcErrFatal):状态错误,比如引擎尚未初始化。
    • 30004(kNERtcErrNotSupported):不支持的操作。
    • 30005(kNERtcErrInvalidState):当前状态不支持的操作,比如引擎尚未初始化。
    • 30105(kNERtcErrUserNotFound):未找到该远端用户,可能对方还未加入房间。

◆ subscribeRemoteVideo:forUserID:streamType:

- (int) subscribeRemoteVideo: (BOOL) subscribe
forUserID: (uint64_t) userID
streamType: (NERtcRemoteVideoStreamType) streamType 

订阅或取消订阅指定远端用户的视频主流。
加入房间后,默认不订阅所有远端用户的视频主流;若您希望看到指定远端用户的视频,可以在监听到对方加入房间或发布视频流之后,通过此方法订阅该用户的视频主流。

自从
V3.5.0
调用时机
请在初始化后调用该方法,且该方法仅可在加入房间后调用。
参数说明
参数名称 类型 描述
userID uint64_t 指定用户的 ID。
streamType NERtcRemoteVideoStreamType 订阅的视频流类型:
  • kNERtcRemoteVideoStreamTypeHigh:高清画质的大流。
  • kNERtcRemoteVideoStreamTypeLow:低清画质的小流。
subscribe BOOL 是否订阅远端用户的视频流:
  • YES:订阅指定视频流。
  • NO:不订阅指定视频流。
示例代码
//订阅对方 uid 为 12345 的大流
[channel subscribeRemoteVideo:YES forUserID:12345 streamType:kNERtcRemoteVideoStreamTypeHigh];
@ kNERtcRemoteVideoStreamTypeHigh
大流,高清画质。
Definition NERtcEngineEnum.h:665
相关接口
若您希望订阅指定远端用户的视频辅流,请调用 INERtcChannel#subscribeRemoteSubStreamVideo:forUserID: 方法。
返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30001(kNERtcErrFatal):引擎尚未初始化。
    • 30004(kNERtcErrNotSupported ):纯音频 SDK 不支持该功能。
    • 30005(kNERtcErrInvalidState):尚未加入房间。
    • 30009(kNERtcErrInvalidDeviceSourceID):设备 ID 非法。
    • 30105(kNERtcErrUserNotFound):未找到指定用户。
    • 30106(kNERtcErrInvalidUserID):非法指定用户,比如订阅了本端。
    • 30107(kNERtcErrMediaNotStarted):媒体会话未建立,比如对端未开启视频主流。
    • 30108(kNERtcErrSourceNotFound):媒体源未找到,比如对端未开启视频主流。

◆ switchCamera

- (int) switchCamera

切换前置/后置摄像头。
该方法需要在相机启动后调用,例如调用 startPreview 或 joinChannel 后。

注解
纯音频 SDK 禁用该接口,如需使用请前往云信官网下载并替换成视频 SDK。
返回
操作返回值,成功则返回 0

◆ switchCameraWithPosition:

- (int) switchCameraWithPosition: (NERtcCameraPosition) position

指定前置/后置摄像头。
该方法需要在相机启动后调用,例如调用 startPreview 或 joinChannel 后。

注解
纯音频 SDK 禁用该接口,如需使用请前往云信官网下载并替换成视频 SDK。
自从
V4.6.10
参数
position摄像头类型。详细信息请参考 NERtcCameraPosition。该参数为必填参数,若未赋值,SDK 会报错。
返回
  • 0:方法调用成功。
  • 其他:方法调用失败。

◆ takeLocalSnapshot:callback:

- (int) takeLocalSnapshot: (NERtcStreamChannelType) streamType
callback: (NERtcTakeSnapshotCallback) callback 

本地视频画面截图。
调用 takeLocalSnapshot 截取本地主流或本地辅流的视频画面,并通过 NERtcTakeSnapshotCallback 的回调返回截图画面的数据。

注解

  • 本地主流截图,需要在 enableLocalVideo 并 joinChannel 成功之后调用。
  • 本地辅流截图,需要在 joinChannel 并 startScreenCapture 之后调用。
  • 同时设置文字、时间戳或图片水印时,如果不同类型的水印位置有重叠,会按照图片、文本、时间戳的顺序进行图层覆盖。
自从
V4.5.0
参数
streamType截图的视频流类型。支持设置为主流或辅流。
callback截图回调。
注解
纯音频 SDK 禁用该接口,如需使用请前往云信官网下载并替换成视频 SDK。
返回
操作返回值,成功则返回 0

◆ takeRemoteSnapshot:forUserID:callback:

- (int) takeRemoteSnapshot: (NERtcStreamChannelType) streamType
forUserID: (uint64_t) userID
callback: (NERtcTakeSnapshotCallback) callback 

远端视频画面截图。
调用 takeRemoteSnapshot 截取指定 uid 远端主流和远端辅流的视频画面,并通过 NERtcTakeSnapshotCallback 的回调返回截图画面的数据。

注解

  • takeRemoteSnapshot 需要在收到 onUserVideoStart 与 onNERtcEngineUserSubStreamDidStartWithUserID 回调之后调用。
  • 同时设置文字、时间戳或图片水印时,如果不同类型的水印位置有重叠,会按照图片、文本、时间戳的顺序进行图层覆盖。
自从
V4.5.0
参数
userID远端用户 ID。
streamType截图的视频流类型。支持设置为主流或辅流。
callback截图回调。
注解
纯音频 SDK 禁用该接口,如需使用请前往云信官网下载并替换成视频 SDK。
返回
操作返回值,成功则返回 0

◆ updateChannelMediaRelay:

- (int) updateChannelMediaRelay: (NERtcChannelMediaRelayConfiguration *_Nonnull) config

更新媒体流转发的目标房间。
成功开始跨房间转发媒体流后,如果您希望将流转发到多个目标房间,或退出当前的转发房间,可以调用该方法。

  • 成功开始跨房间转发媒体流后,如果您需要修改目标房间,例如添加或删减目标房间等,可以调用此方法。
  • 成功调用此方法后,SDK 会触发 onNERtcEngineChannelMediaRelayStateDidChange 回调。如果报告 NERtcChannelMediaRelayStateRunning,则表示已成功转发媒体流。
注解
  • 请在加入房间并成功调用 startChannelMediaRelay 开始跨房间媒体流转发后,调用此方法。调用此方法前需要通过 config 中的 setDestinationInfo 设置目标房间。
  • 跨房间媒体流转发最多支持 4 个目标房间,您可以在调用该方法之前,通过 NERtcChannelMediaRelayConfiguration 中的 removeDestinationInfoForChannelName 方法移除不需要的房间,再添加新的目标房间。
自从
V4.5.0
参数
config跨房间媒体流转发参数配置信息。详细信息请参考 NERtcChannelMediaRelayConfiguration
返回
成功返回 0,其他则失败

◆ updateLiveStreamTask:compeltion:

- (int) updateLiveStreamTask: (NERtcLiveStreamTaskInfo *) taskInfo
compeltion: (NERtcLiveStreamCompletion) completion 

更新房间内指定推流任务。 通过此接口可以实现调整指定推流任务的编码参数、画布布局、推流模式等。

自从
V3.5.0
使用前提
请先调用 INERtcChannel#addLiveStreamTask:compeltion: 方法添加推流任务。
调用时机
请在引擎初始化之后调用此接口,且该方法仅可在加入房间后调用。
注解
仅角色为主播的房间成员能调用此接口,观众成员无相关推流权限。
参数说明
参数名称 类型 描述
taskInfo NERtcLiveStreamTaskInfo * 推流任务信息。详细信息请参考 {@ NERtcLiveStreamTaskInfo}。
compeltion NERtcLiveStreamCompletion 操作结果回调,方法调用成功后会触发对应的 NERtcEngineLiveStreamObserver#onNERTCEngineLiveStreamState:taskID:url: 回调。
示例代码
[channel updateLiveStreamTask:info compeltion:^(NSString * _Nonnull taskId, kNERtcLiveStreamError errorCode){
}];
相关回调
调用此接口成功后会触发 NERtcEngineLiveStreamObserver#onNERTCEngineLiveStreamState:taskID:url: 回调,通知推流任务状态已更新。
返回
  • 0(kNERtcNoError):方法调用成功;
  • 其他:方法调用失败。
    • 403(kNERtcErrChannelReservePermissionDenied):权限不足,观众模式下不支持此操作。
    • 30003(kNERtcErrInvalidParam): 参数错误,比如推流任务 ID 参数为空。
    • 30005(kNERtcErrInvalidState):状态错误,比如引擎尚未初始化。

◆ updatePermissionKey:

- (int) updatePermissionKey: (NSString *) key

更新权限密钥。

  • 通过本接口可以实现当用户权限被变更,或者收到权限密钥即将过期的回调 NERtcChannelDelegate#onNERtcChannelPermissionKeyWillExpire 时,更新权限密钥。
    自从
    V4.6.29
    使用前提
    请确保已开通高级 Token 鉴权功能,具体请联系网易云信商务经理。
    调用时机
    请在引擎初始化之后调用此接口,且该方法仅可在加入房间后调用。
    业务场景
    适用于变更指定用户加入、创建房间或上下麦时发布流相关权限的场景。
    参数说明
    参数名称 类型 描述
    key NSString * 新的权限密钥。

    示例代码
    //getPermToken 为获取高级密钥方法,由您自行实现,具体请参考官方文档的高级 Token 鉴权章节。</a>
    NSString* token = [self getToken];
    [channel updatePermissionKey:token];
    相关回调
    调用此接口成功更新权限密钥后会触发 NERtcChannelDelegate#onNERtcChannelUpdatePermissionKey:error:timeout: 回调。
    返回
  • 0(kNERtcNoError):方法调用成功。
  • 其他:方法调用失败。
    • 30001(kNERtcErrFatal):通用错误,比如引擎尚未初始化。

◆ updateSelfPosition:

- (int) updateSelfPosition: (NERtcPositionInfo *) info

设置空间音效中说话者和接收者的空间位置信息。SDK 会根据该方法中的参数计算接收者和说话者之间的相对位置,进而渲染出空间音效。

自从
V5.4.0
调用时机
请在引擎初始化后调用此接口,且该方法在加入房间前后均可调用。
注解
参数说明
通过 info 参数设置空间音效中说话者和接收者的空间位置信息。::NERtcPositionInfo 的具体参数说明如下表所示。
参数名称 描述
speaker_position 说话者的位置信息,三个值依次表示 X、Y、Z 的坐标值。默认值{0,0,0}
speaker_quaternion 说话者的旋转信息,通过四元组来表示,数据格式为{w, x, y, z}。默认值{0,0,0,0}
head_position 接收者的位置信息,三个值依次表示 X、Y、Z 的坐标值。默认值{0,0,0}
head_quaternion 接收者的旋转信息,通过四元组来表示,数据格式为{w, x, y, z}。默认值{0,0,0,0}
返回
  • 0: 方法调用成功
  • 其他: 调用失败

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