utd_stream_sdk 0.2.1

Headless LiveKit-based audio/video SDK for Flutter (audio call, video call, live stream, audio room) as logic-only sessions with no UI — build your own interface.

Changelog

0.2.1

Added

• Video Effects entitlement. UTDRoom.videoEffectsEntitled reads the trusted videoEffects claim from the local participant's signed token metadata (resolved server-side per platform), so effects run only for entitled customers. Backward-compatible: returns true unless the claim is explicitly false.
• 1:1 calls now send the caller/callee platform (os) on create/accept so the engine can resolve the per-platform Video Effects entitlement into the call token.

0.2.0

A correctness, typing, and tooling pass on the way to full feature parity. Hardened by an adversarial multi-dimension code review (16 verified findings fixed): signal-client connect/auth teardown + reconnect re-checks, publish op-epoch captured before the grant wait with all publish ops (mic/camera/screen) tracked for cancellation, real camera flip in switchCamera, a single generation-guarded seat-state writer using the engine's authoritative request list, 403 no longer blanket-mapped to "banned" (only the actual ban is; other 403s are UTDErrorCode.forbidden/isForbidden), and tolerant JSON guards throughout.

Breaking

• UTDAudioRoomSession.getSeats() / setupSeats() and UTDApi.getSeats() / setupSeats() now return a typed UTDSeatGrid instead of Map<String, dynamic>.

Added

• Reconnection & resync: a UTDConnectionState lifecycle (disconnected / connecting / connected / reconnecting / forceExit), tiered reconnection (light/full re-sync, then force-exit past the recovery window), leak-proof room teardown (a reconnect/switch can no longer orphan a live audio session), and bounded connect retries.
• Realtime in-room state (no polling): a UTDDataRouter decodes the engine's data-channel messages into typed state — the audio room exposes reactive seats (UTDSeatGrid), chatLocked, roles, and pending speaker requests; the live stream's stage updates from _stage_update. Room metadata (_seats / chat_locked) is parsed too, with an apply-generation guard so a slow REST re-sync can't clobber a fresher realtime push.
• Force-exit funnel: _banned / _kicked(signed_in_elsewhere) (and the participant-removed fallback) surface once as a UTDForceExitReason via session.forceExit / onForceExit.
• Unified event handler: an assignable UTDStreamEventHandler (zego-style, per-session) sits alongside the ValueListenables + raw events stream.
• Device control / audio routing: setSpeakerOn, setSpeakerPreferBluetooth, applyBluetoothAudioRouting (the Android communication-mode fix), switchCamera, muteAllRemoteAudio.
• Single-active-session support: a persisted device_id (UTDDeviceId) and auto-collected device_info (UTDDeviceInfo) are now sent on every mint (host-overridable).
• Publish hardening: capture ops are gated on a connected room, guarded by a monotonic op-epoch, and bounded by a media-op timeout; cancelPendingPublish runs before disconnect.
• Typed seat models: UTDSeat, UTDSeatGrid, UTDSpeakerRequest — tolerant of both the REST (seat_index / locked: 0) and data-channel (index / locked: false) shapes.
• UTDRole / UTDRoleChange and UTDSpeakerEvent models for the realtime role/speaker signals.
• Realtime WebSocket plane (UTDSignalClient): presence (subscribe/query + presenceChanges), incoming-call push (incomingCalls — the callee finally receives the call_id), call signalling, and DM/group chat (sendMessage/recall/read, conversation/group ops, messages/readReceipts/conversationEvents). The signal token is minted by the host's backend (it requires the project server secret) via a credentialsProvider; auto-reconnect with backoff refreshes it transparently, and a 4003 close surfaces as a takeover force-exit. New models: UTDPresenceChange, UTDMessage, UTDConversation, UTDCallInvitation, UTDCallUpdate.
• Moderation (session.moderation): ban/unban/listBans, kick, changeRole, setPermissions, forceMute, forbid/resumeStream, lockComments/unlockComments, setRoomMetadata, room/participant reads, closeRoom.
• Full audio-room ops: moveSeat, kickSeat, lockSeat/unlockSeat, muteSeat/unmuteSeat, cancelRequestToSpeak, listSpeakerRequests, rejectSpeaker, acceptInvitation/declineInvitation.
• Call history: client.getCall(id) and client.listCalls(...).
• Quality, sound levels, screen share: session.reportQuality(UTDQualityReport) (the engine dashboard feed), an activeSpeakers listenable, and setScreenShare(bool).

Notes

• UTDProjectConfig discovery and the chat history REST are intentionally NOT in the SDK: both the /project and /signal REST routes are authenticated with the project server secret, which must not live in a client. Expose them through your backend.
• Typed error hierarchy: UTDBannedException (403), UTDRateLimitedException (429, with isTakeoverCooldown), UTDTokenException (empty/malformed mint), plus the UTDErrorCode constants for programmatic branching. The HTTP layer now maps statuses to these automatically.
• A runnable example/ app demonstrating the audio-room, live-stream, and 1:1-call flows entirely from the sessions' ValueListenables, with the iOS/Android/macOS media permissions wired in.
• Explicit platforms: declaration (android, ios, macos, web).

Fixed

• Publish-grant race: enabling the mic/camera now waits for the server publish grant (canPublish) before turning capture on, and flips the state flag only after the SFU accepts the track — no more optimistic writes the SFU can reject.
• Listener leak: a failed Room.connect now disposes its half-wired event listener instead of leaking it.
• Call status: UTDCallSession.accept() reflects the engine's actual status instead of hard-coding active; end() no longer swallows non-engine errors.
• setMicrophone / setCamera / sendData throw UTDStreamException(notConnected) when there is no local participant instead of silently no-op'ing.

0.1.0

Initial release of the headless UTD Stream SDK.

• LiveKit-based audio/video sessions for Flutter with no UI — build your own interface.
• Four product types from one set of credentials: audio_call, video_call, live_stream, audio_room.
• UTDStreamClient entry point that holds credentials, mints tokens, and produces sessions.
• Per-type control surfaces: UTDCallSession, UTDLiveStreamSession, UTDAudioRoomSession.
• ValueListenable state (connected, canPublish, micEnabled, cameraEnabled, remoteParticipants) plus a raw events stream of LiveKit RoomEvents.
• Server-authoritative permissions: the SDK reacts to seat/stage promote-demote, never elevates itself.