nertc::IRtcChannel类 参考

#include <nertc_channel.h>

Public 成员函数
virtual void	release ()=0
virtual const char *	getChannelName ()=0
virtual int	setChannelEventHandler (IRtcChannelEventHandler *handler)=0
virtual int	joinChannel (const char *token)=0
virtual int	joinChannel (const char *token, NERtcJoinChannelOptions channel_options)=0
virtual int	leaveChannel ()=0
virtual int	setStatsObserver (IRtcMediaStatsObserver *observer)=0
virtual int	enableLocalAudio (bool enabled)=0
virtual int	enableLocalSubStreamAudio (bool enabled)=0
virtual int	muteLocalAudioStream (bool mute)=0
virtual int	muteLocalSubStreamAudio (bool mute)=0
virtual int	enableLocalVideo (bool enabled)=0
virtual int	enableLocalVideo (NERtcVideoStreamType type, bool enabled)=0
virtual int	muteLocalVideoStream (bool mute)=0
virtual int	muteLocalVideoStream (NERtcVideoStreamType type, bool mute)=0
virtual int	startScreenCaptureByScreenRect (const NERtcRectangle &screen_rect, const NERtcRectangle &region_rect, const NERtcScreenCaptureParameters &capture_params)=0
virtual int	startScreenCaptureByDisplayId (unsigned int display_id, const NERtcRectangle &region_rect, const NERtcScreenCaptureParameters &capture_params)=0
virtual int	startScreenCaptureByWindowId (source_id_t window_id, const NERtcRectangle &region_rect, const NERtcScreenCaptureParameters &capture_params)=0
virtual int	updateScreenCaptureRegion (const NERtcRectangle &region_rect)=0
virtual int	setScreenCaptureMouseCursor (bool capture_cursor)=0
virtual int	stopScreenCapture ()=0
virtual int	pauseScreenCapture ()=0
virtual int	resumeScreenCapture ()=0
virtual int	setExcludeWindowList (source_id_t *window_list, int count)=0
virtual int	updateScreenCaptureParameters (const nertc::NERtcScreenCaptureParameters &captureParams)=0
virtual int	setupLocalVideoCanvas (NERtcVideoCanvas *canvas)=0
virtual int	setupLocalSubStreamVideoCanvas (NERtcVideoCanvas *canvas)=0
virtual int	setLocalRenderMode (NERtcVideoScalingMode scaling_mode)=0
virtual int	setLocalSubStreamRenderMode (NERtcVideoScalingMode scaling_mode)=0
virtual int	setLocalVideoMirrorMode (NERtcVideoMirrorMode mirror_mode)=0
virtual int	setLocalVideoMirrorMode (NERtcVideoStreamType type, NERtcVideoMirrorMode mirror_mode)=0
virtual int	setupRemoteVideoCanvas (uid_t uid, NERtcVideoCanvas *canvas)=0
virtual int	setupRemoteSubStreamVideoCanvas (uid_t uid, NERtcVideoCanvas *canvas)=0
virtual int	setRemoteRenderMode (uid_t uid, NERtcVideoScalingMode scaling_mode)=0
virtual int	setRemoteSubSteamRenderMode (uid_t uid, NERtcVideoScalingMode scaling_mode)=0
virtual int	setClientRole (NERtcClientRole role)=0
virtual int	setLocalMediaPriority (NERtcMediaPriorityType priority, bool is_preemptive)=0
virtual NERtcConnectionStateType	getConnectionState ()=0
virtual int	setCameraCaptureConfig (const NERtcCameraCaptureConfig &config)=0
virtual int	setCameraCaptureConfig (NERtcVideoStreamType type, const NERtcCameraCaptureConfig &config)=0
virtual int	setVideoConfig (const NERtcVideoConfig &config)=0
virtual int	setVideoConfig (NERtcVideoStreamType type, const NERtcVideoConfig &config)=0
virtual int	enableDualStreamMode (bool enable)=0
virtual int	subscribeRemoteAudioStream (uid_t uid, bool subscribe)=0
virtual int	subscribeRemoteSubStreamAudio (uid_t uid, bool subscribe)=0
virtual int	subscribeAllRemoteAudioStream (bool subscribe)=0
virtual int	setAudioSubscribeOnlyBy (uid_t *uid_array, uint32_t size)=0
virtual int	subscribeRemoteVideoStream (uid_t uid, NERtcRemoteVideoStreamType type, bool subscribe)=0
virtual int	subscribeRemoteVideoSubStream (uid_t uid, bool subscribe)=0
virtual int	addLiveStreamTask (const NERtcLiveStreamTaskInfo &info)=0
virtual int	updateLiveStreamTask (const NERtcLiveStreamTaskInfo &info)=0
virtual int	removeLiveStreamTask (const char *task_id)=0
virtual int	sendSEIMsg (const char *data, int length, NERtcVideoStreamType type)=0
virtual int	sendSEIMsg (const char *data, int length)=0
virtual int	setLocalCanvasWatermarkConfigs (NERtcVideoStreamType type, NERtcCanvasWatermarkConfig &config)=0
virtual int	setRemoteCanvasWatermarkConfigs (uid_t uid, NERtcVideoStreamType type, NERtcCanvasWatermarkConfig &config)=0
virtual int	takeLocalSnapshot (NERtcVideoStreamType stream_type, NERtcTakeSnapshotCallback *callback)=0
virtual int	takeRemoteSnapshot (uid_t uid, NERtcVideoStreamType stream_type, NERtcTakeSnapshotCallback *callback)=0
virtual int	adjustUserPlaybackSignalVolume (uid_t uid, int volume)=0
virtual int	adjustChannelPlaybackSignalVolume (uint32_t volume)=0
virtual int	startChannelMediaRelay (NERtcChannelMediaRelayConfiguration *config)=0
virtual int	updateChannelMediaRelay (NERtcChannelMediaRelayConfiguration *config)=0
virtual int	stopChannelMediaRelay ()=0
virtual int	setLocalPublishFallbackOption (NERtcStreamFallbackOption option)=0
virtual int	setRemoteSubscribeFallbackOption (NERtcStreamFallbackOption option)=0
virtual int	setRemoteHighPriorityAudioStream (bool enabled, uid_t uid)=0
virtual int	enableMediaPub (bool enabled, NERtcMediaPubType media_type)=0
virtual int	updatePermissionKey (const char *key)=0

详细描述

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

成员函数说明

addLiveStreamTask()

virtual int nertc::IRtcChannel::addLiveStreamTask ( const NERtcLiveStreamTaskInfo &  info )

pure virtual

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

自从

V3.5.0

使用前提

请先通过 setChannelProfile 接口设置房间模式为直播模式。

调用时机

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

注解

• 仅角色为主播的房间成员能调用此接口，观众成员无相关推流权限。
• 同一个音视频房间（即同一个 channelId）可以创建 6 个不同的推流任务。

参数说明

参数名称	类型	描述
info	NERtcLiveStreamTaskInfo	推流任务信息。

示例代码

NERtcLiveStreamTaskInfo info;
strncpy(info.task_id, "task1", kNERtcMaxTaskIDLength);
strncpy(info.stream_url, "rtmp://pxxxxxx.live.126.net/live/xxxxxx", kNERtcMaxURILength);
info.ls_mode = kNERtcLsModeVideo;
info.server_record_enabled = false;
//扩展推流信息info.config.single_video_passthrough = false;
info.config.audio_bitrate = 64;
info.config.audioCodecProfile = nertc::kNERtcLiveStreamAudioCodecProfileLCAAC;
info.config.channels = 2;
info.config.sampleRate = nertc::kNERtcLiveStreamAudioSampleRate48000;
//流基础信息info.layout.background_color = 0;
info.layout.width = 1280;
info.layout.height = 720;
info.layout.bg_image = nullptr;
//流成员信息
info.layout.user_count = 2;
info.layout.users = new NERtcLiveStreamUserTranscoding[info.layout.user_count];
for (unsigned int i = 0; i < info.layout.user_count; i++) {
info.layout.users[i].uid = 0;
info.layout.users[i].adaption = kNERtcLsModeVideoScaleFit;
info.layout.users[i].video_push = true;
info.layout.users[i].x = 0;
info.layout.users[i].y = 0;
info.layout.users[i].width = 640;
info.layout.users[i].height = 480;
info.layout.users[i].audio_push = true;
info.layout.users[i].z_order = 0;
}
if (rtc_engine_) {
int res = rtc_engine_->addLiveStreamTask(info);
}
delete[] info.layout.users;

相关回调

onAddLiveStreamTask：推流任务已成功添加回调。 onAddLiveStreamTask：推流任务状态已改变回调。

返回

• 0（kNERtcNoError）：方法调用成功；
• 其他：方法调用失败。
  • 403（kNERtcErrChannelReservePermissionDenied）：权限不足，观众模式下不支持此操作。
  • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎尚未初始化。
  • 30101（kNERtcErrChannelNotJoined）：尚未加入房间。

adjustChannelPlaybackSignalVolume()

virtual int nertc::IRtcChannel::adjustChannelPlaybackSignalVolume ( uint32_t  volume )

pure virtual

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

自从

V4.6.50

调用时机

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

注解

• 该方法设置内部引擎为启用状态，在 leaveChannel 后失效，但在本次通话过程中有效

参数说明

参数名称	类型	描述
volume	uint64_t	播放音量，取值范围为 [0,400]。 0：静音。 100：原始音量。 400：最大可为原始音量的 4 倍（自带溢出保护）。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30005（kNERtcErrInvalidState）：状态错误。

adjustUserPlaybackSignalVolume()

virtual int nertc::IRtcChannel::adjustUserPlaybackSignalVolume ( uid_t  uid, int  volume  )

pure virtual

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

自从

V4.2.1

调用时机

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

注解

• 该方法设置内部引擎为启用状态，在 leaveChannel 后失效，但在本次通话过程中有效，比如指定远端用户中途退出房间，则再次加入此房间时仍旧维持该设置。
• 该方法每次只能调整一位远端用户的播放音量，若需调整多位远端用户在本地播放的音量，则需多次调用该方法。

参数说明

参数名称	类型	描述
uid	uid_t	远端用户 ID。
volume	int	播放音量，取值范围为 [0,100]。 0：静音。 100：原始音量。

示例代码

//调整uid为12345的用户在本地的播放音量为50
rtc_engine_->adjustUserPlaybackSignalVolume(12345, 50);
//调整uid为12345的用户在本地的播放音量为0，静音该用户。
rtc_engine_->adjustUserPlaybackSignalVolume(12345, 0);

返回

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

enableDualStreamMode()

virtual int nertc::IRtcChannel::enableDualStreamMode ( bool  enable )

pure virtual

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

自从

V3.5.0

调用时机

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

注解

• 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
• 该方法只对摄像头数据生效，对自定义输入、屏幕共享等视频流无效。
• 该接口的设置会在摄像头重启后生效。

参数说明

参数名称	类型	描述
enable	boolean	是否开启双流模式： true：开启双流模式。 false：关闭双流模式。

示例代码

NERtcEx.getInstance().enableDualStreamMode(true);

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎尚未初始化。

enableLocalAudio()

virtual int nertc::IRtcChannel::enableLocalAudio ( bool  enabled )

pure virtual

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

自从

V3.5.0

调用时机

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

注解

• 加入房间后，语音功能默认为开启状态。
• 该方法设置内部引擎为启用状态，在 leaveChannel 后仍然有效。
• 该方法不影响接收或播放远端音频流，enableLocalAudio(false) 适用于只下行不上行音频流的场景。
• 该方法会操作音频硬件设备，建议避免频繁开关，否则可能导致设备异常。

参数说明

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

示例代码

//打开音频采集
rtc_engine_->enableLocalAudio(true); 
//关闭音频采集
rtc_engine_->enableLocalAudio(false);

相关回调

• 开启音频采集后，远端会触发 onUserAudioStart 回调。
• 关闭音频采集后，远端会触发 onUserAudioStop 回调。

相关接口

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

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30005（kNERtcErrInvalidState）：引擎尚未初始化，或者多房间场景下未在本房间操作。

enableLocalSubStreamAudio()

virtual int nertc::IRtcChannel::enableLocalSubStreamAudio ( bool  enabled )

pure virtual

开启或关闭音频辅流。
开启时远端会收到 onUserSubStreamAudioStart，关闭时远端会收到 onUserSubStreamAudioStop。

注解

该方法设置内部引擎为启用状态，在 leaveChannel 后仍然有效。

自从

V4.6.10

参数

[in]

enabled

是否开启音频辅流。 true: 开启音频辅流。 false: 关闭音频辅流。

返回

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

enableLocalVideo() [1/2]

virtual int nertc::IRtcChannel::enableLocalVideo ( bool  enabled )

pure virtual

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

自从

V3.5.0

调用时机

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

注解

• 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
• 该方法设置内部引擎为开启或关闭状态, 在 leaveChannel 后仍然有效。

参数说明

参数名称	类型	描述
enabled	bool	是否开启本地视频采集与发送： true：开启本地视频采集。 false：关闭本地视频采集，此时不需要本地有摄像头。关闭后，远端用户无法接收到本地用户的视频流；但本地用户仍然可以接收到远端用户的视频流。

示例代码

//打开视频
rtc_engine_->enableLocalVideo(true);
//关闭视频
rtc_engine_->enableLocalVideo(false);

相关回调

• 开启本地视频采集后，远端会收到 onUserVideoStart 回调。
• 关闭本地视频采集后，远端会收到 onUserVideoStop 回调。

相关接口

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

返回

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

enableLocalVideo() [2/2]

virtual int nertc::IRtcChannel::enableLocalVideo ( NERtcVideoStreamType  type, bool  enabled  )

pure virtual

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

自从

V4.6.20

调用时机

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

注解

• 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
• 该方法仅适用于视频主流，若您希望开启辅流通道的视频采集，请调用 enableLocalVideo 方法。
• 该方法设置内部引擎为开启或关闭状态, 在 leaveChannel 后仍然有效。

参数说明

参数名称	类型	描述
type	NERtcVideoStreamType	视频通道类型： kNERTCVideoStreamMain：主流。 kNERTCVideoStreamSub：辅流。
enabled	bool	是否开启本地视频采集与发送： true：开启本地视频采集。 false：关闭本地视频采集，此时不需要本地有摄像头。关闭后，远端用户无法接收到本地用户的视频流；但本地用户仍然可以接收到远端用户的视频流。

示例代码

//打开视频主流
nertc::NERtcVideoStreamType type = nertc::NERtcVideoStreamType::kNERTCVideoStreamMain;
bool enable = true;
rtc_engine_->enableLocalVideo(type, enable);
//关闭视频主流
nertc::NERtcVideoStreamType type = nertc::NERtcVideoStreamType::kNERTCVideoStreamMain;
bool enable = false;
rtc_engine_->enableLocalVideo(type, enable);
//打开视频辅流
nertc::NERtcVideoStreamType type = nertc::NERtcVideoStreamType::kNERTCVideoStreamSub;
bool enable = true;
rtc_engine_->enableLocalVideo(type, enable);
//关闭视频辅流
nertc::NERtcVideoStreamType type = nertc::NERtcVideoStreamType::kNERTCVideoStreamSub;
bool enable = false;
rtc_engine_->enableLocalVideo(type, enable);

相关回调

• type 为 kNERTCVideoStreamMain（主流）时：
  • 开启本地视频采集后，远端会收到 onUserVideoStart 回调。
  • 关闭本地视频采集后，远端会收到 onUserVideoStop 回调。
• streamType 为 kNERtcVideoStreamTypeSub（辅流）时：
  • 开启本地视频采集后，远端会收到 onUserSubStreamVideoStart 回调。
  • 关闭本地视频采集后，远端会收到 onUserSubStreamVideoStop 回调。

返回

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

enableMediaPub()

virtual int nertc::IRtcChannel::enableMediaPub ( bool  enabled, NERtcMediaPubType  media_type  )

pure virtual

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

自从

V4.6.10

注解

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

相关接口

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

参数

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

返回

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

getChannelName()

virtual const char* nertc::IRtcChannel::getChannelName ( )

pure virtual

获取当前房间名。

自从

V4.5.0

返回

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

getConnectionState()

virtual NERtcConnectionStateType nertc::IRtcChannel::getConnectionState ( )

pure virtual

获取当前房间连接状态。

自从

V4.5.0

返回

房间连接状态。::NERtcConnectionStateType.

joinChannel() [1/2]

virtual int nertc::IRtcChannel::joinChannel ( const char *  token )

pure virtual

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

自从

V3.5.0

调用时机

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

注解

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

参数说明

参数名称	类型	描述
token	const char	安全认证签名（NERTC Token），可以设置为： null。调试模式下可设置为 null。安全性不高，建议在产品正式上线前在云信控制台中将鉴权方式恢复为默认的安全模式。 已获取的 NERTC Token。安全模式下必须设置为获取到的 Token 。若未传入正确的 Token 将无法进入房间。推荐使用安全模式。

示例代码

rtc_engine_->joinChannel(token);

相关接口

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

相关回调

• 成功调用该方法加入房间后，本地会触发 onJoinChannel 回调，远端会触发 onUserJoined 回调。
• 在弱网环境下，若客户端和服务器失去连接，SDK 会自动重连，并在自动重连成功后触发 onRejoinChannel 回调。

返回

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

joinChannel() [2/2]

virtual int nertc::IRtcChannel::joinChannel ( const char *  token, NERtcJoinChannelOptions  channel_options  )

pure virtual

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

自从

V3.5.0

调用时机

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

注解

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

参数说明

参数名称	类型	描述
token	const char	安全认证签名（NERTC Token），可以设置为： null。调试模式下可设置为 null。安全性不高，建议在产品正式上线前在云信控制台中将鉴权方式恢复为默认的安全模式。 已获取的 NERTC Token。安全模式下必须设置为获取到的 Token 。若未传入正确的 Token 将无法进入房间。推荐使用安全模式。
channel_options	NERtcJoinChannelOptions	加入房间时设置一些特定的房间参数。默认值为 nil。

示例代码

rtc_engine_->joinChannel(token);

相关接口

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

相关回调

• 成功调用该方法加入房间后，本地会触发 onJoinChannel 回调，远端会触发 onUserJoined 回调。
• 在弱网环境下，若客户端和服务器失去连接，SDK 会自动重连，并在自动重连成功后触发 onRejoinChannel 回调。

返回

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

leaveChannel()

virtual int nertc::IRtcChannel::leaveChannel ( )

pure virtual

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

自从

V3.5.0

调用时机

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

注解

• 结束通话时必须调用此方法离开房间，否则无法开始下一次通话。
• 该方法是异步操作，调用返回时并没有真正退出频道。在真正退出房间后，SDK 会触发 onLeaveChannel 回调。
• 如果在调用 leaveChannel 后立即调用 release 方法，可能会无法正常离开房间；建议您在收到 onLeaveChannel 回调之后再调用 release 方法释放会话相关所有资源。

示例代码

rtc_engine_->leaveChannel();

相关回调

成功调用该方法离开房间后，本地会触发 onLeaveChannel 回调，远端会触发 onUserLeft 回调。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：正在进行网络探测。
  • 30005（kNERtcErrInvalidState)：状态错误，比如引擎尚未初始化。
  • 30101（kNERtcErrChannelNotJoined）：尚未加入房间。
  • 30102（kNERtcErrChannelRepleatedlyLeave）：重复离开房间。
  • 30104（kNERtcErrSessionNotFound）：会话未找到。

muteLocalAudioStream()

virtual int nertc::IRtcChannel::muteLocalAudioStream ( bool  mute )

pure virtual

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

自从

V3.5.0

调用时机

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

注解

该方法设置内部引擎为启用状态，在 leaveChannel 后恢复至默认（非静音）。

参数说明

参数名称	类型	描述
mute	bool	是否关闭本地音频的发送： true：不发送本地音频。 false：发送本地音频。

示例代码

//不发送本地音频
rtc_engine_->muteLocalAudioStream(false);
//发送本地音频
rtc_engine_->muteLocalAudioStream(true);

相关回调

若本地用户在说话，成功调用该方法后，房间内其他用户会收到 onUserAudioMute 回调。

相关接口

enableMediaPub：

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

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30005（kNERtcErrInvalidState）：引擎未初始化。
  • 30107（kNERtcErrMediaNotStarted）：媒体会话未建立，比如对端未开启音频流。
  • 30200（kNERtcErrConnectionNotFound）: 连接未建立。
  • 30203（kNERtcErrTrackNotFound）：音频 track 未找到。
  • 30300：Transceiver 未找到。
  • 30400：未找到对应房间。

muteLocalSubStreamAudio()

virtual int nertc::IRtcChannel::muteLocalSubStreamAudio ( bool  mute )

pure virtual

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

注解

• 该方法仅可在加入房间后调用。
• 静音状态会在通话结束后被重置为非静音。

自从

V4.6.10

参数

mute	是否静音本地音频辅流发送。 true（默认）：静音本地音频辅流。 false: 取消静音本地音频辅流。

返回

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

muteLocalVideoStream() [1/2]

virtual int nertc::IRtcChannel::muteLocalVideoStream ( bool  mute )

pure virtual

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

自从

V3.5.0

使用前提

一般在通过 enableLocalVideo (true) 接口开启本地视频采集并发送后调用该方法。

调用时机

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

注解

• 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
• 调用该方法取消发布本地视频流时，设备仍然处于工作状态。
• 该方法设置内部引擎为启用状态，在 nertc::IRtcChannel::leaveChannel "leaveChannel" 后设置失效，将恢复至默认，即默认发布本地视频流。
• 该方法与 enableLocalVideo (false) 的区别在于，后者会关闭本地摄像头设备，该方法不禁用摄像头，不会影响本地视频流采集且响应速度更快。

参数说明

参数名称	类型	描述
mute	bool	是否取消发布本地视频流： true：取消发布本地视频流。 false：恢复发布本地视频流。

示例代码

if (rtc_engine_) {
int res = rtc_engine_->muteLocalVideoStream(true);
}

相关回调

取消发布本地视频主流或辅流后，远端会收到 onUserVideoMute 回调。

返回

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

muteLocalVideoStream() [2/2]

virtual int nertc::IRtcChannel::muteLocalVideoStream ( NERtcVideoStreamType  type, bool  mute  )

pure virtual

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

自从

V4.6.20

使用前提

一般在通过 enableLocalVideo (true) 接口开启本地视频采集并发送后调用该方法。

调用时机

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

注解

• 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
• 调用该方法取消发布本地视频流时，设备仍然处于工作状态。
• 若调用该方法取消发布本地视频流，通话结束后会被重置为默认状态，即默认发布本地视频流。
• 该方法与 enableLocalVideo (false) 的区别在于，后者会关闭本地摄像头设备，该方法不禁用摄像头，不会影响本地视频流采集且响应速度更快。

参数说明

参数名称	类型	描述
type	NERtcVideoStreamType	视频通道类型： kNERTCVideoStreamMain：主流。 kNERTCVideoStreamSub：辅流。
mute	bool	是否取消发布本地视频流： true：取消发布本地视频流。 false：恢复发布本地视频流。

示例代码

//取消发布本地视频主流
nertc::NERtcVideoStreamType type = nertc::NERtcVideoStreamType::kNERTCVideoStreamMain;
bool mute = true;
rtc_engine_->muteLocalVideoStream(type, mute);
//恢复发布本地视频主流
nertc::NERtcVideoStreamType type = nertc::NERtcVideoStreamType::kNERTCVideoStreamMain;
bool mute = false;
rtc_engine_->muteLocalVideoStream(type, mute);
//取消发布本地视频辅流
nertc::NERtcVideoStreamType type = nertc::NERtcVideoStreamType::kNERTCVideoStreamSub;
bool mute = true;
rtc_engine_->muteLocalVideoStream(type, mute);
//恢复发布本地视频辅流
nertc::NERtcVideoStreamType type = nertc::NERtcVideoStreamType::kNERTCVideoStreamSub;
bool mute = false;
rtc_engine_->muteLocalVideoStream(type, mute);

相关回调

取消发布本地视频主流或辅流后，远端会收到 onUserVideoMute 回调。

返回

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

pauseScreenCapture()

virtual int nertc::IRtcChannel::pauseScreenCapture ( )

pure virtual

暂停屏幕共享。

• 暂停屏幕共享后，共享区域内会持续显示暂停前的最后一帧画面，直至通过 resumeScreenCapture 恢复屏幕共享。
• 在 Windows 平台中，本端会触发 onScreenCaptureStatus 回调。

自从

V4.5.0

返回

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

release()

virtual void nertc::IRtcChannel::release ( )

pure virtual

销毁 IRtcChannel 实例，释放资源。

自从

V4.5.0

removeLiveStreamTask()

virtual int nertc::IRtcChannel::removeLiveStreamTask ( const char *  task_id )

pure virtual

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

自从

V3.5.0

使用前提

请先调用 addLiveStreamTask 方法添加推流任务。

调用时机

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

注解

• 仅角色为主播的房间成员能调用此接口，观众成员无相关推流权限。
• 通话结束，房间成员全部离开房间后，推流任务会自动删除；如果房间内还有用户存在，则需要创建推流任务的用户删除推流任务。

参数说明

参数名称	类型	描述
task_id	const char*	推流任务 ID。

示例代码

if (rtc_engine_) {
    return rtc_engine_->removeLiveStreamTask(task_id);
}
NERtcEx.getInstance().removeLiveStreamTask(taskInfo.taskId,deleteCallback);

相关回调

onRemoveLiveStreamTask：推流任务已成功删除回调。 onLiveStreamState：推流任务状态已改变回调。

返回

• 0（kNERtcNoError）：方法调用成功；
• 其他：方法调用失败。
  • 403（kNERtcErrChannelReservePermissionDenied）：权限不足，观众模式下不支持此操作。
  • 30005（kNERtcErrChannelNotJoined）：状态错误，比如引擎尚未初始化。
  • 30101（kNERtcErrChannelNotJoined）：尚未加入房间。

resumeScreenCapture()

virtual int nertc::IRtcChannel::resumeScreenCapture ( )

pure virtual

恢复屏幕共享。
在 Windows 平台中，远端会触发 onScreenCaptureStatus 回调。

自从

V4.5.0

返回

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

sendSEIMsg() [1/2]

virtual int nertc::IRtcChannel::sendSEIMsg ( const char *  data, int  length  )

pure virtual

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

• 调用时机：视频流（主流）开启后，可调用此函数。
• 数据长度限制： SEI 最大数据长度为 4096 字节，超限会发送失败。如果频繁发送大量数据会导致视频码率增大，可能会导致视频画质下降甚至卡顿。
• 发送频率限制：最高为视频发送的帧率，建议不超过 10 次/秒。
• 生效时间：调用本接口之后，最快在下一帧视频数据帧之后发送 SEI 数据，最慢在接下来的 5 帧视频之后发送。

注解

• SEI 数据跟随视频帧发送，由于在弱网环境下可能丢帧，SEI 数据也可能随之丢失，所以建议在发送频率限制之内多次发送，保证接收端收到的概率。
• 调用本接口时，默认使用主流通道发送 SEI。

自从

V4.5.0

参数

data	自定义 SEI 数据。
length	自定义 SEI 数据长度，最大不超过 4096 字节。

注解

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

返回

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

• 成功: 成功进入待发送队列，会在最近的视频帧之后发送该数据
• 失败: 数据被限制发送，可能发送的频率太高，队列已经满了，或者数据大小超过最大值 4k

sendSEIMsg() [2/2]

virtual int nertc::IRtcChannel::sendSEIMsg ( const char *  data, int  length, NERtcVideoStreamType  type  )

pure virtual

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

• 调用时机：视频流（主流）开启后，可调用此函数。
• 数据长度限制： SEI 最大数据长度为 4096 字节，超限会发送失败。如果频繁发送大量数据会导致视频码率增大，可能会导致视频画质下降甚至卡顿。
• 发送频率限制：最高为视频发送的帧率，建议不超过 10 次/秒。
• 生效时间：调用本接口之后，最快在下一帧视频数据帧之后发送 SEI 数据，最慢在接下来的 5 帧视频之后发送。

注解

• SEI 数据跟随视频帧发送，由于在弱网环境下可能丢帧，SEI 数据也可能随之丢失，所以建议在发送频率限制之内多次发送，保证接收端收到的概率。
• 调用本接口时，默认使用主流通道发送 SEI。

自从

V4.5.0

参数

data	自定义 SEI 数据。
length	自定义 SEI 数据长度，最大不超过 4096 字节。
type	发送 SEI 时，使用的流通道类型。详细信息请参考 NERtcVideoStreamType 。

返回

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

• 成功: 成功进入待发送队列，会在最近的视频帧之后发送该数据
• 失败: 数据被限制发送，可能发送的频率太高，队列已经满了，或者数据大小超过最大值 4k

setAudioSubscribeOnlyBy()

virtual int nertc::IRtcChannel::setAudioSubscribeOnlyBy ( uid_t *  uid_array, uint32_t  size  )

pure virtual

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

注解

• 此接口需要在加入房间成功后调用。
• 对于调用接口时不在房间的 uid 不生效。

自从

V4.6.10

参数

[in]

uid_array

可订阅自己音频的用户uid 列表。

注解

此列表为全量列表。如果列表为空或 null，表示其他所有人均可订阅自己的音频。

参数

[in]

size

uid_array 的数组长度。

返回

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

setCameraCaptureConfig() [1/2]

virtual int nertc::IRtcChannel::setCameraCaptureConfig ( const NERtcCameraCaptureConfig &  config )

pure virtual

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

自从

V4.5.0

调用时机

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

业务场景

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

注解

• 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
• 该方法仅适用于视频主流，若您希望为辅流通道设置摄像头的采集配置，请调用 nertc::IRtcChannel::setCameraCaptureConfig(NERtcVideoStreamType type, const NERtcCameraCaptureConfig& config)} "setCameraCaptureConfig" 方法。
• 该方法支持在加入房间后动态调用，设置成功后，会自动重启摄像头采集模块。
• 若系统相机不支持您设置的分辨率，会自动调整为最相近一档的分辨率，因此建议您设置为常规标准的分辨率。
• 设置较高的采集分辨率会增加性能消耗，例如 CPU 和内存占用等，尤其是在开启视频前处理的场景下。

参数说明

参数名称	类型	描述
captureConfig	NERtcCameraCaptureConfig	本地摄像头采集配置。

示例代码

nertc::NERtcCameraCaptureConfig capture_config;
capture_config.captureWidth = w;
capture_config.captureHeight = h;
if (rtc_engine_) {
    rtc_engine_->setCameraCaptureConfig(capture_config);
}

返回

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

setCameraCaptureConfig() [2/2]

virtual int nertc::IRtcChannel::setCameraCaptureConfig ( NERtcVideoStreamType  type, const NERtcCameraCaptureConfig &  config  )

pure virtual

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

自从

V4.6.20

调用时机

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

业务场景

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

注解

• 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
• 调用该接口设置成功后，会自动重启摄像头采集模块。

参数说明

参数名称	类型	描述
type	NERtcVideoStreamType	视频通道类型： kNERtcVideoStreamMain：主流。 kNERtcVideoStreamSub：辅流。
captureConfig	NERtcCameraCaptureConfig	本地摄像头采集配置。

示例代码

//设置本地摄像头主流采集配置
nertc::NERtcVideoStreamType type = nertc::NERtcVideoStreamType::kNERTCVideoStreamMain;
nertc::NERtcCameraCaptureConfig video_config_ = {};
video_config_.captureWidth = 1920; // 编码分辨率的宽
video_config_.captureHeight = 1080; // 编码分辨率的高
setCameraCaptureConfig(type, video_config_);
//设置本地摄像头辅流采集配置
nertc::NERtcVideoStreamType type = nertc::NERtcVideoStreamType::kNERTCVideoStreamSub;
nertc::NERtcCameraCaptureConfig video_config_ = {};
video_config_.captureWidth = 1920; // 编码分辨率的宽
video_config_.captureHeight = 1080; // 编码分辨率的高
setCameraCaptureConfig(type, video_config_);

返回

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

setChannelEventHandler()

virtual int nertc::IRtcChannel::setChannelEventHandler ( IRtcChannelEventHandler *  handler )

pure virtual

设置 IRtcChannel 对象的事件句柄。
你可以通过设置的事件句柄，监听当前IRtcChannel对象对应房间的事件，并接收房间中用户视频信息等。

自从

V4.5.0

参数

[in]

handler

事件监听句柄对象

返回

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

setClientRole()

virtual int nertc::IRtcChannel::setClientRole ( NERtcClientRole  role )

pure virtual

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

自从

V3.9.0

使用前提

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

调用时机

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

业务场景

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

注解

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

参数说明

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

示例代码

//切换用户角色为主播
rtc_engine_->setClientRole(nertc::kNERtcClientRoleBroadcaster);
//切换用户角色为观众
rtc_engine_->setClientRole(nertc::kNERtcClientRoleAudience);

相关回调

• 加入房间前调用该方法设置用户角色，不会触发任何回调，在加入房间成功后角色自动生效：
  • 设置用户角色为主播：加入房间后，远端用户触发 onUserJoined 回调。
  • 设置用户角色为观众：加入房间后，远端用户不触发任何回调。
• 加入房间后调用该方法切换用户角色：
  • 从观众角色切为主播：本端用户触发 onClientRoleChanged 回调，远端用户触发 onUserJoined 回调。
  • 从主播角色切为观众：本端用户触发 onClientRoleChanged 回调，远端用户触发 onUserleft 回调。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal)：引擎未创建成功。
  • 30005（kNERtcErrInvalidState)：当前状态不支持的操作，不支持切换角色（主播/观众）。
  • 30101（kNERtcErrChannelNotJoined): 尚未加入房间。

setExcludeWindowList()

virtual int nertc::IRtcChannel::setExcludeWindowList ( source_id_t *  window_list, int  count  )

pure virtual

设置共享整个屏幕或屏幕指定区域时，需要屏蔽的窗口列表。
开启屏幕共享时，可以通过 NERtcScreenCaptureParameters 设置需要屏蔽的窗口列表；开发者可以在开启屏幕共享后，通过此方法动态调整需要屏蔽的窗口列表。被屏蔽的窗口不会显示在屏幕共享区域中。

注解

• 在 Windows 平台中，该接口在屏幕共享过程中可动态调用；在 macOS 平台中，该接口自 V4.6.0 开始支持在屏幕共享过程中动态调用。
• 在 Windows 平台中，某些窗口在被屏蔽之后，如果被置于图层最上层，此窗口图像可能会黑屏。此时会触发 onScreenCaptureStatus.kScreenCaptureStatusCovered 回调，建议应用层在触发此回调时提醒用户将待分享的窗口置于最上层。

自从

V4.5.0

参数

window_list	需要屏蔽的窗口 ID 列表。
count	需屏蔽的窗口的数量。

返回

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

setLocalCanvasWatermarkConfigs()

virtual int nertc::IRtcChannel::setLocalCanvasWatermarkConfigs ( NERtcVideoStreamType  type, NERtcCanvasWatermarkConfig &  config  )

pure virtual

添加本地视频画布水印。

注解

• setLocalCanvasWatermarkConfigs 方法作用于本地视频画布，不影响视频流。画布被移除时，水印也会自动移除。
• 设置水印之前，需要先通过画布相关方法设置画布。
• macOS 暂不支持水印相关方法。

自从

V4.5.0

参数

type	视频流类型。支持设置为主流或辅流。详细信息请参考 NERtcVideoStreamType 。
config	画布水印设置。支持设置文字水印、图片水印和时间戳水印，设置为 null 表示清除水印。 详细信息请参考 NERtcCanvasWatermarkConfig 。

返回

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

setLocalMediaPriority()

virtual int nertc::IRtcChannel::setLocalMediaPriority ( NERtcMediaPriorityType  priority, bool  is_preemptive  )

pure virtual

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

自从

V4.2.0

调用时机

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

注解

• 一个音视频房间中只有一个高优先级的用户。建议房间中只有一位用户调用 setLocalMediaPriority 将本端媒体流设为高优先级，否则需要开启抢占模式，保证本地用户的高优先级设置生效。
• 调用 switchChannel 方法快速切换房间后，媒体优先级会恢复为默认值，即普通优先级。

参数说明

参数名称	类型	描述
priority	NERtcMediaPriorityType	本地用户的媒体流优先级，默认为 kNERtcMediaPriorityNormal，即普通优先级。
is_preemptive	bool	是否开启抢占模式，默认为 NO，即不开启： true：开启抢占模式。抢占模式开启时，本地用户可以抢占其他用户的高优先级，被抢占的用户的媒体优先级变为普通优先级，在抢占者退出房间后，其他用户的优先级仍旧维持普通优先级。 false：关闭抢占模式。抢占模式关闭时，如果房间中已有高优先级用户，则本地用户的高优先级设置不生效，仍旧为普通优先级。

示例代码

nertc::NERtcMediaPriorityType priority = nertc::kNERtcMediaPriorityNormal；
bool is_preemptive = false;
rtc_engine_->setLocalMediaPriority(priority, is_preemptive);

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30005（kNERtcErrInvalidState）：状态错误，比如引擎尚未初始化或者已经加入房间。

setLocalPublishFallbackOption()

virtual int nertc::IRtcChannel::setLocalPublishFallbackOption ( NERtcStreamFallbackOption  option )

pure virtual

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

• SDK 会在上行弱网且音视频质量严重受影响时，自动关断视频流，尽量保证音频质量。
• 同时 SDK 会持续监控网络质量，并在网络质量改善时恢复音视频流。
• 当本地发布的音视频流回退为音频流时，或由音频流恢复为音视频流时，SDK 会触发本地发布的媒体流已回退为音频流 onLocalPublishFallbackToAudioOnly 回调。

注解

请在加入房间（joinChannel）前调用此方法。

自从

V4.5.0

参数

option

发布音视频流的回退选项，默认为不开启回退 kNERtcStreamFallbackAudioOnly。详细信息请参考 nertc::NERTCStreamFallbackOption 。

返回

0 

方法调用成功，其他调用失败

setLocalRenderMode()

virtual int nertc::IRtcChannel::setLocalRenderMode ( NERtcVideoScalingMode  scaling_mode )

pure virtual

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

自从

V3.5.0

调用时机

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

注解

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

参数说明

参数名称	类型	描述
scaling_mode	int	视频显示模式类型： kNERtcVideoScaleFit（0）:适应视频，视频尺寸等比缩放。优先保证视频内容全部显示。若视频尺寸与显示视窗尺寸不一致，视窗未被填满的区域填充背景色。 kNERtcVideoScaleFullFill（1）：视频尺寸非等比缩放。保证视频内容全部显示，且填满视窗。 kNERtcVideoScaleCropFill（2）：适应区域，视频尺寸等比缩放。保证所有区域被填满，视频超出部分会被裁剪。

示例代码

rtc_engine_->setLocalRenderMode(nertc::kNERtcVideoScaleFit);

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎尚未初始化。

setLocalSubStreamRenderMode()

virtual int nertc::IRtcChannel::setLocalSubStreamRenderMode ( NERtcVideoScalingMode  scaling_mode )

pure virtual

设置本端的屏幕共享辅流视频显示模式。
该方法设置本地视图显示模式。 App 可以多次调用此方法更改显示模式。

注解

调用此方法前，必须先通过 setupLocalSubStreamVideoCanvas 设置本地辅流画布。

自从

V4.5.0

参数

[in]

scaling_mode

视频显示模式。

返回

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

setLocalVideoMirrorMode() [1/2]

virtual int nertc::IRtcChannel::setLocalVideoMirrorMode ( NERtcVideoMirrorMode  mirror_mode )

pure virtual

设置本地视频镜像模式。
该方法用于设置本地视频是否开启镜像模式，即画面是否左右翻转。

注解

• 该方法仅适用于视频主流，若您希望设置视频辅流的镜像模式，请调用 IRtcChannel::setLocalVideoMirrorMode(NERtcVideoStreamType type, NERtcVideoMirrorMode mirror_mode "setLocalVideoMirrorMode" 方法。
• 该方法用于 setupLocalVideoCanvas 之后。
• 本地的视频镜像模式仅影响本地用户所见，不影响远端用户所见。App 可以多次调用此方法更改镜像模式。

自从

V4.5.0

参数

[in]

mirror_mode

视频镜像模式。详细信息请参考 NERtcVideoMirrorMode。

返回

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

setLocalVideoMirrorMode() [2/2]

virtual int nertc::IRtcChannel::setLocalVideoMirrorMode ( NERtcVideoStreamType  type, NERtcVideoMirrorMode  mirror_mode  )

pure virtual

设置本地视频镜像模式。
通过此接口可以设置本地视频是否开启镜像模式，即画面是否左右翻转。

自从

V4.6.20

使用前提

请在通过 setupLocalVideoCanvas 接口设置本地视频画布后调用该方法。

调用时机

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

注解

• 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
• 本地视频画布的镜像模式仅影响本地用户所见，不影响远端用户所见。您的应用层可以多次调用此方法更改镜像模式。

参数说明

参数名称	类型	描述
type	NERtcVideoStreamType	视频通道类型： kNERtcVideoStreamMain：主流。 kNERtcVideoStreamSub：辅流。
mirror_mode	NERtcVideoMirrorMode	视频镜像模式： kNERtcVideoMirrorModeAuto：由 SDK 决定是否启用镜像模式。 kNERtcVideoMirrorModeEnabled：启用镜像模式。 kNERtcVideoMirrorModeDisabled（默认）：关闭镜像模式。

示例代码

//设置本地视频主流的镜像模式
nertc::NERtcVideoStreamType type = nertc::NERtcVideoStreamType::kNERTCVideoStreamMain;
nertc::NERtcVideoMirrorMode mirror_mode = kNERtcVideoMirrorModeEnabled;
coreEngine->setLocalVideoMirrorMode(type, mirror_mode);
//设置本地视频辅流的镜像模式
nertc::NERtcVideoStreamType type = nertc::NERtcVideoStreamType::kNERTCVideoStreamMain;
nertc::NERtcVideoMirrorMode mirror_mode = kNERtcVideoMirrorModeEnabled;
coreEngine->setLocalVideoMirrorMode(type, mirror_mode);

相关接口

• setupLocalVideoCanvas：通过此接口也设置本地视频画布的镜像模式，不影响远端用户所见。
• setupRemoteVideoCanvas：通过此接口设置远端用户视频画布的镜像模式，不影响远端用户所见。
• setVideoConfig：通过此接口设置本地视频的镜像模式，影响远端用户看到的视频画面。

返回

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

setRemoteCanvasWatermarkConfigs()

virtual int nertc::IRtcChannel::setRemoteCanvasWatermarkConfigs ( uid_t  uid, NERtcVideoStreamType  type, NERtcCanvasWatermarkConfig &  config  )

pure virtual

添加远端视频画布水印。

自从

V4.2.0

使用前提

请先调用 setupRemoteVideoCanvas 或 setupRemoteSubStreamVideoCanvas 方法设置远端用户的视频画布。

调用时机

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

注解

• 该方法仅适用于 Windows 平台。
• 该方法仅作用于远端视频画布，不影响视频流。画布被移除时，水印也会自动移除。

参数说明

参数名称	类型	描述
uid	uid_t	远端用户 ID。
type	NERtcVideoStreamType	视频通道类型： kNERtcVideoStreamMain：主流。 kNERtcVideoStreamSub：辅流。
config	NERtcCanvasWatermarkConfig	画布水印设置。支持设置文字水印、图片水印和时间戳水印，设置为 NULL 表示清除水印。

示例代码

uint64_t uid = 999;
nertc::NERtcVideoStreamType type = nertc::kNERTCVideoStreamMain；
NERtcCanvasWatermarkConfig watermark;
memset(&watermark, 0, sizeof(watermark));
rtc_engine_->setRemoteCanvasWatermarkConfigs(uid, type, watermark);

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：未找到画布。

setRemoteHighPriorityAudioStream()

virtual int nertc::IRtcChannel::setRemoteHighPriorityAudioStream ( bool  enabled, uid_t  uid  )

pure virtual

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

注解

• 该接口需要通话中设置，并需要自动订阅打开（默认打开）。
• 该接口只能设置一个用户的优先级，后设置的会覆盖之前的设置。
• 该接口通话结束后，优先级设置重置。

参数

[in]	enabled	是否设置音频订阅优先级。 true：设置音频订阅优先级。 false：取消设置音频订阅优先级。
[in]	uid	用户 ID

返回

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

setRemoteRenderMode()

virtual int nertc::IRtcChannel::setRemoteRenderMode ( uid_t  uid, NERtcVideoScalingMode  scaling_mode  )

pure virtual

设置远端视图显示模式。 该方法设置远端视图显示模式。App 可以多次调用此方法更改显示模式。

自从

V4.5.0

参数

[in]	uid	远端用户 ID。
[in]	scaling_mode	视频显示模式: NERtcVideoScalingMode

返回

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

setRemoteSubscribeFallbackOption()

virtual int nertc::IRtcChannel::setRemoteSubscribeFallbackOption ( NERtcStreamFallbackOption  option )

pure virtual

设置弱网条件下订阅的音视频流回退选项。
弱网环境下，订阅的音视频质量会下降。使用该接口并将 option 设置为 kNERtcStreamFallbackVideoStreamLow 或者 kNERtcStreamFallbackAudioOnly 后：

• SDK 会在下行弱网且音视频质量严重受影响时，将视频流切换为小流，或关断视频流，从而保证或提高通信质量。
• SDK 会持续监控网络质量，并在网络质量改善时自动恢复音视频流。
• 当远端订阅流回退为音频流时，或由音频流恢复为音视频流时，SDK 会触发远端订阅流已回退为音频流 onRemoteSubscribeFallbackToAudioOnly 回调。

注解

请在加入房间（joinChannel）前调用此方法。

自从

V4.5.0

参数

option

订阅音视频流的回退选项，默认为弱网时回退到视频小流 kNERtcStreamFallbackVideoStreamLow。详细信息请参考 nertc::NERTCStreamFallbackOption 。

返回

0 

方法调用成功，其他调用失败

setRemoteSubSteamRenderMode()

virtual int nertc::IRtcChannel::setRemoteSubSteamRenderMode ( uid_t  uid, NERtcVideoScalingMode  scaling_mode  )

pure virtual

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

自从

V4.5.0

参数

[in]	uid	远端用户 ID。
[in]	scaling_mode	视频显示模式。

返回

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

setScreenCaptureMouseCursor()

virtual int nertc::IRtcChannel::setScreenCaptureMouseCursor ( bool  capture_cursor )

pure virtual

在共享屏幕或窗口时，更新是否显示鼠标。

自从

V4.6.10

参数

capture_cursor

屏幕共享时是否捕捉鼠标光标。 true：共享屏幕时显示鼠标。 false：共享屏幕时不显示鼠标。

返回

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

setStatsObserver()

virtual int nertc::IRtcChannel::setStatsObserver ( IRtcMediaStatsObserver *  observer )

pure virtual

注册统计信息观测器。

自从

V4.5.0

参数

[in]

observer

统计信息观测器

返回

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

setupLocalSubStreamVideoCanvas()

virtual int nertc::IRtcChannel::setupLocalSubStreamVideoCanvas ( NERtcVideoCanvas *  canvas )

pure virtual

设置本地辅流视频画布。

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

  自从

  V4.5.0

  参数

  [in]

  canvas

  视频画布信息。

  返回

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

setupLocalVideoCanvas()

virtual int nertc::IRtcChannel::setupLocalVideoCanvas ( NERtcVideoCanvas *  canvas )

pure virtual

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

自从

V3.5.0

调用时机

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

注解

• 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
• 在实际业务中，通常建议在初始化后即调用该方法进行本地视图设置，然后再加入房间或开启预览；若您开发的是 macOS 平台的 App，若使用的是外部渲染，必须在初始化 SDK 时设置本地视图。

参数说明

参数名称	类型	描述
canvas	NERtcVideoCanvas	本地用户视频的画布。设置为 NULL 表示取消并释放已设置的画布，详细信息请参考 NERtcVideoCanvas。

示例代码

nertc::NERtcVideoCanvas canvas;
canvas.cb = nullptr;
canvas.user_data = nullptr;
canvas.window = window;
canvas.scaling_mode = nertc::kNERtcVideoScaleFit;
canvas.mirror_mode = nertc::kNERtcVideoMirrorModeAuto;
rtc_engine_->setupLocalVideoCanvas(canvas)

相关接口

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

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：画布创建失败。

setupRemoteSubStreamVideoCanvas()

virtual int nertc::IRtcChannel::setupRemoteSubStreamVideoCanvas ( uid_t  uid, NERtcVideoCanvas *  canvas  )

pure virtual

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

自从

V3.9.0

使用前提

建议在收到远端用户加入房间的 onUserJoined 回调后，再调用此接口通过回调返回的 uid 设置对应视图。

调用时机

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

注解

• 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
• 退出房间后，SDK 会清除远端用户和画布的的绑定关系，该设置自动失效。
• 若您使用的是 macOS 平台，请注意不要动态切换画布，若您移除画布，SDK 会自动停止订阅对应用户的视频流；若您修改画布，可能无法正常生效。

参数说明

参数名称	类型	描述
canvas	NERtcVideoCanvas*	视频画布。详细信息请参考 NERtcVideoCanvas。
uid	uid_t	远端用户 ID。

示例代码

nertc::NERtcVideoCanvas canvas;
canvas.cb = onRemoteFrameDataCallback;//回调和窗口 2选1，全部不填代表移除
canvas.user_data = nullptr;
canvas.window = window;
if (rtc_engine_) {
ret = rtc_engine_->setupRemoteSubStreamVideoCanvas(uid, &canvas);
}

相关接口

可以调用 setRemoteRenderMode 方法在通话过程中更新远端用户视图的渲染模式。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30004（kNERtcErrNotSupported）：不支持的操作，比如纯音频 SDK 不支持该功能。

setupRemoteVideoCanvas()

virtual int nertc::IRtcChannel::setupRemoteVideoCanvas ( uid_t  uid, NERtcVideoCanvas *  canvas  )

pure virtual

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

自从

V3.5.0

调用时机

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

注解

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

参数说明

参数名称	类型	描述
canvas	NERtcVideoCanvas	远端用户视频的画布。
uid	uid_t	远端用户的 ID。可以在 onUserJoined 回调中获取。

示例代码

nertc::NERtcVideoCanvas canvas;
canvas.cb = nullptr;
canvas.user_data = nullptr;
canvas.window = window;
canvas.scaling_mode = nertc::kNERtcVideoScaleFit; 
canvas.mirror_mode  = nertc::kNERtcVideoMirrorModeAuto;
rtc_engine_->setupRemoteVideoCanvas(uid, canvas);

相关接口

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

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：画布创建失败。
  • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎尚未初始化。

setVideoConfig() [1/2]

virtual int nertc::IRtcChannel::setVideoConfig ( const NERtcVideoConfig &  config )

pure virtual

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

自从

V3.5.0

调用时机

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

注解

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

参数说明

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

示例代码

nertc::NERtcVideoConfig video_config_ = {};
video_config_.width = 1920; // 编码分辨率的宽
video_config_.height = 1080; // 编码分辨率的高
video_config_.mirror_mode = nertc::kNERtcVideoMirrorModeAuto; // 视频镜像模式
video_config_.orientation_mode = nertc::kNERtcVideoOutputOrientationModeAdaptative; // 视频旋转的方向模式。
video_config_.max_profile = nertc::kNERtcVideoProfileHD1080P; // 视频编码配置
video_config_.crop_mode_ = nertc::kNERtcVideoCropModeDefault;//裁剪模式
video_config_.bitrate = 0; // 视频编码的码率
video_config_.min_bitrate = 0;//视频编码的最小码率
video_config_.framerate = 30; // 视频编码的帧率
video_config_.min_framerate = 2;// 视频编码的最小帧率
video_config_.degradation_preference = nertc::kNERtcDegradationDefault;// 带宽受限时的视频编码降级偏好
setVideoConfig(video_config_);

相关接口

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

返回

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

setVideoConfig() [2/2]

virtual int nertc::IRtcChannel::setVideoConfig ( NERtcVideoStreamType  type, const NERtcVideoConfig &  config  )

pure virtual

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

自从

V4.6.20

调用时机

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

注解

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

参数说明

参数名称	类型	描述
type	NERtcVideoStreamType	视频通道类型： kNERTCVideoStreamMain：主流。 kNERTCVideoStreamSub：辅流。
config	NERtcVideoConfig	视频编码属性配置。

示例代码

nertc::NERtcVideoConfig video_config_ = {};
video_config_.width = 1920; // 编码分辨率的宽
video_config_.height = 1080; // 编码分辨率的高
video_config_.mirror_mode = nertc::kNERtcVideoMirrorModeAuto; // 视频镜像模式
video_config_.orientation_mode = nertc::kNERtcVideoOutputOrientationModeAdaptative; // 视频旋转的方向模式。
video_config_.max_profile = nertc::kNERtcVideoProfileHD1080P; // 视频编码配置
video_config_.crop_mode_ = nertc::kNERtcVideoCropModeDefault;//裁剪模式
video_config_.bitrate = 0; // 视频编码的码率
video_config_.min_bitrate = 0;//视频编码的最小码率
video_config_.framerate = 30; // 视频编码的帧率
video_config_.min_framerate = 2;// 视频编码的最小帧率
video_config_.degradation_preference = nertc::kNERtcDegradationDefault;// 带宽受限时的视频编码降级偏好
setVideoConfig(nertc::kNERTCVideoStreamMain, video_config_);

返回

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

startChannelMediaRelay()

virtual int nertc::IRtcChannel::startChannelMediaRelay ( NERtcChannelMediaRelayConfiguration *  config )

pure virtual

开始跨房间媒体流转发。

• 该方法可用于实现跨房间连麦等场景。支持同时转发到 4 个房间，同一个房间可以有多个转发进来的媒体流。
• 成功调用该方法后，SDK 会触发 onMediaRelayStateChanged 和 onMediaRelayEvent 回调，并在回调中报告当前的跨房间媒体流转发状态和事件。

  注解

• 请在成功加入房间后调用该方法。调用此方法前需要通过 NERtcChannelMediaRelayConfiguration 中的 dest_infos 设置目标房间。
• 该方法仅对直播场景下的主播角色有效。
• 成功调用该方法后，若您想再次调用该方法，必须先调用 stopChannelMediaRelay 方法退出当前的转发状态。
• 成功开始跨房间转发媒体流后，如果您需要修改目标房间，例如添加或删减目标房间等，可以调用方法 updateChannelMediaRelay 更新目标房间信息。

  自从

  V4.5.0

  参数

  config

  跨房间媒体流转发参数配置信息。

  返回

  成功返回0，其他则失败

startScreenCaptureByDisplayId()

virtual int nertc::IRtcChannel::startScreenCaptureByDisplayId ( unsigned int  display_id, const NERtcRectangle &  region_rect, const NERtcScreenCaptureParameters &  capture_params  )

pure virtual

通过指定屏幕 ID 开启屏幕共享，屏幕共享内容以辅流形式发送。
此方法调用成功后，远端触发 onUserSubStreamVideoStart 回调。

注解

• 该方法仅适用于 macOS。Windows 平台请使用方法 startScreenCaptureByScreenRect。
• 该方法需要在加入房间后设置。

自从

V4.5.0

参数

display_id	指定待共享的屏幕 ID。开发者需要自行实现枚举屏幕 ID 的方法，并通过该参数指定需要共享的屏幕。
region_rect	指定待共享的区域相对于整个窗口的位置。如果设置的共享区域超出了窗口的边界，则只共享窗口内的内容；如果宽或高为 0，则共享整个窗口。
capture_params	屏幕共享的参数配置，包括码率、帧率、编码策略、屏蔽窗口列表等。

返回

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

startScreenCaptureByScreenRect()

virtual int nertc::IRtcChannel::startScreenCaptureByScreenRect ( const NERtcRectangle &  screen_rect, const NERtcRectangle &  region_rect, const NERtcScreenCaptureParameters &  capture_params  )

pure virtual

开启屏幕共享，共享范围为指定屏幕的指定区域。
调用该方法时，可以选择共享整个虚拟屏、指定屏幕，或虚拟屏、整个屏幕的某些区域范围。
此方法调用成功后，远端触发 onUserSubStreamVideoStart 和 setExcludeWindowList 回调。

注解

• 该方法仅适用于 Windows。macOS 平台请使用方法 startScreenCaptureByDisplayId。
• 该方法需要在加入房间后调用。

自从

V4.5.0

参数

screen_rect	指定待共享的屏幕相对于虚拟屏的位置。
region_rect	指定待共享区域相对于整个屏幕屏幕的位置。如果设置的共享区域超出了屏幕的边界，则只共享屏幕内的内容；如果将 width 或 height 设为 0, 则共享整个屏幕。
capture_params	屏幕共享的编码参数配置。

返回

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

startScreenCaptureByWindowId()

virtual int nertc::IRtcChannel::startScreenCaptureByWindowId ( source_id_t  window_id, const NERtcRectangle &  region_rect, const NERtcScreenCaptureParameters &  capture_params  )

pure virtual

通过指定窗口 ID 开启屏幕共享，屏幕共享内容以辅流形式发送。
调用该方法时需要指定待共享的屏幕 ID，共享该屏幕的整体画面或指定区域。
此方法调用成功后：

• Windows 平台远端触发 onUserSubStreamVideoStop 和 onScreenCaptureStatus 回调。
• macOS 平台远端触发 onUserSubStreamVideoStop 回调。

  注解

• 该方法适用于 Windows 和 macOS。
• 该方法需要在加入房间后调用。

  自从

  V4.5.0

  参数

  window_id	指定待共享的窗口 ID。
  region_rect	指定待共享的区域相对于整个窗口的位置。如果设置的共享区域超出了窗口的边界，则只共享指定区域中窗口内的内容；如果宽或高为 0，则共享整个窗口。
  capture_params	屏幕共享的参数配置，包括码率、帧率、编码策略、屏蔽窗口列表等。

  返回

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

stopChannelMediaRelay()

virtual int nertc::IRtcChannel::stopChannelMediaRelay ( )

pure virtual

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

自从

V4.3.0

使用前提

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

调用时机

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

示例代码

rtc_engine_->stopChannelMediaRelay();

相关回调

onMediaRelayStateChanged：跨房间媒体流转发状态发生改变回调。成功调用该方法后会返回 MEDIARELAY_STATE_IDLE，否则会返回 MEDIARELAY_STATE_FAILURE。 onMediaRelayEvent：跨房间媒体流相关转发事件回调。成功调用该方法后会返回 MEDIARELAY_EVENT_DISCONNECT，否则会返回 MEDIARELAY_EVENT_FAILURE。

返回

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

stopScreenCapture()

virtual int nertc::IRtcChannel::stopScreenCapture ( )

pure virtual

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

自从

V3.5.0

调用时机

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

示例代码

rtc_engine_->stopScreenCapture();

相关回调

成功调用此方法后，本端会触发 onScreenCaptureStatus 回调（仅 Windwos 平台），远端会触发 onUserSubStreamVideoStop 回调。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30005（kNERtcErrInvalidState）：引擎未初始化或未开启屏幕共享。
  • 30022（kErrorDesktopCaptureNotReady）：未找到正在共享目标源或未开启屏幕共享。
  • 30101（kErrorRoomNotJoined）：未加入房间。
  • 30200（kErrorConnectionNotFound）：未找到信令连接。
  • 30203（kErrorTrackNotFound）：轨道错误。
  • 30300（kErrorTransceiverNotFound）：收发器错误。
  • 30400（kErrorRtcRoomNotFound）：未找到对应房间。

subscribeAllRemoteAudioStream()

virtual int nertc::IRtcChannel::subscribeAllRemoteAudioStream ( bool  subscribe )

pure virtual

取消或恢复订阅所有远端用户的音频主流。
加入房间时，默认订阅所有远端用户的音频主流，即 setParameters 方法的 KEY_AUTO_SUBSCRIBE_AUDIO 参数默认设置为 true；只有当该参数的设置为 false 时，此接口的调用才会生效。

自从

V4.5.0

调用时机

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

业务场景

适用于重要会议需要一键全体静音的场景。

注解

• 设置该方法的 subscribe 参数为 true 后，对后续加入房间的用户同样生效。
• 在开启自动订阅（默认）时，设置该方法的 subscribe 参数为 false 可以实现取消订阅所有远端用户的音频流，但此时无法再调用 subscribeRemoteAudioStream 方法单独订阅指定远端用户的音频流。

参数说明

参数名称	类型	描述
subscribe	bool	是否订阅所有用户的音频主流： true：订阅音频主流。 false：取消订阅音频主流。

示例代码

//订阅所有远端用户的音频主流
rtc_engine_->subscribeAllRemoteAudioStream(true);
//取消订阅所有远端用户的音频主流
rtc_engine_->subscribeAllRemoteAudioStream(false);

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30005（kNERtcErrInvalidState)：引擎未初始化。
  • 30026：ASL 选路功能启用失败。
  • 30400：Transceiver 未找到。

subscribeRemoteAudioStream()

virtual int nertc::IRtcChannel::subscribeRemoteAudioStream ( uid_t  uid, bool  subscribe  )

pure virtual

取消或恢复订阅所有远端用户的音频主流。
加入房间时，默认订阅所有远端用户的音频主流，即 setParameters 方法的 KEY_AUTO_SUBSCRIBE_AUDIO 参数默认设置为 true；只有当该参数的设置为 false 时，此接口的调用才会生效。

自从

V4.5.0

调用时机

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

业务场景

适用于重要会议需要一键全体静音的场景。

注解

设置该方法的 subscribe 参数为 true 后，对后续加入房间的用户同样生效。 在开启自动订阅（默认）时，设置该方法的 subscribe 参数为 false 可以实现取消订阅所有远端用户的音频流，但此时无法再调用 subscribeRemoteAudioStream 方法单独订阅指定远端用户的音频流。

参数说明

参数名称	类型	描述
subscribe	bool	是否订阅所有用户的音频主流： true：订阅音频主流。 false：取消订阅音频主流。

示例代码

//订阅所有远端用户的音频主流
rtc_engine_->subscribeAllRemoteAudioStream(true);
//取消订阅所有远端用户的音频主流
rtc_engine_->subscribeAllRemoteAudioStream(false);

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30005（kNERtcErrInvalidState）：引擎尚未初始化或尚未加入房间。
  • 30008（kNERtcErrDeviceNotFound：设备未找到。
  • 30015（kNERtcErrConnectFail )：服务器连接错误。
  • 30101（kNERtcErrChannelNotJoined)：尚未加入房间。
  • 30105（kNERtcErrUserNotFound）：未找到指定用户。
  • 30106（kNERtcErrInvalidUserID）：非法指定用户，比如订阅了本端。
  • 30200（kNERtcErrConnectionNotFound）：未连接成功。

subscribeRemoteSubStreamAudio()

virtual int nertc::IRtcChannel::subscribeRemoteSubStreamAudio ( uid_t  uid, bool  subscribe  )

pure virtual

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

自从

V4.6.10

调用时机

请在引擎初始化之后调用此接口，且该方法仅可在加入房间且收到远端用户开启音频辅流的回调 onUserSubStreamAudioStart 后调用。

注解

• 加入房间时，默认订阅所有远端用户的音频流。
• 请在指定远端用户加入房间后再调用此方法。

参数说明

参数名称	类型	描述
uid	uid_t	远端用户 ID。
subscribe	bool	是否订阅指定音频辅流： true：订阅指定音频辅流。 false：取消订阅指定音频辅流。

示例代码

//订阅对方音频辅流
rtc_engine_->subscribeRemoteSubStreamAudio(uid, true);
//取消订阅对方音频辅流
rtc_engine_->subscribeRemoteSubStreamAudio(uid, false);

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30005（kNERtcErrInvalidState）：状态错误，比如引擎未初始化。
  • 30101（kNERtcErrChannelNotJoined)：尚未加入房间。
  • 30105（kNERtcErrUserNotFound）：指定用户尚未加入房间。
  • 30106（kNERtcErrInvalidUserID）：非法的用户 ID。
  • 30200（kNERtcErrConnectionNotFound）：媒体会话未建立，比如指定用户尚未发布音频辅流。

subscribeRemoteVideoStream()

virtual int nertc::IRtcChannel::subscribeRemoteVideoStream ( uid_t  uid, NERtcRemoteVideoStreamType  type, bool  subscribe  )

pure virtual

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

自从

V3.5.0

调用时机

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

参数说明

参数名称	类型	描述
uid	uid_t	指定用户的 ID。
streamType	NERtcRemoteVideoStreamType	订阅的视频流类型： kNERtcRemoteVideoStreamTypeHigh：高清画质的大流。 kNERtcRemoteVideoStreamTypeLow：低清画质的小流。 kNERtcRemoteVideoStreamTypeNone：不订阅。
subscribe	bool	是否订阅远端用户的视频流： true：订阅指定视频流。 false：不订阅指定视频流。

示例代码

//订阅对方uid为12345的大流
rtc_engine_->subscribeRemoteVideoStream(12345, nertc::kNERtcRemoteVideoStreamTypeHigh,true);

相关接口

若您希望订阅指定远端用户的视频辅流，请调用 subscribeRemoteVideoSubStream} 方法。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：画布为空对象，创建远端 peerconnection 失败。
  • 30005（kNERtcErrInvalidState)：状态错误，比如引擎尚未初始化。
  • 30009（kNERtcErrInvalidDeviceSourceID）：设备 ID 非法。
  • 30105（kNERtcErrUserNotFound）：未找到指定用户。
  • 30106（kNERtcErrInvalidUserID）：非法指定用户，比如订阅了本端。
  • 30107（kNERtcErrMediaNotStarted）：媒体会话未建立，比如对端未开启视频主流。
  • 30108（kNERtcErrSourceNotFound）：媒体源未找到，比如对端未开启视频主流。

subscribeRemoteVideoSubStream()

virtual int nertc::IRtcChannel::subscribeRemoteVideoSubStream ( uid_t  uid, bool  subscribe  )

pure virtual

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

自从

V3.9.0

使用前提

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

调用时机

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

注解

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

参数说明

参数名称	类型	描述
uid	uid_t	远端用户 ID。
subsribe	bool	是否订阅远端的视频辅流： true：订阅远端视频辅流。 false：取消订阅远端视频辅流。

示例代码

(rtc_engine_) {
nertc::NERtcVideoCanvas canvas;
canvas.window = window;
ret = rtc_engine_->setupRemoteSubStreamVideoCanvas(uid, canvas);
ret = rtc_engine_->subscribeRemoteVideoSubStream(uid, true);
}

相关回调

• onUserSubStreamVideoStart ：远端用户发布视频辅流的回调。
• onUserSubStreamVideoStop：远端用户停止发布视频辅流的回调。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30004（kNERtcErrNotSupported）：不支持的操作。
  • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎尚未初始化。
  • 30105（kNERtcErrUserNotFound）：未找到该远端用户，可能对方还未加入房间。

takeLocalSnapshot()

virtual int nertc::IRtcChannel::takeLocalSnapshot ( NERtcVideoStreamType  stream_type, NERtcTakeSnapshotCallback *  callback  )

pure virtual

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

注解

• 本地主流截图，需要在 startPreview 或者 enableLocalVideo 并 joinChannel 成功之后调用。
• 本地辅流截图，需要在 startScreenCapture 并 joinChannel 成功之后调用。
• 同时设置文字、时间戳或图片水印时，如果不同类型的水印位置有重叠，会按照图片、文本、时间戳的顺序进行图层覆盖。

自从

V4.5.0

参数

stream_type	截图的视频流类型。支持设置为主流或辅流。详细信息请参考 NERtcVideoStreamType 。
callback	截图回调。详细信息请参考 NERtcTakeSnapshotCallback 。

返回

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

takeRemoteSnapshot()

virtual int nertc::IRtcChannel::takeRemoteSnapshot ( uid_t  uid, NERtcVideoStreamType  stream_type, NERtcTakeSnapshotCallback *  callback  )

pure virtual

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

注解

• takeRemoteSnapshot 需要在收到 onUserVideoStart 与 onUserSubStreamVideoStart 回调之后调用。
• 同时设置文字、时间戳或图片水印时，如果不同类型的水印位置有重叠，会按照图片、文本、时间戳的顺序进行图层覆盖。

自从

V4.5.0

参数

uid	远端用户 ID。
stream_type	截图的视频流类型。支持设置为主流或辅流。详细信息请参考 NERtcVideoStreamType 。
callback	截图回调。详细信息请参考 NERtcTakeSnapshotCallback 。

返回

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

updateChannelMediaRelay()

virtual int nertc::IRtcChannel::updateChannelMediaRelay ( NERtcChannelMediaRelayConfiguration *  config )

pure virtual

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

• 成功开始跨房间转发媒体流后，如果您需要修改目标房间，例如添加或删减目标房间等，可以调用此方法。
• 成功调用该方法后，SDK 会触发 onMediaRelayStateChange 和 onMediaRelayEvent 回调，并在回调中报告当前的跨房间媒体流转发状态和事件。

  注解

  请在加入房间并成功调用 startChannelMediaRelay 开始跨房间媒体流转发后，调用此方法。调用此方法前需要通过 NERtcChannelMediaRelayConfiguration 中的 dest_infos 设置目标房间。

  自从

  V4.5.0

  参数

  config

  目标房间配置信息

  返回

  成功返回0，其他则失败

updateLiveStreamTask()

virtual int nertc::IRtcChannel::updateLiveStreamTask ( const NERtcLiveStreamTaskInfo &  info )

pure virtual

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

自从

V3.5.0

使用前提

请先调用 addLiveStreamTask} 方法添加推流任务。

调用时机

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

注解

仅角色为主播的房间成员能调用此接口，观众成员无相关推流权限。

参数说明

参数名称	类型	描述
info	NERtcLiveStreamTaskInfo	推流任务信息。

示例代码

if (rtc_engine_) {
    return rtc_engine_->updateLiveStreamTask(info);
}

相关回调

onUpdateLiveStreamTask：推流任务已成功更新回调。 onAddLiveStreamTask：推流任务状态已改变回调。

返回

• 0（kNERtcNoError）：方法调用成功；
• 其他：方法调用失败。
  • 403（kNERtcErrChannelReservePermissionDenied）：权限不足，观众模式下不支持此操作。
  • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎尚未初始化。
  • 30101（kNERtcErrChannelNotJoined）：尚未加入房间。

updatePermissionKey()

virtual int nertc::IRtcChannel::updatePermissionKey ( const char *  key )

pure virtual

更新权限密钥。

• 通过本接口可以实现当用户权限被变更，或者收到权限密钥即将过期的回调 onPermissionKeyWillExpire 时，更新权限密钥。

  自从

  V4.6.29

  使用前提

  请确保已开通高级 Token 鉴权功能，具体请联系网易云信商务经理。

  调用时机

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

  业务场景

  适用于变更指定用户加入、创建房间或上下麦时发布流相关权限的场景。

  参数说明

  参数名称	类型	描述
  key	const char*	新的权限密钥。

  
  

  示例代码

  if (rtc_engine_) {
  std::string key;//向服务器请求得到的权限key，具体请参考官方文档的高级 Token 鉴权章节。</a>
  rtc_engine_->updatePermissionKey(key.c_str()));    if (kNERtcNoError != res) {
  }

  相关回调

  调用此接口成功更新权限密钥后会触发 onUpdatePermissionKey 回调。

  返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30003（kNERtcErrInvalidParam）：参数错误，比如 key 无效。
  • 30005（kNERtcErrInvalidState)：当前状态不支持的操作，比如引擎尚未初始化。

updateScreenCaptureParameters()

virtual int nertc::IRtcChannel::updateScreenCaptureParameters ( const nertc::NERtcScreenCaptureParameters &  captureParams )

pure virtual

更新屏幕共享参数。
开始共享屏幕或窗口后，动态更新采集帧率，目标码率，编码分辨率等屏幕共享相关参数。

自从

V4.6.20

调用时机

请在加入房间并成功开启屏幕共享后调用该方法。

注解

• 调用该方法会重新启动屏幕共享，因此建议不要频繁调用。
• 可以通过该方法动态设置是否捕捉鼠标（capture_mouse_cursor）和设置排除窗口（excluded_window_list，excluded_window_count），同时这两项设置也可以通过 setScreenCaptureMouseCursor 和 setExcludeWindowList 方法实现。

参数说明

参数名称	类型	描述
captureParams	NERtcScreenCaptureParameters	屏幕共享编码参数配置。

示例代码

//调用该方法时，需要维护一个 nertc::NERtcScreenCaptureParameters captureParams 变量记录当前设置。更新设置的时候：
nertc::NERtcScreenCaptureParameters captureParams;
captureParams.field1 = new_value1;
captureParams.field2 = new_value2;
...
updateScreenCaptureParameters(captureParams);

相关回调

成功调用该方法后，会触发 onScreenCaptureStatus 回调。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30005（kErrorErrInvalidState）：多房间状态错误。
  • 30021（kNERtcErrDesktopCaptureInvalidParam）：传入的参数无效。
  • 30101（kNERtcErrChannelNotJoined）：未加入房间。

updateScreenCaptureRegion()

virtual int nertc::IRtcChannel::updateScreenCaptureRegion ( const NERtcRectangle &  region_rect )

pure virtual

在共享屏幕或窗口时，更新共享的区域。
在 Windows 平台中，远端会触发 onScreenCaptureStatus 回调。

自从

V4.5.0

参数

region_rect

指定待共享的区域相对于整个窗口或屏幕的位置。如果设置的共享区域超出了边界，则只共享指定区域中，窗口或屏幕内的内容；如果宽或高为 0，则共享整个窗口或屏幕。

返回

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

---

该类的文档由以下文件生成:

• api/nertc_channel.h