Interface NERtc

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

Par

使用前提 请先通过 NERtc#setChannelProfile 接口设置房间模式为直播模式。

Par

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

Note

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

Sample

class CustomCallback extends NERtcCallbackEx {

  //... 其他回调

  onAddLiveStreamTask(taskId: string, url: string, errorCode: number): void {
     //添加推流任务回调
  }

  onUpdateLiveStreamTask(taskId: string, url: string, errorCode: number): void {
     //更新推流任务回调
  }

  onRemoveLiveStreamTask(taskId: string, errorCode: number): void {
       //删除推流任务回调
  }
}


let taskInfo: NERtcConstants.NERtcLiveStreamTaskInfo = {
 taskID: "xxxx",
 streamURL: 'xxxx'
 //其他更多参数
}

//添加推流任务
NERtcSDK.getInstance().addLiveStreamTask(taskInfo)

Copy

Par

相关回调
NERtcCallback.NERtcCallbackEx#onAddLiveStreamTask ：推流任务已成功删除回调。
NERtcCallback.NERtcCallbackEx#onLiveStreamState：推流任务状态已改变回调。
NERtcCallback.NERtcCallbackEx#onRemoveLiveStreamTask: 推流任务状态已更新

调节本地播放的所有远端用户的信号音量。
通过此接口可以实现调节所有远端用户在本地播放的混音音量。

Par

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

Note

建议设置本地播放音量时使用默认值（100）或小于该值，否则可能会导致音质问题。

Sample

示例代码

//调整所有远端用户在本地的播放音量为50
NERtcSDK.getInstance().adjustPlaybackSignalVolume(50);
//调整所有远端用户在本地的播放音量为0，静音所有用户
NERtcSDK.getInstance().adjustPlaybackSignalVolume(0);
Copy

调节采集信号音量。 通过本接口可以实现设置录制声音的信号幅度，从而达到调节采集音量的目的。

Par

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

Note

• 该方法设置内部引擎为启用状态，在 () 后设置失效，将恢复至默认。如果您离开房间后重新加入房间，需要重新调用本接口。
• 建议设置本地采集音量为默认值（100）或小于该值，否则可能会导致音质问题。
• 该方法仅设置应用程序中的采集信号音量，不修改设备音量，也不会影响伴音、音效等的音量；若您需要修改设备音量，请调用设备管理相关接口。

Sample

//将采集音量设置为100
NERtcEx.getInstance().adjustRecordingSignalVolume(100);
Copy

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

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

Par

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

Par

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

Sample

//设置间隔为500ms的人声音量提示
NERtcSDK.getInstance().enableAudioVolumeIndication(true, BigInt(500), true);
Copy

Par

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

Par

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

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

Par

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

Note

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

设置是否开启耳返功能。
请在初始化后调用该方法，且该方法仅可在加入房间后调用。

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

Note

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

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

Par

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

Note

• 加入房间后，语音功能默认为开启状态。
• 该方法设置内部引擎为启用状态，在 () 后仍然有效。
• 该方法不影响接收或播放远端音频流，enableLocalAudio(false) 适用于只下行不上行音频流的场景。
• 自 V4.4.0 版本起，开启或关闭本地音频采集的操作不会影响伴音/音效接口的使用，比如 enableLocalAudio(false) 后仍可以调用 NERtcEx#startAudioMixing() 方法播放音乐文件。
• 该方法会操作音频硬件设备，建议避免频繁开关，否则可能导致设备异常。

Sample

示例代码 //打开音频采集 NERtcSDK.getInstance().enableLocalAudio(true) //关闭音频采集 NERtcSDK.getInstance().enableLocalAudio(false)

Par

相关回调

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

Par

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

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

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

Par

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

Note

• 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
• 该方法设置内部引擎为开启或关闭状态, 在 () 后仍然有效。
• 在您的应用切到后台或者其他应用占用摄像头时，可能会导致摄像头打开失败，需要注册 camera 动态权限，详细信息请参考添加权限。

Sample

//打开视频
NERtcEx.getInstance().enableLocalVideo(true);
//关闭视频
NERtcEx.getInstance().enableLocalVideo(false);
Copy

Par

相关回调

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

开启或关闭音频共享

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

Note

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

Par

相关接口 NERtc#muteLocalAudioStream

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

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

Note

您可以通过 NERtcCallback.onVirtualBackgroundSourceEnabled 回调查看虚拟背景是否开启成功或出错原因。

• 建议您在满足以下条件的场景中使用该功能：
• 采用高清摄像设备，环境光线均匀。
• 捕获的视频图像整洁，用户肖像半长且基本无遮挡，并且背景是与用户衣服颜色不同的单一颜色。
• 虚拟背景功能不支持在 Texture 格式的视频或通过 Push 方法从自定义视频源获取的视频中设置虚拟背景。
• 若您设置背景图片为自定义本地图片，SDK 会在保证背景图片内容不变形的前提下，对图片进行一定程度上的缩放和裁剪，以适配视频采集分辨率。

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

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

Note

• 请在加入房间后调用该方法。
• 伴音相关方法为异步加载，刚开始伴音时，如果立即调用此方法，获取到的伴奏时长可能为错误码30001。如果遇到此类问题，等待伴音状态是开始之后再调用。

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

Note

请先调用 NERtc#startAudioMixing 方法开启伴音。
请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。

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

Note

• 请在加入房间后调用该方法。

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

Note

• 请在加入房间后调用该方法。

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

Note

• 请在加入房间后调用该方法。

获取当前摄像头缩放比例。

获取摄像头支持的最大缩放比例。
该方法需要在相机启动后调用，例如调用 startVideoPreview 或 joinChannel 后。

获取当前房间连接状态。

查看当前摄像头配置。

Note

• 该方法用于查看当前使用的摄像头为前置摄像头还是后置摄像头。
• 该方法需要在相机启动后调用，例如调用 startVideoPreview 或 joinChannel 后。

If

Chinese 获取音效的播放进度。
请在加入房间后调用该方法。 *

Endif

If

Chinese 获取音效文件时长。
请在加入房间后调用该方法。

Endif

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

Note

• 请先调用 NERtc#playEffect 方法播放音效。
• 请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。

If

English Gets the volume of the audio effects.
You can call the method after joining a room.

Endif

If

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

Endif

If

Chinese 获取指定音效文件发送音量。
请在加入房间后调用该方法。

Endif

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

以string的形式获取一些内部参数，此接口为隐藏接口，需要特定参数及特定时机，详情联系技术支持。

创建 NERtc 实例。
通过本接口可以实现创建 NERtc 实例并初始化 NERTC SDK 服务。

检测设备是否支持手动曝光功能。
该方法需要在相机启动后调用，例如调用 startVideoPreview 或 joinChannel 后。

检测设备是否支持手动对焦功能。
该方法需要在相机启动后调用，例如调用 startVideoPreview 或 joinChannel 后。

检测设备是否支持闪光灯常亮。

Note

• 一般情况下，App 默认开启前置摄像头，因此如果设备前置摄像头不支持闪光灯，直接使用该方法会返回 false。如果需要检查后置摄像头是否支持闪光灯，需要先使用 switchCamera 切换摄像头，再使用该方法。
• 该方法需要在相机启动后调用，例如调用 startVideoPreview 或 joinChannel 后。

检测设备当前使用的摄像头是否支持缩放功能。
该方法需要在相机启动后调用，例如调用 startVideoPreview 或 joinChannel 后。

查看当前音频播放设备是否静音。

查看当前音频采集设备是否静音。

检查扬声器状态启用状态。
该方法可在加入房间前后调用。

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

Par

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

Note

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

Par

相关接口

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

Par

相关回调

• 成功调用该方法加入房间后，本地会触发 NERtcCallback#onJoinChannel 回调，远端会触发 NERtcCallback#onUserJoined 回调。

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

Par

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

Note

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

Sample

NERtcSDK.getInstance().leaveChannel()

Par

相关回调 成功调用该方法离开房间后，本地会触发 NERtcCallback#onLeaveChannel 回调，远端会触发 NERtcCallback#onUserLeave 回调。

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

Par

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

Note

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

Sample

示例代码
//不发送本地音频
NERtcSDK.getInstance().muteLocalAudioStream(true);
//发送本地音频
NERtcSDK.getInstance().muteLocalAudioStream(false);

Par

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

Par

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

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

Note

静音状态会在通话结束后被重置为非静音。

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

Par

使用前提 一般在通过 (NERtcVideoStreamType streamType, boolean enable)(true) 接口开启本地视频采集并发送后调用该方法。

Par

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

Note

• 调用该方法取消发布本地视频流时，设备仍然处于工作状态。
• 若调用该方法取消发布本地视频流，通话结束后会被重置为默认状态，即默认发布本地视频流。
• 该方法与 (NERtcVideoStreamType streamType, boolean enable)(false) 的区别在于，后者会关闭本地摄像头设备，该方法不禁用摄像头，不会影响本地视频流采集且响应速度更快。

Par

参数说明

Par

示例代码

Code

//取消发布本地视频主流 NERtcSDK.getInstance().muteLocalVideo(NERtcConstants.NERtcVideoStreamType.kNERtcVideoStreamTypeMain, true); //恢复发布本地视频主流 NERtcSDK.getInstance().muteLocalVideo(NERtcConstants.NERtcVideoStreamType.kNERtcVideoStreamTypeMain, false); //取消发布本地视频辅流 NERtcSDK.getInstance().muteLocalVideo(NERtcConstants.NERtcVideoStreamType.kNERtcVideoStreamTypeSub, true); //恢复发布本地视频辅流 NERtcSDK.getInstance().muteLocalVideo(NERtcConstants.NERtcVideoStreamType.kNERtcVideoStreamTypeSub, false);

Endcode

Par

相关回调 取消发布本地视频主流或辅流后，远端会收到 NERtcCallbackEx.onUserVideoMute() 回调。

暂停播放所有音效文件。

Note

请在加入房间后调用该方法。

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

Par

使用前提
请先调用 NERtc#startAudioMixing 开启伴音。

Par

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

Sample

NERtcEx.getInstance().pauseAudioMixing();
Copy

Par

相关接口
可以继续调用 NERtcEx#resumeAudioMixing() 方法恢复播放伴音文件。

暂停播放指定音效文件。

Note

请在加入房间后调用该方法。

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

Par

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

Note

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

Sample

示例代码

 let option: NERtcConstants.NERtcCreateAudioEffectOption = {
     path: 'xxxx',
     loopCount: 1,
     sendEnabled: true,
     playbackEnabled: true,
     sendVolume: 100,
     playbackVolume: 100,
     startTimeStamp: BigInt(0),
     sendWithAudioType: NERtcConstants.NERtcAudioStreamType.kNERtcAudioStreamTypeMain,
     progressInterval: BigInt(1000)
 }
 let mAudioEffectId = 1
 NERtcSDK.getInstance().playEffect(mAudioEffectId, option)
Copy

Par

相关接口 NERtcCallback.NERtcCallback#onAudioEffectTimestampUpdate：本地音效文件播放进度回调。 NERtcCallback.NERtcCallbackEx#onAudioEffectFinished：本地音效文件播放已结束回调。

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

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

Note

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

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

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

Note

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

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

推送外部视频帧。
该方法主动将视频帧数据用 NERtcVideoFrame 类封装后传递给 SDK。

Note

• 该方法仅适用于视频主流，若您希望向辅流通道推送外部视频帧，请调用 NERtc#pushExternalVideoFrame 方法。
• 该方法设置内部引擎为启用状态，在 leaveChannel 后不再有效。
• 请确保在你调用本方法前已调用 setExternalVideoSource，并将参数设为 true，否则调用本方法后会一直报错。

销毁 NERtc 实例，释放资源。
该方法释放 NERTC SDK 使用的所有资源。有些 App 只在用户需要时才进行实时音视频通信，完成音视频通话后，则将资源释放出来用于其他操作，该方法适用于此类情况。

• 该接口需要在调用 leaveChannel、并收到 onUserLeave 回调后调用。或收到 onDisconnect 回调、重连失败时调用此接口销毁实例，并释放资源。
• 调用 release 方法后，您将无法再使用 SDK 的其它方法和回调。如需再次使用实时音视频通话功能，您必须等待 release 方法执行结束后，重新创建一个新的 NERtc 实例。

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

Par

使用前提 请先调用 NERtc#addLiveStreamTask 方法添加推流任务。

Par

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

Note

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

Sample

class CustomCallback extends NERtcCallbackEx {

  //... 其他回调
  onAddLiveStreamTask(taskId: string, url: string, errorCode: number): void {
     //添加推流任务回调
  }

  onUpdateLiveStreamTask(taskId: string, url: string, errorCode: number): void {
     //更新推流任务回调
  }

  onRemoveLiveStreamTask(taskId: string, errorCode: number): void {
     //删除推流任务回调
  }
}

//移除推流任务
NERtcSDK.getInstance().removeLiveStreamTask(taskId)

Copy

Par

相关回调
NERtcCallback.NERtcCallbackEx#onAddLiveStreamTask ：推流任务已成功删除回调。
NERtcCallback.NERtcCallbackEx#onLiveStreamState：推流任务状态已改变回调。
NERtcCallback.NERtcCallbackEx#onRemoveLiveStreamTask: 推流任务状态已更新

用户自定义上报事件

恢复播放所有音效文件。

Note

请在加入房间后调用该方法。

恢复播放伴奏。
该方法恢复混音，继续播放伴奏。请在房间内调用该方法。

恢复播放指定音效文件。

Note

请在加入房间后调用该方法。

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

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

Note

• SEI 数据跟随视频帧发送，由于在弱网环境下可能丢帧，SEI 数据也可能随之丢失，所以建议在发送频率限制之内多次发送，保证接收端收到的概率。
• 指定通道发送SEI之前，需要提前开启对应的数据流通道。

See

NERtcCallback.NERtcCallbackEx#onRecvSEIMsg

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

Note

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

• 该方法设置内部引擎为启用状态，在 NERtc#leaveChannel 后设置失效，将恢复至默认，即关闭变声音效。
• 该方法和 () 方法互斥，调用了其中任一方法后，另一方法的设置会被重置为默认值。

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

设置当前伴音文件的音调。
通过此接口可以实现当本地人声和播放的音乐文件混音时，仅调节音乐文件的音调。
请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。

Note

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

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

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

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

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

Par

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

Note

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

Sample

//设置profile为标准模式，scenario为语音场景
NERtcSDK.getInstance().setAudioProfile(NERtcConstants.AudioProfile.STANDARD, NERtcConstants.AudioScenario.SPEECH);
Copy

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

Note

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

Note

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

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

Note

• 请在初始化后调用该方法，且该方法在加入房间前后均可调用。
• 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
• 该方法支持在加入房间后动态调用，设置成功后，会自动重启摄像头采集模块。
• 若系统相机不支持您设置的分辨率，会自动调整为最相近一档的分辨率，因此建议您设置为常规标准的分辨率。
• 设置较高的采集分辨率会增加性能消耗，例如 CPU 和内存占用等，尤其是在开启视频前处理的场景下。

设置手动对焦位置。
该方法需要在相机启动后调用，例如调用 startVideoPreview 或 joinChannel 后。
成功调用该方法后，本地会触发 onCameraFocusChanged 回调。

设置手动对焦位置。
该方法需要在相机启动后调用，例如调用 startVideoPreview 或 joinChannel 后。
成功调用该方法后，本地会触发 onCameraFocusChanged 回调。

设置是否打开闪光灯。
该方法需要在相机启动后调用，例如调用 startVideoPreview 或 joinChannel 后。

设置摄像头缩放比例。

Note

• 该方法需要在相机启动后调用，例如调用 startVideoPreview 或 joinChannel 后。
• 建议在调用本接口前，先通过 getCameraMaxZoom 查看摄像头支持的最大缩放比例，并根据实际需求合理设置需要的缩放比例。

设置房间场景。
通过此接口可以实现设置房间场景为通话（默认）或直播场景。针对不同场景采取的优化策略不同，如通话场景侧重语音流畅度，直播场景侧重视频清晰度。

Par

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

Par

参数说明

Par

示例代码

Code

//设置房间场景为直播场景 NERtcSDK.getInstance().setChannelProfile(NERtcConstants.NERtcChannelProfile.kNERtcChannelProfileLiveBroadcasting);

Endcode

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

Par

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

Par

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

Par

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

Note

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

Sample

//切换用户角色为主播 NERtcSDK.getInstance().setClientRole(NERtcConstants.NERtcClientRole.CLIENT_ROLE_BROADCASTER); //切换用户角色为观众 NERtcSDK.getInstance().setClientRole(NERtcConstants.NERtcClientRole.CLIENT_ROLE_AUDIENCE);

Par

相关回调

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

设置耳返音量。

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

Note

• 请先调用 NERtc#playEffect 方法播放音效。
• 请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。

If

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

Endif

If

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

Endif

If

Chinese 设置指定音效文件的播放位置。
请在加入房间后调用该方法。

Endif

If

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

Endif

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

Par

使用前提 建议在通过 NERtc#enableLocalAudio 接口关闭本地音频设备采集之后调用该方法。

Par

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

Par

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

Note

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

Sample

示例代码 //第一步 先关闭设备采集（若已经开启了本地设备采集）
NERtcSDK.getInstance().enableLocalAudio(false);
//第二步 打开外部音频输入
NERtcSDK.getInstance().setExternalAudioSource(true, 44100, 2);
//第三步 打开音频通道
NERtcSDK.getInstance().enableLocalAudio(true);
//第四步 推入外部音频输入数据，这里只推一帧作为参考

let frame: NERtcConstants.NERtcAudioExternalFrame = { data: sampleData, //(Uint8Array)
sampleRate: mSampleRate, //采样率
channels: mChannels, //通道数
samplesPerChannel: mSampleRate * CUSTOM_AUDIO_TIME_DUR / 1000, //单个通道中采集点个数
syncTimestamp: lastSyncTimestamp //同步音频主辅流的时间戳，一般只在同时开启外部音频主流及辅流输入时用到
} NERtcSDK.getInstance().pushExternalAudioFrame(frame)

Par

相关接口

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

开启或关闭外部音频辅流输入。
调用成功后可以使用 NERtc#pushExternalSubStreamAudioFrame 接口发送音频辅流 PCM 数据。

Note

• 请在NERtc#pushExternalSubStreamAudioFrame前调用该方法。
• 开启后音频辅流将由用户驱动，在 leaveChannel 后自动失效。

Note

调用此接口关闭外部音频辅流输入时可传入任意合法值，此时设置不会生效。

Note

调用此接口关闭外部音频辅流输入时可传入任意合法值，此时设置不会生效。

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

Par

使用前提 请在通过 () 接口关闭本地视频设备采集之后调用该方法。

Par

调用时机 请在通过 (NERtcVideoStreamType streamType) 接口开启本地视频预览或通过 (NERtcVideoStreamType streamType, boolean enable) 接口开启视频流传输通道之前调用该方法，且必须使用同一种视频通道，即同为主流。

Par

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

Note

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

Par

参数说明

Par

示例代码

Code

//第一步 先关闭视频设备采集 NERtcSDK.getInstance().enableLocalVideo(false, NERtcConstants.NERtcVideoStreamType.kNERtcVideoStreamTypeMain); //第二步 设置为外部视频 NERtcSDK.getInstance().setExternalVideoSource(true); //第三步 打开视频通道 NERtcSDK.getInstance().enableLocalVideo(true, NERtcConstants.NERtcVideoStreamType.kNERtcVideoStreamTypeMain); //第四步 推送视频帧 NERtcVideoFrame videoFrame = new NERtcVideoFrame(); videoFrame.format = NERtcVideoFrame.Format.I420; //视频数据空间格式 videoFrame.data = mBuffer.array(); //视频数据 videoFrame.width = mWidth; videoFrame.height = mHeight; videoFrame.rotation = mRotation; NERtcSDK.getInstance().pushExternalVideoFrame(videoFrame);

Endcode

Par

相关接口

• 该方法调用成功后可以调用 () 方法推送视频数据帧。
• 若您希望通过辅流通道输入外部输入视频源，可以调用 (NERtcVideoStreamType streamType, boolean enable) 方法。

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

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

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

Par

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

Note

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

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

Note

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

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

Note

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

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

Note

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

设置本地语音混响效果。

Note

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

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

设置事件通知回调。
通过本接口可以实现根据自身业务场景，监听相应的主回调。

设置音视频通话的相关参数。
此接口提供技术预览或特别定制功能，详情请咨询技术支持。

Par

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

Par

参数说明

Par

示例代码

Code

let param: object = new Object(); param[NERtcConstants.NERtcParameterKey.kNERtcKeyStartVideoWithBackCamera] = true; NERtcSDK.getInstance().setParameters(param);

Endcode

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

设置播放远端混音前的音频数据格式。
通过本接口可以实现设置 NERtcAudioFrameObserver#onUserPlaybackSubStreamFrameBeforeMixing 回调的音频格式。

设置是否静音音频播放设备。

Par

调用时机 请在初始化后调用该方法，且该方法仅可在加入房间后调用。
此接口仅静音播放的音频数据，不影响播放设备的运行。

注册解码前媒体数据观测器。
通过此接口可以设置 NERtcPredecodeObserver#onFrame() 回调监听，返回相关解码前媒体数据。
note: 请在引擎初始化之后调用此接口，且该方法在加入房间前后均可调用。
适用于需要自行处理音、视频数据的解码与渲染的场景。
目前仅支持传输 OPUS 格式的音频数据和 H.264 格式的视频数据。

设置是否静音音频采集设备。

Par

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

Par

业务场景
适用于麦克风采集和伴音同时开启时，只发送伴音音频的场景。

Sample

//静音设备<
NERtcSDK.getInstance().setRecordDeviceMute(true);
//解除设备静音
NERtcSDK.getInstance().setRecordDeviceMute(false);
Copy

Par

相关接口

• NERtc#enableLocalAudio：开启或关闭本地音频采集和发送。
• NERtc#enableMediaPub：开启或关闭本地媒体流（主流）的发送；适用于单独开启麦克风但不发送音频的场景，比如会议场景、大房间。
• NERtc#muteLocalAudioStream：开启或关闭本地音频主流的发送；适用于需要频繁静音\取消静音操作的场景。
• NERtc#adjustRecordingSignalVolume：调节采集信号音量；适用于需要精确调整本地音频采集（包括外部输入）音量的场景，比如 KTV、语聊房。

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

设置弱网条件下订阅的音视频流回退选项。 弱网环境下，订阅的音视频质量会下降。调用该接口并将 option 设置为 NERtcConstants.StreamFallbackOption#VIDEO_STREAM_LOW 或者 NERtcConstants.StreamFallbackOption#AUDIO_ONLY 后：

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

Note

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

设置是否由扬声器播放声音。
通过本接口可以实现设置是否将语音路由到扬声器，即设备外放。

Par

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

Note

若设备连接了耳机或蓝牙，则无法开启外放。

Sample