客户端 iOS API 参考
对象总览
| 对象 | 作用 | 最终清理 |
|---|---|---|
TiRtcConfig | 初始化配置 | |
TiRtc | 初始化和关闭全局 runtime | TiRtc.shutdown() |
TiRtcConn | 建连、断连、订阅/退订媒体流、收发命令、收发流消息、请求关键帧 | invalidate() |
TiRtcAudioOutputOptions | 调整音频播放参数 | 调用方自行持有 |
TiRtcAudioOutput | 播放一条远端音频流 | invalidate() |
TiRtcVideoOutput | 播放一条远端视频流，并绑定 UIKit / AppKit 视图 | invalidate() |
TiRtcDebugging | 上传 SDK 日志 | 无 |
通用约束
- 先调用
TiRtc.initialize(_:)，再使用TiRtcConn、TiRtcAudioOutput、TiRtcVideoOutput。 TiRtcConn的 delegate 只在init(delegate:)里传入，当前没有公开 API 可以在构造后替换 delegate。TiRtcConnDelegate、TiRtcAudioOutputDelegate、TiRtcVideoOutputDelegate都是回调入口；SDK 不会额外切到主线程，涉及 UI 更新时请自行切回主线程。disconnect()只断开连接，不销毁对象。attach(...)/detach()只绑定或解除本地播放路由；subscribeAudio()/subscribeVideo()/unsubscribe*()才是向远端发起媒体发送控制。- 调用
TiRtc.shutdown()前，先invalidate()所有TiRtcConn、TiRtcAudioOutput、TiRtcVideoOutput。 detach()、detachView()只解除当前绑定，不销毁对象。invalidate()才是TiRtcConn、TiRtcAudioOutput、TiRtcVideoOutput的最终清理动作。TiRtcVideoOutput.attachView(_:)必须在主线程调用。
TiRtcConfig
| 成员 | 说明 |
|---|---|
endpoint | 自定义服务入口；留空表示使用默认入口 |
isConsoleLoggingEnabled | 是否把日志镜像到控制台 |
environment | 环境编号，默认值是 0 |
TiRtc
| API | 说明 |
|---|---|
initialize(_ config: TiRtcConfig) -> Int32 | 初始化全局 runtime。 |
shutdown() -> Void | 关闭全局 runtime。调用前先 invalidate() 所有连接和输出对象。 |
TiRtcConn
状态
| 状态 | 含义 |
|---|---|
TiRtcConnState.idle | 连接对象已创建，但还没有开始建连 |
TiRtcConnState.connecting | 建连请求已提交，正在等待后续连接结果 |
TiRtcConnState.connected | 连接已经建立，可开始命令、流消息、音视频绑定、媒体订阅控制和关键帧请求 |
TiRtcConnState.disconnected | 连接已经断开 |
TiRtcConnDelegate
| 回调 | 说明 |
|---|---|
conn(_:didChangeState:) | 连接状态变化 |
conn(_:didDisconnectWithCode:) | 连接进入终态断开；文档语义上和 conn(_:didChangeState:) 一起表达终态断连 |
conn(_:didReceiveCommand:data:) | 收到命令通道消息；回调给业务侧的是原始 cmdw |
conn(_:didReceiveStreamMessage:timestampMs:data:) | 收到流内消息；参数依次是 streamId、timestampMs、data。 |
conn(_:didFailWithCode:message:) | 连接级错误 |
属性和方法
| API | 说明 |
|---|---|
init(delegate: TiRtcConnDelegate?) | 创建连接对象。delegate 在这里传入。native bridge 不是在 init 时立即创建，而是在第一次 connect、send、requestKeyFrame 等需要它的调用里按需创建。 |
state: TiRtcConnState | 当前连接状态。只读。 |
connect(to remoteId: String, token: String) -> Int32 | 发起到目标 remote_id 的连接。任一参数不能为空。返回 0 只表示建连请求已提交，不表示已经连接成功；真正结果以后续状态回调为准。 |
disconnect() -> Void | 只断开传输连接。 |
sendCommand(cmdw: UInt32, data: Data) -> Int32 | 在命令通道上发送原始 cmdw。如果链路里包含设备端 C SDK，业务侧自定义 cmdw 应使用 0x2000..0xFFFFFFFF。 |
sendStreamMessage(streamId: UInt8, timestampMs: UInt32, data: Data) -> Int32 | 发送流内消息。 |
requestKeyFrame(streamId: UInt8) -> Int32 | 向指定远端视频流请求关键帧。 |
subscribeVideo(streamId: UInt8) -> Int32 | 请求对端开始发送指定视频流。它只发起远端发送控制，本地仍要配合 TiRtcVideoOutput.attach(to:streamId:) 才能真正播放。 |
unsubscribeVideo(streamId: UInt8) -> Int32 | 请求对端停止发送指定视频流。它不等于 TiRtcVideoOutput.detach()；两者分别作用于远端发送控制和本地播放绑定。 |
subscribeAudio(streamId: UInt8) -> Int32 | 请求对端开始发送指定音频流。它只发起远端发送控制，本地仍要配合 TiRtcAudioOutput.attach(to:streamId:) 才能真正播放。 |
unsubscribeAudio(streamId: UInt8) -> Int32 | 请求对端停止发送指定音频流。它不等于 TiRtcAudioOutput.detach()；两者分别作用于远端发送控制和本地播放绑定。 |
invalidate() -> Void | 最终释放连接对象。 |
TiRtcAudioOutput
状态
| 状态 | 含义 |
|---|---|
TiRtcAudioOutputState.idle | 当前没有绑定远端音频流 |
TiRtcAudioOutputState.buffering | 已绑定远端音频流，但还没有进入稳定播放 |
TiRtcAudioOutputState.playing | 正在播放远端音频。音频状态名强调的是“正在输出到播放设备”。 |
TiRtcAudioOutputState.failed | 播放路径发生错误 |
TiRtcAudioOutputOptions
| 字段 | 说明 |
|---|---|
volumePercent | 线性音量百分比 |
gainLevel | 额外增益等级 |
noiseReductionLevel | 降噪等级 |
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 | 最终释放 output。 |
TiRtcVideoOutput
状态
| 状态 | 含义 |
|---|---|
TiRtcVideoOutputState.idle | 当前没有绑定远端视频流 |
TiRtcVideoOutputState.buffering | 已绑定远端视频流，但还没有进入稳定播放 |
TiRtcVideoOutputState.playing | 正在播放远端视频。视频状态文档当前统一按播放语义描述。 |
TiRtcVideoOutputState.failed | 视频播放路径发生错误 |
TiRtcVideoOutputDelegate
| 回调 | 说明 |
|---|---|
videoOutput(_:didChangeState:) | 播放状态变化 |
videoOutput(_:didChangeRenderSize:) | 渲染尺寸变化 |
videoOutput(_:didFailWithCode:message:) | 播放错误 |
属性和方法
| API | 说明 |
|---|---|
delegate | 视频输出回调入口；weak 持有 |
attachView(_ view: TiRtcPlatformView) -> Int32 | 把 output 绑定到一个 UIKit / AppKit 视图。iOS 下是 UIView，macOS 下是 NSView。必须在主线程调用；若 bridge 尚未创建，这个调用会先触发按需创建。 |
detachView() -> Void | 解除当前视图绑定，但不解除远端视频绑定。 |
attach(to conn: TiRtcConn, streamId: UInt8) -> Int32 | 绑定指定连接上的一条远端视频流。这个绑定只决定本地播放哪一条；如需向远端请求开始或停止发送，再配合 TiRtcConn.subscribeVideo() / unsubscribeVideo()。 |
detach() -> Void | 解除当前视频绑定，但对象仍可复用。 |
invalidate() -> Void | 最终释放 output。 |
TiRtcDebugging
| API | 说明 |
|---|---|
uploadLogs(completion:) -> Int32 | 异步上传当前 SDK 日志。调用成功只表示上传任务已成功启动；真正结果通过 completion(code, logId) 返回。 |
常见误用
- 把
connect(to:token:)返回0误解成已经连上；真正连接结果以后续状态回调为准。 - 把
disconnect()、detach()、detachView()当成最终清理；真正的最终清理是invalidate()。 - 在非主线程调用
attachView(_:)。 - 设备端按订阅再发时，只做
attach(...)没有调用subscribeAudio()/subscribeVideo()，结果一直无声或黑屏。 - 以为 delegate 一定会自动回到主线程；如果要更新 UI，应自行切回主线程。
- 退出前只调用
TiRtc.shutdown()，却没有先invalidate()仍存活的对象。