客户端 Flutter API 参考
对象总览
| 对象 | 作用 | 最终清理 |
|---|---|---|
TiRtc | 初始化和关闭全局 runtime | TiRtc.shutdown() |
TiRtcConn | 建连、断连、订阅/退订媒体流、收发命令、收发流消息、请求关键帧 | dispose() |
TiRtcAudioOutput | 播放一条远端音频流 | dispose() |
TiRtcAudioOutputOptions | 调整音频播放参数 | 调用方自行持有 |
TiRtcVideoOutput | 播放一条远端视频流，并生成 Flutter 渲染视图 | dispose() |
TiRtcLogging | 写 SDK 日志、上传日志 | 无 |
通用约束
- 先
await TiRtc.initialize()，再创建TiRtcConn、TiRtcAudioOutput、TiRtcVideoOutput。 TiRtcConn、TiRtcAudioOutput、TiRtcVideoOutput的构造函数会立即尝试创建 native handle。- 当前公开互通范围里，
streamId统一按0..15使用，并与设备端的stream_id约定保持一致。 attach()/detach()只绑定或解除本地播放路由；subscribeAudio()/subscribeVideo()/unsubscribe*()才是向远端发起媒体发送控制。disconnect()只断开连接，不销毁对象。detach()只解除当前音频或视频绑定，不销毁对象。dispose()才是TiRtcConn、TiRtcAudioOutput、TiRtcVideoOutput的最终清理动作。TiRtc.shutdown()只放在应用级最终 teardown，不要放到单个页面的dispose()里。- 调用
TiRtc.shutdown()前，先dispose()所有连接和输出对象；如果仍有 live handle，当前实现会保持 runtime 处于已初始化状态。 - 一个
TiRtcVideoOutput同时只支持一个已挂载的view()。
TiRtc
把 initialize() 放在应用启动阶段；只有当应用确认后续整个进程都不再使用 TiRTC 时，才调用 shutdown()。
| API | 说明 |
|---|---|
initialize(endpoint = '', environment = 0, consoleLoggingEnabled = false): Future<int> | 初始化全局 runtime。初始化前会先通过 Platform Channel 向宿主取可写日志目录。 |
shutdown(): void | 关闭全局 runtime。只应在应用级最终 teardown 调用；调用前先 dispose() 所有连接和输出对象。如果仍有 live handle，当前实现会保持 runtime 处于已初始化状态。 |
TiRtcConn
状态
| 状态 | 含义 |
|---|---|
TiRtcConnState.idle | 连接对象已创建，但还没有开始建连 |
TiRtcConnState.connecting | 建连请求已提交，正在等待后续连接结果 |
TiRtcConnState.connected | 连接已经建立，可开始命令、流消息、音视频绑定、媒体订阅控制和关键帧请求 |
TiRtcConnState.disconnected | 连接已经断开 |
属性和回调
| 成员 | 说明 |
|---|---|
state | 当前连接状态 |
onStateChanged | 状态变化回调 |
onDisconnected | 终态断开回调；文档语义上和 onStateChanged(TiRtcConnState.disconnected) 一起表达终态断连 |
onCommand | 收到命令通道消息时回调；回调给业务侧的是原始 cmdw |
onStreamMessage | 收到流内消息时回调；参数依次是 streamId、timestampMs、data |
onError | 连接级错误回调 |
方法
| API | 说明 |
|---|---|
TiRtcConn() | 创建连接对象。构造函数会立即尝试创建 native handle。 |
connect({required remoteId, required token}): int | 发起到目标 remote_id 的连接。任一参数不能为空。返回 0 只表示建连请求已提交，不表示已经连接成功；真正结果以后续状态回调为准。 |
disconnect(): void | 只断开传输连接，不销毁对象。 |
sendCommand({required cmdw, required data}): int | 在命令通道上发送原始 cmdw。如果链路里包含设备端 C SDK，业务侧自定义 cmdw 应使用 0x2000..0xFFFFFFFF。 |
sendStreamMessage({required streamId, required timestampMs, required data}): int | 发送流内消息。当前公开互通范围里，streamId 应使用 0..15。 |
requestKeyFrame({required streamId}): int | 向指定远端视频流请求关键帧。当前公开互通范围里，streamId 应使用 0..15。 |
subscribeVideo({required streamId}): int | 请求对端开始发送指定视频流。当前公开互通范围里，streamId 应使用 0..15。它只发起远端发送控制，本地仍要配合 TiRtcVideoOutput.attach(...) 才能真正播放。 |
unsubscribeVideo({required streamId}): int | 请求对端停止发送指定视频流。它不等于 TiRtcVideoOutput.detach()；两者分别作用于远端发送控制和本地播放绑定。 |
subscribeAudio({required streamId}): int | 请求对端开始发送指定音频流。当前公开互通范围里，streamId 应使用 0..15。它只发起远端发送控制，本地仍要配合 TiRtcAudioOutput.attach(...) 才能真正播放。 |
unsubscribeAudio({required streamId}): int | 请求对端停止发送指定音频流。它不等于 TiRtcAudioOutput.detach()；两者分别作用于远端发送控制和本地播放绑定。 |
dispose(): void | 最终释放连接对象。 |
TiRtcAudioOutput
状态
| 状态 | 含义 |
|---|---|
TiRtcAudioOutputState.idle | 当前没有绑定远端音频流 |
TiRtcAudioOutputState.buffering | 已绑定远端音频流，但还没有进入稳定播放 |
TiRtcAudioOutputState.playing | 正在播放远端音频。音频状态名强调的是“正在输出到播放设备”。 |
TiRtcAudioOutputState.failed | 播放路径发生错误 |
属性和回调
| 成员 | 说明 |
|---|---|
state | 当前播放状态 |
onStateChanged | 状态变化回调 |
onError | 播放错误回调 |
TiRtcAudioOutputOptions
| 字段 | 说明 |
|---|---|
volumePercent | 线性音量百分比 |
gainLevel | 额外增益等级 |
noiseReductionLevel | 降噪等级 |
方法
| API | 说明 |
|---|---|
TiRtcAudioOutput() | 创建音频输出对象。 |
attach({required connection, required streamId}): int | 绑定指定连接上的一条远端音频流。当前公开互通范围里，streamId 应使用双方预先约定的 0..15。这个绑定只决定本地播放哪一条；如需向远端请求开始或停止发送，再配合 TiRtcConn.subscribeAudio() / unsubscribeAudio()。 |
detach(): int | 解除当前音频绑定，但对象仍可复用。 |
updateOptions(options): int | 更新播放参数。 |
dispose(): void | 最终释放 output。 |
TiRtcVideoOutput
状态
| 状态 | 含义 |
|---|---|
TiRtcVideoOutputState.idle | 当前没有绑定远端视频流 |
TiRtcVideoOutputState.buffering | 已绑定远端视频流，但还没有进入稳定播放 |
TiRtcVideoOutputState.playing | 正在播放远端视频。视频状态文档当前统一按播放语义描述。 |
TiRtcVideoOutputState.failed | 视频播放路径发生错误 |
属性和回调
| 成员 | 说明 |
|---|---|
state | 当前播放状态 |
renderSize | 当前对外暴露的渲染尺寸。attach() 后可能先暴露默认尺寸，后续再更新为真实远端画面尺寸。 |
onStateChanged | 状态变化回调 |
onRenderSizeChanged | 渲染尺寸变化回调 |
onError | 播放错误回调 |
方法
| API | 说明 |
|---|---|
TiRtcVideoOutput() | 创建视频输出对象。 |
attach({required connection, required streamId}): int | 绑定指定连接上的一条远端视频流。当前公开互通范围里，streamId 应使用双方预先约定的 0..15。这个绑定只决定本地播放哪一条；如需向远端请求开始或停止发送，再配合 TiRtcConn.subscribeVideo() / unsubscribeVideo()。 |
detach(): int | 解除当前视频绑定，但对象仍可复用。已经挂载的 view() 会保留在树里，并回到占位状态。 |
view(): Widget | 返回这个 output 对应的渲染视图。一个 output 同时只支持一个已挂载的 view()；未绑定远端视频或尚未完成宿主绑定时，视图保持占位状态。 |
dispose(): void | 最终释放 output；内部会清理 texture host 和 native 资源。 |
TiRtcLogging
| API | 说明 |
|---|---|
d(tag, message): void | 写一条 debug 日志 |
i(tag, message): void | 写一条 info 日志 |
w(tag, message): void | 写一条 warning 日志 |
e(tag, message): void | 写一条 error 日志 |
upload(): Future<({int code, String? logId})> | 上传当前 SDK 日志。成功时 logId 才有值。 |
常见误用
- 没有先
await TiRtc.initialize()就创建或使用对象。 - 把
connect(...)返回0误解成已经连上；真正连接结果以后续状态回调为准。 - 把
disconnect()、detach()当成最终清理；真正的最终清理是dispose()。 - 同一个
TiRtcVideoOutput同时挂载多个view()。 - 把
15以上的streamId当成公开可互通范围使用，最终和设备端约定冲突。 - 设备端按订阅再发时，只做
attach(...)没有调用subscribeAudio()/subscribeVideo()，结果一直无声或黑屏。 - 在单个页面的
dispose()里调用TiRtc.shutdown()，把页面级回收误当成应用级 runtime 退出。 - 还存在 live handle 时就调用
TiRtc.shutdown()，并误以为 runtime 一定已经关闭。