Agora C++ API Reference for All Platforms

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

自 v2.3.3 开始，Agora C++ API Reference for All Platforms 可以在 Dash 平台下载，详见 FAQ。

• IRtcEngine 接口类包含应用程序调用的主要方法。
• IRtcEngineEventHandler 接口类用于向应用程序发送回调通知。

频道管理

方法	描述
createAgoraRtcEngine	创建 RTC 引擎对象并返回指针。
initialize	初始化 Agora SDK 服务。
release	销毁 IRtcEngine 对象。
setChannelProfile	设置直播场景下的频道模式。
setClientRole	设置直播场景下的用户角色。
joinChannel	加入频道。
switchChannel	快速切换直播频道。
leaveChannel	离开频道。
renewToken	更新 Token。
enableWebSdkInteroperability	打开直播场景下与 Agora Web SDK 的互通。
getConnectionState	获取当前网络连接状态。

频道事件

事件	描述
onConnectionStateChanged	网络连接状态已改变回调。
onJoinChannelSuccess	加入频道回调。
onRejoinChannelSuccess	重新加入频道回调。
onLeaveChannel	离开频道回调。
onClientRoleChanged	直播场景下用户角色已切换回调。
onUserJoined	远端用户（通信模式）/主播（直播模式）加入当前频道回调。
onUserOffline	远端用户（通信模式）/主播（直播模式）离开当前频道回调。
onNetworkTypeChanged	本地网络类型发生改变回调。
onConnectionLost	网络连接丢失回调。
onTokenPrivilegeWillExpire	Token 服务即将过期回调。
onRequestToken	Token 已过期回调。

音频管理

方法	描述
enableAudio	启用音频模块。
disableAudio	关闭音频模块。
setAudioProfile	设置音频编码属性。
adjustRecordingSignalVolume	调节录音音量。
adjustPlaybackSignalVolume	调节播放人声的音量。
enableLocalAudio	开关本地音频采集。
muteLocalAudioStream	开关本地音频发送。
muteRemoteAudioStream	接收／停止接收指定音频流。
muteAllRemoteAudioStreams	接收／停止接收所有音频流。
setDefaultMuteAllRemoteAudioStreams	设置是否默认接收所有音频流。

视频管理

方法	描述
enableVideo	启用视频模块。
disableVideo	关闭视频模块。
setVideoEncoderConfiguration	设置视频编码属性。
setupLocalVideo	设置本地视图。
setupRemoteVideo	设置远端用户视图。
setLocalRenderMode	设置本地视图显示模式。
setRemoteRenderMode	设置远端视图显示模式。
startPreview	开启视频预览。
stopPreview	停止视频预览。
enableLocalVideo	开关本地视频采集。
muteLocalVideoStream	开关本地视频发送。
muteRemoteVideoStream	接收／停止接收指定远端用户的视频流。
muteAllRemoteVideoStreams	接收／停止接收所有远端视频流。
setDefaultMuteAllRemoteVideoStreams	设置是否默认停止接收视频流。

本地媒体事件

事件	描述
onLocalAudioStateChanged	本地音频状态改变回调。
onLocalVideoStateChanged	本地视频状态发生改变回调。
onFirstLocalAudioFrame	已发送本地音频首帧回调。
onFirstLocalVideoFrame	已显示本地视频首帧回调。

远端媒体事件

事件	描述
onRemoteAudioStateChanged	远端用户音频流状态已变化回调。
onRemoteVideoStateChanged	远端用户视频流状态已变化回调。
onUserMuteAudio	远端用户暂停/恢复发送音频流回调。
onUserMuteVideo	远端用户暂停/恢复发送视频流回调。
onFirstRemoteAudioFrame	已接收远端音频首帧回调。
onFirstRemoteAudioDecoded	已解码远端音频首帧回调。
onFirstRemoteVideoFrame	已显示远端视频首帧回调。

数据统计事件

加入频道后，SDK 每隔 2 秒自动触发本组回调。 我们为这些回调提供了详细的功能描述、实现方法文档，详情请参考检测通话质量。

事件	描述
onRtcStats	当前通话统计回调。
onNetworkQuality	网络上下行质量报告回调。
onLocalAudioStats	本地音频流统计信息回调。
onLocalVideoStats	本地视频流统计信息回调。
onRemoteAudioStats	通话中远端音频流的统计信息回调。
onRemoteVideoStats	远端视频流统计信息回调。

视频前处理及后处理

方法	描述
setBeautyEffectOptions	设置美颜效果选项（仅适用于 Android 和 iOS）。

屏幕共享

我们为该组接口提供了详细的场景描述、实现方法及开发注意事项文档，详情请参考进行屏幕共享。

方法	描述
startScreenCaptureByDisplayId	通过屏幕 ID 共享屏幕（仅适用于 macOS）。
startScreenCaptureByScreenRect	通过指定区域共享屏幕。
startScreenCaptureByWindowId	通过窗口 ID 共享窗口。
setScreenCaptureContentHint	设置屏幕共享内容类型。
updateScreenCaptureParameters	更新屏幕共享的编码参数配置。
updateScreenCaptureRegion	更新屏幕共享区域。
stopScreenCapture	停止屏幕共享。

音乐文件播放及混音

方法	描述
startAudioMixing	开始播放音乐文件。
stopAudioMixing	停止播放音乐文件。
pauseAudioMixing	暂停播放音乐文件。
resumeAudioMixing	恢复播放音乐文件。
adjustAudioMixingVolume	调节音乐文件播放音量。
adjustAudioMixingPlayoutVolume	调节音乐文件的本地播放音量。
adjustAudioMixingPublishVolume	调节音乐文件的远端播放音量。
getAudioMixingPlayoutVolume	获取音乐文件的本地播放音量。
getAudioMixingPublishVolume	获取音乐文件的远端播放音量。
getAudioMixingDuration	获取音乐文件播放时长。
getAudioMixingCurrentPosition	获取音乐文件的播放进度。
setAudioMixingPosition	设置音乐文件的播放位置。

事件	描述
onAudioMixingStateChanged	本地用户的音乐文件播放状态改变回调。
onRemoteAudioMixingBegin	远端音乐文件播放已开始回调。
onRemoteAudioMixingEnd	远端音乐文件播放已结束回调。

音效文件播放管理

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

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

变声与混响

方法	描述
setLocalVoiceChanger	设置本地语音变声。
setLocalVoiceReverbPreset	设置本地语音混响。
setLocalVoicePitch	设置本地语音音调。
setLocalVoiceEqualization	设置本地语音音效均衡。
setLocalVoiceReverb	设置本地音效混响。

听声辨位

方法	描述
enableSoundPositionIndication	开启/关闭远端用户的语音立体声。
setRemoteVoicePosition	设置远端用户的语音位置。

CDN 推流

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

方法	描述
setLiveTranscoding	设置直播转码。
addPublishStreamUrl	增加旁路推流地址。
removePublishStreamUrl	删除旁路推流地址。

事件	描述
onRtmpStreamingStateChanged	RTMP 推流状态发生改变回调。
onTranscodingUpdated	旁路推流设置已被更新回调。

跨频道媒体流转发

方法	描述
startChannelMediaRelay	开始跨频道媒体流转发。
updateChannelMediaRelay	更新媒体流转发的频道。
stopChannelMediaRelay	停止跨频道媒体流转发。

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

音量提示

方法	描述
enableAudioVolumeIndication	启用说话者音量提示。

事件	描述
onAudioVolumeIndication	提示频道内谁正在说话、说话者音量及本地用户是否在说话的回调。
onActiveSpeaker	监测到活跃用户回调。

音频播放路由

方法	描述
setDefaultAudioRouteToSpeakerphone	设置默认的音频播放路由（仅适用于 Android 和 iOS）。
setEnableSpeakerphone	启用/关闭扬声器播放（仅适用于 Android 和 iOS）。
isSpeakerphoneEnabled	查询扬声器启用状态（仅适用于 Android 和 iOS）。

事件	描述
onAudioRouteChanged	语音路由已改变回调（仅适用于 Android 和 iOS）。

耳返控制

方法	描述
setInEarMonitoringVolume	设置默认的音频播放路由（仅适用于 Android 和 iOS）。

视频双流模式

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

直播音视频回退

• 该组方法仅适用于互动直播。
• 我们为该组接口提供了详细的场景描述、实现方法及开发注意事项文档，详情请参考改善弱网环境下的用户体验。

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

事件	描述
onLocalPublishFallbackToAudioOnly	本地发布流已回退为音频流或恢复为音视频流回调。
onRemoteSubscribeFallbackToAudioOnly	远端订阅流已回退为音频流或恢复为音视频流回调。

通话前网络测试

我们为该组接口提供了详细的场景描述、实现方法及开发注意事项文档，详情请参考通话前检测网络质量。

方法	描述
startEchoTest	开始语音通话回路测试。
stopEchoTest	停止语音直播回路测试。
enableLastmileTest	启动网络测试。
disableLastmileTest	关闭网络测试。
startLastmileProbeTest	通话前网络上下行 last mile 质量报告回调。
stopLastmileProbeTest	停止通话前网络质量探测。

事件	描述
onLastmileQuality	本地网络质量报告回调。
onLastmileProbeResult	通话前网络质量探测报告回调。

自定义视频模块

• N/A

视频自采集（仅 Push 模式）

方法	描述
setExternalVideoSource	配置外部视频源。
pushVideoFrame	推送外部视频帧。

音频自采集（仅 Push 模式）

方法	描述
setExternalAudioSource	设置外部音频采集参数。
pushAudioFrame	推送外部音频帧。

音频自渲染（仅 Pull 模式）

该组方法仅适用于 Windows。

方法	描述
setExternalAudioSink	设置外部音频渲染。
pullAudioFrame	主动拉取外部音频帧。

原始音频数据

方法	描述
registerAudioFrameObserver	注册语音观测器对象。
setRecordingAudioFrameParameters	设置录制的声音格式。
setPlaybackAudioFrameParameters	设置播放的声音格式。
setMixedAudioFrameParameters	设置录制与播放声音混音后的数据格式。

事件	描述
onRecordAudioFrame	10 ms 自动回调：获得录制的声音。
onPlaybackAudioFrame	10 ms 自动回调：获得播放的声音。
onPlaybackAudioFrameBeforeMixing	10 ms 自动回调：获得混音前的指定用户的声音。
onMixedAudioFrame	10 ms 自动回调：获取录制和播放语音混音后的数据。

原始视频数据

方法	描述
registerVideoFrameObserver	注册视频观测器对象。

事件	描述
onCaptureVideoFrame	获取本地摄像头采集到的视频数据。
onRenderVideoFrame	获取远端发送的视频数据。
getVideoFormatPreference	请求视频数据格式。
getRotationApplied	设置视频数据旋转。
getMirrorApplied	设置视频数据镜像。

媒体附属信息

该组方法仅适用于互动直播。 请不要在 IRtcEngineEventHandler 中实现 getMaxMetadataSize，onReadyToSendMetadata，onMetadataReceived，和 onMetadataReceived 回调。

方法	描述
registerMediaMetadataObserver	注册媒体 Metadata 观测器。

事件	描述
getMaxMetadataSize	请求最大的 Metadata 大小回调。
onReadyToSendMetadata	发送端已准备好发送 Metadata 回调。
onMetadataReceived	接收端已收到 Metadata 回调。

直播水印

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

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

加密

方法	描述
setEncryptionSecret	启用内置加密，并设置数据加密密钥。
setEncryptionMode	设置内置的加密方案。
registerPacketObserver	注册数据包观测器。

音频录制

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

直播导入在线媒体流

• 该组方法仅适用于互动直播。
• 我们为该组接口提供了详细的场景描述、实现方法及开发注意事项文档，详情请参考输入在线媒体流。

方法	描述
addInjectStreamUrl	导入在线媒体流。
removeInjectStreamUrl	删除导入的在线媒体流。

事件	描述
onStreamInjectedStatus	导入在线媒体流状态回调。

摄像头控制

方法	描述
switchCamera	切换前置/后置摄像头（仅适用于 Android 和 iOS)。

事件	描述
onCameraFocusAreaChanged	摄像头对焦区域已改变回调。
onCameraExposureAreaChanged	摄像头曝光区域已改变回调。

设备管理

该组方法仅适用于 Windows。

方法	描述
enumeratePlaybackDevices	获取系统中所有的播放设备。
enumerateRecordingDevices	获取系统中所有的录音设备。
setPlaybackDevice	指定播放设备。
setRecordingDevice	指定录音设备。
startPlaybackDeviceTest	启动播放设备测试。
stopPlaybackDeviceTest	停止播放设备测试。
startRecordingDeviceTest	启动录音设备测试。
stopRecordingDeviceTest	停止录音设备测试。
startAudioDeviceLoopbackTest	开始音频设备回路测试。
stopAudioDeviceLoopbackTest	停止音频设备回路测试。
setPlaybackDeviceVolume	设置播放设备音量。
getPlaybackDeviceVolume	获取播放设备音量。
setRecordingDeviceVolume	设置录音设备音量。
getRecordingDeviceVolume	获取录音设备音量。
setPlaybackDeviceMute	静音播放设备。
isApplicationMute	获取 App 当前的静音状态。
getPlaybackDeviceMute	获取播放设备静音状态。
setRecordingDeviceMute	静音录音设备。
getRecordingDeviceMute	获取录音设备静音状态。
enumerateVideoDevices	获取系统中所有的视频设备列表。
startDeviceTest	启动视频采集设备测试。
stopDeviceTest	停止视频采集设备测试。
getCount	获取系统中被索引的视频采集或播放设备的总数。
getDevice	获取某个被索引的视频采集设备的指定信息。
setDevice	指定设备。

事件	描述
onAudioDeviceStateChanged	音频设备变化回调。
onAudioDeviceVolumeChanged	回放、录音设备或 App 的音量发生改变。
onVideoDeviceStateChanged	视频设备变化回调。

流消息

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

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

其他音频控制

方法	描述
enableLoopbackRecording	开启声卡采集（仅适用于 macOS 和 Windows）。
setAudioSessionOperationRestriction	设置 SDK 对 Audio Session 的控制权限（仅适用于 iOS）。

其他视频控制

方法	描述
setLocalVideoMirrorMode	设置本地视频镜像模式。
setCameraCapturerConfiguration	设置摄像头采集偏好。

其他方法

方法	描述
getCallId	获取通话 ID。
rate	给通话评分。
complain	投诉通话质量。
getVersion	查询 SDK 版本号。
setLogFile	设置日志文件。
setLogFilter	设置日志输出等级。
setLogFileSize	设置日志文件大小。
getErrorDescription	获取警告或错误描述。
queryInterface	获取设备管理员对象的指针。

其他事件

事件	描述
onWarning	发生警告回调。
onError	发生错误回调。
onApiCallExecuted	API 方法已执行回调。

定制方法

方法	描述
setParameters	通过 JSON 配置 SDK 提供技术预览或特别定制功能。