更新日志

​

[1.2.0] - 2026.10.14

本版补齐与 Swift 版对齐的一批能力，只有新增、无不兼容变更，1.1.0 的接入代码可直接升级。 制品：https://repo.open.seastart.cn/repository/vcs-releases/srtc-harmony-1.2.0.har（184KB，SHA-256 c609910ad7c2f34e2fc13422dd2695d68e212872e481413a35fa8dd91b4e7b43）。

​

新增

• 远端视频收流超时 / 恢复：ChannelDelegate.onReceiveStreamStatusChange(channel, status: ReceiveStreamStatus) 与 RemoteVideoTrack.isReceiveTimedOut。订阅后约 3 秒收不到该路视频帧报一次超时，帧恢复后报一次恢复，用来驱动画面上的「加载中 / 对方网络异常」指示；两条引擎都触发。只报跳变，已出过帧的轨道重订不会再报恢复，初始状态按 isReceiveTimedOut 现判。
• MCU 合成画面：Channel.subscribeRemoteVideoMcuTrack() / unsubscribeRemoteVideoMcuTrack() / remoteVideoMcuTrack 与 RemoteVideoMcuTrack。合成流发布者是保留身份 __mcu__、不在成员列表里，用这组接口按保留标识直接订阅；需服务端先开启合成任务。
• 本端采集电平：Channel.getLocalAudioLevel(track)，返回已发布本地音频轨道的采集电平（0~1），用来画「我」的音柱。轮询别超过 10Hz。
• 网宿引擎的活跃说话人：onActiveSpeakersChange 在网宿引擎下也会触发（SDK 每 500ms 轮询已订阅音频的接收音量在本地算出，CDN 链路约 10 秒延迟）。此前只有 SeaStart 引擎触发。
• 前后置判断：LocalCameraTrack.isFrontCamera。切换约 600ms 才完成，切换中读到的仍是旧值，准确值请在 onTrackCameraSwitching(track, false) 之后读。
• 系统侧结束屏幕共享：用户点状态栏录屏胶囊等系统入口结束共享时，SDK 自己 stopCapture() 并触发 TrackDelegate.onTrackEnd。SDK 只停采集，撤发布由业务层在 onTrackEnd 里做。

​

变更

• setMirrored 在后置摄像头上调用无效（与 Swift 版一致，后置画面本就是真实方位），isMirrored 读回真实生效值，此时也不触发 onTrackMirrorUpdate。

​

修复

• 网宿引擎下 RemoteAudioMixTrack 拉流的流名补上 rtc_a_channel_ 前缀，与 Swift 版一致（原来漏了前缀）。

​

[1.1.0] - 2026.10.08

本版按跨端统一错误码表（第 2 版）重排错误码，含不兼容变更，升级前请对照下方「变更」与旧码 → 新码对照表检查按 code / kind 分支的代码。 制品：https://repo.open.seastart.cn/repository/vcs-releases/srtc-harmony-1.1.0.har（172KB，SHA-256 a3dc38ba248f9fdbfb28e1675fc7bd764b89fc0e3d298805549f4a4b1a5180fe）。

​

新增

• SRTC.setLanguage(lang?) / SRTC.language：设置 / 读取 SDK 语言（BCP 47，如 'zh-CN'、'en'），传空恢复缺省（跟随系统语言，取不到时为 'zh'）。影响两处：请求后端时带 Accept-Language，后端业务错误（码 ≥ 1000）的文案随之返回中 / 英；audioRouteName / audioRouteTargetName / audioCallStateName 的显示名按语言返回中 / 英（zh 开头出中文，其余英文）。SDK 自身报错不受影响。
• 新错误码：108031 参数非法、108032 能力不支持、108033 轨道未采集、108039 屏幕共享被拒、108204 用户不存在、108231 无摄像头权限、108251 无麦克风权限、108300 发布失败、108301 订阅失败，配套新增 SRTCErrorKind 成员。108001–108026 取值不变。
• SRTCError 新字段：baseCode（低 3 位语义码，跨端比较用）、httpStatus（请求失败时的 HTTP 状态，连不上 / 超时为 0）、systemCode（被包装的系统 BusinessError.code）、cause（原始异常）；静态方法 SRTCError.isServerError(e) 判断是否后端业务错误。
• 导出 CaptureDevice 枚举（camera / mic / screen）。
• 采集前权限预检：摄像头 / 麦克风 startCapture() 前只读检查一次授权状态，未授权直接抛 108231 / 108251，不弹授权框——权限仍由宿主申请。

​

变更

• 报错英文化：SRTCError.detail 一律英文，不随语言变化。请按 kind / code 判断，不要按文案判断。
• 不兼容：请求失败不再把 HTTP 状态拼进错误码。 网络失败 / HTTP 非 200 统一为 108006（HTTP 状态见 httpStatus）；响应不是 JSON、缺 code 字段统一为 108011；后端返回小于 1000 的异常码一律 108006。以上 kind 仍是 apiRequestFailed。
• 不兼容：采集异常不再直接抛系统 BusinessError，统一包成 SRTCError：无权限 108231 / 108251、屏幕共享被拒 108039、设备不存在 108021、其它 108018。原 BusinessError.code 在 systemCode，原异常在 cause。以前按 e.code === 201 判断的代码要改成判断 kind 或读 systemCode。
• 不兼容：多处 kind 由 invalidState 改为更具体的原因，见下表。
• SeaStart 引擎 SDP 协商中底层抛出的裸 Error 包成 108013（sdpNegotiationFailed），原异常在 cause。

旧码 → 新码对照（108xxx 均为完整码）：

​

修复

• 频道 / IM 心跳只在后端返回业务错误（Token 失效、被踢等）时才退出；一次网络抖动或响应解码失败（108006 / 108011）不再触发 onDisconnected / onImDisconnected，等下一次心跳重试。

---

​

[1.0.1] - 2026.09.11

​

修复

三处都是鸿蒙硬件编码器与 WebRTC 通用假设对不上导致的静默故障——不报错、日志也看不出异常，只有对端画面或后台数据不对。

• 分层发布降级：引擎声明支持 Simulcast、实际却发不出多层时，SDK 会把分层配置降成单层再发布，而不是发一路”以为是多层”的流。共享同一采集源的分层不再下发缩放系数——硬件编码器对共享源做的是中心裁剪而不是缩放，下发反而产生错误的帧。
• 分辨率对账：编码器实际输出的分辨率会因码率爬坡与档位限制而与申报值不同。SDK 现在每 3 秒从 outbound-rtp 读回实际值并回报服务端，后台看到的分辨率与实际发出的一致。
• 发布探针基线：发布完成的判据此前只看 packetsSent 是否非零，复用同一 transceiver 时会把上一路的计数当成本路已经在发。改为先记录基线、要求计数超过基线才算真的在发。

​

[1.0.0] - 2026.09.07

​

新增

• 本端统计：Channel.getStats() 返回 RtcStatsSnapshot，包含实际编码分辨率与帧率、编码器降级原因（qualityLimitationReason）、发送侧丢包与往返时延；配套 logStats() 与 statsSummary()。与服务端下发的 onQualityReport 互补——后者只有 SeaStart 引擎有，而本端统计两条引擎路径都能出，且能回答服务端答不了的问题（实际编码分辨率、为什么降级）。
• SDP 协商结果查询：negotiatedVideoCodec() / negotiatedAudioCodec() / negotiatedMedias() / negotiatedSummary()，用于核对本次通话实际协商到的编码格式。
• 媒体面连接状态：MediaConnectionState 与 mediaConnectionStateName()，反映 PeerConnection 的连通性，与信令面的 ConnectionState 相互独立。
• 摄像头变焦：ZoomRange 类型与变焦接口。
• 长时任务：支持通话切后台后继续采集与推流。
• 诊断工具：statsFieldReport() / cameraSwitchOrderReport() / publishSdpReport()，用于在新机型或升级底层库后自检字段可用性。

​

修复

• 长时任务在部分场景下启动失败（9800005 bgMode is invalid）：除 ohos.permission.KEEP_BACKGROUND_RUNNING 外，module.json5 的 ability 还需声明 "backgroundModes": ["audioRecording"]。

​

[0.0.1] - 2026.09.07

​

首个版本

• 频道：SRTCEngine.joinChannel / leaveChannel，支持多频道实例；入会选项 JoinOptions 可指定自动订阅音频 / 视频与优先编码格式。
• 本地推流：麦克风（createLocalMicTrack）、摄像头（createLocalCameraTrack）、屏幕共享（createLocalScreenTrack），配套预设 micPreset* / cameraPreset* / screenPreset*。
• 订阅：subscribeRemoteAudioTrack / subscribeRemoteVideoTrack 按 uid + trackId 显式订阅，支持 Simulcast 多层选订。
• 渲染：ArkUI 组件 SRTCVideoView，视频帧由底层直接写入 XComponent surface，不经过 ArkUI 绘制流程。
• 事件：ChannelDelegate 覆盖连接状态、成员进出、流增删、自定义消息、网络质量、活跃说话人、Simulcast 层切换。
• 音频路由：AudioRouteSession 统一管理输出路由，支持扬声器 / 听筒的持久设置与通话中临时切换；外接设备（蓝牙 / 有线）由系统接管，SDK 只上报。
• 设备管理：DeviceManager 支持设备枚举与热插拔事件。
• IM：enableIm / disableIm，频道内自定义消息与信令通道。