Java API Reference for Android
声网通过全球部署的虚拟网络，提供可以灵活搭配的 API 组合，为移动端到移动端以及移动端到 Web 端提供质量可靠的实时音视频通信。
RtcEngine类包含应用程序调用的主要方法。IRtcEngineEventHandler类用于向应用程序发送回调通知。RtcChannel类在指定频道中实现实时音视频功能。通过创建多个 RtcChannel 对象，用户可以同时加入多个频道。IRtcChannelEventHandler类监听和报告指定频道的事件和数据。IAudioEffectManager类提供管理音效文件的方法。AgoraMediaRecorder类提供录制本地音视频的方法和回调。
在调用 API 过程中，SDK 可能会返回错误码和警告码，详见错误码和警告码。
自 v2.3.3 开始，Java API Reference for Android 可以在 Dash 平台下载，详见 FAQ。
核心方法
| 方法 | 描述 |
|---|---|
create[1/2] | 创建 RtcEngine 实例 |
create[2/2] | 创建 RtcEngine 实例（指定访问区域） |
destroy | 销毁 RtcEngine 实例 |
setChannelProfile | 设置频道场景 |
setClientRole[1/2] | 设置直播场景下的用户角色 |
setClientRole[2/2] | 设置直播场景下的用户角色和用户级别 |
joinChannel[1/2] | 加入频道 |
joinChannel[2/2] | 加入频道并设置是否发布或自动订阅音频或视频流 |
switchChannel[1/2] | 快速切换直播频道 |
switchChannel[2/2] | 快速切换直播频道并设置订阅状态 |
leaveChannel | 离开频道 |
renewToken | 更新 Token |
getConnectionState | 获取网络连接状态 |
核心事件
| 事件 | 描述 |
|---|---|
onConnectionStateChanged | 网络连接状态已改变回调 |
onJoinChannelSuccess | 加入频道回调 |
onRejoinChannelSuccess | 重新加入频道回调 |
onLeaveChannel | 离开频道回调 |
onClientRoleChanged | 直播场景下用户角色切换成功回调 |
onClientRoleChangeFailed | 直播场景下用户角色失败回调 |
onUserJoined | 远端用户加入当前频道回调 |
onUserOffline | 远端用户离开当前频道回调 |
onNetworkTypeChanged | 本地网络类型发生改变回调 |
onConnectionLost | 网络连接丢失回调 |
onTokenPrivilegeWillExpire | Token 服务即将过期回调 |
onRequestToken | Token 已过期回调 |
音频管理
| 方法 | 描述 |
|---|---|
enableAudio | 启用音频模块 |
disableAudio | 关闭音频模块 |
setAudioProfile | 设置音频编码配置 |
adjustRecordingSignalVolume | 调节采集信号音量 |
adjustUserPlaybackSignalVolume | 调节本地播放的指定远端用户信号音量 |
adjustPlaybackSignalVolume | 调节本地播放的所有远端用户信号音量 |
enableLocalAudio | 开关本地音频采集 |
muteLocalAudioStream | 停止/恢复发送本地音频流 |
muteRemoteAudioStream | 停止/恢复接收指定音频流 |
muteAllRemoteAudioStreams | 停止/恢复接收所有音频流 |
setDefaultMuteAllRemoteAudioStreams | 设置是否默认接收音频流 |
视频管理
| 方法 | 描述 |
|---|---|
enableVideo | 启用视频模块 |
disableVideo | 关闭视频模块 |
setVideoEncoderConfiguration | 设置视频编码配置 |
setupLocalVideo | 初始化本地视图 |
setupRemoteVideo | 初始化远端用户视图 |
setLocalRenderMode | 更新本地视图显示模式 |
setRemoteRenderMode | 更新远端视图显示模式 |
CreateRendererView | 创建渲染视图 |
CreateTextureView | 创建 TextureView |
startPreview | 开启视频预览 |
stopPreview | 停止视频预览 |
enableLocalVideo | 开关本地视频采集 |
muteLocalVideoStream | 停止/恢复发送本地视频流 |
muteRemoteVideoStream | 停止/恢复接收指定视频流 |
muteAllRemoteVideoStreams | 停止/恢复接收所有视频流 |
setDefaultMuteAllRemoteVideoStreams | 设置是否默认接收视频流 |
本地媒体事件
| 事件 | 描述 |
|---|---|
onLocalAudioStateChanged | 本地音频状态改变回调 |
onLocalVideoStateChanged | 本地视频状态改变回调 |
onFirstLocalAudioFramePublished | 已发布本地音频首帧回调 |
onFirstLocalVideoFramePublished | 已发布本地视频首帧回调 |
onFirstLocalVideoFrame | 已显示本地视频首帧回调 |
onAudioPublishStateChanged | 音频发布状态改变回调 |
onVideoPublishStateChanged | 视频发布状态改变回调 |
远端媒体事件
| 事件 | 描述 |
|---|---|
onRemoteAudioStateChanged | 远端用户音频状态已改变回调 |
onRemoteVideoStateChanged | 远端用户视频状态已变化回调 |
onFirstRemoteVideoFrame | 已显示远端视频首帧回调 |
onFirstRemoteVideoDecoded | 已接收并解码远端视频首帧回调 |
onAudioSubscribeStateChanged | 音频订阅状态改变回调 |
onVideoSubscribeStateChanged | 视频订阅状态改变回调 |
onUserMuteAudio | 远端用户停止/恢复发送音频流回调 |
onUserMuteVideo | 远端用户停止/恢复发送视频流回调 |
onUserEnableLocalVideo | 远端用户开/关本地视频采集回调 |
onUserEnableVideo | 远端用户开/关视频模块回调 |
数据统计事件
- 加入频道后，SDK 每隔 2 秒自动触发本组回调。
- 我们为这些回调提供了详细的功能描述、实现方法文档，详情请参考通话中质量监测。
| 事件 | 描述 |
|---|---|
onRtcStats | 当前通话统计回调 |
onNetworkQuality | 网络上下行质量报告回调 |
onLocalAudioStats | 通话中本地音频流统计信息回调 |
onLocalVideoStats | 通话中本地视频流统计信息回调 |
onRemoteAudioStats | 通话中远端音频流的统计信息回调 |
onRemoteVideoStats | 通话中远端视频流统计信息回调 |
视频前处理及后处理
| 方法 | 描述 |
|---|---|
setBeautyEffectOptions | 设置美颜效果选项 |
enableVirtualBackground | 开启/关闭虚拟背景 |
enableRemoteSuperResolution | 开启/关闭远端视频超分辨率（beta 功能） |
setVideoDenoiserOptions | 设置视频降噪功能 |
setLowlightEnhanceOptions | 设置暗光增强功能 |
setColorEnhanceOptions | 设置色彩增强功能 |
| 事件 | 描述 |
|---|---|
onVirtualBackgroundSourceEnabled | 报告虚拟背景是否成功开启 |
onUserSuperResolutionEnabled | 报告超分辨率功能是否成功开启（beta 功能） |
多频道管理
我们为该组接口提供了详细的场景描述、实现方法及开发注意事项文档，详情请参考加入多频道。
| API | 描述 |
|---|---|
createRtcChannel | 创建并获取一个 RtcChannel 对象。通过创建多个对象，用户可以同时加入多个频道。 |
RtcChannel | 提供在指定频道内实现实时音视频功能的方法。 |
IRtcChannelEventHandler | 提供监听指定频道事件和数据的回调。 |
屏幕共享
| 方法 | 描述 |
|---|---|
startScreenCapture | 开始屏幕共享 |
stopScreenCapture | 结束屏幕共享 |
updateScreenCaptureParameters | 更新屏幕共享配置 |
音乐文件播放及混音
| 方法 | 描述 |
|---|---|
startAudioMixing | 开始播放音乐文件 |
stopAudioMixing | 停止播放音乐文件 |
pauseAudioMixing | 暂停播放音乐文件 |
resumeAudioMixing | 恢复播放音乐文件 |
adjustAudioMixingVolume | 调节音乐文件播放音量 |
adjustAudioMixingPlayoutVolume | 调节音乐文件的本地播放音量 |
adjustAudioMixingPublishVolume | 调节音乐文件的远端播放音量 |
setAudioMixingPitch | 调整本地播放的音乐文件的音调 |
getAudioMixingPlayoutVolume | 获取音乐文件的本地播放音量 |
getAudioMixingPublishVolume | 获取音乐文件的远端播放音量 |
getAudioMixingCurrentPosition | 获取音乐文件的播放进度 |
setAudioMixingPosition | 设置音乐文件的播放位置 |
getAudioTrackCount | 获取当前音乐文件的音轨数量 |
selectAudioTrack | 指定当前音乐文件的播放音轨 |
setAudioMixingPlaybackSpeed | 设置当前音乐文件的播放速度 |
setAudioMixingDualMonoMode | 设置当前音乐文件的声道模式 |
| 事件 | 描述 |
|---|---|
onAudioMixingStateChanged | 本地用户的音乐文件播放状态已改变回调 |
音效文件播放管理
| 方法 | 描述 |
|---|---|
getAudioEffectManager | 获取 IAudioEffectManager 类，以管理音效文件 |
getEffectsVolume | 获取播放音效文件音量 |
setEffectsVolume | 设置播放音效文件音量 |
setVolumeOfEffect | 实时调整播放音效文件音量 |
playEffect | 播放指定音效文件 |
stopEffect | 停止播放指定音效文件 |
stopAllEffects | 停止播放所有音效文件 |
preloadEffect | 将音效文件加载至内存 |
unloadEffect | 从内存释放某个预加载的音效文件 |
pauseEffect | 暂停音效文件播放 |
pauseAllEffects | 暂停所有音效文件播放 |
resumeEffect | 恢复播放指定音效文件 |
resumeAllEffects | 恢复播放所有音效文件 |
getEffectCurrentPosition | 获取指定音效文件的播放进度 |
setEffectPosition | 设置指定音效文件的播放位置 |
| 事件 | 描述 |
|---|---|
onAudioEffectFinished | 本地音效文件播放已结束回调 |
音频文件信息
| 方法 | 描述 |
|---|---|
getAudioFileInfo | 获取指定音频文件信息 |
getEffectDuration | 获取指定音频文件信息 |
| 事件 | 描述 |
|---|---|
onRequestAudioFileInfo | 音频文件信息回调 |
虚拟节拍器
| 方法 | 描述 |
|---|---|
startRhythmPlayer | 开启虚拟节拍器 |
configRhythmPlayer | 配置虚拟节拍器 |
stopRhythmPlayer | 关闭虚拟节拍器 |
人声效果
| 方法 | 描述 |
|---|---|
setAudioEffectPreset | 设置 SDK 预设的人声音效 |
setVoiceBeautifierPreset | 设置 SDK 预设的美声效果 |
setVoiceBeautifierParameters | 设置 SDK 预设美声效果的参数 |
setAudioEffectParameters | 设置 SDK 预设人声音效的参数 |
setLocalVoicePitch | 设置本地语音音调 |
enableLocalVoicePitchCallback | 开启本地语音音调回调 |
setLocalVoiceEqualization | 设置本地语音音效均衡 |
setLocalVoiceReverb | 设置本地音效混响 |
setVoiceConversionPreset | 设置 SDK 预设的变声效果 |
| 事件 | 描述 |
|---|---|
onLocalVoicePitchInHz | 报告本地用户的语音音调 |
听声辨位
| 方法 | 描述 |
|---|---|
enableSoundPositionIndication | 开启/关闭远端用户的语音立体声 |
setRemoteVoicePosition | 设置远端用户的语音位置 |
旁路推流
该组方法仅适用于互动直播。
| 方法 | 描述 |
|---|---|
startRtmpStreamWithoutTranscoding | 开始非转码推流 |
startRtmpStreamWithTranscoding | 开始 CDN 直播推流并设置转码属性 |
updateRtmpTranscoding | 更新转码属性 |
stopRtmpStream | 结束 CDN 直播推流 |
| 事件 | 描述 |
|---|---|
onRtmpStreamingStateChanged | 旁路推流状态改变回调 |
onRtmpStreamingEvent | RTMP/RTMPS 推流事件回调 |
onTranscodingUpdated | 旁路推流设置已被更新回调 |
跨频道媒体流转发
| 方法 | 描述 |
|---|---|
startChannelMediaRelay | 开始跨频道媒体流转发 |
updateChannelMediaRelay | 更新媒体流转发的频道 |
pauseAllChannelMediaRelay | 暂停向所有目标频道转发媒体流 |
resumeAllChannelMediaRelay | 恢复跨频道媒体流转发 |
stopChannelMediaRelay | 停止向所有目标频道转发媒体流 |
| 事件 | 描述 |
|---|---|
onChannelMediaRelayStateChanged | 跨频道媒体流转发状态发生改变回调 |
onChannelMediaRelayEvent | 跨频道媒体流转发事件回调 |
音量提示
| 方法 | 描述 |
|---|---|
enableAudioVolumeIndication | 启用说话者音量提示 |
| 事件 | 描述 |
|---|---|
onAudioVolumeIndication | 提示频道内谁正在说话及说话者音量的回调 |
onActiveSpeaker | 监测到远端最活跃用户回调 |
人脸检测
| 方法 | 描述 |
|---|---|
enableFaceDetection | 开启/关闭本地人脸检测 |
| 事件 | 描述 |
|---|---|
onFacePositionChanged | 报告本地人脸检测结果 |
语音播放路由
| 方法 | 描述 |
|---|---|
setDefaultAudioRoutetoSpeakerphone | 设置默认的音频路由 |
setEnableSpeakerphone | 开启/关闭扬声器播放 |
isSpeakerphoneEnabled | 查询扬声器启用状态 |
| 事件 | 描述 |
|---|---|
onAudioRouteChanged | 语音路由已改变回调 |
耳返控制
| 方法 | 描述 |
|---|---|
enableInEarMonitoring | 开启耳返功能 |
setInEarMonitoringVolume | 设置耳返音量 |
视频双流模式
| 方法 | 描述 |
|---|---|
enableDualStreamMode | 开关视频双流模式 |
setRemoteVideoStreamType | 设置订阅的视频流类型 |
setRemoteDefaultVideoStreamType | 设置默认订阅的视频流类型 |
音视频回退
我们为该组接口提供了详细的场景描述、实现方法及开发注意事项文档，详情请参考改善弱网环境下的用户体验。
| 方法 | 描述 |
|---|---|
setLocalPublishFallbackOption | 设置弱网条件下发布的音视频流回退选项 |
setRemoteSubscribeFallbackOption | 设置弱网条件下订阅的音视频流回退选项 |
setRemoteUserPriority | 设置用户媒体流优先级 |
| 事件 | 描述 |
|---|---|
onLocalPublishFallbackToAudioOnly | 本地发布流已回退为音频流或恢复为音视频流回调 |
onRemoteSubscribeFallbackToAudioOnly | 远端订阅流已回退为音频流或恢复为音视频流回调 |
通话前网络测试
我们为该组接口提供了详细的场景描述、实现方法及开发注意事项文档，详情请参考通话前检测。
| 方法 | 描述 |
|---|---|
startEchoTest[2/3] | 开始音频通话回路测试 |
startEchoTest[3/3] | 开始音视频通话回路测试 |
stopEchoTest | 停止通话回路测试 |
enableLastmileTest | 启用网络测试 |
disableLastmileTest | 关闭网络测试 |
startLastmileProbeTest | 开始通话前网络质量探测 |
stopLastmileProbeTest | 停止通话前网络质量探测 |
| 事件 | 描述 |
|---|---|
onLastmileQuality | 本地网络质量报告回调 |
onLastmileProbeResult | 本地网络上下行 Last-mile 质量报告回调 |
自定义视频模块
| 方法 | 描述 |
|---|---|
setVideoSource | 设置自定义视频源 |
setLocalVideoRenderer | 自定义本地视频渲染器 |
setRemoteVideoRenderer | 自定义远端视频渲染器 |
视频自采集（仅适用于 Push 模式）
| 方法 | 描述 |
|---|---|
setExternalVideoSource | 配置外部视频源 |
pushExternalVideoFrame | 推送外部视频帧 |
isTextureEncodeSupported | 检查视频是否支持 Texture 编码 |
音频自采集（仅适用于 Push 模式）
| 方法 | 描述 |
|---|---|
setExternalAudioSource | 设置外部音频采集参数 |
pushExternalAudioFrame | 推送外部音频帧到指定位置 |
setExternalAudioSourceVolume | 设置指定位置的外部音频帧音量 |
音频自渲染
| 方法 | 描述 |
|---|---|
setExternalAudioSink | 设置外部音频渲染 |
pullPlaybackAudioFrame | 拉取外部音频数据 |
原始音频数据
| 方法 | 描述 |
|---|---|
registerAudioFrameObserver | 注册语音观测器对象 |
setRecordingAudioFrameParameters | 设置采集的音频格式 |
setPlaybackAudioFrameParameters | 设置播放的声音的格式 |
setMixedAudioFrameParameters | 设置采集与播放声音混音后的数据格式 |
| 事件 | 描述 |
|---|---|
onRecordFrame | 获得采集的音频 |
onPlaybackFrame | 获得播放的声音 |
onPlaybackFrameBeforeMixing | 获取单个远端用户混音前的音频数据 |
onMixedFrame | 获取本地用户和所有远端用户混音后的原始音频数据 |
isMultipleChannelFrameWanted | 设置是否获取多个频道的原始音频数据 |
onPlaybackFrameBeforeMixingEx | 获取各频道单个远端用户混音前的音频播放数据 |
getObservedAudioFramePosition | 设置音频观测位置 |
getRecordAudioParams | 设置 onRecordFrame 回调数据的格式 |
getPlaybackAudioParams | 设置 onPlaybackFrame 回调数据的格式 |
getMixedAudioParams | 设置 onMixedFrame 回调数据的格式 |
原始视频数据
| 方法 | 描述 |
|---|---|
registerVideoFrameObserver | 注册原始视频数据观测器 |
| 事件 | 描述 |
|---|---|
getObservedFramePosition | 设置视频观测位置 |
onCaptureVideoFrame | 获取本地采集的视频数据 |
onPreEncodeVideoFrame | 获取本地编码前的视频数据 |
onRenderVideoFrame | 获取接收到的远端视频数据 |
getVideoFormatPreference | 设置 SDK 输出的原始视频数据格式 |
getRotationApplied | 设置是否旋转 SDK 输出的原始视频数据 |
getMirrorApplied | 设置是否镜像 SDK 输出的原始视频数据 |
isMultipleChannelFrameWanted | 设置 SDK 是否输出多个频道内接收到的远端视频数据 |
onRenderVideoFrameEx | 获取多个频道内接收到的远端视频数据 |
本地视频编码数据
你可以使用 C++ 的本地视频编码数据接口，实现相关功能。
| 方法 | 描述 |
|---|---|
registerVideoEncodedFrameObserver | 注册本地视频编码数据观测器 |
| 事件 | 描述 |
|---|---|
onVideoEncodedFrame | 获取本地视频编码数据 |
媒体附属信息
请不要在 IRtcEngineEventHandler 类中实现
getMaxMetadataSize、onReadyToSendMetadata和onMetadataReceived回调。
| 方法 | 描述 |
|---|---|
registerMediaMetadataObserver | 注册媒体 Metadata 观测器 |
| 事件 | 描述 |
|---|---|
getMaxMetadataSize | 请求 Metadata 的最大数据大小 |
onReadyToSendMetadata | 发送端已准备好发送 Metadata |
onMetadataReceived | 接收端已收到 Metadata |
直播水印
该组方法仅适用于互动直播。
| 方法 | 描述 |
|---|---|
addVideoWatermark | 添加本地视频水印 |
clearVideoWatermarks | 删除已添加的视频水印 |
视频截图
| 方法 | 描述 |
|---|---|
takeSnapshot | 获取视频截图 |
| 事件 | 描述 |
|---|---|
onSnapshotTaken | 视频截图结果回调 |
视频截图上传
| 方法 | 描述 |
|---|---|
enableContentInspect | 开启/关闭视频截图上传 |
加密
| 方法 | 描述 |
|---|---|
enableEncryption | 开启/关闭内置加密 |
音频录制
| 方法 | 描述 |
|---|---|
startAudioRecording | 开始客户端录音 |
stopAudioRecording | 停止客户端录音 |
音视频录制
| 方法 | 描述 |
|---|---|
getMediaRecorder | 获取 AgoraMediaRecorder 对象 |
startRecording | 开启本地音视频流录制 |
stopRecording | 停止本地音视频流录制 |
release | 释放 AgoraMediaRecorder 对象 |
| 事件 | 描述 |
|---|---|
onRecorderStateChanged | 录制状态发生改变回调 |
onRecorderInfoUpdated | 录制信息更新回调 |
摄像头控制
| 方法 | 描述 |
|---|---|
switchCamera | 切换前置/后置摄像头 |
isCameraZoomSupported | 检测设备是否支持摄像头缩放功能 |
isCameraTorchSupported | 检查设备是否支持打开闪光灯 |
isCameraFocusSupported | 检测设备是否支持手动对焦功能 |
isCameraExposurePositionSupported | 检测设备是否支持手动曝光功能 |
isCameraAutoFocusFaceModeSupported | 检测设备是否支持人脸对焦功能 |
setCameraZoomFactor | 设置摄像头缩放比例 |
getCameraMaxZoomFactor | 获取摄像头支持最大缩放比例 |
setCameraFocusPositionInPreview | 设置手动对焦位置，并触发对焦 |
setCameraExposurePosition | 设置手动曝光位置 |
setCameraTorchOn | 设置是否打开闪光灯 |
setCameraAutoFocusFaceModeEnabled | 设置是否开启人脸对焦功能 |
| 事件 | 描述 |
|---|---|
onCameraFocusAreaChanged | 摄像头对焦区域已改变回调 |
onCameraExposureAreaChanged | 摄像头曝光区域已改变回调 |
设备管理
- N/A
流消息
| 方法 | 描述 |
|---|---|
createDataStream | 创建数据流 |
sendStreamMessage | 发送数据流 |
| 事件 | 描述 |
|---|---|
onStreamMessage | 接收到对方数据流消息的回调 |
onStreamMessageError | 接收对方数据流消息发生错误的回调 |
Wi-Fi 加速
| 方法 | 描述 |
|---|---|
enableWirelessAccelerate | 开启或关闭 Wi-Fi 加速功能 |
| 事件 | 描述 |
|---|---|
onWlAccMessage | 报告 Wi-Fi 连接质量不佳的原因和改善 Wi-Fi 连接的操作建议 |
onWlAccStats | 报告 Wi-Fi 加速效果 |
网络代理
| 方法 | 描述 |
|---|---|
setCloudProxy | 设置声网云代理服务 |
setLocalAccessPoint | 设置本地代理。 |
| 事件 | 描述 |
|---|---|
onProxyConnected | 代理连接状态回调 |
其他视频控制
| 方法 | 描述 |
|---|---|
setCameraCapturerConfiguration | 设置摄像头的采集配置 |
其他音频控制
- N/A
其他方法
| 方法 | 描述 |
|---|---|
setAVSyncSource | 设置发流端音画同步 |
enableDeepLearningDenoise | 开启或关闭 AI 降噪模式 |
sendCustomReportMessage | 自定义数据上报 |
getCallId | 获取通话 ID |
rate | 给通话评分 |
complain | 投诉通话质量 |
getSdkVersion | 查询 SDK 版本号 |
getErrorDescription | 获取警告或错误描述 |
getNativeHandle | 获取 SDK 引擎的 Native 句柄 |
addHandler | 添加 IRtcEngineEventHandler 主回调事件 |
removeHandler | 删除指定的 IRtcEngineEventHandler 回调句柄 |
setAgoraLibPath | 设置 .so 文件的存储目录 |
其他事件
| 事件 | 描述 |
|---|---|
onWarning | 发生警告回调 |
onError | 发生错误回调 |
onApiCallExecuted | API 方法已执行回调 |
