TRTCCallback

TRTCCallback

设置 TRTCCloud 回调

Example

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

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

Events

onError

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

Parameters:
Name Type Description
errCode Number

错误码

errMsg String

错误信息

onWarning

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

Parameters:
Name Type Description
warningCode Number

警告码

warningMsg String

警告信息

onEnterRoom

2.1 已加入房间的回调

调用 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

result > 0 时为进房耗时(ms),result < 0 时为进房错误码。

onExitRoom

2.2 退出房间的事件回调

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

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

Parameters:
Name Type Description
reason Number

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

onSwitchRoom

2.3 切换房间的事件回调

Parameters:
Name Type Description
errCode Number

错误码,ERR_NULL 代表切换成功,其他请参见错误码

errMsg String

错误信息。

onSwitchRole

2.4 切换角色的事件回调

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

Parameters:
Name Type Description
errCode Number

错误码,ERR_NULL 代表切换成功,其他请参见错误码

errMsg String

错误信息。

onConnectOtherRoom

2.5 请求跨房连麦(主播跨房 PK)的结果回调

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

Parameters:
Name Type Description
userId String

要 PK 的目标主播 userId。

errCode Number

错误码,ERR_NULL 代表切换成功,其他请参见错误码

errMsg String

错误信息。

onDisconnectOtherRoom

2.6 关闭跨房连麦(主播跨房 PK)的结果回调

Parameters:
Name Type Description
errCode Number

错误码,ERR_NULL 代表切换成功,其他请参见 错误码

errMsg String

错误信息。

onRemoteUserEnterRoom

3.1 有用户加入当前房间

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

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

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

Parameters:
Name Type Description
userId String

用户标识

onRemoteUserLeaveRoom

3.2 有用户离开当前房间

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

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

用户标识

reason Number

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

onUserVideoAvailable

3.3 用户是否开启摄像头视频

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

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

Parameters:
Name Type Description
userId String

用户标识

available Number

画面是否开启

onUserSubStreamAvailable

3.4 用户是否开启了辅路画面(TRTCVideoStreamTypeSub,一般用于屏幕分享)

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

Parameters:
Name Type Description
userId String

用户标识

available Number

辅路画面是否开启

onUserAudioAvailable

3.5 用户是否开启音频上行

Parameters:
Name Type Description
userId String

用户标识

available Number

声音是否开启

onFirstVideoFrame

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

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

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

Parameters:
Name Type Description
userId String

本地或远程用户 ID,如果 userId == '' 代表本地,userId != '' 代表远程。

streamType Number

视频流类型,TRTCVideoStreamTypeBig:主路画面,一般用于摄像头;TRTCVideoStreamTypeSub:辅路画面,一般用于屏幕分享。

width Number

画面宽度

height Number

画面高度

onFirstAudioFrame

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

Parameters:
Name Type Description
userId String

远程用户 ID。

onSendFirstLocalVideoFrame

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

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

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

onSendFirstLocalAudioFrame

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

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

onUserEnter

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

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

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

用户标识

onUserExit

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

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

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

用户标识

reason Number

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

onNetworkQuality

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

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

Parameters:
Name Type Description
localQuality TRTCQualityInfo

上行网络质量

remoteQuality Array.<TRTCQualityInfo>

下行网络质量

onStatistics

4.2 技术指标统计回调

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

注意:每2秒回调一次

Parameters:
Name Type Description
statis TRTCStatistics

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

onConnectionLost

5.1 SDK 跟服务器的连接断开

onTryToReconnect

5.2 SDK 尝试重新连接到服务器

onConnectionRecovery

5.3 SDK 跟服务器的连接恢复

onSpeedTest

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

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

当前完成的测速结果

finishedCount Number

已完成测速的服务器数量

totalCount Number

需要测速的服务器总数量

onSpeedTestResult

5.5 网速测试的结果回调

该统计回调由 startSpeedTest 触发。

Parameters:
Name Type Description
result TRTCSpeedTestResult

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

onCameraDidReady

6.1 摄像头准备就绪

onMicDidReady

6.2 麦克风准备就绪

onUserVoiceVolume

6.3 userId 对应的成员语音音量

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

Parameters:
Name Type Description
userVolumes TRTCVolumeInfo

每位发言者的语音音量,取值范围0 - 100

userVolumesCount Number

发言者的人数,即 userVolumes 数组的大小

totalVolume Number

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

onDeviceChange

6.4 本地设备通断回调

Parameters:
Name Type Description
deviceId String

Windows 端返回设备名,Mac 端返回设备 ID

type TRTCDeviceType

设备类型

state TRTCDeviceState

事件类型

onTestMicVolume

6.5 麦克风测试音量回调

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

Parameters:
Name Type Description
volume Number

音量值,取值范围0 - 100

onTestSpeakerVolume

6.6 扬声器测试音量回调

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

Parameters:
Name Type Description
volume Number

音量值,取值范围0 - 100

onAudioDeviceCaptureVolumeChanged

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

使用 enableAudioVolumeEvaluation(interval>0)开启,(interval==0)关闭

Parameters:
Name Type Description
volume Number

音量值,取值范围0 - 100

muted Boolean

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

onAudioDevicePlayoutVolumeChanged

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

使用 enableAudioVolumeEvaluation(interval>0)开启,(interval==0)关闭

Parameters:
Name Type Description
volume Number

音量值,取值范围0 - 100

muted Boolean

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

onRecvCustomCmdMsg

7.1 收到自定义消息回调

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

Parameters:
Name Type Description
userId String

用户标识

cmdId Number

命令 ID

seq Number

消息序号

msg String

消息数据

onMissCustomCmdMsg

7.2 自定义消息丢失回调

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

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

Parameters:
Name Type Description
userId String

用户标识

cmdId Number

命令 ID

errCode Number

错误码

missed Number

丢失的消息数量

onRecvSEIMsg

7.3 收到 SEI 消息的回调

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

Parameters:
Name Type Description
userId String

用户标识

message String

数据

onStartPublishCDNStream

8.3 旁路推流到 CDN 的回调

对应于 TRTCCloud 的 startPublishCDNStream() 接口

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

Parameters:
Name Type Description
errCode Number

错误码

errMsg String

错误详细信息

onStopPublishCDNStream

8.4 停止旁路推流到 CDN 的回调

对应于 TRTCCloud 中的 stopPublishCDNStream() 接口

Parameters:
Name Type Description
errCode Number

错误码

errMsg String

错误详细信息

onSetMixTranscodingConfig

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

对应于 TRTCCloud 中的 setMixTranscodingConfig() 接口

Parameters:
Name Type Description
errCode Number

错误码

errMsg String

错误详细信息

onAudioEffectFinished

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

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

音效 ID

code Number

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

onScreenCaptureCovered

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

onScreenCaptureStarted

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

onScreenCapturePaused

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

Parameters:
Name Type Description
reason Number

停止原因,0:表示用户主动暂停;1:表示设置屏幕分享参数导致的暂停;2:表示屏幕分享窗口被最小化导致的暂停;3:表示屏幕分享窗口被隐藏导致的暂停

onScreenCaptureResumed

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

Parameters:
Name Type Description
reason Number

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

onScreenCaptureStopped

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

Parameters:
Name Type Description
reason Number

停止原因,0:表示用户主动停止;1:表示屏幕分享窗口被关闭

onSnapshotComplete

11.1 截图完成时回调

Parameters:
Name Type Description
userId String

用户 ID,空字符串表示截取本地画面

type TRTCVideoStreamType

视频流类型

data String

截图数据, base64 string

width Number

截图画面的宽度

height Number

截图画面的高度

onPlayBGMBegin

12.1 废弃事件: 开始播放背景音乐

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

错误码

onPlayBGMProgress

12.2 废弃事件: 播放背景音乐的进度

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

已播放时间

durationMS Number

总时间

onPlayBGMComplete

12.3 废弃事件: 播放背景音乐结束

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

错误码

onLocalRecordBegin

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

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

Parameters:
Name Type Description
errCode number

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

storagePath string

录制文件存储路径

onLocalRecording

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

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

Parameters:
Name Type Description
duration number

已经录制的累计时长,单位毫秒。

storagePath string

录制文件存储路径

onLocalRecordComplete

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

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

Parameters:
Name Type Description
errCode number

错误码 0:录制成功;-1:录制失败;-2:切换分辨率或横竖屏导致录制结束。

storagePath string

录制文件存储路径

onSystemAudioLoopbackError

13.1 系统音频采集回调

Parameters:
Name Type Description
errCode Number

错误码含义

  • 0 :代表启动成功;
  • ERR_AUDIO_PLUGIN_START_FAIL(-1330) :开启系统声音录制失败,例如音频驱动插件不可用
  • ERR_AUDIO_PLUGIN_INSTALL_NOT_AUTHORIZED (-1331) :未授权安装音频驱动插件
  • ERR_AUDIO_PLUGIN_INSTALL_FAILED (-1332) :安装音频驱动插件失败