Documentation

Class: NERtcEngine

NERtcEngine

new NERtcEngine()

Methods

addLiveStreamTask(info)

添加房间推流任务，成功添加后当前用户可以收到该直播流的状态通知。通话中有效。

Parameters:
Name Type Description
info Object

直播任务信息。

Properties
Name Type Description
task_id String

推流任务ID，为推流任务的唯一标识，用于过程中增删任务操作 <64 chars
stream_url String

直播推流地址 <256 chars
server_record_enabled Boolean

服务器录制功能是否开启
ls_mode Number

直播推流模式:

- 0 推流带视频
- 1 推流纯音频
layout Object

视频布局:

Properties
Name Type Description
width number

视频推流宽度
height number

视频推流高度
background_color number

视频推流背景色，(R & 0xff) << 16 | (G & 0xff) << 8 | (B & 0xff)
user_count number

成员布局个数
users Array.<object>

成员布局数组:
users[].uid number

用户id
users[].video_push boolean

是否推送该用户视频流，info.ls_mode=1时无效
users[].adaption number

视频流裁剪模式:

- 0 视频尺寸等比缩放。优先保证视频内容全部显示。因视频尺寸与显示视窗尺寸不一致造成的视窗未被填满的区域填充背景色
- 1 视频尺寸等比缩放。优先保证视窗被填满。因视频尺寸与显示视窗尺寸不一致而多出的视频将被截掉
users[].x number

画面离主画面左边距
users[].y number

画面离主画面上边距
users[].width number

画面在主画面的显示宽度，画面右边超出主画面会失败
users[].height number

画面在主画面的显示高度，画面底边超出主画面会失败
users[].audio_push boolean

是否推送该用户音频流
users[].bg_image object

背景图信息:

Properties
Name Type Description
url String

图片地址
x number

画面离主画面左边距
y number

画面离主画面上边距
width number

画面在主画面的显示宽度，画面右边超出主画面会失败
height number

画面在主画面的显示高度，画面底边超出主画面会失败
Fires:
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

adjustPlaybackSignalVolume(volume)

调节播放音量。

Parameters:
Name Type Description
volume number

播放音量可在 0 ~ 400 范围内进行调节:

- 0:  静音；
- 100: 原始音量；
- 400: 最大可为原始音量的 4 倍（自带溢出保护）。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

adjustRecordingSignalVolume(volume)

调节录音音量。

Parameters:
Name Type Description
volume number

录音信号音量可在 0 ~ 400 范围内进行调节:

- 0: 静音；
- 100: 原始音量；
- 400: 最大可为原始音量的 4 倍（自带溢出保护）。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

enableAudioVolumeIndication(enable, interval)

启用说话者音量提示。该方法允许 SDK 定期向 App 反馈当前谁在说话以及说话者的音量。

启用该方法后，无论频道内是否有人说话，可以通过NERtcEngine#on方法监听 onRemoteAudioVolumeIndication，根据设置的间隔时间返回音量提示事件。
Parameters:
Name Type Description
enable boolean

是否启用说话者音量提示。
interval number

指定音量提示的时间间隔，单位为毫秒。必须设置为 100 毫秒的整数倍值。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

enableDualStreamMode(enable)

设置视频双流发送。

调用该方法控制是否支持发送双流，只对摄像头数据生效，自定义输入、取屏等无效。设置后，会在摄像头重启后生效。
Parameters:
Name Type Description
enable boolean 
- true: 双流发送（默认）
- false: 只发送一个流
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

enableEarback(enabled, volume)

开启或关闭耳返。

请在频道内调用该方法。
Parameters:
Name Type Description
enabled boolean

开启或关闭。
volume number

耳返音量。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

enableLocalAudio(enabled)

开启或关闭本地语音采集或处理

该方法可以重新开启本地语音功能，重新开始本地音频采集及处理。
该方法不影响接收或播放远端音频流。
NOTE:
- 该方法与 NERtcEngine#muteLocalAudioStream 的区别在于:
- NERtcEngine#enableLocalAudio: 开启本地语音采集及处理
- NERtcEngine#muteLocalAudioStream: 停止或继续发送本地音频流
该方法设置内部引擎为启用状态，在 NERtcEngine#leaveChannel 后仍然有效。
Parameters:
Name Type Description
enabled Boolean 
- true: 重新开启本地语音功能，即开启本地语音采集或处理（默认）
- false: 关闭本地语音功能，即停止本地语音采集或处理
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

enableLocalVideo(enabled)

开启或关闭本地视频采集和渲染

该方法启用本地视频采集功能。
该方法设置内部引擎为启用状态，在 NERtcEngine#leaveChannel 后仍然有效。
Parameters:
Name Type Description
enabled boolean

是否启用本地视频:

- true: 开启本地视频采集和渲染 (默认)；
- false: 关闭使用本地摄像头设备。关闭后，远端用户会接收不到本地用户的视频流；但本地用户依然可以接收远端用户的视频流。设置为 false 时，该方法不需要本地有摄像头。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

enumeratePlayoutDevices()

获取系统中所有的播放设备列表。

该方法返回 NERtcDevice[]，包含系统中所有的播放设备。
Returns:
- Array: 调用成功；
- null：调用失败。



NameTypeDescription


NERtcDevice.device_idString设备ID


NERtcDevice.device_nameString设备名称


NERtcDevice.transport_typeNumber设备链接类型:
- audio:
  - 0 未知设备
  - 1 蓝牙设备
  - 2 蓝牙立体声设备
  - 3 蓝牙低功耗设备
  - 4 USB设备
  - 5 HDMI设备
  - 6 内置设备
  - 7 雷电接口设备
  - 8 AirPlay设备
  - 9 虚拟设备
  - 10 其他设备
- video:
  - 0 未知设备
  - 1 USB设备
  - 2 虚拟设备
  - 3 其他设备


NERtcDevice.suspected_unavailableBoolean是否是不推荐设备


NERtcDevice.system_default_deviceBoolean是否是系统默认设备



     - null: 调用失败。
Type
Array.<NERtcDevice>

enumerateRecordDevices()

获取系统中所有的音频采集设备列表。

 该方法返回 NERtcDevice[] 包含系统中所有的音频采集设备。
Returns:
- NERtcDevice[] : 方法调用成功；



NameTypeDescription


NERtcDevice.device_idString设备ID


NERtcDevice.device_nameString设备名称


NERtcDevice.transport_typeNumber设备链接类型:
- audio:
  - 0 未知设备
  - 1 蓝牙设备
  - 2 蓝牙立体声设备
  - 3 蓝牙低功耗设备
  - 4 USB设备
  - 5 HDMI设备
  - 6 内置设备
  - 7 雷电接口设备
  - 8 AirPlay设备
  - 9 虚拟设备
  - 10 其他设备
- video:
  - 0 未知设备
  - 1 USB设备
  - 2 虚拟设备
  - 3 其他设备


NERtcDevice.suspected_unavailableBoolean是否是不推荐设备


NERtcDevice.system_default_deviceBoolean是否是系统默认设备



- NULL: 方法调用失败。
Type
Array.<NERtcDevice> | null

enumerateVideoCaptureDevices()

获取系统中所有的视频采集设备列表。

该方法返回 NERtcDevice[] 包含系统中所有的音频采集设备。
Returns:
- NERtcDevice[] : 调用成功；



NameTypeDescription


NERtcDevice.device_idString设备ID


NERtcDevice.device_nameString设备名称


NERtcDevice.transport_typeNumber设备链接类型:
- audio:
  - 0 未知设备
  - 1 蓝牙设备
  - 2 蓝牙立体声设备
  - 3 蓝牙低功耗设备
  - 4 USB设备
  - 5 HDMI设备
  - 6 内置设备
  - 7 雷电接口设备
  - 8 AirPlay设备
  - 9 虚拟设备
  - 10 其他设备
- video:
  - 0 未知设备
  - 1 USB设备
  - 2 虚拟设备
  - 3 其他设备


NERtcDevice.suspected_unavailableBoolean是否是不推荐设备


NERtcDevice.system_default_deviceBoolean是否是系统默认设备



- NULL: 调用失败。
Type
Array.<NERtcDevice>

enumerateWindows()

Enumerates windows(windows only).

This method returns windowsInfo[] that includes all windows&monitors in the system
NOTE:
You should call NERtcEngine#startScreenCaptureByScreenRect for 'Monitor' type
Returns:
- Returns windowsInfo[] that includes all windows&monitors in the system: Success.



NameTypeDescription


windowsInfo.idnumber窗口id


windowsInfo.nameString窗口title


windowsInfo.leftnumber窗口左边缘坐标


windowsInfo.topnumber窗口上边缘坐标


windowsInfo.rightnumber窗口右边缘坐标


windowsInfo.bottomnumber窗口下边缘坐标



- null: 调用失败。
Type
Array.<windowsInfo>

getAudioMixingCurrentPosition()

获取音乐文件的播放进度。

该方法获取当前伴奏播放进度，单位为毫秒。请在频道内调用该方法。
Returns:
- >= 0: 伴奏播放进度，单位为毫秒；
- 其他: 方法调用失败。
Type
number

getAudioMixingDuration()

获取伴奏时长。

该方法获取伴奏时长，单位为毫秒。请在频道内调用该方法。
Returns:
- >=0: 伴奏时长，单位为毫秒；
- 其他: 方法调用失败。
Type
number

getAudioMixingPlaybackVolume()

获取伴奏播放音量。

该方法获取混音里伴奏的播放音量大小。请在频道内调用该方法。
Returns:
- >= 0: 伴奏播放音量；
- 其他: 方法调用失败。
Type
number

getAudioMixingSendVolume()

获取伴奏发送音量。

该方法获取混音里伴奏的发送音量大小。请在频道内调用该方法。
Returns:
- >=0: 伴奏发送音量；
- 其他: 方法调用失败。
Type
number

getConnectionState()

获取当前网络状态。

Returns:
- 1 没加入频道。
- 2 正在加入频道。
- 3 加入频道成功。
- 4 正在尝试重新加入频道。
- 5 加入频道失败。
Type
number

getEffectPlaybackVolume(effectId)

获取音效播放音量。

该方法获取音效的播放音量大小。请在频道内调用该方法。
Parameters:
Name Type Description
effectId number

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

  • = 0: 音效播放音量；

  • 其他: 方法调用失败。
Type
number

getEffectSendVolume(effectId)

获取音效发送音量。

该方法获取音效的发送音量大小。请在频道内调用该方法。
Parameters:
Name Type Description
effectId number

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

  • =0: 音效发送音量；

  • 其他: 方法调用失败。
Type
number

getErrorDescription(errorCode)

获取错误描述。

Parameters:
Name Type Description
errorCode number

错误码
Returns:

详细错误码描述

Type
number

getPlayoutDevice()

获取当前使用的音频播放设备 ID。

Returns:

deviceID

Type
String

getPlayoutDeviceMute()

获取音频播放设备静音状态。

Returns:
- true: 静音状态。
- false: 非静音状态。
Type
boolean

getPlayoutDeviceVolume()

获取音频播放设备音量。

Returns:
- >=0: 音频播放设备音量。取值范围为 0~255。
- 其他: 方法调用失败。
Type
number

getRecordDevice()

获取当前使用的音频采集设备 ID。

Returns:
- 设备ID： 调用成功
- null: 调用失败。
Type
String

getRecordDeviceMute()

获取音频采集设备静音状态。

Returns:
- true: 静音状态。
- false: 非静音状态。
Type
boolean

getRecordDeviceVolume()

获取音频采集设备音量。

Returns:
- >=0: 音频采集设备音量。取值范围为 0~255。
- 其他: 方法调用失败。
Type
number

getVersion()

查询 SDK 版本号。

Returns:

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

Type
String

getVideoDevice()

获取当前使用的视频采集设备信息。

Returns:

设备ID

Type
String

initialize(context)

初始化 NERTC SDK 服务。

该方法用来进行初始化 NERTC 服务。传入云信为开发者签发的厂商秘钥进行初始化。在使用其他方法前，必须先调用该方法进行初始化。
初始化成功后，默认处于音视频通话模式。
NOTE:
- 必须使用同一个 App Key 才能进行通话。
- 一个 NERtcEngine 实例对象只能使用一个 App Key。如需更换 App Key，必须先调用 NERtcEngine#release 方法释放当前实例资源再调用本方法初始化实例。
Parameters:
Name Type Description
context Object

传入的RTC engine context对象: NERtcEngineContext.

Properties
Name Type Argument Default Description
app_key String

用户注册云信的APP Key。如果你的开发包里面缺少 APP Key，请申请注册一个新的 APP Key。
log_dir_path String

日志目录的完整路径，采用UTF-8 编码。
log_level number <optional>
 3

日志级别，默认级别为 kNERtcLogLevelInfo。

- 0 Fatal级别日志信息
- 1 Error级别日志信息
- 2 Warning级别日志信息
- 3 Info级别日志信息。默认级别
- 4 DetailInfo级别日志信息
- 5 Verbos级别日志信息
- 6 Debug级别日志信息。如果你想获取最完整的日志，可以将日志级别设为该等级
- 7 不输出日志信息
log_file_max_size_KBytes number <optional>
 20480

指定 SDK 输出日志文件的大小上限，单位为 KB。如果设置为 0，则默认为 20 M。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

joinChannel(token, channelName, uid)

加入频道。如果频道还未创建，会自动尝试创建频道。

该方法让用户加入通话频道，在同一个频道内的用户可以互相通话，多个用户加入同一个频道，可以群聊。 使用不同 App Key 的 App 是不能互通的。如果已在通话中，用户必须调用 NERtcEngine#leaveChannel 退出当前通话，才能进入下一个频道。
频道内每个用户的用户 ID 必须是唯一的。
Parameters:
Name Type Description
token String

动态秘钥。安全要求不高: 将值设为 空字符串。安全要求高: 将值设置为 Token。如果你已经启用了 App Certificate, 请务必使用 Token。
channelName String

标识通话的频道名称，长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）: a-z, A-Z, 0-9, space, !#$%&()+-:;≤.,>? @[]^_{|}~”
uid number

用户ID。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

leaveChannel()

离开频道。

离开频道，即挂断或退出通话。
当调用 NERtcEngine#joinChannel 方法后，必须调用 NERtcEngine#leaveChannel 结束通话，否则无法开始下一次通话。 不管当前是否在通话中，都可以调用 leaveChannel，没有副作用。该方法会把会话相关的所有资源释放掉。
该方法是异步操作，调用返回时并没有真正退出频道。在真正退出频道后，SDK 会触发 onLeaveChannel 事件。
如果你调用了 NERtcEngine#leaveChannel 后立即调用 NERtcEngine#release , SDK 将无法触发 onLeaveChannel 事件。
Fires:
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

muteLocalAudioStream(mute)

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

该方法不影响录音状态，因为并没有禁用录音设备。
Parameters:
Name Type Description
mute boolean

静音/取消静音:

- true: 静音本地音频
- false: 取消静音本地音频（默认）
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

muteLocalVideoStream(mute)

开关本地视频发送。

调用该方法禁视频流时，SDK 不再发送本地视频流，但摄像头仍然处于工作状态。相比于 NERtcEngine#enableLocalVideo (false) 用于控制本地视频流发送的方法，该方法响应速度更快。该方法不影响本地视频流获取，没有禁用摄像头。
Parameters:
Name Type Description
mute boolean 
- true: 不发送本地视频流
- false: 发送本地视频流（默认）
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

pauseAllEffects()

暂停所有音效文件播放。

请在频道内调用该方法。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

pauseAudioMixing()

暂停播放伴奏。

该方法暂停播放伴奏。请在频道内调用该方法。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

pauseEffect(effectId)

暂停音效文件播放。

请在频道内调用该方法。
Parameters:
Name Type Description
effectId number

指定音效的 ID。每个音效均有唯一的 ID。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

pauseScreenCapture()

暂停屏幕共享。

Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

playEffect(effectId, opt)

播放指定音效文件。

你可以多次调用该方法，通过传入不同的音效文件的 effect_id 和 option ，同时播放多个音效文件，实现音效叠加。为获得最佳用户体验，我们建议同时播放的音效文件不要超过 3 个。成功调用该方法后，可以通过NERtcEngine#on方法监听 onAudioEffectFinished 播放结束事件。
请在频道内调用该方法，如果在频道外调用该方法可能会出现问题。
Parameters:
Name Type Argument Default Description
effectId number

指定音效的 ID。每个音效均有唯一的 ID。
opt Array.<object>

创建音效任务配置的选项，包括混音任务类型、混音文件全路径或URL等。支持的音频格式包括: AAC、MP3 和 WAVE。
opt[].path String

本地文件全路径或URL <256 chars
opt[].loop_count number <optional>
 1

循环次数， <= 0, 表示无限循环，默认 1
opt[].send_enabled boolean <optional>
 true

是否可发送，默认为 true
opt[].send_volume number

发送音量。最大为 100（默认）含义（0%-100%）
opt[].playback_enabled boolean <optional>
 true

是否可回放，默认为 true
opt[].playback_volume number

回放音量。最大为 100（默认）
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

release()

释放资源。

removeLiveStreamTask(taskId)

删除房间推流任务。通话中有效。

Parameters:
Name Type Description
taskId String

直播任务id
Fires:
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

resumeAllEffects()

恢复播放所有音效文件。

请在频道内调用该方法。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

resumeAudioMixing()

恢复播放伴奏。

该方法恢复混音，继续播放伴奏。请在频道内调用该方法。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

resumeEffect(effectId)

恢复播放指定音效文件。

请在频道内调用该方法。
Parameters:
Name Type Description
effectId number

指定音效的 ID。每个音效均有唯一的 ID。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

resumeScreenCapture()

恢复屏幕共享。

Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setAudioMixingPlaybackVolume(volume)

调节伴奏播放音量。

该方法调节混音里伴奏的播放音量大小。请在频道内调用该方法。
Parameters:
Name Type Description
volume number

伴奏音量范围为 0~100。默认 100 为原始文件音量。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setAudioMixingPosition(pos)

设置音乐文件的播放位置。

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

进度条位置，单位为毫秒。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setAudioMixingSendVolume(volume)

调节伴奏发送音量。

该方法调节混音里伴奏的发送音量大小。请在频道内调用该方法。
Parameters:
Name Type Description
volume number

伴奏音量范围为 0~100。默认 100 为原始文件音量。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setAudioProfile(profile, scenario)

设置音频编码属性。

NOTE:
- 该方法需要在 NERtcEngine#joinChannel 之前设置好， NERtcEngine#joinChannel 之后设置不生效。
- 音乐场景下，建议将 profile 设置为 4.
Parameters:
Name Type Description
profile number

设置采样率，码率，编码模式和声道数:

- 0 默认设置。Speech场景下为 1，Music场景下为 2
- 1 普通质量的音频编码，16000Hz，20Kbps
- 2 普通质量的音频编码，16000Hz，32Kbps
- 3 中等质量的音频编码，48000Hz，32Kbps
- 4 中等质量的立体声编码，48000Hz * 2，64Kbps
- 5 高质量的音频编码，48000Hz，64Kbps
- 6 高质量的立体声编码，48000Hz * 2，128Kbps
scenario number

设置音频应用场景:

- 0: 默认设置: 通过NERtcEngine#setChannelProfile设置通话模式时为语音场景(1)，直播推流模式时为音乐场景(2)。
- 1: 语音场景. profile 推荐使用 2 及以下
- 2: 音乐场景。profile 推荐使用 3 及以上
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setChannelProfile(profile)

设置通话模式

必须在加入通话前设置，开始通话后设置无效，结束通话后保留之前的设置。
Parameters:
Name Type Description
profile number

场景模式

- 通话场景(0)
- 直播推流场景(1)
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setClientRole(role)

设置参会者角色

NERtcEngine#setClientRole 接口用于在直播场景中设置用户角色。默认情况下用户以主播角色加入房间。
在加入房间前，用户需要调用setClientRole 接口设置本端模式为观众或主播模式。在加入房间后，用户可以通过本接口切换用户模式。
用户角色支持设置为主播或观众，主播和观众的权限不同。默认情况下用户以主播角色加入房间。
可以在通话前后设置，通话前设置会在加入频道之后生效。如果设置观众模式。则会停止音视频设备。
Parameters:
Name Type Description
role number

参会者模式

- 主播(0)：可以开关摄像头等设备、可以发布流、可以操作互动直播推流相关接口、上下线对其他房间内用户可见
- 观众(1)：不可以开关摄像头等设备、不可以发布流、不可以操作互动直播推流相关接口、上下线对其他房间内用户不可见
Fires:
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setEarbackVolume(volume)

设置耳返音量。

请在频道内调用该方法。
Parameters:
Name Type Description
volume number

耳返音量。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setEffectPlaybackVolume(effectId, volume)

调节音效播放音量。

该方法调节音效的播放音量大小。请在频道内调用该方法。
Parameters:
Name Type Description
effectId number

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

音效音量范围为 0~100。默认 100 为原始文件音量。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setEffectSendVolume(effectId, volume)

调节音效发送音量。

该方法调节音效的发送音量大小。请在频道内调用该方法。
Parameters:
Name Type Description
effectId number

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

音效音量范围为 0~100。默认 100 为原始文件音量。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setLocalVideoMirrorMode(mode)

设置本地视频镜像模式。

该方法设置本地视频镜像模式。 App 可以多次调用此方法更改镜像模式。
Parameters:
Name Type Description
mode number

视频镜像模式:

- 0 Windows/macOS SDK 启用镜像模式。
- 1 启用镜像模式。
- 2 （默认）关闭镜像模式。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setParameters(parameters)

通过 JSON 配置 SDK 提供技术预览或特别定制功能。以标准化方式公开 JSON 选项。

Parameters:
Name Type Description
parameters object

JSON 字符串形式的参数

Properties
Name Type Argument Default Description
record_host_enabled boolean 
- true 录制主讲人
- false 不是录制主讲人
record_audio_enabled boolean <optional>
 false

启用服务器音频录制。默认值 false
record_video_enabled boolean <optional>
 false

启用服务器视频录制。默认值 false
record_type number

录制类型：

- 0 参与混合录制且录制单人文件
- 1 参与混合录制
- 2 只录单人文件
auto_subscribe_audio boolean <optional>
 true

其他用户打开音频时，自动订阅。 默认值 true
publish_self_stream_enabled boolean <optional>
 false

开启旁路直播。默认值 false
log_level number <optional>
 3

日志级别，默认级别为 kNERtcLogLevelInfo。

- 0 Fatal级别日志信息
- 1 Error级别日志信息
- 2 Warning级别日志信息
- 3 Info级别日志信息。默认级别
- 4 DetailInfo级别日志信息
- 5 Verbos级别日志信息
- 6 Debug级别日志信息。如果你想获取最完整的日志，可以将日志级别设为该等级
- 7 不输出日志信息
audio_processing_aec_enable boolean <optional>
 true

AEC开关，默认值 true
audio_processing_agc_enable boolean <optional>
 true

AGC开关，默认值 true
audio_processing_ns_enable boolean <optional>
 true

NS开关，默认值 true
audio_processing_ai_ns_enable boolean <optional>
 false

AI NS开关，建议通话前修改，默认值 false
audio_processing_external_audiomix_enable boolean <optional>
 false

输入混音开关，默认值 false
audio_processing_earphone boolean <optional>
 false

通知SDK是否使用耳机:

- true: 使用耳机
- false: 不使用耳机
video_sendonpub_type number <optional>
 1

设置视频发送策略，默认发送大流(1)；通话前设置有效

- 0 不主动发送数据流，被订阅后发送。
- 1 主动发送大流。
- 2 主动发送小流。
- 3 主动发送大小流。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setPlayoutDevice(id)

指定播放设备。

Parameters:
Name Type Description
id String

音频播放设备的设备 ID。可以通过 NERtcEngine#enumeratePlayoutDevices 获取。插拔设备不会影响 deviceId。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setPlayoutDeviceMute(mute)

静音或取消静音音频播放设备。

Parameters:
Name Type Description
mute

是否静音音频播放设备。

- true: 静音音频播放设备。
- false: 取消静音音频播放设备。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setPlayoutDeviceVolume(volume)

设置音频播放设备音量。

Parameters:
Name Type Description
volume number

音频播放设备音量。取值范围为 0~255。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setRecordDevice(id)

指定音频采集设备。

Parameters:
Name Type Description
id String

音频采集设备的设备 ID。可通过 NERtcEngine#enumerateRecordDevices 获取。插拔设备不会影响 deviceId。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setRecordDeviceMute(mute)

静音或取消静音音频采集设备。

Parameters:
Name Type Description
mute boolean

是否静音音频采集设备。

- true: 静音音频采集设备。
- false: 取消静音音频采集设备。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setRecordDeviceVolume(volume)

设置音频采集设备音量。

Parameters:
Name Type Description
volume number

音频采集设备音量。取值范围为 0~255。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setRenderMode(uid, mode)

设置本地视图/远端视图显示模式。

该方法设置视图显示模式。App 可以多次调用此方法更改显示模式。
Parameters:
Name Type Description
uid string | number 
'local':本地视图
{number}: 远端用户 ID。
mode number

视频显示模式:

- 0 视频尺寸等比缩放。优先保证视频内容全部显示。因视频尺寸与显示视窗尺寸不一致造成的视窗未被填满的区域填充黑色。
- 1 视频尺寸非等比缩放。保证视频内容全部显示，且填满视窗。
- 2 视频尺寸等比缩放。优先保证视窗被填满。因视频尺寸与显示视窗尺寸不一致而多出的视频将被截掉。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setSubStreamRenderMode(uid, mode)

设置辅流视图/远端辅流视图显示模式。

该方法设置视图显示模式。App 可以多次调用此方法更改显示模式。
Parameters:
Name Type Description
uid string | number 
'local':本地辅流视图
{number}: 远端辅流用户 ID。
mode number

视频显示模式:

- 0 视频尺寸等比缩放。优先保证视频内容全部显示。因视频尺寸与显示视窗尺寸不一致造成的视窗未被填满的区域填充黑色。
- 1 视频尺寸非等比缩放。保证视频内容全部显示，且填满视窗。
- 2 视频尺寸等比缩放。优先保证视窗被填满。因视频尺寸与显示视窗尺寸不一致而多出的视频将被截掉。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setupLocalSubStreamVideoCanvas(canvas)

设置本地辅流视图。

该方法设置本地辅流视频显示信息。App 通过调用此接口绑定本地辅流的显示视窗(view)。 在 App 开发中，通常在初始化后调用该方法进行本地视频设置，然后再加入频道。
Parameters:
Name Type Description
canvas Object

视频画布信息

Properties
Name Type Description
mode number

视频显示模式

- 0 视频尺寸等比缩放。优先保证视频内容全部显示。因视频尺寸与显示视窗尺寸不一致造成的视窗未被填满的区域填充黑色。
- 1 视频尺寸非等比缩放。保证视频内容全部显示，且填满视窗。
- 2 视频尺寸等比缩放。优先保证视窗被填满。因视频尺寸与显示视窗尺寸不一致而多出的视频将被截掉。
view Element

视频画布对象
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setupLocalVideoCanvas(canvas)

设置本地视图。

该方法设置本地视频显示信息。App 通过调用此接口绑定本地视频流的显示视窗(view)。 在 App 开发中，通常在初始化后调用该方法进行本地视频设置，然后再加入频道。
Parameters:
Name Type Description
canvas Object

视频画布信息

Properties
Name Type Description
mode number

视频画布缩放模式

- 0 视频尺寸等比缩放。优先保证视频内容全部显示。因视频尺寸与显示视窗尺寸不一致造成的视窗未被填满的区域填充黑色。
- 1 视频尺寸非等比缩放。保证视频内容全部显示，且填满视窗。
- 2 视频尺寸等比缩放。优先保证视窗被填满。因视频尺寸与显示视窗尺寸不一致而多出的视频将被截掉。
view Element

视频画布对象
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setupRemoteSubStreamVideoCanvas(uid, canvas)

设置远端用户辅流视图。

该方法绑定远端用户和辅流显示视图，即设定 uid 指定的用户用哪个视图显示。调用该接口时需要指定远端视频的 uid，一般可以在用户加入后设置好。
NODE:
- 如果 App 不能事先知道对方的 uid，可以通过NERtcEngine#on方法监听 onUserJoined 事件时设置。
- 退出频道后，SDK 会把远端用户的绑定关系清除掉。
Parameters:
Name Type Description
uid number

远端用户 ID。
canvas Object

视频画布信息

Properties
Name Type Description
mode number

视频显示模式

- 0 视频尺寸等比缩放。优先保证视频内容全部显示。因视频尺寸与显示视窗尺寸不一致造成的视窗未被填满的区域填充黑色。
- 1 视频尺寸非等比缩放。保证视频内容全部显示，且填满视窗。
- 2 视频尺寸等比缩放。优先保证视窗被填满。因视频尺寸与显示视窗尺寸不一致而多出的视频将被截掉。
view Element

视频画布对象
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setupRemoteVideoCanvas(uid, canvas)

设置远端用户视图。

该方法绑定远端用户和显示视图，即设定 uid 指定的用户用哪个视图显示。调用该接口时需要指定远端视频的 uid，一般可以在用户加入后设置好。
如果 App 不能事先知道对方的 uid，可以在 APP 收到 onUserJoined 事件时设置。
退出频道后，SDK 会把远端用户的绑定关系清除掉。
Parameters:
Name Type Description
uid number

远端用户 ID。
canvas Object

视频画布信息

Properties
Name Type Description
mode number

视频画布缩放模式

- 0 视频尺寸等比缩放。优先保证视频内容全部显示。因视频尺寸与显示视窗尺寸不一致造成的视窗未被填满的区域填充黑色。
- 1 视频尺寸非等比缩放。保证视频内容全部显示，且填满视窗。
- 2 视频尺寸等比缩放。优先保证视窗被填满。因视频尺寸与显示视窗尺寸不一致而多出的视频将被截掉。
view Element

视频画布对象
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setVideoConfig(config)

设置视频配置。

该方法设置视频配置。每个属性对应一套视频参数，如分辨率等，会在摄像头重启后生效。 所有设置的参数均为理想情况下的最大值。当视频引擎因网络环境等原因无法达到设置的分辨率的最大值时，会取最接近最大值的那个值。
Parameters:
Name Type Description
config object

视频配置:

Properties
Name Type Argument Default Description
max_profile number

视频编码的分辨率，用于衡量编码质量:

- 0 160x90/120, 15fps
- 1 320x180/240, 15fps
- 2 640x360/480, 30fps
- 3 1280x720, 30fps
- 4 1920x1080, 30fps
width number

视频编码自定义分辨率之宽度。width为0表示使用max_profile
height number

视频编码自定义分辨率之高度。height为0表示使用max_profile
crop_mode number

视频画面裁剪模式:

- 0 Device Defalut
- 1 16:9
- 2 4:3
- 3 1:1
framerate number

视频帧率:

- 0 默认帧率
- 7 7帧每秒
- 10 10帧每秒
- 15 15帧每秒
- 24 24帧每秒
- 30 30帧每秒
min_framerate number

视频最小帧率:

- 0 默认帧率
- 7 7帧每秒
- 10 10帧每秒
- 15 15帧每秒
- 24 24帧每秒
- 30 30帧每秒
bitrate number <optional>
 0

视频编码码率kbps，取0时使用默认值
min_bitrate number <optional>
 0

视频编码码率下限kbps，取0时使用默认值
degradation_preference number

编码策略:

- 0 使用引擎推荐值。通话场景使用平衡模式，直播推流场景使用清晰优先
- 1 帧率优先
- 2 清晰度优先
- 3 平衡模式
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setVideoDevice(id)

指定视频采集设备。

Parameters:
Name Type Description
id string

视频采集设备的设备 ID。可以通过 NERtcEngine#enumerateCaptureDevices获取。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

startAudioDeviceLoopbackTest(interval)

开始音频设备回路测试。

该方法测试音频采集和播放设备是否能正常工作。一旦测试开始，音频采集设备会采集本地音频，然后使用音频播放设备播放出来。 可以通过 NERtcEngine#on监听 onLocalAudioVolumeIndication 报告音量信息的事件。
NOTE:
- 该方法需在加入房间前调用。
- 音频设备回路测试会在通话开始后自动结束，您也可以手动调用 NERtcEngine#stopAudioDeviceLoopbackTest 停止音频设备回路测试。
- 该方法仅在本地进行音频设备测试，不涉及网络连接。
Parameters:
Name Type Description
interval number

事件上报的时间间隔，单位为毫秒。
Fires:
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

startAudioDump()

开启音频dump。

Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

startAudioMixing(option)

开始播放伴奏。

指定本地或在线音频文件来和录音设备采集的音频流进行混音。成功调用该方法后，可以通过NERtcEngine#on方法监听 onAudioMixingStateChanged 播放状态改变事件。
请在频道内调用该方法，如果在频道外调用该方法可能会出现问题。
Parameters:
Name Type Description
option object

创建混音任务配置的选项，包括混音任务类型、混音文件全路径或URL等。支持的音频格式包括: AAC、MP3 和 WAVE。

Properties
Name Type Argument Default Description
path string

本地文件全路径或URL <256 chars
loop_count number <optional>
 1

循环次数， <= 0, 表示无限循环，默认 1
send_enabled boolean <optional>
 true

是否可发送，默认为 true
send_volume number <optional>
 100

发送音量。最大为 100（默认）含义（0%-100%）
playback_enabled boolean <optional>
 true

是否可回放，默认为 true
playback_volume number <optional>
 100

回放音量。最大为 100（默认）
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

startPlayoutDeviceTest(path)

启动音频播放设备测试。

该方法测试音频播放设备是否能正常工作。启动测试后，SDK 播放指定的音频文件，测试者如果能听到声音，说明播放设备能正常工作。调用该方法后，可以通过NERtcEngine#on方法监听 onLocalAudioVolumeIndication (每隔 100 ms)
NOTE:
- 该方法需在加入房间前调用。
- 音频播放设备测试会在通话开始后自动结束，您也可以手动调用 NERtcEngine#stopPlayoutDeviceTest 停止音频播放设备测试。
- 支持文件格式包括 wav、mp3、aac。
Parameters:
Name Type Description
path string

音频文件的绝对路径，路径字符串使用 UTF-8 编码格式。
Fires:
Returns:
- 0: 方法调用成功，并且可以听到所设置文件的声音。
- 其他: 方法调用失败。
Type
number

startRecordDeviceTest(interval)

启动音频采集设备测试。

该方法测试音频采集设备是否能正常工作。调用该方法后，可以通过NERtcEngine#on方法监听 onLocalAudioVolumeIndication 报告采集设备的音量信息事件。
NOTE:
- 该方法需在加入房间前调用。
- 音频采集设备测试会在通话开始后自动结束，您也可以手动调用 NERtcEngine#stopRecordDeviceTest 停止音频采集设备测试。
Parameters:
Name Type Description
interval number

事件上报的时间间隔，单位为毫秒。
Fires:
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

startScreenCaptureByDisplayId(displayId [, regionRect=], param)

通过屏幕 ID 共享屏幕。共享一个屏幕或该屏幕的部分区域。用户需要在该方法中指定想要共享的屏幕 ID。

NOTE:
- 该方法仅适用于 macOS。
- 该方法打开视频辅流。
Parameters:
Name Type Argument Description
displayId number

指定待共享的屏幕 ID。开发者需要通过该参数指定你要共享的那个屏幕。
regionRect= object <optional>

(可选) 指定待共享区域相对于整个屏幕屏幕的位置。如果设置的共享区域超出了屏幕的边界，则只共享屏幕内的内容；如果将 width 或 height 设为 0, 则共享整个屏幕。
regionRect.x number

左上角的横向偏移
regionRect.y number

左上角的纵向偏移
regionRect.width number

待共享区域的宽
regionRect.height number

待共享区域的高
param object

屏幕共享的编码参数配置。

Properties
Name Type Argument Default Description
profile object <optional>
 2

屏幕共享编码参数配置:

- 0 640x480, 5fps
- 1 1280x720, 5fps
- 2 1920x1080, 5fps。默认
- 3 自定义
dimensions object

屏幕共享视频发送的最大像素值，param.profile=3时生效:

Properties
Name Type Description
width number

宽度
height number

高度
frame_rate number <optional>
 5

共享视频的帧率，param.profile=3时生效，单位为 fps；默认值为 5，建议不要超过 15
bitrate number <optional>
 0

共享视频的码率，单位为 bps；默认值为 0，表示 SDK 根据当前共享屏幕的分辨率计算出一个合理的值
capture_mouse_cursor boolean

是否采集鼠标用于屏幕共享
window_focus boolean

调用 NERtcEngine#startScreenCaptureByWindowId 方法共享窗口时，是否将该窗口前置
excluded_window_list Array.<number>

待屏蔽窗口的 ID 列表
excluded_window_count number

待屏蔽窗口的数量
prefer number

编码策略倾向:

- 0 动画模式
- 1 细节模式
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

startScreenCaptureByScreenRect(screenRect [, regionRect=], param)

通过指定区域共享屏幕。共享一个屏幕或该屏幕的部分区域。用户需要在该方法中指定想要共享的屏幕区域。

NOTE:
- 该方法仅适用于 Windows。
- 该方法打开视频辅流。
Parameters:
Name Type Argument Description
screenRect object

指定待共享的屏幕相对于虚拟屏的位置。

Properties
Name Type Description
x number

左上角的横向偏移
y number

左上角的纵向偏移
width number

待共享区域的宽
height number

待共享区域的高
regionRect= object <optional>

(可选) 指定待共享区域相对于整个屏幕屏幕的位置。如果设置的共享区域超出了屏幕的边界，则只共享屏幕内的内容；如果将 width 或 height 设为 0, 则共享整个屏幕。
regionRect.x number

左上角的横向偏移
regionRect.y number

左上角的纵向偏移
regionRect.width number

待共享区域的宽
regionRect.height number

待共享区域的高
param object

屏幕共享的编码参数配置。

Properties
Name Type Argument Default Description
profile object <optional>
 2

屏幕共享编码参数配置:

- 0 640x480, 5fps
- 1 1280x720, 5fps
- 2 1920x1080, 5fps。默认
- 3 自定义
dimensions object

屏幕共享视频发送的最大像素值，param.profile=3时生效:

Properties
Name Type Description
width number

宽度
height number

高度
frame_rate number <optional>
 5

共享视频的帧率，param.profile=3时生效，单位为 fps；默认值为 5，建议不要超过 15
bitrate number <optional>
 0

共享视频的码率，单位为 bps；默认值为 0，表示 SDK 根据当前共享屏幕的分辨率计算出一个合理的值
capture_mouse_cursor boolean

是否采集鼠标用于屏幕共享
window_focus boolean

调用 NERtcEngine#startScreenCaptureByWindowId 方法共享窗口时，是否将该窗口前置
excluded_window_list Array.<number>

待屏蔽窗口的 ID 列表
excluded_window_count number

待屏蔽窗口的数量
prefer number

编码策略倾向:

- 0 动画模式
- 1 细节模式
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

startScreenCaptureByWindowId(windowid [, regionRect=], param)

通过窗口 ID 共享窗口。共享一个窗口或该窗口的部分区域。用户需要在该方法中指定想要共享的窗口 ID。

NOTE:
- 该方法仅适用于 Windows 和 macOS。
- 该方法打开视频辅流。
Parameters:
Name Type Argument Description
windowid number

指定待共享的窗口 ID。
regionRect= object <optional>

(可选) 指定待共享区域相对于整个屏幕屏幕的位置。如果设置的共享区域超出了屏幕的边界，则只共享屏幕内的内容；如果将 width 或 height 设为 0, 则共享整个屏幕。
regionRect.x number

左上角的横向偏移
regionRect.y number

左上角的纵向偏移
regionRect.width number

待共享区域的宽
regionRect.height number

待共享区域的高
param object

屏幕共享的编码参数配置。

Properties
Name Type Argument Default Description
profile object <optional>
 2

屏幕共享编码参数配置:

- 0 640x480, 5fps
- 1 1280x720, 5fps
- 2 1920x1080, 5fps。默认
- 3 自定义
dimensions object

屏幕共享视频发送的最大像素值，param.profile=3时生效:

Properties
Name Type Description
width number

宽度
height number

高度
frame_rate number <optional>
 5

共享视频的帧率，param.profile=3时生效，单位为 fps；默认值为 5，建议不要超过 15
bitrate number <optional>
 0

共享视频的码率，单位为 bps；默认值为 0，表示 SDK 根据当前共享屏幕的分辨率计算出一个合理的值
capture_mouse_cursor boolean

是否采集鼠标用于屏幕共享
window_focus boolean

调用 NERtcEngine#startScreenCaptureByWindowId 方法共享窗口时，是否将该窗口前置
excluded_window_list Array.<number>

待屏蔽窗口的 ID 列表
excluded_window_count number

待屏蔽窗口的数量
prefer number

编码策略倾向:

- 0 动画模式
- 1 细节模式
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

startVideoPreview()

开启视频预览。

该方法用于在进入频道前启动本地视频预览。调用该 API 前，必须:
- 调用 NERtcEngine#setupLocalVideoCanvas 设置预览窗口；
启用了本地视频预览后，在进入频道前，本地预览必须先关闭，需要调用 NERtcEngine#stopVideoPreview 。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

stopAllEffects()

停止播放所有音效文件。

Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

stopAudioDeviceLoopbackTest()

停止音频设备回路测试。

NOTE:
- 该方法需在加入房间前调用。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

stopAudioDump()

结束音频dump。

Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

stopAudioMixing()

停止播放伴奏。

该方法停止播放伴奏。请在频道内调用该方法。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

stopEffect(effectId)

停止播放指定音效文件。

请在频道内调用该方法。
Parameters:
Name Type Description
effectId number

指定音效的 ID。每个音效均有唯一的 ID。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

stopPlayoutDeviceTest()

停止播放设备测试。

NOTE:
- 该方法需在加入房间前调用。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

stopRecordDeviceTest()

停止音频采集设备测试。

该方法停止音频采集设备测试。
NOTE:
- 该方法需在加入房间前调用。
- 音频采集设备测试会在通话开始后自动结束，您也可以手动调用 NERtcEngine#stopRecordDeviceTest 停止音频采集设备测试。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

stopScreenCapture()

停止屏幕共享。

Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

stopVideoPreview()

停止视频预览。

Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

subscribeRemoteAudioStream(uid, subscribe)

订阅／取消订阅指定音频流。

Parameters:
Name Type Description
uid number

指定用户的 ID
subscribe boolean 
- true: 订阅指定音频流（默认）；
- false: 取消订阅指定音频流。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

subscribeRemoteVideoStream(uid, type, subscribe)

订阅 / 取消订阅指定远端用户的视频流。对方打开视频后需要主动订阅

Parameters:
Name Type Description
uid number

指定用户的用户 ID。
type number

流类型:

- 0 默认大流
- 1 小流
- 2 不订阅
subscribe boolean 
- true: 订阅指定远端用户的视频流；
- false: 取消订阅指定远端用户的视频流。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

subscribeRemoteVideoSubStream(uid, subscribe)

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

对方打开视频后需要主动订阅
NOTE:
- 必须在远端加入房间后调用。
- 必须先设置远端辅流画布。
Parameters:
Name Type Description
uid number

指定用户的用户 ID。
subscribe number 
- true: 订阅指定远端用户的视频流；
- false: 取消订阅指定远端用户的视频流。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

updateLiveStreamTask(info)

更新修改房间推流任务。通话中有效。

Parameters:
Name Type Description
info Object

直播任务信息。

Properties
Name Type Description
task_id String

推流任务ID，为推流任务的唯一标识，用于过程中增删任务操作 <64 chars
stream_url String

直播推流地址 <256 chars
server_record_enabled Boolean

服务器录制功能是否开启
ls_mode Number

直播推流模式:

- 0 推流带视频
- 1 推流纯音频
layout Object

视频布局:

Properties
Name Type Description
width number

视频推流宽度
height number

视频推流高度
background_color number

视频推流背景色，(R & 0xff) << 16 | (G & 0xff) << 8 | (B & 0xff)
user_count number

成员布局个数
users Array.<object>

成员布局数组:
users[].uid number

用户id
users[].video_push boolean

是否推送该用户视频流，info.ls_mode=1时无效
users[].adaption number

视频流裁剪模式:

- 0 视频尺寸等比缩放。优先保证视频内容全部显示。因视频尺寸与显示视窗尺寸不一致造成的视窗未被填满的区域填充背景色
- 1 视频尺寸等比缩放。优先保证视窗被填满。因视频尺寸与显示视窗尺寸不一致而多出的视频将被截掉
users[].x number

画面离主画面左边距
users[].y number

画面离主画面上边距
users[].width number

画面在主画面的显示宽度，画面右边超出主画面会失败
users[].height number

画面在主画面的显示高度，画面底边超出主画面会失败
users[].audio_push boolean

是否推送该用户音频流
users[].bg_image object

背景图信息:

Properties
Name Type Description
url String

图片地址
x number

画面离主画面左边距
y number

画面离主画面上边距
width number

画面在主画面的显示宽度，画面右边超出主画面会失败
height number

画面在主画面的显示高度，画面底边超出主画面会失败
Fires:
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

updateScreenCaptureRegion(param)

在共享屏幕或窗口时，更新共享的区域。

Parameters:
Name Type Description
param object

屏幕共享的编码参数配置。

Properties
Name Type Argument Default Description
profile object <optional>
 2

屏幕共享编码参数配置:

- 0 640x480, 5fps
- 1 1280x720, 5fps
- 2 1920x1080, 5fps。默认
- 3 自定义
dimensions object

屏幕共享视频发送的最大像素值，param.profile=3时生效:

Properties
Name Type Description
width number

宽度
height number

高度
frame_rate number <optional>
 5

共享视频的帧率，param.profile=3时生效，单位为 fps；默认值为 5，建议不要超过 15
bitrate number <optional>
 0

共享视频的码率，单位为 bps；默认值为 0，表示 SDK 根据当前共享屏幕的分辨率计算出一个合理的值
capture_mouse_cursor boolean

是否采集鼠标用于屏幕共享
window_focus boolean

调用 NERtcEngine#startScreenCaptureByWindowId 方法共享窗口时，是否将该窗口前置
excluded_window_list Array.<number>

待屏蔽窗口的 ID 列表
excluded_window_count number

待屏蔽窗口的数量
prefer number

编码策略倾向:

- 0 动画模式
- 1 细节模式
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

uploadSdkInfo()

上传SDK 信息（如log文件和Audio dump文件）。

Events

onAddLiveStreamTask

通知添加直播任务结果。

该回调异步返回 NERtcEngine#addLiveStreamTask 接口的调用结果；实际推流状态参考 onLiveStreamState 事件
Parameters:
Name Type Description
task_id String

任务id
url String

推流地址
error number

结果

onAudioDefaultDeviceChanged

音频默认设备更改回调。

Parameters:
Name Type Description
device_id string

设备ID。
device_type number

音频设备类型:

- 0 未知音频设备
- 1 音频采集设备
- 2 音频播放设备

onAudioDeviceStateChanged

音频设备状态更改回调。

Parameters:
Name Type Description
device_id string

设备ID。
device_type number

音频设备类型:

- 0 未知音频设备
- 1 音频采集设备
- 2 音频播放设备
device_state number

音频设备状态:

- 0 音频设备已激活
- 1 音频设备未激活

onAudioEffectFinished

本地音效文件播放已结束回调。

当播放音效结束后，会触发该回调。
Parameters:
Name Type Description
effect_id number

音效ID

onAudioHowling

监测音频啸叫的回调。

Parameters:
Name Type Description
howling boolean

是否出现啸叫

onAudioMixingStateChanged

本地用户的音乐文件播放状态改变回调。

调用 NERtcEngine#startAudioMixing 播放混音音乐文件后，当音乐文件的播放状态发生改变时，会触发该回调。
- 如果播放音乐文件正常结束，state 会返回相应的状态码 0，error_code 返回 0。
- 如果播放出错，则返回状态码 1，error_code 返回相应的出错原因。
- 如果本地音乐文件不存在、文件格式不支持、无法访问在线音乐文件 URL，error_code都会返回 100。
Parameters:
Name Type Description
state number

音乐文件播放状态:

- 0 音乐文件播放结束。
- 1 音乐文件报错。
error_code number

错误码:

- 0 没有错误。
- 1 通用错误。
- 100 音乐文件打开出错。

onAudioMixingTimestampUpdate

本地用户的音乐文件播放进度回调

调用 NERtcEngine#startAudioMixing 播放混音音乐文件后，当音乐文件的播放进度改变时，会触发该回调。
Parameters:
Name Type Description
timestamp_ms number

音乐文件播放进度，单位为毫秒。

onClientRoleChanged

参会者角色类型变更回调。

本地用户加入房间后，通过 NERtcEngine#setClientRole 切换用户角色后会触发此回调。例如从主播切换为观众、从观众切换为主播。
NOTE:
直播场景下，如果您在加入房间后调用该方法切换用户角色，调用成功后，会触发以下回调：
- 主播切观众，本端触发onClientRoleChanged回调，远端触发 onUserLeft 回调。
- 观众切主播，本端触发onClientRoleChanged回调，远端触发 onUserJoined 回调。
Parameters:
Name Type Description
oldRole number

原角色类型。

- 0 主播
- 1 观众
newRole number

新角色类型。

- 0 主播
- 1 观众

onConnectionStateChange

连接状态变更。

有时候由于通话流程、用户行为、网络原因等，客户端通话状态变更，触发此回调。
Parameters:
Name Type Description
state number

变更后通话状态:

- 1 没加入频道
- 2 正在加入频道
- 3 加入频道成功
- 4 正在尝试重新加入频道
- 5 加入频道失败
reason number

变更原因:

- 1 离开房间
- 2 房间被关闭
- 3 用户被踢
- 4 服务超时
- 5 加入房间
- 6 加入房间成功
- 7 重新加入房间成功（重连）
- 8 媒体连接断开
- 9 信令连接断开
- 10 请求频道失败
- 11 加入频道失败

onDisconnect

掉线回调。

由于非网络原因，客户端可能会和服务器失去连接，此时SDK无需自动重连，直接触发此回调方法。
Parameters:
Name Type Description
result NERtcErrorCode

错误码

onError

发生错误回调。

Parameters:
Name Type Description
errorCode NERtcErrorCode

错误码
msg string

错误描述

onFirstAudioDataReceived

已接收到远端音频首帧回调。

Parameters:
Name Type Description
uid number

发送音频帧的远端用户的用户 ID。

onFirstAudioFrameDecoded

已解码远端音频首帧的回调。

Parameters:
Name Type Description
uid number

远端用户 ID。

onFirstVideoDataReceived

已显示首帧远端视频回调。

第一帧远端视频显示在视图上时，触发此调用。
Parameters:
Name Type Description
uid number

用户 ID，指定是哪个用户的视频流。

onFirstVideoFrameDecoded

已显示首帧远端视频回调。

引擎收到第一帧远端视频流并解码成功时，触发此调用。 App 可在此回调中设置该用户的 video canvas。
Parameters:
Name Type Description
uid number

用户 ID，指定是哪个用户的视频流。
width number

视频流宽（px）。
height number

视频流高（px）。

onJoinChannel

加入频道回调

Parameters:
Name Type Description
cid number

频道 ID
uid number

用户 ID
result NERtcErrorCode

错误码
elapsed number

从 joinChannel 开始到发生此事件过去的时间（毫秒）

onLeaveChannel

离开频道回调。
App 调用 NERtcEngine#leaveChannel 方法时，SDK提示 App 离开频道是否成功。

Parameters:
Name Type Description
result NERtcErrorCode

错误码

onLiveStreamState

通知直播推流状态

Parameters:
Name Type Description
task_id string

任务id
url string

推流地址
state number

直播推流状态:

- 505: 推流中；
- 506: 推流失败；
- 511: 推流结束；

onLocalAudioStats

本地音频流统计信息回调。

该回调描述本地设备发送音频流的统计信息，每 2 秒触发一次。
Parameters:
Name Type Description
stats object

本地音频流统计信息:

Properties
Name Type Description
num_channels number

当前采集声道数。
sent_sample_rate number

本地上行音频采样率。
sent_bitrate number

（上次统计后）发送码率(Kbps)。
audio_loss_rate number

特定时间内的音频丢包率 (%)。
rtt number

RTT。
volume number

音量，范围为 0（最低）- 100（最高）。

onLocalAudioVolumeIndication

提示频道内本地用户瞬时音量的回调。

该回调默认禁用。可以通过 NERtcEngine#enableAudioVolumeIndication 方法开启；
开启后，本地用户说话，SDK 会按 NERtcEngine#enableAudioVolumeIndication 方法中设置的时间间隔触发该回调。
如果本地用户将自己静音（调用了 NERtcEngine#muteLocalAudioStream），SDK 将音量设置为 0 后回调给应用层。
Parameters:
Name Type Description
volume number

（混音后的）音量，取值范围为 [0,100]。

onLocalVideoStats

本地视频流统计信息回调。

该回调描述本地设备发送视频流的统计信息，每 2 秒触发一次。
Parameters:
Name Type Description
stats object

本地视频流统计信息:

Properties
Name Type Description
video_layers_count number

视频流条数。
video_layers_list Array.<object>

视频流信息数组:
video_layers_list[].layer_type number

流类型： 1、主流，2、辅流。
video_layers_list[].width number

视频流宽（像素）
video_layers_list[].height number

视频流高（像素）
video_layers_list[].capture_frame_rate number

视频采集帧率。
video_layers_list[].render_frame_rate number

视频渲染帧率。
video_layers_list[].encoder_frame_rate number

编码帧率。
video_layers_list[].sent_frame_rate number

发送帧率。
video_layers_list[].sent_bitrate number

发送码率(Kbps)。
video_layers_list[].target_bitrate number

编码器目标码率(Kbps)。
video_layers_list[].encoder_bitrate number

编码器实际编码码率(Kbps)。
video_layers_list[].codec_name String

视频编码器名字。

onNetworkQuality

通话中每个用户的网络上下行质量报告回调。

该回调描述每个用户在通话中的网络状态，每 2 秒触发一次，只上报状态有变更的成员。
Parameters:
Name Type Description
uc number

数组的大小，即用户数。
stats object

每个用户 ID 和网络上下行质量信息的数组:
stats[].uid number

用户 ID，指定是哪个用户的视频流。
stats[].tx_quality number

该用户的上行网络质量:

- 0 网络质量未知
- 1 网络质量极好
- 2 用户主观感觉和 excellent 差不多，但码率可能略低于 excellent
- 3 用户主观感受有瑕疵但不影响沟通
- 4 勉强能沟通但不顺畅
- 5 网络质量非常差，基本不能沟通
- 6 完全无法沟通
stats[].rx_quality number

该用户的下行网络质量:

- 0 网络质量未知
- 1 网络质量极好
- 2 用户主观感觉和 excellent 差不多，但码率可能略低于 excellent
- 3 用户主观感受有瑕疵但不影响沟通
- 4 勉强能沟通但不顺畅
- 5 网络质量非常差，基本不能沟通
- 6 完全无法沟通

onReconnectingStart

触发重连。

有时候由于网络原因，客户端可能会和服务器失去连接，SDK会进行自动重连，开始自动重连后触发此回调。
Parameters:
Name Type Description
cid

频道 ID。
uid

用户 ID。

onRejoinChannel

重新加入频道回调。

有时候由于网络原因，客户端可能会和服务器失去连接，SDK会进行自动重连，自动重连后触发此回调方法。
Parameters:
Name Type Description
cid number

频道 ID
uid number

用户 ID
result NERtcErrorCode

错误码
elapsed number

从 joinChannel 开始到发生此事件过去的时间（毫秒）

onReleasedHwResources

释放硬件资源的回调。

Parameters:
Name Type Description
result NERtcErrorCode

错误码

onRemoteAudioStats

通话中远端音频流的统计信息回调。

该回调描述远端用户在通话中端到端的音频流统计信息，每 2 秒触发一次。
Parameters:
Name Type Description
uc number

stats 数组的大小
stats Array.<object>

每个远端用户音频统计信息的数组:
stats[].uid number

用户 ID，指定是哪个用户的音频流
stats[].received_bitrate number

（上次统计后）接收到的码率(Kbps)
stats[].total_frozen_time number

用户的下行音频卡顿累计时长(ms)
stats[].frozen_rate number

用户的下行音频平均卡顿率(%)。
stats[].audio_loss_rate number

特定时间内的音频丢包率 (%)。
stats[].volume number

音量，范围为 0（最低）- 100（最高）。

onRemoteVideoStats

通话中远端视频流的统计信息回调。

该回调描述远端用户在通话中端到端的视频流统计信息，每 2 秒触发一次。
Parameters:
Name Type Description
uc number

数组的大小。
stats object

每个远端用户视频统计信息的数组:

Properties
Name Type Description
uid number

用户 ID，指定是哪个用户的视频流。
video_layers_count number

视频流条数。
video_layers_list Array.<object>

视频流信息数组:
video_layers_list[].layer_type number

流类型： 1、主流，2、辅流。
video_layers_list[].width number

视频流宽（像素）
video_layers_list[].height number

视频流高（像素）
video_layers_list[].capture_frame_rate number

视频采集帧率。
video_layers_list[].render_frame_rate number

视频渲染帧率。
video_layers_list[].encoder_frame_rate number

编码帧率。
video_layers_list[].sent_frame_rate number

发送帧率。
video_layers_list[].sent_bitrate number

发送码率(Kbps)。
video_layers_list[].target_bitrate number

编码器目标码率(Kbps)。
video_layers_list[].encoder_bitrate number

编码器实际编码码率(Kbps)。
video_layers_list[].codec_name String

视频编码器名字。

onRemoveLiveStreamTask

通知删除直播任务结果。

该回调异步返回 NERtcEngine#removeLiveStreamTask 接口的调用结果；实际推流状态参考 onLiveStreamState 事件
Parameters:
Name Type Description
task_id String

任务id
error number

结果

onRtcStats

当前通话统计回调。

SDK 定期向 App 报告当前通话的统计信息，每 2 秒触发一次。
Parameters:
Name Type Description
stats object

NERTC 引擎统计数据:

Properties
Name Type Description
cpu_app_usage number

当前 App 的 CPU 使用率 (%)。
cpu_idle_usage number

当前系统的 CPU 空闲率 (%)。
cpu_total_usage number

当前系统的 CPU 使用率 (%)。
memory_app_usage number

当前App的内存使用率 (%)。
memory_total_usage number

当前系统的内存使用率 (%)。
memory_app_kbytes number

当前App的内存使用量 (KB)。
total_duration number

通话时长（秒）。
tx_bytes number

发送字节数，累计值。(bytes)
rx_bytes number

接收字节数，累计值。(bytes)
tx_audio_bytes number

音频发送字节数，累计值。(bytes)
tx_video_bytes number

视频发送字节数，累计值。(bytes)
rx_audio_bytes number

音频接收字节数，累计值。(bytes)
rx_video_bytes number

视频接收字节数，累计值。(bytes)
tx_audio_kbitrate number

音频发送码率。(kbps)
rx_audio_kbitrate number

音频接收码率。(kbps)
tx_video_kbitrate number

视频发送码率。(kbps)
rx_video_kbitrate number

视频接收码率。(kbps)
up_rtt number

上行平均往返时延rtt(ms)
down_rtt number

下行平均往返时延rtt(ms)
tx_audio_packet_loss_rate number

本地上行音频实际丢包率。(%)
tx_video_packet_loss_rate number

本地上行视频实际丢包率。(%)
tx_audio_packet_loss_sum number

本地上行音频实际丢包数。
tx_video_packet_loss_sum number

本地上行视频实际丢包数。
tx_audio_jitter number

本地上行音频抖动计算。(ms)
tx_video_jitter number

本地上行视频抖动计算。(ms)
rx_audio_packet_loss_rate number

本地下行音频实际丢包率。(%)
rx_video_packet_loss_rate number

本地下行视频实际丢包率。(%)
rx_audio_packet_loss_sum number

本地下行音频实际丢包数。
rx_video_packet_loss_sum number

本地下行视频实际丢包数。
rx_audio_jitter number

本地下行音频抖动计算。(ms)
rx_video_jitter number

本地下行视频抖动计算。(ms)

onUpdateLiveStreamTask

通知更新直播任务结果。

该回调异步返回 NERtcEngine#updateLiveStreamTask 接口的调用结果；实际推流状态参考 onLiveStreamState 事件
Parameters:
Name Type Description
task_id String

任务id
url String

推流地址
error number

结果

onUserAudioMute

远端用户是否静音回调。

Parameters:
Name Type Description
uid number

远端用户ID。
mute boolean

是否静音。

onUserAudioStart

远端用户开启音频回调。

Parameters:
Name Type Description
uid number

远端用户ID。

onUserAudioStop

远端用户停用音频回调。

Parameters:
Name Type Description
uid number

远端用户ID。

onUserJoined

远端用户加入当前频道回调。

- 通信模式下，该回调提示有远端用户加入了频道，并返回新加入用户的 ID；如果加入之前，已经有其他用户在频道中了，新加入的用户也会收到这些已有用户加入频道的回调。
Parameters:
Name Type Description
uid number

新加入频道的远端用户ID。
userName string

新加入频道的远端用户名(无效)。

onUserLeft

远端用户离开当前频道回调。

提示有远端用户离开了频道（或掉线）。
Parameters:
Name Type Description
uid number

远端用户ID。
reason number

远端用户离开原因:

- 0 正常离开
- 1 用户断线导致离开
- 2 用户 Failover 过程中产生的 leave
- 3 用户被踢导致离开
- 4 用户超时导致离开

onUserSubStreamVideoStart

远端用户开启辅流视频回调。

Parameters:
Name Type Description
uid number

远端用户ID。
maxProfile number

最大分辨率:

- 0 160x90/120, 15fps
- 1 320x180/240, 15fps
- 2 640x360/480, 30fps
- 3 1280x720, 30fps
- 4 1920x1080, 30fps

onUserSubStreamVideoStop

远端用户停用辅流视频回调。

Parameters:
Name Type Description
uid number

远端用户ID。

onUserVideoMute

远端用户是否禁视频流回调。

Parameters:
Name Type Description
uid number

远端用户ID。
mute boolean

是否禁视频流。

onUserVideoProfileUpdate

远端用户视频配置更新回调。

Parameters:
Name Type Description
uid number

远端用户ID。
maxProfile number

最大分辨率:

- 0 160x90/120, 15fps
- 1 320x180/240, 15fps
- 2 640x360/480, 30fps
- 3 1280x720, 30fps
- 4 1920x1080, 30fps

onUserVideoStart

远端用户开启视频回调。

Parameters:
Name Type Description
uid number

远端用户ID。
maxProfile number

最大分辨率:

- 0 160x90/120, 15fps
- 1 320x180/240, 15fps
- 2 640x360/480, 30fps
- 3 1280x720, 30fps
- 4 1920x1080, 30fps

onUserVideoStop

远端用户停用视频回调。

Parameters:
Name Type Description
uid number

远端用户ID。

onVideoDeviceStateChanged

视频设备状态更改回调。

Parameters:
Name Type Description
device_id string

设备ID。
device_type number

视频设备类型:

- 0 未知音频设备
- 1 视频采集设备
device_state number

视频设备状态:

- 0 视频设备已添加
- 1 视频设备已拔除

onWarning

发生警告回调。

Parameters:
Name Type Description
warnCode NERtcErrorCode

错误码
msg string

错误描述

Class: NERtcEngine

NERtcEngine

new NERtcEngine()

NERtcEngine类构造函数

Returns:
Type
NERtcEngine

Methods

addLiveStreamTask(info)

添加房间推流任务，成功添加后当前用户可以收到该直播流的状态通知。通话中有效。

Parameters:
Name Type Description
info Object

直播任务信息。

Properties
Name Type Description
task_id String

推流任务ID，为推流任务的唯一标识，用于过程中增删任务操作 <64 chars
stream_url String

直播推流地址 <256 chars
server_record_enabled Boolean

服务器录制功能是否开启
ls_mode Number

直播推流模式:

- 0 推流带视频
- 1 推流纯音频
layout Object

视频布局:

Properties
Name Type Description
width number

视频推流宽度
height number

视频推流高度
background_color number

视频推流背景色，(R & 0xff) << 16 | (G & 0xff) << 8 | (B & 0xff)
user_count number

成员布局个数
users Array.<object>

成员布局数组:
users[].uid number

用户id
users[].video_push boolean

是否推送该用户视频流，info.ls_mode=1时无效
users[].adaption number

视频流裁剪模式:

- 0 视频尺寸等比缩放。优先保证视频内容全部显示。因视频尺寸与显示视窗尺寸不一致造成的视窗未被填满的区域填充背景色
- 1 视频尺寸等比缩放。优先保证视窗被填满。因视频尺寸与显示视窗尺寸不一致而多出的视频将被截掉
users[].x number

画面离主画面左边距
users[].y number

画面离主画面上边距
users[].width number

画面在主画面的显示宽度，画面右边超出主画面会失败
users[].height number

画面在主画面的显示高度，画面底边超出主画面会失败
users[].audio_push boolean

是否推送该用户音频流
users[].bg_image object

背景图信息:

Properties
Name Type Description
url String

图片地址
x number

画面离主画面左边距
y number

画面离主画面上边距
width number

画面在主画面的显示宽度，画面右边超出主画面会失败
height number

画面在主画面的显示高度，画面底边超出主画面会失败
Fires:
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

adjustPlaybackSignalVolume(volume)

调节播放音量。

Parameters:
Name Type Description
volume number

播放音量可在 0 ~ 400 范围内进行调节:

- 0:  静音；
- 100: 原始音量；
- 400: 最大可为原始音量的 4 倍（自带溢出保护）。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

adjustRecordingSignalVolume(volume)

调节录音音量。

Parameters:
Name Type Description
volume number

录音信号音量可在 0 ~ 400 范围内进行调节:

- 0: 静音；
- 100: 原始音量；
- 400: 最大可为原始音量的 4 倍（自带溢出保护）。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

enableAudioVolumeIndication(enable, interval)

启用说话者音量提示。该方法允许 SDK 定期向 App 反馈当前谁在说话以及说话者的音量。

启用该方法后，无论频道内是否有人说话，可以通过NERtcEngine#on方法监听 onRemoteAudioVolumeIndication，根据设置的间隔时间返回音量提示事件。
Parameters:
Name Type Description
enable boolean

是否启用说话者音量提示。
interval number

指定音量提示的时间间隔，单位为毫秒。必须设置为 100 毫秒的整数倍值。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

enableDualStreamMode(enable)

设置视频双流发送。

调用该方法控制是否支持发送双流，只对摄像头数据生效，自定义输入、取屏等无效。设置后，会在摄像头重启后生效。
Parameters:
Name Type Description
enable boolean 
- true: 双流发送（默认）
- false: 只发送一个流
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

enableEarback(enabled, volume)

开启或关闭耳返。

请在频道内调用该方法。
Parameters:
Name Type Description
enabled boolean

开启或关闭。
volume number

耳返音量。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

enableLocalAudio(enabled)

开启或关闭本地语音采集或处理

该方法可以重新开启本地语音功能，重新开始本地音频采集及处理。
该方法不影响接收或播放远端音频流。
NOTE:
- 该方法与 NERtcEngine#muteLocalAudioStream 的区别在于:
- NERtcEngine#enableLocalAudio: 开启本地语音采集及处理
- NERtcEngine#muteLocalAudioStream: 停止或继续发送本地音频流
该方法设置内部引擎为启用状态，在 NERtcEngine#leaveChannel 后仍然有效。
Parameters:
Name Type Description
enabled Boolean 
- true: 重新开启本地语音功能，即开启本地语音采集或处理（默认）
- false: 关闭本地语音功能，即停止本地语音采集或处理
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

enableLocalVideo(enabled)

开启或关闭本地视频采集和渲染

该方法启用本地视频采集功能。
该方法设置内部引擎为启用状态，在 NERtcEngine#leaveChannel 后仍然有效。
Parameters:
Name Type Description
enabled boolean

是否启用本地视频:

- true: 开启本地视频采集和渲染 (默认)；
- false: 关闭使用本地摄像头设备。关闭后，远端用户会接收不到本地用户的视频流；但本地用户依然可以接收远端用户的视频流。设置为 false 时，该方法不需要本地有摄像头。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

enumeratePlayoutDevices()

获取系统中所有的播放设备列表。

该方法返回 NERtcDevice[]，包含系统中所有的播放设备。
Returns:
- Array: 调用成功；
- null：调用失败。



NameTypeDescription


NERtcDevice.device_idString设备ID


NERtcDevice.device_nameString设备名称


NERtcDevice.transport_typeNumber设备链接类型:
- audio:
  - 0 未知设备
  - 1 蓝牙设备
  - 2 蓝牙立体声设备
  - 3 蓝牙低功耗设备
  - 4 USB设备
  - 5 HDMI设备
  - 6 内置设备
  - 7 雷电接口设备
  - 8 AirPlay设备
  - 9 虚拟设备
  - 10 其他设备
- video:
  - 0 未知设备
  - 1 USB设备
  - 2 虚拟设备
  - 3 其他设备


NERtcDevice.suspected_unavailableBoolean是否是不推荐设备


NERtcDevice.system_default_deviceBoolean是否是系统默认设备



     - null: 调用失败。
Type
Array.<NERtcDevice>

enumerateRecordDevices()

获取系统中所有的音频采集设备列表。

 该方法返回 NERtcDevice[] 包含系统中所有的音频采集设备。
Returns:
- NERtcDevice[] : 方法调用成功；



NameTypeDescription


NERtcDevice.device_idString设备ID


NERtcDevice.device_nameString设备名称


NERtcDevice.transport_typeNumber设备链接类型:
- audio:
  - 0 未知设备
  - 1 蓝牙设备
  - 2 蓝牙立体声设备
  - 3 蓝牙低功耗设备
  - 4 USB设备
  - 5 HDMI设备
  - 6 内置设备
  - 7 雷电接口设备
  - 8 AirPlay设备
  - 9 虚拟设备
  - 10 其他设备
- video:
  - 0 未知设备
  - 1 USB设备
  - 2 虚拟设备
  - 3 其他设备


NERtcDevice.suspected_unavailableBoolean是否是不推荐设备


NERtcDevice.system_default_deviceBoolean是否是系统默认设备



- NULL: 方法调用失败。
Type
Array.<NERtcDevice> | null

enumerateVideoCaptureDevices()

获取系统中所有的视频采集设备列表。

该方法返回 NERtcDevice[] 包含系统中所有的音频采集设备。
Returns:
- NERtcDevice[] : 调用成功；



NameTypeDescription


NERtcDevice.device_idString设备ID


NERtcDevice.device_nameString设备名称


NERtcDevice.transport_typeNumber设备链接类型:
- audio:
  - 0 未知设备
  - 1 蓝牙设备
  - 2 蓝牙立体声设备
  - 3 蓝牙低功耗设备
  - 4 USB设备
  - 5 HDMI设备
  - 6 内置设备
  - 7 雷电接口设备
  - 8 AirPlay设备
  - 9 虚拟设备
  - 10 其他设备
- video:
  - 0 未知设备
  - 1 USB设备
  - 2 虚拟设备
  - 3 其他设备


NERtcDevice.suspected_unavailableBoolean是否是不推荐设备


NERtcDevice.system_default_deviceBoolean是否是系统默认设备



- NULL: 调用失败。
Type
Array.<NERtcDevice>

enumerateWindows()

Enumerates windows(windows only).

This method returns windowsInfo[] that includes all windows&monitors in the system
NOTE:
You should call NERtcEngine#startScreenCaptureByScreenRect for 'Monitor' type
Returns:
- Returns windowsInfo[] that includes all windows&monitors in the system: Success.



NameTypeDescription


windowsInfo.idnumber窗口id


windowsInfo.nameString窗口title


windowsInfo.leftnumber窗口左边缘坐标


windowsInfo.topnumber窗口上边缘坐标


windowsInfo.rightnumber窗口右边缘坐标


windowsInfo.bottomnumber窗口下边缘坐标



- null: 调用失败。
Type
Array.<windowsInfo>

getAudioMixingCurrentPosition()

获取音乐文件的播放进度。

该方法获取当前伴奏播放进度，单位为毫秒。请在频道内调用该方法。
Returns:
- >= 0: 伴奏播放进度，单位为毫秒；
- 其他: 方法调用失败。
Type
number

getAudioMixingDuration()

获取伴奏时长。

该方法获取伴奏时长，单位为毫秒。请在频道内调用该方法。
Returns:
- >=0: 伴奏时长，单位为毫秒；
- 其他: 方法调用失败。
Type
number

getAudioMixingPlaybackVolume()

获取伴奏播放音量。

该方法获取混音里伴奏的播放音量大小。请在频道内调用该方法。
Returns:
- >= 0: 伴奏播放音量；
- 其他: 方法调用失败。
Type
number

getAudioMixingSendVolume()

获取伴奏发送音量。

该方法获取混音里伴奏的发送音量大小。请在频道内调用该方法。
Returns:
- >=0: 伴奏发送音量；
- 其他: 方法调用失败。
Type
number

getConnectionState()

获取当前网络状态。

Returns:
- 1 没加入频道。
- 2 正在加入频道。
- 3 加入频道成功。
- 4 正在尝试重新加入频道。
- 5 加入频道失败。
Type
number

getEffectPlaybackVolume(effectId)

获取音效播放音量。

该方法获取音效的播放音量大小。请在频道内调用该方法。
Parameters:
Name Type Description
effectId number

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

  • = 0: 音效播放音量；

  • 其他: 方法调用失败。
Type
number

getEffectSendVolume(effectId)

获取音效发送音量。

该方法获取音效的发送音量大小。请在频道内调用该方法。
Parameters:
Name Type Description
effectId number

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

  • =0: 音效发送音量；

  • 其他: 方法调用失败。
Type
number

getErrorDescription(errorCode)

获取错误描述。

Parameters:
Name Type Description
errorCode number

错误码
Returns:

详细错误码描述

Type
number

getPlayoutDevice()

获取当前使用的音频播放设备 ID。

Returns:

deviceID

Type
String

getPlayoutDeviceMute()

获取音频播放设备静音状态。

Returns:
- true: 静音状态。
- false: 非静音状态。
Type
boolean

getPlayoutDeviceVolume()

获取音频播放设备音量。

Returns:
- >=0: 音频播放设备音量。取值范围为 0~255。
- 其他: 方法调用失败。
Type
number

getRecordDevice()

获取当前使用的音频采集设备 ID。

Returns:
- 设备ID： 调用成功
- null: 调用失败。
Type
String

getRecordDeviceMute()

获取音频采集设备静音状态。

Returns:
- true: 静音状态。
- false: 非静音状态。
Type
boolean

getRecordDeviceVolume()

获取音频采集设备音量。

Returns:
- >=0: 音频采集设备音量。取值范围为 0~255。
- 其他: 方法调用失败。
Type
number

getVersion()

查询 SDK 版本号。

Returns:

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

Type
String

getVideoDevice()

获取当前使用的视频采集设备信息。

Returns:

设备ID

Type
String

initialize(context)

初始化 NERTC SDK 服务。

该方法用来进行初始化 NERTC 服务。传入云信为开发者签发的厂商秘钥进行初始化。在使用其他方法前，必须先调用该方法进行初始化。
初始化成功后，默认处于音视频通话模式。
NOTE:
- 必须使用同一个 App Key 才能进行通话。
- 一个 NERtcEngine 实例对象只能使用一个 App Key。如需更换 App Key，必须先调用 NERtcEngine#release 方法释放当前实例资源再调用本方法初始化实例。
Parameters:
Name Type Description
context Object

传入的RTC engine context对象: NERtcEngineContext.

Properties
Name Type Argument Default Description
app_key String

用户注册云信的APP Key。如果你的开发包里面缺少 APP Key，请申请注册一个新的 APP Key。
log_dir_path String

日志目录的完整路径，采用UTF-8 编码。
log_level number <optional>
 3

日志级别，默认级别为 kNERtcLogLevelInfo。

- 0 Fatal级别日志信息
- 1 Error级别日志信息
- 2 Warning级别日志信息
- 3 Info级别日志信息。默认级别
- 4 DetailInfo级别日志信息
- 5 Verbos级别日志信息
- 6 Debug级别日志信息。如果你想获取最完整的日志，可以将日志级别设为该等级
- 7 不输出日志信息
log_file_max_size_KBytes number <optional>
 20480

指定 SDK 输出日志文件的大小上限，单位为 KB。如果设置为 0，则默认为 20 M。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

joinChannel(token, channelName, uid)

加入频道。如果频道还未创建，会自动尝试创建频道。

该方法让用户加入通话频道，在同一个频道内的用户可以互相通话，多个用户加入同一个频道，可以群聊。 使用不同 App Key 的 App 是不能互通的。如果已在通话中，用户必须调用 NERtcEngine#leaveChannel 退出当前通话，才能进入下一个频道。
频道内每个用户的用户 ID 必须是唯一的。
Parameters:
Name Type Description
token String

动态秘钥。安全要求不高: 将值设为 空字符串。安全要求高: 将值设置为 Token。如果你已经启用了 App Certificate, 请务必使用 Token。
channelName String

标识通话的频道名称，长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）: a-z, A-Z, 0-9, space, !#$%&()+-:;≤.,>? @[]^_{|}~”
uid number

用户ID。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

leaveChannel()

离开频道。

离开频道，即挂断或退出通话。
当调用 NERtcEngine#joinChannel 方法后，必须调用 NERtcEngine#leaveChannel 结束通话，否则无法开始下一次通话。 不管当前是否在通话中，都可以调用 leaveChannel，没有副作用。该方法会把会话相关的所有资源释放掉。
该方法是异步操作，调用返回时并没有真正退出频道。在真正退出频道后，SDK 会触发 onLeaveChannel 事件。
如果你调用了 NERtcEngine#leaveChannel 后立即调用 NERtcEngine#release , SDK 将无法触发 onLeaveChannel 事件。
Fires:
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

muteLocalAudioStream(mute)

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

该方法不影响录音状态，因为并没有禁用录音设备。
Parameters:
Name Type Description
mute boolean

静音/取消静音:

- true: 静音本地音频
- false: 取消静音本地音频（默认）
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

muteLocalVideoStream(mute)

开关本地视频发送。

调用该方法禁视频流时，SDK 不再发送本地视频流，但摄像头仍然处于工作状态。相比于 NERtcEngine#enableLocalVideo (false) 用于控制本地视频流发送的方法，该方法响应速度更快。该方法不影响本地视频流获取，没有禁用摄像头。
Parameters:
Name Type Description
mute boolean 
- true: 不发送本地视频流
- false: 发送本地视频流（默认）
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

pauseAllEffects()

暂停所有音效文件播放。

请在频道内调用该方法。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

pauseAudioMixing()

暂停播放伴奏。

该方法暂停播放伴奏。请在频道内调用该方法。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

pauseEffect(effectId)

暂停音效文件播放。

请在频道内调用该方法。
Parameters:
Name Type Description
effectId number

指定音效的 ID。每个音效均有唯一的 ID。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

pauseScreenCapture()

暂停屏幕共享。

Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

playEffect(effectId, opt)

播放指定音效文件。

你可以多次调用该方法，通过传入不同的音效文件的 effect_id 和 option ，同时播放多个音效文件，实现音效叠加。为获得最佳用户体验，我们建议同时播放的音效文件不要超过 3 个。成功调用该方法后，可以通过NERtcEngine#on方法监听 onAudioEffectFinished 播放结束事件。
请在频道内调用该方法，如果在频道外调用该方法可能会出现问题。
Parameters:
Name Type Argument Default Description
effectId number

指定音效的 ID。每个音效均有唯一的 ID。
opt Array.<object>

创建音效任务配置的选项，包括混音任务类型、混音文件全路径或URL等。支持的音频格式包括: AAC、MP3 和 WAVE。
opt[].path String

本地文件全路径或URL <256 chars
opt[].loop_count number <optional>
 1

循环次数， <= 0, 表示无限循环，默认 1
opt[].send_enabled boolean <optional>
 true

是否可发送，默认为 true
opt[].send_volume number

发送音量。最大为 100（默认）含义（0%-100%）
opt[].playback_enabled boolean <optional>
 true

是否可回放，默认为 true
opt[].playback_volume number

回放音量。最大为 100（默认）
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

release()

释放资源。

removeLiveStreamTask(taskId)

删除房间推流任务。通话中有效。

Parameters:
Name Type Description
taskId String

直播任务id
Fires:
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

resumeAllEffects()

恢复播放所有音效文件。

请在频道内调用该方法。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

resumeAudioMixing()

恢复播放伴奏。

该方法恢复混音，继续播放伴奏。请在频道内调用该方法。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

resumeEffect(effectId)

恢复播放指定音效文件。

请在频道内调用该方法。
Parameters:
Name Type Description
effectId number

指定音效的 ID。每个音效均有唯一的 ID。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

resumeScreenCapture()

恢复屏幕共享。

Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setAudioMixingPlaybackVolume(volume)

调节伴奏播放音量。

该方法调节混音里伴奏的播放音量大小。请在频道内调用该方法。
Parameters:
Name Type Description
volume number

伴奏音量范围为 0~100。默认 100 为原始文件音量。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setAudioMixingPosition(pos)

设置音乐文件的播放位置。

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

进度条位置，单位为毫秒。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setAudioMixingSendVolume(volume)

调节伴奏发送音量。

该方法调节混音里伴奏的发送音量大小。请在频道内调用该方法。
Parameters:
Name Type Description
volume number

伴奏音量范围为 0~100。默认 100 为原始文件音量。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setAudioProfile(profile, scenario)

设置音频编码属性。

NOTE:
- 该方法需要在 NERtcEngine#joinChannel 之前设置好， NERtcEngine#joinChannel 之后设置不生效。
- 音乐场景下，建议将 profile 设置为 4.
Parameters:
Name Type Description
profile number

设置采样率，码率，编码模式和声道数:

- 0 默认设置。Speech场景下为 1，Music场景下为 2
- 1 普通质量的音频编码，16000Hz，20Kbps
- 2 普通质量的音频编码，16000Hz，32Kbps
- 3 中等质量的音频编码，48000Hz，32Kbps
- 4 中等质量的立体声编码，48000Hz * 2，64Kbps
- 5 高质量的音频编码，48000Hz，64Kbps
- 6 高质量的立体声编码，48000Hz * 2，128Kbps
scenario number

设置音频应用场景:

- 0: 默认设置: 通过NERtcEngine#setChannelProfile设置通话模式时为语音场景(1)，直播推流模式时为音乐场景(2)。
- 1: 语音场景. profile 推荐使用 2 及以下
- 2: 音乐场景。profile 推荐使用 3 及以上
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setChannelProfile(profile)

设置通话模式

必须在加入通话前设置，开始通话后设置无效，结束通话后保留之前的设置。
Parameters:
Name Type Description
profile number

场景模式

- 通话场景(0)
- 直播推流场景(1)
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setClientRole(role)

设置参会者角色

NERtcEngine#setClientRole 接口用于在直播场景中设置用户角色。默认情况下用户以主播角色加入房间。
在加入房间前，用户需要调用setClientRole 接口设置本端模式为观众或主播模式。在加入房间后，用户可以通过本接口切换用户模式。
用户角色支持设置为主播或观众，主播和观众的权限不同。默认情况下用户以主播角色加入房间。
可以在通话前后设置，通话前设置会在加入频道之后生效。如果设置观众模式。则会停止音视频设备。
Parameters:
Name Type Description
role number

参会者模式

- 主播(0)：可以开关摄像头等设备、可以发布流、可以操作互动直播推流相关接口、上下线对其他房间内用户可见
- 观众(1)：不可以开关摄像头等设备、不可以发布流、不可以操作互动直播推流相关接口、上下线对其他房间内用户不可见
Fires:
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setEarbackVolume(volume)

设置耳返音量。

请在频道内调用该方法。
Parameters:
Name Type Description
volume number

耳返音量。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setEffectPlaybackVolume(effectId, volume)

调节音效播放音量。

该方法调节音效的播放音量大小。请在频道内调用该方法。
Parameters:
Name Type Description
effectId number

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

音效音量范围为 0~100。默认 100 为原始文件音量。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setEffectSendVolume(effectId, volume)

调节音效发送音量。

该方法调节音效的发送音量大小。请在频道内调用该方法。
Parameters:
Name Type Description
effectId number

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

音效音量范围为 0~100。默认 100 为原始文件音量。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setLocalVideoMirrorMode(mode)

设置本地视频镜像模式。

该方法设置本地视频镜像模式。 App 可以多次调用此方法更改镜像模式。
Parameters:
Name Type Description
mode number

视频镜像模式:

- 0 Windows/macOS SDK 启用镜像模式。
- 1 启用镜像模式。
- 2 （默认）关闭镜像模式。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setParameters(parameters)

通过 JSON 配置 SDK 提供技术预览或特别定制功能。以标准化方式公开 JSON 选项。

Parameters:
Name Type Description
parameters object

JSON 字符串形式的参数

Properties
Name Type Argument Default Description
record_host_enabled boolean 
- true 录制主讲人
- false 不是录制主讲人
record_audio_enabled boolean <optional>
 false

启用服务器音频录制。默认值 false
record_video_enabled boolean <optional>
 false

启用服务器视频录制。默认值 false
record_type number

录制类型：

- 0 参与混合录制且录制单人文件
- 1 参与混合录制
- 2 只录单人文件
auto_subscribe_audio boolean <optional>
 true

其他用户打开音频时，自动订阅。 默认值 true
publish_self_stream_enabled boolean <optional>
 false

开启旁路直播。默认值 false
log_level number <optional>
 3

日志级别，默认级别为 kNERtcLogLevelInfo。

- 0 Fatal级别日志信息
- 1 Error级别日志信息
- 2 Warning级别日志信息
- 3 Info级别日志信息。默认级别
- 4 DetailInfo级别日志信息
- 5 Verbos级别日志信息
- 6 Debug级别日志信息。如果你想获取最完整的日志，可以将日志级别设为该等级
- 7 不输出日志信息
audio_processing_aec_enable boolean <optional>
 true

AEC开关，默认值 true
audio_processing_agc_enable boolean <optional>
 true

AGC开关，默认值 true
audio_processing_ns_enable boolean <optional>
 true

NS开关，默认值 true
audio_processing_ai_ns_enable boolean <optional>
 false

AI NS开关，建议通话前修改，默认值 false
audio_processing_external_audiomix_enable boolean <optional>
 false

输入混音开关，默认值 false
audio_processing_earphone boolean <optional>
 false

通知SDK是否使用耳机:

- true: 使用耳机
- false: 不使用耳机
video_sendonpub_type number <optional>
 1

设置视频发送策略，默认发送大流(1)；通话前设置有效

- 0 不主动发送数据流，被订阅后发送。
- 1 主动发送大流。
- 2 主动发送小流。
- 3 主动发送大小流。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setPlayoutDevice(id)

指定播放设备。

Parameters:
Name Type Description
id String

音频播放设备的设备 ID。可以通过 NERtcEngine#enumeratePlayoutDevices 获取。插拔设备不会影响 deviceId。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setPlayoutDeviceMute(mute)

静音或取消静音音频播放设备。

Parameters:
Name Type Description
mute

是否静音音频播放设备。

- true: 静音音频播放设备。
- false: 取消静音音频播放设备。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setPlayoutDeviceVolume(volume)

设置音频播放设备音量。

Parameters:
Name Type Description
volume number

音频播放设备音量。取值范围为 0~255。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setRecordDevice(id)

指定音频采集设备。

Parameters:
Name Type Description
id String

音频采集设备的设备 ID。可通过 NERtcEngine#enumerateRecordDevices 获取。插拔设备不会影响 deviceId。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setRecordDeviceMute(mute)

静音或取消静音音频采集设备。

Parameters:
Name Type Description
mute boolean

是否静音音频采集设备。

- true: 静音音频采集设备。
- false: 取消静音音频采集设备。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setRecordDeviceVolume(volume)

设置音频采集设备音量。

Parameters:
Name Type Description
volume number

音频采集设备音量。取值范围为 0~255。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setRenderMode(uid, mode)

设置本地视图/远端视图显示模式。

该方法设置视图显示模式。App 可以多次调用此方法更改显示模式。
Parameters:
Name Type Description
uid string | number 
'local':本地视图
{number}: 远端用户 ID。
mode number

视频显示模式:

- 0 视频尺寸等比缩放。优先保证视频内容全部显示。因视频尺寸与显示视窗尺寸不一致造成的视窗未被填满的区域填充黑色。
- 1 视频尺寸非等比缩放。保证视频内容全部显示，且填满视窗。
- 2 视频尺寸等比缩放。优先保证视窗被填满。因视频尺寸与显示视窗尺寸不一致而多出的视频将被截掉。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setSubStreamRenderMode(uid, mode)

设置辅流视图/远端辅流视图显示模式。

该方法设置视图显示模式。App 可以多次调用此方法更改显示模式。
Parameters:
Name Type Description
uid string | number 
'local':本地辅流视图
{number}: 远端辅流用户 ID。
mode number

视频显示模式:

- 0 视频尺寸等比缩放。优先保证视频内容全部显示。因视频尺寸与显示视窗尺寸不一致造成的视窗未被填满的区域填充黑色。
- 1 视频尺寸非等比缩放。保证视频内容全部显示，且填满视窗。
- 2 视频尺寸等比缩放。优先保证视窗被填满。因视频尺寸与显示视窗尺寸不一致而多出的视频将被截掉。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setupLocalSubStreamVideoCanvas(canvas)

设置本地辅流视图。

该方法设置本地辅流视频显示信息。App 通过调用此接口绑定本地辅流的显示视窗(view)。 在 App 开发中，通常在初始化后调用该方法进行本地视频设置，然后再加入频道。
Parameters:
Name Type Description
canvas Object

视频画布信息

Properties
Name Type Description
mode number

视频显示模式

- 0 视频尺寸等比缩放。优先保证视频内容全部显示。因视频尺寸与显示视窗尺寸不一致造成的视窗未被填满的区域填充黑色。
- 1 视频尺寸非等比缩放。保证视频内容全部显示，且填满视窗。
- 2 视频尺寸等比缩放。优先保证视窗被填满。因视频尺寸与显示视窗尺寸不一致而多出的视频将被截掉。
view Element

视频画布对象
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setupLocalVideoCanvas(canvas)

设置本地视图。

该方法设置本地视频显示信息。App 通过调用此接口绑定本地视频流的显示视窗(view)。 在 App 开发中，通常在初始化后调用该方法进行本地视频设置，然后再加入频道。
Parameters:
Name Type Description
canvas Object

视频画布信息

Properties
Name Type Description
mode number

视频画布缩放模式

- 0 视频尺寸等比缩放。优先保证视频内容全部显示。因视频尺寸与显示视窗尺寸不一致造成的视窗未被填满的区域填充黑色。
- 1 视频尺寸非等比缩放。保证视频内容全部显示，且填满视窗。
- 2 视频尺寸等比缩放。优先保证视窗被填满。因视频尺寸与显示视窗尺寸不一致而多出的视频将被截掉。
view Element

视频画布对象
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setupRemoteSubStreamVideoCanvas(uid, canvas)

设置远端用户辅流视图。

该方法绑定远端用户和辅流显示视图，即设定 uid 指定的用户用哪个视图显示。调用该接口时需要指定远端视频的 uid，一般可以在用户加入后设置好。
NODE:
- 如果 App 不能事先知道对方的 uid，可以通过NERtcEngine#on方法监听 onUserJoined 事件时设置。
- 退出频道后，SDK 会把远端用户的绑定关系清除掉。
Parameters:
Name Type Description
uid number

远端用户 ID。
canvas Object

视频画布信息

Properties
Name Type Description
mode number

视频显示模式

- 0 视频尺寸等比缩放。优先保证视频内容全部显示。因视频尺寸与显示视窗尺寸不一致造成的视窗未被填满的区域填充黑色。
- 1 视频尺寸非等比缩放。保证视频内容全部显示，且填满视窗。
- 2 视频尺寸等比缩放。优先保证视窗被填满。因视频尺寸与显示视窗尺寸不一致而多出的视频将被截掉。
view Element

视频画布对象
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setupRemoteVideoCanvas(uid, canvas)

设置远端用户视图。

该方法绑定远端用户和显示视图，即设定 uid 指定的用户用哪个视图显示。调用该接口时需要指定远端视频的 uid，一般可以在用户加入后设置好。
如果 App 不能事先知道对方的 uid，可以在 APP 收到 onUserJoined 事件时设置。
退出频道后，SDK 会把远端用户的绑定关系清除掉。
Parameters:
Name Type Description
uid number

远端用户 ID。
canvas Object

视频画布信息

Properties
Name Type Description
mode number

视频画布缩放模式

- 0 视频尺寸等比缩放。优先保证视频内容全部显示。因视频尺寸与显示视窗尺寸不一致造成的视窗未被填满的区域填充黑色。
- 1 视频尺寸非等比缩放。保证视频内容全部显示，且填满视窗。
- 2 视频尺寸等比缩放。优先保证视窗被填满。因视频尺寸与显示视窗尺寸不一致而多出的视频将被截掉。
view Element

视频画布对象
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setVideoConfig(config)

设置视频配置。

该方法设置视频配置。每个属性对应一套视频参数，如分辨率等，会在摄像头重启后生效。 所有设置的参数均为理想情况下的最大值。当视频引擎因网络环境等原因无法达到设置的分辨率的最大值时，会取最接近最大值的那个值。
Parameters:
Name Type Description
config object

视频配置:

Properties
Name Type Argument Default Description
max_profile number

视频编码的分辨率，用于衡量编码质量:

- 0 160x90/120, 15fps
- 1 320x180/240, 15fps
- 2 640x360/480, 30fps
- 3 1280x720, 30fps
- 4 1920x1080, 30fps
width number

视频编码自定义分辨率之宽度。width为0表示使用max_profile
height number

视频编码自定义分辨率之高度。height为0表示使用max_profile
crop_mode number

视频画面裁剪模式:

- 0 Device Defalut
- 1 16:9
- 2 4:3
- 3 1:1
framerate number

视频帧率:

- 0 默认帧率
- 7 7帧每秒
- 10 10帧每秒
- 15 15帧每秒
- 24 24帧每秒
- 30 30帧每秒
min_framerate number

视频最小帧率:

- 0 默认帧率
- 7 7帧每秒
- 10 10帧每秒
- 15 15帧每秒
- 24 24帧每秒
- 30 30帧每秒
bitrate number <optional>
 0

视频编码码率kbps，取0时使用默认值
min_bitrate number <optional>
 0

视频编码码率下限kbps，取0时使用默认值
degradation_preference number

编码策略:

- 0 使用引擎推荐值。通话场景使用平衡模式，直播推流场景使用清晰优先
- 1 帧率优先
- 2 清晰度优先
- 3 平衡模式
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

setVideoDevice(id)

指定视频采集设备。

Parameters:
Name Type Description
id string

视频采集设备的设备 ID。可以通过 NERtcEngine#enumerateCaptureDevices获取。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

startAudioDeviceLoopbackTest(interval)

开始音频设备回路测试。

该方法测试音频采集和播放设备是否能正常工作。一旦测试开始，音频采集设备会采集本地音频，然后使用音频播放设备播放出来。 可以通过 NERtcEngine#on监听 onLocalAudioVolumeIndication 报告音量信息的事件。
NOTE:
- 该方法需在加入房间前调用。
- 音频设备回路测试会在通话开始后自动结束，您也可以手动调用 NERtcEngine#stopAudioDeviceLoopbackTest 停止音频设备回路测试。
- 该方法仅在本地进行音频设备测试，不涉及网络连接。
Parameters:
Name Type Description
interval number

事件上报的时间间隔，单位为毫秒。
Fires:
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

startAudioDump()

开启音频dump。

Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

startAudioMixing(option)

开始播放伴奏。

指定本地或在线音频文件来和录音设备采集的音频流进行混音。成功调用该方法后，可以通过NERtcEngine#on方法监听 onAudioMixingStateChanged 播放状态改变事件。
请在频道内调用该方法，如果在频道外调用该方法可能会出现问题。
Parameters:
Name Type Description
option object

创建混音任务配置的选项，包括混音任务类型、混音文件全路径或URL等。支持的音频格式包括: AAC、MP3 和 WAVE。

Properties
Name Type Argument Default Description
path string

本地文件全路径或URL <256 chars
loop_count number <optional>
 1

循环次数， <= 0, 表示无限循环，默认 1
send_enabled boolean <optional>
 true

是否可发送，默认为 true
send_volume number <optional>
 100

发送音量。最大为 100（默认）含义（0%-100%）
playback_enabled boolean <optional>
 true

是否可回放，默认为 true
playback_volume number <optional>
 100

回放音量。最大为 100（默认）
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

startPlayoutDeviceTest(path)

启动音频播放设备测试。

该方法测试音频播放设备是否能正常工作。启动测试后，SDK 播放指定的音频文件，测试者如果能听到声音，说明播放设备能正常工作。调用该方法后，可以通过NERtcEngine#on方法监听 onLocalAudioVolumeIndication (每隔 100 ms)
NOTE:
- 该方法需在加入房间前调用。
- 音频播放设备测试会在通话开始后自动结束，您也可以手动调用 NERtcEngine#stopPlayoutDeviceTest 停止音频播放设备测试。
- 支持文件格式包括 wav、mp3、aac。
Parameters:
Name Type Description
path string

音频文件的绝对路径，路径字符串使用 UTF-8 编码格式。
Fires:
Returns:
- 0: 方法调用成功，并且可以听到所设置文件的声音。
- 其他: 方法调用失败。
Type
number

startRecordDeviceTest(interval)

启动音频采集设备测试。

该方法测试音频采集设备是否能正常工作。调用该方法后，可以通过NERtcEngine#on方法监听 onLocalAudioVolumeIndication 报告采集设备的音量信息事件。
NOTE:
- 该方法需在加入房间前调用。
- 音频采集设备测试会在通话开始后自动结束，您也可以手动调用 NERtcEngine#stopRecordDeviceTest 停止音频采集设备测试。
Parameters:
Name Type Description
interval number

事件上报的时间间隔，单位为毫秒。
Fires:
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

startScreenCaptureByDisplayId(displayId [, regionRect=], param)

通过屏幕 ID 共享屏幕。共享一个屏幕或该屏幕的部分区域。用户需要在该方法中指定想要共享的屏幕 ID。

NOTE:
- 该方法仅适用于 macOS。
- 该方法打开视频辅流。
Parameters:
Name Type Argument Description
displayId number

指定待共享的屏幕 ID。开发者需要通过该参数指定你要共享的那个屏幕。
regionRect= object <optional>

(可选) 指定待共享区域相对于整个屏幕屏幕的位置。如果设置的共享区域超出了屏幕的边界，则只共享屏幕内的内容；如果将 width 或 height 设为 0, 则共享整个屏幕。
regionRect.x number

左上角的横向偏移
regionRect.y number

左上角的纵向偏移
regionRect.width number

待共享区域的宽
regionRect.height number

待共享区域的高
param object

屏幕共享的编码参数配置。

Properties
Name Type Argument Default Description
profile object <optional>
 2

屏幕共享编码参数配置:

- 0 640x480, 5fps
- 1 1280x720, 5fps
- 2 1920x1080, 5fps。默认
- 3 自定义
dimensions object

屏幕共享视频发送的最大像素值，param.profile=3时生效:

Properties
Name Type Description
width number

宽度
height number

高度
frame_rate number <optional>
 5

共享视频的帧率，param.profile=3时生效，单位为 fps；默认值为 5，建议不要超过 15
bitrate number <optional>
 0

共享视频的码率，单位为 bps；默认值为 0，表示 SDK 根据当前共享屏幕的分辨率计算出一个合理的值
capture_mouse_cursor boolean

是否采集鼠标用于屏幕共享
window_focus boolean

调用 NERtcEngine#startScreenCaptureByWindowId 方法共享窗口时，是否将该窗口前置
excluded_window_list Array.<number>

待屏蔽窗口的 ID 列表
excluded_window_count number

待屏蔽窗口的数量
prefer number

编码策略倾向:

- 0 动画模式
- 1 细节模式
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

startScreenCaptureByScreenRect(screenRect [, regionRect=], param)

通过指定区域共享屏幕。共享一个屏幕或该屏幕的部分区域。用户需要在该方法中指定想要共享的屏幕区域。

NOTE:
- 该方法仅适用于 Windows。
- 该方法打开视频辅流。
Parameters:
Name Type Argument Description
screenRect object

指定待共享的屏幕相对于虚拟屏的位置。

Properties
Name Type Description
x number

左上角的横向偏移
y number

左上角的纵向偏移
width number

待共享区域的宽
height number

待共享区域的高
regionRect= object <optional>

(可选) 指定待共享区域相对于整个屏幕屏幕的位置。如果设置的共享区域超出了屏幕的边界，则只共享屏幕内的内容；如果将 width 或 height 设为 0, 则共享整个屏幕。
regionRect.x number

左上角的横向偏移
regionRect.y number

左上角的纵向偏移
regionRect.width number

待共享区域的宽
regionRect.height number

待共享区域的高
param object

屏幕共享的编码参数配置。

Properties
Name Type Argument Default Description
profile object <optional>
 2

屏幕共享编码参数配置:

- 0 640x480, 5fps
- 1 1280x720, 5fps
- 2 1920x1080, 5fps。默认
- 3 自定义
dimensions object

屏幕共享视频发送的最大像素值，param.profile=3时生效:

Properties
Name Type Description
width number

宽度
height number

高度
frame_rate number <optional>
 5

共享视频的帧率，param.profile=3时生效，单位为 fps；默认值为 5，建议不要超过 15
bitrate number <optional>
 0

共享视频的码率，单位为 bps；默认值为 0，表示 SDK 根据当前共享屏幕的分辨率计算出一个合理的值
capture_mouse_cursor boolean

是否采集鼠标用于屏幕共享
window_focus boolean

调用 NERtcEngine#startScreenCaptureByWindowId 方法共享窗口时，是否将该窗口前置
excluded_window_list Array.<number>

待屏蔽窗口的 ID 列表
excluded_window_count number

待屏蔽窗口的数量
prefer number

编码策略倾向:

- 0 动画模式
- 1 细节模式
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

startScreenCaptureByWindowId(windowid [, regionRect=], param)

通过窗口 ID 共享窗口。共享一个窗口或该窗口的部分区域。用户需要在该方法中指定想要共享的窗口 ID。

NOTE:
- 该方法仅适用于 Windows 和 macOS。
- 该方法打开视频辅流。
Parameters:
Name Type Argument Description
windowid number

指定待共享的窗口 ID。
regionRect= object <optional>

(可选) 指定待共享区域相对于整个屏幕屏幕的位置。如果设置的共享区域超出了屏幕的边界，则只共享屏幕内的内容；如果将 width 或 height 设为 0, 则共享整个屏幕。
regionRect.x number

左上角的横向偏移
regionRect.y number

左上角的纵向偏移
regionRect.width number

待共享区域的宽
regionRect.height number

待共享区域的高
param object

屏幕共享的编码参数配置。

Properties
Name Type Argument Default Description
profile object <optional>
 2

屏幕共享编码参数配置:

- 0 640x480, 5fps
- 1 1280x720, 5fps
- 2 1920x1080, 5fps。默认
- 3 自定义
dimensions object

屏幕共享视频发送的最大像素值，param.profile=3时生效:

Properties
Name Type Description
width number

宽度
height number

高度
frame_rate number <optional>
 5

共享视频的帧率，param.profile=3时生效，单位为 fps；默认值为 5，建议不要超过 15
bitrate number <optional>
 0

共享视频的码率，单位为 bps；默认值为 0，表示 SDK 根据当前共享屏幕的分辨率计算出一个合理的值
capture_mouse_cursor boolean

是否采集鼠标用于屏幕共享
window_focus boolean

调用 NERtcEngine#startScreenCaptureByWindowId 方法共享窗口时，是否将该窗口前置
excluded_window_list Array.<number>

待屏蔽窗口的 ID 列表
excluded_window_count number

待屏蔽窗口的数量
prefer number

编码策略倾向:

- 0 动画模式
- 1 细节模式
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

startVideoPreview()

开启视频预览。

该方法用于在进入频道前启动本地视频预览。调用该 API 前，必须:
- 调用 NERtcEngine#setupLocalVideoCanvas 设置预览窗口；
启用了本地视频预览后，在进入频道前，本地预览必须先关闭，需要调用 NERtcEngine#stopVideoPreview 。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

stopAllEffects()

停止播放所有音效文件。

Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

stopAudioDeviceLoopbackTest()

停止音频设备回路测试。

NOTE:
- 该方法需在加入房间前调用。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

stopAudioDump()

结束音频dump。

Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

stopAudioMixing()

停止播放伴奏。

该方法停止播放伴奏。请在频道内调用该方法。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

stopEffect(effectId)

停止播放指定音效文件。

请在频道内调用该方法。
Parameters:
Name Type Description
effectId number

指定音效的 ID。每个音效均有唯一的 ID。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

stopPlayoutDeviceTest()

停止播放设备测试。

NOTE:
- 该方法需在加入房间前调用。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

stopRecordDeviceTest()

停止音频采集设备测试。

该方法停止音频采集设备测试。
NOTE:
- 该方法需在加入房间前调用。
- 音频采集设备测试会在通话开始后自动结束，您也可以手动调用 NERtcEngine#stopRecordDeviceTest 停止音频采集设备测试。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

stopScreenCapture()

停止屏幕共享。

Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

stopVideoPreview()

停止视频预览。

Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

subscribeRemoteAudioStream(uid, subscribe)

订阅／取消订阅指定音频流。

Parameters:
Name Type Description
uid number

指定用户的 ID
subscribe boolean 
- true: 订阅指定音频流（默认）；
- false: 取消订阅指定音频流。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

subscribeRemoteVideoStream(uid, type, subscribe)

订阅 / 取消订阅指定远端用户的视频流。对方打开视频后需要主动订阅

Parameters:
Name Type Description
uid number

指定用户的用户 ID。
type number

流类型:

- 0 默认大流
- 1 小流
- 2 不订阅
subscribe boolean 
- true: 订阅指定远端用户的视频流；
- false: 取消订阅指定远端用户的视频流。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

subscribeRemoteVideoSubStream(uid, subscribe)

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

对方打开视频后需要主动订阅
NOTE:
- 必须在远端加入房间后调用。
- 必须先设置远端辅流画布。
Parameters:
Name Type Description
uid number

指定用户的用户 ID。
subscribe number 
- true: 订阅指定远端用户的视频流；
- false: 取消订阅指定远端用户的视频流。
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

updateLiveStreamTask(info)

更新修改房间推流任务。通话中有效。

Parameters:
Name Type Description
info Object

直播任务信息。

Properties
Name Type Description
task_id String

推流任务ID，为推流任务的唯一标识，用于过程中增删任务操作 <64 chars
stream_url String

直播推流地址 <256 chars
server_record_enabled Boolean

服务器录制功能是否开启
ls_mode Number

直播推流模式:

- 0 推流带视频
- 1 推流纯音频
layout Object

视频布局:

Properties
Name Type Description
width number

视频推流宽度
height number

视频推流高度
background_color number

视频推流背景色，(R & 0xff) << 16 | (G & 0xff) << 8 | (B & 0xff)
user_count number

成员布局个数
users Array.<object>

成员布局数组:
users[].uid number

用户id
users[].video_push boolean

是否推送该用户视频流，info.ls_mode=1时无效
users[].adaption number

视频流裁剪模式:

- 0 视频尺寸等比缩放。优先保证视频内容全部显示。因视频尺寸与显示视窗尺寸不一致造成的视窗未被填满的区域填充背景色
- 1 视频尺寸等比缩放。优先保证视窗被填满。因视频尺寸与显示视窗尺寸不一致而多出的视频将被截掉
users[].x number

画面离主画面左边距
users[].y number

画面离主画面上边距
users[].width number

画面在主画面的显示宽度，画面右边超出主画面会失败
users[].height number

画面在主画面的显示高度，画面底边超出主画面会失败
users[].audio_push boolean

是否推送该用户音频流
users[].bg_image object

背景图信息:

Properties
Name Type Description
url String

图片地址
x number

画面离主画面左边距
y number

画面离主画面上边距
width number

画面在主画面的显示宽度，画面右边超出主画面会失败
height number

画面在主画面的显示高度，画面底边超出主画面会失败
Fires:
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

updateScreenCaptureRegion(param)

在共享屏幕或窗口时，更新共享的区域。

Parameters:
Name Type Description
param object

屏幕共享的编码参数配置。

Properties
Name Type Argument Default Description
profile object <optional>
 2

屏幕共享编码参数配置:

- 0 640x480, 5fps
- 1 1280x720, 5fps
- 2 1920x1080, 5fps。默认
- 3 自定义
dimensions object

屏幕共享视频发送的最大像素值，param.profile=3时生效:

Properties
Name Type Description
width number

宽度
height number

高度
frame_rate number <optional>
 5

共享视频的帧率，param.profile=3时生效，单位为 fps；默认值为 5，建议不要超过 15
bitrate number <optional>
 0

共享视频的码率，单位为 bps；默认值为 0，表示 SDK 根据当前共享屏幕的分辨率计算出一个合理的值
capture_mouse_cursor boolean

是否采集鼠标用于屏幕共享
window_focus boolean

调用 NERtcEngine#startScreenCaptureByWindowId 方法共享窗口时，是否将该窗口前置
excluded_window_list Array.<number>

待屏蔽窗口的 ID 列表
excluded_window_count number

待屏蔽窗口的数量
prefer number

编码策略倾向:

- 0 动画模式
- 1 细节模式
Returns:
- 0: 方法调用成功；
- 其他: 方法调用失败。
Type
number

uploadSdkInfo()

上传SDK 信息（如log文件和Audio dump文件）。

Events

onAddLiveStreamTask

通知添加直播任务结果。

该回调异步返回 NERtcEngine#addLiveStreamTask 接口的调用结果；实际推流状态参考 onLiveStreamState 事件
Parameters:
Name Type Description
task_id String

任务id
url String

推流地址
error number

结果

onAudioDefaultDeviceChanged

音频默认设备更改回调。

Parameters:
Name Type Description
device_id string

设备ID。
device_type number

音频设备类型:

- 0 未知音频设备
- 1 音频采集设备
- 2 音频播放设备

onAudioDeviceStateChanged

音频设备状态更改回调。

Parameters:
Name Type Description
device_id string

设备ID。
device_type number

音频设备类型:

- 0 未知音频设备
- 1 音频采集设备
- 2 音频播放设备
device_state number

音频设备状态:

- 0 音频设备已激活
- 1 音频设备未激活

onAudioEffectFinished

本地音效文件播放已结束回调。

当播放音效结束后，会触发该回调。
Parameters:
Name Type Description
effect_id number

音效ID

onAudioHowling

监测音频啸叫的回调。

Parameters:
Name Type Description
howling boolean

是否出现啸叫

onAudioMixingStateChanged

本地用户的音乐文件播放状态改变回调。

调用 NERtcEngine#startAudioMixing 播放混音音乐文件后，当音乐文件的播放状态发生改变时，会触发该回调。
- 如果播放音乐文件正常结束，state 会返回相应的状态码 0，error_code 返回 0。
- 如果播放出错，则返回状态码 1，error_code 返回相应的出错原因。
- 如果本地音乐文件不存在、文件格式不支持、无法访问在线音乐文件 URL，error_code都会返回 100。
Parameters:
Name Type Description
state number

音乐文件播放状态:

- 0 音乐文件播放结束。
- 1 音乐文件报错。
error_code number

错误码:

- 0 没有错误。
- 1 通用错误。
- 100 音乐文件打开出错。

onAudioMixingTimestampUpdate

本地用户的音乐文件播放进度回调

调用 NERtcEngine#startAudioMixing 播放混音音乐文件后，当音乐文件的播放进度改变时，会触发该回调。
Parameters:
Name Type Description
timestamp_ms number

音乐文件播放进度，单位为毫秒。

onClientRoleChanged

参会者角色类型变更回调。

本地用户加入房间后，通过 NERtcEngine#setClientRole 切换用户角色后会触发此回调。例如从主播切换为观众、从观众切换为主播。
NOTE:
直播场景下，如果您在加入房间后调用该方法切换用户角色，调用成功后，会触发以下回调：
- 主播切观众，本端触发onClientRoleChanged回调，远端触发 onUserLeft 回调。
- 观众切主播，本端触发onClientRoleChanged回调，远端触发 onUserJoined 回调。
Parameters:
Name Type Description
oldRole number

原角色类型。

- 0 主播
- 1 观众
newRole number

新角色类型。

- 0 主播
- 1 观众

onConnectionStateChange

连接状态变更。

有时候由于通话流程、用户行为、网络原因等，客户端通话状态变更，触发此回调。
Parameters:
Name Type Description
state number

变更后通话状态:

- 1 没加入频道
- 2 正在加入频道
- 3 加入频道成功
- 4 正在尝试重新加入频道
- 5 加入频道失败
reason number

变更原因:

- 1 离开房间
- 2 房间被关闭
- 3 用户被踢
- 4 服务超时
- 5 加入房间
- 6 加入房间成功
- 7 重新加入房间成功（重连）
- 8 媒体连接断开
- 9 信令连接断开
- 10 请求频道失败
- 11 加入频道失败

onDisconnect

掉线回调。

由于非网络原因，客户端可能会和服务器失去连接，此时SDK无需自动重连，直接触发此回调方法。
Parameters:
Name Type Description
result NERtcErrorCode

错误码

onError

发生错误回调。

Parameters:
Name Type Description
errorCode NERtcErrorCode

错误码
msg string

错误描述

onFirstAudioDataReceived

已接收到远端音频首帧回调。

Parameters:
Name Type Description
uid number

发送音频帧的远端用户的用户 ID。

onFirstAudioFrameDecoded

已解码远端音频首帧的回调。

Parameters:
Name Type Description
uid number

远端用户 ID。

onFirstVideoDataReceived

已显示首帧远端视频回调。

第一帧远端视频显示在视图上时，触发此调用。
Parameters:
Name Type Description
uid number

用户 ID，指定是哪个用户的视频流。

onFirstVideoFrameDecoded

已显示首帧远端视频回调。

引擎收到第一帧远端视频流并解码成功时，触发此调用。 App 可在此回调中设置该用户的 video canvas。
Parameters:
Name Type Description
uid number

用户 ID，指定是哪个用户的视频流。
width number

视频流宽（px）。
height number

视频流高（px）。

onJoinChannel

加入频道回调

Parameters:
Name Type Description
cid number

频道 ID
uid number

用户 ID
result NERtcErrorCode

错误码
elapsed number

从 joinChannel 开始到发生此事件过去的时间（毫秒）

onLeaveChannel

离开频道回调。
App 调用 NERtcEngine#leaveChannel 方法时，SDK提示 App 离开频道是否成功。

Parameters:
Name Type Description
result NERtcErrorCode

错误码

onLiveStreamState

通知直播推流状态

Parameters:
Name Type Description
task_id string

任务id
url string

推流地址
state number

直播推流状态:

- 505: 推流中；
- 506: 推流失败；
- 511: 推流结束；

onLocalAudioStats

本地音频流统计信息回调。

该回调描述本地设备发送音频流的统计信息，每 2 秒触发一次。
Parameters:
Name Type Description
stats object

本地音频流统计信息:

Properties
Name Type Description
num_channels number

当前采集声道数。
sent_sample_rate number

本地上行音频采样率。
sent_bitrate number

（上次统计后）发送码率(Kbps)。
audio_loss_rate number

特定时间内的音频丢包率 (%)。
rtt number

RTT。
volume number

音量，范围为 0（最低）- 100（最高）。

onLocalAudioVolumeIndication

提示频道内本地用户瞬时音量的回调。

该回调默认禁用。可以通过 NERtcEngine#enableAudioVolumeIndication 方法开启；
开启后，本地用户说话，SDK 会按 NERtcEngine#enableAudioVolumeIndication 方法中设置的时间间隔触发该回调。
如果本地用户将自己静音（调用了 NERtcEngine#muteLocalAudioStream），SDK 将音量设置为 0 后回调给应用层。
Parameters:
Name Type Description
volume number

（混音后的）音量，取值范围为 [0,100]。

onLocalVideoStats

本地视频流统计信息回调。

该回调描述本地设备发送视频流的统计信息，每 2 秒触发一次。
Parameters:
Name Type Description
stats object

本地视频流统计信息:

Properties
Name Type Description
video_layers_count number

视频流条数。
video_layers_list Array.<object>

视频流信息数组:
video_layers_list[].layer_type number

流类型： 1、主流，2、辅流。
video_layers_list[].width number

视频流宽（像素）
video_layers_list[].height number

视频流高（像素）
video_layers_list[].capture_frame_rate number

视频采集帧率。
video_layers_list[].render_frame_rate number

视频渲染帧率。
video_layers_list[].encoder_frame_rate number

编码帧率。
video_layers_list[].sent_frame_rate number

发送帧率。
video_layers_list[].sent_bitrate number

发送码率(Kbps)。
video_layers_list[].target_bitrate number

编码器目标码率(Kbps)。
video_layers_list[].encoder_bitrate number

编码器实际编码码率(Kbps)。
video_layers_list[].codec_name String

视频编码器名字。

onNetworkQuality

通话中每个用户的网络上下行质量报告回调。

该回调描述每个用户在通话中的网络状态，每 2 秒触发一次，只上报状态有变更的成员。
Parameters:
Name Type Description
uc number

数组的大小，即用户数。
stats object

每个用户 ID 和网络上下行质量信息的数组:
stats[].uid number

用户 ID，指定是哪个用户的视频流。
stats[].tx_quality number

该用户的上行网络质量:

- 0 网络质量未知
- 1 网络质量极好
- 2 用户主观感觉和 excellent 差不多，但码率可能略低于 excellent
- 3 用户主观感受有瑕疵但不影响沟通
- 4 勉强能沟通但不顺畅
- 5 网络质量非常差，基本不能沟通
- 6 完全无法沟通
stats[].rx_quality number

该用户的下行网络质量:

- 0 网络质量未知
- 1 网络质量极好
- 2 用户主观感觉和 excellent 差不多，但码率可能略低于 excellent
- 3 用户主观感受有瑕疵但不影响沟通
- 4 勉强能沟通但不顺畅
- 5 网络质量非常差，基本不能沟通
- 6 完全无法沟通

onReconnectingStart

触发重连。

有时候由于网络原因，客户端可能会和服务器失去连接，SDK会进行自动重连，开始自动重连后触发此回调。
Parameters:
Name Type Description
cid

频道 ID。
uid

用户 ID。

onRejoinChannel

重新加入频道回调。

有时候由于网络原因，客户端可能会和服务器失去连接，SDK会进行自动重连，自动重连后触发此回调方法。
Parameters:
Name Type Description
cid number

频道 ID
uid number

用户 ID
result NERtcErrorCode

错误码
elapsed number

从 joinChannel 开始到发生此事件过去的时间（毫秒）

onReleasedHwResources

释放硬件资源的回调。

Parameters:
Name Type Description
result NERtcErrorCode

错误码

onRemoteAudioStats

通话中远端音频流的统计信息回调。

该回调描述远端用户在通话中端到端的音频流统计信息，每 2 秒触发一次。
Parameters:
Name Type Description
uc number

stats 数组的大小
stats Array.<object>

每个远端用户音频统计信息的数组:
stats[].uid number

用户 ID，指定是哪个用户的音频流
stats[].received_bitrate number

（上次统计后）接收到的码率(Kbps)
stats[].total_frozen_time number

用户的下行音频卡顿累计时长(ms)
stats[].frozen_rate number

用户的下行音频平均卡顿率(%)。
stats[].audio_loss_rate number

特定时间内的音频丢包率 (%)。
stats[].volume number

音量，范围为 0（最低）- 100（最高）。

onRemoteVideoStats

通话中远端视频流的统计信息回调。

该回调描述远端用户在通话中端到端的视频流统计信息，每 2 秒触发一次。
Parameters:
Name Type Description
uc number

数组的大小。
stats object

每个远端用户视频统计信息的数组:

Properties
Name Type Description
uid number

用户 ID，指定是哪个用户的视频流。
video_layers_count number

视频流条数。
video_layers_list Array.<object>

视频流信息数组:
video_layers_list[].layer_type number

流类型： 1、主流，2、辅流。
video_layers_list[].width number

视频流宽（像素）
video_layers_list[].height number

视频流高（像素）
video_layers_list[].capture_frame_rate number

视频采集帧率。
video_layers_list[].render_frame_rate number

视频渲染帧率。
video_layers_list[].encoder_frame_rate number

编码帧率。
video_layers_list[].sent_frame_rate number

发送帧率。
video_layers_list[].sent_bitrate number

发送码率(Kbps)。
video_layers_list[].target_bitrate number

编码器目标码率(Kbps)。
video_layers_list[].encoder_bitrate number

编码器实际编码码率(Kbps)。
video_layers_list[].codec_name String

视频编码器名字。

onRemoveLiveStreamTask

通知删除直播任务结果。

该回调异步返回 NERtcEngine#removeLiveStreamTask 接口的调用结果；实际推流状态参考 onLiveStreamState 事件
Parameters:
Name Type Description
task_id String

任务id
error number

结果

onRtcStats

当前通话统计回调。

SDK 定期向 App 报告当前通话的统计信息，每 2 秒触发一次。
Parameters:
Name Type Description
stats object

NERTC 引擎统计数据:

Properties
Name Type Description
cpu_app_usage number

当前 App 的 CPU 使用率 (%)。
cpu_idle_usage number

当前系统的 CPU 空闲率 (%)。
cpu_total_usage number

当前系统的 CPU 使用率 (%)。
memory_app_usage number

当前App的内存使用率 (%)。
memory_total_usage number

当前系统的内存使用率 (%)。
memory_app_kbytes number

当前App的内存使用量 (KB)。
total_duration number

通话时长（秒）。
tx_bytes number

发送字节数，累计值。(bytes)
rx_bytes number

接收字节数，累计值。(bytes)
tx_audio_bytes number

音频发送字节数，累计值。(bytes)
tx_video_bytes number

视频发送字节数，累计值。(bytes)
rx_audio_bytes number

音频接收字节数，累计值。(bytes)
rx_video_bytes number

视频接收字节数，累计值。(bytes)
tx_audio_kbitrate number

音频发送码率。(kbps)
rx_audio_kbitrate number

音频接收码率。(kbps)
tx_video_kbitrate number

视频发送码率。(kbps)
rx_video_kbitrate number

视频接收码率。(kbps)
up_rtt number

上行平均往返时延rtt(ms)
down_rtt number

下行平均往返时延rtt(ms)
tx_audio_packet_loss_rate number

本地上行音频实际丢包率。(%)
tx_video_packet_loss_rate number

本地上行视频实际丢包率。(%)
tx_audio_packet_loss_sum number

本地上行音频实际丢包数。
tx_video_packet_loss_sum number

本地上行视频实际丢包数。
tx_audio_jitter number

本地上行音频抖动计算。(ms)
tx_video_jitter number

本地上行视频抖动计算。(ms)
rx_audio_packet_loss_rate number

本地下行音频实际丢包率。(%)
rx_video_packet_loss_rate number

本地下行视频实际丢包率。(%)
rx_audio_packet_loss_sum number

本地下行音频实际丢包数。
rx_video_packet_loss_sum number

本地下行视频实际丢包数。
rx_audio_jitter number

本地下行音频抖动计算。(ms)
rx_video_jitter number

本地下行视频抖动计算。(ms)

onUpdateLiveStreamTask

通知更新直播任务结果。

该回调异步返回 NERtcEngine#updateLiveStreamTask 接口的调用结果；实际推流状态参考 onLiveStreamState 事件
Parameters:
Name Type Description
task_id String

任务id
url String

推流地址
error number

结果

onUserAudioMute

远端用户是否静音回调。

Parameters:
Name Type Description
uid number

远端用户ID。
mute boolean

是否静音。

onUserAudioStart

远端用户开启音频回调。

Parameters:
Name Type Description
uid number

远端用户ID。

onUserAudioStop

远端用户停用音频回调。

Parameters:
Name Type Description
uid number

远端用户ID。

onUserJoined

远端用户加入当前频道回调。

- 通信模式下，该回调提示有远端用户加入了频道，并返回新加入用户的 ID；如果加入之前，已经有其他用户在频道中了，新加入的用户也会收到这些已有用户加入频道的回调。
Parameters:
Name Type Description
uid number

新加入频道的远端用户ID。
userName string

新加入频道的远端用户名(无效)。

onUserLeft

远端用户离开当前频道回调。

提示有远端用户离开了频道（或掉线）。
Parameters:
Name Type Description
uid number

远端用户ID。
reason number

远端用户离开原因:

- 0 正常离开
- 1 用户断线导致离开
- 2 用户 Failover 过程中产生的 leave
- 3 用户被踢导致离开
- 4 用户超时导致离开

onUserSubStreamVideoStart

远端用户开启辅流视频回调。

Parameters:
Name Type Description
uid number

远端用户ID。
maxProfile number

最大分辨率:

- 0 160x90/120, 15fps
- 1 320x180/240, 15fps
- 2 640x360/480, 30fps
- 3 1280x720, 30fps
- 4 1920x1080, 30fps

onUserSubStreamVideoStop

远端用户停用辅流视频回调。

Parameters:
Name Type Description
uid number

远端用户ID。

onUserVideoMute

远端用户是否禁视频流回调。

Parameters:
Name Type Description
uid number

远端用户ID。
mute boolean

是否禁视频流。

onUserVideoProfileUpdate

远端用户视频配置更新回调。

Parameters:
Name Type Description
uid number

远端用户ID。
maxProfile number

最大分辨率:

- 0 160x90/120, 15fps
- 1 320x180/240, 15fps
- 2 640x360/480, 30fps
- 3 1280x720, 30fps
- 4 1920x1080, 30fps

onUserVideoStart

远端用户开启视频回调。

Parameters:
Name Type Description
uid number

远端用户ID。
maxProfile number

最大分辨率:

- 0 160x90/120, 15fps
- 1 320x180/240, 15fps
- 2 640x360/480, 30fps
- 3 1280x720, 30fps
- 4 1920x1080, 30fps

onUserVideoStop

远端用户停用视频回调。

Parameters:
Name Type Description
uid number

远端用户ID。

onVideoDeviceStateChanged

视频设备状态更改回调。

Parameters:
Name Type Description
device_id string

设备ID。
device_type number

视频设备类型:

- 0 未知音频设备
- 1 视频采集设备
device_state number

视频设备状态:

- 0 视频设备已添加
- 1 视频设备已拔除

onWarning

发生警告回调。

Parameters:
Name Type Description
warnCode NERtcErrorCode

错误码
msg string

错误描述