SMeetingEngine - STMLink Docs

SMeetingEngine 是 SDK 的唯一对外入口。同一个 App 内只应创建一个实例并全局持有。本页覆盖初始化、认证、会议管理、进出会议、状态查询、会中用户操作与会议外消息。媒体相关接口见媒体控制，外设见外设，主持人与管理接口见会议管理。

初始化

`init(logLevel:)`

创建 SDK 实例。

let meeting = SMeetingEngine(logLevel: .info)

参数名	类型	必填	说明
`logLevel`	`LogLevel`	否	日志级别，默认 `.warning`。可选 `.verbose`、`.debug`、`.info`、`.warning`、`.error`、`.off`

属性

`version`

let v = SMeetingEngine.version

SDK 版本号，类型 String，静态属性。

`srtc`

底层 RTC 实例，类型 SRTCEngine。当会议层接口不足以满足需求时的逃生口。

meeting.srtc.logLevel = .debug

请始终使用这个实例，不要自行创建第二个 SRTCEngine —— 会议与底层共享同一个实例，另起一个会导致状态分裂、消息通道重复、设备被抢占。

`language`

SDK 语言，类型 String?（如 "en"、"zh-CN"），默认 nil = 跟随系统语言。自 1.4.0 起提供。与 meeting.srtc.language 是同一个进程级设置：会议层和 RTC 层请求后端都带 Accept-Language，后端业务错误（码 ≥ 1000）的文案随之返回中文或英文；SDK 自身的报错（SMeetingError.message / SRTCError.message）一律英文，不受影响。建议在 login 之前设置，之后修改对后续请求即时生效。

meeting.language = "en"

`currentLanguage`

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

`delegates`

事件委托集合，类型 MulticastDelegate<SMeetingDelegate>。弱引用多播，支持多个观察者。

meeting.delegates.add(delegate: self)
meeting.delegates.remove(delegate: self)

`currentUserId`

当前登录用户的 ID，类型 String?，未登录时为 nil。

`isInRoom`

当前是否在会议中，类型 Bool。

`cameraTrack` / `screenTrack` / `mcuTrack`

本地摄像头轨道（LocalCameraTrack?）、本地屏幕共享轨道（LocalScreenTrack?）、远端合屏轨道（RemoteVideoTrack?）。未开启对应能力时为 nil。

认证

登录会议 SDK。登录后才能调用其余接口。

try await meeting.login(token: token)

参数名	类型	必填	说明
`token`	`String`	是	业务后端签发的 meeting token

返回值： 无 可能抛出：

SMeetingError.tokenInvalid —— token 格式无法解析
SMeetingError.tokenExpired —— token 已过期
SMeetingError.apiError(code:message:) —— 服务端拒绝登录
SMeetingError.networkError(_:)

`logout()`

退出登录。若仍在会议中会先自动退出会议，并停用会议外消息通道。

await meeting.logout()

返回值： 无，不抛错。

会议管理（会前）

以下接口只要求已登录，不要求在会议中。

`createRoom(_:)`

创建会议。

var req = MeetingCreateReq(title: "项目周会", meetingMode: .normal)
req.meetingType = .instant
let (roomNo, meetingId) = try await meeting.createRoom(req)

参数名	类型	必填	说明
`req`	`MeetingCreateReq`	是	创建参数，字段见类型定义

返回值： (roomNo: String, meetingId: String) 可能抛出： SMeetingError.notLoggedIn、SMeetingError.apiError(code:message:)

不显式设置 meetingType 时按即时会议创建。

`updateRoom(meetingId:req:)`

修改会议（会前）。

try await meeting.updateRoom(meetingId: meetingId, req: req)

参数名	类型	必填	说明
`meetingId`	`String`	是	要修改的会议 ID
`req`	`MeetingCreateReq`	是	新的会议参数

返回值： 无 可能抛出： SMeetingError.notLoggedIn、SMeetingError.apiError(code:message:)

`cancelRoom(meetingId:)`

取消会议。

try await meeting.cancelRoom(meetingId: meetingId)

参数名	类型	必填	说明
`meetingId`	`String`	是	会议 ID

返回值： 无 可能抛出： SMeetingError.notLoggedIn、SMeetingError.apiError(code:message:)

`detailRoom(meetingId:roomNo:)`

获取会议详情，两个参数二选一。

let info = try await meeting.detailRoom(roomNo: "10000001")

参数名	类型	必填	说明
`meetingId`	`String?`	否	会议 ID
`roomNo`	`String?`	否	房间号

返回值： MeetingInfo。详情回包不带创建时间，createdAt 为 0；1.5.0 起另带 entryMutePolicy、content（后端没给时为 nil），字段见类型定义 可能抛出： SMeetingError.notLoggedIn、SMeetingError.apiError(code:message:)

`attendeeRoom(page:)`

我需要参加的会议（未开始或进行中）。

let result = try await meeting.attendeeRoom()

参数名	类型	必填	说明
`page`	`PageParam`	否	分页参数，默认第 1 页每页 20 条

返回值： PageResult<MeetingInfo> 可能抛出： SMeetingError.notLoggedIn、SMeetingError.apiError(code:message:)

`attendedRoom(page:)`

历史会议。参数与返回值同 attendeeRoom(page:)。

`roomParticipant(meetingId:page:perPage:)`

某场会议的参会人员记录。

let result = try await meeting.roomParticipant(meetingId: meetingId)

参数名	类型	必填	说明
`meetingId`	`String`	是	会议 ID
`page`	`Int`	否	页码，默认 `1`
`perPage`	`Int`	否	每页条数，默认 `20`

返回值： PageResult<ParticipantInfo> 可能抛出： SMeetingError.notLoggedIn、SMeetingError.apiError(code:message:)

进入 / 退出会议

`enterRoom(_:)`

进入会议。

var req = MeetingEnterReq(nickname: "张三", roomNo: "10000001")
req.password = "123456"
try await meeting.enterRoom(req)

参数名	类型	必填	说明
`req`	`MeetingEnterReq`	是	入会参数，`meetingId` 与 `roomNo` 二选一

返回值： 无 可能抛出：

SMeetingError.notLoggedIn
SMeetingError.alreadyInMeeting —— 已经在会议中，需要先 exitRoom()
SMeetingError.apiError(code:message:) —— 密码错误、会议不存在、被限制入会等
底层连接建立失败时抛出的错误

成功后 SDK 会自动订阅远端音频，视频按需订阅。

`exitRoom()`

退出当前会议，登录状态保留。

await meeting.exitRoom()

返回值： 无，不抛错。不在会议中时调用会被安全忽略。

状态查询

`getRoomInfo()`

返回值： RoomInfo?，未在会议中时为 nil。

`getWhiteBoard()`

返回值： String?，当前会议的白板地址，没有时为 nil。

`getUserInfo(_:)`

let user = try meeting.getUserInfo(uid)

参数名	类型	必填	说明
`uid`	`String`	是	成员 ID

返回值： MeetingUserInfo 可能抛出： SMeetingError.notInMeeting、SMeetingError.userNotFound(_:)（会议中没有这个成员）

`getUsersInfo()`

返回值： [String: MeetingUserInfo]，uid 到成员的映射，未在会议中时为空字典。

`getUsersInfoList()`

返回值： [MeetingUserInfo]，未在会议中时为空数组。

`getRemoteVideoTrack(uid:desc:)`

查询某位成员的某路视频轨道对象，不发起订阅。

参数名	类型	必填	说明
`uid`	`String`	是	成员 ID
`desc`	`TrackDesc`	否	轨道描述，默认 `.cameraBig`

返回值： Track?，成员不存在或未发布该轨道时为 nil。

会中用户操作

以下接口都要求在会议中，否则抛出 SMeetingError.notInMeeting；服务端拒绝时抛出 SMeetingError.apiError(code:message:)。

`updateName(_:)`

修改自己的会中昵称。

try await meeting.updateName("新昵称")

参数名	类型	必填	说明
`name`	`String`	是	新昵称

`sendRoomChatMessage(_:type:targetId:)`

发送会中聊天消息。

try await meeting.sendRoomChatMessage("大家好")
try await meeting.sendRoomChatMessage(url, type: .pic, targetId: uid)

参数名	类型	必填	说明
`msg`	`String`	是	消息内容
`type`	`ChatMsgType`	否	消息类型，默认 `.text`
`targetId`	`String?`	否	私聊目标成员；不传为群发

`sendRoomCustomMessage(_:targetId:)`

发送业务自定义消息。

参数名	类型	必填	说明
`content`	`String`	是	消息内容，通常放业务 JSON
`targetId`	`String?`	否	私聊目标成员；不传为群发

`requestHandup(_:)` / `cancelHandup(_:)`

举手申请与取消。

try await meeting.requestHandup(.mic)
try await meeting.cancelHandup(.mic)

参数名	类型	必填	说明
`code`	`HandupType`	是	`.mic` / `.camera` / `.chat` / `.share`

`rejectOpenMic(adminUid:)` / `rejectOpenCamera(adminUid:)`

拒绝主持人的开麦 / 开摄像头邀请。

参数名	类型	必填	说明
`adminUid`	`String?`	否	发起邀请的主持人 ID，取自对应事件的 `opUid`

`rollCallAnswer(rollCallUserId:)`

点名应答。

参数名	类型	必填	说明
`rollCallUserId`	`String`	是	直接传 `RollCallNamedEventData.id`。注意不是 `.sid`（那是发起点名的主持人 uid）

可能抛出： SMeetingError.notLoggedIn、SMeetingError.apiError(code:message:)

会议外消息

`enableIm()`

启用会议外消息通道。

try await meeting.enableIm()

成功后触发一次 meeting(_:imDidConnect:)，此后收到的会议外消息按 action 派发到 imCallCalling / imMeetingRemind / imAdminMoveOutWaitingRoom / imUserHelpSubMeeting，每条消息另外原样触发 imDidReceiveMessage，见会议外消息。1.4.1 及以前这些事件实际不会派发，1.5.0 起修正。 返回值： 无 可能抛出： SMeetingError.notLoggedIn、SMeetingError.apiError(code:message:)、连接建立失败时的底层错误

`disableIm()`

停用会议外消息通道。

await meeting.disableIm()

返回值： 无，不抛错。logout() 内部会自动调用。主动停用不会触发 meeting(_:imDidDisconnect:)。

虚拟背景

属设备级配置（作用于进程内唯一的共享摄像头采集链路），设置同时作用于全部会议。会中切换摄像头、关掉摄像头再打开、断线重连后都不需要业务层重新下发。用法与调优见虚拟背景。

成员	签名	说明
装载	`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` 回落到虚化
推理间隔	`setVirtualBackgroundInferenceInterval(_ interval: Int)`	分割每 N 帧跑一次（合成仍每帧跑），默认 1
蒙版对齐	`setVirtualBackgroundMaskSync(_ enabled: Bool)`	默认 `false`；`interval` 为 1 时开关无区别
实例	`virtualBackground: SRTCVirtualBackground`	诊断用只读状态与丢帧计数

可能抛出： SRTCError.virtualBackgroundAlreadyInstalled、.virtualBackgroundNotInstalled、.virtualBackgroundModelNotFound(String)、.virtualBackgroundSessionFailed(String) 这一组是对音视频层的转发，会议层不另存一份状态，因此与直接用 meeting.srtc 调等价，推荐用会议层的方法。

​初始化

​init(logLevel:)

​属性

​version

​srtc

​language

​currentLanguage

​delegates

​currentUserId

​isInRoom

​cameraTrack / screenTrack / mcuTrack

​认证

​login(token:)

​logout()

​会议管理（会前）

​createRoom(_:)

​updateRoom(meetingId:req:)

​cancelRoom(meetingId:)

​detailRoom(meetingId:roomNo:)

​attendeeRoom(page:)

​attendedRoom(page:)

​roomParticipant(meetingId:page:perPage:)

​进入 / 退出会议

​enterRoom(_:)

​exitRoom()

​状态查询

​getRoomInfo()

​getWhiteBoard()

​getUserInfo(_:)

​getUsersInfo()

​getUsersInfoList()

​getRemoteVideoTrack(uid:desc:)

​会中用户操作

​updateName(_:)

​sendRoomChatMessage(_:type:targetId:)

​sendRoomCustomMessage(_:targetId:)

​requestHandup(_:) / cancelHandup(_:)

​rejectOpenMic(adminUid:) / rejectOpenCamera(adminUid:)

​rollCallAnswer(rollCallUserId:)

​会议外消息

​enableIm()

​disableIm()

​虚拟背景

​相关页面

初始化