@poolse/react-native-calls 0.4.5 → 0.5.0

package/README.md

@@ -17,6 +17,11 @@ await calls.configure('https://api.poolse.dev', { smallIcon: 'ic_call', ringback
 const stop = calls.onCallState((s) => render(s));   // s: Snapshot | null
 await calls.place(conversationId, { media: 'audio', sessionToken });
 calls.answer(); calls.decline(); calls.hangUp();
+
+// Audio output: s.audioOutputs lists the phone, the speaker and every
+// connected headset/Bluetooth device by name; s.audioOutputId is the live one.
+calls.setAudioOutput(s.audioOutputs[0].id);
+calls.setSpeaker(true); // the one-tap toggle, still there
 ```
 
 ## Layout

package/android/src/main/java/dev/poolse/callcore/CallCoreRuntime.kt

@@ -194,6 +194,7 @@ class CallCoreRuntime(
   fun setCamera(on: Boolean) = post { media.setCamera(on) }
   fun switchCamera() = post { media.switchCamera() }
   fun setSpeaker(on: Boolean) = post { media.setSpeaker(on) }
+  fun setAudioOutput(id: String) = post { media.setAudioOutput(id) }
 
   /** Re-emit the current state (the bridge's roster/route changed). */
   fun reemit() = post { if (state.phase != Phase.IDLE) sink.emit(state) }

package/android/src/main/java/dev/poolse/callcore/Ports.kt

@@ -67,6 +67,13 @@ interface MediaPort {
    * route — earpiece, or a connected headset/Bluetooth device (`false`).
    */
   fun setSpeaker(on: Boolean)
+
+  /**
+   * Play through one specific output — an id from the snapshot's
+   * `audioOutputs`. Engines without device selection fall back to the
+   * speaker toggle.
+   */
+  fun setAudioOutput(id: String) = setSpeaker(id == "speaker")
 }
 
 /** The ring UX: CallStyle notification + full-screen activity + tones. */

package/android/src/main/java/dev/poolse/callcore/android/CallCore.kt

@@ -69,6 +69,8 @@ class CallCore private constructor(context: Context) {
   private var cameraOn = false
   private var cameraFacing: String? = null
   private var audioRoute: String? = null
+  private var audioOutputs: List<AudioOutput> = emptyList()
+  private var audioOutputId: String? = null
 
   /** Last snapshot emitted; read by the bridge's getCallState from any thread. */
   @Volatile private var lastSnapshot: Map<String, Any?>? = null
@@ -170,6 +172,12 @@ class CallCore private constructor(context: Context) {
     runtime.reemit()
   }
 
+  /**
+   * Play through one output from the snapshot's `audioOutputs`. Not
+   * optimistic: the adapter reports the route once the OS has moved it.
+   */
+  fun setAudioOutput(id: String) = runtime.setAudioOutput(id)
+
   fun allRingsResolved(outcome: String) = runtime.allRingsResolved(outcome)
 
   fun state(): MachineState = runtime.currentState()
@@ -216,6 +224,8 @@ class CallCore private constructor(context: Context) {
         )
       },
       audioRoute = audioRoute ?: if (state.media == "video") "speaker" else "earpiece",
+      audioOutputs = audioOutputs.map { mapOf("id" to it.id, "kind" to it.kind, "name" to it.name) },
+      audioOutputId = audioOutputId,
       mutedSelf = mutedSelf,
       cameraOn = cameraOn,
       cameraFacing = cameraFacing,
@@ -235,6 +245,8 @@ class CallCore private constructor(context: Context) {
     cameraOn = false
     cameraFacing = null
     audioRoute = null
+    audioOutputs = emptyList()
+    audioOutputId = null
   }
 
   /**
@@ -300,6 +312,10 @@ class CallCore private constructor(context: Context) {
       runtime.post { cameraOn = on; cameraFacing = facing }
       runtime.reemit()
     }
+    override fun onAudioOutputs(outputs: List<AudioOutput>, selectedId: String?) {
+      runtime.post { audioOutputs = outputs; audioOutputId = selectedId }
+      runtime.reemit()
+    }
   }
 
   private fun bringAppToFront(callId: String, from: Context?): Boolean {
@@ -466,8 +482,20 @@ interface MediaEvents {
   fun onAudioRoute(route: String)
   /** The local camera track is (not) published + enabled; [facing] `front` | `back`. */
   fun onLocalCamera(on: Boolean, facing: String?) {}
+  /** Every output call audio can play through right now, and the one it does. */
+  fun onAudioOutputs(outputs: List<AudioOutput>, selectedId: String?) {}
 }
 
+/** One place call audio can play — a snapshot `audioOutputs[]` entry. */
+data class AudioOutput(
+  /** Passed back to `setAudioOutput`; stable while the device stays connected. */
+  val id: String,
+  /** `earpiece` | `speaker` | `bluetooth` | `headset`. */
+  val kind: String,
+  /** What the device calls itself ("Galaxy Buds2"), or a plain default for built-ins. */
+  val name: String,
+)
+
 data class MediaParticipant(
   /** The SFU identity — the poolse user id. */
   val identity: String,

package/android/src/main/java/dev/poolse/callcore/android/SnapshotJson.kt

@@ -18,6 +18,8 @@ internal fun MachineState.toSnapshot(
   conversationName: String? = null,
   participants: List<Map<String, Any>> = emptyList(),
   audioRoute: String = "earpiece",
+  audioOutputs: List<Map<String, Any>> = emptyList(),
+  audioOutputId: String? = null,
   mutedSelf: Boolean = false,
   cameraOn: Boolean = false,
   cameraFacing: String? = null,
@@ -25,6 +27,8 @@ internal fun MachineState.toSnapshot(
   if (phase == Phase.IDLE) return null
   return buildMap {
     putAll(snapshotCore(conversationName, participants, audioRoute, mutedSelf, cameraOn))
+    put("audioOutputs", audioOutputs)
+    put("audioOutputId", audioOutputId)
     // Optional in the contract: present only while a camera is published.
     if (cameraFacing != null) put("cameraFacing", cameraFacing)
   }

package/android/src/main/java/expo/modules/poolsecalls/PoolseCallsModule.kt

@@ -85,6 +85,7 @@ class PoolseCallsModule : Module() {
     Function("setCamera") { on: Boolean -> core()?.setCamera(on) }
     Function("switchCamera") { core()?.switchCamera() }
     Function("setSpeaker") { on: Boolean -> core()?.setSpeaker(on) }
+    Function("setAudioOutput") { id: String -> core()?.setAudioOutput(id) }
 
     // Socket forwarding (open app): idempotent with the FCM path.
     Function("onRingEnded") { callId: String, reason: String -> core()?.onRingEnded(callId, reason) }

package/android/src/main/livekit/java/dev/poolse/callcore/livekit/LiveKitMediaPort.kt

@@ -8,6 +8,7 @@ import androidx.core.content.ContextCompat
 import com.twilio.audioswitch.AudioDevice
 import dev.poolse.callcore.CallSessionBundle
 import dev.poolse.callcore.MediaPort
+import dev.poolse.callcore.android.AudioOutput
 import dev.poolse.callcore.android.CallVideoSource
 import dev.poolse.callcore.android.CallVideoSurface
 import dev.poolse.callcore.android.MediaEvents
@@ -61,8 +62,15 @@ class LiveKitMediaPort(
   private var eventJob: Job? = null
   private var media: String = "audio"
 
-  /** Speaker forced by the user; null = the media-type default. */
-  private var speakerWanted: Boolean? = null
+  /**
+   * The user's output choice for the CURRENT call: an output id
+   * (`speaker`, `earpiece`, `wired`, `bluetooth`) or [PRIVATE] — the
+   * best private route. null = automatic (see [resolve]).
+   */
+  private var outputWanted: String? = null
+
+  /** The current room's last device list; a newcomer in it takes the call. */
+  private var knownDevices: List<AudioDevice>? = null
 
   /**
    * The user's mute / camera choices for the CURRENT call. They survive
@@ -149,7 +157,7 @@ class LiveKitMediaPort(
   private fun resetWanted() {
     mutedWanted = false
     cameraWanted = null
-    speakerWanted = null
+    outputWanted = null
   }
 
   /** Drop the current room only (a rejoin replaces it). */
@@ -256,7 +264,13 @@ class LiveKitMediaPort(
   }
 
   override fun setSpeaker(on: Boolean) {
-    speakerWanted = on
+    outputWanted = if (on) SPEAKER else PRIVATE
+    val handler = room?.audioHandler as? AudioSwitchHandler ?: return
+    applyRoute(handler)
+  }
+
+  override fun setAudioOutput(id: String) {
+    outputWanted = id
     val handler = room?.audioHandler as? AudioSwitchHandler ?: return
     applyRoute(handler)
   }
@@ -264,12 +278,13 @@ class LiveKitMediaPort(
   // ── audio routing ───────────────────────────────────────────────────
 
   /**
-   * A voice call is held to the ear: earpiece by default (a connected
-   * headset or Bluetooth device first); video defaults to the speaker.
-   * Set before connect — the handler starts during connect.
+   * Seed AudioSwitch's own order (it starts during connect, before any
+   * choice is applied): a connected headset or Bluetooth device first,
+   * then the earpiece for voice or the speaker for video.
    */
   private fun configureAudio(r: Room, video: Boolean) {
     val handler = r.audioHandler as? AudioSwitchHandler ?: return
+    knownDevices = null
     handler.preferredDeviceList = if (video) {
       listOf(
         AudioDevice.BluetoothHeadset::class.java,
@@ -285,31 +300,78 @@ class LiveKitMediaPort(
         AudioDevice.Speakerphone::class.java,
       )
     }
-    handler.audioDeviceChangeListener = { devices, selected ->
-      // A user's speaker choice survives device-list changes, except
-      // that plugging in a headset always wins (as the dialer does).
-      val wanted = speakerWanted
-      if (wanted != null && selected != null && room?.audioHandler === handler) {
-        val external = selected is AudioDevice.BluetoothHeadset || selected is AudioDevice.WiredHeadset
-        val isSpeaker = selected is AudioDevice.Speakerphone
-        if (!external && isSpeaker != wanted) devices.pick(wanted)?.let(handler::selectDevice)
-      }
-      events.onAudioRoute(routeOf(handler.selectedAudioDevice ?: selected))
+    handler.audioDeviceChangeListener = listener@{ devices, selected ->
+      if (room?.audioHandler !== handler) return@listener
+      // Putting on a headset or connecting Bluetooth mid-call moves the
+      // call to it, whatever was picked before — as the dialer does. The
+      // first list of a room is not "new": a choice made while
+      // connecting must survive it.
+      val known = knownDevices
+      if (known != null && devices.any { it.isExternal() && it !in known }) outputWanted = null
+      knownDevices = devices
+      val target = resolve(devices)
+      if (target != null && target != selected) handler.selectDevice(target)
+      report(handler, devices, handler.selectedAudioDevice ?: selected)
     }
   }
 
   private fun applyRoute(handler: AudioSwitchHandler) {
-    val want = speakerWanted ?: (media == "video")
-    handler.availableAudioDevices.pick(want)?.let(handler::selectDevice)
-    events.onAudioRoute(routeOf(handler.selectedAudioDevice))
+    val devices = handler.availableAudioDevices
+    resolve(devices)?.let { if (it != handler.selectedAudioDevice) handler.selectDevice(it) }
+    report(handler, devices, handler.selectedAudioDevice)
   }
 
-  /** Speaker, or the best private route: Bluetooth → wired → earpiece. */
-  private fun List<AudioDevice>.pick(speaker: Boolean): AudioDevice? =
-    if (speaker) firstOrNull { it is AudioDevice.Speakerphone }
-    else firstOrNull { it is AudioDevice.BluetoothHeadset }
-      ?: firstOrNull { it is AudioDevice.WiredHeadset }
-      ?: firstOrNull { it is AudioDevice.Earpiece }
+  /**
+   * Where the call should play. A chosen device while it is connected
+   * (it is forgotten once it goes); otherwise a connected headset or
+   * Bluetooth device, then the speaker for video or the earpiece for
+   * voice — never the speaker over earbuds the user put on.
+   */
+  private fun resolve(devices: List<AudioDevice>): AudioDevice? {
+    val wanted = outputWanted
+    if (wanted != null && wanted != PRIVATE) {
+      devices.firstOrNull { idOf(it) == wanted }?.let { return it }
+      outputWanted = null
+    }
+    val external = devices.firstOrNull { it is AudioDevice.BluetoothHeadset }
+      ?: devices.firstOrNull { it is AudioDevice.WiredHeadset }
+    val earpiece = devices.firstOrNull { it is AudioDevice.Earpiece }
+    val speaker = devices.firstOrNull { it is AudioDevice.Speakerphone }
+    return when {
+      external != null -> external
+      outputWanted == PRIVATE -> earpiece ?: speaker
+      media == "video" -> speaker ?: earpiece
+      else -> earpiece ?: speaker
+    }
+  }
+
+  private fun report(handler: AudioSwitchHandler, devices: List<AudioDevice>, selected: AudioDevice?) {
+    if (room?.audioHandler !== handler) return
+    events.onAudioRoute(routeOf(selected))
+    events.onAudioOutputs(
+      devices.map { AudioOutput(id = idOf(it), kind = routeOf(it), name = nameOf(it)) },
+      selected?.let(::idOf),
+    )
+  }
+
+  private fun AudioDevice.isExternal() =
+    this is AudioDevice.BluetoothHeadset || this is AudioDevice.WiredHeadset
+
+  private fun idOf(d: AudioDevice): String = when (d) {
+    is AudioDevice.Speakerphone -> SPEAKER
+    is AudioDevice.Earpiece -> "earpiece"
+    is AudioDevice.WiredHeadset -> "wired"
+    // AudioSwitch carries one Bluetooth device: the active headset.
+    is AudioDevice.BluetoothHeadset -> "bluetooth"
+  }
+
+  /** The Bluetooth device's own name; plain defaults for the rest. */
+  private fun nameOf(d: AudioDevice): String = when (d) {
+    is AudioDevice.Speakerphone -> "Speaker"
+    is AudioDevice.Earpiece -> "Phone"
+    is AudioDevice.WiredHeadset -> "Headphones"
+    is AudioDevice.BluetoothHeadset -> d.name.ifBlank { "Bluetooth" }
+  }
 
   private fun routeOf(d: AudioDevice?): String = when (d) {
     is AudioDevice.Speakerphone -> "speaker"
@@ -326,7 +388,7 @@ class LiveKitMediaPort(
       if (this.room !== room) return@collect
       when (event) {
         is RoomEvent.Connected -> {
-          (room.audioHandler as? AudioSwitchHandler)?.let { if (speakerWanted != null) applyRoute(it) }
+          (room.audioHandler as? AudioSwitchHandler)?.let(::applyRoute)
           events.onConnected()
           // Somebody may already be in (a late join, or a callee who
           // answered before our media came up): they will not "connect".
@@ -403,6 +465,8 @@ class LiveKitMediaPort(
   companion object {
     private const val TAG = "PoolseLiveKit"
     private const val SWITCH_SETTLE_MS = 600L
+    private const val SPEAKER = "speaker"
+    private const val PRIVATE = "private"
 
     /** Pass as `mediaFactory` in CallCoreConfig. */
     val factory: (Context, MediaEvents) -> MediaPort = { ctx, ev -> LiveKitMediaPort(ctx, ev) }

package/dist/index.cjs

@@ -31,6 +31,10 @@ var setMuted = (muted) => native?.setMuted(muted);
 var setCamera = (on) => native?.setCamera(on);
 var switchCamera = () => native?.switchCamera();
 var setSpeaker = (on) => native?.setSpeaker(on);
+function setAudioOutput(id) {
+  if (native?.setAudioOutput) native.setAudioOutput(id);
+  else native?.setSpeaker(id === "speaker");
+}
 var onRingEnded = (callId, reason) => native?.onRingEnded(callId, reason);
 var onCallFinished = (callId, reason) => native?.onCallFinished(callId, reason ?? null);
 var canUseFullScreenIntent = () => native?.canUseFullScreenIntent() ?? true;
@@ -81,6 +85,7 @@ exports.onRingEnded = onRingEnded;
 exports.onVoipToken = onVoipToken;
 exports.openFullScreenIntentSettings = openFullScreenIntentSettings;
 exports.place = place;
+exports.setAudioOutput = setAudioOutput;
 exports.setCamera = setCamera;
 exports.setMuted = setMuted;
 exports.setSpeaker = setSpeaker;

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"names":["requireOptionalNativeModule","requireNativeViewManager","createElement","View"],"mappings":"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","file":"index.cjs","sourcesContent":["// @poolse/react-native-calls — the React Native face of the native\n// call core (CONTRACT.md §8). A thin, typed surface over the native\n// module: commands in, one snapshot event out. All call logic lives in\n// the native cores; nothing here decides anything about a call.\n//\n// On a platform or build without the native module (Expo Go, web,\n// unlinked), every command is a safe no-op and the state stays idle —\n// so a host can render against this unconditionally.\nimport { createElement, type ComponentType, type ReactElement } from 'react';\nimport { View, type ViewProps } from 'react-native';\nimport { requireNativeViewManager, requireOptionalNativeModule } from 'expo-modules-core';\n\n/**\n * A call's complete state. `null` means idle — no call. After a call\n * ends the snapshot stays `phase: 'ended'` (with `reason`) for ~2.5 s,\n * then becomes `null`.\n */\nexport interface Snapshot {\n  cv: 1;\n  callId: string;\n  conversationId: string;\n  conversationName: string | null;\n  direction: 'incoming' | 'outgoing' | 'joined';\n  media: 'audio' | 'video';\n  phase: 'ringing_in' | 'ringing_out' | 'connecting' | 'active' | 'reconnecting' | 'ended';\n  reason?:\n    | 'left'\n    | 'finished'\n    | 'declined_all'\n    | 'busy_all'\n    | 'no_answer'\n    | 'cancelled'\n    | 'connection_lost'\n    | 'failed';\n  /** REMOTE participants only; `userId` is the LiveKit identity. */\n  participants: Array<{\n    userId: string;\n    externalId: string;\n    speaking: boolean;\n    muted: boolean;\n    /** True only with a published, subscribed, unmuted camera track (show video, not avatar). */\n    cameraOn: boolean;\n  }>;\n  audioRoute: 'earpiece' | 'speaker' | 'bluetooth' | 'headset';\n  mutedSelf: boolean;\n  /** True only while the local camera track is actually published and enabled. */\n  cameraOn: boolean;\n  /** Facing of the published local camera; absent when the camera is off. */\n  cameraFacing?: 'front' | 'back';\n}\n\nexport interface ConfigureOptions {\n  /** Drawable resource NAME for the call notification's small icon. */\n  smallIcon?: string;\n  /** Ringback tone: raw resource NAME (Android); main-bundle sound name, mp3/caf/wav (iOS). */\n  ringback?: string;\n  /**\n   * iOS: the APNs environment of this build's `aps-environment`\n   * entitlement. Echoed back with the VoIP token so the server pushes to\n   * the right gateway. Ignored on Android.\n   */\n  apnsEnvironment?: 'production' | 'sandbox';\n}\n\n/** The iOS PushKit (VoIP) token and the APNs environment it belongs to. */\nexport interface VoipToken {\n  /** Hex-encoded PushKit token. */\n  token: string;\n  environment: 'production' | 'sandbox' | string;\n}\n\nexport interface PlaceOptions {\n  media: 'audio' | 'video';\n  /** The user's session token — authorizes placing/joining (CONTRACT.md §3.2). */\n  sessionToken: string;\n}\n\ntype NativeSnapshot = { snapshot: Snapshot | null };\n\ninterface PoolseCallsNative {\n  configure(apiBaseUrl: string, options: ConfigureOptions | null): Promise<void>;\n  getCallState(): NativeSnapshot;\n  place(conversationId: string, media: string, sessionToken: string): Promise<void>;\n  join(callId: string, conversationId: string | null, sessionToken: string): Promise<void>;\n  answer(): void;\n  decline(): void;\n  hangUp(): void;\n  setMuted(muted: boolean): void;\n  setCamera(on: boolean): void;\n  switchCamera(): void;\n  setSpeaker(on: boolean): void;\n  onRingEnded(callId: string, reason: string): void;\n  onCallFinished(callId: string, reason: string | null): void;\n  canUseFullScreenIntent(): boolean;\n  openFullScreenIntentSettings(): void;\n  getVoipToken?(): VoipToken | null;\n  addListener(event: 'onCallState', cb: (payload: NativeSnapshot) => void): { remove(): void };\n  addListener(event: 'onVoipToken', cb: (payload: VoipToken) => void): { remove(): void };\n}\n\nconst native = requireOptionalNativeModule<PoolseCallsNative>('PoolseCalls');\n\n/** True when the native call core is present in this build. */\nexport const nativeCallsAvailable = native != null;\n\n/** Configure once, before any call can arrive. No secrets — just the API origin. */\nexport async function configure(apiBaseUrl: string, options?: ConfigureOptions): Promise<void> {\n  await native?.configure(apiBaseUrl, options ?? null);\n}\n\n/** The current snapshot — safe to read at any moment, including cold answer and before configure. */\nexport function getCallState(): Snapshot | null {\n  return native?.getCallState().snapshot ?? null;\n}\n\nexport type Unsubscribe = () => void;\n\n/** Subscribe to call state. Fires a full snapshot on every change. */\nexport function onCallState(cb: (snapshot: Snapshot | null) => void): Unsubscribe {\n  if (!native) return () => undefined;\n  const sub = native.addListener('onCallState', (payload) => cb(payload.snapshot));\n  return () => sub.remove();\n}\n\nexport function place(conversationId: string, options: PlaceOptions): Promise<void> {\n  return native?.place(conversationId, options.media, options.sessionToken) ?? Promise.resolve();\n}\n\nexport function join(\n  callId: string,\n  conversationId: string | null,\n  sessionToken: string,\n): Promise<void> {\n  return native?.join(callId, conversationId, sessionToken) ?? Promise.resolve();\n}\n\nexport const answer = (): void => native?.answer();\nexport const decline = (): void => native?.decline();\nexport const hangUp = (): void => native?.hangUp();\nexport const setMuted = (muted: boolean): void => native?.setMuted(muted);\nexport const setCamera = (on: boolean): void => native?.setCamera(on);\nexport const switchCamera = (): void => native?.switchCamera();\n/** Route call audio to the loudspeaker (`true`) or back to earpiece / headset (`false`). */\nexport const setSpeaker = (on: boolean): void => native?.setSpeaker(on);\n\n/**\n * Socket forwarding for an open app: a `call:ring_ended` seen on the\n * socket. Idempotent with the push path — the core dedupes.\n */\nexport const onRingEnded = (callId: string, reason: string): void =>\n  native?.onRingEnded(callId, reason);\n\n/**\n * Socket forwarding: `call:finished`. Pass the payload's `reason`\n * (`finished` | `declined_all` | `no_answer` | `cancelled`) so an\n * unanswered caller sees \"Declined\"/\"No answer\", not \"Call ended\".\n * Idempotent with the `finished` push.\n */\nexport const onCallFinished = (callId: string, reason?: string): void =>\n  native?.onCallFinished(callId, reason ?? null);\n\n/**\n * Android 14+: whether the app may show the full-screen ring over the\n * lock screen. `true` on older Android and where the module is absent.\n */\nexport const canUseFullScreenIntent = (): boolean => native?.canUseFullScreenIntent() ?? true;\n\n/** Open the system screen where the user grants full-screen intents (falls back to notification settings). */\nexport const openFullScreenIntentSettings = (): void => native?.openFullScreenIntentSettings();\n\n// ── VoIP push (iOS) ───────────────────────────────────────────────────\n\n/**\n * iOS: the current PushKit VoIP token, registered natively at launch.\n * `null` until iOS issues one, and always on Android (FCM carries rings).\n */\nexport function getVoipToken(): VoipToken | null {\n  return native?.getVoipToken?.() ?? null;\n}\n\n/** iOS: fires whenever PushKit issues (or rotates) the VoIP token. No-op on Android. */\nexport function onVoipToken(cb: (token: VoipToken) => void): Unsubscribe {\n  if (!native || !native.getVoipToken) return () => undefined;\n  const sub = native.addListener('onVoipToken', cb);\n  return () => sub.remove();\n}\n\n// ── video ─────────────────────────────────────────────────────────────\n\nexport interface CallVideoViewProps extends ViewProps {\n  /** Remote participant's userId (LiveKit identity). Omit with local=true for self view. */\n  participantId?: string;\n  local?: boolean;\n  /** default: true for local front camera, false otherwise */\n  mirror?: boolean;\n  /** default 'cover' */\n  fit?: 'cover' | 'contain';\n}\n\ntype NativeVideoProps = CallVideoViewProps;\n\nlet nativeVideo: ComponentType<NativeVideoProps> | null | undefined;\n\n/** Resolved lazily (first render) and only when the native module exists. */\nfunction nativeVideoView(): ComponentType<NativeVideoProps> | null {\n  if (nativeVideo !== undefined) return nativeVideo;\n  nativeVideo = null;\n  if (native) {\n    try {\n      nativeVideo = requireNativeViewManager<NativeVideoProps>('PoolseCalls', 'PoolseCallVideo');\n    } catch {\n      nativeVideo = null; // an older native build without the view\n    }\n  }\n  return nativeVideo;\n}\n\n/**\n * A participant's camera (or, with `local`, your own), rendered natively\n * by the call core. Shows nothing (stays transparent) while that camera\n * is off — draw the avatar from the snapshot's `cameraOn` underneath.\n * Without the native module it renders an empty View.\n */\nexport function CallVideoView(props: CallVideoViewProps): ReactElement | null {\n  const Native = nativeVideoView();\n  if (!Native) {\n    const { participantId: _p, local: _l, mirror: _m, fit: _f, ...rest } = props;\n    return createElement(View, rest);\n  }\n  return createElement(Native, props);\n}\n"]}
+{"version":3,"sources":["../src/index.ts"],"names":["requireOptionalNativeModule","requireNativeViewManager","createElement","View"],"mappings":"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","file":"index.cjs","sourcesContent":["// @poolse/react-native-calls — the React Native face of the native\n// call core (CONTRACT.md §8). A thin, typed surface over the native\n// module: commands in, one snapshot event out. All call logic lives in\n// the native cores; nothing here decides anything about a call.\n//\n// On a platform or build without the native module (Expo Go, web,\n// unlinked), every command is a safe no-op and the state stays idle —\n// so a host can render against this unconditionally.\nimport { createElement, type ComponentType, type ReactElement } from 'react';\nimport { View, type ViewProps } from 'react-native';\nimport { requireNativeViewManager, requireOptionalNativeModule } from 'expo-modules-core';\n\n/**\n * A call's complete state. `null` means idle — no call. After a call\n * ends the snapshot stays `phase: 'ended'` (with `reason`) for ~2.5 s,\n * then becomes `null`.\n */\nexport interface Snapshot {\n  cv: 1;\n  callId: string;\n  conversationId: string;\n  conversationName: string | null;\n  direction: 'incoming' | 'outgoing' | 'joined';\n  media: 'audio' | 'video';\n  phase: 'ringing_in' | 'ringing_out' | 'connecting' | 'active' | 'reconnecting' | 'ended';\n  reason?:\n    | 'left'\n    | 'finished'\n    | 'declined_all'\n    | 'busy_all'\n    | 'no_answer'\n    | 'cancelled'\n    | 'connection_lost'\n    | 'failed';\n  /** REMOTE participants only; `userId` is the LiveKit identity. */\n  participants: Array<{\n    userId: string;\n    externalId: string;\n    speaking: boolean;\n    muted: boolean;\n    /** True only with a published, subscribed, unmuted camera track (show video, not avatar). */\n    cameraOn: boolean;\n  }>;\n  /** The kind of output playing now — the short answer to \"where is the audio\". */\n  audioRoute: AudioOutputKind;\n  /**\n   * Every output the call can play through right now: always the phone\n   * (earpiece, or wired headphones in its place) and the speaker, plus\n   * each connected Bluetooth / USB device by its own name. Empty until\n   * the call's audio is up. Pass an `id` to `setAudioOutput`.\n   */\n  audioOutputs: AudioOutput[];\n  /** The `audioOutputs` entry playing now; null before audio is up. */\n  audioOutputId: string | null;\n  mutedSelf: boolean;\n  /** True only while the local camera track is actually published and enabled. */\n  cameraOn: boolean;\n  /** Facing of the published local camera; absent when the camera is off. */\n  cameraFacing?: 'front' | 'back';\n}\n\nexport type AudioOutputKind = 'earpiece' | 'speaker' | 'bluetooth' | 'headset';\n\n/** One place call audio can play. */\nexport interface AudioOutput {\n  /** Opaque; stable while the device stays connected. */\n  id: string;\n  kind: AudioOutputKind;\n  /**\n   * The device's own name for Bluetooth/USB (\"AirPods Pro\"); a plain\n   * English default for built-ins (\"iPhone\"/\"Phone\", \"Speaker\",\n   * \"Headphones\") — relabel those by `kind` to localise.\n   */\n  name: string;\n}\n\nexport interface ConfigureOptions {\n  /** Drawable resource NAME for the call notification's small icon. */\n  smallIcon?: string;\n  /** Ringback tone: raw resource NAME (Android); main-bundle sound name, mp3/caf/wav (iOS). */\n  ringback?: string;\n  /**\n   * iOS: the APNs environment of this build's `aps-environment`\n   * entitlement. Echoed back with the VoIP token so the server pushes to\n   * the right gateway. Ignored on Android.\n   */\n  apnsEnvironment?: 'production' | 'sandbox';\n}\n\n/** The iOS PushKit (VoIP) token and the APNs environment it belongs to. */\nexport interface VoipToken {\n  /** Hex-encoded PushKit token. */\n  token: string;\n  environment: 'production' | 'sandbox' | string;\n}\n\nexport interface PlaceOptions {\n  media: 'audio' | 'video';\n  /** The user's session token — authorizes placing/joining (CONTRACT.md §3.2). */\n  sessionToken: string;\n}\n\ntype NativeSnapshot = { snapshot: Snapshot | null };\n\ninterface PoolseCallsNative {\n  configure(apiBaseUrl: string, options: ConfigureOptions | null): Promise<void>;\n  getCallState(): NativeSnapshot;\n  place(conversationId: string, media: string, sessionToken: string): Promise<void>;\n  join(callId: string, conversationId: string | null, sessionToken: string): Promise<void>;\n  answer(): void;\n  decline(): void;\n  hangUp(): void;\n  setMuted(muted: boolean): void;\n  setCamera(on: boolean): void;\n  switchCamera(): void;\n  setSpeaker(on: boolean): void;\n  setAudioOutput?(id: string): void;\n  onRingEnded(callId: string, reason: string): void;\n  onCallFinished(callId: string, reason: string | null): void;\n  canUseFullScreenIntent(): boolean;\n  openFullScreenIntentSettings(): void;\n  getVoipToken?(): VoipToken | null;\n  addListener(event: 'onCallState', cb: (payload: NativeSnapshot) => void): { remove(): void };\n  addListener(event: 'onVoipToken', cb: (payload: VoipToken) => void): { remove(): void };\n}\n\nconst native = requireOptionalNativeModule<PoolseCallsNative>('PoolseCalls');\n\n/** True when the native call core is present in this build. */\nexport const nativeCallsAvailable = native != null;\n\n/** Configure once, before any call can arrive. No secrets — just the API origin. */\nexport async function configure(apiBaseUrl: string, options?: ConfigureOptions): Promise<void> {\n  await native?.configure(apiBaseUrl, options ?? null);\n}\n\n/** The current snapshot — safe to read at any moment, including cold answer and before configure. */\nexport function getCallState(): Snapshot | null {\n  return native?.getCallState().snapshot ?? null;\n}\n\nexport type Unsubscribe = () => void;\n\n/** Subscribe to call state. Fires a full snapshot on every change. */\nexport function onCallState(cb: (snapshot: Snapshot | null) => void): Unsubscribe {\n  if (!native) return () => undefined;\n  const sub = native.addListener('onCallState', (payload) => cb(payload.snapshot));\n  return () => sub.remove();\n}\n\nexport function place(conversationId: string, options: PlaceOptions): Promise<void> {\n  return native?.place(conversationId, options.media, options.sessionToken) ?? Promise.resolve();\n}\n\nexport function join(\n  callId: string,\n  conversationId: string | null,\n  sessionToken: string,\n): Promise<void> {\n  return native?.join(callId, conversationId, sessionToken) ?? Promise.resolve();\n}\n\nexport const answer = (): void => native?.answer();\nexport const decline = (): void => native?.decline();\nexport const hangUp = (): void => native?.hangUp();\nexport const setMuted = (muted: boolean): void => native?.setMuted(muted);\nexport const setCamera = (on: boolean): void => native?.setCamera(on);\nexport const switchCamera = (): void => native?.switchCamera();\n/** Route call audio to the loudspeaker (`true`) or back to earpiece / headset (`false`). */\nexport const setSpeaker = (on: boolean): void => native?.setSpeaker(on);\n\n/**\n * Play call audio through one of `snapshot.audioOutputs`. The choice\n * holds for the rest of the call, until that device disconnects or a new\n * headset / Bluetooth device connects (which takes over, as in the\n * phone's own dialer). Without a choice a connected headset wins, then\n * the earpiece for voice calls or the speaker for video.\n */\nexport function setAudioOutput(id: string): void {\n  if (native?.setAudioOutput) native.setAudioOutput(id);\n  else native?.setSpeaker(id === 'speaker'); // an older native build\n}\n\n/**\n * Socket forwarding for an open app: a `call:ring_ended` seen on the\n * socket. Idempotent with the push path — the core dedupes.\n */\nexport const onRingEnded = (callId: string, reason: string): void =>\n  native?.onRingEnded(callId, reason);\n\n/**\n * Socket forwarding: `call:finished`. Pass the payload's `reason`\n * (`finished` | `declined_all` | `no_answer` | `cancelled`) so an\n * unanswered caller sees \"Declined\"/\"No answer\", not \"Call ended\".\n * Idempotent with the `finished` push.\n */\nexport const onCallFinished = (callId: string, reason?: string): void =>\n  native?.onCallFinished(callId, reason ?? null);\n\n/**\n * Android 14+: whether the app may show the full-screen ring over the\n * lock screen. `true` on older Android and where the module is absent.\n */\nexport const canUseFullScreenIntent = (): boolean => native?.canUseFullScreenIntent() ?? true;\n\n/** Open the system screen where the user grants full-screen intents (falls back to notification settings). */\nexport const openFullScreenIntentSettings = (): void => native?.openFullScreenIntentSettings();\n\n// ── VoIP push (iOS) ───────────────────────────────────────────────────\n\n/**\n * iOS: the current PushKit VoIP token, registered natively at launch.\n * `null` until iOS issues one, and always on Android (FCM carries rings).\n */\nexport function getVoipToken(): VoipToken | null {\n  return native?.getVoipToken?.() ?? null;\n}\n\n/** iOS: fires whenever PushKit issues (or rotates) the VoIP token. No-op on Android. */\nexport function onVoipToken(cb: (token: VoipToken) => void): Unsubscribe {\n  if (!native || !native.getVoipToken) return () => undefined;\n  const sub = native.addListener('onVoipToken', cb);\n  return () => sub.remove();\n}\n\n// ── video ─────────────────────────────────────────────────────────────\n\nexport interface CallVideoViewProps extends ViewProps {\n  /** Remote participant's userId (LiveKit identity). Omit with local=true for self view. */\n  participantId?: string;\n  local?: boolean;\n  /** default: true for local front camera, false otherwise */\n  mirror?: boolean;\n  /** default 'cover' */\n  fit?: 'cover' | 'contain';\n}\n\ntype NativeVideoProps = CallVideoViewProps;\n\nlet nativeVideo: ComponentType<NativeVideoProps> | null | undefined;\n\n/** Resolved lazily (first render) and only when the native module exists. */\nfunction nativeVideoView(): ComponentType<NativeVideoProps> | null {\n  if (nativeVideo !== undefined) return nativeVideo;\n  nativeVideo = null;\n  if (native) {\n    try {\n      nativeVideo = requireNativeViewManager<NativeVideoProps>('PoolseCalls', 'PoolseCallVideo');\n    } catch {\n      nativeVideo = null; // an older native build without the view\n    }\n  }\n  return nativeVideo;\n}\n\n/**\n * A participant's camera (or, with `local`, your own), rendered natively\n * by the call core. Shows nothing (stays transparent) while that camera\n * is off — draw the avatar from the snapshot's `cameraOn` underneath.\n * Without the native module it renders an empty View.\n */\nexport function CallVideoView(props: CallVideoViewProps): ReactElement | null {\n  const Native = nativeVideoView();\n  if (!Native) {\n    const { participantId: _p, local: _l, mirror: _m, fit: _f, ...rest } = props;\n    return createElement(View, rest);\n  }\n  return createElement(Native, props);\n}\n"]}

package/dist/index.d.cts

@@ -24,13 +24,36 @@ interface Snapshot {
         /** True only with a published, subscribed, unmuted camera track (show video, not avatar). */
         cameraOn: boolean;
     }>;
-    audioRoute: 'earpiece' | 'speaker' | 'bluetooth' | 'headset';
+    /** The kind of output playing now — the short answer to "where is the audio". */
+    audioRoute: AudioOutputKind;
+    /**
+     * Every output the call can play through right now: always the phone
+     * (earpiece, or wired headphones in its place) and the speaker, plus
+     * each connected Bluetooth / USB device by its own name. Empty until
+     * the call's audio is up. Pass an `id` to `setAudioOutput`.
+     */
+    audioOutputs: AudioOutput[];
+    /** The `audioOutputs` entry playing now; null before audio is up. */
+    audioOutputId: string | null;
     mutedSelf: boolean;
     /** True only while the local camera track is actually published and enabled. */
     cameraOn: boolean;
     /** Facing of the published local camera; absent when the camera is off. */
     cameraFacing?: 'front' | 'back';
 }
+type AudioOutputKind = 'earpiece' | 'speaker' | 'bluetooth' | 'headset';
+/** One place call audio can play. */
+interface AudioOutput {
+    /** Opaque; stable while the device stays connected. */
+    id: string;
+    kind: AudioOutputKind;
+    /**
+     * The device's own name for Bluetooth/USB ("AirPods Pro"); a plain
+     * English default for built-ins ("iPhone"/"Phone", "Speaker",
+     * "Headphones") — relabel those by `kind` to localise.
+     */
+    name: string;
+}
 interface ConfigureOptions {
     /** Drawable resource NAME for the call notification's small icon. */
     smallIcon?: string;
@@ -73,6 +96,14 @@ declare const setCamera: (on: boolean) => void;
 declare const switchCamera: () => void;
 /** Route call audio to the loudspeaker (`true`) or back to earpiece / headset (`false`). */
 declare const setSpeaker: (on: boolean) => void;
+/**
+ * Play call audio through one of `snapshot.audioOutputs`. The choice
+ * holds for the rest of the call, until that device disconnects or a new
+ * headset / Bluetooth device connects (which takes over, as in the
+ * phone's own dialer). Without a choice a connected headset wins, then
+ * the earpiece for voice calls or the speaker for video.
+ */
+declare function setAudioOutput(id: string): void;
 /**
  * Socket forwarding for an open app: a `call:ring_ended` seen on the
  * socket. Idempotent with the push path — the core dedupes.
@@ -116,4 +147,4 @@ interface CallVideoViewProps extends ViewProps {
  */
 declare function CallVideoView(props: CallVideoViewProps): ReactElement | null;
 
-export { CallVideoView, type CallVideoViewProps, type ConfigureOptions, type PlaceOptions, type Snapshot, type Unsubscribe, type VoipToken, answer, canUseFullScreenIntent, configure, decline, getCallState, getVoipToken, hangUp, join, nativeCallsAvailable, onCallFinished, onCallState, onRingEnded, onVoipToken, openFullScreenIntentSettings, place, setCamera, setMuted, setSpeaker, switchCamera };
+export { type AudioOutput, type AudioOutputKind, CallVideoView, type CallVideoViewProps, type ConfigureOptions, type PlaceOptions, type Snapshot, type Unsubscribe, type VoipToken, answer, canUseFullScreenIntent, configure, decline, getCallState, getVoipToken, hangUp, join, nativeCallsAvailable, onCallFinished, onCallState, onRingEnded, onVoipToken, openFullScreenIntentSettings, place, setAudioOutput, setCamera, setMuted, setSpeaker, switchCamera };

package/dist/index.d.ts

@@ -24,13 +24,36 @@ interface Snapshot {
         /** True only with a published, subscribed, unmuted camera track (show video, not avatar). */
         cameraOn: boolean;
     }>;
-    audioRoute: 'earpiece' | 'speaker' | 'bluetooth' | 'headset';
+    /** The kind of output playing now — the short answer to "where is the audio". */
+    audioRoute: AudioOutputKind;
+    /**
+     * Every output the call can play through right now: always the phone
+     * (earpiece, or wired headphones in its place) and the speaker, plus
+     * each connected Bluetooth / USB device by its own name. Empty until
+     * the call's audio is up. Pass an `id` to `setAudioOutput`.
+     */
+    audioOutputs: AudioOutput[];
+    /** The `audioOutputs` entry playing now; null before audio is up. */
+    audioOutputId: string | null;
     mutedSelf: boolean;
     /** True only while the local camera track is actually published and enabled. */
     cameraOn: boolean;
     /** Facing of the published local camera; absent when the camera is off. */
     cameraFacing?: 'front' | 'back';
 }
+type AudioOutputKind = 'earpiece' | 'speaker' | 'bluetooth' | 'headset';
+/** One place call audio can play. */
+interface AudioOutput {
+    /** Opaque; stable while the device stays connected. */
+    id: string;
+    kind: AudioOutputKind;
+    /**
+     * The device's own name for Bluetooth/USB ("AirPods Pro"); a plain
+     * English default for built-ins ("iPhone"/"Phone", "Speaker",
+     * "Headphones") — relabel those by `kind` to localise.
+     */
+    name: string;
+}
 interface ConfigureOptions {
     /** Drawable resource NAME for the call notification's small icon. */
     smallIcon?: string;
@@ -73,6 +96,14 @@ declare const setCamera: (on: boolean) => void;
 declare const switchCamera: () => void;
 /** Route call audio to the loudspeaker (`true`) or back to earpiece / headset (`false`). */
 declare const setSpeaker: (on: boolean) => void;
+/**
+ * Play call audio through one of `snapshot.audioOutputs`. The choice
+ * holds for the rest of the call, until that device disconnects or a new
+ * headset / Bluetooth device connects (which takes over, as in the
+ * phone's own dialer). Without a choice a connected headset wins, then
+ * the earpiece for voice calls or the speaker for video.
+ */
+declare function setAudioOutput(id: string): void;
 /**
  * Socket forwarding for an open app: a `call:ring_ended` seen on the
  * socket. Idempotent with the push path — the core dedupes.
@@ -116,4 +147,4 @@ interface CallVideoViewProps extends ViewProps {
  */
 declare function CallVideoView(props: CallVideoViewProps): ReactElement | null;
 
-export { CallVideoView, type CallVideoViewProps, type ConfigureOptions, type PlaceOptions, type Snapshot, type Unsubscribe, type VoipToken, answer, canUseFullScreenIntent, configure, decline, getCallState, getVoipToken, hangUp, join, nativeCallsAvailable, onCallFinished, onCallState, onRingEnded, onVoipToken, openFullScreenIntentSettings, place, setCamera, setMuted, setSpeaker, switchCamera };
+export { type AudioOutput, type AudioOutputKind, CallVideoView, type CallVideoViewProps, type ConfigureOptions, type PlaceOptions, type Snapshot, type Unsubscribe, type VoipToken, answer, canUseFullScreenIntent, configure, decline, getCallState, getVoipToken, hangUp, join, nativeCallsAvailable, onCallFinished, onCallState, onRingEnded, onVoipToken, openFullScreenIntentSettings, place, setAudioOutput, setCamera, setMuted, setSpeaker, switchCamera };

package/dist/index.js

@@ -29,6 +29,10 @@ var setMuted = (muted) => native?.setMuted(muted);
 var setCamera = (on) => native?.setCamera(on);
 var switchCamera = () => native?.switchCamera();
 var setSpeaker = (on) => native?.setSpeaker(on);
+function setAudioOutput(id) {
+  if (native?.setAudioOutput) native.setAudioOutput(id);
+  else native?.setSpeaker(id === "speaker");
+}
 var onRingEnded = (callId, reason) => native?.onRingEnded(callId, reason);
 var onCallFinished = (callId, reason) => native?.onCallFinished(callId, reason ?? null);
 var canUseFullScreenIntent = () => native?.canUseFullScreenIntent() ?? true;
@@ -63,6 +67,6 @@ function CallVideoView(props) {
   return createElement(Native, props);
 }
 
-export { CallVideoView, answer, canUseFullScreenIntent, configure, decline, getCallState, getVoipToken, hangUp, join, nativeCallsAvailable, onCallFinished, onCallState, onRingEnded, onVoipToken, openFullScreenIntentSettings, place, setCamera, setMuted, setSpeaker, switchCamera };
+export { CallVideoView, answer, canUseFullScreenIntent, configure, decline, getCallState, getVoipToken, hangUp, join, nativeCallsAvailable, onCallFinished, onCallState, onRingEnded, onVoipToken, openFullScreenIntentSettings, place, setAudioOutput, setCamera, setMuted, setSpeaker, switchCamera };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;;;AAoGA,IAAM,MAAA,GAAS,4BAA+C,aAAa,CAAA;AAGpE,IAAM,uBAAuB,MAAA,IAAU;AAG9C,eAAsB,SAAA,CAAU,YAAoB,OAAA,EAA2C;AAC7F,EAAA,MAAM,MAAA,EAAQ,SAAA,CAAU,UAAA,EAAY,OAAA,IAAW,IAAI,CAAA;AACrD;AAGO,SAAS,YAAA,GAAgC;AAC9C,EAAA,OAAO,MAAA,EAAQ,YAAA,EAAa,CAAE,QAAA,IAAY,IAAA;AAC5C;AAKO,SAAS,YAAY,EAAA,EAAsD;AAChF,EAAA,IAAI,CAAC,MAAA,EAAQ,OAAO,MAAM,MAAA;AAC1B,EAAA,MAAM,GAAA,GAAM,OAAO,WAAA,CAAY,aAAA,EAAe,CAAC,OAAA,KAAY,EAAA,CAAG,OAAA,CAAQ,QAAQ,CAAC,CAAA;AAC/E,EAAA,OAAO,MAAM,IAAI,MAAA,EAAO;AAC1B;AAEO,SAAS,KAAA,CAAM,gBAAwB,OAAA,EAAsC;AAClF,EAAA,OAAO,MAAA,EAAQ,MAAM,cAAA,EAAgB,OAAA,CAAQ,OAAO,OAAA,CAAQ,YAAY,CAAA,IAAK,OAAA,CAAQ,OAAA,EAAQ;AAC/F;AAEO,SAAS,IAAA,CACd,MAAA,EACA,cAAA,EACA,YAAA,EACe;AACf,EAAA,OAAO,QAAQ,IAAA,CAAK,MAAA,EAAQ,gBAAgB,YAAY,CAAA,IAAK,QAAQ,OAAA,EAAQ;AAC/E;AAEO,IAAM,MAAA,GAAS,MAAY,MAAA,EAAQ,MAAA;AACnC,IAAM,OAAA,GAAU,MAAY,MAAA,EAAQ,OAAA;AACpC,IAAM,MAAA,GAAS,MAAY,MAAA,EAAQ,MAAA;AACnC,IAAM,QAAA,GAAW,CAAC,KAAA,KAAyB,MAAA,EAAQ,SAAS,KAAK;AACjE,IAAM,SAAA,GAAY,CAAC,EAAA,KAAsB,MAAA,EAAQ,UAAU,EAAE;AAC7D,IAAM,YAAA,GAAe,MAAY,MAAA,EAAQ,YAAA;AAEzC,IAAM,UAAA,GAAa,CAAC,EAAA,KAAsB,MAAA,EAAQ,WAAW,EAAE;AAM/D,IAAM,cAAc,CAAC,MAAA,EAAgB,WAC1C,MAAA,EAAQ,WAAA,CAAY,QAAQ,MAAM;AAQ7B,IAAM,cAAA,GAAiB,CAAC,MAAA,EAAgB,MAAA,KAC7C,QAAQ,cAAA,CAAe,MAAA,EAAQ,UAAU,IAAI;AAMxC,IAAM,sBAAA,GAAyB,MAAe,MAAA,EAAQ,sBAAA,EAAuB,IAAK;AAGlF,IAAM,4BAAA,GAA+B,MAAY,MAAA,EAAQ,4BAAA;AAQzD,SAAS,YAAA,GAAiC;AAC/C,EAAA,OAAO,MAAA,EAAQ,gBAAe,IAAK,IAAA;AACrC;AAGO,SAAS,YAAY,EAAA,EAA6C;AACvE,EAAA,IAAI,CAAC,MAAA,IAAU,CAAC,MAAA,CAAO,YAAA,SAAqB,MAAM,MAAA;AAClD,EAAA,MAAM,GAAA,GAAM,MAAA,CAAO,WAAA,CAAY,aAAA,EAAe,EAAE,CAAA;AAChD,EAAA,OAAO,MAAM,IAAI,MAAA,EAAO;AAC1B;AAgBA,IAAI,WAAA;AAGJ,SAAS,eAAA,GAA0D;AACjE,EAAA,IAAI,WAAA,KAAgB,QAAW,OAAO,WAAA;AACtC,EAAA,WAAA,GAAc,IAAA;AACd,EAAA,IAAI,MAAA,EAAQ;AACV,IAAA,IAAI;AACF,MAAA,WAAA,GAAc,wBAAA,CAA2C,eAAe,iBAAiB,CAAA;AAAA,IAC3F,CAAA,CAAA,MAAQ;AACN,MAAA,WAAA,GAAc,IAAA;AAAA,IAChB;AAAA,EACF;AACA,EAAA,OAAO,WAAA;AACT;AAQO,SAAS,cAAc,KAAA,EAAgD;AAC5E,EAAA,MAAM,SAAS,eAAA,EAAgB;AAC/B,EAAA,IAAI,CAAC,MAAA,EAAQ;AACX,IAAA,MAAM,EAAE,aAAA,EAAe,EAAA,EAAI,KAAA,EAAO,EAAA,EAAI,MAAA,EAAQ,EAAA,EAAI,GAAA,EAAK,EAAA,EAAI,GAAG,IAAA,EAAK,GAAI,KAAA;AACvE,IAAA,OAAO,aAAA,CAAc,MAAM,IAAI,CAAA;AAAA,EACjC;AACA,EAAA,OAAO,aAAA,CAAc,QAAQ,KAAK,CAAA;AACpC","file":"index.js","sourcesContent":["// @poolse/react-native-calls — the React Native face of the native\n// call core (CONTRACT.md §8). A thin, typed surface over the native\n// module: commands in, one snapshot event out. All call logic lives in\n// the native cores; nothing here decides anything about a call.\n//\n// On a platform or build without the native module (Expo Go, web,\n// unlinked), every command is a safe no-op and the state stays idle —\n// so a host can render against this unconditionally.\nimport { createElement, type ComponentType, type ReactElement } from 'react';\nimport { View, type ViewProps } from 'react-native';\nimport { requireNativeViewManager, requireOptionalNativeModule } from 'expo-modules-core';\n\n/**\n * A call's complete state. `null` means idle — no call. After a call\n * ends the snapshot stays `phase: 'ended'` (with `reason`) for ~2.5 s,\n * then becomes `null`.\n */\nexport interface Snapshot {\n  cv: 1;\n  callId: string;\n  conversationId: string;\n  conversationName: string | null;\n  direction: 'incoming' | 'outgoing' | 'joined';\n  media: 'audio' | 'video';\n  phase: 'ringing_in' | 'ringing_out' | 'connecting' | 'active' | 'reconnecting' | 'ended';\n  reason?:\n    | 'left'\n    | 'finished'\n    | 'declined_all'\n    | 'busy_all'\n    | 'no_answer'\n    | 'cancelled'\n    | 'connection_lost'\n    | 'failed';\n  /** REMOTE participants only; `userId` is the LiveKit identity. */\n  participants: Array<{\n    userId: string;\n    externalId: string;\n    speaking: boolean;\n    muted: boolean;\n    /** True only with a published, subscribed, unmuted camera track (show video, not avatar). */\n    cameraOn: boolean;\n  }>;\n  audioRoute: 'earpiece' | 'speaker' | 'bluetooth' | 'headset';\n  mutedSelf: boolean;\n  /** True only while the local camera track is actually published and enabled. */\n  cameraOn: boolean;\n  /** Facing of the published local camera; absent when the camera is off. */\n  cameraFacing?: 'front' | 'back';\n}\n\nexport interface ConfigureOptions {\n  /** Drawable resource NAME for the call notification's small icon. */\n  smallIcon?: string;\n  /** Ringback tone: raw resource NAME (Android); main-bundle sound name, mp3/caf/wav (iOS). */\n  ringback?: string;\n  /**\n   * iOS: the APNs environment of this build's `aps-environment`\n   * entitlement. Echoed back with the VoIP token so the server pushes to\n   * the right gateway. Ignored on Android.\n   */\n  apnsEnvironment?: 'production' | 'sandbox';\n}\n\n/** The iOS PushKit (VoIP) token and the APNs environment it belongs to. */\nexport interface VoipToken {\n  /** Hex-encoded PushKit token. */\n  token: string;\n  environment: 'production' | 'sandbox' | string;\n}\n\nexport interface PlaceOptions {\n  media: 'audio' | 'video';\n  /** The user's session token — authorizes placing/joining (CONTRACT.md §3.2). */\n  sessionToken: string;\n}\n\ntype NativeSnapshot = { snapshot: Snapshot | null };\n\ninterface PoolseCallsNative {\n  configure(apiBaseUrl: string, options: ConfigureOptions | null): Promise<void>;\n  getCallState(): NativeSnapshot;\n  place(conversationId: string, media: string, sessionToken: string): Promise<void>;\n  join(callId: string, conversationId: string | null, sessionToken: string): Promise<void>;\n  answer(): void;\n  decline(): void;\n  hangUp(): void;\n  setMuted(muted: boolean): void;\n  setCamera(on: boolean): void;\n  switchCamera(): void;\n  setSpeaker(on: boolean): void;\n  onRingEnded(callId: string, reason: string): void;\n  onCallFinished(callId: string, reason: string | null): void;\n  canUseFullScreenIntent(): boolean;\n  openFullScreenIntentSettings(): void;\n  getVoipToken?(): VoipToken | null;\n  addListener(event: 'onCallState', cb: (payload: NativeSnapshot) => void): { remove(): void };\n  addListener(event: 'onVoipToken', cb: (payload: VoipToken) => void): { remove(): void };\n}\n\nconst native = requireOptionalNativeModule<PoolseCallsNative>('PoolseCalls');\n\n/** True when the native call core is present in this build. */\nexport const nativeCallsAvailable = native != null;\n\n/** Configure once, before any call can arrive. No secrets — just the API origin. */\nexport async function configure(apiBaseUrl: string, options?: ConfigureOptions): Promise<void> {\n  await native?.configure(apiBaseUrl, options ?? null);\n}\n\n/** The current snapshot — safe to read at any moment, including cold answer and before configure. */\nexport function getCallState(): Snapshot | null {\n  return native?.getCallState().snapshot ?? null;\n}\n\nexport type Unsubscribe = () => void;\n\n/** Subscribe to call state. Fires a full snapshot on every change. */\nexport function onCallState(cb: (snapshot: Snapshot | null) => void): Unsubscribe {\n  if (!native) return () => undefined;\n  const sub = native.addListener('onCallState', (payload) => cb(payload.snapshot));\n  return () => sub.remove();\n}\n\nexport function place(conversationId: string, options: PlaceOptions): Promise<void> {\n  return native?.place(conversationId, options.media, options.sessionToken) ?? Promise.resolve();\n}\n\nexport function join(\n  callId: string,\n  conversationId: string | null,\n  sessionToken: string,\n): Promise<void> {\n  return native?.join(callId, conversationId, sessionToken) ?? Promise.resolve();\n}\n\nexport const answer = (): void => native?.answer();\nexport const decline = (): void => native?.decline();\nexport const hangUp = (): void => native?.hangUp();\nexport const setMuted = (muted: boolean): void => native?.setMuted(muted);\nexport const setCamera = (on: boolean): void => native?.setCamera(on);\nexport const switchCamera = (): void => native?.switchCamera();\n/** Route call audio to the loudspeaker (`true`) or back to earpiece / headset (`false`). */\nexport const setSpeaker = (on: boolean): void => native?.setSpeaker(on);\n\n/**\n * Socket forwarding for an open app: a `call:ring_ended` seen on the\n * socket. Idempotent with the push path — the core dedupes.\n */\nexport const onRingEnded = (callId: string, reason: string): void =>\n  native?.onRingEnded(callId, reason);\n\n/**\n * Socket forwarding: `call:finished`. Pass the payload's `reason`\n * (`finished` | `declined_all` | `no_answer` | `cancelled`) so an\n * unanswered caller sees \"Declined\"/\"No answer\", not \"Call ended\".\n * Idempotent with the `finished` push.\n */\nexport const onCallFinished = (callId: string, reason?: string): void =>\n  native?.onCallFinished(callId, reason ?? null);\n\n/**\n * Android 14+: whether the app may show the full-screen ring over the\n * lock screen. `true` on older Android and where the module is absent.\n */\nexport const canUseFullScreenIntent = (): boolean => native?.canUseFullScreenIntent() ?? true;\n\n/** Open the system screen where the user grants full-screen intents (falls back to notification settings). */\nexport const openFullScreenIntentSettings = (): void => native?.openFullScreenIntentSettings();\n\n// ── VoIP push (iOS) ───────────────────────────────────────────────────\n\n/**\n * iOS: the current PushKit VoIP token, registered natively at launch.\n * `null` until iOS issues one, and always on Android (FCM carries rings).\n */\nexport function getVoipToken(): VoipToken | null {\n  return native?.getVoipToken?.() ?? null;\n}\n\n/** iOS: fires whenever PushKit issues (or rotates) the VoIP token. No-op on Android. */\nexport function onVoipToken(cb: (token: VoipToken) => void): Unsubscribe {\n  if (!native || !native.getVoipToken) return () => undefined;\n  const sub = native.addListener('onVoipToken', cb);\n  return () => sub.remove();\n}\n\n// ── video ─────────────────────────────────────────────────────────────\n\nexport interface CallVideoViewProps extends ViewProps {\n  /** Remote participant's userId (LiveKit identity). Omit with local=true for self view. */\n  participantId?: string;\n  local?: boolean;\n  /** default: true for local front camera, false otherwise */\n  mirror?: boolean;\n  /** default 'cover' */\n  fit?: 'cover' | 'contain';\n}\n\ntype NativeVideoProps = CallVideoViewProps;\n\nlet nativeVideo: ComponentType<NativeVideoProps> | null | undefined;\n\n/** Resolved lazily (first render) and only when the native module exists. */\nfunction nativeVideoView(): ComponentType<NativeVideoProps> | null {\n  if (nativeVideo !== undefined) return nativeVideo;\n  nativeVideo = null;\n  if (native) {\n    try {\n      nativeVideo = requireNativeViewManager<NativeVideoProps>('PoolseCalls', 'PoolseCallVideo');\n    } catch {\n      nativeVideo = null; // an older native build without the view\n    }\n  }\n  return nativeVideo;\n}\n\n/**\n * A participant's camera (or, with `local`, your own), rendered natively\n * by the call core. Shows nothing (stays transparent) while that camera\n * is off — draw the avatar from the snapshot's `cameraOn` underneath.\n * Without the native module it renders an empty View.\n */\nexport function CallVideoView(props: CallVideoViewProps): ReactElement | null {\n  const Native = nativeVideoView();\n  if (!Native) {\n    const { participantId: _p, local: _l, mirror: _m, fit: _f, ...rest } = props;\n    return createElement(View, rest);\n  }\n  return createElement(Native, props);\n}\n"]}
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["// @poolse/react-native-calls — the React Native face of the native\n// call core (CONTRACT.md §8). A thin, typed surface over the native\n// module: commands in, one snapshot event out. All call logic lives in\n// the native cores; nothing here decides anything about a call.\n//\n// On a platform or build without the native module (Expo Go, web,\n// unlinked), every command is a safe no-op and the state stays idle —\n// so a host can render against this unconditionally.\nimport { createElement, type ComponentType, type ReactElement } from 'react';\nimport { View, type ViewProps } from 'react-native';\nimport { requireNativeViewManager, requireOptionalNativeModule } from 'expo-modules-core';\n\n/**\n * A call's complete state. `null` means idle — no call. After a call\n * ends the snapshot stays `phase: 'ended'` (with `reason`) for ~2.5 s,\n * then becomes `null`.\n */\nexport interface Snapshot {\n  cv: 1;\n  callId: string;\n  conversationId: string;\n  conversationName: string | null;\n  direction: 'incoming' | 'outgoing' | 'joined';\n  media: 'audio' | 'video';\n  phase: 'ringing_in' | 'ringing_out' | 'connecting' | 'active' | 'reconnecting' | 'ended';\n  reason?:\n    | 'left'\n    | 'finished'\n    | 'declined_all'\n    | 'busy_all'\n    | 'no_answer'\n    | 'cancelled'\n    | 'connection_lost'\n    | 'failed';\n  /** REMOTE participants only; `userId` is the LiveKit identity. */\n  participants: Array<{\n    userId: string;\n    externalId: string;\n    speaking: boolean;\n    muted: boolean;\n    /** True only with a published, subscribed, unmuted camera track (show video, not avatar). */\n    cameraOn: boolean;\n  }>;\n  /** The kind of output playing now — the short answer to \"where is the audio\". */\n  audioRoute: AudioOutputKind;\n  /**\n   * Every output the call can play through right now: always the phone\n   * (earpiece, or wired headphones in its place) and the speaker, plus\n   * each connected Bluetooth / USB device by its own name. Empty until\n   * the call's audio is up. Pass an `id` to `setAudioOutput`.\n   */\n  audioOutputs: AudioOutput[];\n  /** The `audioOutputs` entry playing now; null before audio is up. */\n  audioOutputId: string | null;\n  mutedSelf: boolean;\n  /** True only while the local camera track is actually published and enabled. */\n  cameraOn: boolean;\n  /** Facing of the published local camera; absent when the camera is off. */\n  cameraFacing?: 'front' | 'back';\n}\n\nexport type AudioOutputKind = 'earpiece' | 'speaker' | 'bluetooth' | 'headset';\n\n/** One place call audio can play. */\nexport interface AudioOutput {\n  /** Opaque; stable while the device stays connected. */\n  id: string;\n  kind: AudioOutputKind;\n  /**\n   * The device's own name for Bluetooth/USB (\"AirPods Pro\"); a plain\n   * English default for built-ins (\"iPhone\"/\"Phone\", \"Speaker\",\n   * \"Headphones\") — relabel those by `kind` to localise.\n   */\n  name: string;\n}\n\nexport interface ConfigureOptions {\n  /** Drawable resource NAME for the call notification's small icon. */\n  smallIcon?: string;\n  /** Ringback tone: raw resource NAME (Android); main-bundle sound name, mp3/caf/wav (iOS). */\n  ringback?: string;\n  /**\n   * iOS: the APNs environment of this build's `aps-environment`\n   * entitlement. Echoed back with the VoIP token so the server pushes to\n   * the right gateway. Ignored on Android.\n   */\n  apnsEnvironment?: 'production' | 'sandbox';\n}\n\n/** The iOS PushKit (VoIP) token and the APNs environment it belongs to. */\nexport interface VoipToken {\n  /** Hex-encoded PushKit token. */\n  token: string;\n  environment: 'production' | 'sandbox' | string;\n}\n\nexport interface PlaceOptions {\n  media: 'audio' | 'video';\n  /** The user's session token — authorizes placing/joining (CONTRACT.md §3.2). */\n  sessionToken: string;\n}\n\ntype NativeSnapshot = { snapshot: Snapshot | null };\n\ninterface PoolseCallsNative {\n  configure(apiBaseUrl: string, options: ConfigureOptions | null): Promise<void>;\n  getCallState(): NativeSnapshot;\n  place(conversationId: string, media: string, sessionToken: string): Promise<void>;\n  join(callId: string, conversationId: string | null, sessionToken: string): Promise<void>;\n  answer(): void;\n  decline(): void;\n  hangUp(): void;\n  setMuted(muted: boolean): void;\n  setCamera(on: boolean): void;\n  switchCamera(): void;\n  setSpeaker(on: boolean): void;\n  setAudioOutput?(id: string): void;\n  onRingEnded(callId: string, reason: string): void;\n  onCallFinished(callId: string, reason: string | null): void;\n  canUseFullScreenIntent(): boolean;\n  openFullScreenIntentSettings(): void;\n  getVoipToken?(): VoipToken | null;\n  addListener(event: 'onCallState', cb: (payload: NativeSnapshot) => void): { remove(): void };\n  addListener(event: 'onVoipToken', cb: (payload: VoipToken) => void): { remove(): void };\n}\n\nconst native = requireOptionalNativeModule<PoolseCallsNative>('PoolseCalls');\n\n/** True when the native call core is present in this build. */\nexport const nativeCallsAvailable = native != null;\n\n/** Configure once, before any call can arrive. No secrets — just the API origin. */\nexport async function configure(apiBaseUrl: string, options?: ConfigureOptions): Promise<void> {\n  await native?.configure(apiBaseUrl, options ?? null);\n}\n\n/** The current snapshot — safe to read at any moment, including cold answer and before configure. */\nexport function getCallState(): Snapshot | null {\n  return native?.getCallState().snapshot ?? null;\n}\n\nexport type Unsubscribe = () => void;\n\n/** Subscribe to call state. Fires a full snapshot on every change. */\nexport function onCallState(cb: (snapshot: Snapshot | null) => void): Unsubscribe {\n  if (!native) return () => undefined;\n  const sub = native.addListener('onCallState', (payload) => cb(payload.snapshot));\n  return () => sub.remove();\n}\n\nexport function place(conversationId: string, options: PlaceOptions): Promise<void> {\n  return native?.place(conversationId, options.media, options.sessionToken) ?? Promise.resolve();\n}\n\nexport function join(\n  callId: string,\n  conversationId: string | null,\n  sessionToken: string,\n): Promise<void> {\n  return native?.join(callId, conversationId, sessionToken) ?? Promise.resolve();\n}\n\nexport const answer = (): void => native?.answer();\nexport const decline = (): void => native?.decline();\nexport const hangUp = (): void => native?.hangUp();\nexport const setMuted = (muted: boolean): void => native?.setMuted(muted);\nexport const setCamera = (on: boolean): void => native?.setCamera(on);\nexport const switchCamera = (): void => native?.switchCamera();\n/** Route call audio to the loudspeaker (`true`) or back to earpiece / headset (`false`). */\nexport const setSpeaker = (on: boolean): void => native?.setSpeaker(on);\n\n/**\n * Play call audio through one of `snapshot.audioOutputs`. The choice\n * holds for the rest of the call, until that device disconnects or a new\n * headset / Bluetooth device connects (which takes over, as in the\n * phone's own dialer). Without a choice a connected headset wins, then\n * the earpiece for voice calls or the speaker for video.\n */\nexport function setAudioOutput(id: string): void {\n  if (native?.setAudioOutput) native.setAudioOutput(id);\n  else native?.setSpeaker(id === 'speaker'); // an older native build\n}\n\n/**\n * Socket forwarding for an open app: a `call:ring_ended` seen on the\n * socket. Idempotent with the push path — the core dedupes.\n */\nexport const onRingEnded = (callId: string, reason: string): void =>\n  native?.onRingEnded(callId, reason);\n\n/**\n * Socket forwarding: `call:finished`. Pass the payload's `reason`\n * (`finished` | `declined_all` | `no_answer` | `cancelled`) so an\n * unanswered caller sees \"Declined\"/\"No answer\", not \"Call ended\".\n * Idempotent with the `finished` push.\n */\nexport const onCallFinished = (callId: string, reason?: string): void =>\n  native?.onCallFinished(callId, reason ?? null);\n\n/**\n * Android 14+: whether the app may show the full-screen ring over the\n * lock screen. `true` on older Android and where the module is absent.\n */\nexport const canUseFullScreenIntent = (): boolean => native?.canUseFullScreenIntent() ?? true;\n\n/** Open the system screen where the user grants full-screen intents (falls back to notification settings). */\nexport const openFullScreenIntentSettings = (): void => native?.openFullScreenIntentSettings();\n\n// ── VoIP push (iOS) ───────────────────────────────────────────────────\n\n/**\n * iOS: the current PushKit VoIP token, registered natively at launch.\n * `null` until iOS issues one, and always on Android (FCM carries rings).\n */\nexport function getVoipToken(): VoipToken | null {\n  return native?.getVoipToken?.() ?? null;\n}\n\n/** iOS: fires whenever PushKit issues (or rotates) the VoIP token. No-op on Android. */\nexport function onVoipToken(cb: (token: VoipToken) => void): Unsubscribe {\n  if (!native || !native.getVoipToken) return () => undefined;\n  const sub = native.addListener('onVoipToken', cb);\n  return () => sub.remove();\n}\n\n// ── video ─────────────────────────────────────────────────────────────\n\nexport interface CallVideoViewProps extends ViewProps {\n  /** Remote participant's userId (LiveKit identity). Omit with local=true for self view. */\n  participantId?: string;\n  local?: boolean;\n  /** default: true for local front camera, false otherwise */\n  mirror?: boolean;\n  /** default 'cover' */\n  fit?: 'cover' | 'contain';\n}\n\ntype NativeVideoProps = CallVideoViewProps;\n\nlet nativeVideo: ComponentType<NativeVideoProps> | null | undefined;\n\n/** Resolved lazily (first render) and only when the native module exists. */\nfunction nativeVideoView(): ComponentType<NativeVideoProps> | null {\n  if (nativeVideo !== undefined) return nativeVideo;\n  nativeVideo = null;\n  if (native) {\n    try {\n      nativeVideo = requireNativeViewManager<NativeVideoProps>('PoolseCalls', 'PoolseCallVideo');\n    } catch {\n      nativeVideo = null; // an older native build without the view\n    }\n  }\n  return nativeVideo;\n}\n\n/**\n * A participant's camera (or, with `local`, your own), rendered natively\n * by the call core. Shows nothing (stays transparent) while that camera\n * is off — draw the avatar from the snapshot's `cameraOn` underneath.\n * Without the native module it renders an empty View.\n */\nexport function CallVideoView(props: CallVideoViewProps): ReactElement | null {\n  const Native = nativeVideoView();\n  if (!Native) {\n    const { participantId: _p, local: _l, mirror: _m, fit: _f, ...rest } = props;\n    return createElement(View, rest);\n  }\n  return createElement(Native, props);\n}\n"]}

package/ios/Core/CallCoreRuntime.swift

@@ -173,6 +173,7 @@ public final class CallCoreRuntime {
   public func setCamera(_ on: Bool) { post { [self] in media.setCamera(on) } }
   public func switchCamera() { post { [self] in media.switchCamera() } }
   public func setSpeaker(_ on: Bool) { post { [self] in media.setSpeaker(on) } }
+  public func setAudioOutput(_ id: String) { post { [self] in media.setAudioOutput(id) } }
 
   /// Re-emit the current state (the bridge's roster/route changed).
   public func reemit() { post { [self] in if state.phase != .idle { sink.emit(state: state) } } }

package/ios/Core/Ports.swift

@@ -71,6 +71,13 @@ public protocol MediaPort: AnyObject {
   func switchCamera()
   /// Loudspeaker (`true`) or back to the private route (`false`).
   func setSpeaker(_ on: Bool)
+  /// Play through one specific output — an id from `Snapshot.audioOutputs`.
+  func setAudioOutput(_ id: String)
+}
+
+public extension MediaPort {
+  /// Engines without device selection fall back to the speaker toggle.
+  func setAudioOutput(_ id: String) { setSpeaker(id == "speaker") }
 }
 
 // MARK: - Ring surface

package/ios/Core/SnapshotEncoding.swift

@@ -23,6 +23,24 @@ public struct SnapshotParticipant: Equatable {
   }
 }
 
+/// One place call audio can play, as a JS `Snapshot.audioOutputs[]` entry.
+public struct AudioOutput: Equatable {
+  /// Stable for the device's lifetime in this call; passed back to `setAudioOutput`.
+  public var id: String
+  /// `earpiece` | `speaker` | `bluetooth` | `headset`.
+  public var kind: String
+  /// What the device calls itself ("AirPods Pro"), or a plain default for built-ins.
+  public var name: String
+
+  public init(id: String, kind: String, name: String) {
+    self.id = id
+    self.kind = kind
+    self.name = name
+  }
+
+  public var dictionary: [String: Any] { ["id": id, "kind": kind, "name": name] }
+}
+
 public extension Phase {
   var wire: String {
     switch self {
@@ -50,6 +68,8 @@ public extension MachineState {
   func toSnapshot(conversationName: String? = nil,
                   participants: [SnapshotParticipant] = [],
                   audioRoute: String = "earpiece",
+                  audioOutputs: [AudioOutput] = [],
+                  audioOutputId: String? = nil,
                   mutedSelf: Bool = false,
                   cameraOn: Bool = false,
                   cameraFacing: String? = nil) -> [String: Any]? {
@@ -64,6 +84,8 @@ public extension MachineState {
       "phase": phase.wire,
       "participants": participants.map { $0.dictionary },
       "audioRoute": audioRoute,
+      "audioOutputs": audioOutputs.map { $0.dictionary },
+      "audioOutputId": audioOutputId.map { $0 as Any } ?? NSNull(),
       "mutedSelf": mutedSelf,
       "cameraOn": cameraOn,
     ]

package/ios/Module/PoolseCallsModule.swift

@@ -70,6 +70,7 @@ public class PoolseCallsModule: Module {
     Function("setCamera") { (on: Bool) in onCore { $0.setCamera(on) } }
     Function("switchCamera") { onCore { $0.switchCamera() } }
     Function("setSpeaker") { (on: Bool) in onCore { $0.setSpeaker(on) } }
+    Function("setAudioOutput") { (id: String) in onCore { $0.setAudioOutput(id) } }
 
     // Socket forwarding (open app): idempotent with the push path.
     Function("onRingEnded") { (callId: String, reason: String) in

package/ios/Platform/CallCore.swift

@@ -143,6 +143,8 @@ final class CallCore {
   private var cameraOn = false
   private var cameraFacing: String?
   private var audioRoute: String?
+  private var audioOutputs: [AudioOutput] = []
+  private var audioOutputId: String?
 
   /// ring_ended reasons seen per call — the CallKit end reason.
   private var ringEndReasons: [String: String] = [:]
@@ -270,6 +272,9 @@ final class CallCore {
     }
   }
 
+  /// Not optimistic: the adapter reports the route once iOS has moved it.
+  func setAudioOutput(_ id: String) { runtime.setAudioOutput(id) }
+
   /// A video slot for the native view. Main thread.
   func createVideoSurface() -> LiveKitVideoSurface { mediaPort.createVideoSurface() }
 
@@ -307,6 +312,8 @@ final class CallCore {
       conversationName: conversationName,
       participants: roster,
       audioRoute: audioRoute ?? (state.media == "video" ? "speaker" : "earpiece"),
+      audioOutputs: audioOutputs,
+      audioOutputId: audioOutputId,
       mutedSelf: mutedSelf,
       cameraOn: cameraOn,
       cameraFacing: cameraFacing
@@ -326,6 +333,8 @@ final class CallCore {
     cameraOn = false
     cameraFacing = nil
     audioRoute = nil
+    audioOutputs = []
+    audioOutputId = nil
   }
 
   /// CallKit follows the FINAL state of each dispatch.
@@ -422,6 +431,10 @@ final class CallCore {
     runtime.post { [weak self] in self?.audioRoute = r }
     runtime.reemit()
   }
+  fileprivate func outputs(_ list: [AudioOutput], selected: String?) {
+    runtime.post { [weak self] in self?.audioOutputs = list; self?.audioOutputId = selected }
+    runtime.reemit()
+  }
   fileprivate func localCamera(on: Bool, facing: String?) {
     runtime.post { [weak self] in self?.cameraOn = on; self?.cameraFacing = facing }
     runtime.reemit()
@@ -497,6 +510,7 @@ private final class EventsAdapter: MediaEvents {
   func onParticipants(_ participants: [SnapshotParticipant]) { core?.participants(participants) }
   func onAudioRoute(_ route: String) { core?.route(route) }
   func onLocalCamera(on: Bool, facing: String?) { core?.localCamera(on: on, facing: facing) }
+  func onAudioOutputs(_ outputs: [AudioOutput], selectedId: String?) { core?.outputs(outputs, selected: selectedId) }
 }
 
 /// Host-facing entry points.

package/ios/Platform/LiveKitMediaPort.swift

@@ -23,6 +23,8 @@ protocol MediaEvents: AnyObject {
   func onParticipants(_ participants: [SnapshotParticipant])
   /// `earpiece` | `speaker` | `bluetooth` | `headset`.
   func onAudioRoute(_ route: String)
+  /// Every output call audio can play through right now, and the one it does.
+  func onAudioOutputs(_ outputs: [AudioOutput], selectedId: String?)
   /// The local camera track is (not) published + enabled; facing `front` | `back`.
   func onLocalCamera(on: Bool, facing: String?)
 }
@@ -66,8 +68,19 @@ final class LiveKitMediaPort: NSObject, MediaPort {
   private var media = "audio"
   private var connectedRoom: ObjectIdentifier?
 
-  /// Speaker forced by the user; nil = the media-type default.
-  private var speakerWanted: Bool?
+  /// Where the user asked the audio to go, for the CURRENT call.
+  enum OutputChoice: Equatable {
+    case speaker
+    /// The best private route: Bluetooth, then wired, then the earpiece.
+    case privateRoute
+    /// The phone itself: earpiece (or wired headphones, which replace it).
+    case builtIn
+    /// One external input/output pair, by AVAudioSessionPortDescription uid.
+    case port(String)
+  }
+
+  /// The user's output choice; nil = automatic (see `resolvedChoice`).
+  private var outputWanted: OutputChoice?
   /// The user's choices for the CURRENT call; survive a rejoin.
   private var mutedWanted = false
   private var cameraWanted: Bool?
@@ -76,8 +89,6 @@ final class LiveKitMediaPort: NSObject, MediaPort {
   private let surfaces = NSHashTable<LiveKitVideoSurface>.weakObjects()
   private var audioPrepared = false
   private var audioActive = false
-  /// The room whose audio engine has been kicked (once per room).
-  private var audioKicked: ObjectIdentifier?
   /// Asks CallKit to (re)try activating the audio session — set by
   /// CallCore. Used when a room is live but activation never arrived.
   var requestAudioActivation: (() -> Void)?
@@ -121,7 +132,6 @@ final class LiveKitMediaPort: NSObject, MediaPort {
     audioActive = true
     if media != self.media && room == nil { self.media = media }
     reassertAudio(session)
-    kickAudioIfReady()
   }
 
   /// Connected with a live mic but CallKit never activated the session
@@ -147,48 +157,6 @@ final class LiveKitMediaPort: NSObject, MediaPort {
     }
   }
 
-  /// Once per call, the first moment the session is active AND the mic is
-  /// published (in whichever order they happen): make LiveKit's audio
-  /// engine rebuild around the live mic.
-  ///
-  /// On a call answered with the app closed, the process is brand new and
-  /// LiveKit's engine never started for a mic published right after
-  /// CallKit made audio available — no capture, no playback, though the
-  /// session was correct (video, which needs no audio engine, worked). A
-  /// user-side mute → unmute cured it, because toggling the mic makes the
-  /// engine re-evaluate and start. This does the same, automatically: an
-  /// availability cycle first, then a mic off/on. A deliberate mute is
-  /// left alone. The remote hears at most a sub-second blip at connect.
-  private func kickAudioIfReady() {
-    guard audioActive, let r = room, connectedRoom == ObjectIdentifier(r),
-          audioKicked != ObjectIdentifier(r), !mutedWanted else { return }
-    guard r.localParticipant.isMicrophoneEnabled() else { return }
-    audioKicked = ObjectIdentifier(r)
-    pcTrace("kick: cycling engine availability + mic")
-    do {
-      try AudioManager.shared.setEngineAvailability(.none)
-      try AudioManager.shared.setEngineAvailability(.default)
-    } catch {
-      NSLog("[PoolseCalls] engine availability cycle failed: %@", "\(error)")
-    }
-    Task { [weak self] in
-      try? await Task.sleep(nanoseconds: 250_000_000)
-      let still = await MainActor.run { () -> Bool in
-        guard let self = self else { return false }
-        return self.room === r && self.audioActive && !self.mutedWanted
-      }
-      guard still else { return }
-      do {
-        try await r.localParticipant.setMicrophone(enabled: false)
-        try await r.localParticipant.setMicrophone(enabled: true)
-      } catch {
-        NSLog("[PoolseCalls] mic cycle failed: %@", "\(error)")
-      }
-      pcTrace("kick done enabled=\(r.localParticipant.isMicrophoneEnabled()) \(pcSessionDescription())")
-      await MainActor.run { self?.reassertAudio() }
-    }
-  }
-
   /// Put the call's audio back the way the call needs it: play-and-record
   /// in the voice/video chat mode, LiveKit's engine available, the chosen
   /// route. Idempotent — only touches what differs — so it is safe to run
@@ -199,7 +167,7 @@ final class LiveKitMediaPort: NSObject, MediaPort {
   func reassertAudio(_ session: AVAudioSession = .sharedInstance()) {
     guard audioActive else { return }
     pcTrace("reassertAudio before: \(pcSessionDescription(session))")
-    let mode: AVAudioSession.Mode = media == "video" && speakerWanted != false ? .videoChat : .voiceChat
+    let mode: AVAudioSession.Mode = media == "video" && resolvedChoice(session) == .speaker ? .videoChat : .voiceChat
     if session.category != .playAndRecord || session.mode != mode {
       do {
         try session.setCategory(.playAndRecord, mode: mode,
@@ -289,7 +257,6 @@ final class LiveKitMediaPort: NSObject, MediaPort {
       // then make sure the engine is actually carrying the mic.
       await MainActor.run {
         self.reassertAudio()
-        self.kickAudioIfReady()
         self.ensureAudioActivated(r, attempt: 0)
       }
       let camera = await MainActor.run { self.cameraWanted ?? wantsVideo }
@@ -305,7 +272,7 @@ final class LiveKitMediaPort: NSObject, MediaPort {
   private func markConnected(_ r: Room) {
     guard room === r, connectedRoom != ObjectIdentifier(r) else { return }
     connectedRoom = ObjectIdentifier(r)
-    if speakerWanted != nil { applyRoute() }
+    if outputWanted != nil { applyRoute() }
     events?.onConnected()
     if !r.remoteParticipants.isEmpty { events?.onRemoteJoined() }
     emit(r)
@@ -339,7 +306,7 @@ final class LiveKitMediaPort: NSObject, MediaPort {
   private func resetWanted() {
     mutedWanted = false
     cameraWanted = nil
-    speakerWanted = nil
+    outputWanted = nil
   }
 
   private func detach() {
@@ -387,25 +354,72 @@ final class LiveKitMediaPort: NSObject, MediaPort {
   }
 
   func setSpeaker(_ on: Bool) {
-    speakerWanted = on
+    outputWanted = on ? .speaker : .privateRoute
+    applyRoute()
+  }
+
+  /// An id from the snapshot's `audioOutputs`: `speaker`, `earpiece`,
+  /// `wired`, or `port:<uid>`. An id that is no longer connected is ignored.
+  func setAudioOutput(_ id: String) {
+    switch id {
+    case "speaker": outputWanted = .speaker
+    case "earpiece", "wired": outputWanted = .builtIn
+    default:
+      guard id.hasPrefix("port:") else { return }
+      let uid = String(id.dropFirst("port:".count))
+      // An output with no matching input (an A2DP-only speaker) cannot be
+      // chosen through the session; the system's own route wins there.
+      outputWanted = selectablePort(uid) != nil ? .port(uid) : .privateRoute
+    }
     applyRoute()
   }
 
   // MARK: - audio routing
 
-  /// A voice call is held to the ear (earpiece, or a headset/Bluetooth
-  /// route first); video defaults to the loudspeaker.
+  private static let externalInputs: Set<AVAudioSession.Port> =
+    [.bluetoothHFP, .bluetoothLE, .carAudio, .usbAudio, .headsetMic]
+  private static let externalOutputs: Set<AVAudioSession.Port> =
+    [.bluetoothHFP, .bluetoothA2DP, .bluetoothLE, .carAudio, .usbAudio, .headphones, .airPlay, .lineOut, .HDMI]
+
+  private func selectablePort(_ uid: String, _ s: AVAudioSession = .sharedInstance()) -> AVAudioSessionPortDescription? {
+    s.availableInputs?.first { $0.uid == uid && Self.externalInputs.contains($0.portType) }
+  }
+
+  /// A headset, Bluetooth device or car is connected — something the
+  /// user put on or plugged in, which should carry the call by default.
+  private func externalConnected(_ s: AVAudioSession) -> Bool {
+    (s.availableInputs ?? []).contains { Self.externalInputs.contains($0.portType) && $0.portType != .usbAudio }
+      || s.currentRoute.outputs.contains { Self.externalOutputs.contains($0.portType) }
+  }
+
+  /// What the call should do now. Automatic: a voice call is held to the
+  /// ear and a video call uses the loudspeaker — unless a headset or
+  /// Bluetooth device is connected, which wins either way (FaceTime does
+  /// the same; forcing the speaker over AirPods was a bug).
+  private func resolvedChoice(_ s: AVAudioSession = .sharedInstance()) -> OutputChoice {
+    if let wanted = outputWanted { return wanted }
+    return media == "video" && !externalConnected(s) ? .speaker : .privateRoute
+  }
+
   private func applyRoute() {
     guard audioActive else { return }
     let s = AVAudioSession.sharedInstance()
-    let want = speakerWanted ?? (media == "video")
+    if case .port(let uid) = outputWanted, selectablePort(uid, s) == nil { outputWanted = nil }
+    let choice = resolvedChoice(s)
     do {
-      if want {
+      switch choice {
+      case .speaker:
         try s.overrideOutputAudioPort(.speaker)
-      } else {
-        // .videoChat forces the speaker; the private route needs .voiceChat.
-        if s.mode == .videoChat { try s.setMode(.voiceChat) }
-        try s.overrideOutputAudioPort(.none)
+      case .privateRoute:
+        try leaveSpeaker(s)
+        if s.preferredInput != nil { try s.setPreferredInput(nil) }
+      case .builtIn:
+        try leaveSpeaker(s)
+        let mic = s.availableInputs?.first { $0.portType == .builtInMic }
+        if let mic = mic, s.preferredInput?.uid != mic.uid { try s.setPreferredInput(mic) }
+      case .port(let uid):
+        try leaveSpeaker(s)
+        if let port = selectablePort(uid, s), s.preferredInput?.uid != uid { try s.setPreferredInput(port) }
       }
     } catch {
       NSLog("[PoolseCalls] audio route failed: %@", "\(error)")
@@ -413,21 +427,77 @@ final class LiveKitMediaPort: NSObject, MediaPort {
     reportRoute()
   }
 
-  private func currentRoute() -> String {
-    let outputs = AVAudioSession.sharedInstance().currentRoute.outputs
-    guard let port = outputs.first?.portType else { return media == "video" ? "speaker" : "earpiece" }
+  /// .videoChat forces the speaker; every private route needs .voiceChat.
+  private func leaveSpeaker(_ s: AVAudioSession) throws {
+    if s.mode == .videoChat { try s.setMode(.voiceChat) }
+    try s.overrideOutputAudioPort(.none)
+  }
+
+  private func kind(of port: AVAudioSession.Port) -> String {
     switch port {
     case .builtInSpeaker: return "speaker"
     case .builtInReceiver: return "earpiece"
     case .bluetoothHFP, .bluetoothA2DP, .bluetoothLE, .carAudio, .airPlay: return "bluetooth"
-    case .headphones, .usbAudio, .lineOut, .HDMI: return "headset"
     default: return "headset"
     }
   }
 
+  private func currentRoute() -> String {
+    guard let port = AVAudioSession.sharedInstance().currentRoute.outputs.first?.portType else {
+      return media == "video" ? "speaker" : "earpiece"
+    }
+    return kind(of: port)
+  }
+
+  /// Every output the user can pick, and the one playing now.
+  ///
+  /// iOS lists inputs, not outputs: a headset or Bluetooth device is
+  /// selectable through its microphone (its input and output share the
+  /// uid), while the earpiece and speaker are always there on a phone.
+  /// Wired headphones replace the earpiece rather than sitting beside it.
+  private func outputs() -> ([AudioOutput], String?) {
+    let s = AVAudioSession.sharedInstance()
+    let inputs = s.availableInputs ?? []
+    let current = s.currentRoute.outputs.first
+    var list: [AudioOutput] = []
+
+    let wiredOut = s.currentRoute.outputs.first { $0.portType == .headphones }
+    if inputs.contains(where: { $0.portType == .headsetMic }) || wiredOut != nil {
+      list.append(AudioOutput(id: "wired", kind: "headset", name: "Headphones"))
+    } else if UIDevice.current.userInterfaceIdiom == .phone {
+      list.append(AudioOutput(id: "earpiece", kind: "earpiece", name: UIDevice.current.model))
+    }
+    list.append(AudioOutput(id: "speaker", kind: "speaker", name: "Speaker"))
+    for p in inputs where Self.externalInputs.contains(p.portType) && p.portType != .headsetMic {
+      list.append(AudioOutput(id: "port:\(p.uid)", kind: p.portType == .usbAudio ? "headset" : "bluetooth", name: p.portName))
+    }
+    // Playing through something with no microphone (an A2DP speaker,
+    // AirPlay): show it so the selection is truthful, even though only
+    // the system picker can choose it.
+    if let c = current, Self.externalOutputs.contains(c.portType), c.portType != .headphones,
+       !list.contains(where: { $0.id == "port:\(c.uid)" || $0.name == c.portName }) {
+      list.append(AudioOutput(id: "port:\(c.uid)", kind: kind(of: c.portType), name: c.portName))
+    }
+
+    let selected: String? = current.map { c in
+      switch c.portType {
+      case .builtInSpeaker: return "speaker"
+      case .builtInReceiver: return "earpiece"
+      case .headphones: return "wired"
+      default:
+        return list.first { $0.id == "port:\(c.uid)" }?.id
+          ?? list.first { $0.name == c.portName }?.id
+          ?? "port:\(c.uid)"
+      }
+    }
+    return (list, selected)
+  }
+
   private func reportRoute() {
     guard joinedCallId != nil || audioActive else { return }
     events?.onAudioRoute(currentRoute())
+    let (list, selected) = outputs()
+    events?.onAudioOutputs(list, selectedId: selected)
   }
 
   /// An interruption (another app's audio, Siri) ended: the session may
@@ -455,14 +525,27 @@ final class LiveKitMediaPort: NSObject, MediaPort {
         self.reassertAudio()
         return
       }
-      // A user's speaker choice survives route changes, except that a
-      // newly connected headset/Bluetooth device always wins.
-      let route = self.currentRoute()
-      if let wanted = self.speakerWanted, route == "speaker" || route == "earpiece", (route == "speaker") != wanted {
+      switch reason {
+      case .newDeviceAvailable:
+        // Putting on a headset or AirPods mid-call moves the call to it,
+        // whatever was picked before — as the Phone app does.
+        self.outputWanted = nil
         self.applyRoute()
-        return
+      case .oldDeviceUnavailable:
+        // A device went away. If it was the chosen one, applyRoute drops
+        // the choice and falls back to automatic — speaker for video,
+        // earpiece for voice; any other choice stands.
+        self.applyRoute()
+      default:
+        // The override is cleared by any route change: put the speaker
+        // back (or take it away) if that is not what the call wants.
+        let onSpeaker = self.currentRoute() == "speaker"
+        if (self.resolvedChoice() == .speaker) != onSpeaker && reason != .override {
+          self.applyRoute()
+        } else {
+          self.reportRoute()
+        }
       }
-      self.reportRoute()
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poolse/react-native-calls",
-  "version": "0.4.5",
+  "version": "0.5.0",
   "description": "Native call core for poolse — Kotlin/Swift calling engine with a thin React Native bridge. Ring, answer and carry audio with the app killed and the phone locked.",
   "license": "MIT",
   "type": "module",

package/src/index.ts

@@ -41,7 +41,17 @@ export interface Snapshot {
     /** True only with a published, subscribed, unmuted camera track (show video, not avatar). */
     cameraOn: boolean;
   }>;
-  audioRoute: 'earpiece' | 'speaker' | 'bluetooth' | 'headset';
+  /** The kind of output playing now — the short answer to "where is the audio". */
+  audioRoute: AudioOutputKind;
+  /**
+   * Every output the call can play through right now: always the phone
+   * (earpiece, or wired headphones in its place) and the speaker, plus
+   * each connected Bluetooth / USB device by its own name. Empty until
+   * the call's audio is up. Pass an `id` to `setAudioOutput`.
+   */
+  audioOutputs: AudioOutput[];
+  /** The `audioOutputs` entry playing now; null before audio is up. */
+  audioOutputId: string | null;
   mutedSelf: boolean;
   /** True only while the local camera track is actually published and enabled. */
   cameraOn: boolean;
@@ -49,6 +59,21 @@ export interface Snapshot {
   cameraFacing?: 'front' | 'back';
 }
 
+export type AudioOutputKind = 'earpiece' | 'speaker' | 'bluetooth' | 'headset';
+
+/** One place call audio can play. */
+export interface AudioOutput {
+  /** Opaque; stable while the device stays connected. */
+  id: string;
+  kind: AudioOutputKind;
+  /**
+   * The device's own name for Bluetooth/USB ("AirPods Pro"); a plain
+   * English default for built-ins ("iPhone"/"Phone", "Speaker",
+   * "Headphones") — relabel those by `kind` to localise.
+   */
+  name: string;
+}
+
 export interface ConfigureOptions {
   /** Drawable resource NAME for the call notification's small icon. */
   smallIcon?: string;
@@ -89,6 +114,7 @@ interface PoolseCallsNative {
   setCamera(on: boolean): void;
   switchCamera(): void;
   setSpeaker(on: boolean): void;
+  setAudioOutput?(id: string): void;
   onRingEnded(callId: string, reason: string): void;
   onCallFinished(callId: string, reason: string | null): void;
   canUseFullScreenIntent(): boolean;
@@ -143,6 +169,18 @@ export const switchCamera = (): void => native?.switchCamera();
 /** Route call audio to the loudspeaker (`true`) or back to earpiece / headset (`false`). */
 export const setSpeaker = (on: boolean): void => native?.setSpeaker(on);
 
+/**
+ * Play call audio through one of `snapshot.audioOutputs`. The choice
+ * holds for the rest of the call, until that device disconnects or a new
+ * headset / Bluetooth device connects (which takes over, as in the
+ * phone's own dialer). Without a choice a connected headset wins, then
+ * the earpiece for voice calls or the speaker for video.
+ */
+export function setAudioOutput(id: string): void {
+  if (native?.setAudioOutput) native.setAudioOutput(id);
+  else native?.setSpeaker(id === 'speaker'); // an older native build
+}
+
 /**
  * Socket forwarding for an open app: a `call:ring_ended` seen on the
  * socket. Idempotent with the push path — the core dedupes.