SRTCEngine 与 Channel

`SRTC`

进程级的全局配置入口：把宿主的 Context 交给 SDK，以及设置 SDK 语言（1.1.0 起）。

`SRTC.init(context)`

static init(context: common.Context): void

参数	类型	说明
`context`	`common.Context`	通常传 `UIAbility` 的 `this.context`

在 UIAbility.onCreate 里调用一次。

不调用不会报错，但摄像头档位查询拿不到 Context，分辨率会退化为”由底层自行吸附档位”，你在 CameraPreset 里设定的值不再生效。

`SRTC.context`

static get context(): common.Context | undefined

返回 undefined 表示没有调用过 init()。

`SRTC.setLanguage(lang?)`

1.1.0 起

static setLanguage(lang?: string): void

参数	类型	必填	说明
`lang`	`string`	否	BCP 47 语言标签，如 `'zh-CN'`、`'en'`；`zh_CN` 会被规范化为 `zh-CN`。传空（不传或空串）恢复缺省：跟随系统语言

影响两件事：

请求后端时的 Accept-Language 头 —— 后端业务错误（码 ≥ 1000）的文案随之返回中 / 英
audioRouteName / audioRouteTargetName / audioCallStateName 的显示名：语言以 zh 开头出中文，其余一律英文

不影响 SDK 自身报错：SRTCError.detail 一律英文，见错误码。进程级全局设置，随时可改，下次请求 / 下次取显示名时生效；SMeeting 鸿蒙版读的也是这一个值。

缺省取的是系统语言。宿主用 setAppPreferredLanguage 单独设置的应用语言暂不跟随，需要与应用内语言一致时请显式调用 SRTC.setLanguage。

`SRTC.language`

1.1.0 起

static get language(): string

当前生效的 SDK 语言。优先级：setLanguage() 设置的值 > 系统语言 > 'zh'。

`SRTCEngine`

SDK 主入口。无参构造。

const srtc: SRTCEngine = new SRTCEngine();
srtc.logLevel = LogLevel.info;

属性

属性	类型	读写	说明
`SRTCEngine.version`	`string`	静态只读	SDK 版本，等同导出的 `SRTC_VERSION`
`channels`	`Channel[]`	只读	当前存活的频道，按加入先后排序
`defaultChannel`	`Channel \| undefined`	只读	最早加入的频道
`deviceId`	`string`	只读	本机设备 ID（上报用）
`deviceType`	`DeviceType`	只读	恒为 `DeviceType.harmonyOS`（`8`）
`logLevel`	`LogLevel`	读写	日志级别

SRTCEngine 没有 dispose()。要释放资源就 leaveChannel() 并把注册过的 delegate 逐一 remove。

`joinChannel(tokenString, options?)`

加入频道。

joinChannel(tokenString: string, options?: JoinOptions): Promise<Channel>

参数	类型	必填	说明
`tokenString`	`string`	是	Base64 编码的频道 Token，由业务后端签发
`options`	`JoinOptions`	否	入会选项，见类型定义

返回：Promise<Channel> 抛出：tokenExpired / tokenInvalid / alreadyJoined / apiRequestFailed / signalingConnectFailed / peerConnectionFailed apiRequestFailed 的 code 为后端业务码、108006（网络 / HTTP 失败，见 httpStatus）或 108011（响应解码失败），见错误码。可以调用多次加入多个频道，各频道互不干扰。

options.autoSubscribeAudio 与 autoSubscribeVideo 默认都是 false，入会后不会自动收流。典型现象是”入会成功但听不到、看不到别人”。

`leaveChannel()`

leaveChannel(): Promise<void>

离开默认频道（最早加入的那个）。

`leaveChannelInstance(channel)`

leaveChannelInstance(channel: Channel): Promise<void>

离开指定频道。多频道场景用这个。

`createLocalMicTrack(preset?)`

createLocalMicTrack(preset?: MicPreset): LocalMicTrack

创建麦克风轨道。不传 preset 用默认参数。

创建 ≠ 采集 ≠ 发布。拿到轨道后还要 startCapture()，要让对端看到 / 听到还要 channel.publishLocalAudioTrack()。

`createLocalCameraTrack(preset?)`

createLocalCameraTrack(preset?: CameraPreset): LocalCameraTrack

创建摄像头轨道。可选预设：cameraPreset1080p() / cameraPreset720p() / cameraPreset360p() / cameraPreset180p()。

LocalCameraTrack 本身是无参构造，预设必须经引擎传入 —— new LocalCameraTrack(preset) 编不过。

`createLocalScreenTrack(preset?, audioPreset?)`

createLocalScreenTrack(preset?: ScreenPreset, audioPreset?: ScreenAudioPreset): LocalScreenTrack

创建屏幕采集轨道。传了 audioPreset 时会同时采集系统音频，通过 screenTrack.audioTrack 取到那条音频轨。 startCapture() 会弹出系统授权窗，用户同意后才出帧。

`enableIm(tokenString)` / `disableIm()`

enableIm(tokenString: string): Promise<Im>
disableIm(): Promise<void>

开启 / 关闭频道 IM 通道。Im 对象上注册 ImDelegate 收消息。重复调用 enableIm 抛 alreadyJoined（108005；1.0.1 及以前是 invalidState）。

IM 是只收不发的：SDK 提供 onImMessage 回调，但没有发送接口 —— 发消息由业务后端负责。频道内自定义消息（onCustomMessage）同理。

`Channel`

一次已经完成鉴权和网络连接的 RTC 会话。由 joinChannel 返回，不要自己构造。

属性

属性	类型	说明
`token`	`ChannelToken`	本次入会用的 Token（已解析）
`delegates`	`MulticastDelegate<ChannelDelegate>`	事件回调容器
`connectState`	`ConnectionState`	信令面连接状态
`mediaState`	`MediaConnectionState`	媒体面连接状态（PeerConnection），与 `connectState` 相互独立
`channelInfo`	`ChannelInfo \| undefined`	频道信息
`me`	`User \| undefined`	自己
`streamVendor`	`StreamVendor`	当前流媒体引擎，排障用

delegates 是强引用，必须成对 add / remove。ArkTS 没有弱引用也没有 deinit，漏掉会导致监听者永不回收、且离开页面后仍收到回调。

发布

publishLocalAudioTrack(track: LocalAudioTrack, options?: AudioPublishOptions): Promise<void>
publishLocalVideoTrack(track: LocalVideoTrack, options?: VideoPublishOptions): Promise<void>
unpublishLocalAudioTrack(track: LocalAudioTrack): Promise<void>
unpublishLocalVideoTrack(track: LocalVideoTrack): Promise<void>
publishedTracks(): Track[]

不传 options 时用轨道的 defaultPublishOptions（预设里带的那份）。抛出：trackAlreadyPublished / trackNotPublished / transportNotReady / maxPublishLimitReached，以及 1.1.0 起：

情形	`kind`	`code`
轨道还没 `startCapture()`	`trackNotCaptured`	`108033`
发布描述为空、未传 `options` 且轨道没有预设	`invalidArgument`	`108031`
同一视频轨已发布到其它频道，又要开 Simulcast	`featureNotSupported`	`108032`
频道或引擎正在重连	`transportNotReady`	`108014`
已离开频道	`notConnected`	`108001`
SeaStart 引擎未连接 / 已断开（非重连中）	`publishFailed`	`108300`
PeerConnection 进入 failed / closed	`peerConnectionFailed`	`108015`

轨道属于引擎而不是频道 —— 同一条采集轨道可以发布给多个频道，采集只做一次。

subscribeRemoteAudioTrack(uid: string, trackId: string): Promise<void>
subscribeRemoteVideoTrack(uid: string, trackId: string): Promise<void>
unsubscribeRemoteTrack(track: Track, debounceMs: number): Promise<void>
getRemoteTrack(uid: string, trackId: string): Track | undefined
getRemoteTrackByDesc(uid: string, desc: string): Track | undefined

uid + trackId 来自 onTrackAdded 回调里的 UserInfo 与 TrackInfo。抛出（订阅）：userNotFound（108204，频道内没有该 uid）/ trackNotFound（108003）/ invalidArgument（108031，轨道类型与方法不符）/ transportNotReady（108014，重连中）/ subscribeFailed（108301，SeaStart 引擎未连接 / 已断开）。其中 108204 / 108031 / 108301 为 1.1.0 起；此前 uid 不存在报 108003。 unsubscribeRemoteTrack 的 debounceMs 用来抑制”快速滑动列表导致的反复订阅/退订”—— 传 0 表示立即退订。

拿到 Track 对象不等于已经有帧。远端轨道是信令先建对象、订阅协商完成后才绑定底层轨道，渲染时机看 onTrackBindRtcTrack（SRTCVideoView 内部已处理）。

MCU 合成画面

1.2.0 起

subscribeRemoteVideoMcuTrack(): Promise<RemoteVideoMcuTrack>
unsubscribeRemoteVideoMcuTrack(): Promise<void>
get remoteVideoMcuTrack(): RemoteVideoMcuTrack | undefined

订阅频道级 MCU 合成视频（服务端把频道内的画面合成一路）。合成流由服务端合成任务以保留身份 __mcu__ 发布，不在成员列表里，所以不能走 subscribeRemoteVideoTrack(uid, trackId)，要用这一组按保留标识直接订阅。保留标识与 Swift / C / Python SDK 一致。

const mcu = await channel.subscribeRemoteVideoMcuTrack();
// 渲染与普通远端视频一样
SRTCVideoView({ track: mcu, trackKey: RemoteVideoMcuTrack.mcuTrackId })

需要服务端先开启合成任务（服务端 API mcu/start）。任务没起来时 SFU 回 not found，SDK 会重试几秒；任务起来得更晚，请在收到合成任务进入运行状态后再调一次——这个时机由业务决定，SDK 不监听合成任务状态。
重复调用返回同一个轨道对象；订阅失败时对象仍保留在 remoteVideoMcuTrack 上，可直接再调一次重试。
收流状态同样经 onReceiveStreamStatusChange 上报，uid 为 RemoteVideoMcuTrack.publisherUid。
SeaStart 与网宿两条引擎都支持。

Simulcast

switchLayer(pubUid: string, trackId: string, targetTrackId: string): void
getSubscribeHit(uid: string, trackId: string): string | undefined

switchLayer 主动切到指定层（大流 / 小流）。getSubscribeHit 返回当前实际命中的轨道 ID —— 服务端可能因带宽自动降级，这个值才是真相。切换结果通过 onLayerSwitched 回调上报。

远端音频播放控制

setRemoteAudioPlayback(enabled: boolean): void
setUserAudioPlayback(uid: string, enabled: boolean): void
isUserAudioMuted(uid: string): boolean
getMutedAudioUids(): string[]

这几个只影响本地播放，不改变订阅关系 —— 也就是”关扬声器”而不是”退订”。带宽照旧消耗，但切回来是瞬时的。

成员

getUsers(): Map<string, UserInfo>
getUser(uid: string): User | undefined
getInfo(): ChannelInfo | undefined

质量

getConnectionQuality(): QualityEvaluation | undefined

主动查询当前连接质量。做 UI 指示器更建议监听 onConnectionQualityChange，它已经做过等级判定与抖动抑制。

本端采集电平

1.2.0 起

getLocalAudioLevel(track: LocalAudioTrack): Promise<number | undefined>

读一条已发布本地音频轨道当前的采集电平（0~1，线性值），用来画「我」的音柱。onActiveSpeakersChange 只含远端，自己的音量要用它读。

读的是送进编码器之前的电平：mute() 后归零，与对端听到的一致。
未发布的轨道没有发送统计，返回 undefined。
每次调用是一次 getStats，轮询频率别超过 10Hz（建议 5～10Hz），平滑与映射由业务层做。

统计

getStats(): Promise<RtcStatsSnapshot>
logStats(): Promise<void>
rawStatsTypeCounts(): Promise<string>

采集一次本端 WebRTC 统计，返回 RtcStatsSnapshot。与 getConnectionQuality() / onQualityReport 的分工：

	来源	覆盖范围
`QualityReport`	SFU 通过控制面下发	只有 SeaStart 引擎，服务端视角
`getStats()`	本端观察 PeerConnection	两条引擎都有，本端视角

所以网宿 CDN 路径上想拿到任何质量数据，只有 getStats() 这一条路；而”我实际编码出来是多少分辨率""编码器是被 CPU 还是被带宽限住了”这类问题服务端根本答不了，也只有这一条路。 logStats() 是排障快捷入口，采集一次并按每行一路流打成日志。

首次调用的码率恒为 0。 码率由两次采集之间的字节差算出，没有上一次快照就没有差分区间。要展示码率就周期性调用，1 秒一次比较合适；排障时连着调两次、看第二次。

上新机型或升级底层库后先跑 rawStatsTypeCounts()。 底层 webrtc.d.ts 没有声明 outbound-rtp 等类型的字段，native 侧究竟填了哪些未经约定。类型缺失时上面所有统计读出来都是 undefined，而且不报错。

离开

leave(): Promise<void>

一般用 srtc.leaveChannel() / srtc.leaveChannelInstance(channel)，它们会同时维护引擎侧的频道列表。

Channel 上还有 refresh() / leaveWithReason() / onDisconnect / isTrackPublishedInOtherChannel 等成员，那些是 SDK 内部在用的，业务侧不要调。

`User`

频道成员。由 channel.getUser(uid) 取得。

成员	说明
`uid` / `sid` / `linkId`	标识
`getInfo(): UserInfo`	信息副本
`getTrack(id)` / `getTrackByDesc(desc)` / `getTracks()`	该成员的轨道

概览

Web SDK

Android SDK

Windows SDK

Swift SDK（iOS/macOS）

iOS SDK

HarmonyOS SDK

C SDK（服务端/嵌入式）

Python SDK（服务端 AI）

服务端 API

`SRTC`

`SRTC.init(context)`

`SRTC.context`

`SRTC.setLanguage(lang?)`

`SRTC.language`

`SRTCEngine`

属性

`joinChannel(tokenString, options?)`

`leaveChannel()`

`leaveChannelInstance(channel)`

`createLocalMicTrack(preset?)`

`createLocalCameraTrack(preset?)`

`createLocalScreenTrack(preset?, audioPreset?)`

`enableIm(tokenString)` / `disableIm()`

`Channel`

属性

发布

订阅

MCU 合成画面

Simulcast

远端音频播放控制

成员

质量

本端采集电平

统计

离开

`User`

相关阅读

​SRTC

​SRTC.init(context)

​SRTC.context

​SRTC.setLanguage(lang?)

​SRTC.language

​SRTCEngine

​属性

​joinChannel(tokenString, options?)

​leaveChannel()

​leaveChannelInstance(channel)

​createLocalMicTrack(preset?)

​createLocalCameraTrack(preset?)

​createLocalScreenTrack(preset?, audioPreset?)

​enableIm(tokenString) / disableIm()

​Channel

​属性

​发布

​订阅

​MCU 合成画面

​Simulcast

​远端音频播放控制

​成员

​质量

​本端采集电平

​统计

​离开

​User

​相关阅读

`SRTC`

`SRTC.init(context)`

`SRTC.context`

`SRTC.setLanguage(lang?)`

`SRTC.language`

`SRTCEngine`

属性

`joinChannel(tokenString, options?)`

`leaveChannel()`

`leaveChannelInstance(channel)`

`createLocalMicTrack(preset?)`

`createLocalCameraTrack(preset?)`

`createLocalScreenTrack(preset?, audioPreset?)`

`enableIm(tokenString)` / `disableIm()`

`Channel`

属性

发布

订阅

MCU 合成画面

Simulcast

远端音频播放控制

成员

质量

本端采集电平

统计

离开

`User`

相关阅读