SRTCEngine

SRTCEngine 是 Swift SDK 的主入口，负责加入频道、离开频道、创建本地轨道以及配置日志和音频处理器。

初始化

`init()`

创建一个 SDK 实例，并完成底层 WebRTC 初始化。

let srtc = SRTCEngine()

属性

`logLevel`

设置 SDK 日志级别。

参数名	类型	必填	说明
`logLevel`	`LogLevel`	否	可选值包括 `debug`、`info`、`warning`、`error`

示例：

srtc.logLevel = .debug

`language`

SDK 语言，类型 String?（BCP 47 语言标签，如 "en"、"zh-CN"），默认 nil = 跟随系统语言。自 1.5.0 起提供。只影响请求后端时的 Accept-Language 头，即后端业务错误（码 1000–99999）文案的语言；SDK 自身的报错（SRTCError.message）一律英文，不随它变化。与 logLevel 一样是进程级全局设置，建议在 joinChannel / enableIm 之前设置。

srtc.language = "en"

`currentLanguage`

当前实际生效的语言，类型 String，只读：language 已设置则为它，否则为系统首选语言，取不到时为 "zh"。自 1.5.0 起提供。错误码与处理方式见错误码。

`audioCaptureProcessor`

麦克风采集后的音频处理器，可用于变声、降噪等处理。全局只有一个，SDK 自身的本端电平计量串在它之后，两者互不影响。自 1.6.0 起不需要再用它算自己的音量，见 activeSpeakerOptions。

`activeSpeakerOptions`

ActiveSpeakerOptions，didChangeActiveSpeakers 快照里「自己」那一条的参数，自 1.6.0 起提供：includeLocal（默认 true）、interval（本端采样间隔，默认 0.5 秒，加入频道时读取）、silenceThreshold（默认 0.01）。详见通话质量与活跃说话人。

`audioRenderProcessor`

远端音频播放前处理器，可用于播放侧音频增强。

`channels`

已加入且仍存活的频道列表（[Channel]），按加入先后排序。空数组表示不在任何频道中。

`defaultChannel`

默认频道（Channel?）：最早加入且仍存活的那个，它离会后顺延到下一个。无参的 leaveChannel() 作用于它。详见多频道。

方法

`joinChannel(token:options:)`

加入频道并返回 Channel 实例。可多次调用以同时加入多个频道，各频道的发布、订阅、成员与事件互不干扰，仅当同一频道名已加入（或正在加入中）时抛 alreadyJoined。

let channel = try await srtc.joinChannel(
    token: token,
    options: JoinOptions(autoSubscribeAudio: true)
)

参数名	类型	必填	说明
`token`	`String`	是	Base64 编码的频道 Token
`options`	`JoinOptions`	否	加入选项，默认 `JoinOptions()`

返回值： Channel 可能抛出：

SRTCError.alreadyJoined
SRTCError.tokenExpired
SRTCError.tokenInvalid
其他网络、信令、流媒体连接错误

`leaveChannel()`

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

await srtc.leaveChannel()

如果当前没有已加入的频道，调用会被安全忽略。

`leaveChannel(_:)`

离开指定频道，等价于 channel.leave()，其它频道不受影响。多频道下建议用这个版本，避免「默认频道顺延」带来的歧义。

await srtc.leaveChannel(groupChannel)

参数名	类型	必填	说明
`channel`	`Channel`	是	要离开的频道

`createLocalMicTrack(preset:)`

创建本地麦克风轨道。

let micTrack = srtc.createLocalMicTrack(preset: .music)

参数名	类型	必填	说明
`preset`	`MicPreset`	否	默认 `.music`

返回值： LocalMicTrack

`createLocalCameraTrack(preset:)`

创建本地摄像头轨道。

let cameraTrack = srtc.createLocalCameraTrack(preset: .h720p)

参数名	类型	必填	说明
`preset`	`CameraPreset`	否	默认 `.h720p`

返回值： LocalCameraTrack

`createLocalScreenTrack(preset:audioPreset:mode:)`

创建本地屏幕共享轨道。

let screenTrack = srtc.createLocalScreenTrack(
    preset: .h1080p,
    audioPreset: .default
)

// iOS 全屏采集（需先集成 Broadcast Upload Extension）
let fullScreen = srtc.createLocalScreenTrack(
    preset: .h720p,
    mode: .broadcast(appGroup: "group.your.app.group")
)

参数名	类型	必填	说明
`preset`	`ScreenPreset`	否	屏幕共享视频预设，默认 `.h1080p`
`audioPreset`	`ScreenAudioPreset?`	否	macOS 下可用于开启屏幕音频
`mode`	`ScreenCaptureMode`	否	仅 iOS 有效，默认 `.inApp`（应用内采集）；`.broadcast(appGroup:)` 为全屏采集，见屏幕共享

返回值： LocalScreenTrack

iOS 全屏采集下 startCapture() 成功只代表 SDK 开始监听，画面要等用户从系统 UI 发起广播后才会传输，真正的开始 / 结束通过 TrackDelegate.screenBroadcastDidStart / screenBroadcastDidFinish(_:reason:) 通知。

`createLocalScreenTrack(source:preset:audioPreset:excludedWindowIds:excludesCurrentApplication:)`

macOS 12.3+ 专用重载，用于指定显示器或窗口源。

let track = srtc.createLocalScreenTrack(
    source: selectedSource,
    preset: .h1080p,
    audioPreset: .default
)

// 共享整屏，同时挖掉自家正在渲染这路画面的窗口
let previewWindowIds = NSApplication.shared.windows
    .filter { $0.isVisible && $0.identifier?.rawValue == "meeting-room" }
    .map { UInt32($0.windowNumber) }
let shared = srtc.createLocalScreenTrack(
    source: display,
    excludedWindowIds: previewWindowIds
)

参数名	类型	必填	说明
`source`	`ScreenCaptureSource?`	否	`DisplaySource` 或 `WindowSource`，为空时默认主显示器
`preset`	`ScreenPreset`	否	默认 `.h1080p`
`audioPreset`	`ScreenAudioPreset?`	否	是否采集系统音频
`excludedWindowIds`	`[UInt32]`	否	整屏共享时要挖掉的自家窗口，取值 `UInt32(NSWindow.windowNumber)`；采集单个窗口时无意义。默认 `[]`
`excludesCurrentApplication`	`Bool`	否	置 `true` 回到「整个 App 都不共享」的旧行为，此时 `excludedWindowIds` 被忽略。默认 `false`

返回值： LocalScreenTrack

自 1.4.2 起，整屏共享默认包含本 App 自己的窗口。凡是会渲染这路共享画面的窗口都要放进 excludedWindowIds，否则形成无限镜像。窗口列表在 startCapture() 时快照一次，之后新开的窗口一律进画面。

`createLocalCustomVideoTrack(desc:)`

创建自定义视频轨道，适合外部推帧场景。

let customVideoTrack = srtc.createLocalCustomVideoTrack(desc: "canvas")

参数名	类型	必填	说明
`desc`	`String`	否	轨道描述，默认 `"custom"`

返回值： LocalVideoTrack 调用后可通过 pushFrame(...) 注入 CVPixelBuffer。

指定轨道 ID 建轨（1.5.5 起）

createLocalCustomVideoTrack(desc:trackId:)、createLocalScreenTrack(preset:audioPreset:mode:trackId:)，以及 macOS 的 createLocalScreenTrack(source:preset:audioPreset:excludedWindowIds:excludesCurrentApplication:trackId:)，与同名的原接口相同，只是多一个 trackId: String 参数，用它作为轨道 ID，不再随机生成。适用于「同一路画面先后换采集源」：几条轨道对象各自采集、先后互斥发布，但对外始终是同一个轨道 ID。网宿 CDN 的流名由轨道 ID 决定，云端录制只拉开录时的那一路流，换了 ID，录制会判定推流中断；同 ID 先取消发布再发布则不受影响。

let id = UUID().uuidString
let viewTrack = srtc.createLocalCustomVideoTrack(desc: "screen", trackId: id)
let screenTrack = srtc.createLocalScreenTrack(preset: .h1080p, trackId: id)
// viewTrack 取消发布之后再发布 screenTrack，二者不能同时发布

参数名	类型	必填	说明
`trackId`	`String`	是	轨道 ID

同一时刻只能发布同一 ID 的其中一个对象：另一个还在发布时调用 publishLocalTrack 会抛 invalidState。取消发布只对当前正在发布的那个对象生效，对已被替换的旧对象调用 unpublishLocalTrack 直接返回，不影响新轨道。

`createLocalCustomAudioTrack(desc:)`

创建自定义音频轨道，适合外部 PCM 输入场景。

let customAudioTrack = srtc.createLocalCustomAudioTrack(desc: "bgm")

参数名	类型	必填	说明
`desc`	`String`	否	轨道描述，默认 `"custom"`

返回值： LocalAudioTrack 调用后可通过 pushAudioBuffer(...) 注入 AVAudioPCMBuffer。

视频前处理

`defaultVideoProcessors`

默认视频处理器管线。在这里配一次，此后每条新建的摄像头轨道自动带上。

srtc.defaultVideoProcessors = [myProcessor]

参数名	类型	必填	说明
`defaultVideoProcessors`	`[VideoProcessor]`	否	默认为空

摄像头轨道每次开摄像头都是新建的（关摄像头即销毁），只在轨道上设一次，下次开摄像头效果就没了 —— 这个属性就是为此存在。只影响此后新建的轨道，不追溯已存在的轨道；自定义视频轨道不受影响（那条路的帧由业务方 pushFrame，要不要过处理器自己决定）。

虚拟背景

以下方法转发到 SRTCVirtualBackground.shared，状态整机一份。开启后自动作用于所有摄像头轨道，不需要往 videoProcessors 里挂东西。用法与调优见虚拟背景。

成员	签名	说明
装载	`installVirtualBackground(modelPath: String? = nil) throws`	加载模型 + 建推理会话，耗时百毫秒级，不要在主线程 / 采集线程调；`nil` 用内置模型
卸载	`uninstallVirtualBackground()`	释放推理会话与缓冲，不清效果参数
总开关	`enableVirtualBackground(_ enabled: Bool) throws`	关闭即零开销直通，不跑推理
开关状态	`isVirtualBackgroundEnabled: Bool`	只读
背景虚化	`setVirtualBackgroundBlur(level: Int)`	`level` 取值 1~10，默认 5，超出范围收敛到边界
背景替换	`setVirtualBackgroundImage(_ image: SRTCNativeImage?)`	按 cover 裁剪不拉伸；`nil` 回落到虚化。另有 `CGImage` 重载
推理间隔	`setVirtualBackgroundInferenceInterval(_ interval: Int)`	分割每 N 帧跑一次（合成仍每帧跑），默认 1
蒙版对齐	`setVirtualBackgroundMaskSync(_ enabled: Bool)`	默认 `false`；`interval` 为 1 时开关无区别
实例	`virtualBackground: SRTCVirtualBackground`	诊断用：`droppedFrameCount`、`isInstalled`、`effect`、`inferenceIntervalMs` 等

可能抛出： SRTCError.virtualBackgroundAlreadyInstalled、.virtualBackgroundNotInstalled、.virtualBackgroundModelNotFound(String)、.virtualBackgroundSessionFailed(String) 背景虚化与背景替换互斥，后调用的生效；两者在装载前调用也会被记住，装载完成后自动生效。

概览

Web SDK

Android SDK

Windows SDK

Swift SDK（iOS/macOS）

iOS SDK

HarmonyOS SDK

C SDK（服务端/嵌入式）

Python SDK（服务端 AI）

服务端 API

初始化

`init()`

属性

`logLevel`

`language`

`currentLanguage`

`audioCaptureProcessor`

`activeSpeakerOptions`

`audioRenderProcessor`

`channels`

`defaultChannel`

方法

`joinChannel(token:options:)`

`leaveChannel()`

`leaveChannel(_:)`

`createLocalMicTrack(preset:)`

`createLocalCameraTrack(preset:)`

`createLocalScreenTrack(preset:audioPreset:mode:)`

`createLocalScreenTrack(source:preset:audioPreset:excludedWindowIds:excludesCurrentApplication:)`

`createLocalCustomVideoTrack(desc:)`

指定轨道 ID 建轨（1.5.5 起）

`createLocalCustomAudioTrack(desc:)`

视频前处理

`defaultVideoProcessors`

虚拟背景

相关页面

​初始化

​init()

​属性

​logLevel

​language

​currentLanguage

​audioCaptureProcessor

​activeSpeakerOptions

​audioRenderProcessor

​channels

​defaultChannel

​方法

​joinChannel(token:options:)

​leaveChannel()

​leaveChannel(_:)

​createLocalMicTrack(preset:)

​createLocalCameraTrack(preset:)

​createLocalScreenTrack(preset:audioPreset:mode:)

​createLocalScreenTrack(source:preset:audioPreset:excludedWindowIds:excludesCurrentApplication:)

​createLocalCustomVideoTrack(desc:)

​指定轨道 ID 建轨（1.5.5 起）

​createLocalCustomAudioTrack(desc:)

​视频前处理

​defaultVideoProcessors

​虚拟背景

​相关页面

初始化

`init()`

属性

`logLevel`

`language`

`currentLanguage`

`audioCaptureProcessor`

`activeSpeakerOptions`

`audioRenderProcessor`

`channels`

`defaultChannel`

方法

`joinChannel(token:options:)`

`leaveChannel()`

`leaveChannel(_:)`

`createLocalMicTrack(preset:)`

`createLocalCameraTrack(preset:)`

`createLocalScreenTrack(preset:audioPreset:mode:)`

`createLocalScreenTrack(source:preset:audioPreset:excludedWindowIds:excludesCurrentApplication:)`

`createLocalCustomVideoTrack(desc:)`

指定轨道 ID 建轨（1.5.5 起）

`createLocalCustomAudioTrack(desc:)`

视频前处理

`defaultVideoProcessors`

虚拟背景

相关页面