帮你快速理解、总结文档立即下载
文档中心>实时音视频>TRTC SDK>客户端 API> Flutter>TRTCCloudListener

TRTCCloudListener

最近更新时间：2026-10-30 14:35:01
我的收藏

本页目录：

Copyright (c) 2026 Tencent. All rights reserved.

Module: TRTCCloudListener @ TXLiteAVSDK
Function: 腾讯云 TRTC 的事件回调接口
Version: 13.5

腾讯云 TRTC 事件回调接口，Flutter SDK：tencent_rtc_sdk。创建 TRTCCloudListener 对象并通过 TRTCCloud 的 ​registerListener 注册后，即可接收 SDK 抛出的各类事件。

回调列表

错误与警告事件

回调
描述
onError
错误事件回调。
onWarning
警告事件回调。

房间事件

回调
描述
进入房间成功与否的事件回调。
离开房间的事件回调。
切换角色的事件回调。
切换房间的结果回调。
请求跨房通话的结果回调。
结束跨房通话的结果回调。

用户与音视频流事件

回调
描述
有用户加入当前房间。
有用户离开当前房间。
某远端用户发布/取消了主路视频画面。
某远端用户发布/取消了辅路视频画面。
某远端用户发布/取消了自己的音频。
SDK 开始渲染自己本地或远端用户的首帧画面。
SDK 开始播放远端用户的首帧音频。
自己本地的首个视频帧已被发布出去。
自己本地的首个音频帧已被发布出去。
远端视频状态变化的事件回调。
远端音频状态变化的事件回调。
远端视频分辨率变化的事件回调。

网络与技术指标统计

回调
描述
网络质量的实时统计回调。
音视频技术指标的实时统计回调。
网速测试的结果回调。

与云端连接情况

回调
描述
SDK 与云端的连接已经断开。
SDK 正在尝试重新连接到云端。
SDK 与云端的连接已经恢复。

硬件设备事件

回调
描述
摄像头准备就绪。
麦克风准备就绪。
当前音频路由发生变化。
音量大小的反馈回调。
当前麦克风的系统采集音量发生变化（桌面系统）。
当前系统的播放音量发生变化（桌面系统）。
系统声音采集是否被成功开启的事件回调（仅桌面系统）。
测试麦克风时的音量回调。
测试扬声器时的音量回调。

自定义消息的接收事件

回调
描述
收到自定义消息的事件回调。
自定义消息丢失的事件回调。
收到 SEI 消息的回调。

CDN 相关事件

回调
描述
开始发布媒体流的事件回调。
更新媒体流的事件回调。
停止媒体流的事件回调。
RTMP/RTMPS 推流状态发生改变回调。

屏幕分享相关事件

回调
描述
屏幕分享开启的事件回调。
屏幕分享暂停的事件回调。
屏幕分享恢复的事件回调。
屏幕分享停止的事件回调。
屏幕分享的目标窗口被遮挡的事件回调（仅 Windows）。

本地录制与本地截图事件

回调
描述
本地录制任务已经开始的事件回调。
本地录制任务正在进行中的进展事件回调。
录制分片结束的事件回调。
本地录制任务已经结束的事件回调。
本地截图完成的事件回调。

回调详情

以下按回调列表顺序逐一说明各回调的签名、触发时机、参数及注意事项。

onError

final void Function(int errCode, String errMsg)? onError
错误事件回调。
错误事件，表示 SDK 抛出的不可恢复的错误，比如进入房间失败或设备开启失败等。
更多信息请参见 错误码表。
参数
类型
描述
errCode
int
错误码。
errMsg
String
错误信息。

onWarning

final void Function(int warningCode, String warningMsg)? onWarning
警告事件回调。
警告事件，表示 SDK 抛出的需要关注的问题，比如视频出现卡顿或 CPU 使用率太高等。
更多信息请参见 错误码表。
参数
类型
描述
warningCode
int
警告码。
warningMsg
String
警告信息。

onEnterRoom

final void Function(int result)? onEnterRoom
进入房间成功与否的事件回调。
调用 TRTCCloud 中的 ​enterRoom 接口执行进房操作后，会收到来自 SDK 的 onEnterRoom(result) 回调：
如果加入成功，result 会是一个正数（result > 0），代表进入房间所消耗的时间，单位是毫秒（ms）。
如果加入失败，result 会是一个负数（result < 0），代表进房失败的错误码。
进房失败的错误码含义请参见 错误码表。
参数
类型
描述
result
int
result > 0 时为进房耗时，单位：毫秒；
result < 0 时为进房错误码。
说明：
1. 在 TRTC 6.6 之前的版本中，只有进房成功会抛出 onEnterRoom(result) 回调，进房失败由 onError() 回调抛出。
2. 从 TRTC 6.6 版本开始，无论进房成功或失败均会抛出 onEnterRoom(result) 回调，同时进房失败也会有 onError() 回调抛出。

onExitRoom

final void Function(int reason)? onExitRoom
离开房间的事件回调。
调用 TRTCCloud 中的 ​exitRoom 接口会执行退出房间的相关逻辑，例如释放音视频设备资源和编解码器资源等。待 SDK 占用的所有资源释放完毕后，SDK 会抛出 onExitRoom() 回调通知到您。
如果您要再次调用 enterRoom() 或者切换到其他的音视频 SDK，请等待 onExitRoom() 回调到来后再执行相关操作。否则可能会遇到例如摄像头、麦克风设备被占用等问题。
参数
类型
描述
reason
int
离开房间原因。
0：主动调用 exitRoom 退出房间；
1：被服务器踢出当前房间；
2：当前房间整个被解散。

onSwitchRole

final void Function(int errCode, String errMsg)? onSwitchRole
切换角色的事件回调。
调用 TRTCCloud 中的 ​switchRole 接口会切换主播和观众的角色，该操作会伴随一个线路切换的过程。待 SDK 切换完成后，会抛出 onSwitchRole() 事件回调。
参数
类型
描述
errCode
int
错误码，ERR_NULL 代表切换成功，其他请参见 错误码表。
errMsg
String
错误信息。

onSwitchRoom

final void Function(int errCode, String errMsg)? onSwitchRoom
切换房间的结果回调。
调用 TRTCCloud 中的 ​switchRoom 接口可以让用户从一个房间切换到另一个房间，待 SDK 切换完成后，会抛出 onSwitchRoom() 事件回调。
参数
类型
描述
errCode
int
错误码，ERR_NULL 代表切换成功，其他请参见 错误码表。
errMsg
String
错误信息。

onConnectOtherRoom

final void Function(String userId, int errCode, String errMsg)? onConnectOtherRoom
请求跨房通话的结果回调。
调用 TRTCCloud 中的 ​connectOtherRoom 接口会将两个不同房间中的主播拉通视频通话，也就是所谓的“主播 PK”功能。调用者会收到 onConnectOtherRoom() 回调来获知跨房通话是否成功。
如果成功，两个房间中的所有用户都会收到来自另一个房间中的 PK 主播的 onUserVideoAvailable() 回调。
参数
类型
描述
userId
String
要跨房通话的另一个房间中的主播的用户 ID。
errCode
int
错误码，ERR_NULL 代表跨房连接成功，其他请参见 错误码表。
errMsg
String
错误信息。

onDisconnectOtherRoom

final void Function(int errCode, String errMsg)? onDisconnectOtherRoom
结束跨房通话的结果回调。
参数
类型
描述
errCode
int
错误码，详见 错误码表。
errMsg
String
错误信息。

onRemoteUserEnterRoom

final void Function(String userId)? onRemoteUserEnterRoom
有用户加入当前房间。
出于性能方面的考虑，在不同的应用场景（即 AppScene，在 enterRoom 时通过第二个参数指定）下，该回调的行为会有差别：
直播类场景（TRTCAppScene.live 或 TRTCAppScene.voiceChatRoom）：该场景下的用户区分主播和观众两种角色，只有主播进入房间时才会触发该通知。
通话类场景（TRTCAppScene.videoCall 或 TRTCAppScene.audioCall）：该场景下的用户没有角色的区分（可认为都是主播），任何用户进入房间都会触发该通知。
参数
类型
描述
userId
String
远端用户的用户 ID。
说明：
1. 事件回调 onRemoteUserEnterRoom 只代表有用户进入了房间，并不代表该用户已经开启了音频或视频。
2. 如果您想了解某个用户是否开启了视频，建议使用 ​onUserVideoAvailable 回调。

onRemoteUserLeaveRoom

final void Function(String userId, int reason)? onRemoteUserLeaveRoom
有用户离开当前房间。
与 onRemoteUserEnterRoom 相对应，在不同的应用场景（即 ​TRTCAppScene，在 enterRoom 时通过第二个参数指定）下，该回调的行为会有差别：
直播类场景（TRTCAppScene.live 或 TRTCAppScene.voiceChatRoom）：只有主播离开房间时才会触发该通知。
通话类场景（TRTCAppScene.videoCall 或 TRTCAppScene.audioCall）：该场景下的用户没有角色的区分，任何用户离开房间都会触发该通知。
参数
类型
描述
userId
String
远端用户的用户 ID。
reason
int
离开原因。
0：用户主动退出房间；
1：用户超时退出；
2：用户被踢出房间；
3：主播因切换到观众退出房间。

onUserVideoAvailable

final void Function(String userId, bool available)? onUserVideoAvailable
某远端用户发布/取消了主路视频画面。
“主路画面”一般被用于承载摄像头画面。当您收到 onUserVideoAvailable(userId, true) 通知时，表示该用户有可播放的主路画面。此时，您可以调用 ​startRemoteView 接口订阅该用户的远程画面，订阅成功后，您会继续收到该用户的首帧画面渲染回调 onFirstVideoFrame(userId)。
当您收到 onUserVideoAvailable(userId, false) 通知时，表示该路远程画面已经被关闭，关闭的原因可能是该用户调用了 ​muteLocalVideo 或 ​stopLocalPreview。
参数
类型
描述
userId
String
远端用户的用户 ID。
available
bool
该用户是否发布（或取消发布）了主路视频画面。
true：发布；
false：取消发布。

onUserSubStreamAvailable

final void Function(String userId, bool available)? onUserSubStreamAvailable
某远端用户发布/取消了辅路视频画面。
“辅路画面”一般被用于承载屏幕分享的画面。当您收到 onUserSubStreamAvailable(userId, true) 通知时，表示该用户有可播放的辅路画面。此时，您可以调用 ​startRemoteView 接口订阅该用户的远程画面，订阅成功后，您会继续收到该用户的首帧画面渲染回调 onFirstVideoFrame(userId)。
参数
类型
描述
userId
String
远端用户的用户 ID。
available
bool
该用户是否发布（或取消发布）了辅路视频画面。
true：发布；
false：取消发布。
说明：
显示辅路画面使用的接口是 ​startRemoteView（streamType 传 TRTCVideoStreamType.sub）。

onUserAudioAvailable

final void Function(String userId, bool available)? onUserAudioAvailable
某远端用户发布/取消了自己的音频。
当您收到 onUserAudioAvailable(userId, true) 通知时，表示该用户发布了自己的声音：
在自动订阅模式下，SDK 会自动播放该用户的声音。
在手动订阅模式下，您可以调用 ​muteRemoteAudio(userId, false) 来播放该用户的声音。
参数
类型
描述
userId
String
远端用户的用户 ID。
available
bool
该用户是否发布（或取消发布）了自己的音频。
true：发布；
false：取消发布。
说明：
SDK 默认使用自动订阅模式，您可以通过调用 ​setDefaultStreamRecvMode 切换为手动订阅，但需要在进房之前调用才能生效。

onFirstVideoFrame

final void Function(String userId, TRTCVideoStreamType streamType, int width, int height)? onFirstVideoFrame
SDK 开始渲染自己本地或远端用户的首帧画面。
SDK 会在渲染自己本地或远端用户的首帧画面时抛出该事件，您可以通过回调中的 userId 参数来判断事件来自于“本地”还是来自于“远端”：
如果 userId 为空值，代表 SDK 已经开始渲染自己本地的视频画面，前提是您已经调用了 ​startLocalPreview 或 ​startScreenCapture。
如果 userId 不为空，代表 SDK 已经开始渲染远端用户的视频画面，前提是您已经调用了 ​startRemoteView 订阅了该用户的视频画面。
参数
类型
描述
userId
String
本地或远端的用户 ID。为空值代表自己本地的首帧画面已到来；不为空代表远端用户的首帧画面已到来。
streamType
视频流类型：主路一般用于承载摄像头画面，辅路一般用于承载屏幕分享画面。
width
int
画面的宽度。
height
int
画面的高度。
说明：
1. 只有当您调用了 ​startLocalPreview 或 ​startScreenCapture 之后，才会触发自己本地的首帧画面事件回调。
2. 只有当您调用了 ​startRemoteView 之后，才会触发远端用户的首帧画面事件回调。

onFirstAudioFrame

final void Function(String userId)? onFirstAudioFrame
SDK 开始播放远端用户的首帧音频。
SDK 会在播放远端用户的首帧音频时抛出该事件，本地音频的首帧事件不会抛出。
参数
类型
描述
userId
String
远端用户的用户 ID。

onSendFirstLocalVideoFrame

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

onSendFirstLocalAudioFrame

final void Function()? onSendFirstLocalAudioFrame
自己本地的首个音频帧已被发布出去。
当您成功进入房间并通过 ​startLocalAudio 开启本地音频采集之后（开启采集和进入房间的先后顺序无影响），SDK 就会开始进行音频编码，并通过自身的网络模块向云端发布自己本地的音频数据。
当 SDK 成功地向云端送出自己的第一帧音频数据帧以后，就会抛出 onSendFirstLocalAudioFrame 事件回调。

onRemoteVideoStatusUpdated

final void Function(String userId, TRTCVideoStreamType streamType, TRTCAVStatusType status, TRTCAVStatusChangeReason reason)? onRemoteVideoStatusUpdated
远端视频状态变化的事件回调。
您可以通过此回调获取每一个远端用户的视频状态（包括 Playing、Loading 和 Stopped 三种状态），从而进行相应的 UI 展示。
参数
类型
描述
userId
String
用户 ID。
streamType
视频流类型：主路一般用于承载摄像头画面，辅路一般用于承载屏幕分享画面。
status
视频状态，详见 ​TRTCAVStatusType。
reason
视频状态改变的原因，详见 ​TRTCAVStatusChangeReason。

onRemoteAudioStatusUpdated

final void Function(String userId, TRTCAVStatusType status, TRTCAVStatusChangeReason reason)? onRemoteAudioStatusUpdated
远端音频状态变化的事件回调。
您可以通过此回调获取每一个远端用户的音频状态（包括 Playing、Loading 和 Stopped 三种状态），从而进行相应的 UI 展示。
参数
类型
描述
userId
String
用户 ID。
status
音频状态，详见 ​TRTCAVStatusType。
reason
音频状态改变的原因，详见 ​TRTCAVStatusChangeReason。

onUserVideoSizeChanged

final void Function(String userId, TRTCVideoStreamType streamType, int newWidth, int newHeight)? onUserVideoSizeChanged
远端视频分辨率变化的事件回调。
当您收到 onUserVideoSizeChanged(userId, streamType, newWidth, newHeight) 回调时，表示该路画面的分辨率发生了变化，可能是由远端用户调用 ​setVideoEncoderParam 或者 ​setSubStreamEncoderParam 引起的。
参数
类型
描述
userId
String
用户 ID。
streamType
视频流类型：主路一般用于承载摄像头画面，辅路一般用于承载屏幕分享画面。
newWidth
int
视频流的宽度。
newHeight
int
视频流的高度。

onNetworkQuality

final void Function(TRTCQualityInfo localQuality, List<TRTCQualityInfo> remoteQuality)? onNetworkQuality
网络质量的实时统计回调。
该统计回调每间隔 2 秒抛出一次，用于通知 SDK 感知到的当前网络的上行和下行质量。SDK 会使用一组内嵌的自研算法对当前网络的延迟高低、带宽大小以及稳定情况进行评估，并计算出一个评估结果：
如果评估结果为 1（Excellent）代表当前的网络情况非常好；如果评估结果为 6（Down）代表当前网络无法支撑 TRTC 的正常通话。取值详见 ​TRTCQuality。
参数
类型
描述
localQuality
上行网络质量。
remoteQuality
List<TRTCQualityInfo>
下行网络质量，指数据流经过“远端 > 云端 > 本地”这样一条完整的传输链路后，最终在本地统计到的数据质量。因此这里的下行网络质量代表的是远端上行链路与本地下行链路共同影响的结果。
说明：
该接口无法单独判断远端用户的上行质量。

onStatistics

final void Function(TRTCStatistics statistics)? onStatistics
音视频技术指标的实时统计回调。
该统计回调每间隔 2 秒抛出一次，用于通知 SDK 内部音频、视频以及网络相关的专业技术指标，这些信息在 ​TRTCStatistics 中均有罗列：
视频统计信息：视频的分辨率（resolution）、帧率（FPS）和比特率（bitrate）等信息。
音频统计信息：音频的采样率（samplerate）、声道（channel）和比特率（bitrate）等信息。
网络统计信息：SDK 和云端一次往返（SDK > Cloud > SDK）的网络耗时（rtt）、丢包率（loss）、上行流量（sentBytes）和下行流量（receivedBytes）等信息。
参数
类型
描述
statistics
统计数据，包括自己本地的统计信息和远端用户的统计信息。
说明：
如果您只需要获知当前网络质量的好坏，并不需要花太多时间研究本统计回调，更推荐您使用 ​onNetworkQuality。

onSpeedTestResult

final void Function(TRTCSpeedTestResult result)? onSpeedTestResult
网速测试的结果回调。
该回调由 ​startSpeedTest 触发。
参数
类型
描述
result
网速测试数据，包括丢包率、往返延迟、上下行的带宽速率。

onConnectionLost

final void Function()? onConnectionLost
SDK 与云端的连接已经断开。

onTryToReconnect

final void Function()? onTryToReconnect
SDK 正在尝试重新连接到云端。

onConnectionRecovery

final void Function()? onConnectionRecovery
SDK 与云端的连接已经恢复。

onCameraDidReady

final void Function()? onCameraDidReady
摄像头准备就绪。

onMicDidReady

final void Function()? onMicDidReady
麦克风准备就绪。

onAudioRouteChanged

final void Function(TXAudioRoute newRoute, TXAudioRoute oldRoute)? onAudioRouteChanged
当前音频路由发生变化。
参数
类型
描述
newRoute
变化后的音频路由，详见 ​TXAudioRoute。
oldRoute
变化前的音频路由，详见 ​TXAudioRoute。

onUserVoiceVolume

final void Function(List<TRTCVolumeInfo> userVolumes, int totalVolume)? onUserVoiceVolume
音量大小的反馈回调。
SDK 可以评估每一路音频的音量大小，并定时抛出该回调，您可以根据回调结果在 UI 上展示例如声波或音量条等效果。
您需要先调用 ​enableAudioVolumeEvaluation 开启该功能并设置回调间隔。
需要注意的是，无论房间中是否有人说话，SDK 都会按照您设定的时间间隔定时抛出此回调。
参数
类型
描述
userVolumes
List<TRTCVolumeInfo>
房间中所有正在说话的用户的音量大小。
totalVolume
int
所有远端用户的总音量大小，取值范围：0 - 100。
说明：
userVolumes 为一个数组，对于数组中的每一个元素，当 userId 为空时表示本地用户的音量，不为空时表示远端用户的音量。

onAudioDeviceCaptureVolumeChanged

final void Function(int volume, bool muted)? onAudioDeviceCaptureVolumeChanged
当前麦克风的系统采集音量发生变化（桌面系统）。
在 macOS 和 Windows 这类桌面操作系统上，用户可以在音量控制面板上设置麦克风的采集音量大小，用户设置得越大，麦克风采集到的声音原始音量也会越大。在有些型号的键盘以及笔记本电脑上，用户还可以通过按下“禁用麦克风”按钮（图标是一个话筒上叠加了一道斜线）来将麦克风静音。
当用户通过系统界面或者快捷键调整麦克风的采集音量时，SDK 便会抛出此事件。
参数
类型
描述
volume
int
系统采集音量，即用户可以在音量控制面板上设置的音量大小，取值范围：0 - 100。
muted
bool
麦克风是否被用户禁用。
true：被禁用；
false：被启用。
说明：
您需要调用 ​enableAudioVolumeEvaluation 并设定（interval > 0）开启此事件回调，设定（interval = 0）关闭此事件回调。

onAudioDevicePlayoutVolumeChanged

final void Function(int volume, bool muted)? onAudioDevicePlayoutVolumeChanged
当前系统的播放音量发生变化（桌面系统）。
在 macOS 和 Windows 这类桌面操作系统上，用户可以在音量控制面板上设置系统的播放音量大小。在有些型号的键盘以及笔记本电脑上，用户还可以通过按下“静音”按钮（图标是一个喇叭上叠加了一道斜线）来将扬声器静音。
当用户通过系统界面或者快捷键调整系统的播放音量时，SDK 便会抛出此事件。
参数
类型
描述
volume
int
系统播放音量，即用户可以在音量控制面板上设置的音量大小，取值范围：0 - 100。
muted
bool
扬声器是否被用户禁用。
true：被禁用；
false：被启用。
说明：
您需要调用 ​enableAudioVolumeEvaluation 并设定（interval > 0）开启此事件回调，设定（interval = 0）关闭此事件回调。

onSystemAudioLoopbackError

final void Function(int errCode)? onSystemAudioLoopbackError
系统声音采集是否被成功开启的事件回调（仅桌面系统）。
在 macOS 上，您可以通过调用 ​startSystemAudioLoopback 安装一个音频驱动，并让 SDK 捕获当前系统播放出的声音。
在 Windows 系统上，您可以通过调用 ​startSystemAudioLoopback 让 SDK 捕获当前系统播放出的声音。
在视频教学和音乐直播等应用场景中，老师可以使用此功能让 SDK 采集其电脑上播放的视频中的声音，从而让房间中的学生也能听到。
SDK 会将本次尝试开启系统声音采集的结果通过本回调抛出，您需要关注参数中的错误码信息。
参数
类型
描述
errCode
int
如果为 ERR_NULL 表示开启系统声音采集成功，否则表示开启失败。

onTestMicVolume

final void Function(int volume)? onTestMicVolume
测试麦克风时的音量回调。
当您调用 ​startMicDeviceTest 测试麦克风是否正常工作时，SDK 会不断地抛出此回调，参数中的 volume 代表当前麦克风采集到的音量大小。
如果在测试期间 volume 出现了大小波动的情况，说明麦克风状态健康；如果 volume 的数值始终是 0，说明麦克风的状态异常，需要提示用户进行更换。
参数
类型
描述
volume
int
麦克风采集到的音量值，取值范围：0 - 100。

onTestSpeakerVolume

final void Function(int volume)? onTestSpeakerVolume
测试扬声器时的音量回调。
当您调用 ​startSpeakerDeviceTest 测试扬声器是否正常工作时，SDK 会不断地抛出此回调。
参数中的 volume 代表的是 SDK 提交给系统扬声器去播放的声音的音量值大小。如果该数值持续变化，但用户反馈听不到声音，则说明扬声器状态异常。
参数
类型
描述
volume
int
SDK 提交给扬声器去播放的声音的音量，取值范围：0 - 100。

onRecvCustomCmdMsg

final void Function(String userId, int cmdId, int seq, String message)? onRecvCustomCmdMsg
收到自定义消息的事件回调。
当房间中的某个用户使用 ​sendCustomCmdMsg 发送自定义消息时，房间中的其它用户可以通过 onRecvCustomCmdMsg 事件回调接收到该条消息。
参数
类型
描述
userId
String
用户 ID。
cmdId
int
命令 ID。
seq
int
消息序号。
message
String
消息数据。

onMissCustomCmdMsg

final void Function(String userId, int cmdId, int errCode, int missed)? onMissCustomCmdMsg
自定义消息丢失的事件回调。
当您使用 ​sendCustomCmdMsg 发送自定义 UDP 消息时，即使设置了可靠传输（reliable 为 true），也无法确保 100% 不丢失，只是消息丢失的概率会很低，能满足大部分场景的可靠性要求。
在发送端设置了可靠传输（reliable 为 true）后，SDK 会通过此回调通知接收方过去一段时间内（通常为 5s）传输途中丢失的自定义消息数量。
参数
类型
描述
userId
String
用户 ID。
cmdId
int
命令 ID。
errCode
int
错误码。
missed
int
丢失的消息数量。
说明：
只有在发送端设置了可靠传输（reliable 为 true），接收方才能收到消息的丢失回调。

onRecvSEIMsg

final void Function(String userId, String message)? onRecvSEIMsg
收到 SEI 消息的回调。
当房间中的某个用户使用 ​sendSEIMsg 借助视频数据帧发送 SEI 消息时，房间中的其它用户可以通过 onRecvSEIMsg 事件回调接收到该条消息。
参数
类型
描述
userId
String
用户 ID。
message
String
数据。

onStartPublishMediaStream

final void Function(String taskId, int errCode, String errMsg, String extraInfo)? onStartPublishMediaStream
开始发布媒体流的事件回调。
当您调用 ​startPublishMediaStream 开始向 TRTC 后台服务发布媒体流时，SDK 会立刻将这一指令同步给云端服务器，随后 SDK 会收到来自云端服务器的处理结果，并将指令的执行结果通过本事件回调通知给您。
参数
类型
描述
taskId
String
当请求成功时，TRTC 后台会在回调中给您返回这次任务的 taskId，后续您可以通过该 taskId 结合 ​updatePublishMediaStream 和 ​stopPublishMediaStream 进行更新和停止。
errCode
int
回调结果，0 表示成功，其余值表示失败。
errMsg
String
具体回调信息。
extraInfo
String
额外信息。对于部分错误码，可能会有额外的信息帮助您排查问题。

onUpdatePublishMediaStream

final void Function(String taskId, int errCode, String errMsg, String extraInfo)? onUpdatePublishMediaStream
更新媒体流的事件回调。
当您调用 ​updatePublishMediaStream 修改发布参数时，SDK 会立刻将这一指令同步给云端服务器，随后 SDK 会收到来自云端服务器的处理结果，并将指令的执行结果通过本事件回调通知给您。
参数
类型
描述
taskId
String
您调用 updatePublishMediaStream 时传入的 taskId，用于标识该回调属于哪一次请求。
errCode
int
回调结果，0 表示成功，其余值表示失败。
errMsg
String
具体回调信息。
extraInfo
String
额外信息。对于部分错误码，可能会有额外的信息帮助您排查问题。

onStopPublishMediaStream

final void Function(String taskId, int errCode, String errMsg, String extraInfo)? onStopPublishMediaStream
停止媒体流的事件回调。
当您调用 ​stopPublishMediaStream 停止发布媒体流时，SDK 会立刻将这一指令同步给云端服务器，随后 SDK 会收到来自云端服务器的处理结果，并将指令的执行结果通过本事件回调通知给您。
参数
类型
描述
taskId
String
您调用 stopPublishMediaStream 时传入的 taskId，用于标识该回调属于哪一次请求。
errCode
int
回调结果，0 表示成功，其余值表示失败。
errMsg
String
具体回调信息。
extraInfo
String
额外信息。对于部分错误码，可能会有额外的信息帮助您排查问题。

onCdnStreamStateChanged

final void Function(String cdnUrl, int status, int errCode, String errMsg, String extraInfo)? onCdnStreamStateChanged
RTMP/RTMPS 推流状态发生改变回调。
当您调用 ​startPublishMediaStream 开始向 TRTC 后台服务发布媒体流时，SDK 会立刻将这一指令同步给云端服务器。
若您在目标推流配置（​TRTCPublishTarget）中设置了腾讯云或者第三方 CDN 的 URL，则具体的 RTMP/RTMPS 推流状态将通过此回调同步给您。
参数
类型
描述
cdnUrl
String
您调用 startPublishMediaStream 时通过目标推流配置（​TRTCPublishTarget）传入的 URL。
status
int
推流状态，取值见下方「推流状态取值」。
errCode
int
推流结果，0 表示成功，其余值表示失败。
errMsg
String
具体推流信息。
extraInfo
String
额外信息。对于部分错误码，可能会有额外的信息帮助您排查问题。
推流状态取值：
取值
描述
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 时，SDK 会先返回该状态，再返回状态 0。

onScreenCaptureStarted

final void Function()? onScreenCaptureStarted
屏幕分享开启的事件回调。

onScreenCapturePaused

final void Function(int reason)? onScreenCapturePaused
屏幕分享暂停的事件回调。
当您通过 ​pauseScreenCapture 暂停屏幕分享时，SDK 便会抛出此事件回调。
参数
类型
描述
reason
int
暂停原因。
0：用户主动暂停；
1：分享窗口变为不可见状态导致的暂停（Mac），或设置屏幕分享参数导致的暂停（Windows）；
2：屏幕分享窗口被最小化导致的暂停（仅 Windows）；
3：屏幕分享窗口被隐藏导致的暂停（仅 Windows）。

onScreenCaptureResumed

final void Function(int reason)? onScreenCaptureResumed
屏幕分享恢复的事件回调。
当您通过 ​resumeScreenCapture 恢复屏幕分享时，SDK 便会抛出此事件回调。
参数
类型
描述
reason
int
恢复原因。
0：用户主动恢复；
1：分享窗口恢复可见后自动恢复（Mac），或屏幕分享参数设置完毕后自动恢复（Windows）；
2：屏幕分享窗口从最小化被恢复后自动恢复（仅 Windows）；
3：屏幕分享窗口从隐藏被恢复后自动恢复（仅 Windows）。

onScreenCaptureStopped

final void Function(int reason)? onScreenCaptureStopped
屏幕分享停止的事件回调。
当您通过 ​stopScreenCapture 停止屏幕分享时，SDK 便会抛出此事件回调。
参数
类型
描述
reason
int
停止原因。
0：用户主动停止；
1：屏幕分享窗口被关闭。

onScreenCaptureCovered

final void Function()? onScreenCaptureCovered
屏幕分享的目标窗口被遮挡的事件回调（仅 Windows）。
当屏幕分享的目标窗口被遮挡无法正常捕获时，SDK 会抛出此事件回调。您可以在收到该回调后，通过 UI 提示用户移开遮挡的窗口。

onLocalRecordBegin

final void Function(int errCode, String storagePath)? onLocalRecordBegin
本地录制任务已经开始的事件回调。
当您调用 ​startLocalRecording 启动本地媒体录制任务时，SDK 会抛出该事件回调，用于通知您录制任务是否已经顺利启动。
参数
类型
描述
errCode
int
录制状态。
0：录制任务启动成功；
-1：录制任务启动失败；
-2：不支持的录制格式；
-6：录制已经启动，需要先停止录制；
-7：录制文件已存在，需要先删除；
-8：录制目录无写入权限，请检查目录权限。
storagePath
String
录制文件的存储路径。

onLocalRecording

final void Function(int duration, String storagePath)? onLocalRecording
本地录制任务正在进行中的进展事件回调。
当您调用 ​startLocalRecording 成功启动本地媒体录制任务后，SDK 会定时地抛出本事件回调。您可以通过该回调获知录制任务的状态。
您可以在调用 startLocalRecording 时设定本事件回调的抛出间隔。
参数
类型
描述
duration
int
已经录制的累计时长，单位：毫秒。
storagePath
String
录制文件的存储路径。

onLocalRecordFragment

final void Function(String storagePath)? onLocalRecordFragment
录制分片结束的事件回调。
开启分片录制时，每完成一个分片文件，SDK 都会抛出本事件回调。
参数
类型
描述
storagePath
String
分片文件的存储路径。

onLocalRecordComplete

final void Function(int errCode, String storagePath)? onLocalRecordComplete
本地录制任务已经结束的事件回调。
当您调用 ​stopLocalRecording 停止本地媒体录制任务时，SDK 会抛出该事件回调，用于通知您录制任务的最终结果。
参数
类型
描述
errCode
int
录制状态。
0：录制成功；
-1：录制失败；
-2：切换分辨率或横竖屏导致录制结束；
-3：录制时间太短，或未采集到任何视频或音频数据，请检查录制时长，或是否已开启音视频采集。
storagePath
String
录制文件的存储路径。

onSnapshotComplete

final void Function(String userId, String path, int errCode, String errMsg)? onSnapshotComplete
本地截图完成的事件回调。
调用 ​snapshotVideo 截图完成后，SDK 会通过此回调返回截图结果。
参数
类型
描述
userId
String
截图对应的用户 ID。
path
String
截图文件的路径。
errCode
int
错误码。
errMsg
String
错误信息。

类型定义

本文档回调参数中用到的枚举与数据类定义于 lib/trtc_cloud_def.dart，详见 ​TRTCCloudDef，常用的有：
类型
描述
音视频播放状态。
播放状态变化的原因。
网络质量。
网络质量信息。
网络和性能的汇总统计指标。
音量大小。
网络测速结果。
视频流类型。
日志级别。
音频路由类型 ​TXAudioRoute 定义于 lib/tx_device_manager.dart。

其他回调类

TRTCLogCallback

TRTCLogCallback({required void Function(String log, TRTCLogLevel level, String module) onLog})
日志回调。
通过 TRTCCloud 的 ​setLogCallback 设置。

onLog

final void Function(String log, TRTCLogLevel level, String module) onLog
本地日志的打印回调。
如果您希望捕获 SDK 的本地日志打印行为，可以设置日志回调，让 SDK 通过此回调将所有要打印的日志都回调给您。
参数
类型
描述
log
String
日志内容。
level
日志等级。
module
String
保留字段，暂无具体意义，目前为固定值 TXLiteAVSDK。

示例代码

trtcCloud.setLogCallback(TRTCLogCallback(
  onLog: (String log, TRTCLogLevel level, String module) {
    debugPrint('[$level] $log');
  },
));
中国站