NERtc iOS SDK  V4.6.0
构造函数 | 所有成员列表
<INERtcChannel>协议 参考

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

#import <INERtcChannel.h>

类 <INERtcChannel> 继承关系图:
NERtcChannel

构造函数

(int) - destroy
 
(int) - setChannelDelegate:
 设置 channel 的回调。 更多...
 
(NSString *) - getChannelName
 获取当前房间名。 更多...
 
(NERtcConnectionStateType- connectionState
 获取当前房间连接状态。 更多...
 
(int) - joinChannelWithToken:completion:
 加入音视频房间。
加入音视频房间时,如果指定房间尚未创建,云信服务器内部会自动创建一个同名房间。 更多...
 
(int) - leaveChannel
 离开房间,即挂断或退出通话。
结束通话时,必须调用 leaveChannel 结束通话,否则无法开始下一次通话。
成功调用该方法离开房间后,本地会触发 onNERtcEngineDidLeaveChannelWithResult 回调,远端会触发 onNERtcEngineUserDidLeaveWithUserID 回调。 更多...
 
(int) - enableLocalAudio:
 开启/关闭本地音频采集和发送。
当 App 加入房间时,语音功能默认为开启状态。
该方法不影响接收或播放远端音频流,enableLocalAudio(NO) 适用于只下行不上行音频流的场景。
成功调用该方法后,房间内其他用户触发 onNERtcEngineUserAudioDidStart 或 onNERtcEngineUserAudioDidStop 回调。 更多...
 
(int) - enableLocalVideo:
 是否开启本地视频采集。 更多...
 
(int) - enableDualStreamMode:
 设置是否开启视频大小流模式。
该方法设置单流或者双流模式。发送端开启双流模式后,接收端可以选择接收大流还是小流。其中,大流指高分辨率、高码率的视频流,小流指低分辨率、低码率的视频流。 更多...
 
(int) - setCameraCaptureConfig:
 设置本地摄像头的采集偏好等配置。
在视频通话或直播中,SDK 自动控制摄像头的输出参数。默认情况下,SDK 根据用户的 setLocalVideoConfig 配置匹配最合适的分辨率进行采集。但是在部分业务场景中,如果采集画面质量无法满足实际需求,可以调用该接口调整摄像头的采集配置。 更多...
 
(int) - setLocalVideoConfig:
 设置视频编码属性。 更多...
 
(int) - subscribeRemoteAudio:forUserID:
 取消或恢复订阅指定远端用户音频流。
加入房间时,默认订阅所有远端用户的音频流,您可以通过此方法取消或恢复订阅指定远端用户的音频流。 更多...
 
(int) - subscribeAllRemoteAudio:
 取消或恢复订阅所有远端用户音频流。 更多...
 
(int) - muteLocalAudio:
 开关本地音频发送。
该方法用于允许或禁止向网络发送本地音频流。 更多...
 
(int) - setupLocalVideoCanvas:
 设置本地视图。
该方法设置本地视频显示信息。只影响本地用户看到的视频画面,不影响远端。 App 通过调用此接口绑定本地视频流的显示视窗(view)。 在 App 开发中,通常在初始化后调用该方法进行本地视频设置,然后再加入房间。 更多...
 
(int) - setLocalRenderScaleMode:
 设置本端的视频显示模式。 更多...
 
(int) - setupRemoteVideoCanvas:forUserID:
 设置远端用户视图。
该方法绑定远端用户和显示视图,并设置远端用户视图在本地显示时的渲染模式和镜像模式,只影响本地用户看到的视频画面。 更多...
 
(int) - setRemoteRenderScaleMode:forUserID:
 设置远端的视频显示模式。 更多...
 
(int) - subscribeRemoteVideo:forUserID:streamType:
 订阅或取消订阅指定远端用户的视频流。 更多...
 
(int) - muteLocalVideo:
 取消或恢复发布本地视频流。 更多...
 
(int) - setClientRole:
 在直播场景中设置用户角色。
用户角色支持设置为主播或观众,主播和观众的权限不同。 更多...
 
(int) - adjustUserPlaybackSignalVolume:forUserID:
 调节本地播放的指定远端用户的信号音量。
加入房间后,您可以多次调用该方法设置本地播放的不同远端用户的音量;也可以反复调节本地播放的某个远端用户的音量。 更多...
 
(int) - setupLocalSubStreamVideoCanvas:
 设置本地辅流视频画布。
该方法设置本地辅流视频显示信息。App 通过调用此接口绑定本地辅流的显示视窗(view)。 在 App 开发中,通常在初始化后调用该方法进行本地视频设置,然后再加入房间。 更多...
 
(int) - startScreenCapture:
 开启屏幕共享,屏幕共享内容以辅流形式发送。
只能在加入房间后调用。
如果您在加入房间后调用该方法开启辅流,调用成功后,远端触发 onNERtcEngineUserSubStreamDidStartWithUserID 回调。 更多...
 
(int) - stopScreenCapture
 关闭辅流形式的屏幕共享。
如果您在加入房间后调用该方法关闭辅流,调用成功后,远端触发 onNERtcEngineUserSubStreamDidStop 回调。 更多...
 
(int) - setLocalRenderSubStreamScaleMode:
 设置本端的屏幕共享辅流视频显示模式。
在本端开启辅流形式的屏幕共享时使用。App 可以多次调用此方法更改显示模式。 更多...
 
(int) - setupRemoteSubStreamVideoCanvas:forUserID:
 设置远端的辅流视频画布。
该方法绑定远端用户和辅流显示视图,即指定某个 userID 使用对应的画布显示。 更多...
 
(int) - subscribeRemoteSubStreamVideo:forUserID:
 订阅或取消订阅远端的屏幕共享辅流视频,订阅之后才能接收远端的辅流视频数据。 更多...
 
(int) - setRemoteRenderSubStreamVideoScaleMode:forUserID:
 设置远端的屏幕共享辅流视频显示模式。 更多...
 
(int) - setRemoteHighPriorityAudioStream:forUserID:streamType:
 设置远端用户音频流的高优先级。 支持在音频自动订阅的情况下,设置某一个远端用户的音频为最高优先级,可以优先听到该用户的音频。 更多...
 
(int) - setLocalCanvasWatermarkConfigs:withStreamType:
 添加本地视频画布水印。 更多...
 
(int) - setRemoteCanvasWatermarkConfigs:forUserID:withStreamType:
 添加远端视频画布水印。 更多...
 
(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
 停止跨房间媒体流转发。
主播离开房间时,跨房间媒体流转发自动停止,您也可以在需要的时候随时调用 stopChannelMediaRelay 方法,此时主播会退出所有目标房间。 更多...
 
(int) - setLocalMediaPriority:preemptive:
 设置本地用户的媒体流优先级。
如果某个用户的优先级为高,那么该用户媒体流的优先级就会高于其他用户,弱网环境下 SDK 会优先保证其他用户收到的、高优先级用户的媒体流的质量。 更多...
 
(int) - setLocalPublishFallbackOption:
 设置弱网条件下发布的音视频流回退选项。
在网络不理想的环境下,发布的音视频质量都会下降。使用该接口并将 option 设置为 kNERtcStreamFallbackOptionAudioOnly 后: 更多...
 
(int) - setRemoteSubscribeFallbackOption:
 设置弱网条件下订阅的音视频流回退选项。
弱网环境下,订阅的音视频质量会下降。通过该接口设置订阅音视频流的回退选项后: 更多...
 

详细描述

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 

添加房间推流任务。
成功调用该方法后,当前用户可以收到该直播流的状态通知。

注解
  • 该方法仅适用直播场景。
  • 请在房间内调用该方法,该方法在通话中有效。
  • 该方法每次只能增加一路旁路推流地址。如需推送多路流,则需多次调用该方法。同一个音视频房间(即同一个 channelid)可以创建 3 个不同的推流任务。
自从
V4.5.0
参数
taskInfo推流任务信息,详细信息请参考 NERtcLiveStreamTaskInfo
completion操作结果回调,方法调用成功后会触发对应回调。详细信息请参考 NERtcLiveStreamCompletion
返回
操作返回值,成功则返回 0

◆ adjustUserPlaybackSignalVolume:forUserID:

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

调节本地播放的指定远端用户的信号音量。
加入房间后,您可以多次调用该方法设置本地播放的不同远端用户的音量;也可以反复调节本地播放的某个远端用户的音量。

注解
  • 请在成功加入房间后调用该方法。
  • 该方法在本次通话中有效。如果远端用户中途退出房间,则再次加入此房间时仍旧维持该设置,通话结束后设置失效。
  • 该方法调节的是本地播放的指定远端用户混音后的音量,且每次只能调整一位远端用户。若需调整多位远端用户在本地播放的音量,则需多次调用该方法。
自从
V4.5.0
参数
userID远端用户 ID。
volume播放音量,取值范围为 [0,100]。
  • 0:静音。
  • 100:原始音量。
返回
操作返回值,成功则返回 0

◆ cleanupChannelMediaStatsObserver

- (int) cleanupChannelMediaStatsObserver

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

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

◆ connectionState

- (NERtcConnectionStateType) connectionState

获取当前房间连接状态。

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

◆ destroy

- (int) destroy
自从
V4.5.0 销毁 IRtcChannel 实例,释放资源。

◆ enableDualStreamMode:

- (int) enableDualStreamMode: (BOOL)  enable

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

注解
  • 纯音频 SDK 禁用该接口,如需使用请前往云信官网下载并替换成视频 SDK。
  • 该方法只对摄像头数据生效,自定义输入、屏幕共享等视频流无效。
  • 该方法在加入房间前后都能调用。
自从
V4.5.0
参数
enableYES 发送双流, NO 发送单流。
返回
操作返回值,成功则返回 0

◆ enableLocalAudio:

- (int) enableLocalAudio: (BOOL)  enabled

开启/关闭本地音频采集和发送。
当 App 加入房间时,语音功能默认为开启状态。
该方法不影响接收或播放远端音频流,enableLocalAudio(NO) 适用于只下行不上行音频流的场景。
成功调用该方法后,房间内其他用户触发 onNERtcEngineUserAudioDidStart 或 onNERtcEngineUserAudioDidStop 回调。

注解
  • 该方法与 muteLocalAudio 的区别在于,enableLocalAudio 用于开启本地语音采集及处理;muteLocalAudio 用于停止或继续发送本地音频流。
  • 该方法设置内部引擎为启用状态,在 leaveChannel 后仍然有效。
  • 从 V4.4.0 版本开始,开启或关闭本地音频采集的操作不再影响音乐文件播放,即 enableLocalAudio(NO) 后仍旧可以通过 startAudioMixingWithOption: 播放音乐文件。
自从
V4.5.0
参数
enabled是否开启本地音频采集。
返回
  • 0: 方法调用成功;
  • 其他: 方法调用失败。

◆ enableLocalVideo:

- (int) enableLocalVideo: (BOOL)  enabled

是否开启本地视频采集。

注解
  • 该方法在加入房间前和加入房间后均可调用。
  • 成功启用或禁用本地视频采集后,远端会触发 onNERtcEngineUserVideoDidStartWithUserID 或 onNERtcEngineUserVideoDidStop 回调。
自从
V4.5.0
参数
enabled是否开启本地视频采集。
返回
操作返回值,成功则返回 0

◆ getChannelName

- (NSString *) getChannelName

获取当前房间名。

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

◆ joinChannelWithToken:completion:

- (int) joinChannelWithToken: (NSString *)  token
completion: (NERtcJoinChannelCompletion completion 

加入音视频房间。
加入音视频房间时,如果指定房间尚未创建,云信服务器内部会自动创建一个同名房间。

  • SDK 加入房间后,同一个房间内的用户可以互相通话,多个用户加入同一个房间,可以群聊。使用不同 App Key 的 App 之间不能互通。
  • 成功调用该方加入房间后,远端会触发 onNERtcEngineUserDidJoinWithUserID 回调。
自从
V4.5.0
参数
token安全认证签名(NERTC Token)。可设置为:
  • null。非安全模式下可设置为 null。安全性不高,建议在产品正式上线前联系对应商务经理转为安全模式。
  • 已获取的NERTC Token。安全模式下必须设置为获取到的 Token 。若未传入正确的 Token 将无法进入房间。推荐使用安全模式。
completion操作完成的 block 回调。
返回
操作返回值,被执行了则返回 0。

◆ leaveChannel

- (int) leaveChannel

离开房间,即挂断或退出通话。
结束通话时,必须调用 leaveChannel 结束通话,否则无法开始下一次通话。
成功调用该方法离开房间后,本地会触发 onNERtcEngineDidLeaveChannelWithResult 回调,远端会触发 onNERtcEngineUserDidLeaveWithUserID 回调。

注解
  • 该方法是异步操作,调用返回时并没有真正退出频道。在真正退出房间后,SDK 会触发 onNERtcEngineDidLeaveChannelWithResult 回调。
  • 如果在调用 leaveChannel 后立即调用 destroyEngine,可能会无法正常离开房间。因此建议用户在收到 onNERtcEngineDidLeaveChannelWithResult 回调之后再调用 destroyEngine 释放会话相关所有资源。
自从
V4.5.0
返回
操作返回值,成功则返回 0

◆ muteLocalAudio:

- (int) muteLocalAudio: (BOOL)  muted

开关本地音频发送。
该方法用于允许或禁止向网络发送本地音频流。

注解
  • 该方法不影响音频采集状态,因为并没有禁用音频采集设备。
  • 静音状态会在通话结束后被重置为非静音。
  • 成功调用该方法后,房间内其他用户会收到 onNERtcEngineUser:audioMuted 回调。
自从
V4.5.0
参数
muted是否开启本地音频发送。
返回
  • 0: 方法调用成功;
  • 其他: 方法调用失败。

◆ muteLocalVideo:

- (int) muteLocalVideo: (BOOL)  muted

取消或恢复发布本地视频流。

注解
  • 调用该方法取消发布本地视频流后,SDK 不再发送本地视频流。
  • 该方法在加入房间前后均可调用。
  • 若调用该方法取消发布本地视频流,通话结束后会被重置为默认状态,即默认发布本地视频流。
  • 该方法与 enableLocalVideo 的区别在于,enableLocalVideo 会关闭本地摄像头设备,muteLocalVideo 不影响本地视频流采集,不禁用摄像头,且响应速度更快。
  • 成功调用该方法后,远端会触发 onNERtcEngineUser:videoMuted: 回调。
自从
V4.5.0
参数
muted是否取消发布本地视频流。
  • true:不发布本地视频流。
  • false:(默认)发布本地视频流。
返回
  • 0: 方法调用成功;
  • 其他: 方法调用失败。

◆ removeChannelMediaStatsObserver:

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

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

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

◆ removeLiveStreamTask:compeltion:

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

删除房间推流任务。

注解
  • 该方法仅适用直播场景。
  • 请在房间内调用该方法,该方法在通话中有效。
自从
V4.5.0
参数
taskId推流任务 ID。
completion操作结果回调,方法调用成功后会触发对应回调。详细信息请参考 NERtcLiveStreamCompletion
返回
操作返回值,成功则返回 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。

◆ setCameraCaptureConfig:

- (int) setCameraCaptureConfig: (NERtcCameraCaptureConfiguration *)  config

设置本地摄像头的采集偏好等配置。
在视频通话或直播中,SDK 自动控制摄像头的输出参数。默认情况下,SDK 根据用户的 setLocalVideoConfig 配置匹配最合适的分辨率进行采集。但是在部分业务场景中,如果采集画面质量无法满足实际需求,可以调用该接口调整摄像头的采集配置。

  • 需要采集并预览高清画质时,可以将采集偏好设置为 kNERtcCameraOutputQuality,此时 SDK 会自动设置较高的摄像头输出参数,本地采集与预览画面比编码参数更加清晰。
  • 需要自定义设置摄像头采集的视频尺寸时,请通过参数 preference 将采集偏好设为 kNERtcCameraOutputManual,并通过 NERtcCameraPreference 中的 captureWidth 和 captureHeight 自定义设置本地摄像头采集的视频宽高。
注解
  • 该方法可以在加入房间前后动态调用,设置成功后,会自动重启采集模块。
  • 设置更高的采集参数会导致更大的性能消耗,例如 CPU 和内存占用等,尤其是在开启视频前处理的场景下。
自从
V4.5.0
参数
config摄像头采集配置。
返回
0
方法调用成功,其他调用失败

◆ setChannelDelegate:

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

设置 channel 的回调。

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

◆ setClientRole:

- (int) setClientRole: (NERtcClientRole role

在直播场景中设置用户角色。
用户角色支持设置为主播或观众,主播和观众的权限不同。

  • 主播:可以开关摄像头等设备、可以发布流、可以操作互动直播推流相关接口、上下线对其他房间内用户可见。
  • 观众:不可以开关摄像头等设备、不可以发布流、不可以操作互动直播推流相关接口、上下线对其他房间内用户不可见。

如果你在加入频道后调用该方法切换角色,调用成功后会收到以下回调:

  • 主播切观众,本端触发 onNERtcEngineDidClientRoleChanged 回调,远端触发 onNERtcEngineUserDidLeaveWithUserID 回调。
  • 观众切主播,本端触发 onNERtcEngineDidClientRoleChanged 回调,远端触发 onNERtcEngineUserDidJoinWithUserID 回调。
注解
  • 默认情况下用户以主播角色加入房间。在加入房间前,用户可以调用本接口切换本端模式为观众。在加入房间后,用户也可以通过本接口切换用户模式。
  • 用户切换为观众角色时,SDK 会自动关闭音视频设备。
自从
V4.5.0
参数
role用户角色。详细信息请参考 NERtcClientRole
返回
  • 0(kNERtcNoError): 方法调用成功。
  • < 0: 方法调用失败。
    • 30001(kNERtcErrFatal): Engine 未创建。
    • 30101(kNERtcErrChannelNotJoined): 尚未加入房间。

◆ setLocalCanvasWatermarkConfigs:withStreamType:

- (int) setLocalCanvasWatermarkConfigs: (nullable NERtcCanvasWatermarkConfig *)  config
withStreamType: (NERtcStreamChannelType type 

添加本地视频画布水印。

注解
  • setLocalCanvasWatermarkConfigs 方法作用于本地视频画布,不影响视频流。画布被移除时,水印也会自动移除。
  • 设置水印之前,需要先通过画布相关方法设置画布。
自从
V4.5.0
参数
type视频流类型。支持设置为主流或辅流。详细信息请参考 NERtcStreamChannelType
config画布水印设置。支持设置文字水印、图片水印和时间戳水印,设置为 null 表示清除水印。详细信息请参考 NERtcCanvasWatermarkConfig
注解
纯音频SDK禁用该接口,如需使用请前往云信官网下载并替换成视频SDK
返回
操作返回值,成功则返回 0

◆ setLocalMediaPriority:preemptive:

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

设置本地用户的媒体流优先级。
如果某个用户的优先级为高,那么该用户媒体流的优先级就会高于其他用户,弱网环境下 SDK 会优先保证其他用户收到的、高优先级用户的媒体流的质量。

注解
  • 请在加入房间(joinChannel)前调用此方法。
  • 快速切换房间 (switchChannel) 后,媒体优先级会恢复为默认值,即普通优先级。
自从
V4.5.0
参数
priority本地用户的媒体流优先级,默认为 kNERtcMediaPriorityNormal ,即普通优先级。详细信息请参考 NERtcMediaPriorityType
preemptive是否开启抢占模式,默认为 NO,即不开启。
  • 抢占模式开启后,本地用户可以抢占其他用户的高优先级,被抢占的用户的媒体优先级变为普通优先级,在抢占者退出房间后,其他用户的优先级仍旧维持普通优先级。
  • 抢占模式关闭时,如果房间中已有高优先级用户,则本地用户的高优先级设置不生效,仍旧为普通优先级。
返回
操作返回值,成功则返回 0

◆ setLocalPublishFallbackOption:

- (int) setLocalPublishFallbackOption: (NERtcStreamFallbackOptions option

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

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

◆ setLocalRenderScaleMode:

- (int) setLocalRenderScaleMode: (NERtcVideoRenderScaleMode mode

设置本端的视频显示模式。

注解
纯音频 SDK 禁用该接口,如需使用请前往云信官网下载并替换成视频 SDK。
自从
V4.5.0
参数
mode视频显示模式。详细信息请参考 NERtcVideoRenderScaleMode
返回
操作返回值,成功则返回 0

◆ setLocalRenderSubStreamScaleMode:

- (int) setLocalRenderSubStreamScaleMode: (NERtcVideoRenderScaleMode mode

设置本端的屏幕共享辅流视频显示模式。
在本端开启辅流形式的屏幕共享时使用。App 可以多次调用此方法更改显示模式。

注解
  • 纯音频 SDK 禁用该接口,如需使用请前往云信官网下载并替换成视频 SDK。
  • 调用此方法前,必须先通过 setupLocalSubStreamVideoCanvas 设置本地辅流画布。
自从
V4.5.0
参数
mode视频显示模式。详细信息请参考 NERtcVideoRenderScaleMode
返回
操作返回值,成功则返回 0

◆ setLocalVideoConfig:

- (int) setLocalVideoConfig: (NERtcVideoEncodeConfiguration *)  config

设置视频编码属性。

  • 可以在加入房间前或加入房间后调用此接口。
  • NERtcVideoConfig 中的 videoProfile 可以指定预设的 Profile 模式,但是预设模式往往无法满足实际场景需求,网易云信建议您通过 widthheight 进行自定义设置。详细信息请参考设置视频属性
    注解

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

◆ setRemoteCanvasWatermarkConfigs:forUserID:withStreamType:

- (int) setRemoteCanvasWatermarkConfigs: (nullable NERtcCanvasWatermarkConfig *)  config
forUserID: (uint64_t)  userID
withStreamType: (NERtcStreamChannelType type 

添加远端视频画布水印。

注解
  • setRemoteCanvasWatermarkConfigs 方法作用于远端视频画布,不影响视频流。画布被移除时,水印也会自动移除。
  • 设置水印之前,需要先通过画布相关方法设置画布。
自从
V4.5.0
参数
userID远端用户 ID。
type视频流类型。支持设置为主流或辅流。详细信息请参考 NERtcStreamChannelType
config画布水印设置。支持设置文字水印、图片水印和时间戳水印,设置为 null 表示清除水印。详细信息请参考 NERtcCanvasWatermarkConfig
注解
纯音频SDK禁用该接口,如需使用请前往云信官网下载并替换成视频 SDK。
返回
操作返回值,成功则返回 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 

设置远端的视频显示模式。

注解
纯音频 SDK 禁用该接口,如需使用请前往云信官网下载并替换成视频 SDK。
自从
V4.5.0
参数
mode视频显示模式。详细信息请参考 NERtcVideoRenderScaleMode
userID远端用户 ID。
返回
操作返回值,成功则返回 0

◆ setRemoteRenderSubStreamVideoScaleMode:forUserID:

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

设置远端的屏幕共享辅流视频显示模式。

注解
  • 纯音频 SDK 禁用该接口,如需使用请前往云信官网下载并替换成视频 SDK。
  • 调用本接口之前,请先通过 subscribeRemoteSubStreamVideo 订阅远端的屏幕共享辅流视频。
自从
V4.5.0
参数
mode视频显示模式。详细信息请参考 NERtcVideoRenderScaleMode
userID远端用户 ID。
返回
操作返回值,成功则返回 0

◆ setRemoteSubscribeFallbackOption:

- (int) setRemoteSubscribeFallbackOption: (NERtcStreamFallbackOptions option

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

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

◆ setupLocalSubStreamVideoCanvas:

- (int) setupLocalSubStreamVideoCanvas: (NERtcVideoCanvas *)  canvas

设置本地辅流视频画布。
该方法设置本地辅流视频显示信息。App 通过调用此接口绑定本地辅流的显示视窗(view)。 在 App 开发中,通常在初始化后调用该方法进行本地视频设置,然后再加入房间。

注解
  • 若使用外部渲染,建议在加入房间之前设置。
  • 请在初始化后调用该方法,然后再加入房间。
  • 同一个画布只能设置给一个用户。
  • 纯音频 SDK 禁用该接口,如需使用请前往云信官网下载并替换成视频 SDK。
自从
V4.5.0
参数
canvas视频画布。详细信息请参考 NERtcVideoCanvas。删除画布设置时请传 nil。
返回
操作返回值,成功则返回 0

◆ setupLocalVideoCanvas:

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

设置本地视图。
该方法设置本地视频显示信息。只影响本地用户看到的视频画面,不影响远端。 App 通过调用此接口绑定本地视频流的显示视窗(view)。 在 App 开发中,通常在初始化后调用该方法进行本地视频设置,然后再加入房间。

注解
自从
V4.5.0
参数
canvas视频画布。详细信息请参考 NERtcVideoCanvas。如果需要删除则传 nil。
返回
  • 0: 方法调用成功;
  • 其他: 方法调用失败。

◆ setupRemoteSubStreamVideoCanvas:forUserID:

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

设置远端的辅流视频画布。
该方法绑定远端用户和辅流显示视图,即指定某个 userID 使用对应的画布显示。

注解
  • 纯音频 SDK 禁用该接口,如需使用请前往云信官网下载并替换成视频 SDK。
  • 若使用外部渲染,建议在收到 onNERtcEngineUserDidJoinWithUserID 后设置。
  • 如果 App 无法事先知道对方的用户 ID,可以在远端加入房间后调用。从 onNERtcEngineUserDidJoinWithUserID 中获取对方的 uid,并通过本方法为该用户设置辅流视频画布。
  • 退出房间后,SDK 清除远端用户和画布的的绑定关系,该设置自动失效。
自从
V4.5.0
参数
userID远端用户 ID。
canvas视频画布。详细信息请参考 NERtcVideoCanvas。删除画布设置时请传 nil。
返回
操作返回值,成功则返回 0

◆ setupRemoteVideoCanvas:forUserID:

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

设置远端用户视图。
该方法绑定远端用户和显示视图,并设置远端用户视图在本地显示时的渲染模式和镜像模式,只影响本地用户看到的视频画面。

注解
  • 如果 App 无法事先知道对方的用户 ID,可以在 APP 收到 onNERtcEngineUserDidJoinWithUserID 事件时设置。
  • 解除某个用户的绑定视图可以把 canvas 设置为空。
  • 退出房间后,SDK 会清除远程用户和视图的绑定关系。
  • 如果您希望在通话中更新本地用户视图的渲染或镜像模式,请使用 INERtcEngineEx#setRemoteRenderScaleMode:forUserID: 方法。
自从
V4.5.0
参数
userID远端用户 ID。
canvas视频窗口。详细信息请参考 NERtcVideoCanvas。如果需要删除则传 nil。
返回
  • 0: 方法调用成功;
  • 其他: 方法调用失败。

◆ 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

开启屏幕共享,屏幕共享内容以辅流形式发送。
只能在加入房间后调用。
如果您在加入房间后调用该方法开启辅流,调用成功后,远端触发 onNERtcEngineUserSubStreamDidStartWithUserID 回调。

自从
V4.5.0
注解
纯音频 SDK 禁用该接口,如需使用请前往云信官网下载并替换成视频 SDK。
参数
config本地辅流发送配置,详细信息请参考 NERtcVideoSubStreamEncodeConfiguration
返回
操作返回值,成功则返回 0

◆ stopChannelMediaRelay

- (int) stopChannelMediaRelay

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

  • 成功调用该方法后,SDK 会触发 onNERtcEngineChannelMediaRelayStateDidChange 回调。如果报告 NERtcChannelMediaRelayStateIdle,则表示已停止转发媒体流。
  • 如果该方法调用不成功,SDK 会触发 onNERtcEngineChannelMediaRelayStateDidChange 回调,并报告状态码 NERtcChannelMediaRelayStateFailure。
自从
V4.5.0
返回
成功返回0,其他则失败

◆ stopScreenCapture

- (int) stopScreenCapture

关闭辅流形式的屏幕共享。
如果您在加入房间后调用该方法关闭辅流,调用成功后,远端触发 onNERtcEngineUserSubStreamDidStop 回调。

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

◆ subscribeAllRemoteAudio:

- (int) subscribeAllRemoteAudio: (BOOL)  subscribe

取消或恢复订阅所有远端用户音频流。

注解
  • 加入房间时,默认订阅所有远端用户的音频,即 setParameters 接口的 KEY_AUTO_SUBSCRIBE_AUDIO 参数默认设置为 true,只有在该参数设置为 false 时,本接口的调用才生效。
  • 该方法加入房间前后都可调用。设置 subscribeAllRemoteAudio 的参数为 YES 后,对后续加入的用户同样生效。
参数
subscribe是否取消订阅所有远端用户的音频流。
返回
操作返回值,成功则返回 0

◆ subscribeRemoteAudio:forUserID:

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

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

注解
该方法需要在加入房间后调用。
自从
V4.5.0
参数
subscribe是否订阅指定音频流。
userID指定远端用户的 ID。
返回
  • 0: 方法调用成功。
  • 30005: 状态异常,可能是自动订阅打开,导致该接口无效。
  • 其他: 方法调用失败。

◆ subscribeRemoteSubStreamVideo:forUserID:

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

订阅或取消订阅远端的屏幕共享辅流视频,订阅之后才能接收远端的辅流视频数据。

注解
  • 纯音频 SDK 禁用该接口,如需使用请前往云信官网下载并替换成视频 SDK。
  • 只能在加入房间后调用。
自从
V4.5.0
参数
subscribe是否订阅远端的屏幕共享辅流视频。
userID远端用户 ID。
返回
操作返回值,成功则返回 0

◆ subscribeRemoteVideo:forUserID:streamType:

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

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

注解
  • 该方法需要在加入房间后调用。
  • 用户加入房间之后,默认不订阅远端用户的视频流。如果希望看到指定远端用户的视频,可以在监听到对方加入房间或发布视频流之后,通过此方法订阅该用户的视频流。
自从
V4.5.0
参数
subscribe是否取消订阅本地视频流。
  • YES:(默认)订阅指定视频流。
  • NO:不订阅指定视频流。
userID指定用户的用户 ID。
streamType订阅的视频流类型,详细信息请参考 NERtcRemoteVideoStreamType
返回
  • 0: 方法调用成功;
  • 其他: 方法调用失败。

◆ takeLocalSnapshot:callback:

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

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

注解

  • 本地主流截图,需要在 startPreview 或者 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 

更新房间推流任务。

注解
  • 该方法仅适用直播场景。
  • 请在房间内调用该方法,该方法在通话中有效。
自从
V4.5.0
参数
taskInfo推流任务信息,详细信息请参考 NERtcLiveStreamTaskInfo
completion操作结果回调,方法调用成功后会触发对应回调。详细信息请参考 NERtcLiveStreamCompletion
返回
操作返回值,成功则返回 0

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