语音通话

Public 类型
typedef unsigned int	WindowIDType
typedef HWND	WindowIDType

Public 成员函数
virtual int	initialize (const RtcEngineContext &context)=0
virtual int	release (bool sync=false)=0
virtual int	setChannelProfile (CHANNEL_PROFILE_TYPE profile)=0
virtual int	setClientRole (CLIENT_ROLE_TYPE role)=0
virtual int	joinChannel (const char token, const char channelId, const char *info, uid_t uid)=0
virtual int	switchChannel (const char token, const char channelId)=0
virtual int	leaveChannel ()=0
virtual int	renewToken (const char *token)=0
virtual int	queryInterface (INTERFACE_ID_TYPE iid, void **inter)=0
virtual int	startEchoTest ()=0
virtual int	startEchoTest (int intervalInSeconds)=0
virtual int	stopEchoTest ()=0
virtual int	enableVideo ()=0
virtual int	disableVideo ()=0
virtual int	setVideoEncoderConfiguration (const VideoEncoderConfiguration &config)=0
virtual int	setCameraCapturerConfiguration (const CameraCapturerConfiguration &config)=0
virtual int	setupLocalVideo (const VideoCanvas &canvas)=0
virtual int	setupRemoteVideo (const VideoCanvas &canvas)=0
virtual int	startPreview ()=0
virtual int	setRemoteUserPriority (uid_t uid, PRIORITY_TYPE userPriority)=0
virtual int	stopPreview ()=0
virtual int	enableAudio ()=0
virtual int	enableLocalAudio (bool enabled)=0
virtual int	disableAudio ()=0
virtual int	setAudioProfile (AUDIO_PROFILE_TYPE profile, AUDIO_SCENARIO_TYPE scenario)=0
virtual int	muteLocalAudioStream (bool mute)=0
virtual int	muteAllRemoteAudioStreams (bool mute)=0
virtual int	setDefaultMuteAllRemoteAudioStreams (bool mute)=0
virtual int	adjustUserPlaybackSignalVolume (unsigned int uid, int volume)=0
virtual int	muteRemoteAudioStream (uid_t userId, bool mute)=0
virtual int	muteLocalVideoStream (bool mute)=0
virtual int	enableLocalVideo (bool enabled)=0
virtual int	muteAllRemoteVideoStreams (bool mute)=0
virtual int	setDefaultMuteAllRemoteVideoStreams (bool mute)=0
virtual int	muteRemoteVideoStream (uid_t userId, bool mute)=0
virtual int	setRemoteVideoStreamType (uid_t uid, REMOTE_VIDEO_STREAM_TYPE streamType)=0
virtual int	setRemoteDefaultVideoStreamType (REMOTE_VIDEO_STREAM_TYPE streamType)=0
virtual int	takeSnapshot (const char* channel,uid_t uid,const char* filePath)=0
virtual int	enableAudioVolumeIndication (int interval, int smooth, bool report_vad)=0
virtual int	startAudioRecording (const char *filePath, AUDIO_RECORDING_QUALITY_TYPE quality)=0
virtual int	startAudioRecording (const char *filePath, int sampleRate, AUDIO_RECORDING_QUALITY_TYPE quality)=0
virtual int	stopAudioRecording ()=0
virtual int	startAudioMixing (const char *filePath, bool loopback, bool replace, int cycle)=0
virtual int	startAudioMixing (const char *filePath, bool loopback, bool replace, int cycle, int startPos)=0
virtual int	stopAudioMixing ()=0
virtual int	pauseAudioMixing ()=0
virtual int	resumeAudioMixing ()=0
virtual int	adjustAudioMixingVolume (int volume)=0
virtual int	adjustAudioMixingPlayoutVolume (int volume)=0
virtual int	getAudioMixingPlayoutVolume ()=0
virtual int	adjustAudioMixingPublishVolume (int volume)=0
virtual int	getAudioMixingPublishVolume ()=0
virtual int	getAudioMixingDuration ()=0
virtual int	getAudioMixingCurrentPosition ()=0
virtual int	setAudioMixingPosition (int pos)=0
virtual int	setAudioMixingPlaybackSpeed (int speed)=0
virtual int	selectAudioTrack (int index)=0
virtual int	getAudioTrackCount ()=0
virtual int	setAudioMixingDualMonoMode (ar::media::AUDIO_MIXING_DUAL_MONO_MODE mode)=0
virtual int	getEffectsVolume ()=0
virtual int	setEffectsVolume (int volume)=0
virtual int	setVolumeOfEffect (int soundId, int volume)=0
virtual int	playEffect (int soundId, const char *filePath, int loopCount, double pitch, double pan, int gain, bool publish=false)=0
virtual int	playEffect (int soundId, const char *filePath, int loopCount, double pitch, double pan, int gain, bool publish=false,int startPos)=0
virtual int	stopEffect (int soundId)=0
virtual int	stopAllEffects ()=0
virtual int	preloadEffect (int soundId, const char *filePath)=0
virtual int	unloadEffect (int soundId)=0
virtual int	pauseEffect (int soundId)=0
virtual int	pauseAllEffects ()=0
virtual int	resumeEffect (int soundId)=0
virtual int	resumeAllEffects ()=0
virtual int	enableSoundPositionIndication (bool enabled)=0
virtual int	setRemoteVoicePosition (int uid, double pan, double gain)=0
virtual int	setLocalVoicePitch (double pitch)=0
virtual int	setLocalVoiceEqualization (AUDIO_EQUALIZATION_BAND_FREQUENCY bandFrequency, int bandGain)=0
virtual int	setLocalVoiceReverb (AUDIO_REVERB_TYPE reverbKey, int value)=0
virtual int	setLocalVoiceChanger (VOICE_CHANGER_PRESET voiceChanger)=0
virtual int	setLocalVoiceReverbPreset (AUDIO_REVERB_PRESET reverbPreset)=0
virtual int	setLogFile (const char *filePath)=0
virtual int	setLogFilter (unsigned int filter)=0
virtual int	setLogFileSize (unsigned int fileSizeInKBytes)=0
virtual int	setLocalRenderMode (RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode)=0
virtual int	setRemoteRenderMode (uid_t uid, RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode)=0
virtual int	setLocalVideoMirrorMode (VIDEO_MIRROR_MODE_TYPE mirrorMode)=0
virtual int	enableDualStreamMode (bool enabled)=0
virtual int	setExternalAudioSource (bool enabled, int sampleRate, int channels)=0
virtual int	setExternalAudioSink (bool enabled, int sampleRate, int channels)=0
virtual int	setRecordingAudioFrameParameters (int sampleRate, int channel, RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall)=0
virtual int	setPlaybackAudioFrameParameters (int sampleRate, int channel, RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall)=0
virtual int	setMixedAudioFrameParameters (int sampleRate, int samplesPerCall)=0
virtual int	adjustRecordingSignalVolume (int volume)=0
virtual int	adjustPlaybackSignalVolume (int volume)=0
virtual int	setLocalPublishFallbackOption (STREAM_FALLBACK_OPTIONS option)=0
virtual int	setRemoteSubscribeFallbackOption (STREAM_FALLBACK_OPTIONS option)=0
virtual int	switchCamera ()=0
virtual int	setDefaultAudioRouteToSpeakerphone (bool defaultToSpeaker)=0
virtual int	setEnableSpeakerphone (bool speakerOn)=0
virtual int	enableInEarMonitoring (bool enabled)=0
virtual int	setInEarMonitoringVolume (int volume)=0
virtual bool	isSpeakerphoneEnabled ()=0
virtual int	setAudioSessionOperationRestriction (AUDIO_SESSION_OPERATION_RESTRICTION restriction)=0
virtual int	enableLoopbackRecording (bool enabled, const char *deviceName=NULL)=0
virtual int	startScreenCaptureByDisplayId (unsigned int displayId, const Rectangle &regionRect, const ScreenCaptureParameters &captureParams)=0
virtual int	startScreenCaptureByScreenRect (const Rectangle &screenRect, const Rectangle &regionRect, const ScreenCaptureParameters &captureParams)=0
virtual int	startScreenCaptureByWindowId (view_t windowId, const Rectangle &regionRect, const ScreenCaptureParameters &captureParams)=0
virtual int	setScreenCaptureContentHint (VideoContentHint contentHint)=0
virtual int	updateScreenCaptureParameters (const ScreenCaptureParameters &captureParams)=0
virtual int	updateScreenCaptureRegion (const Rectangle &regionRect)=0
virtual int	stopScreenCapture ()=0
virtual int	updateScreenCaptureRegion (const Rect *rect)=0
virtual bool	setVideoSource (IVideoSource *source)=0
virtual int	enableDeepLearningDenoise (bool enable)=0
virtual int	getCallId (ar::util::AString &callId)=0
virtual int	rate (const char callId, int rating, const char description)=0
virtual int	complain (const char callId, const char description)=0
virtual const char *	getVersion (int *build)=0
virtual int	enableLastmileTest ()=0
virtual int	disableLastmileTest ()=0
virtual int	startLastmileProbeTest (const LastmileProbeConfig &config)=0
virtual int	stopLastmileProbeTest ()=0
virtual const char *	getErrorDescription (int code)=0
virtual int	setEncryptionSecret (const char *secret)=0
virtual int	setEncryptionMode (const char *encryptionMode)=0
virtual int	registerPacketObserver (IPacketObserver *observer)=0
virtual int	createDataStream (int *streamId, bool reliable, bool ordered)=0
virtual int	sendStreamMessage (int streamId, const char *data, size_t length)=0
virtual int	addPublishStreamUrl (const char *url, bool transcodingEnabled)=0
virtual int	removePublishStreamUrl (const char *url)=0
virtual int	setLiveTranscoding (const LiveTranscoding &transcoding)=0
virtual int	addVideoWatermark (const char *watermarkUrl, const WatermarkOptions &options)=0
virtual int	clearVideoWatermarks ()=0
virtual int	setBeautyEffectOptions (bool enabled, BeautyOptions options)=0
virtual int	addInjectStreamUrl (const char *url, const InjectStreamConfig &config)=0
virtual int	startChannelMediaRelay (const ChannelMediaRelayConfiguration &configuration)=0
virtual int	updateChannelMediaRelay (const ChannelMediaRelayConfiguration &configuration)=0
virtual int	stopChannelMediaRelay ()=0
virtual int	removeInjectStreamUrl (const char *url)=0
virtual bool	registerEventHandler (IRtcEngineEventHandler *eventHandler)=0
virtual bool	unregisterEventHandler (IRtcEngineEventHandler *eventHandler)=0
virtual CONNECTION_STATE_TYPE	getConnectionState ()=0
virtual int	registerMediaMetadataObserver (IMetadataObserver *observer, IMetadataObserver::METADATA_TYPE type)=0

Protected 成员函数
virtual	~IRtcEngine ()

详细描述

IRtcEngine 类提供了供 App 调用的主要接口方法。

IRtcEngine 是 anyRTC Native SDK 的基础接口类。创建一个 IRtcEngine 对象并调用这个对象的方法可以激活 anyRTC Native SDK 的通信功能。

成员类型定义说明

WindowIDType

typedef unsigned int ar::rtc::IRtcEngine::WindowIDType

WindowIDType

typedef HWND ar::rtc::IRtcEngine::WindowIDType

~IRtcEngine

virtual ~IRtcEngine();

构造及析构函数说明

createARRtcEngine

AR_API ar::rtc::IRtcEngine* AR_CALL createARRtcEngine();

创建 IRtcEngine 对象并返回指针

IRtcEngine

返回值

指向 IRtcEngine 对象的指针。

注意事项：

目前 anyRTC Native SDK 只支持每个 app 创建一个 IArRtcEngine 对象。

initialize

virtual int initialize(const RtcEngineContext& context)

初始化 RTC SDK 服务

请确保在调用其他 API 前先调用 createARRtcEngine 和 initialize 创建并初始化 IArRtcEngine。

参数

参数	描述
context	详见 RtcEngineContext 。

返回值

0方法调用成功
<0方法调用失败。
- ERR_INVALID_APP_ID(101)：不是有效的 App ID。请更换有效的 App ID 重新初始化。建议你检查 App ID 的格式是否有效。

release

virtual void release(bool sync = false)

销毁 IRtcEngine 对象

如果重启通话，必须在本方法执行结束后再调用 initialize 重新创建 IRtcEngine。

参数

参数	描述
sync	-\ true: 同步调用。在等待 IRtcEngine 对象资源释放后再返回。App 不应该在 SDK 产生的回调中调用该接口，否则由于 SDK 要等待回调返回才能回收相关的对象资源，会造成死锁。SDK 会自动检测这种死锁并转为异步调用，但是检测本身会消耗额外的时间。 -\ false: 异步调用。不等 IRtcEngine 对象资源释放就立即返回。SDK 会自行释放所有资源。使用异步调用时要注意，不要在该调用后立即卸载 SDK 动态库，否则可能会因为 SDK 的清理线程还没有退出而崩溃。

描述

sync

-\ true: 同步调用。在等待 IRtcEngine 对象资源释放后再返回。App 不应该在 SDK 产生的回调中调用该接口，否则由于 SDK 要等待回调返回才能回收相关的对象资源，会造成死锁。SDK 会自动检测这种死锁并转为异步调用，但是检测本身会消耗额外的时间。 -\ false: 异步调用。不等 IRtcEngine 对象资源释放就立即返回。SDK 会自行释放所有资源。使用异步调用时要注意，不要在该调用后立即卸载 SDK 动态库，否则可能会因为 SDK 的清理线程还没有退出而崩溃。

setChannelProfile

virtual int setChannelProfile(AR::CHANNEL_PROFILE_TYPE profile);

设置频道场景

该方法用于设置 anyRTC IRtcEngine 频道的使用场景。RtcEngine 会针对不同的使用场景采用不同的优化策略，如通信场景偏好流畅，直播场景偏好画质。

为保证实时音视频质量，我们建议相同频道内的用户使用同一种频道场景。

该方法必须在 joinChannel 前调用和进行设置，进入频道后无法再设置。

参数

参数	描述
profile	频道使用场景: CHANNEL_PROFILE_TYPE

返回值

0方法调用成功，<0方法调用失败。

setClientRole

virtual int setClientRole(AR::CLIENT_ROLE_TYPE role);

设置直播场景下的用户角色

在加入频道前，用户需要通过本方法设置观众（默认）或主播。在加入频道后，用户可以通过本方法切换用户角色。直播场景下，如果你在加入频道后调用该方法切换用户角色，调用成功后，本地会触发 onClientRoleChanged 回调；远端会触发 onUserJoined 回调或 onUserOffline (BECOME_AUDIENCE) 回调。

参数

参数	描述
role	直播场景里的用户角色: CLIENT_ROLE_TYPE 。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

该方法仅适用于直播场景。

joinChannel

virtual int joinChannel(const char* token, const char* channelId, const char* info, AR::uid_t uid);

加入频道

该方法让用户加入通话频道，在同一个频道内的用户可以互相通话，多个用户加入同一个频道，可以群聊。使用不同 App ID 的 App 是不能互通的。如果已在通话中，用户必须调用 leaveChannel 退出当前通话，才能进入下一个频道。成功调用该方加入频道后，本地会触发onJoinChannelSuccess 回调；通信场景下的用户和直播场景下的主播加入频道后，远端会触发onUserJoined 回调。在网络状况不理想的情况下，客户端可能会与 anyRTC 的服务器失去连接；SDK 会自动尝试重连，重连成功后，本地会触发 onRejoinChannelSuccess 回调。

参数

参数	描述
token	动态秘钥。安全要求不高: 将值设为 NULL。安全要求高: 将值设置为 Token。如果你已经启用了 App Certificate, 请务必使用 Token。
channelId	标识通话的频道名称，该字符串不可超过 64 字节。不可设为空、null 或 "null"。以下为支持的字符集范围: 26 个小写英文字母 a-z 26 个大写英文字母 A-Z 10 个数字 0-9 空格 "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "~", ",","¦"
info	(非必选项) 开发者需加入的任何附加信息。一般可设置为空字符串，或频道相关信息。该信息不会传递给频道内的其他用户。
uid	(非必选项) 用户ID，长度在64字节以内的字符串，并保证频道内唯一性。如果不填或设置为nil，SDK 会自动分配一个，并在 onJoinChannelSuccess 回调方法中返回，App 层必须记住该返回值并维护，SDK 不对该返回值进行维护。以下为支持的字符集范围: 26 个小写英文字母 a-z 26 个大写英文字母 A-Z 10 个数字 0-9 空格 "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "~", ",","¦"

返回值

0方法调用成功，<0方法调用失败。

注意事项：

频道内每个用户的用户 ID 必须是唯一的。如果将 uid 设为 0，系统将自动分配一个 uid。如果想要从不同的设备同时接入同一个频道，请确保每个设备上使用的 uid 是不同的。

请务必确保用于生成 Token 的 App ID 和 initialize 方法初始化引擎时用的是同一个 App ID，否则会造成旁路推流失败。

switchChannel

virtual int switchChannel(const char* token, const char* channelId);

快速切换直播频道

当直播频道中的观众想从一个频道切换到另一个频道时，可以调用该方法，实现快速切换。

成功调用该方切换频道后，本地会先收到离开原频道的回调 onLeaveChannel，再收到成功加入新频道的回调 onJoinChannelSuccess。

参数

参数	描述
token	动态秘钥。安全要求不高: 将值设为 NULL。安全要求高: 将值设置为 Token。如果你已经启用了 App Certificate, 请务必使用 Token。
channelId	标识通话的频道名称，长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符): 26 个小写英文字母 az； 26 个大写英文字母 AZ； 10个数字 0~9；空格； "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、" {"、"}"、"

返回值

0方法调用成功，<0方法调用失败。

注意事项：

该方法仅适用于直播场景中，角色为观众的用户。

leaveChannel

virtual int leaveChannel();

离开频道

离开频道，即挂断或退出通话。

当调用 joinChannel 方法后，必须调用 leaveChannel 结束通话，否则无法开始下一次通话。不管当前是否在通话中，都可以调用 leaveChannel，没有副作用。该方法会把会话相关的所有资源释放掉。该方法是异步操作，调用返回时并没有真正退出频道。在真正退出频道后，SDK 会触发 onLeaveChannel 回调。成功调用该方法离开频道后，本地会触发 onLeaveChannel 回调；通信场景下的用户和直播场景下的主播离开频道后，远端会触发 onUserOffline 回调。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

如果你调用了 leaveChannel 后立即调用 release，SDK 将无法触发 onLeaveChannel 回调。

-如果你在旁路推流时调用 leaveChannel 方法， SDK 将自动调用 removePublishStreamUrl 方法。

renewToken

virtual int renewToken(const char* token);

更新Token

该方法用于更新 Token。如果启用了 Token 机制，过一段时间后使用的 Token 会失效。当：

发生 [onTokenPrivilegeWillExpire](ar_rtc_win_engine_handler

title: RTCEngineHandler#ontokenprivilegewillexpire) 回调时，或发生

[onConnectionStateChanged](ar_rtc_win_engine_handler

title: RTCEngineHandler#onconnectionstatechanged) 回调报告 CONNECTION_CHANGED_TOKEN_EXPIRED(9) 时。 App 应重新获取 Token，然后调用该方法更新 Token，否则 SDK 无法和服务器建立连接。

参数

参数	描述
token	新的 Token。

返回值

0方法调用成功，<0方法调用失败。

queryInterface

virtual int queryInterface(INTERFACE_ID_TYPE iid, void** inter) = 0;

获取设备管理员对象的指针。

参数

参数	描述
iid	想要获取的接口的接口。
inter	指向 DeviceManager 对象的指针。

返回值

0方法调用成功，<0方法调用失败。

startEchoTest

virtual int startEchoTest(int intervalInSeconds) = 0;

开始语音通话回路测试

该方法启动语音通话测试，目的是测试系统的音频设备（耳麦、扬声器等）和网络连接是否正常。在测试过程中，用户先说一段话，声音会在设置的时间间隔（单位为秒）后回放出来。如果用户能正常听到自己刚才说的话，就表示系统音频设备和网络连接都是正常的。

请在加入频道前调用该方法。
调用 startEchoTest 后必须调用 stopEchoTest 以结束测试，否则不能进行下一次回声测试，也无法加入频道。
直播场景下，该方法仅能由用户角色为主播的用户调用。

参数

参数	描述
intervalInSeconds	设置返回语音通话回路测试结果的时间间隔，取值范围为 [2, 10]，单位为秒，默认为 10 秒。

返回值

0方法调用成功，<0方法调用失败。

stopEchoTest

virtual int stopEchoTest() = 0;

停止语音通话回路测试。

返回值

0方法调用成功，<0方法调用失败。

enableVideo

virtual int enableVideo() = 0;

启用视频模块

该方法可以在加入频道前或者通话中调用，在加入频道前调用则自动开启视频模块；在通话中调用则由音频模式切换为视频模式。调用 disableVideo 方法可关闭视频模式。成功调用该方法后，远端会触发 onUserEnableVideo (true) 回调。

该方法设置内部引擎为启用状态，在 leaveChannel 后仍然有效。
该方法重置整个引擎，响应时间较慢，因此anyRTC建议使用如下方法来控制视频模块：
- enableLocalVideo: 是否启动摄像头采集并创建本地视频流。
- muteLocalVideoStream: 是否发布本地视频流。
- muteRemoteVideoStream: 是否接收并播放远端视频流。
- muteAllRemoteVideoStreams: 是否接收并播放所有远端视频流。

返回值

0方法调用成功，<0方法调用失败。

disableVideo

virtual int disableVideo() = 0;

关闭视频模块

该方法可以在加入频道前或者通话中调用，在加入频道前调用，则自动开启纯音频模式，在通话中调用则由视频模式切换为纯音频频模式。调用 enableVideo 方法可开启视频模式。成功调用该方法后，远端会触发 onUserEnableVideo (false) 回调

该方法设置内部引擎为启用状态，在 leaveChannel 后仍然有效。
该方法重置整个引擎，响应时间较慢，因此anyRTC建议使用如下方法来控制视频模块：
- enableLocalVideo: 是否启动摄像头采集并创建本地视频流。
- muteLocalVideoStream: 是否发布本地视频流。
- muteRemoteVideoStream: 是否接收并播放远端视频流。
- muteAllRemoteVideoStreams: 是否接收并播放所有远端视频流。

返回值

0方法调用成功，<0方法调用失败。

setVideoEncoderConfiguration

virtual int setVideoEncoderConfiguration(const VideoEncoderConfiguration& config) = 0;

设置视频编码属性

设置本地视频的编码属性。

参数

参数	描述
config	视频编码参数配置。详见: VideoEncoderConfiguration 。

返回值

0方法调用成功，<0方法调用失败。

setCameraCapturerConfiguration

virtual int setCameraCapturerConfiguration(const CameraCapturerConfiguration& config) = 0;

设置摄像头采集偏好

一般的视频通话或直播中，默认由 SDK 自动控制摄像头的输出参数。在如下特殊场景中，默认的参数通常无法满足需求，或可能引起设备性能问题，我们推荐调用该方法设置摄像头的采集偏好：

使用原始音视频数据自采集接口时，如果 SDK 输出的分辨率和帧率高于 setVideoEncoderConfiguration 中指定的参数，在后续处理视频帧的时候，比如美颜功能时，会需要更高的 CPU 及内存，容易导致性能问题。在这种情况下，我们推荐将摄像头采集偏好设置为 CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE = 1，避免性能问题。
如果没有本地预览功能或者对预览质量没有要求，我们推荐将采集偏好设置为 CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE = 1，以优化 CPU 和内存的资源分配。
如果用户希望本地预览视频比实际编码发送的视频清晰，可以将采集偏好设置为 CAPTURER_OUTPUT_PREFERENCE_PREVIEW = 2。

参数

参数	描述
config	摄像头采集偏好，详见 CameraCapturerConfiguration 。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

请在启动摄像头之前调用该方法，如 joinChannel，enableVideo 或者 enableLocalVideo 之前。

setupLocalVideo

virtual int setupLocalVideo(const VideoCanvas& canvas) = 0;

初始化本地视图

该方法初始化本地视图并设置本地用户视频显示信息，只影响本地用户看到的视频画面，不影响本地发布视频。调用该方法绑定本地视频流的显示视窗(view)，并设置本地用户视图的渲染模式和镜像模式。

在 App 开发中，通常在初始化后调用该方法进行本地视频设置，然后再加入频道。退出频道后，绑定仍然有效，如果需要解除绑定，可以指定空(NULL)View 调用 setupLocalVideo。

参数

参数	描述
config	摄像头采集偏好，详见 CameraCapturerConfiguration 。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

建议你在加入频道前调用该方法。

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

setupRemoteVideo

virtual int setupRemoteVideo(const VideoCanvas& canvas) = 0;

初始化远端用户视图

该方法绑定远端用户和显示视图，并设置远端用户视图在本地显示时的渲染模式和镜像模式，只影响本地用户看到的视频画面。调用该接口时需要指定远端视频的 uid，一般可以在进频道前提前设置好。

如果 App 不能事先知道对方的 uid，可以在 APP 收到 onUserJoined 事件时设置。如果启用了视频录制功能，视频录制服务会做为一个哑客户端加入频道，因此其他客户端也会收到它的 onUserJoined 事件，App 不应给它绑定视图（因为它不会发送视频流），如果 App 不能识别哑客户端，可以在 onFirstRemoteVideoDecoded 事件时再绑定视图。解除某个用户的绑定视图可以把 view 设置为空。退出频道后，SDK 会把远端用户的绑定关系清除掉。

参数

参数	描述
canvas	视频画布信息: VideoCanvas 。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

如果你希望在通话中更新远端用户视图的渲染或镜像模式，请使用 setRemoteRenderMode 方法。

startPreview

virtual int startPreview() = 0;

初始化远端用户视图

该方法用于在进入频道前启动本地视频预览。调用该 API 前，必须：

调用 setupLocalVideo 设置预览窗口及属性；
调用 enableVideo 开启视频功能。

启用了本地视频预览后，如果调用 leaveChannel 退出频道，本地预览依然处于启动状态，如需要关闭本地预览，需要调用 stopPreview。

返回值

0方法调用成功，<0方法调用失败。

setRemoteUserPriority

virtual int setRemoteUserPriority(uid_t uid, PRIORITY_TYPE userPriority) = 0;

设置远端用户流的优先级

设置远端用户的优先级。如果将某个用户的优先级设为高，那么发给这个用户的音视频流的优先级就会高于其他用户。该方法可以与 setRemoteSubscribeFallbackOption 搭配使用。如果开启了订阅流回退选项，弱网下 SDK 会优先保证高优先级用户收到的流的质量。

参数

参数	描述
userPriority	远端用户的需求优先级。详见: PRIORITY_TYPE 。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

目前 anyRTC SDK 仅允许将一名远端用户设为高优先级。

stopPreview

virtual int stopPreview() = 0;

停止视频预览。

返回值

0方法调用成功，<0方法调用失败。

enableAudio

irtual int enableAudio() = 0;

启用音频模块

启用音频模块（默认为开启状态）。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

该方法设置内部引擎为启用状态，在频道内和频道外均可调用。在 leaveChannel 后仍然有效。

该方法重置整个引擎，响应时间较慢，因此anyRTC建议使用如下方法来控制音频模块：

enableLocalAudio: 是否启动麦克风采集并创建本地音频流。

muteLocalAudioStream: 是否发布本地音频流。

muteRemoteAudioStream: 是否接收并播放远端音频流。

muteAllRemoteAudioStreams: 是否接收并播放所有远端音频流。

enableLocalAudio

irtual int enableLocalAudio(bool enabled) = 0;

开关本地音频采集

当用户加入频道时，语音功能默认是开启的。该方法可以关闭或重新开启本地语音功能，即停止或重新开始本地音频采集。该方法不影响接收或播放远端音频流，enableLocalAudio(false) 适用于只听不发的用户场景。语音功能关闭或重新开启后，会收到回调 onMicrophoneEnabled。

参数

参数	描述
enabled	true: 重新开启本地语音功能，即开启本地语音采集（默认）； false: 关闭本地语音功能，即停止本地语音采集。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

该方法与 muteLocalAudioStream 的区别在于：

enableLocalAudio: 开启或关闭本地语音采集及处理。使用 enableLocalAudio 关闭或开启本地采集后，本地听远端播放会有短暂中断。

muteLocalAudioStream: 停止或继续发送本地音频流。

disableAudio

irtual int disableAudio() = 0;

关闭音频模块

返回值

0方法调用成功，<0方法调用失败。

注意事项：

该方法设置内部引擎为禁用状态，在频道内和频道外均可调用。在 leaveChannel 后仍然有效。该方法重置整个引擎，响应时间较慢，因此anyRTC建议使用如下方法来控制音频模块:

enableLocalAudio: 是否启动麦克风采集并创建本地音频流。

muteLocalAudioStream: 是否发布本地音频流。

muteRemoteAudioStream: 是否接收并播放远端音频流。

muteAllRemoteAudioStreams: 是否接收并播放所有远端音频流。

setAudioProfile

virtual int setAudioProfile(AUDIO_PROFILE_TYPE profile, AUDIO_SCENARIO_TYPE scenario) = 0;

设置音频编码属性

参数

参数	描述
profile	设置采样率，码率，编码模式和声道数: AUDIO_PROFILE_TYPE 。
scenario	设置音频应用场景: AUDIO_SCENARIO_TYPE 。不同的音频场景下，设备的系统音量是不同的。详见如何区分媒体音量和通话音量。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

该方法需要在 joinChannel 之前设置好， joinChannel 之后设置不生效。

通信和直播场景下，音质（码率）会有网络自适应的调整，通过该方法设置的是一个最高码率。

在有高音质需求的场景（例如音乐教学场景）中，建议将 profile 设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY (4)，scenario 设置为 AUDIO_SCENARIO_GAME_STREAMING (3)。

muteLocalAudioStream

virtual int muteLocalAudioStream(bool mute) = 0;

开关本地音频发送

该方法用于允许/禁止往网络发送本地音频流。成功调用该方法后，远端会触发 onUserMuteAudio 回调。

参数

参数	描述
mute	true: 停止发送本地音频流； false: 继续发送本地音频流（默认）。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

该方法不影响录音状态，因为并没有禁用录音设备。

如果你在该方法后调用 setChannelProfile 方法，SDK 会根据你设置的频道场景以及用户角色，重新设置是否停止发送本地音频。因此我们建议在 setChannelProfile 后调用该方法。

muteAllRemoteAudioStreams

virtual int muteAllRemoteAudioStreams(bool mute) = 0;

接收／停止接收所有音频流

该方法用于允许/禁止往网络发送本地音频流。成功调用该方法后，远端会触发 onUserMuteAudio 回调。

参数

参数	描述
mute	true: 停止接收所有音频流； false: 继续接收所有音频流（默认）。

返回值

0方法调用成功，<0方法调用失败。

setDefaultMuteAllRemoteAudioStreams

virtual int setDefaultMuteAllRemoteAudioStreams(bool mute) = 0;

设置是否默认接收所有音频流

该方法在加入频道前后都可调用。如果在加入频道后调用 setDefaultMuteAllRemoteAudioStreams(true)，会接收不到后面加入频道的用户的音频流。

参数

参数	描述
mute	true: 默认停止接收所有音频流； false: 默认接收所有音频流（默认）。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

停止接收音频流后，如果想要恢复接收，请调用 muteRemoteAudioStream(false)，并指定你想要接收的远端用户的 ID。如果想恢复接收多个用户的音频流，则需要多次调用 muteRemoteAudioStream。

setDefaultMuteAllRemoteAudioStreams(false) 只能恢复接收后面加入频道的用户的音频流。

adjustUserPlaybackSignalVolume

virtual int adjustUserPlaybackSignalVolume(AR::uid_t uid, int volume) = 0;

调节本地播放的指定远端用户音量

你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的音量，则需多次调用该方法。

参数

参数	描述
uid	远端用户 ID。
volume	播放音量，取值范围为 [0,100]: 0: 静音 100: 原始音量

返回值

0方法调用成功，<0方法调用失败。

注意事项：

请在加入频道后，调用该方法。

该方法调节的是本地播放的指定远端用户混音后的音量。

muteRemoteAudioStream

virtual int muteRemoteAudioStream(uid_t uid, bool mute) = 0;

接收／停止接收指定音频流。

你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的音量，则需多次调用该方法。

参数

参数	描述
uid	指定用户的 ID
mute	true: 停止接收指定音频流； false: 继续接收指定音频流（默认）。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

如果之前有调用过 muteAllRemoteAudioStreams (true) 停止订阅所有远端音频，在调用本 API 之前请确保你已调用 muteAllRemoteAudioStreams (false)。 muteAllRemoteAudioStreams 是全局控制，muteRemoteAudioStream 是精细控制。

muteLocalVideoStream

virtual int muteLocalVideoStream(bool mute) = 0;

开关本地视频发送

成功调用该方法后，远端会触发 onUserMuteVideo 回调。

参数

参数	描述
mute	true: 不发送本地视频流; false: 发送本地视频流（默认）。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

如调用该方法时，SDK 不再发送本地视频流，但摄像头仍然处于工作状态。相比于 enableLocalVideo (false) 用于控制本地视频流发送的方法，该方法响应速度更快。该方法不影响本地视频流获取，没有禁用摄像头。

如果你在该方法后调用 setChannelProfile 方法，SDK 会根据你设置的频道场景以及用户角色，重新设置是否停止发送本地视频。因此我们建议在 setChannelProfile 后调用该方法。

enableLocalVideo

virtual int enableLocalVideo(bool enabled) = 0;

开关本地视频采集

该方法禁用或重新启用本地视频采集，不影响接收远端视频。

调用 enableVideo 后，本地视频即默认开启。你可以调用 enableLocalVideo(false) 关闭本地视频采集。关闭后如果想要重新开启，则可调用 enableLocalVideo(true)。

成功禁用或启用本地视频采集后，远端会触发 onUserEnableLocalVideo 回调。

参数

参数	描述
enabled	true: 开启本地视频采集和渲染 (默认)； false: 关闭使用本地摄像头设备。关闭后，远端用户会接收不到本地用户的视频流；但本地用户依然可以接收远端用户的视频流。设置为 false 时，该方法不需要本地有摄像头。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

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

muteAllRemoteVideoStreams

virtual int muteAllRemoteVideoStreams(bool mute) = 0;

接收／停止接收所有远端视频流

参数

参数	描述
mute	true: 停止接收所有远端视频流； false: 允许接收所有远端视频流（默认）。

返回值

0方法调用成功，<0方法调用失败。

setDefaultMuteAllRemoteVideoStreams

virtual int setDefaultMuteAllRemoteVideoStreams(bool mute) = 0;

设置是否默认停止接收视频流

该方法在加入频道前后都可调用。如果在加入频道后调用 setDefaultMuteAllRemoteVideoStreams (true)，会接收不到设置后加入频道的用户的视频流。

参数

参数	描述
mute	true: 默认停止接收所有远端视频； false: 默认接收所有远端视频（默认）。

返回值

0方法调用成功，<0方法调用失败。

停止接收视频流后，如果想要恢复接收，请调用 muteRemoteVideoStream (false)，并指定你想要接收的远端用户 uid；如果想恢复接收多个用户的视频流，则需要多次调用 muteRemoteVideoStream。

setDefaultMuteAllRemoteVideoStreams (false) 只能恢复接收后面加入频道的用户的视频流。

muteRemoteVideoStream

virtual int muteRemoteVideoStream(uid_t uid, bool mute) = 0;

接收／停止接收指定远端用户的视频流。

参数

参数	描述
uid	指定用户的用户 ID。
mute	true: 停止接收指定远端用户的视频流； false: 允许接收指定远端用户的视频流（默认）。

返回值

0方法调用成功，<0方法调用失败。

如果之前调用过 muteAllRemoteVideoStreams (true) 停止接收放所有远端视频流，在调用本 API 之前请确保你已调用 muteAllRemoteVideoStreams (false) 。muteAllRemoteVideoStreams 是全局控制，muteRemoteVideoStream 是精细控制。

setRemoteVideoStreamType

virtual int setRemoteVideoStreamType(uid_t uid, REMOTE_VIDEO_STREAM_TYPE streamType) = 0;

设置订阅的视频流类型

在网络条件受限的情况下，如果发送端没有调用 enableDualStreamMode (false) 关闭双流模式，接收端可以选择接收大流还是小流。其中，大流可以接为高分辨率高码率的视频流，小流则是低分辨率低码率的视频流。正常情况下，用户默认接收大流。如需接收小流，可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小，以节约带宽和计算资源。视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比，系统会自动分配小流的分辨率、帧率及码率。调用本方法的执行结果将在 onApiCallExecuted 中返回。

参数

参数	描述
uid	用户 ID。
streamType	视频流类型: REMOTE_VIDEO_STREAM_TYPE 。

返回值

0方法调用成功，<0方法调用失败。

setRemoteDefaultVideoStreamType

virtual int setRemoteDefaultVideoStreamType(REMOTE_VIDEO_STREAM_TYPE streamType) = 0;

设置默认订阅的视频流类型

在网络条件受限的情况下，如果发送端没有调用 enableDualStreamMode (false) 关闭双流模式，接收端可以选择接收大流还是小流。其中，大流可以接为高分辨率高码率的视频流，小流则是低分辨率低码率的视频流。

正常情况下，用户默认接收大流。如需默认接收所有用户的视频小流，可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小，以节约带宽和计算资源。视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比，系统会自动分配小流的分辨率、帧率及码率。

调用本方法的执行结果将在 onApiCallExecuted 中返回。

参数

参数	描述
streamType	视频流类型: REMOTE_VIDEO_STREAM_TYPE 。

返回值

0方法调用成功，<0方法调用失败。

takeSnapshot

virtual int takeSnapshot(const char* channel,uid_t uid, const char* filePath) = 0;

获取视频截图

该方法用于对指定用户的视频流进行截图，生成一张 JPG 格式的图片，并保存至指定的路径。

该方法是异步操作，调用返回时 SDK 并没有真正获取截图。成功调用该方法后，SDK 会触发 onSnapshotTaken 回调报告截图是否成功和获取截图的详情。

参数

参数	描述
channel	频道。
uid	用户 ID。（暂不支持对本地截图）如果要对本地用户的视频截图，填写自己的uid 即可。
filePath	截图的本地保存路径，需精确到文件名及格式。

返回值

0方法调用成功，<0方法调用失败。

enableAudioVolumeIndication

virtual int enableAudioVolumeIndication(int interval, int smooth, bool report_vad) = 0;

启用说话者音量提示

该方法允许 SDK 定期向 App 反馈当前谁在说话以及说话者的音量。启用该方法后，无论频道内是否有人说话，都会在 onAudioVolumeIndication 回调中按设置的间隔时间返回音量提示。

参数

参数	描述
interval	指定音量提示的时间间隔： ≤ 0: 禁用音量提示功能； > 0: 返回音量提示的间隔，单位为毫秒。建议设置到大于 200 毫秒。最小不得少于 10 毫秒，否则会收不到 onAudioVolumeIndication 回调。
smooth	平滑系数，指定音量提示的灵敏度。取值范围为 [0,10]，建议值为 3。数字越大，波动越灵敏；数字越小，波动越平滑。
report_vad	true：开启本地人声检测功能。开启后，onAudioVolumeIndication 回调的 vad 参数会报告是否在本地检测到人声。 false：（默认）关闭本地人声检测功能。除引擎自动进行本地人声检测的场景外，onAudioVolumeIndication 回调的 vad 参数不会报告是否在本地检测到人声。

返回值

0方法调用成功，<0方法调用失败。

startAudioRecording

virtual int startAudioRecording(const char* filePath, int sampleRate, AUDIO_RECORDING_QUALITY_TYPE quality) = 0;

开始客户端录音

anyRTC SDK 支持通话过程中在客户端进行录音。调用该方法后，你可以录制频道内所有用户的音频，并得到一个包含所有用户声音的录音文件。录音文件格式可以为:

.wav: 文件大，音质保真度较高。
.aac: 文件小，音质保真度较低。

参数

参数	描述
filePath	录音文件在本地保存的绝对路径，由用户自行指定，需精确到文件名及格式，例如：c:/music/audio.aac。
sampleRate	录音采样率（Hz），可以设为以下值： 16000 32000 441000 48000
quality	录音音质。详见 AUDIO_RECORDING_QUALITY_TYPE 。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

请确保你在该方法中指定的路径存在并且可写。

该接口需在 joinChannel 之后调用。如果调用 leaveChannel 时还在录音，录音会自动停止。

为保证录音效果，当 sampleRate 设为 44.1 kHz 或 48 kHz 时，建议将 quality 设为 AUDIO_RECORDING_QUALITY_MEDIUM 或 AUDIO_RECORDING_QUALITY_HIGH 。

stopAudioRecording

virtual int stopAudioRecording() = 0;

停止客户端录音

停止录音。该接口需要在 leaveChannel 之前调用，不然会在调用 leaveChannel 时自动停止。

返回值

0方法调用成功，<0方法调用失败。

startAudioMixing【1/2】

virtual int startAudioMixing(const char* filePath, bool loopback, bool replace, int cycle) = 0;

开始播放音乐文件

指定本地或在线音频文件来和麦克风采集的音频流进行混音和替换。替换是指用音频文件替换录音设备采集的音频流。该方法可以选择是否让对方听到本地播放的音频并指定循环播放的次数。成功调用该方法后，本地会触发 onAudioMixingStateChanged (PLAY) 回调。播放结束后，会收到 onAudioMixingStateChanged (STOPPED) 回调。

参数

参数	描述
filePath	指定需要混音的本地或在线音频文件的绝对路径，例如：c:/music/audio.mp4。建议填写文件后缀名。若无法确定文件后缀名，可不填。支持的音频格式包括：3GP、ASF、ADTS、AVI、MP3、MP4、MPEG-4、SAMI 和 WAVE。详见 Supported Media Formats in Media Foundation 。
loopback	true: 只有本地用户可以听到混音的音频； false: 本地用户和远端用户都能听到混音的音频。
replace	true: 只推送指定的本地音频文件或者线上音频文件，不传输麦克风收录的音频。 false: 本地音频文件与来自麦克风的音频流混音。
cycle	循环播放次数：正整数: 循环播放的次数； -1: 无限循环。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

请在频道内调用该方法，如果在频道外调用该方法可能会出现问题。

如果本地音乐文件不存在、文件格式不支持、无法访问在线音乐文件 URL 都会返回警告码 WARN_AUDIO_MIXING_OPEN_ERROR = 701。

startAudioMixing【2/2】

virtual int startAudioMixing(const char* filePath, bool loopback, bool replace, int cycle,int startPos) = 0;

开始播放音乐文件

自从
v4.3.0

该方法支持将本地或在线音乐文件和麦克风采集的音频进行混音或替换。成功播放音乐文件后，本地会触发onAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING,AUDIO_MIXING_REASON_STARTED_BY_USER) 回调。播放结束后，本地会触发 onAudioMixingStateChanged(AUDIO_MIXING_STATE_STOPPED,AUDIO_MIXING_REASON_ALL_LOOPS_COMPLETED) 回调。

注解

如需多次调用 startAudioMixing，请确保调用间隔大于 500 ms。
如果本地音乐文件不存在、文件格式不支持或无法访问在线音乐文件 URL，则 SDK 会报告 WARN_AUDIO_MIXING_OPEN_ERROR(701)。

参数

参数	描述
filePath	指定需要混音的本地或在线音频文件的绝对路径，例如：c:/music/audio.mp4。建议填写文件后缀名。若无法确定文件后缀名，可不填。支持的音频格式包括：3GP、ASF、ADTS、AVI、MP3、MP4、MPEG-4、SAMI 和 WAVE。详见 Supported Media Formats in Media Foundation 。
loopback	true: 只有本地用户可以听到混音的音频； false: 本地用户和远端用户都能听到混音的音频。
replace	true: 只推送指定的本地音频文件或者线上音频文件，不传输麦克风收录的音频。 false: 本地音频文件与来自麦克风的音频流混音。
cycle	循环播放次数：正整数: 循环播放的次数； -1: 无限循环。
startPoss	音乐文件的播放位置，单位为毫秒。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

请在频道内调用该方法，如果在频道外调用该方法可能会出现问题。

如果本地音乐文件不存在、文件格式不支持、无法访问在线音乐文件 URL 都会返回警告码 WARN_AUDIO_MIXING_OPEN_ERROR = 701。

stopAudioMixing

virtual int stopAudioMixing() = 0;

停止播放音乐文件

该方法停止播放音乐文件。请在频道内调用该方法。

返回值

0方法调用成功，<0方法调用失败。

pauseAudioMixing

virtual int pauseAudioMixing() = 0;

暂停播放音乐文件

该方法暂停播放音乐文件。请在频道内调用该方法。

返回值

0方法调用成功，<0方法调用失败。

resumeAudioMixing

virtual int resumeAudioMixing() = 0;

恢复播放音乐文件

该方法恢复混音，继续播放音乐文件。请在频道内调用该方法。

返回值

0方法调用成功，<0方法调用失败。

adjustAudioMixingVolume

virtual int adjustAudioMixingVolume(int volume) = 0;

调节音乐文件的播放音量

该方法调节混音音乐文件在本端和远端的播放音量大小。请在频道内调用该方法。

参数

参数	描述
volume	音乐文件音量范围为 0~100。100 （默认值）为原始文件音量。

返回值

0方法调用成功，<0方法调用失败。

注意事项：

调用该方法不影响调用 playEffect 播放音效文件的音量。

adjustAudioMixingPlayoutVolume

virtual int adjustAudioMixingPlayoutVolume(int volume) = 0;

调节音乐文件本端播放音量。

该方法调节混音音乐文件在本端的播放音量大小。请在频道内调用该方法。

参数

参数	描述
volume	音乐文件音量范围为 0~100。100 （默认值）为原始文件音量。

返回值

0方法调用成功，<0方法调用失败。

getAudioMixingPlayoutVolume

virtual int getAudioMixingPlayoutVolume() = 0;

获取音乐文件的本地播放音量。

该方法获取混音的音乐文件本地播放音量，方便排查音量相关问题。

参数

参数	描述
volume	音乐文件音量范围为 0~100。100 （默认值）为原始文件音量。

返回值

=0方法调用成功则返回音量值，范围为 [0,100]; <0方法调用失败。

注意事项：

请在频道内调用该方法。

adjustAudioMixingPublishVolume

virtual int adjustAudioMixingPublishVolume(int volume) = 0;

调节音乐文件远端播放音量

该方法调节混音音乐文件在远端的播放音量大小。请在频道内调用该方法。

参数

参数	描述
volume	音乐文件音量范围为 0~100。100 （默认值）为原始文件音量。

返回值

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

getAudioMixingPublishVolume

virtual int getAudioMixingPublishVolume() = 0;

获取音乐文件的远端播放音量

该接口可以方便开发者排查音量相关问题。

返回值

≥ 0：方法调用成功则返回音量值，范围为 [0, 100];< 0：方法调用失败

注意事项：

请在频道内调用该方法。

getAudioMixingDuration

virtual int getAudioMixingDuration() = 0;

获取音乐文件总时长

该方法获取音乐文件总时长，单位为毫秒。请在频道内调用该方法。

返回值

≥ 0: 方法调用成功返回音乐文件时长;< 0: 方法调用失败

getAudioMixingCurrentPosition

virtual int getAudioMixingCurrentPosition() = 0;

获取音乐文件的播放进度

该方法获取当前音乐文件播放进度，单位为毫秒。请在频道内调用该方法。

返回值

≥ 0: 方法调用成功返回音乐文件播放进度;< 0: 方法调用失败

setAudioMixingPosition

virtual int setAudioMixingPosition(int pos /in ms/) = 0;

设置音乐文件的播放位置

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

参数

参数	描述
pos	整数。进度条位置，单位为毫秒。

返回值

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

setAudioMixingPlaybackSpeed

virtual int setAudioMixingPlaybackSpeed(int speed) = 0;

设置当前音乐文件的播放速度

自从

v4.3.0 你需要在调用 startAudioMixing [2/2] 并收到 onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) 回调后调用该方法。

参数

参数	描述
speed	播放速度。推荐取值范围为 [50,400]，其中： 50: 0.5 倍速。 100: 原始速度。 400: 4 倍速。

返回值

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

selectAudioTrack

virtual int selectAudioTrack(int index) = 0;

指定当前音乐文件的播放音轨

自从

v4.3.0 获取音乐文件的音轨索引后，你可以调用该方法指定任一音轨进行播放。例如，如果一个多音轨文件的不同音轨存放了不同语言的歌曲，则你可以调用该方法设置音乐文件的播放语言。

注意

你需要在调用 startAudioMixing [2/2] 并收到 onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) 回调后调用该方法。
该方法仅适用于 Android、iOS 和 Windows。

参数

参数	描述
index	指定的播放音轨。该参数需小于或等于 getAudioTrackCount 的返回值。

返回值

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

getAudioTrackCount

virtual int getAudioTrackCount() = 0;

获取当前音乐文件的音轨索引

自从

v4.3.0

注意

你需要在调用 startAudioMixing [2/2] 并收到 onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) 回调后调用该方法。
该方法仅适用于 Android、iOS 和 Windows。

参数

参数	描述
index	指定的播放音轨。该参数需小于或等于 getAudioTrackCount 的返回值。

返回值

≥ 0: 方法调用成功，返回当前音乐文件的音轨索引。
< 0: 方法调用失败。

setAudioMixingDualMonoMode

virtual int setAudioMixingDualMonoMode(AM::AUDIO_MIXING_DUAL_MONO_MODE mode) = 0;

设置当前音乐文件的声道模式

自从

v4.3.0 在双声道音乐文件中，左声道和右声道可以存储不同的音频数据。根据实际需要，你可以设置声道模式为原始模式、左声道模式、右声道模式或混合模式。例如，在 KTV 场景中，音乐文件的左声道存储了伴奏，右声道存储了原唱的歌声。如果你只需听伴奏，调用该方法设置音乐文件的声道模式为左声道模式；如果你需要同时听伴奏和原唱，调用该方法设置声道模式为混合模式。

注意

你需要在调用 startAudioMixing [2/2] 并收到 onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) 回调后调用该方法。
该方法仅适用于双声道的音乐文件。

参数

参数	描述
mode	声道模式。详见 AUDIO_MIXING_DUAL_MONO_MODE。

返回值

≥ 0: 方法调用成功，返回当前音乐文件的音轨索引。
< 0: 方法调用失败。

getEffectsVolume

virtual int getEffectsVolume() = 0;

获取音效文件的播放音量

音量范围为 0~100。100 （默认值）为原始文件音量。

返回值

音效文件的音量; <0方法调用失败。

setEffectsVolume

virtual int setEffectsVolume(int volume) = 0;

设置音效文件的播放音量

音量范围为 0~100。100 （默认值）为原始文件音量。

参数

参数	描述
volume	该方法设置音效的音量。

返回值

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

setVolumeOfEffect

virtual int setVolumeOfEffect(int soundId, int volume) = 0;

实时调整音效文件的播放音量。

参数

参数	描述
soundId	指定音效的 ID。每个音效均有唯一的 ID。
volume	播放音量。音量范围为 0~100。100 （默认值）为原始文件音量。

返回值

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

playEffect【1/2】

virtual int playEffect(int soundId, const char* filePath, int loopCount, double pitch, double pan, int gain, bool publish = false) = 0;

播放指定音效文件

弃用:

自 v4.3.0 废弃，请改用 playEffect [2/2] 方法。

你可以多次调用该方法，通过传入不同的音效文件的 soundID 和 filePath，同时播放多个音效文件，实现音效叠加。为获得最佳用户体验，我们建议同时播放的音效文件不要超过 3 个。在 macOS 和 Windows 上，该方法不支持同时播放多个在线音效文件。

参数

参数	描述
filePath	音效文件的绝对路径或 URL 地址，例如：c:/music/audio.mp4。建议填写文件后缀名。若无法确定文件后缀名，可不填。支持的音频格式包括：mp3、mp4、m4a、aac、3gp、mkv 及 wav。详见 Supported Media Formats in Media Foundation 。
loopCount	设置音效循环播放的次数： 0: 播放音效一次； 1: 播放音效两次； -1: 无限循环播放音效，直至调用 stopEffect 或 stopAllEffects 后停止。
pitch	设置音效的音调取值范围为 [0.5, 2]。默认值为 1.0，表示不需要修改音调。取值越小，则音调越低。
pan	设置是否改变音效的空间位置。取值范围为 [-1.0, 1.0]: 0.0: 音效出现在正前方； 1.0: 音效出现在右边； -1.0: 音效出现在左边；
gain	设置是否改变单个音效的音量。取值范围为 [0.0, 100.0]。默认值为 100.0。取值越小，则音效的音量越低。
publish	设置是否将音效传到远端： true: 音效在本地播放的同时，会发布到 anyRTC 云端，因此远端用户也能听到该音效； false: 音效不会发布到 anyRTC 云端，因此只能在本地听到该音效。

返回值

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

注意事项：

如果你已通过 preloadEffect 将音效加载至内存，确保这里设置的 soundId 与 preloadEffect 设置的 soundId 相同。

playEffect【2/2】

virtual int playEffect(int soundId, const char* filePath, int loopCount, double pitch, double pan, int gain, bool publish = false,int startPos) = 0;

自从

v4.3.0

播放指定音效文件

你可以多次调用该方法，传入不同的 soundId 和 filePath，同时播放多个音效文件。为获得最佳用户体验，anyRTC 推荐同时播放的音效文件不超过 3 个。音效文件播放结束后，SDK 会触发 onAudioEffectFinished 回调。

参数

参数	描述
filePath	音效文件的绝对路径或 URL 地址，例如：c:/music/audio.mp4。建议填写文件后缀名。若无法确定文件后缀名，可不填。支持的音频格式包括：mp3、mp4、m4a、aac、3gp、mkv 及 wav。详见 Supported Media Formats in Media Foundation 。
loopCount	设置音效循环播放的次数： 0: 播放音效一次； 1: 播放音效两次； -1: 无限循环播放音效，直至调用 stopEffect 或 stopAllEffects 后停止。
pitch	设置音效的音调取值范围为 [0.5, 2]。默认值为 1.0，表示不需要修改音调。取值越小，则音调越低。
pan	设置是否改变音效的空间位置。取值范围为 [-1.0, 1.0]: 0.0: 音效出现在正前方； 1.0: 音效出现在右边； -1.0: 音效出现在左边；
gain	设置是否改变单个音效的音量。取值范围为 [0.0, 100.0]。默认值为 100.0。取值越小，则音效的音量越低。
publish	设置是否将音效传到远端： true: 音效在本地播放的同时，会发布到 anyRTC 云端，因此远端用户也能听到该音效； false: 音效不会发布到 anyRTC 云端，因此只能在本地听到该音效。
startPos	音效文件的播放位置，单位为毫秒。

返回值

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

注意事项：

该方法需要在加入频道后调用。

stopEffect

virtual int stopEffect(int soundId) = 0;

停止播放指定音效文件

参数

参数	描述
soundId	指定音效文件的 ID。每个音效文件均有唯一的 ID。

返回值

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

stopAllEffects

virtual int stopAllEffects() = 0;

停止播放所有音效文件

返回值

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

preloadEffect

virtual int preloadEffect(int soundId, const char* filePath) = 0;

将音效文件加载至内存

该方法将指定音效文件预加载至内存。为保证通信畅通，请注意控制预加载音效文件的大小，并在 joinChannel 前就使用该方法完成音效预加载。音频文件支持以下音频格式: mp3、aac、m4a、3gp，和 wav。

参数

参数	描述
soundId	指定音效文件的 ID。每个音效文件均有唯一的 ID。
filePath	音效文件的绝对路径。

返回值

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

注意事项：

该方法不支持在线音频文件。

unloadEffect

virtual int unloadEffect(int soundId) = 0;

从内存释放某个预加载的音效文件

参数

参数	描述
soundId	指定音效文件的 ID。每个音效文件均有唯一的 ID。

返回值

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

pauseEffect

virtual int pauseEffect(int soundId) = 0;

暂停音效文件播放

参数

参数	描述
soundId	指定音效文件的 ID。每个音效文件均有唯一的 ID。

返回值

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

pauseAllEffects

virtual int pauseAllEffects() = 0;

暂停所有音效文件播放

返回值

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

resumeEffect

virtual int resumeEffect(int soundId) = 0;

恢复播放指定音效文件

参数

参数	描述
soundId	指定音效文件的 ID。每个音效文件均有唯一的 ID。

返回值

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

resumeAllEffects

virtual int resumeAllEffects() = 0;

恢复播放所有音效文件

返回值

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

enableSoundPositionIndication

virtual int enableSoundPositionIndication(bool enabled) = 0;

开启/关闭远端用户的语音立体声

如果想调用 setRemoteVoicePosition 实现听声辨位的功能，请确保在加入频道前调用该方法开启远端用户的语音立体声。

参数

参数	描述
enabled	是否开启远端用户语音立体声： true: 开启 false: 关闭

返回值

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

setRemoteVoicePosition

virtual int setRemoteVoicePosition(uid_t uid, double pan, double gain) = 0;

设置远端用户的语音位置

设置远端用户声音的空间位置和音量，方便本地用户听声辨位。

通过调用该接口设置远端用户声音出现的位置，左右声道的声音差异会产生声音的方位感，从而判断出远端用户的实时位置。在多人在线游戏场景，如吃鸡游戏中，该方法能有效增加游戏角色的方位感，模拟真实场景。

参数

参数	描述
uid	远端用户的 ID
pan	设置远端用户声音的空间位置，取值范围为 [-1.0,1.0]: (默认）0.0: 声音出现在正前方。 -1.0: 声音出现在左边。 1.0: 声音出现在右边。
gain	设置远端用户声音的音量，取值范围为 [0.0,100.0]，默认值为 100.0，表示该用户的原始音量。取值越小，则音量越低。

返回值

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

setLocalVoicePitch

virtual int setLocalVoicePitch(double pitch) = 0;

设置本地语音音调

参数

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

返回值

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

setLocalVoiceEqualization

virtual int setLocalVoiceEqualization(AUDIO_EQUALIZATION_BAND_FREQUENCY bandFrequency, int bandGain) = 0;

设置本地语音音效均衡

参数

参数	描述
bandFrequency	频谱子带索引。取值范围是 [0,9]，分别代表音效的 10 个频带。对应的中心频率为 [31，62，125，250，500，1k，2k，4k，8k，16k] Hz。详见 AUDIO_EQUALIZATION_BAND_FREQUENCY 。
bandGain	每个 band 的增益，单位是 dB，每一个值的范围是 [-15,15]。

返回值

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

setLocalVoiceReverb

virtual int setLocalVoiceReverb(AUDIO_REVERB_TYPE reverbKey, int value) = 0;

设置本地音效混响

参数

参数	描述
reverbKey	混响音效 Key。该方法共有 5 个混响音效 Key: AUDIO_REVERB_TYPE 。
value	各混响音效 Key 所对应的值：

返回值

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

setLocalVoiceChanger

virtual int setLocalVoiceChanger(VOICE_CHANGER_PRESET voiceChanger) = 0;

设置本地语音变声、美音或语聊美声效果。

通信场景下的用户或直播场景下的主播均可调用该方法为本地语音设置以下效果。成功设置以后，频道内的所有用户均可听到声音效果。

变声效果：枚举值以 VOICE_CHANGER 为前缀。效果包括老男人、小男孩、小女孩、猪八戒、空灵和绿巨人，通常用于语聊场景。
美音效果：枚举值以 VOICE_BEAUTY 为前缀。效果包括浑厚、低沉、圆润、假音、饱满、清澈、高亢、嘹亮和空旷，通常用于语聊和唱歌场景。
语聊美声效果：枚举值以 GENERAL_BEAUTY_VOICE 为前缀。效果包括磁性（男）、清新（女）和活力（女），通常用于语聊场景。该功能主要细化了男声和女声各自的特点。

参数

参数	描述
voiceChanger	预设本地语音变声、美音或语聊美声效果选项，默认值为 VOICE_CHANGER_OFF ，即原声。详见 VOICE_CHANGER_PRESET 。 AR 推荐使用 GENERAL_BEAUTY_VOICE_MALE_MAGNETIC 处理男声，使用 GENERAL_BEAUTY_VOICE_FEMALE_FRESH 或 GENERAL_BEAUTY_VOICE_FEMALE_VITALITY 处理女声，否则音频可能会产生失真。

返回值

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

注意事项：

为达到更好的声音效果，AR 推荐在调用该方法前将 setAudioProfile 的 profile 参数设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY (4) 或 AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO (5)

该方法对人声的处理效果最佳，AR 不推荐调用该方法处理含人声和音乐的音频数据。

该方法不能与 setLocalVoiceReverbPreset 方法一同使用，否则先调的方法会不生效。更多注意事项，详见高级功能《变声与混响》。

setLocalVoiceReverbPreset

virtual int setLocalVoiceReverbPreset(AUDIO_REVERB_PRESET reverbPreset) = 0;

设置本地语音混响（含虚拟立体声效果)

通信场景下的用户或直播场景下的主播均可调用该方法设置本地语音混响。成功设置以后，频道内的所有用户均可听到声音效果。

参数

参数	描述
reverbPreset	本地语音混响选项，默认值为 AUDIO_REVERB_OFF ，即原声。详见 AUDIO_REVERB_PRESET 。为达到更好的混响效果，AR 推荐使用以 AUDIO_REVERB_FX 为前缀的枚举值。

返回值

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

注意事项：

当使用以 AUDIO_REVERB_FX 为前缀的枚举值时，请确保在调用该方法前将 setAudioProfile 的 profile 参数设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY (4) 或 AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO (5) ，否则该方法设置无效。

当使用 AUDIO_VIRTUAL_STEREO 时，AR 推荐在调用该方法前将 setAudioProfile 的 profile 参数设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO (5)

该方法对人声的处理效果最佳，anyRTC 不推荐调用该方法处理含人声和音乐的音频数据。

该方法不能与 setLocalVoiceChanger 方法一同使用，否则先调的方法会不生效。更多注意事项，详见高级功能《变声与混响》。

setLogFile

virtual int setLogFile(const char* filePath) = 0;

设置日志文件

设置 SDK 的输出 log 文件。SDK 运行时产生的所有 log 将写入该文件。 App 必须保证指定的目录存在而且可写。

参数

参数	描述
filePath	日志文件的完整路径。该日志文件为 UTF-8 编码。

返回值

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

注意事项：

Windows 平台下日志文件的默认地址为："C:\Users<user_name>\AppData\Local\ar<process_name>"。

如需调用本方法，请在调用 initialize 方法初始化 IRtcEngine 对象后立即调用，否则可能造成输出日志不完整。

setLogFilter

virtual int setLogFilter(unsigned int filter) = 0;

设置日志输出等级

设置 AR SDK 的输出日志输出等级。不同的输出等级可以单独或组合使用。日志级别顺序依次为 OFF、CRITICAL、ERROR、WARNING、INFO 和 DEBUG。选择一个级别，你就可以看到在该级别之前所有级别的日志信息。

例如，你选择 WARNING 级别，就可以看到在 CRITICAL、ERROR 和 WARNING 级别上的所有日志信息。

参数

参数	描述
filter	设置过滤等级: LOG_FILTER_TYPE 。

返回值

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

setLogFileSize

virtual int setLogFileSize(unsigned int fileSizeInKBytes) = 0;

设置日志文件大小

设置 SDK 输出的日志文件大小，单位为 KB。 AR SDK 设有 2 个日志文件，每个文件大小为 512 KB。如果你将 fileSizeInKBytes 设置为 1024 KB， SDK 会最多输出 2 M 的日志文件。如果日志文件超出设置值，新的日志会覆盖之前的日志。

参数

参数	描述
fileSizeInKBytes	指定 SDK 输出日志文件的内存大小，单位为 KB。

返回值

0方法调用成功; <0方法调用失败, 有可能是因为传入的参数无效。

setLocalRenderMode

virtual int setLocalRenderMode(RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode) = 0;

更新本地视图显示模式

更新本地视图显示模式。初始化本地用户视图后，你可以调用该方法更新本地用户视图的渲染和镜像模式。该方法只影响本地用户看到的视频画面，不影响本地发布视频。

参数

参数	描述
renderMode	本地视图的渲染模式，详见 RENDER_MODE_TYPE
mirrorMode	本地视图的镜像模式，详见 VIDEO_MIRROR_MODE_TYPE Note: 如果你使用前置摄像头，默认启动本地用户视图镜像模式；如果你使用后置摄像头，默认关闭本地视图镜像模式。

返回值

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

注意事项：

请在调用 setupLocalVideo 方法初始化本地视图后，调用该方法。

你可以在通话中多次调用该方法，多次更新本地用户视图的显示模式。

setRemoteRenderMode

virtual int setRemoteRenderMode(uid_t uid, RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode) = 0;

更新远端视图显示模式

初始化远端用户视图后，你可以调用该方法更新远端用户视图在本地显示时的渲染和镜像模式。该方法只影响本地用户看到的视频画面。

参数

参数	描述
uid	远端用户 ID。
renderMode	远端用户视图的渲染模式，详见 RENDER_MODE_TYPE
mirrorMode	远端用户视图的镜像模式，详见 VIDEO_MIRROR_MODE_TYPE Note: 默认关闭远端用户的镜像模式。

返回值

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

注意事项：

请在调用 setupRemoteVideo 方法初始化远端视图后，调用该方法。

你可以在通话中多次调用该方法，多次更新远端用户视图的显示模式。

setLocalVideoMirrorMode

virtual int setLocalVideoMirrorMode(VIDEO_MIRROR_MODE_TYPE mirrorMode) = 0;

设置本地镜像

参数

参数	描述
mirrorMode	详见VIDEO_MIRROR_MODE_TYPE

返回值

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

enableDualStreamMode

virtual int enableDualStreamMode(bool enabled) = 0;

开关双流模式

该方法设置单流（默认）或者双流模式。发送端开启双流模式后，接收端可以选择接收大流还是小流。其中，大流指高分辨率、高码率的视频流，小流指低分辨率、低码率的视频流。

参数

参数	描述
enabled	true: 双流； false: 单流（默认）。

返回值

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

setExternalAudioSource

virtual int setExternalAudioSource(bool enabled, int sampleRate, int channels) = 0;

设置外部音频采集参数。请在 joinChannel 前调用该方法。

参数

参数	描述
enabled	true: 开启使用外部音频源的功能； false: 关闭使用外部音频源的功能（默认）。
sampleRate	外部音频源的采样率 (Hz)，可设置为 8000，16000，32000，44100 或 48000。
channels	外部音频源的通道数，可设置为 1 或 2: 1: 单声道 2: 双声道

返回值

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

setExternalAudioSink

virtual int setExternalAudioSink(bool enabled, int sampleRate, int channels) = 0;

设置外部音频渲染

参数

参数	描述
enabled	true: 开启外部音频渲染。 false: （默认）关闭外部音频渲染。
sampleRate	外部音频渲染的采样率 (Hz)，可设置为 16000，32000，44100 或 48000。
channels	外部音频渲染的声道数，可设置为 1 或 2: 1: 单声道 2: 双声道

返回值

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

注意事项：

开启外部音频渲染后，App 会无法从 onPlaybackAudioFrame 回调中获得数据。

setRecordingAudioFrameParameters

virtual int setRecordingAudioFrameParameters(int sampleRate, int channel, RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall) = 0;

设置录制的声音格式

参数

参数	描述
sampleRate	指定 onRecordAudioFrame 中返回数据的采样率，可设置为 8000、 16000、 32000、 44100 或 48000。
channel	指定 onRecordAudioFrame 中返回数据的通道数，可设置为 1 或 2: 1: 单声道 2: 双声道
mode	onRecordAudioFrame 回调的使用模式: RAW_AUDIO_FRAME_OP_MODE_TYPE 。
samplesPerCall	指定 onRecordAudioFrame 中返回数据的采样点数，如 RTMP 推流应用中通常为 1024。

返回值

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

注意事项：

SDK 会根据该采样间隔触发 onRecordAudioFrame 回调。请确保采样间隔不得小于 0.01 (s)。其中，采样间隔 = samplesPerCall/(sampleRate × channel)。

setPlaybackAudioFrameParameters

virtual int setPlaybackAudioFrameParameters(int sampleRate, int channel, RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall) = 0;

设置播放的声音格式

参数

参数	描述
sampleRate	指定 onPlaybackAudioFrame 中返回数据的采样率，可设置为 8000、 16000、 32000、 44100 或 48000。
channel	指定 nPlaybackAudioFrame 中返回数据的通道数，可设置为 1 或 2: 1: 单声道 2: 双声道
mode	onPlaybackAudioFrame 回调的使用模式: RAW_AUDIO_FRAME_OP_MODE_TYPE 。
samplesPerCall	指定 onPlaybackAudioFrame 中返回数据的采样点数，如 RTMP 推流应用中通常为 1024。

返回值

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

注意事项：

SDK 会根据该采样间隔触发 onPlaybackAudioFrame 回调。请确保采样间隔不得小于 0.01 (s)。其中，采样间隔 = samplesPerCall/(sampleRate × channel)。

setMixedAudioFrameParameters

virtual int setMixedAudioFrameParameters(int sampleRate, int samplesPerCall) = 0;

设置录制与播放声音混音后的数据格式

参数

参数	描述
sampleRate	指定 onMixedAudioFrame 中返回数据的采样率，可设置为 8000，16000，32000，44100 或 48000。
samplesPerCall	指定 onMixedAudioFrame 中返回数据的采样点数，如 RTMP 推流应用中通常为 1024。

返回值

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

注意事项：

SDK 会根据该采样间隔触发 onMixedAudioFrame 回调。请确保采样间隔不得小于 0.01 (s)。其中，采样间隔 = samplesPerCall/(sampleRate × channels)。

adjustRecordingSignalVolume

virtual int adjustRecordingSignalVolume(int volume) = 0;

调节录音音量

参数

参数	描述
volume	录音信号音量。为避免回声并提升通话质量，AR 建议将 volume 值设为 [0,100]。如果 volume 值需超过 100，联系技术支持: 0: 静音； 100: 原始音量。

返回值

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

adjustPlaybackSignalVolume

virtual int adjustPlaybackSignalVolume(int volume) = 0;

调节本地播放的所有远端用户音量

参数

参数	描述
volume	播放音量。为避免回声并提升通话质量，AR 建议将 volume 值设为 [0,100]。如果 volume 值需超过 100，联系技术支持: 0: 静音； 100: 原始音量。

返回值

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

注意事项：

该方法调节的是本地播放的所有远端用户混音后的音量。

静音本地音频需同时调用 adjustPlaybackSignalVolume 和 adjustAudioMixingPlayoutVolume 方法，并将 volume 设置为 0。

setLocalPublishFallbackOption

virtual int setLocalPublishFallbackOption(STREAM_FALLBACK_OPTIONS option) = 0;

设置弱网条件下发布的音视频流回退选项

网络不理想的环境下，实时通信音视频的质量都会下降。使用该接口并将 option 设置为 STREAM_FALLBACK_OPTION_AUDIO_ONLY (2) 后，SDK 会在上行弱网且音视频质量严重受影响时，自动关断视频流，从而保证或提高音频质量。同时 SDK 会持续监控网络质量，并在网络质量改善时恢复音视频流。当本地推流回退为音频流时，或由音频流恢复为音视频流时，SDK 会触发本地发布的媒体流已回退为音频流 onLocalPublishFallbackToAudioOnly 回调。

参数

参数	描述
option	本地发流回退处理选项 STREAM_FALLBACK_OPTION_DISABLED (0)：（默认）上行网络较弱时，不对音视频流作回退处理，但不能保证音视频流的质量 STREAM_FALLBACK_OPTION_AUDIO_ONLY (2)：上行网络较弱时只发布音频流

返回值

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

注意事项：

视频直播场景下，旁路推流的发流用户（即主播）设置 STREAM_FALLBACK_OPTION_AUDIO_ONLY (2) 可能导致 CDN 观众听到的声音有所延迟。AR 不建议主播使用视频流回退机制。

setRemoteSubscribeFallbackOption

virtual int setRemoteSubscribeFallbackOption(STREAM_FALLBACK_OPTIONS option) = 0;

设置弱网条件下订阅的音视频流的回退选项

默认 option 为 STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW (1) 。如果你使用本方法并将 option 设置为 STREAM_FALLBACK_OPTION_AUDIO_ONLY (2)， SDK 会在下行弱网且音视频质量严重受影响时，将视频流切换为小流，或关断视频流，从而保证或提高音频质量。同时 SDK 会持续监控网络质量，并在网络质量改善时恢复音视频流。当远端订阅流回退为音频流时，或由音频流恢复为音视频流时，SDK 会触发 onRemoteSubscribeFallbackToAudioOnly 回调。

参数

参数	描述
option	详见 STREAM_FALLBACK_OPTIONS 。

返回值

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

switchCamera

virtual int switchCamera() = 0;

切换前置/后置摄像头

返回值

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

注意事项：

该方法仅适用于 Android 和 iOS 平台。

setDefaultAudioRouteToSpeakerphone

virtual int setDefaultAudioRouteToSpeakerphone(bool defaultToSpeaker) = 0;

设置默认的语音路由

该方法设置接收到的语音从听筒或扬声器出声。如果用户不调用本方法，语音默认从听筒出声。

各频道场景下默认的语音路由：

语音通话：听筒
视频通话：扬声器。如果有用户在频道中使用 disableVideo 、 muteLocalVideoStream 或 muteAllRemoteVideoStreams 方法关闭视频，则语音路由会自动切换回听筒。
直播：扬声器
游戏语音：扬声器

参数

参数	描述
defaultToSpeaker	设置默认的语音路由 true: 语音路由为外放（扬声器）。如果设备连接了耳机或蓝牙，则无法切换到外放。 false:（默认）语音路由为听筒。

返回值

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

注意事项：

该方法仅适用于 Android 和 iOS 平台。

在 iOS 平台上，该方法只在纯音频模式下工作，在有视频的模式下不工作。

该方法需要在 joinChannel 前设置，否则不生效。如需在加入频道后更改默认语音路由，请调用 setEnableSpeakerphone 方法。

setEnableSpeakerphone

virtual int setEnableSpeakerphone(bool speakerOn) = 0;

启用/关闭扬声器播放

该方法设置是否将语音路由到扬声器（外放）

该方法设置是否将语音路由设到扬声器（外放）。你可以在 setDefaultAudioRouteToSpeakerphone 方法中查看默认的语音路由。

在 Android 上，setAudioProfile 中 scenario 及 setChannelProfile 的设置会影响 setEnableSpeakerphone 的行为。setEnableSpeakerphone 不生效的情况如下：

当 scenario 为 AUDIO_SCENARIO_GAME_STREAMING 时，所有用户都无法切换音频播放路由。
当 scenario 为 AUDIO_SCENARIO_DEFAULT或 AUDIO_SCENARIO_SHOWROOM时，直播场景中的观众无法切换音频播放路由，且当频道中只有一个主播时，该主播也无法切换音频播放路由。
当 scenario 为 AUDIO_SCENARIO_EDUCATION 时，直播场景中的观众无法切换音频播放路由。

参数

参数	描述
speakerOn	设置是否切换语音路由到扬声器（外放）： true: 切换到外放。如果设备连接了耳机或蓝牙，则无法切换到外放。 false: 切换到听筒。如果设备连接了耳机，则语音路由走耳机。

返回值

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

注意事项：

该方法仅适用于 Android 和 iOS 平台。

请确保在调用此方法前已调用过 joinChannel 方法。

调用该方法后，SDK 将返回 onAudioRouteChanged 回调提示状态已更改。

enableInEarMonitoring

virtual int enableInEarMonitoring(bool enabled) = 0;

开启耳返功能

该方法打开或关闭耳返功能。

参数

参数	描述
enabled	开启/关闭耳返功能： true：开启耳返功能。 false：关闭耳返功能(默认)。

返回值

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

注意事项：

该方法仅适用于 Android 和 iOS 平台。

用户必须使用有线耳机才能听到耳返效果。

setInEarMonitoringVolume

virtual int setInEarMonitoringVolume(int volume) = 0;

设置耳返音量

该方法打开或关闭耳返功能。

参数

参数	描述
volume	设置耳返音量，取值范围在 [0,100]。默认值为 100

返回值

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

注意事项：

该方法仅适用于 Android 和 iOS 平台。

用户必须使用有线耳机才能听到耳返效果。

isSpeakerphoneEnabled

virtual bool isSpeakerphoneEnabled() = 0;

查询扬声器启用状态

该方法打开或关闭耳返功能。

返回值

0打开了扬声器;
<0未打开扬声器。

注意事项：

该方法仅适用于 Android 和 iOS 平台。

setAudioSessionOperationRestriction

virtual int setAudioSessionOperationRestriction(AUDIO_SESSION_OPERATION_RESTRICTION restriction) = 0;

设置 SDK 对 Audio Session 的控制权限

该接口可以在任意时候调用，可以在任意时候通过该方法把控制权交还给 SDK。

参数

参数	描述
restriction	AR SDK 对 Audio Session 的控制权限，详见: AUDIO_SESSION_OPERATION_RESTRICTION 。该 restriction 为 Bit Mask，每个 Bit 对应一个权限。

返回值

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

注意事项：

该方法仅适用于 iOS 平台。

该方法限制 AR SDK 对 Audio Session 的操作权限。在默认情况下，SDK 和 App 对 Audio Session 都有控制权，但某些场景下，App 会希望限制 anyRTC SDK 对 Audio Session 的控制权限，而使用其他应用或第三方组件对 Audio Session 进行操控。调用该方法可以实现该功能。

一旦调用该方法限制了 AR SDK 对 Audio Session 的控制权限， SDK 将无法对 Audio Session 进行相关设置，而需要用户自己或第三方组件进行维护。

enableLoopbackRecording

virtual int enableLoopbackRecording(bool enabled, const char* deviceName = NULL) = 0;

开启声卡采集

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

参数

参数	描述
enabled	设置是否开启声卡采集： true: 开启声卡采集 false: （默认）关闭声卡采集
deviceName	声卡的设备名。默认设为 NULL，即使用当前声卡采集。如果用户使用虚拟声卡，如 “Soundflower”，可以将虚拟声卡名称 “Soundflower” 作为参数，SDK 会找到对应的虚拟声卡设备，并开始采集。

返回值

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

注意事项：

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

macOS 系统默认声卡不支持采集功能，如需开启此功能需要 App 自己启用一个虚拟声卡，并将该虚拟声卡的名字作为 deviceName 传入 SDK。 anyRTC 测试并推荐 soundflower 作为虚拟声卡。

startScreenCaptureByDisplayId

virtual int startScreenCaptureByDisplayId(unsigned int displayId, const Rectangle& regionRect, const ScreenCaptureParameters& captureParams) = 0;

通过屏幕 ID 共享屏幕。

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

参数

参数	描述
displayId	指定待共享的屏幕 ID。开发者需要通过该参数指定你要共享的那个屏幕。关于如何获取屏幕 ID，请参考高级功能《共享屏幕》。
regionRect	（可选）指定待共享区域相对于整个屏幕的位置。如不填，则表示共享整个屏幕。详见: Rectangle 。如果设置的共享区域超出了屏幕的边界，则只共享屏幕视窗内的内容；如果宽或高为 0，则共享整个屏幕。
captureParams	（屏幕共享的编码参数配置。详见: ScreenCaptureParameters 。

返回值

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

注意事项：

该方法仅适用于 macOS。

startScreenCaptureByScreenRect

virtual int startScreenCaptureByScreenRect(const Rectangle& screenRect, const Rectangle& regionRect, const ScreenCaptureParameters& captureParams) = 0;

通过指定区域共享屏幕

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

参数

参数	描述
screenRect	指定待共享的屏幕相对于虚拟屏的位置。关于如何获取屏幕位置，请参考高级功能《共享屏幕》。
regionRect	(可选）指定待共享区域相对于整个屏幕屏幕的位置。如不填，则表示共享整个屏幕。详见: Rectangle 。如果设置的共享区域超出了屏幕的边界，则只共享屏幕内的内容；如果将 width 或 height 设为 0 ，则共享整个屏幕。
captureParams	屏幕共享的编码参数配置。详见: ScreenCaptureParameters 。

返回值

0:方法调用成功;
<0方法调用失败。
- ERR_INVALID_STATE: 屏幕共享状态无效。可能有屏幕或窗口正在共享中，请调用 stopScreenCapturecreenCapture 停止共享。
- ERR_INVALID_ARGUMENT: 传入的参数无效。

startScreenCaptureByWindowId

virtual int startScreenCaptureByWindowId(view_t windowId, const Rectangle& regionRect, const ScreenCaptureParameters& captureParams) = 0;

通过窗口 ID 共享窗口

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

参数

参数	描述
windowId	指定待共享的屏幕相对于虚拟屏的位置。关于如何获取屏幕位置，请参考高级功能《共享屏幕》。
regionRect	(可选）指定待共享区域相对于整个屏幕屏幕的位置。如不填，则表示共享整个屏幕。详见: Rectangle 。如果设置的共享区域超出了屏幕的边界，则只共享屏幕内的内容；如果将 width 或 height 设为 0 ，则共享整个屏幕。
captureParams	屏幕共享的编码参数配置。详见: ScreenCaptureParameters 。

返回值

0:方法调用成功;
<0方法调用失败。
- ERR_INVALID_STATE: 屏幕共享状态无效。可能有屏幕或窗口正在共享中，请调用 stopScreenCapturecreenCapture 停止共享。
- ERR_INVALID_ARGUMENT: 传入的参数无效。

setScreenCaptureContentHint

virtual int setScreenCaptureContentHint(VideoContentHint contentHint) = 0;

设置屏幕共享内容类型

设置屏幕共享的内容类型。AR SDK 会根据不同的内容类型，使用不同的算法对共享效果进行优化。如果不调用该方法，SDK 会将屏幕共享的内容默认为 CONTENT_HINT_NONE ，即无指定的内容类型。

参数

参数	描述
contentHint	指定屏幕共享的内容类型。详见: VideoContentHint 。

返回值

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

updateScreenCaptureParameters

virtual int updateScreenCaptureParameters(const ScreenCaptureParameters& captureParams) = 0;

更新屏幕共享的编码参数配置

参数

参数	描述
captureParams	屏幕共享的编码参数配置。详见: ScreenCaptureParameters 。

返回值

0:方法调用成功;
<0方法调用失败。
ERR_NOT_READY: 如果当前没有共享的屏幕，会返回该错误码。

updateScreenCaptureRegion

virtual int updateScreenCaptureRegion(const Rectangle& regionRect) = 0;

更新屏幕共享区域

参数

参数	描述
regionRect	待共享区域相对于整个屏幕或窗口的位置，如不填，则表示共享整个屏幕或窗口。详见: Rectangle 。如果设置的共享区域超出了屏幕或窗口的边界，则只共享屏幕或窗口内的内容；如果将 width 或 height 设为 0 ，则共享整个屏幕或窗口。

返回值

0:方法调用成功;
<0方法调用失败。
ERR_NOT_READY: 如果当前没有共享的屏幕，会返回该错误码。

stopScreenCapture

virtual int stopScreenCapture() = 0;

停止屏幕共享

返回值

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

setVideoSource

virtual bool setVideoSource(AR::IVideoSource *source) = 0;

设置自定义的视频源

实时通信过程中，anyRTC SDK 会启动默认的视频输入设备，即内置的摄像头，采集视频。但是，如果你需要自定义视频输入设备，你可以先通过 IVideoSource 类自定义视频源，再调用该方法将自定义的视频源加入到 SDK 中。

参数

参数	描述
source	自定义的视频源。详细定义见 IVideoSource。

返回值

true: 自定义视频源添加成功。
false: 自定义视频源添加失败。

enableDeepLearningDenoise

virtual int enableDeepLearningDenoise(bool enable) = 0;

开启或关闭 AI 降噪模式。

该方法对人声的处理效果最佳，anyRTC 不推荐调用该方法处理含音乐的音频数据。

成功开启 AI 降噪模式后，如果 SDK 检测到当前设备的性能不足，SDK 会自动关闭 AI 降噪模式，并开启传统降噪模式。

参数

参数	描述
enable	是否开启 AI 降噪模式： true:（默认）开启。 false: 关闭

返回值

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

getCallId

virtual int getCallId(ar::util::AString& callId) = 0;

获取当前通话 ID

客户端在每次 joinChannel 后会生成一个对应的 callId，标识该客户端的此次通话。有些方法如 rate 、 complain 需要在通话结束后调用，向 SDK 提交反馈，这些方法必须指定 CallId 参数。使用这些反馈方法，需要在通话过程中调用 getCallId 方法获取 CallId，在通话结束后在反馈方法中作为参数传入。

参数

参数	描述
callId	当前的通话 ID。

返回值

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

rate

virtual int rate(const char* callId, int rating, const char* description) = 0;

给通话评分

该方法能够让用户为通话评分，一般在通话结束后调用。

参数

参数	描述
callId	通话 getCallId 函数获取的通话 ID。
rating	给通话的评分，最低 1 分，最高 5 分。如超过这个范围，SDK 会返回 ERR_INVALID_ARGUMENT (2) 错误。
description	(非必选项) 给通话的描述，可选，长度应小于 800 字节。

返回值

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

complain

virtual int complain(const char* callId, const char* description) = 0;

投诉通话质量

该方法让用户就通话质量进行投诉。一般在通话结束后调用。

参数

参数	描述
callId	通话 getCallId 函数获取的通话 ID。
rating	给通话的评分，最低 1 分，最高 5 分。如超过这个范围，SDK 会返回 ERR_INVALID_ARGUMENT (2) 错误。
description	(非必选项) 给通话的描述，可选，长度应小于 800 字节。

返回值

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

getVersion

virtual const char* getVersion(int* build) = 0;

查询 SDK 版本号

参数

参数	描述
build	编译号.

返回值

当前的 SDK 版本号，格式为字符串，如 4.0.0。

enableLastmileTest

virtual int enableLastmileTest() = 0;

启动网络测试

该方法启用网络连接质量测试，用于检测用户目前的网络接入质量（上行网络质量）。默认该功能为关闭状态。该方法主要用于以下场景:

用户加入频道前，可以调用该方法判断和预测目前的上行网络质量是否足够好。
直播场景下，当用户角色由观众切换为主播时，可以调用该方法判断和预测目前的上行网络质量是否足够好。

启用该方法均会消耗网络流量，影响通话质量。用户必须在收到 onLastmileQuality 回调后须调用 disableLastmileTest 停止测试，再加入频道或切换为主播。

返回值

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

注意事项：

该方法请勿与 startLastmileProbeTest 同时使用。

调用该方法后，在收到 onLastmileQuality 回调前请勿调用其他方法，否则可能由于 API 操作过于频繁导致回调无法执行。

在直播场景中，如果本地用户为主播，请勿加入频道后调用该方法。

加入频道前调用该方法检测网络质量后，SDK 会占用一路视频的带宽，码率与 setVideoEncoderConfiguration 中设置的码率相同。加入频道后，无论是否调用了 disableLastmileTest ，SDK 均会自动停止带宽占用。

disableLastmileTest

virtual int disableLastmileTest() = 0;

关闭网络测试

返回值

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

startLastmileProbeTest

virtual int startLastmileProbeTest(const LastmileProbeConfig& config) = 0;

开始通话前网络质量探测

开始通话前网络质量探测，向用户反馈上下行网络的带宽、丢包、网络抖动和往返时延数据。启用该方法后，SDK 会依次返回如下 2 个回调：

onLastmileQuality，视网络情况约 2 秒内返回。该回调通过打分反馈上下行网络质量，更贴近用户的主观感受。
onLastmileProbeResult，视网络情况约 30 秒内返回。该回调通过具体数据反馈上下行网络质量，更加客观。

该方法主要用于以下两种场景：

用户加入频道前，可以调用该方法判断和预测目前的上行网络质量是否足够好。
直播场景下，当用户角色想由观众切换为主播时，可以调用该方法判断和预测目前的上行网络质量是否足够好。

参数

参数	描述
config	Last mile 网络探测配置，详见 LastmileProbeConfig 。

返回值

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

注意事项：

该方法会消耗一定的网络流量，影响通话质量，因此我们建议不要和 enableLastmileTest 同时使用。

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

在直播场景中，如果本地用户为主播，请勿加入频道后调用该方法。

stopLastmileProbeTest

virtual int stopLastmileProbeTest() = 0;

停止通话前网络质量探测

返回值

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

getErrorDescription

virtual const char* getErrorDescription(int code) = 0;

获取警告或错误描述

参数

参数	描述
code	onWarning 或 onError 提供的警告码或错误码。

返回值

WARN_CODE_TYPE 或 ERROR_CODE_TYPE 。

setEncryptionSecret

virtual int setEncryptionSecret(const char* secret) = 0;

启用内置加密，并设置数据加密密码

弃用: 该方法自 v4.0.0 起废弃。请改用 enableEncryption 方法。

在加入频道之前，App 需调用 setEncryptionSecret 方法指定 secret 来启用内置的加密功能，同一频道内的所有用户应设置相同的 secret。当用户离开频道时，该频道的 secret 会自动清除。如果未指定 secret 或将 secret 设置为空，则无法激活加密功能。

参数

参数	描述
secret	加密密码。

返回值

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

注意事项：

请不要在旁路推流时调用此方法。

为保证最佳传输效果，请确保加密后的数据大小不超过原始数据大小 + 16 字节。16 字节是 AES 通用加密模式下最大填充块大小。。

setEncryptionMode

virtual int setEncryptionMode(const char* encryptionMode) = 0;

启用内置的加密方案

弃用: 该方法自 v4.0.0 起废弃。请改用 enableEncryption 方法。

AR Video SDK 支持内置加密方案，默认支持 AES-128-XTS。如需采用其他加密方案，可以调用本方法。同一频道内的所有用户必须设置相同的加密方式和 secret 才能进行通话。关于这几种加密方式的区别，请参考 AES 加密算法的相关资料。

参数

参数	描述
encryptionMode	加密模式： "aes-128-xts": 128 位 AES 加密，XTS 模式； "aes-128-ecb":128 位 AES 加密，ECB 模式； "aes-256-xts": 256 位 AES 加密，XTS 模式； "": 设置为空字符串时，默认使用加密方式 "aes-128-xts"。

返回值

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

注意事项：

在调用本方法前，请先调用 setEncryptionSecret 启用内置加密功能。

enableEncryption

virtual int enableEncryption ( bool enabled, const EncryptionConfig & config )

开启或关闭内置加密。

在安全要求较高的场景下，anyRTC 建议你在加入频道前，调用 enableEncryption 方法开启内置加密。

同一频道内所有用户必须使用相同的加密模式和密钥。一旦所有用户都离开频道，该频道的加密密钥会自动清除。

注意事项：

如果开启了内置加密，则不能使用 RTMP 推流功能。

anyRTC 支持 4 种加密模式。详见《媒体流加密》。

参数

参数	描述
enabled	是否开启内置加密： true: 开启 false: 关闭
config	配置内置加密模式和密钥。详见 EncryptionConfig。

返回值

0:方法调用成功
< 0: 方法调用失败
- -2(ERR_INVALID_ARGUMENT): 调用了无效的参数。需重新指定参数。
- -4(ERR_NOT_SUPPORTED): 设置的加密模式不正确或加载外部加密库失败。需检查枚举值是否正确或重新加载外部加密库。
- -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。需在调用 API 之前已创建 IRtcEngine 对象并完成初始化。

registerPacketObserver

virtual int registerPacketObserver(IPacketObserver* observer) = 0;

注册数据包观测器

该方法注册数据包观测器 (Packet Observer)。在 AR SDK 发送/接收（语音、视频）网络包时，会回调 IPacketObserver 定义的接口，App 可用此接口对数据做处理，例如加解密。

参数

参数	描述
observer	IPacketObserver 。

返回值

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

注意事项：

处理后发送到网络的包大小不应超过 1200 字节，否则有可能发送失败。

若需调用此方法，需确保接收端和发送端都调用此方法，否则会出现未定义行为（例如音频无声或视频黑屏）。

若在直播场景下使用 CDN 推流、录制或储存，AR 不建议调用此方法。

createDataStream

virtual int createDataStream(int* streamId, bool reliable, bool ordered) = 0;

创建数据流

该方法用于创建数据流。RtcEngine 生命周期内，每个用户最多只能创建 5 个数据流。频道内数据通道最多允许数据延迟 5 秒，若超过 5 秒接收方尚未收到数据流，则数据通道会向 App 报错。

参数

参数	描述
streamId	数据流 ID 。
reliable	true: 接收方 5 秒内会收到发送方所发送的数据，否则会收到 onStreamMessageError 回调获得相应报错信息。 false: 接收方不保证收到，就算数据丢失也不会报错。
ordered	true: 接收方 5 秒内会按照发送方发送的顺序收到数据包； false: 接收方不保证按照发送方发送的顺序收到数据包。

返回值

0:创建数据流成功;
<0创建数据流失败。

注意事项：

将 reliable 和 ordered 同时设为 true 或 false。不要一个设为 true 另一个设为 false。

sendStreamMessage

virtual int sendStreamMessage(int streamId, const char* data, size_t length) = 0;

发送数据流

该方法发送数据流消息到频道内所有用户。SDK 对该方法的实现进行了如下限制：频道内每秒最多能发送 30 个包，且每个包最大为 1 KB。 API 须对数据通道的传送速率进行控制: 每个客户端每秒最多能发送 6 KB 数据。频道内每人最多能同时有 5 个数据通道。成功调用该方法后，远端会触发 onStreamMessage 回调，远端用户可以在该回调中获取接收到的流消息；若调用失败，远端会触发 onStreamMessageError 回调。

参数

参数	描述
streamId	由 createDataStream 返回的数据流 ID。
data	自定义数据。
length	数据长度。

返回值

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

注意事项：

请确保在调用该方法前，已调用 createDataStream 创建了数据流。

该方法仅适用于通信场景以及直播场景下的主播用户，如果直播场景下的观众调用此方法可能会造成观众变主播。

addPublishStreamUrl

virtual int addPublishStreamUrl(const char *url, bool transcodingEnabled) = 0;

增加旁路推流地址

调用该方法后，SDK会在本地触发 onRtmpStreamingStateChanged 回调，报告增加旁路推流地址的状态。

参数

参数	描述
url	CDN 推流地址，格式为 RTMP。该字符长度不能超过 1024 字节。url 不支持中文字符等特殊字符。
transcodingEnabled	true: 转码（转码是指在旁路推流时对音视频流进行转码处理后再推送到其他 RTMP 服务器。多适用于频道内有多个主播，需要进行混流、合图的场景）。如果设为 true，需先调用 setLiveTranscoding 方法。 false: 不转码。

返回值

0:方法调用成功;
<0方法调用失败。
ERR_INVALID_ARGUMENT (2): URL 为空或是长度为 0 的的字符串.
ERR_NOT_INITIALIZED (7): 推流时未初始化引擎.

注意事项：

请确保在成功加入频道后才能调用该接口。

请确保已开通旁路推流的功能，详见高级功能《推流到 CDN》中的前提条件。

该方法每次只能增加一路旁路推流地址。若需推送多路流，则需多次调用该方法。

在直播场景中，只有角色为主播的用户才能调用该方法。

removePublishStreamUrl

virtual int removePublishStreamUrl(const char *url) = 0;

删除旁路推流地址

调用该方法后，SDK 会在本地触发 onRtmpStreamingStateChanged 回调，报告删除旁路推流地址的状态。

参数

参数	描述
url	待删除的旁路推流地址，格式为 RTMP。该字符长度不能超过 1024 字节。

返回值

0:方法调用成功;
<0方法调用失败。
ERR_INVALID_ARGUMENT (2): URL 为空或是长度为 0 的的字符串.
ERR_NOT_INITIALIZED (7): 推流时未初始化引擎.

注意事项：

该方法每次只能删除一路旁路推流地址。若需删除多路流，则需多次调用该方法。

URL 不支持中文等特殊字符。

在直播场景中，只有角色为主播的用户才能调用该方法。

setLiveTranscoding

virtual int setLiveTranscoding(const LiveTranscoding &transcoding) = 0;

设置直播推流转码

该方法用于旁路推流的视图布局及音频设置等。调用该方法更新转码设置后本地会触发 onTranscodingUpdated 回调。

参数

参数	描述
transcoding	详见 LiveTranscoding 。

返回值

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

注意事项：

在直播场景中，只有角色为主播的用户才能调用该方法。

请确保已开通旁路推流的功能，详见高级功能《推流到 CDN》中的前提条件。

首次调用该方法更新转码设置时，不会触发 onTranscodingUpdated 回调。

addVideoWatermark

virtual int addVideoWatermark(const char* watermarkUrl, const WatermarkOptions& options) = 0;

添加本地视频水印

该方法将一张 PNG 图片作为水印添加到本地发布的直播视频流上，同一直播频道中的观众、旁路直播观众和录制设备都能看到或采集到该水印图片。anyRTC 当前只支持在直播视频流中添加一个水印，后添加的水印会替换掉之前添加的水印。水印坐标和 setVideoEncoderConfiguration 方法中的设置有依赖关系：

如果视频编码方向/ ORIENTATION_MODE 固定为横屏或自适应模式下的横屏，那么水印使用横屏坐标。
如果视频编码方向/ ORIENTATION_MODE 固定为竖屏或自适应模式下的竖屏，那么水印使用竖屏坐标。
设置水印坐标时，水印的图像区域不能超出 setVideoEncoderConfiguration 方法中设置的视频尺寸，否则超出部分将被裁剪。

参数

参数	描述
watermarkUrl	待添加的水印图片的本地路径。本方法支持从本地绝对/相对路径添加水印图片。
options	待添加的水印图片的设置选项，详见WatermarkOptions 。

返回值

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

注意事项：

你需要在调用 enableVideo 方法之后再调用本方法。

如果你只是在旁路直播（推流到CDN）中添加水印，你可以使用本方法或 setLiveTranscoding 方法设置水印。

待添加水印图片必须是 PNG 格式。本方法支持所有像素格式的 PNG 图片：RGBA、RGB、Palette、Gray 和 Alpha_gray。

如果待添加的 PNG 图片的尺寸与你在本方法中设置的尺寸不一致，SDK 会对 PNG 图片进行缩放或裁剪，以与设置相符。

如果你已经使用 startPreview 方法开启本地视频预览，那么本方法的 visibleInPreview 可设置水印在预览时是否可见。

如果你已设置本地视频为镜像模式，那么此处的本地水印也为镜像。为避免本地用户看本地视频时的水印也被镜像，AR 建议你不要对本地视频同时使用镜像和水印功能，请在应用层实现本地水印功能。

clearVideoWatermarks

virtual int clearVideoWatermarks() = 0;

删除已添加的视频水印

返回值

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

setBeautyEffectOptions

virtual int setBeautyEffectOptions(bool enabled, BeautyOptions options) = 0;

设置美颜效果选项

开启本地美颜功能，并设置美颜效果选项。

参数

参数	描述
enabled	是否开启美颜功能： true: 开启。 false: （默认）关闭。
options	美颜选项。详见: BeautyOptions 。

返回值

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

注意事项：

请在调用 enableVideo 方法后，调用该方法。

该方法目前不适用于 macOS 平台。

addInjectStreamUrl

virtual int addInjectStreamUrl(const char* url, const InjectStreamConfig& config) = 0;

输入在线媒体流

该方法将正在播放的音视频作为音视频源导入到正在进行的直播中。可主要应用于赛事直播、多人看视频互动等直播场景。调用该方法后，SDK 会在本地触发 onStreamInjectedStatus 回调，报告输入在线媒体流的状态；成功输入媒体流后，该音视频流会出现在频道中，频道内所有用户都会收到 onUserJoined 回调，其中 uid 为 666。该音视频流会出现在频道中。

参数

参数	描述
url	添加到直播中的视频流 URL 地址。支持 RTMP、HLS、HTTP-FLV 协议传输。支持的音频编码格式：AAC; 支持的视频编码格式：H.264(AVC)。
config	所添加的视频流属性定义，详见: InjectStreamConfig 。

返回值

0:方法调用成功;
<0方法调用失败。
ERR_INVALID_ARGUMENT (2): 输入的 URL 为空。请重新调用该方法，并确认输入的媒体流的 URL 有效。
ERR_NOT_READY (3): 用户没有加入频道。
ERR_NOT_SUPPORTED (4): 频道非直播场景。请调用 setChannelProfile 并将频道设置为直播场景再调用该方法。
ERR_NOT_INITIALIZED (7): 引擎没有初始化。请确认调用该方法前已创建 IRtcEngine 对象并完成初始化。

注意事项：

请确保已开通旁路推流的功能，详见高级功能《推流到 CDN》中的前提条件。

在直播场景中，只有角色为主播的用户才能调用该方法。

频道内同一时间只允许输入一个在线媒体流。

startChannelMediaRelay

virtual int startChannelMediaRelay(const ChannelMediaRelayConfiguration &configuration) = 0;

开始跨频道媒体流转发

该方法可用于实现跨频道连麦等场景。

成功调用该方法后，SDK 会触发 onChannelMediaRelayStateChanged 和 onChannelMediaRelayEvent 回调，并在回调中报告当前的跨频道媒体流转发状态和事件。

如果 onChannelMediaRelayStateChanged 回调报告 RELAY_STATE_RUNNING (2) 和 RELAY_OK (0)，且 onChannelMediaRelayEvent 回调报告 RELAY_EVENT_PACKET_SENT_TO_DEST_CHANNEL (4)，则表示 SDK 开始在源频道和目标频道之间转发媒体流。
如果 onChannelMediaRelayStateChanged 回调报告 RELAY_STATE_FAILURE (3)，则表示跨频道媒体流转发出现异常。

参数

参数	描述
configuration	跨频道媒体流转发参数配置。详见 ChannelMediaRelayConfiguration 。

返回值

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

注意事项：

请在成功加入频道后调用该方法。

在直播场景中，只有角色为主播的用户才能调用该方法。

成功调用该方法后，若你想再次调用该方法，必须先调用 stopChannelMediaRelay 方法退出当前的转发状态。

updateChannelMediaRelay

virtual int updateChannelMediaRelay(const ChannelMediaRelayConfiguration &configuration) = 0;

更新媒体流转发的频道

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

成功调用该方法后，SDK 会触发 onChannelMediaRelayEvent 回调，并在回调中报告状态码 RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL (7)。

参数

参数	描述
configuration	跨频道媒体流转发参数配置。详见 ChannelMediaRelayConfiguration 。

返回值

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

注意事项：

请在 startChannelMediaRelay 方法后调用该方法，更新媒体流转发的频道。

stopChannelMediaRelay

virtual int stopChannelMediaRelay() = 0;

停止跨频道媒体流转发

一旦停止，主播会退出所有目标频道。

成功调用该方法后，SDK 会触发 onChannelMediaRelayStateChanged 回调。如果报告 RELAY_STATE_IDLE (0) 和 RELAY_OK (0)，则表示已停止转发媒体流。

返回值

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

注意事项：

如果该方法调用不成功，SDK 会触发 onChannelMediaRelayStateChanged 回调，并报告状态码 RELAY_ERROR_SERVER_NO_RESPONSE (2) 或 RELAY_ERROR_SERVER_CONNECTION_LOST (8)。你可以调用 leaveChannel 方法离开频道，跨频道媒体流转发会自动停止。

removeInjectStreamUrl

virtual int removeInjectStreamUrl(const char* url) = 0;

删除导入的外部媒体流

参数

参数	描述
url	已导入、待删除的外部视频源 URL 地址。

返回值

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

注意事项：

成功删除外部视频源 URL 地址后会触发 onUserOffline 回调，uid 为 share666。

registerEventHandler

virtual bool registerEventHandler(IRtcEngineEventHandler *eventHandler) = 0;

注册事件回调

参数

参数	描述
eventHandler	回调。

返回值

ture:方法调用成功;
false:方法调用失败。

unregisterEventHandler

virtual bool unregisterEventHandler(IRtcEngineEventHandler *eventHandler) = 0;

取消注册事件回调

参数

参数	描述
eventHandler	回调。

返回值

ture:方法调用成功;
false:方法调用失败。

getConnectionState

virtual AR::CONNECTION_STATE_TYPE getConnectionState();

获取当前网络连接状态。

返回值

CONNECTION_STATE_TYPE 。

registerMediaMetadataObserver

virtual int registerMediaMetadataObserver(IMetadataObserver *observer, IMetadataObserver::METADATA_TYPE type) = 0;

注册媒体 metadata 观测器用于接收或发送 metadata

参数

参数	描述
observer	指向已注册的 metadata 观测器的指针。详见： IMetadataObserver 。
type	用户希望在观测器中使用的 METADATA 类型。目前仅支持 VIDEO_METADATA 。详见： METADATA_TYPE 。

返回值

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