Back to Developers

< Headless Flutter SDK />

UTD Stream SDK

Headless LiveKit audio/video sessions for Flutter — you build the UI.

Version 0.1.0On pub.dev
Get startedView on 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

Session types

Headless

Zero UI

7

Platforms

LiveKit

Engine

< utd_stream_sdk />

Key features

A headless SDK for building audio/video apps on Flutter with LiveKit as the engine. It exposes four session types (audio call, video call, live stream, audio room) as logic-only sessions, surfacing state via ValueListenables and a raw event stream. You own all the UI; the SDK handles sessions, server-authoritative permissions, and media control — with no secrets shipped in the app.

Four session types: audio call, video call, live stream, audio room

Headless by design — pure logic and state, zero UI

LiveKit integration with adaptive streaming and dynacast on by default

Reactive state via ValueListenables plus a raw RoomEvent stream

Server-authoritative permissions (seat/stage promotion controlled by the engine)

Live-stream stage management with unbounded co-publishers

Seat-based speaker/listener model for audio rooms

1:1 call lifecycle state machine

Typed REST facade with no secrets in the app

< utd_stream_sdk />

Get started

1

Install

Terminal
flutter pub add utd_stream_sdk
2

View on pub.dev

Headless LiveKit audio/video sessions for Flutter — you build the UI.

View on pub.dev

< utd_stream_sdk />

API reference

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.

Parameters

  • appIdStringrequired

    Publishable app id for the project.

  • appKeyStringrequired

    Publishable app key paired with appId.

  • baseUrlStringDefault = UTDApiClient.defaultBaseUrl

    Engine REST base URL.

  • tokenBaseUrlStringDefault = UTDApiClient.defaultTokenBaseUrl

    Token-minting service base URL.

identitygetter
String? get identity

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

Returns: 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.

Parameters

  • identityStringrequired

    Unique user identity to mint the bearer for.

  • nameString?

    Optional display name.

  • deviceIdString?

    Optional device identifier.

Returns: 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.

Parameters

  • typeUTDStreamTyperequired

    Must be audioCall or videoCall.

Returns: 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().

Parameters

  • identityStringrequired

    Joining user identity.

  • roomNameStringrequired

    Room to join (un-prefixed name).

  • asHostboolDefault = false

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

  • nameString?

    Optional display name.

  • deviceIdString?

    Optional device identifier.

Returns: 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.

Parameters

  • identityStringrequired

    Joining user identity.

  • roomNameStringrequired

    Room to join (un-prefixed name).

  • asHostboolDefault = 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).

Returns: Future<UTDAudioRoomSession> — A connected audio room session.

disposemethod
void dispose()

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

Returns: 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).

Returns: UTDStreamType — The session product type.

roomproperty
final UTDRoom room

The headless UTDRoom wrapper owning the LiveKit connection lifecycle.

Returns: UTDRoom — The underlying room wrapper.

connectedgetter
ValueListenable<bool> get connected

Listenable that reflects whether the media room is currently connected.

Returns: ValueListenable<bool> — Connection state.

canPublishgetter
ValueListenable<bool> get canPublish

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

Returns: ValueListenable<bool> — Publish capability state.

remoteParticipantsgetter
ValueListenable<List<RemoteParticipant>> get remoteParticipants

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

Returns: 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).

Returns: Stream<RoomEvent> — Broadcast LiveKit event stream.

localParticipantgetter
LocalParticipant? get localParticipant

The local LiveKit participant, or null before connection.

Returns: 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.

Parameters

  • enabledboolrequired

    Whether to enable the microphone.

Returns: 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.

Parameters

  • dataList<int>required

    Raw bytes payload.

  • reliableboolDefault = true

    Use reliable delivery.

  • toList<String>?

    Target participant identities; null broadcasts to all.

Returns: Future<void> — Completes when sent.

leavemethodasync
Future<void> leave()

Leaves the media room but keeps the session object reusable.

Returns: Future<void> — Completes after disconnect.

disposemethodasync
Future<void> dispose()

Tears down the session and its LiveKit room.

Returns: 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.

Returns: ValueNotifier<UTDCallStatus?> — Current call status.

callIdproperty
final ValueNotifier<String?> callId

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

Returns: 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.

Parameters

  • calleeIdentityStringrequired

    Identity of the user being called.

  • calleeNameString?

    Optional callee display name.

  • metadataMap<String, dynamic>?

    Optional call metadata.

Returns: 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).

Parameters

  • idStringrequired

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

Returns: Future<UTDCall> — The accepted engine call.

ringingmethodasync
Future<void> ringing(String id)

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

Parameters

  • idStringrequired

    The call id.

Returns: Future<void> — Completes when status updated.

rejectmethodasync
Future<void> reject(String id)

Rejects an incoming call and updates status.

Parameters

  • idStringrequired

    The call id to reject.

Returns: Future<void> — Completes when rejected.

busymethodasync
Future<void> busy(String id)

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

Parameters

  • idStringrequired

    The call id.

Returns: 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.

Returns: 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.

Returns: String — Room name.

isHostproperty
final bool isHost

Whether this participant joined as the host.

Returns: bool — Host flag.

stageproperty
final ValueNotifier<List<UTDStageMember>> stage

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

Returns: 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.

Parameters

  • withVideoboolDefault = true

    Publish camera in addition to mic.

Returns: Future<void> — Completes when broadcasting.

refreshStagemethodasync
Future<void> refreshStage()

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

Returns: Future<void> — Completes when stage refreshed.

inviteToStagemethodasync
Future<void> inviteToStage(String identity)

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

Parameters

  • identityStringrequired

    Viewer identity to promote.

Returns: Future<void> — Completes after promotion and stage refresh.

removeFromStagemethodasync
Future<void> removeFromStage(String identity)

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

Parameters

  • identityStringrequired

    Co-publisher identity to demote.

Returns: Future<void> — Completes after demotion and stage refresh.

requestStagemethodasync
Future<void> requestStage()

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

Returns: Future<void> — Completes when request sent.

leaveStagemethodasync
Future<void> leaveStage()

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

Returns: 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.

Returns: String — Room name.

isHostproperty
final bool isHost

Whether this participant joined as the host.

Returns: 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.

Parameters

  • seatCountint?

    Number of seats.

  • seatModeString?

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

  • modeIdString?

    Optional mode identifier.

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

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

Fetches the current seat grid state from the engine.

Returns: 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.

Parameters

  • indexintrequired

    Seat index to occupy.

Returns: 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.

Returns: Future<void> — Completes when off-seat.

requestToSpeakmethodasync
Future<void> requestToSpeak()

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

Returns: Future<void> — Completes when request sent.

approveSpeakermethodasync
Future<void> approveSpeaker(int requestId)

Host: approves a pending speak request by id.

Parameters

  • requestIdintrequired

    Pending request id to approve.

Returns: Future<void> — Completes when approved.

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

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

Parameters

  • identityStringrequired

    Listener identity to invite.

  • seatIndexint?

    Optional target seat index.

Returns: 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.

Parameters

  • adaptiveStreamboolDefault = true

    Enable LiveKit adaptive stream.

  • dynacastboolDefault = true

    Enable LiveKit dynacast.

roomproperty
final Room room

The underlying LiveKit Room instance.

Returns: Room — LiveKit room.

eventsgetterasync
Stream<RoomEvent> get events

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

Returns: 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.

Parameters

  • urlStringrequired

    LiveKit ws URL.

  • tokenStringrequired

    LiveKit JWT.

  • autoSubscribeboolDefault = true

    Auto-subscribe to remote tracks.

Returns: 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.

Parameters

  • enabledboolrequired

    Whether to enable the mic.

Returns: 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.

Parameters

  • enabledboolrequired

    Whether to enable the camera.

Returns: 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.

Parameters

  • dataList<int>required

    Raw bytes payload.

  • reliableboolDefault = true

    Use reliable delivery.

  • destinationIdentitiesList<String>?

    Target identities; null broadcasts.

Returns: 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).

Ready to build with UTD?

Create your account, fund your master wallet, and turn on the services you need.

Create your free account