TRTCCallback

TRTCCallback

设置 TRTCCloud 回调

Example

// 创建/使用/销毁 TRTCCloud 对象的示例代码：
import TRTCCloud from 'trtc-electron-sdk';
this.rtcCloud = TRTCCloud.getTRTCShareInstance();

// 注册回调的方法，事件关键字详见下方"通用事件回调"
subscribeEvents = (rtcCloud) => {
 rtcCloud.on('onError', (errcode, errmsg) => {
     console.info('trtc_demo: onError :' + errcode + " msg" + errmsg);
 });
};

Events

onError

错误回调：SDK 不可恢复的错误，一定要监听，并分情况给用户适当的界面提示。

Parameters:
Name Type Description
errCode Number required

错误码
errMsg String required

错误信息

onWarning

警告回调：用于告知您一些非严重性问题，例如出现了卡顿或者可恢复的解码失败。

Parameters:
Name Type Description
warningCode Number required

警告码
warningMsg String required

警告信息
extra Any required

补充信息

onEnterRoom

已加入房间的回调

调用 TRTCCloud 中的 enterRoom() 接口执行进房操作后，会收到来自 SDK 的 onEnterRoom(result) 回调： 如果加入成功，result 会是一个正数（result > 0），代表加入房间的时间消耗，单位是毫秒（ms）。 如果加入失败，result 会是一个负数（result < 0），代表进房失败的错误码。 进房失败的错误码含义请参见 错误码。

注意：

  • 在 Ver6.6 之前的版本，只有进房成功会抛出 onEnterRoom(result) 回调，进房失败由 onError() 回调抛出。
  • 在 Ver6.6 及之后改为：进房成功返回正的 result，进房失败返回负的 result，同时进房失败也会有 onError() 回调抛出。
Parameters:
Name Type Description
result Number required

result > 0 时为进房耗时（ms），result < 0 时为进房错误码。

onExitRoom

退出房间的事件回调

调用 TRTCCloud 中的 exitRoom() 接口会执行退出房间的相关逻辑，例如释放音视频设备资源和编解码器资源等。 待资源释放完毕，SDK 会通过 onExitRoom() 回调通知到您。

如果您要再次调用 enterRoom() 或者切换到其他的音视频 SDK，请等待 onExitRoom() 回调到来后再执行相关操作。 否则可能会遇到例如摄像头、麦克风设备被强占等各种异常问题。

Parameters:
Name Type Description
reason Number required

离开房间原因，0：主动调用 exitRoom 退房；1：被服务器踢出当前房间；2：当前房间整个被解散。

onSwitchRoom

切换房间的事件回调

Parameters:
Name Type Description
errCode Number required

错误码，ERR_NULL 代表切换成功，其他请参见错误码。
errMsg String required

错误信息。

onSwitchRole

切换角色的事件回调

调用 TRTCCloud 中的 switchRole() 接口会切换主播和观众的角色，该操作会伴随一个线路切换的过程， 待 SDK 切换完成后，会抛出 onSwitchRole() 事件回调。

Parameters:
Name Type Description
errCode Number required

错误码，ERR_NULL 代表切换成功，其他请参见错误码。
errMsg String required

错误信息。

onConnectOtherRoom

请求跨房连麦（主播跨房 PK）的结果回调

调用 TRTCCloud 中的 connectOtherRoom() 接口会将两个不同房间中的主播拉通视频通话，也就是所谓的“主播PK”功能。 调用者会收到 onConnectOtherRoom() 回调来获知跨房通话是否成功， 如果成功，两个房间中的所有用户都会收到 PK 主播的 onUserVideoAvailable() 回调。

Parameters:
Name Type Description
userId String required

要 PK 的目标主播 userId。
errCode Number required

错误码，ERR_NULL 代表切换成功，其他请参见错误码。
errMsg String required

错误信息。

onDisconnectOtherRoom

关闭跨房连麦（主播跨房 PK）的结果回调

Parameters:
Name Type Description
errCode Number required

错误码，ERR_NULL 代表切换成功，其他请参见 错误码。
errMsg String required

错误信息。

onRemoteUserEnterRoom

有用户加入当前房间

出于性能方面的考虑，在两种不同的应用场景下，该通知的行为会有差别：

  • 通话场景（TRTCAppSceneVideoCall 和 TRTCAppSceneAudioCall）：该场景下用户没有角色的区别，任何用户进入房间都会触发该通知。
  • 直播场景（TRTCAppSceneLIVE 和 TRTCAppSceneVoiceChatRoom）：该场景不限制观众的数量，如果任何用户进出都抛出回调会引起很大的性能损耗，所以该场景下只有主播进入房间时才会触发该通知，观众进入房间不会触发该通知。

注意：onRemoteUserEnterRoom 和 onRemoteUserLeaveRoom 只适用于维护当前房间里的“成员列表”，如果需要显示远程画面，建议使用监听 onUserVideoAvailable() 事件回调。

Parameters:
Name Type Description
userId String required

用户标识

onRemoteUserLeaveRoom

有用户离开当前房间

与 onRemoteUserEnterRoom 相对应，在两种不同的应用场景下，该通知的行为会有差别：

  • 通话场景（TRTCAppSceneVideoCall 和 TRTCAppSceneAudioCall）：该场景下用户没有角色的区别，任何用户的离开都会触发该通知。
  • 直播场景（TRTCAppSceneLIVE 和 TRTCAppSceneVoiceChatRoom）：只有主播离开房间时才会触发该通知，观众离开房间不会触发该通知。
Parameters:
Name Type Description
userId String required

用户标识
reason Number required

离开原因，0表示用户主动退出房间，1表示用户超时退出，2表示被踢出房间。

onUserVideoAvailable

用户是否开启摄像头视频

当您收到 onUserVideoAvailable(userId, 1) 通知时，代表该路画面已经有可用的视频数据帧到达。 之后，您需要调用 startRemoteView() 接口加载该用户的远程画面。 再之后，您还会收到名为 onFirstVideoFrame(userId) 的首帧画面渲染回调。

当您收到了 onUserVideoAvailable(userId, 0) 通知时，代表该路远程画面已经被关闭，这可能是 由于该用户调用了 muteLocalVideo() 或 stopLocalPreview() 所致。

Parameters:
Name Type Description
userId String required

用户标识
available Number required

画面是否开启

onUserSubStreamAvailable

用户是否开启了辅路画面（TRTCVideoStreamTypeSub，一般用于屏幕分享）

注意：显示辅路画面使用的函数是startRemoteView(), 从 8.0 版本开始已不再推荐使用 startRemoteSubStreamView()。

Parameters:
Name Type Description
userId String required

用户标识
available Number required

辅路画面是否开启

onUserAudioAvailable

用户是否开启音频上行

Parameters:
Name Type Description
userId String required

用户标识
available Number required

声音是否开启

onFirstVideoFrame

开始渲染本地或远程用户的首帧画面

如果 userId 为 null，表示开始渲染本地采集的摄像头画面，需要您先调用 startLocalPreview() 触发。 如果 userId 不为 null，表示开始渲染远程用户的首帧画面，需要您先调用 startRemoteView() 触发。

注意：只有当您调用 startLocalPreview() 或 startRemoteView() 之后，才会触发该回调。

Parameters:
Name Type Description
userId String required

本地或远程用户 ID，如果 userId == '' 代表本地，userId != '' 代表远程。
streamType Number required

视频流类型，TRTCVideoStreamTypeBig：主路画面，一般用于摄像头；TRTCVideoStreamTypeSub：辅路画面，一般用于屏幕分享。
width Number required

画面宽度
height Number required

画面高度

onFirstAudioFrame

开始播放远程用户的首帧音频（本地声音暂不通知）

Parameters:
Name Type Description
userId String required

远程用户 ID。

onSendFirstLocalVideoFrame

首帧本地视频数据已经被送出

SDK 会在 enterRoom() 并 startLocalPreview() 成功后开始摄像头采集，并将采集到的画面进行编码。 当 SDK 成功向云端送出第一帧视频数据后，会抛出这个回调事件。

Parameters:
Name Type Description
streamType Number required
  • 视频流类型，TRTCVideoStreamTypeBig：主路画面，一般用于摄像头；TRTCVideoStreamTypeSub：辅路画面，一般用于屏幕分享。

onSendFirstLocalAudioFrame

首帧本地音频数据已经被送出

SDK 会在 enterRoom() 并 startLocalAudio() 成功后开始麦克风采集，并将采集到的声音进行编码。 当 SDK 成功向云端送出第一帧音频数据后，会抛出这个回调事件。

onUserEnter

废弃事件：有主播加入当前房间

该回调接口可以被看作是 onRemoteUserEnterRoom 的废弃版本，不推荐使用。请使用 onUserVideoAvailable 或 onRemoteUserEnterRoom 进行替代。

Deprecated:
  • 从 TRTCSDK6.8 后该接口已被废弃，不推荐使用
Parameters:
Name Type Description
userId String required

用户标识

onUserExit

废弃事件：有主播离开当前房间

该回调接口可以被看作是 onRemoteUserLeaveRoom 的废弃版本，不推荐使用。请使用 onUserVideoAvailable 或 onRemoteUserEnterRoom 进行替代。

Deprecated:
  • 从 TRTCSDK6.8 后该接口已被废弃，不推荐使用
Parameters:
Name Type Description
userId String required

用户标识
reason Number required

离开原因代码，区分用户是正常离开，还是由于网络断线等原因离开。

onNetworkQuality

网络质量：该回调每2秒触发一次，统计当前网络的上行和下行质量

注意：userId == '' 代表自己当前的视频质量

Parameters:
Name Type Description
localQuality TRTCQualityInfo required

上行网络质量
remoteQuality Array.<TRTCQualityInfo> required

下行网络质量

onStatistics

技术指标统计回调

如果您是熟悉音视频领域相关术语，可以通过这个回调获取 SDK 的所有技术指标。 如果您是首次开发音视频相关项目，可以只关注 onNetworkQuality 回调。

注意：每2秒回调一次

Parameters:
Name Type Description
statis TRTCStatistics required

统计数据，包括本地和远程的

onConnectionLost

SDK 跟服务器的连接断开

onTryToReconnect

SDK 尝试重新连接到服务器

onConnectionRecovery

SDK 跟服务器的连接恢复

onSpeedTest

废弃事件：服务器测速的回调，SDK 对多个服务器 IP 做测速，每个 IP 的测速结果通过这个回调通知

Deprecated:
  • 从 TRTCSDK 9.3 后该接口已被废弃，不会抛出该事件, 请采用 onSpeedTestResult 事件代替
Parameters:
Name Type Description
currentResult TRTCSpeedTestResult required

当前完成的测速结果
finishedCount Number required

已完成测速的服务器数量
totalCount Number required

需要测速的服务器总数量

onSpeedTestResult

网速测试的结果回调

该统计回调由 startSpeedTest 触发。

Parameters:
Name Type Description
result TRTCSpeedTestResult required

网速测试数据数据，包括丢包、往返延迟、上下行的带宽速率。

onCameraDidReady

摄像头准备就绪

onMicDidReady

麦克风准备就绪

onUserVoiceVolume

userId 对应的成员语音音量

您可以通过调用 TRTCCloud 中的 enableAudioVolumeEvaluation() 接口来开关这个回调或者设置它的触发间隔。 需要注意的是，调用 enableAudioVolumeEvaluation 开启音量回调后，无论频道内是否有人说话，都会按设置的时间间隔调用这个回调， 如果没有人说话，则 totalVolume 为0。

Parameters:
Name Type Description
userVolumes TRTCVolumeInfo required

每位发言者的语音音量，取值范围0 - 100
userVolumesCount Number required

发言者的人数，即 userVolumes 数组的大小
totalVolume Number required

总的语音音量, 取值范围0 - 100

onDeviceChange

本地设备通断回调

Parameters:
Name Type Description
deviceId String required

Windows 端返回设备名，Mac 端返回设备 ID
type TRTCDeviceType required

设备类型
state TRTCDeviceState required

事件类型

onTestMicVolume

麦克风测试音量回调

麦克风测试接口 startMicDeviceTest() 会触发这个回调

Parameters:
Name Type Description
volume Number required

音量值，取值范围0 - 100

onTestSpeakerVolume

扬声器测试音量回调

扬声器测试接口 startSpeakerDeviceTest() 会触发这个回调

Parameters:
Name Type Description
volume Number required

音量值，取值范围0 - 100

onAudioDeviceCaptureVolumeChanged

当前音频采集设备音量变化回调

使用 enableAudioVolumeEvaluation（interval>0）开启，（interval==0）关闭

Parameters:
Name Type Description
volume Number required

音量值，取值范围0 - 100
muted Boolean required

当前采集音频设备是否被静音

onAudioDevicePlayoutVolumeChanged

当前音频播放设备音量变化回调

使用 enableAudioVolumeEvaluation（interval>0）开启，（interval==0）关闭

Parameters:
Name Type Description
volume Number required

音量值，取值范围0 - 100
muted Boolean required

当前音频播放设备是否被静音

onRecvCustomCmdMsg

收到自定义消息回调

当房间中的某个用户使用 sendCustomCmdMsg() 发送自定义消息时，房间中的其它用户可以通过 onRecvCustomCmdMsg 接口接收消息

Parameters:
Name Type Description
userId String required

用户标识
cmdId Number required

命令 ID
seq Number required

消息序号
msg String required

消息数据

onMissCustomCmdMsg

自定义消息丢失回调

实时音视频使用 UDP 通道，即使设置了可靠传输（reliable）也无法确保100%不丢失，只是丢消息概率极低，能满足常规可靠性要求。 在发送端设置了可靠传输（reliable）后，SDK 都会通过此回调通知过去时间段内（通常为5s）传输途中丢失的自定义消息数量统计信息。

注意：只有在发送端设置了可靠传输(reliable)，接收方才能收到消息的丢失回调

Parameters:
Name Type Description
userId String required

用户标识
cmdId Number required

命令 ID
errCode Number required

错误码
missed Number required

丢失的消息数量

onRecvSEIMsg

收到 SEI 消息的回调

当房间中的某个用户使用 sendSEIMsg() 发送数据时，房间中的其它用户可以通过 onRecvSEIMsg 接口接收数据。

Parameters:
Name Type Description
userId String required

用户标识
message String required

数据

onStartPublishing

开始向腾讯云的直播 CDN 推流的回调，对应于 TRTCCloud 中的 startPublishing() 接口

Deprecated:
  • Yes
Parameters:
Name Type Description
errCode Number required

0 表示成功，其余值表示失败
errMsg String required

具体错误原因

onStopPublishing

停止向腾讯云的直播 CDN 推流的回调，对应于 TRTCCloud 中的 stopPublishing() 接口

Deprecated:
  • Yes
Parameters:
Name Type Description
errCode Number required

0 表示成功，其余值表示失败
errMsg String required

具体错误原因

onStartPublishCDNStream

旁路推流到 CDN 的回调

对应于 TRTCCloud 的 startPublishCDNStream() 接口

注意：Start 回调如果成功，只能说明转推请求已经成功告知给腾讯云，如果目标 CDN 有异常，还是有可能会转推失败。

Deprecated:
  • Yes
Parameters:
Name Type Description
errCode Number required

错误码
errMsg String required

错误详细信息

onStopPublishCDNStream

停止旁路推流到 CDN 的回调

对应于 TRTCCloud 中的 stopPublishCDNStream() 接口

Deprecated:
  • Yes
Parameters:
Name Type Description
errCode Number required

错误码
errMsg String required

错误详细信息

onSetMixTranscodingConfig

设置云端的混流转码参数的回调

对应于 TRTCCloud 中的 setMixTranscodingConfig() 接口

Deprecated:
  • Yes
Parameters:
Name Type Description
errCode Number required

错误码
errMsg String required

错误详细信息

onStartPublishMediaStream

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

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

Parameters:
Name Type Description
taskId String required

当请求成功时，TRTC 后台会在回调中提供给您这项任务的 taskId，后续您可以通过该 taskId 结合 updatePublishMediaStream 和 stopPublishMediaStream 进行更新和停止。
code Number required

回调结果，0 表示成功，其余值表示失败。
message String required

具体回调信息。

onUpdatePublishMediaStream

更新媒体流的事件回调

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

Parameters:
Name Type Description
taskId String required

您调用媒体流发布接口 (updatePublishMediaStream) 时传入的 taskId，会通过此回调再带回给您，用于标识该回调属于哪一次更新请求。
code Number required

回调结果，0 表示成功，其余值表示失败。
message String required

具体回调信息。

onStopPublishMediaStream

停止媒体流的事件回调

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

Parameters:
Name Type Description
taskId String required

您调用停止发布媒体流 (stopPublishMediaStream) 时传入的 taskId，会通过此回调再带回给您，用于标识该回调属于哪一次停止请求。
code Number required

回调结果，0 表示成功，其余值表示失败。
message String required

具体回调信息。

onCdnStreamStateChanged

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

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

Parameters:
Name Type Description
cdnUrl String required

您调用 startPublishMediaStream 时通过目标推流配置 (TRTCPublishTarget) 传入的 url，在推流状态变更时，会通过此回调同步给您。
status Number required

推流状态。

  • 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。
code Number required

回调结果，0 表示成功，其余值表示失败。
msg String required

具体回调信息。

onAudioEffectFinished

废弃事件： 播放音效结束回调

Deprecated:
  • 从 TRTCSDK 8.0 后该接口已被废弃，不推荐使用
Parameters:
Name Type Description
effectId Number required

音效 ID
code Number required

0表示播放正常结束；其他表示异常结束

onScreenCaptureCovered

当屏幕分享窗口被遮挡无法正常捕获时，SDK 会通过此回调通知，可在此回调里通知用户移开遮挡窗口

onScreenCaptureStarted

当屏幕分享开始时，SDK 会通过此回调通知

onScreenCapturePaused

当屏幕分享暂停时，SDK 会通过此回调通知

Parameters:
Name Type Description
reason Number required

停止原因，0：表示用户主动暂停；1：注意此字段的含义在 MAC 和 Windows 平台有稍微差异。屏幕窗口不可见暂停（Mac）。表示设置屏幕分享参数导致的暂停（Windows）；2：表示屏幕分享窗口被最小化导致的暂停（仅 Windows）；3：表示屏幕分享窗口被隐藏导致的暂停（仅 Windows）

onScreenCaptureResumed

当屏幕分享恢复时，SDK 会通过此回调通知

Parameters:
Name Type Description
reason Number required

停止原因，0：表示用户主动恢复，1：表示屏幕分享参数设置完毕后自动恢复；2：表示屏幕分享窗口从最小化被恢复；3：表示屏幕分享窗口从隐藏被恢复

onScreenCaptureStopped

当屏幕分享停止时，SDK 会通过此回调通知

Parameters:
Name Type Description
reason Number required

停止原因，0：表示用户主动停止；1：表示屏幕分享窗口被关闭

onSnapshotComplete

截图完成时回调

Parameters:
Name Type Description
userId String required

用户 ID，空字符串表示截取本地画面
type TRTCVideoStreamType required

视频流类型
data String required

截图数据, base64 string
width Number required

截图画面的宽度
height Number required

截图画面的高度

onLocalRecordBegin

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

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

Parameters:
Name Type Description
errCode number required

错误码 0：初始化录制成功；-1：初始化录制失败；-2: 文件后缀名有误。
storagePath string required

录制文件存储路径

onLocalRecording

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

当您调用 startLocalRecording 成功启动本地媒体录制任务后，SDK 变会定时地抛出本事件回调。 您可通过捕获该事件回调来获知录制任务的健康状况。 您可以在 startLocalRecording 时设定本事件回调的抛出间隔。

Parameters:
Name Type Description
duration number required

已经录制的累计时长，单位毫秒。
storagePath string required

录制文件存储路径

onLocalRecordComplete

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

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

Parameters:
Name Type Description
errCode number required

错误码

  • 0：录制成功；
  • -1：录制失败；
  • -2：切换分辨率或横竖屏导致录制结束；
  • -3：录制时间太短，或未采集到任何视频或音频数据，请检查录制时长，或是否已开启音、视频采集。
storagePath string required

录制文件存储路径

onSystemAudioLoopbackError

系统音频采集回调，SDK在采集失败时会抛出该事件回调，用于通知错误信息

Parameters:
Name Type Description
errCode Number required

错误码含义

  • ERR_AUDIO_PLUGIN_START_FAIL(-1330) ：开启系统声音录制失败，例如音频驱动插件不可用
  • ERR_AUDIO_PLUGIN_INSTALL_NOT_AUTHORIZED (-1331) ：未授权安装音频驱动插件
  • ERR_AUDIO_PLUGIN_INSTALL_FAILED (-1332) ：安装音频驱动插件失败