iOS API 参考
本页描述 Darwin SDK TiRTC_AV 在 iOS 上当前公开的 Swift / Objective-C 可见 API，适用于用 iOS 原生应用接入 TiRTC 的开发者。
如果你还没有完成 SDK 引入、工程配置或连接主线准备，先看 集成到客户端。页面里提到的 AppId、remote_id、token、stream_id 等术语，以 名词解释 为准。
对象总览
| 对象 | 作用 | 最终清理 |
|---|---|---|
TiRtcInitOptions | 组织 runtime 初始化参数 | 调用方自行持有 |
TiRtc | 初始化和关闭全局 runtime | TiRtc.shutdown() |
TiRtcConn | 建连、断连、收发命令、收发流内消息、手动订阅媒体、请求关键帧 | invalidate() |
TiRtcAudioOutputOptions | 组织音频播放参数 | 调用方自行持有 |
TiRtcAudioOutput | 播放一条远端音频流 | invalidate() |
TiRtcVideoOutput | 播放一条远端视频流，并绑定 iOS 视图 | invalidate() |
TiRtcDebugging | 上传 SDK 日志 | 无 |
通用约束
- 先调用
TiRtc.initialize(_:)，再使用TiRtcConn、TiRtcAudioOutput、TiRtcVideoOutput。 - Darwin 当前公开 client surface 不会把 callback 自动切回主线程；如果 delegate 里要更新 UI，请你自己切回主线程或主 actor。
connect(...)返回0只表示建连请求已提交，不表示已经连上；真正连接结果以后续conn(_:didChangeState:errorCode:)为准。attach(...)/detach()只控制本地播放绑定；subscribeAudio()/subscribeVideo()/unsubscribe*()才是向远端发起媒体发送控制。disconnect()只断开连接，detach()/detachView()只解除当前播放绑定；对象本身仍可复用。invalidate()才是TiRtcConn、TiRtcAudioOutput、TiRtcVideoOutput的最终清理动作。- 调用
TiRtc.shutdown()前，先invalidate()所有仍存活的连接和输出对象。 - 当前公开互通范围里，
streamId按stream_id的约定使用0..15。 TiRtcVideoOutput.attachView(_:)在 iOS 下接收UIView，并且必须在主线程调用。
TiRtcInitOptions
TiRtc.initialize(_:) 的参数对象。
| 字段 | 说明 |
|---|---|
appId | 你的 AppId。默认值为空字符串。 |
endpoint | 自定义服务入口。留空时使用 runtime 当前默认入口。 |
consoleLogEnabled | 是否把 SDK 日志镜像到控制台。默认值为 false。 |
TiRtc
TiRtc 管理进程级共享 runtime。典型调用顺序是：initialize() -> 创建连接和播放对象 -> 业务结束后 invalidate() 这些对象 -> shutdown()。
| API | 说明 |
|---|---|
initialize(_ config: TiRtcInitOptions) -> Int32 | 初始化共享 runtime。返回统一的 TiRTCError 错误码。 |
shutdown() -> Void | 关闭共享 runtime。它本身不返回错误码，也不会替你清理仍存活的对象。 |
TiRtcConn
状态
| 状态 | 含义 |
|---|---|
TiRtcConnState.idle | 连接对象已存在，但没有活动中的传输尝试 |
TiRtcConnState.connecting | 建连请求已提交，正在等待连接结果 |
TiRtcConnState.connected | 连接已经建立，可开始收发命令、流内消息、绑定播放对象、手动订阅和请求关键帧 |
TiRtcConnState.disconnected | 连接已经不可用；对象仍需要 invalidate() |
TiRtcConnDelegate
| 回调 | 说明 |
|---|---|
conn(_:didChangeState:errorCode:) | 连接状态变化回调。当前公开 surface 把状态和错误码统一放在同一个回调里。 |
conn(_:didReceiveCommand:data:) | 收到命令通道消息时回调；业务侧看到的是 commandId + Data。 |
conn(_:didReceiveStreamMessage:data:streamId:) | 收到流内消息时回调。参数顺序是 timestampMs、data、streamId。 |
当前公开 iOS client 主线里，没有额外的 didDisconnect 或 didFailWithCode delegate 方法。
属性和方法
| API | 说明 |
|---|---|
init(delegate: TiRtcConnDelegate?) | 创建连接对象。delegate 只在这里传入，并且是 weak 持有。native bridge 不是在 init 时立即创建，而是在第一次 connect、send、requestKeyFrame 等需要它的调用里按需创建。 |
state: TiRtcConnState | 当前连接状态。只读。 |
connect(to remoteId: String, token: String) -> Int32 | 发起到目标 remote_id 的连接。参数任一为空时返回 invalid argument。返回 0 只表示请求提交成功。 |
disconnect() -> Void | 断开当前连接，但不释放对象。 |
send(commandId: UInt32, data: Data) -> Int32 | 在命令通道上发送业务自定义命令。iOS 当前公开参数名是 commandId。 |
sendStreamMessage(timestampMs: UInt32, data: Data, streamId: UInt8) -> Int32 | 发送流内消息。iOS 当前公开参数顺序是 timestampMs、data、streamId。 |
subscribeVideo(streamId: UInt8) -> Int32 | 可选的手动视频订阅控制。它只负责请求远端开始发送，不会自动创建本地播放。 |
unsubscribeVideo(streamId: UInt8) -> Int32 | 取消手动视频订阅。它不等于 TiRtcVideoOutput.detach()。 |
subscribeAudio(streamId: UInt8) -> Int32 | 可选的手动音频订阅控制。它只负责请求远端开始发送，不会自动创建本地播放。 |
unsubscribeAudio(streamId: UInt8) -> Int32 | 取消手动音频订阅。它不等于 TiRtcAudioOutput.detach()。 |
requestKeyFrame(streamId: UInt8) -> Int32 | 向指定远端视频流请求关键帧。 |
invalidate() -> Void | 最终释放连接对象。重复调用是安全 no-op。 |
TiRtcAudioOutputOptions
TiRtcAudioOutput.updateOptions(_:) 使用的参数对象。
| 字段 | 说明 |
|---|---|
volumePercent | 线性音量百分比，默认值为 100 |
gainLevel | 额外增益等级，默认值为 0 |
noiseReductionLevel | 降噪等级，默认值为 0 |
TiRtcAudioOutput
状态
| 状态 | 含义 |
|---|---|
TiRtcAudioOutputState.idle | 当前没有绑定远端音频流 |
TiRtcAudioOutputState.buffering | 已绑定远端音频流，但还没有进入稳定播放 |
TiRtcAudioOutputState.playing | 正在播放远端音频 |
TiRtcAudioOutputState.failed | 播放路径发生错误 |
TiRtcAudioOutputDelegate
| 回调 | 说明 |
|---|---|
audioOutput(_:didChangeState:) | 播放状态变化 |
audioOutput(_:didFailWithCode:message:) | 播放错误 |
属性和方法
| API | 说明 |
|---|---|
delegate | 音频输出回调入口；weak 持有。 |
updateOptions(_ options: TiRtcAudioOutputOptions) -> Int32 | 更新播放参数。若 bridge 尚未创建，这个调用也会触发按需创建。 |
attach(to conn: TiRtcConn, streamId: UInt8) -> Int32 | 绑定指定连接上的一条远端音频流。它只决定本地播放哪一条流；如需控制远端开始或停止发送，还要配合 TiRtcConn.subscribeAudio() / unsubscribeAudio()。 |
detach() -> Void | 解除当前音频绑定，但对象仍可复用。 |
invalidate() -> Void | 最终释放音频输出对象。 |
当前公开 iOS surface 没有额外暴露只读 state 属性；如果你需要感知播放状态，应以 delegate 回调为准。
TiRtcVideoOutput
状态
| 状态 | 含义 |
|---|---|
TiRtcVideoOutputState.idle | 当前没有可用的视频本地渲染路径 |
TiRtcVideoOutputState.buffering | 已绑定远端视频流，但还没有开始稳定渲染 |
TiRtcVideoOutputState.rendering | 已经开始渲染远端视频 |
TiRtcVideoOutputState.failed | 视频播放路径发生错误 |
TiRtcVideoOutputDelegate
| 回调 | 说明 |
|---|---|
videoOutput(_:didChangeState:) | 播放状态变化 |
videoOutput(_:didChangeRenderSize:) | 渲染尺寸变化 |
videoOutput(_:didFailWithCode:message:) | 播放错误 |
属性和方法
| API | 说明 |
|---|---|
delegate | 视频输出回调入口；weak 持有。 |
attachView(_ view: TiRtcPlatformView) -> Int32 | 把 output 绑定到 iOS 视图。在 iOS 下，TiRtcPlatformView 就是 UIView。必须在主线程调用。 |
detachView() -> Void | 解除当前视图绑定，但不解除远端视频绑定。 |
attach(to conn: TiRtcConn, streamId: UInt8) -> Int32 | 绑定指定连接上的一条远端视频流。它只决定本地播放哪一条流；如需控制远端开始或停止发送，还要配合 TiRtcConn.subscribeVideo() / unsubscribeVideo()。 |
detach() -> Void | 解除当前视频绑定，但对象仍可复用。 |
invalidate() -> Void | 最终释放视频输出对象。 |
当前公开 iOS surface 没有额外暴露 state 或 renderSize 只读属性；如果你需要感知这些信息，应以 delegate 回调为准。
TiRtcDebugging
| API | 说明 |
|---|---|
uploadLogs(completion:) -> Int32 | 异步上传当前 SDK 日志。调用成功只表示上传任务已成功启动；真正结果通过 completion(code, logId) 返回。 |
常见误用
- 按旧文档去找
TiRtcConfig、environment、连接级didDisconnect、连接级didFailWithCode这类当前 Darwin client 主线里已经不存在的 surface。 - 把
connect(to:token:)返回0误解成已经连上；真正连接结果要以后续conn(_:didChangeState:errorCode:)为准。 - 以为 SDK 会自动把 delegate 切回主线程；如果要更新 UI，应自行切回主线程或主 actor。
- 把
disconnect()、detach()、detachView()当成最终清理；真正的最终清理是invalidate()。 - 把视频状态写成
playing；当前 Darwin 公开状态名是TiRtcVideoOutputState.rendering。 - 在非主线程调用
attachView(_:)。 - 以为
TiRtcAudioOutput/TiRtcVideoOutput暴露了可直接读取的state或renderSize属性；当前公开 surface 里这些信息都通过 delegate 回调给出。 - 设备端按订阅再发时，只做
attach(...)没有配合subscribeAudio()/subscribeVideo()，结果一直无声或黑屏。 - 退出前只调用
TiRtc.shutdown()，却没有先invalidate()仍存活的对象。