媒体控制 - STMLink 文档

本页接口都挂在 SMeetingEngine 上。使用说明见媒体控制与视频渲染。 NativeVideoView 是 SDK 为渲染视图定义的别名，实际类型是 SRTC 的 SRTCVideoRenderer。

摄像头

`requestOpenCamera(view:deviceId:preset:byAdmin:adminUid:)`

打开摄像头：向会议申请 → 开始采集 → 发布。

let track = try await meeting.requestOpenCamera()

参数名	类型	必填	说明
`view`	`NativeVideoView?`	否	本地预览视图。SwiftUI 传 `nil`，改用 `SRTCVideoView(track:)`
`deviceId`	`String?`	否	指定摄像头，取自 `getDevices(kind: .videoInput)`；不传用默认设备
`preset`	`CameraPreset`	否	采集预设，默认 `.h720p`
`byAdmin`	`Bool`	否	是否在响应主持人的开启邀请，默认 `false`
`adminUid`	`String?`	否	发起邀请的主持人 ID，`byAdmin` 为 `true` 时必须一起传

返回值： LocalCameraTrack（可忽略，也可随时读 meeting.cameraTrack） 可能抛出：

SMeetingError.unauthorized —— 房间全体禁画且禁止自我解除，且你不是主持人 / 联席主持人
SMeetingError.apiError(code:message:)
采集或发布失败时的底层错误（此时 SDK 已自动回滚，无需你再调 closeCamera()）

已经打开时重复调用不会重复起流；如果传入了不同的 deviceId，会切到目标设备。

`closeCamera()`

await meeting.closeCamera()

返回值： 无，不抛错。会取消发布、移除渲染视图、停止采集，并上报 userCameraStateDidChange。

`switchCamera(deviceId:)`

try await meeting.switchCamera()                     // iOS 前后摄互切
try await meeting.switchCamera(deviceId: deviceId)   // 切到指定设备

参数名	类型	必填	说明
`deviceId`	`String?`	否	目标摄像头；不传时在 iOS 上做前后摄互切

返回值： 无 可能抛出： SMeetingError.deviceError(_:) —— 摄像头尚未开启

麦克风

`requestOpenMic(deviceId:preset:byAdmin:adminUid:)`

try await meeting.requestOpenMic()

参数名	类型	必填	说明
`deviceId`	`String?`	否	指定麦克风，取自 `getDevices(kind: .audioInput)`
`preset`	`MicPreset`	否	采集预设，默认 `.music`
`byAdmin`	`Bool`	否	是否在响应主持人的开启邀请，默认 `false`
`adminUid`	`String?`	否	发起邀请的主持人 ID

返回值： 无 可能抛出：

SMeetingError.unauthorized —— 房间全体静音且禁止自我解除，且你不是主持人 / 联席主持人
SMeetingError.apiError(code:message:)
采集或发布失败时的底层错误（SDK 会自动回滚）

`closeMic()`

await meeting.closeMic()

返回值： 无，不抛错。会取消发布、停止采集，并上报 userMicStateDidChange。

屏幕共享

1.3.5 变更：requestShare 已移除 messageOnly 参数及对应模式。需要仅广播共享状态时，请使用 requestShare(shareType: .whiteBoard)；屏幕共享仍会执行正常的媒体采集与发布。旧代码中的 messageOnly: true 需要删除或改用白板共享。

`requestShare(shareType:preset:view:byAdmin:adminUid:)`

try await meeting.requestShare()

参数名	类型	必填	说明
`shareType`	`ShareType`	否	`.screen`（默认）或 `.whiteBoard`
`preset`	`ScreenPreset`	否	采集预设，默认 `.h1080p`
`view`	`NativeVideoView?`	否	本地预览视图
`byAdmin`	`Bool`	否	是否在响应主持人的开启邀请，默认 `false`
`adminUid`	`String?`	否	发起邀请的主持人 ID

返回值： 无 可能抛出：

SMeetingError.unauthorized —— 房间禁共享且你不是主持人 / 联席主持人
SMeetingError.internalError(_:) —— 本端已在共享
SMeetingError.apiError(code:message:)
采集失败（例如用户拒绝屏幕录制授权）时的底层错误

shareType 为 .whiteBoard 时不创建媒体流，只广播共享状态并触发 roomShareDidStart。

`requestShare(source:preset:view:byAdmin:adminUid:excludedWindowIds:excludesCurrentApplication:)`

指定采集源的重载，仅 macOS 12.3 及以上。

let displays = try await ScreenCaptureSources.availableDisplays()
try await meeting.requestShare(source: displays[0])

// 整屏共享，同时挖掉会中窗口（否则同机自测时形成无限镜像）
let ids = NSApplication.shared.windows
    .filter { $0.isVisible && $0.windowNumber > 0 }
    .map { UInt32($0.windowNumber) }
try await meeting.requestShare(source: displays[0], excludedWindowIds: ids)

参数名	类型	必填	说明
`source`	`ScreenCaptureSource`	是	`DisplaySource`（显示器）或 `WindowSource`（应用窗口）
`preset`	`ScreenPreset`	否	采集预设，默认 `.h1080p`
`view`	`NativeVideoView?`	否	本地预览视图
`byAdmin`	`Bool`	否	是否在响应主持人的开启邀请
`adminUid`	`String?`	否	发起邀请的主持人 ID
`excludedWindowIds`	`[UInt32]`	否	整屏共享时要挖掉的自家窗口，取值 `UInt32(NSWindow.windowNumber)`；采集单个窗口时无意义。默认 `[]`
`excludesCurrentApplication`	`Bool`	否	置 `true` 回到「整个 App 都不共享」的旧行为，此时 `excludedWindowIds` 被忽略。默认 `false`

返回值： 无 可能抛出： 同上一个重载。

自 1.3.2（SRTC 1.4.2）起，整屏共享默认包含本 App 自己的窗口。会中主窗口通常正在渲染远端画面，界面上若有共享预览、或同机双开自测，务必把这些窗口放进 excludedWindowIds，否则形成无限镜像。

`stopShare()`

await meeting.stopShare()

返回值： 无，不抛错。

视图录制

以下接口自 1.3.4 起可用。调用方负责将视图渲染为 CVPixelBuffer 并持续推帧，SDK 只负责创建和发布视频轨道，不负责截取视图或保存本地录制文件。

`startViewCaptureShare()`

public func startViewCaptureShare() async throws -> LocalVideoTrack

参数： 无。 返回值： 已发布的 LocalVideoTrack，轨道描述为 screen，降级策略为保持分辨率。重复调用返回已有轨道。 可能抛出：

SMeetingError.notInMeeting —— 尚未加入会议。
SMeetingError.internalError(_:) —— 屏幕共享轨道已存在，包括已准备但尚未发布的广播监听轨道。
底层轨道发布错误。

该接口直接发布媒体轨道，不执行 requestShare() 的会议后端申请及共享状态通知流程。调用方应按自己的业务管理共享状态，并保证视图录制与屏幕共享互斥；需要切换到屏幕共享时，先停止视图录制。

`stopViewCaptureShare()`

public func stopViewCaptureShare() async

参数： 无。 返回值： 无，不抛错。尝试取消发布并清除轨道及其渲染器，不关闭或取消发布麦克风轨道。调用方同时停止推帧。视图录制应通过此接口结束，不能用 stopShare() 代替。

iOS 全屏共享

以下接口仅 iOS 可用，用于共享整个系统屏幕（requestShare() 在 iOS 上只能采到本 App 画面）。需要先集成 Broadcast Upload Extension，完整步骤见屏幕共享。

`prepareBroadcastShare(appGroup:preset:)`

try await meeting.prepareBroadcastShare(appGroup: "group.your.app")

参数名	类型	必填	说明
`appGroup`	`String`	是	宿主与扩展共用的 App Group ID
`preset`	`ScreenPreset`	否	采集预设，默认 `.h1080p`

挂起全屏采集的监听，等用户从系统 UI 发起广播。不通知会议后端、不发布轨道 —— 此刻共享还没开始。入会后调用即可，已在监听或已在共享时幂等返回。 返回值： 无 可能抛出： 采集监听建立失败时的底层错误（如 App Group 配置不正确）。

`publishBroadcastShare(view:byAdmin:adminUid:)`

try await meeting.publishBroadcastShare()

参数名	类型	必填	说明
`view`	`NativeVideoView?`	否	本地预览视图，通常不需要
`byAdmin`	`Bool`	否	是否在响应主持人的开启邀请，默认 `false`
`adminUid`	`String?`	否	发起邀请的主持人 ID

把已经在出帧的全屏采集发布到会议（后端 + 频道）。在收到 shareBroadcastDidStart 之后调用 —— 那才是用户真的开始共享的时刻。已发布时幂等返回。 返回值： 无 可能抛出：

SMeetingError.internalError(_:) —— 尚未调用 prepareBroadcastShare
SMeetingError.unauthorized —— 房间禁共享且你不是主持人 / 联席主持人
SMeetingError.apiError(code:message:)

发布失败时 SDK 会自动回滚共享状态。

`stopBroadcastListening()`

await meeting.stopBroadcastListening()

停止监听全屏采集。正在共享中调用等同于 stopShare()，并且之后不会再自动重新挂上监听。exitRoom() 会自动调用它。 返回值： 无，不抛错。

`requestShare(broadcastAppGroup:preset:view:byAdmin:adminUid:)`

try await meeting.requestShare(broadcastAppGroup: "group.your.app")

一步到位版：建立监听的同时就对会议宣布共享。

用户可能根本不点系统胶囊，那时会议里会挂着一个没有画面的共享标记，需要你自己超时撤回。会议类场景请用 prepareBroadcastShare + publishBroadcastShare，本重载只为「不关心中间态」的简单集成保留。

`isShareBroadcastActive`

if meeting.isShareBroadcastActive { /* 屏幕正在出帧 */ }

类型： Bool（只读） iOS 全屏共享当前是否真的在出帧。prepareBroadcastShare 之后本属性仍为 false，直到用户在系统胶囊里点了「开始直播」。应用内采集模式恒为 false。

远端视频

`subscribeRemoteVideoTrack(uid:trackDesc:)`

订阅远端视频轨道，不绑定渲染视图。

let track = try await meeting.subscribeRemoteVideoTrack(uid: uid, trackDesc: .cameraBig)

参数名	类型	必填	说明
`uid`	`String`	是	远端成员 ID
`trackDesc`	`TrackDesc`	是	轨道描述，例如 `.cameraBig`、`.screen`

返回值： RemoteVideoTrack 可能抛出：

SMeetingError.notInMeeting
SMeetingError.internalError(_:) —— 该成员没有这一路轨道

`unsubscribeRemoteVideoTrack(uid:trackDesc:)`

无条件取消订阅，不考虑是否还有渲染视图在用。

参数名	类型	必填	说明
`uid`	`String`	是	远端成员 ID
`trackDesc`	`TrackDesc`	是	轨道描述

返回值： 无 可能抛出： SMeetingError.notInMeeting。轨道不存在时静默返回。

`startPlayRemoteVideo(view:uid:trackDesc:)`

订阅并把画面绑定到传入的渲染视图，适合 UIKit / AppKit。

参数名	类型	必填	说明
`view`	`NativeVideoView`	是	已挂在视图层级上的渲染视图
`uid`	`String`	是	远端成员 ID
`trackDesc`	`TrackDesc`	是	轨道描述

返回值： RemoteVideoTrack 可能抛出： 同 subscribeRemoteVideoTrack(uid:trackDesc:)

`stopPlayRemoteVideo(view:uid:trackDesc:)`

解绑渲染视图。只有当这路轨道上已经没有任何渲染视图时才会真正取消订阅。

参数名	类型	必填	说明
`view`	`NativeVideoView`	是	要解绑的渲染视图
`uid`	`String`	是	远端成员 ID
`trackDesc`	`TrackDesc`	是	轨道描述

返回值： 无 可能抛出： SMeetingError.notInMeeting

远端音频

进入会议时远端音频已自动订阅，以下接口用于需要精细控制的场景。

`subscribeRemoteAudioTrack(uid:trackDesc:)`

参数名	类型	必填	说明
`uid`	`String`	是	远端成员 ID
`trackDesc`	`TrackDesc`	否	默认 `.mic`

返回值： 无 可能抛出： SMeetingError.notInMeeting、SMeetingError.internalError(_:)

`unsubscribeRemoteAudioTrack(uid:trackDesc:)`

参数同上。轨道不存在时静默返回。

`toggleRemoteAudioMute(_:)`

远端音频播放总开关，只切播放不改订阅关系。

meeting.toggleRemoteAudioMute(true)   // 静音

参数名	类型	必填	说明
`mute`	`Bool`	是	`true` 静音，`false` 恢复播放

返回值： 无，不抛错。

合屏画面（MCU）

`startPlayRemoteVideoMcu(view:uid:)`

订阅并播放服务端合成画面。需要服务端已配置合屏任务。

参数名	类型	必填	说明
`view`	`NativeVideoView`	是	渲染视图
`uid`	`String`	是	合成画面对应的用户 ID

返回值： RemoteVideoTrack 可能抛出： SMeetingError.notInMeeting、SMeetingError.internalError(_:)（未找到合成画面轨道）

`stopPlayRemoteVideoMcu(view:)`

参数名	类型	必填	说明
`view`	`NativeVideoView`	是	之前传入的渲染视图

返回值： 无

​摄像头

​requestOpenCamera(view:deviceId:preset:byAdmin:adminUid:)

​closeCamera()

​switchCamera(deviceId:)

​麦克风

​requestOpenMic(deviceId:preset:byAdmin:adminUid:)

​closeMic()

​屏幕共享

​requestShare(shareType:preset:view:byAdmin:adminUid:)

​requestShare(source:preset:view:byAdmin:adminUid:excludedWindowIds:excludesCurrentApplication:)

​stopShare()

​视图录制

​startViewCaptureShare()

​stopViewCaptureShare()

​iOS 全屏共享

​prepareBroadcastShare(appGroup:preset:)

​publishBroadcastShare(view:byAdmin:adminUid:)

​stopBroadcastListening()

​requestShare(broadcastAppGroup:preset:view:byAdmin:adminUid:)

​isShareBroadcastActive

​远端视频

​subscribeRemoteVideoTrack(uid:trackDesc:)

​unsubscribeRemoteVideoTrack(uid:trackDesc:)

​startPlayRemoteVideo(view:uid:trackDesc:)

​stopPlayRemoteVideo(view:uid:trackDesc:)

​远端音频

​subscribeRemoteAudioTrack(uid:trackDesc:)

​unsubscribeRemoteAudioTrack(uid:trackDesc:)

​toggleRemoteAudioMute(_:)

​合屏画面（MCU）

​startPlayRemoteVideoMcu(view:uid:)

​stopPlayRemoteVideoMcu(view:)

​相关页面

摄像头

`requestOpenCamera(view:deviceId:preset:byAdmin:adminUid:)`

`closeCamera()`

`switchCamera(deviceId:)`

麦克风

`requestOpenMic(deviceId:preset:byAdmin:adminUid:)`

`closeMic()`

屏幕共享

`requestShare(shareType:preset:view:byAdmin:adminUid:)`

`requestShare(source:preset:view:byAdmin:adminUid:excludedWindowIds:excludesCurrentApplication:)`

`stopShare()`

视图录制

`startViewCaptureShare()`

`stopViewCaptureShare()`

iOS 全屏共享

`prepareBroadcastShare(appGroup:preset:)`

`publishBroadcastShare(view:byAdmin:adminUid:)`

`stopBroadcastListening()`

`requestShare(broadcastAppGroup:preset:view:byAdmin:adminUid:)`

`isShareBroadcastActive`

远端视频

`subscribeRemoteVideoTrack(uid:trackDesc:)`

`unsubscribeRemoteVideoTrack(uid:trackDesc:)`

`startPlayRemoteVideo(view:uid:trackDesc:)`

`stopPlayRemoteVideo(view:uid:trackDesc:)`

远端音频

`subscribeRemoteAudioTrack(uid:trackDesc:)`

`unsubscribeRemoteAudioTrack(uid:trackDesc:)`

`toggleRemoteAudioMute(_:)`

合屏画面（MCU）

`startPlayRemoteVideoMcu(view:uid:)`

`stopPlayRemoteVideoMcu(view:)`

相关页面