API 概览
声网通过全球部署的虚拟网络,提供可以灵活搭配的 API 组合,为移动端到移动端以及移动端到 Web 端提供质量可靠的实时音视频通信。
注:
- 在调用 API 过程中,SDK 可能会返回错误码和警告码,详见错误码和警告码。
- AgoraRtcEngine 类包含应用程序调用的主要方法。
- AgoraRtcEngine.on 用于向应用程序发送回调通知。
- AgoraRtcChannel 类在指定频道中实现实时音视频功能。通过创建多个 AgoraRtcChannel 对象,用户可以同时加入多个频道。
- AgoraRtcChannel.on 监听和报告指定频道的事件和数据。
核心方法
方法 | 描述 |
---|---|
initializeWithContext | 创建并初始化 AgoraRtcEngine。 |
release | 销毁 AgoraRtcEngine 对象。 |
setChannelProfile | 设置频道场景。 |
setClientRole | 设置直播场景下的用户角色。 |
setClientRoleWithOptions | 设置直播场景下的用户角色和级别。 |
joinChannel | 加入频道并设置是否自动订阅音频或视频流。 |
switchChannel | 快速切换直播频道,并设置是否自动订阅音频流或视频流。 |
leaveChannel | 离开频道。 |
renewToken | 更新 Token。 |
getConnectionState | 获取当前网络连接状态。 |
核心事件
事件 | 描述 |
---|---|
CONNECTION_STATE_CHANGED | 网络连接状态已改变回调。 |
JOINED_CHANNEL | 成功加入频道回调。 |
REJOIN_CHANNEL_SUCCESS | 成功重新加入频道回调。 |
LEAVE_CHANNEL | 离开频道回调。 |
CLIENT_ROLE_CHANGED | 直播场景下用户角色已切换回调。 |
USER_JOINED | 远端用户(通信场景)/主播(直播场景)加入当前频道回调。 |
USER_OFFLINE | 远端用户(通信场景)/主播(直播场景)离开当前频道回调。 |
NETWORK_TYPE_CHANGED | 本地网络类型发生改变回调。 |
CONNECTION_LOST | 网络连接中断,且 SDK 无法在 10 秒内连接服务器回调。 |
TOKEN_PRIVILEGE_WILL_EXPIRE | Token 服务将在30s内过期回调。 |
REQUEST_TOKEN | Token 已过期回调。 |
音频管理
方法 | 描述 |
---|---|
enableAudio | 启用音频模块。 |
disableAudio | 关闭音频模块。 |
setAudioProfile | 设置音频编码属性。 |
adjustRecordingSignalVolume | 调节音频采集信号音量。 |
adjustUserPlaybackSignalVolume | 调节本地播放的指定远端用户信号音量。 |
adjustPlaybackSignalVolume | 调节本地播放的所有远端用户信号音量。 |
enableLocalAudio | 开关本地音频采集。 |
muteLocalAudioStream | 取消或恢复发布本地音频流。 |
muteRemoteAudioStream | 取消或恢复订阅指定远端用户的音频流。 |
muteAllRemoteAudioStreams | 取消或恢复订阅所有远端用户的音频流。 |
视频管理
方法 | 描述 |
---|---|
enableVideo | 启用视频模块。 |
disableVideo | 关闭视频模块。 |
setRenderMode | 设置渲染模式。 |
setView | 设置视频渲染。 |
destroyRenderer | 销毁视频渲染。 |
setVideoRenderDimension | 设置本地视频渲染分辨率(JavaScript 层)。 |
setVideoRenderFPS | 设置本地视频渲染帧率(JavaScript 层)。 |
setVideoEncoderConfiguration | 设置视频编码属性。 |
startPreview | 开启视频预览。 |
stopPreview | 停止视频预览。 |
enableLocalVideo | 开关本地视频采集。 |
muteLocalVideoStream | 取消或恢复发布本地视频流。 |
muteRemoteVideoStream | 取消或恢复订阅指定远端用户的视频流。 |
muteAllRemoteVideoStreams | 取消或恢复订阅所有远端用户的视频流。 |
本地媒体事件
事件 | 描述 |
---|---|
LOCAL_AUDIO_STATE_CHANGED | 本地音频状态发生改变回调。 |
LOCAL_VIDEO_STATE_CHANGED | 本地视频状态发生改变回调。 |
FIRST_LOCAL_AUDIO_FRAME_PUBLISHED | 已发布本地音频首帧回调。 |
FIRST_LOCAL_VIDEO_FRAME_PUBLISHED | 已发布本地视频首帧回调。 |
FIRST_LOCAL_VIDEO_FRAME | 已显示本地视频首帧回调。 |
AUDIO_PUBLISH_STATE_CHANGED | 音频发布状态改变回调。 |
VIDEO_PUBLISH_STATE_CHANGED | 视频发布状态改变回调。 |
远端媒体事件
事件 | 描述 |
---|---|
REMOTE_AUDIO_STATE_CHANGED | 远端音频流状态发生改变回调。 |
REMOTE_VIDEO_STATE_CHANGED | 远端视频状态发生改变回调。 |
FIRST_REMOTE_VIDEO_FRAME | 已显示首帧远端视频回调。 |
AUDIO_SUBSCRIBE_STATE_CHANGED | 音频订阅状态发生改变回调。 |
VIDEO_SUBSCRIBE_STATE_CHANGED | 视频订阅状态发生改变回调。 |
数据统计事件
加入频道后,SDK 每隔 2 秒自动触发本组回调。
事件 | 描述 |
---|---|
RTC_STATS | 当前通话统计信息回调。 |
NETWORK_QUALITY | 通话中每个用户的网络上下行 last mile 质量报告回调。 |
LOCAL_AUDIO_STATS | 通话中本地音频流的统计信息回调。 |
LOCAL_VIDEO_STATS | 本地视频流统计信息回调。 |
REMOTE_AUDIO_STATS | 通话中远端音频流的统计信息回调。 |
REMOTE_VIDEO_STATS | 通话中远端视频流的统计信息回调。 |
视频前处理及后处理
方法 | 描述 |
---|---|
setBeautyEffectOptions | 设置美颜效果选项。 |
多频道管理
API | 描述 |
---|---|
createChannel | 创建并获取一个 AgoraRtcChannel 对象。 |
AgoraRtcChannel | 提供在 AgoraRtcChannel 频道中实现实时音视频功能的方法。 |
屏幕共享
方法 | 描述 |
---|---|
startScreenCaptureByScreen | 通过指定区域共享屏幕。 |
startScreenCaptureByWindow | 通过窗口 ID 共享窗口。 |
setScreenCaptureContentHint | 设置屏幕共享内容类型。 |
updateScreenCaptureParameters | 更新屏幕共享的参数配置。 |
updateScreenCaptureRegion | 更新屏幕共享区域。 |
stopScreenCapture | 停止屏幕共享。 |
getWindowsInfo | 获取窗口信息。 |
getScreensInfo | 获取屏幕信息。 |
音乐文件播放及混音
方法 | 描述 |
---|---|
startAudioMixing | 开始播放音乐文件。 |
stopAudioMixing | 停止播放音乐文件。 |
pauseAudioMixing | 暂停播放音乐文件。 |
resumeAudioMixing | 恢复播放音乐文件。 |
adjustAudioMixingVolume | 调节音乐文件的播放音量。 |
adjustAudioMixingPlayoutVolume | 调节音乐文件在本地播放的音量。 |
adjustAudioMixingPublishVolume | 调节音乐文件远端播放音量。 |
setAudioMixingPitch | 调整本地播放的音乐文件的音调。 |
getAudioMixingPlayoutVolume | 获取音乐文件的本地播放音量。 |
getAudioMixingPublishVolume | 获取音乐文件的远端播放音量。 |
getAudioMixingDuration | 获取音乐文件的时长。 |
getAudioMixingCurrentPosition | 获取音乐文件的播放进度。 |
setAudioMixingPosition | 设置音乐文件的播放位置。 |
事件 | 描述 |
---|---|
AUDIO_MIXING_STATE_CHANGED | 音乐文件的播放状态已改变回调。 |
REMOTE_AUDIO_MIXING_BEGIN | 远端音乐文件播放已开始回调。 |
REMOTE_AUDIO_MIXING_END | 远端音乐文件播放已结束回调。 |
音效文件播放管理
方法 | 描述 |
---|---|
getEffectsVolume | 获取音效文件的播放音量。 |
setEffectsVolume | 设置音效文件的播放音量。 |
setVolumeOfEffect | 实时调整音效文件的播放音量。 |
playEffect | 播放指定的本地或在线音效文件。 |
stopEffect | 停止播放指定音效文件。 |
stopAllEffects | 停止播放所有音效文件。 |
preloadEffect | 将音效文件加载至内存。 |
unloadEffect | 从内存释放某个预加载的音效文件。 |
pauseEffect | 暂停音效文件播放。 |
resumeEffect | 恢复播放指定音效文件。 |
resumeAllEffects | 恢复播放所有音效文件。 |
getEffectDuration | 获取指定音效文件总时长。 |
setEffectPosition | 设置指定音效文件的播放位置。 |
getEffectCurrentPosition | 获取指定音效文件的播放进度。 |
事件 | 描述 |
---|---|
AUDIO_EFFECT_FINISHED | 本地音效文件播放已结束回调。 |
人声效果
方法 | 描述 |
---|---|
setLocalVoicePitch | 设置本地语音音调。 |
setLocalVoiceEqualization | 设置本地语音音效均衡。 |
setLocalVoiceReverb | 设置本地音效混响。 |
setVoiceBeautifierPreset | 设置预设的美声效果。 |
setVoiceBeautifierParameters | 设置预设美声效果的参数。 |
setAudioEffectPreset | 设置 SDK 预设的人声音效。 |
setAudioEffectParameters | 设置 SDK 预设人声音效的参数。 |
setVoiceConversionPreset | 设置预设的变声效果。 |
听声辨位
方法 | 描述 |
---|---|
enableSoundPositionIndication | 开启/关闭远端用户的语音立体声。 |
setRemoteVoicePosition | 设置远端用户的语音位置。 |
CDN 推流
该组方法仅适用于互动直播。
方法 | 描述 |
---|---|
setLiveTranscoding | 设置直播推流转码。 |
addPublishStreamUrl | 增加旁路推流地址。 |
removePublishStreamUrl | 删除旁路推流地址。 |
事件 | 描述 |
---|---|
RTMP_STREAMING_STATE_CHANGED | RTMP/RTMPS 推流状态发生改变回调。 |
RTMP_STREAMING_EVENT | RTMP/RTMPS 推流事件回调。 |
TRANSCODING_UPDATED | 旁路推流转码设置已被更新回调。 |
跨频道媒体流转发
方法 | 描述 |
---|---|
startChannelMediaRelay | 开始跨频道媒体流转发。该方法可用于实现跨频道连麦等场景。 |
updateChannelMediaRelay | 更新媒体流转发的频道。 |
stopChannelMediaRelay | 停止跨频道媒体流转发。一旦停止,主播会退出所有目标频道。 |
事件 | 描述 |
---|---|
CHANNEL_MEDIA_RELAY_STATE | 跨频道媒体流转发状态发生改变回调。 |
CHANNEL_MEDIA_RELAY_EVENT | 跨频道媒体流转发事件回调。 |
音量提示
方法 | 描述 |
---|---|
enableAudioVolumeIndication | 启用用户音量提示。 |
事件 | 描述 |
---|---|
AUDIO_VOLUME_INDICATION | 用户音量提示回调。 |
ACTIVE_SPEAKER | 监测到最活跃用户回调。 |
视频双流模式
方法 | 描述 |
---|---|
enableDualStreamMode | 开关双流模式。 |
setRemoteVideoStreamType | 设置订阅的视频流类型。 |
setRemoteDefaultVideoStreamType | 设置默认订阅的视频流类型。 |
视频流回退
方法 | 描述 |
---|---|
setLocalPublishFallbackOption | 设置弱网条件下发布的音视频流回退选项。 |
setRemoteSubscribeFallbackOption | 设置弱网条件下订阅的音视频流的回退选项。 |
setRemoteUserPriority | 设置远端用户媒体流的优先级。 |
事件 | 描述 |
---|---|
LOCAL_PUBLISH_FALLBACK_TO_AUDIO_ONLY | 本地发布流已回退为音频流回调。 |
REMOTE_SUBSCRIBE_FALLBACK_TO_AUDIO_ONLY | 远端订阅流已回退为音频流回调。 |
通话前网络测试
方法 | 描述 |
---|---|
startEchoTestWithInterval | 开始语音通话回路测试。 |
stopEchoTest | 停止语音通话回路测试。 |
enableLastmileTest | 启用网络测试。 |
disableLastmileTest | 关闭网络测试。 |
startLastmileProbeTest | 开始通话前网络质量探测。 |
stopLastmileProbeTest | 停止通话前网络质量探测。 |
事件 | 描述 |
---|---|
LASTMILE_QUALITY | 网络上下行 last mile 质量报告回调。 |
LASTMILE_PROBE_RESULT | 通话前网络上下行 Last mile 质量探测报告回调。 |
媒体附属信息
该组方法仅适用于互动直播。
方法 | 描述 |
---|---|
registerMediaMetadataObserver | 注册媒体 metadata 观测器用于接收或发送 metadata。 |
setMaxMetadataSize | 设置媒体附属信息的最大大小。 |
事件 | 描述 |
---|---|
READY_TO_SEND_METADATA | 发送端已准备好发送 Metadata。 |
METADATA_RECEIVED | 接收端已收到 Metadata。 |
直播水印
该组方法仅适用于互动直播。
方法 | 描述 |
---|---|
addVideoWatermark | 添加本地视频水印。 |
clearVideoWatermarks | 删除已添加的视频水印。 |
加密
方法 | 描述 |
---|---|
enableEncryption | 开启或关闭内置加密。 |
音频采集
方法 | 描述 |
---|---|
startAudioRecordingWithConfig | 开始客户端录音。 |
stopAudioRecording | 停止客户端录音。 |
摄像头控制
事件 | 描述 |
---|---|
CAMERA_FOCUS_AREA_CHANGED | 相机对焦区域已改变回调。 |
CAMERA_EXPOSURE_AREA_CHANGED | 摄像头曝光区域已改变回调。 |
设备管理
方法 | 描述 |
---|---|
getAudioPlaybackDevices | 获取音频播放设备列表。 |
getAudioRecordingDevices | 获取音频录制设备。 |
setAudioPlaybackDevice | 指定播放设备。 |
setAudioRecordingDevice | 指定音频采集设备。 |
startAudioPlaybackDeviceTest | 启动音频播放设备测试。 |
stopAudioPlaybackDeviceTest | 停止播放设备测试。 |
startAudioRecordingDeviceTest | 启动音频采集设备测试。 |
stopAudioRecordingDeviceTest | 停止音频采集设备测试。 |
startAudioDeviceLoopbackTest | 开始音频设备回路测试。 |
stopAudioDeviceLoopbackTest | 停止音频设备回路测试。 |
setAudioPlaybackVolume | 设置播放设备音量。 |
getAudioPlaybackVolume | 获取播放设备音量。 |
setAudioRecordingVolume | 设置音频采集设备音量。 |
getAudioRecordingVolume | 获取音频采集设备音量。 |
setAudioPlaybackDeviceMute | 设置播放设备静音。 |
getAudioPlaybackDeviceMute | 获取当前播放设备静音状态。 |
setAudioRecordingDeviceMute | 设置当前音频采集设备静音。 |
getAudioRecordingDeviceMute | 获取当前音频采集设备静音状态。 |
getVideoDevices | 获取视频设备列表。 |
startVideoDeviceTest | 开启视频采集设备测试。 |
stopVideoDeviceTest | 停止视频采集设备测试。 |
getCurrentVideoDevice | 获取当前使用的视频采集设备。 |
setVideoDevice | 通过设备 ID 指定视频采集设备。 |
事件 | 描述 |
---|---|
AUDIO_DEVICE_STATE_CHANGED | 音频设备变化回调。 |
AUDIO_DEVICE_VOLUME_CHANGED | 回放、音频采集设备或 App 的音量发生改变。 |
VIDEO_DEVICE_STATE_CHANGED | 视频设备变化回调。 |
流消息
方法 | 描述 |
---|---|
createDataStreamWithConfig | 创建数据流。 |
sendStreamMessage | 发送数据流。 |
事件 | 描述 |
---|---|
STREAM_MESSAGE | 接收到对方数据流消息的回调。 |
STREAM_MESSAGE_ERROR | 接收对方数据流消息发生错误的回调。 |
其他音频控制
方法 | 描述 |
---|---|
enableLoopbackRecording | 开启声卡采集。 |
其他视频控制
方法 | 描述 |
---|---|
setCameraCapturerConfiguration | 设置摄像头采集配置。 |
双实例
Agora Electron SDK 提供双实例的实现方法。第二个实例用以屏幕共享,请调用下表中的方法实现对应功能。
下表为以上双实例方法对应的回调。
其他方法
方法 | 描述 |
---|---|
setCloudProxy | 设置 Agora 云代理服务。 |
enableDeepLearningDenoise | 开启或关闭 AI 降噪模式。 |
sendCustomReportMessage | 发送自定义上报消息。 |
getCallId | 获取通话 ID。 |
rate | 给通话评分。 |
complain | 投诉通话质量。 |
getVersion | 获取 SDK 版本。 |
getErrorDescription | 获取警告或错误描述。 |
其他事件
事件 | 描述 |
---|---|
WARNING | 发生警告回调。 |
ERROR | 发生错误回调。 |
API_CALL_EXECUTED | API 方法已执行回调。 |