@mentra/engine 3.2.1-dev.277 → 3.2.1-dev.279

package/src/services/LocalMiniappRuntime.ts

@@ -46,6 +46,8 @@ import type {DisplayPayload} from "./LocalDisplayManager"
 import headingService from "./HeadingService"
 import localSttFallbackCoordinator from "./LocalSttFallbackCoordinator"
 import micStateCoordinator from "./MicStateCoordinator"
+import micSessionManager, {MIC_SOURCE_CONFLICT, type MicSession} from "./MicSessionManager"
+import {ENGINE_ONLY_USE_CASES, MIC_USE_CASES, VOICE_CALL_PACKAGES, type MicUseCase} from "./micPolicy"
 import {BlobStore} from "./BlobStore"
 import {CloudAudioSubscriptionSync} from "./CloudAudioSubscriptionSync"
 import {phoneCameraFovCoordinator} from "./PhoneCameraFovCoordinator"
@@ -574,6 +576,14 @@ class LocalMiniappRuntime {
    */
   private transcriptionHintsByApp = new Map<string, string[]>()
 
+  /**
+   * Microphone sessions taken through session.mic.acquire, by session id.
+   *
+   * Bookkeeping only, so a release can be matched to its owner; MicSessionManager holds the real
+   * leases and resolves them into hardware state.
+   */
+  private micSessionsByApp = new Map<number, {packageName: string; session: MicSession}>()
+
   /** Ping interval handle. */
   private pingIntervalId: number | null = null
   private foregroundProbeTimers: Map<string, number> = new Map()
@@ -980,6 +990,10 @@ class LocalMiniappRuntime {
   public unregisterApp(packageName: string): void {
     console.log(`${LOG_TAG}: unregisterApp(${packageName})`)
     const releasedMicGateOverride = micStateCoordinator.clearMiniappGateOverrides(packageName)
+    // Backstop for a miniapp that crashed or was killed mid-call: the microphone profile and the
+    // PCM claim must not outlive the app that asked for them.
+    this.forgetMicSessions(packageName)
+    micSessionManager.releaseOwner(packageName)
     this.clearForegroundProbe(packageName)
     this.clearMiniappAuthRefresh(packageName)
     this.clearMiniappAuthDeliveryRetry(packageName)
@@ -1259,6 +1273,12 @@ class LocalMiniappRuntime {
       case MiniappRequestType.MIC_SET_LOUDNESS_GATE_ENABLED:
         void this.handleMicSetLoudnessGateEnabled(packageName, payload, requestId)
         break
+      case MiniappRequestType.MIC_ACQUIRE:
+        this.handleMicAcquire(packageName, payload, requestId)
+        break
+      case MiniappRequestType.MIC_RELEASE:
+        this.handleMicRelease(packageName, payload, requestId)
+        break
       case MiniappRequestType.PING:
         // SDK should handle this itself; reply PONG just in case
         this.sendToMiniapp(packageName, {type: MiniappResponseType.PONG}, requestId)
@@ -3220,6 +3240,100 @@ class LocalMiniappRuntime {
     }
   }
 
+  /**
+   * session.mic.acquire — take a semantic microphone session.
+   *
+   * The miniapp names a use case; MicSessionManager and micPolicy decide what that means for the
+   * hardware. This handler is only the gate: who is allowed to ask for what.
+   */
+  private handleMicAcquire(packageName: string, payload: Record<string, unknown>, requestId?: string): void {
+    const app = this.connectedApps.get(packageName)
+    const hasMicPermission = app?.installedManifest?.permissions?.some((p) => p.type === "MICROPHONE")
+    if (!hasMicPermission) {
+      logPermissionNotDeclared(packageName, "MICROPHONE", "to acquire a microphone session", `{"type": "MICROPHONE"}`)
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: MiniappErrorCode.PERMISSION_NOT_DECLARED,
+        message: `MICROPHONE permission not declared in miniapp.json. Add {"type": "MICROPHONE"} to the "permissions" array.`,
+        permission: "MICROPHONE",
+        operation: MiniappRequestType.MIC_ACQUIRE,
+      })
+      return
+    }
+
+    const source = payload.source
+    const useCase = payload.useCase
+    if (source !== "glasses" && source !== "phone") {
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: MiniappErrorCode.INVALID_ARGUMENT,
+        message: `source must be "glasses" or "phone"`,
+      })
+      return
+    }
+    if (!MIC_USE_CASES.includes(useCase as MicUseCase)) {
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: MiniappErrorCode.INVALID_ARGUMENT,
+        message: `useCase must be one of ${MIC_USE_CASES.join(", ")}`,
+      })
+      return
+    }
+
+    // A voice call gets a microphone profile tuned for close-talk speech, so which app may ask for
+    // one is a product decision, not a permission a manifest can grant itself.
+    if (useCase === "voice_call" && !VOICE_CALL_PACKAGES.includes(packageName)) {
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: MiniappErrorCode.PERMISSION_DENIED,
+        message: `${packageName} is not allowed to acquire a voice_call microphone session`,
+      })
+      return
+    }
+    // Diagnostic leases exist so the mic probe measures what users actually get. Handing one to a
+    // miniapp would also hand it a glasses lease it could pair with a meeting join.
+    if (ENGINE_ONLY_USE_CASES.includes(useCase as MicUseCase)) {
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: MiniappErrorCode.PERMISSION_DENIED,
+        message: `the ${useCase} microphone use case is reserved for the Mentra App`,
+      })
+      return
+    }
+
+    try {
+      const session = micSessionManager.acquire({owner: packageName, source, useCase: useCase as MicUseCase})
+      this.micSessionsByApp.set(session.id, {packageName, session})
+      console.log(`${LOG_TAG}: mic_acquire #${session.id} ${useCase}/${source} (by ${packageName})`)
+      this.sendResult(packageName, requestId, true, {sessionId: session.id})
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "mic acquire error"
+      console.warn(`${LOG_TAG}: mic_acquire failed for ${packageName}:`, message)
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: message.startsWith(MIC_SOURCE_CONFLICT) ? MiniappErrorCode.MIC_SOURCE_CONFLICT : MiniappErrorCode.INTERNAL,
+        message,
+      })
+    }
+  }
+
+  /** session.mic.acquire(...).release() — drop one session, if the caller owns it. */
+  private handleMicRelease(packageName: string, payload: Record<string, unknown>, requestId?: string): void {
+    const sessionId = payload.sessionId
+    const entry = typeof sessionId === "number" ? this.micSessionsByApp.get(sessionId) : undefined
+    if (!entry || entry.packageName !== packageName) {
+      // Idempotent by design: a miniapp releasing twice, or releasing after unregister already
+      // dropped its sessions, is not an error worth failing a teardown path over.
+      this.sendResult(packageName, requestId, true)
+      return
+    }
+    this.micSessionsByApp.delete(entry.session.id)
+    entry.session.release()
+    console.log(`${LOG_TAG}: mic_release #${entry.session.id} (by ${packageName})`)
+    this.sendResult(packageName, requestId, true)
+  }
+
+  /** Drop the bookkeeping for every session an app owns. The manager is the source of truth. */
+  private forgetMicSessions(packageName: string): void {
+    for (const [id, entry] of this.micSessionsByApp) {
+      if (entry.packageName === packageName) this.micSessionsByApp.delete(id)
+    }
+  }
+
   /**
    * session.system.scanQr — host camera overlay. Must not clear miniapp
    * foreground; the host seam is responsible for presenting a Modal on top.
@@ -3749,6 +3863,18 @@ class LocalMiniappRuntime {
     // asked too late to explain itself, and ACS fails the join outright without the camera.
     if (!(await this.requireOsPermission(packageName, requestId, PermissionFeatures.CAMERA, "camera"))) return
     if (!(await this.requireOsPermission(packageName, requestId, PermissionFeatures.MICROPHONE, "microphone"))) return
+    // The wearer's voice rides a microphone session, not the meeting. An app allowed to make voice
+    // calls must hold one before the sink starts, or it would get a call configured for dictation.
+    // Other joiners are not required to: without a session the BLE LC3 uplink is simply not
+    // selected and the audio rides the WHIP capture path, exactly as it did before.
+    const glassesSession = micSessionManager.hasGlassesSession(packageName)
+    if (VOICE_CALL_PACKAGES.includes(packageName) && !glassesSession) {
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: MiniappErrorCode.MIC_SESSION_REQUIRED,
+        message: "acquire a glasses microphone session before joining a meeting",
+      })
+      return
+    }
     const meetingUrl = typeof payload.meetingUrl === "string" ? payload.meetingUrl : ""
     const token = typeof payload.token === "string" ? payload.token : ""
     const displayName = typeof payload.displayName === "string" ? payload.displayName : undefined
@@ -3799,7 +3925,14 @@ class LocalMiniappRuntime {
         })
         const startedAt = Date.now()
         try {
-          const state = await this.joinSoftapMeeting(packageName, {meetingUrl, token, displayName, video, origin})
+          const state = await this.joinSoftapMeeting(packageName, {
+            meetingUrl,
+            token,
+            displayName,
+            video,
+            origin,
+            glassesSession,
+          })
           softapTrace("meeting_join_result", {
             packageName,
             requestId: requestId ?? "none",
@@ -3827,6 +3960,7 @@ class LocalMiniappRuntime {
         videoSource,
         displayName,
         origin,
+        glassesSession,
         ...(video ? {video} : {}),
       })
       this.sendResult(packageName, requestId, true, state)
@@ -3855,7 +3989,14 @@ class LocalMiniappRuntime {
    */
   private async joinSoftapMeeting(
     packageName: string,
-    args: {meetingUrl: string; token: string; displayName?: string; video?: AcsOutgoingVideo; origin?: AcsCallOrigin},
+    args: {
+      meetingUrl: string
+      token: string
+      displayName?: string
+      video?: AcsOutgoingVideo
+      origin?: AcsCallOrigin
+      glassesSession: boolean
+    },
   ): Promise<MeetingState> {
     // Reserve before awaiting retirement: a second Start or Cancel must see this request,
     // including while it is waiting for its predecessor's native cleanup.
@@ -4015,7 +4156,14 @@ class LocalMiniappRuntime {
   private async runSoftapAttempt(
     attempt: SoftapAttempt,
     previous: SoftapAttempt | null,
-    args: {meetingUrl: string; token: string; displayName?: string; video?: AcsOutgoingVideo; origin?: AcsCallOrigin},
+    args: {
+      meetingUrl: string
+      token: string
+      displayName?: string
+      video?: AcsOutgoingVideo
+      origin?: AcsCallOrigin
+      glassesSession: boolean
+    },
   ): Promise<MeetingState> {
     const packageName = attempt.packageName
     if (previous) {
@@ -4131,6 +4279,7 @@ class LocalMiniappRuntime {
               videoSource: options.videoSource,
               displayName: options.displayName,
               origin: args.origin,
+              glassesSession: args.glassesSession,
               ...(args.video ? {video: args.video} : {}),
             }),
           leaveMeeting: (pkg) => acsMeetingService.leave(pkg),

package/src/services/MicSessionManager.ts

@@ -0,0 +1,255 @@
+/**
+ * MicSessionManager
+ *
+ * The engine's microphone ownership layer. Applications acquire a lease that
+ * says what they are doing; this class tracks the live leases, resolves them
+ * through `micPolicy`, and pushes the result to MicStateCoordinator.
+ *
+ * Everything above it is semantic ("I need a glasses microphone for a voice
+ * call"). Everything below it is hardware. Audio *sinks* — AcsMeetingService
+ * today, another transport later — are downstream of the PCM this produces and
+ * must not reach past it to the coordinator or the Bluetooth SDK.
+ */
+
+import {Platform} from "react-native"
+import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
+
+import {getCallGainSweep} from "./CallGainSweep"
+import micStateCoordinator from "./MicStateCoordinator"
+import {
+  resolveMicPolicy,
+  type MicPlatformCaps,
+  type MicSessionSpec,
+  type MicSource,
+  type MicUseCase,
+} from "./micPolicy"
+
+const LOG_TAG = "MIC_SESSION"
+
+/** Raised when a second source is requested while another is already live. */
+export const MIC_SOURCE_CONFLICT = "MIC_SOURCE_CONFLICT"
+
+export interface MicSessionOptions {
+  /** Package name for a miniapp, or `engine:<name>` for an engine feature. */
+  owner: string
+  source: MicSource
+  useCase: MicUseCase
+}
+
+export interface MicSession {
+  readonly id: number
+  readonly owner: string
+  readonly source: MicSource
+  readonly useCase: MicUseCase
+  /** Idempotent. Releasing a session that is already gone is a no-op. */
+  release(): void
+}
+
+interface LiveSession extends MicSessionSpec {
+  id: number
+  owner: string
+}
+
+function defaultCaps(): MicPlatformCaps {
+  return {
+    // iOS has no `setMicSourcePin`, so it cannot promise the phone microphone
+    // stays shut, and `glassesLc3UplinkSupported` never selects the BLE LC3
+    // uplink there.
+    glassesPcmUplink: Platform.OS === "android" && typeof BluetoothSdk.setMicSourcePin === "function",
+  }
+}
+
+class MicSessionManager {
+  private static instance: MicSessionManager | null = null
+
+  private readonly sessions = new Map<number, LiveSession>()
+  private nextId = 1
+  private caps: MicPlatformCaps = defaultCaps()
+  /** Last pin we asked for, so a no-op change does not re-enter native. */
+  private pinned = false
+  /**
+   * One 15→14→15→13 walk per voice-call generation. Cleared when the last
+   * glasses voice_call session drops so the next join can measure again.
+   */
+  private sweepFinished = false
+  /** One-shot A/B walk. Off now that 15/14/13 is measured; Super Mode can still start it. */
+  private sweepEnabled = false
+
+  private constructor() {}
+
+  public static getInstance(): MicSessionManager {
+    if (!MicSessionManager.instance) {
+      MicSessionManager.instance = new MicSessionManager()
+    }
+    return MicSessionManager.instance
+  }
+
+  /** Test seam. Production reads the platform once at construction. */
+  public setPlatformCaps(caps: MicPlatformCaps): void {
+    this.caps = caps
+  }
+
+  /**
+   * Take a microphone lease.
+   *
+   * Throws [MIC_SOURCE_CONFLICT] when a different source is already live: only
+   * the glasses can be pinned, so silently mixing sources would leave one
+   * consumer reading a microphone it did not ask for. That is the failure ACS
+   * already guards against frame by frame.
+   */
+  public acquire(options: MicSessionOptions): MicSession {
+    const conflicting = [...this.sessions.values()].find((s) => s.source !== options.source)
+    if (conflicting) {
+      throw new Error(
+        `${MIC_SOURCE_CONFLICT}: ${options.owner} asked for "${options.source}" while ` +
+          `${conflicting.owner} holds "${conflicting.source}"`,
+      )
+    }
+
+    const id = this.nextId++
+    this.sessions.set(id, {id, owner: options.owner, source: options.source, useCase: options.useCase})
+    console.log(`${LOG_TAG}: acquire #${id} ${options.owner} ${options.useCase}/${options.source}`)
+    this.recompute()
+
+    return {
+      id,
+      owner: options.owner,
+      source: options.source,
+      useCase: options.useCase,
+      release: () => this.releaseId(id),
+    }
+  }
+
+  /** Drop every lease an owner holds. The backstop for unregister / disconnect. */
+  public releaseOwner(owner: string): boolean {
+    let removed = false
+    for (const [id, session] of this.sessions) {
+      if (session.owner !== owner) continue
+      this.sessions.delete(id)
+      removed = true
+    }
+    if (removed) {
+      console.log(`${LOG_TAG}: released all sessions for ${owner}`)
+      this.recompute()
+    }
+    return removed
+  }
+
+  /**
+   * Whether an owner holds a glasses lease.
+   *
+   * Ownership only. Whether that lease has any hardware effect is
+   * [resolveMicPolicy]'s business, so on a platform without a glasses PCM
+   * uplink this still answers true while nothing is claimed.
+   */
+  public hasGlassesSession(owner: string): boolean {
+    for (const session of this.sessions.values()) {
+      if (session.owner === owner && session.source === "glasses") return true
+    }
+    return false
+  }
+
+  public releaseAll(): void {
+    if (this.sessions.size === 0) {
+      this.stopSweep("released_all")
+      return
+    }
+    this.sessions.clear()
+    console.log(`${LOG_TAG}: released all sessions`)
+    this.recompute()
+  }
+
+  public cleanup(): void {
+    this.stopSweep("cleanup")
+    this.sessions.clear()
+    this.pinned = false
+    this.sweepFinished = false
+    MicSessionManager.instance = null
+  }
+
+  /** Tests disable the auto-walk so acquire still means "policy 14". */
+  public setCallGainSweepEnabled(enabled: boolean): void {
+    this.sweepEnabled = enabled
+    if (!enabled) this.stopSweep("disabled")
+  }
+
+  /**
+   * Start or restart the 15→14→15→13 comparison on a live voice_call session.
+   * Super Mode uses this so a call already in progress can be measured.
+   */
+  public startCallGainSweep(): boolean {
+    if (!this.hasVoiceCallGlasses()) {
+      console.warn(`${LOG_TAG}: CALL_GAIN_SWEEP ignored — no live voice_call glasses session`)
+      return false
+    }
+    if (micStateCoordinator.hasConfiguredMicTuning()) {
+      console.warn(
+        `${LOG_TAG}: CALL_GAIN_SWEEP Super Mode mic-tuning is set; reset it or the glasses will ignore the sweep`,
+      )
+    }
+    this.sweepFinished = false
+    return getCallGainSweep().restart(
+      (gain) => micStateCoordinator.setSessionMicTuning({gain}),
+      () => {
+        this.sweepFinished = true
+        this.recompute()
+      },
+    )
+  }
+
+  private releaseId(id: number): void {
+    if (!this.sessions.delete(id)) return
+    console.log(`${LOG_TAG}: release #${id}`)
+    this.recompute()
+  }
+
+  private hasVoiceCallGlasses(): boolean {
+    if (!this.caps.glassesPcmUplink) return false
+    for (const session of this.sessions.values()) {
+      if (session.useCase === "voice_call" && session.source === "glasses") return true
+    }
+    return false
+  }
+
+  private stopSweep(reason: string): void {
+    if (getCallGainSweep().isActive()) getCallGainSweep().stop(reason)
+  }
+
+  private recompute(): void {
+    const policy = resolveMicPolicy([...this.sessions.values()], this.caps)
+    const voiceCall = this.hasVoiceCallGlasses()
+    if (!voiceCall) {
+      this.stopSweep("session_ended")
+      this.sweepFinished = false
+    }
+
+    // Pin before claiming PCM, so the first frame the claim produces is
+    // already from the right microphone and the phone mic is never opened.
+    if (policy.pinGlasses !== this.pinned) {
+      this.pinned = policy.pinGlasses
+      void Promise.resolve(BluetoothSdk.setMicSourcePin?.(policy.pinGlasses ? "glasses" : null)).catch(
+        (error) => {
+          console.warn(`${LOG_TAG}: setMicSourcePin failed`, error)
+        },
+      )
+    }
+
+    micStateCoordinator.setSessionRequirement(policy.rawPcm)
+
+    if (getCallGainSweep().isActive()) {
+      const gain = getCallGainSweep().currentGain()
+      micStateCoordinator.setSessionMicTuning(gain == null ? policy.micTuning : {gain})
+      return
+    }
+
+    if (this.sweepEnabled && voiceCall && !this.sweepFinished) {
+      this.startCallGainSweep()
+      return
+    }
+
+    micStateCoordinator.setSessionMicTuning(policy.micTuning)
+  }
+}
+
+const micSessionManager = MicSessionManager.getInstance()
+export default micSessionManager

package/src/services/MicStateCoordinator.ts

@@ -6,11 +6,17 @@
  * Local miniapps subscribe to audio_chunk / transcription streams.
  * This coordinator pushes the aggregate local requirement set to BluetoothSdk
  * so the mic runs whenever at least one local consumer needs it.
+ *
+ * It also merges what the live microphone sessions require (MicSessionManager,
+ * via `setSessionRequirement` / `setSessionMicTuning`) with the OS preferences
+ * the settings store derives. Applications go through MicSessionManager; this
+ * class is an engine implementation detail.
  */
 
 import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
 
 import {createDebouncedPatchFlusher} from "../utils/debouncedPatch"
+import type {MicTuningProfile} from "./micPolicy"
 
 const LOG_TAG = "MIC_COORDINATOR"
 
@@ -24,6 +30,7 @@ interface GateOverride {
 interface ConfiguredMicGates {
   vadEnabled?: boolean | null
   loudnessGateEnabled?: boolean | null
+  micTuning?: Record<string, number> | null
 }
 
 /** Mic-requirement flips are debounced (300ms) and merged into one BLE write
@@ -49,15 +56,28 @@ class MicStateCoordinator {
   private localWantsPcm = false
   private localWantsLc3 = false
   /**
-   * A live ACS call taking the wearer's voice off the glasses over BLE LC3.
+   * A live microphone session held through MicSessionManager — a voice call today.
    *
    * Tracked separately from the miniapp requirement because the two have independent lifetimes:
    * the call miniapp does not subscribe to `audio_chunk`, and a captions miniapp that stops mid-call
    * must not take the call's microphone with it.
    */
-  private callWantsPcm = false
+  private sessionWantsPcm = false
   private configuredVad: boolean | undefined
   private configuredLoudnessGate: boolean | undefined
+  /** `mic_tuning` as the settings store last derived it: `super_mode ? desired : {}`. */
+  private configuredMicTuning: Record<string, number> = {}
+  /** Tuning required by the live sessions, resolved by micPolicy. */
+  private sessionMicTuning: MicTuningProfile | null = null
+  /**
+   * Latched once a session profile has actually been written.
+   *
+   * Before that, `mic_tuning` stays out of every patch, so a device that never
+   * runs a profile does not carry the key on unrelated mic writes. After it,
+   * the OS value keeps being restated, which is what stops a reconnect after a
+   * call from resurrecting the profile.
+   */
+  private sessionMicTuningWritten = false
   private readonly miniappVadOverrides = new Map<string, GateOverride>()
   private readonly miniappLoudnessGateOverrides = new Map<string, GateOverride>()
   private overrideSequence = 0
@@ -84,26 +104,69 @@ class MicStateCoordinator {
   }
 
   /**
-   * Claim or release raw PCM on behalf of an active call.
+   * Claim or release raw PCM on behalf of the live microphone sessions.
    *
-   * Called by AcsMeetingService around a call whose uplink is the glasses microphone over BLE LC3.
+   * MicSessionManager only. Applications acquire a session; they do not reach past it to here.
    * Releasing is a claim release, not a mic shutdown: if a captions miniapp still wants PCM the
    * microphone stays on, which is the whole reason this is a separate flag rather than a setter on
    * the local requirement.
    */
-  public setCallRequirement(pcm: boolean): void {
-    if (this.callWantsPcm === pcm) return
-    this.callWantsPcm = pcm
-    console.log(`${LOG_TAG}: call requirement updated — pcm=${pcm}`)
+  public setSessionRequirement(pcm: boolean): void {
+    if (this.sessionWantsPcm === pcm) return
+    this.sessionWantsPcm = pcm
+    console.log(`${LOG_TAG}: session requirement updated — pcm=${pcm}`)
     this.applyUnion()
   }
 
+  /**
+   * Apply or drop the tuning the live sessions require.
+   *
+   * MicSessionManager only. Rides `applyUnion` so the profile and the PCM claim land in one
+   * debounced write, resolved at flush time: a session released inside the debounce window wins
+   * over the value that was queued.
+   */
+  public setSessionMicTuning(profile: MicTuningProfile | null): void {
+    if (profile?.gain === this.sessionMicTuning?.gain) return
+    this.sessionMicTuning = profile
+    if (profile) this.sessionMicTuningWritten = true
+    // Nothing was ever written, so there is nothing to restore.
+    else if (!this.sessionMicTuningWritten) return
+    console.log(`${LOG_TAG}: session mic tuning ${profile ? JSON.stringify(profile) : "cleared"}`)
+    this.applyUnion()
+  }
+
+  /** Last session profile queued, or null when the OS value is in force. */
+  public getSessionMicTuning(): MicTuningProfile | null {
+    return this.sessionMicTuning
+  }
+
+  /**
+   * Super Mode sliders outrank a session profile. A live override means a gain
+   * sweep would write to the coordinator and the glasses would ignore it.
+   */
+  public hasConfiguredMicTuning(): boolean {
+    return Object.keys(this.configuredMicTuning).length > 0
+  }
+
   /**
    * Whether anything on this device needs a continuous raw-PCM timeline. Also the condition that
    * forces hardware VAD off: a gate that drops silence turns a call into clipped half-words.
    */
   private get wantsRawPcm(): boolean {
-    return this.localWantsPcm || this.callWantsPcm
+    return this.localWantsPcm || this.sessionWantsPcm
+  }
+
+  /**
+   * The session profile, but only when it wins.
+   *
+   * A live Super Mode tuning value outranks it: that screen is how a profile's numbers get found
+   * on a real call in the first place. Emptiness is by key count — the settings store hands back a
+   * fresh `{}` every time, so reference checks would never match.
+   */
+  private winningSessionMicTuning(): Record<string, number> | undefined {
+    if (!this.sessionMicTuning) return undefined
+    if (Object.keys(this.configuredMicTuning).length > 0) return undefined
+    return {...this.sessionMicTuning} as Record<string, number>
   }
 
   /**
@@ -168,6 +231,10 @@ class MicStateCoordinator {
           : undefined,
       loudnessGateEnabled:
         typeof settings.loudness_gate_enabled === "boolean" ? settings.loudness_gate_enabled : undefined,
+      micTuning:
+        settings.mic_tuning && typeof settings.mic_tuning === "object"
+          ? (settings.mic_tuning as Record<string, number>)
+          : undefined,
     })
 
     return this.applyActiveRuntimeOverrides(settings)
@@ -199,6 +266,12 @@ class MicStateCoordinator {
       runtimeSettings.loudness_gate_enabled = loudnessOverride.enabled
     }
 
+    // BES forgets mic_tuning on disconnect, so the on-connect replay is what
+    // puts a live session's profile back.
+    const sessionTuning = this.winningSessionMicTuning()
+    if (sessionTuning) runtimeSettings.mic_tuning = sessionTuning
+    else if (this.sessionMicTuningWritten) runtimeSettings.mic_tuning = this.configuredMicTuning
+
     return runtimeSettings
   }
 
@@ -235,6 +308,9 @@ class MicStateCoordinator {
     if (configured.loudnessGateEnabled !== undefined) {
       this.configuredLoudnessGate = configured.loudnessGateEnabled ?? undefined
     }
+    if (configured.micTuning !== undefined) {
+      this.configuredMicTuning = configured.micTuning ?? {}
+    }
   }
 
   private overridesFor(gate: MicGate): Map<string, GateOverride> {
@@ -265,6 +341,10 @@ class MicStateCoordinator {
       patch.loudness_gate_enabled = this.configuredLoudnessGate
     }
 
+    const sessionTuning = this.winningSessionMicTuning()
+    if (sessionTuning) patch.mic_tuning = sessionTuning
+    else if (this.sessionMicTuningWritten) patch.mic_tuning = this.configuredMicTuning
+
     return patch
   }
 
@@ -274,7 +354,8 @@ class MicStateCoordinator {
   public reset(): void {
     this.localWantsPcm = false
     this.localWantsLc3 = false
-    this.callWantsPcm = false
+    this.sessionWantsPcm = false
+    this.sessionMicTuning = null
     this.applyUnion()
   }