@mentra/engine 3.2.1-dev.278 → 3.2.1-dev.282

package/src/services/CallGainSweep.ts

@@ -0,0 +1,318 @@
+/**
+ * Timed A/B/A/C gain comparison for a live voice call.
+ *
+ * Mentra Live's last ADC step is +32 dB (index 15); the step below is +26 dB
+ * (14), then 2 dB per index. Close-talk clips at 15 and still rails at 14, so
+ * a call has to be measured at 15 → 14 → 15 → 13 on the same voice, not by
+ * swapping phones or days.
+ *
+ * Production policy stays in micPolicy. This object only writes a temporary
+ * override and logs speech-gated clip stats so a human can pick the index.
+ */
+
+import {PCM16_FULL_SCALE, pcm16WindowStats, type Pcm16Level} from "../utils/pcm16"
+
+const LOG_TAG = "CALL_GAIN_SWEEP"
+
+/** codec_adc_vol[] dB, same table as Super Mode. */
+const GAIN_DB = [-99, 0, 2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22, 24, 26, 32]
+
+export const CALL_GAIN_SWEEP_STEPS = [
+  {gain: 15, label: "15a"},
+  {gain: 14, label: "14"},
+  {gain: 15, label: "15b"},
+  {gain: 13, label: "13"},
+] as const
+
+export const CALL_GAIN_SWEEP_STEP_MS = 25_000
+/** Quiet room on this path is meanAbs ≈ 90–120. Talk starts well above this. */
+export const CALL_GAIN_SWEEP_SPEECH_MEAN_ABS = 400
+
+export type CallGainSweepStep = (typeof CALL_GAIN_SWEEP_STEPS)[number]
+
+export type CallGainSweepPhaseSummary = {
+  label: string
+  gain: number
+  db: number
+  windows: number
+  speechWindows: number
+  quietWindows: number
+  clippedWindows: number
+  nearClipWindows: number
+  speechMeanAbs: number
+  speechPeakMax: number
+  speechPeakPct: number
+  speechClipPct: number
+  speechNearClipPct: number
+  samples: number
+  speechSamples: number
+  clipped: number
+  nearClip: number
+}
+
+export type CallGainSweepRecommendation = {
+  gain: number
+  reason: string
+}
+
+export type CallGainSweepClock = {
+  now: () => number
+  setTimeout: (fn: () => void, ms: number) => unknown
+  clearTimeout: (id: unknown) => void
+  log: (...args: unknown[]) => void
+}
+
+type PhaseBucket = {
+  step: CallGainSweepStep
+  windows: number
+  speechWindows: number
+  quietWindows: number
+  clippedWindows: number
+  nearClipWindows: number
+  speechMeanAbsSum: number
+  speechPeakMax: number
+  samples: number
+  speechSamples: number
+  clipped: number
+  nearClip: number
+  speechClipped: number
+  speechNearClip: number
+}
+
+const defaultClock = (): CallGainSweepClock => ({
+  now: () => Date.now(),
+  setTimeout: (fn, ms) => setTimeout(fn, ms),
+  clearTimeout: (id) => clearTimeout(id as ReturnType<typeof setTimeout>),
+  log: (...args) => console.log(...args),
+})
+
+export function gainDb(index: number): number {
+  return GAIN_DB[index] ?? Number.NaN
+}
+
+/**
+ * Highest gain whose speech windows stay under the clip lines.
+ *
+ * Clip is the failure (rail = 32767). Near-clip at 30000 is the warning that
+ * the next syllable will hit the rail. 15 is only legal if both 15a and 15b
+ * agree; otherwise a loud stretch on one of them was luck.
+ */
+export function recommendCallGain(phases: readonly CallGainSweepPhaseSummary[]): CallGainSweepRecommendation {
+  const speech = phases.filter((p) => p.speechWindows > 0)
+  if (speech.length === 0) {
+    return {gain: 13, reason: "no speech windows; stay at 13 until the sweep is talked through"}
+  }
+
+  const fifteen = speech.filter((p) => p.gain === 15)
+  const fourteen = speech.find((p) => p.gain === 14)
+  const thirteen = speech.find((p) => p.gain === 13)
+
+  const clean = (p: CallGainSweepPhaseSummary) => p.speechClipPct < 0.5 && p.speechNearClipPct < 5
+  const fifteenClean = fifteen.length >= 2 && fifteen.every(clean)
+  if (fifteenClean) return {gain: 15, reason: "both 15 phases stayed under 0.5% clip / 5% near-clip"}
+  if (fourteen && clean(fourteen)) {
+    return {gain: 14, reason: "15 clips; 14 stayed under 0.5% clip / 5% near-clip"}
+  }
+  if (thirteen && clean(thirteen)) {
+    return {gain: 13, reason: "15 and 14 clip; 13 stayed under 0.5% clip / 5% near-clip"}
+  }
+  return {gain: 13, reason: "every measured step still clipped; 13 is the floor of this sweep"}
+}
+
+function emptyBucket(step: CallGainSweepStep): PhaseBucket {
+  return {
+    step,
+    windows: 0,
+    speechWindows: 0,
+    quietWindows: 0,
+    clippedWindows: 0,
+    nearClipWindows: 0,
+    speechMeanAbsSum: 0,
+    speechPeakMax: 0,
+    samples: 0,
+    speechSamples: 0,
+    clipped: 0,
+    nearClip: 0,
+    speechClipped: 0,
+    speechNearClip: 0,
+  }
+}
+
+function summarizeBucket(bucket: PhaseBucket): CallGainSweepPhaseSummary {
+  const speechClipPct =
+    bucket.speechSamples > 0 ? Math.round((bucket.speechClipped / bucket.speechSamples) * 1000) / 10 : 0
+  const speechNearClipPct =
+    bucket.speechSamples > 0 ? Math.round((bucket.speechNearClip / bucket.speechSamples) * 1000) / 10 : 0
+  return {
+    label: bucket.step.label,
+    gain: bucket.step.gain,
+    db: gainDb(bucket.step.gain),
+    windows: bucket.windows,
+    speechWindows: bucket.speechWindows,
+    quietWindows: bucket.quietWindows,
+    clippedWindows: bucket.clippedWindows,
+    nearClipWindows: bucket.nearClipWindows,
+    speechMeanAbs:
+      bucket.speechWindows > 0 ? Math.round(bucket.speechMeanAbsSum / bucket.speechWindows) : 0,
+    speechPeakMax: bucket.speechPeakMax,
+    speechPeakPct: Math.round((bucket.speechPeakMax / PCM16_FULL_SCALE) * 1000) / 10,
+    speechClipPct,
+    speechNearClipPct,
+    samples: bucket.samples,
+    speechSamples: bucket.speechSamples,
+    clipped: bucket.clipped,
+    nearClip: bucket.nearClip,
+  }
+}
+
+export class CallGainSweep {
+  private readonly clock: CallGainSweepClock
+  private applyGain: ((gain: number) => void) | null = null
+  private onDone: (() => void) | null = null
+  private index = -1
+  private timer: unknown = null
+  private enteredAt = 0
+  private bucket: PhaseBucket | null = null
+  private readonly finished: CallGainSweepPhaseSummary[] = []
+
+  constructor(clock: CallGainSweepClock = defaultClock()) {
+    this.clock = clock
+  }
+
+  isActive(): boolean {
+    return this.index >= 0
+  }
+
+  currentGain(): number | null {
+    return this.index >= 0 ? CALL_GAIN_SWEEP_STEPS[this.index].gain : null
+  }
+
+  currentLabel(): string | null {
+    return this.index >= 0 ? CALL_GAIN_SWEEP_STEPS[this.index].label : null
+  }
+
+  /**
+   * Begin the 15 → 14 → 15 → 13 walk.
+   * Returns false when a sweep is already mid-phase so a recompute cannot reset the clock.
+   */
+  start(applyGain: (gain: number) => void, onDone?: () => void): boolean {
+    if (this.isActive()) return false
+    this.applyGain = applyGain
+    this.onDone = onDone ?? null
+    this.finished.length = 0
+    this.enter(0)
+    return true
+  }
+
+  /** Super Mode / explicit re-run. Aborts the current phase if one is live. */
+  restart(applyGain: (gain: number) => void, onDone?: () => void): boolean {
+    if (this.isActive()) this.stop("restart")
+    return this.start(applyGain, onDone)
+  }
+
+  stop(reason: string): void {
+    if (!this.isActive() && this.timer == null) return
+    this.closePhase("aborted")
+    this.clearTimer()
+    this.clock.log(`${LOG_TAG} stop`, {reason, phases: this.finished.slice()})
+    this.index = -1
+    this.bucket = null
+    this.applyGain = null
+    this.onDone = null
+  }
+
+  ingest(level: Pcm16Level): void {
+    if (!this.bucket) return
+    const stats = pcm16WindowStats(level)
+    const speech = level.meanAbs >= CALL_GAIN_SWEEP_SPEECH_MEAN_ABS
+    this.bucket.windows++
+    this.bucket.samples += level.samples
+    this.bucket.clipped += level.clipped
+    this.bucket.nearClip += level.nearClip
+    if (speech) {
+      this.bucket.speechWindows++
+      this.bucket.speechSamples += level.samples
+      this.bucket.speechClipped += level.clipped
+      this.bucket.speechNearClip += level.nearClip
+      this.bucket.speechMeanAbsSum += level.meanAbs
+      if (level.peak > this.bucket.speechPeakMax) this.bucket.speechPeakMax = level.peak
+    } else {
+      this.bucket.quietWindows++
+    }
+    if (level.clipped > 0) this.bucket.clippedWindows++
+    if (level.nearClip > 0) this.bucket.nearClipWindows++
+
+    this.clock.log(`${LOG_TAG} window`, {
+      label: this.bucket.step.label,
+      gain: this.bucket.step.gain,
+      db: gainDb(this.bucket.step.gain),
+      speech,
+      meanAbs: stats.meanAbs,
+      peak: stats.peak,
+      peakPct: stats.peakPct,
+      clipped: stats.clipped,
+      clipPct: stats.clipPct,
+      nearClip: stats.nearClip,
+      nearClipPct: stats.nearClipPct,
+      samples: stats.samples,
+    })
+    // RN pauses setTimeout while Mentra is behind Mentra Call. The ACS
+    // uplink still delivers 1 s windows, so the hold is measured here.
+    if (this.clock.now() - this.enteredAt >= CALL_GAIN_SWEEP_STEP_MS) this.advance()
+  }
+
+  private enter(index: number): void {
+    this.index = index
+    const step = CALL_GAIN_SWEEP_STEPS[index]
+    this.bucket = emptyBucket(step)
+    this.enteredAt = this.clock.now()
+    this.applyGain?.(step.gain)
+    this.clock.log(`${LOG_TAG} phase-start`, {
+      label: step.label,
+      gain: step.gain,
+      db: gainDb(step.gain),
+      holdMs: CALL_GAIN_SWEEP_STEP_MS,
+      remaining: CALL_GAIN_SWEEP_STEPS.length - index,
+    })
+    this.timer = this.clock.setTimeout(() => this.advance(), CALL_GAIN_SWEEP_STEP_MS)
+  }
+
+  private advance(): void {
+    this.timer = null
+    this.closePhase("complete")
+    const next = this.index + 1
+    if (next >= CALL_GAIN_SWEEP_STEPS.length) {
+      const pick = recommendCallGain(this.finished)
+      this.clock.log(`${LOG_TAG} done`, {phases: this.finished.slice(), pick})
+      this.index = -1
+      this.bucket = null
+      const done = this.onDone
+      this.applyGain = null
+      this.onDone = null
+      done?.()
+      return
+    }
+    this.enter(next)
+  }
+
+  private closePhase(how: "complete" | "aborted"): void {
+    if (!this.bucket || this.bucket.windows === 0) return
+    const summary = summarizeBucket(this.bucket)
+    this.finished.push(summary)
+    this.clock.log(`${LOG_TAG} phase-${how}`, summary)
+    this.bucket = null
+  }
+
+  private clearTimer(): void {
+    if (this.timer == null) return
+    this.clock.clearTimeout(this.timer)
+    this.timer = null
+  }
+}
+
+const sharedSweep = new CallGainSweep()
+
+/** Process-wide sweep. MicSessionManager writes it; the ACS uplink meters it. */
+export function getCallGainSweep(): CallGainSweep {
+  return sharedSweep
+}

package/src/services/GlassesMicProbe.ts

@@ -12,7 +12,7 @@
 import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
 
 import audioPlaybackService from "./AudioPlaybackService"
-import micStateCoordinator from "./MicStateCoordinator"
+import micSessionManager, {type MicSession} from "./MicSessionManager"
 import {SETTINGS, useSettingsStore} from "../stores/settings"
 import {summarizePcm16} from "../utils/pcm16"
 import {BgTimer} from "../utils/timers"
@@ -85,6 +85,8 @@ export type MicProbeSample = {
 type Listener = (sample: MicProbeSample) => void
 
 const GLASSES = "glasses"
+/** Lease owner for probe runs. Engine features own their sessions; miniapps cannot claim this. */
+const MIC_PROBE_OWNER = "engine:mic-probe"
 const A2DP_RATE = 16000
 const A2DP_CHUNK_MS = 60
 const TONE_HZ = 440
@@ -133,6 +135,8 @@ class GlassesMicProbe {
   private nonGlasses = 0
   /** `preferred_mic` before a `source=phone` control run changed it. */
   private savedPreferredMic: string | null = null
+  /** The probe's microphone lease, which owns the pin and the PCM claim while a run is live. */
+  private micSession: MicSession | null = null
   private listeners = new Set<Listener>()
   private lastSample: MicProbeSample | null = null
 
@@ -164,21 +168,22 @@ class GlassesMicProbe {
     const source = options.source ?? GLASSES
     console.log("[MIC_PROBE] start", options)
 
-    if (source === GLASSES) {
-      // Same order as AcsMeetingService.startGlassesMicUplink: pin first so the first frame the
-      // requirement produces is already from the glasses and the phone mic is never opened.
-      await Promise.resolve(BluetoothSdk.setMicSourcePin?.(GLASSES)).catch((error) => {
-        console.warn("[MIC_PROBE] pin failed", error)
-      })
-    } else {
-      // Control run: no pin (only the glasses can be pinned); steer the ranking with the
-      // user preference and put it back on stop.
+    if (source !== GLASSES) {
+      // Control run: the manager cannot pin a phone (only the glasses can be pinned), so steer the
+      // ranking with the user preference and put it back on stop. That is probe behaviour, not mic
+      // policy, which is why it stays here rather than moving into MicSessionManager.
       const settings = useSettingsStore.getState()
       this.savedPreferredMic = settings.getSetting(SETTINGS.preferred_mic.key) ?? "auto"
       await settings.setSetting(SETTINGS.preferred_mic.key, source, false)
     }
     if (this.generation !== generation) return
-    micStateCoordinator.setCallRequirement(true)
+    // `diagnostic` carries no tuning profile on purpose: the probe has to measure the gain users
+    // actually get, not one it asked for.
+    this.micSession = micSessionManager.acquire({
+      owner: MIC_PROBE_OWNER,
+      source: source === GLASSES ? "glasses" : "phone",
+      useCase: "diagnostic",
+    })
     this.micSub = BluetoothSdk.addListener("mic_pcm", (event: {pcm?: unknown; source?: string}) => {
       this.lastSource = event.source ?? ""
       if (event.source !== source) {
@@ -206,13 +211,11 @@ class GlassesMicProbe {
     this.report()
     this.micSub?.remove()
     this.micSub = null
-    micStateCoordinator.setCallRequirement(false)
+    // Releasing the lease is what unpins the glasses and drops the PCM claim.
+    this.micSession?.release()
+    this.micSession = null
     this.stopping = (async () => {
-      if ((this.options?.source ?? GLASSES) === GLASSES) {
-        await Promise.resolve(BluetoothSdk.setMicSourcePin?.(null)).catch((error) => {
-          console.warn("[MIC_PROBE] unpin failed", error)
-        })
-      } else if (this.savedPreferredMic !== null) {
+      if ((this.options?.source ?? GLASSES) !== GLASSES && this.savedPreferredMic !== null) {
         const restore = this.savedPreferredMic
         this.savedPreferredMic = null
         await useSettingsStore.getState().setSetting(SETTINGS.preferred_mic.key, restore, false)

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),