事件参考

事件都以可选方法的接口形式提供，只实现关心的那几个即可：

import { ChannelDelegate, UserInfo, TrackInfo } from 'srtc';

const delegate: ChannelDelegate = {
  onUserJoin: (channel, user: UserInfo) => { /* ... */ },
  onTrackAdded: (channel, user: UserInfo, track: TrackInfo) => { /* ... */ }
};

channel.delegates.add(delegate);

delegates 是强引用，必须成对 add / remove。ArkTS 既没有弱引用、也没有 deinit。注册后不摘除会导致监听者永不回收，而且离开页面后仍然收到回调。通常在 aboutToAppear / aboutToDisappear 里配对：

aboutToAppear(): void {
  this.channel.delegates.add(this.delegate);
}
aboutToDisappear(): void {
  this.channel.delegates.remove(this.delegate);
}

ChannelDelegate

频道级事件。第一个参数恒为 channel，下表省略。

连接状态

事件	其余参数	触发时机
`onJoinSucceed`	`info: ChannelInfo`	加入频道成功，信令与媒体均已就绪
`onReconnecting`	—	连接中断，SDK 正在自动重连
`onReconnected`	`info: ChannelInfo`	重连成功，频道信息可能已变化
`onDisconnected`	`reason: DisconnectReason`, `error?: Error`	连接断开且不再自动恢复
`onMediaStateChange`	`state: MediaConnectionState`, `reason?: string`	媒体面（PeerConnection）连通性变化

onReconnecting / onReconnected 之间 SDK 会自行恢复发布与订阅，业务侧一般只需要更新 UI 上的连接指示。收到 onDisconnected 才需要走「退出会议」的业务流程。

心跳失败何时触发 onDisconnected（1.1.0 起）： 只有后端返回业务错误（Token 失效、被踢等，SRTCError.isServerError(error) 为 true）才退出频道，reason 为 error、error 带后端码；网络抖动或响应解码失败（108006 / 108011）不再退会，等下一次心跳重试。1.0.1 及以前一次心跳网络失败就会触发 onDisconnected。IM 心跳与 onImDisconnected 同理。

onMediaStateChange 与上面几个不是同一条线。onReconnecting / onReconnected 说的是信令面（MQTT），onMediaStateChange 说的是画面和声音还在不在。两者各自独立地断开与恢复。UI 上的「网络异常」提示应当同时接这两条线：只接信令那条会出现”提示已经消失、画面还是黑的”；只接媒体这条会漏掉成员列表已经不再更新。参数 reason 只用于日志，不要拿它做分支判断。收到 disconnected 表示 SDK 已放弃重连、不会再自行恢复。状态取值见 MediaConnectionState。

成员

事件	其余参数	触发时机
`onUserJoin`	`user: UserInfo`	有成员加入
`onUserUpdate`	`user: UserInfo`	成员信息变化（昵称、自定义属性等）
`onMeUpdate`	`user: UserInfo`	自己的信息变化
`onUserLeave`	`uid: string`, `reason: DisconnectReason`	成员离开

媒体轨道

事件	其余参数	触发时机
`onTrackAdded`	`user: UserInfo`, `track: TrackInfo`	远端有新流可订阅
`onTrackUpdated`	`user: UserInfo`, `track: TrackInfo`	远端流信息变化（分辨率、静音态等）
`onTrackRemoved`	`user: UserInfo`, `track: TrackInfo`	远端流已移除
`onReceiveStreamStatusChange`	`status: ReceiveStreamStatus`	某一路已订阅的远端视频收流超时 / 恢复（1.2.0 起）

onTrackAdded 只表示「可以订阅了」，不会自动订阅（除非入会时开了 autoSubscribeAudio / autoSubscribeVideo）。要看到画面还需要显式调用 channel.subscribeRemoteVideoTrack(uid, trackId)。

onReceiveStreamStatusChange（1.2.0 起）：订阅后约 3 秒收不到该路视频帧报一次 timedOut = true，帧恢复后报一次 false；首帧到达时会先收到一次 false，可据此关掉初始 loading。按轨道判定，用来开关某一格画面上的「加载中 / 对方网络异常」指示，覆盖所有已订阅的远端视频（含 MCU 合成轨，uid 为 __mcu__）。判定纯在本端，两条引擎都触发。

只报跳变：已出过帧的轨道退订后再订阅，不会再报一次恢复。初始状态请按 RemoteVideoTrack.isReceiveTimedOut 现判。不要用 onConnectionQualityChange 代替——那是整条链路的档位，单路画面停了档位也可能是 excellent。

频道与消息

事件	其余参数	触发时机
`onChannelInfoUpdate`	`info: ChannelInfo`	频道属性变化
`onCustomMessage`	`msg: CustomMessage`	收到频道内自定义消息

质量与 Simulcast

事件	其余参数	触发时机
`onQualityReport`	`report: QualityReport`	周期性上报的原始质量采样
`onConnectionQualityChange`	`change: ConnectionQualityChange`	连接质量等级发生变化
`onActiveSpeakersChange`	`snapshot: ActiveSpeakersSnapshot`	活跃说话人集合变化（只含远端；1.2.0 起网宿引擎也触发）
`onLayerSwitched`	`info: LayerSwitchedInfo`	Simulcast 大小流发生切换

做 UI 指示器请用 onConnectionQualityChange（已经做过等级判定与抖动抑制）， onQualityReport 是原始采样，适合上报到自己的监控系统。细节见通话质量。

TrackDelegate

轨道级事件。第一个参数恒为 track。

事件	其余参数	触发时机
`onTrackInfoUpdate`	`info: TrackInfo`	轨道信息变化
`onTrackMute`	—	轨道被静音
`onTrackUnmute`	—	轨道取消静音
`onTrackEnd`	—	采集结束 / 轨道失效。1.2.0 起屏幕共享被系统侧结束时也会触发
`onTrackBindRtcTrack`	—	底层 WebRTC 轨道绑定完成
`onTrackMirrorUpdate`	—	镜像状态变化
`onTrackCameraSwitching`	`switching: boolean`	摄像头切换开始（`true`）/ 完成（`false`），切换完成后再读 `isFrontCamera`

onTrackBindRtcTrack 是渲染的关键时机：远端轨道是信令先建对象、订阅协商完成后才绑定底层轨道，所以拿到 Track 对象不等于已经有帧。SRTCVideoView 内部已经监听了它并自动补挂，自己接渲染层时需要处理这一点。

DeviceManagerDelegate

设备热插拔。注册在 DeviceManager.shared.delegates 上。

事件	参数	触发时机
`onDeviceAdd`	`device: DeviceInfo`	设备接入
`onDeviceRemove`	`device: DeviceInfo`	设备移除

AudioRouteSessionDelegate

音频路由与通话状态。注册在 AudioRouteSession.shared.delegates 上。

事件	参数	触发时机
`onAudioRouteChange`	`route: AudioRoute`, `previousRoute: AudioRoute`	输出路由变化（含蓝牙 / 有线耳机插拔）
`onCallStateChange`	`state: AudioCallState`, `previous: AudioCallState`	系统通话状态变化

外接设备由系统接管，SDK 只上报不主动切换 —— 收到 onAudioRouteChange 时更新 UI 即可，不要试图在回调里再切回去，那会和系统抢。见音频路由。

ImDelegate

频道 IM。srtc.enableIm(tokenString) 之后注册在返回的 Im 对象上。

事件	其余参数	触发时机
`onImEnabled`	—	IM 通道就绪
`onImReconnecting`	—	IM 连接中断，正在重连
`onImReconnected`	—	IM 重连成功
`onImDisconnected`	`reason: ImDisconnectReason`, `error?: Error`	IM 断开且不再自动恢复
`onImMessage`	`msg: ImMessage`	收到 IM 消息

第一个参数恒为 im。

概览

Web SDK

Android SDK

Windows SDK

Swift SDK（iOS/macOS）

iOS SDK

HarmonyOS SDK

C SDK（服务端/嵌入式）

Python SDK（服务端 AI）

服务端 API

ChannelDelegate

连接状态

成员

媒体轨道

频道与消息

质量与 Simulcast

TrackDelegate

DeviceManagerDelegate

AudioRouteSessionDelegate

ImDelegate

相关阅读

​ChannelDelegate

​连接状态

​成员

​媒体轨道

​频道与消息

​质量与 Simulcast

​TrackDelegate

​DeviceManagerDelegate

​AudioRouteSessionDelegate

​ImDelegate

​相关阅读

ChannelDelegate

连接状态

成员

媒体轨道

频道与消息

质量与 Simulcast

TrackDelegate

DeviceManagerDelegate

AudioRouteSessionDelegate

ImDelegate

相关阅读