개발자로 돌아가기

< 헤드리스 Flutter SDK />

UTD Stream SDK

Flutter용 헤드리스 LiveKit 오디오/비디오 세션 — UI는 직접 구축하세요.

버전 0.1.0pub.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 없음

적응형 스트리밍과 dynacast가 기본 활성화된 LiveKit 통합

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와 함께 빌드할 준비가 되셨나요?

계정을 만들고, 마스터 지갑을 충전한 뒤, 필요한 서비스를 켜세요.

무료 계정 만들기