nertc::IRtcEngineEx类 参考

#include <nertc_engine_ex.h>

类 nertc::IRtcEngineEx 继承关系图:

Public 成员函数
virtual IRtcChannel *	createChannel (const char *channel_name)=0
virtual NERtcConnectionStateType	getConnectionState ()=0
virtual int	muteLocalAudioStream (bool mute)=0
virtual int	enableLocalSubStreamAudio (bool enabled)=0
virtual int	muteLocalSubStreamAudio (bool mute)=0
virtual int	setAudioProfile (NERtcAudioProfileType profile, NERtcAudioScenarioType scenario)=0
virtual int	setAudioEffectPreset (NERtcVoiceChangerType type)=0
virtual int	setVoiceBeautifierPreset (NERtcVoiceBeautifierType type)=0
virtual int	setLocalVoicePitch (double pitch)=0
virtual int	setLocalVoiceEqualization (NERtcVoiceEqualizationBand band_frequency, int band_gain)=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 void	setStreamAlignmentProperty (bool enable)=0
virtual int64_t	getNtpTimeOffset ()=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	setupLocalSubStreamVideoCanvas (NERtcVideoCanvas *canvas)=0
virtual int	setLocalSubStreamRenderMode (NERtcVideoScalingMode scaling_mode)=0
virtual int	setLocalRenderMode (NERtcVideoScalingMode scaling_mode)=0
virtual int	setLocalVideoMirrorMode (NERtcVideoMirrorMode mirror_mode)=0
virtual int	setLocalVideoMirrorMode (NERtcVideoStreamType type, NERtcVideoMirrorMode mirror_mode)=0
virtual int	setRemoteRenderMode (uid_t uid, NERtcVideoScalingMode scaling_mode)=0
virtual int	setupRemoteSubStreamVideoCanvas (uid_t uid, NERtcVideoCanvas *canvas)=0
virtual int	subscribeRemoteVideoSubStream (uid_t uid, bool subscribe)=0
virtual int	setRemoteSubSteamRenderMode (uid_t uid, NERtcVideoScalingMode scaling_mode)=0
virtual int	startVideoPreview ()=0
virtual int	startVideoPreview (NERtcVideoStreamType type)=0
virtual int	stopVideoPreview ()=0
virtual int	stopVideoPreview (NERtcVideoStreamType type)=0
virtual int	muteLocalVideoStream (bool mute)=0
virtual int	muteLocalVideoStream (NERtcVideoStreamType type, bool mute)=0
virtual int	setLocalMediaPriority (NERtcMediaPriorityType priority, bool is_preemptive)=0
virtual int	setParameters (const char *parameters)=0
virtual int	setRecordingAudioFrameParameters (NERtcAudioFrameRequestFormat *format)=0
virtual int	setPlaybackAudioFrameParameters (NERtcAudioFrameRequestFormat *format)=0
virtual int	setMixedAudioFrameParameters (int sample_rate)=0
virtual int	setAudioFrameObserver (INERtcAudioFrameObserver *observer)=0
virtual int	startAudioDump ()=0
virtual int	startAudioDump (NERtcAudioDumpType type)=0
virtual int	stopAudioDump ()=0
virtual int	startAudioMixing (NERtcCreateAudioMixingOption *option)=0
virtual int	stopAudioMixing ()=0
virtual int	pauseAudioMixing ()=0
virtual int	resumeAudioMixing ()=0
virtual int	setAudioMixingSendVolume (uint32_t volume)=0
virtual int	getAudioMixingSendVolume (uint32_t *volume)=0
virtual int	setAudioMixingPlaybackVolume (uint32_t volume)=0
virtual int	getAudioMixingPlaybackVolume (uint32_t *volume)=0
virtual int	getAudioMixingDuration (uint64_t *duration)=0
virtual int	getAudioMixingCurrentPosition (uint64_t *position)=0
virtual int	setAudioMixingPosition (uint64_t seek_position)=0
virtual int	playEffect (uint32_t effect_id, NERtcCreateAudioEffectOption *option)=0
virtual int	stopEffect (uint32_t effect_id)=0
virtual int	stopAllEffects ()=0
virtual int	pauseEffect (uint32_t effect_id)=0
virtual int	resumeEffect (uint32_t effect_id)=0
virtual int	pauseAllEffects ()=0
virtual int	resumeAllEffects ()=0
virtual int	setEffectSendVolume (uint32_t effect_id, uint32_t volume)=0
virtual int	getEffectSendVolume (uint32_t effect_id, uint32_t *volume)=0
virtual int	setEffectPlaybackVolume (uint32_t effect_id, uint32_t volume)=0
virtual int	getEffectPlaybackVolume (uint32_t effect_id, uint32_t *volume)=0
virtual int	setAudioMixingPitch (int32_t pitch)=0
virtual int	getAudioMixingPitch (int32_t *pitch)=0
virtual int	setEffectPitch (uint32_t effect_id, int32_t pitch)=0
virtual int	getEffectPitch (uint32_t effect_id, int32_t *pitch)=0
virtual int	enableLoopbackRecording (bool enabled, const char *device_name)=0
virtual int	adjustLoopbackRecordingSignalVolume (int volume)=0
virtual int	enableEarback (bool enabled, uint32_t volume)=0
virtual int	setEarbackVolume (uint32_t volume)=0
virtual int	setStatsObserver (IRtcMediaStatsObserver *observer)=0
virtual int	setVideoEncoderQosObserver (INERtcVideoEncoderQosObserver *observer)=0
virtual int	setPreDecodeObserver (INERtcPreDecodeObserver *observer)=0
virtual int	enableAudioVolumeIndication (bool enable, uint64_t interval)=0
virtual int	enableAudioVolumeIndication (bool enable, uint64_t interval, bool enable_vad)=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	setExternalVideoSource (bool enabled)=0
virtual int	setExternalVideoSource (NERtcVideoStreamType type, bool enabled)=0
virtual int	pushExternalVideoFrame (NERtcVideoFrame *frame)=0
virtual int	pushExternalVideoFrame (NERtcVideoStreamType type, NERtcVideoFrame *frame)=0
virtual int	pushExternalVideoEncodedFrame (NERtcVideoStreamType type, NERtcVideoEncodedFrame *encoded_frame)=0
virtual int	setExternalAudioSource (bool enabled, int sample_rate, int channels)=0
virtual int	pushExternalAudioFrame (NERtcAudioFrame *frame)=0
virtual int	pushExternalAudioEncodedFrame (NERtcAudioEncodedFrame *encoded_frame)=0
virtual int	setExternalSubStreamAudioSource (bool enabled, int sample_rate, int channels)=0
virtual int	pushExternalSubStreamAudioFrame (NERtcAudioFrame *frame)=0
virtual int	pushExternalSubStreamAudioEncodedFrame (NERtcAudioEncodedFrame *encoded_frame)=0
virtual int	setExternalAudioRender (bool enabled, int sample_rate, int channels)=0
virtual int	pullExternalAudioFrame (void *data, int len)=0
virtual const char *	getVersion (int *build)=0
virtual const char *	getErrorDescription (int error_code)=0
virtual void	uploadSdkInfo ()=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	setLocalVideoWatermarkConfigs (bool enabled, NERtcVideoStreamType type, NERtcVideoWatermarkConfig &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	startAudioRecording (const char *file_path, int sample_rate, NERtcAudioRecordingQuality quality)=0
virtual int	startAudioRecordingWithConfig (const NERtcAudioRecordingConfiguration &config)=0
virtual int	stopAudioRecording ()=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	enableSuperResolution (bool enable)=0
virtual int	enableEncryption (bool enable, NERtcEncryptionConfig config)=0
virtual int	startLastmileProbeTest (const NERtcLastmileProbeConfig &config)=0
virtual int	stopLastmileProbeTest ()=0
virtual int	setRemoteHighPriorityAudioStream (bool enabled, uid_t uid)=0
virtual int	checkNECastAudioDriver ()=0
virtual int	enableVirtualBackground (bool enabled, VirtualBackgroundSource backgroundSource)=0
virtual int	setCloudProxy (int proxyType)=0
virtual int	startBeauty (const char *file_path)=0
virtual void	stopBeauty ()=0
virtual void	enableBeauty (bool enabled)=0
virtual void	enableBeautyMirrorMode (bool enabled)=0
virtual float	getBeautyEffect (NERtcBeautyEffectType type)=0
virtual int	setBeautyEffect (NERtcBeautyEffectType type, float level)=0
virtual int	addBeautyFilter (const char *file_path)=0
virtual int	removeBeautyFilter ()=0
virtual int	setBeautyFilterLevel (float level)=0
virtual int	addBeautySticker (const char *file_path)=0
virtual int	removeBeautySticker ()=0
virtual int	addBeautyMakeup (const char *file_path)=0
virtual int	removeBeautyMakeup ()=0
virtual int	setLocalVoiceReverbParam (NERtcReverbParam &param)=0
virtual int	enableMediaPub (bool enabled, NERtcMediaPubType media_type)=0
virtual int	updatePermissionKey (const char *key)=0
virtual int	setEffectPosition (uint32_t effect_id, uint64_t timestamp_ms)=0
virtual int	getEffectCurrentPosition (uint64_t effect_id, uint64_t *timestamp_ms)=0
virtual int	getEffectDuration (uint64_t effect_id, uint64_t *duration_ms)=0
Public 成员函数 继承自 nertc::IRtcEngine
virtual int	initialize (const NERtcEngineContext &context)=0
virtual void	release (bool sync=true)=0
virtual int	setClientRole (NERtcClientRole role)=0
virtual int	setChannelProfile (NERtcChannelProfileType profile)=0
virtual int	joinChannel (const char *token, const char *channel_name, uid_t uid)=0
virtual int	joinChannel (const char *token, const char *channel_name, uid_t uid, NERtcJoinChannelOptions channel_options)=0
virtual int	switchChannel (const char *token, const char *channel_name)=0
virtual int	switchChannel (const char *token, const char *channel_name, NERtcJoinChannelOptions channel_options)=0
virtual int	leaveChannel ()=0
virtual int	queryInterface (NERtcInterfaceIdType iid, void **inter)=0
virtual int	enableLocalAudio (bool enabled)=0
virtual int	setupLocalVideoCanvas (NERtcVideoCanvas *canvas)=0
virtual int	setupRemoteVideoCanvas (uid_t uid, NERtcVideoCanvas *canvas)=0
virtual int	enableLocalVideo (bool enabled)=0
virtual int	enableLocalVideo (NERtcVideoStreamType type, bool enabled)=0
virtual int	subscribeRemoteVideoStream (uid_t uid, NERtcRemoteVideoStreamType type, bool subscribe)=0

详细描述

RtcEngine 类提供了供 App 调用的主要接口方法。
IRtcEngineEx 是 NERTC SDK 的扩展接口类。创建一个 IRtcEngine 对象并调用这个对象的方法可以激活 NERTC SDK 的通信功能。

成员函数说明

addBeautyFilter()

virtual int nertc::IRtcEngineEx::addBeautyFilter ( const char *  file_path )

pure virtual

添加滤镜效果。
通过此接口可以实现加载滤镜资源，并添加对应的滤镜效果；若您需要更换滤镜，重复调用此接口使用新的滤镜资源即可。

自从

V4.6.10

使用前提

请先调用 startBeauty 方法开启美颜功能模块。

调用时机

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

注解

• 该方法仅适用于 Windows 平台。
• 使用滤镜、贴纸和美妆等自定义美颜效果之前，请联系商务经理获取美颜资源或模型。
• 滤镜效果可以和全局美颜、贴纸、美妆等效果互相叠加，但是不支持叠加多个滤镜。

参数说明

参数名称	类型	描述
file_path	const char*	滤镜资源或模型所在的绝对路径。

示例代码

std::string filter_path = "xxx";
rtc_engine_->addBeautyFilter(filter_path.c_str());

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kErrorFatal）：美颜模块管理未加载。
  • 30003（kNERtcErrInvalidParam）：无效参数。
  • 30004（kErrorNotSupported）：当前不支持的操作，比如使用的是纯音频 SDK。
  • 30005（kErrorInvalidState）：引擎尚未初始化或美颜模块未初始化。

addBeautyMakeup()

virtual int nertc::IRtcEngineEx::addBeautyMakeup ( const char *  file_path )

pure virtual

（此接口为 beta 版本）添加美妆效果。 此接口用于加载美妆模型，添加对应的美妆效果。需要更换美妆效果时，重复调用此接口使用新的美妆模型即可。

注解

• 该方法仅适用于 Windows 平台。
• 使用滤镜、贴纸和美妆等自定义美颜效果之前，需要先准备好对应的美颜资源或模型。
• 美妆效果可以和全局美颜、滤镜、贴纸等效果互相叠加，但是不支持叠加多个美妆效果。

自从

V4.2.202

参数

file_path

美妆模型所在的绝对路径。

返回

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

addBeautySticker()

virtual int nertc::IRtcEngineEx::addBeautySticker ( const char *  file_path )

pure virtual

（此接口为 beta 版本）添加贴纸效果。
此接口用于加载贴纸资源，添加对应的贴纸效果。需要更换贴纸时，重复调用此接口使用新的贴纸资源即可。

注解

• 该方法仅适用于 Windows 平台。
• 使用滤镜、贴纸和美妆等自定义美颜效果之前，需要先准备好对应的美颜资源或模型。
• 贴纸效果可以和全局美颜、滤镜、美妆等效果互相叠加，但是不支持叠加多个贴纸。

自从

V4.2.202

参数

file_path

贴纸资源或模型所在的绝对路径。

返回

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

addLiveStreamTask()

virtual int nertc::IRtcEngineEx::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::IRtcEngineEx::adjustChannelPlaybackSignalVolume ( uint32_t  volume )

pure virtual

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

自从

V4.6.50

调用时机

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

注解

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

参数说明

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

返回

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

adjustLoopbackRecordingSignalVolume()

virtual int nertc::IRtcEngineEx::adjustLoopbackRecordingSignalVolume ( int  volume )

pure virtual

调节声卡采集信号音量。

自从

V4.4.0 调用 enableLoopbackRecording 开启声卡采集后，你可以调用该方法调节声卡采集的信号音量。

参数

[in]

volume

声卡采集信号音量。取值范围为 [0,100]。默认值为 100，表示原始音量。

返回

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

adjustUserPlaybackSignalVolume()

virtual int nertc::IRtcEngineEx::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）：状态错误，比如引擎未初始化。

checkNECastAudioDriver()

virtual int nertc::IRtcEngineEx::checkNECastAudioDriver ( )

pure virtual

检测虚拟声卡是否安装（仅适用于 Mac 系统）。 该接口会检测电脑是否安装最新版本的虚拟声卡。如果未安装，并且应用中已集成NERTCPrivilegedTask库，该接口会弹出安装虚拟声卡对话框，方便用户安装。

自从

V4.6.0

返回

• 0: 电脑未安装网易虚拟声卡或虚拟声卡不是最新版本
• 1: 电脑已安装最新版本的网易虚拟声卡

createChannel()

virtual IRtcChannel* nertc::IRtcEngineEx::createChannel ( const char *  channel_name )

pure virtual

创建一个 IRtcChannel 对象

参数

[in]

channel_name

房间名。设置相同房间名称的用户会进入同一个通话房间。字符串格式，长度为1~ 64 字节。支持以下89个字符：a-z, A-Z, 0-9, space, !#$%&()+-:;≤.,>? @[]^_{|}~”

返回

返回 IRtcChannel 对象指针

• 0: 方法调用失败。

enableAudioVolumeIndication() [1/2]

virtual int nertc::IRtcEngineEx::enableAudioVolumeIndication ( bool  enable, uint64_t  interval  )

pure virtual

弃用:

这个方法已废弃。 启用说话者音量提示。
通过此接口可以实现允许 SDK 定期向 App 反馈房间内发音频流的用户和瞬时音量最高的远端用户（最多 3 位，包括本端）的音量相关信息，即当前谁在说话以及说话者的音量。

自从

V3.5.0

调用时机

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

业务场景

适用于通过发言者的人声相关信息做出 UI 上的音量展示的场景，或根据发言者的音量大小进行视图布局的动态调整。

参数说明

参数名称	类型	描述
enable	bool	是否启用说话者音量提示： true：启用说话者音量提示。 false：关闭说话者音量提示。
interval	uint64_t	指定音量提示的时间间隔。单位为毫秒。必须设置为 100 毫秒的整数倍值，建议设置为 200 毫秒以上。

示例代码

//设置间隔为500ms的人声音量提示
rtc_engine_->enableAudioVolumeIndication(true, 500);

相关回调

启用该方法后，只要房间内有发流用户，无论是否有人说话，SDK 都会在加入房间后根据预设的时间间隔触发 onRemoteAudioVolumeIndication 回调。

相关接口

若您希望在返回音量相关信息的同时检测是否有真实人声存在，请调用 enableAudioVolumeIndication 方法。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30003（kNERtcErrInvalidParam）：参数错误，比如时间间隔小于 100ms。
  • 30005（kNERtcErrInvalidState）：状态错误，比如引擎未初始化。

enableAudioVolumeIndication() [2/2]

virtual int nertc::IRtcEngineEx::enableAudioVolumeIndication ( bool  enable, uint64_t  interval, bool  enable_vad  )

pure virtual

启用说话者音量提示。
通过此接口可以实现允许 SDK 定期向 App 反馈房间内发音频流的用户和瞬时音量最高的远端用户（最多 3 位，包括本端）的音量相关信息，即当前谁在说话以及说话者的音量。

自从

V4.6.10

调用时机

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

业务场景

适用于通过发言者的人声相关信息做出 UI 上的音量展示的场景，或根据发言者的音量大小进行视图布局的动态调整。

参数说明

参数名称	类型	描述
enable	bool	是否启用说话者音量提示： true：启用说话者音量提示。 false：关闭说话者音量提示。
interval	uint64_t	指定音量提示的时间间隔。单位为毫秒。必须设置为 100 毫秒的整数倍值，建议设置为 200 毫秒以上。
enableVad	boolean	是否启用本地采集人声监测： true：启用本地采集人声监测。 false：关闭本地采集人声监测。

示例代码

//设置间隔为500ms的人声音量提示
rtc_engine_->enableAudioVolumeIndication(true, 500, true);

相关回调

启用该方法后，只要房间内有发流用户，无论是否有人说话，SDK 都会在加入房间后根据预设的时间间隔触发 onRemoteAudioVolumeIndication 回调。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30003（kNERtcErrInvalidParam）：参数错误，比如时间间隔小于 100ms。
  • 30005（kNERtcErrInvalidState）：状态错误，比如引擎未初始化。

enableBeauty()

virtual void nertc::IRtcEngineEx::enableBeauty ( bool  enabled )

pure virtual

暂停或恢复美颜效果。
通过此接口实现取消美颜效果后，包括全局美颜、滤镜在内的所有美颜效果都会暂时关闭，直至重新恢复美颜效果。

自从

V4.6.10

使用前提

请先调用 startBeauty 方法开启美颜功能模块。

调用时机

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

注解

该方法仅适用于 Windows 平台。

参数说明

参数名称	类型	描述
enabled	bool	是否恢复美颜效果： true：恢复美颜效果。 false：取消美颜效果。

示例代码

rtc_engine_->enableBeauty(true);

返回

无返回值。

enableBeautyMirrorMode()

virtual void nertc::IRtcEngineEx::enableBeautyMirrorMode ( bool  enabled )

pure virtual

启用美颜时，启用或关闭镜像模式。

• 美颜功能启用时，此接口用于开启或关闭镜像模式。默认为关闭状态。美颜功能暂停或结束后，此接口不再生效。
• 启用镜像模式之后，本端画面会呈现为左右翻转的视觉效果。
• 该方法已废弃。

自从

V4.2.202

参数

enabled

美颜时是否启用镜像模式。默认为 true，表示美颜时启用镜像模式。false 表示美颜时取消镜像模式。

enableDualStreamMode()

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

pure virtual

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

自从

V3.5.0

调用时机

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

注解

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

参数说明

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

示例代码

NERtcEx.getInstance().enableDualStreamMode(true);

返回

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

enableEarback()

virtual int nertc::IRtcEngineEx::enableEarback ( bool  enabled, uint32_t  volume  )

pure virtual

设置是否开启耳返功能。

自从

V3.5.0

调用时机

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

注解

• 加入房间后，耳返功能可以随时开启，且在未插入耳机或耳麦时也可生效，但是是从扬声器直接播放耳返音频，因此为了保证耳返质量，建议在插入耳机或耳麦时使用此功能。
• 若您使用的是 V4.0.0 版本的 SDK，请注意此版本该方法的 volume 参数无效，请调用 setEarbackVolume 接口设置耳返音量。

参数说明

参数名称	类型	描述
enabled	bool	是否开启耳返功能： true：开启耳返。 false：关闭耳返。
volume	uint32_t	设置耳返音量。取值范围为 0 ~ 100，默认值为 100。

示例代码

//开启耳返并设置耳返音量为 100
rtc_engine_->EnableEarback(true, 100);

相关回调

建议通过 onAudioDefaultDeviceChanged 回调监听播放设备的变化，当监听到播放设备切换为耳机时才开启耳返功能。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：音频模块尚未初始化。
  • 30003（kNERtcErrInvalidParam)：参数错误。
  • 30101（kNERtcErrChannelNotJoined）：尚未加入房间。

enableEncryption()

virtual int nertc::IRtcEngineEx::enableEncryption ( bool  enable, NERtcEncryptionConfig  config  )

pure virtual

开启或关闭媒体流加密。

自从

V4.4.0 在金融行业等安全性要求较高的场景下，您可以在加入房间前通过此方法设置媒体流加密模式。

注解

• 请在加入房间前调用该方法，加入房间后无法修改加密模式与密钥。用户离开房间后，SDK 会自动关闭加密。如需重新开启加密，需要在用户再次加入房间前调用此方法。
• 同一房间内，所有开启媒体流加密的用户必须使用相同的加密模式和密钥，否则使用不同密钥的成员加入房间时会报错 kNERtcErrEncryptNotSuitable（30113）。
• 安全起见，建议每次启用媒体流加密时都更换新的密钥。
  

参数

enable	是否开启媒体流加密。 true: 开启 false:（默认）关闭
config	媒体流加密方案。详细信息请参考 nertc::NERtcEncryptionConfig 。

返回

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

enableLocalSubStreamAudio()

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

pure virtual

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

注解

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

自从

V4.6.10

参数

[in]

enabled

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

返回

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

enableLoopbackRecording()

virtual int nertc::IRtcEngineEx::enableLoopbackRecording ( bool  enabled, const char *  device_name  )

pure virtual

开启或关闭声卡采集。

自从

V4.4.0 启用声卡采集功能后，声卡播放的声音会被合到本地音频流中，从而可以发送到远端。

注解

• 该方法仅适用于 macOS 和 Windows 平台。
• 该方法在加入房间前后都能调用。
• 您不能同时使用音频自播放和音频共享功能，否则会导致加入音视频通话房间后，无法听到对端用户的音频和本地共享音频的声音。
• macOS 系统默认声卡不支持采集功能，如需开启此功能需要 App 自己启用一个虚拟声卡，并将该虚拟声卡的名字作为 device_name 传入 SDK。 网易云信建议使用 Soundflower 作为虚拟声卡，以获得更好的音频效果。

参数

[in]	enabled	是否开启声卡采集功能。 true: 开启声卡采集。 false: （默认）关闭声卡采集。
[in]	device_name	声卡的设备名。默认设为 NULL，即使用当前声卡采集。 该参数仅适用于 macOS 平台。 如果用户使用虚拟声卡，如 “Soundflower”，可以将虚拟声卡名称 “Soundflower” 作为参数，SDK 会找到对应的虚拟声卡设备，并开始采集。

返回

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

enableMediaPub()

virtual int nertc::IRtcEngineEx::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：方法调用成功。
• 其他：方法调用失败。

enableSuperResolution()

virtual int nertc::IRtcEngineEx::enableSuperResolution ( bool  enable )

pure virtual

启用或停止 AI 超分。

自从

V4.4.0

注解

• 使用 AI 超分功能之前，请联系技术支持开通 AI 超分功能。
• AI 超分仅对以下类型的视频流有效：
  • 必须为本端接收到第一路 360P 的视频流。
  • 必须为摄像头采集到的主流大流视频。AI 超分功能暂不支持复原重建小流和屏幕共享辅流。

参数

enable

是否启用 AI 超分。默认为关闭状态。

返回

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

enableVirtualBackground()

virtual int nertc::IRtcEngineEx::enableVirtualBackground ( bool  enabled, VirtualBackgroundSource  backgroundSource  )

pure virtual

启用/禁用虚拟背景。 启用虚拟背景功能后，您可以使用自定义背景图片替换本地用户的原始背景图片。 替换后，频道内所有用户都可以看到自定义背景图片。

自从

V4.6.0

注解

• 您可以通过 onVirtualBackgroundSourceEnabled 回调查看虚拟背景是否开启成功或出错原因。
• 建议您使用配备 i5 CPU 及更高性能的设备。
• 建议您在满足以下条件的场景中使用该功能：
• 采用高清摄像设备，环境光线均匀。
• 捕获的视频图像整洁，用户肖像半长且基本无遮挡，并且背景是与用户衣服颜色不同的单一颜色。
• 虚拟背景功能不支持 Texture 格式的视频或通过 Push 方法从自定义视频捕获中获取的视频。

参数

backgroundSource

自定义背景图片。请参阅 VirtualBackgroundSource。

返回

• 0：方法调用成功。
• < 0: 方法调用失败。

getAudioMixingCurrentPosition()

virtual int nertc::IRtcEngineEx::getAudioMixingCurrentPosition ( uint64_t *  position )

pure virtual

获取音乐文件的播放进度。
该方法获取当前伴奏播放进度，单位为毫秒。请在房间内调用该方法。

参数

[out]

position

伴奏播放进度，单位为毫秒。

返回

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

getAudioMixingDuration()

virtual int nertc::IRtcEngineEx::getAudioMixingDuration ( uint64_t *  duration )

pure virtual

获取伴奏时长。
该方法获取伴奏时长，单位为毫秒。请在房间内调用该方法。

参数

[out]

duration

伴奏时长，单位为毫秒。

返回

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

getAudioMixingPitch()

virtual int nertc::IRtcEngineEx::getAudioMixingPitch ( int32_t *  pitch )

pure virtual

获取当前伴音文件的音调。

自从

V4.6.29

使用前提

请先调用 startAudioMixing 方法开启伴音。

调用时机

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

参数说明

参数名称	类型	描述
pitch	int32_t*	当前伴音文件的音调。默认值为 0，即不调整音调，取值范围为 -12 ~ 12，按半音音阶调整。每相邻两个值的音高距离相差半音；取值的绝对值越大，音调升高或降低得越多。

示例代码

int pitch = 0;
rtc_engine_->getAudioMixingPitch(&pitch);

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如找不到对应的伴音任务或引擎尚未初始化。
  • 30101（kNERtcErrChannelNotJoined）：尚未加入房间。

getAudioMixingPlaybackVolume()

virtual int nertc::IRtcEngineEx::getAudioMixingPlaybackVolume ( uint32_t *  volume )

pure virtual

获取伴奏播放音量。
该方法获取混音里伴奏的播放音量大小。请在房间内调用该方法。

参数

[out]

volume

伴奏播放音量。

返回

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

getAudioMixingSendVolume()

virtual int nertc::IRtcEngineEx::getAudioMixingSendVolume ( uint32_t *  volume )

pure virtual

获取伴奏发送音量。
该方法获取混音里伴奏的发送音量大小。请在房间内调用该方法。

参数

[out]

volume

伴奏发送音量。

返回

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

getBeautyEffect()

virtual float nertc::IRtcEngineEx::getBeautyEffect ( NERtcBeautyEffectType  type )

pure virtual

获取指定美颜类型的强度设置。
通过接口 setBeautyEffect 设置美颜效果及强度后，可以通过此接口查看指定美颜效果的强度设置。

注解

该方法仅适用于 Windows 平台。

自从

V4.2.202

参数

type

美颜类型。

返回

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

getConnectionState()

virtual NERtcConnectionStateType nertc::IRtcEngineEx::getConnectionState ( )

pure virtual

获取当前房间连接状态。

返回

房间连接状态。::NERtcConnectionStateType.

getEffectCurrentPosition()

virtual int nertc::IRtcEngineEx::getEffectCurrentPosition ( uint64_t  effect_id, uint64_t *  timestamp_ms  )

pure virtual

获取指定音效文件的播放进度。

自从

V4.6.29

使用前提

请先调用 playEffect 方法播放音效。

调用时机

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

参数说明

参数名称	类型	描述
effect_id	uint32_t	指定音效文件的 ID。每个音效文件均对应唯一的 ID。
timestamp_ms	uint64_t*	指定音效文件的当前播放位置。单位为毫秒。

示例代码

uint32 effect_id = 7788;
int32_t pitch = 0;
rtc_engine_->getEffectCurrentPosition(effect_id, &timestamp_ms);

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：接口操作失败或未找到对应的音效任务。
  • 30003（kNERtcErrInvalidParam）：参数错误，比如 effect_id 不正确。
  • 30101（kNERtcErrChannelNotJoined）：尚未加入房间。

getEffectDuration()

virtual int nertc::IRtcEngineEx::getEffectDuration ( uint64_t  effect_id, uint64_t *  duration_ms  )

pure virtual

获取指定音效文件的时长。

自从

V4.6.29

使用前提

请先调用 playEffect 方法播放音效。

调用时机

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

参数说明

参数名称	类型	描述
effect_id	uint32_t	指定音效文件的 ID。每个音效文件均对应唯一的 ID。
duration_ms	uint64_t*	指定音效文件的时长。单位为毫秒。

示例代码

uint32 effect_id = 7788;
int32_t pitch = 0;
rtc_engine_->getEffectDuration(effect_id, &duration_ms);

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：接口操作失败或未找到对应的音效任务。
  • 30003（kNERtcErrInvalidParam）：参数错误，比如 effect_id 不正确。
  • 30101（kNERtcErrChannelNotJoined）：尚未加入房间。

getEffectPitch()

virtual int nertc::IRtcEngineEx::getEffectPitch ( uint32_t  effect_id, int32_t *  pitch  )

pure virtual

获取指定音效文件的音调。

自从

V4.6.29

使用前提

请先调用 playEffect 方法播放音效。

调用时机

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

参数说明

参数名称	类型	描述
effect_id	uint32_t	指定音效文件的 ID。每个音效文件均对应唯一的 ID。
pitch	int32_t	指定音效文件的音调。默认值为 0，即不调整音调，取值范围为 -12 ~ 12，按半音音阶调整。每相邻两个值的音高距离相差半音；取值的绝对值越大，音调升高或降低得越多。

示例代码

uint32 effect_id = 7788;
int32_t pitch = 0;
rtc_engine_->getEffectPitch(effect_id, &pitch);

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如找不到对应的音效任务或引擎尚未初始化。
  • 30101（kNERtcErrChannelNotJoined）：尚未加入房间。

getEffectPlaybackVolume()

virtual int nertc::IRtcEngineEx::getEffectPlaybackVolume ( uint32_t  effect_id, uint32_t *  volume  )

pure virtual

获取音效文件播放音量。
请在加入房间后调用该方法。

参数

[in]	effect_id	指定音效的 ID。每个音效均有唯一的 ID。
[out]	volume	音效播放音量。

返回

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

getEffectSendVolume()

virtual int nertc::IRtcEngineEx::getEffectSendVolume ( uint32_t  effect_id, uint32_t *  volume  )

pure virtual

获取音效发送音量。 该方法获取音效的发送音量大小。请在房间内调用该方法。

参数

[in]	effect_id	指定音效的 ID。每个音效均有唯一的 ID。
[out]	volume	音效发送音量。

返回

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

getErrorDescription()

virtual const char* nertc::IRtcEngineEx::getErrorDescription ( int  error_code )

pure virtual

查看指定错误码的错误描述。

注解

目前该方法无效，只返回空值。请在 onError 中查看返回的错误码及具体的错误描述。

参数

[in]

error_code

NERtcErrorCode 。

返回

详细错误码描述

getNtpTimeOffset()

virtual int64_t nertc::IRtcEngineEx::getNtpTimeOffset ( )

pure virtual

获取本地系统时间与服务端时间差值。
可以用于做时间对齐，通过 (毫秒级系统时间 - offset) 可能得到当前服务端时间。

自从

V4.6.10

返回

本地与服务端时间差值，单位为毫秒（ms）。如果没有成功加入音视频房间，返回 0。

getVersion()

virtual const char* nertc::IRtcEngineEx::getVersion ( int *  build )

pure virtual

查询 SDK 版本号。 该方法在加入房间前后都能调用。

参数

[out]

build

编译号。

返回

当前的 SDK 版本号，格式为字符串，如1.0.0.

muteLocalAudioStream()

virtual int nertc::IRtcEngineEx::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::IRtcEngineEx::muteLocalSubStreamAudio ( bool  mute )

pure virtual

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

注解

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

自从

V4.6.10

参数

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

返回

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

muteLocalVideoStream() [1/2]

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

pure virtual

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

自从

V3.5.0

使用前提

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

调用时机

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

注解

• 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
• 调用该方法取消发布本地视频流时，设备仍然处于工作状态。
• 该方法设置内部引擎为启用状态，在 nertc::IRtcEngine::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::IRtcEngineEx::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）：方法调用成功。
• 其他：方法调用失败。

pauseAllEffects()

virtual int nertc::IRtcEngineEx::pauseAllEffects ( )

pure virtual

暂停所有音效文件播放。
请在房间内调用该方法。

返回

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

pauseAudioMixing()

virtual int nertc::IRtcEngineEx::pauseAudioMixing ( )

pure virtual

暂停伴音。
通过此接口可以实现暂停播放伴音文件。

自从

V3.5.0

使用前提

请先调用 startAudioMixing 方法开启伴音。

调用时机

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

示例代码

if (rtc_engine_) {
ret = rtc_engine_->pauseAudioMixing();
}

相关接口

可以继续调用 nertc::IRtcEngineEx::resumeAudioMixing “resumeAudioMixing” 方法恢复播放伴音文件。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：通用错误，比如未开启伴音。
  • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎尚未初始化。
  • 30101（kNERtcErrChannelNotJoined）：尚未加入房间。

pauseEffect()

virtual int nertc::IRtcEngineEx::pauseEffect ( uint32_t  effect_id )

pure virtual

暂停音效文件播放。
请在房间内调用该方法。

参数

[in]

effect_id

指定音效的 ID。每个音效均有唯一的 ID。

返回

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

pauseScreenCapture()

virtual int nertc::IRtcEngineEx::pauseScreenCapture ( )

pure virtual

暂停屏幕共享。

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

  返回

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

playEffect()

virtual int nertc::IRtcEngineEx::playEffect ( uint32_t  effect_id, NERtcCreateAudioEffectOption *  option  )

pure virtual

播放指定音效文件。 通过此接口可以实现播放指定的本地或在线音效文件。

自从

V3.5.0

调用时机

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

注解

支持的音效文件类型包括 MP3、M4A、AAC、3GP、WMA 和 WAV 格式，支持本地文件和在线 URL。 您可以多次调用该方法，通过传入不同音效文件的 effect_id 和 option，同时播放多个音效文件，实现音效叠加；但是为获得最佳用户体验，建议同时播放不超过 3 个音效文件。 若通过此接口成功播放某指定音效文件后，反复停止或重新播放该 effect_id 对应的音效文件，仅首次播放时设置的 option 有效，后续的 option 设置无效。

参数说明

参数名称	类型	描述
effect_id	uint32_t	指定音效的 ID。每个音效均应有唯一的 ID。
option	NERtcCreateAudioEffectOption *	音效相关参数，包括混音任务类型、混音文件路径等。详细信息请参考 NERtcCreateAudioEffectOption。

示例代码

if (nrtc_engine_) {    
NERtcCreateAudioEffectOption option;
// option.type = audio_mix_type_;
memcpy(option.path, cur_audio_effect_task_info_.option.path, kNERtcMaxURILength);
option.loop_count = audio_mix_loop_count_;
option.send_enabled = audio_mix_transport_enabled_;
option.send_volume = audio_mix_transport_volume_;
option.playback_enabled = audio_mix_loopback_enabled_;
option.playback_volume = audio_mix_loopback_volume_;
res = nrtc_engine_->PlayEffect(effect_id, option);
}

相关接口

onAudioEffectTimestampUpdate：本地音效文件播放进度回调。 onAudioEffectFinished：本地音效文件播放已结束回调。

返回

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

pullExternalAudioFrame()

virtual int nertc::IRtcEngineEx::pullExternalAudioFrame ( void *  data, int  len  )

pure virtual

拉取外部音频数据。
该方法将从内部引擎拉取音频数据。 通过 setExternalAudioRender 启用外部音频数据渲染功能成功后，可以使用 pullExternalAudioFrame 接口获取音频 PCM 数据。

注解

• 该方法需要在加入房间后调用。
• 数据帧时长建议匹配 10ms 周期。
• 该方法在音频渲染设备关闭后不再生效，此时会返回空数据。例如通话结束、通话前扬声器设备测试关闭等情况下，该设置不再生效。

参数

[out]	data	数据指针，SDK内部会将数据拷贝到data中。
[in]	len	待拉取音频数据的字节数，单位为 byte。 建议音频数据的时长至少为 10 毫秒，数据长度不能超过 7680字节。 计算公式为： len = sampleRate/1000 × 2 × channels × 音频数据时长（毫秒）。

返回

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

pushExternalAudioEncodedFrame()

virtual int nertc::IRtcEngineEx::pushExternalAudioEncodedFrame ( NERtcAudioEncodedFrame *  encoded_frame )

pure virtual

推送外部音频主流编码帧。

• 通过此接口可以实现通过主流音频通道推送外部音频编码后的数据。

  自从

  V4.6.29

  使用前提

  该方法仅在设置 setExternalAudioSource 接口的 enabled 参数为 true 后调用有效。

  调用时机

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

  业务场景

  适用于需要自行处理音频数据的采集与编码的场景。

  注解

• 目前仅支持传输 OPUS 格式的音频数据。
• 建议不要同时调用 pushExternalAudioFrame 方法。
• 该方法在音频输入设备关闭后，例如在关闭本地音频、通话结束、通话前麦克风设备测试关闭等情况下，设置会恢复至默认。

  参数说明

  参数名称	类型	描述
  encoded_frame	NERtcAudioEncodedFrame*	编码后的音频帧数据。

  
  

  示例代码

  int timediff = 20; // opus need 20ms
  uint64_t encoded_audio_ts = 0;
  nertc::NERtcAudioEncodedFrame audioFrame;
  memset(&audioFrame, 0, sizeof(audioFrame));
  audioFrame.sample_rate = sample_rate; //采样率
  audioFrame.channels = channels; // 声道数
  audioFrame.samples_per_channel = sample_rate / 1000 * timediff;  //每声道采样数
  audioFrame.payload_type = nertc::kNERtcAudioPayloadTypeOPUS; // OPUS, 参考NERtcAudioPayloadType
  audioFrame.encoded_len = len; // 编码后数据长度
  audioFrame.data = data; // 编码后数据
  audioFrame.timestamp_us = TimeMicros(); // 机器时间，us
  audioFrame.encoded_timestamp = encoded_audio_ts;  // 编码时间, 单位为样本数
  encoded_audio_ts += audioFrame.samples_per_channel;
  auto ret = rtc_engine_->pushExternalAudioEncodedFrame(&audioFrame);
  if (ret != nertc::kNERtcNoError) {
  // 错误处理
  } 

  返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：未开启外部音频输入。
  • 30003（kNERtcErrInvalidParam）：参数错误，比如传入对象为空。
  • 30005（kNERtcErrInvalidState）：状态错误，比如尚未加入房间或未开启本地音频。

pushExternalAudioFrame()

virtual int nertc::IRtcEngineEx::pushExternalAudioFrame ( NERtcAudioFrame *  frame )

pure virtual

推送外部音频数据输入。
将外部音频数据帧推送给内部引擎。 通过 setExternalAudioSource 启用外部音频数据输入功能成功后，可以使用 pushExternalAudioFrame 接口发送音频 PCM 数据。

注解

• 该方法需要在加入房间后调用。
• 数据帧时长建议匹配 10ms 周期。
• 该方法在音频输入设备关闭后不再生效。例如关闭本地音频、通话结束、通话前麦克风设备测试关闭等情况下，该设置不再生效。

参数

[in]

frame

外部音频帧数据；数据长度不能超过 7680 字节，和调用周期时长一致。

返回

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

pushExternalSubStreamAudioEncodedFrame()

virtual int nertc::IRtcEngineEx::pushExternalSubStreamAudioEncodedFrame ( NERtcAudioEncodedFrame *  encoded_frame )

pure virtual

推送外部音频辅流编码帧。

• 通过此接口可以实现通过辅流音频通道推送外部音频编码后的数据。

  自从

  V4.6.29

  使用前提

  该方法仅在设置 setExternalSubStreamAudioSource 接口的 enabled 参数为 true 后调用有效。

  调用时机

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

  业务场景

  适用于需要自行处理音频数据的采集与编码的场景。

  注解

• 目前仅支持传输 OPUS 格式的音频数据。
• 建议不要同时调用 pushExternalSubStreamAudioFrame 方法。
• 该方法在音频输入设备关闭后，例如在关闭本地音频、通话结束、通话前麦克风设备测试关闭等情况下，设置会恢复至默认。

  参数说明

  参数名称	类型	描述
  encoded_frame	NERtcAudioEncodedFrame*	编码后的音频帧数据。

  
  

  示例代码

  int timediff = 20; // opus need 20ms
  uint64_t encoded_audio_ts = 0;
  nertc::NERtcAudioEncodedFrame audioFrame;
  memset(&audioFrame, 0, sizeof(audioFrame));
  audioFrame.sample_rate = sample_rate; //采样率
  audioFrame.channels = channels; // 声道数
  audioFrame.samples_per_channel = sample_rate / 1000 * timediff;  //每声道采样数
  audioFrame.payload_type = nertc::kNERtcAudioPayloadTypeOPUS; // OPUS, 参考NERtcAudioPayloadType
  audioFrame.encoded_len = len; // 编码后数据长度
  audioFrame.data = data; // 编码后数据
  audioFrame.timestamp_us = TimeMicros(); // 机器时间，us
  audioFrame.encoded_timestamp = encoded_audio_ts;  // 编码时间, 单位为样本数
  encoded_audio_ts += audioFrame.samples_per_channel;
  auto ret = rtc_engine_->pushExternalSubStreamAudioEncodedFrame(&audioFrame);
  if (ret != nertc::kNERtcNoError) {
  // 错误处理
  } 

  返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：未开启外部音频输入。
  • 30003（kNERtcErrInvalidParam）：参数错误，比如传入对象为空。
  • 30005（kNERtcErrInvalidState）：状态错误，比如尚未加入房间或未开启本地音频。

pushExternalSubStreamAudioFrame()

virtual int nertc::IRtcEngineEx::pushExternalSubStreamAudioFrame ( NERtcAudioFrame *  frame )

pure virtual

推送外部音频辅流数据帧。
将外部音频辅流帧数据帧主动推送给内部引擎。通过 enableLocalSubStreamAudio 启用音频辅流后，可以调用此接口发送音频辅流 PCM 数据。

注解

• 该方法需要在加入房间后调用。
• 数据帧时长建议匹配 10ms 周期。
• 该方法在音频辅流关闭后不再生效。

自从

V4.6.10

参数

frame

音频帧数据。

返回

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

pushExternalVideoEncodedFrame()

virtual int nertc::IRtcEngineEx::pushExternalVideoEncodedFrame ( NERtcVideoStreamType  type, NERtcVideoEncodedFrame *  encoded_frame  )

pure virtual

推送外部视频编码帧。

• 通过此接口可以实现通过主流或辅流视频通道推送外部视频编码后的数据。

  自从

  V4.6.29

  使用前提

  该方法仅在设置 setExternalVideoSource 接口的 enable 参数为 true 后调用有效。

  调用时机

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

  业务场景

  适用于需要自行处理视频数据的采集与编码的场景。

  注解

• 目前仅支持传输 H.264 格式的视频数据。
• 该方法设置内部引擎为启用状态，在 leaveChannel 后设置会重置为默认状态。
• 建议先调用 enableDualStreamMode} 方法关闭视频大小流功能，否则远端可能无法正常接收下行流。
• 建议不要同时调用 pushExternalVideoFrame 方法。
• 外部视频源数据的输入通道、本地视频采集通道与外部视频编码帧数据的推送通道必须同为主流或者辅流通道，否则 SDK 会报错。

  参数说明

  参数名称	类型	描述
  encoded_frame	NERtcVideoEncodedFrame*	编码后的视频帧数据。
  type	NERtcVideoStreamType	视频通道类型： kNERTCVideoStreamMain：主流。 kNERTCVideoStreamSub：辅流。

  
  

  示例代码

  nertc::NERtcVideoEncodedFrame frame;
  memset(&frame, 0, sizeof(frame));
  frame.codec_type = nertc::kNERtcVideoCodecTypeH264; // H264类型，详见NERtcVideoCodecType
  frame.frame_type = nertc::kNERtcNalFrameTypeIDR; // IDR帧，详见NERtcNalFrameType
  frame.nal_count = nalCnt; // nal个数
  frame.nal_length = nalLen; // 每个nal对应的长度数组
  frame.nal_data = data; // nal数据
  frame.timestamp_us = TimeMicros(); // 机器时间，us
  frame.width = width; // 视频宽
  frame.height = height; // 视频高
  auto ret = rtc_engine_->pushExternalVideoEncodedFrame(&frame);
  if (ret != nertc::kNERtcNoError) {
  // 错误处理
  }

  相关接口

  可以调用 setVideoEncoderQosObserver 接口设置视频编码 QoS 信息监听器，通过回调的数据信息调整编码策略。

  返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 11403（kNERtcErrInvalid）：无效操作，比如未开启外部视频输入。
  • 30003（kNERtcErrInvalidParam）：参数错误，比如传入对象为空。
  • 30005（kNERtcErrInvalidState）：状态错误，比如引擎未初始化或视频未开启。

pushExternalVideoFrame() [1/2]

virtual int nertc::IRtcEngineEx::pushExternalVideoFrame ( NERtcVideoFrame *  frame )

pure virtual

推送外部视频帧。
该方法主动将视频帧数据用 NERtcVideoFrame 类封装后传递给 SDK。 请确保在你调用本方法前已调用 setExternalVideoSource，并将参数设为 true，否则调用本方法后会一直报错。

注解

• 该方法仅适用于视频主流，若您希望向辅流通道推送外部视频帧，请调用 pushExternalVideoFrame 方法。
• 该方法设置内部引擎为启用状态，在 leaveChannel 后不再有效。

参数

[in]

frame

外部视频帧数据。详细信息请参考 NERtcVideoFrame 。

返回

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

pushExternalVideoFrame() [2/2]

virtual int nertc::IRtcEngineEx::pushExternalVideoFrame ( NERtcVideoStreamType  type, NERtcVideoFrame *  frame  )

pure virtual

推送外部视频帧。
通过本接口可以实现创建外部视频输入源之后，将主流或辅流的外部视频数据帧用 NERtcVideoFrame 类封装后传递给 SDK。

自从

V4.6.20

使用前提

请在通过 setExternalVideoSource 接口开启外部视频源数据输入后调用该方法，且必须使用同一种视频通道，即同为主流或辅流。

调用时机

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

业务场景

实现由应用层而非 SDK 采集视频数据，适用于对输入的视频数据做水印、美颜、马赛克等前处理的场景。

注解

• 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
• 该方法设置开启外部视频源输入时，内部引擎为启用状态，在离开房间（leaveChannel）后，该接口设置失效，将恢复至默认。

参数说明

参数名称	类型	描述
type	NERtcVideoStreamType	视频通道类型： kNERTCVideoStreamMain：主流。 kNERTCVideoStreamSub：辅流。
frame	NERtcVideoFrame	外部视频帧的数据信息。

示例代码

//给视频主流通道设置外部视频帧数据
nertc::NERtcVideoStreamType type = nertc::NERtcVideoStreamType::kNERTCVideoStreamMain; 
nertc::NERtcVideoFrame external_video_frame_ = ...; //构造一个视频数据帧
PushExternalVideoFrame(type, external_video_frame_);
//给视频辅流通道设置外部视频帧数据
nertc::NERtcVideoStreamType type = nertc::NERtcVideoStreamType::kNERTCVideoStreamSub;
nertc::NERtcVideoFrame external_video_frame_ = ...; //构造一个视频数据帧
PushExternalVideoFrame(type, external_video_frame_);

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 11403（kNERtcErrInvalid)：无效的操作，比如没有调用 setExternalVideoSource 开启外部视频输入。
  • 30001（kNERtcErrFatal）：通用错误，比如视频格式错误。
  • 30003（kNERtcErrInvalidParam）：参数错误，比如 frame 为 nullptr。

removeBeautyFilter()

virtual int nertc::IRtcEngineEx::removeBeautyFilter ( )

pure virtual

取消滤镜效果。

注解

该方法仅适用于 Windows 平台。

自从

V4.2.202

返回

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

removeBeautyMakeup()

virtual int nertc::IRtcEngineEx::removeBeautyMakeup ( )

pure virtual

（此接口为 beta 版本）取消美妆效果。

注解

该方法仅适用于 Windows 平台。

自从

V4.2.202

返回

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

removeBeautySticker()

virtual int nertc::IRtcEngineEx::removeBeautySticker ( )

pure virtual

（此接口为 beta 版本）取消贴纸效果。

注解

该方法仅适用于 Windows 平台。

自从

V4.2.202

返回

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

removeLiveStreamTask()

virtual int nertc::IRtcEngineEx::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）：尚未加入房间。

resumeAllEffects()

virtual int nertc::IRtcEngineEx::resumeAllEffects ( )

pure virtual

恢复播放所有音效文件。
请在房间内调用该方法。

返回

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

resumeAudioMixing()

virtual int nertc::IRtcEngineEx::resumeAudioMixing ( )

pure virtual

恢复伴音。
通过此接口可以实现恢复播放伴音文件。

自从

V3.5.0

使用前提

请先调用 startAudioMixing 方法开启伴音。

调用时机

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

示例代码

rtc_engine_->resumeAudioMixing();

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：通用错误，比如未开启伴音。
  • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎尚未初始化。
  • 30101（kNERtcErrChannelNotJoined）：尚未加入房间。

resumeEffect()

virtual int nertc::IRtcEngineEx::resumeEffect ( uint32_t  effect_id )

pure virtual

恢复播放指定音效文件。
请在房间内调用该方法。

参数

[in]

effect_id

指定音效的 ID。每个音效均有唯一的 ID。

返回

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

resumeScreenCapture()

virtual int nertc::IRtcEngineEx::resumeScreenCapture ( )

pure virtual

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

返回

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

sendSEIMsg() [1/2]

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

pure virtual

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

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

  注解

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

  参数

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

  注解

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

  返回

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

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

sendSEIMsg() [2/2]

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

pure virtual

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

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

  注解

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

  参数

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

  返回

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

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

setAudioEffectPreset()

virtual int nertc::IRtcEngineEx::setAudioEffectPreset ( NERtcVoiceChangerType  type )

pure virtual

预设变声效果。
通过此接口可以实现将人声原音调整为多种特殊效果，改变声音特性。

自从

V4.1.0

调用时机

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

注解

• 该方法设置内部引擎为启用状态，在 leaveChannel 后设置失效，将恢复至默认，即关闭变声音效。

参数说明

参数名称	类型	描述
type	NERtcVoiceChangerType	预设的变声音效。默认关闭变声音效。

示例代码

if (engine)
{
int res = engine->setAudioEffectPreset(kNERtcVoiceChangerManToLoli);
}

返回

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

setAudioFrameObserver()

virtual int nertc::IRtcEngineEx::setAudioFrameObserver ( INERtcAudioFrameObserver *  observer )

pure virtual

注册语音观测器对象。
通过此接口可以设置音频采集/播放 PCM 回调，可用于声音处理等操作。

自从

V3.5.0

调用时机

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

参数说明

参数名称	类型	描述
observer	INERtcAudioFrameObserver	接口对象实例。如果传入参数为 NULL，取消注册，同时会清理 NERtcAudioFrameRequestFormat 的相关设置。

示例代码

//注册音频流观测器对象
NRTCEngine *nrtc_engine_ = new NRTCEngine();
nrtc_engine_.SetAudioFrameObserver(nrtc_engine_);
//实现音频流观察器对象
void NRTCEngine::onAudioFrameDidRecord(NERtcAudioFrame *frame) {
    //ToDo        record_audio_filter_.audio_filter_process(frame->data, frame->format.channels, frame->format.sample_rate,
}
void NRTCEngine::onSubStreamAudioFrameDidRecord(nertc::NERtcAudioFrame *frame) {
    //ToDo        record_audio_filter_.audio_filter_process(frame->data, frame->format.channels, frame->format.sample_rate,
}
void NRTCEngine::onAudioFrameWillPlayback(NERtcAudioFrame *frame) {
    //ToDo        playout_audio_fileter_.audio_filter_process(frame->data, frame->format.channels, frame->format.sample_rate,
}
void NRTCEngine::onMixedAudioFrame(nertc::NERtcAudioFrame *frame) {
    //ToDo        
}
void NRTCEngine::onPlaybackAudioFrameBeforeMixing(nertc::uid_t uid, nertc::NERtcAudioFrame *frame) {
    //ToDo        std::string key = std::to_string(cid) + "-" + std::to_string(uid);
}
void NRTCEngine::onPlaybackSubStreamAudioFrameBeforeMixing(uint64_t userID, NERtcAudioFrame *frame, channel_id_t cid) {
    //ToDo        std::string key = std::to_string(cid) + "-" + std::to_string(userID) + "sub";
}

相关回调

• onAudioFrameDidRecord：采集音频数据回调，用于声音处理等操作。
• onSubStreamAudioFrameDidRecord：本地音频辅流数据回调，用于自定义音频辅流数据。
• onAudioFrameWillPlayback：播放音频数据回调，用于声音处理等操作。
• onMixedAudioFrame：获取本地用户和所有远端用户混音后的原始音频数据。
• onPlaybackAudioFrameBeforeMixing：获取指定远端用户混音前的音频数据。
• onPlaybackSubStreamAudioFrameBeforeMixing：获取指定远端用户混音前的音频辅流数据。

返回

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

setAudioMixingPitch()

virtual int nertc::IRtcEngineEx::setAudioMixingPitch ( int32_t  pitch )

pure virtual

设置当前伴音文件的音调。

• 通过此接口可以实现当本地人声和播放的音乐文件混音时，仅调节音乐文件的音调。

  自从

  V4.6.29

  使用前提

  请先调用 startAudioMixing 方法开启伴音。

  调用时机

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

  业务场景

  适用于 K 歌中为了匹配人声，调节背景音乐音高的场景。

  注解

  当前伴音任务结束后，此接口的设置会恢复至默认。

  参数说明

  参数名称	类型	描述
  pitch	int32_t	当前伴音文件的音调。默认值为 0，即不调整音调，取值范围为 -12 ~ 12，按半音音阶调整。每相邻两个值的音高距离相差半音；取值的绝对值越大，音调升高或降低得越多。

  
  

  示例代码

  int pitch = 0;
  rtc_engine_->setAudioMixingPitch(pitch);

  相关接口

  可以调用 getAudioMixingPitch 方法获取伴音文件的音调。

  返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30003（kNERtcErrInvalidParam）：参数有误，比如 pitch 超出范围。
  • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如找不到对应的伴音任务或引擎尚未初始化。
  • 30101（kNERtcErrChannelNotJoined）：尚未加入房间。

setAudioMixingPlaybackVolume()

virtual int nertc::IRtcEngineEx::setAudioMixingPlaybackVolume ( uint32_t  volume )

pure virtual

调节伴奏播放音量。
该方法调节混音里伴奏的播放音量大小。请在房间内调用该方法。

参数

[in]

volume

伴奏音量范围为 0~200。默认 100 为原始文件音量。

返回

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

setAudioMixingPosition()

virtual int nertc::IRtcEngineEx::setAudioMixingPosition ( uint64_t  seek_position )

pure virtual

设置音乐文件的播放位置。
该方法可以设置音频文件的播放位置，这样你可以根据实际情况播放文件，而非从头到尾播放整个文件。

参数

[in]

seek_position

进度条位置，单位为毫秒。

返回

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

setAudioMixingSendVolume()

virtual int nertc::IRtcEngineEx::setAudioMixingSendVolume ( uint32_t  volume )

pure virtual

调节伴奏发送音量。
该方法调节混音里伴奏的发送音量大小。请在房间内调用该方法。

参数

[in]

volume

伴奏发送音量。取值范围为 0~200。默认 100 为原始文件音量。

返回

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

setAudioProfile()

virtual int nertc::IRtcEngineEx::setAudioProfile ( NERtcAudioProfileType  profile, NERtcAudioScenarioType  scenario  )

pure virtual

设置音频编码属性。
通过此接口可以实现设置音频编码的采样率、码率、编码模式、声道数等，也可以设置音频属性的应用场景，包括聊天室场景、语音场景、音乐场景等。

自从

V3.5.0

调用时机

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

注解

• 音乐场景下，建议将 profile 设置为 kNERtcAudioProfileHighQuality。
• 若您通过 setChannelProfile 接口设置房间场景为直播模式，即 kNERtcChannelProfileLiveBroadcasting，但未调用此方法设置音频编码属性，或仅设置 profile 为 kNERtcAudioProfileDefault，则 SDK 会自动设置 profile 为 kNERtcAudioProfileHighQuality，且设置 scenario 为 kNERtcAudioScenarioMusic。

参数说明

参数名称	类型	描述
profile	NERtcAudioProfileType	设置采样率、码率、编码模式和声道数。
scenario	NERtcAudioScenarioType	设置音频应用场景。

示例代码

//设置profile为标准模式，scenario为语音场景
rtc_engine_->setAudioProfile(nertc::kNERtcAudioProfileStandard, nertc::kNERtcAudioScenarioSpeech);

返回

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

setAudioSubscribeOnlyBy()

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

pure virtual

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

注解

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

自从

V4.6.10

参数

[in]

uid_array

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

注解

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

参数

[in]

size

uid_array 的数组长度。

返回

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

setBeautyEffect()

virtual int nertc::IRtcEngineEx::setBeautyEffect ( NERtcBeautyEffectType  type, float  level  )

pure virtual

设置美颜效果。 通过此接口可以实现设置磨皮、美白、大眼等多种全局美颜类型和对应的美颜强度。

自从

V4.6.10

使用前提

请先调用 startBeauty 方法开启美颜。

调用时机

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

注解

• 该方法仅适用于 Windows 平台，若您使用的是 macOS 平台，请调用 NERtcBeauty#setBeautyEffectWithValue:atType: 方法。
• 您可以多次调用此接口以叠加多种全局美颜效果，也可以在此基础上通过其他方法叠加滤镜等自定义效果。

参数说明

参数名称	类型	描述
type	NERtcBeautyEffectType	美颜类型。
level	float	对应美颜类型的强度。取值范围为 [0, 1]，各种美颜效果的默认值不同。

示例代码

if (rtc_engine_) {
ret = rtc_engine_->setBeautyEffect(kNERtcBeautyNarrowFace, 0.5);
}

相关接口

可以调用 NERtcBeauty#addBeautyFilterWithPath:andName: 方法叠加滤镜等自定义美颜效果。

返回

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

setBeautyFilterLevel()

virtual int nertc::IRtcEngineEx::setBeautyFilterLevel ( float  level )

pure virtual

设置滤镜强度。 取值越大，滤镜强度越大，开发者可以根据业务需求自定义设置滤镜强度。

注解

• 该方法仅适用于 Windows 平台。
• 滤镜强度设置实时生效，更换滤镜后需要重新设置滤镜强度，否则强度取默认值。

自从

V4.2.202

参数

level

滤镜强度。取值范围为 [0 - 1]，默认值为 0.5。

返回

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

setCameraCaptureConfig() [1/2]

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

pure virtual

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

自从

V4.5.0

调用时机

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

业务场景

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

注解

• 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
• 该方法仅适用于视频主流，若您希望为辅流通道设置摄像头的采集配置，请调用 nertc::IRtcEngineEx::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::IRtcEngineEx::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）：方法调用成功。
• 其他：方法调用失败。

setCloudProxy()

virtual int nertc::IRtcEngineEx::setCloudProxy ( int  proxyType )

pure virtual

开启并设置云代理服务。
在内网环境下，如果用户防火墙开启了网络限制，请参考《使用云代理》将指定 IP 地址和端口号加入防火墙白名单，然后调用此方法开启云代理，并将 proxyType 参数设置为 NERtcTransportTypeUDPProxy(1)，即指定使用 UDP 协议的云代理。

• 成功连接云代理后，SDK 会触发 onNERtcEngineConnectionStateChangeWithState(kNERtcConnectionStateConnecting, kNERtcReasonConnectionChangedSettingProxyServer) 回调。
• 如果需要关闭已设置的云代理，请调用 setCloudProxy(NERtcTransportTypeNoneProxy)。

  注解

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

  参数

  proxyType

  云代理类型。详细信息请参考 NERtcTransportType。该参数为必填参数，若未赋值，SDK 会报错。

  返回

  0 

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

setEarbackVolume()

virtual int nertc::IRtcEngineEx::setEarbackVolume ( uint32_t  volume )

pure virtual

设置耳返音量。 请在房间内调用该方法。

参数

[in]

volume

耳返音量。可设置为 0~100，默认为 100。

返回

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

setEffectPitch()

virtual int nertc::IRtcEngineEx::setEffectPitch ( uint32_t  effect_id, int32_t  pitch  )

pure virtual

设置指定音效文件的音调。

• 通过此接口可以实现当本地人声和播放的音乐文件混音时，仅调节音乐文件的音调。

  自从

  V4.6.29

  使用前提

  请先调用 playEffect 方法播放音效。

  调用时机

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

  业务场景

  适用于 K 歌中为了匹配人声，调节背景音乐音高的场景。

  注解

  当前音效任务结束后，此接口的设置会恢复至默认。

  参数说明

  参数名称	类型	描述
  effect_id	uint32_t	指定音效文件的 ID。每个音效文件均对应唯一的 ID。
  pitch	int32_t	指定音效文件的音调。默认值为 0，即不调整音调，取值范围为 -12 ~ 12，按半音音阶调整。每相邻两个值的音高距离相差半音；取值的绝对值越大，音调升高或降低得越多。

  
  

  示例代码

  uint32 effect_id = 7788;
  int32_t pitch = 0;
  rtc_engine_->setEffectPitch(effect_id, pitch);

  相关接口

  可以调用 getEffectPitch 方法获取指定音效文件的音调。

  返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30003（kNERtcErrInvalidParam）：参数有误，比如 pitch 超出范围。
  • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如找不到对应的音效任务或引擎尚未初始化。
  • 30101（kNERtcErrChannelNotJoined）：尚未加入房间。

setEffectPlaybackVolume()

virtual int nertc::IRtcEngineEx::setEffectPlaybackVolume ( uint32_t  effect_id, uint32_t  volume  )

pure virtual

设置音效文件播放音量。 请在加入房间后调用该方法。

参数

[in]	effect_id	指定音效的 ID。每个音效均有唯一的 ID。
[in]	volume	音效播放音量。范围为0~100，默认为100。

返回

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

setEffectPosition()

virtual int nertc::IRtcEngineEx::setEffectPosition ( uint32_t  effect_id, uint64_t  timestamp_ms  )

pure virtual

设置指定音效文件的播放位置。

• 通过此接口可以实现根据实际情况播放音效文件，而非从头到尾播放整个文件。

  自从

  V4.6.29

  使用前提

  请先调用 playEffect 方法播放音效。

  调用时机

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

  参数说明

  参数名称	类型	描述
  effect_id	uint32_t	指定音效文件的 ID。每个音效文件均对应唯一的 ID。
  timestamp_ms	uint64_t	指定音效文件的起始播放位置。单位为毫秒。

  
  

  示例代码

  uint32_t effect_id = 7788;
  uint64_t timestamp_ms = 0;
  rtc_engine_->setEffectPosition(effect_id, timestamp_ms);

  相关接口

• getEffectCurrentPosition：获取指定音效文件的当前播放位置。
• onAudioEffectTimestampUpdate：注册此回调实时获取指定音效文件的当前播放进度，默认为每隔 1s 返回一次。

  返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：接口操作失败或未找到对应的音效任务。
  • 30003（kNERtcErrInvalidParam）：参数错误，比如 effect_id 不正确。
  • 30101（kNERtcErrChannelNotJoined）：尚未加入房间。

setEffectSendVolume()

virtual int nertc::IRtcEngineEx::setEffectSendVolume ( uint32_t  effect_id, uint32_t  volume  )

pure virtual

调节音效发送音量。 该方法调节音效的发送音量大小。请在房间内调用该方法。

参数

[in]	effect_id	指定音效的 ID。每个音效均有唯一的 ID。
[in]	volume	音效音量范围为 0~100。默认 100 为原始文件音量。

返回

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

setExcludeWindowList()

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

pure virtual

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

注解

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

自从

V4.2.0

参数

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

返回

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

setExternalAudioRender()

virtual int nertc::IRtcEngineEx::setExternalAudioRender ( bool  enabled, int  sample_rate, int  channels  )

pure virtual

设置外部音频渲染。
通过此接口可以实现启用外部音频渲染，并设置音频渲染的采样率、声道数等。

自从

V4.0.0

调用时机

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

业务场景

适用于需要自行渲染音频的场景。

注解

• 该方法设置内部引擎为启用状态，在 leaveChannel 后仍然有效；如果需要关闭该功能，需要在下次通话前调用此接口关闭外部音频数据渲染功能。
• 成功调用此方法后，音频播放设备的选择和异常重启功能将失效， 且将用虚拟设备代替扬声器工作，因此扬声器的相关设置会无法生效，例如进行 loopback 检测时，需要由外部渲染播放。
• 设置 enable 参数为 false 关闭该功能时，其他参数可传入任意合法值，均不会生效。

参数说明

参数名称	类型	描述
enabled	bool	是否开启外部音频渲染： true：开启外部音频渲染。 false（默认）：关闭外部音频渲染。
sample_rate	int	外部音频渲染的采样率，单位为赫兹（Hz），可设置为 16000，32000，44100 或 48000。
channels	int	外部音频渲染的声道数，可设置为： 1：单声道。 2：双声道。

示例代码

//设置采样率为 16000 的双声道外部渲染
rtc_engine_->setExternalAudioRender(true, 16000, 2);

相关接口

可以继续调用 pullExternalAudioFrame 方法获取音频 PCM 数据，用以后续自行渲染并播放。

返回

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

setExternalAudioSource()

virtual int nertc::IRtcEngineEx::setExternalAudioSource ( bool  enabled, int  sample_rate, int  channels  )

pure virtual

开启或关闭外部音频源数据输入。
通过本接口可以实现创建自定义的外部音频源，并通过主流通道传输该外部音频源的数据。

自从

V3.9.0

使用前提

建议在通过 enableLocalAudio 接口关闭本地音频采集之后调用该方法。

调用时机

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

业务场景

实现由应用层而非 SDK 采集音频数据，比如在合唱过程中使用自定义的音乐文件。

注解

• 调用该方法关闭外部音频输入时可以传入任意合法值，此时设置不会生效，例如 setExternalAudioSource(false, 0, 0)。
• 该方法设置内部引擎为启用状态，在 leaveChannel 后仍然有效；如果需要关闭该功能，需要在下次通话前调用此接口关闭外部音频数据输入功能。
• 成功调用此方法后，将用虚拟设备代替麦克风工作，因此麦克风的相关设置会无法生效，例如进行 loopback 检测时，会听到外部输入的音频数据。

参数说明

参数名称	类型	描述
enabled	bool	是否开启外部音频输入： true：开启外部音频输入。 false：关闭外部音频输入。
sample_rate	int	外部音频源的数据采样率，单位为 Hz。建议设置为 8000，16000，32000，44100 或 48000。
channels	int	外部音频源的数据声道数： 1：单声道。 2：双声道。

示例代码

rtc_engine->setExternalAudioSource(true, 48000, 1);

相关接口

• 该方法调用成功后可以调用 pushExternalAudioFrame 方法发送音频 PCM 数据。
• 若您希望通过辅流通道输入外部输入视频源，可以调用 setExternalSubStreamAudioSource 方法。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：设备参数更新失败。
  • 30003（kNERtcErrInvalidParam）：参数错误，比如声道数不是 1 或者 2，或者采样率设置有问题。
  • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎未初始化成功。

setExternalSubStreamAudioSource()

virtual int nertc::IRtcEngineEx::setExternalSubStreamAudioSource ( bool  enabled, int  sample_rate, int  channels  )

pure virtual

开启或关闭外部音频辅流数据源输入。
通过本接口可以实现创建自定义的外部音频源，并通过辅流通道传输该外部音频源的数据。

自从

V4.6.10

使用前提

建议在通过 enableLocalAudio 接口关闭本地音频采集之后调用该方法。

调用时机

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

业务场景

实现由应用层而非 SDK 采集音频数据，比如在合唱过程中使用自定义的音乐文件。

注解

• 调用该方法关闭外部音频输入时可以传入任意合法值，此时设置不会生效，例如 setExternalAudioSource(false, 0, 0)。
• 该方法设置内部引擎为启用状态，在 leaveChannel 后仍然有效；如果需要关闭该功能，需要在下次通话前调用此接口关闭外部音频数据输入功能。
• 成功调用此方法后，将用虚拟设备代替麦克风工作，因此麦克风的相关设置会无法生效，例如进行 loopback 检测时，会听到外部输入的音频数据。

参数说明

参数名称	类型	描述
enabled	bool	是否开启外部音频输入： true：开启外部音频输入。 false：关闭外部音频输入。
sample_rate	int	外部音频源的数据采样率，单位为 Hz。建议设置为 8000，16000，32000，44100 或 48000。
channels	int	外部音频源的数据声道数： 1：单声道。 2：双声道。

示例代码

rtc_engine_->setExternalSubStreamAudioSource(true, 48000, 2);

相关接口

该方法调用成功后可以调用 pushExternalSubStreamAudioFrame 方法发送音频 PCM 数据。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：设备参数更新失败。
  • 30003（kNERtcErrInvalidParam）：参数错误，比如声道数不是 1 或者 2，或者采样率设置有问题。
  • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎未初始化成功。
  • 30008（kErrorDeviceNotFound）：未找到对应设备。

setExternalVideoSource() [1/2]

virtual int nertc::IRtcEngineEx::setExternalVideoSource ( bool  enabled )

pure virtual

开启或关闭外部视频源数据输入。
通过本接口可以实现创建自定义的外部视频源，并通过主流通道传输该外部视频源的数据。

自从

V3.5.0

使用前提

请在通过 enableLocalVideo 接口关闭本地视频设备采集，并通过 setDevice 接口设置 kNERtcExternalVideoDeviceID 为外部视频输入源 ID 后调用该方法。

调用时机

请在通过 startVideoPreview 接口开启本地视频预览或通过 enableLocalVideo 接口开启本地视频采集之前调用该方法，且必须使用同一种视频通道，即同为主流。

业务场景

实现由应用层而非 SDK 采集视频数据，适用于对输入的视频数据做水印、美颜、马赛克等前处理的场景。

注解

• 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
• 该方法设置内部引擎为启用状态，在 leaveChannel 后仍然有效；如果需要关闭该功能，需要在下次通话前调用此接口关闭外部视频数据输入功能。

参数说明

参数名称	类型	描述
enable	bool	是否开启外部视频输入： true：开启外部视频输入。 false：关闭外部视频输入。

示例代码

rtc_engine.setExternalVideoSource(true);

相关接口

• 该方法调用成功后可以调用 pushExternalAudioFrame 方法推送视频数据帧。
• 若您希望通过辅流通道输入外部输入视频源，可以调用 setExternalVideoSource 方法。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：视频设备管理异常。

setExternalVideoSource() [2/2]

virtual int nertc::IRtcEngineEx::setExternalVideoSource ( NERtcVideoStreamType  type, bool  enabled  )

pure virtual

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

自从

V4.6.20

使用前提

请在通过 startVideoPreview 接口开启本地视频预览或通过 enableLocalVideo 接口开启本地视频采集之前调用该方法，且必须使用同一种视频通道，即同为主流或辅流。

调用时机

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

业务场景

实现由应用层而非 SDK 采集视频数据，适用于对输入的视频数据做水印、美颜、马赛克等前处理的场景。

注解

• 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
• 当外部视频源输入作为主流或辅流时，内部引擎为启用状态，在切换房间（switchChannel）、主动离开房间（leaveChannel）、触发断网重连失败回调（onDisconnect）或触发重新加入房间回调（onRejoinChannel）后仍然有效。如果需要关闭该功能，请在下次通话前调用接口关闭该功能。
• 请务必保证视频主流和辅流输入通道各最多只能有一种视频输入源，其中屏幕共享只能通过辅流通道开启，因此：
  • 若您开启了辅流形式的屏幕共享，请使用主流通道输入外部视频源数据，即设置 type 参数为 kNERTCVideoStreamMain。
  • 若您已调用 enableLocalVideo 方法开启本地主流视频采集，请勿再调用此接口创建主流形式的外部视频源输入，辅流通道同理。

参数说明

参数名称	类型	描述
type	NERtcVideoStreamType	视频通道类型： kNERTCVideoStreamMain：主流。 kNERTCVideoStreamSub：辅流。
enable	bool	是否使用外部视频源： true：开启。 false：关闭。

示例代码

//通过主流视频通道输入外部视频源数据
nertc::NERtcVideoStreamType type = nertc::NERtcVideoStreamType::kNERTCVideoStreamMain; 
bool enable = true; 
setExternalVideoSource(type, enable);
//通过辅流视频通道输入外部视频源数据
nertc::NERtcVideoStreamType::kNERTCVideoStreamSub
bool enable = true;
setExternalVideoSource(type, enable);

返回

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

setLocalCanvasWatermarkConfigs()

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

pure virtual

添加本地视频画布水印。

注解

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

参数

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

返回

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

setLocalMediaPriority()

virtual int nertc::IRtcEngineEx::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::IRtcEngineEx::setLocalPublishFallbackOption ( NERtcStreamFallbackOption  option )

pure virtual

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

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

  注解

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

  自从

  V4.3.0

  参数

  option

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

  返回

  0 

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

setLocalRenderMode()

virtual int nertc::IRtcEngineEx::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::IRtcEngineEx::setLocalSubStreamRenderMode ( NERtcVideoScalingMode  scaling_mode )

pure virtual

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

注解

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

参数

[in]

scaling_mode

视频显示模式。

返回

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

setLocalVideoMirrorMode() [1/2]

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

pure virtual

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

注解

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

参数

[in]

mirror_mode

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

返回

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

setLocalVideoMirrorMode() [2/2]

virtual int nertc::IRtcEngineEx::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）：方法调用成功。
• 其他：方法调用失败。

setLocalVideoWatermarkConfigs()

virtual int nertc::IRtcEngineEx::setLocalVideoWatermarkConfigs ( bool  enabled, NERtcVideoStreamType  type, NERtcVideoWatermarkConfig &  config  )

pure virtual

设置视频水印，水印在本地预览及发送过程中均生效。

注解

设置水印后，建议关注水印状态回调 onLocalVideoWatermarkState。

自从

V4.6.10

参数

enabled	添加或删除水印。 true：添加水印。 false：删除水印。
type	视频流类型。支持设置为主流或辅流。详细信息请参考 NERtcVideoStreamType 。
config	画布水印设置。支持设置文字水印、图片水印和时间戳水印。详细信息请参考 NERtcVideoWatermarkConfig 。

返回

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

setLocalVoiceEqualization()

virtual int nertc::IRtcEngineEx::setLocalVoiceEqualization ( NERtcVoiceEqualizationBand  band_frequency, int  band_gain  )

pure virtual

设置本地语音音效均衡，即自定义设置本地人声均衡波段的中心频率。

注解

该方法在加入房间前后都能调用，通话结束后重置为默认关闭状态。

参数

[in]	band_frequency	频谱子带索引，取值范围是 [0-9]，分别代表 10 个频带，对应的中心频率是 [31，62，125，250，500，1k，2k，4k，8k，16k] Hz。
[in]	band_gain	每个 band 的增益，单位是 dB，每一个值的范围是 [-15，15]，默认值为 0。

返回

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

setLocalVoicePitch()

virtual int nertc::IRtcEngineEx::setLocalVoicePitch ( double  pitch )

pure virtual

设置本地语音音调。 该方法改变本地说话人声音的音调。

注解

• 通话结束后该设置会重置，默认为 1.0。
• 此方法与 setAudioEffectPreset 互斥，调用此方法后，已设置的变声效果会被取消。

参数

[in]

pitch

语音频率。可以在 [0.5, 2.0] 范围内设置。取值越小，则音调越低。默认值为 1.0，表示不需要修改音调。

返回

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

setLocalVoiceReverbParam()

virtual int nertc::IRtcEngineEx::setLocalVoiceReverbParam ( NERtcReverbParam &  param )

pure virtual

设置本地语音混响效果。

注解

该方法在加入房间前后都能调用，通话结束后重置为默认的关闭状态。

自从

V4.6.10

参数

param

详细信息请参考 NERtcReverbParam。

返回

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

setMixedAudioFrameParameters()

virtual int nertc::IRtcEngineEx::setMixedAudioFrameParameters ( int  sample_rate )

pure virtual

设置采集和播放声音混音后的音频数据采样率。
通过本接口可以实现设置 onMixedAudioFrame 回调的混音音频采样率。

自从

V3.5.0

调用时机

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

业务场景

适用于需要获取本地用户和远端所有用户的声音的场景，比如通话录音的场景。

注解

• 该方法设置内部引擎为启用状态，在 leaveChannel 后设置会重置为默认状态。
• 未调用该接口设置返回的音频数据格式时，回调中的采样率取默认值。

参数说明

参数名称	类型	描述
sample_rate	int	指定 onMixedAudioFrame 中返回数据的采样率。可以设置为 8000，16000，32000，44100 或 48000。若您希望使用音频的原始格式，format 参数传 NULL 即可，默认为 NULL。

示例代码

rtc_engine->setMixedAudioFrameParameters(32000);

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：媒体工厂为空
  • 30003（kNERtcErrInvalidParam）：参数错误。
  • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎未初始化成功。

setParameters()

virtual int nertc::IRtcEngineEx::setParameters ( const char *  parameters )

pure virtual

设置音视频通话的相关参数。
此接口以标准化方式公开 JSON 选项，提供技术预览或特别定制功能，详情请咨询技术支持。

自从

V3.5.0

调用时机

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

参数说明

参数名称	类型	描述
parameters	const char	音视频通话的参数集合。JSON 字符串形式，参数 key，详细信息请参考 nertc_engine_defines.h 中的定义。

示例代码

Json::Value values;
values[nertc::kNERtcKeyRecordHostEnabled] = false;
values[nertc::kNERtcKeyRecordAudioEnabled] = false;
values[nertc::kNERtcKeyRecordVideoEnabled] = false;
values[nertc::kNERtcKeyRecordType] = nertc::kNERtcRecordTypeAll;
...
Json::FastWriter writer;
std::string parameters = writer.write(values);
rtc_engine_->setParameters(parameters.c_str());

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 20400（kNERtcErrChannelJoinInvalidParam）：参数错误。

setPlaybackAudioFrameParameters()

virtual int nertc::IRtcEngineEx::setPlaybackAudioFrameParameters ( NERtcAudioFrameRequestFormat *  format )

pure virtual

设置音频播放回调的声音格式。
通过此接口可以实现设置 SDK 播放音频 PCM 回调 onAudioFrameWillPlayback 的采样率及声道数，同时还可以设置读写模式。在写模式下，您可以通过 onAudioFrameWillPlayback 回调修改 PCM 数据，后续将播放修改后的音频数据。

自从

V3.5.0

调用时机

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

业务场景

适用于需要自行对待播放的声音进行二次处理的场景。

参数说明

参数名称	类型	描述
format	NERtcAudioFrameRequestFormat	指定 onAudioFrameWillPlayback 中返回数据的采样率和数据的通道数。允许传入 NULL，默认为 NULL，表示使用音频的原始格式。

示例代码

nertc::NERtcAudioFrameRequestFormat format;
format.channels = 1;
format.sample_rate = 48000;
format.mode = nertc::kNERtcRawAudioFrameOpModeReadOnly;
rtc_engine_->setPlaybackAudioFrameParameters(format); 

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：媒体工厂为空。
  • 30003（kNERtcErrInvalidParam）：参数错误。
  • 30005（kNERtcErrInvalidState)：状态错误，比如引擎尚未初始化。

setPreDecodeObserver()

virtual int nertc::IRtcEngineEx::setPreDecodeObserver ( INERtcPreDecodeObserver *  observer )

pure virtual

注册解码前媒体数据观测器。

• 通过此接口可以设置 onFrame 回调监听，返回相关解码前媒体数据。

  自从

  V4.6.29

  使用前提

  若您需要接收未解码的视频数据，建议先调用 setParameters 接口关闭 SDK 的视频解码功能。

  调用时机

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

  业务场景

  适用于需要自行处理音、视频数据的解码与渲染的场景。

  注解

  目前仅支持传输 OPUS 格式的音频数据和 H.264 格式的视频数据。

  参数说明

  参数名称	类型	描述
  observer	INERtcPreDecodeObserver *	接口对象实例。可以传 NULL 表示取消注册。

  
  

  示例代码

  auto ret = rtc_engine_->setPreDecodeObserver(observer); //observer为观测器实例地址
  if (ret != nertc::kNERtcNoError) {
  // 错误处理
  }         logDebug(">>>setPreDecodeObserver [0x%x] successful", enable ? this : nullptr);

  相关回调

  onFrame：返回相关解码前媒体数据，包括用户的 UID、媒体数据类型、数据长度等。

  返回

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

setRecordingAudioFrameParameters()

virtual int nertc::IRtcEngineEx::setRecordingAudioFrameParameters ( NERtcAudioFrameRequestFormat *  format )

pure virtual

设置采集的音频格式。
通过本接口可以实现设置 onAudioFrameDidRecord 回调的录制声音格式。

自从

V3.5.0

调用时机

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

业务场景

适用于需要监听音频 PCM 采集数据回调并指定回调的数据格式的场景。

注解

若您希望使用音频的原始格式，format 参数传 NULL 即可。

参数说明

参数名称	类型	描述
format	NERtcAudioFrameRequestFormat	指定 onAudioFrameDidRecord 中返回数据的采样率和数据的通道数。

示例代码

//设置双声道，采样率为48k，可读写
nertc::NERtcAudioFrameRequestFormat recording_format_;
recording_format_.channels = 2;
recording_format_.sample_rate = 48000;
recording_format_.mode = nertc::kNERtcRawAudioFrameOpModeReadWrite;
rtc_engine_->setRecordingAudioFrameParameters(&recording_format_);

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30003（kNERtcErrInvalidParam）：参数错误。
  • 30005（kNERtcErrInvalidState）：引擎尚未初始化。

setRemoteCanvasWatermarkConfigs()

virtual int nertc::IRtcEngineEx::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::IRtcEngineEx::setRemoteHighPriorityAudioStream ( bool  enabled, uid_t  uid  )

pure virtual

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

注解

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

参数

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

返回

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

setRemoteRenderMode()

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

pure virtual

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

参数

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

返回

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

setRemoteSubscribeFallbackOption()

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

pure virtual

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

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

  注解

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

  自从

  V4.3.0

  参数

  option

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

  返回

  0 

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

setRemoteSubSteamRenderMode()

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

pure virtual

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

参数

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

返回

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

setScreenCaptureMouseCursor()

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

pure virtual

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

自从

V4.6.10

参数

capture_cursor

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

返回

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

setStatsObserver()

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

pure virtual

注册统计信息观测器。

参数

[in]

observer

统计信息观测器

返回

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

setStreamAlignmentProperty()

virtual void nertc::IRtcEngineEx::setStreamAlignmentProperty ( bool  enable )

pure virtual

开启精准对齐。 通过此接口可以实现精准对齐功能，对齐本地系统与服务端的时间。

自从

V4.6.10

调用时机

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

业务场景

适用于 KTV 实时合唱的场景。

参数说明

参数名称	类型	描述
enable	bool	是否开启精准对齐功能： true：开启精准对齐功能。 false：关闭精准对齐功能。

示例代码

if (nrtc_engine_) {
nrtc_engine_->setStreamAlignmentProperty(truetrue);
}

相关接口

可以调用 getNtpTimeOffset 方法获取本地系统时间与服务端时间的差值。

返回

无返回值。

setupLocalSubStreamVideoCanvas()

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

pure virtual

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

自从

V3.9.0

调用时机

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

参数说明

参数名称	类型	描述
canvas	NERtcVideoCanvas*	视频画布。详细信息请参考 nertc::NERtcVideoCanvas 'NERtcVideoCanvas"。

示例代码

nertc::NERtcVideoCanvas canvas;
canvas.window = window;
if (rtc_engine_) {
int ret = rtc_engine_->setupLocalSubStreamVideoCanvas(&canvas);
}

返回

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

setupRemoteSubStreamVideoCanvas()

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

pure virtual

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

自从

V3.9.0

使用前提

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

调用时机

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

注解

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

参数说明

参数名称	类型	描述
canvas	NERtcVideoCanvas*	视频画布。详细信息请参考 NERtcVideoView。
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 不支持该功能。

setVideoConfig() [1/2]

virtual int nertc::IRtcEngineEx::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::IRtcEngineEx::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 未找到。

setVideoEncoderQosObserver()

virtual int nertc::IRtcEngineEx::setVideoEncoderQosObserver ( INERtcVideoEncoderQosObserver *  observer )

pure virtual

注册视频编码 QoS 信息监听器。

• 通过此接口可以设置 onRequestSendKeyFrame、 onVideoCodecUpdated、 onBitrateUpdated 回调监听，并通过返回的相关视频编码数据调整视频编码策略。

  自从

  V4.6.29

  调用时机

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

  业务场景

  适用于需要自行处理视频数据的采集与编码的场景。

  注解

  该方法设置内部引擎为启用状态，在 leaveChannel 后仍然有效；如果需要关闭该功能，需要在下次通话前调用此接口关闭视频编码 QoS 信息监听。

  参数说明

  参数名称	类型	描述
  observer	INERtcVideoEncoderQosObserver *	接口对象实例。可以传 NULL 表示取消注册。

  
  

  示例代码

  auto ret = rtc_engine_->setVideoEncoderQosObserver(observer); // observer为观测器实例地址
  if (ret != nertc::kNERtcNoError) {
  // 错误处理
  }

  相关回调

  onRequestSendKeyFrame：I 帧请求回调。 onBitrateUpdated：码率信息回调。 onVideoCodecUpdated：视频编码器类型信息回调。

  返回

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

setVoiceBeautifierPreset()

virtual int nertc::IRtcEngineEx::setVoiceBeautifierPreset ( NERtcVoiceBeautifierType  type )

pure virtual

预设美声效果。 通过此接口可以实现为本地发流用户设置 SDK 预设的人声美声效果。

自从

V4.0.0

调用时机

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

业务场景

适用于多人语聊或 K 歌房中需要美化主播或连麦者声音的场景。

注解

• 该方法设置内部引擎为启用状态，在 leaveChannel 后设置失效，将恢复至默认。
• 该方法和 setLocalVoicePitch 方法互斥，调用了其中任一方法后，另一方法的设置会被重置为默认值。

参数说明

参数名称	类型	描述
type	NERtcVoiceBeautifierType	预设的美声效果模式。默认值为 kNERtcVoiceBeautifierOff，即关闭美声效果。

示例代码

if (engine)
{
engine->setVoiceBeautifierPreset(nertc::kNERtcVoiceBeautifierMuffled);
}

返回

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

startAudioDump() [1/2]

virtual int nertc::IRtcEngineEx::startAudioDump ( )

pure virtual

开始记录音频 dump。 音频 dump 可用于分析音频问题。

返回

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

startAudioDump() [2/2]

virtual int nertc::IRtcEngineEx::startAudioDump ( NERtcAudioDumpType  type )

pure virtual

开始记录音频 dump。
音频 dump 可用于分析音频问题。

注解

该方法在加入房间前后均可调用。

参数

type	音频 dump 类型。详细信息请参考 NERtcAudioDumpType 。

startAudioMixing()

virtual int nertc::IRtcEngineEx::startAudioMixing ( NERtcCreateAudioMixingOption *  option )

pure virtual

开启伴音。
通过本接口可以实现指定本地或在线音频文件和录音设备采集的音频流进行混音。

自从

V3.5.0

使用前提

发送伴音前必须前调用 enableLocalAudio 方法开启本地音频采集（V4.4.0 版本除外）。

调用时机

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

注解

• 支持的音乐文件类型包括 MP3、M4A、AAC、3GP、WMA 和 WAV 格式，支持本地文件或在线 URL。
• 自 V4.3.0 版本起，若您在通话中途调用此接口播放音乐文件时，手动设置了伴音播放音量或发送音量，则当前通话中再次调用时默认沿用此设置。

参数说明

参数名称	类型	描述
option	NERtcCreateAudioMixingOption	创建伴音任务的配置选项，包括伴音任务类型、伴音文件的绝对路径或 URL 等。

示例代码

NERtcCreateAudioMixingOption option;
memcpy(option.path, path, kNERtcMaxURILength);
option.loop_count = 1;   //伴音播放一次
option.send_enabled = true;  //伴音发送至远端
option.send_volume = 100;    //伴音发送音量100
option.playback_enabled = true;   //本地播放伴音
option.playback_volume = 50;      //本地伴音播放音量50
option.start_timestamp = 0;       //立即播放伴音
option.send_with_audio_type = nertc::kNERtcAudioStreamTypeMain; //伴音走主流
rtc_engine_->startAudioMixing(option);

相关回调

• onAudioMixingStateChanged：本地用户的伴音文件播放状态改变时，本地会触发此回调；可通过此回调接收伴音文件播放状态改变的相关信息，若播放出错，可通过对应错误码排查故障，详细信息请参考 NERtcAudioMixingErrorCode。
• onAudioMixingTimestampUpdate：本地用户的伴音文件播放进度回调。

返回

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

startAudioRecording()

virtual int nertc::IRtcEngineEx::startAudioRecording ( const char *  file_path, int  sample_rate, NERtcAudioRecordingQuality  quality  )

pure virtual

开启客户端本地录音。 通过此接口可以实现录制客户端房间内所有用户混音后的音频流，并将其保存在一个本地录音文件中。

自从

V4.2.0

调用时机

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

注解

客户端只能同时运行一个录音任务；若您在录音过程中重复调用 startAudioRecording 方法，会结束当前录制任务，并重新开始新的录音任务。 本端用户离开房间时，自动停止录音；也可以在通话中随时调用 stopAudioRecording 方法以实现手动停止录音。 请保证录音文件的保存路径存在并且可写，目前支持 WAV（音质保真度高，文件大）、AAC（音质保真度低，文件小）格式的文件。

参数说明

参数名称	类型	描述
file_path	const char*	录音文件在本地保存的绝对路径，需要精确到文件名及格式，例如：sdcard/xxx/audio.aac。
sample_rate	int	录音采样率。单位为赫兹（Hz），可以设置为 16000、32000（默认）、44100 或 48000。
quality	NERtcAudioRecordingQuality	录音音质。此参数仅在 AAC 格式下有效。

示例代码

if (rtc_engine_) {
int res = rtc_engine_->startAudioRecording("c:\\test.wav", 48000, nertc::kNERtcAudioRecordingQualityHigh);
}

相关回调

调用此接口成功后会触发 onAudioRecording 回调，通知音频录制任务状态已更新。音频录制状态码请参考 NERtcAudioRecordingCode。

返回

• 0（kNERtcNoError）：方法调用成功；
• 其他：方法调用失败。
  • 30003（kNERtcErrInvalidParam）： 参数错误，比如设置的采样率无效。
  • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎尚未初始化。
  • 30101（kNERtcErrChannelNotJoined）：尚未加入房间。

startAudioRecordingWithConfig()

virtual int nertc::IRtcEngineEx::startAudioRecordingWithConfig ( const NERtcAudioRecordingConfiguration &  config )

pure virtual

开始客户端录音。 调用该方法后，客户端会录制房间内所有用户混音后的音频流，并将其保存在本地一个录音文件中。录制开始或结束时，自动触发 onAudioRecording() 回调。 指定的录音音质不同，录音文件会保存为不同格式：

• WAV：音质保真度高，文件大。
• AAC：音质保真度低，文件小。

  注解

• 请在加入房间后调用此方法。
• 客户端只能同时运行一个录音任务，正在录音时，如果重复调用 startAudioRecordingWithConfig，会结束当前录制任务，并重新开始新的录音任务。
• 当前用户离开房间时，自动停止录音。您也可以在通话中随时调用 stopAudioRecording 手动停止录音。

  自从

  V4.6.0

  参数

  filePath	录音文件在本地保存的绝对路径，需要精确到文件名及格式。例如：sdcard/xxx/audio.aac。 请确保指定的路径存在并且可写。 目前仅支持 WAV 或 AAC 文件格式。
  sampleRate	录音采样率（Hz），可以设为 16000、32000（默认）、44100 或 48000。
  quality	录音音质，只在 AAC 格式下有效。详细信息请参考 NERtcAudioRecordingQuality 。
  position	录音对象。详细信息请参考 NERtcAudioRecordingPosition。
  cycleTime	循环缓存的最大时长跨度。该参数单位为秒，可以设为 0、10、60、360、900，默认值为 0，即实时写文件。

  返回

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

startBeauty()

virtual int nertc::IRtcEngineEx::startBeauty ( const char *  file_path )

pure virtual

开启美颜功能模块。

• 调用此接口后，开启美颜引擎。如果后续不再需要使用美颜功能，可以调用 stopBeauty 结束美颜功能模块，销毁美颜引擎并释放资源。
• 开启美颜功能模块后，默认无美颜效果，您需要通过 setBeautyEffect 或其他滤镜、贴纸相关接口设置美颜或滤镜效果。

  注解

• 该方法需要在 enableLocalVideo 之前设置。
• 该方法仅适用于 Windows 平台。

  自从

  V4.2.202

  参数

  file_path

  文件文件绝对路径。（例：windows环境下传入xxx\data\beauty\nebeauty）

  返回

• 0: 方法调用成功。
• 30001（kNERtcErrFatal）：方法调用失败。
• 30004（kNERtcErrNotSupported）：不支持美颜功能。

startChannelMediaRelay()

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

pure virtual

开始跨房间媒体流转发。

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

  注解

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

  自从

  V4.3.0

  参数

  config

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

  返回

  成功返回0，其他则失败

startLastmileProbeTest()

virtual int nertc::IRtcEngineEx::startLastmileProbeTest ( const NERtcLastmileProbeConfig &  config )

pure virtual

开始通话前网络质量探测。
启用该方法后，SDK 会通过回调方式反馈上下行网络的质量状态与质量探测报告，包括带宽、丢包率、网络抖动和往返时延等数据。一般用于通话前的网络质量探测场景，用户加入房间之前可以通过该方法预估音视频通话中本地用户的主观体验和客观网络状态。
相关回调如下：

• onLastmileQuality：网络质量状态回调，以打分形式描述上下行网络质量的主观体验。该回调视网络情况在约 5 秒内返回。
• onLastmileProbeResult：网络质量探测报告回调，报告中通过客观数据反馈上下行网络质量。该回调视网络情况在约 30 秒内返回。

  注解

• 请在加入房间（joinChannel）前调用此方法。
• 调用该方法后，在收到 onLastmileQuality 和 onLastmileProbeResult 回调之前请不要调用其他方法，否则可能会由于 API 操作过于频繁导致此方法无法执行。

  自从

  V4.5.0

  参数

  config

  Last mile 网络探测配置。

  返回

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

startScreenCaptureByDisplayId()

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

pure virtual

开启屏幕共享，共享范围为指定屏幕的指定区域。
通过此接口实现屏幕共享后，可以选择共享整个虚拟屏、指定屏幕，或虚拟屏、整个屏幕的某些区域范围。

调用时机

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

注解

该方法仅适用于 macOS 平台；若您使用的是 Windows 平台，请调用 startScreenCaptureByScreenRect 方法。

参数说明

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

示例代码

int64_t display_id = 999;
nertc::NERtcRectangle region_rect = {0,0,0,0};
nertc::NERtcScreenCaptureParameters capture_params;
capture_params.profile = nertc::kNERtcScreenProfileHD1080P;      
capture_params.frame_rate = 15;
capture_params.bitrate = 0;
capture_params.dimensions.height =1080;
capture_params.dimensions.width = 1920;
capture_params.prefer = nertc::NERtcSubStreamContentPrefer;   
capture_params.excluded_window_count = 0;
capture_params.excluded_window_list = nullptr;
rtc_engine_->startScreenCaptureByDisplayId(display_id, region_rect, capture_params);

相关回调

成功调用此方法开启屏幕共享后，远端会触发 onUserSubStreamVideoStart 回调。

返回

• 0（kNERtcNoError）：方法调用成功；
• 其他：方法调用失败。
  • 30003（kNERtcErrInvalidParam）：无效参数。
  • 30005（kErrorInvalidState）：引擎尚未初始化或未找到房间。
  • 30012（kErrorInvalidRender）：未找到画布。
  • 30021（kNERtcErrDesktopCaptureInvalidParam）：宽高帧率码率参数不正确。
  • 30101（kNERtcErrChannelNotJoined）：尚未加入房间。

startScreenCaptureByScreenRect()

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

pure virtual

开启屏幕共享，共享范围为指定屏幕的指定区域。
通过此接口实现屏幕共享后，可以选择共享整个虚拟屏、指定屏幕，或虚拟屏、整个屏幕的某些区域范围。

自从

V3.5.0

调用时机

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

注解

• 该方法仅适用于 Windows 平台；若您使用的是 macOS 平台，请调用 startScreenCaptureByDisplayId 方法。
• 共享区域 region_rect 的坐标是相对于采集区域 screen_rect 而言的，也就是认为 screen_rect 的左上角坐标为原点 (0, 0)，X 轴方向向右增大， Y 轴向下增大。
• 如果设置的共享区域超出了屏幕的边界，则只共享屏幕内的内容；如果将 width 或 height 设为 0, 则共享整个屏幕。

参数说明

参数名称	类型	描述
screen_rect	NERtcRectangle	指定待共享的屏幕相对于虚拟屏的位置。
region_rect	NERtcRectangle	指定待共享区域相对于整个屏幕的位置。比如设定采集到的屏幕帧数据 screen_rect 为 (x:0, y:0, width: 1920, height: 1080)，同时设定共享区域 region_rect 为 (x: 200, y: 10, width: 400, height: 600)，则在 (0,0,1920,1080) 的采集结果的基础上裁剪出指定的这一块区域。
capture_params	NERtcScreenCaptureParameters	屏幕共享的编码参数配置，包括码率、帧率、编码策略、屏蔽窗口列表等。

示例代码

NERtcRectangle rc{100, 100, 500, 800};
nertc::NERtcScreenCaptureParameters capture_params;
capture_params.profile = nertc::kNERtcScreenProfileHD1080P;      
capture_params.frame_rate = 15;
capture_params.bitrate = 0;
capture_params.dimensions.height =1080;
capture_params.dimensions.width = 1920;
capture_params.prefer = nertc::NERtcSubStreamContentPrefer;   
capture_params.excluded_window_count = 0;
capture_params.excluded_window_list = nullptr;
rtc_engine_->startScreenCaptureByScreenRect(rc, {0, 0, 0, 0}, capture_params);

相关回调

成功调用此方法开启屏幕共享后，远端会触发 onUserSubStreamVideoStart 回调。

返回

• 0（kNERtcNoError）：方法调用成功；
• 其他：方法调用失败。
  • 30003（kNERtcErrInvalidParam）：无效参数。
  • 30005（kErrorInvalidState）：引擎尚未初始化或未找到房间。
  • 30012（kErrorInvalidRender）：未找到画布。
  • 30021（kNERtcErrDesktopCaptureInvalidParam）：宽高帧率码率参数不正确。
  • 30101（kNERtcErrChannelNotJoined）：尚未加入房间。

startScreenCaptureByWindowId()

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

pure virtual

通过指定屏幕 ID 开启屏幕共享。
通过此接口实现屏幕共享时，需要指定待共享的屏幕 ID，共享该屏幕的整体画面或指定区域。

调用时机

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

注解

该方法适用于 Windows 和 macOS 平台。

参数说明

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

示例代码

int64_t display_id = 999;
nertc::NERtcRectangle region_rect = {0,0,0,0};
nertc::NERtcScreenCaptureParameters capture_params;
capture_params.profile = nertc::kNERtcScreenProfileHD1080P;      
capture_params.frame_rate = 15;
capture_params.bitrate = 0;
capture_params.dimensions.height =1080;
capture_params.dimensions.width = 1920;
capture_params.prefer = nertc::NERtcSubStreamContentPrefer;   
capture_params.excluded_window_count = 0;
capture_params.excluded_window_list = nullptr;
rtc_engine_->startScreenCaptureByWindowId(window_id, region_rect, capture_params);

相关回调

成功调用此方法开启屏幕共享后，本端会触发 onScreenCaptureStatus，远端会触发 onUserSubStreamVideoStart 回调。

返回

• 0（kNERtcNoError）：方法调用成功；
• 其他：方法调用失败。
  • 30003（kNERtcErrInvalidParam）：无效参数。
  • 30005（kErrorInvalidState）：引擎尚未初始化或未找到房间。
  • 30012（kErrorInvalidRender）：未找到画布。
  • 30021（kNERtcErrDesktopCaptureInvalidParam）：宽高帧率码率参数不正确。
  • 30101（kNERtcErrChannelNotJoined）：尚未加入房间。

startVideoPreview() [1/2]

virtual int nertc::IRtcEngineEx::startVideoPreview ( )

pure virtual

开启视频预览。
通过本接口可以实现在加入房间前启动本地视频预览，支持预览本地摄像头或外部输入视频。

自从

V3.5.0

使用前提

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

调用时机

请在初始化后调用该方法，且该方法仅可当不在房间内时可调用。

业务场景

适用于加入房间前检查设备状态是否可用、预览视频效果等场景。

注解

• 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
• 在加入房间前预览视频效果时设置的美颜、虚拟背景等视频效果在房间内仍然生效；在房间内设置的视频效果在退出房间后预览视频时也可生效。

示例代码

//开启视频预览
rtc_engine_->startVideoPreview(nertc::kNERTCVideoStreamMain);

相关接口

该方法仅适用于视频主流，若您希望开启辅流通道的视频预览，请调用 startVideoPreview 方法。

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30004（kNERtcErrNotSupported）：不支持的操作，比如已经加入房间。
  • 30010（kNERtcErrInvalidVideoProfile）：设置的视频 profile 无效。
  • 30011（kNERtcErrCreateDeviceSourceFail）：设备创建失败。
  • 30012（kNERtcErrInvalidRender）：未设置渲染画布。
  • 30013（kNERtcErrDevicePreviewAlreadyStarted）: 所选设备已经启用预览。

startVideoPreview() [2/2]

virtual int nertc::IRtcEngineEx::startVideoPreview ( NERtcVideoStreamType  type )

pure virtual

开启视频预览。
通过本接口可以实现在加入房间前启动本地视频预览，支持预览本地摄像头或外部输入视频。

自从

V4.6.20

使用前提

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

调用时机

请在初始化后调用该方法，且该方法仅可当不在房间内时可调用。

业务场景

适用于加入房间前检查设备状态是否可用、预览视频效果等场景。

注解

• 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
• 在加入房间前预览视频效果时设置的美颜、虚拟背景等视频效果在房间内仍然生效；在房间内设置的视频效果在退出房间后预览视频时也可生效。

参数说明

参数名称	类型	描述
type	NERtcVideoStreamType	视频通道类型： kNERtcVideoStreamMain：主流。 kNERtcVideoStreamSub：辅流。

示例代码

//开启主流视频通道预览
nertc::NERtcVideoStreamType type = nertc::NERtcVideoStreamType::kNERTCVideoStreamMain; 
startVideoPreview(type);
//开启辅流视频通道预览
nertc::NERtcVideoStreamType type = nertc::NERtcVideoStreamType::kNERTCVideoStreamSub;
startVideoPreview(type);

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30004（kNERtcErrNotSupported）：不支持的操作，比如已经加入房间。
  • 30010（kNERtcErrInvalidVideoProfile）：设置的视频 profile 无效。
  • 30011（kNERtcErrCreateDeviceSourceFail）：设备创建失败。
  • 30012（kNERtcErrInvalidRender）：未设置渲染画布。
  • 30013（kNERtcErrDevicePreviewAlreadyStarted）: 所选设备已经启用预览。

stopAllEffects()

virtual int nertc::IRtcEngineEx::stopAllEffects ( )

pure virtual

停止播放所有音效文件。 通过此接口可以实现在同时播放多个音效文件时，可以一次性停止播放所有文件（含暂停播放的文件）。

自从

V3.5.0

使用前提

请先调用 playEffect 接口播放音效文件。

调用时机

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

示例代码

rtc_engine_->stopAllEffects();

相关接口

可以调用 stopEffect 方法停止播放指定音效文件。

返回

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

stopAudioDump()

virtual int nertc::IRtcEngineEx::stopAudioDump ( )

pure virtual

结束记录音频 dump。

自从

V3.5.0

使用前提

请先调用 startAudioDump 方法开始记录音频 dump。

调用时机

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

示例代码

rtc_engine_->stopAudioDump();

返回

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

stopAudioMixing()

virtual int nertc::IRtcEngineEx::stopAudioMixing ( )

pure virtual

停止伴音。
通过本接口可以实现停止播放本地或在线音频文件，或者录音设备采集的混音音频流。

自从

V3.5.0

调用时机

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

示例代码

rtc_engine->stopAudioMixing();

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：当前状态不支持的操作，比如引擎尚未初始化或当前未在播放伴音。
  • 30101（kNERtcErrChannelNotJoined）：尚未加入房间。

stopAudioRecording()

virtual int nertc::IRtcEngineEx::stopAudioRecording ( )

pure virtual

停止客户端本地录音。 本端用户离开房间时会自动停止本地录音，也可以通过此接口实现在通话过程中随时停止录音。

自从

V4.2.0

使用前提

请先调用 startAudioRecordingWithConfig 方法开启客户端本地音频录制。

调用时机

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

示例代码

if (engine)
{
engine->stopAudioRecording();
}

相关回调

调用此接口成功后会触发 onAudioRecording 回调，通知音频录制任务状态已更新。音频录制状态码请参考 nertc:: NERtcAudioRecordingCode "NERtcAudioRecordingCode"。

返回

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

stopBeauty()

virtual void nertc::IRtcEngineEx::stopBeauty ( )

pure virtual

结束美颜功能模块。
如果后续不再需要使用美颜功能，可以调用 stopBeauty 结束美颜功能模块，SDK 会自动销毁美颜引擎并释放资源。

注解

该方法仅适用于 Windows 平台。

自从

V4.2.202

返回

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

stopChannelMediaRelay()

virtual int nertc::IRtcEngineEx::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）：方法调用成功。

stopEffect()

virtual int nertc::IRtcEngineEx::stopEffect ( uint32_t  effect_id )

pure virtual

停止播放指定音效文件。

自从

V3.5.0

使用前提

请先调用 playEffect 接口播放音效文件。

调用时机

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

参数名称	类型	描述
effect_id	uint32_t	指定音效文件的 ID，每个音效文件均有唯一的 ID。

示例代码

uint32_t effect_id = 999;
rtc_engine_->stopEffect(effect_id);

返回

• 0（kNERtcNoError）：方法调用成功；
• 其他：方法调用失败。
  • 30003（kNERtcErrInvalidParam ）：未找到 ID 对应的音效文件。
  • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎尚未初始化。
  • 30101（kNERtcErrChannelNotJoined）：尚未加入房间。

stopLastmileProbeTest()

virtual int nertc::IRtcEngineEx::stopLastmileProbeTest ( )

pure virtual

停止通话前网络质量探测。

自从

V4.5.0

返回

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

stopScreenCapture()

virtual int nertc::IRtcEngineEx::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）：未找到对应房间。

stopVideoPreview() [1/2]

virtual int nertc::IRtcEngineEx::stopVideoPreview ( )

pure virtual

停止视频预览。
通过此接口可以实现在预览本地视频后关闭预览。

自从

V3.5.0

使用前提

建议在通过 startVideoPreview 接口开启视频预览后调用该方法。

调用时机

请在初始化后调用该方法，且该方法仅可当不在房间内时可调用。

注解

• 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
• 该方法只适用于视频主流，若您希望停止辅流通道的视频预览，请调用 stopVideoPreview 方法。

示例代码

if (rtc_engine_) {
    res = rtc_engine_->stopVideoPreview();
}

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：通用错误，比如引擎未初始化或者使用的是纯音频 SDK。
  • 30003（kNERtcErrInvalidParam）：参数错误，比如因预览的设备被拔出，无法获取到对应的设备 ID。
  • 30004（kNERtcErrNotSupported）：不支持的操作，比如已经加入房间。
  • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎尚未初始化。
  • 30101（kNERtcErrChannelNotJoined）：尚未加入房间。

stopVideoPreview() [2/2]

virtual int nertc::IRtcEngineEx::stopVideoPreview ( NERtcVideoStreamType  type )

pure virtual

停止视频预览。
通过本接口可以实现在预览本地视频后关闭预览。

自从

V4.6.20

使用前提

建议在通过 startVideoPreview 接口开启视频预览后调用该方法。

调用时机

请在初始化后调用该方法，且该方法仅可当不在房间内时可调用。

注解

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

参数说明

参数名称	类型	描述
type	NERtcVideoStreamType	视频通道类型： kNERtcVideoStreamMain：主流。 kNERtcVideoStreamSub：辅流。

示例代码

//关闭主流视频通道预览
nertc::NERtcVideoStreamType type = nertc::NERtcVideoStreamType::kNERTCVideoStreamMain;
stopVideoPreview(type);
//关闭辅流视频通道预览
nertc::NERtcVideoStreamType type = nertc::NERtcVideoStreamType::kNERTCVideoStreamSub;
stopVideoPreview(type);

返回

• 0（kNERtcNoError）：方法调用成功。
• 其他：方法调用失败。
  • 30001（kNERtcErrFatal）：通用错误，比如引擎未初始化或者使用的是纯音频 SDK。
  • 30003（kNERtcErrInvalidParam）：参数错误，比如因预览的设备被拔出，无法获取到对应的设备 ID。
  • 30004（kNERtcErrNotSupported）：不支持的操作，比如已经加入房间。

subscribeAllRemoteAudioStream()

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

pure virtual

取消或恢复订阅所有远端用户的音频主流。
加入房间时，默认订阅所有远端用户的音频主流，您可以通过本接口取消订阅所有远端用户的音频主流。

自从

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::IRtcEngineEx::subscribeRemoteAudioStream ( uid_t  uid, bool  subscribe  )

pure virtual

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

自从

V3.5.0

调用时机

该方法仅在加入房间后收到远端用户开启音频主流的回调 onUserAudioStart 后可调用。

业务场景

适用于需要手动订阅指定用户音频流的场景。

注解

该方法设置内部引擎为启用状态，在 leaveChannel 后设置失效，将恢复至默认。 在开启音频自动订阅且未打开服务端 ASL 自动选路的情况下，调用该接口无效。

参数说明

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

示例代码

//订阅对方uid为12345的音频主流
rtc_engine_->subscribeRemoteAudioStream(uid, true);
//取消订阅对方uid为12345的音频主流
rtc_engine_->subscribeRemoteAudioStream(uid, false);

相关接口

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

返回

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

subscribeRemoteSubStreamAudio()

virtual int nertc::IRtcEngineEx::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）：媒体会话未建立，比如指定用户尚未发布音频辅流。

subscribeRemoteVideoSubStream()

virtual int nertc::IRtcEngineEx::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::IRtcEngineEx::takeLocalSnapshot ( NERtcVideoStreamType  stream_type, NERtcTakeSnapshotCallback *  callback  )

pure virtual

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

注解

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

参数

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

返回

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

takeRemoteSnapshot()

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

pure virtual

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

注解

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

参数

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

返回

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

updateChannelMediaRelay()

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

pure virtual

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

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

  注解

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

  自从

  V4.3.0

  参数

  config

  目标房间配置信息

  返回

  成功返回0，其他则失败

updateLiveStreamTask()

virtual int nertc::IRtcEngineEx::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::IRtcEngineEx::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::IRtcEngineEx::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::IRtcEngineEx::updateScreenCaptureRegion ( const NERtcRectangle &  region_rect )

pure virtual

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

参数

region_rect

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

返回

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

uploadSdkInfo()

virtual void nertc::IRtcEngineEx::uploadSdkInfo ( )

pure virtual

上传 SDK 信息。
只能在加入房间后调用。
上传的信息包括 log 和 Audio dump 等文件。

返回

void

---

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

• api/nertc_engine_ex.h