개발자로 돌아가기

< Flutter UIKit />

UTD Audio Room Kit

좌석, 실시간 채팅, 모더레이션을 갖춘 바로 쓰는 라이브 오디오 룸.

버전 1.5.0pub.dev에서 보기
시작하기pub.dev에서 보기
iOS 11+Android 21+
audio_room_kit.dart
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

완전한 UI

0

백엔드 서버

EN · AR

내장 다국어

PiP

+ 최소화

< utd_audio_room_kit />

주요 기능

LiveKit과 UTD Stream Engine으로 구동되는 라이브 오디오 룸 경험을 위한 완전하고 커스터마이즈 가능한 Flutter 패키지입니다. 좌석 관리, 발언 요청, 멤버 목록, 실시간 채팅, 미디어 컨트롤, 최소화/PiP, 그리고 호스트/관리자 모더레이션을 모두 갖춘 바로 쓰는 룸 UI를 제공합니다 — 별도의 백엔드 토큰 서버가 필요 없습니다.

바로 쓰는 오디오 룸 UI — 추가 코드 불필요

좌석 관리: 앉기, 나가기, 이동, 잠금, 잠금 해제, 강퇴, 음소거, 자리 교체

승인/거부가 가능한 발언 요청 대기열

호스트/관리자 작업이 포함된 멤버 목록(음소거, 강퇴, 초대, 차단, 승격/강등)

배칭과 중복 제거를 갖춘 실시간 데이터 채널 채팅

Bluetooth 우선 라우팅을 적용한 마이크 및 스피커 컨트롤

계층형 재연결(라이트 동기화 <15s, 풀 동기화 <60s)

플로팅 오버레이로 최소화 및 Android OS Picture-in-Picture

테마 커스터마이즈 및 내장 다국어 지원(EN/AR)

전체 섹션 교체(헤더, 메시지, 컨트롤, 배경, 좌석)

백엔드 토큰 서버 불필요 — appKey 기반 토큰 흐름

< utd_audio_room_kit />

시작하기

1

설치

Terminal
flutter pub add utd_audio_room_kit
2

pub.dev에서 보기

좌석, 실시간 채팅, 모더레이션을 갖춘 바로 쓰는 라이브 오디오 룸.

pub.dev에서 보기

< utd_audio_room_kit />

API 레퍼런스

Main widget

The drop-in prebuilt audio-room widget that hosts the full UI and connection lifecycle.

UTDAudioRoomwidget
const 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.

매개변수

  • appIdString필수

    UTD Stream Engine app ID.

  • appKeyString필수

    Publishable app key (no backend); used to mint tokens via X-App-Key. The server secret never ships.

  • userIdString필수

    Local user identity.

  • userNameString필수

    Local user display name.

  • roomIdString필수

    Room name to join.

  • roomOwnerIdString필수

    Identity of the room owner; the owner joins as host.

  • adminIdsSet<String>기본값 = const {}

    Identities the app treats as admins at join.

  • adminIdsResolverFuture<Set<String>> Function()?기본값 = null

    Async admin-list source; triggers a non-blocking self-upgrade if it lists the local user.

  • adminIdsNowSet<String> Function()?기본값 = null

    Sync admin-list probe used at token time without waiting.

  • layoutModeString기본값 = '3'

    Room mode id selecting the seat layout / seat count.

  • configUTDAudioRoomConfig기본값 = const UTDAudioRoomConfig()

    Behavior, theming and custom-widget configuration.

  • modesList<UTDRoomMode>기본값 = const []

    Custom room modes registered on the controller.

  • controllerUTDRoomController?기본값 = null

    Optional externally-owned controller (e.g. when restoring from minimize).

  • onControllerReadyvoid Function(UTDRoomController)?기본값 = null

    Called once the controller is created/attached.

  • onConnectionChangedvoid Function(bool isConnected)?기본값 = null

    Fired on connect success/failure.

  • onSeatTapvoid Function(int index, SeatState seat)?기본값 = null

    Called when a seat is tapped.

  • onSeatChangedvoid Function(List<SeatState> seats)?기본값 = null

    Called whenever seat state changes.

  • onConnectErrorvoid Function(Object error, StackTrace)?기본값 = null

    Called when the initial connect fails.

Room controller

Top-level controller owning connection, sub-controllers, roles, bans and speaker flows.

UTDRoomControllerconstructor
UTDRoomController()

Creates the controller and its seat, media, chat, minimize and PiP sub-controllers. Usually created internally by UTDAudioRoom.

initApimethod
void 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.

매개변수

  • baseUrlString기본값 = UTDApiClient.defaultBaseUrl

    In-room engine host for seat/speaker/ban/role calls.

  • tokenBaseUrlString기본값 = UTDApiClient.defaultTokenBaseUrl

    Edge host used for token generation.

  • appIdString?기본값 = null

    Engine app ID.

  • appKeyString필수

    Publishable app key sent as X-App-Key for minting.

connectmethodasync
Future<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.

매개변수

  • urlString필수

    LiveKit server URL.

  • tokenString필수

    LiveKit access token.

  • seatCountint기본값 = 9

    Number of seats to initialize.

  • enableMicOnJoinbool기본값 = false

    Publish the local mic on connect.

  • useSpeakerbool기본값 = true

    Prefer Bluetooth/loudspeaker output on join.

  • userAttributesMap<String,String>기본값 = const {}

    Cosmetic LiveKit participant attributes (avatar/frame/etc.).

  • roomNameString?기본값 = null

    Room name used for seat API calls.

반환값: Future<void>

generateTokenmethodasync
Future<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.

매개변수

  • identityString필수

    User identity.

  • roomNameString필수

    Room name.

  • roomOwnerIdString필수

    Room owner identity.

  • typeString기본값 = 'audio_room'

    Room type.

  • roleString기본값 = 'audience'

    Requested role (host/admin/audience).

  • nameString?기본값 = null

    Display name.

  • seatCountint?기본값 = null

    Initial seat count (host only).

  • modeIdString?기본값 = null

    Room mode id (host only).

반환값: Future<UTDTokenResponse>

leavemethodasync
Future<void> leave()

Leaves the room: tears down listeners, drains any pending mic publish, disconnects LiveKit, and resets minimize/PiP state.

반환값: Future<void>

changeRolemethodasync
Future<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.

매개변수

  • targetIdentityString필수

    Identity whose role changes.

  • roleString필수

    New role (host/admin/guest/audience).

반환값: Future<UTDRoleChangeResult>

banUsermethodasync
Future<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.

매개변수

  • identityString필수

    User to ban.

  • reasonString?기본값 = null

    Optional ban reason.

  • durationSecondsint?기본값 = null

    Ban duration; null = permanent.

  • globalbool기본값 = false

    True for a project-wide ban.

반환값: Future<bool>

lockCommentsmethodasync
Future<bool> lockComments()

Locks room chat so only host/admin may send (host/admin-only). State is confirmed by the server broadcast, not set optimistically.

반환값: Future<bool>

requestToSpeakmethodasync
Future<Map<String,dynamic>?> requestToSpeak()

Audience requests to speak (request mode). Returns the API result map, or null on error / when not ready.

반환값: Future<Map<String,dynamic>?>

inviteToSpeakmethodasync
Future<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.

매개변수

  • targetIdentityString필수

    Identity to invite.

  • seatIndexint?기본값 = null

    Target seat the invitee is seated on if accepted.

반환값: Future<Map<String,dynamic>?>

isConnectedgetter
bool get isConnected

True when the room connection state is connected.

반환값: bool

isHostOrAdmingetter
bool get isHostOrAdmin

Whether the local participant's role is host or admin.

반환값: bool

participantsStreamgetterasync
Stream<List<UTDParticipant>> get participantsStream

Stream of all room participants, emitting on join/leave/attribute/metadata changes.

반환값: Stream<List<UTDParticipant>>

roleChangeStreamgetterasync
Stream<UTDRoleChangeEvent> get roleChangeStream

Stream of role changes for all participants (promotions, demotions, engine auto-corrections).

반환값: Stream<UTDRoleChangeEvent>

activeSpeakersproperty
final ValueNotifier<Set<String>> activeSpeakers

Reactive set of identities currently speaking, polled from LiveKit every 300ms.

반환값: ValueNotifier<Set<String>>

commentsLockedproperty
final ValueNotifier<bool> commentsLocked

Reactive whether room chat is currently locked (server-driven; never set optimistically).

반환값: ValueNotifier<bool>

onBannedcallback
void Function(UTDBanNotice notice)? onBanned

Fired once when the local user is banned from any source (data message, removal, or token 403). Wired internally by UTDAudioRoom.

반환값: void Function(UTDBanNotice)?

disposemethod
void 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.

UTDSeatControllerclass
UTDSeatController(UTDRoomManager roomManager)

Manages reactive seat state. Mutations call the REST API; local state updates only from _seat_update data messages or room _seats metadata.

takeSeatmethodasync
Future<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.

매개변수

  • indexint필수

    Target seat index.

  • userIdString필수

    Identity taking the seat.

반환값: Future<bool>

leaveSeatmethodasync
Future<bool> leaveSeat(String userId)

Leaves the user's current seat via the API.

매개변수

  • userIdString필수

    Identity leaving the seat.

반환값: Future<bool>

moveSeatmethodasync
Future<bool> moveSeat(String userId, int targetSeat)

Atomically moves the user to another seat via the API.

매개변수

  • userIdString필수

    Identity to move.

  • targetSeatint필수

    Destination seat index.

반환값: Future<bool>

lockSeatmethodasync
Future<bool> lockSeat(int index, {required String identity})

Admin locks the seat at index (host/admin). State arrives via _seat_update.

매개변수

  • indexint필수

    Seat to lock.

  • identityString필수

    Acting host/admin identity.

반환값: Future<bool>

kickFromSeatmethodasync
Future<bool> kickFromSeat(int index, {required String identity})

Removes the occupant from the seat at index (host/admin only).

매개변수

  • indexint필수

    Seat to vacate.

  • identityString필수

    Acting host/admin identity.

반환값: Future<bool>

setupSeatsmethodasync
Future<bool> setupSeats({required String identity, required int seatCount, required String seatMode, String? modeId})

Changes seat configuration mid-room (count/mode/modeId) (host/admin only).

매개변수

  • identityString필수

    Acting host/admin identity.

  • seatCountint필수

    New seat count.

  • seatModeString필수

    New seat mode ('free'/'request').

  • modeIdString?기본값 = null

    New room mode id.

반환값: Future<bool>

seatsproperty
final ValueNotifier<List<SeatState>> seats

Reactive list of all seat states.

반환값: ValueNotifier<List<SeatState>>

pendingRequestsproperty
final ValueNotifier<List<SpeakerRequest>> pendingRequests

Reactive list of pending speaker requests (for host/admin UI).

반환값: ValueNotifier<List<SpeakerRequest>>

getSeatIndexByUserIdmethod
int getSeatIndexByUserId(String userId)

Returns the seat index occupied by a user, or -1 if not seated.

매개변수

  • userIdString필수

    Identity to look up.

반환값: int

isSeatAvailablemethod
bool isSeatAvailable(int index, {String? userId})

Whether the seat at index is empty, unlocked and not reserved for someone else.

매개변수

  • indexint필수

    Seat index to test.

  • userIdString?기본값 = null

    User to evaluate reservations against.

반환값: bool

Media control

Mic, camera, speaker and Bluetooth-routing controls, kept in sync with server/host-side mutes.

UTDMediaControllerclass
UTDMediaController(UTDRoomManager roomManager)

Controls mic, camera and speaker state and listens to LiveKit mute/permission events to keep reactive state authoritative.

setMicrophoneEnabledmethodasync
Future<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.

매개변수

  • enabledbool필수

    Target mic state.

반환값: Future<void>

toggleMicrophonemethodasync
Future<void> toggleMicrophone()

Toggles the local microphone on/off.

반환값: Future<void>

applyBluetoothAudioRoutingmethodasync
Future<void> applyBluetoothAudioRouting()

Re-applies the Android communication audio config with forceHandleAudioRouting so Bluetooth routing works after connect/publish; iOS uses the AVAudioSession path.

반환값: Future<void>

setSpeakerOnmethodasync
Future<void> setSpeakerOn(bool on)

Routes audio to the loudspeaker (true) or earpiece (false).

매개변수

  • onbool필수

    Speakerphone on/off.

반환값: Future<void>

muteAllRemoteAudiomethod
void muteAllRemoteAudio(bool mute)

Mutes/unmutes playback of all remote participants' audio (and enforces it on late-subscribed tracks).

매개변수

  • mutebool필수

    Whether to mute remote audio.

isMicEnabledproperty
final ValueNotifier<bool> isMicEnabled

Reactive local mic state, kept in sync with LiveKit track mute/unmute events.

반환값: ValueNotifier<bool>

canPublishproperty
final ValueNotifier<bool> canPublish

Reactive whether the local participant may publish mic/camera; flips false on demotion.

반환값: ValueNotifier<bool>

Chat

Room chat send/receive with comment-lock gating and a bounded message buffer.

UTDChatControllerclass
UTDChatController(UTDRoomManager roomManager)

Sends and receives room chat over the data channel, enforcing the comment-lock gate and capping retained messages at 300.

sendMessagemethodasync
Future<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.

매개변수

  • textString필수

    Message body.

  • userDataMap<String,dynamic>?기본값 = null

    Optional extra payload attached to the message.

반환값: Future<void>

addDisplayMessagemethod
void addDisplayMessage(UTDChatMessage message)

Appends a message to the local list without sending it (used for system lines).

매개변수

  • messageUTDChatMessage필수

    Message to display locally.

clearMessagesmethod
void clearMessages()

Clears the local message list.

messagesproperty
final ValueNotifier<List<UTDChatMessage>> messages

Reactive list of chat messages (bounded to the most recent 300).

반환값: ValueNotifier<List<UTDChatMessage>>

Configuration & theming

Behavior config, color tokens, localized strings and minimize/PiP options.

UTDAudioRoomConfigconstructor
const 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.

매개변수

  • showControlsBarbool기본값 = true

    Show the default controls bar.

  • showSeatNamesbool기본값 = true

    Show occupant names under seats.

  • enableMinimizebool기본값 = true

    Allow minimizing the room to a floating overlay.

  • turnOnMicrophoneWhenJoiningbool기본값 = false

    Publish the mic on join.

  • useSpeakerWhenJoiningbool기본값 = true

    Prefer speaker/Bluetooth output on join.

  • hostSeatIndexint기본값 = 0

    Seat index reserved for the host.

  • themeUTDRoomTheme기본값 = const UTDRoomTheme()

    Color tokens for the default UI.

  • stringsUTDRoomStrings?기본값 = null

    Localized strings; null = English defaults.

  • autoHostMicbool기본값 = true

    Auto-enable the host's mic even if join-mic is false.

  • autoSeatHostbool기본값 = true

    Auto-seat the host on hostSeatIndex if empty.

  • headerWidgetWidget?기본값 = null

    Custom header replacing the default.

  • seatBuilderWidget Function(SeatState, double)?기본값 = null

    Custom builder for a seat slot.

  • avatarBuilderWidget Function(String,double,Map<String,String>,bool,int,String)?기본값 = null

    Custom occupant avatar builder.

  • userInRoomAttributesMap<String,String>기본값 = const {}

    Cosmetic attributes published to other participants.

UTDAudioRoomConfig.hostconstructor
factory UTDAudioRoomConfig.host()

Factory preset for a host (microphone on when joining).

resolveStringsmethod
UTDRoomStrings resolveStrings()

Returns the configured strings or the English defaults.

반환값: UTDRoomStrings

UTDRoomThemeconstructor
const 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.

매개변수

  • backgroundColor기본값 = Color(0xFF14121C)

    Full-screen room background.

  • primaryColor기본값 = Color(0xFF6C5CE7)

    Accent / call-to-action color.

  • dangerColor기본값 = Color(0xFFE74C3C)

    Destructive color (leave/kick/ban).

  • seatRingSpeakingColor기본값 = Color(0xFF2ECC71)

    Ring around an actively-speaking seat.

  • badgeHostColor기본값 = Color(0xFFFFA726)

    Host role badge color.

  • badgeAdminColor기본값 = Color(0xFF448AFF)

    Admin role badge color.

copyWithmethod
UTDRoomTheme copyWith({Color? background, Color? primary, Color? danger, ...})

Returns a copy of the theme overriding only the supplied color tokens.

반환값: UTDRoomTheme

UTDRoomStrings.enconstructor
factory UTDRoomStrings.en()

English defaults for all built-in UI labels (seat actions, requests, host panels, comment-lock, templated lines).

UTDRoomStrings.arconstructor
factory UTDRoomStrings.ar()

Arabic defaults for all built-in UI labels.

UTDMinimizeConfigconstructor
const 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).

매개변수

  • onCloseVoidCallback?기본값 = null

    Called when the room is closed from the overlay.

  • overlayBuilderMiniOverlayBuilder?기본값 = null

    Custom floating-overlay builder.

  • enableOSPipbool기본값 = false

    Enable Android 12+ system PiP in addition to the overlay.

  • pipAspectWidthint기본값 = 1

    PiP aspect ratio numerator.

  • pipAspectHeightint기본값 = 1

    PiP aspect ratio denominator.

Models & enums

Data models for seats, room modes, chat and connection state.

SeatStateclass
const 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.

매개변수

  • indexint필수

    Seat index (0 = host seat).

  • occupantUserIdString?기본값 = null

    Occupant identity; null = empty.

  • isLockedbool기본값 = false

    Whether the seat is admin-locked.

  • isMutedbool기본값 = false

    Whether the occupant's mic is muted.

  • reservedForString?기본값 = null

    Identity this seat is reserved for.

  • attributesMap<String,String>기본값 = const {}

    Occupant cosmetic attributes (avatar, frame, etc.).

SpeakerRequestclass
const SpeakerRequest({required int id, required String identity, String? createdAt})

A pending request to speak: id, requester identity and createdAt timestamp.

매개변수

  • idint필수

    Request id.

  • identityString필수

    Requesting identity.

  • createdAtString?기본값 = null

    Creation timestamp.

RoomSeatStateclass
const 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.

매개변수

  • countint필수

    Seat count.

  • modeString필수

    Seat mode ('free'/'request').

  • modeIdString?기본값 = null

    Room mode id.

  • seatsList<SeatState>필수

    Per-seat states.

  • requestsList<SpeakerRequest>필수

    Pending speaker requests.

UTDRoomModeclass
const 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.

매개변수

  • idString필수

    Unique mode id (e.g. '3').

  • seatCountint필수

    Number of seats.

  • rowsList<List<int>>필수

    Seat-index layout per row.

  • seatSizedouble?기본값 = null

    Explicit seat size override.

  • containerBuilderUTDSeatContainerBuilder?기본값 = null

    Custom seat-grid container builder.

  • backgroundBuilderUTDBackgroundBuilder?기본값 = null

    Mode-specific background builder.

computeSeatSizemethod
double 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.

매개변수

  • screenWidthdouble필수

    Available screen width.

반환값: double

UTDRoomMode.defaultModefield
static const UTDRoomMode defaultMode

Built-in default mode: id '3', 9 seats in a 1-4-4 layout.

반환값: UTDRoomMode

UTDChatMessageclass
UTDChatMessage({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.

매개변수

  • senderUserIdString필수

    Sender identity.

  • senderNameString필수

    Sender display name.

  • textString필수

    Message body.

  • timestampDateTime필수

    Message time.

  • userDataMap<String,dynamic>기본값 = const {}

    Extra payload (e.g. system-line markers).

  • messageIDString?기본값 = null

    Message id; auto-generated when omitted.

UTDConnectionStateenum
enum UTDConnectionState { disconnected, connecting, connected, reconnecting, error }

Room connection state: disconnected, connecting, connected, reconnecting, error.

반환값: UTDConnectionState

UTD와 함께 빌드할 준비가 되셨나요?

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

무료 계정 만들기