添加监听

方法名

addListener

注意

您可以通过该方法获得来自 SDK 的各类事件通知（例如：错误码，警告码，音视频状态参数等）

用法

用法如下：

uniappuniappx

module.addListener({
  //成功执行的函数
  success: (res) => {
    let data = res.data;
    console.log(data)
  },
  //失败执行的函数
  fail: (res) => {
    console.log(res)
  },
  //接口调用完成返回函数，不管成功还是失败都会返回
  complete: (res) => {
    // console.log(res)
  }
})

module.addListener({
  //成功执行的函数
  success: (res) => {
    const data = res.data;
    console.log(data)
  },
  //失败执行的函数
  fail: (res) => {
    console.log(res)
  },
  //接口调用完成返回函数，不管成功还是失败都会返回
  // complete: (res) => {
  //   console.log(res)
  // }
} as LevenOptions)

参数说明

参数名	参数类型	是否必填	默认值	参数描述
success	Function	否	无	执行成功的函数
fail	Function	否	无	执行失败的函数
complete	Function	否	无	执行完成的函数，不管成功还是失败都会执行

回调

示例

json

{
  "data": { },
  "message": "",
  "code": 0
}

回调说明：

参数名	参数类型	参数描述
message	String	消息提示
data	Object	数据对象
data.type	String	事件类型，请参考下方说明，类型相关其他数据会在type同级回调
code	Integer	返回类型，0.成功，其他：失败

事件类型说明

错误事件回调

类型名称 onError
说明
- 错误事件，表示 SDK 抛出的不可恢复的错误，例如进入房间失败或设备开启失败等。
- 参考文档：错误码表
字段说明
参数名参数类型参数描述
errCode Integer 错误码
errMsg String 错误信息
extraInfo Object 扩展信息字段，个别错误码可能会带额外的信息帮助定位问题

参数名	参数类型	参数描述
errCode	Integer	错误码
errMsg	String	错误信息
extraInfo	Object	扩展信息字段，个别错误码可能会带额外的信息帮助定位问题

警告事件回调

类型名称 onWarning
说明
- 警告事件，表示 SDK 抛出的提示性问题，例如视频出现卡顿或 CPU 使用率太高等
- 参考文档：错误码表
字段说明
参数名参数类型参数描述
warningCode Integer 警告码
errMsg String 警告信息
extraInfo Object 扩展信息字段，个别错误码可能会带额外的信息帮助定位问题

参数名	参数类型	参数描述
warningCode	Integer	警告码
errMsg	String	警告信息
extraInfo	Object	扩展信息字段，个别错误码可能会带额外的信息帮助定位问题

进入房间成功与否的事件回调

类型名称 onEnterRoom
说明
调用插件方法中的 enterRoom 接口执行进房操作后，会收到来自 onEnterRoom 回调：
- 如果加入成功，回调 result 会是一个正数（result > 0），代表进入房间所消耗的时间，单位是毫秒（ms）。
- 如果加入失败，回调 result 会是一个负数（result < 0），代表失败原因的错误码。
进房失败的错误码含义请参见错误码表
字段说明
参数名参数类型参数描述
result Integer result > 0 时为进房耗时（ms），result < 0 时为进房错误码。

参数名	参数类型	参数描述
result	Integer	result > 0 时为进房耗时（ms），result < 0 时为进房错误码。

离开房间的事件回调

类型名称 onEnterRoom
说明
调用插件方法中的 exitRoom 接口会执行退出房间的相关逻辑，例如释放音视频设备资源和编解码器资源等。
待SDK 占用的所有资源释放完毕后，SDK 会抛出 onExitRoom 回调通知到您。
如果您要再次调用 enterRoom 或者切换到其他的音视频 SDK，请等待 onExitRoom 回调到来后再执行相关操作。否则可能会遇到例如摄像头、麦克风设备被强占等各种异常问题。

字段说明

参数名	参数类型	参数描述
reason	Integer	离开房间原因 0：主动调用 `exitRoom` 退出房间； 1：被服务器移出当前房间； 2：当前房间整个被解散 3: 服务器状态异常。

切换角色的事件回调

类型名称 onSwitchRole
说明
调用插件方法中的 switchRole 接口会切换主播和观众的角色，该操作会伴随一个线路切换的过程，待 SDK 切换完成后，会抛出 onSwitchRole 事件回调。
字段说明
参数名参数类型参数描述
errCode Integer 错误码，ERR_NULL 代表切换成功，其他请参见错误码表
errMsg String 错误信息

切换房间的结果回调

类型名称 onSwitchRoom
说明
调用插件方法中的 switchRoom 接口可以让用户快速地从一个房间切换到另一个房间，待 SDK 切换完成后，会抛出onSwitchRoom事件回调。
字段说明
参数名参数类型参数描述
errCode Integer 错误码，ERR_NULL 代表切换成功，其他请参见错误码表
errMsg String 错误信息

请求跨房通话的结果回调

类型名称 onConnectOtherRoom
说明
调用插件方法中的 connectOtherRoom 接口会将两个不同房间中的主播拉通视频通话，也就是所谓的“主播PK”功能。调用者会收到 onConnectOtherRoom 回调来获知跨房通话是否成功。

字段说明

参数名	参数类型	参数描述
errCode	Integer	错误码，ERR_NULL 代表切换成功，其他请参见错误码表
errMsg	String	错误信息
userId	String	要跨房通话的另一个房间中的主播的用户 ID

结束跨房通话的结果回调

类型名称 onDisConnectOtherRoom
说明
调用插件方法中的 disConnectOtherRoom 接口会结束两个不同房间中的主播视频通话，也就是所谓的“主播PK”功能。调用者会收到 onDisconnectOtherRoom 回调来获知结束跨房通话是否成功。
字段说明
参数名参数类型参数描述
errCode Integer 错误码，ERR_NULL 代表成功，其他请参见错误码表
errMsg String 错误信息

参数名	参数类型	参数描述
errCode	Integer	错误码，ERR_NULL 代表成功，其他请参见错误码表
errMsg	String	错误信息

更改跨房主播上行能力的结果回调

类型名称 onUpdateOtherRoomForwardMode
说明
调用插件方法中的 updateOtherRoomForwardMode 接口会限制跨房主播在本房间内的上行能力，禁止或允许跨房主播发布音频/主路视频/辅路视频，该行为会影响房间内的所有用户。调用者会收到 onUpdateOtherRoomForwardMode 回调来获知更改跨房主播上行能力是否成功。
字段说明
参数名参数类型参数描述
errCode Integer 错误码，ERR_NULL 代表成功，其他请参见错误码表
errMsg String 错误信息

参数名	参数类型	参数描述
errCode	Integer	错误码，ERR_NULL 代表成功，其他请参见错误码表
errMsg	String	错误信息

有用户加入当前房间

类型名称 onRemoteUserEnterRoom
说明
出于性能方面的考虑，在 TRTC 两种不同的应用场景（即 AppScene ，在 enterRoom 时通过第二个参数指定）下，该通知的行为会有差别：
- 直播类场景（TRTC_APP_SCENE_LIVE 和 TRTC_APP_SCENE_VOICE_CHATROOM）：该场景下的用户区分主播和观众两种角色，只有主播进入房间时才会触发该通知，观众进入房间时不会触发该通知。
- 通话类场景（TRTC_APP_SCENE_VIDEOCALL 和 TRTC_APP_SCENE_AUDIOCALL）：该场景下的用户没有角色的区分（可认为都是主播），任何用户进入房间都会触发该通知。
注意
1. 事件回调 onRemoteUserEnterRoom 和 onRemoteUserLeaveRoom 只适用于维护当前房间里的“用户列表”，有此事件回调不代表一定有视频画面。
2. 如果需要显示远程画面，请监听代表某个用户是否有视频画面的 onUserVideoAvailable 事件回调。
字段说明
参数名参数类型参数描述
userId String 远端用户的用户标识。

有用户离开当前房间

类型名称 onRemoteUserLeaveRoom
说明
与 onRemoteUserEnterRoom 相对应，在两种不同的应用场景（即 AppScene，在 enterRoom 时通过第二个参数指定）下，该通知的行为会有差别：
- 直播类场景（TRTC_APP_SCENE_LIVE 和 TRTC_APP_SCENE_VOICE_CHATROOM）：该场景下的用户区分主播和观众两种角色，只有主播离开房间时才会触发该通知，观众离开房间时不会触发该通知。
- 通话类场景（TRTC_APP_SCENE_VIDEOCALL 和 TRTC_APP_SCENE_AUDIOCALL）：该场景下的用户没有角色的区分（可认为都是主播），任何用户离开房间都会触发该通知。

字段说明

参数名	参数类型	参数描述
userId	String	远端用户的用户标识。
reason	Integer	离开原因 `0`表示用户主动退出房间 `1`表示用户超时退出 `2`表示被移出房间 `3`表示主播因切换到观众退出房间。

某远端用户发布/取消了主路视频画面

类型名称 onUserVideoAvailable
说明
主路画面一般被用于承载摄像头画面。当您收到onUserVideoAvailable通知时，表示该路画面已经有可播放的视频帧到达。此时，您需要调用组件的 startRemoteView 接口订阅该用户的远程画面，订阅成功后，您会继续收到该用户的首帧画面渲染回调 onFirstVideoFrame
当您收到 onUserVideoAvailable 通知时，表示该路远程画面已经被关闭，关闭的原因可能是该用户调用了 muteLocalVideo 或 stopLocalPreview。
字段说明
参数名参数类型参数描述
userId String 远端用户的用户标识。
available Boolean 该用户是否发布（或取消发布）了主路视频画面，true：发布；false：取消发布。

某远端用户发布/取消了辅路视频画面

类型名称 onUserSubStreamAvailable
说明
“辅路画面”一般被用于承载屏幕分享的画面。当您收到 onUserSubStreamAvailable 通知时，表示该路画面已经有可播放的视频帧到达。
此时，您需要调用 startRemoteView 接口订阅该用户的远程画面，订阅成功后，您会继续收到该用户的首帧画面渲染回调 onFirstVideoFrame 。
字段说明
参数名参数类型参数描述
userId String 远端用户的用户标识。
available Boolean 该用户是否发布（或取消发布）了辅路视频画面，true: 发布；false：取消发布。

某远端用户发布/取消了自己的音频

类型名称 onUserAudioAvailable
说明
当您收到 onUserAudioAvailable 通知时，表示该用户发布了自己的声音，此时 SDK 的表现为：
- 在自动订阅模式下，您无需做任何操作，SDK 会自动播放该用户的声音。
- 在手动订阅模式下，您可以通过 muteRemoteAudio 来播放该用户的声音。
字段说明
参数名参数类型参数描述
userId String 远端用户的用户标识。
available Boolean 该用户是否发布（或取消发布）了自己的音频，true: 发布；false：取消发布

SDK 开始渲染自己本地或远端用户的首帧画面。

类型名称 onFirstVideoFrame
说明
SDK 会在渲染自己本地或远端用户的首帧画面时抛出该事件，您可以通过回调事件中的 userId 参数来判断事件来自于“本地”还是来自于“远端”。
- 如果 userId 为空值，代表 SDK 已经开始渲染自己本地的视频画面，不过前提是您已经调用了 startLocalPreview 或 startScreenCapture。
- 如果 userId 不为空，代表 SDK 已经开始渲染远端用户的视频画面，不过前提是您已经调用了 startRemoteView 订阅了该用户的视频画面。

字段说明

参数名	参数类型	参数描述
userId	String	本地或远端的用户标识，如果 userId 为空值代表自己本地的首帧画面已到来，userId 不为空则代表远端用户的首帧画面已到来。
streamType	Boolean	视频流类型：主路（Main）一般用于承载摄像头画面，辅路（Sub）一般用于承载屏幕分享画面
height	Integer	画面的高度。
width	Integer	画面的宽度

SDK 开始播放远端用户的首帧音频

类型名称 onFirstAudioFrame
说明
SDK 会在播放远端用户的首帧音频时抛出该事件，本地音频的首帧事件暂不抛出。
字段说明
参数名参数类型参数描述
userId String 远端用户的用户标识。

自己本地的首个视频帧已被发布出去

类型名称 onSendFirstLocalVideoFrame
说明
当您成功进入房间并通过 startLocalPreview 或 startScreenCapture 开启本地视频采集之后（开启采集和进入房间的先后顺序无影响），SDK 就会开始进行视频编码，并通过自身的网络模块向云端发布自己本地的视频数据。当 SDK 成功地向云端送出自己的第一帧视频数据帧以后，就会抛出 onSendFirstLocalVideoFrame 事件回调。
字段说明
参数名参数类型参数描述
streamType Integer 视频流类型：主路（Main）一般用于承载摄像头画面，辅路（Sub）一般用于承载屏幕分享画面。

参数名	参数类型	参数描述
streamType	Integer	视频流类型：主路（Main）一般用于承载摄像头画面，辅路（Sub）一般用于承载屏幕分享画面。

自己本地的首个音频帧已被发布出去

类型名称 onSendFirstLocalAudioFrame
说明
当您成功进入房间并通过 startLocalAudio 开启本地音频采集之后（开启采集和进入房间的先后顺序无影响），SDK 就会开始进行音频编码，并通过自身的网络模块向云端发布自己本地的音频数据。当 SDK 成功地向云端送出自己的第一帧音频数据帧以后，就会抛出 onSendFirstLocalAudioFrame 事件回调。
字段说明
参数名参数类型参数描述
无 - -

参数名	参数类型	参数描述
无	-	-

远端视频状态变化的事件回调

类型名称 onRemoteVideoStatusUpdated
说明
您可以通过此事件回调获取远端每一路画面的播放状态（包括 Playing、Loading 和 Stopped 三种状态），从而进行相应的 UI 展示

字段说明

参数名	参数类型	参数描述
userId	String	用户标识
streamType	Integer	视频流类型：主路（Main）一般用于承载摄像头画面，辅路（Sub）一般用于承载屏幕分享画面
status	Integer	视频状态：包括 Playing、Loading 和 Stopped 三种状态 `0`: Stopped `1`: Playing `2`: Loading
reason	Integer	视频状态改变的原因
extraInfo	Object	额外信息

远端音频状态变化的事件回调

类型名称 onRemoteAudioStatusUpdated
说明
您可以通过此事件回调获取远端每一路音频的播放状态（包括 Playing、Loading 和 Stopped 三种状态），从而进行相应的 UI 展示

字段说明

参数名	参数类型	参数描述
userId	String	用户标识
status	Integer	音频状态：包括 Playing、Loading 和 Stopped 三种状态 `0`: Stopped `1`: Playing `2`: Loading
reason	Integer	音频状态改变的原因
extraInfo	Object	额外信息

用户视频大小发生改变回调

类型名称 onUserVideoSizeChanged
说明
当您收到 onUserVideoSizeChanged 通知时，表示该路画面大小发生了调整，调整的原因可能是该用户调用了 setVideoEncoderParam 或者 setSubStreamEncoderParam 重新设置了画面尺寸

字段说明

参数名	参数类型	参数描述
userId	String	用户标识
streamType	Integer	视频流类型：主路（Main）一般用于承载摄像头画面，辅路（Sub）一般用于承载屏幕分享画面
newWidth	Integer	视频流的宽度（像素）
newHeight	Object	视频流的高度（像素）

网络质量的实时统计回调

类型名称 onNetworkQuality
说明
该统计回调每间隔2秒抛出一次，用于通知 SDK 感知到的当前网络的上行和下行质量。SDK 会使用一组内嵌的自研算法对当前网络的延迟高低、带宽大小以及稳定情况进行评估，并计算出一个评估结果：如果评估结果为 1（Excellent）代表当前的网络情况非常好，如果评估结果为 6（Down）代表当前网络无法支撑 TRTC 的正常通话。

字段说明

参数名	参数类型	参数描述
localQuality	Object	上行网络质量
localQuality.quality	Integer	网络质量，参考值
localQuality.userId	String	用户标识
remoteQualityList	Array[Object]	下行网络质量，代表数据流历经“远端->云端->本端”这样一条完整的传输链路后，最终在本端统计到的数据质量。因此，这里的下行网络质量代表的是远端上行链路与本端下行链路共同影响的结果
remoteQualityList.quality	Integer	网络质量，参考值
remoteQualityList.userId	String	用户标识

音视频技术指标的实时统计回调

类型名称 onStatistics
说明
该统计回调每间隔2秒抛出一次，用于通知 SDK 内部音频、视频以及网络相关的专业技术指标，这些信息在 TRTCStatistics 均有罗列：
- 视频统计信息：视频的分辨率（resolution）、帧率（FPS）和比特率（bitrate）等信息。
- 音频统计信息：音频的采样率（samplerate）、声道（channel）和比特率（bitrate）等信息。
- 网络统计信息：SDK 和云端一次往返（SDK > Cloud > SDK）的网络耗时（rtt）、丢包率（loss）、上行流量（sentBytes）和下行流量（receivedBytes）等信息。
注意
如果您只需要获知当前网络质量的好坏，并不需要花太多时间研究本统计回调，更推荐您使用 onNetworkQuality 来解决问题。

字段说明

参数名	参数类型	参数描述
appCpu	Integer	当前应用的 CPU 使用率，单位 (%)，Android 8.0 以上不支持
downLoss	Integer	从云端到 SDK 的下行丢包率，单位 (%) 该数值越小越好，如果 downLoss 为 0%，则意味着下行链路的网络质量很好，从云端接收的数据包基本不发生丢失。如果 downLoss 为 30%，则意味着云端向 SDK 传输的音视频数据包中，会有 30% 丢失在传输链路中。
gatewayRtt	Integer	从 SDK 到本地路由器的往返时延，单位 ms 该数值代表从 SDK 发送一个网络包到本地路由器网关，再从网关回送一个网络包到 SDK 的总计耗时，也就是一个网络包经历 “SDK=>网关=>SDK” 的总耗时该数值越小越好：如果 gatewayRtt < 50ms，意味着较低的音视频通话延迟；如果 gatewayRtt > 200ms，则意味着较高的音视频通话延迟。当网络类型为蜂窝网时，该值无效。
localArray	Array[Object]	本地的音视频统计信息由于本地可能有三路音视频流（即高清大画面，低清小画面，以及辅流画面），因此本地的音视频统计信息是一个数组。
localArray.audioBitrate	Integer	本地音频的码率，即每秒钟新产生音频数据的多少，单位 Kbps
localArray.streamType	Integer	视频流类型（高清大画面
localArray.height	Integer	本地视频的高度，单位 px
localArray.width	Integer	本地视频的宽度，单位 px
localArray.audioCaptureState	Integer	音频设备采集状态（用于检测音频外设的健康度）。 `0`：采集设备状态正常； `1`：检测到长时间静音； `2`：检测到破音； `3`：检测到声音异常间断。
localArray.audioSampleRate	Integer	本地音频的采样率，单位 Hz
localArray.frameRate	Integer	本地视频的帧率，即每秒钟会有多少视频帧，单位：FPS
localArray.videoBitrate	Integer	本地视频的码率，即每秒钟新产生视频数据的多少，单位 Kbps
receiveBytes	Integer	总接收字节数（包含信令数据和音视频数据），单位：字节数（Bytes）
remoteArray	Array[Object]	远端的音视频统计信息因为同时可能有多个远端用户，而且每个远端用户同时可能有多路音视频流（即高清大画面，低清小画面，以及辅流画面），因此远端的音视频统计信息是一个数组。
remoteArray.audioBitrate	Integer	远端音频的码率，单位 Kbps
remoteArray.audioSampleRate	Integer	远端音频的采样率，单位 Hz
remoteArray.audioBlockRate	Integer	音频播放卡顿率，单位 (%) 音频播放卡顿率（audioBlockRate） = 音频播放的累计卡顿时长（audioTotalBlockTime） / 音频播放的总时长
remoteArray.height	Integer	远端视频的高度，单位 px
remoteArray.frameRate	Integer	远端视频的帧率，单位：FPS。
remoteArray.audioPacketLoss	Integer	音频流的总丢包率（％）。 audioPacketLoss 代表音频流历经“主播>云端>观众”这样一条完整的传输链路后，最终在观众端统计到的丢包率。 audioPacketLoss 越小越好，丢包率为0即表示该路音频流的所有数据均已经完整地到达了观众端。如果出现了 downLoss == 0 但 audioPacketLoss != 0 的情况，说明该路音频流在“云端=>观众”这一段链路上没有出现丢包，但是在主播>云端这一段链路上出现了不可恢复的丢包。
remoteArray.audioTotalBlockTime	Integer	音频播放的累计卡顿时长，单位 ms
~~remoteArray.finalLoss~~	Integer	该路音视频流的总丢包率（％）。已废弃，不推荐使用；建议使用 audioPacketLoss、videoPacketLoss 替代。
remoteArray.jitterBufferDelay	Integer	播放延迟，单位 ms 为了避免网络抖动和网络包乱序导致的声音和画面卡顿，TRTC 会在播放端管理一个播放缓冲区，用于对接收到的网络数据包进行整理，该缓冲区的大小会根据当前的网络质量进行自适应调整，该缓冲区的大小折算成以毫秒为单位的时间长度，也就是 jitterBufferDelay
remoteArray.point2PointDelay	Integer	端到端延迟，单位 ms point2PointDelay 代表 “主播=>云端=>观众” 的延迟，更准确地说，它代表了“采集=>编码=>网络传输=>接收=>缓冲=>解码=>播放” 全链路的延迟。 point2PointDelay 需要本地和远端的 SDK 均为 8.5 及以上的版本才生效，若远端用户为 8.5 以前的版本，此数值会一直为0，代表无意义。
remoteArray.remoteNetworkRTT	Integer	该用户从 SDK 到云端的往返延时，单位 ms 该数值代表从 SDK 发送一个网络包到云端，再从云端回送一个网络包到 SDK 的总计耗时，也就是一个网络包经历 “SDK=>云端=>SDK” 的总耗时。该数值越小越好：如果 remoteNetworkRTT < 50ms，意味着较低的音视频通话延迟；如果 remoteNetworkRTT > 200ms，则意味着较高的音视频通话延迟。需要特别解释的是，remoteNetworkRTT 代表 “SDK=>云端=>SDK” 的总耗时，所以不需要区分 remoteNetworkUpRTT 和 remoteNetworkDownRTT
remoteArray.remoteNetworkUplinkLoss	Integer	该用户从 SDK 到云端的上行丢包率，单位 (%) 该数值越小越好，如果 remoteNetworkUplinkLoss 为 0%，则意味着上行链路的网络质量很好，上传到云端的数据包基本不发生丢失。如果 remoteNetworkUplinkLoss 为 30%，则意味着 SDK 向云端发送的音视频数据包中，会有 30% 丢失在传输链路中。
remoteArray.streamType	Integer	视频流类型（高清大画面
remoteArray.userId	String	用户 ID
remoteArray.videoBitrate	Integer	远端视频的码率，单位 Kbps
remoteArray.videoBlockRate	Integer	视频播放卡顿率，单位 (%) 视频播放卡顿率（videoBlockRate） = 视频播放的累计卡顿时长（videoTotalBlockTime） / 视频播放的总时长
remoteArray.videoPacketLoss	Integer	该路视频流的总丢包率（％）。 videoPacketLoss 代表该路视频流历经“主播>云端>观众”这样一条完整的传输链路后，最终在观众端统计到的丢包率。 videoPacketLoss 越小越好，丢包率为0即表示该路视频流的所有数据均已经完整地到达了观众端。如果出现了 downLoss == 0 但 videoPacketLoss != 0 的情况，说明该路视频流在“云端>观众”这一段链路上没有出现丢包，但是在“主播>云端”这一段链路上出现了不可恢复的丢包。
remoteArray.videoTotalBlockTime	Integer	视频播放的累计卡顿时长，单位 ms
rtt	Integer	从 SDK 到云端的往返延时，单位 ms 该数值代表从 SDK 发送一个网络包到云端，再从云端回送一个网络包到 SDK 的总计耗时，也就是一个网络包经历 “SDK=>云端=>SDK” 的总耗时。该数值越小越好：如果 rtt < 50ms，意味着较低的音视频通话延迟；如果 rtt > 200ms，则意味着较高的音视频通话延迟。需要特别解释的是，rtt 代表 “SDK=>云端=>SDK” 的总耗时，所以不需要区分 upRtt 和 downRtt
sendBytes	Integer	总发送字节数（包含信令数据和音视频数据），单位：字节数（Bytes）
systemCpu	Integer	当前系统的 CPU 使用率，单位 (%)，Android 8.0 以上不支持
upLoss	Integer	从 SDK 到云端的上行丢包率，单位 (%) 该数值越小越好，如果 upLoss 为 0%，则意味着上行链路的网络质量很好，上传到云端的数据包基本不发生丢失。如果 upLoss 为 30%，则意味着 SDK 向云端发送的音视频数据包中，会有 30% 丢失在传输链路中

网速测试的结果回调

类型名称 onSpeedTestResult
说明
该统计回调由 startSpeedTest 触发

字段说明

参数名	参数类型	参数描述
errMsg	String	带宽测试错误信息
rtt	Integer	延迟（毫秒），指当前设备到 TRTC 服务器的一次网络往返时间，该值越小越好，正常数值范围是10ms - 100ms
ip	String	服务器 IP 地址
quality	Integer	部通过评估算法测算出的网络质量 `0`.未定义 `1`.当前网络非常好 `2`.当前网络比较好 `3`.当前网络一般 `4`.当前网络较差 `5`.当前网络很差 `6`.当前网络不满足 TRTC 的最低要求
availableDownBandwidth	Integer	下行带宽（kbps，-1：无效值）
availableUpBandwidth	Integer	上行带宽（kbps，-1：无效值）
downJitter	Integer	下行数据包抖动（ms)，指用户当前网络环境下数据通信的稳定性，该值越小越好，正常数值范围是 [0, 100]，-1 代表此次测速没有成功测得有效值，一般情况下 Wi-Fi 网络的 Jitter 会比 4G/5G 环境稍大。
downLostRate	Integer	下行丢包率，取值范围是 [0 - 1.0]，例如 0.2 表示每从服务器收取 10 个数据包可能会在中途丢失 2 个
success	Boolean	测试是否成功
upJitter	Integer	上行数据包抖动（ms)，指用户当前网络环境下数据通信的稳定性，该值越小越好，正常数值范围是 [0, 100]，-1 代表此次测速没有成功测得有效值，一般情况下 Wi-Fi 网络的 Jitter 会比 4G/5G 环境稍大。
upLostRate	Integer	上行丢包率，取值范围是 [0 - 1.0]，例如 0.3 表示每向服务器发送 10 个数据包可能会在中途丢失 3 个

SDK与云端的连接已经断开

类型名称 onConnectionLost
说明
SDK 会在跟云端的连接断开时抛出此事件回调，导致断开的原因大多是网络不可用或者网络切换所致，例如用户在通话中走进电梯时就可能会遇到此事件。
在抛出此事件之后，SDK 会努力跟云端重新建立连接，重连过程中会抛出 onTryToReconnect，连接恢复后会抛出 onConnectionRecovery 。
字段说明
参数名参数类型参数描述
无 - -

参数名	参数类型	参数描述
无	-	-

SDK正在尝试重新连接到云端

类型名称 onTryToReconnect
说明
SDK 会在跟云端的连接断开时抛出 onConnectionLost，之后会努力跟云端重新建立连接并抛出本事件，连接恢复后会抛出 onConnectionRecovery。
字段说明
参数名参数类型参数描述
无 - -

参数名	参数类型	参数描述
无	-	-

SDK与云端的连接已经恢复

类型名称 onConnectionRecovery
说明
SDK 会在跟云端的连接断开时抛出 onConnectionLost，之后会努力跟云端重新建立连接并抛出 onTryToReconnect，连接恢复后会抛出本事件回调。
字段说明
参数名参数类型参数描述
无 - -

参数名	参数类型	参数描述
无	-	-

摄像头准备就绪

类型名称 onCameraDidReady
说明
当您调用 startLocalPreview 之后，SDK 会尝试启动摄像头，如果摄像头能够启动成功就会抛出本事件。
如果启动失败，大概率是因为当前应用没有获得访问摄像头的权限，或者摄像头当前正在被其他程序独占使用中。
您可以通过捕获 onError 事件回调获知这些异常情况并通过 UI 界面提示用户。
字段说明
参数名参数类型参数描述
无 - -

参数名	参数类型	参数描述
无	-	-

麦克风准备就绪

类型名称 onMicDidReady
说明
当您调用 startLocalAudio 之后，SDK 会尝试启动麦克风，如果麦克风能够启动成功就会抛出本事件。如果启动失败，大概率是因为当前应用没有获得访问麦克风的权限，或者麦克风当前正在被其他程序独占使用中。您可以通过捕获 onError 事件回调获知这些异常情况并通过 UI 界面提示用户。
字段说明
参数名参数类型参数描述
无 - -

参数名	参数类型	参数描述
无	-	-

当前音频路由发生变化

类型名称 onAudioRouteChanged
说明
所谓“音频路由”，是指声音是从手机的扬声器还是从听筒中播放出来，音频路由变化也就是声音的播放位置发生了变化。
- 当音频路由为听筒时，声音比较小，只有将耳朵凑近才能听清楚，隐私性较好，适合用于接听电话。
- 当音频路由为扬声器时，声音比较大，不用将手机贴脸也能听清，因此可以实现“免提”的功能。
- 当音频路由为有线耳机。
- 当音频路由为蓝牙耳机。
- 当音频路由为USB专业声卡设备。
字段说明
参数名参数类型参数描述
newRoute Integer 音频路由，即声音由哪里输出（扬声器、听筒）
oldRoute Integer 变更前的音频路由

参数名	参数类型	参数描述
newRoute	Integer	音频路由，即声音由哪里输出（扬声器、听筒）
oldRoute	Integer	变更前的音频路由

音量大小的反馈回调

类型名称 onUserVoiceVolume
说明
SDK 可以评估每一路音频的音量大小，并每隔一段时间抛出该事件回调，您可以根据音量大小在 UI 上做出相应的提示，例如 波形图 或 音量槽 。
要完成这个功能，您需要先调用 enableAudioVolumeEvaluation 开启这个能力并设定事件抛出的时间间隔。
需要补充说明的是，无论当前房间中是否有人说话，SDK 都会按照您设定的时间间隔定时抛出此事件回调。

字段说明

参数名	参数类型	参数描述
userVolumes	Object[]	是一个数组，用于承载所有正在说话的用户的音量大小，取值范围 [0, 100]
userVolumes.volume	Integer	说话者的音量大小, 取值范围[0 - 100]
userVolumes.userId	String	说话者的 userId, 如果 userId 为空则代表是当前用户自己
userVolumes.spectrumData	Float[]	音频频谱数据是将音频数据在频率域中的分布，划分为 256 个频率段，使用 spectrumData 记录各个频率段的能量值，每个能量值的取值范围为 [-300, 0]，单位为 dBFS
userVolumes.vad	Integer	是否检测到人声，0：非人声 1：人声
userVolumes.pitch	Float	本地用户的人声频率（单位：Hz），取值范围[0 - 4000]，对于远端用户，该值始终为0
totalVolume	Integer	所有远端用户的总音量大小，取值范围 [0, 100]

收到自定义消息的事件回调

类型名称 onRecvCustomCmdMsg
说明
当房间中的某个用户使用 sendCustomCmdMsg 发送自定义 UDP 消息时，房间中的其他用户可以通过 onRecvCustomCmdMsg 事件回调接收到该条消息。
字段说明
参数名参数类型参数描述
userId String 用户标识
cmdID Integer 命令 ID
seq Integer 消息序号
message byte[] 消息字节数据
messageString String 消息内容

自定义消息丢失的事件回调

类型名称 onMissCustomCmdMsg
说明
当您使用 sendCustomCmdMsg 发送自定义 UDP 消息时，即使设置了可靠传输（reliable），也无法确 100% 不丢失，只是丢消息概率极低，能满足常规可靠性要求。
在发送端设置了可靠运输（reliable）后，SDK 都会通过此回调通知过去时间段内（通常为5s）传输途中丢失的自定义消息数量统计信息。
注意
只有在发送端设置了可靠传输（reliable），接收方才能收到消息的丢失回调。
字段说明
参数名参数类型参数描述
userId String 用户标识
cmdID Integer 命令 ID
errCode Integer 错误码
missed Integer 丢失的消息数量

收到SEI消息的回调

类型名称 onRecvSEIMsg
说明
当房间中的某个用户使用 sendSEIMsg 借助视频数据帧发送 SEI 消息时，房间中的其他用户可以通过 onRecvSEIMsg 事件回调接收到该条消息。
字段说明
参数名参数类型参数描述
userId String 用户标识
message byte[] 消息字节数据
messageString String 消息内容

开始向腾讯云直播CDN上发布音视频流的事件回调

类型名称 onStartPublishing
说明
当您调用 startPublishing 开始向腾讯云直播 CDN 上发布音视频流时，SDK 会立刻将这一指令同步给云端服务器。随后 SDK 会收到来自云端服务器的处理结果，并将指令的执行结果通过本事件回调通知给您。
字段说明
参数名参数类型参数描述
err Integer 0表示成功，其余值表示失败，详见错误码。
errMsg String 具体错误原因

参数名	参数类型	参数描述
err	Integer	0表示成功，其余值表示失败，详见错误码。
errMsg	String	具体错误原因

停止向腾讯云直播CDN上发布音视频流的事件回调

类型名称 onStopPublishing
说明
当您调用 stopPublishing 停止向腾讯云直播 CDN 上发布音视频流时，SDK 会立刻将这一指令同步给云端服务器。
随后 SDK 会收到来自云端服务器的处理结果，并将指令的执行结果通过本事件回调通知给您。
字段说明
参数名参数类型参数描述
err Integer 0表示成功，其余值表示失败，详见错误码。
errMsg String 具体错误原因

参数名	参数类型	参数描述
err	Integer	0表示成功，其余值表示失败，详见错误码。
errMsg	String	具体错误原因

开始向非腾讯云CDN上发布音视频流的事件回调

类型名称 onStartPublishCDNStream
说明
当您调用 startPublishCDNStream 开始向非腾讯云直播 CDN 上发布音视频流时，SDK 会立刻将这一指令同步给云端服务器。随后 SDK 会收到来自云端服务器的处理结果，并将指令的执行结果通过本事件回调通知给您。
字段说明
参数名参数类型参数描述
err Integer 0表示成功，其余值表示失败，详见错误码。
errMsg String 具体错误原因

参数名	参数类型	参数描述
err	Integer	0表示成功，其余值表示失败，详见错误码。
errMsg	String	具体错误原因

停止向非腾讯云CDN上发布音视频流的事件回调

类型名称 onStopPublishCDNStream
说明
当您调用 stopPublishCDNStream 开始向非腾讯云直播 CDN 上发布音视频流时，SDK 会立刻将这一指令同步给云端服务器。随后 SDK 会收到来自云端服务器的处理结果，并将指令的执行结果通过本事件回调通知给您
字段说明
参数名参数类型参数描述
err Integer 0表示成功，其余值表示失败，详见错误码。
errMsg String 具体错误原因

参数名	参数类型	参数描述
err	Integer	0表示成功，其余值表示失败，详见错误码。
errMsg	String	具体错误原因

设置云端混流的排版布局和转码参数的事件回调

类型名称 onSetMixTranscodingConfig
说明
当您调用 setMixTranscodingConfig 调整云端混流的排版布局和转码参数时，SDK 会立刻将这一调整指令同步给云端服务器。随后 SDK 会收到来自云端服务器的处理结果，并将指令的执行结果通过本事件回调通知给您。
字段说明
参数名参数类型参数描述
err Integer 0表示成功，其余值表示失败，详见错误码。
errMsg String 具体错误原因

参数名	参数类型	参数描述
err	Integer	0表示成功，其余值表示失败，详见错误码。
errMsg	String	具体错误原因

开始发布媒体流的事件回调

类型名称 onStartPublishMediaStream
说明
当您调用 startPublishMediaStream 开始向 TRTC 后台服务发布媒体流时，SDK 会立刻将这一指令同步给云端服务器，随后 SDK 会收到来自云端服务器的处理结果，并将指令的执行结果通过本事件回调通知给您。

字段说明

参数名	参数类型	参数描述
taskId	String	当请求成功时，TRTC 后台会在回调中提供给您这项任务的 taskId，后续您可以通过该 taskId 结合 updatePublishMediaStream 和 stopPublishMediaStream 进行更新和停止。
code	Integer	回调结果，0 表示成功，其余值表示失败，详见错误码。
message	String	具体回调信息。
extraInfo	Object	扩展信息字段，个别错误码可能会带额外的信息帮助定位问题。当 code 返回值为 `ERR_SERVER_PROCESS_FAILED` 时，意味着服务器无法处理您的请求，此时可使用“error_code” 作为 key 获取到服务器返回的错误码，具体的错误码以及建议处理措施说明如下： `2000`: 参数错误，建议检查请求参数 `2001`: 未开通直播服务，建议去直播控制台开通直播服务 `2021`: 未开通转推第三方服务，建议联系产品开通转推第三方服务 `3000`: 服务器内部错误，建议重试 `4006`: 同一个任务并发冲突，上一个 startPublishMediaStream 任务服务器还在处理中，建议延迟重试 `4007`: 同一个任务已经通过 startPublishMediaStream 启动成功，建议使用返回的 taskId 调用 updatePublishMediaStream 接口更新任务 `5001`: 资源受限，建议延迟重试

更新媒体流的事件回调

类型名称 onUpdatePublishMediaStream
说明
当您调用媒体流发布接口 updatePublishMediaStream 开始向 TRTC 后台服务更新媒体流时，SDK 会立刻将这一指令同步给云端服务器，随后 SDK 会收到来自云端服务器的处理结果，并将指令的执行结果通过本事件回调通知给您。

字段说明

参数名	参数类型	参数描述
taskId	String	您调用媒体流发布接口 updatePublishMediaStream 时传入的 taskId，会通过此回调再带回给您，用于标识该回调属于哪一次更新请求。
code	Integer	回调结果，0 表示成功，其余值表示失败，详见错误码。
message	String	具体回调信息。
extraInfo	Object	扩展信息字段，个别错误码可能会带额外的信息帮助定位问题。当 code 返回值为 `ERR_SERVER_PROCESS_FAILED` 时，意味着服务器无法处理您的请求，此时可使用“error_code” 作为 key 获取到服务器返回的错误码，具体的错误码以及建议处理措施说明如下： `2000`: 参数错误，建议检查请求参数 `2001`: 未开通直播服务，建议去直播控制台开通直播服务 `2002`: 找不到任务，建议调用 startPublishMediaStream 接口重新启动任务 `2018`: 并发请求乱序，建议使用最新混流参数重试 `2021`: 未开通转推第三方服务，建议联系产品开通转推第三方服务 `3000`: 服务器内部错误，建议重试 `4003`: 任务正在退出中，建议先调用 stopPublishMediaStream 接口停止任务，再调用 startPublishMediaStream 接口启动任务

停止媒体流的事件回调

类型名称 onStopPublishMediaStream
说明
当您调用停止发布媒体流 topPublishMediaStream 开始向 TRTC 后台服务停止媒体流时，SDK 会立刻将这一指令同步给云端服务器，随后 SDK 会收到来自云端服务器的处理结果，并将指令的执行结果通过本事件回调通知给您。

字段说明

参数名	参数类型	参数描述
taskId	String	您调用停止发布媒体流 topPublishMediaStream 时传入的 taskId，会通过此回调再带回给您，用于标识该回调属于哪一次停止请求。
code	Integer	回调结果，0 表示成功，其余值表示失败，详见错误码。
message	String	具体回调信息。
extraInfo	Object	扩展信息字段，个别错误码可能会带额外的信息帮助定位问题。当 code 返回值为 `ERR_SERVER_PROCESS_FAILED` 时，意味着服务器无法处理您的请求，此时可使用“error_code” 作为 key 获取到服务器返回的错误码，具体的错误码以及建议处理措施说明如下： `2000`: 参数错误，建议检查请求参数 `2002`: 找不到任务，无需处理 `3000`: 服务器内部错误，建议重试 `4003`: 任务正在退出中，无需处理

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

类型名称 onCdnStreamStateChanged
说明
当您调用 startPublishMediaStream 开始向 TRTC 后台服务发布媒体流时，SDK 会立刻将这一指令同步给云端服务。
若您在目标推流配置(target)设置了向腾讯或者第三方 CDN 上发布音视频流的 URL 配置，则具体 RTMP 或者 RTMPS 推流状态将通过此回调同步给您。

字段说明

参数名	参数类型	参数描述
cdnUrl	String	您调用 startPublishMediaStream 时通过目标推流配置 (target) 传入的 url，在推流状态变更时，会通过此回调同步给您。
code	Integer	推流结果，0 表示成功，其余值表示出错，详见错误码。
status	Integer	推流状态。 `0`：推流未开始或者已结束。在您调用 stopPublishMediaStream 时会返回该状态。 `1`：正在连接 TRTC 服务器和 CDN 服务器。若无法立刻成功，TRTC 后台服务会多次重试尝试推流，并返回该状态（5s回调一次）。如成功进行推流，则进入状态 2；如服务器出错或 60 秒内未成功推流，则进入状态 4。 `2`：CDN 推流正在进行。在成功推流后，会返回该状态 `3`：TRTC 服务器和 CDN 服务器推流中断，正在恢复。当 CDN 出现异常，或推流短暂中断时，TRTC 后台服务会自动尝试恢复推流，并返回该状态（5s回调一次）。如成功恢复推流，则进入状态 2；如服务器出错或 60 秒内未成功恢复，则进入状态 4。 `4`：TRTC 服务器和 CDN 服务器推流中断，且恢复或连接超时。即此时推流失败，您可以再次调用 updatePublishMediaStream 尝试推流。 `5`：正在断开 TRTC 服务器和 CDN 服务器。在您调用 stopPublishMediaStream 时，TRTC 后台服务会依次同步状态 5 和状态 0。
msg	String	具体推流信息
extraInfo	Object	扩展信息字段，个别错误码可能会带额外的信息帮助定位问题

屏幕分享开启的事件回调

类型名称 onScreenCaptureStarted
说明
当您通过 startScreenCapture 等相关接口启动屏幕分享时，SDK 便会抛出此事件回调
字段说明
参数名参数类型参数描述
无 - -

参数名	参数类型	参数描述
无	-	-

屏幕分享暂停的事件回调

类型名称 onScreenCapturePaused
说明
当您通过 pauseScreenCapture 暂停屏幕分享时，SDK 便会抛出此事件回调
字段说明
参数名参数类型参数描述
无 - -

参数名	参数类型	参数描述
无	-	-

屏幕分享恢复的事件回调

类型名称 onScreenCaptureResumed
说明
当您通过 resumeScreenCapture 恢复屏幕分享时，SDK 便会抛出此事件回调
字段说明
参数名参数类型参数描述
无 - -

参数名	参数类型	参数描述
无	-	-

屏幕分享停止的事件回调

类型名称 onScreenCaptureStopped
说明
当您通过 stopScreenCapture 停止屏幕分享时，SDK 便会抛出此事件回调

字段说明

参数名	参数类型	参数描述
reason	Integer	停止原因，0：用户主动停止；1：屏幕窗口关闭导致停止；2：表示屏幕分享的显示屏状态变更（如接口被拔出、投影模式变更等）。

本地录制任务已经开始的事件回调

类型名称 onLocalRecordBegin
说明
当您调用 startLocalRecording 启动本地媒体录制任务时，SDK 会抛出该事件回调，用于通知您录制任务是否已经顺利启动

字段说明

参数名	参数类型	参数描述
errCode	Integer	状态码。 `0`：录制任务启动成功。 `-1`：内部错误导致录制任务启动失败。 `-2`：文件后缀名有误（例如不支持的录制格式）。 `-6`：录制已经启动，需要先停止录制。 `-7`：录制文件已存在，需要先删除文件。 `-8`：录制目录无写入权限，请检查目录权限问题。
storagePath	String	录制文件存储路径

本地录制任务正在进行中的进展事件回调

类型名称 onLocalRecording
说明
当您调用 startLocalRecording 成功启动本地媒体录制任务后，SDK 会定时地抛出本事件回调。
您可通过捕获该事件回调来获知录制任务的健康状况。
您可以在 startLocalRecording 时设定本事件回调的抛出间隔。
字段说明
参数名参数类型参数描述
duration Integer 已经录制的累计时长，单位毫秒
storagePath String 录制文件存储路径

本地录制分片的事件回调

类型名称 onLocalRecording
说明
当您开启分片录制时，每完成一个分片，都会通过此接口回调
字段说明
参数名参数类型参数描述
storagePath String 分片文件存储路径

本地录制任务已经结束的事件回调

类型名称 onLocalRecordComplete
说明
当您调用 stopLocalRecording 停止本地媒体录制任务时，SDK 会抛出该事件回调，用于通知您录制任务的最终结果

字段说明

参数名	参数类型	参数描述
errCode	Integer	状态码。 `0`：结束录制任务成功。 `-1`：录制失败。 `-2`：切换分辨率或横竖屏导致录制结束。 `-3`：录制时间太短，或未采集到任何视频或音频数据，请检查录制时长，或是否已开启音、视频采集。
storagePath	String	录制文件存储路径

实验性接口的事件回调

类型名称 onExperimentalEvent
字段说明
参数名参数类型参数描述
eventName String 事件名称
params String 参数

添加监听 ​

方法名 ​

用法 ​

回调 ​

事件类型说明 ​

错误事件回调 ​

警告事件回调 ​

进入房间成功与否的事件回调 ​

离开房间的事件回调 ​

切换角色的事件回调 ​

切换房间的结果回调 ​

请求跨房通话的结果回调 ​

结束跨房通话的结果回调 ​

更改跨房主播上行能力的结果回调 ​

有用户加入当前房间 ​

有用户离开当前房间 ​

某远端用户发布/取消了主路视频画面 ​

某远端用户发布/取消了辅路视频画面 ​

某远端用户发布/取消了自己的音频 ​

SDK 开始渲染自己本地或远端用户的首帧画面。 ​

SDK 开始播放远端用户的首帧音频 ​

自己本地的首个视频帧已被发布出去 ​

自己本地的首个音频帧已被发布出去 ​

远端视频状态变化的事件回调 ​

远端音频状态变化的事件回调 ​

用户视频大小发生改变回调 ​

网络质量的实时统计回调 ​

音视频技术指标的实时统计回调 ​

网速测试的结果回调 ​

SDK与云端的连接已经断开 ​

SDK正在尝试重新连接到云端 ​

SDK与云端的连接已经恢复 ​

摄像头准备就绪 ​

麦克风准备就绪 ​

当前音频路由发生变化 ​

音量大小的反馈回调 ​

收到自定义消息的事件回调 ​

自定义消息丢失的事件回调 ​

收到SEI消息的回调 ​

开始向腾讯云直播CDN上发布音视频流的事件回调 ​

停止向腾讯云直播CDN上发布音视频流的事件回调 ​

开始向非腾讯云CDN上发布音视频流的事件回调 ​

停止向非腾讯云CDN上发布音视频流的事件回调 ​

设置云端混流的排版布局和转码参数的事件回调 ​

开始发布媒体流的事件回调 ​

更新媒体流的事件回调 ​

停止媒体流的事件回调 ​

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

屏幕分享开启的事件回调 ​

屏幕分享暂停的事件回调 ​

屏幕分享恢复的事件回调 ​

屏幕分享停止的事件回调 ​

本地录制任务已经开始的事件回调 ​

本地录制任务正在进行中的进展事件回调 ​

本地录制分片的事件回调 ​

本地录制任务已经结束的事件回调 ​

实验性接口的事件回调 ​

添加监听

方法名

用法

回调

事件类型说明

错误事件回调

警告事件回调

进入房间成功与否的事件回调

离开房间的事件回调

切换角色的事件回调

切换房间的结果回调

请求跨房通话的结果回调

结束跨房通话的结果回调

更改跨房主播上行能力的结果回调

有用户加入当前房间

有用户离开当前房间

某远端用户发布/取消了主路视频画面

某远端用户发布/取消了辅路视频画面

某远端用户发布/取消了自己的音频

SDK 开始渲染自己本地或远端用户的首帧画面。

SDK 开始播放远端用户的首帧音频

自己本地的首个视频帧已被发布出去

自己本地的首个音频帧已被发布出去

远端视频状态变化的事件回调

远端音频状态变化的事件回调

用户视频大小发生改变回调

网络质量的实时统计回调

音视频技术指标的实时统计回调

网速测试的结果回调

SDK与云端的连接已经断开

SDK正在尝试重新连接到云端

SDK与云端的连接已经恢复

摄像头准备就绪

麦克风准备就绪

当前音频路由发生变化

音量大小的反馈回调

收到自定义消息的事件回调

自定义消息丢失的事件回调

收到SEI消息的回调

开始向腾讯云直播CDN上发布音视频流的事件回调

停止向腾讯云直播CDN上发布音视频流的事件回调

开始向非腾讯云CDN上发布音视频流的事件回调

停止向非腾讯云CDN上发布音视频流的事件回调

设置云端混流的排版布局和转码参数的事件回调

开始发布媒体流的事件回调

更新媒体流的事件回调

停止媒体流的事件回调

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

屏幕分享开启的事件回调

屏幕分享暂停的事件回调

屏幕分享恢复的事件回调

屏幕分享停止的事件回调

本地录制任务已经开始的事件回调

本地录制任务正在进行中的进展事件回调

本地录制分片的事件回调

本地录制任务已经结束的事件回调

实验性接口的事件回调