Retour aux développeurs

< SDK Flutter headless />

UTD Stream SDK

Sessions audio/vidéo LiveKit headless pour Flutter — l'UI, c'est vous qui la construisez.

Version 0.1.0Sur pub.dev
CommencerVoir sur 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

Types de sessions

Headless

Zéro UI

7

Plateformes

LiveKit

Moteur

< utd_stream_sdk />

Fonctionnalités clés

Un SDK headless pour créer des applications audio/vidéo sous Flutter avec LiveKit comme moteur. Il expose quatre types de sessions (appel audio, appel vidéo, live stream, salon audio) en tant que sessions purement logiques, exposant leur état via des ValueListenables et un flux d'événements brut. Toute l'UI vous appartient ; le SDK gère les sessions, les permissions faisant autorité côté serveur et le contrôle des médias — sans aucun secret embarqué dans l'application.

Quatre types de sessions : appel audio, appel vidéo, live stream, salon audio

Headless par conception — pure logique et état, zéro UI

Intégration LiveKit avec streaming adaptatif et dynacast activé par défaut

État réactif via des ValueListenables, plus un flux RoomEvent brut

Permissions faisant autorité côté serveur (promotion sur siège/scène pilotée par le moteur)

Gestion de scène en live stream avec un nombre illimité de co-publishers

Modèle intervenant/auditeur basé sur les sièges pour les salons audio

Machine à états du cycle de vie des appels 1:1

Façade REST typée, sans aucun secret dans l'application

< utd_stream_sdk />

Commencer

1

Installer

Terminal
flutter pub add utd_stream_sdk
2

Voir sur pub.dev

Sessions audio/vidéo LiveKit headless pour Flutter — l'UI, c'est vous qui la construisez.

Voir sur pub.dev

< utd_stream_sdk />

Référence de l'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.

Paramètres

  • appIdStringrequis

    Publishable app id for the project.

  • appKeyStringrequis

    Publishable app key paired with appId.

  • baseUrlStringPar défaut = UTDApiClient.defaultBaseUrl

    Engine REST base URL.

  • tokenBaseUrlStringPar défaut = UTDApiClient.defaultTokenBaseUrl

    Token-minting service base URL.

identitygetter
String? get identity

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

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

Paramètres

  • identityStringrequis

    Unique user identity to mint the bearer for.

  • nameString?

    Optional display name.

  • deviceIdString?

    Optional device identifier.

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

Paramètres

  • typeUTDStreamTyperequis

    Must be audioCall or videoCall.

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

Paramètres

  • identityStringrequis

    Joining user identity.

  • roomNameStringrequis

    Room to join (un-prefixed name).

  • asHostboolPar défaut = false

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

  • nameString?

    Optional display name.

  • deviceIdString?

    Optional device identifier.

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

Paramètres

  • identityStringrequis

    Joining user identity.

  • roomNameStringrequis

    Room to join (un-prefixed name).

  • asHostboolPar défaut = 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).

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

disposemethod
void dispose()

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

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

Retourne: UTDStreamType — The session product type.

roomproperty
final UTDRoom room

The headless UTDRoom wrapper owning the LiveKit connection lifecycle.

Retourne: UTDRoom — The underlying room wrapper.

connectedgetter
ValueListenable<bool> get connected

Listenable that reflects whether the media room is currently connected.

Retourne: ValueListenable<bool> — Connection state.

canPublishgetter
ValueListenable<bool> get canPublish

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

Retourne: ValueListenable<bool> — Publish capability state.

remoteParticipantsgetter
ValueListenable<List<RemoteParticipant>> get remoteParticipants

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

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

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

localParticipantgetter
LocalParticipant? get localParticipant

The local LiveKit participant, or null before connection.

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

Paramètres

  • enabledboolrequis

    Whether to enable the microphone.

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

Paramètres

  • dataList<int>requis

    Raw bytes payload.

  • reliableboolPar défaut = true

    Use reliable delivery.

  • toList<String>?

    Target participant identities; null broadcasts to all.

Retourne: Future<void> — Completes when sent.

leavemethodasync
Future<void> leave()

Leaves the media room but keeps the session object reusable.

Retourne: Future<void> — Completes after disconnect.

disposemethodasync
Future<void> dispose()

Tears down the session and its LiveKit room.

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

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

callIdproperty
final ValueNotifier<String?> callId

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

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

Paramètres

  • calleeIdentityStringrequis

    Identity of the user being called.

  • calleeNameString?

    Optional callee display name.

  • metadataMap<String, dynamic>?

    Optional call metadata.

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

Paramètres

  • idStringrequis

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

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

ringingmethodasync
Future<void> ringing(String id)

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

Paramètres

  • idStringrequis

    The call id.

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

rejectmethodasync
Future<void> reject(String id)

Rejects an incoming call and updates status.

Paramètres

  • idStringrequis

    The call id to reject.

Retourne: Future<void> — Completes when rejected.

busymethodasync
Future<void> busy(String id)

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

Paramètres

  • idStringrequis

    The call id.

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

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

Retourne: String — Room name.

isHostproperty
final bool isHost

Whether this participant joined as the host.

Retourne: bool — Host flag.

stageproperty
final ValueNotifier<List<UTDStageMember>> stage

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

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

Paramètres

  • withVideoboolPar défaut = true

    Publish camera in addition to mic.

Retourne: Future<void> — Completes when broadcasting.

refreshStagemethodasync
Future<void> refreshStage()

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

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

inviteToStagemethodasync
Future<void> inviteToStage(String identity)

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

Paramètres

  • identityStringrequis

    Viewer identity to promote.

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

removeFromStagemethodasync
Future<void> removeFromStage(String identity)

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

Paramètres

  • identityStringrequis

    Co-publisher identity to demote.

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

requestStagemethodasync
Future<void> requestStage()

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

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

leaveStagemethodasync
Future<void> leaveStage()

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

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

Retourne: String — Room name.

isHostproperty
final bool isHost

Whether this participant joined as the host.

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

Paramètres

  • seatCountint?

    Number of seats.

  • seatModeString?

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

  • modeIdString?

    Optional mode identifier.

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

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

Fetches the current seat grid state from the engine.

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

Paramètres

  • indexintrequis

    Seat index to occupy.

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

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

requestToSpeakmethodasync
Future<void> requestToSpeak()

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

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

approveSpeakermethodasync
Future<void> approveSpeaker(int requestId)

Host: approves a pending speak request by id.

Paramètres

  • requestIdintrequis

    Pending request id to approve.

Retourne: Future<void> — Completes when approved.

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

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

Paramètres

  • identityStringrequis

    Listener identity to invite.

  • seatIndexint?

    Optional target seat index.

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

Paramètres

  • adaptiveStreamboolPar défaut = true

    Enable LiveKit adaptive stream.

  • dynacastboolPar défaut = true

    Enable LiveKit dynacast.

roomproperty
final Room room

The underlying LiveKit Room instance.

Retourne: Room — LiveKit room.

eventsgetterasync
Stream<RoomEvent> get events

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

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

Paramètres

  • urlStringrequis

    LiveKit ws URL.

  • tokenStringrequis

    LiveKit JWT.

  • autoSubscribeboolPar défaut = true

    Auto-subscribe to remote tracks.

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

Paramètres

  • enabledboolrequis

    Whether to enable the mic.

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

Paramètres

  • enabledboolrequis

    Whether to enable the camera.

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

Paramètres

  • dataList<int>requis

    Raw bytes payload.

  • reliableboolPar défaut = true

    Use reliable delivery.

  • destinationIdentitiesList<String>?

    Target identities; null broadcasts.

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

Prêt à construire avec UTD ?

Créez votre compte, alimentez votre portefeuille principal et activez les services dont vous avez besoin.

Créer votre compte gratuit