Flutter API 参考
本页描述 Flutter plugin tirtc_av_kit 当前公开的 Dart API，适用于用 Flutter 开发 Android、iOS、macOS 客户端的接入者。
如果你还没有完成包接入、原生工程配置或连接主线准备，先看 集成到客户端。页面里提到的 AppId、remote_id、token、stream_id 等术语，以 名词解释 为准。
对象总览
| 对象 | 作用 | 清理方式 |
|---|---|---|
TiRtcInitOptions | 组织 SDK 初始化参数 | 无需显式清理 |
TiRtc | 初始化和关闭 SDK 运行环境，格式化错误码 | TiRtc.shutdown() |
TiRtcConn | 建连、断连、收发命令、收发流消息、请求关键帧、手动订阅媒体 | dispose() |
TiRtcAudioOutputOptions | 组织音频播放参数 | 无需显式清理 |
TiRtcAudioOutput | 播放一条远端音频流，读取排查快照 | dispose() |
TiRtcVideoOutputOptions | 组织视频解码选项 | 无需显式清理 |
TiRtcVideoOutput | 播放一条远端视频流、生成 Flutter 视图，读取排查快照 | dispose() |
TiRtcLogging | 写 SDK 日志、上传日志 | 无 |
TiRtcInitOptions
TiRtc.initialize(...) 的参数对象。
| 字段 | 说明 |
|---|---|
appId | 你的 AppId。默认值为空字符串。 |
endpoint | 自定义服务入口。留空时使用 SDK 当前默认入口。 |
consoleLogEnabled | 是否把 SDK 日志镜像到宿主控制台。默认值为 false。 |
TiRtc
TiRtc 管理 SDK 运行环境。典型调用顺序是：initialize() -> 创建连接和播放对象 -> 业务结束后 dispose() 这些对象 -> shutdown()。
| API | 说明 |
|---|---|
initialize(TiRtcInitOptions config): Future<int> | 初始化 SDK 运行环境。成功返回 0，失败返回错误码；初始化完成后才能创建或使用 TiRtcConn、TiRtcAudioOutput、TiRtcVideoOutput。 |
shutdown(): int | 关闭 SDK 运行环境。调用前必须先 dispose() 所有 TiRtcConn、TiRtcAudioOutput、TiRtcVideoOutput；否则会返回错误码，不会强制释放这些对象。 |
errorToString(int code): String | 把错误码转成稳定错误标识字符串。 |
formatError(int code): String | 把错误码格式化成可直接展示给用户或写进日志的字符串，例如 error XXX (1234)。 |
TiRtcConn
本节所有 streamId 参数按 stream_id 的公开约定使用 0..15。
状态
| 状态 | 含义 |
|---|---|
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() | 创建连接对象。调用前需要先完成 TiRtc.initialize(...)；它本身不发起建连。 |
connect({required String remoteId, required String token}): int | 发起到目标 remote_id 的连接。两个参数都必须是非空字符串。返回 0 只表示请求提交成功，不表示已经连上；真正连接结果以后续 onStateChanged 为准。 |
disconnect(): int | 断开当前连接，但不释放连接对象。成功后当前实例仍可再次 connect(...)。 |
dispose(): void | 释放连接对象。调用后该实例不能再继续使用。 |
sendCommand({required int commandId, required Uint8List data}): int | 在命令通道上发送业务自定义命令。commandId 是两端约定的业务命令编号。 |
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 | 向指定远端视频流请求关键帧。 |
TiRtcAudioOutputOptions
TiRtcAudioOutput.configure(...) 使用的参数对象。
| 字段 | 说明 |
|---|---|
volumePercent | 线性音量百分比，默认值为 100 |
agcLevel | 自动增益控制（AGC）等级，默认值为 0 |
ansLevel | 自动噪声抑制（ANS）等级，默认值为 0 |
TiRtcAudioOutput
状态
| 状态 | 含义 |
|---|---|
TiRtcAudioOutputState.idle | 当前没有绑定远端音频流 |
TiRtcAudioOutputState.buffering | 已绑定远端音频流，但还没有进入稳定播放 |
TiRtcAudioOutputState.playing | 正在播放远端音频 |
TiRtcAudioOutputState.failed | 播放路径发生错误 |
属性和回调
| 成员 | 说明 |
|---|---|
state | 当前播放状态 |
onStateChanged | 播放状态变化回调，签名为 void Function(TiRtcAudioOutputState state) |
onError | 播放错误回调，签名为 void Function(int code) |
方法
| API | 说明 |
|---|---|
TiRtcAudioOutput() | 创建音频输出对象。调用前需要先完成 TiRtc.initialize(...)。 |
attach({required TiRtcConn connection, required int streamId}): int | 绑定指定连接上的一条远端音频流。它只决定本地播放哪一条流；如果远端配置为收到订阅后才发送媒体，还需要调用 TiRtcConn.subscribeAudio()。 |
detach(): int | 解除当前音频绑定，但不释放对象；同一个音频输出对象仍可复用。 |
configure(TiRtcAudioOutputOptions options): int | 配置播放参数。应在 attach() 前调用；已经绑定后的音频输出不支持动态更新参数。 |
dispose(): void | 释放音频输出对象。调用后该实例不能再继续使用。 |
getDebugSnapshot(): ({int code, TiRtcAudioOutputDebugSnapshot? snapshot}) | 获取音频排查快照。成功时 code 为 0，snapshot 才有值。 |
TiRtcVideoOutputOptions
TiRtcVideoOutput.setOptions(...) 使用的视频解码参数对象。普通播放不用设置；只有需要指定软件解码 / 硬件解码偏好时才使用。
| 字段 | 说明 |
|---|---|
decoderPreference | 视频解码偏好，默认值为 0。0 表示自动选择，1 表示请求软件解码，2 表示请求硬件解码。 |
decoderPreference 只是请求偏好，不保证实际解码器一定按该值选择。实际结果取决于设备、系统、视频编码格式和当前可用能力。
TiRtcVideoOutput
状态
| 状态 | 含义 |
|---|---|
TiRtcVideoOutputState.idle | 当前没有绑定远端视频流 |
TiRtcVideoOutputState.buffering | 已绑定远端视频流，但还没有进入稳定渲染 |
TiRtcVideoOutputState.rendering | 已经开始渲染远端视频 |
TiRtcVideoOutputState.failed | 视频播放路径发生错误 |
属性和回调
| 成员 | 说明 |
|---|---|
state | 当前播放状态 |
renderSize | 最近一次已知的远端视频渲染尺寸。初始值为 null；只有收到真实尺寸后才会更新。 |
onStateChanged | 播放状态变化回调，签名为 void Function(TiRtcVideoOutputState state) |
onRenderSizeChanged | 渲染尺寸变化回调，签名为 void Function(Size size) |
onError | 播放错误回调，签名为 void Function(int code) |
方法
| API | 说明 |
|---|---|
TiRtcVideoOutput() | 创建视频输出对象。调用前需要先完成 TiRtc.initialize(...)。 |
setOptions(TiRtcVideoOutputOptions options): int | 设置视频解码选项。建议在 attach() 前调用；普通播放不用调用。 |
attach({required TiRtcConn connection, required int streamId}): int | 绑定指定连接上的一条远端视频流。它只决定本地播放哪一条流；如果远端配置为收到订阅后才发送媒体，还需要调用 TiRtcConn.subscribeVideo()。 |
detach(): int | 解除当前视频绑定，但不释放对象；同一个视频输出对象仍可复用。 |
view(): Widget | 返回这个视频输出对象对应的 Flutter 渲染视图。同一个 TiRtcVideoOutput 同时只支持挂载一个 view()；未绑定、尚未完成绑定或暂时没有画面时，视图保持占位状态。 |
dispose(): void | 释放视频输出对象和相关系统资源。调用后该实例不能再继续使用。 |
getDebugSnapshot(): ({int code, TiRtcVideoOutputDebugSnapshot? 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})> | 异步上传当前 SDK 日志。成功时 logId 才有值。 |
排查快照类型
排查快照用于读取 SDK 当前已知的编码格式、分辨率、解码方式等信息。它们是查询 API，不会改变播放状态，也不会触发 onError。
TiRtcAudioOutputDebugSnapshot
| 字段 | 说明 |
|---|---|
codec | 当前已知的音频编码格式；0 表示 SDK 暂未获取到该信息 |
TiRtcVideoOutputDebugSnapshot
| 字段 | 说明 |
|---|---|
codec | 当前已知的视频编码格式；0 表示 SDK 暂未获取到该信息 |
bitstreamFormat | 当前已知的视频码流格式；0 表示 SDK 暂未获取到该信息 |
width | 最近一次已知视频宽度；0 表示 SDK 暂未获取到该信息 |
height | 最近一次已知视频高度；0 表示 SDK 暂未获取到该信息 |
decoderPreference | 当前请求的视频解码偏好 |
resolvedDecoderBackend | 已锁定的实际解码器类型；0 表示尚未锁定，1 表示软件解码，2 表示硬件解码 |
常见误用
- 没有先
await TiRtc.initialize(...)就创建和使用连接或播放对象。 - 把
connect(...)返回0误解成已经连上；真正连接结果要以后续onStateChanged为准。 - 把
disconnect()或detach()当成对象释放；业务结束后仍需要调用dispose()。 - 在音频已经
attach()之后再调用configure(...)，把它误当成动态调参入口。 - 把
TiRtcVideoOutputOptions.decoderPreference当成常规必配项；普通播放使用默认自动策略即可。 - 把
decoderPreference当成最终解码结果；实际解码器应以TiRtcVideoOutputDebugSnapshot.resolvedDecoderBackend为准。 - 把视频状态写成
playing；当前 Flutter 公开状态名是TiRtcVideoOutputState.rendering。 - 同一个
TiRtcVideoOutput同时挂载多个view()。 - 如果远端配置为收到订阅后才发送媒体，只做
attach(...)没有配合subscribeAudio()/subscribeVideo()，结果一直无声或黑屏。 - 还有连接或播放对象没有
dispose()时就调用TiRtc.shutdown()，并误以为 SDK 运行环境一定已经关闭。