< Flutter UIKit />
UTD Audio Room Kit
Koltuklar, gerçek zamanlı sohbet ve moderasyonla hazır canlı ses odaları.
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
Tam arayüz
0
Backend sunucu
EN · AR
Yerleşik i18n
PiP
+ küçültme
< utd_audio_room_kit />
Öne çıkan özellikler
LiveKit ve UTD Stream Engine ile çalışan, canlı ses odası deneyimleri için eksiksiz ve özelleştirilebilir bir Flutter paketi. Koltuk yönetimi, konuşma istekleri, üye listeleri, gerçek zamanlı sohbet, medya kontrolleri, küçültme/PiP ve eksiksiz host/admin moderasyonu sunan hazır oda arayüzü — üstelik backend token sunucusuna gerek kalmadan.
Hazır ses odası arayüzü — ek kod gerektirmez
Koltuk yönetimi: oturma, ayrılma, değiştirme, kilitleme, kilit açma, atma, susturma, takas
Onayla/reddet seçenekli konuşma isteği kuyruğu
Host/admin işlemli üye listesi (susturma, atma, davet etme, yasaklama, terfi/tenzil)
Toplu işleme ve yineleme önlemeli, data-channel üzerinden gerçek zamanlı sohbet
Bluetooth önceliklendiren yönlendirmeyle mikrofon ve hoparlör kontrolleri
Kademeli yeniden bağlanma (hafif eşitleme <15s, tam eşitleme <60s)
Yüzen yer paylaşımına küçültme ve Android OS Picture-in-Picture
Tema özelleştirme ve yerleşik i18n (EN/AR)
Tüm bölümlerin değiştirilmesi (başlık, mesajlar, kontroller, arka plan, koltuklar)
Backend token sunucusu yok — appKey tabanlı token akışı
< utd_audio_room_kit />
Başlayın
Kurulum
flutter pub add utd_audio_room_kitpub.dev üzerinde görüntüle
Koltuklar, gerçek zamanlı sohbet ve moderasyonla hazır canlı ses odaları.
< utd_audio_room_kit />
API referansı
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.
Parametreler
appIdStringzorunluUTD Stream Engine app ID.
appKeyStringzorunluPublishable app key (no backend); used to mint tokens via X-App-Key. The server secret never ships.
userIdStringzorunluLocal user identity.
userNameStringzorunluLocal user display name.
roomIdStringzorunluRoom name to join.
roomOwnerIdStringzorunluIdentity of the room owner; the owner joins as host.
adminIdsSet<String>Varsayılan = const {}Identities the app treats as admins at join.
adminIdsResolverFuture<Set<String>> Function()?Varsayılan = nullAsync admin-list source; triggers a non-blocking self-upgrade if it lists the local user.
adminIdsNowSet<String> Function()?Varsayılan = nullSync admin-list probe used at token time without waiting.
layoutModeStringVarsayılan = '3'Room mode id selecting the seat layout / seat count.
configUTDAudioRoomConfigVarsayılan = const UTDAudioRoomConfig()Behavior, theming and custom-widget configuration.
modesList<UTDRoomMode>Varsayılan = const []Custom room modes registered on the controller.
controllerUTDRoomController?Varsayılan = nullOptional externally-owned controller (e.g. when restoring from minimize).
onControllerReadyvoid Function(UTDRoomController)?Varsayılan = nullCalled once the controller is created/attached.
onConnectionChangedvoid Function(bool isConnected)?Varsayılan = nullFired on connect success/failure.
onSeatTapvoid Function(int index, SeatState seat)?Varsayılan = nullCalled when a seat is tapped.
onSeatChangedvoid Function(List<SeatState> seats)?Varsayılan = nullCalled whenever seat state changes.
onConnectErrorvoid Function(Object error, StackTrace)?Varsayılan = 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.
Parametreler
baseUrlStringVarsayılan = UTDApiClient.defaultBaseUrlIn-room engine host for seat/speaker/ban/role calls.
tokenBaseUrlStringVarsayılan = UTDApiClient.defaultTokenBaseUrlEdge host used for token generation.
appIdString?Varsayılan = nullEngine app ID.
appKeyStringzorunluPublishable 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.
Parametreler
urlStringzorunluLiveKit server URL.
tokenStringzorunluLiveKit access token.
seatCountintVarsayılan = 9Number of seats to initialize.
enableMicOnJoinboolVarsayılan = falsePublish the local mic on connect.
useSpeakerboolVarsayılan = truePrefer Bluetooth/loudspeaker output on join.
userAttributesMap<String,String>Varsayılan = const {}Cosmetic LiveKit participant attributes (avatar/frame/etc.).
roomNameString?Varsayılan = nullRoom name used for seat API calls.
Döndürür: 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.
Parametreler
identityStringzorunluUser identity.
roomNameStringzorunluRoom name.
roomOwnerIdStringzorunluRoom owner identity.
typeStringVarsayılan = 'audio_room'Room type.
roleStringVarsayılan = 'audience'Requested role (host/admin/audience).
nameString?Varsayılan = nullDisplay name.
seatCountint?Varsayılan = nullInitial seat count (host only).
modeIdString?Varsayılan = nullRoom mode id (host only).
Döndürür: Future<UTDTokenResponse>
leavemethodasyncFuture<void> leave()Leaves the room: tears down listeners, drains any pending mic publish, disconnects LiveKit, and resets minimize/PiP state.
Döndürür: 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.
Parametreler
targetIdentityStringzorunluIdentity whose role changes.
roleStringzorunluNew role (host/admin/guest/audience).
Döndürür: 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.
Parametreler
identityStringzorunluUser to ban.
reasonString?Varsayılan = nullOptional ban reason.
durationSecondsint?Varsayılan = nullBan duration; null = permanent.
globalboolVarsayılan = falseTrue for a project-wide ban.
Döndürür: 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.
Döndürür: 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.
Döndürür: 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.
Parametreler
targetIdentityStringzorunluIdentity to invite.
seatIndexint?Varsayılan = nullTarget seat the invitee is seated on if accepted.
Döndürür: Future<Map<String,dynamic>?>
isConnectedgetterbool get isConnectedTrue when the room connection state is connected.
Döndürür: bool
isHostOrAdmingetterbool get isHostOrAdminWhether the local participant's role is host or admin.
Döndürür: bool
participantsStreamgetterasyncStream<List<UTDParticipant>> get participantsStreamStream of all room participants, emitting on join/leave/attribute/metadata changes.
Döndürür: Stream<List<UTDParticipant>>
roleChangeStreamgetterasyncStream<UTDRoleChangeEvent> get roleChangeStreamStream of role changes for all participants (promotions, demotions, engine auto-corrections).
Döndürür: Stream<UTDRoleChangeEvent>
activeSpeakerspropertyfinal ValueNotifier<Set<String>> activeSpeakersReactive set of identities currently speaking, polled from LiveKit every 300ms.
Döndürür: ValueNotifier<Set<String>>
commentsLockedpropertyfinal ValueNotifier<bool> commentsLockedReactive whether room chat is currently locked (server-driven; never set optimistically).
Döndürür: 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.
Döndürür: 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.
Parametreler
indexintzorunluTarget seat index.
userIdStringzorunluIdentity taking the seat.
Döndürür: Future<bool>
leaveSeatmethodasyncFuture<bool> leaveSeat(String userId)Leaves the user's current seat via the API.
Parametreler
userIdStringzorunluIdentity leaving the seat.
Döndürür: Future<bool>
moveSeatmethodasyncFuture<bool> moveSeat(String userId, int targetSeat)Atomically moves the user to another seat via the API.
Parametreler
userIdStringzorunluIdentity to move.
targetSeatintzorunluDestination seat index.
Döndürür: Future<bool>
lockSeatmethodasyncFuture<bool> lockSeat(int index, {required String identity})Admin locks the seat at index (host/admin). State arrives via _seat_update.
Parametreler
indexintzorunluSeat to lock.
identityStringzorunluActing host/admin identity.
Döndürür: Future<bool>
kickFromSeatmethodasyncFuture<bool> kickFromSeat(int index, {required String identity})Removes the occupant from the seat at index (host/admin only).
Parametreler
indexintzorunluSeat to vacate.
identityStringzorunluActing host/admin identity.
Döndürür: 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).
Parametreler
identityStringzorunluActing host/admin identity.
seatCountintzorunluNew seat count.
seatModeStringzorunluNew seat mode ('free'/'request').
modeIdString?Varsayılan = nullNew room mode id.
Döndürür: Future<bool>
seatspropertyfinal ValueNotifier<List<SeatState>> seatsReactive list of all seat states.
Döndürür: ValueNotifier<List<SeatState>>
pendingRequestspropertyfinal ValueNotifier<List<SpeakerRequest>> pendingRequestsReactive list of pending speaker requests (for host/admin UI).
Döndürür: ValueNotifier<List<SpeakerRequest>>
getSeatIndexByUserIdmethodint getSeatIndexByUserId(String userId)Returns the seat index occupied by a user, or -1 if not seated.
Parametreler
userIdStringzorunluIdentity to look up.
Döndürür: int
isSeatAvailablemethodbool isSeatAvailable(int index, {String? userId})Whether the seat at index is empty, unlocked and not reserved for someone else.
Parametreler
indexintzorunluSeat index to test.
userIdString?Varsayılan = nullUser to evaluate reservations against.
Döndürür: 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.
Parametreler
enabledboolzorunluTarget mic state.
Döndürür: Future<void>
toggleMicrophonemethodasyncFuture<void> toggleMicrophone()Toggles the local microphone on/off.
Döndürür: 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.
Döndürür: Future<void>
setSpeakerOnmethodasyncFuture<void> setSpeakerOn(bool on)Routes audio to the loudspeaker (true) or earpiece (false).
Parametreler
onboolzorunluSpeakerphone on/off.
Döndürür: Future<void>
muteAllRemoteAudiomethodvoid muteAllRemoteAudio(bool mute)Mutes/unmutes playback of all remote participants' audio (and enforces it on late-subscribed tracks).
Parametreler
muteboolzorunluWhether to mute remote audio.
isMicEnabledpropertyfinal ValueNotifier<bool> isMicEnabledReactive local mic state, kept in sync with LiveKit track mute/unmute events.
Döndürür: ValueNotifier<bool>
canPublishpropertyfinal ValueNotifier<bool> canPublishReactive whether the local participant may publish mic/camera; flips false on demotion.
Döndürür: 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.
Parametreler
textStringzorunluMessage body.
userDataMap<String,dynamic>?Varsayılan = nullOptional extra payload attached to the message.
Döndürür: Future<void>
addDisplayMessagemethodvoid addDisplayMessage(UTDChatMessage message)Appends a message to the local list without sending it (used for system lines).
Parametreler
messageUTDChatMessagezorunluMessage 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).
Döndürür: 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.
Parametreler
showControlsBarboolVarsayılan = trueShow the default controls bar.
showSeatNamesboolVarsayılan = trueShow occupant names under seats.
enableMinimizeboolVarsayılan = trueAllow minimizing the room to a floating overlay.
turnOnMicrophoneWhenJoiningboolVarsayılan = falsePublish the mic on join.
useSpeakerWhenJoiningboolVarsayılan = truePrefer speaker/Bluetooth output on join.
hostSeatIndexintVarsayılan = 0Seat index reserved for the host.
themeUTDRoomThemeVarsayılan = const UTDRoomTheme()Color tokens for the default UI.
stringsUTDRoomStrings?Varsayılan = nullLocalized strings; null = English defaults.
autoHostMicboolVarsayılan = trueAuto-enable the host's mic even if join-mic is false.
autoSeatHostboolVarsayılan = trueAuto-seat the host on hostSeatIndex if empty.
headerWidgetWidget?Varsayılan = nullCustom header replacing the default.
seatBuilderWidget Function(SeatState, double)?Varsayılan = nullCustom builder for a seat slot.
avatarBuilderWidget Function(String,double,Map<String,String>,bool,int,String)?Varsayılan = nullCustom occupant avatar builder.
userInRoomAttributesMap<String,String>Varsayılan = 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.
Döndürür: 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.
Parametreler
backgroundColorVarsayılan = Color(0xFF14121C)Full-screen room background.
primaryColorVarsayılan = Color(0xFF6C5CE7)Accent / call-to-action color.
dangerColorVarsayılan = Color(0xFFE74C3C)Destructive color (leave/kick/ban).
seatRingSpeakingColorVarsayılan = Color(0xFF2ECC71)Ring around an actively-speaking seat.
badgeHostColorVarsayılan = Color(0xFFFFA726)Host role badge color.
badgeAdminColorVarsayılan = 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.
Döndürür: 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).
Parametreler
onCloseVoidCallback?Varsayılan = nullCalled when the room is closed from the overlay.
overlayBuilderMiniOverlayBuilder?Varsayılan = nullCustom floating-overlay builder.
enableOSPipboolVarsayılan = falseEnable Android 12+ system PiP in addition to the overlay.
pipAspectWidthintVarsayılan = 1PiP aspect ratio numerator.
pipAspectHeightintVarsayılan = 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.
Parametreler
indexintzorunluSeat index (0 = host seat).
occupantUserIdString?Varsayılan = nullOccupant identity; null = empty.
isLockedboolVarsayılan = falseWhether the seat is admin-locked.
isMutedboolVarsayılan = falseWhether the occupant's mic is muted.
reservedForString?Varsayılan = nullIdentity this seat is reserved for.
attributesMap<String,String>Varsayılan = 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.
Parametreler
idintzorunluRequest id.
identityStringzorunluRequesting identity.
createdAtString?Varsayılan = 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.
Parametreler
countintzorunluSeat count.
modeStringzorunluSeat mode ('free'/'request').
modeIdString?Varsayılan = nullRoom mode id.
seatsList<SeatState>zorunluPer-seat states.
requestsList<SpeakerRequest>zorunluPending 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.
Parametreler
idStringzorunluUnique mode id (e.g. '3').
seatCountintzorunluNumber of seats.
rowsList<List<int>>zorunluSeat-index layout per row.
seatSizedouble?Varsayılan = nullExplicit seat size override.
containerBuilderUTDSeatContainerBuilder?Varsayılan = nullCustom seat-grid container builder.
backgroundBuilderUTDBackgroundBuilder?Varsayılan = 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.
Parametreler
screenWidthdoublezorunluAvailable screen width.
Döndürür: double
UTDRoomMode.defaultModefieldstatic const UTDRoomMode defaultModeBuilt-in default mode: id '3', 9 seats in a 1-4-4 layout.
Döndürür: 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.
Parametreler
senderUserIdStringzorunluSender identity.
senderNameStringzorunluSender display name.
textStringzorunluMessage body.
timestampDateTimezorunluMessage time.
userDataMap<String,dynamic>Varsayılan = const {}Extra payload (e.g. system-line markers).
messageIDString?Varsayılan = nullMessage id; auto-generated when omitted.
UTDConnectionStateenumenum UTDConnectionState { disconnected, connecting, connected, reconnecting, error }Room connection state: disconnected, connecting, connected, reconnecting, error.
Döndürür: UTDConnectionState
UTD ile inşa etmeye hazır mısınız?
Hesabınızı oluşturun, ana cüzdanınızı fonlayın ve ihtiyacınız olan hizmetleri açın.