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

package/ios/BluetoothSdkModule.swift

@@ -640,8 +640,11 @@ public class BluetoothSdkModule: Module, MentraBluetoothSDKDelegate {
 
         // MARK: - Live PCM output stream (miniapp speaker.createStream)
 
+        // jitterMs is accepted for signature parity with Android and ignored: AVAudioEngine's
+        // scheduled-buffer playout has no equivalent fixed track buffer to size, so there is no
+        // knob here that would mean the same thing.
         AsyncFunction("pcmStreamOpen") {
-            (streamId: String, sampleRate: Int, channels: Int, volume: Double) async throws in
+            (streamId: String, sampleRate: Int, channels: Int, volume: Double, _: Int?) async throws in
             try PcmStreamManager.open(
                 streamId: streamId,
                 sampleRate: sampleRate,
@@ -711,6 +714,17 @@ public class BluetoothSdkModule: Module, MentraBluetoothSDKDelegate {
             }
         }
 
+        /**
+         * Android-only today. Present so a host that pins the microphone for a call does not have
+         * to branch on platform, and so a caller cannot mistake a missing function for a pin that
+         * was taken: the ACS capability gate excludes iOS precisely because this cannot honour it.
+         */
+        AsyncFunction("setMicSourcePin") { (source: String?) in
+            if source != nil {
+                Bridge.log("BluetoothSdkModule: setMicSourcePin(\(source ?? "")) is not implemented on iOS; ignoring")
+            }
+        }
+
         AsyncFunction("restartTranscriber") {
             await MainActor.run {
                 DeviceManager.shared.restartTranscriber()

package/ios/Source/BluetoothSdkDefaults.swift

@@ -11,7 +11,7 @@ enum BluetoothSdkDefaults {
     static let voiceActivityDetectionEnabled = false
     static let loudnessGateEnabled = false
     private static let infoSdkVersionKey = "MentraBluetoothSdkVersion"
-    private static let swiftPackageSdkVersion = "3.2.0-dev.217"
+    private static let swiftPackageSdkVersion = "3.2.0-dev.222"
     private static let swiftPackageSdkVersionPlaceholder = "__MENTRA" + "_BLUETOOTH_SDK_VERSION__"
 
     private static func normalizedSdkVersion(_ value: String?) -> String? {

package/ios/Source/Bridge.swift

@@ -15,17 +15,6 @@ class Bridge {
     private static let micChannels = 1
     private static let lc3FrameDurationMs = 10
     private static let defaultLc3FrameSizeBytes = 60
-    private static let audioTraceMetadataKeys = [
-        "sampleRate",
-        "bitsPerSample",
-        "channels",
-        "encoding",
-        "frameDurationMs",
-        "frameSizeBytes",
-        "bitrate",
-        "packetizedFromGlasses",
-        "voiceActivityDetectionEnabled",
-    ]
     private static let eventSinkLock = NSLock()
     private static let defaultEventSinkId = "default"
     private static var eventSinks: [String: (String, [String: Any]) -> Void] = [:]
@@ -148,6 +137,10 @@ class Bridge {
             "channels": micChannels,
             "encoding": "pcm_s16le",
             "voiceActivityDetectionEnabled": voiceActivityDetectionEnabled,
+            // Stamped per frame so a consumer that asked for a specific microphone can verify it
+            // rather than assume it. Read now, not captured: the point is which microphone is
+            // selected for this buffer. Empty when the SDK has not selected one.
+            "source": DeviceStore.shared.get("bluetooth", "currentMic") as? String ?? "",
         ]
     }
 
@@ -700,47 +693,22 @@ class Bridge {
         dispatchEvent(type, body)
     }
 
+    /// Returns nil for events that must not be traced.
+    ///
+    /// "log" is excluded so tracing never recurses back through the log event. Audio payload
+    /// events are excluded because they arrive at frame rate, which made every microphone
+    /// frame emit a second bridge event. On Android that overflowed the JNI global reference
+    /// table and aborted the process; here it is wasted work on the audio path. Audio faults
+    /// (sequence gaps, decode failures) are still reported through "mic_health", and healthy
+    /// frames need no trace.
     private static func tracePayloadForTypedMessage(_ type: String, body: [String: Any]) -> [String: Any]? {
-        if type == "log" {
+        if type == "log" || isAudioPayloadEvent(type) {
             return nil
         }
-        if isAudioPayloadEvent(type) {
-            return audioTracePayload(type, body: body)
-        }
         return body
     }
 
     private static func isAudioPayloadEvent(_ type: String) -> Bool {
         type == "mic_pcm" || type == "mic_lc3"
     }
-
-    private static func audioTracePayload(_ type: String, body: [String: Any]) -> [String: Any] {
-        var payload: [String: Any] = [
-            "type": type,
-            "timestamp": Int(Date().timeIntervalSince1970 * 1000),
-            "payloadOmitted": true,
-            "payloadOmittedReason": "audio",
-        ]
-
-        switch type {
-        case "mic_pcm":
-            if let data = body["pcm"] as? Data {
-                payload["audioBytes"] = data.count
-            }
-        case "mic_lc3":
-            if let data = body["lc3"] as? Data {
-                payload["audioBytes"] = data.count
-            }
-        default:
-            break
-        }
-
-        for key in audioTraceMetadataKeys {
-            if let value = body[key] {
-                payload[key] = value
-            }
-        }
-
-        return payload
-    }
 }

package/ios/Source/GeneratedReleaseMetadata.swift

@@ -3,9 +3,9 @@ import Foundation
 /// Generated by release CI. Do not edit in a release checkout.
 enum GeneratedReleaseMetadata {
     static let familyBaseVersion = "3.2.0"
-    static let releaseIdentity = "3.2.0-dev.217"
-    static let releaseSetId = "mentra-3.2.0-dev.217"
-    static let sourceCommit = "acd4336bcf67c5e2c7ddfa17ea1a2600dc7fb1d9"
-    static let otaManifestUrl = "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.217.json"
-    static let otaManifestSha256 = "4ec6bf57ab08ef2749a58232737dface3b0ddb0d8269b61e134b7cb5986efa4a"
+    static let releaseIdentity = "3.2.0-dev.222"
+    static let releaseSetId = "mentra-3.2.0-dev.222"
+    static let sourceCommit = "7865d7f192a2d9a732269857bb877a3a8a6bf4b8"
+    static let otaManifestUrl = "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.222.json"
+    static let otaManifestSha256 = "8c33e8beb5ba61eb0821d89b58d81fe2bbf05641d0a99b2e1972926863cc6ab7"
 }

package/ios/Source/streaming/StreamModels.swift

@@ -87,6 +87,34 @@ public struct StreamAudioConfig {
     }
 }
 
+/// ICE overrides for a WHIP stream. Ignored by the RTMP and SRT paths.
+public struct StreamIceConfig {
+    /// STUN server the glasses use while gathering candidates.
+    ///
+    /// `nil` and empty are different answers, and both have to survive the BLE round trip. `nil`
+    /// leaves the glasses on their default Cloudflare STUN server; an empty string is an explicit
+    /// request for host-only gathering, which is what a WHIP server on the glasses' own hotspot
+    /// needs, since a reflexive candidate there is meaningless and unreachable.
+    public let stun: String?
+
+    public init(stun: String? = nil) {
+        self.stun = stun
+    }
+
+    var dictionary: [String: Any] {
+        var values: [String: Any] = [:]
+        // Not filtered on emptiness, unlike the other optional string fields here: "" is the
+        // host-only signal, so dropping it would silently restore the default STUN server.
+        if let stun { values["stun"] = stun }
+        return values
+    }
+
+    init?(values: [String: Any]?) {
+        guard let values else { return nil }
+        self.init(stun: values["stun"] as? String ?? values["s"] as? String)
+    }
+}
+
 /// Effective video settings reported by the glasses after defaults and clamps.
 public struct StreamResolvedVideoConfig: Equatable {
     /// Encoded output width sent to the stream endpoint.
@@ -286,6 +314,10 @@ public struct StreamRequest {
     public let audio: StreamAudioConfig?
     public let authToken: String?
     public let captureAudio: Bool
+    public let ice: StreamIceConfig?
+    /// Correlation id the glasses echo in every SOFTAP_TRACE line, so phone and glasses logs can
+    /// be joined despite unsynchronised clocks.
+    public let traceId: String?
 
     public init(
         streamUrl: String,
@@ -294,7 +326,9 @@ public struct StreamRequest {
         video: StreamVideoConfig? = nil,
         audio: StreamAudioConfig? = nil,
         authToken: String? = nil,
-        captureAudio: Bool = true
+        captureAudio: Bool = true,
+        ice: StreamIceConfig? = nil,
+        traceId: String? = nil
     ) {
         self.streamUrl = streamUrl
         self.streamId = streamId
@@ -303,6 +337,8 @@ public struct StreamRequest {
         self.audio = audio
         self.authToken = authToken
         self.captureAudio = captureAudio
+        self.ice = ice
+        self.traceId = traceId
     }
 
     init(values: [String: Any]) {
@@ -317,7 +353,11 @@ public struct StreamRequest {
             video: StreamVideoConfig(values: values["video"] as? [String: Any]),
             audio: StreamAudioConfig(values: values["audio"] as? [String: Any]),
             authToken: values["authToken"] as? String ?? values["auth_token"] as? String,
-            captureAudio: (values["captureAudio"] as? Bool) ?? (values["ca"] as? Bool) ?? true
+            captureAudio: (values["captureAudio"] as? Bool) ?? (values["ca"] as? Bool) ?? true,
+            ice: StreamIceConfig(
+                values: (values["ice"] as? [String: Any]) ?? (values["i"] as? [String: Any])
+            ),
+            traceId: values["traceId"] as? String
         )
     }
 
@@ -339,6 +379,12 @@ public struct StreamRequest {
         if !captureAudio {
             values["captureAudio"] = false
         }
+        if let iceValues = ice?.dictionary, !iceValues.isEmpty {
+            values["ice"] = iceValues
+        }
+        if let traceId, !traceId.isEmpty {
+            values["traceId"] = traceId
+        }
         return values
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentra/bluetooth-sdk",
-  "version": "3.2.0-dev.217",
+  "version": "3.2.0-dev.222",
   "description": "SDK for communicating with smart glasses",
   "main": "build/index.js",
   "react-native": "src/index.ts",

package/src/BluetoothSdk.types.ts

@@ -714,6 +714,20 @@ export type StreamAudioConfig = {
   noiseSuppression?: boolean
 }
 
+/** ICE overrides for a WHIP stream. Ignored by the RTMP and SRT paths. */
+export type StreamIceConfig = {
+  /**
+   * STUN server the glasses should use while gathering candidates.
+   *
+   * Omit to keep the default Cloudflare STUN server. Pass an empty string to force host-only
+   * gathering, which is what SoftAP calling needs: the WHIP server runs on the phone across the
+   * glasses' own hotspot, so a server-reflexive candidate is meaningless and there is no route to
+   * a STUN server anyway. A value that is not a `stun:`/`stuns:` URI is ignored and the default is
+   * kept, so a malformed override cannot silently disable ICE.
+   */
+  stun?: string
+}
+
 export type StreamStartRequest = {
   type?: "start_stream"
   streamUrl: string
@@ -721,8 +735,16 @@ export type StreamStartRequest = {
   sound?: boolean
   video?: StreamVideoConfig
   audio?: StreamAudioConfig
+  ice?: StreamIceConfig
   /** When false, glasses skip mic capture. Defaults to true. */
   captureAudio?: boolean
+  /**
+   * Correlation id echoed by the glasses in every SOFTAP_TRACE log line, so phone and glasses
+   * logs can be joined despite having unsynchronised clocks.
+   *
+   * TEMPORARY: part of the SoftAP diagnostic trace layer.
+   */
+  traceId?: string
 }
 
 export type StreamKeepAliveRequest = {
@@ -791,6 +813,12 @@ export type MicPcmEvent = {
   channels: 1
   encoding: "pcm_s16le"
   voiceActivityDetectionEnabled: boolean
+  /**
+   * The microphone this buffer came from (`"glasses"`, `"phone"`, `"bluetooth"`, or `""` when none
+   * is selected). Stamped per frame because the SDK can move the source mid-stream, so a consumer
+   * that told a remote party which microphone it is sending can check rather than assume.
+   */
+  source: string
 }
 
 export type MicLc3Event = {

package/src/_private/BluetoothSdkModule.ts

@@ -209,6 +209,15 @@ declare class BluetoothSdkNativeModule extends NativeModule<BluetoothSdkModuleEv
   // Microphone Commands
   setMicState(enabled: boolean, useGlassesMic?: boolean, sendTranscript?: boolean, sendLc3Data?: boolean): Promise<void>
   setPreferredMic(preferredMic: MicPreference): Promise<void>
+  /**
+   * Lock microphone selection to one source (`"glasses"`) until released with `null`.
+   *
+   * Stronger than [setPreferredMic]: a preference is a ranking the SDK falls through when a source
+   * is unavailable, while a pin has no fallback and reports `mic_health` with
+   * `reason: "pinned-source-unavailable"` instead. Android only; the iOS implementation is a no-op,
+   * so a caller that depends on the guarantee must gate on platform.
+   */
+  setMicSourcePin(source: string | null): Promise<void>
   restartTranscriber(): Promise<void>
 
   // Audio Playback Monitoring
@@ -220,8 +229,21 @@ declare class BluetoothSdkNativeModule extends NativeModule<BluetoothSdkModuleEv
   // ? 16-bit LE PCM chunks into a streaming AudioTrack (USAGE_MEDIA, so it
   // follows the phone's media route, e.g. A2DP to glasses). Implemented with
   // AudioTrack on Android and AVAudioEngine on iOS.
-  /** Open a PCM stream session. One AudioTrack per id; caller manages ids. */
-  pcmStreamOpen(streamId: string, sampleRate: number, channels: number, volume: number): Promise<void>
+  /**
+   * Open a PCM stream session. One AudioTrack per id; caller manages ids.
+   *
+   * `jitterMs` sizes the playout buffer and is therefore also the stream's floor latency, since a
+   * streaming track fills to its buffer and stays there. Omit it for one-way media, where the
+   * default cushion is inaudible; pass a small value for conversational audio, where the same
+   * cushion is delay before the far end is heard. Android only — iOS accepts and ignores it.
+   */
+  pcmStreamOpen(
+    streamId: string,
+    sampleRate: number,
+    channels: number,
+    volume: number,
+    jitterMs?: number,
+  ): Promise<void>
   /**
    * Append base64 PCM. Resolves with the queued-but-unplayed backlog in ms;
    * blocks (on a background dispatcher) while the backlog is above the

package/src/generated/releaseMetadata.ts

@@ -12,9 +12,9 @@ export interface BluetoothSdkReleaseMetadata {
 export const BLUETOOTH_SDK_RELEASE_METADATA: Readonly<BluetoothSdkReleaseMetadata> = Object.freeze({
   "schemaVersion": 1,
   "familyBaseVersion": "3.2.0",
-  "releaseIdentity": "3.2.0-dev.217",
-  "releaseSetId": "mentra-3.2.0-dev.217",
-  "sourceCommit": "acd4336bcf67c5e2c7ddfa17ea1a2600dc7fb1d9",
-  "otaManifestUrl": "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.217.json",
-  "otaManifestSha256": "4ec6bf57ab08ef2749a58232737dface3b0ddb0d8269b61e134b7cb5986efa4a"
+  "releaseIdentity": "3.2.0-dev.222",
+  "releaseSetId": "mentra-3.2.0-dev.222",
+  "sourceCommit": "7865d7f192a2d9a732269857bb877a3a8a6bf4b8",
+  "otaManifestUrl": "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.222.json",
+  "otaManifestSha256": "8c33e8beb5ba61eb0821d89b58d81fe2bbf05641d0a99b2e1972926863cc6ab7"
 })