UTD Calls Kit

The calls kit entry widget. Takes a UTDCallsConfig, owns a UTDCallController (or adopts one passed in), wires the UTDCallsScope, and renders the right default screen for the current call phase. On mount it builds the controller and (unless autoInit is false) calls UTDCallController.init to mint the bearer and connect the signal WebSocket, then invokes onControllerReady so the host can call startCall / acceptIncoming / wire onIncomingCall / onCallEnded. Routes UTDCallPhase.outgoing|connecting to UTDOutgoingCallScreen, incoming to UTDIncomingCallScreen, active|reconnecting to UTDInCallScreen, and idle|ended to idleBuilder (or an empty SizedBox).

Immutable configuration (credentials, hosts, identity, theme, strings).

An externally-owned controller to adopt. When null, UTDCallView creates and owns one (and disposes it on unmount).

Called once the controller is built (and init() started when autoInit).

Whether to call UTDCallController.init automatically on mount.

What to render when there is no call in progress (idle / ended). Defaults to an empty SizedBox so the host controls navigation.

Creates the private state object backing UTDCallView; not for direct use.

Rückgabewert: State<UTDCallView> — The internal state that builds the controller and renders the phase screen.

Default outgoing-call screen: the peer avatar/name, a 'Ringing…' status (or 'Connecting…' before the room is live), and a cancel button that calls controller.end. Reads theme/strings/controller from the surrounding UTDCallsScope. Shown while UTDCallState.phase is UTDCallPhase.outgoing or connecting.

The current immutable call snapshot driving the displayed peer label and ringing/connecting status.

Builds the outgoing-call UI: avatar, peer name, ringing/connecting status text, and a cancel control wired to controller.end.

Rückgabewert: Widget — The rendered outgoing-call screen.

Default incoming-call screen: the caller avatar/name, a call-type subtitle (incoming video vs voice based on UTDCallState.type), and accept/decline actions wired to controller.acceptIncoming and controller.reject. Reads theme/strings/controller from the surrounding UTDCallsScope. Shown while UTDCallState.phase is UTDCallPhase.incoming.

The current immutable call snapshot driving the caller label and call-type subtitle.

Builds the incoming-call UI: avatar, caller name, voice/video subtitle, and decline/accept controls wired to controller.reject and controller.acceptIncoming.

Rückgabewert: Widget — The rendered incoming-call screen.

Default in-call screen. For a voice call it shows the peer avatar/name, a live timer, a reconnecting banner and a mute/camera/speaker/minimize/end control bar. For a video call it renders the remote video full-screen with a draggable local self-view PiP tile. A proximity overlay blanks the screen while a voice call is held to the ear (earpiece route). Reads theme/strings/controller from the surrounding UTDCallsScope. Shown while UTDCallState.phase is UTDCallPhase.active or reconnecting.

The current immutable call snapshot driving the timer, audio/video stage and reconnecting banner.

Creates the private stateful object that drives the per-second timer ticker and tracks the draggable PiP offset; not for direct use.

Rückgabewert: State<UTDInCallScreen> — The internal state managing the live-duration ticker and self-view PiP position.

The high-level phase of a 1:1 call, driving which default screen UTDCallView shows. Values: idle (no call), outgoing (we created it and are ringing the callee), incoming (callee side before accept/decline), connecting (joining the media room post-accept), active (both parties in the room), reconnecting (transport dropped and auto-reconnecting), ended (terminal state). UTDCallView routes outgoing/connecting to the outgoing screen, incoming to the incoming screen, active/reconnecting to the in-call screen, and idle/ended to idleBuilder.

The single source of truth for a 1:1 call. A ChangeNotifier that owns the transport (UTDCallsClient) and the active UTDCallSession, drives the call lifecycle, and exposes one reactive state for the default UI plus a few ValueNotifier surfaces for fine-grained binding. A static activeController guard prevents two concurrent calls from fighting over the audio device.

The kit configuration passed to the constructor (final UTDCallsConfig).

Static getter returning the controller that currently owns an active/ringing call, or null when none is active.

Rückgabewert: UTDCallController? — The currently active controller, or null.

Static getter for whether any call is currently in progress (true when the active controller's state.isInCall is true).

Rückgabewert: bool — True if a call is in progress.

Thin mic/camera/speaker passthrough sub-controller, rebound to each call's room (final UTDCallMediaController).

Speaker/earpiece/bluetooth output routing sub-controller, rebound to each call's room (final UTDAudioRouteController).

Proximity-based screen blanking sub-controller for an earpiece voice call (final UTDProximityController).

In-app minimize (floating overlay) orchestration sub-controller; drives enableMinimize (late final UTDCallMinimizeController, created with this controller).

Android OS-level Picture-in-Picture orchestration sub-controller (no-op off Android; late final UTDCallPipController, created with this controller).

The current call snapshot as a reactive ValueNotifier; also mirrored to listeners via notifyListeners (final ValueNotifier<UTDCallState>).

Incoming calls not yet answered (callee side) as a reactive ValueNotifier; drives an incoming-call UI even before the host routes to the call screen (final ValueNotifier<UTDCallInvitation?>).

The current call snapshot, a convenience getter over callState.value.

Rückgabewert: UTDCallState — The current call state snapshot.

Callback invoked when an incoming call arrives (callee side) while no call is active. The host typically navigates to the incoming-call screen here.

Callback invoked once when the call reaches a terminal state. The host typically pops the call screen here.

Initialize the transport: mint the bearer and connect the signal WS, then start listening for incoming calls and call updates. Configures minimize and starts the CallKit bridge when enabled, and resumes a cold-started accepted call when push + CallKit are enabled. Call once at startup; no-op after dispose.

Rückgabewert: Future<void> — Completes once transport is initialized and listeners are attached.

Caller: start a call to calleeId. Claims the active-controller guard, joins the media room and rings the callee; moves state to UTDCallPhase.outgoing, then active when the callee accepts/joins. No-op if a call is already in progress; rethrows UTDStreamException after terminating on failure.

Rückgabewert: Future<void> — Completes once the call has been created server-side and the room joined.

Callee: accept the pending incoming call. Claims the active-controller guard, clears the pending invitation, joins the media room and moves to UTDCallPhase.connecting then active. No-op when there is no pending invitation; rethrows UTDStreamException after terminating on failure.

Rückgabewert: Future<void> — Completes once the call is accepted and the room joined.

Callee: reject the pending incoming call (no media room is joined). Dismisses the native UI, sends the reject signal best-effort, and resets to idle. No-op when there is no pending invitation.

Rückgabewert: Future<void> — Completes once the reject signal is sent and local state is reset.

Hang up the current call (or cancel an outgoing one). Ends it server-side, tears down the media room, and terminates with cancelled (outgoing not yet joined) or localHangup otherwise.

Rückgabewert: Future<void> — Completes once the call is ended server-side and the session is torn down.

Toggle the local microphone (delegates to media.toggleMicrophone).

Rückgabewert: Future<void> — Completes once the mic state is toggled.

Toggle the local camera (delegates to media.toggleCamera). Enabling on a voice call performs a live audio→video upgrade in the same room (no reconnect).

Rückgabewert: Future<void> — Completes once the camera state is toggled.

Switch between the front and back camera, video calls only (delegates to media.flipCamera).

Rückgabewert: Future<void> — Completes once the camera is flipped.

Toggle the loudspeaker (delegates to media.toggleSpeaker).

Rückgabewert: Future<void> — Completes once the speaker state is toggled.

Cycle the audio output route earpiece → speaker → bluetooth → earpiece (delegates to audioRoute.cycle).

Rückgabewert: Future<void> — Completes once the route is cycled.

Route audio to the given route — earpiece, speaker, or bluetooth (delegates to audioRoute.setRoute).

Rückgabewert: Future<void> — Completes once the route is applied.

Unregister this device's push token (e.g. on sign-out). Best-effort; delegates to the transport client.

Rückgabewert: Future<void> — Completes once the unregister request is sent.

Tear down the controller: cancel all subscriptions, end and dispose any active session and the CallKit bridge, dispose the media/audioRoute/proximity/pip sub-controllers and transport client, and dispose the reactive notifiers. Idempotent; overrides ChangeNotifier.dispose.

Thin mic/camera/speaker passthrough to the active call's UTDRoom. The room is rebindable: each new call gets a fresh UTDRoom and the controller is re-pointed via bind(). State is mirrored from the room's own ValueNotifiers, which flip only when the SFU confirms (never optimistically).

Whether the local mic is currently publishing (mirrors the room). Starts false.

Whether the local camera is currently publishing (mirrors the room). Starts false.

Whether audio is routed to the loudspeaker (mirrors the room). Starts false.

The bound room, or null before the first bind(). Exposed so the UI can render local/remote video tracks via the LiveKit room.

Point the controller at the call's room and start mirroring its mic/camera/speaker state. Replaces any previous binding.

Stop mirroring the current room (e.g. on call end) without disposing it — the session owns the room's lifecycle.

Toggle the local microphone (calls setMicrophoneEnabled with the inverse of isMicEnabled).

Rückgabewert: Future<void> — Completes once the mic request is sent to the room.

Set the local microphone to enabled. Gated by the room on the publish grant; isMicEnabled flips only after the SFU confirms. No-op when no room is bound.

Rückgabewert: Future<void> — Completes once the request reaches the room.

Toggle the local camera. Enabling on an audio call performs a live audio→video upgrade in the same room (no reconnect).

Rückgabewert: Future<void> — Completes once the camera request is sent.

Set the local camera to enabled. Gated by the room on the publish grant; isCameraEnabled flips only after the SFU confirms. No-op when no room is bound.

Rückgabewert: Future<void> — Completes once the request reaches the room.

Switch between the front and back camera. No-op when the camera is off.

Rückgabewert: Future<void> — Completes once the camera is switched.

Toggle the loudspeaker (calls setSpeakerOn with the inverse of isSpeakerOn).

Rückgabewert: Future<void> — Completes once the speaker request is sent.

Route audio to the loudspeaker (on) or back to the earpiece/Bluetooth. No-op when no room is bound.

Rückgabewert: Future<void> — Completes once the request reaches the room.

Apply the Android Bluetooth-routing fix; call after connect + mic publish.

Rückgabewert: Future<void> — Completes once the routing fix is applied.

Unbind and dispose the mic/camera/speaker notifiers. Idempotent.

The audio output destination for a call. Values: earpiece (the phone's in-ear receiver, the default for a voice call held to the ear), speaker (the loudspeaker), bluetooth (a connected Bluetooth headset).

Drives a call's audio output routing on top of UTDRoom's low-level setSpeakerOn / setSpeakerPreferBluetooth / applyBluetoothAudioRouting. The room is rebindable per call via bind(). The route notifier reflects the last requested destination; the room's speaker flag is mirrored back so route and room stay consistent.

The currently selected output route. Defaults to UTDAudioRoute.earpiece — the right default for a 1:1 voice call. A platform-confirmed speaker flip from the room reconciles this (speaker-on ⇒ speaker, speaker-off ⇒ earpiece), while a bluetooth selection is preserved.

Point the controller at the call's room and start mirroring its speaker state. Replaces any previous binding and resets the route to the earpiece.

Stop mirroring the current room without disposing it (the session owns the room lifecycle).

Route audio to target. earpiece/speaker toggle the loudspeaker; bluetooth prefers a connected headset and applies the Android communication-mode fix. Updates route immediately, then applies to the room. No-op when no room is bound.

Rückgabewert: Future<void> — Completes once the route change is applied to the room.

Cycle earpiece → speaker → bluetooth → earpiece. A convenience for a single tri-state control button.

Rückgabewert: Future<void> — Completes once the next route is applied.

Apply the preferred Bluetooth routing after connect + publish. Safe to re-call on device changes / reconnect. Leaves route unchanged unless a headset is the active destination.

Rückgabewert: Future<void> — Completes once the routing is applied.

Unbind and dispose the route notifier. Idempotent.

Toggles the phone's proximity-based screen blanking for the duration of a voice call. Active only while it is a voice call AND audio is on the earpiece; suppressed when the loudspeaker comes on or on any video call. All platform calls are best-effort — a device with no proximity sensor simply never reports near.

Whether the proximity sensor currently reports the device is near (held to the ear). The UI binds to this to paint a black, input-absorbing overlay. Starts false.

Recompute whether proximity blanking should run for the current call. Blanking runs only when it is a voice call held to the earpiece (isVoiceCall && !speakerOn), starting or stopping the sensor accordingly.

Stop the sensor and dispose the isNear notifier. Idempotent.

The minimize state of a call. Values: idle (no active overlay), inCall (call shown full-screen), minimizing (call shrunk to the floating overlay).

Process-wide singleton tracking whether the current call is on its full screen, minimized to the floating overlay, or idle. Access via the static UTDCallMiniOverlayMachine.instance (private constructor). Exposes stateNotifier, state, isMinimizing/isInCall/isIdle getters, and changeState(UTDCallMiniOverlayState).

In-app minimize orchestration for a call: captures the current named route, pops the call screen into a floating overlay, and restores it later. Backed by the UTDCallMiniOverlayMachine singleton.

Whether a call is currently minimized to the overlay (proxies the overlay machine).

The minimize-state notifier from the underlying overlay machine; bind UI to react to idle/inCall/minimizing transitions.

The minimize configuration set via configure(), or null if not yet configured.

The captured navigation snapshot (controller + route name + arguments), or null when no minimize is active.

Set the overlay/PiP configuration used when minimizing.

Snapshot the current Navigator and modal route (name + arguments) so the call screen can later be restored.

Capture navigation, switch the machine to minimizing, and pop the call screen into the overlay. Returns false if already minimizing or not currently in a call.

Rückgabewert: bool — True if the minimize started; false if it was a no-op.

Bring the minimized call back full-screen by pushing the captured named route via Navigator.of(context). Returns false if not minimizing, no data, or no captured route name.

Rückgabewert: bool — True if a restore was scheduled; false otherwise.

Restore the call screen using the NavigatorState captured at minimize time (no BuildContext needed, e.g. from the floating overlay). Returns false if not minimizing, no data, no captured navigator, or no route name.

Rückgabewert: bool — True if a restore was scheduled; false otherwise.

End the call, reset the machine to idle, invoke the config's onClose callback, and clear the captured navigation/data.

Rückgabewert: Future<void> — Completes once the call has ended and state is reset.

Dismiss the overlay without ending the call or invoking onClose. Used internally when the controller tears a call down on its own.

Configuration for minimizing a call to a floating in-app overlay and, optionally, an Android OS-level Picture-in-Picture window.

Builds a fully custom minimize overlay, overriding the kit's default. The host wires onRestore (bring the call screen back) and onClose (hang up).

Drives Android OS-level Picture-in-Picture for a call, alongside the in-app minimize overlay. On Android 12+ (API 31+) it delegates to the floating plugin's OnLeavePiP so the OS auto-enters a system PiP window when the app is backgrounded while on the call screen. Android-only: every method is a no-op on other platforms.

True while the app is actually shrunk into the system PiP window. Starts false.

Arms auto-enter-on-Home if PiP is enabled in config and supported by the device. Safe to call repeatedly. No-op on iOS, when disposed, when disabled in config, or when PiP is unavailable.

Rückgabewert: Future<void> — Completes once arming is attempted.

Reports the real OS PiP enter/exit transition. Driven by the host app's pip_state_channel handler forwarding MainActivity.onPictureInPictureModeChanged. Re-arms auto-enter on exit. No-op on iOS / Android < 31 / after dispose.

Cancels auto-enter so backgrounding no longer triggers PiP and resets isInPip. No-op on iOS.

Rückgabewert: Future<void> — Completes once auto-enter is cancelled.

Final teardown (call from UTDCallController.dispose). Cancels auto-enter and disposes isInPip; does NOT dispose the shared process-wide floating singleton. Idempotent.

Immutable configuration for the calls kit. Carries the no-backend mint credentials (appId + the publishable appKey), the local user identity, the engine hosts, and the default-UI theme/strings/flags. One set of credentials works for every enabled call type; the type is chosen per call, never per credential. Extends Equatable.

App ID for the UTD Stream Engine (e.g. "9325906999").

The project's publishable app key (the no-backend mint credential, sent as X-App-Key). The server secret never ships.

The local user's identity (the caller/callee identity on the engine).

The local user's display name.

The engine host for privileged in-call ops (Bearer). Grey-cloud origin.

The mint host for POST /api/v1/token + /api/v1/signal/token (X-App-Key).

Color tokens for the built-in default call UI.

User-facing strings for the built-in default call UI.

Whether the in-call screen may be minimized to a floating overlay (and, when minimizeConfig opts in, Android OS PiP). Default true.

Tuning for the minimize overlay / OS PiP. When null a sensible default (UTDCallMinimizeConfig) is used. Excluded from equality.

Whether incoming calls are shown on the OS-native call UI via UTDCallKitBridge. Default true.

Whether the kit registers device push tokens with the engine and wakes the app from background/killed on incoming calls. Default true.

Returns a copy of this config with the given fields replaced. Any omitted argument keeps the current value.

Rückgabewert: UTDCallsConfig — A new config with the requested overrides applied.

Equatable props used for value equality: appId, appKey, userId, userName, baseUrl, tokenBaseUrl, theme, strings, enableMinimize, enableCallKit, enablePush. Note minimizeConfig is intentionally excluded.

Configuration for minimizing a call to a floating in-app overlay (and, optionally, an Android OS-level Picture-in-Picture window). Mirrors the audio kit's UTDMinimizeConfig, trimmed for a 1:1 call (no room cover; the overlay shows the peer + remote video when present).

Called when the floating overlay's end button is tapped (after the call is torn down).

A fully custom overlay builder. When null the kit's default tile is used.

Enables Android OS-level Picture-in-Picture in addition to the in-app overlay (Android 12+/API 31+). Defaults to false (no behavior change).

Builds a fully custom minimize overlay, overriding the kit's default. The host wires onRestore (bring the call screen back) and onClose (hang up).

Rückgabewert: Widget — The custom overlay widget to render.

Immutable snapshot of the current call, exposed via UTDCallController.state. Every state transition produces a new instance; it is the single value the default UI binds to. Extends Equatable for value comparison.

The current high-level phase of the call.

Whether this is a voice or video call.

Why the call ended, on a terminal UTDCallPhase.ended state; otherwise null.

When the call became active (the duration timer's epoch); null until the call connects.

The best label for the peer: peerName when non-empty, else peerId, else null.

Rückgabewert: String? — Display name, falling back to identity, or null.

Whether a call is in any non-idle, non-ended phase.

Rückgabewert: bool — True when phase is neither idle nor ended.

Whether this is a video call (the call type carries video).

Rückgabewert: bool — True when type.hasVideo is true.

Elapsed call duration since connectedAt, or Duration.zero before connect.

Rückgabewert: Duration — Time elapsed since the call connected.

Returns a new UTDCallState with the given fields overridden and the rest copied from this instance.

Rückgabewert: UTDCallState — A new snapshot with the overrides applied.

The high-level phase of a 1:1 call, driving which default screen shows. Values: idle (no call in progress), outgoing (we created the call and are ringing the callee), incoming (callee side, before accept/decline), connecting (joining the media room post-accept, before the room is live), active (both parties are in the media room), reconnecting (the media transport dropped and is auto-reconnecting), ended (terminal state; UTDCallState.endReason says why).

Why a call ended, surfaced on a terminal UTDCallState. Values: localHangup (the local user hung up), remoteHangup (the remote party hung up / left), rejected (the callee declined), busy (the callee was on another call), missed (the callee never answered in the ring window), cancelled (the local user cancelled an outgoing call before it connected), failed (reconnection failed or a server force-exit ended the call).

The audio output destination for a call. Values: earpiece (the phone's in-ear receiver, the default for a voice call held to the ear), speaker (the loudspeaker), bluetooth (a connected Bluetooth headset).

The 1:1 call product types the signalling plane serves, mirroring the engine taxonomy. The call type passed to startCall (defaults to audioCall). Values: audioCall (wire 'audio_call' — 1:1 audio call), videoCall (wire 'video_call' — 1:1 audio + video call). Each value carries a `wire` string the engine expects, plus getters `isCall` (true for audioCall or videoCall) and `hasVideo` (true for videoCall).

The exact string the engine expects on the wire for this stream type, e.g. 'audio_call'.

Whether this stream type is a 1:1 call type (audioCall or videoCall).

Rückgabewert: bool — True for audioCall or videoCall.

Whether this stream type carries video (videoCall).

Rückgabewert: bool — True for videoCall.

An incoming 1:1 call delivered over the signalling WebSocket (`call.invitation`). The callee answers with UTDSignalClient.acceptCall (or rejects/marks busy).

Builds a UTDCallInvitation from a decoded WebSocket data map (keys: call_id, caller_identity, caller_name, type, metadata); maps type 'video' to videoCall, otherwise audioCall.

A non-invitation call signal pushed over the WebSocket after an invite. Values: ringing, accepted, rejected, busy, ended (mapping the `call.ringing` / `call.accepted` / `call.rejected` / `call.busy` / `call.ended` frame types).

A progress update on an in-flight call other than the initial invitation, carrying the signal kind, affected call id, and raw push payload.

Builds a UTDCallUpdate from a parsed signal kind and the raw frame data, extracting call_id from the data map.

Top-level helper that maps a `call.*` push frame type string to a UTDCallSignalKind, or null for `call.invitation` (handled separately) or unknown frame types.

Rückgabewert: UTDCallSignalKind? — The matching signal kind, or null if not a recognized call.* update frame.

A facade owning the calls-kit transport: a UTDApiClient + UTDApi (REST), a UTDSignalClient (presence + incoming-call WebSocket), and the per-call UTDCallSessions. On init it performs the no-backend mint (POST /api/v1/auth/session with X-App-Id/X-App-Key) to obtain a per-user user_token (applied as the engine bearer) and ws_url, which doubles as the signalling WS credential. Re-exposes the signal client's incomingCalls/callUpdates/forceExit streams and drives the optional push dispatcher.

The kit configuration passed to the constructor (credentials, hosts, identity, flags).

Rückgabewert: UTDCallsConfig

The REST facade used for mints and call actions (createCall/acceptCall/endCall, push token register, etc.).

Rückgabewert: UTDApi

The realtime signalling client (presence + incoming-call WebSocket).

Rückgabewert: UTDSignalClient

Stream of incoming 1:1 calls (the callee side), forwarded from the signal client.

Rückgabewert: Stream<UTDCallInvitation>

Stream of progress on in-flight calls (ringing/accepted/rejected/busy/ended), forwarded from the signal client.

Rückgabewert: Stream<UTDCallUpdate>

Stream of server force-close events (single-active-session takeover, WS close code 4003).

Rückgabewert: Stream<UTDForceExitReason>

The signalling connection state as a ValueListenable.

Rückgabewert: ValueListenable<UTDConnectionState>

Whether init() has completed and the bearer is applied.

Rückgabewert: bool

Mint the bearer (no-backend) and connect the signalling WebSocket; if config.enablePush is true it also starts push-token collection/registration. Idempotent: a second call is a no-op once initialized (or after dispose). Throws UTDStreamException if the mint or signal connect fails. The mint runs inside the signal client's credentials provider, so connecting both opens the socket and applies the freshly-minted bearer.

Rückgabewert: Future<void>

Create a new UTDCallSession for the given call type, wired to the internal REST API. The caller drives it via start()/accept()/end(); the controller wires it to the UI.

Rückgabewert: UTDCallSession

Unregister this device's push token with the engine (e.g. on sign-out). Best-effort: a UTDStreamException is swallowed so sign-out proceeds regardless.

Rückgabewert: Future<void>

Dispose the transport (push dispatcher, signal client, and API client). Idempotent; the object must not be used afterwards.

Rückgabewert: Future<void>

A 1:1 call session (audioCall or videoCall) backed by a headless LiveKit room capped at 2 participants by the engine. Both parties publish. The caller start()s a call; the callee accept()s an incoming one (the call_id arrives out-of-band via push or the engine presence socket). Extends UTDSession. Asserts the given type is a call type.

The current call status as a ValueNotifier, or null before start()/accept(). Changes are forwarded to the registered handler's onCallStateChanged.

Rückgabewert: ValueNotifier<UTDCallStatus?>

The current call id as a ValueNotifier, or null before start()/accept().

Rückgabewert: ValueNotifier<String?>

Caller side: create the call, ring the callee, set callId/status, and (if the engine returned join credentials) connect to the media room and publish. Returns the engine UTDCall.

Rückgabewert: Future<UTDCall> — The created engine call.

Callee side: accept an incoming call by id, set callId/status to the engine's actual returned status (which may resolve to ended/busy if the caller bailed first), and if connectable join the media room and publish. Returns the engine UTDCall.

Rückgabewert: Future<UTDCall> — The accepted engine call.

Notify the engine that the callee device is ringing for the given call id; updates status from the response.

Rückgabewert: Future<void>

Reject the incoming call with the given id; updates status from the response.

Rückgabewert: Future<void>

Mark the given call id as busy (callee on another call); updates status from the response.

Rückgabewert: Future<void>

Hang up the active call: end it server-side (swallowing UTDStreamException when the call already reached a terminal state, in which case status is set to ended locally) and disconnect the media room. Local teardown proceeds even if the server call fails with a UTDStreamException.

Rückgabewert: Future<void>

Abstract shared base for every session type. Owns a UTDRoom and re-exposes its headless state two ways: per-field ValueListenables plus a raw event stream (reactive), and a single assignable UTDStreamEventHandler (imperative). Concrete sessions (e.g. UTDCallSession) add the per-type control surface and feed the handler with typed events. Constructor is for subclasses.

The product type this session serves.

Rückgabewert: UTDStreamType

The headless LiveKit room wrapper backing this session.

Rückgabewert: UTDRoom

Register a single UTDStreamEventHandler for everything this session emits, replacing any previous handler. The reactive listenables and raw events stream remain available alongside it.

Remove the registered event handler, if any.

The connection lifecycle state (mirrors the underlying room).

Rückgabewert: ValueListenable<UTDConnectionState>

Whether the room is connected (boolean mirror of connectionState).

Rückgabewert: ValueListenable<bool>

The current remote participants in the room.

Rückgabewert: ValueListenable<List<RemoteParticipant>>

The local participant, or null before connecting.

Rückgabewert: LocalParticipant?

The raw LiveKit RoomEvent firehose.

Rückgabewert: Stream<RoomEvent>

Fires once when the session is forcibly ended (ban / takeover / kick / reconnect timeout).

Rückgabewert: Stream<UTDForceExitReason>

Toggle the local mic publish (works once the server has granted publish).

Rückgabewert: Future<void>

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

Rückgabewert: Future<void>

Switch between the front and back camera.

Rückgabewert: Future<void>

Leave the media room but keep the session object reusable (disconnects without disposing).

Rückgabewert: Future<void>

Tear down the session and its LiveKit room: detaches listeners, cancels subscriptions, and disposes the room. Must be called via super by subclasses.

Rückgabewert: Future<void>

A single, assignable place to register for everything a session emits — the imperative counterpart to the per-field ValueListenables, modelled on assignable callbacks but per-session (no global statics, so concurrent sessions stay independent). Assign the fields you care about and hand it to session.setEventHandler; every field is optional. Trimmed for the calls kit to only the call-relevant callbacks.

Owns the push transport for the calls kit: collects device push tokens (iOS PushKit VoIP via FlutterCallkitIncoming.getDevicePushTokenVoIP and/or the FCM token via FirebaseMessaging), reports them through onTokens for engine registration, and routes foreground {type:'call'} FCM messages into CallKit. iOS VoIP pushes are delivered to CallKit natively, so this dispatcher focuses on token collection on both platforms and the Android FCM data-message to CallKit path. The host must call Firebase.initializeApp() before start().

Starts the dispatcher: registers the FCM background handler, requests iOS notification permission, collects the initial tokens, wires foreground call messages, and subscribes to FCM and iOS VoIP token refreshes. Idempotent (no-op if already started or disposed). The host MUST have called Firebase.initializeApp() beforehand.

Rückgabewert: Future<void> — Completes once the dispatcher is wired and the initial tokens have been collected and reported.

Static. Reads the kit call_id of the CallKit call the app was cold-launched into, if any (e.g. the user accepted a VoIP/FCM call from a killed state). Prefers an already-accepted call, falling back to the most recent active call. Returns null when there is no pending native call or no usable call_id. The controller uses this on init to resume the accepted call.

Rückgabewert: Future<UTDCallPush?> — The parsed push for the cold-started accepted call, or null when none exists.

Cancels the foreground-message, FCM token-refresh, and VoIP token-refresh subscriptions and marks the dispatcher disposed. Idempotent.

Rückgabewert: Future<void> — Completes once all subscriptions are cancelled.

App name shown on the CallKit screen for FCM-driven incoming calls.

Callback invoked with the latest push tokens (fcmToken / voipToken, either nullable) and the current UTDPushPlatform whenever tokens are collected or refreshed.

Immutable data payload the engine sends for a background call push, normalised away from the raw FCM map. Mirrors the engine contract {type:'call', call_id, caller_identity, caller_name, call_type:'voice'|'video'}.

Static. Parses the engine's FCM data map into a UTDCallPush. Returns null when the map is not a type:'call' push or lacks a usable call_id. Maps call_type=='video' to UTDStreamType.videoCall, otherwise UTDStreamType.audioCall.

Rückgabewert: UTDCallPush? — The parsed push, or null when the map is not a usable call push.

The kit call_id to accept/join.

The caller's engine identity.

The caller's display name, when the engine provided one; otherwise null.

Whether the call is audio or video (UTDStreamType.audioCall or UTDStreamType.videoCall).

Top-level function. Presents the OS-native incoming-call UI (CallKit/ConnectionService) for a background/killed-state call push. Used by both the FCM background isolate and the foreground handler, so it must not touch the controller or app state — it only renders CallKit. The call_id (and call type) is stored in CallKitParams.extra so the accept event can resolve it back. A fresh UUID is generated for the CallKit call id.

Rückgabewert: Future<void> — Completes once the native incoming-call UI has been shown.

Top-level Android FCM background message handler, annotated @pragma('vm:entry-point') so it is a valid entry point for the background FlutterEngine. On a {type:'call'} data message it parses the payload and shows the full-screen CallKit incoming UI; non-call messages are ignored. The user's accept later reaches the app (waking it from killed) and is handled by UTDPushDispatcher in the main isolate.

Rückgabewert: Future<void> — Completes after the native UI is shown, or immediately when the message is not a call push.

Wraps FlutterCallkitIncoming to present the OS-native incoming-call UI (CallKit on iOS, ConnectionService on Android) for an in-app UTDCallInvitation and to bridge the user's choice back to the controller. Owns the call_id↔UUID mapping (a UUID is generated the first time a call_id is shown and reused thereafter) and translates the plugin's sealed CallEvent stream into a normalised events stream of UTDCallKitEvent. Background/killed pushes shown by UTDPushDispatcher carry the call_id in CallKitParams.extra and are resolved from there.

Broadcast stream of normalised native-UI actions (accept / decline / ended / timeout), each carrying the kit call_id. The controller listens here to drive the call.

Rückgabewert: Stream<UTDCallKitEvent> — The normalised native call-UI event stream.

Begins bridging FlutterCallkitIncoming.onEvent into the events stream. Idempotent (no-op if already started or disposed).

Shows the native incoming-call UI for the given invitation. A UUID is generated for the invitation's call_id (or reused if already shown) so accept/decline events map back to the same call. The call_id is also stored in CallKitParams.extra.

Rückgabewert: Future<void> — Completes once the native incoming-call UI has been shown.

Marks the call connected on the native UI (starts its in-call timer). Call when the media room connects or the remote joins. No-op when the call_id has no registered UUID.

Rückgabewert: Future<void> — Completes once the native UI has been updated.

Dismisses the native UI for one call (after a local/remote hang-up) and removes its call_id↔UUID mapping. No-op when the call_id is unknown.

Rückgabewert: Future<void> — Completes once the native call UI has been dismissed.

Dismisses every native call UI and clears all call_id↔UUID mappings (teardown / takeover).

Rückgabewert: Future<void> — Completes once all native call UIs have been dismissed.

Cancels the plugin subscription, closes the events stream, and clears the call_id↔UUID mappings. The bridge must not be used afterwards. Idempotent.

Rückgabewert: Future<void> — Completes once the bridge has been torn down.

Immutable native call-UI action paired with the kit call_id it refers to. Emitted on UTDCallKitBridge.events.

What happened on the native UI (a UTDCallKitAction value).

The kit call_id the action refers to, or empty when it could not be mapped back to a known call.

What the user (or system) did on the native call UI, normalised away from the plugin's sealed CallEvent hierarchy. Values: accept (tapped Accept), decline (tapped Decline), ended (call ended/hung up from native UI), timeout (ring window elapsed with no answer / missed).