Agora Unity SDK API Reference

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

在调用 API 过程中，SDK 可能会返回错误码和警告码，详见错误码和警告码。

• IRtcEngine 类包含应用程序调用的主要方法。
• AgoraCallback 用于向应用程序发送回调通知。
• AgoraChannel 类在指定频道中实现实时音视频功能。通过创建多个 AgoraChannel 对象，用户可以同时加入多个频道。
• AudioEffectManagerImpl 提供管理音效文件的 API。
• AudioPlaybackDeviceManager 类提供管理音频播放设备的 API。
• AudioRecordingDeviceManager 类提供管理音频采集设备的 API。
• VideoDeviceManager 类提供管理视频采集设备的 API。
• MetadataObserver 类提供管理 metadata 媒体附属信息的 API。
• PacketObserver 类提供管理数据包观测器的 API。
• AudioRawDataManager 类提供采集或接收原始音频数据的 API。
• VideoRawDataManager 类提供采集或接收原始视频数据的 API。
• VideoSurface 类提供设置视频显示等 API。

核心方法

方法	描述
GetEngine1	初始化 IRtcEngine 实例。
GetEngine2	初始化 IRtcEngine 实例并指定访问区域。
Destroy	销毁 IRtcEngine 实例。
SetChannelProfile	设置频道场景。
SetClientRole1	设置直播场景下的用户角色。
SetClientRole2	设置直播场景下的用户角色和级别。
JoinChannelByKey	加入频道。
JoinChannel	加入频道并设置发布和订阅状态。
SwitchChannel1	快速切换直播频道。
SwitchChannel2	快速切换直播频道并设置订阅状态。
LeaveChannel	离开频道。
RenewToken	更新 Token。
GetConnectionState	获取网络连接状态。

核心事件

事件	描述
OnConnectionStateChangedHandler	网络连接状态已改变回调。
OnJoinChannelSuccessHandler	加入频道回调。
OnReJoinChannelSuccessHandler	重新加入频道回调。
OnLeaveChannelHandler	离开频道回调。
OnClientRoleChangedHandler	用户角色已切换回调。
OnUserJoinedHandler	远端用户加入当前频道回调。
OnUserOfflineHandler	远端用户离开当前频道回调。
OnNetworkTypeChangedHandler	本地网络类型发生改变回调。
OnConnectionLostHandler	网络连接丢失回调。
OnTokenPrivilegeWillExpireHandler	Token 服务即将过期回调。
OnRequestTokenHandler	Token 已过期回调。

音频管理

方法	描述
EnableAudio	启用音频模块。
DisableAudio	关闭音频模块。
SetAudioProfile	设置音频编码配置。
AdjustRecordingSignalVolume	调节麦克风采集的信号音量。
AdjustLoopbackRecordingSignalVolume	调节声卡采集信号音量。
AdjustUserPlaybackSignalVolume	调节本地播放的指定远端用户的信号音量。
AdjustPlaybackSignalVolume	调节播放所有远端用户的信号音量。
EnableLocalAudio	开关本地音频采集。
MuteLocalAudioStream	取消或恢复发布本地音频流。
MuteRemoteAudioStream	取消或恢复订阅指定远端用户的音频流。
MuteAllRemoteAudioStreams	取消或恢复订阅所有远端用户的音频流。

音量提示

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

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

人脸检测

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

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

视频管理

方法	描述
EnableVideo	开启视频模块。
EnableVideoObserver	开启视频观测器。
DisableVideo	关闭视频模块。
DisableVideoObserver	关闭视频观测器。
SetVideoEncoderConfiguration	设置视频编码配置。
SetForUser	设置本地/远端视频显示。
StartPreview	开启视频预览。
StopPreview	停止视频预览。
EnableLocalVideo	开关本地视频采集。
MuteLocalVideoStream	取消或恢复发布本地视频流。
MuteRemoteVideoStream	取消或恢复订阅指定远端用户的视频流。
MuteAllRemoteVideoStreams	取消或恢复订阅所有远端用户的视频流。

音效文件播放管理

方法	描述
GetEffectsVolume	获取音效文件的播放音量。
SetEffectsVolume	设置音效文件的播放音量。
SetVolumeOfEffect	实时调整音效文件的播放音量。
PlayEffect	播放指定的本地或在线音效文件。
StopEffect	停止播放指定音效文件。
StopAllEffects	停止播放所有音效文件。
PreloadEffect	将音效文件加载至内存。
UnloadEffect	从内存释放某个预加载的音效文件。
PauseEffect	暂停音效文件播放。
PauseAllEffects	暂停所有音效文件播放。
ResumeEffect	恢复播放指定音效文件。
ResumeAllEffects	恢复播放所有音效文件。
GetEffectDuration	获取指定音效文件总时长。
SetEffectPosition	设置指定音效文件的播放位置。
GetEffectCurrentPosition	获取指定音效文件的播放进度。
SetVoiceOnlyMode	设置仅限语音模式。

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

人声效果

方法	描述
SetVoiceBeautifierPreset	设置 SDK 预设的美声效果。
SetVoiceBeautifierParameters	设置 SDK 预设美声效果的参数。
SetAudioEffectPreset	设置 SDK 预设的人声效果。
SetAudioEffectParameters	设置 SDK 预设人声音效的参数。
SetVoiceConversionPreset	设置 SDK 预设的变声效果。
SetLocalVoicePitch	设置本地语音音调。
SetLocalVoiceEqualization	设置本地语音音效均衡。
SetLocalVoiceReverb	设置本地音效混响。

听声辨位

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

音频播放路由

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

事件	描述
OnAudioRouteChangedHandler	音频路由已改变回调。（仅适用于Android、iOS 和 macOS）

本地媒体事件

事件	描述
OnLocalAudioStateChangedHandler	本地音频状态改变回调。
OnLocalVideoStateChangedHandler	本地视频状态改变回调。
OnFirstLocalAudioFramePublishedHandler	已发布本地音频首帧回调。
OnFirstLocalVideoFramePublishedHandler	已发布本地视频首帧回调。
OnFirstLocalVideoFrameHandler	已发送本地视频首帧回调。
OnAudioPublishStateChangedHandler	音频发布状态改变回调。
OnVideoPublishStateChangedHandler	视频发布状态改变回调。

远端媒体事件

事件	描述
OnRemoteAudioStateChangedHandler	远端用户音频状态已改变回调。
OnRemoteVideoStateChangedHandler	远端用户视频状态已变化回调。
OnFirstRemoteVideoFrameHandler	已显示远端视频首帧回调。
OnAudioSubscribeStateChangedHandler	音频订阅状态发生改变回调。
OnVideoSubscribeStateChangedHandler	视频订阅状态发生改变回调。

数据统计事件

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

事件	描述
OnRtcStatsHandler	当前通话统计回调。
OnNetworkQualityHandler	网络上下行质量报告回调。
OnLocalAudioStatsHandler	通话中本地音频流统计信息回调。
OnLocalVideoStatsHandler	通话中本地视频流统计信息回调。
OnRemoteAudioStatsHandler	通话中远端音频流的统计信息回调。
OnRemoteVideoStatsHandler	通话中远端视频流统计信息回调。

视频前处理及后处理

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

方法	描述
SetBeautyEffectOptions	设置美颜效果选项。
EnableVirtualBackground	开启/关闭虚拟背景。（beta 功能）

事件	描述
OnVirtualBackgroundSourceEnabledHandler	报告虚拟背景是否成功开启。（beta 功能）

Multi-channel management

我们为该组接口提供了详细的场景描述、实现方法及开发注意事项文档，详情请参考加入多频道。

方法	描述
CreateChannel	创建并获取一个 AgoraChannel 对象。通过创建多个对象，用户可以同时加入多个频道。
SetMultiChannelWant	设置是否开启多频道模式。
SetForMultiChannelUser	在多频道中设置本地/远端视频显示。
AgoraChannel	提供在指定频道内实现实时音视频功能的方法。

屏幕共享

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

方法	描述
StartScreenCaptureByDisplayId	通过屏幕 ID 共享屏幕。
StartScreenCaptureByScreenRect	通过指定区域共享屏幕。
StartScreenCaptureByWindowId	通过窗口 ID 共享窗口。
SetScreenCaptureContentHint	设置屏幕共享内容类型。
UpdateScreenCaptureParameters	更新屏幕共享的参数配置。
UpdateScreenCaptureRegion	更新屏幕共享区域。
StopScreenCapture	停止屏幕共享。

音乐文件播放及混音

方法	描述
StartAudioMixing	开始播放音乐文件。
StopAudioMixing	停止播放音乐文件。
PauseAudioMixing	暂停播放音乐文件。
ResumeAudioMixing	恢复播放音乐文件。
AdjustAudioMixingVolume	调节音乐文件播放音量。
AdjustAudioMixingPlayoutVolume	调节音乐文件的本地播放音量。
AdjustAudioMixingPublishVolume	调节音乐文件的远端播放音量。
SetAudioMixingPitch	调整本地播放的音乐文件的音调。
GetAudioMixingPlayoutVolume	获取音乐文件的本地播放音量。
GetAudioMixingPublishVolume	获取音乐文件的远端播放音量。
GetAudioMixingDuration	获取音乐文件总时长。
GetAudioMixingCurrentPosition	获取音乐文件的播放进度。
SetAudioMixingPosition	设置音乐文件的播放位置。

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

CDN 推流

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

方法	描述
SetLiveTranscoding	设置直播转码。
AddPublishStreamUrl	增加旁路推流地址。
RemovePublishStreamUrl	删除旁路推流地址。

事件	描述
OnRtmpStreamingStateChangedHandler	RTMP/RTMPS 推流状态发生改变回调。
OnRtmpStreamingEventHandler	RTMP/RTMPS 推流状态发生改变回调。
OnTranscodingUpdatedHandler	旁路推流设置已被更新回调。

跨频道媒体流转发

方法	描述
StartChannelMediaRelay	开始跨频道媒体流转发。
UpdateChannelMediaRelay	更新媒体流转发的频道。
StopChannelMediaRelay	停止跨频道媒体流转发。

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

耳返控制

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

方法	描述
EnableInEarMonitoring	开启耳返功能。
SetInEarMonitoringVolume	设置耳返音量。

视频双流模式

方法	描述
EnableDualStreamMode	开关视频双流模式。
SetRemoteVideoStreamType	设置订阅的视频流类型。
SetRemoteDefaultVideoStreamType	设置默认订阅的视频流类型。

直播音视频回退

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

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

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

通话前网络测试

方法	描述
StartEchoTest	开始语音通话回路测试。
StopEchoTest	停止语音通话回路测试。
EnableLastmileTest	启用网络测试。
DisableLastmileTest	关闭网络测试。
StartLastmileProbeTest	开始通话前网络质量探测。
StopLastmileProbeTest	停止通话前网络质量探测。

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

视频自采集（仅 Push 模式）

方法	描述
SetExternalVideoSource	配置外部视频源。
PushVideoFrame	推送外部视频帧。

音频自采集（仅 Push 模式）

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

音频自渲染（仅 Pull 模式）

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

原始音频数据

方法	描述
RegisterAudioRawDataObserver	注册语音观测器对象。
UnRegisterAudioRawDataObserver	注销语音观测器对象。
SetOnRecordAudioFrameCallback	监听 OnRecordAudioFrameHandler delegate。
SetOnPlaybackAudioFrameCallback	监听 OnPlaybackAudioFrameHandler delegate。
SetOnPlaybackAudioFrameBeforeMixingCallback	监听 OnPlaybackAudioFrameBeforeMixingHandler delegate。
SetOnMixedAudioFrameCallback	监听 OnMixedAudioFrameHandler delegate。

事件	描述
OnRecordAudioFrameHandler	10 ms 自动回调：获得采集的声音。
OnPlaybackAudioFrameHandler	10 ms 自动回调：获得播放的声音。
OnPlaybackAudioFrameBeforeMixingHandler	10 ms 自动回调：获得混音前的指定用户的声音。
OnMixedAudioFrameHandler	10 ms 自动回调：获取采集和播放语音混音后的数据。

原始视频数据

方法	描述
RegisterVideoRawDataObserver	注册视频观测器对象。
UnRegisterVideoRawDataObserver	注销视频观测器对象。
SetOnCaptureVideoFrameCallback	监听 OnCaptureVideoFrameHandler delegate。
SetOnRenderVideoFrameCallback	监听 OnRenderVideoFrameHandler delegate。

事件	描述
OnCaptureVideoFrameHandler	获取本地摄像头采集到的视频数据。
OnRenderVideoFrameHandler	获取远端发送的视频数据。

媒体附属信息

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

方法	描述
RegisterMediaMetadataObserver	注册媒体 Metadata 观测器。
UnRegisterMediaMetadataObserver	注销媒体 Metadata 观测器。

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

直播水印

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

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

加密

方法	描述
EnableEncryption	开启或关闭内置加密。
RegisterPacketObserver	注册数据包观测器。
UnRegisterPacketObserver	注销数据包观测器。

音频录制

方法	描述
StartAudioRecording	开始客户端录音。
StopAudioRecording	停止客户端录音。

摄像头控制

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

音频设备管理

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

方法	描述
CreateAAudioPlaybackDeviceManager	创建 AudioPlaybackDeviceManager 实例。
ReleaseAAudioPlaybackDeviceManager	释放 AudioPlaybackDeviceManager 实例。
CreateAAudioRecordingDeviceManager	创建 AudioRecordingDeviceManager 实例。
ReleaseAAudioRecordingDeviceManager	释放 AudioRecordingDeviceManager 实例。
GetAudioPlaybackDeviceCount	获取系统中被索引的音频播放设备的总数。
GetAudioRecordingDeviceCount	获取系统中被索引的音频采集设备的总数。
GetAudioPlaybackDevice	获取某个被索引的音频播放设备的指定信息。
GetAudioRecordingDevice	获取某个被索引的音频采集设备的指定信息。
SetAudioPlaybackDevice	指定音频播放设备。
SetAudioRecordingDevice	指定音频采集设备。
StartAudioPlaybackDeviceTest	启动音频播放设备测试。
StopAudioPlaybackDeviceTest	停止音频播放设备测试。
StartAudioRecordingDeviceTest	启动音频采集设备测试。
StopAudioRecordingDeviceTest	停止音频采集设备测试。
SetAudioPlaybackDeviceVolume	设置当前音频播放设备的音量。
GetAudioPlaybackDeviceVolume	获取当前音频播放设备的音量。
SetAudioRecordingDeviceVolume	设置当前音频采集设备的音量。
GetAudioRecordingDeviceVolume	获取当前音频采集设备的音量。
SetAudioPlaybackDeviceMute	静音当前音频播放设备。
IsAudioPlaybackDeviceMute	获取当前音频播放设备的静音状态。
SetAudioRecordingDeviceMute	静音当前音频采集设备。
IsAudioRecordingDeviceMute	获取当前音频采集设备的静音状态。
GetCurrentPlaybackDevice	获取当前音频播放设备的 ID。
GetCurrentRecordingDevice	获取当前音频采集设备的 ID。
GetCurrentPlaybackDeviceInfo	获取当前音频播放设备的信息。
GetCurrentRecordingDeviceInfo	获取当前音频采集设备的信息。

事件	描述
OnAudioDeviceStateChangedHandler	音频设备变化回调。
OnAudioDeviceVolumeChangedHandler	回放、采集设备或 app 的音量发生改变。（仅适用于 Windows）

视频设备管理

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

方法	描述
CreateAVideoDeviceManager	创建 VideoDeviceManager 实例。
ReleaseAVideoDeviceManager	释放 VideoDeviceManager 实例。
GetVideoDeviceCount	获取系统中被索引的视频采集设备的总数。
GetVideoDevice	获取某个被索引的视频采集设备的指定信息。
SetVideoDevice	指定视频采集设备。
StartVideoDeviceTest	启动视频采集设备测试。
StopVideoDeviceTest	停止视频采集设备测试。
GetCurrentVideoDevice	获取当前视频采集设备的 ID。

事件	描述
OnVideoDeviceStateChangedHandler	视频设备变化回调。

流消息

方法	描述
CreateDataStream	创建数据流。
SendStreamMessage	发送数据流。

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

其他音频控制

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

其他视频控制

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

其他方法

方法	描述
SetGameFps	设置视频渲染帧率。
EnableFilpTextureApply	开启或关闭镜像模式。
SetVideoSurfaceType	设置视频渲染器类型。
SetEnable	开始/停止视频渲染。
SetCloudProxy	设置 Agora 云代理服务。
EnableDeepLearningDenoise	开启/关闭 AI 降噪模式。
SendCustomReportMessage	自定义数据上报。
GetCallId	获取通话 ID。
Rate	给通话评分。
Complain	投诉通话质量。
GetSdkVersion	查询 SDK 版本号。
GetErrorDescription	获取警告或错误描述。

其他事件

事件	描述
OnSDKWarningHandler	发生警告回调。
OnSDKErrorHandler	发生错误回调。
OnApiExecutedHandler	API 方法已执行回调。