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

package/build/utils/pcm16.js

@@ -28,11 +28,28 @@ export function pcmDataView(frame) {
     }
     return null;
 }
+/** Signed 16-bit full scale. `-32768` abs-counts as 32768 and is also a rail. */
+export const PCM16_FULL_SCALE = 32767;
+/** Headroom line: loud speech that is not yet hard-clipped. */
+export const PCM16_NEAR_CLIP = 30000;
+/** Percentages for a closed window. Zero samples → all percents 0. */
+export function pcm16WindowStats(level) {
+    const denom = level.samples || 1;
+    const pct = (count) => Math.round((count / denom) * 1000) / 10;
+    return {
+        ...level,
+        peakPct: Math.round((level.peak / PCM16_FULL_SCALE) * 1000) / 10,
+        clipPct: level.samples ? pct(level.clipped) : 0,
+        nearClipPct: level.samples ? pct(level.nearClip) : 0,
+    };
+}
 /** Level statistics over a batch of PCM16 frames. Unreadable frames are skipped, never thrown on. */
 export function summarizePcm16(frames) {
     let sum = 0;
     let peak = 0;
     let samples = 0;
+    let clipped = 0;
+    let nearClip = 0;
     for (const frame of frames) {
         const view = pcmDataView(frame);
         if (!view)
@@ -43,10 +60,14 @@ export function summarizePcm16(frames) {
             sum += v;
             if (v > peak)
                 peak = v;
+            if (v >= PCM16_FULL_SCALE)
+                clipped++;
+            if (v >= PCM16_NEAR_CLIP)
+                nearClip++;
         }
         samples += n;
     }
-    return { meanAbs: samples ? Math.round(sum / samples) : 0, peak, samples };
+    return { meanAbs: samples ? Math.round(sum / samples) : 0, peak, samples, clipped, nearClip };
 }
 /**
  * Incremental accumulator for the same statistics, for hot paths that see one frame at a time
@@ -56,6 +77,8 @@ export class Pcm16LevelMeter {
     sum = 0;
     peakValue = 0;
     count = 0;
+    clipped = 0;
+    nearClip = 0;
     add(frame) {
         const view = pcmDataView(frame);
         if (!view)
@@ -66,6 +89,10 @@ export class Pcm16LevelMeter {
             this.sum += v;
             if (v > this.peakValue)
                 this.peakValue = v;
+            if (v >= PCM16_FULL_SCALE)
+                this.clipped++;
+            if (v >= PCM16_NEAR_CLIP)
+                this.nearClip++;
         }
         this.count += n;
     }
@@ -75,10 +102,14 @@ export class Pcm16LevelMeter {
             meanAbs: this.count ? Math.round(this.sum / this.count) : 0,
             peak: this.peakValue,
             samples: this.count,
+            clipped: this.clipped,
+            nearClip: this.nearClip,
         };
         this.sum = 0;
         this.peakValue = 0;
         this.count = 0;
+        this.clipped = 0;
+        this.nearClip = 0;
         return level;
     }
 }

package/build/utils/pcm16.js.map

@@ -1 +1 @@
-{"version":3,"file":"pcm16.js","sourceRoot":"","sources":["../../src/utils/pcm16.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Level statistics for 16-bit little-endian mono PCM, as delivered by `mic_pcm`.\n *\n * Shared by the call uplink and the dev mic probe so both report the same number: a soak that\n * says `meanAbs=40` in one log and `meanAbs=40` in the other is measuring the same thing.\n */\n\n/**\n * Hermes / the Expo bridge delivers `mic_pcm.pcm` as a Uint8Array, not an ArrayBuffer.\n * `new DataView(uint8Array)` throws `buffer must be an ArrayBuffer` — that is the redbox\n * attributed to whatever screen happens to be up (wifi scan, home, …).\n */\nexport function pcmDataView(frame: unknown): DataView | null {\n  if (frame instanceof ArrayBuffer) {\n    return new DataView(frame)\n  }\n  if (ArrayBuffer.isView(frame)) {\n    try {\n      return new DataView(frame.buffer, frame.byteOffset, frame.byteLength)\n    } catch {\n      const copy = Uint8Array.from(frame as unknown as ArrayLike<number>)\n      return new DataView(copy.buffer)\n    }\n  }\n  if (Array.isArray(frame)) {\n    const copy = Uint8Array.from(frame)\n    return new DataView(copy.buffer)\n  }\n  return null\n}\n\nexport type Pcm16Level = {\n  /** Mean absolute sample value (16-bit scale). ~30–60 is a quiet room on Mentra Live LC3. */\n  meanAbs: number\n  /** Largest absolute sample. */\n  peak: number\n  /** Samples counted. */\n  samples: number\n}\n\n/** Level statistics over a batch of PCM16 frames. Unreadable frames are skipped, never thrown on. */\nexport function summarizePcm16(frames: unknown[]): Pcm16Level {\n  let sum = 0\n  let peak = 0\n  let samples = 0\n  for (const frame of frames) {\n    const view = pcmDataView(frame)\n    if (!view) continue\n    const n = Math.floor(view.byteLength / 2)\n    for (let i = 0; i < n; i++) {\n      const v = Math.abs(view.getInt16(i * 2, true))\n      sum += v\n      if (v > peak) peak = v\n    }\n    samples += n\n  }\n  return {meanAbs: samples ? Math.round(sum / samples) : 0, peak, samples}\n}\n\n/**\n * Incremental accumulator for the same statistics, for hot paths that see one frame at a time\n * and report once a window (the call uplink logs every 5 s at 20 frames/s).\n */\nexport class Pcm16LevelMeter {\n  private sum = 0\n  private peakValue = 0\n  private count = 0\n\n  add(frame: unknown): void {\n    const view = pcmDataView(frame)\n    if (!view) return\n    const n = Math.floor(view.byteLength / 2)\n    for (let i = 0; i < n; i++) {\n      const v = Math.abs(view.getInt16(i * 2, true))\n      this.sum += v\n      if (v > this.peakValue) this.peakValue = v\n    }\n    this.count += n\n  }\n\n  /** Read the window and start a new one. */\n  take(): Pcm16Level {\n    const level = {\n      meanAbs: this.count ? Math.round(this.sum / this.count) : 0,\n      peak: this.peakValue,\n      samples: this.count,\n    }\n    this.sum = 0\n    this.peakValue = 0\n    this.count = 0\n    return level\n  }\n}\n"]}
+{"version":3,"file":"pcm16.js","sourceRoot":"","sources":["../../src/utils/pcm16.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;QACjC,OAAO,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAA;IAC5B,CAAC;IACD,IAAI,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,IAAI,CAAC;YACH,OAAO,IAAI,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,UAAU,CAAC,CAAA;QACvE,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,KAAqC,CAAC,CAAA;YACnE,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAClC,CAAC;IACH,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACnC,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IAClC,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED,iFAAiF;AACjF,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,CAAA;AACrC,+DAA+D;AAC/D,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,CAAA;AAwBpC,sEAAsE;AACtE,MAAM,UAAU,gBAAgB,CAAC,KAAiB;IAChD,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,IAAI,CAAC,CAAA;IAChC,MAAM,GAAG,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG,KAAK,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;IACtE,OAAO;QACL,GAAG,KAAK;QACR,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,IAAI,GAAG,gBAAgB,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE;QAChE,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/C,WAAW,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;KACrD,CAAA;AACH,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,cAAc,CAAC,MAAiB;IAC9C,IAAI,GAAG,GAAG,CAAC,CAAA;IACX,IAAI,IAAI,GAAG,CAAC,CAAA;IACZ,IAAI,OAAO,GAAG,CAAC,CAAA;IACf,IAAI,OAAO,GAAG,CAAC,CAAA;IACf,IAAI,QAAQ,GAAG,CAAC,CAAA;IAChB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,CAAA;QAC/B,IAAI,CAAC,IAAI;YAAE,SAAQ;QACnB,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC,CAAA;QACzC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC3B,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC,CAAA;YAC9C,GAAG,IAAI,CAAC,CAAA;YACR,IAAI,CAAC,GAAG,IAAI;gBAAE,IAAI,GAAG,CAAC,CAAA;YACtB,IAAI,CAAC,IAAI,gBAAgB;gBAAE,OAAO,EAAE,CAAA;YACpC,IAAI,CAAC,IAAI,eAAe;gBAAE,QAAQ,EAAE,CAAA;QACtC,CAAC;QACD,OAAO,IAAI,CAAC,CAAA;IACd,CAAC;IACD,OAAO,EAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAC,CAAA;AAC7F,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,eAAe;IAClB,GAAG,GAAG,CAAC,CAAA;IACP,SAAS,GAAG,CAAC,CAAA;IACb,KAAK,GAAG,CAAC,CAAA;IACT,OAAO,GAAG,CAAC,CAAA;IACX,QAAQ,GAAG,CAAC,CAAA;IAEpB,GAAG,CAAC,KAAc;QAChB,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,CAAA;QAC/B,IAAI,CAAC,IAAI;YAAE,OAAM;QACjB,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC,CAAA;QACzC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC3B,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC,CAAA;YAC9C,IAAI,CAAC,GAAG,IAAI,CAAC,CAAA;YACb,IAAI,CAAC,GAAG,IAAI,CAAC,SAAS;gBAAE,IAAI,CAAC,SAAS,GAAG,CAAC,CAAA;YAC1C,IAAI,CAAC,IAAI,gBAAgB;gBAAE,IAAI,CAAC,OAAO,EAAE,CAAA;YACzC,IAAI,CAAC,IAAI,eAAe;gBAAE,IAAI,CAAC,QAAQ,EAAE,CAAA;QAC3C,CAAC;QACD,IAAI,CAAC,KAAK,IAAI,CAAC,CAAA;IACjB,CAAC;IAED,2CAA2C;IAC3C,IAAI;QACF,MAAM,KAAK,GAAG;YACZ,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YAC3D,IAAI,EAAE,IAAI,CAAC,SAAS;YACpB,OAAO,EAAE,IAAI,CAAC,KAAK;YACnB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,QAAQ,EAAE,IAAI,CAAC,QAAQ;SACxB,CAAA;QACD,IAAI,CAAC,GAAG,GAAG,CAAC,CAAA;QACZ,IAAI,CAAC,SAAS,GAAG,CAAC,CAAA;QAClB,IAAI,CAAC,KAAK,GAAG,CAAC,CAAA;QACd,IAAI,CAAC,OAAO,GAAG,CAAC,CAAA;QAChB,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAA;QACjB,OAAO,KAAK,CAAA;IACd,CAAC;CACF","sourcesContent":["/**\n * Level statistics for 16-bit little-endian mono PCM, as delivered by `mic_pcm`.\n *\n * Shared by the call uplink and the dev mic probe so both report the same number: a soak that\n * says `meanAbs=40` in one log and `meanAbs=40` in the other is measuring the same thing.\n */\n\n/**\n * Hermes / the Expo bridge delivers `mic_pcm.pcm` as a Uint8Array, not an ArrayBuffer.\n * `new DataView(uint8Array)` throws `buffer must be an ArrayBuffer` — that is the redbox\n * attributed to whatever screen happens to be up (wifi scan, home, …).\n */\nexport function pcmDataView(frame: unknown): DataView | null {\n  if (frame instanceof ArrayBuffer) {\n    return new DataView(frame)\n  }\n  if (ArrayBuffer.isView(frame)) {\n    try {\n      return new DataView(frame.buffer, frame.byteOffset, frame.byteLength)\n    } catch {\n      const copy = Uint8Array.from(frame as unknown as ArrayLike<number>)\n      return new DataView(copy.buffer)\n    }\n  }\n  if (Array.isArray(frame)) {\n    const copy = Uint8Array.from(frame)\n    return new DataView(copy.buffer)\n  }\n  return null\n}\n\n/** Signed 16-bit full scale. `-32768` abs-counts as 32768 and is also a rail. */\nexport const PCM16_FULL_SCALE = 32767\n/** Headroom line: loud speech that is not yet hard-clipped. */\nexport const PCM16_NEAR_CLIP = 30000\n\nexport type Pcm16Level = {\n  /** Mean absolute sample value (16-bit scale). ~30–60 is a quiet room on Mentra Live LC3. */\n  meanAbs: number\n  /** Largest absolute sample. */\n  peak: number\n  /** Samples counted. */\n  samples: number\n  /** Samples at the int16 rail (`>= 32767`). */\n  clipped: number\n  /** Samples at or above [PCM16_NEAR_CLIP]. */\n  nearClip: number\n}\n\nexport type Pcm16WindowStats = Pcm16Level & {\n  /** `peak / 32767`, percent. */\n  peakPct: number\n  /** `clipped / samples`, percent. */\n  clipPct: number\n  /** `nearClip / samples`, percent. */\n  nearClipPct: number\n}\n\n/** Percentages for a closed window. Zero samples → all percents 0. */\nexport function pcm16WindowStats(level: Pcm16Level): Pcm16WindowStats {\n  const denom = level.samples || 1\n  const pct = (count: number) => Math.round((count / denom) * 1000) / 10\n  return {\n    ...level,\n    peakPct: Math.round((level.peak / PCM16_FULL_SCALE) * 1000) / 10,\n    clipPct: level.samples ? pct(level.clipped) : 0,\n    nearClipPct: level.samples ? pct(level.nearClip) : 0,\n  }\n}\n\n/** Level statistics over a batch of PCM16 frames. Unreadable frames are skipped, never thrown on. */\nexport function summarizePcm16(frames: unknown[]): Pcm16Level {\n  let sum = 0\n  let peak = 0\n  let samples = 0\n  let clipped = 0\n  let nearClip = 0\n  for (const frame of frames) {\n    const view = pcmDataView(frame)\n    if (!view) continue\n    const n = Math.floor(view.byteLength / 2)\n    for (let i = 0; i < n; i++) {\n      const v = Math.abs(view.getInt16(i * 2, true))\n      sum += v\n      if (v > peak) peak = v\n      if (v >= PCM16_FULL_SCALE) clipped++\n      if (v >= PCM16_NEAR_CLIP) nearClip++\n    }\n    samples += n\n  }\n  return {meanAbs: samples ? Math.round(sum / samples) : 0, peak, samples, clipped, nearClip}\n}\n\n/**\n * Incremental accumulator for the same statistics, for hot paths that see one frame at a time\n * and report once a window (the call uplink logs every 5 s at 20 frames/s).\n */\nexport class Pcm16LevelMeter {\n  private sum = 0\n  private peakValue = 0\n  private count = 0\n  private clipped = 0\n  private nearClip = 0\n\n  add(frame: unknown): void {\n    const view = pcmDataView(frame)\n    if (!view) return\n    const n = Math.floor(view.byteLength / 2)\n    for (let i = 0; i < n; i++) {\n      const v = Math.abs(view.getInt16(i * 2, true))\n      this.sum += v\n      if (v > this.peakValue) this.peakValue = v\n      if (v >= PCM16_FULL_SCALE) this.clipped++\n      if (v >= PCM16_NEAR_CLIP) this.nearClip++\n    }\n    this.count += n\n  }\n\n  /** Read the window and start a new one. */\n  take(): Pcm16Level {\n    const level = {\n      meanAbs: this.count ? Math.round(this.sum / this.count) : 0,\n      peak: this.peakValue,\n      samples: this.count,\n      clipped: this.clipped,\n      nearClip: this.nearClip,\n    }\n    this.sum = 0\n    this.peakValue = 0\n    this.count = 0\n    this.clipped = 0\n    this.nearClip = 0\n    return level\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentra/engine",
-  "version": "3.2.1-dev.278",
+  "version": "3.2.1-dev.282",
   "description": "Mentra Engine — miniapp registry, WebView bridge, and miniapp store",
   "main": "build/index.js",
   "react-native": "src/index.ts",
@@ -97,13 +97,13 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@mentra/acs-meeting": "3.2.1-dev.278",
-    "@mentra/glasses-media": "3.2.1-dev.278",
-    "@mentra/bluetooth-sdk": "3.2.1-dev.278",
-    "@mentra/cloud-client": "3.2.1-dev.278",
-    "@mentra/cloud-protocol": "3.2.1-dev.278",
-    "@mentra/crust": "3.2.1-dev.278",
-    "@mentra/miniapp": "3.2.1-dev.278",
+    "@mentra/acs-meeting": "3.2.1-dev.282",
+    "@mentra/glasses-media": "3.2.1-dev.282",
+    "@mentra/bluetooth-sdk": "3.2.1-dev.282",
+    "@mentra/cloud-client": "3.2.1-dev.282",
+    "@mentra/cloud-protocol": "3.2.1-dev.282",
+    "@mentra/crust": "3.2.1-dev.282",
+    "@mentra/miniapp": "3.2.1-dev.282",
     "buffer": "^6.0.3",
     "events": "^3.3.0",
     "react-native-marked": "8.1.1",

package/src/generated/releaseMetadata.ts

@@ -12,9 +12,9 @@ export interface EngineReleaseMetadata {
 export const ENGINE_RELEASE_METADATA: Readonly<EngineReleaseMetadata> = Object.freeze({
   "schemaVersion": 1,
   "familyBaseVersion": "3.2.1",
-  "releaseIdentity": "3.2.1-dev.278",
-  "releaseSetId": "mentra-3.2.1-dev.278",
-  "sourceCommit": "3fdfe01c096c79797d51fdef608ddb8ed91e14c3",
-  "otaManifestUrl": "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.2.1/mentra-live-ota-3.2.1-dev.278.json",
-  "otaManifestSha256": "1ab2a29845eb5b865b15ad16e2006d34a2f9590dcade5bf085722c4aba0ca978"
+  "releaseIdentity": "3.2.1-dev.282",
+  "releaseSetId": "mentra-3.2.1-dev.282",
+  "sourceCommit": "53defbe045377507bdd6c188d303be138040c450",
+  "otaManifestUrl": "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.2.1/mentra-live-ota-3.2.1-dev.282.json",
+  "otaManifestSha256": "c69e779261aac872c9b0a26abbdb2d7e6549db577ee4bf0755adf770d8f879f6"
 })

package/src/services/AcsMeetingService.ts

@@ -9,9 +9,12 @@ import {Platform} from "react-native"
 import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
 
 import audioPlaybackService from "./AudioPlaybackService"
+import {getCallGainSweep} from "./CallGainSweep"
 import micStateCoordinator from "./MicStateCoordinator"
+import micSessionManager, {type MicSession} from "./MicSessionManager"
+import {ENGINE_OWNER_PREFIX} from "./micPolicy"
 import {SETTINGS, useSettingsStore} from "../stores/settings"
-import {Pcm16LevelMeter} from "../utils/pcm16"
+import {Pcm16LevelMeter, pcm16WindowStats} from "../utils/pcm16"
 import {softapTrace, softapTraceFailure, softapTraceId} from "../utils/softapTrace"
 import {ACS_CALL_MIC, type AcsAudioSource, type ResolvedAudioSource, type SourceReason} from "./acsAudioSource"
 import type {SoftapProgress} from "./SoftapCallTransport"
@@ -204,8 +207,13 @@ export function glassesLc3UplinkSupported(args: {
   audioSource: AcsAudioSource
   hasPushOutgoingPcm: boolean
   platform: string
+  /** Somebody holds a glasses microphone session through MicSessionManager. */
+  glassesSession: boolean
 }): boolean {
   if (!(softapBleLc3UplinkForTests ?? SOFTAP_BLE_LC3_UPLINK)) return false
+  // The microphone belongs to whoever leased it. Without a lease nothing has pinned the glasses
+  // or claimed raw PCM, so this call has no wearer audio to read off them.
+  if (!args.glassesSession) return false
   // iOS has no `setMicSourcePin` yet, so it cannot promise the phone microphone stays shut.
   if (args.platform !== "android") return false
   // WHEP audio comes back from Cloudflare already mixed into the subscribed track; there is no
@@ -537,6 +545,8 @@ const GLASSES_MIC_SOURCE = "glasses"
 const GLASSES_MIC_GRACE_MS = 1000
 /** Cadence of the uplink health line, matching the native P8 ladder. */
 const MIC_UPLINK_LOG_INTERVAL_MS = 5000
+/** During a gain sweep, one-second windows so each 25 s phase has enough speech samples. */
+const MIC_UPLINK_SWEEP_LOG_INTERVAL_MS = 1000
 /** A 50 ms LC3 frame arriving more than this late is a missed beat, not jitter. */
 const MIC_GAP_WARN_MS = 90
 
@@ -612,6 +622,17 @@ class AcsMeetingService {
   private callOrigin: AcsCallOrigin = "unknown"
   private micTransport: MicTransport = "whip"
   private micSub: {remove: () => void} | null = null
+  /** Backstop lease, held only while this call is actually reading the glasses mic. */
+  private micSession: MicSession | null = null
+  private micTuningSub: {remove: () => void} | null = null
+  private micRmsSub: {remove: () => void} | null = null
+  /** Only turn telemetry off again if this call is what turned it on. */
+  private micRmsEnabled = false
+  private gateSamples = 0
+  private gateClosed = 0
+  private gateElevated = 0
+  private gateClosedElevated = 0
+  private gateRmsMax = 0
   /** True between the pin/requirement being taken and released, so release is exactly once. */
   private micUplinkActive = false
   private micFramesForwarded = 0
@@ -972,6 +993,12 @@ class AcsMeetingService {
       displayName?: string
       video?: AcsOutgoingVideo
       origin?: AcsCallOrigin
+      /**
+       * Whether the caller holds a glasses microphone session. The uplink is the wearer's voice,
+       * so it is only taken off the glasses when somebody has actually claimed that microphone
+       * through MicSessionManager; this class never claims it itself.
+       */
+      glassesSession?: boolean
     },
   ): Promise<MeetingState> {
     const native = getNative()
@@ -998,6 +1025,7 @@ class AcsMeetingService {
       audioSource: resolved.source,
       hasPushOutgoingPcm: typeof native.pushOutgoingPcm === "function",
       platform: Platform.OS,
+      glassesSession: args.glassesSession ?? false,
     })
     this.micTransport = lc3Uplink ? "ble-lc3" : resolved.source === "phone" ? "phone" : "whip"
     this.bindNative(native, packageName)
@@ -1287,11 +1315,15 @@ class AcsMeetingService {
   /**
    * Start forwarding the glasses microphone into ACS for this call.
    *
-   * Order matters and is the whole point: pin the Bluetooth SDK to the glasses *before* asking it
-   * for PCM, so the first frame the mic requirement produces is already from the right source and
-   * the phone microphone is never opened even for one buffer. `generation` is captured by the
-   * listener so a frame that lands after this call ended is dropped rather than pushed at a native
-   * session that has left the meeting.
+   * This class is a sink: it never names a gain, a pin or a setting. It does take a semantic
+   * voice_call lease first, because reading the glasses mic without one is what put this call on
+   * the OS default of VAD-on — a speech gate that drops the wearer's uplink whenever the GX8002
+   * disagrees, which during a call is most of the time the far end is talking. The lease is a
+   * backstop: when the miniapp already holds one this simply merges with it, and micPolicy still
+   * decides what voice_call means for the hardware.
+   *
+   * `generation` is captured by the listener so a frame that lands after this call ended is
+   * dropped rather than pushed at a native session that has left the meeting.
    */
   private startGlassesMicUplink(generation: number): void {
     if (this.micTransport !== "ble-lc3") return
@@ -1310,11 +1342,9 @@ class AcsMeetingService {
     this.micLevel.take()
     this.lastMicLevel = null
     try {
-      void Promise.resolve(BluetoothSdk.setMicSourcePin?.(GLASSES_MIC_SOURCE)).catch((error) => {
-        console.warn("[AcsMeeting] pinning the glasses microphone failed", error)
-      })
+      this.acquireMicSession()
+      this.startMicGateTelemetry()
       this.micUplinkActive = true
-      micStateCoordinator.setCallRequirement(true)
       this.micSub = BluetoothSdk.addListener("mic_pcm", (event: {pcm?: ArrayBuffer; sampleRate?: number; source?: string}) => {
         if (generation !== this.callGeneration) {
           this.micDropsStale += 1
@@ -1362,29 +1392,132 @@ class AcsMeetingService {
     }
   }
 
-  /** Release the microphone claims this call took. Safe to call when it never took them. */
+  /**
+   * Stop reading the glasses microphone. Safe to call when this call never started.
+   *
+   * Only this call's own backstop lease is dropped. A lease the miniapp took is its to release,
+   * and letting go of ours before that owner releases is what keeps a normal hang-up from looking
+   * like the wearer's microphone disappearing.
+   */
   private stopGlassesMicUplink(): void {
     this.micSub?.remove()
     this.micSub = null
+    this.releaseMicSession()
     if (this.micUplinkActive) {
       this.micUplinkActive = false
-      micStateCoordinator.setCallRequirement(false)
-      // Last, and unconditionally: while the pin is set no other consumer can pick a microphone,
-      // so leaving it behind would leave captions and the cloud uplink stuck on the glasses.
-      void Promise.resolve(BluetoothSdk.setMicSourcePin?.(null)).catch((error) => {
-        console.warn("[AcsMeeting] releasing the glasses microphone pin failed", error)
-      })
       console.log("[AcsMeeting] phase=glasses-mic-uplink-stop", {
         frames: this.micFramesForwarded,
         dropsStale: this.micDropsStale,
         dropsNonGlasses: this.micDropsNonGlasses,
         gaps: this.micGaps,
         gapMsMax: this.micGapMsMax,
+        ...this.gateSummary(),
       })
     }
+    this.stopMicGateTelemetry()
     this.micTransport = "whip"
   }
 
+  /**
+   * Watch what the glasses are actually running for the length of the call.
+   *
+   * Two different questions, both unanswerable from this side otherwise. `mic_tuning_state` is
+   * the post-clamp reply, so it catches a profile the firmware rewrote rather than accepted.
+   * `mic_rms` carries the Barrier's own verdict per frame, which is the only way to tell a gate
+   * that is suppressing speaker leak from one that is suppressing the wearer.
+   */
+  private startMicGateTelemetry(): void {
+    this.gateSamples = 0
+    this.gateClosed = 0
+    this.gateElevated = 0
+    this.gateClosedElevated = 0
+    this.gateRmsMax = 0
+
+    try {
+      this.micTuningSub = BluetoothSdk.addListener("mic_tuning_state", (event: Record<string, unknown>) => {
+        console.log("[AcsMeeting] phase=glasses-mic-tuning-applied", event)
+      })
+      this.micRmsSub = BluetoothSdk.addListener(
+        "mic_rms",
+        (event: {rms?: number; gateOpen?: boolean; speakerElevated?: boolean}) => {
+          this.gateSamples += 1
+          if (event.gateOpen === false) this.gateClosed += 1
+          if (event.speakerElevated) {
+            this.gateElevated += 1
+            if (event.gateOpen === false) this.gateClosedElevated += 1
+          }
+          if (typeof event.rms === "number" && event.rms > this.gateRmsMax) this.gateRmsMax = event.rms
+        },
+      )
+      void Promise.resolve(BluetoothSdk.setMicRmsTelemetry?.(true))
+        .then(() => {
+          this.micRmsEnabled = true
+        })
+        .catch((error) => console.warn("[AcsMeeting] mic RMS telemetry unavailable", error))
+      void Promise.resolve(BluetoothSdk.requestMicTuningState?.()).catch(() => {})
+    } catch (error) {
+      console.warn("[AcsMeeting] mic gate telemetry unavailable", error)
+    }
+  }
+
+  private stopMicGateTelemetry(): void {
+    this.micTuningSub?.remove()
+    this.micTuningSub = null
+    this.micRmsSub?.remove()
+    this.micRmsSub = null
+    if (!this.micRmsEnabled) return
+    this.micRmsEnabled = false
+    // Super Mode may have the readout open behind this call; it re-requests on focus.
+    void Promise.resolve(BluetoothSdk.setMicRmsTelemetry?.(false)).catch(() => {})
+  }
+
+  /** Barrier's behaviour over the window, as percentages a listening test can be checked against. */
+  private gateSummary(): Record<string, number> {
+    if (this.gateSamples === 0) return {}
+    const pct = (n: number, of: number) => (of === 0 ? 0 : Math.round((n / of) * 1000) / 10)
+    return {
+      gateSamples: this.gateSamples,
+      gateClosedPct: pct(this.gateClosed, this.gateSamples),
+      speakerElevatedPct: pct(this.gateElevated, this.gateSamples),
+      // The number that matters: closed while the far end was quiet means the wearer was cut.
+      gateClosedQuietPct: pct(this.gateClosed - this.gateClosedElevated, this.gateSamples - this.gateElevated),
+      gateRmsMax: this.gateRmsMax,
+    }
+  }
+
+  /**
+   * Guarantee a voice_call session for as long as this call reads the glasses mic.
+   *
+   * The miniapp asking for one is the intended path; this covers the builds where it cannot,
+   * because a bundled Call that predates MIC_ACQUIRE joins anyway rather than failing. Without
+   * this the uplink runs under whatever the OS settings say, and the shipped default is VAD-on.
+   */
+  private acquireMicSession(): void {
+    if (this.micSession) return
+    try {
+      this.micSession = micSessionManager.acquire({
+        owner: `${ENGINE_OWNER_PREFIX}acs-uplink`,
+        source: "glasses",
+        useCase: "voice_call",
+      })
+    } catch (error) {
+      // A source conflict means something else already owns the microphone. Forwarding whatever
+      // it captures is still better than dropping the wearer from the call.
+      console.warn("[AcsMeeting] glasses mic session unavailable", error)
+    }
+  }
+
+  private releaseMicSession(): void {
+    const session = this.micSession
+    if (!session) return
+    this.micSession = null
+    try {
+      session.release()
+    } catch (error) {
+      console.warn("[AcsMeeting] releasing the glasses mic session failed", error)
+    }
+  }
+
   /**
    * Report a call whose pinned microphone stopped delivering. There is deliberately no fallback:
    * the wearer agreed to be heard from the glasses, and quietly switching to the phone in the
@@ -1413,42 +1546,36 @@ class AcsMeetingService {
   private logMicUplink(): void {
     const now = Date.now()
     const elapsed = now - this.lastMicUplinkLogAt
-    if (elapsed < MIC_UPLINK_LOG_INTERVAL_MS) return
+    const sweep = getCallGainSweep()
+    const interval = sweep.isActive() ? MIC_UPLINK_SWEEP_LOG_INTERVAL_MS : MIC_UPLINK_LOG_INTERVAL_MS
+    if (elapsed < interval) return
     this.lastMicUplinkLogAt = now
     // Level, not just cadence: a 20 Hz stream of the noise floor and a 20 Hz stream of speech
     // have the same framesPerSecond. Quiet room on Mentra Live LC3 is meanAbs ≈30–60.
     const level = this.micLevel.take()
+    const stats = pcm16WindowStats(level)
     this.lastMicLevel = {meanAbs: level.meanAbs, peak: level.peak}
+    const gain = sweep.currentGain() ?? micStateCoordinator.getSessionMicTuning()?.gain ?? null
+    if (sweep.isActive()) sweep.ingest(level)
     console.log("[AcsMeeting] phase=glasses-mic-uplink", {
       framesPerSecond: Math.round((this.micFramesWindow * 1000) / elapsed),
       frames: this.micFramesForwarded,
-      meanAbs: level.meanAbs,
-      peak: level.peak,
+      meanAbs: stats.meanAbs,
+      peak: stats.peak,
+      peakPct: stats.peakPct,
+      clipped: stats.clipped,
+      clipPct: stats.clipPct,
+      nearClip: stats.nearClip,
+      nearClipPct: stats.nearClipPct,
+      gain,
+      barrier: micStateCoordinator.getSessionLoudnessGate(),
+      sweep: sweep.currentLabel(),
       dropsStale: this.micDropsStale,
       dropsNonGlasses: this.micDropsNonGlasses,
       gaps: this.micGaps,
       gapMsMax: this.micGapMsMax,
+      ...this.gateSummary(),
     })
-    // #region agent log
-    fetch("http://127.0.0.1:7905/ingest/5a9713c9-45ff-4d09-9435-2adc5db5e91d", {
-      method: "POST",
-      headers: {"Content-Type": "application/json", "X-Debug-Session-Id": "828181"},
-      body: JSON.stringify({
-        sessionId: "828181",
-        runId: "run1",
-        hypothesisId: "E",
-        location: "AcsMeetingService.ts:logMicUplink",
-        message: "phone decoded glasses PCM window",
-        data: {
-          fps: Math.round((this.micFramesWindow * 1000) / elapsed),
-          meanAbs: level.meanAbs,
-          peak: level.peak,
-          frames: this.micFramesForwarded,
-        },
-        timestamp: Date.now(),
-      }),
-    }).catch(() => {})
-    // #endregion
     this.micFramesWindow = 0
   }