NERTC iOS SDK V5.6.40
载入中...
搜索中...
未找到
实例方法 | 所有成员列表
<INERtcEngineEx>协议 参考

#include <INERtcEngineEx.h>

类 <INERtcEngineEx> 继承关系图:
<INERtcEngine> NERtcEngine

实例方法

(int) - enableDualStreamMode:
 
(int) - setLocalMediaPriority:preemptive:
 
(int) - setLocalPublishFallbackOption:
 
(int) - setRemoteSubscribeFallbackOption:
 
(int) - muteLocalAudio:
 
(int) - subscribeRemoteAudio:forUserID:
 
(int) - subscribeAllRemoteAudio:
 
(int) - setAudioSubscribeOnlyBy:
 
(int) - enableLocalSubStreamAudio:
 
(int) - subscribeRemoteSubStreamAudio:forUserID:
 
(int) - muteLocalSubStreamAudio:
 
(int) - setExternalSubStreamAudioSource:sampleRate:channels:
 
(int) - pushExternalSubStreamAudioFrame:
 
(int) - subscribeRemoteVideo:forUserID:streamType:
 
(int) - startPreview
 
(int) - startPreview:
 
(int) - stopPreview
 
(int) - stopPreview:
 
(int) - setLocalRenderScaleMode:
 
(int) - setLocalRenderScaleMode:streamType:
 
(int) - setRemoteRenderScaleMode:forUserID:
 
(int) - setRemoteRenderScaleMode:forUserID:streamType:
 
(int) - setVideoRotationMode:
 
(int) - muteLocalVideo:
 
(int) - muteLocalVideo:streamType:
 
(int) - setLoudspeakerMode:
 
(int) - getLoudspeakerMode:
 
(int) - startAudioDump
 
(int) - startAudioDumpWithType:
 
(int) - stopAudioDump
 
(int) - setRemoteHighPriorityAudioStream:forUserID:streamType:
 
(int) - switchCameraWithPosition:
 
(int) - updatePermissionKey:
 
(BOOL) - isFeatureSupportedWithType:
 
(NERtcFeatureSupportType) - getFeatureSupportedType:
 
(NERtcNetworkConnectionType) - getNetworkType
 
(int) - setExternalVideoSource:isScreen:
 
(int) - setExternalVideoSource:streamType:
 
(int) - pushExternalVideoFrame:
 
(int) - pushExternalVideoFrame:streamType:
 
(int) - setupLocalSubStreamVideoCanvas:
 
(int) - setupLocalVideoCanvas:streamType:
 
(int) - startScreenCapture:
 
(int) - stopScreenCapture
 
(int) - setLocalRenderSubStreamScaleMode:
 
(int) - setupRemoteSubStreamVideoCanvas:forUserID:
 
(int) - setupRemoteVideoCanvas:forUserID:streamType:
 
(int) - subscribeRemoteSubStreamVideo:forUserID:
 
(int) - subscribeRemoteVideo:forUserID:streamType:subscribeType:
 
(int) - setRemoteRenderSubStreamVideoScaleMode:forUserID:
 
(int) - setAudioSessionOperationRestriction:
 
(int) - setPlayoutDeviceMute:
 
(int) - getPlayoutDeviceMute:
 
(int) - setRecordDeviceMute:
 
(int) - getRecordDeviceMute:
 
(BOOL) - isCameraZoomSupported
 
(BOOL) - isCameraTorchSupported
 
(BOOL) - isCameraFocusSupported
 
(BOOL) - isCameraExposurePositionSupported
 
(int) - setCameraExposurePosition:
 
(int) - setCameraTorchOn:
 
(BOOL) - isCameraTorchOn
 
(int) - setCameraZoomFactor:
 
(float) - maxCameraZoomScale
 
(int) - setCameraFocusPositionX:Y:
 
(int) - setCameraCaptureConfig:
 
(int) - setCameraCaptureConfig:streamType:
 
(int) - startAudioMixingWithOption:
 
(int) - stopAudioMixing
 
(int) - pauseAudioMixing
 
(int) - resumeAudioMixing
 
(int) - setAudioMixingSendVolume:
 
(int) - getAudioMixingSendVolume:
 
(int) - setAudioMixingPlaybackVolume:
 
(int) - getAudioMixingPlaybackVolume:
 
(int) - getAudioMixingDuration:
 
(int) - getAudioMixingCurrentPosition:
 
(int) - setAudioMixingPosition:
 
(int) - setAudioMixingPitch:
 
(int) - getAudioMixingPitch:
 
(int) - playEffectWitdId:effectOption:
 
(int) - stopEffectWitdId:
 
(int) - stopAllEffects
 
(int) - pauseEffectWitdId:
 
(int) - resumeEffectWitdId:
 
(int) - pauseAllEffects
 
(int) - resumeAllEffects
 
(int) - setEffectSendVolumeWithId:volume:
 
(int) - getEffectSendVolumeWithId:volume:
 
(int) - setEffectPlaybackVolumeWithId:volume:
 
(int) - getEffectPlaybackVolumeWithId:volume:
 
(int) - getEffectDurationWithId:duration:
 
(int) - getEffectCurrentPositionWithId:position:
 
(int) - setEffectPositionWithId:position:
 
(int) - setEffectPitchWithId:pitch:
 
(int) - getEffectPitchWithId:pitch:
 
(int) - enableEarback:volume:
 
(int) - setEarbackVolume:
 
(int) - startAudioRecording:sampleRate:quality:
 
(int) - startAudioRecordingWithConfig:
 
(int) - stopAudioRecording
 
(int) - setExternalAudioSource:sampleRate:channels:
 
(int) - pushExternalAudioFrame:
 
(int) - setExternalAudioRender:sampleRate:channels:
 
(int) - pullExternalAudioFrame:length:
 
(int) - setRangeAudioMode:
 
(int) - setRangeAudioTeamID:
 
(int) - setAudioRecvRange:conversationalDistance:rollOff:
 
(int) - updateSelfPosition:
 
(int) - enableSpatializerRoomEffects:
 
(int) - setSpatializerRoomProperty:
 
(int) - setSpatializerRenderMode:
 
(int) - initSpatializer
 
(int) - enableSpatializer:applyToTeam:
 
(int) - setSubscribeAudioBlocklist:uidArray:
 
(int) - setSubscribeAudioAllowlist:
 
(int) - enableLocalData:
 
(int) - subscribeRemoteData:forUserID:
 
(int) - sendData:
 
(int) - addEngineMediaStatsObserver:
 
(int) - removeEngineMediaStatsObserver:
 
(int) - cleanupEngineMediaStatsObserver
 
(int) - addLiveStreamTask:compeltion:
 
(int) - updateLiveStreamTask:compeltion:
 
(int) - removeLiveStreamTask:compeltion:
 
(int) - setRecordingAudioFrameParameters:
 
(int) - setPlaybackAudioFrameParameters:
 
(int) - setMixedAudioFrameParameters:
 
(int) - setPlaybackBeforeMixingAudioFrameParameters:
 
(int) - setAudioFrameObserver:
 
(int) - setVideoFrameObserver:
 
(int) - enableAudioVolumeIndication:interval:
 
(int) - enableAudioVolumeIndication:interval:vad:
 
(int) - adjustRecordingSignalVolume:
 
(int) - adjustPlaybackSignalVolume:
 
(int) - adjustUserPlaybackSignalVolume:forUserID:
 
(int) - adjustChannelPlaybackSignalVolume:
 
(int) - setLocalVoicePitch:
 
(int) - setLocalVoiceEqualizationOfBandFrequency:withGain:
 
(int) - setVoiceBeautifierPreset:
 
(int) - setAudioEffectPreset:
 
(int) - setLocalVoiceReverbParam:
 
(int) - setLocalVideoWatermarkConfigs:withStreamType:
 
(int) - takeLocalSnapshot:callback:
 
(int) - takeRemoteSnapshot:forUserID:callback:
 
(int) - uploadSdkInfo
 
(int) - reportCustomEvent:customIdentify:param:
 
(int) - sendSEIMsg:streamChannelType:
 
(int) - sendSEIMsg:
 
(int) - startChannelMediaRelay:
 
(int) - updateChannelMediaRelay:
 
(int) - stopChannelMediaRelay
 
(int) - enableSuperResolution:
 
(int) - enableEncryption:config:
 
(int) - startLastmileProbeTest:
 
(int) - stopLastmileProbeTest
 
(nullable NERtcChannel *) - createChannel:
 
(int) - enableVideoCorrection:
 
(int) - setVideoCorrectionConfig:
 
(int) - enableVirtualBackground:backData:
 
(int) - enableVirtualBackground:backData:force:
 
(int) - setCloudProxy:
 
(void) - setStreamAlignmentProperty:
 
(int64_t) - getNtpTimeOffset
 
(int) - setPreDecodeObserver:
 
(int) - setVideoEncoderQosObserver:
 
(int) - pushExternalAudioEncodedFrame:
 
(int) - pushExternalSubStreamAudioEncodedFrame:
 
(int) - pushExternalVideoEncodedFrame:
 
(int) - pushExternalSubStreamVideoEncodedFrame:
 
(int) - startPushStreaming:
 
(int) - stopPushStreaming
 
- 实例方法 继承自 <INERtcEngine>
(NERtcConnectionStateType) - connectionState
 
(int) - setupEngineWithContext:
 
(int) - setEngineEventDelegate:
 
(int) - setDelegateQueue:
 
(int) - joinChannelWithToken:channelName:myUid:completion:
 
(int) - joinChannelWithToken:channelName:myUid:channelOptions:completion:
 
(int) - leaveChannel
 
(int) - switchChannelWithToken:channelName:completion:
 
(int) - switchChannelWithToken:channelName:channelOptions:completion:
 
(int) - enableLocalAudio:
 
(int) - enableLocalVideo:
 
(int) - enableLocalVideo:streamType:
 
(int) - enableMediaPub:withMediaType:
 
(int) - setChannelProfile:
 
(int) - setLocalVideoConfig:
 
(int) - setLocalVideoConfig:streamType:
 
(int) - setAudioProfile:scenario:
 
(int) - setAudioProfile:
 
(int) - setAudioScenario:
 
(int) - setupLocalVideoCanvas:
 
(int) - setupRemoteVideoCanvas:forUserID:
 
(int) - switchCamera
 
(int) - setClientRole:
 
(int) - setParameters:
 
(NSString *_Nullable) - getParameter:extraInfo:
 

额外继承的成员函数

- 属性 继承自 <INERtcEngine>
id< NERtcEngineDelegateEx > engineDelegate
 

详细描述

NERtcEngine 扩展接口

成员函数文档

◆ addEngineMediaStatsObserver:

- (int) addEngineMediaStatsObserver: (id< NERtcEngineMediaStatsObserver >) observer

注册媒体统计信息观测器。

参数
observer统计信息观测器。详细信息请参考 NERtcEngineMediaStatsObserver。
返回
操作返回值，成功则返回 0

◆ addLiveStreamTask:compeltion:

- (int) addLiveStreamTask: (NERtcLiveStreamTaskInfo *) taskInfo
compeltion: (NERtcLiveStreamCompletion) completion 

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

自从
V3.5.0
使用前提
请先通过 INERtcEngine#setChannelProfile: 接口设置房间模式为直播模式。
调用时机
请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。
注解
  • 仅角色为主播的房间成员能调用此接口，观众成员无相关推流权限。
  • 同一个音视频房间（即同一个 channelId）可以创建 6 个不同的推流任务。
参数说明
参数名称 类型 描述
taskInfo NERtcLiveStreamTaskInfo * 推流任务信息。详细信息请参考 {@ NERtcLiveStreamTaskInfo}。
compeltion NERtcLiveStreamCompletion 操作结果回调，方法调用成功后会触发对应的 NERtcEngineLiveStreamObserver#onNERTCEngineLiveStreamState:taskID:url: 回调。
示例代码
NERtcLiveStreamTaskInfo *info = [[NERtcLiveStreamTaskInfo alloc] init];
//info 的具体参数参考 NERtcLiveStreamTaskInfo 的定义
[[NERtcEngine sharedEngine] addLiveStreamTask:info compeltion:^(NSString * _Nonnull taskId, kNERtcLiveStreamError errorCode){
}];
NERtcEngine
定义 NERtcEngine.h:15
NERtcLiveStreamTaskInfo
定义 NERtcEngineBase.h:1308
相关回调
调用此接口成功后会触发 NERtcEngineLiveStreamObserver#onNERTCEngineLiveStreamState:taskID:url: 回调，通知推流任务状态已更新。
返回
  • 0（kNERtcNoError）：方法调用成功；
  • 其他：方法调用失败。
    • 403（kNERtcErrChannelReservePermissionDenied）：权限不足，观众模式下不支持此操作。
    • 30003（kNERtcErrInvalidParam）： 参数错误。
    • 30005（kNERtcErrInvalidState）：状态错误，比如引擎尚未初始化。

◆ adjustChannelPlaybackSignalVolume:

- (int) adjustChannelPlaybackSignalVolume: (uint32_t) volume

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

自从
V4.6.50
调用时机
请在引擎初始化之后调用此接口，该方法可在加入房间前后调用。
注解
  • 该方法设置内部引擎为启用状态，在 leaveChannel 后失效，但在本次通话过程中有效
参数说明
参数名称 类型 描述
volume uint64_t 播放音量，取值范围为 [0,400]。
  • 0：静音。
  • 100：原始音量。
  • 400：最大可为原始音量的 4 倍（自带溢出保护）。
示例代码
//调整该房间内的的用户在本地的播放音量为 50
[[NERtcEngine sharedEngine] adjustChannelPlaybackSignalVolume:50];
//调整该房间内的用户在本地的播放音量为 0，静音该房间
[[NERtcEngine sharedEngine] adjustChannelPlaybackSignalVolume:0];
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：状态错误，比如引擎未初始化。

◆ adjustPlaybackSignalVolume:

- (int) adjustPlaybackSignalVolume: (uint32_t) volume

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

自从
V3.5.0
调用时机
请在引擎初始化之后调用此接口，且该方法在加入房间前后均可调用。
注解
建议设置本地播放音量时使用默认值（100）或小于该值，否则可能会导致音质问题。
参数说明
参数名称 类型 描述
volume uint32_t 播放音量，取值范围为 [0,400]。
  • 0：静音。
  • 100：原始音量。
  • 400：最大可为原始音量的 4 倍（自带溢出保护）。
示例代码
 * //调整所有远端用户在本地的播放音量为 50
[[NERtcEngine sharedEngine] adjustPlaybackSignalVolume:50];
//调整所有远端用户在本地的播放音量为 0，静音所有用户
[[NERtcEngine sharedEngine] adjustPlaybackSignalVolume:0];
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：状态错误，比如引擎未初始化。

◆ adjustRecordingSignalVolume:

- (int) adjustRecordingSignalVolume: (uint32_t) volume

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

自从
V3.5.0
调用时机
请在引擎初始化之后调用此接口，且该方法在加入房间前后均可调用。
注解
  • 该方法设置内部引擎为启用状态，在 leaveChannel 后设置失效，将恢复至默认。
  • 建议设置本地采集音量为默认值（100）或小于该值，否则可能会导致音质问题。
  • 该方法仅设置应用程序中的采集信号音量，不修改设备音量，也不会影响伴音、音效等的音量；若您需要修改设备音量，请调用设备管理相关接口。
参数说明
参数名称 类型 描述
volume uint32_t 采集信号音量，取值范围为 0 ~ 400。
  • 0：静音。
  • 100（默认）：原始音量。
  • 400：最大音量值（自带溢出保护）。
示例代码
//将采集音量设置为 100
[[NERtcEngine sharedEngine] adjustRecordingSignalVolume:100];
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。

◆ adjustUserPlaybackSignalVolume:forUserID:

- (int) adjustUserPlaybackSignalVolume: (uint32_t) volume
forUserID: (uint64_t) userID 

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

自从
V4.2.1
调用时机
请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。
注解
  • 该方法设置内部引擎为启用状态，在 leaveChannel 后失效，但在本次通话过程中有效，比如指定远端用户中途退出房间，则再次加入此房间时仍旧维持该设置。
  • 该方法每次只能调整一位远端用户的播放音量，若需调整多位远端用户在本地播放的音量，则需多次调用该方法。
参数说明
参数名称 类型 描述
userID uint64_t 远端用户 ID。
volume uint64_t 播放音量，取值范围为 0 ~ 400。
  • 0：静音。
  • 100（默认）：原始音量。
  • 400：最大音量值（自带溢出保护）。
示例代码
//调整 uid 为 12345 的用户在本地的播放音量为 50
[[NERtcEngine sharedEngine] adjustUserPlaybackSignalVolume:50 forUserID:12345];
//调整 uid 为 12345 的用户在本地的播放音量为 0，静音该用户
[[NERtcEngine sharedEngine] adjustUserPlaybackSignalVolume:0 forUserID:12345];
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：状态错误，比如引擎未初始化。

◆ cleanupEngineMediaStatsObserver

- (int) cleanupEngineMediaStatsObserver

清除全部媒体统计信息观测器。

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

◆ createChannel:

- (nullable NERtcChannel *) createChannel: (NSString *) channelName

创建一个 IRtcChannel 对象

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

◆ enableAudioVolumeIndication:interval:

- (int) enableAudioVolumeIndication: (BOOL) enable
interval: (uint64_t) interval 

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

自从
V3.5.0
调用时机
请在引擎初始化之后调用此接口，且该方法在加入房间前后均可调用。
业务场景
适用于通过发言者的人声相关信息做出 UI 上的音量展示的场景，或根据发言者的音量大小进行视图布局的动态调整。
注解
该方法在 leaveChannel 后设置失效，将恢复至默认。如果您离开房间后重新加入房间，需要重新调用本接口。
参数说明
参数名称 类型 描述
enable BOOL 是否启用说话者音量提示：
  • YES：启用说话者音量提示。
  • NO：关闭说话者音量提示。
interval uint64_t 指定音量提示的时间间隔。单位为毫秒。必须设置为 100 毫秒的整数倍值，建议设置为 200 毫秒以上。
示例代码
//设置间隔为 500ms 的人声音量提示
[[NERtcEngine sharedEngine] enableAudioVolumeIndication:YES interval:500];
相关回调
启用该方法后，只要房间内有发流用户，无论是否有人说话，SDK 都会在加入房间后根据预设的时间间隔触发 NERtcEngineDelegateEx#onRemoteAudioVolumeIndication:totalVolume: 回调。
相关接口
若您希望在返回音量相关信息的同时检测是否有真实人声存在，请调用 INERtcEngineEx#enableAudioVolumeIndication:interval:vad: 方法。
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30003（kNERtcErrInvalidParam）：参数错误，比如时间间隔小于 100ms。

◆ enableAudioVolumeIndication:interval:vad:

- (int) enableAudioVolumeIndication: (BOOL) enable
interval: (uint64_t) interval
vad: (BOOL) enableVad 

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

自从
V4.6.10
调用时机
请在引擎初始化之后调用此接口，且该方法在加入房间前后均可调用。
业务场景
适用于通过发言者的人声相关信息做出 UI 上的音量展示的场景，或根据发言者的音量大小进行视图布局的动态调整。
注解
  • 该方法设置内部引擎为启用状态，该方法在 leaveChannel 后设置失效，将恢复至默认。如果您离开房间后重新加入房间，需要重新调用本接口。
  • 建议设置本地采集音量为默认值（100）或小于该值，否则可能会导致音质问题。
  • 该方法仅设置应用程序中的采集信号音量，不修改设备音量，也不会影响伴音、音效等的音量；若您需要修改设备音量，请调用设备管理相关接口。
参数说明
参数名称 类型 描述
enable BOOL 是否启用说话者音量提示：
  • YES：启用说话者音量提示。
  • NO：关闭说话者音量提示。
interval uint64_t 指定音量提示的时间间隔。单位为毫秒。必须设置为 100 毫秒的整数倍值，建议设置为 200 毫秒以上。
enableVad BOOL 是否启用本地采集人声监测：
  • YES：启用本地采集人声监测。
  • NO：关闭本地采集人声监测。
示例代码
//设置间隔为 500ms 的人声音量提示
[[NERtcEngine sharedEngine] enableAudioVolumeIndication:YES interval:500 enableVad:YES];
相关回调
启用该方法后，只要房间内有发流用户，无论是否有人说话，SDK 都会在加入房间后根据预设的时间间隔触发 NERtcEngineDelegateEx#onRemoteAudioVolumeIndication:totalVolume: 回调。
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30003（kNERtcErrInvalidParam）：参数错误，比如时间间隔小于 100ms。

◆ enableDualStreamMode:

- (int) enableDualStreamMode: (BOOL) enable

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

自从
V3.5.0
调用时机

请在初始化后调用该方法，且该方法在加入房间前后均可调用。
注解
  • 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
  • 该方法只对摄像头数据生效，对自定义输入、屏幕共享等视频流无效。
  • 该接口的设置会在摄像头重启后生效。
参数说明
参数名称 类型 描述
enable BOOL 是否开启双流模式：
  • YES：开启双流模式。
  • NO：关闭双流模式。
示例代码
[[NERtcEngine sharedEngine] enableDualStreamMode:YES];
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30004（kNERtcErrNotSupported）：不支持的操作，比如当前使用的是纯音频 SDK。
    • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎尚未初始化。

◆ enableEarback:volume:

- (int) enableEarback: (BOOL) enabled
volume: (uint32_t) volume 

设置是否开启耳返功能。

自从
V3.5.0
调用时机
请在初始化后调用该方法，且该方法仅可在加入房间后调用。
注解
  • 加入房间后，耳返功能可以随时开启，但只有当插入耳机或耳麦时，耳返功能才会生效；当拔出耳机或耳麦时会自动暂停，再次插入耳机或耳麦自动恢复，且耳返功能可以实时关闭。
  • 若您使用的是 V4.0.0 版本的 SDK，请注意此版本该方法的 volume 参数无效，请调用 INERtcEngineEx#setEarbackVolume: 接口设置耳返音量。
参数说明
参数名称 类型 描述
enabled BOOL 是否开启耳返功能：
  • YES：开启耳返。
  • NO：关闭耳返。
volume uint32_t 设置耳返音量。取值范围为 0 ~ 100，默认值为 100。
示例代码
//开启耳返并设置耳返音量为 100
示例代码
[[NERtcEngine sharedEngine] enableEarback:YES volume:100];
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30003（kNERtcErrInvalidParam）：参数错误。
    • 30005（kNERtcErrInvalidState)：当前状态不支持的操作，比如引擎尚未初始化。

◆ enableEncryption:config:

- (int) enableEncryption: (BOOL) enable
config: (NERtcEncryptionConfig *) config 

开启或关闭媒体流加密。

自从
V4.4.0 在金融行业等安全性要求较高的场景下，您可以在加入房间前通过此方法设置媒体流加密模式。
注解
  • 请在加入房间前调用该方法，加入房间后无法修改加密模式与密钥。用户离开房间后，SDK 会自动关闭加密。如需重新开启加密，需要在用户再次加入房间前调用此方法。
  • 同一房间内，所有开启媒体流加密的用户必须使用相同的加密模式和密钥，否则使用不同密钥的成员加入房间时会报错 kNERtcErrEncryptNotSuitable（30113）。
  • 安全起见，建议每次启用媒体流加密时都更换新的密钥。
参数
enable是否开启媒体流加密。
  • YES: 开启
  • NO:（默认）关闭
config媒体流加密方案。详细信息请参考 NERtcEncryptionConfig。
返回
0 方法调用成功，其他调用失败

◆ enableLocalData:

- (int) enableLocalData: (BOOL) enabled

开启或关闭本地数据通道。

注解
  • 该方法加入房间后才可调用。
  • 成功启用或禁用本地数据通道后，远端会触发 onNERtcEngineUserDataDidStop 或 onNERtcEngineUserDataDidStart 回调。
参数
[in]enabled是否启用本地数据通道:
  • true: 开启本地数据通道；
  • false: 关闭本地数据通道。
自从
V5.0.0
返回
  • 0: 方法调用成功；
  • 其他: 方法调用失败。

◆ enableLocalSubStreamAudio:

- (int) enableLocalSubStreamAudio: (BOOL) enabled

开启或关闭音频辅流。
开启时远端会收到 NERtcChannelDelegate#onNERtcChannelUserSubStreamAudioDidStart: 回调，关闭时远端会收到 NERtcChannelDelegate#onNERtcChannelUserSubStreamAudioDidStop: 回调。

自从
V4.6.10
参数
enabled是否开启音频辅流。
  • YES：开启音频辅流。
  • NO：关闭音频辅流。
返回
  • 0 ：方法调用成功。
  • 其他：方法调用失败。

◆ enableSpatializer:applyToTeam:

- (int) enableSpatializer: (BOOL) enabled
applyToTeam: (BOOL) applyToTeam 

开启或关闭空间音效

自从
V5.4.0
调用时机
请在引擎初始化后调用此接口，且该方法在加入房间前才可调用。
注解
  • 开启空间音效后，通话结束时仍保留该开关状态，不重置。
  • 请先调用 initSpatializer 接口初始化空间音效算法，再调用本接口。
参数
enabled是否打开 3D 音效算法功能，默认为关闭状态。
apply_to_team是否仅本小队开启 3D 音效。true: 仅仅和接收端同一个小队的人有 3D 音效；false: 接收到所有的语音都有 3d 音效
  • YES：: 开启空间音效
  • NO: 关闭空间音效
返回
  • 0: 方法调用成功
  • 其他: 调用失败

◆ enableSpatializerRoomEffects:

- (int) enableSpatializerRoomEffects: (BOOL) enabled

开启或关闭空间音效的房间混响效果

自从
V5.4.0
调用时机
请在引擎初始化后调用此接口，且该方法在加入房间前后均可调用。
注解
请先调用 enableSpatializer:applyToTeam: 接口后，再调用本接口。
参数
enabled混响效果开关，默认值关闭
返回
  • 0: 方法调用成功
  • 其他: 调用失败

◆ enableSuperResolution:

- (int) enableSuperResolution: (BOOL) enabled

启用或停止 AI 超分。

自从
V4.4.0
注解
  • 使用 AI 超分功能之前，请 提交工单 联系网易云信技术支持工程师开通 AI 超分功能。
  • AI 超分仅对以下类型的视频流有效：
  • 必须为本端接收到第一路 360P 的视频流。
  • 必须为摄像头采集到的主流大流视频。AI 超分功能暂不支持复原重建小流和屏幕共享辅流。
参数
enabled是否启用 AI 超分。默认为关闭状态。
返回
0 方法调用成功，其他调用失败

◆ enableVideoCorrection:

- (int) enableVideoCorrection: (BOOL) enable

是否启用视频图像畸变矫正。

自从
V4.6.0
注解
  • 当使用相机去拍摄物体时，存在着一个从三维世界到二维图像的映射过程，这个过程中由于相机位置的变化和移动，会对拍摄物体的成像产生一定的形变影响。
  • 开启该功能时，根据合适的参数，可以通过算法把这个形变进行复原。
  • 使用该功能时，本地画布的渲染模式需要为 fit（即视频帧保持自身比例不变全部显示在当前视图中），否则矫正功能可能不会正常生效。
  • 矫正参数生效后，本地画面和对端看到的画面，均会是矫正以后的画面。
参数
enable是否开启视频图像矫正。
  • true：开启视频图像矫正。
  • false（默认）：关闭视频图像矫正。
返回
  • 0：方法调用成功。
  • 其他：方法调用失败。

◆ enableVirtualBackground:backData:

- (int) enableVirtualBackground: (BOOL) enable
backData: (NERtcVirtualBackgroundSource *_Nullable) backData 

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

注解
  • 您可以通过 NERtcEngineDelegateEx#onNERtcEngineVirtualBackgroundSourceEnabled:reason: 回调查看虚拟背景是否开启成功或出错原因。
  • 建议您在满足以下条件的场景中使用该功能：
    • 采用高清摄像设备，环境光线均匀。
    • 捕获的视频图像整洁，用户肖像半长且基本无遮挡，并且背景是与用户衣服颜色不同的单一颜色。
  • 虚拟背景功能不支持在 Texture 格式的视频或通过 Push 方法从自定义视频源获取的视频中设置虚拟背景。
  • 若您设置背景图片为自定义本地图片，SDK 会在保证背景图片内容不变形的前提下，对图片进行一定程度上的缩放和裁剪，以适配视频采集分辨率。
自从
V4.6.10
参数
enable设置是否开启虚拟背景。
  • true：开启。
  • false: 关闭。
backData自定义背景图片。详细信息请参考 NERtcVirtualBackgroundSource。
返回
  • 0：方法调用成功。
  • 其他：方法调用失败。

◆ enableVirtualBackground:backData:force:

- (int) enableVirtualBackground: (BOOL) enable
backData: (NERtcVirtualBackgroundSource *_Nullable) backData
force: (BOOL) force 

开启或关闭虚拟背景。

  • 启用虚拟背景功能后，您可以使用自定义图片替换本地用户的原始背景图片。
  • 替换后，频道内所有用户都可以看到该自定义图片。
    注解
  • 如需查看是否成功开启虚拟背景，或获取出错原因，请通过 NERtcEngineDelegateEx#onNERtcEngineVirtualBackgroundSourceEnabled:reason: 回调实现。
    • 建议您在满足以下条件的场景中使用该功能：
      • 采用高清摄像的设备，环境中的光线均匀。
      • 捕获的视频图像整洁，用户肖像半长且基本无遮挡，并且背景是与用户衣服颜色不同的其他纯色。
    • Texture 格式的视频，或通过 Push 方法从自定义视频源获取的视频，不支持设置虚拟背景。
    • 若您设置了自定义的背景图片，NERTC SDK 在保证背景图片内容不变形的前提下，会一定程度上缩放或调整图片，以适配视频采集分辨率。
      自从
      V5.6.30
      参数
      enable设置是否开启虚拟背景。
  • true：开启。
  • false: 关闭。
    参数
    backData自定义背景图片。详细信息请参考 NERtcVirtualBackgroundSource。
    force为 YES 时，低性能的设备，也支持强制开启虚拟背景。
    返回
  • 0：方法调用成功。
  • 其他：方法调用失败。

◆ getAudioMixingCurrentPosition:

- (int) getAudioMixingCurrentPosition: (uint64_t *) position

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

参数
position音乐文件的播放位置，单位为毫秒。
返回
操作返回值，成功则返回 0

◆ getAudioMixingDuration:

- (int) getAudioMixingDuration: (uint64_t *) duration

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

参数
duration伴奏时长，单位为毫秒。
返回
操作返回值，成功则返回 0

◆ getAudioMixingPitch:

- (int) getAudioMixingPitch: (int32_t *) pitch

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

自从
V4.6.29
使用前提
请先调用 INERtcEngineEx#startAudioMixingWithOption: 方法开启伴音。
调用时机
请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。
示例代码
int32_t pitch = 0;
[[NERtcEngine sharedEngine] getAudioMixingPitch:&pitch];
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：引擎尚未初始化。
    • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如找不到对应的伴音任务。

◆ getAudioMixingPlaybackVolume:

- (int) getAudioMixingPlaybackVolume: (uint32_t *) volume

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

参数
volume伴奏播放音量。范围为 0~200。
返回
操作返回值，成功则返回 0

◆ getAudioMixingSendVolume:

- (int) getAudioMixingSendVolume: (uint32_t *) volume

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

参数
volume伴奏发送音量。
返回
操作返回值，成功则返回 0

◆ getEffectCurrentPositionWithId:position:

- (int) getEffectCurrentPositionWithId: (uint32_t) effectId
position: (uint64_t *) position 

获取音效的播放进度。

自从
V4.4.0 该方法获取当前音效播放进度，单位为毫秒。
注解
请在房间中调用该方法。
参数
[in]effectId音效 ID。
[out]position音效文件的播放位置，单位为毫秒。
返回
操作返回值，成功则返回 0

◆ getEffectDurationWithId:duration:

- (int) getEffectDurationWithId: (uint32_t) effectId
duration: (uint64_t *) duration 

获取音效文件时长。

自从
V4.4.0 该方法获取音效文件时长，单位为毫秒。
注解
请在房间内调用该方法。
参数
[in]effectId音效 ID。
[out]duration音效文件时长，单位为毫秒。
返回
操作返回值，成功则返回 0

◆ getEffectPitchWithId:pitch:

- (int) getEffectPitchWithId: (uint32_t) effectId
pitch: (int32_t *) pitch 

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

自从
V4.6.29
使用前提
请先调用 INERtcEngineEx#playEffectWitdId:effectOption: 方法播放音效。
调用时机
请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。
参数说明
参数名称 类型 描述
effectId uint32_t 指定音效文件的 ID。每个音效文件均对应唯一的 ID。

示例代码
uint32_t effectId;
int32_t pitch = 0;
[[NERtcEngine sharedEngine] getEffectPitchWithId:effectId pitch:&pitch];
相关接口
可以调用 INERtcEngineEx#getEffectPitchWithId:pitch: 方法获取指定音效文件的音调。
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：引擎尚未初始化。
    • 30003（kNERtcErrInvalidParam）：参数错误，比如 effectId 错误，没有对应的音效任务。

◆ getEffectPlaybackVolumeWithId:volume:

- (int) getEffectPlaybackVolumeWithId: (uint32_t) effectId
volume: (uint32_t *) volume 

获取音效的回放音量

参数
effectId音效 ID。
volume返回的音量值
返回
操作返回值，成功则返回 0

◆ getEffectSendVolumeWithId:volume:

- (int) getEffectSendVolumeWithId: (uint32_t) effectId
volume: (uint32_t *) volume 

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

参数
effectId指定音效的 ID。每个音效均有唯一的 ID。
volume返回的发送音量。
返回
操作返回值，成功则返回 0

◆ getFeatureSupportedType:

- (NERtcFeatureSupportType) getFeatureSupportedType: (NERtcFeatureType) featureType

查询当前设备支持的 NERtc SDK 的某项功能的级别。

自从
v5.6.30
业务场景
以虚拟背景为例，在用户跳转 UI 至直播之前，您可调用此接口查询设备支持虚拟背景的级别。
  • kNERtcFeatureSupportFull: 设备支持虚拟背景功能，可直接打开虚拟背景。
  • kNERtcFeatureSupportHardwareLimit: 由于设备硬件或系统原因，设备不支持虚拟背景功能。
  • kNERtcFeatureSupportPerformanceLimit: 由于设备性能不足，不支持虚拟背景功能，但可以强制开启。例如，低性能设备通过设置 getFeatureSupportedType 接口的 force 为 YES 强制开启虚拟背景功能。
调用时机
请在初始化引擎之后，调用此接口。
返回
  • 0：接口执行成功
  • 其他：接口执行失败

◆ getLoudspeakerMode:

- (int) getLoudspeakerMode: (bool *) enabled

检查扬声器状态启用状态。

注解
该方法可在加入房间前后调用。
参数
enabled是否正在使用扬声器模式。
返回
操作返回值，成功则返回 0

◆ getNetworkType

- (NERtcNetworkConnectionType) getNetworkType

获取本地网络连接类型。

自从
v5.6.40
调用时机
请在初始化引擎之后，调用此接口。
返回
NERtcNetworkConnectionType 网络类型

◆ getNtpTimeOffset

- (int64_t) getNtpTimeOffset

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

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

◆ getPlayoutDeviceMute:

- (int) getPlayoutDeviceMute: (bool *) muted

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

参数
muted是否静音。
返回
操作返回值，成功则返回 0

◆ getRecordDeviceMute:

- (int) getRecordDeviceMute: (bool *) muted

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

参数
muted是否静音。
返回
操作返回值，成功则返回 0

◆ initSpatializer

- (int) initSpatializer

初始化引擎 3D 音效算法

自从
V5.5.10
调用时机
请在引擎初始化后调用此接口，此接口在加入房间前后均可调用。
返回
  • 0: 方法调用成功
  • 其他: 调用失败

◆ isCameraExposurePositionSupported

- (BOOL) isCameraExposurePositionSupported

检测设备是否支持手动曝光功能。

注解
  • 该方法需要在相机启动后调用，例如调用 startPreview 或 joinChannel 后。
  • 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
返回
YES 表示支持，NO 表示不支持。

◆ isCameraFocusSupported

- (BOOL) isCameraFocusSupported

检测设备是否支持手动对焦功能。

注解
  • 该方法需要在相机启动后调用，例如调用 startPreview 或 joinChannel 后。
  • 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
返回
YES 表示支持，NO 表示不支持。

◆ isCameraTorchOn

- (BOOL) isCameraTorchOn

查询设备是否开启了闪光灯。

注解
纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
返回
YES 表示开启；NO 表示关闭。

◆ isCameraTorchSupported

- (BOOL) isCameraTorchSupported

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

注解
  • 一般情况下，App 默认开启前置摄像头，因此如果设备前置摄像头不支持闪光灯，直接使用该方法会返回 NO。如果需要检查后置摄像头是否支持闪光灯，需要先使用 switchCamera 切换摄像头，再使用该方法。
  • 该方法需要在相机启动后调用，例如调用 startPreview 或 joinChannel 后。
  • 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
返回
YES 表示支持，NO 表示不支持。

◆ isCameraZoomSupported

- (BOOL) isCameraZoomSupported

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

注解
纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
返回
YES 表示支持，NO 表示支持。

◆ isFeatureSupportedWithType:

- (BOOL) isFeatureSupportedWithType: (NERtcFeatureType) featureType

查询当前设备是否支持 SDK 中的某项功能

自从
v5.5.21
业务场景
以虚拟背景为例，在用户跳转 UI 至直播之前，可调用此接口来判断当前设备是否支持虚拟背景功能，如果不支持，则隐藏相关的按钮。
调用时机
请在引擎初始化之后调用此接口。
参数说明
参数名称 类型 描述
featureType NERtcFeatureType RTC 功能类型。
示例代码
NERtcFeatureType featureType = kNERtcFeatureTypeVirtualBackground;
BOOL supported = [[NERtcEngine sharedEngine] isFeatureSupportedWithType:featureType];
if (supported) {
// 该设备支持
} else {
// 该设备不支持
}
相关回调
无
返回
YES: 表示支持 NO: 表示不支持

◆ maxCameraZoomScale

- (float) maxCameraZoomScale

获取摄像头支持最大缩放比例。

注解
  • 该方法需要在相机启动后调用，例如调用 startPreview 或 joinChannel 后。
  • 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
返回
最大缩放比例。

◆ muteLocalAudio:

- (int) muteLocalAudio: (BOOL) muted

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

自从
V3.5.0
调用时机
请在引擎初始化之后调用此接口，且该方法在加入房间前后均可调用。
参数说明
参数名称 类型 描述
mute BOOL 是否关闭本地音频的发送：
  • YES：不发送本地音频。
  • NO：发送本地音频。
示例代码
//不发送本地音频
[[NERtcEngine sharedEngine] muteLocalAudio:YES];
//发送本地音频
[[NERtcEngine sharedEngine] muteLocalAudio:NO];
相关回调
若本地用户在说话，成功调用该方法后，房间内其他用户会收到 NERtcEngineDelegateEx#onNERtcEngineUser:audioMuted: 回调。
相关接口
INERtcChannel#enableMediaPub:withMediaType:：
  • 在需要开启本地音频采集（监测本地用户音量）但不发送音频流的情况下，您也可以调用 enableMeidaPub(NO) 方法。
  • 两者的差异在于， muteLocalAudio(YES) 仍然保持与服务器的音频通道连接，而 enableMediaPub(NO) 表示断开此通道，因此若您的实际业务场景为多人并发的大房间，建议您调用 enableMediaPub 方法。
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：引擎未初始化。

◆ muteLocalSubStreamAudio:

- (int) muteLocalSubStreamAudio: (BOOL) muted

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

注解
静音状态会在通话结束后被重置为非静音。
自从
V4.6.10
参数
muted是否静音本地音频辅流发送。
  • YES（默认）：静音本地音频辅流。
  • NO：取消静音本地音频辅流。
返回
  • 0：方法调用成功。
  • 其他：方法调用失败。

◆ muteLocalVideo:

- (int) muteLocalVideo: (BOOL) muted

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

自从
V3.5.0
使用前提
一般在通过 INERtcEngine#enableLocalVideo:streamType: 接口开启本地视频采集并发送后调用该方法。
调用时机

请在初始化后调用该方法，且该方法在加入房间前后均可调用。
注解
  • 调用该方法取消发布本地视频流时，设备仍然处于工作状态。
  • 该方法设置内部引擎为启用状态，在 INERtcEngine#leaveChannel 后设置失效，将恢复至默认，即默认发布本地视频流。
  • 该方法与 INERtcEngine#enableLocalVideo:streamType:(NO) 的区别在于，后者会关闭本地摄像头设备，该方法不禁用摄像头，不会影响本地视频流采集且响应速度更快。
参数说明
参数名称 类型 描述
muted BOOL 是否取消发布本地视频流：
  • YES：取消发布本地视频流。
  • NO（默认）：恢复发布本地视频流。
示例代码
[[NERtcEngine sharedEngine] muteLocalVideo:YES];
相关回调
取消发布本地视频主流或辅流后，远端会收到 NERtcEngineDelegateEx#onNERtcEngineUser:videoMuted:streamType: 回调。
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：状态错误，比如引擎尚未初始化。
    • 30004（kNERtcErrNotSupported）：不支持的操作，比如当前使用的是纯音频 SDK。

◆ muteLocalVideo:streamType:

- (int) muteLocalVideo: (BOOL) muted
streamType: (NERtcStreamChannelType) streamType 

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

自从
V4.6.20
使用前提
一般在通过 INERtcEngine#enableLocalVideo:streamType: 接口开启本地视频采集并发送后调用该方法。
调用时机

请在初始化后调用该方法，且该方法在加入房间前后均可调用。
注解
  • 调用该方法取消发布本地视频流时，设备仍然处于工作状态。
  • 若调用该方法取消发布本地视频流，通话结束后会被重置为默认状态，即默认发布本地视频流。
  • 该方法与 INERtcEngine#enableLocalVideo:streamType:(NO) 的区别在于，后者会关闭本地摄像头设备，该方法不禁用摄像头，不会影响本地视频流采集且响应速度更快。
参数说明
参数名称 类型 描述
streamType NERtcStreamChannelType 视频通道类型：
  • kNERtcStreamChannelTypeMainStream：主流。
  • kNERtcStreamChannelTypeSubStream：辅流。
muted BOOL 是否取消发布本地视频流：
  • YES：取消发布本地视频流。
  • NO（默认）：恢复发布本地视频流。
示例代码
//取消发布本地视频主流
[[NERtcEngine sharedEngine] muteLocalVideo:YES streamType:kNERtcStreamChannelTypeMainStream];
//恢复发布本地视频主流
[[NERtcEngine sharedEngine] muteLocalVideo:NO streamType:kNERtcStreamChannelTypeMainStream];
//取消发布本地视频辅流
[[NERtcEngine sharedEngine] muteLocalVideo:YES streamType:kNERtcStreamChannelTypeSubStream];
//恢复发布本地视频辅流
[[NERtcEngine sharedEngine] muteLocalVideo:NO streamType:kNERtcStreamChannelTypeSubStream];
相关回调
取消发布本地视频主流或辅流后，远端会收到 NERtcEngineDelegateEx#onNERtcEngineUser:videoMuted:streamType: 回调。
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30004（kNERtcErrNotSupported）：不支持的操作，比如当前使用的是纯音频 SDK。

◆ pauseAllEffects

- (int) pauseAllEffects

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

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

◆ pauseAudioMixing

- (int) pauseAudioMixing

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

自从
V3.5.0
使用前提
请先调用 INERtcEngineEx#startAudioMixingWithOption: 开启伴音。
调用时机

请在初始化后调用该方法，且该方法仅可在加入房间后调用。
示例代码
[[NERtcEngine sharedEngine] pauseAudioMixing]
相关接口
可以继续调用 INERtcEngineEx#resumeAudioMixing 方法恢复播放伴音文件。
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。

◆ pauseEffectWitdId:

- (int) pauseEffectWitdId: (uint32_t) effectId

暂停播放指定音效文件。
请在加入房间后调用该方法。

参数
effectId音效 ID。
返回
操作返回值，成功则返回 0

◆ playEffectWitdId:effectOption:

- (int) playEffectWitdId: (uint32_t) effectId
effectOption: (NERtcCreateAudioEffectOption *) option 

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

自从
V3.5.0
调用时机
请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。
注解
支持的音效文件类型包括 MP3、M4A、AAC、3GP、WMA 和 WAV 格式，支持本地文件和在线 URL。 您可以多次调用该方法，通过传入不同音效文件的 effectId 和 option，同时播放多个音效文件，实现音效叠加；但是为获得最佳用户体验，建议同时播放不超过 3 个音效文件。 若通过此接口成功播放某指定音效文件后，反复停止或重新播放该 effectId 对应的音效文件，仅首次播放时设置的 option 有效，后续的 option 设置无效。
参数说明
参数名称 类型 描述
effectId uint32_t 指定音效的 ID。每个音效均应有唯一的 ID。
option NERtcCreateAudioEffectOption * 音效相关参数，包括混音任务类型、混音文件路径等。详细信息请参考 NERtcCreateAudioEffectOption。
示例代码
//播放音效文件 1 taskId 需要自己管理
uint32_t taskId1 = 1;
NERtcCreateAudioEffectOption *option = [[NERtcCreateAudioEffectOption alloc] init];
option.path = @"your effect file path 1";
option.loopCount = 1;
[[NERtcEngine sharedEngine] playEffectWitdId:taskId1 effectOption:option];
//播放音效文件 2 taskId 需要自己管理
uint32_t taskId2 = 2;
NERtcCreateAudioEffectOption *option = [[NERtcCreateAudioEffectOption alloc] init];
option.path = @"your effect file path 2";
option.loopCount = 1;
[[NERtcEngine sharedEngine] playEffectWitdId:taskId2 effectOption:option];
NERtcCreateAudioEffectOption
Options for creating audio effects
定义 NERtcEngineBase.h:806
NERtcCreateAudioEffectOption::loopCount
int loopCount
定义 NERtcEngineBase.h:833
NERtcCreateAudioEffectOption::path
NSString * path
定义 NERtcEngineBase.h:819
相关接口
NERtcEngineDelegateEx#onAudioEffectTimestampUpdateWithId:timeStampMS:：本地音效文件播放进度回调。 NERtcEngineDelegateEx#onAudioEffectFinished:：本地音效文件播放已结束回调。
返回
  • 0（kNERtcNoError）：方法调用成功；
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：状态错误，比如引擎尚未初始化。

◆ pullExternalAudioFrame:length:

- (int) pullExternalAudioFrame: (void *_Nonnull) data
length: (int) len 

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

注解
  • 该方法需要在加入房间后调用。
  • 数据帧时长建议匹配 10ms 周期。
  • 该方法在音频渲染设备关闭后不再生效，此时会返回空数据。例如通话结束、通话前扬声器设备测试关闭等情况下，该设置不再生效。
参数
data数据指针。
len待拉取音频数据的字节数，单位为 byte。建议音频数据的时长至少为 10 毫秒，数据长度不能超过 7680 字节。
计算公式为： len = sampleRate/1000 × 2 × channels × 音频数据时长（毫秒）。
返回
操作返回值，成功则返回 0

◆ pushExternalAudioEncodedFrame:

- (int) pushExternalAudioEncodedFrame: (NERtcAudioEncodedFrame *) encodedAudioFrame

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

◆ pushExternalAudioFrame:

- (int) pushExternalAudioFrame: (NERtcAudioFrame *) frame

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

注解
  • 该方法需要在加入房间后调用。
  • 数据帧时长建议匹配 10ms 周期。
  • 该方法在音频输入设备关闭后不再生效。例如关闭本地音频、通话结束、通话前麦克风设备测试关闭等情况下，该设置不再生效。
参数
frame外部音频帧数据；数据长度不能超过 7680 字节，和调用周期时长一致。
返回
  • 0: 方法调用成功；
  • 其他: 方法调用失败。

◆ pushExternalSubStreamAudioEncodedFrame:

- (int) pushExternalSubStreamAudioEncodedFrame: (NERtcAudioEncodedFrame *) encodedAudioFrame

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

  • 通过此接口可以实现通过辅流音频通道推送外部音频编码后的数据。
    自从
    V4.6.29
    使用前提
    该方法仅在设置 INERtcEngineEx#setExternalSubStreamAudioSource:sampleRate:channels: 接口的 enabled 参数为 YES 后调用有效。
    调用时机
    请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。
    业务场景
    适用于需要自行处理音频数据的采集与编码的场景。
    注解
  • 目前仅支持传输 OPUS 格式的音频数据。
  • 建议不要同时调用 INERtcEngineEx#pushExternalSubStreamAudioFrame: 方法。
  • 该方法在音频输入设备关闭后，例如在关闭本地音频、通话结束、通话前麦克风设备测试关闭等情况下，设置会恢复至默认。
    参数说明
    参数名称 类型 描述
    encodedAudioFrame NERtcAudioEncodedFrame * 编码后的音频帧数据。

    示例代码
    NERtcAudioEncodedFrame *subAudioFrame = [[NERtcAudioEncodedFrame alloc] init];
    subAudioFrame.sampleRate = 采样率
    subAudioFrame.channels = 声道数
    subAudioFrame.samplesPerChannel = 每个声道的样本数
    subAudioFrame.payloadType = 数据类型，参考枚举 NERtcPayLoadType
    subAudioFrame.timeStampUs = 时间戳
    subAudioFrame.encodedTimestamp = 编码时间戳
    [[NERtcEngine sharedEngine] pushExternalSubStreamAudioEncodedFrame:subAudioFrame];
    返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：未开启外部音频输入。
    • 30003（kNERtcErrInvalidParam）：参数错误，比如传入对象为空。
    • 30005（kNERtcErrInvalidState）：状态错误，比如引擎尚未初始化。

◆ pushExternalSubStreamAudioFrame:

- (int) pushExternalSubStreamAudioFrame: (NERtcAudioFrame *) frame

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

注解
  • 该方法需要在加入房间后调用。
  • 数据帧时长建议匹配 10ms 周期。
  • 该方法在音频辅流关闭后不再生效。
自从
V4.6.10
参数
frame音频帧数据。
返回
  • 0: 方法调用成功。
  • 其他: 方法调用失败。

◆ pushExternalSubStreamVideoEncodedFrame:

- (int) pushExternalSubStreamVideoEncodedFrame: (NERtcVideoEncodedFrame *) encodedVideoFrame

推送外部视频编码帧。

◆ pushExternalVideoEncodedFrame:

- (int) pushExternalVideoEncodedFrame: (NERtcVideoEncodedFrame *) encodedVideoFrame

推送外部视频编码帧。

  • 通过此接口可以实现通过主流视频通道推送外部视频编码后的数据。
    自从
    V4.6.29
    使用前提
    该方法仅在设置 INERtcEngineEx#setExternalVideoSource:streamType: 接口的 enable 参数为 YES 后调用有效。
    调用时机
    请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。
    业务场景
    适用于需要自行处理视频数据的采集与编码的场景。
    注解
  • 目前仅支持传输 H.264 格式的视频数据。
  • 该方法设置内部引擎为启用状态，在 INERtcEngine#leaveChannel 后设置会重置为默认状态。
  • 建议先调用 INERtcEngineEx#enableDualStreamMode: 方法关闭视频大小流功能，否则远端可能无法正常接收下行流。
  • 建议不要同时调用 INERtcEngineEx#pushExternalVideoFrame: 方法。
  • 外部视频源数据的输入通道、本地视频采集通道与外部视频编码帧数据的推送通道必须同为主流或者辅流通道，否则 SDK 会报错。
  • 暂不支持同时开启视频主、辅流通道推送外部视频编码帧数据。
    参数说明
    参数名称 类型 描述
    encodedVideoFrame NERtcVideoEncodedFrame * 编码后的视频帧数据。

    示例代码
    NERtcVideoEncodedFrame *frame = [[NERtcVideoEncodedFrame alloc] init];
    frame.frameType = 帧类型;
    frame.width = 视频宽;
    frame.height = 视频高;
    frame.codecType = 视频编码类型;
    frame.timestampUs = 时间戳;
    frame.nalData = 帧数据;
    frame.nalLengths = lengthArray;
    [[NERtcEngine sharedEngine] pushExternalVideoEncodedFrame:frame];
    相关接口
    可以调用 INERtcEngineEx#setVideoEncoderQosObserver: 接口设置视频编码 QoS 信息监听器，通过回调的数据信息调整编码策略。
    返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：未开启视频。
    • 30003（kNERtcErrInvalidParam）：参数错误，比如传入对象为空。
    • 30005（kNERtcErrInvalidState）：状态错误，比如引擎未初始化或未开启外部视频输入。

◆ pushExternalVideoFrame:

- (int) pushExternalVideoFrame: (NERtcVideoFrame *) frame
弃用
此方法已废弃，请使用方法 INERtcEngineEx#pushExternalVideoFrame:streamType: 代替。 推送外部视频帧。
该方法主动将视频帧数据用 NERtcVideoFrame 类封装后传递给 SDK。
注解
  • 该方法设置内部引擎为启用状态，在 leaveChannel 后不再有效。
  • 请确保在您调用本方法前已调用 setExternalVideoSource，并将参数设为 YES，否则调用本方法后会一直报错。
  • 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
参数
frame外部视频帧的数据信息。详细信息请参考 NERtcVideoFrame。
返回
  • 0：方法调用成功；
  • 其他：方法调用失败。

◆ pushExternalVideoFrame:streamType:

- (int) pushExternalVideoFrame: (NERtcVideoFrame *) frame
streamType: (NERtcStreamChannelType) streamType 

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

注解
  • 该方法设置内部引擎为启用状态，在 leaveChannel 后不再有效。
  • 请确保在您调用本方法前已调用 setExternalVideoSource，并将参数设为 YES，否则调用本方法后会一直报错。
  • 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
参数
frame外部视频帧的数据信息。详细信息请参考 NERtcVideoFrame。
streamType视频流通道类型，默认为主流 kNERtcStreamChannelTypeMainStream。
返回
  • 0：方法调用成功；
  • 其他：方法调用失败。

◆ removeEngineMediaStatsObserver:

- (int) removeEngineMediaStatsObserver: (id< NERtcEngineMediaStatsObserver >) observer

移除指定媒体统计信息观测器。

参数
observer统计信息观测器
返回
操作返回值，成功则返回 0

◆ removeLiveStreamTask:compeltion:

- (int) removeLiveStreamTask: (NSString *) taskId
compeltion: (NERtcLiveStreamCompletion) completion 

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

自从
V3.5.0
使用前提
请先调用 INERtcEngineEx#addLiveStreamTask:compeltion: 方法添加推流任务。
调用时机
请在引擎初始化之后调用此接口，该方法在加入房间前后均可调用。
注解
  • 仅角色为主播的房间成员能调用此接口，观众成员无相关推流权限。
  • 通话结束，房间成员全部离开房间后，推流任务会自动删除；如果房间内还有用户存在，则需要创建推流任务的用户删除推流任务。
参数说明
参数名称 类型 描述
taskId NSString * 推流任务 ID。
completion NERtcLiveStreamCompletion 操作结果回调，方法调用成功后会触发对应的 NERtcEngineLiveStreamObserver#onNERTCEngineLiveStreamState:taskID:url: 回调。
示例代码
[[NERtcEngine sharedEngine] removeLiveStreamTask:task_id compeltion:^(NSString * _Nonnull taskId, kNERtcLiveStreamError errorCode){
}];
相关回调
调用此接口成功后会触发 NERtcEngineLiveStreamObserver#onNERTCEngineLiveStreamState:taskID:url: 回调，通知推流任务已删除。
返回
  • 0（kNERtcNoError）：方法调用成功；
  • 其他：方法调用失败。
    • 403（kNERtcErrChannelReservePermissionDenied）：权限不足，观众模式下不支持此操作。
    • 30003（kNERtcErrInvalidParam）： 参数错误。
    • 30005（kNERtcErrInvalidState）：状态错误，比如引擎尚未初始化。

◆ reportCustomEvent:customIdentify:param:

- (int) reportCustomEvent: (NSString *) eventName
customIdentify: (NSString *) customIdentify
param: (NSDictionary *) param 

上报自定义事件

参数
eventName事件名 不能为空
customIdentify自定义标识，比如产品或业务类型，如不需要填 null
param参数键值对，参数值支持 String 及 java 基本类型(int 、bool....)， 如不需要填 null
返回
操作返回值，成功则返回 0

◆ resumeAllEffects

- (int) resumeAllEffects

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

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

◆ resumeAudioMixing

- (int) resumeAudioMixing

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

自从
V3.5.0
使用前提
请先调用 INERtcEngineEx#startAudioMixingWithOption: 开启伴音。
调用时机

请在初始化后调用该方法，且该方法仅可在加入房间后调用。
示例代码
[[NERtcEngine sharedEngine] resumeAudioMixing];
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：引擎尚未初始化。
    • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎尚未初始化或当前未在播放伴音。

◆ resumeEffectWitdId:

- (int) resumeEffectWitdId: (uint32_t) effectId

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

参数
effectId指定音效的 ID。每个音效均有唯一的 ID。
返回
操作返回值，成功则返回 0

◆ sendData:

- (int) sendData: (NSData *) data

通过数据通道发送数据。

参数
[in]data自定义数据。
自从
V5.0.0
返回
  • 0: 方法调用成功。
  • 其他: 方法调用失败。

◆ sendSEIMsg:

- (int) sendSEIMsg: (NSData *) data

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

  • 调用时机：视频流（主流、辅流）开启后，可调用此函数。
  • 数据长度限制： SEI 最大数据长度为 4096 字节，超限会发送失败。如果频繁发送大量数据会导致视频码率增大，可能会导致视频画质下降甚至卡顿。
  • 发送频率限制：最高为视频发送的帧率，建议不超过 10 次/秒。
  • 生效时间：调用本接口之后，最快在下一帧视频数据帧之后发送 SEI 数据，最慢在接下来的 5 帧视频之后发送。
    注解
  • SEI 数据跟随视频帧发送，由于在弱网环境下可能丢帧，SEI 数据也可能随之丢失，所以建议在发送频率限制之内多次发送，保证接收端收到的概率。
  • 调用本接口时，默认使用主流通道发送 SEI。
  • 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
    参数
    data自定义 SEI 数据。
    返回
    操作返回值，成功则返回 0
  • 成功: 成功进入待发送队列，会在最近的视频帧之后发送该数据
  • 失败: 数据被限制发送，可能发送的频率太高，队列已经满了，或者数据大小超过最大值 4k

◆ sendSEIMsg:streamChannelType:

- (int) sendSEIMsg: (NSData *) data
streamChannelType: (NERtcStreamChannelType) type 

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

  • 调用时机：视频流（主流、辅流）开启后，可调用此函数。
  • 数据长度限制： SEI 最大数据长度为 4096 字节，超限会发送失败。如果频繁发送大量数据会导致视频码率增大，可能会导致视频画质下降甚至卡顿。
  • 发送频率限制：最高为视频发送的帧率，建议不超过 10 次/秒。
  • 生效时间：调用本接口之后，最快在下一帧视频数据帧之后发送 SEI 数据，最慢在接下来的 5 帧视频之后发送。
    注解
  • SEI 数据跟随视频帧发送，由于在弱网环境下可能丢帧，SEI 数据也可能随之丢失，所以建议在发送频率限制之内多次发送，保证接收端收到的概率。
  • 指定通道发送 SEI 之前，需要提前开启对应的数据流通道。
  • 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
    参数
    data自定义 SEI 数据。
    type发送 SEI 时，使用的流通道类型。详细信息请参考 NERtcStreamChannelType。
    返回
    操作返回值，成功则返回 0
  • 成功: 成功进入待发送队列，会在最近的视频帧之后发送该数据。
  • 失败: 数据被限制发送，可能发送的频率太高，队列已经满了，或者数据大小超过最大值 4k。

◆ setAudioEffectPreset:

- (int) setAudioEffectPreset: (NERtcVoiceChangerType) type

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

自从
V4.1.0
调用时机
请在引擎初始化之后调用此接口，且该方法在加入房间前后均可调用。
注解
参数说明
参数名称 类型 描述
type NERtcVoiceChangerType 预设的变声音效。默认关闭变声音效。
示例代码
[[NERtcEngine sharedEngine] setAudioEffectPreset:kNERtcVoiceChangerRobot];
返回
  • 0（kNERtcNoError）：方法调用成功；
  • 其他：方法调用失败。
    • 30003（kNERtcErrInvalidParam）：参数错误，比如设置的音效无效。

◆ setAudioFrameObserver:

- (int) setAudioFrameObserver: (nullable id< NERtcEngineAudioFrameObserver >) observer

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

自从
V3.5.0
调用时机
请在引擎初始化之后调用此接口，且该方法仅可在加入房间前调用。
参数说明
参数名称 类型 描述
observer NERtcEngineAudioFrameObserver 接口对象实例。如果传入参数为 NULL，取消注册，同时会清理 NERtcAudioFrameRequestFormat 的相关设置。
示例代码
//开启监听 pcm 数据回调
[[NERtcEngine sharedEngine] setAudioFrameObserver:self];
相关回调
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30005（kNERtcErrInvalidState）：状态错误，比如已经加入房间。

◆ setAudioMixingPitch:

- (int) setAudioMixingPitch: (int32_t) pitch

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

  • 通过此接口可以实现当本地人声和播放的音乐文件混音时，仅调节音乐文件的音调。
    自从
    V4.6.29
    使用前提
    请先调用 INERtcEngineEx#startAudioMixingWithOption: 方法开启伴音。
    调用时机
    请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。
    业务场景
    适用于 K 歌中为了匹配人声，调节背景音乐音高的场景。
    注解
    当前伴音任务结束后，此接口的设置会恢复至默认。
    参数说明
    参数名称 类型 描述
    pitch int32_t 当前伴音文件的音调。默认值为 0，即不调整音调，取值范围为 -12 ~ 12，按半音音阶调整。每相邻两个值的音高距离相差半音；取值的绝对值越大，音调升高或降低得越多。

    示例代码
    int32_t pitch = 5;
    [[NERtcEngine sharedEngine] setAudioMixingPitch:pitch];
    相关接口
    可以调用 INERtcEngineEx#getAudioMixingPitch: 方法获取伴音文件的音调。
    返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：引擎尚未初始化。
    • 30003（kNERtcErrInvalidParam）：参数错误，比如 pitch 超出范围。
    • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如找不到对应的伴音任务。

◆ setAudioMixingPlaybackVolume:

- (int) setAudioMixingPlaybackVolume: (uint32_t) volume

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

参数
volume伴奏播放音量。取值范围为 0~200。默认 100，即原始文件音量。
返回
操作返回值，成功则返回 0

◆ setAudioMixingPosition:

- (int) setAudioMixingPosition: (uint64_t) position

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

参数
position音乐文件的播放位置，单位为毫秒。
返回
操作返回值，成功则返回 0

◆ setAudioMixingSendVolume:

- (int) setAudioMixingSendVolume: (uint32_t) volume

设置伴奏的发送音量。

参数
volume伴奏发送音量。取值范围为 0~200。默认 100，即原始文件音量。
返回
操作返回值，成功则返回 0

◆ setAudioRecvRange:conversationalDistance:rollOff:

- (int) setAudioRecvRange: (int) audibleDistance
conversationalDistance: (int) conversationalDistance
rollOff: (NERtcDistanceRolloffModel) rollOff 

设置空间音效的距离衰减属性和语音范围。

自从
V5.5.10
调用时机
请在引擎初始化后调用此接口，且该方法在加入房间前后均可调用。
注解
  • 若要使用范围语音或空间音效功能，加入房间前需要调用一次本接口。
  • 仅使用范围语音时，只需要设置 audibleDistance 参数，其他参数设置不生效，填写默认值即可。
参数
audibleDistance监听器能够听到扬声器并接收其语音的距离扬声器的最大距离。距离有效范围：[1,max int)，无默认值。
conversationalDistance范围语音场景中，该参数设置的值不起作用，保持默认值即可。空间音效场景中，需要配置该参数。 控制音频保持其原始音量的范围，超出该范围时，语音聊天的响度在被听到时开始淡出。 默认值为 1。
rollOff范围语音场景中，该参数设置的值不起作用，保持默认值即可。空间音效场景中，需要配置该参数。 距离衰减模式，具体请参考 NERtcDistanceRolloffModel，默认值为 kNERtcDistanceRolloffNone。
返回
  • 0: 方法调用成功
  • 其他: 调用失败

◆ setAudioSessionOperationRestriction:

- (int) setAudioSessionOperationRestriction: (NERtcAudioSessionOperationRestriction) restriction

设置 SDK 对 Audio Session 的控制权限。
该方法仅适用于 iOS 平台。
该方法限制 SDK 对 Audio Session 的操作权限。在默认情况下，SDK 和 App 对 Audio Session 都有控制权，但某些场景下，App 会希望限制 SDK 对 Audio Session 的控制权限，而使用其他应用或第三方组件对 Audio Session 进行操控。调用该方法可以实现该功能。
该接口只能在入会之前调用。

注解
一旦调用该方法限制了 SDK 对 Audio Session 的控制权限， SDK 将无法对 Audio Session 进行相关设置，而需要用户自己或第三方组件进行维护。
参数
restrictionSDK 对 Audio Session 的控制权限。详细信息请参考 NERtcAudioSessionOperationRestriction。
返回
操作返回值，成功则返回 0

◆ setAudioSubscribeOnlyBy:

- (int) setAudioSubscribeOnlyBy: (NSArray< NSNumber * > *) uidArray

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

注解
  • 此接口需要在加入房间成功后调用。
  • 对于调用接口时不在房间的 uid 不生效。
自从
V4.6.10
参数
uidArray可订阅自己音频的用户 uid 列表。
注解
此列表为全量列表。如果列表为空或 null，表示其他所有人均可订阅自己的音频。
返回
  • 0：方法调用成功。
  • 其他：方法调用失败。

◆ setCameraCaptureConfig:

- (int) setCameraCaptureConfig: (NERtcCameraCaptureConfiguration *) config

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

自从
V4.5.0
调用时机

请在初始化后调用该方法，且该方法在加入房间前后均可调用。
业务场景
在视频通话或直播中，SDK 自动控制摄像头的输出参数。默认情况下，SDK 会根据用户该接口的配置匹配最合适的分辨率进行采集。但是在部分业务场景中，如果采集画面质量无法满足实际需求，可以调用该接口调整摄像头的采集配置。
注解
  • 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
  • 该方法仅适用于视频主流，若您希望为辅流通道设置摄像头的采集配置，请调用 INERtcEngineEx#setCameraCaptureConfig:streamType: 方法。
  • 该方法支持在加入房间后动态调用，设置成功后，会自动重启摄像头采集模块。
  • 若系统相机不支持您设置的分辨率，会自动调整为最相近一档的分辨率，因此建议您设置为常规标准的分辨率。
  • 设置较高的采集分辨率会增加性能消耗，例如 CPU 和内存占用等，尤其是在开启视频前处理的场景下。
参数说明
参数名称 类型 描述
config NERtcCameraCaptureConfiguration 本地摄像头采集配置。
示例代码
NERtcCameraCaptureConfiguration *config = [[NERtcCameraCaptureConfiguration alloc] init];
config.captureWidth = 1280;
config.captureHeight = 720;
[[NERtcEngine sharedEngine] setCameraCaptureConfig:config];
NERtcCameraCaptureConfiguration
定义 NERtcEngineBase.h:488
NERtcCameraCaptureConfiguration::captureWidth
int captureWidth
定义 NERtcEngineBase.h:509
NERtcCameraCaptureConfiguration::captureHeight
int captureHeight
定义 NERtcEngineBase.h:530
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30003（kNERtcErrInvalidParam）：参数错误，比如 config 设置为空。
    • 30004（kNERtcErrNotSupported）：不支持的操作，比如当前使用的是纯音频 SDK。
    • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎未初始化成功。

◆ setCameraCaptureConfig:streamType:

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

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

自从
V4.6.20
调用时机

请在初始化后调用该方法，且该方法在加入房间前后均可调用。
业务场景
在视频通话或直播中，SDK 自动控制摄像头的输出参数。默认情况下，SDK 会根据用户该接口的配置匹配最合适的分辨率进行采集。但是在部分业务场景中，如果采集画面质量无法满足实际需求，可以调用该接口调整摄像头的采集配置。
注解
调用该接口设置成功后，会自动重启摄像头采集模块。
参数说明
参数名称 类型 描述
config NERtcCameraCaptureConfiguration 本地摄像头采集配置。
streamType NERtcStreamChannelType 视频通道类型：
  • kNERtcStreamChannelTypeMainStream：主流。
  • kNERtcStreamChannelTypeSubStream：辅流。
示例代码
//设置本地摄像头主流采集配置
NERtcCameraCaptureConfiguration *capConfig = [[NERtcCameraCaptureConfiguration alloc] init];
capConfig.captureWidth = 1280;
capConfig.captureHeight = 720;
[[NERtcEngine sharedEngine] setCameraCaptureConfig:capConfig streamType:kNERtcStreamChannelTypeMainStream];
//设置本地摄像头辅流采集配置
NERtcCameraCaptureConfiguration *subCapConfig = [[NERtcCameraCaptureConfiguration alloc] init];
subCapConfig.captureWidth = 1280;
subCapConfig.captureHeight = 720;
[[NERtcEngine sharedEngine] setCameraCaptureConfig:subCapConfig streamType:kNERtcStreamChannelTypeSubStream];
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30003（kNERtcErrInvalidParam）：参数错误，比如 config 设置为空。
    • 30004（kNERtcErrNotSupported）：不支持的操作，比如当前使用的是纯音频 SDK。
    • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎未初始化成功。

◆ setCameraExposurePosition:

- (int) setCameraExposurePosition: (CGPoint) positionInView

设置摄像头的手动曝光位置。
通过此接口实现设置摄像头的手动曝光位置前，建议先通过 INERtcEngineEx#isCameraExposurePositionSupported 接口检测设备是否支持手动曝光功能。

自从
V3.5.0
使用前提
请在启用相机后调用此接口，例如调用 INERtcEngineEx#startPreview: 或 INERtcEngine#enableLocalVideo:streamType: 之后。
调用时机

请在引擎初始化之后调用此接口，且该方法在加入房间前后均可调用。
注解
纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
参数说明
参数名称 类型 描述
positionInView CGPoint 曝光位置点。
示例代码
CGPoint position = CGPointMake(0.5, 0.5);
[[NERtcEngine sharedEngine] setCameraExposurePosition:position];
相关回调
成功调用此方法后，本地会触发 NERtcEngineDelegateEx#onNERtcCameraExposureChanged: 回调。
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：引擎尚未初始化或未开启摄像头。
    • 30004（kNERtcErrNotSupported）：不支持的操作，比如当前使用的是纯音频 SDK。

◆ setCameraFocusPositionX:Y:

- (int) setCameraFocusPositionX: (float) focusX
Y: (float) focusY 

设置摄像头的手动曝光位置。
通过此接口实现设置摄像头的手动曝光位置前，建议先通过 INERtcEngineEx#isCameraFocusSupported 接口检测设备是否支持手动曝光功能。

自从
V3.5.0
使用前提
请在启用相机后调用此接口，例如调用 INERtcEngineEx#startPreview: 或 INERtcEngine#enableLocalVideo:streamType: 之后。
调用时机

请在引擎初始化之后调用此接口，且该方法在加入房间前后均可调用。
注解
纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
参数说明
参数名称 类型 描述
focusX float 触摸点相对于视图的横坐标，取值范围为 0 ~ 1。
focusY float 触摸点相对于视图的纵坐标，取值范围为 0 ~ 1。
示例代码
[[NERtcEngine sharedEngine] setCameraFocusPosition X:0.5 Y:0.5];
相关回调
成功调用此方法后，本地会触发 NERtcEngineDelegateEx#onNERtcCameraFocusChanged: 回调。
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：引擎尚未初始化或未开启摄像头。
    • 30004（kNERtcErrNotSupported）：不支持的操作，比如当前使用的是纯音频 SDK。

◆ setCameraTorchOn:

- (int) setCameraTorchOn: (BOOL) on

设置是否打开闪光灯。

注解
  • 该方法需要在相机启动后调用，例如调用 startPreview 或 joinChannel 后。
  • 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
参数
onYES 表示开启；NO 表示关闭。
返回
操作返回值，成功则返回 0

◆ setCameraZoomFactor:

- (int) setCameraZoomFactor: (float) factor

设置摄像头缩放比例。
通过此接口实现设置摄像头缩放比例前，建议先通过 INERtcEngineEx#maxCameraZoomScale 接口查看摄像头支持的最大缩放比例，并根据实际需求合理设置需要的缩放比例。

自从
V3.5.0
使用前提
请在启用相机后调用此接口，例如调用 INERtcEngineEx#startPreview: 或 INERtcEngine#enableLocalVideo:streamType: 之后。
调用时机

请在引擎初始化之后调用此接口，且该方法在加入房间前后均可调用。
注解
纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
参数说明
参数名称 类型 描述
factor float 摄像头缩放比例。
示例代码
float factor = 0.5;
[[NERtcEngine sharedEngine] setCameraZoomFactor:factor];
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：引擎尚未初始化或未开启摄像头。
    • 30004（kNERtcErrNotSupported）：不支持的操作，比如当前使用的是纯音频 SDK。

◆ setCloudProxy:

- (int) setCloudProxy: (NERtcTransportType) proxyType

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

  • 成功连接云代理后，SDK 会触发 onNERtcEngineConnectionStateChangeWithState(kNERtcConnectionStateConnecting, kNERtcReasonConnectionChangedSettingProxyServer) 回调。
  • 如果需要关闭已设置的云代理，请调用 setCloudProxy(NERtcTransportTypeNoneProxy)。
    注解
    请在加入房间前调用此方法。
    参数
    proxyType云代理类型。详细信息请参考 NERtcTransportType。该参数为必填参数，若未赋值，SDK 会报错。
    返回
    0 方法调用成功，其他失败。

◆ setEarbackVolume:

- (int) setEarbackVolume: (uint32_t) volume

设置耳返音量。

参数
volume设置耳返音量，可设置为 0~100，默认为 100。
返回
操作返回值，成功则返回 0

◆ setEffectPitchWithId:pitch:

- (int) setEffectPitchWithId: (uint32_t) effectId
pitch: (int32_t) pitch 

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

  • 通过此接口可以实现当本地人声和播放的音乐文件混音时，仅调节音乐文件的音调。
    自从
    V4.6.29
    使用前提
    请先调用 INERtcEngineEx#playEffectWitdId:effectOption: 方法播放音效。
    调用时机
    请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。
    业务场景
    适用于 K 歌中为了匹配人声，调节背景音乐音高的场景。
    注解
    当前音效任务结束后，此接口的设置会恢复至默认。
    参数说明
    参数名称 类型 描述
    effectId uint32_t 指定音效文件的 ID。每个音效文件均对应唯一的 ID。
    pitch int32_t 指定音效文件的音调。默认值为 0，即不调整音调，取值范围为 -12 ~ 12，按半音音阶调整。每相邻两个值的音高距离相差半音；取值的绝对值越大，音调升高或降低得越多。

    示例代码
    uint32_t effectId;
    int32_t pitch = 5;
    [[NERtcEngine sharedEngine] setEffectPitchWithId:effectId pitch:pitch];
    相关接口
    可以调用 INERtcEngineEx#getEffectPitchWithId:pitch: 方法获取指定音效文件的音调。
    返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：引擎尚未初始化。
    • 30003（kNERtcErrInvalidParam）：参数错误，比如 pitch 超出范围或者 effectId 错误，没有对应的音效任务。

◆ setEffectPlaybackVolumeWithId:volume:

- (int) setEffectPlaybackVolumeWithId: (uint32_t) effectId
volume: (uint32_t) volume 

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

参数
effectId指定音效的 ID。每个音效均有唯一的 ID。
volume音效播放音量。范围为 0~100，默认为 100。
返回
操作返回值，成功则返回 0

◆ setEffectPositionWithId:position:

- (int) setEffectPositionWithId: (uint32_t) effectId
position: (uint64_t) position 

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

  • 通过此接口可以实现根据实际情况播放音效文件，而非从头到尾播放整个文件。
    自从
    V4.6.29
    使用前提
    请先调用 INERtcEngineEx#playEffectWitdId:effectOption: 方法播放音效。
    调用时机
    请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。
    参数说明
    参数名称 类型 描述
    effectId uint32_t 指定音效文件的 ID。每个音效文件均对应唯一的 ID。
    position uint64_t 指定音效文件的起始播放位置。单位为毫秒。

    示例代码
    相关接口
  • INERtcEngineEx#getEffectCurrentPositionWithId:position:：获取指定音效文件的当前播放位置。
  • NERtcEngineDelegateEx#onAudioEffectTimestampUpdateWithId:timeStampMS:：注册此回调实时获取指定音效文件的当前播放进度，默认为每隔 1s 返回一次。
    返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：引擎尚未初始化。
    • 30003（kNERtcErrInvalidParam）：参数错误，比如 effectId 错误。

◆ setEffectSendVolumeWithId:volume:

- (int) setEffectSendVolumeWithId: (uint32_t) effectId
volume: (uint32_t) volume 

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

参数
effectId指定音效的 ID。每个音效均有唯一的 ID。
volume音效发送音量。范围为 0~100，默认为 100，表示原始音量。
返回
操作返回值，成功则返回 0

◆ setExternalAudioRender:sampleRate:channels:

- (int) setExternalAudioRender: (BOOL) enabled
sampleRate: (int32_t) sampleRate
channels: (int32_t) channels 

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

自从
V3.9.0
调用时机
请在引擎初始化之后调用此接口，且该方法仅可在加入房间前调用。
业务场景
适用于需要自行渲染音频的场景。
注解
  • 该方法设置内部引擎为启用状态，在 INERtcEngine#leaveChannel 后仍然有效；如果需要关闭该功能，需要在下次通话前调用此接口关闭外部音频数据渲染功能。
  • 成功调用此方法后，音频播放设备的选择和异常重启功能将失效， 且将用虚拟设备代替扬声器工作，因此扬声器的相关设置会无法生效，例如进行 loopback 检测时，需要由外部渲染播放。
  • 设置 enable 参数为 NO 关闭该功能时，其他参数可传入任意合法值，均不会生效。
参数说明
参数名称 类型 描述
enabled BOOL 是否开启外部音频渲染：
  • YES：开启外部音频渲染。
  • NO（默认）：关闭外部音频渲染。
sampleRate int32_t 外部音频渲染的采样率，单位为赫兹（Hz），可设置为 16000，32000，44100 或 48000。
channels int32_t 外部音频渲染的声道数，可设置为：
  • 1：单声道。
  • 2：双声道。
示例代码
//设置采样率为 16000 的双声道外部渲染
[[NERtcEngine sharedEngine] setExternalAudioRender:YES sampleRate:16000 channels:2];
相关接口
可以继续调用 INERtcEngineEx#pullExternalAudioFrame:length: 方法获取音频 PCM 数据，用以后续自行渲染并播放。
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如已经加入了房间。

◆ setExternalAudioSource:sampleRate:channels:

- (int) setExternalAudioSource: (BOOL) enabled
sampleRate: (int32_t) sampleRate
channels: (int32_t) channels 

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

自从
V3.9.0
使用前提
建议在通过 INERtcEngine#enableLocalAudio: 接口关闭本地音频采集之后调用该方法。
调用时机

请在初始化后调用该方法，且该方法在加入房间前后均可调用。
业务场景
实现由应用层而非 SDK 采集音频数据，比如在合唱过程中使用自定义的音乐文件。
注解
  • 调用该方法关闭外部音频输入时可以传入任意合法值，此时设置不会生效，例如 setExternalAudioSource(false, 0, 0)。
  • 该方法设置内部引擎为启用状态，在 INERtcEngine#leaveChannel 后仍然有效；如果需要关闭该功能，需要在下次通话前调用此接口关闭外部音频数据输入功能。
  • 成功调用此方法后，将用虚拟设备代替麦克风工作，因此麦克风的相关设置会无法生效，例如进行 loopback 检测时，会听到外部输入的音频数据。
参数说明
参数名称 类型 描述
enabled BOOL 是否开启外部音频输入：
  • YES：开启外部音频输入。
  • NO：关闭外部音频输入。
sampleRate int32_t 外部音频源的数据采样率，单位为 Hz。建议设置为 8000，16000，32000，44100 或 48000。
channels int32_t 外部音频源的数据声道数：
  • 1：单声道。
  • 2：双声道。
示例代码
[[[NTESDemoLogic sharedLogic] getCoreEngine] setExternalAudioSource:enabled sampleRate:sampleRate channels:channels];
相关接口
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：引擎尚未初始化。
    • 30003（kNERtcErrInvalidParam）：参数错误，比如声道数不是 1 或者 2，或者采样率设置有问题。

◆ setExternalSubStreamAudioSource:sampleRate:channels:

- (int) setExternalSubStreamAudioSource: (BOOL) enabled
sampleRate: (int32_t) sampleRate
channels: (int32_t) channels 

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

自从
V4.6.10
使用前提
建议在通过 INERtcEngine#enableLocalAudio: 接口关闭本地音频采集之后调用该方法。
调用时机

请在初始化后调用该方法，且该方法在加入房间前后均可调用。
业务场景
实现由应用层而非 SDK 采集音频数据，比如在合唱过程中使用自定义的音乐文件。
注解
  • 调用该方法关闭外部音频输入时可以传入任意合法值，此时设置不会生效，例如 setExternalAudioSource(false, 0, 0)。
  • 该方法设置内部引擎为启用状态，在 INERtcEngine#leaveChannel 后仍然有效；如果需要关闭该功能，需要在下次通话前调用此接口关闭外部音频数据输入功能。
  • 成功调用此方法后，将用虚拟设备代替麦克风工作，因此麦克风的相关设置会无法生效，例如进行 loopback 检测时，会听到外部输入的音频数据。
参数说明
参数名称 类型 描述
enabled BOOL 是否开启外部音频输入：
  • YES：开启外部音频输入。
  • NO：关闭外部音频输入。
sampleRate int32_t 外部音频源的数据采样率，单位为 Hz。建议设置为 8000，16000，32000，44100 或 48000。
channels int32_t 外部音频源的数据声道数：
  • 1：单声道。
  • 2：双声道。
示例代码
* @if Chinese
开启或关闭外部音频源数据输入。
<br>通过本接口可以实现创建自定义的外部音频源，并通过主流通道传输该外部音频源的数据。
@since V3.9.0
@par 使用前提
建议在通过 {@link INERtcEngine#enableLocalAudio:} 接口关闭本地音频采集之后调用该方法。
@par 调用时机
请在初始化后调用该方法，且该方法在加入房间前后均可调用。
@par 业务场景
实现由应用层而非 SDK 采集音频数据，比如在合唱过程中使用自定义的音乐文件。
@note
- 调用该方法关闭外部音频输入时可以传入任意合法值，此时设置不会生效，例如 setExternalAudioSource(false, 0, 0)。
- 该方法设置内部引擎为启用状态，在 {@link INERtcEngine#leaveChannel} 后仍然有效；如果需要关闭该功能，需要在下次通话前调用此接口关闭外部音频数据输入功能。
- 成功调用此方法后，将用虚拟设备代替麦克风工作，因此麦克风的相关设置会无法生效，例如进行 loopback 检测时，会听到外部输入的音频数据。
@par 参数说明
<table>
<tr>
<th>**参数名称**</th>
<th>**类型**</th>
<th>**描述**</th>
</tr>
<tr>
<td>enabled</td>
<td>BOOL</td>
<td>是否开启外部音频输入：<ul><li>YES：开启外部音频输入。<li>NO：关闭外部音频输入。</td>
</tr>
<tr>
<td>sampleRate</td>
<td>int32_t</td>
<td>外部音频源的数据采样率，单位为 Hz。建议设置为 8000，16000，32000，44100 或 48000。</td>
</tr>
<tr>
<td>channels</td>
<td>int32_t</td>
<td>外部音频源的数据声道数：<ul><li>1：单声道。<li>2：双声道。</td>
</tr>
</table>
@par 示例代码
@code
//开启外部辅流音频输入，并设置输入采样率为 48k 单声道
[[NERtcEngine sharedEngine] setExternalSubStreamAudioSource:YES sampleRate:48000 channels:1];
相关接口
该方法调用成功后可以调用 INERtcEngineEx#pushExternalSubStreamAudioFrame: 方法发送音频 PCM 数据。
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：引擎尚未初始化。
    • 30003（kNERtcErrInvalidParam）：参数错误，比如声道数不是 1 或者 2，或者采样率设置有问题。

◆ setExternalVideoSource:isScreen:

- (int) setExternalVideoSource: (BOOL) enable
isScreen: (BOOL) isScreen 
弃用
该方法已经废弃，请使用 INERtcEngineEx#setExternalVideoSource:streamType: 方法代替。注意，如果已经调了此方法，将会导致再 INERtcEngine#setExternalVideoSource:streamType: 方法失效。 开启或关闭外部视频源数据输入。
通过本接口可以实现创建自定义的外部视频源，并通过主流通道传输该外部视频源的数据。
自从
V3.5.0
使用前提
请在通过 INERtcEngine#enableLocalVideo:streamType: 接口关闭本地视频设备采集之后调用该方法。
调用时机

请在通过 INERtcEngineEx#startPreview: 接口开启本地视频预览、通过 INERtcEngine#enableLocalVideo:streamType: 接口开启本地视频采集或通过 INERtcEngineEx#startScreenCapture: 接口开启屏幕共享之前调用该方法，且必须使用同一种视频通道，即同为主流。
业务场景
实现由应用层而非 SDK 采集视频数据，适用于对输入的视频数据做水印、美颜、马赛克等前处理的场景。
注解
  • 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
  • 该方法设置内部引擎为启用状态，在 INERtcEngine#leaveChannel 后仍然有效；如果需要关闭该功能，需要在下次通话前调用此接口关闭外部视频数据输入功能。
  • 屏幕共享时，外部输入视频源默认使用辅流通道；非屏幕共享时，外部输入视频源使用主流通道。
参数说明
参数名称 类型 描述
enable BOOL 是否开启外部视频输入：
  • YES：开启外部视频输入。
  • NO：关闭外部视频输入。
isScreen BOOL 使用外部视频源时，外部视频源是否为屏幕共享数据：
  • YES：是屏幕共享数据。
  • NO：不是屏幕共享数据。
示例代码
BOOL useExternalVideoSource = YES;
BOOL isScreen = YES;
[[NERtcEngine sharedEngine] setExternalVideoSource:useExternalVideoSource isScreen:isScreen];
相关接口
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：不支持的操作，比如已开启了同视频通道的本地视频采集。
    • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎未初始化成功。

◆ setExternalVideoSource:streamType:

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

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

自从
V4.6.20
使用前提
请在通过 INERtcEngineEx#startPreview: 接口开启本地视频预览、通过 INERtcEngine#enableLocalVideo:streamType: 接口开启本地视频采集或通过 INERtcEngineEx#startScreenCapture: 接口开启屏幕共享之前调用该方法，且必须使用同一种视频通道，即同为主流或辅流。
调用时机
请在初始化后调用该方法，且该方法在加入房间前后均可调用。
业务场景
实现由应用层而非 SDK 采集视频数据，适用于对输入的视频数据做水印、美颜、马赛克等前处理的场景。
注解
  • 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
  • 当外部视频源输入作为主流或辅流时，内部引擎为启用状态，在切换房间（switchChannelWithToken）、主动离开房间（leaveChannel）、触发断网重连失败回调（onNERtcChannelDidDisconnectWithReason）或触发重新加入房间回调（onNERtcChannelRejoinChannel）后仍然有效。如果需要关闭该功能，请在下次通话前调用接口关闭该功能。
  • 请务必保证视频主流和辅流输入通道各最多只能有一种视频输入源，其中屏幕共享只能通过辅流通道开启，因此：
    • 若您开启了辅流形式的屏幕共享，请使用主流通道输入外部视频源数据，即设置 streamType 参数为 kNERtcStreamChannelTypeMainStream。
    • 若您已调用 INERtcEngine#enableLocalVideo:streamType: 方法开启本地主流视频采集，请勿再调用此接口创建主流形式的外部视频源输入，辅流通道同理。
  • 如果调用此方法之前调过废弃方法 INERtcEngineEx#setExternalVideoSource:isScreen: ，此方法会不生效。
参数说明
参数名称 类型 描述
streamType NERtcStreamChannelType 视频通道类型：
  • kNERtcStreamChannelTypeMainStream：主流。
  • kNERtcStreamChannelTypeSubStream：辅流。
enable BOOL 是否使用外部视频源：
  • YES：开启。
  • NO（默认）：关闭。
示例代码
//通过主流通道输入外部视频源数据
[NERtcEngine.sharedEngine setExternalVideoSource:YES streamType:kNERtcStreamChannelTypeMainStream];
[NERtcEngine.sharedEngine.enableLocalVideo:YES streamType:kNERtcStreamChannelTypeMainStream];
[NERtcEngine.sharedEngine pushExternalVideoFrame:frame];
//通过辅流通道输入外部视频源数据
[[NERtcEngine sharedEngine] setExternalVideoSource:YES streamType:kNERtcStreamChannelTypeSubStream];
NERtcVideoSubStreamEncodeConfiguration *config = [[NERtcVideoSubStreamEncodeConfiguration alloc] init];
config.maxProfile = kNERtcVideoProfileHD720P;
config.frameRate = kNERtcVideoFrameRateFps15;
[[NERtcEngine sharedEngine] startScreenCapture:config];
//屏幕共享视频帧回调，此方法来自屏幕共享的 framework NERtcReplayKit.framework
- (void)onReceiveVideoFrame:(NEScreenShareVideoFrame *)videoFrame
{
NERtcVideoFrame *frame = [[NERtcVideoFrame alloc] init];
frame.format = kNERtcVideoFormatI420;
frame.width = videoFrame.width;
frame.height = videoFrame.height;
frame.buffer = (void *)[videoFrame.videoData bytes];
frame.timestamp = videoFrame.timeStamp;
frame.rotation = rotation;
NERtcEngine.sharedEngine pushExternalVideoFrame:frame];
}
NERtcBaseVideoEncodeConfiguration::frameRate
NERtcVideoFrameRate frameRate
定义 NERtcEngineBase.h:392
NERtcBaseVideoEncodeConfiguration::maxProfile
NERtcVideoProfileType maxProfile
定义 NERtcEngineBase.h:374
+[NERtcEngine sharedEngine]
instancetype sharedEngine()
NERtcVideoFrame
定义 NERtcEngineBase.h:1609
NERtcVideoFrame::rotation
NERtcVideoRotationType rotation
定义 NERtcEngineBase.h:1659
NERtcVideoFrame::width
uint32_t width
定义 NERtcEngineBase.h:1639
NERtcVideoFrame::format
NERtcVideoFormatType format
定义 NERtcEngineBase.h:1619
NERtcVideoFrame::timestamp
uint64_t timestamp
定义 NERtcEngineBase.h:1629
NERtcVideoFrame::buffer
void * buffer
定义 NERtcEngineBase.h:1673
NERtcVideoFrame::height
uint32_t height
定义 NERtcEngineBase.h:1649
NERtcVideoSubStreamEncodeConfiguration
定义 NERtcEngineBase.h:648
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：通用错误，比如已通过主流通道开启本地视频采集，又创建了主流通道的外部视频源。
    • 30004（kNERtcErrNotSupported）：不支持的操作，比如当前使用的是纯音频 SDK。

◆ setLocalMediaPriority:preemptive:

- (int) setLocalMediaPriority: (NERtcMediaPriorityType) priority
preemptive: (BOOL) preemptive 

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

自从
V4.2.0
调用时机
请在引擎初始化之后调用此接口，且该方法仅可在加入房间前调用。
注解
  • 一个音视频房间中只有一个高优先级的用户。建议房间中只有一位用户调用 setLocalMediaPriority 将本端媒体流设为高优先级，否则需要开启抢占模式，保证本地用户的高优先级设置生效。
  • 调用 INERtcEngine#switchChannelWithToken:channelName:channelOptions:completion: 方法快速切换房间后，媒体优先级会恢复为默认值，即普通优先级。
参数说明
参数名称 类型 描述
priority NERtcMediaPriorityType 本地用户的媒体流优先级，默认为 kNERtcMediaPriorityNormal，即普通优先级。
preemptive BOOL 是否开启抢占模式：
  • YES：开启抢占模式。抢占模式开启时，本地用户可以抢占其他用户的高优先级，被抢占的用户的媒体优先级变为普通优先级，在抢占者退出房间后，其他用户的优先级仍旧维持普通优先级。
  • NO：关闭抢占模式。抢占模式关闭时，如果房间中已有高优先级用户，则本地用户的高优先级设置不生效，仍旧为普通优先级。
示例代码
[[NERtcEngine sharedEngine] setLocalMediaPriority:kNERtcMediaPriorityHigh preemptive:YES];
返回
  • 0（kNERtcNoError）：方法调用成功。

◆ setLocalPublishFallbackOption:

- (int) setLocalPublishFallbackOption: (NERtcStreamFallbackOptions) option

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

  • SDK 会在上行弱网且音视频质量严重受影响时，自动关断视频流，尽量保证音频质量。
  • 同时 SDK 会持续监控网络质量，并在网络质量改善时恢复音视频流。
  • 当本地发布的音视频流回退为音频流时，或由音频流恢复为音视频流时，SDK 会触发本地发布的媒体流已回退为音频流 onLocalPublishFallbackToAudioOnly 回调。
    注解
    请在加入房间（joinChannel）前调用此方法。
    自从
    V4.3.0
    参数
    option发布音视频流的回退选项，默认为不开启回退。 详细信息请参考 NERtcStreamFallbackOptions。
    返回
    操作返回值，成功则返回 0

◆ setLocalRenderScaleMode:

- (int) setLocalRenderScaleMode: (NERtcVideoRenderScaleMode) mode

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

自从
V3.5.0
调用时机

请在初始化后调用该方法，且该方法仅可在加入房间后调用。
注解
参数说明
参数名称 类型 描述
mode NERtcVideoRenderScaleMode 视频显示模式类型：
  • kNERtcVideoRenderScaleFit（0）:适应视频，视频尺寸等比缩放。优先保证视频内容全部显示。若视频尺寸与显示视窗尺寸不一致，视窗未被填满的区域填充背景色。
  • kNERtcVideoRenderScaleFullFill（1）：视频尺寸非等比缩放。保证视频内容全部显示，且填满视窗。
  • kNERtcVideoRenderScaleCropFill（2）：适应区域，视频尺寸等比缩放。保证所有区域被填满，视频超出部分会被裁剪。
示例代码
[[NERtcEngine sharedEngine] setLocalRenderScaleMode:kNERtcVideoRenderScaleFit];
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30004（kNERtcErrNotSupported）：不支持的操作，比如当前使用的是纯音频 SDK。
    • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎尚未初始化。

◆ setLocalRenderScaleMode:streamType:

- (int) setLocalRenderScaleMode: (NERtcVideoRenderScaleMode) mode
streamType: (NERtcStreamChannelType) streamType 

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

自从
V5.6.40
调用时机

请在初始化后调用该方法，且该方法仅可在加入房间后调用。
注解
参数说明
参数名称 类型 描述
mode NERtcVideoRenderScaleMode 视频显示模式类型：
  • kNERtcVideoRenderScaleFit（0）:适应视频，视频尺寸等比缩放。优先保证视频内容全部显示。若视频尺寸与显示视窗尺寸不一致，视窗未被填满的区域填充背景色。
  • kNERtcVideoRenderScaleFullFill（1）：视频尺寸非等比缩放。保证视频内容全部显示，且填满视窗。
  • kNERtcVideoRenderScaleCropFill（2）：适应区域，视频尺寸等比缩放。保证所有区域被填满，视频超出部分会被裁剪。
streamType NERtcStreamChannelType 视频通道类型：
  • kNERtcStreamChannelTypeMainStream：主流。
  • kNERtcStreamChannelTypeSubStream：辅流。
示例代码
[[NERtcEngine sharedEngine] setLocalRenderScaleMode:kNERtcVideoRenderScaleFit streamType:kNERtcStreamChannelTypeMainStream];
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30004（kNERtcErrNotSupported）：不支持的操作，比如当前使用的是纯音频 SDK。
    • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎尚未初始化。

◆ setLocalRenderSubStreamScaleMode:

- (int) setLocalRenderSubStreamScaleMode: (NERtcVideoRenderScaleMode) mode

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

自从
V3.9.0
使用前提
请先调用 INERtcEngineEx#setupLocalSubStreamVideoCanvas: 方法设置本地辅流画布。
调用时机

请在初始化后调用该方法，且该方法仅可在加入房间后调用。
注解
纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
参数说明
参数名称 类型 描述
mode NERtcVideoRenderScaleMode 视频显示模式类型：
  • kNERtcVideoRenderScaleFit（0）:适应视频，视频尺寸等比缩放。优先保证视频内容全部显示。若视频尺寸与显示视窗尺寸不一致，视窗未被填满的区域填充背景色。
  • kNERtcVideoRenderScaleFullFill（1）：视频尺寸非等比缩放。保证视频内容全部显示，且填满视窗。
  • kNERtcVideoRenderScaleCropFill（2）：适应区域，视频尺寸等比缩放。保证所有区域被填满，视频超出部分会被裁剪。
示例代码
[[NERtcEngine sharedEngine] setLocalRenderSubStreamScaleMode:kNERtcVideoRenderScaleFit];
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30004（kNERtcErrNotSupported）：不支持的操作，比如当前使用的是纯音频 SDK。
    • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎尚未初始化。

◆ setLocalVideoWatermarkConfigs:withStreamType:

- (int) setLocalVideoWatermarkConfigs: (nullable NERtcVideoWatermarkConfig *) config
withStreamType: (NERtcStreamChannelType) type 

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

注解
设置水印后，建议关注水印状态回调 NERtcEngineDelegateEx#onNERtcEngineLocalVideoWatermarkStateWithStreamType:state:。
自从
V4.6.10
参数
type水印的视频流类型。支持设置为主流或辅流。详细信息请参考 NERtcStreamChannelType。
config水印设置。设置为 nil 表示取消之前的水印。详细信息请参考 NERtcVideoWatermarkConfig。
返回
  • 0：方法调用成功。
  • 其他：方法调用失败。

◆ setLocalVoiceEqualizationOfBandFrequency:withGain:

- (int) setLocalVoiceEqualizationOfBandFrequency: (NERtcAudioEqualizationBandFrequency) bandFrequency
withGain: (NSInteger) gain 

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

注解
该方法在加入房间前后都能调用，通话结束后重置为默认关闭状态。
参数
bandFrequency频谱子带索引，取值范围是 [0-9]，分别代表 10 个频带，对应的中心频率是 [31，62，125，250，500，1k，2k，4k，8k，16k] Hz。
gain每个 band 的增益，单位是 dB，每一个值的范围是 [-15，15]，默认值为 0。
返回
操作返回值，成功则返回 0

◆ setLocalVoicePitch:

- (int) setLocalVoicePitch: (double) pitch

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

注解
  • 通话结束后该设置会重置，默认为 1.0。
  • 此方法与 setAudioEffectPreset 互斥，调用此方法后，已设置的变声效果会被取消。
参数
pitch语音频率。可以在 [0.5, 2.0] 范围内设置。取值越小，则音调越低。默认值为 1.0，表示不需要修改音调。
返回
操作返回值，成功则返回 0

◆ setLocalVoiceReverbParam:

- (int) setLocalVoiceReverbParam: (NERtcReverbParam *) param

设置本地语音混响效果。

注解
该方法在加入房间前后都能调用，通话结束后重置为默认的关闭状态。
自从
V4.6.10
参数
param详细信息请参考 NERtcReverbParam。
返回
  • 0：方法调用成功。
  • 其他：方法调用失败。

◆ setLoudspeakerMode:

- (int) setLoudspeakerMode: (bool) enable

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

自从
V3.5.0
调用时机

请在初始化后调用该方法，且该方法仅可在加入房间后调用。
注解
  • 平板设备暂时不支持此接口。
  • 若设备连接了耳机或蓝牙，则无法开启外放。
参数说明
参数名称 类型 描述
enable bool 是否将音频路由到扬声器：
  • YES：启用扬声器播放。
  • NO：关闭扬声器播放。
示例代码
//打开外放
[[NERtcEngine sharedEngine] setLoudspeakerMode:YES];
//关闭外放
[[NERtcEngine sharedEngine] setLoudspeakerMode:NO];
相关接口
INERtcEngineEx#getLoudspeakerMode:：检查扬声器的启用状态。
相关回调
NERtcEngineDelegateEx#onNERtcEngineAudioDeviceStateChangeWithDeviceID:deviceType:deviceState:：音频路由改变回调，可以通过此回调判断当前音频播放设备。
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30004（kNERtcErrNotSupported）：当前状态不支持的操作，比如引擎未初始化成功。

◆ setMixedAudioFrameParameters:

- (int) setMixedAudioFrameParameters: (nullable NERtcAudioFrameRequestFormat *) format

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

自从
V3.5.0
调用时机

请在初始化后调用该方法，且该方法在加入房间前后均可调用。
业务场景
适用于需要获取本地用户和远端所有用户的声音的场景，比如通话录音的场景。
注解
  • 该方法设置内部引擎为启用状态，在 INERtcEngine#leaveChannel 后设置会重置为默认状态。
  • 目前仅支持设置对应回调的音频采样率；未调用该接口设置返回的音频数据格式时，回调中的采样率取默认值。
参数说明
参数名称 类型 描述
format NERtcAudioFrameRequestFormat 指定 NERtcEngineAudioFrameObserver#onNERtcEngineMixedAudioFrame: 中返回数据的采样率和数据的通道数。若您希望使用音频的原始格式，format 参数传 nil 即可，默认为 nil。
示例代码
//设置 pcm 录制和播放声音混音后的数据回调格式
NERtcAudioFrameRequestFormat *format = [[NERtcAudioFrameRequestFormat alloc] init];
format.sampleRate = sampleRate;
[[NERtcEngine sharedEngine] setRecordingAudioFrameParameters:format];
//开启监听 pcm 数据回调
[[NERtcEngine sharedEngine] setAudioFrameObserver:self];
NERtcAudioFrameRequestFormat
定义 NERtcEngineBase.h:1406
NERtcAudioFrameRequestFormat::sampleRate
uint32_t sampleRate
定义 NERtcEngineBase.h:1431
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30003（kNERtcErrInvalidParam）：参数错误。

◆ setPlaybackAudioFrameParameters:

- (int) setPlaybackAudioFrameParameters: (nullable NERtcAudioFrameRequestFormat *) format

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

自从
V3.5.0
调用时机
请在初始化后调用该方法，且该方法仅可在加入房间后调用。
业务场景
适用于需要自行对待播放的声音进行二次处理的场景。
参数说明
参数名称 类型 描述
format NERtcAudioFrameRequestFormat 指定 NERtcEngineAudioFrameObserver#onNERtcEngineAudioFrameWillPlayback: 中返回数据的采样率和数据的通道数。允许传入 nil，默认为 nil，表示使用音频的原始格式。
示例代码
//设置 pcm 播放数据回调格式
NERtcAudioFrameRequestFormat *format = [[NERtcAudioFrameRequestFormat alloc] init];
format.channels = channels;
format.sampleRate = sampleRate;
format.mode = mode;
[[NERtcEngine sharedEngine] setRecordingAudioFrameParameters:format];
//开启监听 pcm 数据回调
[[NERtcEngine sharedEngine] setAudioFrameObserver:self];
NERtcAudioFrameRequestFormat::mode
NERtcAudioFrameOpMode mode
定义 NERtcEngineBase.h:1441
NERtcAudioFrameRequestFormat::channels
uint32_t channels
定义 NERtcEngineBase.h:1421
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30005（kNERtcErrInvalidState)：状态错误，比如引擎尚未初始化。

◆ setPlaybackBeforeMixingAudioFrameParameters:

- (int) setPlaybackBeforeMixingAudioFrameParameters: (nullable NERtcAudioFrameRequestFormat *) format

设置录制和播放声音混音后的数据格式。
该方法设置 NERtcEngineAudioFrameObserver#onNERtcEnginePlaybackAudioFrameBeforeMixingWithUserID:frame:channelId: 回调的声音格式。

◆ setPlayoutDeviceMute:

- (int) setPlayoutDeviceMute: (bool) muted

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

自从
V3.5.0
调用时机

请在初始化后调用该方法，且该方法仅可在加入房间后调用。
注解
此接口仅静音播放的音频数据，不影响播放设备的运行。
参数说明
参数名称 类型 描述
muted bool 是否静音音频播放设备：
  • YES：静音音频播放设备。
  • NO：取消静音音频播放设备。
示例代码
//设置播放设备静音
[[NERtcEngine sharedEngine] setPlayoutDeviceMute:YES];
//设置播放设备取消静音
[[NERtcEngine sharedEngine] setPlayoutDeviceMute:NO];
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：音频模块尚未初始化。
    • 30005（kNERtcErrInvalidState ）：当前状态不支持的操作，比如引擎尚未初始化。

◆ setPreDecodeObserver:

- (int) setPreDecodeObserver: (nullable id< NERtcEnginePreDecodeObserver >) observer

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

  • 通过此接口可以设置 NERtcEnginePreDecodeObserver#onNERtcEnginePreDecoderFrame: 回调监听，返回相关解码前媒体数据。
    自从
    V4.6.29
    使用前提
    若您需要接收未解码的视频数据，建议先调用 INERtcEngine#setParameters: 接口关闭 SDK 的视频解码功能。
    调用时机
    请在引擎初始化之后调用此接口，且该方法在加入房间前后均可调用。
    业务场景
    适用于需要自行处理音、视频数据的解码与渲染的场景。
    注解
    目前仅支持传输 OPUS 格式的音频数据和 H.264 格式的视频数据。
    参数说明
    参数名称 类型 描述
    observer NERtcEnginePreDecodeObserver 接口对象实例。可以传 nil 表示取消注册。

    示例代码
    [[NERtcEngine sharedEngine] setPreDecodeObserver:Observer];
    相关回调
    NERtcEnginePreDecodeObserver#onNERtcEnginePreDecoderFrame:：返回相关解码前媒体数据，包括用户的 UID、媒体数据类型、数据长度等。
    返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。

◆ setRangeAudioMode:

- (int) setRangeAudioMode: (NERtcRangeAudioMode) mode

设置玩家本人在房间中的范围语音模式，该设置不影响其他人。

自从
V5.5.10
调用时机
请在引擎初始化后调用此接口，且该方法在加入房间前后均可调用。
注解
  • 离开房间后，此参数不会自动重置为默认模式，所以请在每次加入房间之前都调用此方法设置语音模式。
  • 加入房间后，可以随时修改语音模式，并立即生效。
参数
[in]mode范围语音模式，包括所有人和仅小队两种模式。具体请参考 NERtcRangeAudioMode。
返回
  • 0: 方法调用成功
  • 其他: 调用失败

◆ setRangeAudioTeamID:

- (int) setRangeAudioTeamID: (int32_t) teamId

设置范围语音的小队 ID。

自从
V5.5.10
调用时机
请在引擎初始化后调用此接口，且该方法在加入房间前后均可调用。
注解
  • 离开房间后，TeamID 失效，需要重新配置 TeamID，请在每次加入房间之前都调用此方法设置队伍号。
  • 如果离开房间后再加入房间，请在收到退房成功回调（onLeaveChannel）后，再调用此方法设置队伍号。
  • 若加入房间后，调用此接口修改队伍号，设置后立即生效。
  • 请配合 setRangeAudioMode: 接口一起使用。
参数
teamId小队 ID, 有效值: >=0。若 team_id = 0，则房间内所有人（不论范围语音的模式是所有人还是仅小队）都可以听到该成员的声音。
返回
  • 0: 方法调用成功
  • 其他: 调用失败

◆ setRecordDeviceMute:

- (int) setRecordDeviceMute: (bool) muted

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

自从
V3.5.0
调用时机
请在初始化后调用该方法，且该方法仅可在加入房间后调用。
业务场景
适用于麦克风采集和伴音同时开启时，只发送伴音音频的场景。
参数说明
参数名称 类型 描述
muted bool 是否静音音频采集设备：
  • YES：静音音频采集设备。
  • NO：取消静音音频采集设备。
示例代码
//设置采集设备静音
[[NERtcEngine sharedEngine] setRecordDeviceMute:YES];
//设置采集设备取消静音
[[NERtcEngine sharedEngine] setRecordDeviceMute:NO];
相关接口
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：音频模块尚未初始化。
    • 30005（kNERtcErrInvalidState)：状态错误，比如引擎尚未初始化。

◆ setRecordingAudioFrameParameters:

- (int) setRecordingAudioFrameParameters: (nullable NERtcAudioFrameRequestFormat *) format

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

自从
V3.5.0
调用时机

请在初始化后调用该方法，且该方法在加入房间前后均可调用。
业务场景
适用于需要监听音频 PCM 采集数据回调并指定回调的数据格式的场景。
注解
若您希望使用音频的原始格式，format 参数传 nil 即可。
参数说明
参数名称 类型 描述
format NERtcAudioFrameRequestFormat 指定 NERtcEngineAudioFrameObserver#onNERtcEngineAudioFrameDidRecord: 中返回数据的采样率和数据的通道数。
示例代码
//设置 pcm 采集数据回调格式
NERtcAudioFrameRequestFormat *format = [[NERtcAudioFrameRequestFormat alloc] init];
format.channels = channels;
format.sampleRate = sampleRate;
format.mode = mode;
[[NERtcEngine sharedEngine] setRecordingAudioFrameParameters:format];
//开启监听 pcm 数据回调
[[NERtcEngine sharedEngine] setAudioFrameObserver:self];
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30003（kNERtcErrInvalidParam）：参数错误。

◆ setRemoteHighPriorityAudioStream:forUserID:streamType:

- (int) setRemoteHighPriorityAudioStream: (BOOL) enable
forUserID: (uint64_t) userID
streamType: (NERtcAudioStreamType) streamType 

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

注解
  • 该接口需要通话中设置，并需要自动订阅打开（默认打开）。
  • 该接口只能设置一个用户的优先级，后设置的会覆盖之前的设置。
  • 该接口通话结束后，优先级设置重置。
自从
V4.6.0
参数
enable是否设置音频订阅优先级。
  • true：设置音频订阅优先级。
  • false：取消设置音频订阅优先级。
userID用户 ID
streamType订阅音频流的类型。默认为 kNERtcAudioStreamMain。
返回
操作返回值，成功则返回 0。

◆ setRemoteRenderScaleMode:forUserID:

- (int) setRemoteRenderScaleMode: (NERtcVideoRenderScaleMode) mode
forUserID: (uint64_t) userID 

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

自从
V3.5.0
使用前提
请先调用 INERtcEngineEx#subscribeRemoteVideo:forUserID:streamType: 方法订阅指定远端用户的视频流。
调用时机

请在初始化后调用该方法，且该方法仅可在加入房间后调用。
注解
参数说明
参数名称 类型 描述
mode NERtcVideoRenderScaleMode 视频显示模式类型：
  • kNERtcVideoRenderScaleFit（0）:适应视频，视频尺寸等比缩放。优先保证视频内容全部显示。若视频尺寸与显示视窗尺寸不一致，视窗未被填满的区域填充背景色。
  • kNERtcVideoRenderScaleFullFill（1）：视频尺寸非等比缩放。保证视频内容全部显示，且填满视窗。
  • kNERtcVideoRenderScaleCropFill（2）：适应区域，视频尺寸等比缩放。保证所有区域被填满，视频超出部分会被裁剪。
userID uint64_t 远端用户 ID。
示例代码
[[NERtcEngine sharedEngine] setRemoteRenderScaleMode:kNERtcVideoRenderScaleFit forUserID:userID];
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30004（kNERtcErrNotSupported）：不支持的操作，比如当前使用的是纯音频 SDK。
    • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如尚未加入房间。

◆ setRemoteRenderScaleMode:forUserID:streamType:

- (int) setRemoteRenderScaleMode: (NERtcVideoRenderScaleMode) mode
forUserID: (uint64_t) userID
streamType: (NERtcStreamChannelType) streamType 

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

自从
V5.6.40
使用前提
请先调用 INERtcEngineEx#subscribeRemoteVideo:forUserID:streamType: 方法订阅指定远端用户的视频流。
调用时机

请在初始化后调用该方法，且该方法仅可在加入房间后调用。
注解
参数说明
参数名称 类型 描述
mode NERtcVideoRenderScaleMode 视频显示模式类型：
  • kNERtcVideoRenderScaleFit（0）:适应视频，视频尺寸等比缩放。优先保证视频内容全部显示。若视频尺寸与显示视窗尺寸不一致，视窗未被填满的区域填充背景色。
  • kNERtcVideoRenderScaleFullFill（1）：视频尺寸非等比缩放。保证视频内容全部显示，且填满视窗。
  • kNERtcVideoRenderScaleCropFill（2）：适应区域，视频尺寸等比缩放。保证所有区域被填满，视频超出部分会被裁剪。
userID uint64_t 远端用户 ID。
streamType NERtcStreamChannelType 视频通道类型：
  • kNERtcStreamChannelTypeMainStream：主流。
  • kNERtcStreamChannelTypeSubStream：辅流。
示例代码
[[NERtcEngine sharedEngine] setRemoteRenderScaleMode:kNERtcVideoRenderScaleFit forUserID:userID streamType:kNERtcStreamChannelTypeMainStream];
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30004（kNERtcErrNotSupported）：不支持的操作，比如当前使用的是纯音频 SDK。
    • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如尚未加入房间。

◆ setRemoteRenderSubStreamVideoScaleMode:forUserID:

- (int) setRemoteRenderSubStreamVideoScaleMode: (NERtcVideoRenderScaleMode) mode
forUserID: (uint64_t) userID 

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

自从
V3.5.0
使用前提
请先调用 INERtcEngineEx#subscribeRemoteSubStreamAudio:forUserID: 方法订阅指定远端用户的屏幕共享流。
调用时机

请在初始化后调用该方法，且该方法仅可在加入房间后调用。
注解
纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
参数说明
参数名称 类型 描述
mode NERtcVideoRenderScaleMode 视频显示模式类型：
  • kNERtcVideoRenderScaleFit（0）:适应视频，视频尺寸等比缩放。优先保证视频内容全部显示。若视频尺寸与显示视窗尺寸不一致，视窗未被填满的区域填充背景色。
  • kNERtcVideoRenderScaleFullFill（1）：视频尺寸非等比缩放。保证视频内容全部显示，且填满视窗。
  • kNERtcVideoRenderScaleCropFill（2）：适应区域，视频尺寸等比缩放。保证所有区域被填满，视频超出部分会被裁剪。
userID uint64_t 远端用户 ID。
示例代码
[[NERtcEngine sharedEngine] setRemoteRenderSubStreamVideoScaleMode:kNERtcVideoRenderScaleFit forUserID:userID];
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30004（kNERtcErrNotSupported）：不支持的操作，比如当前使用的是纯音频 SDK。
    • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如尚未加入房间。

◆ setRemoteSubscribeFallbackOption:

- (int) setRemoteSubscribeFallbackOption: (NERtcStreamFallbackOptions) option

设置弱网条件下订阅的音视频流回退选项。
弱网环境下，订阅的音视频质量会下降。通过该接口设置订阅音视频流的回退选项后：

  • SDK 会在下行弱网且音视频质量严重受影响时，将视频流切换为小流，或关断视频流，从而保证或提高通信质量。
  • SDK 会持续监控网络质量，并在网络质量改善时自动恢复音视频流。
  • 当远端订阅流回退为音频流时，或由音频流恢复为音视频流时，SDK 会触发远端订阅流已回退为音频流回调。
    注解
    请在加入房间（joinChannel）前调用此方法。
    自从
    V4.3.0
    参数
    option订阅音视频流的回退选项，默认为弱网时回退到视频小流。详细信息请参考 NERtcStreamFallbackOptions。
    返回
    操作返回值，成功则返回 0

◆ setSpatializerRenderMode:

- (int) setSpatializerRenderMode: (NERtcSpatializerRenderMode) mode

设置空间音效的渲染模式

自从
V5.4.0
调用时机
请在引擎初始化后调用此接口，且该方法在加入房间前才可调用。
注解
请先调用 enableSpatializer:applyToTeam: 接口启用空间音效，再调用本接口。
参数
mode渲染模式，具体请参考 #NERtcSpatializerRenderMode，默认值 #kNERtcSpatializerRenderBinauralHighQuality
返回
  • 0: 方法调用成功
  • 其他: 调用失败

◆ setSpatializerRoomProperty:

- (int) setSpatializerRoomProperty: (NERtcSpatializerRoomProperty *) roomProperty

设置空间音效的房间混响属性

自从
V5.4.0
调用时机
请在引擎初始化后调用此接口，且该方法在加入房间前才可调用。
注解
请先调用 enableSpatializer:applyToTeam: 接口启用空间音效，再调用本接口。
参数
roomProperty房间属性，具体请参考 NERtcSpatializerRoomProperty
返回
  • 0: 方法调用成功
  • 其他: 调用失败

◆ setStreamAlignmentProperty:

- (void) setStreamAlignmentProperty: (BOOL) enable

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

自从
V4.6.10
调用时机
请在引擎初始化之后调用此接口，且该方法仅可在加入房间前调用。
业务场景
适用于 KTV 实时合唱的场景。
参数说明
参数名称 类型 描述
enable BOOL 是否开启精准对齐功能：
  • YES：开启精准对齐功能。
  • NO：关闭精准对齐功能。
示例代码
[[NERtcEngine sharedEngine] setStreamAlignmentProperty:YES];
相关接口
可以调用 INERtcEngineEx#getNtpTimeOffset 方法获取本地系统时间与服务端时间的差值。
返回
无返回值。

◆ setSubscribeAudioAllowlist:

- (int) setSubscribeAudioAllowlist: (NSArray< NSNumber * > *) uidArray

您可以调用该方法指定只订阅的音频流。

注解
  • 此接口需要在加入房间成功后调用。
  • 对于调用接口时不在房间的 uid 不生效。
自从
V5.5.10
参数
[in]uid_array只订阅此 用户 uid 列表 的音频。 此列表为全量列表。如果列表为空或 null，取消订阅白名单。
返回
  • 0：方法调用成功。
  • 其他：方法调用失败。

◆ setSubscribeAudioBlocklist:uidArray:

- (int) setSubscribeAudioBlocklist: (NERtcAudioStreamType) type
uidArray: (NSArray< NSNumber * > *) uidArray 

您可以调用该方法指定不订阅的音频流。

注解
  • 此接口需要在加入房间成功后调用。
  • 对于调用接口时不在房间的 uid 不生效。
自从
V5.5.10
参数
[in]type音频流类型。
[in]uidArray不订阅此 用户 uid 列表 的音频。 此列表为全量列表。如果列表为空或 null，取消订阅黑名单。
返回
  • 0：方法调用成功。
  • 其他：方法调用失败。

◆ setupLocalSubStreamVideoCanvas:

- (int) setupLocalSubStreamVideoCanvas: (nullable NERtcVideoCanvas *) canvas

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

自从
V3.9.0
调用时机
请在引擎初始化之后调用此接口，且该方法建议在加入房间前调用。
参数说明
参数名称 类型 描述
canvas NERtcVideoCanvas * 视频画布。详细信息请参考 NERtcVideoCanvas。
示例代码
UIView *localSubStreamView = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 200, 200)];
NERtcVideoCanvas *canvas = [[NERtcVideoCanvas alloc] init];
canvas.container = localSubStreamView;
canvas.renderMode = kNERtcVideoRenderScaleFit;
canvas.mirrorMode = kNERtcVideoMirrorModeAuto;
[[NERtcEngine sharedEngine] setupLocalSubStreamVideoCanvas:canvas];
NERtcVideoCanvas
定义 NERtcEngineBase.h:296
NERtcVideoCanvas::renderMode
NERtcVideoRenderScaleMode renderMode
定义 NERtcEngineBase.h:325
NERtcVideoCanvas::container
VIEW_CLASS * container
定义 NERtcEngineBase.h:315
NERtcVideoCanvas::mirrorMode
NERtcVideoMirrorMode mirrorMode
定义 NERtcEngineBase.h:339
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：状态错误，比如引擎尚未初始化。
    • 30004（kNERtcErrNotSupported）：纯音频 SDK 不支持该功能。

◆ setupLocalVideoCanvas:streamType:

- (int) setupLocalVideoCanvas: (nullable NERtcVideoCanvas *) canvas
streamType: (NERtcStreamChannelType) streamType 

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

自从
V5.6.40
调用时机
请在初始化后调用该方法，且该方法在加入房间前后均可调用。
注解
  • 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
  • 在实际业务中，通常建议在初始化后即调用该方法进行本地视图设置，然后再加入房间或开启预览。
参数说明
参数名称 类型 描述
canvas NERtcVideoCanvas 本地用户视频的画布。设置为 nil 表示取消并释放已设置的画布。
streamType NERtcStreamChannelType 视频流通道类型，默认为主流 kNERtcStreamChannelTypeMainStream。
示例代码
UIView *localUserView = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 200, 200)];
NERtcVideoCanvas *canvas = [[NERtcVideoCanvas alloc] init];
canvas.container = localUserView;
canvas.renderMode = kNERtcVideoRenderScaleFit;
canvas.mirrorMode = kNERtcVideoMirrorModeAuto;
[[NERtcEngine sharedEngine] setupLocalVideoCanvas:canvas streamType:kNERtcStreamChannelTypeMainStream];
相关接口
若您希望在通话中更新本地用户视图的渲染或镜像模式，请调用 INERtcEngineEx#setLocalRenderScaleMode: 方法。
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：引擎尚未初始化。
    • 30004（kNERtcErrNotSupported）：不支持的操作，比如纯音频 SDK 不支持该功能。
    • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引起尚未成功启动。

◆ setupRemoteSubStreamVideoCanvas:forUserID:

- (int) setupRemoteSubStreamVideoCanvas: (nullable NERtcVideoCanvas *) canvas
forUserID: (uint64_t) userID 

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

自从
V3.9.0
使用前提
建议在收到远端用户加入房间的 NERtcEngineDelegate#onNERtcEngineUserDidJoinWithUserID:userName:joinExtraInfo: 回调后，再调用此接口通过回调返回的 uid 设置对应视图。
调用时机
请在引擎初始化之后调用此接口，且该方法在加入房间前后均可调用。
注解
  • 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
  • 退出房间后，SDK 会清除远端用户和画布的的绑定关系，该设置自动失效。
参数说明
参数名称 类型 描述
canvas NERtcVideoCanvas * 视频画布。详细信息请参考 NERtcVideoCanvas。
userID uint64_t 远端用户 ID。
示例代码
- (void)onNERtcEngineUserDidJoinWithUserID:(uint64_t)userID userName:(NSString *)userName {
UIView *remoteUserView = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 200, 200)];
NERtcVideoCanvas *canvas = [[NERtcVideoCanvas alloc] init];
canvas.container = remoteUserView;
canvas.renderMode = kNERtcVideoRenderScaleFit;
canvas.mirrorMode = kNERtcVideoMirrorModeAuto;
[[NERtcEngine sharedEngine] setupRemoteSubStreamVideoCanvas:canvas forUserID:userID];
}
相关接口
可以调用 INERtcEngineEx#setRemoteRenderScaleMode:forUserID: 方法在通话过程中更新远端用户视图的渲染模式。
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：状态错误，比如引擎尚未初始化。
    • 30004（kNERtcErrNotSupported）：不支持的操作，比如纯音频 SDK 不支持该功能。
    • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如尚未加入房间。

◆ setupRemoteVideoCanvas:forUserID:streamType:

- (int) setupRemoteVideoCanvas: (nullable NERtcVideoCanvas *) canvas
forUserID: (uint64_t) userID
streamType: (NERtcStreamChannelType) streamType 

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

自从
V5.6.40
使用前提
建议在收到远端用户加入房间的 NERtcEngineDelegate#onNERtcEngineUserDidJoinWithUserID:userName:joinExtraInfo: 回调后，再调用此接口通过回调返回的 uid 设置对应视图。
调用时机
请在引擎初始化之后调用此接口，且该方法在加入房间前后均可调用。
注解
  • 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
  • 退出房间后，SDK 会清除远端用户和画布的的绑定关系，该设置自动失效。
参数说明
参数名称 类型 描述
canvas NERtcVideoCanvas * 视频画布。详细信息请参考 NERtcVideoCanvas。
userID uint64_t 远端用户 ID。
streamType NERtcStreamChannelType 流类型。详细信息请参考 NERtcStreamChannelType。
示例代码
- (void)onNERtcEngineUserDidJoinWithUserID:(uint64_t)userID userName:(NSString *)userName {
UIView *remoteUserView = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 200, 200)];
NERtcVideoCanvas *canvas = [[NERtcVideoCanvas alloc] init];
canvas.container = remoteUserView;
canvas.renderMode = kNERtcVideoRenderScaleFit;
canvas.mirrorMode = kNERtcVideoMirrorModeAuto;
[[NERtcEngine sharedEngine] setupRemoteSubStreamVideoCanvas:canvas forUserID:userID streamType:kNERtcStreamChannelTypeMainStream];
}
相关接口
可以调用 INERtcEngineEx#setRemoteRenderScaleMode:forUserID: 方法在通话过程中更新远端用户视图的渲染模式。
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：状态错误，比如引擎尚未初始化。
    • 30004（kNERtcErrNotSupported）：不支持的操作，比如纯音频 SDK 不支持该功能。
    • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如尚未加入房间。

◆ setVideoCorrectionConfig:

- (int) setVideoCorrectionConfig: (nullable NERtcVideoCorrectionConfiguration *) config

设置视频图像矫正参数。

自从
V4.6.0
注解
  • 矫正参数结构体的前 4 个参数，代表了待矫正区域相对于屏幕上视图的坐标，每个坐标点的 x 和 y 的取值范围均为 0 ~ 1 的浮点数。
  • 矫正参数结构体的后 3 个参数只有在使用了外部视频渲染功能时才需要传入。
  • config 可以传入 nil，清空之前设置过的矫正参数，将画面恢复至矫正之前的效果。
参数
config视频图像矫正相关参数。详细说明请参考 NERtcVideoCorrectionConfiguration。
返回
  • 0：方法调用成功。
  • 其他：方法调用失败。

◆ setVideoEncoderQosObserver:

- (int) setVideoEncoderQosObserver: (nullable id< NERtcEngineVideoEncoderQosObserver >) encoderQosObserver

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

◆ setVideoFrameObserver:

- (int) setVideoFrameObserver: (nullable id< NERtcEngineVideoFrameObserver >) videoframeObserver

注册视频数据观察对象 通过此接口可以设置视频数据采集回调对象，可以用于第三方美颜等操作

自从
V4.6.40
调用时机
请在初始化后调用该方法，且该方法在加入房间前后均可调用。 设置空指针，表示不再监听视频数据采集回调。

◆ setVideoRotationMode:

- (int) setVideoRotationMode: (NERtcVideoRotationMode) rotationMode

设置本地视频画面的旋转模式。
该接口用于设置本地视频画面在本地和远端设备上的旋转模式，可以指定本地画面和系统设备的横屏/竖屏模式一致、或者和 App UI 的横屏/竖屏模式一致。

注解
  • 请在加入房间之前调用此接口。
  • 无论在哪种旋转模式下，采集端和播放端的旋转模式均保持一致。即本地看到的本地画面和远端看到的本地画面总是同样横屏模式或同样竖屏模式。
  • 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
自从
V4.3.0
参数
rotationMode视频旋转模式。详细信息请参考 NERtcVideoRotationMode。
返回
操作返回值，成功则返回 0

◆ setVoiceBeautifierPreset:

- (int) setVoiceBeautifierPreset: (NERtcVoiceBeautifierType) type

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

自从
V4.0.0
调用时机
请在引擎初始化之后调用此接口，且该方法在加入房间前后均可调用。
业务场景
适用于多人语聊或 K 歌房中需要美化主播或连麦者声音的场景。
注解
该方法设置内部引擎为启用状态，在 INERtcEngine#leaveChannel 后设置失效，将恢复至默认。
参数说明
参数名称 类型 描述
type NERtcVoiceBeautifierType 预设的美声效果模式。默认值为 kNERtcVoiceBeautifierOff，即关闭美声效果。
示例代码
[[NERtcEngine sharedEngine] setVoiceBeautifierPreset:kNERtcVoiceBeautifierKTV];
返回
  • 0（kNERtcNoError）：方法调用成功；
  • 其他：方法调用失败。
    • 30003（kNERtcErrInvalidParam）：参数错误。

◆ startAudioDump

- (int) startAudioDump

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

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

◆ startAudioDumpWithType:

- (int) startAudioDumpWithType: (NERtcAudioDumpType) type

开始进行音频 dump。

注解
该方法可在加入房间前后调用。
参数
type音频 dump 类型。详细信息请参考 NERtcAudioDumpType。
返回
操作返回值，成功则返回 0

◆ startAudioMixingWithOption:

- (int) startAudioMixingWithOption: (NERtcCreateAudioMixingOption *) option

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

自从
V3.5.0
使用前提
发送伴音前必须前调用 INERtcEngine#enableLocalAudio: 方法开启本地音频采集（V4.4.0 版本除外）。
调用时机

请在初始化后调用该方法，且该方法仅可在加入房间后调用。
注解
  • 支持的音乐文件类型包括 MP3、M4A、AAC、3GP、WMA 、WAV 和 FLAC 格式，支持本地文件或在线 URL。
  • 自 V4.3.0 版本起，若您在通话中途调用此接口播放音乐文件时，手动设置了伴音播放音量或发送音量，则当前通话中再次调用时默认沿用此设置。
参数说明
参数名称 类型 描述
option NERtcCreateAudioMixingOption 创建伴音任务的配置选项，包括伴音任务类型、伴音文件的绝对路径或 URL 等。
示例代码
NERtcCreateAudioMixingOption *option = [[NERtcCreateAudioMixingOption alloc] init];
option.loopCount = loopCount; //循环播放次数
option.playbackEnabled = playbackEnabled; //是否本地播放伴音
option.playbackVolume = playbackVolume; //音乐文件的播放音量
option.sendEnabled = sendEnabled; //是否将伴音发送远端
option.sendVolume = sendVolume; //音乐文件的发送音量
option.path = path; //待播放的音乐文件的绝对路径或 URL 地址
option.sendWithAudioType = sendWithAudioType//伴音跟随音频主流还是辅流，默认跟随主流
[[NERtcEngine sharedEngine] startAudioMixingWithOption:option];
NERtcCreateAudioMixingOption
Options for creating mixing audios
定义 NERtcEngineBase.h:688
NERtcCreateAudioMixingOption::path
NSString * path
定义 NERtcEngineBase.h:701
NERtcCreateAudioMixingOption::sendEnabled
BOOL sendEnabled
定义 NERtcEngineBase.h:725
NERtcCreateAudioMixingOption::playbackVolume
uint32_t playbackVolume
定义 NERtcEngineBase.h:759
NERtcCreateAudioMixingOption::sendVolume
uint32_t sendVolume
定义 NERtcEngineBase.h:747
NERtcCreateAudioMixingOption::sendWithAudioType
NERtcAudioStreamType sendWithAudioType
定义 NERtcEngineBase.h:779
NERtcCreateAudioMixingOption::loopCount
int loopCount
定义 NERtcEngineBase.h:715
NERtcCreateAudioMixingOption::playbackEnabled
BOOL playbackEnabled
定义 NERtcEngineBase.h:735
相关回调
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30003（kNERtcErrInvalidParam）：参数错误。
    • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎尚未初始化。

◆ startAudioRecording:sampleRate:quality:

- (int) startAudioRecording: (NSString *) filePath
sampleRate: (int) sampleRate
quality: (NERtcAudioRecordingQuality) quality 

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

自从
V4.2.0
调用时机
请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。
注解
客户端只能同时运行一个录音任务；若您在录音过程中重复调用 INERtcEngineEx#startAudioRecording:sampleRate:quality: 方法，会结束当前录制任务，并重新开始新的录音任务。 本端用户离开房间时，自动停止录音；也可以在通话中随时调用 INERtcEngineEx#stopAudioRecording 方法以实现手动停止录音。 请保证录音文件的保存路径存在并且可写，目前支持 WAV（音质保真度高，文件大）、AAC（音质保真度低，文件小）格式的文件。
参数说明
参数名称 类型 描述
filePath NSString * 录音文件在本地保存的绝对路径，需要精确到文件名及格式，例如：sdcard/xxx/audio.aac。
sampleRate int 录音采样率。单位为赫兹（Hz），可以设置为 16000、32000（默认）、44100 或 48000。
quality NERtcAudioRecordingQuality 录音音质。此参数仅在 AAC 格式下有效。
示例代码
[[NERtcEngine sharedEngine] startAudioRecording:path sampleRate:sampleRate quality:quality];
相关回调
调用此接口成功后会触发 NERtcEngineDelegateEx#onNERtcEngineAudioRecording:filePath: 回调，通知音频录制任务状态已更新。音频录制状态码请参考 NERtcAudioRecordingCode。
返回
  • 0（kNERtcNoError）：方法调用成功；
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：状态错误，比如引擎尚未初始化。
    • 30003（kNERtcErrInvalidParam）： 参数错误，比如设置的采样率无效。

◆ startAudioRecordingWithConfig:

- (int) startAudioRecordingWithConfig: (NERtcAudioRecordingConfiguration *_Nonnull) config

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

  • WAV：音质保真度高，文件大。
  • AAC：音质保真度低，文件小。
    注解
  • 请在加入房间后调用此方法。
  • 客户端只能同时运行一个录音任务，正在录音时，如果重复调用 startAudioRecordingWithConfig，会结束当前录制任务，并重新开始新的录音任务。
  • 当前用户离开房间时，自动停止录音。您也可以在通话中随时调用 stopAudioRecording 手动停止录音。
    自从
    V4.6.0
    参数
    filePath录音文件在本地保存的绝对路径，需要精确到文件名及格式。例如：sdcard/xxx/audio.aac。
    • 请确保指定的路径存在并且可写。
    • 目前仅支持 WAV 或 AAC 文件格式。
    sampleRate录音采样率（Hz），可以设为 16000、32000（默认）、44100 或 48000。
    quality录音音质，只在 AAC 格式下有效。详细信息请参考 NERtcAudioRecordingQuality。
    position录音对象。详细信息请参考 NERtcAudioRecordingPosition。
    cycleTime循环缓存的最大时长跨度。该参数单位为秒，可以设为 0、10、60、360、900，默认值为 0，即实时写文件。
    返回
  • 0：方法调用成功。
  • 其他：方法调用失败。

◆ startChannelMediaRelay:

- (int) startChannelMediaRelay: (NERtcChannelMediaRelayConfiguration *_Nonnull) config

开始跨房间媒体流转发。

  • 该方法可用于实现跨房间连麦等场景。支持同时转发到 4 个房间，同一个房间可以有多个转发进来的媒体流。
  • 成功调用该方法后，SDK 会触发 onNERtcEngineChannelMediaRelayStateDidChange 和 onNERtcEngineDidReceiveChannelMediaRelayEvent 回调，并在回调中报告当前的跨房间媒体流转发状态和事件。
    注解
  • 请在成功加入房间后调用该方法。调用此方法前需要通过 config 中的 setDestinationInfo 设置目标房间。
  • 该方法仅对直播场景下的主播角色有效。
  • 成功调用该方法后，若您想再次调用该方法，必须先调用 stopChannelMediaRelay 方法退出当前的转发状态。
  • 成功开始跨房间转发媒体流后，如果您需要修改目标房间，例如添加或删减目标房间等，可以调用方法 updateChannelMediaRelay 更新目标房间信息。
    参数
    config跨房间媒体流转发参数配置信息。详细信息请参考 NERtcChannelMediaRelayConfiguration。
    返回
    成功返回 0，其他则失败

◆ startLastmileProbeTest:

- (int) startLastmileProbeTest: (NERtcLastmileProbeConfig *_Nullable) config

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

  • onNERtcEngineLastmileQuality：网络质量状态回调，以打分形式描述上下行网络质量的主观体验。该回调视网络情况在约 5 秒内返回。
  • onNERtcEngineLastmileProbeTestResult：网络质量探测报告回调，报告中通过客观数据反馈上下行网络质量。该回调视网络情况在约 30 秒内返回。
    注解
  • 请在加入房间（joinChannel）前调用此方法。
  • 调用该方法后，在收到 onNERtcEngineLastmileQuality 和 onNERtcEngineLastmileProbeTestResult 回调之前请不要调用其他方法，否则可能会由于 API 操作过于频繁导致此方法无法执行。
    自从
    V4.5.0
    参数
    configLast mile 网络探测配置。
    返回
  • 0: 方法调用成功
  • 其他: 调用失败

◆ startPreview

- (int) startPreview

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

自从
V4.6.20
使用前提
请在通过 INERtcEngine#setupLocalVideoCanvas: 接口设置视频画布后调用该方法。
调用时机
请在初始化后调用该方法，且该方法仅可当不在房间内时可调用。
业务场景
适用于加入房间前检查设备状态是否可用、预览视频效果等场景。
注解
  • 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
  • 在加入房间前预览视频效果时设置的美颜、虚拟背景等视频效果在房间内仍然生效；在房间内设置的视频效果在退出房间后预览视频时也可生效。
示例代码
//设置本端视频画布
UIView *localUserView = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 200, 200)];
NERtcVideoCanvas *canvas = [[NERtcVideoCanvas alloc] init];
canvas.container = localUserView;
[[NERtcEngine sharedEngine] setupLocalVideoCanvas:canvas];
//开启视频预览
[[NERtcEngine sharedEngine] startPreview];
相关接口
该方法仅适用于视频主流，若您希望开启辅流通道的视频预览，请调用 INERtcEngineEx#startPreview: 方法。
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：引擎尚未初始化。
    • 30004（kNERtcErrNotSupported）：不支持的操作，比如当前使用的是纯音频 SDK，或已经开启预览。
    • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎未初始化成功，或尚未设置画布。
    • 30027（kNERtcErrDeviceOccupied）：所选设备已被占用，比如已通过主流通道开启了摄像头，无法再通过辅流通道开启摄像头预览。
    • 30300（kNERtcErrOSAuthorize）：应用未获取到操作系统的摄像头权限。

◆ startPreview:

- (int) startPreview: (NERtcStreamChannelType) streamType

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

自从
V3.5.0
使用前提
请在通过 INERtcEngine#setupLocalVideoCanvas: 接口设置视频画布后调用该方法。
调用时机
请在初始化后调用该方法，且该方法仅可当不在房间内时可调用。
业务场景
适用于加入房间前检查设备状态是否可用、预览视频效果等场景。
注解
  • 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
  • 在加入房间前预览视频效果时设置的美颜、虚拟背景等视频效果在房间内仍然生效；在房间内设置的视频效果在退出房间后预览视频时也可生效。
参数说明
参数名称 类型 描述
streamType video.NERtcStreamChannelType 视频通道类型：
  • kNERtcStreamChannelTypeMainStream：主流。
  • kNERtcStreamChannelTypeSubStream：辅流。
示例代码
//开启主流视频通道预览
NERtcVideoCanvas *canvas = [[NERtcVideoCanvas alloc] init];
canvas.container = self.renderView;
[NERtcEngine.sharedEngine setupLocalVideoCanvas:canvas];
[NERtcEngine.sharedEngine startPreview:kNERtcStreamChannelTypeMainStream];
//开启辅流视频通道预览
NERtcVideoCanvas *subCanvas = [[NERtcVideoCanvas alloc] init];
subCanvas.container = self.subRenderView;
[NERtcEngine.sharedEngine setupLocalSubStreamVideoCanvas:subCanvas];
[NERtcEngine.sharedEngine startPreview:kNERtcStreamChannelTypeSubStream];
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：引擎尚未初始化。
    • 30004（kNERtcErrNotSupported）：不支持的操作，比如当前使用的是纯音频 SDK，或已经开启预览。
    • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎未初始化成功，或尚未设置画布。
    • 30027（kNERtcErrDeviceOccupied）：所选设备已被占用，比如已通过主流通道开启了摄像头，无法再通过辅流通道开启摄像头预览。
    • 30300（kNERtcErrOSAuthorize）：应用未获取到操作系统的摄像头权限。

◆ startPushStreaming:

- (int) startPushStreaming: (NERtcPushStreamingConfig *) config

开始推流。
通过本接口可以实现将 RTMP 流推到指定的地址。

自从
V4.6.420
调用时机
请在初始化后调用该方法。
注解
  • 本接口跟 joinChannel 互斥。
参数说明
参数名称 类型 描述
config NERtcPushStreamingConfig 推流参数，参考 NERtcPushStreamingConfig
示例代码
NERtcPushStreamingConfig *pushConfig = [[NERtcPushStreamingConfig alloc] init];
NERtcStreamingRoomInfo *roomInfo = [[NERtcStreamingRoomInfo alloc] init];
roomInfo.channelName = channelName;
roomInfo.uId = uId;
roomInfo.token = token;
pushConfig.streamingUrl = streamingUrl;
pushConfig.streamingRoomInfo = roomInfo;
[[NERtcEngine sharedEngine] startPushStreaming:pushConfig];
NERtcPushStreamingConfig
定义 NERtcEngineBase.h:3175
NERtcPushStreamingConfig::streamingRoomInfo
NERtcStreamingRoomInfo * streamingRoomInfo
定义 NERtcEngineBase.h:3194
NERtcPushStreamingConfig::streamingUrl
NSString * streamingUrl
定义 NERtcEngineBase.h:3184
NERtcStreamingRoomInfo
定义 NERtcEngineBase.h:3136
NERtcStreamingRoomInfo::uId
uint64_t uId
定义 NERtcEngineBase.h:3147
NERtcStreamingRoomInfo::channelName
NSString * channelName
定义 NERtcEngineBase.h:3159
NERtcStreamingRoomInfo::token
NSString * token
定义 NERtcEngineBase.h:3170
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30003（kNERtcErrInvalidParam）：错误的参数。
    • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎尚未初始化。

◆ startScreenCapture:

- (int) startScreenCapture: (NERtcVideoSubStreamEncodeConfiguration *) config

开启屏幕共享。
通过此接口开启屏幕共享后，屏幕共享内容以视频辅流的形式发送。

自从
V3.5.0
调用时机
请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。
参数说明
参数名称 类型 描述
config NERtcVideoSubStreamEncodeConfiguration * 本地辅流发送配置，详细信息请参考 NERtcVideoSubStreamEncodeConfiguration。
示例代码
NERtcVideoSubStreamEncodeConfiguration *config = [[NERtcVideoSubStreamEncodeConfiguration alloc] init];
config.maxProfile = 视频编码的分辨率;
config.minBitrate = 最小编码码率
config.minFrameRate = 最小编码帧率
config.frameRate = 帧率
config.bitrate = 最小编码码率
config.contentPrefer = 屏幕共享功能的编码策略倾向;
[[NERtcEngine sharedEngine] startScreenCapture:config];
NERtcBaseVideoEncodeConfiguration::bitrate
NSInteger bitrate
定义 NERtcEngineBase.h:465
NERtcBaseVideoEncodeConfiguration::minFrameRate
NSInteger minFrameRate
定义 NERtcEngineBase.h:402
NERtcBaseVideoEncodeConfiguration::minBitrate
NSInteger minBitrate
定义 NERtcEngineBase.h:475
NERtcVideoSubStreamEncodeConfiguration::contentPrefer
NERtcSubStreamContentPrefer contentPrefer
定义 NERtcEngineBase.h:657
相关回调
成功开启屏幕共享辅流后，远端会触发 NERtcEngineDelegate#onNERtcEngineUserSubStreamDidStartWithUserID:subStreamProfile: 回调。
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30005（kNERtcErrInvalidState）：状态错误，比如引擎尚未初始化。
    • 50001（kNERtcRuntimeErrVDMNotScreenUseSubStream）：当前使用的非屏幕共享形式的辅流。

◆ stopAllEffects

- (int) stopAllEffects

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

自从
V3.5.0
使用前提
请先调用 INERtcEngineEx#playEffectWitdId:effectOption: 接口播放音效文件。
调用时机
请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。
示例代码
[[NERtcEngine sharedEngine] stopAllEffects];
相关接口
可以调用 INERtcEngineEx#stopEffectWitdId: 方法停止播放指定音效文件。
返回
  • 0（kNERtcNoError）：方法调用成功；
  • 其他：方法调用失败。
    • 30005（kNERtcErrInvalidState）：引擎尚未初始化。

◆ stopAudioDump

- (int) stopAudioDump

结束记录音频 dump。

自从
V3.5.0
使用前提
请先调用 INERtcEngineEx#startAudioDumpWithType: 方法开始记录音频 dump。
调用时机
请在引擎初始化之后调用此接口，且该方法在加入房间前后均可调用。
示例代码
[[NERtcEngine sharedEngine] stopAudioDump];
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：状态错误，比如引擎尚未初始化。

◆ stopAudioMixing

- (int) stopAudioMixing

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

自从
V3.5.0
调用时机

请在初始化后调用该方法，且该方法仅可在加入房间后调用。
示例代码
[[NERtcEngine sharedEngine] stopAudioMixing];
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎尚未初始化或当前未在播放伴音。

◆ stopAudioRecording

- (int) stopAudioRecording

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

自从
V4.2.0
使用前提
请先调用 INERtcEngineEx#startAudioRecordingWithConfig: 方法开启客户端本地音频录制。
调用时机
请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。
示例代码
[[NERtcEngine sharedEngine] stopAudioRecording];
相关回调
调用此接口成功后会触发 NERtcEngineDelegateEx#onNERtcEngineAudioRecording:filePath: 回调，通知音频录制任务状态已更新。音频录制状态码请参考 NERtcAudioRecordingCode。
返回
  • 0（kNERtcNoError）：方法调用成功；
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：状态错误，比如引擎尚未初始化。

◆ stopChannelMediaRelay

- (int) stopChannelMediaRelay

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

自从
V4.2.1
使用前提
请在调用 INERtcEngineEx#startChannelMediaRelay: 方法开启跨房间媒体流转发之后调用此接口。
调用时机
请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。
示例代码
[[NERtcEngine sharedEngine] stopChannelMediaRelay];
相关回调
NERtcEngineDelegateEx#onNERtcEngineChannelMediaRelayStateDidChange:channelName:：跨房间媒体流转发状态发生改变回调。成功调用该方法后会返回 NERtcChannelMediaRelayStateIdle，否则会返回 NERtcChannelMediaRelayStateFailure。 NERtcEngineDelegateEx#onNERtcEngineDidReceiveChannelMediaRelayEvent:channelName:error:：跨房间媒体流相关转发事件回调。成功调用该方法后会返回 NERtcChannelMediaRelayEventDisconnect，否则会返回 NERtcChannelMediaRelayEventFailure。
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：通用错误。
    • 30005（kNERtcErrInvalidState）：状态错误，比如引擎未初始化。

◆ stopEffectWitdId:

- (int) stopEffectWitdId: (uint32_t) effectId

停止播放指定音效文件。

自从
V3.5.0
使用前提
请先调用 INERtcEngineEx#playEffectWitdId:effectOption: 接口播放音效文件。
调用时机
请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。
参数说明
参数名称 类型 描述
effectId uint32_t 指定音效文件的 ID，每个音效文件均有唯一的 ID。

示例代码
//停止 effectId 为 0 的音效播放
[[NERtcEngine sharedEngine] stopEffectWitdId:0]
返回
  • 0（kNERtcNoError）：方法调用成功；
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：引擎尚未初始化。
    • 30003（kNERtcErrInvalidParam）：未找到 ID 对应的音效文件。

◆ stopLastmileProbeTest

- (int) stopLastmileProbeTest

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

自从
V4.5.0
返回
  • 0: 方法调用成功
  • 其他: 调用失败

◆ stopPreview

- (int) stopPreview

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

自从
V3.5.0
使用前提
建议在通过 INERtcEngineEx#startPreview: 接口开启视频预览后调用该方法。
调用时机
请在初始化后调用该方法，且该方法仅可当不在房间内时可调用。
注解
  • 纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
  • 该方法只适用于视频主流，若您希望停止辅流通道的视频预览，请调用 INERtcEngineEx#stopPreview: 方法。
示例代码
[[NERtcEngine sharedEngine] stopPreview]
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：状态错误，比如引擎尚未初始化。
    • 30004（kNERtcErrNotSupported）：不支持的操作，比如当前使用的是纯音频 SDK。

◆ stopPreview:

- (int) stopPreview: (NERtcStreamChannelType) streamType

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

自从
V4.6.20
使用前提
建议在通过 INERtcEngineEx#startPreview: 接口开启视频预览后调用该方法。
调用时机
请在初始化后调用该方法，且该方法仅可当不在房间内时可调用。
注解
纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
参数说明
参数名称 类型 描述
streamType video.NERtcStreamChannelType 视频通道类型：
  • kNERtcStreamChannelTypeMainStream：主流。
  • kNERtcStreamChannelTypeSubStream：辅流。
示例代码
//关闭主流视频通道预览
[NERtcEngine.sharedEngine stopPreview:kNERtcStreamChannelTypeMainStream];
//关闭辅流视频通道预览
[NERtcEngine.sharedEngine stopPreview:kNERtcStreamChannelTypeSubStream];
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30004（kNERtcErrNotSupported）：不支持的操作，比如当前使用的是纯音频 SDK。

◆ stopPushStreaming

- (int) stopPushStreaming

停止推流。
通过此接口可以停止当前正在进行的 rtmp 推流。

自从
V4.6.420
使用前提
建议在通过 INERtcEngineEx#startPushStreaming: 接口开启推流后调用此方法。
调用时机
请在引擎初始化之后调用此接口，且该方法在 startPushStreaming 开始推流之后可以调用
注解
  • 该方法在单推流的时候调用会离开当前的 RTC 房间。
  • 在 PK 连麦等复合场景下推流仅停止 rtmp 推流，不会离开当前的 RTC 房间。
示例代码
[[NERtcEngine sharedEngine] stopPushStreaming];
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎尚未初始化。

◆ stopScreenCapture

- (int) stopScreenCapture

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

自从
V3.5.0
调用时机
请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。
示例代码
[[NERtcEngine sharedEngine] stopScreenCapture];
相关回调
成功调用此方法后，远端会触发 NERtcEngineDelegate#onNERtcEngineUserSubStreamDidStop: 回调。
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎尚未初始化。
    • 50001（kNERtcRuntimeErrVDMNotScreenUseSubStream）：当前使用的非屏幕共享形式的辅流。

◆ subscribeAllRemoteAudio:

- (int) subscribeAllRemoteAudio: (BOOL) subscribe

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

自从
V3.5.0
调用时机
请在引擎初始化之后调用此接口，且该方法在加入房间前后均可调用。
业务场景
适用于重要会议需要一键全体静音的场景。
注解
  • 设置该方法的 subscribe 参数为 YES 后，对后续加入房间的用户同样生效。
  • 在开启自动订阅（默认）时，设置该方法的 subscribe 参数为 NO 可以实现取消订阅所有远端用户的音频流，但此时无法再调用 INERtcEngineEx#subscribeRemoteAudio:forUserID: 方法单独订阅指定远端用户的音频流。
参数说明
参数名称 类型 描述
subscribe BOOL 是否订阅所有用户的音频主流：
  • YES：订阅音频主流。
  • NO：取消订阅音频主流。
示例代码
//订阅所有远端用户的音频主流
[[NERtcEngine sharedEngine] subscribeAllRemoteAudio:YES];
//取消订阅所有远端用户的音频主流
[[NERtcEngine sharedEngine] subscribeAllRemoteAudio:NO];
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal)：引擎未创建成功。

◆ subscribeRemoteAudio:forUserID:

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

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

自从
V3.5.0
调用时机
该方法仅在加入房间后收到远端用户开启音频主流的回调 NERtcEngineDelegate#onNERtcEngineUserAudioDidStart: 后可调用。
业务场景
适用于需要手动订阅指定用户音频流的场景。
注解
该方法设置内部引擎为启用状态，在 leaveChannel 后设置失效，将恢复至默认。 在开启音频自动订阅且未打开服务端 ASL 自动选路的情况下，调用该接口无效。
参数说明
参数名称 类型 描述
userID uint64_t 指定用户的 ID。
subscribe BOOL 是否订阅指定用户的音频主流：
  • YES：订阅音频主流。
  • NO：取消订阅音频主流。
示例代码
//订阅对方 uid 为 12345 的音频主流
[[NERtcEngine sharedEngine] subscribeRemoteAudio:YES forUserID:12345];
//取消订阅对方 uid 为 12345 的音频主流
[[NERtcEngine sharedEngine] subscribeRemoteAudio:NO forUserID:12345];
相关接口
若您希望订阅指定远端用户的音频辅流，请调用 INERtcEngineEx#subscribeRemoteSubStreamAudio:forUserID: 方法。
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal)：引擎未创建成功。
    • 30005（kNERtcErrInvalidState)：当前状态不支持的操作，比如尚未加入房间。
    • 30105（kNERtcErrFatal)：未找到指定用户。

◆ subscribeRemoteData:forUserID:

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

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

注解
当 kNERtcKeyAutoSubscribeData 默认打开时，用户不能手动修改数据通道订阅状态
参数
[in]userID指定用户的 ID。
[in]subscribe是否订阅远端用户数据通道流。
  • true: 订阅指定数据通道流（默认）。
  • false: 取消订阅指定数据通道流。
自从
V5.0.0
返回
  • 0: 方法调用成功。
  • 其他: 方法调用失败。

◆ subscribeRemoteSubStreamAudio:forUserID:

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

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

自从
V4.6.10
调用时机
请在引擎初始化之后调用此接口，且该方法仅可在加入房间且收到远端用户开启音频辅流的回调 NERtcEngineDelegate#onNERtcEngineUserSubStreamAudioDidStart: 后调用。
注解
  • 加入房间时，默认订阅所有远端用户的音频流。
  • 请在指定远端用户加入房间后再调用此方法。
参数说明
参数名称 类型 描述
uid uint64_t 远端用户 ID。
subscribe BOOL 是否订阅指定音频辅流：
  • YES：订阅指定音频辅流。
  • NO：取消订阅指定音频辅流。
示例代码
//订阅 userId 用户的音频辅流
[[NERtcEngine sharedEngine] subscribeRemoteSubStreamAudio forUserID:userId];
//取消订阅 userId 用户的音频辅流
[[NERtcEngine sharedEngine] subscribeRemoteSubStreamAudio forUserID:userId];
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：操作不支持，比如已开启自动订阅音频辅流。
    • 30005（kNERtcErrInvalidState）：状态错误，比如引擎未初始化。
    • 30105（kNERtcErrUserNotFound）：指定用户尚未加入房间。

◆ subscribeRemoteSubStreamVideo:forUserID:

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

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

自从
V3.9.0
使用前提
调用时机
请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。
注解
纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
参数说明
参数名称 类型 描述
userID uint64_t 远端用户 ID。
subsribe BOOL 是否订阅远端的视频辅流：
  • YES：订阅远端视频辅流。
  • NO：取消订阅远端视频辅流。
示例代码
[[NERtcEngine sharedEngine] subscribeRemoteSubStreamVideo:YES forUserID:userID];
相关回调
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：状态错误，比如引擎尚未初始化。
    • 30004（kNERtcErrNotSupported）：不支持的操作。
    • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎尚未初始化。
    • 30105（kNERtcErrUserNotFound）：未找到该远端用户，可能对方还未加入房间。

◆ subscribeRemoteVideo:forUserID:streamType:

- (int) subscribeRemoteVideo: (BOOL) subscribe
forUserID: (uint64_t) userID
streamType: (NERtcRemoteVideoStreamType) streamType 

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

自从
V3.5.0
调用时机
请在初始化后调用该方法，且该方法仅可在加入房间后调用。
参数说明
参数名称 类型 描述
userID uint64_t 指定用户的 ID。
streamType NERtcRemoteVideoStreamType 订阅的视频流类型：
  • kNERtcRemoteVideoStreamTypeHigh：高清画质的大流。
  • kNERtcRemoteVideoStreamTypeLow：低清画质的小流。
subscribe BOOL 是否订阅远端用户的视频流：
  • YES：订阅指定视频流。
  • NO：不订阅指定视频流。
示例代码
//订阅对方 uid 为 12345 的大流
[[NERtcEngine sharedEngine] subscribeRemoteVideo:YES forUserID:12345 streamType:kNERtcRemoteVideoStreamTypeHigh];
相关接口
若您希望订阅指定远端用户的视频辅流，请调用 INERtcEngineEx#subscribeRemoteSubStreamVideo:forUserID: 方法。
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：引擎尚未初始化。
    • 30004（kNERtcErrNotSupported ）：纯音频 SDK 不支持该功能。
    • 30005（kNERtcErrInvalidState)：尚未加入房间。
    • 30009（kNERtcErrInvalidDeviceSourceID）：设备 ID 非法。
    • 30105（kNERtcErrUserNotFound）：未找到指定用户。
    • 30106（kNERtcErrInvalidUserID）：非法指定用户，比如订阅了本端。
    • 30107（kNERtcErrMediaNotStarted）：媒体会话未建立，比如对端未开启视频主流。
    • 30108（kNERtcErrSourceNotFound）：媒体源未找到，比如对端未开启视频主流。

◆ subscribeRemoteVideo:forUserID:streamType:subscribeType:

- (int) subscribeRemoteVideo: (BOOL) subscribe
forUserID: (uint64_t) userID
streamType: (NERtcStreamChannelType) streamType
subscribeType: (NERtcRemoteVideoStreamType) subscribeType 

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

自从
V5.6.40
调用时机
请在初始化后调用该方法，且该方法仅可在加入房间后调用。
参数说明
参数名称 类型 描述
userID uint64_t 指定用户的 ID。
streamType NERtcStreamChannelType 视频流类型。详细信息请参考 NERtcStreamChannelType。
subscribeType NERtcRemoteVideoStreamType 订阅的视频流类型：
  • kNERtcRemoteVideoStreamTypeHigh：高清画质的大流。
  • kNERtcRemoteVideoStreamTypeLow：低清画质的小流。
subscribe BOOL 是否订阅远端用户的视频流：
  • YES：订阅指定视频流。
  • NO：不订阅指定视频流。
示例代码
//订阅对方 uid 为 12345 的大流
[[NERtcEngine sharedEngine] subscribeRemoteVideo:YES forUserID:12345 streamType:kNERtcRemoteVideoStreamTypeHigh];
相关接口
若您希望订阅指定远端用户的视频辅流，请调用 INERtcEngineEx#subscribeRemoteVideo:forUserID:streamType:subscribeType: 方法。
返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal）：状态错误，比如引擎尚未初始化。
    • 30004（kNERtcErrNotSupported）：不支持的操作。
    • 30005（kNERtcErrInvalidState）：当前状态不支持的操作，比如引擎尚未初始化。
    • 30105（kNERtcErrUserNotFound）：未找到该远端用户，可能对方还未加入房间。

◆ switchCameraWithPosition:

- (int) switchCameraWithPosition: (NERtcCameraPosition) position

指定前置/后置摄像头。
该方法需要在相机启动后调用，例如调用 startPreview 或 joinChannel 后。

注解
纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
自从
V4.6.10
参数
position摄像头类型。详细信息请参考 NERtcCameraPosition。该参数为必填参数，若未赋值，SDK 会报错。
返回
  • 0：方法调用成功。
  • 其他：方法调用失败。

◆ takeLocalSnapshot:callback:

- (int) takeLocalSnapshot: (NERtcStreamChannelType) streamType
callback: (NERtcTakeSnapshotCallback) callback 

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

注解

  • 本地主流截图，需要在 enableLocalVideo 并 joinChannel 成功之后调用。
  • 本地辅流截图，需要在 joinChannel 并 startScreenCapture 之后调用。
  • 同时设置文字、时间戳或图片水印时，如果不同类型的水印位置有重叠，会按照图片、文本、时间戳的顺序进行图层覆盖。
参数
streamType截图的视频流类型。支持设置为主流或辅流。
callback截图回调。
注解
纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
返回
操作返回值，成功则返回

◆ takeRemoteSnapshot:forUserID:callback:

- (int) takeRemoteSnapshot: (NERtcStreamChannelType) streamType
forUserID: (uint64_t) userID
callback: (NERtcTakeSnapshotCallback) callback 

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

注解

  • takeRemoteSnapshot 需要在收到 onUserVideoStart 与 onNERtcEngineUserSubStreamDidStartWithUserID 回调之后调用。
  • 同时设置文字、时间戳或图片水印时，如果不同类型的水印位置有重叠，会按照图片、文本、时间戳的顺序进行图层覆盖。
参数
userID远端用户 ID。
streamType截图的视频流类型。支持设置为主流或辅流。
callback截图回调。
注解
纯音频 SDK 禁用该接口，如需使用请前往云信官网下载并替换成视频 SDK。
返回
操作返回值，成功则返回 0

◆ updateChannelMediaRelay:

- (int) updateChannelMediaRelay: (NERtcChannelMediaRelayConfiguration *_Nonnull) config

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

  • 成功开始跨房间转发媒体流后，如果您需要修改目标房间，例如添加或删减目标房间等，可以调用此方法。
  • 成功调用此方法后，SDK 会触发 onNERtcEngineChannelMediaRelayStateDidChange 回调。如果报告 NERtcChannelMediaRelayStateRunning，则表示已成功转发媒体流。
    注解
  • 请在加入房间并成功调用 startChannelMediaRelay 开始跨房间媒体流转发后，调用此方法。调用此方法前需要通过 config 中的 setDestinationInfo 设置目标房间。
  • 跨房间媒体流转发最多支持 4 个目标房间，您可以在调用该方法之前，通过 NERtcChannelMediaRelayConfiguration 中的 removeDestinationInfoForChannelName 方法移除不需要的房间，再添加新的目标房间。
    参数
    config跨房间媒体流转发参数配置信息。详细信息请参考 NERtcChannelMediaRelayConfiguration。
    返回
    成功返回 0，其他则失败

◆ updateLiveStreamTask:compeltion:

- (int) updateLiveStreamTask: (NERtcLiveStreamTaskInfo *) taskInfo
compeltion: (NERtcLiveStreamCompletion) completion 

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

自从
V3.5.0
使用前提
请先调用 INERtcEngineEx#addLiveStreamTask:compeltion: 方法添加推流任务。
调用时机
请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。
注解
仅角色为主播的房间成员能调用此接口，观众成员无相关推流权限。
参数说明
参数名称 类型 描述
taskInfo NERtcLiveStreamTaskInfo * 推流任务信息。详细信息请参考 {@ NERtcLiveStreamTaskInfo}。
compeltion NERtcLiveStreamCompletion 操作结果回调，方法调用成功后会触发对应的 NERtcEngineLiveStreamObserver#onNERTCEngineLiveStreamState:taskID:url: 回调。
示例代码
[[NERtcEngine sharedEngine] updateLiveStreamTask:info compeltion:^(NSString * _Nonnull taskId, kNERtcLiveStreamError errorCode){
}];
相关回调
调用此接口成功后会触发 NERtcEngineLiveStreamObserver#onNERTCEngineLiveStreamState:taskID:url: 回调，通知推流任务状态已更新。
返回
  • 0（kNERtcNoError）：方法调用成功；
  • 其他：方法调用失败。
    • 403（kNERtcErrChannelReservePermissionDenied）：权限不足，观众模式下不支持此操作。
    • 30003（kNERtcErrInvalidParam）： 参数错误。
    • 30005（kNERtcErrInvalidState）：状态错误，比如引擎尚未初始化。

◆ updatePermissionKey:

- (int) updatePermissionKey: (NSString *) key

更新权限密钥。

  • 通过本接口可以实现当用户权限被变更，或者收到权限密钥即将过期的回调 NERtcEngineDelegateEx#onNERtcEnginePermissionKeyWillExpire 时，更新权限密钥。
    自从
    V4.6.29
    使用前提
    请确保已开通高级 Token 鉴权功能，具体请联系网易云信商务经理。
    调用时机
    请在引擎初始化之后调用此接口，且该方法仅可在加入房间后调用。
    业务场景
    适用于变更指定用户加入、创建房间或上下麦时发布流相关权限的场景。
    参数说明
    参数名称 类型 描述
    key NSString * 新的权限密钥。

    示例代码
    //getPermToken 为获取高级密钥方法，由您自行实现，具体请参考官方文档的高级 Token 鉴权章节。</a>
    [self getToken];
    [[NERtcEngine sharedEngine] updatePermissionKey:token];
    相关回调
    调用此接口成功更新权限密钥后会触发 NERtcEngineDelegateEx#onNERtcEngineUpdatePermissionKey:error:timeout: 回调。
    返回
  • 0（kNERtcNoError）：方法调用成功。
  • 其他：方法调用失败。
    • 30001（kNERtcErrFatal)：通用错误，比如引擎尚未初始化。

◆ updateSelfPosition:

- (int) updateSelfPosition: (NERtcPositionInfo *) info

设置空间音效中说话者和接收者的空间位置信息。SDK 会根据该方法中的参数计算接收者和说话者之间的相对位置，进而渲染出空间音效。

自从
V5.5.10
调用时机
请在引擎初始化后调用此接口，且该方法在加入房间前后均可调用。
注解
参数说明
通过 info 参数设置空间音效中说话者和接收者的空间位置信息。#NERtcPositionInfo 的具体参数说明如下表所示。
参数名称 描述
speaker_position 说话者的位置信息，三个值依次表示 X、Y、Z 的坐标值。默认值{0,0,0}
speaker_quaternion <note type="note">该参数设置的值暂时不起作用，保持默认值即可。</note>说话者的旋转信息，通过四元组来表示，数据格式为{w, x, y, z}。默认值{0,0,0,0}
head_position 接收者的位置信息，三个值依次表示 X、Y、Z 的坐标值。默认值{0,0,0}
head_quaternion 接收者的旋转信息，通过四元组来表示，数据格式为{w, x, y, z}。默认值{0,0,0,0}

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

◆ uploadSdkInfo

- (int) uploadSdkInfo

上传 SDK 信息。
上传的信息包括 log 和 Audio dump 等文件。

注解
只能在加入房间后调用。
返回
操作返回值，成功则返回 0
该协议的文档由以下文件生成:
制作者 doxygen 1.12.0