Flutter API Reference

This page describes the public Dart API of the Flutter plugin tirtc_av_kit for Android, iOS, macOS, and OpenHarmony / HarmonyOS NEXT client apps.

If you have not added the package, configured the native projects, or prepared the connection flow, start with Client Integration. Terms such as AppId, remote_id, token, and stream_id follow the glossary.

Object Overview

Object	Purpose	Cleanup
`TiRtcInitOptions`	Holds SDK initialization options	No explicit cleanup
`TiRtc`	Initializes and shuts down the SDK environment; formats error codes	`TiRtc.shutdown()`
`TiRtcConn`	Connects, disconnects, sends commands and stream messages, requests key frames, and controls manual media subscription	`dispose()`
`TiRtcAudioOutputOptions`	Holds audio output options	No explicit cleanup
`TiRtcAudioOutput`	Plays one remote audio stream and reads diagnostic snapshots	`dispose()`
`TiRtcVideoOutputOptions`	Holds video decoding options	No explicit cleanup
`TiRtcVideoOutput`	Plays one remote video stream, creates the Flutter render widget, and reads diagnostic snapshots	`dispose()`
`TiRtcLogging`	Writes and uploads SDK logs	None

`TiRtcInitOptions`

Field	Description
`appId`	Your `AppId`. Default is an empty string.
`endpoint`	Custom service endpoint. Leave it empty to use the SDK default.
`consoleLogEnabled`	Whether to mirror SDK logs to the host console. Default is `false`.

`TiRtc`

Typical order: initialize() -> create connection and output objects -> dispose() those objects -> shutdown().

API	Description
`initialize(TiRtcInitOptions config): Future<int>`	Initializes the SDK environment. Returns `0` on success or an error code on failure. Create and use `TiRtcConn`, `TiRtcAudioOutput`, and `TiRtcVideoOutput` only after initialization succeeds.
`shutdown(): int`	Shuts down the SDK environment. Dispose every `TiRtcConn`, `TiRtcAudioOutput`, and `TiRtcVideoOutput` first; otherwise this returns an error code and does not force-release those objects.
`errorToString(int code): String`	Converts an error code to a stable error identifier string.
`formatError(int code): String`	Formats an error code for logs or UI, for example `error XXX (1234)`.

`TiRtcConn`

All streamId parameters in this section use the public stream_id range 0..15.

States

State	Meaning
`TiRtcConnState.idle`	The connection object exists but has not started connecting.
`TiRtcConnState.connecting`	The connection request has been submitted.
`TiRtcConnState.connected`	The connection is established. You can send messages and bind outputs.
`TiRtcConnState.disconnected`	The connection is disconnected. The object still needs `dispose()`.

Properties and Callbacks

Member	Description
`state`	Current connection state
`onStateChanged`	`void Function(TiRtcConnState state, int errorCode)`
`onCommand`	`void Function(int commandId, Uint8List data)`
`onStreamMessage`	`void Function(int streamId, int timestampMs, Uint8List data)`

Methods

API	Description
`TiRtcConn()`	Creates a connection object. Call it only after `TiRtc.initialize(...)` succeeds. It does not connect by itself.
`connect({required String remoteId, required String token}): int`	Starts connecting to the target `remote_id`. Both parameters must be non-empty strings. A `0` return value only means the request was submitted; use `onStateChanged` for the final connection result.
`disconnect(): int`	Disconnects the current connection without releasing the object. The same instance can connect again after success.
`dispose(): void`	Releases the connection object. Do not use the instance again after calling it.
`sendCommand({required int commandId, required Uint8List data}): int`	Sends an application command over the command channel.
`sendStreamMessage({required int streamId, required int timestampMs, required Uint8List data}): int`	Sends a stream message. Both sides should agree on the `streamId` and message meaning first.
`subscribeVideo({required int streamId}): int`	Requests the remote side to start sending a video stream. It does not create local playback.
`unsubscribeVideo({required int streamId}): int`	Cancels a manual video subscription. It is not the same as `TiRtcVideoOutput.detach()`.
`subscribeAudio({required int streamId}): int`	Requests the remote side to start sending an audio stream. It does not create local playback.
`unsubscribeAudio({required int streamId}): int`	Cancels a manual audio subscription. It is not the same as `TiRtcAudioOutput.detach()`.
`requestKeyFrame({required int streamId}): int`	Requests a key frame for a remote video stream.

`TiRtcAudioOutputOptions`

Field	Description
`volumePercent`	Linear volume percentage. Default is `100`.
`agcLevel`	Automatic gain control (AGC) level. Default is `0`.
`ansLevel`	Automatic noise suppression (ANS) level. Default is `0`.

`TiRtcAudioOutput`

API	Description
`TiRtcAudioOutput()`	Creates an audio output object. Call it only after `TiRtc.initialize(...)` succeeds.
`attach({required TiRtcConn connection, required int streamId}): int`	Binds this output to one remote audio stream on the connection. If the remote side sends media only after subscription, also call `TiRtcConn.subscribeAudio()`.
`detach(): int`	Removes the current audio binding without releasing the object. The same audio output object can be reused.
`configure(TiRtcAudioOutputOptions options): int`	Configures audio output options before `attach()`. Already-bound audio outputs do not support dynamic option updates.
`dispose(): void`	Releases the audio output. Do not use the instance again after calling it.
`getDebugSnapshot(): ({int code, TiRtcAudioOutputDebugSnapshot? snapshot})`	Reads an audio diagnostic snapshot.

`TiRtcVideoOutputOptions`

Video decoding options for TiRtcVideoOutput.setOptions(...). Normal playback does not need this. Use it only when you need to request software or hardware decoding.

Field	Description
`decoderPreference`	Video decoder preference. Default is `0`. `0` means auto, `1` requests software decoding, and `2` requests hardware decoding.

decoderPreference is a request, not a guarantee. The actual decoder depends on device, OS, codec, and platform capability.

`TiRtcVideoOutput`

API	Description
`TiRtcVideoOutput()`	Creates a video output object. Call it only after `TiRtc.initialize(...)` succeeds.
`setOptions(TiRtcVideoOutputOptions options): int`	Sets video decoding options. Call before `attach()` when needed. Normal playback does not need this.
`attach({required TiRtcConn connection, required int streamId}): int`	Binds this output to one remote video stream on the connection. If the remote side sends media only after subscription, also call `TiRtcConn.subscribeVideo()`.
`detach(): int`	Removes the current video binding without releasing the object. The same video output object can be reused.
`view(): Widget`	Returns the Flutter render widget for this video output. One `TiRtcVideoOutput` supports only one mounted `view()` at a time. The widget stays as a placeholder before binding completes or when no frame is available.
`dispose(): void`	Releases the video output and related system resources. Do not use the instance again after calling it.
`getDebugSnapshot(): ({int code, TiRtcVideoOutputDebugSnapshot? snapshot})`	Reads a video diagnostic snapshot.

Diagnostic Snapshot Types

Diagnostic snapshots read the SDK's currently known codec, resolution, and decoder information. They are query APIs. They do not change playback state and do not trigger onError.

`TiRtcAudioOutputDebugSnapshot`

Field	Description
`codec`	Current audio codec. `0` means the SDK has not obtained this information yet.

`TiRtcVideoOutputDebugSnapshot`

Field	Description
`codec`	Current video codec. `0` means the SDK has not obtained this information yet.
`bitstreamFormat`	Current video bitstream format. `0` means the SDK has not obtained this information yet.
`width`	Last known video width. `0` means the SDK has not obtained this information yet.
`height`	Last known video height. `0` means the SDK has not obtained this information yet.
`decoderPreference`	Requested decoder preference
`resolvedDecoderBackend`	Locked actual decoder type. `0` means unknown, `1` means software decoding, and `2` means hardware decoding.

Common Misuse

Creating or using objects before await TiRtc.initialize(...).
Treating connect(...) == 0 as already connected.
Treating disconnect() or detach() as object release. Call dispose() when the object is no longer needed.
Calling configure(...) on an audio output after attach() and expecting dynamic option updates.
Treating TiRtcVideoOutputOptions.decoderPreference as required. Normal playback uses auto.
Treating decoderPreference as the actual decoder result. Use TiRtcVideoOutputDebugSnapshot.resolvedDecoderBackend when you need the actual backend.
Using playing as the video state name. The Flutter public state is TiRtcVideoOutputState.rendering.
Mounting multiple view() widgets from the same TiRtcVideoOutput at the same time.
Calling TiRtc.shutdown() while connection or output objects have not been disposed.

Flutter API Reference ​

Object Overview ​

TiRtcInitOptions ​

TiRtc ​

TiRtcConn ​

States ​

Properties and Callbacks ​

Methods ​

TiRtcAudioOutputOptions ​

TiRtcAudioOutput ​

TiRtcVideoOutputOptions ​

TiRtcVideoOutput ​

Diagnostic Snapshot Types ​

TiRtcAudioOutputDebugSnapshot ​

TiRtcVideoOutputDebugSnapshot ​

Common Misuse ​

Related Docs ​