<INERtcChannel>协议 参考

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

#import <INERtcChannel.h>

类 <INERtcChannel> 继承关系图:

构造函数
(int)	- destroy
(int)	- setChannelDelegate:
	设置 channel 的回调。 更多...
(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)	- 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: 回调。

示例代码

NERtcLiveStreamTaskInfo *info = [[NERtcLiveStreamTaskInfo alloc] init];
//info的具体参数详见 NERtcLiveStreamTaskInfo的定义
[[NERtcEngine sharedEngine]  addLiveStreamTask:info compeltion:^(NSString * _Nonnull taskId, kNERtcLiveStreamError errorCode){
    }];

相关回调

调用此接口成功后会触发 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
NERtcChannel *channel = [NERtcEngine sharedEngine] createChannel:@"secondChannel"];
[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
[[NERtcEngine sharedEngine] adjustUserPlaybackSignalVolume:50 forUserID:12345];
//调整uid为12345的用户在本地的播放音量为0，静音该用户 
[[NERtcEngine sharedEngine] 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：关闭双流模式。

示例代码

[[NERtcEngine sharedEngine] 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：关闭本地音频采集。关闭后，远端用户会接收不到本地用户的音频流；但本地用户依然可以接收到远端用户的音频流。

示例代码

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

相关回调

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

相关接口

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：关闭本地视频采集。关闭后，远端用户无法接收到本地用户的视频流；但本地用户仍然可以接收到远端用户的视频流。

示例代码

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

相关回调

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

相关接口

若您希望开启辅流通道的视频采集，请调用 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：关闭本地视频采集。关闭后，远端用户无法接收到本地用户的视频流；但本地用户仍然可以接收到远端用户的视频流。

示例代码

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

相关回调

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

返回

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

enableMediaPub:withMediaType:

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

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

自从

V4.6.10

注解

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

相关接口

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

参数

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

返回

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

getChannelName

- (NSString *) getChannelName

获取当前房间名。

自从

V4.5.0

返回

• 成功：当前 IRtcChannel 房间名。
• 失败：返回空。

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 回调。

示例代码

int result = [[NERtcEngine sharedEngine] 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
}

相关接口

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

相关回调

成功调用该方法加入房间后，远端会触发 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 回调。

示例代码

int result = [[NERtcEngine sharedEngine] 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
}

相关接口

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

相关回调

成功调用该方法加入房间后，远端会触发 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 回调。

示例代码

int result = [[NERtcEngine sharedEngine] 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
}

相关接口

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

相关回调

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

返回

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

leaveChannel

- (int) leaveChannel

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

自从

V3.5.0

调用时机

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

注解

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

示例代码

[[NERtcEngine sharedEngine] leaveChannel];

相关回调

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

返回

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

muteLocalAudio:

- (int) muteLocalAudio:

(BOOL)

muted

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

自从

V3.5.0

调用时机

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

参数说明

参数名称	类型	描述
mute	BOOL	是否关闭本地音频的发送： YES：不发送本地音频。 NO：发送本地音频。

示例代码

//不发送本地音频
[[NERtcEngine sharedEngine] muteLocalAudio:YES];
//发送本地音频
[[NERtcEngine sharedEngine] 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（默认）：恢复发布本地视频流。

示例代码

[[NERtcEngine sharedEngine] 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（默认）：恢复发布本地视频流。

示例代码

//取消发布本地视频主流
[[NERtcEngine sharedEngine] muteLocalVideo:YES streamType:kNERtcStreamChannelTypeMainStream];
//恢复发布本地视频主流
[[NERtcEngine sharedEngine] muteLocalVideo:NO streamType:kNERtcStreamChannelTypeMainStream];
//取消发布本地视频辅流
[[NERtcEngine sharedEngine] muteLocalVideo:YES streamType:kNERtcStreamChannelTypeSubStream];
//恢复发布本地视频辅流
[[NERtcEngine sharedEngine] 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: 回调。

示例代码

[[NERtcEngine sharedEngine]  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。

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	本地摄像头采集配置。

示例代码

NERtcCameraCaptureConfiguration *config = [[NERtcCameraCaptureConfiguration alloc] init];
config.captureWidth = 1280;
config.captureHeight = 720;
[[NERtcEngine sharedEngine] setCameraCaptureConfig:config];

返回

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

setCameraCaptureConfig:streamType:

- (int) setCameraCaptureConfig:		(NERtcCameraCaptureConfiguration *)	config
streamType:		(NERtcStreamChannelType)	streamType

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

自从

V4.6.20

调用时机

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

业务场景

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

注解

调用该接口设置成功后，会自动重启摄像头采集模块。

参数说明

参数名称	类型	描述
config	NERtcCameraCaptureConfiguration	本地摄像头采集配置。
streamType	NERtcStreamChannelType	视频通道类型： kNERtcStreamChannelTypeMainStream：主流。 kNERtcStreamChannelTypeSubStream：辅流。

示例代码

//设置本地摄像头主流采集配置
NERtcCameraCaptureConfiguration *capConfig = [[NERtcCameraCaptureConfiguration alloc] init];
capConfig.captureWidth = 1280;
capConfig.captureHeight = 720;
[[NERtcEngine sharedEngine] setCameraCaptureConfig:capConfig streamType:kNERtcStreamChannelTypeMainStream];
//设置本地摄像头辅流采集配置
NERtcCameraCaptureConfiguration *subCapConfig = [[NERtcCameraCaptureConfiguration alloc] init];
subCapConfig.captureWidth = 1280;
subCapConfig.captureHeight = 720;
[[NERtcEngine sharedEngine] 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

参数

channelDelegate

channel 的回调对象。

返回

操作返回值，成功则返回 0

setClientRole:

- (int) setClientRole:

(NERtcClientRole)

role

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

自从

V3.9.0

使用前提

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

调用时机

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

业务场景

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

注解

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

参数说明

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

示例代码

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

相关回调

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

返回

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

setExternalVideoSource:streamType:

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

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：关闭抢占模式。抢占模式关闭时，如果房间中已有高优先级用户，则本地用户的高优先级设置不生效，仍旧为普通优先级。

示例代码

[[NERtcEngine sharedEngine] setLocalMediaPriority:kNERtcMediaPriorityHigh preemptive:YES];

返回

• 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）：适应区域，视频尺寸等比缩放。保证所有区域被填满，视频超出部分会被裁剪。

示例代码

[[NERtcEngine sharedEngine] setLocalRenderScaleMode:kNERtcVideoRenderScaleFit];

返回

• 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）：适应区域，视频尺寸等比缩放。保证所有区域被填满，视频超出部分会被裁剪。

示例代码

[[NERtcEngine sharedEngine] 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	视频编码属性配置。

示例代码

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

相关接口

若您希望为视频辅流通道设置编码属性，请调用 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：辅流。

示例代码

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

返回

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

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。

示例代码

[[NERtcEngine sharedEngine] 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。

示例代码

[[NERtcEngine sharedEngine] 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

setupLocalSubStreamVideoCanvas:

- (int) setupLocalSubStreamVideoCanvas:

(NERtcVideoCanvas *)

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;
canvas.renderMode = kNERtcVideoRenderScaleFit;
canvas.mirrorMode = kNERtcVideoMirrorModeAuto;
[[NERtcEngine sharedEngine] setupLocalSubStreamVideoCanvas:canvas];

返回

• 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;
canvas.renderMode = kNERtcVideoRenderScaleFit;
canvas.mirrorMode = kNERtcVideoMirrorModeAuto;
[[NERtcEngine sharedEngine] setupLocalVideoCanvas:canvas];

相关接口

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

返回

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

setupRemoteSubStreamVideoCanvas:forUserID:

- (int) setupRemoteSubStreamVideoCanvas:		(NERtcVideoCanvas *)	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;
    canvas.renderMode = kNERtcVideoRenderScaleFit;
    canvas.mirrorMode = kNERtcVideoMirrorModeAuto;
    [[NERtcEngine sharedEngine] 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;
    canvas.renderMode = kNERtcVideoRenderScaleFit;
    canvas.mirrorMode = kNERtcVideoMirrorModeAuto;
    [[NERtcEngine sharedEngine] 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。

示例代码

NERtcVideoSubStreamEncodeConfiguration *config = [[NERtcVideoSubStreamEncodeConfiguration alloc] init];
config.maxProfile = 视频编码的分辨率;
config.minBitrate = 最小编码码率
config.minFrameRate = 最小编码帧率
config.frameRate = 帧率
config.bitrate = 最小编码码率
config.contentPrefer = 屏幕共享功能的编码策略倾向;
[[NERtcEngine sharedEngine] startScreenCapture:config];

相关回调

成功开启屏幕共享辅流后，远端会触发 NERtcChannelDelegate#onNERtcChannelUserSubStreamDidStartWithUserID:subStreamProfile: 回调。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30005（kNERtcErrInvalidState）：状态错误，比如引擎尚未初始化。
  • 50001（kNERtcRuntimeErrVDMNotScreenUseSubStream）：当前使用的非屏幕共享形式的辅流。

stopChannelMediaRelay

- (int) stopChannelMediaRelay

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

自从

V4.2.1

使用前提

请在调用 INERtcChannel#startChannelMediaRelay: 方法开启跨房间媒体流转发之后调用此接口。

调用时机

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

示例代码

[[NERtcEngine sharedEngine] stopChannelMediaRelay];

相关回调

NERtcChannelDelegate#onNERtcChannelMediaRelayStateDidChange:channelName:：跨房间媒体流转发状态发生改变回调。成功调用该方法后会返回 NERtcChannelMediaRelayStateIdle，否则会返回 NERtcChannelMediaRelayStateFailure。 NERtcChannelDelegate#onNERtcChannelDidReceiveChannelMediaRelayEvent:channelName:error:：跨房间媒体流相关转发事件回调。成功调用该方法后会返回 NERtcChannelMediaRelayEventDisconnect，否则会返回 NERtcChannelMediaRelayEventFailure。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：通用错误。
  • 30005（kNERtcErrInvalidState）：状态错误，比如引擎未初始化。

stopScreenCapture

- (int) stopScreenCapture

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

自从

V3.5.0

调用时机

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

示例代码

[[NERtcEngine sharedEngine] 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：取消订阅音频主流。

示例代码

//订阅所有远端用户的音频主流
[[NERtcEngine sharedEngine] subscribeAllRemoteAudio:YES];
//取消订阅所有远端用户的音频主流
[[NERtcEngine sharedEngine] 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的音频主流
[[NERtcEngine sharedEngine] subscribeRemoteAudio:YES forUserID:12345];
//取消订阅对方uid为12345的音频主流
[[NERtcEngine sharedEngine] 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 用户的音频辅流
[[NERtcEngine sharedEngine] subscribeRemoteSubStreamAudio forUserID:userId];
//取消订阅 userId 用户的音频辅流
[[NERtcEngine sharedEngine] subscribeRemoteSubStreamAudio forUserID:userId];

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：操作不支持，比如已开启自动订阅音频辅流。
  • 30005（kNERtcErrInvalidState）：状态错误，比如引擎未初始化。
  • 30105（kNERtcErrUserNotFound）：指定用户尚未加入房间。

subscribeRemoteSubStreamVideo:forUserID:

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

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

自从

V3.9.0

使用前提

• 请先调用 INERtcChannel#setupRemoteSubStreamVideoCanvas:forUserID: 设置远端用户的视频辅流画布。
• 建议在收到远端用户发布视频辅流的回调通知 NERtcChannelDelegate#onNERtcChannelUserSubStreamDidStartWithUserID:subStreamProfile: 后调用此接口。

调用时机

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

注解

纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。

参数说明

参数名称	类型	描述
userID	uint64_t	远端用户 ID。
subsribe	BOOL	是否订阅远端的视频辅流： YES：订阅远端视频辅流。 NO：取消订阅远端视频辅流。

示例代码

[[NERtcEngine sharedEngine] subscribeRemoteSubStreamVideo:YES forUserID:userID];

相关回调

• NERtcChannelDelegate#onNERtcChannelUserSubStreamDidStartWithUserID:subStreamProfile:：远端用户发布视频辅流的回调。
• NERtcChannelDelegate#onNERtcChannelUserSubStreamDidStop:：远端用户停止发布视频辅流的回调。

返回

• 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的大流
[[NERtcEngine sharedEngine] subscribeRemoteVideo:YES forUserID:12345 streamType:kNERtcRemoteVideoStreamTypeHigh];

相关接口

若您希望订阅指定远端用户的视频辅流，请调用 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: 回调。

示例代码

[[NERtcEngine sharedEngine]  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>
  [self getToken];
  [[NERtcEngine sharedEngine] updatePermissionKey:token];

  相关回调

  调用此接口成功更新权限密钥后会触发 NERtcChannelDelegate#onNERtcChannelUpdatePermissionKey:error:timeout: 回调。

  返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal)：通用错误，比如引擎尚未初始化。

---

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

• include/INERtcChannel.h