文档中心
视频通话 (Legacy)
Console 官网 社区 技术支持
简体中文
search-icon

Cocos Creator SDK API Reference

概览 agora AgoraRtcEvents

AgoraRtcEvents 类用于向应用程序发送回调通知。

Hierarchy

  • AgoraRtcEvents

Index

Properties

Properties

onActiveSpeaker

onActiveSpeaker: (uid: number) => void

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

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

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

远端最活跃用户的 ID。

Type declaration

    • (uid: number): void

    • Parameters

      • uid: number

        远端最活跃用户的 ID。

      Returns void

onApiCallExecuted

onApiCallExecuted: (err: ERROR_CODE_TYPE, api: string, result: string) => void

API 方法已执行回调。

Type declaration

    • Parameters

      • err: ERROR_CODE_TYPE

        当该方法调用失败时 SDK 返回的错误码。如果方法调用失败，会返回错误码 ERROR_CODE_TYPE 。 如果该方法调用成功，SDK 将返回 0。

      • api: string

        SDK 执行的 API。

      • result: string

        SDK 调用 API 的调用结果。

      Returns void

onAudioDeviceStateChanged

onAudioDeviceStateChanged: (deviceId: string, deviceType: MEDIA_DEVICE_TYPE, deviceState: MEDIA_DEVICE_STATE_TYPE) => void

音频设备变化回调。 提示系统音频设备状态发生改变，比如耳机被拔出。

Type declaration

onAudioDeviceVolumeChanged

onAudioDeviceVolumeChanged: (deviceType: MEDIA_DEVICE_TYPE, volume: number, muted: boolean) => void

回放、录音设备、或 App 的音量发生改变。

Type declaration

    • Parameters

      • deviceType: MEDIA_DEVICE_TYPE

        设备类型定义: MEDIA_DEVICE_TYPE 。

      • volume: number

        音量：范围 [0,255]。

      • muted: boolean
        • true: 音频设备已被静音；
        • false: 音频设备未被静音。

      Returns void

onAudioEffectFinished

onAudioEffectFinished: (soundId: number) => void

本地音效文件播放已结束回调。 当播放音效结束后，会触发该回调。

Type declaration

    • (soundId: number): void

    • Parameters

      • soundId: number

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

      Returns void

onAudioMixingFinished

onAudioMixingFinished: () => void

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

deprecated

该回调已废弃。请改用 onAudioMixingStateChanged。 当调用 startAudioMixing 播放本地音乐文件结束后，会触发该回调。如果调用 startAudioMixing 失败，会在 onError 回调里返回错误码 。

Type declaration

    • (): void

    • Returns void

onAudioMixingStateChanged

onAudioMixingStateChanged: (state: AUDIO_MIXING_STATE_TYPE, errorCode: AUDIO_MIXING_ERROR_TYPE) => void

本地用户的音乐文件播放状态已改变回调。 该回调在音乐文件播放状态发生改变时触发，并报告当前的播放状态和错误码。 如果本地音乐文件不存在、文件格式不支持或无法访问在线音乐文件 URL，SDK 会返回警告码 WARN_AUDIO_MIXING_OPEN_ERROR (701)。

Type declaration

onAudioPublishStateChanged

onAudioPublishStateChanged: (channel: string, oldState: STREAM_PUBLISH_STATE, newState: STREAM_PUBLISH_STATE, elapseSinceLastState: number) => void

音频发布状态改变回调。

Type declaration

onAudioQuality

onAudioQuality: (uid: number, quality: QUALITY_TYPE, delay: number, lost: number) => void
deprecated

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

Type declaration

    • (uid: number, quality: QUALITY_TYPE, delay: number, lost: number): void

    • Parameters

      • uid: number

        用户 ID，指定是谁发的音频流。

      • quality: QUALITY_TYPE

        语音质量，详见: QUALITY_TYPE 。

      • delay: number

        音频包从发送端到接收端的延迟（毫秒）。包括声音采样前处理、网络传输、网络抖动缓冲引起的延迟。

      • lost: number

        音频包从发送端到接收端的丢包率 (%)。

      Returns void

onAudioRouteChanged

onAudioRouteChanged: (routing: AUDIO_ROUTE_TYPE) => void

语音路由已发生变化回调。 当语音路由发生变化时，SDK 会触发此回调。

Type declaration

onAudioSubscribeStateChanged

onAudioSubscribeStateChanged: (channel: string, uid: number, oldState: STREAM_SUBSCRIBE_STATE, newState: STREAM_SUBSCRIBE_STATE, elapseSinceLastState: number) => void

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

Type declaration

onAudioVolumeIndication

onAudioVolumeIndication: (speakers: AudioVolumeInfo[], speakerNumber: number, totalVolume: number) => void

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

Note

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

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

Type declaration

    • (speakers: AudioVolumeInfo[], speakerNumber: number, totalVolume: number): void

    • Parameters

      • speakers: AudioVolumeInfo[]

        用户音量信息，详见 AudioVolumeInfo 数组。 如果 speakers 为空，则表示远端用户不发流或没有远端用户。

      • speakerNumber: number

        用户数量。

        • 在本地用户的回调中，只要本地用户在发流，speakerNumber 始终为 1。
        • 在远端用户的回调中，speakerNumber 取值范围为 [0,3]。如果远端发流用户数量大于 3，则此回调中 speakerNumber 值为 3。
      • totalVolume: number

        混音后的总音量，取值范围为 [0,255]。

        • 在本地用户的回调中，totalVolume 为本地发流用户的音量。
        • 在远端用户的回调中，totalVolume 为瞬时音量最高的远端用户（最多 3 位）混音后的总音量。

        如果用户调用了 startAudioMixing，则 totalVolume 为混音后的音量。

      Returns void

onCameraExposureAreaChanged

onCameraExposureAreaChanged: (x: number, y: number, width: number, height: number) => void

摄像头曝光区域已改变回调。 该回调是由本地用户调用 setCameraExposurePosition 方法改变曝光位置触发的。

Type declaration

    • (x: number, y: number, width: number, height: number): void

    • Parameters

      • x: number

        发生改变的曝光区域的 x 坐标。

      • y: number

        发生改变的曝光区域的 y 坐标。

      • width: number

        发生改变的曝光区域的宽度。

      • height: number

        发生改变的曝光区域的高度。

      Returns void

onCameraFocusAreaChanged

onCameraFocusAreaChanged: (x: number, y: number, width: number, height: number) => void

相机对焦区域已改变回调。 该回调表示相机的对焦区域发生了改变。 该回调是由本地用户调用 setCameraFocusPositionInPreview 方法改变对焦位置触发的。

Type declaration

    • (x: number, y: number, width: number, height: number): void

    • Parameters

      • x: number

        发生改变的对焦区域的 x 坐标。

      • y: number

        发生改变的对焦区域的 y 坐标。

      • width: number

        发生改变的对焦区域的宽度。

      • height: number

        发生改变的对焦区域的高度。

      Returns void

onCameraReady

onCameraReady: () => void
deprecated

摄像头就绪回调。 提示已成功打开摄像头，可以开始捕获视频。如果摄像头打开失败，可在 onError 中处理相应错误。 该回调已废弃。请改用 onLocalVideoStateChanged 回调中的 LOCAL_VIDEO_STREAM_STATE_CAPTURING (1)。

Type declaration

    • (): void

    • Returns void

onChannelMediaRelayEvent

onChannelMediaRelayEvent: (code: CHANNEL_MEDIA_RELAY_EVENT) => void

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

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

Type declaration

onChannelMediaRelayStateChanged

onChannelMediaRelayStateChanged: (state: CHANNEL_MEDIA_RELAY_STATE, code: CHANNEL_MEDIA_RELAY_ERROR) => void

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

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

Type declaration

onClientRoleChanged

onClientRoleChanged: (oldRole: CLIENT_ROLE_TYPE, newRole: CLIENT_ROLE_TYPE) => void

直播场景下用户角色已切换回调。 直播场景下，当用户切换角色时会触发此回调，即主播切换为观众时，或观众切换为主播时。 该回调由本地用户在加入频道后调用 setClientRole 改变用户角色触发的。

Type declaration

onConnectionBanned

onConnectionBanned: () => void
deprecated

连接已被服务器禁止回调。该回调已废弃，被 onConnectionStateChanged 取代。 当你被服务端禁掉连接的权限时，会触发该回调。

Type declaration

    • (): void

    • Returns void

onConnectionInterrupted

onConnectionInterrupted: () => void

网络连接中断回调。

deprecated

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

  • onConnectionInterrupted 回调一定是发生在加入频道成功后，且 SDK 刚失去和服务器连接超过 4 秒时触发。
  • onConnectionLost 回调是无论之前加入频道是否成功，只要 10 秒内和服务器无法建立连接都会触发。 如果 SDK 在断开连接后，20 分钟内还是没能重新加入频道，SDK 会停止尝试重连。

Type declaration

    • (): void

    • Returns void

onConnectionLost

onConnectionLost: () => void

网络连接丢失回调。 SDK 在调用 joinChannel 后无论是否加入成功，只要 10 秒和服务器无法连接就会触发该回调。

与 onConnectionInterrupted 的区别是：

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

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

Type declaration

    • (): void

    • Returns void

onConnectionStateChanged

onConnectionStateChanged: (state: CONNECTION_STATE_TYPE, reason: CONNECTION_CHANGED_REASON_TYPE) => void

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

Type declaration

onError

onError: (err: ERROR_CODE_TYPE, msg: string) => void

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

Type declaration

onFacePositionChanged

onFacePositionChanged: (imageWidth: number, imageHeight: number, vecRectangle: Rectangle[], vecDistance: number[], numFaces: number) => void

报告本地人脸检测结果。

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

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

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

Note

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

Type declaration

    • (imageWidth: number, imageHeight: number, vecRectangle: Rectangle[], vecDistance: number[], numFaces: number): void

    • Parameters

      • imageWidth: number

        摄像头采集画面的宽度 (px)。

      • imageHeight: number

        摄像头采集画面的高度 (px)。

      • vecRectangle: Rectangle[]

        检测到的人脸信息：

        • x：人脸在画面中的 x 坐标 (px)。以摄像头采集画面的左上角为原点，x 坐标为人脸左上角相对于原点的横向位移。
        • y：人脸在画面中的 y 坐标 (px)。以摄像头采集画面的左上角为原点，y 坐标为人脸左上角相对原点的纵向位移。
        • width：人脸在画面中的宽度 (px)。
        • height：人脸在画面中的高度 (px)。
      • vecDistance: number[]

        人脸距设备屏幕的距离 (cm)。

      • numFaces: number

        检测的人脸数量。如果为 0，则表示没有检测到人脸。

      Returns void

onFirstLocalAudioFrame

onFirstLocalAudioFrame: (elapsed: number) => void

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

deprecated

该回调已废弃，请改用 onFirstLocalAudioFramePublished 回调。

Type declaration

    • (elapsed: number): void

    • Parameters

      • elapsed: number

        从调用 joinChannel 方法直至该回调被触发的时间。

      Returns void

onFirstLocalAudioFramePublished

onFirstLocalAudioFramePublished: (elapsed: number) => void

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

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

Type declaration

    • (elapsed: number): void

    • Parameters

      • elapsed: number

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

      Returns void

onFirstLocalVideoFrame

onFirstLocalVideoFrame: (width: number, height: number, elapsed: number) => void

已显示本地视频首帧回调。 本地视频首帧显示在本地视图上时，SDK 会触发此回调。

Type declaration

    • (width: number, height: number, elapsed: number): void

    • Parameters

      • width: number

        本地渲染视频的宽 (px) 。

      • height: number

        本地渲染视频的高 (px)。

      • elapsed: number

        从调用 joinChannel 到发生此事件过去的时间（毫秒）。如果在 joinChannel 前调用了 startPreview，则是从 startPreview 到发生此事件过去的时间。

      Returns void

onFirstLocalVideoFramePublished

onFirstLocalVideoFramePublished: (elapsed: number) => void

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

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

Type declaration

    • (elapsed: number): void

    • Parameters

      • elapsed: number

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

      Returns void

onFirstRemoteAudioDecoded

onFirstRemoteAudioDecoded: (uid: number, elapsed: number) => void

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

deprecated

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

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

Type declaration

    • (uid: number, elapsed: number): void

    • Parameters

      • uid: number

        远端用户 ID

      • elapsed: number

        从本地用户调用 joinChannel 直至该回调触发的延迟，单位为毫秒。

      Returns void

onFirstRemoteAudioFrame

onFirstRemoteAudioFrame: (uid: number, elapsed: number) => void

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

deprecated

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

Type declaration

    • (uid: number, elapsed: number): void

    • Parameters

      • uid: number

        发送音频帧的远端用户的用户 ID。

      • elapsed: number

        从调用 joinChannel 方法直至该回调被触发的时间。

      Returns void

onFirstRemoteVideoDecoded

onFirstRemoteVideoDecoded: (uid: number, width: number, height: number, elapsed: number) => void

已接收到远端视频并完成解码回调。

deprecated

该回调已被废弃，请改用 onRemoteVideoStateChanged 回调的：

引擎收到第一帧远端视频流并解码成功时，触发此调用。 App 可在此回调中设置该用户的 view。有两种情况：

  • 远端用户首次上线后发送视频。
  • 远端用户视频离线再上线后发送视频。出现这种中断的可能原因包括：
  • 远端用户离开频道。
  • 远端用户掉线。
  • 远端用户调用 muteLocalVideoStream 方法停止发送本地视频流。
  • 远端用户调用 disableVideo 方法关闭视频模块。

Type declaration

    • (uid: number, width: number, height: number, elapsed: number): void

    • Parameters

      • uid: number

        用户 ID，指定是哪个用户的视频流。

      • width: number

        视频流宽（px）。

      • height: number

        视频流高（px）。

      • elapsed: number

        从本地调用 joinChannel 开始到该回调触发的延迟（毫秒)。

      Returns void

onFirstRemoteVideoFrame

onFirstRemoteVideoFrame: (uid: number, width: number, height: number, elapsed: number) => void

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

Type declaration

    • (uid: number, width: number, height: number, elapsed: number): void

    • Parameters

      • uid: number

        用户 ID，指定是哪个用户的视频流。

      • width: number

        视频流宽（px）。

      • height: number

        视频流高（px）。

      • elapsed: number

        从本地调用 joinChannel 到发生此事件过去的时间（毫秒)。

      Returns void

onJoinChannelSuccess

onJoinChannelSuccess: (channel: string, uid: number, elapsed: number) => void

加入频道回调。 该回调方法表示该客户端成功加入了指定的频道。 channel ID 基于 joinChannel 中指定的 channel name 分配。如果调用 joinChannel 时并没有指定 user ID。 服务器会自动分配一个。

Type declaration

    • (channel: string, uid: number, elapsed: number): void

    • Parameters

      • channel: string

        频道名。

      • uid: number

        用户 ID。如果 joinChannel 中指定了 uid，则此处返回该 ID；否则使用声网服务器自动分配的 ID。

      • elapsed: number

        从 joinChannel 开始到发生此事件过去的时间（毫秒）。

      Returns void

onLastmileProbeResult

onLastmileProbeResult: (result: LastmileProbeResult) => void

通话前网络质量探测报告回调。 通话前网络上下行 Last mile 质量探测报告回调。在调用 startLastmileProbeTest 之后， SDK 会在约 30 秒内返回该回调。

Type declaration

onLastmileQuality

onLastmileQuality: (quality: QUALITY_TYPE) => void

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

Type declaration

    • Parameters

      • quality: QUALITY_TYPE

        网络上下行质量，基于上下行网络的丢包率和抖动计算，探测结果主要反映上行网络的状态。 详见: QUALITY_TYPE 。

      Returns void

onLeaveChannel

onLeaveChannel: (stats: RtcStats) => void

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

Type declaration

onLocalAudioStateChanged

onLocalAudioStateChanged: (state: LOCAL_AUDIO_STREAM_STATE, error: LOCAL_AUDIO_STREAM_ERROR) => void

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

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

note

当状态为 LOCAL_AUDIO_STREAM_STATE_FAILED (3) 时， 你可以在 error 参数中查看返回的错误信息。

Type declaration

onLocalAudioStats

onLocalAudioStats: (stats: LocalAudioStats) => void

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

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

Type declaration

onLocalPublishFallbackToAudioOnly

onLocalPublishFallbackToAudioOnly: (isFallbackOrRecover: boolean) => void

本地发布流已回退为音频流回调。 如果你调用了 setLocalPublishFallbackOption 接口并将 option 设置为 STREAM_FALLBACK_OPTION_AUDIO_ONLY ，当上行网络环境不理想、 本地发布的媒体流回退为音频流时，或当上行网络改善、媒体流恢复为音视频流时，会触发该回调。

note

如果本地发流已回退为音频流，远端的 App 上会收到 onUserMuteVideo 的回调事件。

Type declaration

    • (isFallbackOrRecover: boolean): void

    • Parameters

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

      Returns void

onLocalUserRegistered

onLocalUserRegistered: (uid: number, userAccount: string) => void

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

Type declaration

    • (uid: number, userAccount: string): void

    • Parameters

      • uid: number

        本地用户的 UID

      • userAccount: string

        本地用户的 User Account

      Returns void

onLocalVideoStateChanged

onLocalVideoStateChanged: (localVideoState: LOCAL_VIDEO_STREAM_STATE, error: LOCAL_VIDEO_STREAM_ERROR) => void

本地视频状态发生改变回调 本地视频的状态发生改变时，SDK 会触发该回调返回当前的本地视频状态。 在本地视频出现故障时，你可以通过该回调了解当前视频的状态以及出现故障的原因，方便排查问题。

note

对某些机型而言，当本地视频采集设备正在使用中时，SDK 不会在本地视频状态发生改变时触发该回调，你需要自行做超时判断。

Type declaration

onLocalVideoStats

onLocalVideoStats: (stats: LocalVideoStats) => void

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

note

如果你调用了 enableDualStreamMode 方法，该回调会报告视频大流的统计信息。

Type declaration

onMediaEngineLoadSuccess

onMediaEngineLoadSuccess: () => void

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

Type declaration

    • (): void

    • Returns void

onMediaEngineStartCallSuccess

onMediaEngineStartCallSuccess: () => void

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

Type declaration

    • (): void

    • Returns void

onMetadataReceived

onMetadataReceived: (metadata: Metadata) => void

接收端已收到 Metadata。 当接收到远端用户发送的 Metadata 时，SDK 会触发该回调。

Type declaration

onMicrophoneEnabled

onMicrophoneEnabled: (enabled: boolean) => void

麦克风状态已改变回调。

deprecated

从 v2.9.0。此方法已被废弃，请改用 onLocalAudioStateChanged 回调的：

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

Type declaration

    • (enabled: boolean): void

    • Parameters

      • enabled: boolean
        • true: 麦克风已启用；
        • false: 麦克风已禁用。

      Returns void

onNetworkQuality

onNetworkQuality: (uid: number, txQuality: QUALITY_TYPE, rxQuality: QUALITY_TYPE) => void

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

Type declaration

    • Parameters

      • uid: number

        用户 ID。表示该回调报告的是持有该 ID 的用户的网络质量。当 uid 为 0 时，返回的是本地用户的网络质量。

      • txQuality: QUALITY_TYPE

        该用户的上行网络质量，基于发送码率、上行丢包率、平均往返时延和网络抖动计算。该值代表当前的上行网络质量， 帮助判断是否可以支持当前设置的视频编码属性。假设上行码率是 1000 Kbps，那么支持直播场景下 640 × 480 的分辨率、15 fps 的帧率没有问题， 但是支持 1280 × 720 的分辨率就会有困难。详见 QUALITY_TYPE 。

      • rxQuality: QUALITY_TYPE

        该用户的下行网络质量，基于下行网络的丢包率、平均往返延时和网络抖动计算。详见 QUALITY_TYPE 。

      Returns void

onNetworkTypeChanged

onNetworkTypeChanged: (type: NETWORK_TYPE) => void

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

Type declaration

onRejoinChannelSuccess

onRejoinChannelSuccess: (channel: string, uid: number, elapsed: number) => void

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

Type declaration

    • (channel: string, uid: number, elapsed: number): void

    • Parameters

      • channel: string

        频道名。

      • uid: number

        用户 ID。

      • elapsed: number

        从开始重连到重连成功的时间（毫秒）。

      Returns void

onRemoteAudioMixingBegin

onRemoteAudioMixingBegin: () => void

远端音乐文件播放已开始回调。 当远端有用户调用 startAudioMixing 播放本地音乐文件，会触发该回调。

Type declaration

    • (): void

    • Returns void

onRemoteAudioMixingEnd

onRemoteAudioMixingEnd: () => void

远端音乐文件播放已结束回调。 当远端有用户播放本地音乐文件结束，会触发该回调。

Type declaration

    • (): void

    • Returns void

onRemoteAudioStateChanged

onRemoteAudioStateChanged: (uid: number, state: REMOTE_AUDIO_STATE, reason: REMOTE_AUDIO_STATE_REASON, elapsed: number) => void

远端音频流状态发生改变回调。 远端用户/主播音频状态发生改变时，SDK 会触发该回调向本地用户报告当前的远端音频流状态。

note

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

Type declaration

onRemoteAudioStats

onRemoteAudioStats: (stats: RemoteAudioStats) => void

通话中远端音频流的统计信息回调。用于取代 onAudioQuality 回调。 该回调描述远端用户在通话中端到端的音频流统计信息。该回调函数针对每个发送音频流的远端用户/主播每 2 秒触发一次。如果远端有多个用户/主播发送音频流， 该回调每 2 秒会被触发多次。

Type declaration

onRemoteAudioTransportStats

onRemoteAudioTransportStats: (uid: number, delay: number, lost: number, rxKBitRate: number) => void
deprecated

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

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

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

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

Type declaration

    • (uid: number, delay: number, lost: number, rxKBitRate: number): void

    • Parameters

      • uid: number

        用户 ID，指定是哪个用户/主播的音频包。

      • delay: number

        音频包从发送端到接收端的延时（毫秒）。

      • lost: number

        音频包从发送端到接收端的丢包率 (%)。

      • rxKBitRate: number

        远端音频包的接收码率（Kbps）。

      Returns void

onRemoteSubscribeFallbackToAudioOnly

onRemoteSubscribeFallbackToAudioOnly: (uid: number, isFallbackOrRecover: boolean) => void

远端订阅流已回退为音频流回调。

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

note

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

Type declaration

    • (uid: number, isFallbackOrRecover: boolean): void

    • Parameters

      • uid: number

        远端用户的用户 ID。

      • isFallbackOrRecover: boolean
        • true: 由于网络环境不理想，远端订阅流已回退为音频流；
        • false: 由于网络环境改善，订阅的音频流已恢复为音视频流。

      Returns void

onRemoteVideoStateChanged

onRemoteVideoStateChanged: (uid: number, state: REMOTE_VIDEO_STATE, reason: REMOTE_VIDEO_STATE_REASON, elapsed: number) => void

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

note

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

Type declaration

onRemoteVideoStats

onRemoteVideoStats: (stats: RemoteVideoStats) => void

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

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

Type declaration

onRemoteVideoTransportStats

onRemoteVideoTransportStats: (uid: number, delay: number, lost: number, rxKBitRate: number) => void
deprecated

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

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

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

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

Type declaration

    • (uid: number, delay: number, lost: number, rxKBitRate: number): void

    • Parameters

      • uid: number

        用户 ID，指定是哪个用户/主播的视频包。

      • delay: number

        视频包从发送端到接收端的延时（毫秒）。

      • lost: number

        视频包从发送端到接收端的丢包率 (%)。

      • rxKBitRate: number

        远端视频包的接收码率（Kbps）。

      Returns void

onRequestToken

onRequestToken: () => void

Token 已过期回调。 在调用 joinChannel , 时如果指定了 Token，由于 Token 具有一定的时效，在通话过程中 SDK 可能由于网络原因 和服务器失去连接，重连时可能需要新的 Token。 该回调通知 App 需要生成新的 Token，然后调用 joinChannel，使用新的 Token 重新加入频道。

Type declaration

    • (): void

    • Returns void

onRtcStats

onRtcStats: (stats: RtcStats) => void

当前通话统计回调。 SDK 定期向 App 报告当前通话的统计信息，每两秒触发一次。

Type declaration

onRtmpStreamingEvent

onRtmpStreamingEvent: (url: string, eventCode: RTMP_STREAMING_EVENT) => void

RTMP 推流事件回调。

Type declaration

onRtmpStreamingStateChanged

onRtmpStreamingStateChanged: (url: string, state: RTMP_STREAM_PUBLISH_STATE, errCode: RTMP_STREAM_PUBLISH_ERROR) => void

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

该回调返回本地用户调用 addPublishStreamUrl 或 removePublishStreamUrl 方法的结果。 RTMP 推流状态发生改变时，SDK 会触发该回调，并在回调中明确状态发生改变的 URL 地址及当前推流状态。 该回调方便推流用户了解当前的推流状态；推流出错时，你可以通过返回的错误码了解出错的原因，方便排查问题。

Type declaration

onStreamMessage

onStreamMessage: (uid: number, streamId: number, data: Uint8Array, length: number) => void

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

Type declaration

    • (uid: number, streamId: number, data: Uint8Array, length: number): void

    • Parameters

      • uid: number

        发送消息的用户 ID。

      • streamId: number

        Stream ID。

      • data: Uint8Array

        接收到的数据。

      • length: number

        数据长度。

      Returns void

onStreamMessageError

onStreamMessageError: (uid: number, streamId: number, code: number, missed: number, cached: number) => void

接收对方数据流消息发生错误的回调。 该回调表示本地用户未收到远端用户调用 sendStreamMessage 方法发送的流消息。

Type declaration

    • (uid: number, streamId: number, code: number, missed: number, cached: number): void

    • Parameters

      • uid: number

        发送消息的用户 ID。

      • streamId: number

        Stream ID。

      • code: number

        错误码: ERROR_CODE_TYPE。

      • missed: number

        丢失的消息数量。

      • cached: number

        数据流中断时，后面缓存的消息数量。

      Returns void

onStreamPublished

onStreamPublished: (url: string, error: number) => void

旁路推流已开启回调。

deprecated

此方法已废弃，请改用 onRtmpStreamingStateChanged 该回调用于通知主播推流状态。

Type declaration

    • (url: string, error: number): void

    • Parameters

      • url: string

        主播推流的 URL 地址 。

      • error: number

        agora.ERROR_CODE_TYPE 。

        • 0(ERR_OK): 推流成功。
        • -1(ERR_FAILED): 推流失败。
        • -2(ERR_INVALID_ARGUMENT): 参数错误。如果你在调用 addPublishStreamUrl 前没有调用 setLiveTranscoding 配置 LiveTranscoding，SDK 会回调 ERR_INVALID_ARGUMENT。
        • -10(ERR_TIMEDOUT): 推流超时未成功。
        • -19(ERR_ALREADY_IN_USE): 推流地址已推流。
        • -22(ERR_RESOURCE_LIMITED): 后台没有足够资源推流。
        • -130(ERR_ENCRYPTED_STREAM_NOT_ALLOWED_PUBLISH): 推流已加密不能推流。
        • -151(ERR_PUBLISH_STREAM_CDN_ERROR)
        • -152(ERR_PUBLISH_STREAM_NUM_REACH_LIMIT)
        • -153(ERR_PUBLISH_STREAM_NOT_AUTHORIZED)
        • -154(ERR_PUBLISH_STREAM_INTERNAL_SERVER_ERROR)
        • -156(ERR_PUBLISH_STREAM_FORMAT_NOT_SUPPORTED)

      Returns void

onStreamUnpublished

onStreamUnpublished: (url: string) => void

旁路推流已停止回调。

deprecated

此方法已废弃，请改用 onRtmpStreamingStateChanged 回调用于通知主播停止推流成功。

Type declaration

    • (url: string): void

    • Parameters

      • url: string

        被删除的 RTMP 推流地址。

      Returns void

onTokenPrivilegeWillExpire

onTokenPrivilegeWillExpire: (token: string) => void

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

Type declaration

    • (token: string): void

    • Parameters

      • token: string

        即将服务失效的 Token。

      Returns void

onTranscodingUpdated

onTranscodingUpdated: () => void

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

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

note

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

Type declaration

    • (): void

    • Returns void

onUserEnableLocalVideo

onUserEnableLocalVideo: (uid: number, enabled: boolean) => void

其他用户启用/关闭本地视频。

deprecated

从 v2.9.0。该回调已被废弃，请改用 onRemoteVideoStateChanged 回调的：

提示有其他用户启用/关闭了本地视频功能。关闭视频功能是指该用户只能进行语音通话， 不能显示、发送自己的视频，也不能接收、显示别人的视频。

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

Type declaration

    • (uid: number, enabled: boolean): void

    • Parameters

      • uid: number

        用户 ID，提示是哪个用户的视频流。

      • enabled: boolean
        • true: 该用户已启用视频功能。启用后，其他用户可以接收到该用户的视频流。
        • false: 该用户已关闭视频功能。关闭后，该用户仍然可以接收其他用户的视频流， 但其他用户接收不到该用户的视频流。

      Returns void

onUserEnableVideo

onUserEnableVideo: (uid: number, enabled: boolean) => void

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

deprecated

该回调已被废弃，请改用 onRemoteVideoStateChanged 回调的：

提示有远端用户开关了本地视频采集。关闭视频功能是指该用户只能进行语音通话，不能显示、 发送自己的视频，也不能接收、显示别人的视频。 该回调是由远端用户调用 enableVideo 或 disableVideo 方法开启或关闭视频模块触发的。

Type declaration

    • (uid: number, enabled: boolean): void

    • Parameters

      • uid: number

        用户 ID，提示是哪个用户的视频流。

      • enabled: boolean
        • true: 该用户已启用了视频功能。启用后，该用户可以进行视频通话或直播。
        • false: 该用户已关闭了视频功能。关闭后，该用户只能进行语音通话或直播，不能显示、 发送自己的视频，也不能接收、显示别人的视频。

      Returns void

onUserInfoUpdated

onUserInfoUpdated: (uid: number, info: UserInfo) => void

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

Type declaration

    • Parameters

      • uid: number

        远端用户的 UID

      • info: UserInfo

        标识用户信息的 UserInfo，包含用户 UID 和 User Account

      Returns void

onUserJoined

onUserJoined: (uid: number, elapsed: number) => void

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

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

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

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

Note

直播场景下，

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

Type declaration

    • (uid: number, elapsed: number): void

    • Parameters

      • uid: number

        新加入频道的远端用户/主播 ID。

      • elapsed: number

        从本地用户调用 joinChannel 到该回调触发的延迟（毫秒)。

      Returns void

onUserMuteAudio

onUserMuteAudio: (uid: number, muted: boolean) => void

远端用户静音回调。

deprecated

该回调已废弃。请改用 onRemoteAudioStateChanged 提示有远端用户已将其 音频流静音（或取消静音）。 该回调是由远端用户调用 muteLocalAudioStream 方法关闭或开启音频发送触发的。

note

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

Type declaration

    • (uid: number, muted: boolean): void

    • Parameters

      • uid: number

        用户 ID。

      • muted: boolean

        该用户是否静音：

        • true: 该用户已将音频静音；
        • false: 该用户取消了音频静音。

      Returns void

onUserMuteVideo

onUserMuteVideo: (uid: number, muted: boolean) => void

远端用户暂停/恢复发送视频流回调。

deprecated

该回调已废弃。你也可以使用 onRemoteVideoStateChanged 回调的：

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

note

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

Type declaration

    • (uid: number, muted: boolean): void

    • Parameters

      • uid: number

        远端用户 ID。

      • muted: boolean

        该用户是否暂停发送其视频流

        • true: 该用户已暂停发送其视频流；
        • false: 该用户已恢复发送其视频流。

      Returns void

onUserOffline

onUserOffline: (uid: number, reason: USER_OFFLINE_REASON_TYPE) => void

远端用户（通信场景）/主播（直播场景）离开当前频道回调。 提示有远端用户/主播离开了频道（或掉线）。用户离开频道有两个原因，即正常离开和超时掉线：

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

Type declaration

onVideoDeviceStateChanged

onVideoDeviceStateChanged: (deviceId: string, deviceType: MEDIA_DEVICE_TYPE, deviceState: MEDIA_DEVICE_STATE_TYPE) => void

视频设备变化回调。 该回调提示系统视频设备状态发生改变，比如被拔出或移除。如果设备已使用外接摄像头采集，外接摄像头被拔开后，视频会中断。

Type declaration

onVideoPublishStateChanged

onVideoPublishStateChanged: (channel: string, oldState: STREAM_PUBLISH_STATE, newState: STREAM_PUBLISH_STATE, elapseSinceLastState: number) => void

视频发布状态改变回调。

Type declaration

onVideoSizeChanged

onVideoSizeChanged: (uid: number, width: number, height: number, rotation: number) => void

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

Type declaration

    • (uid: number, width: number, height: number, rotation: number): void

    • Parameters

      • uid: number

        图像尺寸和旋转信息发生变化的用户的用户 ID（本地用户的 uid 为 0）。

      • width: number

        视频流的宽度（像素）。

      • height: number

        视频流的高度（像素）。

      • rotation: number

        旋转信息 [0,360)。

      Returns void

onVideoStopped

onVideoStopped: () => void

视频功能已停止回调。

deprecated

请改用 onLocalVideoStateChanged 回调中的 LOCAL_VIDEO_STREAM_STATE_STOPPED(0)。 提示视频功能已停止。 App 如需在停止视频后对 view 做其他处理（比如显示其他画面），可以在这个回调中进行。

Type declaration

    • (): void

    • Returns void

onVideoSubscribeStateChanged

onVideoSubscribeStateChanged: (channel: string, uid: number, oldState: STREAM_SUBSCRIBE_STATE, newState: STREAM_SUBSCRIBE_STATE, elapseSinceLastState: number) => void

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

Type declaration

onWarning

onWarning: (warn: WARN_CODE_TYPE, msg: string) => void

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

Type declaration