API 概览

声网通过全球部署的虚拟网络，提供可以灵活搭配的 API 组合，为移动端到移动端以及移动端到 Web 端提供质量可靠的实时音视频通信。

• RtcEngine 类包含应用程序调用的主要方法。
• RtcEngineEventHandler 类用于向应用程序发送回调通知。
• RtcChannel 类在指定频道中实现实时音视频功能。通过创建多个 RtcChannel 对象，用户可以同时加入多个频道。
• RtcChannelEventHandler 类监听和报告指定频道的事件和数据。
• RtcDeviceManager 类提供用于测试音、视频设备的相关接口。

核心方法

方法	描述
create	创建 RtcEngine 对象并返回指针。
createWithContext	创建并初始化 RtcEngine 。
destroy	销毁 RtcEngine 对象。
setChannelProfile	设置频道场景。
setClientRole	设置直播场景下的用户角色和级别。
joinChannel	加入频道并设置是否自动订阅音频或视频流。
switchChannel	快速切换直播频道，并设置是否自动订阅音频流或视频流。
leaveChannel	离开频道。
renewToken	更新 Token。
getConnectionState	获取当前网络连接状态。

核心事件

事件	描述
connectionStateChanged	网络连接状态已改变回调。
joinChannelSuccess	成功加入频道回调。
rejoinChannelSuccess	成功重新加入频道回调。
leaveChannel	离开频道回调。
clientRoleChanged	直播场景下用户角色切换成功回调。
userJoined	远端用户（通信场景）/主播（直播场景）加入当前频道回调。
userOffline	远端用户（通信场景）/主播（直播场景）离开当前频道回调。
networkTypeChanged	本地网络类型发生改变回调。
connectionLost	网络连接中断，且 SDK 无法在 10 秒内连接服务器回调。
tokenPrivilegeWillExpire	Token 服务将在30s内过期回调。
requestToken	Token 已过期回调。

音频管理

方法	描述
enableAudio	启用音频模块。
disableAudio	关闭音频模块。
setAudioProfile	设置音频编码属性和音频场景。
adjustUserPlaybackSignalVolume	调节本地播放的指定远端用户信号音量。
adjustPlaybackSignalVolume	调节本地播放的所有远端用户信号音量。
enableLocalAudio	开关本地音频采集。
muteLocalAudioStream	取消或恢复发布本地音频流。
muteRemoteAudioStream	取消或恢复订阅指定远端用户的音频流。
muteAllRemoteAudioStreams	取消或恢复订阅所有远端用户的音频流。

视频管理

方法	描述
enableVideo	启用视频模块。
disableVideo	关闭视频模块。
setVideoEncoderConfiguration	设置视频编码属性。
startPreview	开启视频预览。
stopPreview	停止视频预览。
enableLocalVideo	开关本地视频采集。
muteLocalVideoStream	取消或恢复发布本地视频流。
muteRemoteVideoStream	取消或恢复订阅指定远端用户的视频流。
muteAllRemoteVideoStreams	取消或恢复订阅所有远端用户的视频流。

本地媒体事件

事件	描述
localAudioStateChanged	本地音频状态发生改变回调。
localVideoStateChanged	本地视频状态发生改变回调。
firstLocalAudioFramePublished	已发布本地音频首帧回调。
firstLocalVideoFramePublished	已发布本地视频首帧回调。
firstLocalVideoFrame	已显示本地视频首帧回调。
audioPublishStateChanged	音频发布状态改变回调。
videoPublishStateChanged	视频发布状态改变回调。

远端媒体事件

事件	描述
remoteAudioStateChanged	远端音频流状态发生改变回调。
remoteVideoStateChanged	远端视频状态发生改变回调。
firstRemoteVideoFrame	已显示首帧远端视频回调。
audioSubscribeStateChanged	音频订阅状态发生改变回调。
videoSubscribeStateChanged	视频订阅状态发生改变回调。
userMuteAudio	远端用户（通信场景）/主播（直播场景）停止或恢复发送音频流回调。
userMuteVideo	远端用户暂停/恢复发送视频流回调。
userEnableVideo	远端用户开/关视频模块回调。
userEnableLocalVideo	远端用户开/关本地视频采集回调。

数据统计事件

加入频道后，SDK 每隔 2 秒自动触发本组回调。

事件	描述
rtcStats	当前通话统计信息回调。
networkQuality	通话中每个用户的网络上下行 last mile 质量报告回调。
localAudioStats	通话中本地音频流的统计信息回调。
localVideoStats	本地视频流统计信息回调。
remoteAudioStats	通话中远端音频流的统计信息回调。
remoteVideoStats	通话中远端视频流的统计信息回调。

视频前处理及后处理

方法	描述
setBeautyEffectOptions	设置美颜效果选项。
enableVirtualBackground	开启/关闭虚拟背景（beta 功能）。
enableRemoteSuperResolution	开启或关闭远端视频超分辨率。
setVideoDenoiserOptions	设置视频降噪功能。
setLowlightEnhanceOptions	设置暗光增强功能。
setColorEnhanceOptions	设置色彩增强功能。

事件	描述
virtualBackgroundSourceEnabled	报告虚拟背景是否成功开启。（beta 功能）
userSuperResolutionEnabled	报告超分辨率功能是否成功开启。

多频道管理

API	描述
create	创建并获取一个 RtcChannel 对象。
RtcChannel	提供在频道中实现实时音视频功能的方法。
RtcChannelEventHandler	RtcChannelEventHandler 接口类用于 SDK 向 app 发送 RtcChannel 的事件通知。

屏幕共享

方法	描述
getAssetAbsolutePath	通过 Asset 的相对规路径获取该 Asset 的实际绝对路径。
enumerateDisplays	列举系统中所有屏幕的信息。
enumerateWindows	列举系统中所有窗口的信息。
startScreenCaptureByDisplayId	通过屏幕 ID 共享屏幕。
startScreenCaptureByWindowId	通过窗口 ID 共享窗口。
setScreenCaptureContentHint	设置屏幕共享内容类型。
updateScreenCaptureParameters	更新屏幕共享的参数配置。
updateScreenCaptureParametersMobile	更新屏幕共享的参数配置（仅支持 Android 和 iOS）。
updateScreenCaptureRegion	更新屏幕共享区域。
startScreenCaptureMobile	开始屏幕共享（仅支持 Android 和 iOS）。
stopScreenCapture	停止屏幕共享。

事件	描述
screenCaptureInfoUpdated	屏幕共享信息更新回调。

音乐文件播放及混音

方法	描述
startAudioMixing	开始播放音乐文件。
stopAudioMixing	停止播放音乐文件。
pauseAudioMixing	暂停播放音乐文件。
resumeAudioMixing	恢复播放音乐文件。
adjustAudioMixingVolume	调节音乐文件的播放音量。
adjustAudioMixingPlayoutVolume	调节音乐文件在本地播放的音量。
adjustAudioMixingPublishVolume	调节音乐文件远端播放音量。
setAudioMixingPitch	调整本地播放的音乐文件的音调。
getAudioMixingPlayoutVolume	获取音乐文件的本地播放音量。
getAudioMixingPublishVolume	获取音乐文件的远端播放音量。
getAudioMixingDuration	获取音乐文件的时长。
getAudioMixingCurrentPosition	获取音乐文件的播放进度。
setAudioMixingPosition	设置音乐文件的播放位置。
getAudioTrackCount	获取当前音乐文件的音轨索引。
selectAudioTrack	指定当前音乐文件的播放音轨。
setAudioMixingPlaybackSpeed	设置当前音乐文件的播放速度。
setAudioMixingDualMonoMode	设置当前音乐文件的声道模式。

事件	描述
audioMixingStateChanged	音乐文件的播放状态已改变回调。
remoteAudioMixingBegin	远端音乐文件播放已开始回调。
remoteAudioMixingEnd	远端音乐文件播放已结束回调。

音效文件播放管理

方法	描述
getEffectsVolume	获取音效文件的播放音量。
setEffectsVolume	设置音效文件的播放音量。
setVolumeOfEffect	实时调整音效文件的播放音量。
playEffect	播放指定的本地或在线音效文件。
stopEffect	停止播放指定音效文件。
stopAllEffects	停止播放所有音效文件。
preloadEffect	将音效文件加载至内存。
unloadEffect	从内存释放某个预加载的音效文件。
pauseEffect	暂停音效文件播放。
pauseAllEffects	暂停所有音效文件播放。
resumeEffect	恢复播放指定音效文件。
resumeAllEffects	恢复播放所有音效文件。
getEffectDuration	获取指定音效文件总时长。
setEffectPosition	设置指定音效文件的播放位置。
getEffectCurrentPosition	获取指定音效文件的播放进度。

事件	描述
audioEffectFinished	本地音效文件播放已结束回调。

音频文件信息

方法	描述
getAudioFileInfo	获取指定音频文件信息。

事件	描述
requestAudioFileInfo	音频文件信息回调。

虚拟节拍器

方法	描述
startRhythmPlayer	开启虚拟节拍器。
stopRhythmPlayer	关闭虚拟节拍器。
configRhythmPlayer	配置虚拟节拍器。

人声效果

方法	描述
setLocalVoicePitch	设置本地语音音调。
setLocalVoiceEqualization	设置本地语音音效均衡。
setLocalVoiceReverb	设置本地音效混响。
setVoiceBeautifierPreset	设置预设的美声效果。
setVoiceBeautifierParameters	设置预设美声效果的参数。
setAudioEffectPreset	设置 SDK 预设的人声音效。
setAudioEffectParameters	设置 SDK 预设人声音效的参数。
setVoiceConversionPreset	设置预设的变声效果。

听声辨位

方法	描述
enableSoundPositionIndication	开启/关闭远端用户的语音立体声。
setRemoteVoicePosition	设置远端用户声音的 2D 位置，即水平面位置。

CDN 推流

该组方法仅适用于互动直播。

方法	描述
startRtmpStreamWithoutTranscoding	开始非转码推流。
startRtmpStreamWithTranscoding	开始旁路推流并设置转码属性。
updateRtmpTranscoding	更新旁路推流转码属性。
stopRtmpStream	结束旁路推流。

事件	描述
rtmpStreamingStateChanged	旁路推流状态发生改变回调。
rtmpStreamingEvent	旁路推流事件回调。
transcodingUpdated	旁路推流转码设置已被更新回调。

跨频道媒体流转发

方法	描述
startChannelMediaRelay	开始跨频道媒体流转发。该方法可用于实现跨频道连麦等场景。
updateChannelMediaRelay	更新媒体流转发的频道。
pauseAllChannelMediaRelay	暂停向所有目标频道转发媒体流。
resumeAllChannelMediaRelay	恢复向所有目标频道转发媒体流。
stopChannelMediaRelay	停止跨频道媒体流转发。一旦停止，主播会退出所有目标频道。

事件	描述
channelMediaRelayStateChanged	跨频道媒体流转发状态发生改变回调。
channelMediaRelayEvent	跨频道媒体流转发事件回调。

音量提示

方法	描述
enableAudioVolumeIndication	启用用户音量提示。

事件	描述
audioVolumeIndication	用户音量提示回调。
activeSpeaker	监测到最活跃用户回调。

人脸检测

方法	描述
enableFaceDetection	开启/关闭本地人脸检测。

事件	描述
facePositionChanged	报告本地人脸检测结果。

音频播放路由

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

方法	描述
setDefaultAudioRouteToSpeakerphone	设置默认的音频路由。
setEnableSpeakerphone	启用/关闭扬声器播放。
isSpeakerphoneEnabled	检查扬声器状态启用状态。

事件	描述
audioRouteChanged	音频路由已发生变化回调。

耳返控制

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

方法	描述
enableInEarMonitoring	开启耳返功能。
setInEarMonitoringVolume	设置耳返音量。

视频双流模式

方法	描述
enableDualStreamMode	开关双流模式。
setRemoteVideoStreamType	设置订阅的视频流类型。
setRemoteDefaultVideoStreamType	设置默认订阅的视频流类型。

视频流回退

方法	描述
setLocalPublishFallbackOption	设置弱网条件下发布的音视频流回退选项。
setRemoteSubscribeFallbackOption	设置弱网条件下订阅的音视频流的回退选项。
setRemoteUserPriority	设置远端用户媒体流的优先级。

事件	描述
localPublishFallbackToAudioOnly	本地发布流已回退为音频流回调。
remoteSubscribeFallbackToAudioOnly	远端订阅流已回退为音频流回调。

通话前网络测试

方法	描述
startEchoTest	开始语音通话回路测试。
stopEchoTest	停止语音通话回路测试。
enableLastmileTest	启用网络测试。
disableLastmileTest	关闭网络测试。
startLastmileProbeTest	开始通话前网络质量探测。
stopLastmileProbeTest	停止通话前网络质量探测。

事件	描述
lastmileQuality	网络上下行 last mile 质量报告回调。
lastmileProbeResult	通话前网络上下行 Last mile 质量探测报告回调。

媒体附属信息

该组方法仅适用于互动直播。

方法	描述
registerMediaMetadataObserver	注册媒体 metadata 观测器用于接收或发送 metadata。
unregisterMediaMetadataObserver	取消注册媒体 metadata 观测器。
setMaxMetadataSize	设置媒体附属信息的最大大小。
sendMetadata	发送媒体附属信息。

事件	描述
metadataReceived	接收端已收到 metadata。

直播水印

该组方法仅适用于互动直播。

方法	描述
addVideoWatermark	添加本地视频水印。
clearVideoWatermarks	删除已添加的视频水印。

视频截图

方法	描述
takeSnapshot	获取视频截图。

事件	描述
snapshotTaken	视频截图结果回调。

视频截图上传

方法	描述
enableContentInspect	开启/关闭视频截图上传

加密

方法	描述
enableEncryption	开启或关闭内置加密。

音频采集

方法	描述
startAudioRecordingWithConfig	开始客户端录音。
stopAudioRecording	停止客户端录音。

音视频录制

方法	描述
getMediaRecorder	获取 MediaRecorder 对象。
startRecording	开启本地音视频流录制。
stopRecording	停止本地音视频流录制。
releaseRecorder	释放 MediaRecorder 对象。

事件	描述
onRecorderStateChanged	录制状态发生改变回调。
onRecorderInfoUpdated	录制信息更新回调。

摄像头控制

方法	描述
switchCamera	切换前置/后置摄像头。
isCameraZoomSupported	检测设备是否支持摄像头缩放功能。
isCameraTorchSupported	检测设备是否支持闪光灯常开。
isCameraFocusSupported	检测设备是否支持手动对焦功能。
isCameraExposurePositionSupported	检测设备是否支持手动曝光功能。
isCameraAutoFocusFaceModeSupported	检测设备是否支持人脸对焦功能。
setCameraTorchOn	设置是否打开闪光灯。
setCameraAutoFocusFaceModeEnabled	设置是否开启人脸对焦功能。
setCameraZoomFactor	设置摄像头缩放比例。
getCameraMaxZoomFactor	获取摄像头支持最大缩放比例。
setCameraFocusPositionInPreview	设置手动对焦位置，并触发对焦。
setCameraExposurePosition	设置手动曝光位置。

事件	描述
cameraFocusAreaChanged	相机对焦区域已改变回调。
cameraExposureAreaChanged	摄像头曝光区域已改变回调。

设备管理

方法	描述
enumerateAudioPlaybackDevices	获取系统中所有的播放设备列表。
enumerateAudioRecordingDevices	获取系统中所有的音频采集设备列表。
setAudioPlaybackDevice	指定播放设备。
setAudioRecordingDevice	指定音频采集设备。
startAudioPlaybackDeviceTest	启动音频播放设备测试。
stopAudioPlaybackDeviceTest	停止音频播放设备测试。
startAudioRecordingDeviceTest	启动音频采集设备测试。
stopAudioRecordingDeviceTest	停止音频采集设备测试。
startAudioDeviceLoopbackTest	开始音频设备回路测试。
stopAudioDeviceLoopbackTest	停止音频设备回路测试。
setAudioPlaybackDeviceVolume	设置播放设备音量。
getAudioPlaybackDeviceVolume	获取播放设备音量。
setAudioRecordingDeviceVolume	设置音频采集设备音量。
getAudioRecordingDeviceVolume	获取音频采集设备音量。
setAudioPlaybackDeviceMute	设置播放设备静音。
getAudioPlaybackDeviceMute	获取当前播放设备静音状态。
setAudioRecordingDeviceMute	设置当前音频采集设备静音。
getAudioRecordingDeviceMute	获取当前音频采集设备静音状态。
followSystemPlaybackDevice	设置 SDK 使用的音频播放设备跟随系统默认的音频播放设备。
followSystemRecordingDevice	设置 SDK 使用的音频播放设备跟随系统默认的音频播放设备。
enumerateVideoDevices	获取系统中所有的视频设备列表。
getVideoDevice	获取当前使用的视频采集设备。
setVideoDevice	通过设备 ID 指定视频采集设备。

事件	描述
audioDeviceStateChanged	音频设备变化回调。
audioDeviceVolumeChanged	回放、音频采集设备或 App 的音量发生改变。
audioDeviceTestVolumeIndication	音频设备测试回调。
videoDeviceStateChanged	视频设备变化回调。

流消息

方法	描述
createDataStreamWithConfig	创建数据流。
sendStreamMessage	发送数据流。

事件	描述
streamMessage	接收到对方数据流消息的回调。
streamMessageError	接收对方数据流消息发生错误的回调。

Wi-Fi 加速

方法	描述
enableWirelessAccelerate	开启或关闭 Wi-Fi 加速功能 。

事件	描述
wlAccStats	报告 Wi-Fi 加速效果。
wlAccMessage	报告 Wi-Fi 连接质量不佳的原因和改善 Wi-Fi 连接的操作建议。

子线程

方法	描述
getScreenShareHelper	获取一个子进程对象。

其他音频控制

方法	描述
enableLoopbackRecording	开启声卡采集。
setAudioSessionOperationRestriction	设置 SDK 对 Audio Session 的操作权限。

其他视频控制

方法	描述
setCameraCapturerConfiguration	设置摄像头采集配置。

其他方法

方法	描述
setAVSyncSource	设置发流端音画同步。
setCloudProxy	设置声网云代理服务。
enableDeepLearningDenoise	开启或关闭 AI 降噪模式。
sendCustomReportMessage	发送自定义上报消息。
getCallId	获取通话 ID。
rate	给通话评分。
complain	投诉通话质量。
getSdkVersion	获取 SDK 版本。
getErrorDescription	获取警告或错误描述。

其他事件

事件	描述
warning	发生警告回调。
error	发生错误回调。
apiCallExecuted	API 方法已执行回调。
proxyConnected	代理连接状态回调。