العودة إلى المطوّرين

< حزمة Flutter SDK بلا واجهة />

UTD Stream SDK

جلسات صوت/فيديو بلا واجهة عبر LiveKit في Flutter — وأنت من يبني الواجهة.

الإصدار 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

صفر واجهة

7

المنصّات

LiveKit

المحرّك

< utd_stream_sdk />

أبرز المزايا

حزمة SDK بلا واجهة لبناء تطبيقات الصوت والفيديو على Flutter باستخدام LiveKit كمحرّك. تتيح أربعة أنواع من الجلسات (مكالمة صوتية، مكالمة فيديو، بث مباشر، غرفة صوتية) كجلسات منطقية بحتة، وتكشف الحالة عبر ValueListenables وتدفّق أحداث خام. أنت تملك كامل الواجهة؛ والحزمة تتولّى الجلسات والصلاحيات المُدارة من الخادم والتحكم في الوسائط — دون أي أسرار داخل التطبيق.

أربعة أنواع جلسات: مكالمة صوتية، مكالمة فيديو، بث مباشر، غرفة صوتية

بلا واجهة بحكم التصميم — منطق وحالة فقط، صفر واجهة

تكامل مع LiveKit مع البث التكيّفي وdynacast مُفعّل افتراضياً

حالة تفاعلية عبر ValueListenables إضافةً إلى تدفّق RoomEvent خام

صلاحيات مُدارة من الخادم (ترقية المقعد/المنصّة يتحكّم بها المحرّك)

إدارة منصّة البث المباشر مع عدد غير محدود من المشاركين بالنشر

نموذج متحدّث/مستمع قائم على المقاعد للغرف الصوتية

آلة حالة لدورة حياة المكالمات الثنائية 1:1

واجهة REST مُنمّطة دون أي أسرار في التطبيق

< utd_stream_sdk />

ابدأ الآن

1

التثبيت

Terminal
flutter pub add utd_stream_sdk
2

عرض على pub.dev

جلسات صوت/فيديو بلا واجهة عبر LiveKit في Flutter — وأنت من يبني الواجهة.

عرض على 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؟

أنشئ حسابك، اشحن محفظتك الأم، وشغّل الخدمات التي تحتاجها.

أنشئ حسابك المجاني