@mentra/acs-meeting 3.2.0-dev.221 → 3.2.0-dev.223

package/android/src/test/java/com/mentra/acsmeeting/telemetry/VideoQualityTest.kt

@@ -0,0 +1,182 @@
+package com.mentra.acsmeeting.telemetry
+
+import com.mentra.acsmeeting.telemetry.VideoQuality.Band
+import com.mentra.acsmeeting.video.VideoProfile
+import org.assertj.core.api.Assertions.assertThat
+import org.assertj.core.api.Assertions.within
+import org.junit.Test
+
+class VideoQualityTest {
+  @Test
+  fun bitsPerPixelIsBitrateOverPixelsPerSecond() {
+    // 960x540 at 15 fps on 1.5 Mbps: 1_500_000 / (960*540*15).
+    val bpp = VideoQuality.bitsPerPixel(1_500_000, 960, 540, 15.0)!!
+    assertThat(bpp).isCloseTo(0.193, within(0.001))
+  }
+
+  @Test
+  fun missingOrZeroInputsGiveNoNumberRatherThanZero() {
+    assertThat(VideoQuality.bitsPerPixel(null, 960, 540, 15.0)).isNull()
+    assertThat(VideoQuality.bitsPerPixel(1_500_000, 960, 540, null)).isNull()
+    assertThat(VideoQuality.bitsPerPixel(1_500_000, 0, 540, 15.0)).isNull()
+    assertThat(VideoQuality.bitsPerPixel(1_500_000, 960, 540, 0.0)).isNull()
+    assertThat(VideoQuality.band(null)).isEqualTo(Band.UNKNOWN)
+  }
+
+  @Test
+  fun bandsFollowTheKushGaugeMotionMultiples() {
+    assertThat(VideoQuality.band(0.03)).isEqualTo(Band.BLOCKY)
+    assertThat(VideoQuality.band(0.10)).isEqualTo(Band.SOFT)
+    assertThat(VideoQuality.band(0.20)).isEqualTo(Band.OK)
+    assertThat(VideoQuality.band(0.30)).isEqualTo(Band.GOOD)
+  }
+
+  @Test
+  fun bandBoundariesAreTheConstantsThemselves() {
+    assertThat(VideoQuality.band(VideoQuality.STATIC_BPP)).isEqualTo(Band.SOFT)
+    assertThat(VideoQuality.band(VideoQuality.MODERATE_BPP)).isEqualTo(Band.OK)
+    assertThat(VideoQuality.band(VideoQuality.HIGH_MOTION_BPP)).isEqualTo(Band.GOOD)
+  }
+
+  /**
+   * The measured device state: `wire=960x540@14.4 kbps=1276`. Every rate counter
+   * read healthy and the picture was reported pixelated, which is the whole
+   * reason this file exists.
+   */
+  @Test
+  fun theMeasuredDeviceStateLandsShortOfHighMotion() {
+    val bpp = VideoQuality.bitsPerPixel(1_276_000, 960, 540, 14.4)!!
+    assertThat(bpp).isCloseTo(0.171, within(0.001))
+    assertThat(VideoQuality.band(bpp)).isEqualTo(Band.OK)
+    assertThat(bpp).isLessThan(VideoQuality.HIGH_MOTION_BPP)
+  }
+
+  /**
+   * The old 1.5 Mbps grant could not reach high motion at 540p15 no matter what the
+   * encoder did, which is why the ceiling was raised. This pins the new one to the
+   * requirement rather than to a round number, so shrinking it back below what the
+   * geometry needs fails here instead of on someone's screen.
+   */
+  @Test
+  fun theShipped540pBudgetCanNowReachHighMotion() {
+    val p540 = VideoProfile.P540_15
+    val needed = VideoQuality.neededBps(p540.width, p540.height, p540.fps.toDouble(), VideoQuality.HIGH_MOTION_BPP)
+    assertThat(needed).isCloseTo(2_177_280L, within(1_000L))
+    assertThat(p540.maxBitrateBps.toLong()).isGreaterThanOrEqualTo(needed)
+    assertThat(
+      VideoQuality.budgetCapsQuality(p540.width, p540.height, p540.fps.toDouble(), p540.maxBitrateBps),
+    ).isFalse()
+    // The grant it replaced, kept as the regression it was.
+    assertThat(VideoQuality.budgetCapsQuality(p540.width, p540.height, p540.fps.toDouble(), 1_500_000)).isTrue()
+  }
+
+  /** 360p15 fits inside its 1 Mbps grant, so the smaller profile is not budget-capped. */
+  @Test
+  fun theSdProfileIsNotBudgetCapped() {
+    val sd = VideoProfile.SD
+    assertThat(
+      VideoQuality.budgetCapsQuality(sd.width, sd.height, sd.fps.toDouble(), sd.maxBitrateBps),
+    ).isFalse()
+  }
+
+  @Test
+  fun aBudgetOfZeroIsNotTreatedAsACap() {
+    assertThat(VideoQuality.budgetCapsQuality(960, 540, 15.0, 0)).isFalse()
+  }
+
+  @Test
+  fun everyBandHasANonEmptyHint() {
+    for (band in Band.entries) {
+      for (capped in listOf(true, false)) {
+        for (spending in listOf(true, false)) {
+          for (busy in listOf(true, false)) {
+            assertThat(VideoQuality.hint(band, capped, spending, busy)).isNotBlank()
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Underspending with a nearly full core and underspending with an idle one look
+   * the same on screen and want opposite fixes, so they must not share a hint.
+   */
+  @Test
+  fun underspendSplitsOnCpuRatherThanCollapsingToOneRemedy() {
+    val busy = VideoQuality.hint(Band.OK, budgetCapped = true, spendingBudget = false, encoderBusy = true)
+    val idle = VideoQuality.hint(Band.OK, budgetCapped = true, spendingBudget = false, encoderBusy = false)
+    assertThat(busy).contains("cut pixels")
+    assertThat(idle).contains("congestion control")
+    assertThat(idle).doesNotContain("cut pixels")
+  }
+
+  @Test
+  fun spendingIsMeasuredAgainstTheGrantedCeiling() {
+    assertThat(VideoQuality.spendingBudget(1_275_000, 1_500_000)).isTrue()
+    assertThat(VideoQuality.spendingBudget(1_200_000, 1_500_000)).isFalse()
+    assertThat(VideoQuality.spendingBudget(null, 1_500_000)).isFalse()
+    assertThat(VideoQuality.spendingBudget(1_200_000, 0)).isFalse()
+  }
+
+  /**
+   * Measured on device during the bitrate slide: `kbps=1210 budgetKbps=1500` with
+   * process CPU at 69–88% of one core on an 8-core phone. The encoder had headroom
+   * and the rate still fell, so this must not be reported as an encoder problem.
+   */
+  @Test
+  fun theMeasuredSlideIsBlamedOnCongestionNotTheEncoder() {
+    val line = VideoQuality.line(960, 540, 14.2, 1_210_000, 1_500_000, 140.0, 77.8, "GOOD")
+    assertThat(line).contains("used=81%")
+    assertThat(line).contains("cpu=77.8")
+    assertThat(line).contains("sendQuality=GOOD")
+    assertThat(line).contains("congestion control")
+    assertThat(line).doesNotContain("cut pixels")
+  }
+
+  /** A picture that is already sharp is never told to cut anything. */
+  @Test
+  fun aGoodPictureIsNotGivenARemedy() {
+    val hint = VideoQuality.hint(
+      Band.GOOD,
+      budgetCapped = true,
+      spendingBudget = false,
+      encoderBusy = true,
+    )
+    assertThat(hint).isEqualTo("enough for high motion")
+  }
+
+  @Test
+  fun theLinePrintsTheShortfallAndNotJustTheNumber() {
+    val line = VideoQuality.line(
+      wireWidth = 960,
+      wireHeight = 540,
+      wireFps = 14.4,
+      wireBitrateBps = 1_276_000,
+      budgetBps = 1_500_000,
+      packetsPerSecond = 143.0,
+      cpuPercent = 74.4,
+      sendQuality = "GOOD",
+    )
+    assertThat(line).startsWith("P9 quality band=OK")
+    assertThat(line).contains("bpp=0.171")
+    assertThat(line).contains("size=960x540@14.4")
+    assertThat(line).contains("kbps=1276")
+    assertThat(line).contains("budgetKbps=1500")
+    assertThat(line).contains("used=85%")
+    // What it would take to look sharp on a head-mounted camera, scored against the
+    // rate actually on the wire (960*540*14.4*0.28), not the rate we asked for.
+    assertThat(line).contains("goodNeedsKbps=2090")
+    assertThat(line).contains("budgetCapped=true")
+    assertThat(line).contains("pps=143.0")
+  }
+
+  @Test
+  fun theLineSurvivesAMissingWireReport() {
+    val line = VideoQuality.line(null, null, null, null, 1_500_000, null, null, "")
+    assertThat(line).contains("band=UNKNOWN")
+    assertThat(line).contains("bpp=na")
+    assertThat(line).contains("pps=na")
+    assertThat(line).contains("cpu=na")
+    assertThat(line).contains("sendQuality=na")
+  }
+}

package/android/src/test/java/com/mentra/acsmeeting/telemetry/VideoRateVerdictTest.kt

@@ -0,0 +1,149 @@
+package com.mentra.acsmeeting.telemetry
+
+import com.mentra.acsmeeting.telemetry.VideoRateVerdict.Bound
+import org.assertj.core.api.Assertions.assertThat
+import org.junit.Test
+
+class VideoRateVerdictTest {
+  /** 540p15 against a starved 1.5 Mbps budget — the grant Mentra Call used to send. */
+  private fun verdict(
+    advertisedFps: Double = 15.0,
+    sinkFps: Double = 15.0,
+    admittedFps: Double = 15.0,
+    wireFps: Double? = 15.0,
+    wireBitrateBps: Long? = 1_400_000,
+    budgetBps: Int = 1_500_000,
+    cpuPercent: Double? = 55.0,
+  ) = VideoRateVerdict.of(
+    advertisedFps = advertisedFps,
+    sinkFps = sinkFps,
+    admittedFps = admittedFps,
+    wireFps = wireFps,
+    wireBitrateBps = wireBitrateBps,
+    budgetBps = budgetBps,
+    cpuPercent = cpuPercent,
+  )
+
+  @Test
+  fun aWireHoldingTheAdvertisedRateIsOk() {
+    assertThat(verdict()).isEqualTo(Bound.OK)
+  }
+
+  /**
+   * The verdict that decides whether "the call quality is low" is answered by raising the grant.
+   * Every frame is on the wire, so nothing here is short — but the bits are pressed against the
+   * ceiling, which is the one condition under which a bigger number changes the picture. Without
+   * this the same tick reads OK and the ceiling never enters the conversation.
+   */
+  @Test
+  fun aFullRateRidingTheCeilingIsNamedAsCapBound() {
+    assertThat(verdict(wireBitrateBps = 1_480_000)).isEqualTo(Bound.CAP_BOUND)
+    // The controller routinely overshoots the grant; that is still the ceiling binding.
+    assertThat(verdict(wireBitrateBps = 1_623_000)).isEqualTo(Bound.CAP_BOUND)
+  }
+
+  /** Headroom under the grant at a full rate is a healthy stream, not a ceiling problem. */
+  @Test
+  fun aFullRateWithBitsToSpareIsStillPlainOk() {
+    assertThat(verdict(wireBitrateBps = 1_100_000)).isEqualTo(Bound.OK)
+    assertThat(verdict(wireBitrateBps = null)).isEqualTo(Bound.OK)
+  }
+
+  /**
+   * Cap-bound is about the ceiling, and a short frame rate means something else is wrong first.
+   * Raising the grant for a stream that cannot fill the one it has buys nothing.
+   */
+  @Test
+  fun aShortRateIsDiagnosedBeforeTheCeilingIsConsidered() {
+    assertThat(verdict(wireFps = 8.0, wireBitrateBps = 1_480_000, cpuPercent = 92.0))
+      .isEqualTo(Bound.ENCODER_SHORT)
+  }
+
+  /**
+   * The exact shape of the greedy-gate bug: the glasses supplied 14.6 fps, the
+   * pacer admitted 7.3 against an advertised 8, and every counter downstream
+   * looked like an encoder problem. It was ours.
+   */
+  @Test
+  fun aGateThatDropsFramesTheSourceSuppliedIsBlamedOnThePacer() {
+    assertThat(verdict(advertisedFps = 8.0, sinkFps = 14.6, admittedFps = 7.3, wireFps = 7.0))
+      .isEqualTo(Bound.PACER_SHORT)
+  }
+
+  @Test
+  fun aShortSourceIsNotBlamedOnAnythingDownstream() {
+    assertThat(verdict(sinkFps = 6.0, admittedFps = 6.0, wireFps = 6.0))
+      .isEqualTo(Bound.SOURCE_SHORT)
+  }
+
+  /**
+   * A source a little under the advertise is not the pacer's fault. Scoring the
+   * gate against the advertise alone would read every slightly slow glasses leg
+   * as our own bug and send the next fix to the wrong place.
+   */
+  @Test
+  fun thePacerIsNotBlamedForFramesTheSourceNeverSent() {
+    assertThat(verdict(sinkFps = 13.0, admittedFps = 13.0, wireFps = 13.0))
+      .isEqualTo(Bound.OK)
+  }
+
+  /**
+   * The two verdicts that matter, because they want opposite fixes. Same short
+   * wire rate, same delivered rate; only CPU and the bitrate headroom differ.
+   */
+  @Test
+  fun aBusyCpuMeansTheEncoderIsTheCeiling() {
+    assertThat(verdict(wireFps = 8.0, cpuPercent = 92.0)).isEqualTo(Bound.ENCODER_SHORT)
+  }
+
+  @Test
+  fun sparecpuAndACollapsedBitrateMeansTheRateControllerIsThrottling() {
+    assertThat(verdict(wireFps = 8.0, wireBitrateBps = 496_000, cpuPercent = 50.0))
+      .isEqualTo(Bound.BITRATE_STARVED)
+  }
+
+  /** Spare CPU but the budget is being spent: the encoder really is the limit. */
+  @Test
+  fun sparecpuWithTheBudgetSpentIsStillTheEncoder() {
+    assertThat(verdict(wireFps = 8.0, wireBitrateBps = 1_450_000, cpuPercent = 50.0))
+      .isEqualTo(Bound.ENCODER_SHORT)
+  }
+
+  @Test
+  fun aMissingWireReportIsNotAVerdict() {
+    assertThat(verdict(wireFps = null)).isEqualTo(Bound.UNKNOWN)
+    assertThat(verdict(advertisedFps = 0.0)).isEqualTo(Bound.UNKNOWN)
+  }
+
+  /** Every bound carries an action, or the line makes the reader open this file. */
+  @Test
+  fun everyBoundHasANonEmptyHint() {
+    for (bound in Bound.entries) {
+      assertThat(VideoRateVerdict.hint(bound)).isNotBlank()
+    }
+  }
+
+  @Test
+  fun theLinePrintsTheInputsBesideTheVerdict() {
+    val line = VideoRateVerdict.line(
+      advertisedFps = 15.0,
+      sinkFps = 14.6,
+      admittedFps = 7.3,
+      wireFps = 7.0,
+      wireBitrateBps = 496_000,
+      budgetBps = 1_500_000,
+      cpuPercent = 61.3,
+      codecName = "h264 sw",
+    )
+    assertThat(line).startsWith("P7 rate bound=PACER_SHORT")
+    assertThat(line).contains("advertised=15.0")
+    assertThat(line).contains("sink=14.6")
+    assertThat(line).contains("admitted=7.3")
+    assertThat(line).contains("wire=7.0")
+    assertThat(line).contains("kbps=496")
+    assertThat(line).contains("budgetKbps=1500")
+    assertThat(line).contains("cpu=61.3")
+    assertThat(line).contains("codec=h264_sw")
+    assertThat(line).contains(VideoRateVerdict.hint(Bound.PACER_SHORT))
+  }
+}

package/android/src/test/java/com/mentra/acsmeeting/trace/SoftApTraceTest.kt

@@ -0,0 +1,97 @@
+package com.mentra.acsmeeting.trace
+
+import org.assertj.core.api.Assertions.assertThat
+import org.junit.Test
+
+/**
+ * Covers the pure formatter. The `Log.i` wrapper is a one-liner and is exercised on device.
+ */
+class SoftApTraceTest {
+
+    @Test
+    fun `format carries the grep marker`() {
+        assertThat(SoftApTrace.format("t1", "scoped_network_available", 12))
+            .contains("SOFTAP_TRACE")
+    }
+
+    @Test
+    fun `format includes traceId stage and elapsed`() {
+        assertThat(SoftApTrace.format("abc123", "ice_selected_pair", 450))
+            .isEqualTo("[SOFTAP_TRACE] traceId=abc123 stage=ice_selected_pair elapsedMs=450")
+    }
+
+    @Test
+    fun `format omits traceId when absent`() {
+        assertThat(SoftApTrace.format("", "boot", 0))
+            .isEqualTo("[SOFTAP_TRACE] stage=boot elapsedMs=0")
+    }
+
+    @Test
+    fun `format appends fields in order`() {
+        assertThat(SoftApTrace.format("t", "whip_request", 7, "method" to "POST", "status" to 201))
+            .endsWith("method=POST status=201")
+    }
+
+    @Test
+    fun `sanitize redacts the hotspot password`() {
+        assertThat(SoftApTrace.sanitize("password", "hunter2")).isEqualTo("<redacted>")
+        assertThat(SoftApTrace.sanitize("hotspotPassword", "hunter2")).isEqualTo("<redacted>")
+        assertThat(SoftApTrace.sanitize("psk", "hunter2")).isEqualTo("<redacted>")
+        assertThat(SoftApTrace.sanitize("passphrase", "hunter2")).isEqualTo("<redacted>")
+    }
+
+    @Test
+    fun `sanitize redacts tokens and credentials`() {
+        assertThat(SoftApTrace.sanitize("token", "eyJhbGciOi")).isEqualTo("<redacted>")
+        assertThat(SoftApTrace.sanitize("acsToken", "eyJhbGciOi")).isEqualTo("<redacted>")
+        assertThat(SoftApTrace.sanitize("Authorization", "Bearer x")).isEqualTo("<redacted>")
+        assertThat(SoftApTrace.sanitize("meetingUrl", "https://teams.microsoft.com/l/x"))
+            .isEqualTo("<redacted>")
+    }
+
+    @Test
+    fun `format never leaks a secret value into the line`() {
+        val line = SoftApTrace.format(
+            "t", "hotspot_started", 5,
+            "ssid" to "MentraLive", "password" to "hunter2",
+        )
+        assertThat(line).doesNotContain("hunter2")
+        assertThat(line).contains("ssid=MentraLive")
+        assertThat(line).contains("password=<redacted>")
+    }
+
+    @Test
+    fun `sanitize keeps the local whip url which is diagnostic`() {
+        assertThat(SoftApTrace.sanitize("whipUrl", "http://192.168.43.20:8790/whip/abc"))
+            .isEqualTo("http://192.168.43.20:8790/whip/abc")
+    }
+
+    @Test
+    fun `sanitize strips query strings that may carry tokens`() {
+        assertThat(SoftApTrace.sanitize("playbackUrl", "https://example.com/live?token=secret123"))
+            .isEqualTo("https://example.com/live?<redacted>")
+    }
+
+    @Test
+    fun `sanitize strips userinfo from urls`() {
+        val result = SoftApTrace.sanitize("endpoint", "https://user:pw@example.com/x")
+        assertThat(result).doesNotContain("pw@")
+        assertThat(result).contains("<redacted>@example.com/x")
+    }
+
+    @Test
+    fun `sanitize quotes values containing spaces`() {
+        assertThat(SoftApTrace.sanitize("reason", "two words")).isEqualTo("\"two words\"")
+    }
+
+    @Test
+    fun `sanitize renders null and empty`() {
+        assertThat(SoftApTrace.sanitize("reason", null)).isEqualTo("null")
+        assertThat(SoftApTrace.sanitize("reason", "")).isEqualTo("\"\"")
+    }
+
+    @Test
+    fun `newTraceId produces distinct ids`() {
+        assertThat(SoftApTrace.newTraceId()).isNotEqualTo(SoftApTrace.newTraceId())
+    }
+}

package/android/src/test/java/com/mentra/acsmeeting/video/AcsTimestampTest.kt

@@ -40,4 +40,38 @@ class AcsTimestampTest {
     val ticks = AcsTimestamp.resolve(streamTicks = 0, captureNs = 100, lastTicks = 9_000)
     assertThat(ticks).isEqualTo(9_001)
   }
+
+  /**
+   * Outgoing audio's shape: `RawOutgoingAudioStream` in 2.16.0 exposes no stream clock, so the
+   * capture time is always the source and `streamTicks` is always 0.
+   *
+   * The audio and the video come from different places — one over BLE, one over the SoftAP peer —
+   * so a shared `System.nanoTime()` base is the only thing that lets a receiver relate them at all.
+   * These assertions are the precondition for the A/V question, not the answer to it: whether ACS
+   * honours the ticks for raw audio is a receiver measurement.
+   */
+  @Test
+  fun audioFramesStampedFromCaptureTimeShareTheVideoTickBase() {
+    val captureNs = 1_234_500_000L
+    val audio = AcsTimestamp.resolve(streamTicks = 0, captureNs = captureNs, lastTicks = 0)
+    val videoFromTheSameInstant = AcsTimestamp.resolve(streamTicks = 0, captureNs = captureNs, lastTicks = 0)
+
+    assertThat(audio).isEqualTo(videoFromTheSameInstant)
+    assertThat(audio).isEqualTo(captureNs / AcsTimestamp.NS_PER_TICK)
+  }
+
+  @Test
+  fun aStreamOfAudioFramesIsStrictlyIncreasingAndNeverZero() {
+    // 20 ms periods on a clock coarse enough that two frames could collide.
+    var last = 0L
+    val ticks = (0 until 50).map { period ->
+      val resolved = AcsTimestamp.resolve(streamTicks = 0, captureNs = period * 20_000_000L, lastTicks = last)
+      last = resolved
+      resolved
+    }
+
+    assertThat(ticks).doesNotContain(0L)
+    assertThat(ticks).isSorted()
+    assertThat(ticks.toSet()).hasSameSizeAs(ticks)
+  }
 }

package/android/src/test/java/com/mentra/acsmeeting/video/FramePacerTest.kt

@@ -0,0 +1,105 @@
+package com.mentra.acsmeeting.video
+
+import org.assertj.core.api.Assertions.assertThat
+import org.assertj.core.api.Assertions.within
+import org.junit.Test
+
+class FramePacerTest {
+  @Test
+  fun firstFrameAlwaysAdmits() {
+    val pacer = FramePacer()
+    assertThat(pacer.tryAdmit(FramePacer.intervalNs(8f), nowNs = 1_000L)).isTrue()
+  }
+
+  @Test
+  fun dropsAFrameThatArrivesInsideTheAdvertisedInterval() {
+    val pacer = FramePacer()
+    val interval = FramePacer.intervalNs(8f)
+    assertThat(pacer.tryAdmit(interval, nowNs = 0L)).isTrue()
+    assertThat(pacer.tryAdmit(interval, nowNs = interval - 1)).isFalse()
+  }
+
+  @Test
+  fun admitsOnceTheAdvertisedIntervalHasElapsed() {
+    val pacer = FramePacer()
+    val interval = FramePacer.intervalNs(8f)
+    assertThat(pacer.tryAdmit(interval, nowNs = 0L)).isTrue()
+    assertThat(pacer.tryAdmit(interval, nowNs = interval)).isTrue()
+  }
+
+  /**
+   * Fifteen frames a second against an 8 fps advertise is the production SoftAP
+   * case, and the only assertion that catches the failure is the sustained rate.
+   *
+   * Counting admits inside one 15-frame window cannot: 8 of 15 is also what a
+   * 7.5 fps stream looks like, because both land on i=0,2,4..14. That is how a
+   * greedy "interval elapsed since the last admit" gate passed this file while
+   * the device ran `sub=7.0 wire=960x540@7.0` against an advertised 8.
+   */
+  @Test
+  fun sustainsTheAdvertisedRateFromAnyFasterSource() {
+    // 14.49 and 14.6 are arrival rates measured on device (gapP50 68-69ms), not
+    // round numbers. The greedy gate delivered 7.25 and 7.30 for them.
+    for (sourceFps in listOf(14.49f, 14.6f, 15f, 30f)) {
+      assertThat(sustainedFps(advertisedFps = 8f, sourceFps = sourceFps))
+        .`as`("source %s fps", sourceFps)
+        .isCloseTo(8.0, within(0.05))
+    }
+  }
+
+  /** A source slower than the advertise passes through untouched, not padded. */
+  @Test
+  fun neverInventsFramesTheSourceDidNotSend() {
+    assertThat(sustainedFps(advertisedFps = 8f, sourceFps = 5f)).isCloseTo(5.0, within(0.05))
+  }
+
+  /**
+   * Catch-up is bounded. A source that goes away must not buy its debt back as a
+   * burst of back-to-back admits: that is over-delivery against the same
+   * advertised rate, which is the way the ungated path starved the encoder.
+   */
+  @Test
+  fun aStallDoesNotEarnABurstOfCatchUpAdmits() {
+    val pacer = FramePacer()
+    val interval = FramePacer.intervalNs(8f)
+    assertThat(pacer.tryAdmit(interval, nowNs = 0L)).isTrue()
+    val afterStall = 10 * interval
+    assertThat(pacer.tryAdmit(interval, nowNs = afterStall)).isTrue()
+    // The resync admit starts a fresh interval; nothing is due until it elapses.
+    assertThat(pacer.tryAdmit(interval, nowNs = afterStall + 1)).isFalse()
+    assertThat(pacer.tryAdmit(interval, nowNs = afterStall + interval)).isTrue()
+  }
+
+  private fun sustainedFps(advertisedFps: Float, sourceFps: Float, frames: Int = 3000): Double {
+    val pacer = FramePacer()
+    val interval = FramePacer.intervalNs(advertisedFps)
+    val arrival = FramePacer.intervalNs(sourceFps)
+    var admitted = 0
+    for (i in 0 until frames) {
+      if (pacer.tryAdmit(interval, nowNs = i * arrival)) admitted += 1
+    }
+    return admitted / ((frames - 1).toDouble() * arrival / 1_000_000_000.0)
+  }
+
+  @Test
+  fun resetForgetsTheLastAdmit() {
+    val pacer = FramePacer()
+    val interval = FramePacer.intervalNs(8f)
+    assertThat(pacer.tryAdmit(interval, nowNs = 0L)).isTrue()
+    pacer.reset()
+    assertThat(pacer.tryAdmit(interval, nowNs = 1L)).isTrue()
+  }
+
+  @Test
+  fun zeroIntervalNeverPaces() {
+    val pacer = FramePacer()
+    assertThat(FramePacer.intervalNs(0f)).isEqualTo(0L)
+    assertThat(pacer.tryAdmit(0L, nowNs = 0L)).isTrue()
+    assertThat(pacer.tryAdmit(0L, nowNs = 1L)).isTrue()
+  }
+
+  @Test
+  fun eightFpsIntervalIsOneHundredTwentyFiveMilliseconds() {
+    assertThat(FramePacer.intervalNs(8f)).isEqualTo(125_000_000L)
+  }
+}

package/android/src/test/java/com/mentra/acsmeeting/video/I420FormatSpecTest.kt

@@ -54,6 +54,11 @@ class AcsFrameSenderFormatTest {
   fun parseOrNullAllowsDocumentedVirtualCameraSizesOnly() {
     assertThat(I420FormatSpec.parseOrNull(1280, 720, 15f)).isNotNull()
     assertThat(I420FormatSpec.parseOrNull(960, 540, 30f)).isNotNull()
+    for (fps in listOf(15f, 24f, 30f)) {
+      val spec = I420FormatSpec.parseOrNull(858, 480, fps)!!
+      assertThat(spec.namedResolution()).isEqualTo(AcsNamedResolution.P480)
+      assertThat(spec.packedSize()).isEqualTo(I420Packer.packedSize(858, 480))
+    }
     assertThat(I420FormatSpec.parseOrNull(540, 960, 30f)).isNull()
     assertThat(I420FormatSpec.parseOrNull(854, 480, 15f)).isNull()
   }

package/android/src/test/java/com/mentra/acsmeeting/video/VideoProfileTest.kt

@@ -49,15 +49,50 @@ class VideoProfileTest {
     }
   }
 
+  @Test
+  fun acsCeilingsSitAboveTheGlassesPhoneLink() {
+    val glassesPhoneBps = 2_500_000
+    for (profile in listOf(VideoProfile.HD, VideoProfile.P540, VideoProfile.P540_15)) {
+      assertThat(profile.maxBitrateBps).isGreaterThan(glassesPhoneBps)
+    }
+  }
+
   @Test
   fun parseAcceptsDocumentedVirtualCameraSizesAndRejectsPortraitAnd480p() {
-    assertThat(VideoProfile.parse(1280, 720, 15, 2_500_000)).isEqualTo(VideoProfile.HD)
-    assertThat(VideoProfile.parse(960, 540, 30, 1_500_000)).isEqualTo(VideoProfile.P540)
-    assertThat(VideoProfile.parse(960, 540, 15, 1_500_000)).isEqualTo(VideoProfile.P540_15)
+    assertThat(VideoProfile.parse(1280, 720, 15, 3_000_000)).isEqualTo(VideoProfile.HD)
+    assertThat(VideoProfile.parse(960, 540, 30, 3_000_000)).isEqualTo(VideoProfile.P540)
+    assertThat(VideoProfile.parse(960, 540, 15, 3_000_000)).isEqualTo(VideoProfile.P540_15)
     assertThat(VideoProfile.parse(540, 960, 30, 1_500_000)).isNull()
     assertThat(VideoProfile.parse(854, 480, 15, 1_500_000)).isNull()
   }
 
+  @Test
+  fun softwareEncoderClampDropsOnlyTheRate() {
+    val requested = VideoProfile.P540_15
+    val clamped = requested.forSoftwareEncoder()
+    assertThat(clamped.width).isEqualTo(requested.width)
+    assertThat(clamped.height).isEqualTo(requested.height)
+    assertThat(clamped.maxBitrateBps).isEqualTo(requested.maxBitrateBps)
+    assertThat(clamped.fps).isEqualTo(VideoProfile.SOFTWARE_ENCODER_FPS)
+    assertThat(clamped.spec().withinAcsBounds()).isTrue()
+    assertThat(clamped.bitsPerFrame()).isEqualTo(requested.maxBitrateBps / VideoProfile.SOFTWARE_ENCODER_FPS)
+  }
+
+  @Test
+  fun softwareEncoderClampIsIdempotentAtOrBelowTheSustainRate() {
+    val alreadyHeld = VideoProfile.P540_15.copy(fps = VideoProfile.SOFTWARE_ENCODER_FPS)
+    assertThat(alreadyHeld.forSoftwareEncoder()).isSameAs(alreadyHeld)
+    val slower = VideoProfile.P540_15.copy(fps = 5)
+    assertThat(slower.forSoftwareEncoder()).isSameAs(slower)
+  }
+
+  @Test
+  fun softwareEncoderClampHitsEveryShippedProfile() {
+    for (profile in listOf(VideoProfile.HD, VideoProfile.SD, VideoProfile.P540, VideoProfile.P540_15)) {
+      assertThat(profile.forSoftwareEncoder().fps).isEqualTo(VideoProfile.SOFTWARE_ENCODER_FPS)
+    }
+  }
+
   /** The fallback only earns its place if it is a real cut in encoder work. */
   @Test
   fun sdIsAQuarterOfTheHdPixelCount() {

package/build/AcsMeeting.types.d.ts

@@ -42,6 +42,11 @@ export type AcsMeetingJoinOptions = {
     displayName?: string;
     /** "glasses" sends WHEP PCM. "phone" uses the ACS local mic (handset or BT). */
     audioSource?: AcsAudioSource;
+    /**
+     * Hold outgoing PCM this many ms before ACS. SoftAP+LC3 sets this in the host
+     * because BLE audio reaches the phone before SoftAP video.
+     */
+    audioDelayMs?: number;
     /** Dump WHEP PCM to a WAV in cache for P4 verification. */
     dumpPcmWav?: boolean;
     /** When omitted, native keeps 1280×720@15 / 2.5 Mbps. */

package/build/AcsMeeting.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AcsMeeting.types.d.ts","sourceRoot":"","sources":["../src/AcsMeeting.types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,YAAY,GAAG,OAAO,GAAG,WAAW,GAAG,cAAc,GAAG,OAAO,CAAA;AAEnG,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,OAAO,CAAA;AAChD,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAA;AAC1D,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,UAAU,GAAG,QAAQ,CAAA;AAC3D;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,YAAY,GAAG,MAAM,GAAG,QAAQ,CAAA;AAE3E,MAAM,MAAM,0BAA0B,GAAG,MAAM,GAAG,YAAY,GAAG,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,cAAc,CAAA;AAEhH,MAAM,MAAM,qBAAqB,GAAG;IAClC,EAAE,EAAE,MAAM,CAAA;IACV,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,KAAK,EAAE,0BAA0B,CAAA;IACjC,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,EAAE,OAAO,CAAA;CACpB,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,EAAE,YAAY,CAAA;IACnB,KAAK,EAAE,OAAO,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,WAAW,CAAA;IACtB,WAAW,CAAC,EAAE,cAAc,CAAA;IAC5B,YAAY,CAAC,EAAE,eAAe,CAAA;IAC9B,WAAW,CAAC,EAAE,cAAc,CAAA;IAC5B,WAAW,CAAC,EAAE,mBAAmB,CAAA;IACjC,4DAA4D;IAC5D,YAAY,CAAC,EAAE,qBAAqB,EAAE,CAAA;CACvC,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,aAAa,EAAE,MAAM,CAAA;CACtB,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG;IAClC,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gFAAgF;IAChF,WAAW,CAAC,EAAE,cAAc,CAAA;IAC5B,2DAA2D;IAC3D,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,yDAAyD;IACzD,KAAK,CAAC,EAAE,gBAAgB,CAAA;CACzB,CAAA;AAED,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAA;IACzC,aAAa,EAAE,CAAC,GAAG,EAAE,mBAAmB,KAAK,IAAI,CAAA;CAClD,CAAA"}
+{"version":3,"file":"AcsMeeting.types.d.ts","sourceRoot":"","sources":["../src/AcsMeeting.types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,YAAY,GAAG,OAAO,GAAG,WAAW,GAAG,cAAc,GAAG,OAAO,CAAA;AAEnG,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,OAAO,CAAA;AAChD,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAA;AAC1D,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,UAAU,GAAG,QAAQ,CAAA;AAC3D;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,YAAY,GAAG,MAAM,GAAG,QAAQ,CAAA;AAE3E,MAAM,MAAM,0BAA0B,GAAG,MAAM,GAAG,YAAY,GAAG,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,cAAc,CAAA;AAEhH,MAAM,MAAM,qBAAqB,GAAG;IAClC,EAAE,EAAE,MAAM,CAAA;IACV,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,KAAK,EAAE,0BAA0B,CAAA;IACjC,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,EAAE,OAAO,CAAA;CACpB,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,EAAE,YAAY,CAAA;IACnB,KAAK,EAAE,OAAO,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,WAAW,CAAA;IACtB,WAAW,CAAC,EAAE,cAAc,CAAA;IAC5B,YAAY,CAAC,EAAE,eAAe,CAAA;IAC9B,WAAW,CAAC,EAAE,cAAc,CAAA;IAC5B,WAAW,CAAC,EAAE,mBAAmB,CAAA;IACjC,4DAA4D;IAC5D,YAAY,CAAC,EAAE,qBAAqB,EAAE,CAAA;CACvC,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,aAAa,EAAE,MAAM,CAAA;CACtB,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG;IAClC,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gFAAgF;IAChF,WAAW,CAAC,EAAE,cAAc,CAAA;IAC5B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,yDAAyD;IACzD,KAAK,CAAC,EAAE,gBAAgB,CAAA;CACzB,CAAA;AAED,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAA;IACzC,aAAa,EAAE,CAAC,GAAG,EAAE,mBAAmB,KAAK,IAAI,CAAA;CAClD,CAAA"}

package/build/AcsMeeting.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"AcsMeeting.types.js","sourceRoot":"","sources":["../src/AcsMeeting.types.ts"],"names":[],"mappings":"","sourcesContent":["export type MeetingPhase = \"idle\" | \"connecting\" | \"lobby\" | \"connected\" | \"disconnected\" | \"error\"\n\nexport type AcsAudioSource = \"glasses\" | \"phone\"\nexport type AcsActiveStream = \"none\" | \"virtual\" | \"local\"\nexport type AcsAudioSafety = \"safe\" | \"degraded\" | \"unsafe\"\n/**\n * Health of the glasses WHEP subscription feeding the call. `failed` = ICE dropped or\n * the WHEP endpoint went away while the ACS call may still be `connected`. Native\n * rebuilds it on its own with backoff; the host can force one via `restartVideoSource`.\n */\nexport type AcsMediaSourceState = \"idle\" | \"connecting\" | \"live\" | \"failed\"\n\nexport type AcsMeetingParticipantState = \"idle\" | \"connecting\" | \"connected\" | \"lobby\" | \"hold\" | \"disconnected\"\n\nexport type AcsMeetingParticipant = {\n  id: string\n  displayName: string | null\n  state: AcsMeetingParticipantState\n  isMuted: boolean\n  isSpeaking: boolean\n}\n\nexport type AcsMeetingState = {\n  state: MeetingPhase\n  muted: boolean\n  error?: string\n  meetingUrl?: string\n  provider?: \"acs-teams\"\n  audioSource?: AcsAudioSource\n  activeStream?: AcsActiveStream\n  audioSafety?: AcsAudioSafety\n  mediaSource?: AcsMediaSourceState\n  /** Remote roster (Android emits this; iOS does not yet). */\n  participants?: AcsMeetingParticipant[]\n}\n\nexport type AcsOutgoingVideo = {\n  width: number\n  height: number\n  fps: number\n  maxBitrateBps: number\n}\n\nexport type AcsMeetingJoinOptions = {\n  meetingUrl: string\n  token: string\n  whepUrl: string\n  displayName?: string\n  /** \"glasses\" sends WHEP PCM. \"phone\" uses the ACS local mic (handset or BT). */\n  audioSource?: AcsAudioSource\n  /** Dump WHEP PCM to a WAV in cache for P4 verification. */\n  dumpPcmWav?: boolean\n  /** When omitted, native keeps 1280×720@15 / 2.5 Mbps. */\n  video?: AcsOutgoingVideo\n}\n\nexport type AcsIncomingPcmEvent = {\n  base64: string\n  sampleRate: number\n  channels: number\n}\n\nexport type AcsMeetingModuleEvents = {\n  onState: (state: AcsMeetingState) => void\n  onIncomingPcm: (pcm: AcsIncomingPcmEvent) => void\n}\n"]}
+{"version":3,"file":"AcsMeeting.types.js","sourceRoot":"","sources":["../src/AcsMeeting.types.ts"],"names":[],"mappings":"","sourcesContent":["export type MeetingPhase = \"idle\" | \"connecting\" | \"lobby\" | \"connected\" | \"disconnected\" | \"error\"\n\nexport type AcsAudioSource = \"glasses\" | \"phone\"\nexport type AcsActiveStream = \"none\" | \"virtual\" | \"local\"\nexport type AcsAudioSafety = \"safe\" | \"degraded\" | \"unsafe\"\n/**\n * Health of the glasses WHEP subscription feeding the call. `failed` = ICE dropped or\n * the WHEP endpoint went away while the ACS call may still be `connected`. Native\n * rebuilds it on its own with backoff; the host can force one via `restartVideoSource`.\n */\nexport type AcsMediaSourceState = \"idle\" | \"connecting\" | \"live\" | \"failed\"\n\nexport type AcsMeetingParticipantState = \"idle\" | \"connecting\" | \"connected\" | \"lobby\" | \"hold\" | \"disconnected\"\n\nexport type AcsMeetingParticipant = {\n  id: string\n  displayName: string | null\n  state: AcsMeetingParticipantState\n  isMuted: boolean\n  isSpeaking: boolean\n}\n\nexport type AcsMeetingState = {\n  state: MeetingPhase\n  muted: boolean\n  error?: string\n  meetingUrl?: string\n  provider?: \"acs-teams\"\n  audioSource?: AcsAudioSource\n  activeStream?: AcsActiveStream\n  audioSafety?: AcsAudioSafety\n  mediaSource?: AcsMediaSourceState\n  /** Remote roster (Android emits this; iOS does not yet). */\n  participants?: AcsMeetingParticipant[]\n}\n\nexport type AcsOutgoingVideo = {\n  width: number\n  height: number\n  fps: number\n  maxBitrateBps: number\n}\n\nexport type AcsMeetingJoinOptions = {\n  meetingUrl: string\n  token: string\n  whepUrl: string\n  displayName?: string\n  /** \"glasses\" sends WHEP PCM. \"phone\" uses the ACS local mic (handset or BT). */\n  audioSource?: AcsAudioSource\n  /**\n   * Hold outgoing PCM this many ms before ACS. SoftAP+LC3 sets this in the host\n   * because BLE audio reaches the phone before SoftAP video.\n   */\n  audioDelayMs?: number\n  /** Dump WHEP PCM to a WAV in cache for P4 verification. */\n  dumpPcmWav?: boolean\n  /** When omitted, native keeps 1280×720@15 / 2.5 Mbps. */\n  video?: AcsOutgoingVideo\n}\n\nexport type AcsIncomingPcmEvent = {\n  base64: string\n  sampleRate: number\n  channels: number\n}\n\nexport type AcsMeetingModuleEvents = {\n  onState: (state: AcsMeetingState) => void\n  onIncomingPcm: (pcm: AcsIncomingPcmEvent) => void\n}\n"]}