Java API Reference for Android

发生警告回调。

该回调方法表示 SDK 运行时出现了（网络或媒体相关的）警告。通常情况下，SDK 上报的警告信息 App 可以忽略，SDK 会自动恢复。 例如和服务器失去连接时，SDK 可能会上报 WARN_LOOKUP_CHANNEL_TIMEOUT 警告，同时自动尝试重连。

参数

warn	警告代码，详细定义见 Warning Code

发生错误回调。

表示 SDK 运行时出现了（网络或媒体相关的）错误。通常情况下，SDK 上报的错误意味着 SDK 无法自动恢复，需要 App 干预或提示用户。例如启动通话失败时，SDK 会上报 ERR_START_CALL 错误。App 可以提示用户启动通话失败，并调用 leaveChannel 退出频道。

参数

err	错误代码，详细定义见 Error Code

加入频道回调。

表示客户端已经登入服务器，且分配了频道 ID 和用户 ID。频道 ID 的分配是根据 joinChannel 方法中指定的频道名称。如果调用 joinChannel 时并未指定用户 ID，服务器就会分配一个。

参数

channel	频道名
uid	用户 ID 。如果 joinChannel 中指定了 uid，则此处返回该 ID；否则使用声网服务器自动分配的 ID
elapsed	从 joinChannel 开始到发生此事件过去的时间（毫秒)

重新加入频道回调。

有时候由于网络原因，客户端可能会和服务器失去连接，SDK 会进行自动重连，自动重连成功后触发此回调方法。

参数

channel	频道名
uid	用户 ID。如果 joinChannel 中指定了 uid，则此处返回该 ID；否则使用声网服务器自动分配的 ID
elapsed	从调用 joinChannel 方法到触发该回调的时间间隔（毫秒）。

离开频道回调。

App 调用 leaveChannel 方法时，SDK 提示 App 离开频道成功。 在该回调方法中，App 可以得到此次通话的总通话时长、SDK 收发数据的流量等信息。

参数

stats

通话相关的统计信息：RtcStats

直播场景下用户角色切换成功回调。

直播场景下，本地用户加入频道后调用 setClientRole 成功改变用户角色时， 例如主播切换为观众，或观众切换为主播，SDK 会触发该回调，报告切换前和切换后的角色。

参数

oldRole	切换前的角色： CLIENT_ROLE_BROADCASTER(1)：主播。 CLIENT_ROLE_AUDIENCE(2)：观众。
newRole	切换后的角色： CLIENT_ROLE_BROADCASTER(1)：主播。 CLIENT_ROLE_AUDIENCE(2)：观众。

本地用户成功注册 User Account 回调。

自从

v2.8.0。

本地用户成功调用 registerLocalUserAccount 方法注册用户 User Account，或调用 joinChannelWithUserAccount 加入频道后，SDK 会触发该回调，并告知本地用户的 UID 和 User Account。

参数

uid	本地用户的 ID
userAccount	本地用户的 User Account

远端用户信息已更新回调。

自从

v2.8.0。

远端用户加入频道后， SDK 会获取到该远端用户的 UID 和 User Account，然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表，并在本地触发该回调。

参数

uid	本地用户 ID
userInfo	标识用户信息的 UserInfo 对象，包含用户 UID 和 User Account，详见 UserInfo 类

远端用户（通信场景）/主播（直播场景）加入当前频道回调。

• 通信场景下，该回调提示有远端用户加入了频道，并返回新加入用户的 ID；如果加入之前，已经有其他用户在频道中了，新加入的用户也会收到这些已有用户加入频道的回调
• 直播场景下，该回调提示有主播加入了频道，并返回该主播的用户 ID。如果在加入之前，已经有主播在频道中了，新加入的用户也会收到已有主播加入频道的回调。声网建议连麦主播不超过 17 人

该回调在如下情况下会被触发：

• 远端用户/主播调用 joinChannel 方法加入频道。
• 远端用户加入频道后调用 setClientRole 将用户角色改变为主播。
• 远端用户/主播网络中断后重新加入频道。

参数

uid	新加入频道的远端用户/主播 ID
elapsed	从本地用户调用 joinChannel/setClientRole 到触发该回调的延迟（毫秒）

注解

直播场景下：

• 主播间能相互收到新主播加入频道的回调，并能获得该主播的用户 ID
• 观众也能收到新主播加入频道的回调，并能获得该主播的用户 ID
• 当 Web 端加入直播频道时，只要 Web 端有推流，SDK 会默认该 Web 端为主播，并触发该回调

远端用户（通信场景）/主播（直播场景）离开当前频道回调。

提示有远端用户/主播离开了频道（或掉线）。用户离开频道有两个原因，即正常离开和超时掉线：

• 正常离开的时候，远端用户/主播会收到类似“再见”的消息，接收此消息后，判断用户离开频道
• 超时掉线的依据是，在一定时间内（约 20 秒），用户没有收到对方的任何数据包，则判定为对方掉线。在网络较差的情况下，有可能会误报。声网建议使用声网实时消息 SDK 来做可靠的掉线检测。

参数

uid	主播 ID
reason	离线原因： USER_OFFLINE_QUIT(0)：用户主动离开。 USER_OFFLINE_DROPPED(1)：因过长时间收不到对方数据包，超时掉线。**Note:** 由于 SDK 使用的是不可靠通道，也有可能对方主动离开本方没收到对方离开消息而误判为超时掉线。在 Android 系统上，用户通过手势滑动杀死 app 后，因系统限制，SDK 会报告 USER_OFFLINE_DROPPED(1)，而非报告 USER_OFFLINE_QUIT(0)。 USER_OFFLINE_BECOME_AUDIENCE(2)：直播场景下，用户身份从主播切换为观众。

代理连接状态回调。

自从

v3.6.2

通过该回调你可以监听 SDK 连接代理的状态。例如，当用户调用 setCloudProxy 或 setLocalAccessPoint 设置云代理或本地代理 并成功加入频道后，SDK 会触发该回调报告用户 ID、连接的代理类型和从调用 joinChannel 到触发该回调经过的时间等。

参数

channel	频道名称。
uid	用户 ID。
proxyType	连接上的代理类型： PROXY_TYPE_NONE_PROXY(0)：调用 setLocalAccessPoint 并加入了频道，但未连接本地代理。 PROXY_TYPE_UDP_CLOUD_PROXY(1)：UDP 协议的云代理，即 Force UDP 云代理模式。在该模式下，SDK 始终通过 UDP 协议传输数据。 PROXY_TYPE_TCP_CLOUD_PROXY(2)：TCP（加密）协议的云代理，即 Force TCP 云代理模式。在该模式下，SDK 始终通过 TLS 443 传输数据。 PROXY_TYPE_LOCAL_PROXY(3)：调用 setLocalAccessPoint 方法并连接到本地代理。 PROXY_TYPE_TCP_AUTO_FALLBACK(4)：自动模式。在该模式下，SDK 优先连接 SD-RTN™，如果连接失败，自动切换为 TLS 443。
localProxyIp	本地代理的 IP 地址。当 proxyType 的值不为 3 时，该参数的值为空。
elapsed	从调用 joinChannel 到 SDK 触发该回调的经过的时间（毫秒）。

网络连接状态已改变回调。

自从

v2.3.2。

该回调在网络连接状态发生改变的时候触发，并告知用户当前的网络连接状态，和引起网络状态改变的原因。

参数

state

当前的网络连接状态： CONNECTION_STATE_DISCONNECTED(1)：网络连接断开。 CONNECTION_STATE_CONNECTING(2)：建立网络连接中。 CONNECTION_STATE_CONNECTED(3)：网络已连接。 CONNECTION_STATE_RECONNECTING(4)：重新建立网络连接中。 CONNECTION_STATE_FAILED(5)：网络连接失败。

reason

引起当前网络连接状态发生改变的原因： CONNECTION_CHANGED_CONNECTING(0)：建立网络连接中。 CONNECTION_CHANGED_JOIN_SUCCESS(1)：成功加入频道。 CONNECTION_CHANGED_INTERRUPTED(2)：网络连接中断。 CONNECTION_CHANGED_BANNED_BY_SERVER(3)：网络连接被服务器禁止。 可能是由于服务端调用封禁用户权限 API 将用户踢出频道。请在应用中弹框提示“用户被踢出频道。” CONNECTION_CHANGED_JOIN_FAILED(4)：加入频道失败。 当 SDK 收到 onConnectionStateChanged(connection_state_reconnecting, connection_changed_interrupted) 后连续 20 分钟无法重新加入频道时，会报告该状态并停止重连。请在应用中弹框显示“因网络问题无法加入频道。请尝试切换网络并重新加入频道。” CONNECTION_CHANGED_LEAVE_CHANNEL(5)：离开频道 CONNECTION_CHANGED_INVALID_APP_ID(6)：不是有效的 APP ID。 请检查用户使用的 App ID 是否与从声网控制台获取的项目的 App ID 一致，并更换有效的 APP ID 重新加入频道。 CONNECTION_CHANGED_INVALID_CHANNEL_NAME(7)：不是有效的频道名。频道名不能为空，且字符长度不能超过 64 字节，支持的字符集详见 joinChannel 的 channelName 参数描述。 请在应用中弹框提示“频道名不合法。请更换有效的频道名并重新加入频道。” CONNECTION_CHANGED_INVALID_TOKEN(8)：Token 无效。一般有以下原因： 在控制台上启用了 App Certificate，但加入频道未使用 Token。当启用了 App Certificate，必须使用 Token。 在调用 joinChannel 加入频道时指定的 uid 与生成 Token 时传入的 uid 不一致。 请检查用户使用的 Token 是否与业务服务器上生成的 Token 一致，并更换有效的 Token 重新加入频道。 CONNECTION_CHANGED_TOKEN_EXPIRED(9)：请检查用户使用的 Token 是否与业务服务器上生成的 Token一致，并更换有效的 Token 重新加入频道。 CONNECTION_CHANGED_REJECTED_BY_SERVER(10)：此用户被服务器禁止。一般有以下原因： 用户已进入频道，再次调用加入频道的 API，例如 joinChannel。 用户在调用 startEchoTest 进行通话测试时尝试加入频道。等待通话测试结束后再加入频道即可。 CONNECTION_CHANGED_SETTING_PROXY_SERVER(11)：由于设置了代理服务器，SDK 尝试重连 CONNECTION_CHANGED_RENEW_TOKEN(12)：更新 Token 引起网络连接状态改变 CONNECTION_CHANGED_CLIENT_IP_ADDRESS_CHANGED(13)：由于网络类型，或网络运营商的 IP 或端口发生改变，客户端 IP 地址变更，SDK 尝试重连。 如果多次出现该状态，请在应用中弹框提示“您的网络连接不稳定，建议切换网络。” CONNECTION_CHANGED_KEEP_ALIVE_TIMEOUT(14)：SDK 和服务器连接保活超时，进入自动重连状态。 CONNECTION_CHANGED_SAME_UID_LOGIN(19)：使用相同的 UID 从不同的设备加入同一频道。 CONNECTION_CHANGED_TOO_MANY_BROADCASTERS(20)：频道内主播人数已达上限。

网络连接中断回调。

弃用:

从 v2.3.2 起废弃。声网不建议你使用。如果你希望获取 SDK 的网络连接状态改变事件，请改用 onConnectionStateChanged 回调。

SDK 在和服务器建立连接后，失去了网络连接超过 4 秒，会触发该回调。在触发事件后，SDK 会主动重连服务器，所以该事件可以用于 UI 提示。 与 onConnectionLost 回调的区别是：

• onConnectionInterrupted 回调一定是发生在 joinChannel() 成功后，且 SDK 刚失去和服务器连接超过 4 秒时触发
• onConnectionLost 回调是无论之前 joinChannel() 是否连接成功，只要 10 秒内和服务器无法建立连接都会触发

如果 SDK 在断开连接后，20 分钟内还是没能重新加入频道，SDK 会停止尝试重连。

网络连接中断，且 SDK 无法在 10 秒内连接服务器回调。

SDK 在调用 joinChannel() 后，无论是否加入成功，只要 10 秒和服务器无法连接就会触发该回调。 与 onConnectionInterrupted 回调的区别是：

• onConnectionInterrupted 回调一定是发生在 joinChannel() 成功后，且 SDK 刚失去和服务器连接 4 秒时触发
• onConnectionLost 回调是无论之前 joinChannel() 是否连接成功，只要 10 秒内和服务器无法建立连接都会触发

如果 SDK 在断开连接后，20 分钟内还是没能重新加入频道，SDK 会停止尝试重连。

网络连接已被服务器禁止回调。

弃用:

从 v2.3.2 起废弃。声网不建议你使用。如果你希望获取 SDK 的网络连接状态改变事件，请改用 onConnectionStateChanged 回调。

当你被服务端禁掉连接的权限时，会触发该回调。

API 方法已执行回调。

参数

error	错误码。如果方法调用失败，会返回错误码 Error code；如果返回 0，则表示方法调用成功
api	SDK 所调用的 API
result	SDK 调用 API 的调用结果

Token 服务即将过期回调。

在调用 joinChannel 时如果指定了 Token，由于 Token 具有一定的时效，在通话过程中如果 Token 即将失效，SDK 会提前 30 秒触发该回调，提醒 App 更新 Token。当收到该回调时，你需要重新在服务端生成新的 Token，然后调用 renewToken 将新生成的 Token 传给 SDK。

参数

token

即将服务失效的 Token

Token 过期回调。

在调用 joinChannel 时如果指定了 Token，

由于 Token 具有一定的时效，在通话过程中 SDK 可能由于网络原因和服务器失去连接，重连时可能需要新的 Token。

该回调通知 App 需要生成新的 Token，并调用 renewToken 更新 Token。

麦克风状态已改变回调。

弃用:

v2.9.0。该回调已废弃。请改用 onLocalAudioStateChanged 回调中的 LOCAL_AUDIO_STREAM_STATE_STOPPED(0) 或 LOCAL_AUDIO_STREAM_STATE_CAPTURING(1)。

该回调由本地用户调用 enableLocalAudio 方法开启或关闭本地音频采集触发的。

参数

enabled

true：麦克风已启用 false：麦克风已禁用

用户音量提示回调。

该回调默认禁用。可以通过 enableAudioVolumeIndication 方法开启。开启后，只要频道内有发流用户，SDK 会在加入频道后按 enableAudioVolumeIndication 中设置的时间间隔触发 onAudioVolumeIndication 回调。每次会触发两个 onAudioVolumeIndication 回调，一个报告本地发流用户的音量相关信息，另一个报告瞬时音量最高的远端用户（最多 3 位）的音量相关信息。

注解

启用该功能后，如果有用户将自己静音（调用了 muteLocalAudioStream），SDK 行为会受如下影响：

• 本地用户静音后，SDK 立即停止报告本地用户的音量提示回调。
• 瞬时音量最高的远端用户静音后 20 秒，远端的音量提示回调中将不再包含该用户；如果远端所有用户都将自己静音，20 秒后 SDK 停止报告远端用户的音量提示回调。

参数

speakers	用户音量信息，详见 AudioVolumeInfo 数组。如果 speakers 为空，则表示远端用户不发流或没有远端用户。
totalVolume	混音后的总音量，取值范围为 [0,255]。 在本地用户的回调中，totalVolume 为本地发流用户的音量。 在远端用户的回调中，totalVolume 为瞬时音量最高的远端用户（最多 3 位）混音后的总音量。 如果用户调用了 startAudioMixing，则 totalVolume 为音乐文件和用户声音的总音量。

报告本地用户的语音音调。

自从

v3.7.0

开启本地音频采集并调用 enableLocalVoicePitchCallback 后，SDK 会按 enableLocalVoicePitchCallback 中设置的时间间隔触发 onLocalVoicePitchInHz 回调，报告本地用户的语音音调。

注解

启用该功能后，如果用户关闭了本地音频采集，例如， 调用了 enableLocalAudio(false)，SDK 会停止发送 onLocalVoicePitchInHz

参数

pitchInHz

本地用户的语音音调，单位为 Hz。

监测到远端最活跃用户回调。

成功调用 enableAudioVolumeIndication 后， SDK 会持续监测音量最大的远端用户，并统计该用户被判断为音量最大者的次数。当前时间段内，该次数累积最多的远端用户为最活跃的用户。

当频道内用户数量大于或等于 2 且有活跃用户时，SDK 会触发该回调并报告最活跃用户的 uid。

• 如果最活跃用户一直是同一位用户，则 SDK 不会再次触发 onActiveSpeaker 回调。
• 如果最活跃用户有变化，则 SDK 会再次触发该回调并报告新的最活跃用户的 uid。

参数

uid	远端最活跃用户的 ID。

已发送本地音频首帧回调。

弃用:

自 v3.1.0 起废弃。请改用 IRtcEngineEventHandler#onFirstLocalAudioFramePublished()。

参数

elapsed

从本地用户调用 joinChannel 方法直至该回调被触发的延迟（毫秒）

已发布本地音频首帧回调。

自从

v3.1.0。

SDK 会在以下三种时机触发该回调：

• 开启本地音频的情况下，调用 joinChannel 成功加入频道后。
• 调用 muteLocalAudioStream(true)，再调用 muteLocalAudioStream(false) 后。
• 调用 disableAudio，再调用 enableAudio 后。
• 调用 pushExternalAudioFrame 成功向 SDK 推送音频帧后。

参数

elapsed

从调用 joinChannel 方法到触发该回调的时间间隔（毫秒）。

已接收远端音频首帧回调。

弃用:

v3.0.0。该回调已废弃。请改用 onRemoteAudioStateChanged 中的 REMOTE_AUDIO_STATE_STARTING(1)。

参数

uid	发送音频帧的远端用户的 ID
elapsed	从调用 joinChannel 方法直至该回调被触发的延迟（毫秒）

已解码远端音频首帧回调。

弃用:

v3.0.0。该回调已废弃，请改用 onRemoteAudioStateChanged 中的 REMOTE_AUDIO_STATE_DECODING(2)。

SDK 完成远端音频首帧解码，并发送给音频模块用以播放时，会触发此回调。有两种情况：

• 远端用户首次上线后发送音频。
• 远端用户音频离线再上线发送音频。音频离线指本地在 15 秒内没有收到音频包，可能有如下原因：
  • 远端用户离开频道。
  • 远端用户掉线。
  • 远端用户停止发送音频流（调用了 muteLocalAudioStream 方法）。
  • 远端用户关闭音频（调用了 disableAudio 方法）。

参数

uid	用户 ID，指定是哪个用户的音频流
elapsed	从本地用户调用 joinChannel 方法加入频道直至该回调触发的延迟，单位为毫秒

视频功能停止回调。

弃用:

从 v2.4.1 起废弃。请改用 onLocalVideoStateChanged 回调中的 LOCAL_VIDEO_STREAM_STATE_STOPPED(0)。

提示视频功能已停止。 App 如需在停止视频后对 view 做其他处理（例如显示其他画面），可以在这个回调中进行。

已显示本地视频首帧回调。

第一帧本地视频显示在本地视图上时，触发此回调。

参数

width	本地渲染视频的宽（px）
height	本地渲染视频的高（px）
elapsed	从本地用户调用 joinChannel 方法直至该回调被触发的延迟（毫秒） 如果在 joinChannel 之前调用了 startPreview，则返回的是从调用 startPreview 直至该回调被触发的延迟（毫秒）

已发布本地视频首帧回调。

自从

v3.1.0。

SDK 会在以下时机触发该回调：

• 开启本地视频的情况下，调用 joinChannel 成功加入频道后。
• 调用 muteLocalVideoStream(true)，再调用 muteLocalVideoStream(false) 后。
• 调用 disableVideo，再调用 enableVideo 后。
• 调用 pushExternalVideoFrame 成功向 SDK 推送视频帧后。

  参数

  elapsed

  从调用 joinChannel 方法到触发该回调的时间间隔（毫秒）。

已完成远端视频首帧解码回调。

本地收到远端第一个视频帧并解码成功后，会触发该回调。有两种情况：

• 远端用户首次上线后发送视频
• 远端用户视频离线再上线后发送视频

其中，视频离线与用户离线不同。视频离线指本地在 15 秒内没有收到视频包，可能有如下原因：

• 远端用户离开频道
• 远端用户掉线
• 远端用户停止发送本地视频流（调用了 muteLocalVideoStream）
• 远端用户关闭本地视频模块（调用了 disableVideo）

参数

uid	用户 ID，指定是哪个用户的视频流
width	视频流宽（像素）
height	视频流高（像素）
elapsed	从本地用户调用 joinChannel 方法直至该回调被触发的延迟（毫秒）

已显示远端视频首帧回调。 第一帧远端视频显示在视图上时，触发此调用。App 可在此调用中获知出图时间（elapsed）。

参数

uid	用户 ID，指定是哪个用户的视频流
width	视频流宽（像素）
height	视频流高（像素）
elapsed	从本地用户调用 joinChannel 加入频道开始到发生此事件过去的时间（毫秒）

远端用户停止/恢复发送音频流回调。

提示有其他用户将他的音频流静音/取消静音。

该回调是由远端用户调用 muteLocalAudioStream 方法关闭或开启音频发送触发的。

注解

当频道内的用户（通信场景）或主播（直播场景）的人数超过 17 时，该回调可能不准确。

参数

uid	用户 ID
muted	该用户是否静音： true: 该用户已静音音频 false: 该用户已取消音频静音

远端用户取消或恢复发布视频流回调。

当远端用户调用 muteLocalVideoStream 取消或恢复发布视频流时，SDK 会触发该回调向本地用户报告远端用户的发流状况。

注解

当频道内的用户（通信场景）或主播（直播场景）的人数超过 17 时，该回调可能不准确。

参数

uid	远端用户 UID。
muted	远端用户是否取消发布视频流： true：取消发布视频流。 false：发布视频流。

远端用户开/关视频模块回调。

提示有其他用户启用/关闭了视频功能。

该回调是由远端用户调用 enableVideo 或 disableVideo 方法开启或关闭视频模块触发的。

参数

uid	用户 ID，提示是哪个用户的视频流
enabled	true：该用户已启用视频功能。启用后，该用户可以进行视频通话或直播。 false：该用户已关闭视频功能。关闭后，该用户只能进行语音通话或直播，不能显示、发送自己的视频，也不能接收、显示别人的视频。

远端用户开/关本地视频采集回调。

提示有其他用户启用/关闭了本地视频功能。

该回调是由远端用户调用 enableLocalVideo 方法开启或关闭视频采集触发的。

参数

uid	用户 ID，提示是哪个用户的视频流
enabled	true：该用户已启用本地视频功能。启用后，其他用户可以接收到该用户的视频流 false：该用户已关闭视频功能。关闭后，该用户仍然可以接收其他用户的视频流，但其他用户接收不到该用户的视频流

本地或远端视频大小或旋转信息发生改变回调。

参数

uid	图像尺寸和旋转信息发生变化的用户 ID。如果返回的 uid 为 0，则表示本地用户
width	视频流的宽度（像素）
height	视频流的高度（像素）
rotation	旋转信息 [0，360]

远端音频状态发生改变回调。

自从

v2.9.0。

远端用户（通信场景）或主播（直播场景）音频状态发生改变时，SDK 会触发该回调向本地用户报告当前的远端音频流状态。

注解

当频道内的用户（通信场景）或主播（直播场景）的人数超过 17 时，该回调可能不准确。

参数

uid	发生音频状态改变的远端用户 ID
state	远端音频流状态: REMOTE_AUDIO_STATE_STOPPED(0)：远端音频流默认初始状态。 在 REMOTE_AUDIO_REASON_LOCAL_MUTED(3)、REMOTE_AUDIO_REASON_REMOTE_MUTED(5) 或 REMOTE_AUDIO_REASON_REMOTE_OFFLINE(7) 的情况下，会报告该状态。 REMOTE_AUDIO_STATE_STARTING(1)：本地用户已接收远端音频首包。 REMOTE_AUDIO_STATE_DECODING(2)：远端音频流正在解码，正常播放。在 REMOTE_AUDIO_REASON_NETWORK_RECOVERY(2)、 REMOTE_AUDIO_REASON_LOCAL_UNMUTED(4) 或 REMOTE_AUDIO_REASON_REMOTE_UNMUTED(6) 的情况下，会报告该状态。 REMOTE_AUDIO_STATE_FROZEN(3)：远端音频流卡顿。在 REMOTE_AUDIO_REASON_NETWORK_CONGESTION(1) 的情况下，会报告该状态。 REMOTE_AUDIO_STATE_FAILED(4)：远端音频流播放失败。在 REMOTE_AUDIO_REASON_INTERNAL(0) 的情况下，会报告该状态。
reason	远端音频流状态改变的具体原因： REMOTE_AUDIO_REASON_INTERNAL(0)：音频状态发生改变时，会报告该原因。 REMOTE_AUDIO_REASON_NETWORK_CONGESTION(1)：远端用户的网络阻塞。如果网络状态持续不佳，请在应用中弹框显示“对方的网络状态不佳”。 REMOTE_AUDIO_REASON_NETWORK_RECOVERY(2)：远端用户的网络恢复正常。请在应用中弹框显示“对方的网络状态恢复正常”。 REMOTE_AUDIO_REASON_LOCAL_MUTED(3)：本地用户停止接收远端音频流或本地用户禁用音频模块。请在应用中弹框显示“你已静音对方”。 REMOTE_AUDIO_REASON_LOCAL_UNMUTED(4)：本地用户恢复接收远端音频流或本地用户启用音频模块。请在应用中弹框显示“你已取消静音对方”。 REMOTE_AUDIO_REASON_REMOTE_MUTED(5)：远端用户停止发送音频流或远端用户禁用音频模块。请在应用界面的用户列表中用图标显示该远端用户已静音，并在应用中弹框显示“对方已静音自己”。 REMOTE_AUDIO_REASON_REMOTE_UNMUTED(6)：远端用户恢复发送音频流或远端用户启用音频模块。请在应用界面的用户列表中用图标显示该远端用户已取消静音，并在应用中弹框显示“对方已取消静音自己”。 REMOTE_AUDIO_REASON_REMOTE_OFFLINE(7)：远端用户离开频道。请在应用界面的用户列表中移除该远端用户。
elapsed	从本地用户调用 joinChannel 方法到发生本事件经历的时间，单位为 ms

音频发布状态改变回调。

自从

v3.1.0。

发布状态包括：

• PUB_STATE_IDLE(0)
• PUB_STATE_NO_PUBLISHED(1)
• PUB_STATE_PUBLISHING(2)
• PUB_STATE_PUBLISHED(3)

参数

channel	频道名。
oldState	之前的发布状态。
newState	当前的发布状态。
elapseSinceLastState	两次状态变化时间间隔（毫秒）。

视频发布状态改变回调。

自从

v3.1.0。

发布状态包括：

• PUB_STATE_IDLE(0)
• PUB_STATE_NO_PUBLISHED(1)
• PUB_STATE_PUBLISHING(2)
• PUB_STATE_PUBLISHED(3)

参数

channel	频道名。
oldState	之前的发布状态。
newState	当前的发布状态。
elapseSinceLastState	两次状态变化时间间隔（毫秒）。

音频订阅状态发生改变回调。

自从

v3.1.0。

订阅状态包括：

• SUB_STATE_IDLE(0)
• SUB_STATE_NO_SUBSCRIBED(1)
• SUB_STATE_SUBSCRIBING(2)
• SUB_STATE_SUBSCRIBED(3)

参数

channel	频道名。
uid	远端用户的 ID。
oldState	之前的订阅状态。
newState	当前的订阅状态。
elapseSinceLastState	两次状态变化时间间隔（毫秒）。

视频订阅状态发生改变回调。

自从

v3.1.0。

订阅状态包括：

• SUB_STATE_IDLE(0)
• SUB_STATE_NO_SUBSCRIBED(1)
• SUB_STATE_SUBSCRIBING(2)
• SUB_STATE_SUBSCRIBED(3)

参数

channel	频道名。
uid	远端用户的 ID。
oldState	之前的订阅状态。
newState	当前的订阅状态。
elapseSinceLastState	两次状态变化时间间隔（毫秒）。

远端用户视频状态发生改变回调。

自从

v2.9.0。

注解

当频道内的用户（通信场景）或主播（直播场景）的人数超过 17 时，该回调可能不准确。

参数

uid	发生视频状态改变的远端用户 ID
state	远端视频流状态: REMOTE_VIDEO_STATE_STOPPED(0)：远端视频默认初始状态。在 REMOTE_VIDEO_STATE_REASON_LOCAL_MUTED(3)、 REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED(5) 或 REMOTE_VIDEO_STATE_REASON_REMOTE_OFFLINE(7) 的情况下，会报告该状态。 REMOTE_VIDEO_STATE_STARTING(1)：本地用户已接收远端视频首包。 REMOTE_VIDEO_STATE_DECODING(2)：远端视频流正在解码，正常播放。在 REMOTE_VIDEO_STATE_REASON_NETWORK_RECOVERY(2)、 REMOTE_VIDEO_STATE_REASON_LOCAL_UNMUTED(4)、REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED(6) 或 REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK_RECOVERY(9) 的情况下，会报告该状态。 REMOTE_VIDEO_STATE_FROZEN(3)：远端视频流卡顿。在 REMOTE_VIDEO_STATE_REASON_NETWORK_CONGESTION(1) 或 REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK(8) 的情况下，会报告该状态。 REMOTE_VIDEO_STATE_FAILED(4)：远端视频流播放失败。在 REMOTE_VIDEO_STATE_REASON_INTERNAL(0) 的情况下，会报告该状态。
reason	远端视频流状态改变的具体原因： REMOTE_VIDEO_STATE_REASON_INTERNAL(0)：视频状态发生改变时，会报告该原因。 REMOTE_VIDEO_STATE_REASON_NETWORK_CONGESTION(1)：远端用户的网络阻塞。如果网络状态持续不佳，请在应用中弹框显示“对方的网络状态不佳”。 REMOTE_VIDEO_STATE_REASON_NETWORK_RECOVERY(2)：远端用户的网络恢复正常。请在应用中弹框显示“对方的网络状态恢复正常”。 REMOTE_VIDEO_STATE_REASON_LOCAL_MUTED(3)：本地用户停止接收远端视频流或本地用户禁用视频模块。请关闭用于渲染该远端用户视频的窗口并在应用中弹框显示“你已停止接收对方视频”。 REMOTE_VIDEO_STATE_REASON_LOCAL_UNMUTED(4)：本地用户恢复接收远端视频流或本地用户启动视频模块。请恢复用于渲染该远端用户视频的窗口并在应用中弹框显示“你已恢复接收对方视频”。 REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED(5)：远端用户停止发送视频流或远端用户禁用视频模块。请关闭用于渲染该远端用户视频的窗口，在应用界面的用户列表中用图标显示该远端用户已停止发送视频，在应用中弹框显示“对应已关闭摄像头”。 REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED(6)：远端用户恢复发送视频流或远端用户启用视频模块。请恢复用于渲染该远端用户视频的窗口，在应用界面的用户列表中用图标显示该远端用户已恢复发送视频，在应用中弹框显示“对应已开启摄像头”。 REMOTE_VIDEO_STATE_REASON_REMOTE_OFFLINE(7)：远端用户离开频道。请关闭用于渲染该远端用户视频的窗口，在应用界面的用户列表中移除该远端用户。 REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK(8)：弱网情况下，远端音视频流回退为音频流。请关闭用户渲染该远端用户视频的窗口，在应用中弹框显示“对方网络状态不佳”。 REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK_RECOVERY(9)：网络情况改善时，远端音频流恢复为音视频流。请恢复用于渲染该远端用户视频的窗口，在应用中弹框显示“对方网络状态恢复正常”。 - REMOTE_VIDEO_STATE_REASON_SDK_IN_BACKGROUND(10): 当远端用户使用 iOS 应用且应用处于后台时，SDK 会向本地用户报告该错误码。此时，本地用户看到远端用户视频卡住。
elapsed	从本地用户调用 joinChannel 方法到发生本事件经历的时间，单位为 ms

报告超分辨率功能是否成功开启。(beta 功能）

自从

v3.5.1

调用 enableRemoteSuperResolution 后，SDK 触发该回调报告超分辨率是否成功开启。如果未成功开启，请通过 reason 排查问题。

参数

uid	远端用户 ID。
enabled	是否对远端视频成功开启超分辨率： true：成功开启超分辨率。 false：未成功开启超分辨率。
reason	超分辨率功能未成功开启的原因： SR_STATE_REASON_SUCCESS(0)：超分辨率已成功开启。 SR_STATE_REASON_STREAM_OVER_LIMITATION(1)：远端用户的原始视频分辨率超出了可以应用超分辨率功能的范围。 SR_STATE_REASON_USER_COUNT_OVER_LIMITATION(2)：已对一个远端用户的视频使用超分辨率。 SR_STATE_REASON_DEVICE_NOT_SUPPORTED(3)： 设备不支持使用超分辨率。 SR_STATE_REASON_INSUFFICIENT_PERFORMANCE(4): 开启或运行超分辨率功能时，SDK 检测到用户设备性能不足。收到该原因码后，声网建议用户关闭虚拟背景功能。

报告虚拟背景是否成功开启。

自从

v3.5.0

调用 enableVirtualBackground 后，SDK 触发该回调报告虚拟背景是否成功开启。

注解

如果虚拟背景中自定义的背景图为 PNG、JPG 格式的图片，该回调的触发时机会延迟到图片读取完毕。

参数

enabled

是否已成功开启虚拟背景： true：成功开启虚拟背景。 false：未成功开启虚拟背景。

reason

虚拟背景开启出错的原因或开启成功的提示。 VBS_STATE_REASON_SUCCESS(0)：虚拟背景已成功开启。 VBS_STATE_REASON_IMAGE_NOT_EXIST(1)：自定义的背景图不存在。请检查 VirtualBackgroundSource 中 source 的值。 VBS_STATE_REASON_COLOR_FORMAT_NOT_SUPPORTED(2)：自定义的背景图颜色格式出错。请检查 VirtualBackgroundSource 中 color 的值。 VBS_STATE_REASON_DEVICE_NOT_SUPPORTED(3)：设备不支持使用虚拟背景。 VBS_STATE_REASON_INSUFFICIENT_PERFORMANCE(4)：开启或运行虚拟背景功能时，SDK 检测到用户设备性能不足。收到该原因码后，声网建议用户关闭虚拟背景功能。

视频截图结果回调。

自从

v3.5.2

成功调用 takeSnapshot 后，SDK 触发该回调报告截图是否成功和获取截图的详情。

参数

channel	频道名。
uid	用户 ID。如果 uid 为 0，表示本地用户。
filePath	截图的本地保存路径。
width	图片宽度（px）。
height	图片高度（px）。
errCode	截图成功的提示或失败的原因： 0：截图成功。 < 0：截图失败。 -1：写入文件失败或 JPEG 编码失败。 -2：takeSnapshot 方法调用成功后 1 秒内没有发现指定用户的视频流。

跨频道媒体流转发状态发生改变回调。

自从

v2.9.0。

当跨频道媒体流转发状态发生改变时，SDK 会触发该回调，并报告当前的转发状态以及相关的错误信息。

参数

state

跨频道媒体流转发状态： RELAY_STATE_IDLE(0)：SDK 正在初始化 RELAY_STATE_CONNECTING(1)：SDK 尝试跨频道 RELAY_STATE_RUNNING(2)：源频道主播成功加入目标频道 RELAY_STATE_FAILURE(3)：发生异常，详见 code 中提示的错误信息

code

跨频道媒体流转发出错的错误码： RELAY_OK(0)：一切正常 RELAY_ERROR_SERVER_ERROR_RESPONSE(1)：服务器回应出错 RELAY_ERROR_SERVER_NO_RESPONSE(2)：服务器无回应。该错误也可能是由于当前的 App ID 未开启跨频道连麦服务导致的。你可以提交工单申请开通跨频道连麦服务。 RELAY_ERROR_NO_RESOURCE_AVAILABLE(3)：SDK 无法获取服务，可能是因为服务器资源有限导致 RELAY_ERROR_FAILED_JOIN_SRC(4)：发起跨频道转发媒体流请求失败 RELAY_ERROR_FAILED_JOIN_DEST(5)：接受跨频道转发媒体流请求失败 RELAY_ERROR_FAILED_PACKET_RECEIVED_FROM_SRC(6)：服务器接收跨频道转发媒体流失败 RELAY_ERROR_FAILED_PACKET_SENT_TO_DEST(7)：服务器发送跨频道转发媒体流失败 RELAY_ERROR_SERVER_CONNECTION_LOST(8)：SDK 因网络质量不佳与服务器断开。你可以调用 leaveChannel 方法离开当前频道 RELAY_ERROR_INTERNAL_ERROR(9)：服务器内部出错 RELAY_ERROR_SRC_TOKEN_EXPIRED(10)：源频道的 Token 已过期 RELAY_ERROR_DEST_TOKEN_EXPIRED(11)：目标频道的 Token 已过期

跨频道媒体流转发事件回调。

自从

v2.9.0。

该回调报告跨频道媒体流转发过程中发生的事件。

参数

code

跨频道媒体流转发事件码： RELAY_EVENT_NETWORK_DISCONNECTED(0)：网络中断导致用户与服务器连接断开 RELAY_EVENT_NETWORK_CONNECTED(1)：用户与服务器建立连接 RELAY_EVENT_PACKET_JOINED_SRC_CHANNEL(2)：用户已加入源频道 RELAY_EVENT_PACKET_JOINED_DEST_CHANNEL(3)：用户已加入目标频道 RELAY_EVENT_PACKET_SENT_TO_DEST_CHANNEL(4)：SDK 开始向目标频道发送数据包 RELAY_EVENT_PACKET_RECEIVED_VIDEO_FROM_SRC(5)：服务器收到了源频道发送的视频流 RELAY_EVENT_PACKET_RECEIVED_AUDIO_FROM_SRC(6)：服务器收到了源频道发送的音频流 RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL(7)：目标频道已更新 RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL_REFUSED(8)：内部原因导致目标频道更新失败 RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL_NOT_CHANGE(9)：目标频道未发生改变，即目标频道更新失败 RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL_IS_NULL(10)：目标频道名为 NULL RELAY_EVENT_VIDEO_PROFILE_UPDATE(11)：视频属性已发送至服务器 RELAY_EVENT_PAUSE_SEND_PACKET_TO_DEST_CHANNEL_SUCCESS(12)：成功暂停向目标频道转发媒体流 RELAY_EVENT_PAUSE_SEND_PACKET_TO_DEST_CHANNEL_FAILED(13)：暂停向目标频道转发媒体流失败 RELAY_EVENT_RESUME_SEND_PACKET_TO_DEST_CHANNEL_SUCCESS(14)：成功恢复向目标频道转发媒体流 RELAY_EVENT_RESUME_SEND_PACKET_TO_DEST_CHANNEL_FAILED(15)：恢复向目标频道转发媒体流失败

本地发布流已回退为音频流回调。

如果你调用了设置本地推流回退选项 setLocalPublishFallbackOption 接口并将 option 设置为 AUDIO_ONLY(2) 时，当上行网络环境不理想、本地发布的媒体流回退为音频流时，或当上行网络改善、媒体流恢复为音视频流时，会触发该回调。 如果本地推流已回退为音频流，远端的 App 上会收到 onRemoteVideoStateChanged 的回调事件。

参数

isFallbackOrRecover

本地推流已回退或恢复： true：由于网络环境不理想，本地发布的媒体流已回退为音频流。 false：由于网络环境改善，发布的音频流已恢复为音视频流。

远端订阅流已回退为音频流回调或因网络质量改善，恢复为音视频流。

如果你调用了设置远端订阅流回退选项 setRemoteSubscribeFallbackOption 接口并将 option 设置为 AUDIO_ONLY(2) 时，当下行网络环境不理想、仅接收远端音频流时，或当下行网络改善、恢复订阅音视频流时，会触发该回调。

远端订阅流因弱网环境不能同时满足音视频而回退为小流时，你可以使用onRemoteVideoStats 回调来监控远端视频大小流的切换。

参数

uid	远端用户的 ID
isFallbackOrRecover	远端订阅流已回退或恢复： true：由于网络环境不理想，远端订阅流已回退为音频流。 false：由于网络环境改善，订阅的音频流已恢复为音视频流。

音频路由已变更回调。

参数

routing

当前的音频路由： AUDIO_ROUTE_DEFAULT(-1)：使用默认的音频路由。 AUDIO_ROUTE_HEADSET(0)：音频路由为带麦克风的耳机。 AUDIO_ROUTE_EARPIECE(1)：音频路由为听筒。 AUDIO_ROUTE_HEADSETNOMIC(2)：音频路由为不带麦克风的耳机。 AUDIO_ROUTE_SPEAKERPHONE(3)：音频路由为设备自带的扬声器。 AUDIO_ROUTE_LOUDSPEAKER(4)：(暂不支持)音频路由为外接的扬声器。 AUDIO_ROUTE_HEADSETBLUETOOTH(5)：音频路由为蓝牙耳机。

摄像头就绪回调。

弃用:

从 v2.4.1 起废弃。请改用 onLocalVideoStateChanged 回调中的 LOCAL_VIDEO_STREAM_STATE_CAPTURING(1)。

提示已成功打开摄像头，可以开始捕获视频。如果摄像头打开失败，可在 onError 中处理相应错误。

摄像头对焦区域已改变回调。

该回调表示相机的对焦区域发生了改变。

该回调是由本地用户调用 setCameraFocusPositionInPreview 方法改变对焦位置触发的。

参数

rect	镜头内表示对焦的区域

摄像头曝光区域已改变回调。

该回调是由本地用户调用 setCameraExposurePosition 方法改变曝光位置触发的。

自从

v2.3.2。

参数

rect	镜头内表示曝光的区域

报告本地人脸检测结果。

自从

3.0.1

调用 enableFaceDetection(true) 开启本地人脸检测后，你可以通过该回调实时获取以下人脸检测的信息：

• 摄像头采集的画面大小
• 人脸在 view 中的位置
• 人脸距设备屏幕的距离

其中，人脸距设备屏幕的距离由 SDK 通过摄像头采集的画面大小和人脸在 view 中的位置拟合计算得出。

注解

• 当检测到摄像头前没有人脸时，该回调触发频率会降低，以节省设备耗能。
• 当人脸距离设备屏幕过近时，SDK 不会触发该回调。
• Android 平台上，人脸距设备屏幕的距离（distance）值有一定误差，请不要用它进行精确计算。

参数

imageWidth	摄像头采集画面的宽度 (px)
imageHeight	摄像头采集画面的高度 (px)
faces	检测到的人脸信息，详见 AgoraFacePositionInfo。检测到几张人脸，就会报告几个 AgoraFacePositionInfo 数组。数组长度可以为 0，表示没有检测到摄像头前出现人脸。

远端音频质量回调。

弃用:

从 v2.3.2 起废弃。声网不建议你使用。如果你希望获取远端音频的质量回调，请改用 onRemoteAudioStats 方法。

该回调描述远端用户在通话中的音频质量，针对每个远端用户/主播每 2 秒触发一次。如果远端同时存在多个用户/主播，该回调每 2 秒会被触发多次。

参数

uid	用户 ID，指定是谁发的音频流
quality	语音质量： QUALITY_UNKNOWN(0)：质量未知 QUALITY_EXCELLENT(1)：质量极好 QUALITY_GOOD(2)：用户主观感觉和极好差不多，但码率可能略低于极好 QUALITY_POOR(3)：用户主观感受有瑕疵但不影响沟通 QUALITY_BAD(4)：勉强能沟通但不顺畅 QUALITY_VBAD(5)：网络质量非常差，基本不能沟通 QUALITY_DOWN(6)：网络连接已断开，完全无法沟通 QUALITY_DETECTING(8)：SDK 正在探测网络质量
delay	音频包从发送端到接收端的延迟（毫秒）。包括声音采样前处理、网络传输、网络抖动缓冲引起的延迟。
lost	音频包从发送端到接收端的丢包率 (%)

当前通话统计回调。 该回调在通话中每两秒触发一次。

参数

stats

RtcEngine 数据，详细定义见 RtcStats

通话前网络上下行 last mile 质量报告回调。

该回调描述本地用户在加入频道前的 last mile 网络探测的结果，其中 last mile 是指设备到声网边缘服务器的网络状态。在 enableLastmileTest 之后，该回调函数每 2 秒触发一次。如果远端有多个用户/主播，该回调每 2 秒会被触发多次。

参数

quality

网络上下行质量，基于上下行网络的丢包率和抖动计算，探测结果主要反映上行网络的状态 QUALITY_UNKNOWN(0)：质量未知 QUALITY_EXCELLENT(1)：质量极好 QUALITY_GOOD(2)：用户主观感觉和极好差不多，但码率可能略低于极好 QUALITY_POOR(3)：用户主观感受有瑕疵但不影响沟通 QUALITY_BAD(4)：勉强能沟通但不顺畅 QUALITY_VBAD(5)：网络质量非常差，基本不能沟通 QUALITY_DOWN(6)：完全无法沟通 QUALITY_DETECTING(8)：SDK 正在探测网络质量

通话前网络上下行 Last mile 质量探测报告回调。

自从

v2.4.0。

在调用 startLastmileProbeTest 之后，SDK 会在约 30 秒内返回该回调。

参数

result

上下行 Last mile 质量探测结果，详见 LastmileProbeResult。

通话中每个用户的网络上下行 last mile 质量报告回调。

该回调描述每个用户在通话中的 last mile 网络状态，其中 last mile 是指设备到声网边缘服务器的网络状态。该回调每 2 秒触发一次。如果远端有多个用户/主播，该回调每 2 秒会被触发多次。

注解

用户不发流时，txQuality 为 UNKNOWN; 用户不收流时，rxQuality 为 UNKNOWN。

参数

uid	用户 ID。表示该回调报告的是持有该 ID 的用户的网络质量。当 uid 为 0 时，返回的是本地用户的网络质量。
txQuality	该用户的上行网络质量，基于上行视频的发送码率、上行丢包率、平均往返时延和网络抖动计算。该值代表当前的上行网络质量，帮助判断是否可以支持当前设置的视频编码属性。假设上行码率是 1000 Kbps，那么支持 640 × 480 的分辨率、30 fps 的帧率没有问题，但是支持 1280 x 720 的分辨率就会有困难 QUALITY_UNKNOWN(0)：质量未知 QUALITY_EXCELLENT(1)：质量极好 QUALITY_GOOD(2)：用户主观感觉和极好差不多，但码率可能略低于极好 QUALITY_POOR(3)：用户主观感受有瑕疵但不影响沟通 QUALITY_BAD(4)：勉强能沟通但不顺畅 QUALITY_VBAD(5)：网络质量非常差，基本不能沟通 QUALITY_DOWN(6)：网络连接断开，完全无法沟通 QUALITY_DETECTING(8)：SDK 正在探测网络质量
rxQuality	该用户的下行网络质量，基于下行网络的丢包率、平均往返延时和网络抖动计算 QUALITY_UNKNOWN(0)：质量未知 QUALITY_EXCELLENT(1)：质量极好 QUALITY_GOOD(2)：用户主观感觉和极好差不多，但码率可能略低于极好 QUALITY_POOR(3)：用户主观感受有瑕疵但不影响沟通 QUALITY_BAD(4)：勉强能沟通但不顺畅 QUALITY_VBAD(5)：网络质量非常差，基本不能沟通 QUALITY_DOWN(6)：网络连接断开，完全无法沟通 QUALITY_DETECTING(8)：SDK 正在探测网络质量

报告 Wi-Fi 连接质量不佳的原因和改善 Wi-Fi 连接的操作建议。

调用 enableWirelessAccelerate(true) 开启 Wi-Fi 加速功能后， 当 Wi-Fi 连接质量不佳时，SDK 会触发该回调，报告 Wi-Fi 连接质量不佳的原因和改善 Wi-Fi 连接的操作建议。

注解

声网强烈建议你在 app 中展示将该回调报告的 action 和 wlAccMsg，提示用户采取网络优化措施，以获得更好的音视频体验。

参数

reason	Wi-Fi 连接质量不佳的原因： WLACC_MESSAGE_REASON_WEAK_SIGNAL(0)：Wi-Fi 信号弱。 WLACC_MESSAGE_REASON_CHANNEL_CONGESTION(1)：网络拥塞。
action	改善 Wi-Fi 连接质量的操作建议： WLACC_SUGGEST_ACTION_CLOSE_TO_WIFI(0)：由于路由器接收到的 Wi-Fi 信号弱，请用户靠近路由器。 WLACC_SUGGEST_ACTION_CONNECT_SSID(1)：请用户连接到指定的无线网络。无线网络名称（SSID）详见 wlAccMsg 参数。 WLACC_SUGGEST_ACTION_CHECK_5G(2)：当前路由器不支持 5G 频道。请用户检查路由器是否支持并开启了 5G 频道，或更换支持 5G 频道的路由器。开启 5G 频道的步骤详见 wlAccMsg 参数。 WLACC_SUGGEST_ACTION_MODIFY_SSID(3)：2.4G 频段和 5G 频道的网络名称（SSID）相同。请用户修改 2.4G 频段或 5G 频道的网络名称。修改步骤详见 wlAccMsg 参数。
wlAccMsg	根据 action 的值提供的详细帮助信息： 当 action 为 WLACC_SUGGEST_ACTION_CLOSE_TO_WIFI，该参数的值为 NULL。 当 action 为 WLACC_SUGGEST_ACTION_CONNECT_SSID，该参数的值为推荐用户连接的网络名称（SSID）。 当 action 为 WLACC_SUGGEST_ACTION_CHECK_5G，该参数的值为开启路由器 5G 频道的操作步骤的链接。 当 action 为 WLACC_SUGGEST_ACTION_MODIFY_SSID，该参数的值为修改网络名称（SSID）的操作步骤的链接。

报告 Wi-Fi 加速效果。

自从

v3.6.2

调用 enableWirelessAccelerate(true) 开启 Wi-Fi 加速功能后，SDK 每隔两秒触发一次该回调， 报告当前的 Wi-Fi 加速效果和自加入频道后平均的 Wi-Fi 加速效果。 Wi-Fi 加速效果用端到端延时、丢包率和音视频卡顿率三个指标下降的百分比来衡量。

参数

currentStats	当前的 Wi-Fi 加速效果。详见 WlAccStats。
averageStats	自加入频道后平均的 Wi-Fi 加速效果。详见 WlAccStats。

通话中本地视频流的统计信息回调。

该回调描述本地设备发送视频流的统计信息，每 2 秒触发一次。

参数

stats

本地视频统计数据，详细定义见 Local Video Stats

通话中远端视频流的统计信息回调。

该回调描述远端用户在通话中端到端的视频流状态，针对每个远端用户/主播每 2 秒触发一次。如果远端同时存在多个用户/主播，该回调每 2 秒会被触发多次。

参数

stats

远端视频统计数据，详细定义见 Remote Video Stats

通话中本地音频流的统计信息回调。

自从

v2.9.0。

该回调描述本地设备发送音频流的统计信息。SDK 每 2 秒触发该回调一次。

参数

stats

本地音频统计数据，详见 LocalAudioStats

通话中远端音频流的统计信息回调。

自从

v2.3.2。用于替换 onAudioQuality 回调。

该回调描述远端用户在通话中端到端的音频流统计信息，针对每个远端用户/主播每 2 秒触发一次。如果远端同时存在多个用户/主播，该回调每 2 秒会被触发多次。

参数

stats

接收到的远端音频统计数据，详细定义见 Remote Audio Stats

本地视频流统计信息回调。

弃用:

该方法已废弃。声网不建议你使用。如果你希望获取本地视频统计信息回调，请改用 onLocalVideoStats 方法。

报告更新本地视频统计信息，该回调函数每两秒触发一次。

参数

sentBitrate	（统计周期内）发送的码率 (Kbps)
sentFrameRate	（统计周期内）发送的帧率 (fps)

远端视频流统计信息回调。

弃用:

该方法已废弃。声网不建议你使用。如果你希望获取远端视频统计信息回调，请改用 onRemoteVideoStats 方法。

报告远端视频统计信息，该回调函数每两秒触发一次。

参数

uid	用户 ID，指定是哪个用户的视频流
delay	延迟（毫秒）
receivedBitrate	接收码率（Kbps）
receivedFrameRate	接收帧率（fps）

通话中远端音频流传输的统计信息回调。

弃用:

该回调已删除。请改用 onRemoteAudioStats。

该回调描述远端用户通话中端到端的网络统计信息，通过音频包计算，用客观的数据，如丢包、网络延迟等，展示当前网络状态。

通话中，当用户收到远端用户/主播发送的音频数据包后，会每 2 秒触发一次该回调。

和 onRemoteAudioStats 回调相比，该回调以数据展示当前网络状态，因此更客观。

参数

uid	用户 ID，指定是哪个用户/主播的音频包
delay	音频包从发送端到接收端的延时（毫秒）
lost	音频包从发送端到接收端的丢包率 (%)
rxKBitRate	远端音频包的接收码率（Kbps）

通话中远端视频流传输的统计信息回调。

弃用:

该回调已废弃。请改用 onRemoteVideoStats。

该回调描述远端用户通话中端到端的网络统计信息，通过视频包计算，用客观的数据，如丢包、网络延迟等 ，展示当前网络状态。

通话中，当用户收到远端用户/主播发送的视频数据包后，会每 2 秒触发一次该回调。

和 onRemoteVideoStats 回调相比，该回调以数据展示当前网络状态，因此更客观。

参数

uid	用户 ID，指定是哪个用户/主播的视频包
delay	视频包从发送端到接收端的延时（毫秒）
lost	视频包从发送端到接收端的丢包率 (%)
rxKBitRate	远端视频包的接收码率（Kbps）

本地用户的音乐文件播放状态已改变回调。

自从

v3.4.0

该回调在音乐文件播放状态发生改变时触发，并报告当前的播放状态和播放状态改变的原因。

注解

通过 startAudioMixing 播放在线音乐文件时，如果遇到网络情况较差，onAudioMixingStateChanged 回调报告 AUDIO_MIXING_STATE_PLAYING 的时刻可能与用户听到音乐的时刻不同。因为 SDK 会在解码第一帧音频帧后触发该回调报告 PLAYING 状态，但在弱网情况下，SDK 无法稳定地接收在线音频包，因此音乐播放不稳定，用户主观感受到的音频开始播放的时刻可能比音频首帧解码的时刻更晚。

参数

state

当前音乐文件播放状态： MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY(710)：音乐文件正常播放。该状态可能由以下原因导致： AUDIO_MIXING_REASON_STARTED_BY_USER(720) AUDIO_MIXING_REASON_ONE_LOOP_COMPLETED(721) AUDIO_MIXING_REASON_START_NEW_LOOP(722) AUDIO_MIXING_REASON_RESUMED_BY_USER(726) MEDIA_ENGINE_AUDIO_EVENT_MIXING_PAUSED(711)：音乐文件暂停播放。该状态由 AUDIO_MIXING_REASON_PAUSED_BY_USER(725) 原因导致。 MEDIA_ENGINE_AUDIO_EVENT_MIXING_STOPPED(713)：音乐文件停止播放。该状态可能由以下原因导致： AUDIO_MIXING_REASON_ALL_LOOPS_COMPLETED(723) AUDIO_MIXING_REASON_STOPPED_BY_USER(724) MEDIA_ENGINE_AUDIO_EVENT_MIXING_ERROR(714)：音乐文件播放失败。该状态可能由以下原因导致： AUDIO_MIXING_REASON_CAN_NOT_OPEN(701) AUDIO_MIXING_REASON_TOO_FREQUENT_CALL(702) AUDIO_MIXING_REASON_INTERRUPTED_EOF(703)

reason

音乐文件播放状态改变的原因： AUDIO_MIXING_REASON_CAN_NOT_OPEN(701)：音乐文件打开出错。例如，本地音乐文件不存在、文件格式不支持或无法访问在线音乐文件 URL。 AUDIO_MIXING_REASON_TOO_FREQUENT_CALL(702)：音乐文件打开太频繁。如需多次调用 startAudioMixing，请确保调用间隔大于 500 ms。 AUDIO_MIXING_REASON_INTERRUPTED_EOF(703)：音乐文件播放中断。 AUDIO_MIXING_REASON_STARTED_BY_USER(720)：成功调用 startAudioMixing 播放音乐文件。 AUDIO_MIXING_REASON_ONE_LOOP_COMPLETED(721)：音乐文件完成一次循环播放。 AUDIO_MIXING_REASON_START_NEW_LOOP(722)：音乐文件开始新的一次循环播放。 AUDIO_MIXING_REASON_ALL_LOOPS_COMPLETED(723)：音乐文件完成所有循环播放。 AUDIO_MIXING_REASON_STOPPED_BY_USER(724)：成功调用 stopAudioMixing 停止播放音乐文件。 AUDIO_MIXING_REASON_PAUSED_BY_USER(725)：成功调用 pauseAudioMixing 暂停播放音乐文件。 AUDIO_MIXING_REASON_RESUMED_BY_USER(726)：成功调用 resumeAudioMixing 恢复音乐文件播放。

本地音乐文件播放已结束回调。

当调用 startAudioMixing 播放伴奏音乐结束后，会触发该回调。 如果该方法调用失败，会在 onWarning 回调里，返回警告码 WARN_AUDIO_MIXING_OPEN_ERROR。

本地音效文件播放已结束回调。

当调用 playEffect 播放音效结束后，会触发该回调。

参数

soundId

指定音效的 ID。每个音效均有唯一的 ID

本地音频状态发生改变回调。

自从

v2.9.0。

本地音频的状态发生改变时（包括本地麦克风采集状态和音频编码状态），SDK 会触发该回调报告当前的本地音频状态。 在本地音频出现故障时，该回调可以帮助你了解当前音频的状态以及出现故障的原因，方便你排查问题。

参数

state

当前的本地音频状态： LOCAL_AUDIO_STREAM_STATE_STOPPED(0)：本地音频默认初始状态。 LOCAL_AUDIO_STREAM_STATE_CAPTURING(1)：本地音频采集设备启动成功。 LOCAL_AUDIO_STREAM_STATE_ENCODING(2)：本地音频首帧编码成功。 LOCAL_AUDIO_STREAM_STATE_FAILED(3)：本地音频启动失败。

error

本地音频出错原因： LOCAL_AUDIO_STREAM_ERROR_OK(0)：本地音频状态正常。 LOCAL_AUDIO_STREAM_ERROR_FAILURE(1)：本地音频出错原因不明确。建议提示用户尝试重新加入频道。 LOCAL_AUDIO_STREAM_ERROR_DEVICE_NO_PERMISSION(2)：没有权限启动本地音频采集设备。请提示用户开启权限。 LOCAL_AUDIO_STREAM_ERROR_DEVICE_BUSY(3)：本地音频采集设备已经在使用中。请提示用户检查麦克风是否被其他应用占用。麦克风空闲约 5 秒后本地音频采集会自动恢复，你也可以在麦克风空闲后尝试重新加入频道。 LOCAL_AUDIO_STREAM_ERROR_CAPTURE_FAILURE(4)：本地音频采集失败。 LOCAL_AUDIO_STREAM_ERROR_ENCODE_FAILURE(5)：本地音频编码失败 LOCAL_AUDIO_STREAM_ERROR_INTERRUPTED(8)：本地音频采集被系统来电、闹钟中断。如需恢复本地音频采集，请用户中止电话、闹钟。

音频文件信息回调。

自从

v3.5.1

成功调用 getAudioFileInfo 后，SDK 会触发该回调并报告音频文件的路径、时长等信息。

参数

info	音频文件信息。详见 AudioFileInfo。
error	信息获取状态： AUDIO_FILE_INFO_ERROR_OK(0)：获取成功。 AUDIO_FILE_INFO_ERROR_FAILURE(1)：获取失败。

本地视频状态发生改变回调。

自从

v2.4.1。

本地视频的状态发生改变时，SDK 会触发该回调返回当前的本地视频状态。

该接口在本地视频出现故障时，方便你了解当前视频的状态以及出现故障的原因，方便排查问题。

SDK 会在如下情况触发 onLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_FAILED，LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE) 回调：

• Android 9 及以上版本，应用退到后台，系统回收摄像头。
• Android 6 及以上版本，摄像头被第三方应用占用。
  • 当第三方应用释放摄像头时，SDK 会触发 onLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_CAPTURING，LOCAL_VIDEO_STREAM_ERROR_OK) 回调。
• 摄像头正常启动，但连续 4 秒都没有输出采集的视频。

摄像头输出采集的视频帧时，如果连续 15 帧中，所有视频帧都一样，SDK 触发 onLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_CAPTURING，LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE) 回调。注意：帧重复检测仅针对分辨率大于 200 × 200，帧率大于等于 10 fps，码率小于 20 Kbps 的视频帧。

屏幕共享时，如未授予应用屏幕采集权限，SDK 会触发 onLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_FAILED，ERR_SCREEN_CAPTURE_PERMISSION_DENIED) 回调。

参数

localVideoState

当前的本地视频状态： LOCAL_VIDEO_STREAM_STATE_STOPPED(0)：本地视频默认初始状态 LOCAL_VIDEO_STREAM_STATE_CAPTURING(1)：本地视频采集设备启动成功 LOCAL_VIDEO_STREAM_STATE_ENCODING(2)：本地视频首帧编码成功 LOCAL_VIDEO_STREAM_STATE_FAILED(3)：本地视频启动失败

error

本地视频出错原因： LOCAL_VIDEO_STREAM_ERROR_OK(0)：本地视频状态正常 LOCAL_VIDEO_STREAM_ERROR_FAILURE(1)：出错原因不明确 LOCAL_VIDEO_STREAM_ERROR_DEVICE_NO_PERMISSION(2)：没有权限启动本地视频采集设备。请提示用户开启权限再重新加入频道。 LOCAL_VIDEO_STREAM_ERROR_DEVICE_BUSY(3)：本地视频采集设备正在使用中。请提示用户检查摄像头是否被其他应用占用。 LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE(4)：本地视频采集失败。 请检查视频采集设备是否正常工作，检查摄像头是否被其他应用占用，或者尝试重新加入频道。 LOCAL_VIDEO_STREAM_ERROR_ENCODE_FAILURE(5)：本地视频编码失败。 LOCAL_VIDEO_STREAM_ERROR_DEVICE_NOT_FOUND(8)：找不到本地视频采集设备。请检查摄像头是否与设备连接正常，检查摄像头是否正常工作，或者尝试重新加入频道。 ERR_SCREEN_CAPTURE_PERMISSION_DENIED(16)：用户拒绝向应用授予屏幕采集权限。

RTMP/RTMPS 推流状态发生改变回调。

自从

v2.4.1。

RTMP/RTMPS 推流状态发生改变时，SDK 会触发该回调，并在回调中明确状态发生改变的 URL 地址及当前推流状态；当推流状态为 RTMP_STREAM_PUBLISH_STATE_FAILURE(4) 时，你可以在 errCode 参数中查看返回的错误信息。 该回调方便推流用户了解当前的推流状态；推流出错时，你可以通过返回的错误码了解出错的原因，方便排查问题。

参数

url	推流状态发生改变的 URL 地址
state	当前的推流状态： RTMP_STREAM_PUBLISH_STATE_IDLE(0)：推流未开始或已结束。成功调用 removePublishStreamUrl 方法删除推流地址后，也会返回该状态 RTMP_STREAM_PUBLISH_STATE_CONNECTING(1)：正在连接声网推流服务器和 CDN 服务器。SDK 调用 addPublishStreamUrl 方法后，会返回该状态 RTMP_STREAM_PUBLISH_STATE_RUNNING(2)：推流正在进行。SDK 成功推流后，会返回该状态 RTMP_STREAM_PUBLISH_STATE_RECOVERING(3)：正在恢复推流。当 CDN 出现异常，或推流短暂中断时，SDK 会自动尝试恢复推流，并返回该状态。如成功恢复推流，则进入状态 RTMP_STREAM_PUBLISH_STATE_RUNNING(2)；如服务器出错或 60 秒内未成功恢复，则进入状态 RTMP_STREAM_PUBLISH_STATE_FAILURE(4)。如果觉得 60 秒太长，也可以主动调用 removePublishStreamUrl 和 addPublishStreamUrl 方法尝试重连 RTMP_STREAM_PUBLISH_STATE_FAILURE(4)：推流失败。你可以再次调用 addPublishStreamUrl 重新尝试推流 RTMP_STREAM_PUBLISH_STATE_DISCONNECTING(5)：SDK 正在与声网推流服务器和 CDN 服务器断开连接。当你调用 remove 或 stop 方法正常结束推流时，SDK 会依次报告推流状态为 DISCONNECTING，IDLE。
errCode	详细的推流错误信息： RTMP_STREAM_PUBLISH_ERROR_OK(0)：推流成功 RTMP_STREAM_PUBLISH_ERROR_INVALID_ARGUMENT(1)：参数无效。比如说如果你在调用 addPublishStreamUrl 前没有调用 setLiveTranscoding 设置转码参数，SDK 会返回该错误。请检查输入参数是否正确 RTMP_STREAM_PUBLISH_ERROR_ENCRYPTED_STREAM_NOT_ALLOWED(2)：推流已加密不能推流 RTMP_STREAM_PUBLISH_ERROR_CONNECTION_TIMEOUT(3)：推流超时未成功。可调用 addPublishStreamUrl 重新推流 RTMP_STREAM_PUBLISH_ERROR_INTERNAL_SERVER_ERROR(4)：推流服务器出现错误。请调用 addPublishStreamUrl 重新推流 RTMP_STREAM_PUBLISH_ERROR_RTMP_SERVER_ERROR(5)：CDN 服务器出现错误 RTMP_STREAM_PUBLISH_ERROR_TOO_OFTEN(6)：预留参数 RTMP_STREAM_PUBLISH_ERROR_REACH_LIMIT(7)：单个主播的推流地址数目达到上限 10。请删掉一些不用的推流地址再增加推流地址 RTMP_STREAM_PUBLISH_ERROR_NOT_AUTHORIZED(8)：主播操作不属于主播自己的流，如更新其他主播的流参数、停止其他主播的流。请检查 App 逻辑 RTMP_STREAM_PUBLISH_ERROR_STREAM_NOT_FOUND(9)：服务器未找到这个流 RTMP_STREAM_PUBLISH_ERROR_FORMAT_NOT_SUPPORTED(10)：推流地址格式有错误。请检查推流地址格式是否正确。 RTMP_STREAM_PUBLISH_ERROR_NOT_BROADCASTER(11)：用户角色不是主播，该用户无法使用推流功能。请检查你的应用代码逻辑。 RTMP_STREAM_PUBLISH_ERROR_TRANSCODING_NO_MIX_STREAM(13)：非转码推流情况下，调用了 updateRtmpTranscoding 或 setLiveTranscoding 方法更新转码属性。请检查你的应用代码逻辑。 RTMP_STREAM_PUBLISH_ERROR_NET_DOWN(14)：主播的网络出错。 RTMP_STREAM_PUBLISH_ERROR_INVALID_APPID(15)：你的 App ID 没有使用声网推流服务的权限。请参考前提条件开启推流服务。 RTMP_STREAM_UNPUBLISH_ERROR_OK(100)：推流已正常结束。当你调用 removePublishStreamUrl 结束推流后，SDK 会返回该值。

开启旁路推流的结果回调。

弃用:

v3.0.0。该回调已废弃。请改用 onRtmpStreamingStateChanged。

该回调返回 addPublishStreamUrl 方法的调用结果。用于通知主播是否推流成功。如果不成功，你可以在 error 参数中查看详细的错误信息。

参数

url

新增的推流地址

error

详细的错误信息： ERR_OK(0)：推流成功 ERR_FAILED(1)：推流失败 ERR_INVALID_ARGUMENT(2)：参数错误。如果你在调用 addPublishStreamUrl 前没有调用 setLiveTranscoding 配置 LiveTranscoding，SDK 会返回该错误 ERR_TIMEDOUT(10)：推流超时未成功 ERR_ALREADY_IN_USE(19)：推流地址已经在推流 ERR_ENCRYPTED_STREAM_NOT_ALLOWED_PUBLISHED(130)：推流已加密不能推流 ERR_PUBLISH_STREAM_CDN_ERROR(151)：CDN 相关错误。请调用 removePublishStreamUrl 方法删除原来的推流地址，然后调用 addPublishStreamUrl 方法重新推流到新地址 ERR_PUBLISH_STREAM_NUM_REACH_LIMIT(152)：单个主播的推流地址数目达到上限 10。请删掉一些不用的推流地址再增加推流地址 ERR_PUBLISH_STREAM_NOT_AUTHORIZED(153)：操作不属于主播自己的流，如更新其他主播的流参数、停止其他主播的流。请检查 App 逻辑 RR_PUBLISH_STREAM_INTERNAL_SERVER_ERROR(154)：推流服务器出现错误。请调用 addPublishStreamUrl 重新推流 ERR_PUBLISH_STREAM_FORMAT_NOT_SUPPORTED(156)：推流地址格式有错误。请检查推流地址格式是否正确

停止旁路推流的结果回调。

弃用:

v3.0.0。该回调已废弃。请改用 onRtmpStreamingStateChanged。

该回调返回 removePublishStreamUrl 方法的调用结果。用于通知主播是否停止推流成功。

参数

url

主播停止推流的地址

旁路推流设置被更新回调。

setLiveTranscoding 方法中的直播转码参数 LiveTranscoding 更新时， 该回调会被触发， 并向主播报告更新信息。

注解

首次调用 setLiveTranscoding 方法设置转码参数时，不会触发该回调。

RTMP/RTMPS 推流事件回调。

自从

v3.1.0。

参数

url	RTMP/RTMPS 推流 URL。
error	RTMP/RTMPS 推流事件码。 RTMP_STREAMING_EVENT_FAILED_LOAD_IMAGE(1): RTMP/RTMPS 推流时，添加背景图或水印出错。 RTMP_STREAMING_EVENT_URL_ALREADY_IN_USE(2)：该推流 URL 已用于推流。如果你想开始新的推流，请使用新的推流 URL。 RTMP_STREAMING_EVENT_ADVANCED_FEATURE_NOT_SUPPORT(3)：功能不支持。 RTMP_STREAMING_EVENT_REQUEST_TOO_OFTEN(4)：预留参数。

接收到对方数据流消息的回调。

该回调表示本地用户收到了远端用户调用 sendStreamMessage 方法发送的流消息。

参数

uid	用户 ID
streamId	数据流 ID
data	接收到的数据

接收对方数据流消息发生错误的回调。

该回调表示本地用户未收到远端用户调用 sendStreamMessage 方法发送的流消息。

参数

uid	用户 ID
streamId	数据流 ID
error	错误代码，详细定义见 Error code
missed	丢失的消息数量
cached	数据流中断时，后面缓存的消息数量

媒体引擎成功加载的回调。

媒体引擎成功启动的回调。

本地网络类型发生改变回调。

自从

v2.4.1。

本地网络连接类型发生改变时，SDK 会触发该回调，并在回调中明确当前的网络连接类型。 你可以通过该回调获取正在使用的网络类型；当连接中断时，该回调能辨别引起中断的原因是网络切换还是网络条件不好。

参数

type

网络连接类型： NETWORK_TYPE_UNKNOWN(-1)：网络连接类型未知 NETWORK_TYPE_DISCONNECTED(0)：网络连接已断开 NETWORK_TYPE_LAN(1)：网络类型为 LAN NETWORK_TYPE_WIFI(2)：网络类型为 Wi-Fi（包含热点） NETWORK_TYPE_MOBILE_2G(3)：网络类型为 2G 移动网络 NETWORK_TYPE_MOBILE_3G(4)：网络类型为 3G 移动网络 NETWORK_TYPE_MOBILE_4G(5)：网络类型为 4G 移动网络 NETWORK_TYPE_MOBILE_5G(6)：网络类型为 5G 移动网络

直播场景下切换用户角色失败回调。

自从

v3.7.0

直播场景下，本地用户加入频道后调用 setClientRole 切换用户角色失败时， SDK 会触发该回调，报告切换失败的原因和当前的用户角色。

参数

reason	切换用户角色失败的原因： CLIENT_ROLE_CHANGE_FAILED_BY_TOO_MANY_BROADCASTERS(1) CLIENT_ROLE_CHANGE_FAILED_BY_NOT_AUTHORIZED(2) CLIENT_ROLE_CHANGE_FAILED_BY_REQUEST_TIME_OUT(3) CLIENT_ROLE_CHANGE_FAILED_BY_CONNECTION_FAILED(4)
currentRole	当前的用户角色： CLIENT_ROLE_BROADCASTER(1) CLIENT_ROLE_AUDIENCE(2)