< Flutter UIKit />
UTD Audio Room Kit
Sofort einsatzbereite Live-Audioräume mit Seats, Echtzeit-Chat und Moderation.
import 'package:utd_audio_room_kit/utd_audio_room_kit.dart';
UTDAudioRoom(
appId: '<utd-app-id>',
appKey: '<utd-app-key>',
userId: 'user123',
userName: 'John Doe',
roomId: 'room456',
roomOwnerId: 'owner789',
);Drop-in
Komplette UI
0
Backend-Server
EN · AR
Integrierte i18n
PiP
+ Minimieren
< utd_audio_room_kit />
Wichtigste Funktionen
Ein vollständiges, anpassbares Flutter-Paket für Live-Audioraum-Erlebnisse, angetrieben von LiveKit und der UTD Stream Engine. Sofort einsatzbereite Raum-UI mit Seat-Verwaltung, Sprechanfragen, Mitgliederlisten, Echtzeit-Chat, Mediensteuerung, Minimieren/PiP und vollständiger Host-/Admin-Moderation — ganz ohne eigenen Token-Server im Backend.
Sofort einsatzbereite Audioraum-UI — ohne zusätzlichen Code
Seat-Verwaltung: Platz nehmen, verlassen, wechseln, sperren, entsperren, kicken, stummschalten, tauschen
Warteschlange für Sprechanfragen mit Annehmen/Ablehnen
Mitgliederliste mit Host-/Admin-Aktionen (stummschalten, kicken, einladen, bannen, befördern/herabstufen)
Echtzeit-Chat über Data-Channel mit Batching und Deduplizierung
Mikrofon- und Lautsprechersteuerung mit Bluetooth-bevorzugtem Routing
Gestaffelte Wiederverbindung (Light-Sync <15s, Full-Sync <60s)
Minimieren in ein schwebendes Overlay und Android-OS Picture-in-Picture
Theme-Anpassung und integrierte i18n (EN/AR)
Vollständiger Austausch aller Bereiche (Header, Nachrichten, Steuerung, Hintergrund, Seats)
Kein Token-Server im Backend — appKey-basierter Token-Flow
< utd_audio_room_kit />
Erste Schritte
Installieren
flutter pub add utd_audio_room_kitAuf pub.dev ansehen
Sofort einsatzbereite Live-Audioräume mit Seats, Echtzeit-Chat und Moderation.
< utd_audio_room_kit />
API-Referenz
Main widget
The drop-in prebuilt audio-room widget that hosts the full UI and connection lifecycle.
UTDAudioRoomwidgetconst UTDAudioRoom({required String appId, required String appKey, required String userId, required String userName, required String roomId, required String roomOwnerId, Set<String> adminIds, UTDAudioRoomConfig config, List<UTDRoomMode> modes, UTDRoomController? controller, ...})Prebuilt audio-room widget. Mints a token directly from the engine with the publishable appKey (no backend), connects to LiveKit, and renders seats, chat and controls. Self-upgrades admins post-join.
Parameter
appIdStringerforderlichUTD Stream Engine app ID.
appKeyStringerforderlichPublishable app key (no backend); used to mint tokens via X-App-Key. The server secret never ships.
userIdStringerforderlichLocal user identity.
userNameStringerforderlichLocal user display name.
roomIdStringerforderlichRoom name to join.
roomOwnerIdStringerforderlichIdentity of the room owner; the owner joins as host.
adminIdsSet<String>Standard = const {}Identities the app treats as admins at join.
adminIdsResolverFuture<Set<String>> Function()?Standard = nullAsync admin-list source; triggers a non-blocking self-upgrade if it lists the local user.
adminIdsNowSet<String> Function()?Standard = nullSync admin-list probe used at token time without waiting.
layoutModeStringStandard = '3'Room mode id selecting the seat layout / seat count.
configUTDAudioRoomConfigStandard = const UTDAudioRoomConfig()Behavior, theming and custom-widget configuration.
modesList<UTDRoomMode>Standard = const []Custom room modes registered on the controller.
controllerUTDRoomController?Standard = nullOptional externally-owned controller (e.g. when restoring from minimize).
onControllerReadyvoid Function(UTDRoomController)?Standard = nullCalled once the controller is created/attached.
onConnectionChangedvoid Function(bool isConnected)?Standard = nullFired on connect success/failure.
onSeatTapvoid Function(int index, SeatState seat)?Standard = nullCalled when a seat is tapped.
onSeatChangedvoid Function(List<SeatState> seats)?Standard = nullCalled whenever seat state changes.
onConnectErrorvoid Function(Object error, StackTrace)?Standard = nullCalled when the initial connect fails.
Room controller
Top-level controller owning connection, sub-controllers, roles, bans and speaker flows.
UTDRoomControllerconstructorUTDRoomController()Creates the controller and its seat, media, chat, minimize and PiP sub-controllers. Usually created internally by UTDAudioRoom.
initApimethodvoid initApi({String baseUrl, String tokenBaseUrl, String? appId, required String appKey})Initializes the engine and token API clients. Must be called before connect/generateToken. Token issuance and in-room ops use different hosts.
Parameter
baseUrlStringStandard = UTDApiClient.defaultBaseUrlIn-room engine host for seat/speaker/ban/role calls.
tokenBaseUrlStringStandard = UTDApiClient.defaultTokenBaseUrlEdge host used for token generation.
appIdString?Standard = nullEngine app ID.
appKeyStringerforderlichPublishable app key sent as X-App-Key for minting.
connectmethodasyncFuture<void> connect({required String url, required String token, int seatCount = 9, bool enableMicOnJoin = false, bool useSpeaker = true, Map<String,String> userAttributes, String? roomName})Connects to the LiveKit room with the given url/token, initializes seats, wires data/role/ban/chat-lock handlers, and optionally enables the mic and speaker.
Parameter
urlStringerforderlichLiveKit server URL.
tokenStringerforderlichLiveKit access token.
seatCountintStandard = 9Number of seats to initialize.
enableMicOnJoinboolStandard = falsePublish the local mic on connect.
useSpeakerboolStandard = truePrefer Bluetooth/loudspeaker output on join.
userAttributesMap<String,String>Standard = const {}Cosmetic LiveKit participant attributes (avatar/frame/etc.).
roomNameString?Standard = nullRoom name used for seat API calls.
Rückgabewert: Future<void>
generateTokenmethodasyncFuture<UTDTokenResponse> generateToken({required String identity, required String roomName, required String roomOwnerId, String role = 'audience', String? name, int? seatCount, String? seatMode, int? hostSeat, String? modeId, ...})Requests a LiveKit token from the engine and applies the returned per-user bearer to the in-room clients. Throws UTDBannedException on a 403 banned response.
Parameter
identityStringerforderlichUser identity.
roomNameStringerforderlichRoom name.
roomOwnerIdStringerforderlichRoom owner identity.
typeStringStandard = 'audio_room'Room type.
roleStringStandard = 'audience'Requested role (host/admin/audience).
nameString?Standard = nullDisplay name.
seatCountint?Standard = nullInitial seat count (host only).
modeIdString?Standard = nullRoom mode id (host only).
Rückgabewert: Future<UTDTokenResponse>
leavemethodasyncFuture<void> leave()Leaves the room: tears down listeners, drains any pending mic publish, disconnects LiveKit, and resets minimize/PiP state.
Rückgabewert: Future<void>
changeRolemethodasyncFuture<UTDRoleChangeResult> changeRole({required String targetIdentity, required String role})Changes a participant's role (owner-only; server returns 403 otherwise). Optimistically caches the result; throws on REST error.
Parameter
targetIdentityStringerforderlichIdentity whose role changes.
roleStringerforderlichNew role (host/admin/guest/audience).
Rückgabewert: Future<UTDRoleChangeResult>
banUsermethodasyncFuture<bool> banUser(String identity, {String? reason, int? durationSeconds, bool global = false})Bans a user. Room-scoped by default; pass global true for a project-wide ban and durationSeconds null for permanent. Returns true on success.
Parameter
identityStringerforderlichUser to ban.
reasonString?Standard = nullOptional ban reason.
durationSecondsint?Standard = nullBan duration; null = permanent.
globalboolStandard = falseTrue for a project-wide ban.
Rückgabewert: Future<bool>
lockCommentsmethodasyncFuture<bool> lockComments()Locks room chat so only host/admin may send (host/admin-only). State is confirmed by the server broadcast, not set optimistically.
Rückgabewert: Future<bool>
requestToSpeakmethodasyncFuture<Map<String,dynamic>?> requestToSpeak()Audience requests to speak (request mode). Returns the API result map, or null on error / when not ready.
Rückgabewert: Future<Map<String,dynamic>?>
inviteToSpeakmethodasyncFuture<Map<String,dynamic>?> inviteToSpeak(String targetIdentity, {int? seatIndex})Host/admin invites a user to speak, optionally targeting a specific seat. Returns the API result map or null.
Parameter
targetIdentityStringerforderlichIdentity to invite.
seatIndexint?Standard = nullTarget seat the invitee is seated on if accepted.
Rückgabewert: Future<Map<String,dynamic>?>
isConnectedgetterbool get isConnectedTrue when the room connection state is connected.
Rückgabewert: bool
isHostOrAdmingetterbool get isHostOrAdminWhether the local participant's role is host or admin.
Rückgabewert: bool
participantsStreamgetterasyncStream<List<UTDParticipant>> get participantsStreamStream of all room participants, emitting on join/leave/attribute/metadata changes.
Rückgabewert: Stream<List<UTDParticipant>>
roleChangeStreamgetterasyncStream<UTDRoleChangeEvent> get roleChangeStreamStream of role changes for all participants (promotions, demotions, engine auto-corrections).
Rückgabewert: Stream<UTDRoleChangeEvent>
activeSpeakerspropertyfinal ValueNotifier<Set<String>> activeSpeakersReactive set of identities currently speaking, polled from LiveKit every 300ms.
Rückgabewert: ValueNotifier<Set<String>>
commentsLockedpropertyfinal ValueNotifier<bool> commentsLockedReactive whether room chat is currently locked (server-driven; never set optimistically).
Rückgabewert: ValueNotifier<bool>
onBannedcallbackvoid Function(UTDBanNotice notice)? onBannedFired once when the local user is banned from any source (data message, removal, or token 403). Wired internally by UTDAudioRoom.
Rückgabewert: void Function(UTDBanNotice)?
disposemethodvoid dispose()Releases all resources: timers, subscriptions, notifiers, sub-controllers and API clients.
Seat & stage control
Seat state management; all mutations go through the REST API and apply from server _seat_update messages.
UTDSeatControllerclassUTDSeatController(UTDRoomManager roomManager)Manages reactive seat state. Mutations call the REST API; local state updates only from _seat_update data messages or room _seats metadata.
takeSeatmethodasyncFuture<bool> takeSeat(int index, String userId)Requests microphone (and Bluetooth on Android) permissions then takes the seat at index via the API. State arrives via _seat_update.
Parameter
indexinterforderlichTarget seat index.
userIdStringerforderlichIdentity taking the seat.
Rückgabewert: Future<bool>
leaveSeatmethodasyncFuture<bool> leaveSeat(String userId)Leaves the user's current seat via the API.
Parameter
userIdStringerforderlichIdentity leaving the seat.
Rückgabewert: Future<bool>
moveSeatmethodasyncFuture<bool> moveSeat(String userId, int targetSeat)Atomically moves the user to another seat via the API.
Parameter
userIdStringerforderlichIdentity to move.
targetSeatinterforderlichDestination seat index.
Rückgabewert: Future<bool>
lockSeatmethodasyncFuture<bool> lockSeat(int index, {required String identity})Admin locks the seat at index (host/admin). State arrives via _seat_update.
Parameter
indexinterforderlichSeat to lock.
identityStringerforderlichActing host/admin identity.
Rückgabewert: Future<bool>
kickFromSeatmethodasyncFuture<bool> kickFromSeat(int index, {required String identity})Removes the occupant from the seat at index (host/admin only).
Parameter
indexinterforderlichSeat to vacate.
identityStringerforderlichActing host/admin identity.
Rückgabewert: Future<bool>
setupSeatsmethodasyncFuture<bool> setupSeats({required String identity, required int seatCount, required String seatMode, String? modeId})Changes seat configuration mid-room (count/mode/modeId) (host/admin only).
Parameter
identityStringerforderlichActing host/admin identity.
seatCountinterforderlichNew seat count.
seatModeStringerforderlichNew seat mode ('free'/'request').
modeIdString?Standard = nullNew room mode id.
Rückgabewert: Future<bool>
seatspropertyfinal ValueNotifier<List<SeatState>> seatsReactive list of all seat states.
Rückgabewert: ValueNotifier<List<SeatState>>
pendingRequestspropertyfinal ValueNotifier<List<SpeakerRequest>> pendingRequestsReactive list of pending speaker requests (for host/admin UI).
Rückgabewert: ValueNotifier<List<SpeakerRequest>>
getSeatIndexByUserIdmethodint getSeatIndexByUserId(String userId)Returns the seat index occupied by a user, or -1 if not seated.
Parameter
userIdStringerforderlichIdentity to look up.
Rückgabewert: int
isSeatAvailablemethodbool isSeatAvailable(int index, {String? userId})Whether the seat at index is empty, unlocked and not reserved for someone else.
Parameter
indexinterforderlichSeat index to test.
userIdString?Standard = nullUser to evaluate reservations against.
Rückgabewert: bool
Media control
Mic, camera, speaker and Bluetooth-routing controls, kept in sync with server/host-side mutes.
UTDMediaControllerclassUTDMediaController(UTDRoomManager roomManager)Controls mic, camera and speaker state and listens to LiveKit mute/permission events to keep reactive state authoritative.
setMicrophoneEnabledmethodasyncFuture<void> setMicrophoneEnabled(bool enabled)Enables/disables the local mic. Refuses to publish on a non-connected room to avoid the addTransceiver-on-disposed-track crash.
Parameter
enabledboolerforderlichTarget mic state.
Rückgabewert: Future<void>
toggleMicrophonemethodasyncFuture<void> toggleMicrophone()Toggles the local microphone on/off.
Rückgabewert: Future<void>
applyBluetoothAudioRoutingmethodasyncFuture<void> applyBluetoothAudioRouting()Re-applies the Android communication audio config with forceHandleAudioRouting so Bluetooth routing works after connect/publish; iOS uses the AVAudioSession path.
Rückgabewert: Future<void>
setSpeakerOnmethodasyncFuture<void> setSpeakerOn(bool on)Routes audio to the loudspeaker (true) or earpiece (false).
Parameter
onboolerforderlichSpeakerphone on/off.
Rückgabewert: Future<void>
muteAllRemoteAudiomethodvoid muteAllRemoteAudio(bool mute)Mutes/unmutes playback of all remote participants' audio (and enforces it on late-subscribed tracks).
Parameter
muteboolerforderlichWhether to mute remote audio.
isMicEnabledpropertyfinal ValueNotifier<bool> isMicEnabledReactive local mic state, kept in sync with LiveKit track mute/unmute events.
Rückgabewert: ValueNotifier<bool>
canPublishpropertyfinal ValueNotifier<bool> canPublishReactive whether the local participant may publish mic/camera; flips false on demotion.
Rückgabewert: ValueNotifier<bool>
Chat
Room chat send/receive with comment-lock gating and a bounded message buffer.
UTDChatControllerclassUTDChatController(UTDRoomManager roomManager)Sends and receives room chat over the data channel, enforcing the comment-lock gate and capping retained messages at 300.
sendMessagemethodasyncFuture<void> sendMessage(String text, {Map<String,dynamic>? userData})Sends a chat message (trimmed, non-empty). Refused when comments are locked and the local user is not host/admin.
Parameter
textStringerforderlichMessage body.
userDataMap<String,dynamic>?Standard = nullOptional extra payload attached to the message.
Rückgabewert: Future<void>
addDisplayMessagemethodvoid addDisplayMessage(UTDChatMessage message)Appends a message to the local list without sending it (used for system lines).
Parameter
messageUTDChatMessageerforderlichMessage to display locally.
clearMessagesmethodvoid clearMessages()Clears the local message list.
messagespropertyfinal ValueNotifier<List<UTDChatMessage>> messagesReactive list of chat messages (bounded to the most recent 300).
Rückgabewert: ValueNotifier<List<UTDChatMessage>>
Configuration & theming
Behavior config, color tokens, localized strings and minimize/PiP options.
UTDAudioRoomConfigconstructorconst UTDAudioRoomConfig({bool showControlsBar = true, bool turnOnMicrophoneWhenJoining = false, bool useSpeakerWhenJoining = true, int hostSeatIndex = 0, UTDRoomTheme theme, UTDRoomStrings? strings, bool enableMinimize = true, Widget? headerWidget, ...})Configures room behavior, theme, strings and custom section/seat builders. Replaces the prebuilt config.
Parameter
showControlsBarboolStandard = trueShow the default controls bar.
showSeatNamesboolStandard = trueShow occupant names under seats.
enableMinimizeboolStandard = trueAllow minimizing the room to a floating overlay.
turnOnMicrophoneWhenJoiningboolStandard = falsePublish the mic on join.
useSpeakerWhenJoiningboolStandard = truePrefer speaker/Bluetooth output on join.
hostSeatIndexintStandard = 0Seat index reserved for the host.
themeUTDRoomThemeStandard = const UTDRoomTheme()Color tokens for the default UI.
stringsUTDRoomStrings?Standard = nullLocalized strings; null = English defaults.
autoHostMicboolStandard = trueAuto-enable the host's mic even if join-mic is false.
autoSeatHostboolStandard = trueAuto-seat the host on hostSeatIndex if empty.
headerWidgetWidget?Standard = nullCustom header replacing the default.
seatBuilderWidget Function(SeatState, double)?Standard = nullCustom builder for a seat slot.
avatarBuilderWidget Function(String,double,Map<String,String>,bool,int,String)?Standard = nullCustom occupant avatar builder.
userInRoomAttributesMap<String,String>Standard = const {}Cosmetic attributes published to other participants.
UTDAudioRoomConfig.hostconstructorfactory UTDAudioRoomConfig.host()Factory preset for a host (microphone on when joining).
resolveStringsmethodUTDRoomStrings resolveStrings()Returns the configured strings or the English defaults.
Rückgabewert: UTDRoomStrings
UTDRoomThemeconstructorconst UTDRoomTheme({Color background, Color surface, Color onSurface, Color primary, Color danger, Color seatRingSpeaking, Color badgeHost, Color badgeAdmin, Color badgeGuest, Color sheetBackground, Color bubbleBackground, ...})Color tokens for the built-in default UI. Every field has a dark-room default, so const UTDRoomTheme() is a complete theme.
Parameter
backgroundColorStandard = Color(0xFF14121C)Full-screen room background.
primaryColorStandard = Color(0xFF6C5CE7)Accent / call-to-action color.
dangerColorStandard = Color(0xFFE74C3C)Destructive color (leave/kick/ban).
seatRingSpeakingColorStandard = Color(0xFF2ECC71)Ring around an actively-speaking seat.
badgeHostColorStandard = Color(0xFFFFA726)Host role badge color.
badgeAdminColorStandard = Color(0xFF448AFF)Admin role badge color.
copyWithmethodUTDRoomTheme copyWith({Color? background, Color? primary, Color? danger, ...})Returns a copy of the theme overriding only the supplied color tokens.
Rückgabewert: UTDRoomTheme
UTDRoomStrings.enconstructorfactory UTDRoomStrings.en()English defaults for all built-in UI labels (seat actions, requests, host panels, comment-lock, templated lines).
UTDRoomStrings.arconstructorfactory UTDRoomStrings.ar()Arabic defaults for all built-in UI labels.
UTDMinimizeConfigconstructorconst UTDMinimizeConfig({VoidCallback? onClose, MiniOverlayBuilder? overlayBuilder, double overlayWidth = 120, double overlayHeight = 120, bool enableOSPip = false, int pipAspectWidth = 1, int pipAspectHeight = 1, ...})Configures the minimize floating overlay and optional Android OS-level Picture-in-Picture (enableOSPip).
Parameter
onCloseVoidCallback?Standard = nullCalled when the room is closed from the overlay.
overlayBuilderMiniOverlayBuilder?Standard = nullCustom floating-overlay builder.
enableOSPipboolStandard = falseEnable Android 12+ system PiP in addition to the overlay.
pipAspectWidthintStandard = 1PiP aspect ratio numerator.
pipAspectHeightintStandard = 1PiP aspect ratio denominator.
Models & enums
Data models for seats, room modes, chat and connection state.
SeatStateclassconst SeatState({required int index, String? occupantUserId, bool isLocked = false, bool isMuted = false, String? reservedFor, Map<String,String> attributes})Immutable (Equatable) state of a single seat: index, occupant, lock/mute flags, reservation and occupant attributes.
Parameter
indexinterforderlichSeat index (0 = host seat).
occupantUserIdString?Standard = nullOccupant identity; null = empty.
isLockedboolStandard = falseWhether the seat is admin-locked.
isMutedboolStandard = falseWhether the occupant's mic is muted.
reservedForString?Standard = nullIdentity this seat is reserved for.
attributesMap<String,String>Standard = const {}Occupant cosmetic attributes (avatar, frame, etc.).
SpeakerRequestclassconst SpeakerRequest({required int id, required String identity, String? createdAt})A pending request to speak: id, requester identity and createdAt timestamp.
Parameter
idinterforderlichRequest id.
identityStringerforderlichRequesting identity.
createdAtString?Standard = nullCreation timestamp.
RoomSeatStateclassconst RoomSeatState({required int count, required String mode, String? modeId, required List<SeatState> seats, required List<SpeakerRequest> requests})Full seat snapshot from the backend _seats namespace: count, mode, modeId, seats and pending requests.
Parameter
countinterforderlichSeat count.
modeStringerforderlichSeat mode ('free'/'request').
modeIdString?Standard = nullRoom mode id.
seatsList<SeatState>erforderlichPer-seat states.
requestsList<SpeakerRequest>erforderlichPending speaker requests.
UTDRoomModeclassconst UTDRoomMode({required String id, required int seatCount, required List<List<int>> rows, double? seatSize, UTDSeatContainerBuilder? containerBuilder, UTDBackgroundBuilder? backgroundBuilder, String? displayName})Defines a seat layout mode: id, seat count, row arrangement and optional custom container/background builders. Identity is its id.
Parameter
idStringerforderlichUnique mode id (e.g. '3').
seatCountinterforderlichNumber of seats.
rowsList<List<int>>erforderlichSeat-index layout per row.
seatSizedouble?Standard = nullExplicit seat size override.
containerBuilderUTDSeatContainerBuilder?Standard = nullCustom seat-grid container builder.
backgroundBuilderUTDBackgroundBuilder?Standard = nullMode-specific background builder.
computeSeatSizemethoddouble computeSeatSize(double screenWidth)Single source of truth for the seat slot size in logical px, scaled sub-linearly (sqrt) with screen width and clamped to 52–120.
Parameter
screenWidthdoubleerforderlichAvailable screen width.
Rückgabewert: double
UTDRoomMode.defaultModefieldstatic const UTDRoomMode defaultModeBuilt-in default mode: id '3', 9 seats in a 1-4-4 layout.
Rückgabewert: UTDRoomMode
UTDChatMessageclassUTDChatMessage({required String senderUserId, required String senderName, required String text, required DateTime timestamp, Map<String,dynamic> userData, String? messageID})A chat message with sender, text, timestamp, arbitrary userData and an auto-generated messageID. JSON-serializable.
Parameter
senderUserIdStringerforderlichSender identity.
senderNameStringerforderlichSender display name.
textStringerforderlichMessage body.
timestampDateTimeerforderlichMessage time.
userDataMap<String,dynamic>Standard = const {}Extra payload (e.g. system-line markers).
messageIDString?Standard = nullMessage id; auto-generated when omitted.
UTDConnectionStateenumenum UTDConnectionState { disconnected, connecting, connected, reconnecting, error }Room connection state: disconnected, connecting, connected, reconnecting, error.
Rückgabewert: UTDConnectionState
Bereit, mit UTD zu entwickeln?
Erstellen Sie Ihr Konto, laden Sie Ihre Master-Wallet auf und aktivieren Sie die Dienste, die Sie brauchen.