更新日志

​

[1.6.0] - 2026.10.30

​

新增

• 自己的音量也走 didChangeActiveSpeakers：快照里新增本端那一条，ActiveSpeakerInfo.isLocal 为 true，trackId 是本端发布的音频轨。只在已发布音频、没有静音且确实在说话时出现，与对端听到的一致。以前「我」的音量只能自己实现 AudioProcessor、挂到 audioCaptureProcessor 上从采集数据算，现在不需要了。
• SRTCEngine.activeSpeakerOptions（ActiveSpeakerOptions）：includeLocal（默认 true，关掉即回到只含远端）、interval（本端采样间隔，默认 0.5 秒，加入频道时读取）、silenceThreshold（本端静默门限，默认 0.01）。

​

变更

• 远端与自己同一量纲，一个阈值即可：本端由 SDK 按服务端判定说话人的同一算法计算，level 与远端一样按 1/8 分档（0.125、0.25 …）。
• 网宿（CDN）频道里远端 level 的口径变了：以前取的是接收统计里的峰值音量，同一段语音比 SeaStart 频道大两三倍、且不分档；现在与 SeaStart 一致。按数值写死阈值的接入方请重新核对（例如原先用 0.3 判断「大声说话」，现在同样的声音约为 0.125～0.25）。网宿频道的远端说话人仍只覆盖已订阅的音频。
• audioCaptureProcessor 仍完全留给业务：SDK 的电平计量与它串在同一条链上（先跑你的处理器、再量电平），设置或清空它都不会影响快照里自己的音量。

​

[1.5.5] - 2026.10.27

​

新增

• 建轨时可指定轨道 ID：createLocalCustomVideoTrack(desc:trackId:)、createLocalScreenTrack(preset:audioPreset:mode:trackId:)，以及 macOS 带采集源的 createLocalScreenTrack(source:...:trackId:)。用于同一路画面先后换采集源（例如视图录制与屏幕共享轮流发布）时保持轨道 ID 不变。网宿 CDN 的流名由轨道 ID 决定，云端录制只拉开录时的那一路流，ID 一换就会在约 30～45 秒后报「检测到推流中断了」并停止录制。原有建轨接口不变，仍随机生成 ID。

​

变更

• 同一个轨道 ID 同时只能有一个对象在发布：另一个对象仍在发布时再调用 publishLocalTrack 抛 invalidState，不再悄悄顶掉前一个。
• 取消发布按对象身份判断：对已被同 ID 新轨道替换的旧对象调用 unpublishLocalTrack 直接返回，不会把正在发布的新轨道一起摘掉。

​

[1.5.4] - 2026.10.24

​

修复

• 切换前后置摄像头后 LocalCameraTrack.isFrontCamera 不更新：旧版 switchCamera() 只切了底层采集，轨道上的前后置状态停在开摄像头时的值，切到后置仍报前置。由此带来三个问题：业务层按 isFrontCamera 回填的前后置按钮不跟着变；isMirrored 仍为 true，后置摄像头的本地预览也被左右镜像；mute() 后再 unmute()（或 restartCapture()）会按旧状态重启采集，切到后置后关开一次摄像头会悄悄回到前置。现在切换完成后轨道状态随之更新，镜像随前后置自动切换。
• changeDeviceId(_:) 后同样回写：按设备 ID 切换摄像头后，captureOptions.deviceId 与前后置（iOS 按实际打开的摄像头）随之更新，镜像状态同步刷新。

​

[1.5.3] - 2026.10.10

​

新增

• 频道级 MCU 合成视频订阅：Channel.subscribeRemoteVideoMcuTrack() / unsubscribeRemoteVideoMcuTrack() / remoteVideoMcuTrack 与 RemoteVideoMcuTrack。服务端合成任务以保留身份 __mcu__ 发布合成流，这个身份不在频道成员列表里，subscribeRemoteVideoTrack(uid:trackId:) 找不到它；新接口按保留标识直接订阅，重复调用返回同一轨道。收流超时 / 恢复照常经 didChangeReceiveStreamStatus 上报，uid 为 "__mcu__"。网宿 CDN 引擎同样支持（拉 rtc_v_channel_{频道} 流）。

​

[1.5.2] - 2026.10.10

​

修复

• iOS 通话音频会话被外部改掉后可以自愈：SDK 占用通话音频会话期间，如果宿主 App 自己把会话类别改成了别的（常见于后台保活、播放提示音时设成 .playback），录音链路会当场停掉、状态栏橙色麦克风指示点消失，而且之后再开麦也救不回来，这一场的麦克风一直无声。现在再次开麦或再次入会时，SDK 会检查类别是否被外部顶走，是则重新下发通话配置并拉起录音。
• 离会后不再上报音频路由变化：离会时 SDK 把音频会话还给系统，系统随即把输出从听筒切回扬声器，旧版仍会补发一次路由变化回调，宿主据此弹出「已切换为扬声器模式」之类的提示。现在未占用音频通道时不再回调；.oldDeviceUnavailable（如拔耳机）后的回落重设照常执行。

​

[1.5.1] - 2026.10.01

​

修复

• AudioRoute.displayName / AudioRouteTarget.displayName 按系统语言返回中文或英文：此前一律返回中文（「扬声器」「听筒」等），英文系统的 App 直接拿来显示就会在英文界面里夹着中文。现在系统首选语言以 zh 开头（zh-Hans / zh-Hant / zh-HK 等）时返回中文，其余返回英文（Speaker、Earpiece、Bluetooth headset、Wired headset、Unknown route）。它是给终端用户看的文案，只跟随系统语言，不受 SRTCEngine.language 影响。

​

[1.5.0] - 2026.09.30

​

新增

• SRTCEngine.language（String?，BCP 47 语言标签，如 "en"、"zh-CN"；nil = 跟随系统语言）与只读的 currentLanguage（实际生效的语言：已设置取设置值，否则取系统首选语言，取不到为 "zh"）。SDK 请求后端时带上 Accept-Language，后端返回的业务错误（码 1000–99999）文案随之中 / 英；SDK 自身的报错一律英文，不受它影响。与 logLevel 一样是进程级全局设置，建议在 joinChannel / enableIm 之前设置。
• SRTCError.baseCode：低 3 位语义码，跨端统一（如 231 = 无摄像头权限），便于与 Web / Android / 鸿蒙端对照；后端业务码返回自身。
• SRTCError 实现 CustomNSError：桥接成 NSError 后 domain = "cn.seastart.srtc"、code 为完整码（如 103231），ObjC / uni-app / Flutter 等走 NSError 的集成方可直接按码判断。
• 新增错误 case：cameraPermissionDenied（231）、microphonePermissionDenied（251）、screenShareDenied(_:underlying:)（039，underlying 为系统原始错误，桥接后放在 NSUnderlyingErrorKey）、invalidArgument（031）、userNotFound（204）、featureNotSupported（032）、cameraFormatUnavailable（242）、publishFailed（300）、subscribeFailed（301）。
• SRTCBroadcastKit（本次 1.0.13）：结束广播时的系统弹窗文案按系统语言出中文或英文；子类可重写 SRTCBroadcastSampleHandler.finishMessage(for:) 自定义文案（参数为新增的结束原因枚举 SRTCBroadcastFinishReason），内置中英文案可通过 builtinFinishMessage(for:language:) 取用。

​

变更

• 报错文案全部改为英文：SRTCError.message / localizedDescription（格式仍为 "<code>: <message>"）以及拼进报错里的参数说明、BroadcastError 描述、screenBroadcastDidFinish 的 reason 均改为英文。它们是给开发者和日志看的，给终端用户的提示请按 code / baseCode 自行映射，不要直接展示 message。
• HTTP 状态码不再拼进错误码：此前 HTTP 非 200 会报成 103<HTTP 状态>（如 103502），与其它低位码撞号；现在一律报 apiRequestFailed → 103006，HTTP 状态只放在关联值 statusCode 和描述里。
• 麦克风无权限开麦会抛错：此前采集「成功」但发出去的是静音，现在抛 microphonePermissionDenied（103251）。
• 心跳遇到 HTTP 非 200 / 网络失败不再离会：只有后端业务错误（码 1000–99999，如被踢出、会话失效）才离会，网关 502 / 504 之类的临时错误改为继续等待重连。
• SRTCUniBridge 回调的错误码不再出现 -1：非 SRTCError 的错误归一为 006（网络）/ 026（取消）/ 025（内部错误）。

​

旧码 → 新码对照

iOS 前缀为 103、macOS 为 105，下表以 iOS 为例（macOS 把前缀换成 105）。 后端业务码（1000–99999）仍原样透传，不加前缀，数值不变；其文案现在随 language 返回中文或英文。

​

[1.4.7] - 2026.09.23

​

修复

• 未知 device_type 不再让整份成员列表解析失败：后端新增端侧类型的节奏不受 SDK 发版控制，而此前 channel/detail 的 users 里只要有一条 device_type 超出本版本的枚举，整个响应就解不出来、入会直接失败（报 The data couldn't be read...）——等于一个陌生端进会就能把所有老版本客户端挡在门外。现在 DeviceType 补齐了 unknown 与 80–89 服务端代理号段（MCU/SIP/H.323/GB28181/RTSP/RTMP/文件播放/流分发/语音转写），users 改为逐条解析、跳过解不出的那条。
• SFU 逐条拒绝的订阅不再静默失败：sfu/subscribe 对单条轨道的拒绝是放在 HTTP 200 + code:0 的响应体里（failed 字段）而不是抛错，因此外层重试一次都不会触发，而调用侧的 subscribe() 早已返回成功。这一路订阅之后再也救不回来：内部登记还挂着会短路重订，收流超时又是边沿事件、从没建立起来的订阅不产生边沿，表现为远端画面永久停在最后一帧或黑屏。现在按轨道指数退避重投 5 次（约 6 秒），用尽后撤销内部订阅登记，把重订的权利交还业务层。

​

变更

• UserInfo.deviceType 语义调整：nil 现在表示「本 SDK 不认识这个端」，不再只是「对端没上报」。按端型分支的业务代码请把 nil 当作未知端处理，不要当成缺省端型。

​

[1.4.6] - 2026.09.23

​

修复

• 摄像头采集方向跟随界面方向，设备平放不再回落竖屏：此前设备平放在桌面上（faceUp / faceDown）或方向未知时，一律按竖屏处理，于是锁定横屏的 App 里，把设备放到桌上就会突然推出一路竖画面，对端只能在横向窗口里看到上下加黑边的画面——即业务侧反馈的「横竖屏采集画面自己切来切去」。现在优先按 UIWindowScene.interfaceOrientation 解析（宿主锁横屏时它恒为横向），取不到才退回设备方向；平放与未知方向维持上一次有效方向，不再回落竖屏。
• 横屏屏幕共享画面倒 180°：ReplayKit 在 RPVideoSampleOrientationKey 里给的是 CGImagePropertyOrientation（描述「这一帧怎么摆才是正的」），而 SDK 内部的 VideoRotation 描述的是「接收端要顺时针转多少度」，两者方向相反。此前把 right / left 当作同向直接映射，导致两种横屏都差 180°，表现为老师横屏发起屏幕共享、学生看到的画面是倒的。现已修正映射关系。

​

[1.4.5] - 2026.09.18

​

新增

• 远端视频收流超时 / 恢复检测：新增 ChannelDelegate 的 channel(_:didChangeReceiveStreamStatus:) 回调与 ReceiveStreamStatus（uid / trackId / trackDesc / timedOut），另有 RemoteVideoTrack.isReceiveTimedOut 可随时查询。按轨道判定：订阅之后连续一段时间没收到该路视频帧即判超时，帧一恢复立即再报一次，用来驱动画面上的「加载中 / 对方网络异常」指示。订阅后首帧到达时会先收到一次 timedOut == false，据此关掉初始 loading。对应老 RTCEngineKit 的 engineChannel:onReceiveStreamStatusChange:trackId:status:，timedOut 与老版 status 真假值一致（true 为超时），迁移不需要取反。
• 音频单元启停：新增 AudioRouteSession.setAudioModuleEnabled(_:) 与 isAudioModuleEnabled（iOS）。录像直播课这类纯本地播放场景可以停掉 VoIP 语音处理单元，避免它压低 AVPlayer 的播放音量。

​

[1.4.4] - 2026.09.15

​

变更

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

​

[1.4.3] - 2026.09.14

​

新增

• 网宿(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

​

修复

• 网宿(CDN) 频道下ChannelDelegate.didChangeActiveSpeakers不再触发：活跃说话人此前只有 SeaStart(SFU) 引擎有数据（由服务端通过信令通道下发），CDN 链路上没有该通道，导致同一个对外回调在 网宿频道里恒不触发，业务据此绘制的音量条、发言人提示会静默失效且无任何报错。现在 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。