更新日志

​

[1.4.4] - 2026.09.15

​

变更

• WangSu(CDN) 视图录制共享视频流现在与标准屏幕共享一样附带麦克风录制音频；SRTCBroadcastKit 升级至 1.0.9。
• 保持音频录制链路预热，避免播放音量降低：音频设备初始化和播放路径切换时不再意外中断录制链路。

​

[1.4.3] - 2026.09.14

​

新增

• WangSu(CDN) 频道的屏幕共享流自带音频，云端录制不再是哑的：网宿的云端录制按流名整条流拉取，此前屏幕共享流里只有视频，录出来的共享片段没有声音。现在发布屏幕共享时会在同一条推流连接上追加一路 opus 音频（封顶 32kbps），业务代码无需改动。这路音频只有 CDN 录制看得见——它不上报信令、订阅侧也协商不出来，所以远端不会多出一个音频轨道，订阅逻辑与回调完全不受影响。

​

修复

• 取消发布音频失败后，对端显示麦克风已开却听不到声音：关闭麦克风时 SDK 要取消发布内部的混音音频轨道，这一步会走一次 HTTP 请求，网络抖动就可能失败（实测NSURLError -1005）。此前 SDK 在请求发出前就把轨道句柄置空了，失败时不回滚——服务端那条轨道其实还在，于是下次开麦会另起一条音频轨道，对端订阅到的往往是那条早已没人喂数据的旧流。现在只有取消发布成功才释放句柄，失败可自愈：下次开麦会正确复用已有的那条轨道，不会产生第二条。

​

[1.4.2] - 2026.09.12

​

新增

• macOS 整屏共享支持按窗口排除：createLocalScreenTrack(source:preset:audioPreset:)新增excludedWindowIds与excludesCurrentApplication两个带默认值的参数，ScreenCaptureOptions同步新增同名属性。excludedWindowIds的取值是UInt32(NSWindow.windowNumber)，仅在共享整个显示器时有意义（采集单个窗口时忽略）；列表在startCapture()时快照一次，之后新开的窗口一律进画面。两个参数都有默认值，现有调用点源码兼容。

​

变更

• macOS 整屏共享默认包含本 App 自己的窗口：此前 SDK 把整个进程的窗口都从画面里挖掉，表现为「共享整屏时对端看不到你自己的应用窗口」——这不是系统限制，是 SDK 自己排的。现在改为默认包含，与 Zoom / 腾讯会议一致，需要挖掉的窗口通过excludedWindowIds逐个指定。
• ScreenCaptureSources.availableWindows(includeCurrentApp:)的默认值由false改为true，自己的窗口可以作为单窗口共享源出现在列表里。

​

修复

• 只共享屏幕音频时麦克风被一起发出去：mix 模式下所有音频源共用同一条采集流，原先靠混音节点的音量决定要不要混入麦克风，但那个节点实际上没有输入，改它的音量对硬件麦克风毫无作用——结果是业务侧没有发布麦克风轨、只共享屏幕音频时，对端仍能听到本端的环境声。现改为在音频设备模块层面直接静音硬件麦克风（默认静音，只有发布麦克风轨或LocalMicTrack.unmute()才解除），屏幕音频与自定义音频注入的声音不受影响。
• 同一根因下，macOS 上LocalMicTrack.mute()此前是空操作（调用后对端仍能听到），现已真正生效。

​

[1.4.1] - 2026.09.11

​

修复

• WangSu(CDN) 频道下ChannelDelegate.didChangeActiveSpeakers不再触发：活跃说话人此前只有 SeaStart(SFU) 引擎有数据（由服务端通过信令通道下发），CDN 链路上没有该通道，导致同一个对外回调在 WangSu 频道里恒不触发，业务据此绘制的音量条、发言人提示会静默失效且无任何报错。现在 CDN 侧在本地按 WebRTC 标准统计（inbound-rtp的audioLevel）每 500ms 采样一次，产出与 SFU 完全相同的ActiveSpeakersSnapshot，两种引擎对外行为一致，业务代码无需改动。

​

[1.4.0] - 2026.09.09

​

新增

• 虚拟背景：在摄像头采集链路上做人像分割，把人像之外的区域替换成虚化或指定图片，装载不需要授权密钥。SRTCEngine新增installVirtualBackground(modelPath:)、uninstallVirtualBackground()、enableVirtualBackground(_:)、isVirtualBackgroundEnabled、setVirtualBackgroundBlur(level:)、setVirtualBackgroundImage(_:)、setVirtualBackgroundInferenceInterval(_:)、setVirtualBackgroundMaskSync(_:)，以及实例访问器virtualBackground（诊断用只读状态与droppedFrameCount）。配套新增类型SRTCVirtualBackground、SRTCVirtualBackgroundEffect、SRTCNativeImage，详见虚拟背景；
  • 开启后自动作用于所有摄像头轨道（含开启之后才新建的），不需要往videoProcessors里挂东西；
  • 状态整机一份，切前后摄像头 / 切换摄像头设备后不需要重新下发配置；
  • 分割失败或输出缓冲池耗尽时丢掉该帧而不是送出未处理的原始画面（避免把真实背景闪给对端），丢帧计数见virtualBackground.droppedFrameCount。
• SRTCEngine新增defaultVideoProcessors：视频处理器管线配置一次，此后新建的摄像头轨道自动带上（摄像头轨道每次开摄像头都是新建的，只在轨道上设一次会丢）。
• SRTCError新增四个取值：virtualBackgroundAlreadyInstalled、virtualBackgroundNotInstalled、virtualBackgroundModelNotFound(String)、virtualBackgroundSessionFailed(String)。

​

[1.3.3] - 2026.09.07

​

修复

• DegradationPreference现在真正生效：发布视频时会下发到底层编码器，弱网下按设置降级分辨率或帧率（此前该设置被忽略）。

​

变更

• 摄像头与屏幕共享预设统一改为maintainResolution（优先保清晰度、必要时降帧率），此前各预设取值不一致。共享文档、演示这类以文字为主的场景由此明显更清晰。

​

新增

• macOS DeviceManager新增setSystemDefaultOutputDevice(_:)，直接切换系统默认音频输出设备（对齐 Windows 端行为）。

​

[1.3.2] - 2026.09.07

​

修复

• 修复 mqtt 消息中content为null时，JSONSerialization抛 ObjC 异常导致的崩溃（取值时统一过滤NSNull）。

​

[1.3.1] - 2026.09.07

​

新增

• DeviceType新增harmonyOS（值为8），用于识别鸿蒙端接入的成员。

​

[1.3.0] - 2026.08.20

​

新增

• iOS 音频路由：新增AudioRouteSession.shared，统一管理 iOS 的音频会话与输出路由。配套新增类型AudioRoute（当前路由，只读五态，含蓝牙 / 有线耳机）、AudioRouteTarget（可切换目标，扬声器 / 听筒两态）、AudioRouteInfo、AudioCallState，以及事件协议AudioRouteSessionDelegate（路由变化 / 会话中断 / 中断恢复 / 系统通话状态）。
  • 持久设置defaultAudioRoute：入会前设定默认走扬声器还是听筒，长期有效，外设拔出后按它回落；
  • 临时设置setAudioRoute(_:) / clearAudioRouteOverride()：通话中临时切换，优先级高于持久设置；
  • 外接设备（蓝牙 / 有线）由系统接管，SDK 只上报不主动切换 —— iOS 无可靠手段指定具体外设，需要用户主动选择时请用系统的AVRoutePickerView。
• DeviceManager新增isSpeakerOutputPreferred，用于查询当前是否走扬声器外放。

​

变更

• iOS 加入频道时即建立通话音频通道并保持到离会，「开不开麦」只决定是否推流，不再影响底层音频采集是否运行。这是让不开麦时也能切换听筒 / 扬声器的前提。
• DeviceManager.setSpeakerOutputPreferred(_:)语义对齐主流 RTC SDK：true切扬声器、false切听筒（此前false表示「撤销覆盖、回到系统默认」，结果不确定）。方法签名未变，调用方无需改动。

​

[1.2.0] - 2026.08.19

​

破坏性变更

• 错误枚举中的信令相关取值由mqtt*改名为signaling*（signalingConnectFailed / signalingSubscribeFailed），对外不再暴露信令实现细节。捕获了旧取值的代码需要改名，取值语义未变。

​

新增

• iOS 全屏屏幕共享：createLocalScreenTrack(mode:)新增采集方式参数，.broadcast(appGroup:)基于 ReplayKit Broadcast Upload Extension 采集整个系统屏幕；原有的应用内采集为默认值.inApp，行为不变。配套新增：
  • SRTCBroadcastKit产品（扩展侧使用，不含 WebRTC）与基类SRTCBroadcastSampleHandler，业务扩展只需class SampleHandler: SRTCBroadcastSampleHandler {}；
  • 系统广播选择器封装SRTCBroadcastPicker（SwiftUI）/ SRTCBroadcastPickerView（UIKit）；
  • TrackDelegate新增screenBroadcastDidStart(_:)与screenBroadcastDidFinish(_:reason:)，用于感知用户从系统 UI 发起 / 停止广播；
  • LocalScreenTrack新增captureMode与isBroadcastActive（isCapturing仅表示监听就绪，展示「共享中」状态应看isBroadcastActive）。
• 多频道：同一个SRTCEngine可同时加入多个频道。新增channels、defaultChannel、leaveChannel(_:)；轨道为引擎级对象，可发布到多个频道，采集回收遵循「最后一个释放者负责」。

​

变更

• 多频道发布音频的校验方式：由「同一时刻只允许一个频道发布音频」的独占限制，改为「各发布音频的频道必须持有完全相同的音频源集合」，放开了最常见的「多频道各发一路麦克风」。集合不一致时publishLocalTrack抛invalidState，避免跨频道音频泄漏；订阅侧不受限制。

​

修复

• iOS 摄像头采集改为 SDK 自建 AVCaptureSession，修复部分真机上采集静默失败、对端看不到画面的问题。

​

[1.1.0] - 2026.08.02

​

新增

• 新增视频帧旋转枚举VideoRotation，取值._0/._90/._180/._270，原始值即角度。

​

变更

• LocalVideoTrack.pushFrame(_:rotation:timestampNs:)与VideoFrame.rotation的类型由底层 WebRTC 类型改为VideoRotation；
• Track.rtcTrack不再对外公开。需要感知轨道与底层媒体对象绑定完成时，改用trackDidBindRtcTrack事件；
• 公开 API 不再出现任何底层 WebRTC 类型，接入方无需 import WebRTC 相关模块。

​

[1.0.0] - 2026.08.02

​

新增

• 首个正式版本，以预编译 XCFramework 形式通过 Swift Package Manager 分发，包含 iOS 真机、iOS 模拟器、macOS 三个平台切片；
• SDK 主入口类为SRTCEngine。