Flutter API 参考
本页描述 Flutter plugin tirtc_av_kit 当前公开的 Dart API，适用于用 Flutter 开发 Android、iOS、macOS 客户端的接入者。
如果你还没有完成包接入、原生工程配置或连接主线准备，先看 集成到客户端。页面里提到的 AppId、remote_id、token、stream_id 等术语，以 名词解释 为准。
对象总览
| 对象 | 作用 | 最终清理 |
|---|---|---|
TiRtcInitOptions | 组织 runtime 初始化参数 | 调用方自行持有 |
TiRtc | 初始化和关闭全局 runtime，格式化错误码 | TiRtc.shutdown() |
TiRtcConn | 建连、断连、收发命令、收发流内消息、请求关键帧、手动订阅媒体、读取连接指标 | dispose() |
TiRtcAudioOutputOptions | 组织音频播放参数 | 调用方自行持有 |
TiRtcAudioOutput | 播放一条远端音频流并读取播放指标 | dispose() |
TiRtcVideoOutput | 播放一条远端视频流、生成 Flutter 视图并读取播放指标 | dispose() |
TiRtcLogging | 写 SDK 日志、上传日志 | 无 |
通用约束
- 先
await TiRtc.initialize(...)，再创建或使用TiRtcConn、TiRtcAudioOutput、TiRtcVideoOutput。 connect(...)返回0只表示建连请求已成功提交，不表示已经连上；真正连接结果以后续onStateChanged为准。attach()/detach()只控制本地播放绑定；subscribeAudio()/subscribeVideo()/unsubscribe*()才是向远端发起媒体发送控制。disconnect()只断开连接，detach()只解除当前播放绑定；对象本身仍然存在，可继续复用。dispose()才是TiRtcConn、TiRtcAudioOutput、TiRtcVideoOutput的最终清理动作。调用后该对象不能再继续使用。TiRtc.shutdown()只应放在应用级或一次完整播放流程结束后的最终 teardown。调用前先dispose()所有仍存活的连接和输出对象；否则shutdown()会返回错误码，而不是强制回收这些对象。- 当前公开互通范围里，
streamId按stream_id的公开约定使用0..15。 TiRtcVideoOutput.view()返回的是这个 output 专属的渲染视图；同一个TiRtcVideoOutput同时只支持一个已挂载的view()。
TiRtcInitOptions
TiRtc.initialize(...) 的参数对象。
| 字段 | 说明 |
|---|---|
appId | 你的 AppId。默认值为空字符串。 |
endpoint | 自定义服务入口。留空时使用 SDK 当前默认入口。 |
consoleLogEnabled | 是否把 SDK 日志镜像到宿主控制台。默认值为 false。 |
TiRtc
TiRtc 管理共享 runtime。典型调用顺序是：initialize() -> 创建连接和播放对象 -> 业务结束后 dispose() 这些对象 -> shutdown()。
| API | 说明 |
|---|---|
initialize(TiRtcInitOptions config): Future<int> | 初始化共享 runtime。调用时会先通过 Platform Channel 向宿主获取可写日志目录；返回统一的 TiRTCError 错误码。 |
shutdown(): int | 关闭共享 runtime。只有在所有 runtime-backed 对象都已经 dispose() 后，才会返回成功。 |
errorToString(int code): String | 把错误码转成稳定错误 token。 |
formatError(int code): String | 把错误码格式化成可直接展示给用户或写进日志的字符串，例如 error XXX (1234)。 |
TiRtcConn
状态
| 状态 | 含义 |
|---|---|
TiRtcConnState.idle | 连接对象已存在，但还没有开始建连 |
TiRtcConnState.connecting | 建连请求已提交，正在等待后续结果 |
TiRtcConnState.connected | 连接已经建立，可开始收发命令、流内消息、绑定播放对象、手动订阅和请求关键帧 |
TiRtcConnState.disconnected | 连接已经断开；对象仍需要 dispose() |
属性和回调
| 成员 | 说明 |
|---|---|
state | 当前连接状态 |
onStateChanged | 连接状态变化回调，签名为 void Function(TiRtcConnState state, int errorCode) |
onCommand | 收到命令通道消息时回调，签名为 void Function(int commandId, Uint8List data) |
onStreamMessage | 收到流内消息时回调，签名为 void Function(int streamId, int timestampMs, Uint8List data) |
方法
| API | 说明 |
|---|---|
TiRtcConn() | 创建连接对象。它本身不发起建连。 |
connect({required String remoteId, required String token}): int | 发起到目标 remote_id 的连接。两个参数都必须是非空字符串。返回 0 只表示请求提交成功。 |
disconnect(): int | 断开当前连接。成功后当前实例仍可再次 connect(...)。 |
dispose(): void | 最终释放连接对象。调用后该实例不能再继续使用。 |
sendCommand({required int commandId, required Uint8List data}): int | 在命令通道上发送业务自定义命令。Flutter 公开参数名是 commandId；如果链路里包含设备端 C SDK，这个值与设备侧看到的原始 cmdw 是同一份标识。 |
sendStreamMessage({required int streamId, required int timestampMs, required Uint8List data}): int | 发送流内消息。发送前两端应先约定好对应的 streamId 和消息语义。 |
subscribeVideo({required int streamId}): int | 可选的手动视频订阅控制。它只负责请求远端开始发送，不会自动创建本地播放。 |
unsubscribeVideo({required int streamId}): int | 取消手动视频订阅。它不等于 TiRtcVideoOutput.detach()。 |
subscribeAudio({required int streamId}): int | 可选的手动音频订阅控制。它只负责请求远端开始发送，不会自动创建本地播放。 |
unsubscribeAudio({required int streamId}): int | 取消手动音频订阅。它不等于 TiRtcAudioOutput.detach()。 |
requestKeyFrame({required int streamId}): int | 向指定远端视频流请求关键帧。 |
getMetricsSnapshot(): ({int code, TiRtcConnMetricsSnapshot? snapshot}) | 获取连接侧指标快照。成功时 code 为 0，snapshot 才有值。 |
TiRtcAudioOutputOptions
TiRtcAudioOutput.configure(...) 使用的参数对象。
| 字段 | 说明 |
|---|---|
volumePercent | 线性音量百分比，默认值为 100 |
gainLevel | 额外增益等级，默认值为 0 |
noiseReductionLevel | 降噪等级，默认值为 0 |
TiRtcAudioOutput
状态
| 状态 | 含义 |
|---|---|
TiRtcAudioOutputState.idle | 当前没有绑定远端音频流 |
TiRtcAudioOutputState.buffering | 已绑定远端音频流，但还没有进入稳定播放 |
TiRtcAudioOutputState.playing | 正在播放远端音频 |
TiRtcAudioOutputState.failed | 播放路径发生错误 |
属性和回调
| 成员 | 说明 |
|---|---|
state | 当前播放状态 |
onStateChanged | 播放状态变化回调，签名为 void Function(TiRtcAudioOutputState state) |
onError | 播放错误回调，签名为 void Function(int code) |
方法
| API | 说明 |
|---|---|
TiRtcAudioOutput() | 创建音频输出对象。 |
attach({required TiRtcConn connection, required int streamId}): int | 绑定指定连接上的一条远端音频流。它只决定本地播放哪一条流；如需控制远端开始或停止发送，还要配合 TiRtcConn.subscribeAudio() / unsubscribeAudio()。 |
detach(): int | 解除当前音频绑定，但对象仍可复用。 |
configure(TiRtcAudioOutputOptions options): int | 配置播放参数。当前公开语义里，这个方法应在 attach() 前调用；已 attach 的 output 不支持运行时更新参数。 |
dispose(): void | 最终释放音频输出对象。 |
getMetricsSnapshot(): ({int code, TiRtcAudioOutputMetricsSnapshot? snapshot}) | 获取音频播放指标快照。成功时 code 为 0，snapshot 才有值。 |
TiRtcVideoOutput
状态
| 状态 | 含义 |
|---|---|
TiRtcVideoOutputState.idle | 当前没有绑定远端视频流 |
TiRtcVideoOutputState.buffering | 已绑定远端视频流，但还没有进入稳定渲染 |
TiRtcVideoOutputState.rendering | 已经开始渲染远端视频 |
TiRtcVideoOutputState.failed | 视频播放路径发生错误 |
属性和回调
| 成员 | 说明 |
|---|---|
state | 当前播放状态 |
renderSize | 最近一次由 native 层上报的远端渲染尺寸。初始值为 null；只有收到真实尺寸后才会更新。 |
onStateChanged | 播放状态变化回调，签名为 void Function(TiRtcVideoOutputState state) |
onRenderSizeChanged | 渲染尺寸变化回调，签名为 void Function(Size size) |
onError | 播放错误回调，签名为 void Function(int code) |
方法
| API | 说明 |
|---|---|
TiRtcVideoOutput() | 创建视频输出对象。 |
attach({required TiRtcConn connection, required int streamId}): int | 绑定指定连接上的一条远端视频流。它只决定本地播放哪一条流；如需控制远端开始或停止发送，还要配合 TiRtcConn.subscribeVideo() / unsubscribeVideo()。 |
detach(): int | 解除当前视频绑定，但对象仍可复用。 |
view(): Widget | 返回这个 output 对应的 Flutter 渲染视图。把它挂到你自己的 Widget 树里后，SDK 会在内部管理 texture host 和视频显示。未 attach、尚未完成绑定或暂时没有画面时，视图保持占位状态。 |
dispose(): void | 最终释放视频输出对象；内部会清理 texture host 和 native 资源。 |
getMetricsSnapshot(): ({int code, TiRtcVideoOutputMetricsSnapshot? snapshot}) | 获取视频播放指标快照。成功时 code 为 0，snapshot 才有值。 |
TiRtcLogging
| API | 说明 |
|---|---|
d(String tag, String message): void | 写一条 debug 日志 |
i(String tag, String message): void | 写一条 info 日志 |
w(String tag, String message): void | 写一条 warning 日志 |
e(String tag, String message): void | 写一条 error 日志 |
upload(): Future<({int code, String? logId})> | 在后台 isolate 上传当前 SDK 日志。成功时 logId 才有值。 |
指标类型
如果你要做首帧耗时、连接耗时或卡顿观测，可以读取以下快照类型。
TiRtcConnMetricsSnapshot
| 字段 / 计算属性 | 说明 |
|---|---|
hasConnectStart | 是否已经记录连接开始时间 |
hasConnected | 是否已经记录连接成功时间 |
connectStartMonotonicMs | 连接开始时的单调时钟时间戳 |
connectedMonotonicMs | 连接成功时的单调时钟时间戳 |
isReady | 连接耗时是否已经可计算 |
connectDurationMs | 连接耗时；只有 isReady 为 true 时才有值 |
TiRtcAudioOutputMetricsSnapshot
| 字段 | 说明 |
|---|---|
stutter | 音频播放卡顿指标，类型为 TiRtcOutputStutterMetrics |
pending | 音频待消费时长指标，类型为 TiRtcPendingDurationMetrics |
TiRtcVideoOutputMetricsSnapshot
| 字段 | 说明 |
|---|---|
startup | 视频启动阶段指标，类型为 TiRtcVideoOutputStartupMetrics |
stutter | 视频播放卡顿指标，类型为 TiRtcOutputStutterMetrics |
pending | 视频待消费时长指标，类型为 TiRtcPendingDurationMetrics |
TiRtcVideoOutputStartupMetrics
| 字段 / 计算属性 | 说明 |
|---|---|
hasConnectStart / hasConnected | 是否已经记录连接起止时间 |
hasFirstVideoInput / hasFirstVideoDecoded / hasFirstVideoRendered | 是否已经记录首个输入帧、首个解码帧、首个渲染帧 |
connectStartMonotonicMs / connectedMonotonicMs | 连接阶段时间点 |
firstVideoInputMonotonicMs / firstVideoDecodedMonotonicMs / firstVideoRenderedMonotonicMs | 视频启动阶段关键时间点 |
hasFirstFrame | 首帧耗时是否已经可计算 |
firstFrameDurationMs | 从连接开始到首帧渲染完成的耗时；只有 hasFirstFrame 为 true 时才有值 |
TiRtcOutputStutterMetrics
| 字段 | 说明 |
|---|---|
sessionStarted | 当前播放会话是否已经开始 |
sessionDurationMs | 当前会话总时长 |
sessionStutterTotalMs | 当前会话累计卡顿总时长 |
sessionStutterCount | 当前会话累计卡顿次数 |
sessionStutterPeakMs | 当前会话单次最大卡顿时长 |
sessionStutterRatio | 当前会话卡顿占比 |
recentWindowDurationMs | 最近观测窗口总时长 |
recentWindowStutterTotalMs | 最近观测窗口累计卡顿总时长 |
recentWindowStutterCount | 最近观测窗口累计卡顿次数 |
recentWindowStutterPeakMs | 最近观测窗口单次最大卡顿时长 |
recentWindowStutterRatio | 最近观测窗口卡顿占比 |
TiRtcPendingDurationMetrics
| 字段 | 说明 |
|---|---|
undecodedDurationMs | 尚未完成解码的数据时长 |
decodedDurationMs | 已解码但尚未消费的数据时长 |
常见误用
- 没有先
await TiRtc.initialize(...)就创建和使用连接或播放对象。 - 把
connect(...)返回0误解成已经连上；真正连接结果要以后续onStateChanged为准。 - 把
disconnect()或detach()当成最终清理；真正的最终清理是dispose()。 - 在音频已经
attach()之后再调用configure(...)，把它误当成运行时动态调参入口。 - 把视频状态写成
playing；当前 Flutter 公开状态名是TiRtcVideoOutputState.rendering。 - 同一个
TiRtcVideoOutput同时挂载多个view()。 - 设备端按订阅再发时，只做
attach(...)没有配合subscribeAudio()/subscribeVideo()，结果一直无声或黑屏。 - 还有 live object 没有
dispose()时就调用TiRtc.shutdown()，并误以为 runtime 一定已经关闭。