@mentra/bluetooth-sdk 3.2.0-dev.217 → 3.2.0-dev.222

package/README.md

@@ -29,6 +29,15 @@ to its existing retention limits. Native diagnostics are also kept in the native
 console. Forwarding covers SDK-owned diagnostics while the JS runtime is active,
 not arbitrary OS or third-party native logs or logs from before subscription.
 
+On Android, forwarding to JavaScript is capped at 100 messages per second. Each
+forwarded message holds a JNI global reference until the JavaScript thread drains
+it, so an unbounded log source can exhaust the process-wide reference table and
+abort the app rather than merely slow it down. Messages above the cap are withheld
+from the JavaScript stream only — they are still written to the native console —
+and the next forwarded message is preceded by a notice saying how many were
+withheld. Per-frame microphone payload events are not traced at all; audio faults
+are still reported through the `mic_health` event.
+
 Rebuild the native app after updating the SDK to pick up both platforms' logging
 changes. Adding this JS package alone cannot reroute logs in an older binary.
 

package/android/src/main/java/com/mentra/bluetoothsdk/BluetoothSdkModule.kt

@@ -133,6 +133,7 @@ private inline fun <
 class BluetoothSdkModule : Module() {
     private var sdk: MentraBluetoothSdk? = null
     private var deviceManager: DeviceManager? = null
+    private val logForwarding = LogForwardingBudget()
     private val sdkListener =
             object : MentraBluetoothSdkListener {
                 override fun onGlassesChanged(glasses: GlassesRuntimeState) {
@@ -295,6 +296,16 @@ class BluetoothSdkModule : Module() {
                 }
 
                 override fun onLog(message: String) {
+                    // Each event pins a JNI global reference until JavaScript drains it. The
+                    // log stream is the one source whose rate is unbounded, so it is budgeted.
+                    val withheld = logForwarding.admit() ?: return
+                    if (withheld > 0) {
+                        val notice =
+                                "[W/BluetoothSdkModule] withheld $withheld native log line(s) from " +
+                                        "JavaScript to stay under ${logForwarding.maxPerWindow}/s; " +
+                                        "logcat has them all"
+                        sendEvent("log", mapOf("message" to notice))
+                    }
                     sendEvent("log", mapOf("message" to message))
                 }
 
@@ -824,6 +835,10 @@ class BluetoothSdkModule : Module() {
             )
         }
 
+        SdkAsyncFunction("setMicSourcePin") { source: String? ->
+            sdk?.setMicSourcePin(source)
+        }
+
         // Runs on Dispatchers.IO, not the shared Expo AsyncFunctionQueue: restart()
         // does a synchronous JNI model reload that would otherwise block every other
         // native call in the app until it completes.
@@ -846,8 +861,14 @@ class BluetoothSdkModule : Module() {
         // close blocks until the backlog drains — either would otherwise stall
         // every other native call queued behind them.
 
-        AsyncFunction("pcmStreamOpen") { streamId: String, sampleRate: Int, channels: Int, volume: Double ->
-            PcmStreamManager.open(streamId, sampleRate, channels, volume.toFloat())
+        AsyncFunction("pcmStreamOpen") {
+            streamId: String,
+            sampleRate: Int,
+            channels: Int,
+            volume: Double,
+            jitterMs: Int?,
+            ->
+            PcmStreamManager.open(streamId, sampleRate, channels, volume.toFloat(), jitterMs)
         }
 
         AsyncFunction("pcmStreamWrite") Coroutine { streamId: String, base64: String ->

package/android/src/main/java/com/mentra/bluetoothsdk/Bridge.kt

@@ -30,18 +30,6 @@ public class Bridge private constructor() {
         private const val MIC_CHANNELS = 1
         private const val LC3_FRAME_DURATION_MS = 10
         private const val DEFAULT_LC3_FRAME_SIZE_BYTES = 60
-        private val AUDIO_TRACE_METADATA_KEYS =
-                listOf(
-                        "sampleRate",
-                        "bitsPerSample",
-                        "channels",
-                        "encoding",
-                        "frameDurationMs",
-                        "frameSizeBytes",
-                        "bitrate",
-                        "packetizedFromGlasses",
-                        "voiceActivityDetectionEnabled",
-                )
 
         @Volatile private var instance: Bridge? = null
 
@@ -206,6 +194,10 @@ public class Bridge private constructor() {
             body["channels"] = MIC_CHANNELS
             body["encoding"] = "pcm_s16le"
             body["voiceActivityDetectionEnabled"] = voiceActivityDetectionEnabled
+            // Stamped per frame so a consumer that pinned the source can verify it rather than
+            // assume it. Read from the store, not from a captured value: the whole point is to
+            // report the microphone that is selected right now.
+            body["source"] = DeviceStore.store.get("bluetooth", "currentMic") as? String ?: ""
             return body
         }
 
@@ -943,43 +935,29 @@ public class Bridge private constructor() {
             }
         }
 
+        /**
+         * Returns null for events that must not be traced.
+         *
+         * "log" is excluded so tracing never recurses back through NativeLog. Audio payload
+         * events are excluded because they arrive at frame rate: tracing them turned every
+         * microphone frame into a second bridge event, and each of those pins a JNI global
+         * reference until JavaScript drains it. A JavaScript thread busy with call audio
+         * cannot keep up, so the references accumulated until the process-wide table
+         * overflowed and the runtime aborted. Audio faults (sequence gaps, decode failures)
+         * are still reported through "mic_health", and healthy frames need no trace.
+         */
         private fun tracePayloadForTypedMessage(
                 type: String,
                 body: Map<String, Any>
         ): Map<String, Any>? =
                 when {
                     type == "log" -> null
-                    isAudioPayloadEvent(type) -> audioTracePayload(type, body)
+                    isAudioPayloadEvent(type) -> null
                     else -> body
                 }
 
         private fun isAudioPayloadEvent(type: String): Boolean =
                 type == "mic_pcm" || type == "mic_lc3"
-
-        private fun audioTracePayload(type: String, body: Map<String, Any>): Map<String, Any> {
-            val payload = HashMap<String, Any>()
-            payload["type"] = type
-            payload["timestamp"] = System.currentTimeMillis()
-            payload["payloadOmitted"] = true
-            payload["payloadOmittedReason"] = "audio"
-
-            val audioBytes =
-                    when (type) {
-                        "mic_pcm" -> (body["pcm"] as? ByteArray)?.size
-                        "mic_lc3" -> (body["lc3"] as? ByteArray)?.size
-                        else -> null
-                    }
-            audioBytes?.let { payload["audioBytes"] = it }
-
-            AUDIO_TRACE_METADATA_KEYS.forEach { key ->
-                val value = body[key]
-                if (value != null) {
-                    payload[key] = value
-                }
-            }
-
-            return payload
-        }
     }
 
     init {

package/android/src/main/java/com/mentra/bluetoothsdk/DeviceManager.kt

@@ -28,6 +28,7 @@ import com.mentra.bluetoothsdk.sgcs.Simulated
 import com.mentra.bluetoothsdk.utils.ControllerTypes
 import com.mentra.bluetoothsdk.utils.DeviceTypes
 import com.mentra.bluetoothsdk.utils.MicMap
+import com.mentra.bluetoothsdk.utils.MicSourcePin
 import com.mentra.bluetoothsdk.utils.MicTypes
 import com.mentra.bluetoothsdk.utils.PhoneAudioMonitor
 import com.mentra.lc3Lib.Lc3Cpp
@@ -850,6 +851,9 @@ class DeviceManager {
             }
         }
         if (pcmData != null && pcmData.isNotEmpty()) {
+            // #region agent log — per-second RX window: LC3 bytes in, fingerprint, decoded PCM level (H-E)
+            micDbgLc3Window(rawLC3Data, sequenceNumber, pcmData)
+            // #endregion
             // Re-encode to canonical LC3 via handlePcm (outside lock to avoid deadlock)
             recordMicPcmProduced()
             handlePcm(pcmData)
@@ -859,6 +863,72 @@ class DeviceManager {
         }
     }
 
+    // #region agent log — glasses LC3 RX diagnostics (debug session 828181)
+    private var micDbgWindowStart = 0L
+    private var micDbgPkts = 0
+    private var micDbgLc3Bytes = 0L
+    private var micDbgPcmBytes = 0L
+    private var micDbgSumAbs = 0L
+    private var micDbgSamples = 0L
+    private var micDbgPeak = 0
+    private var micDbgDcSum = 0L
+    private var micDbgDistinctFrames = HashSet<Int>()
+    private var micDbgFirstSeq = -1
+    private var micDbgLastSeq = -1
+    private var micDbgSeqGaps = 0
+
+    private fun micDbgLc3Window(lc3: ByteArray, seq: Int?, pcm: ByteArray) {
+        val now = System.currentTimeMillis()
+        if (micDbgWindowStart == 0L) micDbgWindowStart = now
+        micDbgPkts++
+        micDbgLc3Bytes += lc3.size
+        micDbgPcmBytes += pcm.size
+        var i = 0
+        while (i + 1 < pcm.size) {
+            val v = ((pcm[i + 1].toInt() shl 8) or (pcm[i].toInt() and 0xff)).toShort().toInt()
+            val a = if (v < 0) -v else v
+            micDbgSumAbs += a
+            micDbgDcSum += v
+            if (a > micDbgPeak) micDbgPeak = a
+            micDbgSamples++
+            i += 2
+        }
+        var off = 0
+        while (off + 40 <= lc3.size) {
+            var h = 17
+            for (k in off until off + 40) h = h * 31 + lc3[k]
+            micDbgDistinctFrames.add(h)
+            off += 40
+        }
+        if (seq != null) {
+            if (micDbgFirstSeq < 0) micDbgFirstSeq = seq
+            if (micDbgLastSeq >= 0 && ((micDbgLastSeq + 1) and 0xff) != seq) micDbgSeqGaps++
+            micDbgLastSeq = seq
+        }
+        if (now - micDbgWindowStart >= 1000) {
+            val meanAbs = if (micDbgSamples > 0) micDbgSumAbs / micDbgSamples else 0
+            val dc = if (micDbgSamples > 0) micDbgDcSum / micDbgSamples else 0
+            val head = lc3.take(8).joinToString("") { String.format("%02x", it.toInt() and 0xff) }
+            Bridge.log(
+                "MICDBG-RX pkts=$micDbgPkts lc3B=$micDbgLc3Bytes pcmB=$micDbgPcmBytes samples=$micDbgSamples " +
+                    "meanAbs=$meanAbs peak=$micDbgPeak dc=$dc distinctLc3Frames=${micDbgDistinctFrames.size} " +
+                    "seq=$micDbgFirstSeq..$micDbgLastSeq gaps=$micDbgSeqGaps frameSizeArg=40 lastLen=${lc3.size} head=$head"
+            )
+            micDbgWindowStart = now
+            micDbgPkts = 0
+            micDbgLc3Bytes = 0
+            micDbgPcmBytes = 0
+            micDbgSumAbs = 0
+            micDbgSamples = 0
+            micDbgPeak = 0
+            micDbgDcSum = 0
+            micDbgDistinctFrames = HashSet()
+            micDbgFirstSeq = -1
+            micDbgSeqGaps = 0
+        }
+    }
+    // #endregion
+
     fun handlePcm(pcmData: ByteArray) {
         // Audio always flows. The previous phone-side Silero VAD gate was a
         // bandwidth-saver that ate transcripts when the mic delivered frames
@@ -909,11 +979,13 @@ class DeviceManager {
 
         // allow the sgc to make changes to the micRanking:
         micRanking = sgc?.sortMicRanking(micRanking) ?: micRanking
-        Bridge.log("MAN: updateMicState() micRanking: $micRanking")
+        val pin = micSourcePin
+        val ranking: List<String> = MicSourcePin.selectionOrder(micRanking, pin)
+        Bridge.log("MAN: updateMicState() micRanking: $micRanking pin: $pin")
 
         if (micEnabled) {
 
-            for (micMode in micRanking) {
+            for (micMode in ranking) {
                 if (micMode == MicTypes.PHONE_INTERNAL ||
                     micMode == MicTypes.BLUETOOTH_CLASSIC ||
                     micMode == MicTypes.BLUETOOTH
@@ -961,9 +1033,55 @@ class DeviceManager {
 
         if (micUsed == "" && micEnabled) {
             Bridge.log("MAN: No available mic found!")
+            if (pin == null) return
+            // A pin taken while another microphone was already recording must still close it:
+            // leaving it open would keep feeding PCM that the pinned consumer will reject, with
+            // the phone's indicator lit for audio nobody uses.
+            stopMicsExcept(micUsed)
+            reportPinnedSourceUnavailable(pin)
             return
         }
 
+        stopMicsExcept(micUsed)
+    }
+
+    /**
+     * Call-scoped microphone source lock, or null for the normal ranking.
+     *
+     * Only [MicTypes.GLASSES_CUSTOM] is supported today: it exists so an ACS call can promise that
+     * the wearer's own microphone — and nothing else — is what reaches the far end.
+     */
+    @Volatile private var micSourcePin: String? = null
+
+    /**
+     * Restrict microphone selection to one source for the duration of a call, or release it.
+     *
+     * Releasing re-runs selection so every other consumer (cloud LC3, miniapp `audio_chunk`,
+     * on-device STT) gets the source its own preference asks for back. A `preferred_mic` change
+     * made while the pin is held is stored but not applied until this releases.
+     */
+    fun setMicSourcePin(source: String?) {
+        val normalized = MicSourcePin.normalize(source)
+        if (micSourcePin == normalized) return
+        micSourcePin = normalized
+        Bridge.log("MAN: setMicSourcePin($normalized)")
+        updateMicState()
+    }
+
+    /** The microphone the SDK is currently recording from, for consumers that must verify it. */
+    fun activeMicSource(): String = currentMic
+
+    /**
+     * Report a pinned source that cannot be opened. Emitted rather than silently fixed, because the
+     * fix — opening a different microphone — is the thing the pin exists to forbid.
+     */
+    private fun reportPinnedSourceUnavailable(pin: String) {
+        Bridge.log("MAN: pinned mic source '$pin' is unavailable; no fallback will be started")
+        val health = synchronized(micHealthLock) { micHealthSnapshotLocked() }
+        Bridge.sendMicHealth(health, "pinned-source-unavailable")
+    }
+
+    private fun stopMicsExcept(micUsed: String) {
         // go through and disable all mics after the first used one:
         val allMics = micRanking
         // add any missing mics to the list:

package/android/src/main/java/com/mentra/bluetoothsdk/GeneratedReleaseMetadata.kt

@@ -3,9 +3,9 @@ package com.mentra.bluetoothsdk
 /** Generated by release CI. Do not edit in a release checkout. */
 internal object GeneratedReleaseMetadata {
     const val FAMILY_BASE_VERSION: String = "3.2.0"
-    const val RELEASE_IDENTITY: String = "3.2.0-dev.217"
-    const val RELEASE_SET_ID: String = "mentra-3.2.0-dev.217"
-    const val SOURCE_COMMIT: String = "acd4336bcf67c5e2c7ddfa17ea1a2600dc7fb1d9"
-    const val OTA_MANIFEST_URL: String = "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.217.json"
-    const val OTA_MANIFEST_SHA256: String = "4ec6bf57ab08ef2749a58232737dface3b0ddb0d8269b61e134b7cb5986efa4a"
+    const val RELEASE_IDENTITY: String = "3.2.0-dev.222"
+    const val RELEASE_SET_ID: String = "mentra-3.2.0-dev.222"
+    const val SOURCE_COMMIT: String = "7865d7f192a2d9a732269857bb877a3a8a6bf4b8"
+    const val OTA_MANIFEST_URL: String = "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.222.json"
+    const val OTA_MANIFEST_SHA256: String = "8c33e8beb5ba61eb0821d89b58d81fe2bbf05641d0a99b2e1972926863cc6ab7"
 }

package/android/src/main/java/com/mentra/bluetoothsdk/LogForwardingBudget.kt

@@ -0,0 +1,50 @@
+package com.mentra.bluetoothsdk
+
+import android.os.SystemClock
+
+/**
+ * Bounds how many native log lines per second the module hands to the JavaScript runtime.
+ *
+ * Every event the module emits pins a JNI global reference until the JavaScript thread
+ * drains it, and the process-wide table holds about 51,200 references. Native code can log
+ * faster than a busy JavaScript thread drains, so an unbounded log stream aborts the process
+ * instead of merely lagging. Lines over the budget are withheld from JavaScript only; the
+ * native console still has every one of them. The first line forwarded after a shortfall
+ * reports how many were withheld, so the gap is visible in the JavaScript stream.
+ */
+internal class LogForwardingBudget(
+    val maxPerWindow: Int = DEFAULT_MAX_PER_SECOND,
+    private val windowMs: Long = 1_000L,
+    private val clock: () -> Long = SystemClock::elapsedRealtime,
+) {
+    private var windowEndsAtMs = Long.MIN_VALUE
+    private var forwardedInWindow = 0
+    private var withheld = 0
+
+    /**
+     * Returns null when the current line must be withheld, otherwise the number of lines
+     * withheld since the previous forwarded one (zero in steady state).
+     */
+    @Synchronized
+    fun admit(): Int? {
+        val now = clock()
+        if (now >= windowEndsAtMs) {
+            windowEndsAtMs = now + windowMs
+            forwardedInWindow = 0
+        }
+        if (forwardedInWindow >= maxPerWindow) {
+            withheld++
+            return null
+        }
+        forwardedInWindow++
+        return withheld.also { withheld = 0 }
+    }
+
+    companion object {
+        /**
+         * Far above the SDK's steady-state diagnostic rate, and low enough that a
+         * JavaScript thread has to stay stalled for minutes before the table could fill.
+         */
+        const val DEFAULT_MAX_PER_SECOND = 100
+    }
+}

package/android/src/main/java/com/mentra/bluetoothsdk/MentraBluetoothSdk.kt

@@ -806,6 +806,18 @@ class MentraBluetoothSdk private constructor(
         DeviceStore.apply(ObservableStore.BLUETOOTH_CATEGORY, "preferred_mic", preferredMic.value)
     }
 
+    /**
+     * Lock microphone selection to one source until it is released with `null`.
+     *
+     * Distinct from [setPreferredMic]: a preference is a ranking the SDK may fall through, while a
+     * pin forbids the fallback. It exists for consumers that told a remote party which microphone
+     * they are hearing — an ACS call — where quietly substituting the phone microphone is worse
+     * than no audio at all. Only `"glasses"` is supported.
+     */
+    fun setMicSourcePin(source: String?) {
+        deviceManager.setMicSourcePin(source)
+    }
+
     fun setOwnAppAudioPlaying(playing: Boolean) {
         PhoneAudioMonitor.getInstance(appContext).setOwnAppAudioPlaying(playing)
     }

package/android/src/main/java/com/mentra/bluetoothsdk/audio/AudioModels.kt

@@ -14,6 +14,15 @@ data class MicPcmEvent(
     val channels: Int,
     val encoding: String,
     val voiceActivityDetectionEnabled: Boolean,
+    /**
+     * Which microphone produced this buffer, as [MicTypes]: `"glasses"`, `"phone"`, `"bluetooth"`.
+     *
+     * Carried per frame rather than inferred, because the SDK can move the source mid-stream when
+     * one becomes unavailable. A consumer that promised the far end a specific microphone — an ACS
+     * call, for instance — has no other way to tell that the audio it is forwarding is still the
+     * one it advertised. Empty when the SDK has not selected a microphone.
+     */
+    val source: String,
 ) {
     constructor(values: Map<String, Any>) : this(
         pcm = values["pcm"] as? ByteArray ?: ByteArray(0),
@@ -24,6 +33,7 @@ data class MicPcmEvent(
         voiceActivityDetectionEnabled =
             boolValue(values, "voiceActivityDetectionEnabled")
                 ?: BluetoothSdkDefaults.VOICE_ACTIVITY_DETECTION_ENABLED,
+        source = stringValue(values, "source") ?: "",
     )
 
     fun toMap(): Map<String, Any> =
@@ -35,6 +45,7 @@ data class MicPcmEvent(
             "channels" to channels,
             "encoding" to encoding,
             "voiceActivityDetectionEnabled" to voiceActivityDetectionEnabled,
+            "source" to source,
         )
 
     companion object {

package/android/src/main/java/com/mentra/bluetoothsdk/streaming/StreamModels.kt

@@ -63,6 +63,34 @@ data class StreamAudioConfig @JvmOverloads constructor(
     }
 }
 
+/** ICE overrides for a WHIP stream. Ignored by the RTMP and SRT paths. */
+data class StreamIceConfig @JvmOverloads constructor(
+    /**
+     * STUN server the glasses use while gathering candidates.
+     *
+     * Null and empty are different answers, and both have to survive the BLE round trip. Null
+     * leaves the glasses on their default Cloudflare STUN server; an empty string is SoftAP
+     * calling's explicit request for host-only gathering, because the phone's WHIP server sits on
+     * the glasses' own hotspot where a reflexive candidate is meaningless and unreachable.
+     */
+    val stun: String? = null,
+) {
+    fun toMap(): Map<String, Any> =
+        buildMap {
+            // Not filtered on blankness, unlike the other optional string fields here: "" is the
+            // host-only signal, so dropping it would silently restore the default STUN server.
+            stun?.let { put("stun", it) }
+        }
+
+    companion object {
+        @JvmStatic
+        fun fromMap(values: Map<String, Any>?): StreamIceConfig? {
+            values ?: return null
+            return StreamIceConfig(stun = stringValue(values, "stun", "s"))
+        }
+    }
+}
+
 /** Effective video settings reported by the glasses after defaults and clamps. */
 data class StreamResolvedVideoConfig @JvmOverloads constructor(
     /** Encoded output width sent to the stream endpoint. */
@@ -214,6 +242,12 @@ data class StreamRequest @JvmOverloads constructor(
     val audio: StreamAudioConfig? = null,
     val authToken: String? = null,
     val captureAudio: Boolean = true,
+    val ice: StreamIceConfig? = null,
+    /**
+     * Correlation id the glasses echo in every SOFTAP_TRACE line, so phone and glasses logs can be
+     * joined despite unsynchronised clocks.
+     */
+    val traceId: String? = null,
 ) {
     fun toMap(): Map<String, Any> =
         buildMap {
@@ -225,6 +259,8 @@ data class StreamRequest @JvmOverloads constructor(
             audio?.toMap()?.takeIf { it.isNotEmpty() }?.let { put("audio", it) }
             authToken?.takeIf { it.isNotEmpty() }?.let { put("authToken", it) }
             if (!captureAudio) put("captureAudio", false)
+            ice?.toMap()?.takeIf { it.isNotEmpty() }?.let { put("ice", it) }
+            traceId?.takeIf { it.isNotEmpty() }?.let { put("traceId", it) }
         }
 
     companion object {
@@ -240,6 +276,8 @@ data class StreamRequest @JvmOverloads constructor(
                 audio = StreamAudioConfig.fromMap(stringMapValue(values["audio"])),
                 authToken = values["authToken"] as? String ?: values["auth_token"] as? String,
                 captureAudio = boolValue(values, "captureAudio") ?: boolValue(values, "ca") ?: true,
+                ice = StreamIceConfig.fromMap(stringMapValue(values["ice"] ?: values["i"])),
+                traceId = stringValue(values, "traceId"),
             )
     }
 }

package/android/src/main/java/com/mentra/bluetoothsdk/utils/MicSourcePin.kt

@@ -0,0 +1,31 @@
+package com.mentra.bluetoothsdk.utils
+
+/**
+ * Call-scoped microphone lock.
+ *
+ * The ranking in `DeviceManager` answers "which microphone can we get?", and for captions or the
+ * cloud uplink that is the right question — any working microphone beats none. A call is the case
+ * where it is the wrong question: the wearer agreed to be heard from the glasses, so falling
+ * through to the phone puts the room they are standing in onto a Teams call that still reports
+ * "glasses". A pin turns the fallback off for exactly as long as the call holds it.
+ */
+object MicSourcePin {
+  /**
+   * Validate a pin request. Only the glasses microphone can be pinned: every other source is one
+   * the ranking would have picked anyway, so pinning it buys nothing and only adds a way to strand
+   * the selection on a microphone no consumer asked for.
+   */
+  fun normalize(source: String?): String? {
+    val trimmed = source?.trim()?.takeIf { it.isNotEmpty() } ?: return null
+    require(trimmed == MicTypes.GLASSES_CUSTOM) { "unsupported mic source pin: $trimmed" }
+    return trimmed
+  }
+
+  /**
+   * The sources selection may consider. A pin replaces the ranking outright rather than reordering
+   * it, so "the pinned source is unavailable" resolves to no microphone instead of the next best
+   * one.
+   */
+  fun selectionOrder(ranking: List<String>, pin: String?): List<String> =
+    if (pin == null) ranking else listOf(pin)
+}

package/android/src/main/java/com/mentra/bluetoothsdk/utils/audio/PcmStreamPlayer.kt

@@ -29,6 +29,7 @@ class PcmStreamPlayer(
         private val sampleRate: Int,
         channels: Int,
         volume: Float,
+        jitterMs: Int = TRACK_BUFFER_MS,
 ) {
     companion object {
         private const val TAG = "PcmStreamPlayer"
@@ -41,8 +42,28 @@ class PcmStreamPlayer(
 
         /** AudioTrack buffer: max(4x minimum, 500ms) of jitter headroom. */
         private const val TRACK_BUFFER_MS = 500
+
+        /**
+         * Floor on the requested headroom.
+         *
+         * A MODE_STREAM track fills to its buffer size and stays there, so this value is also the
+         * steady-state output latency, not just a jitter cushion. Callers that want a conversation
+         * to feel live ask for a small number; below this the feeder cannot outrun playback and the
+         * track underruns into audible chop, which is worse than the delay it buys back.
+         */
+        private const val MIN_TRACK_BUFFER_MS = 80
     }
 
+    /**
+     * Playout headroom, and therefore this stream's floor latency.
+     *
+     * [TRACK_BUFFER_MS] suits one-way media (a miniapp `speaker.createStream()` clip), where half a
+     * second of cushion costs nothing audible. A realtime call is the opposite trade: that same
+     * cushion is half a second of delay before the far end's voice reaches the wearer, so the ACS
+     * meeting path asks for a much smaller one.
+     */
+    private val jitterBufferMs = jitterMs.coerceIn(MIN_TRACK_BUFFER_MS, TRACK_BUFFER_MS)
+
     private val bytesPerFrame = 2 * channels
     private val channelMask =
             if (channels >= 2) AudioFormat.CHANNEL_OUT_STEREO else AudioFormat.CHANNEL_OUT_MONO
@@ -70,7 +91,7 @@ class PcmStreamPlayer(
     init {
         val minBuf =
                 AudioTrack.getMinBufferSize(sampleRate, channelMask, AudioFormat.ENCODING_PCM_16BIT)
-        val jitterBuf = sampleRate * bytesPerFrame * TRACK_BUFFER_MS / 1000
+        val jitterBuf = sampleRate * bytesPerFrame * jitterBufferMs / 1000
         audioTrack =
                 AudioTrack.Builder()
                         .setAudioAttributes(
@@ -86,7 +107,11 @@ class PcmStreamPlayer(
                                         .setChannelMask(channelMask)
                                         .build()
                         )
-                        .setBufferSizeInBytes(max(minBuf * 4, jitterBuf))
+                        // minBuf is AudioTrack's own floor, so it wins over a smaller request; the
+                        // requested headroom is otherwise authoritative. Any fixed multiple of
+                        // minBuf here would silently override a caller asking for low latency,
+                        // since minBuf scales with the rate while the request does not.
+                        .setBufferSizeInBytes(max(minBuf, jitterBuf))
                         .setTransferMode(AudioTrack.MODE_STREAM)
                         .build()
         if (audioTrack.state != AudioTrack.STATE_INITIALIZED) {
@@ -101,7 +126,11 @@ class PcmStreamPlayer(
                     isDaemon = true
                     start()
                 }
-        Log.d(TAG, "[$streamId] opened: rate=$sampleRate ch=$channels vol=$volume")
+        Log.d(
+                TAG,
+                "[$streamId] opened: rate=$sampleRate ch=$channels vol=$volume " +
+                        "jitterMs=$jitterBufferMs trackBytes=${max(minBuf, jitterBuf)}",
+        )
     }
 
     /** Milliseconds of audio accepted but not yet played out. */
@@ -285,7 +314,7 @@ class PcmStreamPlayer(
 object PcmStreamManager {
     private val players = java.util.concurrent.ConcurrentHashMap<String, PcmStreamPlayer>()
 
-    fun open(streamId: String, sampleRate: Int, channels: Int, volume: Float) {
+    fun open(streamId: String, sampleRate: Int, channels: Int, volume: Float, jitterMs: Int? = null) {
         require(streamId.isNotBlank()) { "streamId is required" }
         require(sampleRate == 16000 || sampleRate == 24000 || sampleRate == 48000) {
             "unsupported PCM sample rate $sampleRate"
@@ -293,7 +322,12 @@ object PcmStreamManager {
         require(channels == 1) { "only mono PCM is supported" }
         // Replacing an id is a caller bug, but never leak the old track.
         players.remove(streamId)?.abort()
-        players[streamId] = PcmStreamPlayer(streamId, sampleRate, channels, volume)
+        players[streamId] =
+                if (jitterMs == null) {
+                    PcmStreamPlayer(streamId, sampleRate, channels, volume)
+                } else {
+                    PcmStreamPlayer(streamId, sampleRate, channels, volume, jitterMs)
+                }
     }
 
     fun write(streamId: String, base64: String): Long {