@mentra/bluetooth-sdk 3.2.0-dev.221 → 3.2.0-dev.223

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

@@ -835,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.
@@ -857,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

@@ -194,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
         }
 

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.221"
-    const val RELEASE_SET_ID: String = "mentra-3.2.0-dev.221"
-    const val SOURCE_COMMIT: String = "3837a3055e7a69e18553ce51c3a97579d2ad3b83"
-    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.221.json"
-    const val OTA_MANIFEST_SHA256: String = "657e9616ad0c464ee57d827c05b53393e45559992c13b15adbb06e0c903eb870"
+    const val RELEASE_IDENTITY: String = "3.2.0-dev.223"
+    const val RELEASE_SET_ID: String = "mentra-3.2.0-dev.223"
+    const val SOURCE_COMMIT: String = "03c06ea8306e617803295e8707e9a57f2b64a8ef"
+    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.223.json"
+    const val OTA_MANIFEST_SHA256: String = "41657c616a7d88d0f12fb2dddb0f7ead6fa38b6859500c22067faededcd80d4c"
 }

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 {

package/android/src/test/java/com/mentra/bluetoothsdk/MicPcmEventSourceTest.kt

@@ -0,0 +1,75 @@
+package com.mentra.bluetoothsdk
+
+import com.mentra.bluetoothsdk.utils.MicTypes
+import org.assertj.core.api.Assertions.assertThat
+import org.junit.Test
+
+/**
+ * The per-frame source tag, and the JS keys that read it.
+ *
+ * An ACS call pins the glasses microphone and then forwards every buffer to the far end. The pin is
+ * what makes that safe, but a pin the SDK could not honour is exactly the case worth catching, so
+ * each frame says which microphone produced it and the call verifies rather than assumes. That is
+ * only true if the tag survives the bridge, so the key names here are a contract with
+ * `AcsMeetingService`, not an implementation detail.
+ */
+class MicPcmEventSourceTest {
+  private fun frame(source: String) = MicPcmEvent(
+    pcm = ByteArray(320),
+    sampleRate = MicPcmEvent.SAMPLE_RATE,
+    bitsPerSample = MicPcmEvent.BITS_PER_SAMPLE,
+    channels = MicPcmEvent.CHANNELS,
+    encoding = MicPcmEvent.ENCODING,
+    voiceActivityDetectionEnabled = false,
+    source = source,
+  )
+
+  @Test
+  fun theKeysTheCallReadsAreAllPresent() {
+    val map = frame(MicTypes.GLASSES_CUSTOM).toMap()
+
+    assertThat(map).containsKeys("pcm", "sampleRate", "source")
+    assertThat(map["source"]).isEqualTo(MicTypes.GLASSES_CUSTOM)
+    assertThat(map["sampleRate"]).isEqualTo(16_000)
+    assertThat(map["encoding"]).isEqualTo("pcm_s16le")
+  }
+
+  @Test
+  fun everySourceTheRankingCanPickRoundTrips() {
+    for (source in MicTypes.ALL) {
+      val restored = MicPcmEvent(frame(source).toMap())
+      assertThat(restored.source).isEqualTo(source)
+    }
+  }
+
+  /**
+   * Absent must not decode as "glasses". A frame from a build that predates the tag is a frame
+   * whose source is unknown, and the call has to drop it rather than forward the phone's room.
+   */
+  @Test
+  fun anUntaggedFrameDecodesAsUnknownRatherThanGlasses() {
+    val legacy = mapOf<String, Any>(
+      "pcm" to ByteArray(320),
+      "sampleRate" to 16_000,
+      "bitsPerSample" to 16,
+      "channels" to 1,
+      "encoding" to "pcm_s16le",
+      "voiceActivityDetectionEnabled" to false,
+    )
+
+    val decoded = MicPcmEvent(legacy)
+
+    assertThat(decoded.source).isEmpty()
+    assertThat(decoded.source).isNotEqualTo(MicTypes.GLASSES_CUSTOM)
+  }
+
+  /** 16 kHz mono PCM16, 10 ms per LC3 frame: the size the call's base64 round trip has to preserve. */
+  @Test
+  fun aDecodedLc3FrameIsOneHundredAndSixtySamples() {
+    val map = frame(MicTypes.GLASSES_CUSTOM).toMap()
+    val pcm = map["pcm"] as ByteArray
+
+    assertThat(pcm).hasSize(320)
+    assertThat(pcm.size / 2).isEqualTo(160)
+  }
+}

package/android/src/test/java/com/mentra/bluetoothsdk/StreamRequestCaptureAudioTest.kt

@@ -39,4 +39,48 @@ class StreamRequestCaptureAudioTest {
     val full = StreamRequest.fromMap(mapOf("streamUrl" to "https://example.com/whip", "captureAudio" to false))
     assertThat(full.captureAudio).isFalse()
   }
+
+  @Test
+  fun hostOnlyIceSurvivesBridgeAndWireSerialization() {
+    val request = StreamRequest.fromMap(mapOf(
+      "streamUrl" to "http://192.168.43.79:8080/whip",
+      "ice" to mapOf("stun" to ""),
+    ))
+    assertThat(request.ice?.stun).isEqualTo("")
+
+    // The empty string is the host-only request. Dropping it as "blank" is what silently left the
+    // glasses gathering against the default Cloudflare STUN server on an internet-less hotspot.
+    @Suppress("UNCHECKED_CAST")
+    val ice = request.toMap()["ice"] as Map<String, Any>
+    assertThat(ice).containsEntry("stun", "")
+  }
+
+  @Test
+  fun absentIceStaysAbsentSoGlassesKeepTheirDefault() {
+    val request = StreamRequest.fromMap(mapOf("streamUrl" to "https://example.com/whip"))
+    assertThat(request.ice).isNull()
+    assertThat(request.toMap()).doesNotContainKey("ice")
+  }
+
+  @Test
+  fun compactIceKeysParse() {
+    val request = StreamRequest.fromMap(mapOf(
+      "streamUrl" to "http://192.168.43.79:8080/whip",
+      "i" to mapOf("s" to "stun:stun.example.com:3478"),
+    ))
+    assertThat(request.ice?.stun).isEqualTo("stun:stun.example.com:3478")
+  }
+
+  @Test
+  fun traceIdSurvivesBridgeAndWireSerialization() {
+    val request = StreamRequest.fromMap(mapOf(
+      "streamUrl" to "http://192.168.43.79:8080/whip",
+      "traceId" to "d34eeb11",
+    ))
+    assertThat(request.traceId).isEqualTo("d34eeb11")
+    assertThat(request.toMap()).containsEntry("traceId", "d34eeb11")
+
+    assertThat(StreamRequest(streamUrl = "https://example.com/whip").toMap())
+      .doesNotContainKey("traceId")
+  }
 }

package/android/src/test/java/com/mentra/bluetoothsdk/utils/MicSourcePinTest.kt

@@ -0,0 +1,68 @@
+package com.mentra.bluetoothsdk.utils
+
+import org.assertj.core.api.Assertions.assertThat
+import org.assertj.core.api.Assertions.assertThatThrownBy
+import org.junit.Test
+
+class MicSourcePinTest {
+  private val auto = MicMap.map.getValue("auto")
+
+  @Test
+  fun noPinLeavesTheRankingAlone() {
+    assertThat(MicSourcePin.selectionOrder(auto, null)).isEqualTo(auto)
+  }
+
+  /**
+   * The whole point of the pin: with the glasses microphone unavailable, an unpinned selection
+   * walks on to the phone. That fallback is right for captions and wrong for a call, so a pin has
+   * to remove the other sources rather than merely prefer the glasses.
+   */
+  @Test
+  fun aPinRemovesTheFallbacksRatherThanReorderingThem() {
+    val order = MicSourcePin.selectionOrder(auto, MicTypes.GLASSES_CUSTOM)
+
+    assertThat(order).containsExactly(MicTypes.GLASSES_CUSTOM)
+    assertThat(order).doesNotContain(MicTypes.PHONE_INTERNAL, MicTypes.BLUETOOTH, MicTypes.BLUETOOTH_CLASSIC)
+  }
+
+  @Test
+  fun aPinOutranksAPhoneFirstPreference() {
+    // `preferred_mic = phone` is an STT preference. It must not decide who a Teams call hears.
+    assertThat(MicSourcePin.selectionOrder(MicMap.map.getValue("phone"), MicTypes.GLASSES_CUSTOM))
+      .containsExactly(MicTypes.GLASSES_CUSTOM)
+  }
+
+  @Test
+  fun releasingRestoresEveryOtherConsumersPreference() {
+    val phoneFirst = MicMap.map.getValue("phone")
+    assertThat(MicSourcePin.selectionOrder(phoneFirst, MicSourcePin.normalize(null)))
+      .isEqualTo(phoneFirst)
+  }
+
+  @Test
+  fun blankAndNullBothMeanUnpinned() {
+    assertThat(MicSourcePin.normalize(null)).isNull()
+    assertThat(MicSourcePin.normalize("")).isNull()
+    assertThat(MicSourcePin.normalize("   ")).isNull()
+  }
+
+  @Test
+  fun theGlassesSourceIsAcceptedAndTrimmed() {
+    assertThat(MicSourcePin.normalize(MicTypes.GLASSES_CUSTOM)).isEqualTo(MicTypes.GLASSES_CUSTOM)
+    assertThat(MicSourcePin.normalize(" glasses ")).isEqualTo(MicTypes.GLASSES_CUSTOM)
+  }
+
+  /**
+   * Pinning any other source would strand selection on a microphone no consumer asked for, and
+   * failing loudly beats a call that silently pins the phone — the exact outcome the pin exists to
+   * prevent.
+   */
+  @Test
+  fun everyOtherSourceIsRejected() {
+    for (source in listOf(MicTypes.PHONE_INTERNAL, MicTypes.BLUETOOTH, MicTypes.BLUETOOTH_CLASSIC, "auto")) {
+      assertThatThrownBy { MicSourcePin.normalize(source) }
+        .isInstanceOf(IllegalArgumentException::class.java)
+        .hasMessageContaining(source)
+    }
+  }
+}