返回开发者中心

< 无界面 Flutter SDK />

UTD Stream SDK

面向 Flutter 的无界面 LiveKit 音视频会话——UI 由你来构建。

版本 0.1.0在 pub.dev 上
开始使用在 pub.dev 上查看
FlutteriOSAndroidWebmacOSWindowsLinux
stream_sdk.dart
final client = UTDStreamClient(
  appId: '1234567890',
  appKey: 'a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6',
);

// Audio room
final room = await client.joinAudioRoom(
  identity: 'u1', roomName: 'lobby', asHost: true, seatCount: 8,
);
await room.takeSeat(0);

// Live stream
final live = await client.joinLiveStream(
  identity: 'host1', roomName: 'show', asHost: true,
);
await live.goLive();

// 1:1 call
await client.authenticate(identity: 'u1');
final call = client.callSession(UTDStreamType.videoCall);
await call.start(calleeIdentity: 'u2');

4

会话类型

Headless

零 UI

7

平台

LiveKit

引擎

< utd_stream_sdk />

核心功能

一款以 LiveKit 为引擎、用于在 Flutter 上构建音视频应用的无界面 SDK。它将四种会话类型（音频通话、视频通话、直播、音频房间）作为纯逻辑会话提供，并通过 ValueListenables 和原始事件流暴露状态。所有 UI 由你掌控；SDK 负责会话、服务端权威的权限控制和媒体控制——应用中不会留存任何密钥。

四种会话类型：音频通话、视频通话、直播、音频房间

无界面设计——纯逻辑与状态，零 UI

集成 LiveKit，默认开启自适应流和 dynacast

通过 ValueListenables 提供响应式状态，并附带原始 RoomEvent 事件流

服务端权威的权限（座位/上麦提升由引擎控制）

直播上麦管理，支持不限数量的共同发布者

面向音频房间的基于座位的发言者/聆听者模型

1:1 通话生命周期状态机

类型化的 REST 封装，应用中不含任何密钥

< utd_stream_sdk />

开始使用

1

安装

Terminal
flutter pub add utd_stream_sdk
2

在 pub.dev 上查看

面向 Flutter 的无界面 LiveKit 音视频会话——UI 由你来构建。

在 pub.dev 上查看

< utd_stream_sdk />

API 参考

Client & entry point

Top-level entry point that holds credentials and produces logic-only sessions for each product type.

UTDStreamClientconstructor
factory UTDStreamClient({required String appId, required String appKey, String baseUrl, String tokenBaseUrl})

Builds a headless client from publishable credentials (appId + appKey). One instance per signed-in user; shares a single HTTP layer across all sessions.

参数

  • appIdString必填

    Publishable app id for the project.

  • appKeyString必填

    Publishable app key paired with appId.

  • baseUrlString默认值 = UTDApiClient.defaultBaseUrl

    Engine REST base URL.

  • tokenBaseUrlString默认值 = UTDApiClient.defaultTokenBaseUrl

    Token-minting service base URL.

identitygetter
String? get identity

The identity of the currently authenticated / joined user, or null if none.

返回值: String? — Current user identity or null.

authenticatemethodasync
Future<String> authenticate({required String identity, String? name, String? deviceId})

Mints a room-less per-user bearer and attaches it for privileged calls. Required before starting/accepting 1:1 calls. Returns the user_token.

参数

  • identityString必填

    Unique user identity to mint the bearer for.

  • nameString?

    Optional display name.

  • deviceIdString?

    Optional device identifier.

返回值: Future<String> — The minted user_token bearer.

callSessionmethod
UTDCallSession callSession(UTDStreamType type)

Creates a 1:1 call session (audio or video). Call authenticate() first. Asserts the type is a call type.

参数

  • typeUTDStreamType必填

    Must be audioCall or videoCall.

返回值: UTDCallSession — A new call session driven by start()/accept().

joinLiveStreammethodasync
Future<UTDLiveStreamSession> joinLiveStream({required String identity, required String roomName, bool asHost, String? name, String? deviceId})

Mints a room token, connects the media room, and returns a live stream session. Host publishes via goLive(); viewers subscribe and may requestStage().

参数

  • identityString必填

    Joining user identity.

  • roomNameString必填

    Room to join (un-prefixed name).

  • asHostbool默认值 = false

    Join as host (role=host, owns the room) vs audience.

  • nameString?

    Optional display name.

  • deviceIdString?

    Optional device identifier.

返回值: Future<UTDLiveStreamSession> — A connected live stream session.

joinAudioRoommethodasync
Future<UTDAudioRoomSession> joinAudioRoom({required String identity, required String roomName, bool asHost, String? name, String? deviceId, int? seatCount, String? seatMode})

Mints a room token, connects, and returns a seat-based audio room session. Host may seed the seat grid via seatCount/seatMode.

参数

  • identityString必填

    Joining user identity.

  • roomNameString必填

    Room to join (un-prefixed name).

  • asHostbool默认值 = false

    Join as host vs audience; only hosts may seed seats.

  • nameString?

    Optional display name.

  • deviceIdString?

    Optional device identifier.

  • seatCountint?

    Host only: number of seats to seed the grid with.

  • seatModeString?

    Host only: seat mode (e.g. free/request).

返回值: Future<UTDAudioRoomSession> — A connected audio room session.

disposemethod
void dispose()

Releases the underlying HTTP pools. Sessions must be disposed separately.

返回值: void — Nothing.

Session base & headless state

Shared base class re-exposing the LiveKit room state as ValueListenables and a raw event stream.

UTDSessionclass
abstract class UTDSession

Abstract base for every session type. Owns the UTDRoom and re-exposes its headless state; concrete sessions add per-type control (call lifecycle, stage, seats).

typeproperty
final UTDStreamType type

The product type of this session (audioCall, videoCall, liveStream, audioRoom).

返回值: UTDStreamType — The session product type.

roomproperty
final UTDRoom room

The headless UTDRoom wrapper owning the LiveKit connection lifecycle.

返回值: UTDRoom — The underlying room wrapper.

connectedgetter
ValueListenable<bool> get connected

Listenable that reflects whether the media room is currently connected.

返回值: ValueListenable<bool> — Connection state.

canPublishgetter
ValueListenable<bool> get canPublish

Listenable for whether the server has granted this participant publish capability (seat/stage authoritative).

返回值: ValueListenable<bool> — Publish capability state.

remoteParticipantsgetter
ValueListenable<List<RemoteParticipant>> get remoteParticipants

Listenable list of remote participants, refreshed on connect/disconnect and track subscription events.

返回值: ValueListenable<List<RemoteParticipant>> — Current remote participants.

eventsgetterasync
Stream<RoomEvent> get events

Raw broadcast stream of LiveKit RoomEvents for apps that want the full firehose (track subscribed, data, metadata, speakers).

返回值: Stream<RoomEvent> — Broadcast LiveKit event stream.

localParticipantgetter
LocalParticipant? get localParticipant

The local LiveKit participant, or null before connection.

返回值: LocalParticipant? — Local participant or null.

setMicrophonemethodasync
Future<void> setMicrophone(bool enabled)

Toggles the local mic. Refused by the SFU unless the server has granted publish.

参数

  • enabledbool必填

    Whether to enable the microphone.

返回值: Future<void> — Completes when applied.

sendDatamethodasync
Future<void> sendData(List<int> data, {bool reliable = true, List<String>? to})

Sends a data message (chat/gifts/custom signalling) to the room, optionally to specific identities.

参数

  • dataList<int>必填

    Raw bytes payload.

  • reliablebool默认值 = true

    Use reliable delivery.

  • toList<String>?

    Target participant identities; null broadcasts to all.

返回值: Future<void> — Completes when sent.

leavemethodasync
Future<void> leave()

Leaves the media room but keeps the session object reusable.

返回值: Future<void> — Completes after disconnect.

disposemethodasync
Future<void> dispose()

Tears down the session and its LiveKit room.

返回值: Future<void> — Completes after teardown.

Call session (1:1)

1:1 audio/video call lifecycle. Caller starts, callee accepts; room capped at 2 by the engine.

UTDCallSessionclass
class UTDCallSession extends UTDSession

1:1 call session (audio_call or video_call). Both parties publish. Caller start()s; callee accept()s an incoming call by id.

statusproperty
final ValueNotifier<UTDCallStatus?> status

Listenable for the current call lifecycle status, null until a call starts.

返回值: ValueNotifier<UTDCallStatus?> — Current call status.

callIdproperty
final ValueNotifier<String?> callId

Listenable for the active engine call id, null until a call starts/accepts.

返回值: ValueNotifier<String?> — Active call id.

startmethodasync
Future<UTDCall> start({required String calleeIdentity, String? calleeName, Map<String, dynamic>? metadata})

Caller side: creates the call, rings the callee, joins the call room and publishes. Returns the engine call.

参数

  • calleeIdentityString必填

    Identity of the user being called.

  • calleeNameString?

    Optional callee display name.

  • metadataMap<String, dynamic>?

    Optional call metadata.

返回值: Future<UTDCall> — The created engine call.

acceptmethodasync
Future<UTDCall> accept(String id)

Callee side: accepts an incoming call by id and joins the call room, publishing mic (and camera for video).

参数

  • idString必填

    The incoming call id (arrives out-of-band).

返回值: Future<UTDCall> — The accepted engine call.

ringingmethodasync
Future<void> ringing(String id)

Marks the call as ringing on the engine and updates status.

参数

  • idString必填

    The call id.

返回值: Future<void> — Completes when status updated.

rejectmethodasync
Future<void> reject(String id)

Rejects an incoming call and updates status.

参数

  • idString必填

    The call id to reject.

返回值: Future<void> — Completes when rejected.

busymethodasync
Future<void> busy(String id)

Marks the callee as busy for the given call and updates status.

参数

  • idString必填

    The call id.

返回值: Future<void> — Completes when marked busy.

endmethodasync
Future<void> end()

Hangs up the active call, ending it server-side and disconnecting the media room. Tolerant of terminal/duplicate ends.

返回值: Future<void> — Completes after teardown.

Live stream session & stage control

One host + unlimited viewers; host promotes any number of viewers to co-publish (no engine cap).

UTDLiveStreamSessionclass
class UTDLiveStreamSession extends UTDSession

Live stream session: one host publishes A/V, unlimited viewers subscribe, host can promote any number of co-publishers. Stage promotion is server-authoritative.

roomNameproperty
final String roomName

The (un-prefixed) live stream room name.

返回值: String — Room name.

isHostproperty
final bool isHost

Whether this participant joined as the host.

返回值: bool — Host flag.

stageproperty
final ValueNotifier<List<UTDStageMember>> stage

Listenable list of current stage members (host + co-publishers), refreshed via refreshStage() or stage events.

返回值: ValueNotifier<List<UTDStageMember>> — Current stage members.

goLivemethodasync
Future<void> goLive({bool withVideo = true})

Host: begins broadcasting by publishing mic and (optionally) camera. Viewers never call this.

参数

  • withVideobool默认值 = true

    Publish camera in addition to mic.

返回值: Future<void> — Completes when broadcasting.

refreshStagemethodasync
Future<void> refreshStage()

Fetches the current stage roster from the engine and updates the stage listenable.

返回值: Future<void> — Completes when stage refreshed.

inviteToStagemethodasync
Future<void> inviteToStage(String identity)

Host/admin: promotes a viewer to co-publish (audio+video). Unbounded.

参数

  • identityString必填

    Viewer identity to promote.

返回值: Future<void> — Completes after promotion and stage refresh.

removeFromStagemethodasync
Future<void> removeFromStage(String identity)

Host/admin: removes a co-publisher back to viewer.

参数

  • identityString必填

    Co-publisher identity to demote.

返回值: Future<void> — Completes after demotion and stage refresh.

requestStagemethodasync
Future<void> requestStage()

Viewer: raises a hand to be promoted, notifying the host.

返回值: Future<void> — Completes when request sent.

leaveStagemethodasync
Future<void> leaveStage()

Co-publisher: steps down to a viewer, stopping camera and mic.

返回值: Future<void> — Completes after stepping down.

Audio room session & seat control

Seat-based speakers + listeners; taking a seat is what grants publish. Audio-only by design.

UTDAudioRoomSessionclass
class UTDAudioRoomSession extends UTDSession

Audio room session: speakers occupy seats and publish mic, listeners subscribe. Publishing is seat occupancy, not a token role. Audio-only.

roomNameproperty
final String roomName

The (un-prefixed) audio room name.

返回值: String — Room name.

isHostproperty
final bool isHost

Whether this participant joined as the host.

返回值: bool — Host flag.

setupSeatsmethodasync
Future<Map<String, dynamic>> setupSeats({int? seatCount, String? seatMode, String? modeId})

Host: configures the seat grid (count + free/request mode). Usually passed at join instead. Returns the raw engine response.

参数

  • seatCountint?

    Number of seats.

  • seatModeString?

    Seat mode (e.g. free/request).

  • modeIdString?

    Optional mode identifier.

返回值: Future<Map<String, dynamic>> — Raw engine seat-setup response.

getSeatsmethodasync
Future<Map<String, dynamic>> getSeats()

Fetches the current seat grid state from the engine.

返回值: Future<Map<String, dynamic>> — Raw engine seats state.

takeSeatmethodasync
Future<void> takeSeat(int index)

Takes a seat to become a speaker; the engine grants publish, then the mic is enabled locally.

参数

  • indexint必填

    Seat index to occupy.

返回值: Future<void> — Completes when seated and mic on.

leaveSeatmethodasync
Future<void> leaveSeat()

Leaves the seat (back to listener); the engine revokes publish and the mic is disabled.

返回值: Future<void> — Completes when off-seat.

requestToSpeakmethodasync
Future<void> requestToSpeak()

Listener: requests to speak (in request mode); a host approves.

返回值: Future<void> — Completes when request sent.

approveSpeakermethodasync
Future<void> approveSpeaker(int requestId)

Host: approves a pending speak request by id.

参数

  • requestIdint必填

    Pending request id to approve.

返回值: Future<void> — Completes when approved.

inviteToSpeakmethodasync
Future<void> inviteToSpeak(String identity, {int? seatIndex})

Host: invites a listener to speak, optionally targeting a specific seat.

参数

  • identityString必填

    Listener identity to invite.

  • seatIndexint?

    Optional target seat index.

返回值: Future<void> — Completes when invite sent.

Room wrapper & media

Headless wrapper around a LiveKit Room exposing connection state, media toggles, and the event stream.

UTDRoomconstructor
UTDRoom({bool adaptiveStream = true, bool dynacast = true})

Headless wrapper around a LiveKit Room. Owns the connection lifecycle and surfaces state as ValueListenables + a broadcast event stream. Never elevates its own permissions.

参数

  • adaptiveStreambool默认值 = true

    Enable LiveKit adaptive stream.

  • dynacastbool默认值 = true

    Enable LiveKit dynacast.

roomproperty
final Room room

The underlying LiveKit Room instance.

返回值: Room — LiveKit room.

eventsgetterasync
Stream<RoomEvent> get events

Raw LiveKit room events for apps that want the full firehose (track subscribed, data, etc.).

返回值: Stream<RoomEvent> — Broadcast LiveKit event stream.

connectmethodasync
Future<void> connect(String url, String token, {bool autoSubscribe = true})

Connects to the LiveKit room with the given url and token, wires event listeners, and refreshes permissions/remotes.

参数

  • urlString必填

    LiveKit ws URL.

  • tokenString必填

    LiveKit JWT.

  • autoSubscribebool默认值 = true

    Auto-subscribe to remote tracks.

返回值: Future<void> — Completes when connected.

setMicrophonemethodasync
Future<void> setMicrophone(bool enabled)

Enables/disables the local microphone. Refused by the SFU unless the server granted publish.

参数

  • enabledbool必填

    Whether to enable the mic.

返回值: Future<void> — Completes when applied.

setCameramethodasync
Future<void> setCamera(bool enabled)

Enables/disables the local camera. Refused by the SFU unless the server granted publish.

参数

  • enabledbool必填

    Whether to enable the camera.

返回值: Future<void> — Completes when applied.

sendDatamethodasync
Future<void> sendData(List<int> data, {bool reliable = true, List<String>? destinationIdentities})

Sends a data message to the room (chat/gifts/custom signalling), optionally to specific identities.

参数

  • dataList<int>必填

    Raw bytes payload.

  • reliablebool默认值 = true

    Use reliable delivery.

  • destinationIdentitiesList<String>?

    Target identities; null broadcasts.

返回值: Future<void> — Completes when sent.

Models & enums

Data types and enums returned by the engine: stream types, call lifecycle, token responses, errors.

UTDStreamTypeenum
enum UTDStreamType { audioCall, videoCall, liveStream, audioRoom }

The four canonical product types (audioCall, videoCall, liveStream, audioRoom). Each carries a wire value and isCall/hasVideo helpers.

UTDCallStatusenum
enum UTDCallStatus { initiating, ringing, active, ended, rejected, busy, missed }

Lifecycle of a 1:1 call mirroring engine call states: initiating, ringing, active, ended, rejected, busy, missed.

UTDTokenResponseclass
class UTDTokenResponse { final String token; final String url; final String roomName; final String userToken; final String? wsUrl; }

Response of a room token mint (POST /api/v1/token), carrying the LiveKit token+url, room name, engine bearer user_token, and optional wsUrl.

UTDCallclass
class UTDCall { final String callId; final UTDCallStatus status; final UTDStreamType type; ... }

A 1:1 call as returned by the engine, carrying callId, status, type, and optional roomName/token/url/callee+caller identities.

UTDStageMemberclass
class UTDStageMember { final String identity; final String? name; final String? role; }

A member of a live_stream stage (the unbounded publisher set), with identity and optional name/role.

UTDStreamExceptionclass
class UTDStreamException implements Exception { final String message; final int? statusCode; final String? code; }

All SDK errors surface as this, carrying the engine HTTP statusCode + message + optional code; exposes isBanned (403) and isRateLimited (429).

准备好与 UTD 一起构建了吗？

创建账户，为主钱包充值，按需开启你所需要的服务。

创建免费账户