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

package/android/src/main/java/com/mentra/acsmeeting/telemetry/AvSyncProbe.kt

@@ -0,0 +1,155 @@
+package com.mentra.acsmeeting.telemetry
+
+import android.util.Log
+import kotlin.math.abs
+
+/**
+ * Measures how far glasses audio leads glasses video at ACS ingest.
+ *
+ * SoftAP video and BLE LC3 do not share a capture clock, so first-frame arrival is startup
+ * skew, not lip-sync. This probe watches both paths on [System.nanoTime]: a clap in frame is a
+ * loud PCM transient and a luma jump. Their difference is [lastAudioLeadMs] — the number the
+ * delay line can cancel. ACS/Teams jitter after ingest is still a receiver recording.
+ *
+ * Audio is sampled at uplink ingest, in front of any configured delay, so the lead is the raw
+ * path offset even when the host already holds PCM for alignment.
+ */
+class AvSyncProbe(
+  private val clock: () -> Long = System::nanoTime,
+  private val log: (String) -> Unit = { Log.i(TAG, it) },
+) {
+  private val lock = Any()
+  private var lastMeanAbs = -1
+  private var lastLumaY = -1
+  private var pendingAudioNs = 0L
+  private var pendingVideoNs = 0L
+  private var pendingMeanAbs = -1
+  private var pendingLumaY = -1
+  private var cooldownUntilNs = 0L
+  @Volatile private var clapCount = 0
+  @Volatile private var lastAudioLeadMs: Int? = null
+  @Volatile private var publishedMeanAbs = -1
+  @Volatile private var publishedLumaY = -1
+
+  fun onAudio(pcm: ByteArray, nowNs: Long = clock()) {
+    onAudioLevel(meanAbs16(pcm), nowNs)
+  }
+
+  fun onAudioLevel(meanAbs: Int, nowNs: Long = clock()) {
+    publishedMeanAbs = meanAbs
+    synchronized(lock) {
+      val prev = lastMeanAbs
+      lastMeanAbs = meanAbs
+      expire(nowNs)
+      if (nowNs < cooldownUntilNs) return
+      if (!isAudioTransient(prev, meanAbs)) return
+      if (pendingVideoNs > 0L) {
+        emit(pendingVideoNs - nowNs, meanAbs, pendingLumaY, nowNs)
+        return
+      }
+      pendingAudioNs = nowNs
+      pendingMeanAbs = meanAbs
+    }
+  }
+
+  fun onVideoLuma(y: Int, nowNs: Long = clock()) {
+    publishedLumaY = y
+    synchronized(lock) {
+      val prev = lastLumaY
+      lastLumaY = y
+      expire(nowNs)
+      if (nowNs < cooldownUntilNs) return
+      if (!isVideoTransient(prev, y)) return
+      if (pendingAudioNs > 0L) {
+        emit(nowNs - pendingAudioNs, pendingMeanAbs, y, nowNs)
+        return
+      }
+      pendingVideoNs = nowNs
+      pendingLumaY = y
+    }
+  }
+
+  fun lastAudioLeadMs(): Int? = lastAudioLeadMs
+
+  fun clapCount(): Int = clapCount
+
+  fun tick(videoE2eP50: String, videoAgeP50: String): String {
+    val lead = lastAudioLeadMs
+    return "AVSYNC live videoE2eP50=$videoE2eP50 " +
+      "videoAgeP50=$videoAgeP50 " +
+      "lastClapLeadMs=${lead?.toString() ?: "na"} clapN=$clapCount " +
+      "meanAbs=$publishedMeanAbs lumaY=$publishedLumaY"
+  }
+
+  fun reset() {
+    synchronized(lock) {
+      lastMeanAbs = -1
+      lastLumaY = -1
+      pendingAudioNs = 0L
+      pendingVideoNs = 0L
+      pendingMeanAbs = -1
+      pendingLumaY = -1
+      cooldownUntilNs = 0L
+      clapCount = 0
+      lastAudioLeadMs = null
+      publishedMeanAbs = -1
+      publishedLumaY = -1
+    }
+  }
+
+  private fun emit(leadNs: Long, meanAbs: Int, lumaY: Int, nowNs: Long) {
+    val leadMs = (leadNs / 1_000_000L).toInt()
+    lastAudioLeadMs = leadMs
+    clapCount += 1
+    pendingAudioNs = 0L
+    pendingVideoNs = 0L
+    pendingMeanAbs = -1
+    pendingLumaY = -1
+    cooldownUntilNs = nowNs + COOLDOWN_NS
+    log("AVSYNC clap audioLeadMs=$leadMs meanAbs=$meanAbs lumaY=$lumaY clapN=$clapCount")
+  }
+
+  private fun expire(nowNs: Long) {
+    if (pendingAudioNs > 0L && nowNs - pendingAudioNs > MATCH_WINDOW_NS) {
+      pendingAudioNs = 0L
+      pendingMeanAbs = -1
+    }
+    if (pendingVideoNs > 0L && nowNs - pendingVideoNs > MATCH_WINDOW_NS) {
+      pendingVideoNs = 0L
+      pendingLumaY = -1
+    }
+  }
+
+  companion object {
+    private const val TAG = "ACS-SPIKE"
+    internal const val AUDIO_CLAP = 2_000
+    internal const val AUDIO_RISE = 1_500
+    internal const val VIDEO_JUMP = 10
+    internal const val MATCH_WINDOW_NS = 500L * 1_000_000L
+    internal const val COOLDOWN_NS = 750L * 1_000_000L
+
+    fun meanAbs16(pcm: ByteArray): Int {
+      var acc = 0L
+      var n = 0
+      var i = 0
+      while (i + 1 < pcm.size) {
+        val s = (pcm[i].toInt() and 0xff) or (pcm[i + 1].toInt() shl 8)
+        val signed = if (s >= 0x8000) s - 0x10000 else s
+        acc += abs(signed)
+        n++
+        i += 2
+      }
+      return if (n == 0) 0 else (acc / n).toInt()
+    }
+
+    internal fun isAudioTransient(previous: Int, current: Int): Boolean {
+      if (previous < 0 || current < AUDIO_CLAP) return false
+      return current - previous >= AUDIO_RISE
+    }
+
+    internal fun isVideoTransient(previous: Int, current: Int): Boolean {
+      if (previous < 0) return false
+      return abs(current - previous) >= VIDEO_JUMP
+    }
+  }
+}

package/android/src/main/java/com/mentra/acsmeeting/telemetry/PipelineStats.kt

@@ -24,6 +24,7 @@ class PipelineStats(
   private val dropNotStarted = AtomicInteger(0)
   private val dropFail = AtomicInteger(0)
   private val dropNullI420 = AtomicInteger(0)
+  private val dropPaced = AtomicInteger(0)
   private val abandoned = AtomicInteger(0)
   private val dup = AtomicInteger(0)
   private val rot = AtomicInteger(0)
@@ -33,6 +34,8 @@ class PipelineStats(
 
   private val lastTickSink = AtomicInteger(0)
   private val lastTickSub = AtomicInteger(0)
+  private val lastTickPackets = AtomicInteger(0)
+  private val lastPacketsAtMs = AtomicLong(0)
   private val lastTickMs = AtomicLong(0)
 
   private val lastArrivalNs = AtomicLong(0)
@@ -46,6 +49,28 @@ class PipelineStats(
   val copy = RingPercentile()
   val send = RingPercentile()
 
+  /**
+   * How stale a frame already is when the decoder hands it to us.
+   *
+   * Everything else on this ladder measures work we do, so all of it can read healthy while the
+   * wearer's picture lags seconds behind: capture, encode, and the network happen before our first
+   * timestamp. WebRTC's extrapolated capture time is the only upstream clock we get, and it is an
+   * estimate — read the trend, not the absolute value.
+   */
+  val age = RingPercentile()
+
+  /**
+   * Wait between handing a frame to the ACS sender and its single send thread picking it up.
+   *
+   * The one stage with no other symptom. `sendP95` times the ACS call itself, so a backed-up
+   * `acs-i420-send` queue shows only as drops at the gate, with every timing on this ladder still
+   * looking fast.
+   */
+  val queue = RingPercentile()
+
+  /** Decoder-estimated capture time to ACS accepting the frame: the number the far end feels. */
+  val e2e = RingPercentile()
+
   /**
    * WebRTC inbound-rtp disposition. Cumulative; the ladder prints deltas so a
    * climbing counter is visible without reading absolute values.
@@ -74,12 +99,30 @@ class PipelineStats(
   @Volatile var pix: String = "i420"
   /** MEDIA_STATISTICS codecName, underscored. Empty until the first report. */
   @Volatile var codecName: String = ""
+  /** The fps we declared to ACS, so [VideoRateVerdict] can score against it. */
+  @Volatile var advertisedFps: Double = 0.0
+  /** The bitrate ceiling we granted ACS, for the starved-versus-CPU-bound split. */
+  @Volatile var budgetBps: Int = 0
+  /** Last rates computed by [tick], kept so the verdict scores the same numbers the ladder printed. */
+  @Volatile var lastSinkFps: Double = 0.0
+  @Volatile var lastSubFps: Double = 0.0
   @Volatile var decodedFps: Double? = null
   @Volatile var recvFps: Double? = null
   @Volatile var wireFps: Double? = null
   @Volatile var wireWidth: Int? = null
   @Volatile var wireHeight: Int? = null
   @Volatile var wireBitrateBps: Long? = null
+  /** ACS cumulative outgoing packet count; differenced per tick into [lastPacketsPerSecond]. */
+  @Volatile var wirePacketCount: Int? = null
+  @Volatile var lastPacketsPerSecond: Double? = null
+
+  /**
+   * Latest ACS `networkSendQuality`, the only send-side network signal the SDK
+   * exposes. It arrives on change rather than on a schedule, so it is latched here
+   * and reprinted every tick — a GOOD/POOR that fired once before the bitrate
+   * started sliding is exactly the line nobody scrolls back far enough to find.
+   */
+  @Volatile var sendQuality: String = ""
   @Volatile private var recv: RecvHealth? = null
   @Volatile private var recvPrev: RecvHealth? = null
   @Volatile var width: Int = 0
@@ -125,6 +168,15 @@ class PipelineStats(
   fun onDropFail() = dropFail.incrementAndGet()
   fun onDropMalformed() = dropFail.incrementAndGet()
 
+  /**
+   * Dropped because it arrived sooner than the rate we advertised to ACS.
+   *
+   * Distinct from [onDropBusy]: the send thread is idle, we just refuse to
+   * over-feed the software encoder. Counted in [dropCount] so conservation
+   * still holds after the sink has already seen the frame.
+   */
+  fun onDropPaced() = dropPaced.incrementAndGet()
+
   /**
    * A send that timed out. The future is not cancelled, so ACS may still read those
    * direct buffers; they are never recycled. Non-zero here means the pool is leaking.
@@ -221,7 +273,8 @@ class PipelineStats(
 
   fun sinkCount(): Int = sink.get()
   fun subCount(): Int = sub.get()
-  fun dropCount(): Int = dropSize.get() + dropBusy.get() + dropNotStarted.get() + dropFail.get() + dropNullI420.get()
+  fun dropCount(): Int =
+    dropSize.get() + dropBusy.get() + dropNotStarted.get() + dropFail.get() + dropNullI420.get() + dropPaced.get()
 
   /** Read sink last: every frame hits sink before sub or drop, so this cannot go negative. */
   fun inFlightCount(): Int {
@@ -234,6 +287,26 @@ class PipelineStats(
 
   fun conserved(): Boolean = inFlightCount() >= 0
 
+  /**
+   * The phone-side stage with the highest p95, so a soak log names its own bottleneck.
+   *
+   * Only stages we actually perform are ranked. [age] is excluded on purpose: it is dominated by
+   * capture, encode and the network, so including it would make every healthy call blame a stage
+   * this device does not run. It is printed beside the verdict instead, which is what separates
+   * "the phone is slow" from "the phone is fine and the frames arrive late".
+   */
+  fun slowestStage(): String {
+    val stages = listOf(
+      "scale" to scale.p95Ms(),
+      "toI420" to toI420.p95Ms(),
+      "copy" to copy.p95Ms(),
+      "queue" to queue.p95Ms(),
+      "send" to send.p95Ms(),
+    )
+    val worst = stages.filter { it.second >= 0 }.maxByOrNull { it.second } ?: return "na"
+    return "${worst.first}=${format(worst.second)}"
+  }
+
   fun tick(): String {
     val now = nowMs()
     val previous = lastTickMs.get()
@@ -245,6 +318,23 @@ class PipelineStats(
     val subDelta = subNow - lastTickSub.getAndSet(subNow)
     val sinkRate = rate(sinkDelta, dt)
     val subRate = rate(subDelta, dt)
+    lastSinkFps = sinkDelta * 1000.0 / dt
+    lastSubFps = subDelta * 1000.0 / dt
+    // ACS reports packets cumulatively on the MEDIA_STATISTICS interval, which is
+    // several times longer than this 1 Hz tick. Differencing every tick reported
+    // pps=0.0 on every tick between reports, so rate is measured across the gap
+    // between actual changes and held in between rather than recomputed against a
+    // count that did not move.
+    wirePacketCount?.let { total ->
+      val previous = lastTickPackets.get()
+      if (total != previous) {
+        val previousAt = lastPacketsAtMs.getAndSet(now)
+        if (previous in 1..total && previousAt > 0) {
+          lastPacketsPerSecond = (total - previous) * 1000.0 / (now - previousAt).coerceAtLeast(1L)
+        }
+        lastTickPackets.set(total)
+      }
+    }
     val dec = decodedFps?.let { formatRate(it) } ?: "na"
     val rcv = recvFps?.let { formatRate(it) } ?: "na"
     val wireFpsLabel = wireFps?.let { formatRate(it) } ?: "na"
@@ -257,13 +347,14 @@ class PipelineStats(
     val inFlightNow = inFlightCount()
     val conserve = if (inFlightNow >= 0) "" else " CONSERVE_FAIL"
     return "P6 ladder arm=$arm $sizeLabel recv=$rcv dec=$dec sink=$sinkRate dup=${dup.get()} sub=$subRate wire=$wire rot=${rot.get()} " +
-      "drop{size=${dropSize.get()} busy=${dropBusy.get()} notStarted=${dropNotStarted.get()} fail=${dropFail.get()} nullI420=${dropNullI420.get()} abandoned=${abandoned.get()}} " +
+      "drop{size=${dropSize.get()} busy=${dropBusy.get()} notStarted=${dropNotStarted.get()} fail=${dropFail.get()} nullI420=${dropNullI420.get()} pace=${dropPaced.get()} abandoned=${abandoned.get()}} " +
       "${recvLabel()} " +
       "path{mode=$pathMode copy=$pathCopy pix=$pix} " +
       "buf{tex=${bufTex.get()} i420=${bufI420.get()} other=${bufOther.get()}} " +
       "stride{y=$strideY u=$strideU v=$strideV tight=${strideTight.get()} padded=${stridePadded.get()}} " +
       "zc{on=$zcOn used=${zcUsed.get()} fell=${zcFell.get()} padded=${zcPadded.get()} heldMax=${zcHeldMax.get()} timeout=${zcTimeout.get()}} " +
-      "ms{gapP50=${gap.p50()} gapP95=${gap.p95()} i420P95=${toI420.p95()} packP95=${pack.p95()} scaleP95=${scale.p95()} sinkCbP95=${sinkCb.p95()} splitP95=${split.p95()} copyP95=${copy.p95()} sendP95=${send.p95()}} " +
+      "ms{gapP50=${gap.p50()} gapP95=${gap.p95()} i420P95=${toI420.p95()} packP95=${pack.p95()} scaleP95=${scale.p95()} sinkCbP95=${sinkCb.p95()} splitP95=${split.p95()} copyP95=${copy.p95()} queueP95=${queue.p95()} sendP95=${send.p95()}} " +
+      "lat{ageP50=${age.p50()} ageP95=${age.p95()} e2eP50=${e2e.p50()} e2eP95=${e2e.p95()} slowest=${slowestStage()}} " +
       "alloc{dest=${destAlloc.get()} plane=${planeAlloc.get()}} " +
       "chroma{y=$chromaY u=$chromaU v=$chromaV} " +
       "cum{sink=$sinkNow sub=$subNow drop=${dropCount()} inFlight=$inFlightNow}" +

package/android/src/main/java/com/mentra/acsmeeting/telemetry/PipelineTicker.kt

@@ -7,6 +7,7 @@ import android.os.Process
 /** Timer-driven 1 Hz emit so a stall prints sink=0 instead of going silent. */
 class PipelineTicker(
   private val stats: PipelineStats,
+  private val avSync: AvSyncProbe? = null,
   looper: Looper = Looper.getMainLooper(),
   private val elapsedCpuMs: () -> Long = { Process.getElapsedCpuTime() },
   private val cores: Int = Runtime.getRuntime().availableProcessors(),
@@ -17,7 +18,35 @@ class PipelineTicker(
   private var lastWallMs = 0L
   private val tick = object : Runnable {
     override fun run() {
-      emit("${stats.tick()} ${cpuLabel()}")
+      // CPU is sampled once and shared: the ladder prints it and the verdict uses
+      // it to tell an encoder that cannot keep up from one being throttled.
+      val percent = samplePercent()
+      emit("${stats.tick()} ${ProcessCpu.label(percent, cores)}")
+      emit(
+        VideoRateVerdict.line(
+          advertisedFps = stats.advertisedFps,
+          sinkFps = stats.lastSinkFps,
+          admittedFps = stats.lastSubFps,
+          wireFps = stats.wireFps,
+          wireBitrateBps = stats.wireBitrateBps,
+          budgetBps = stats.budgetBps,
+          cpuPercent = percent,
+          codecName = stats.codecName,
+        ),
+      )
+      emit(
+        VideoQuality.line(
+          wireWidth = stats.wireWidth,
+          wireHeight = stats.wireHeight,
+          wireFps = stats.wireFps,
+          wireBitrateBps = stats.wireBitrateBps,
+          budgetBps = stats.budgetBps,
+          packetsPerSecond = stats.lastPacketsPerSecond,
+          cpuPercent = percent,
+          sendQuality = stats.sendQuality,
+        ),
+      )
+      avSync?.let { emit(it.tick(stats.e2e.p50(), stats.age.p50())) }
       handler.postDelayed(this, INTERVAL_MS)
     }
   }
@@ -33,16 +62,15 @@ class PipelineTicker(
     handler.removeCallbacks(tick)
   }
 
-  private fun cpuLabel(): String {
+  private fun samplePercent(): Double? {
     val now = System.currentTimeMillis()
     val cpu = elapsedCpuMs()
     val prevCpu = lastCpuMs
     val prevWall = lastWallMs
     lastCpuMs = cpu
     lastWallMs = now
-    val percent = if (prevCpu < 0 || prevWall <= 0) null
-    else ProcessCpu.percent(cpu - prevCpu, now - prevWall)
-    return ProcessCpu.label(percent, cores)
+    if (prevCpu < 0 || prevWall <= 0) return null
+    return ProcessCpu.percent(cpu - prevCpu, now - prevWall)
   }
 
   companion object {

package/android/src/main/java/com/mentra/acsmeeting/telemetry/RingPercentile.kt

@@ -28,6 +28,21 @@ class RingPercentile(private val capacity: Int = 32) {
     return ((copy[idx] / 1_000_000.0) * 10).roundToInt().div(10.0).toString()
   }
 
+  /**
+   * p95 in milliseconds, or -1 when nothing has been recorded.
+   *
+   * Numeric rather than the formatted [p95] because the ladder ranks stages against each other to
+   * name the slowest one, and comparing the rendered strings would order "9.0" above "10.0".
+   */
+  @Synchronized
+  fun p95Ms(): Double {
+    if (count == 0) return -1.0
+    val copy = samples.copyOf(count)
+    copy.sort()
+    val idx = ((copy.size - 1) * 0.95).roundToInt().coerceIn(0, copy.lastIndex)
+    return copy[idx] / 1_000_000.0
+  }
+
   @Synchronized
   fun size(): Int = count
 }

package/android/src/main/java/com/mentra/acsmeeting/telemetry/VideoQuality.kt

@@ -0,0 +1,178 @@
+package com.mentra.acsmeeting.telemetry
+
+import kotlin.math.roundToInt
+
+/**
+ * How good the picture is, as opposed to how many frames of it there are.
+ *
+ * Every rate number we log can be healthy while Teams shows mush, because
+ * "pixelated" is bits per pixel and nothing in the ladder computed that.
+ * `wire=960x540@14.4 kbps=1276` reads fine and is 0.17 bits per pixel, which is
+ * under what a head-mounted camera needs. ACS 2.16.0's
+ * `OutgoingVideoStatistics` exposes no QP and no quality-limitation reason —
+ * only codec, bitrate, packet count, rate, and size — so bits per pixel is the
+ * only quality signal available and it has to be derived here.
+ *
+ * Bands come from the Kush gauge, the standard H.264 estimate
+ * `bitrate ≈ width · height · fps · 0.07 · motion`, which rearranges to
+ * `bpp ≈ 0.07 · motion`. Motion is 1 for a near-static scene, 2 for moderate,
+ * and 4 for high. Glasses are strapped to someone's head, so the honest target
+ * is the high-motion one — which is why a number sitting mid-band can still
+ * look bad and the log says so rather than printing a bare "OK".
+ */
+object VideoQuality {
+  enum class Band {
+    /** Below what even a static scene needs. Visible blocking. */
+    BLOCKY,
+
+    /** Enough for a near-static scene only. Soft, smeared on movement. */
+    SOFT,
+
+    /** Enough for moderate motion. Still short for a head-mounted camera. */
+    OK,
+
+    /** Enough for high motion, which is what glasses actually produce. */
+    GOOD,
+
+    UNKNOWN,
+  }
+
+  /** bpp ≈ 0.07 · motion, for motion = 1, 2, and 4. */
+  const val STATIC_BPP = 0.07
+  const val MODERATE_BPP = 0.14
+  const val HIGH_MOTION_BPP = 0.28
+
+  fun bitsPerPixel(bitrateBps: Long?, width: Int?, height: Int?, fps: Double?): Double? {
+    if (bitrateBps == null || width == null || height == null || fps == null) return null
+    if (bitrateBps <= 0 || width <= 0 || height <= 0 || fps <= 0.0) return null
+    return bitrateBps / (width.toDouble() * height * fps)
+  }
+
+  fun band(bpp: Double?): Band = when {
+    bpp == null -> Band.UNKNOWN
+    bpp < STATIC_BPP -> Band.BLOCKY
+    bpp < MODERATE_BPP -> Band.SOFT
+    bpp < HIGH_MOTION_BPP -> Band.OK
+    else -> Band.GOOD
+  }
+
+  /** Bitrate this geometry needs to reach [bpp], so the log can name the shortfall. */
+  fun neededBps(width: Int, height: Int, fps: Double, bpp: Double): Long {
+    if (width <= 0 || height <= 0 || fps <= 0.0) return 0L
+    return (width.toDouble() * height * fps * bpp).toLong()
+  }
+
+  /**
+   * Whether the granted ceiling can even reach high motion at this geometry.
+   *
+   * This is the check that turns "the picture is bad" into a decision. 540p15
+   * against a 1.5 Mbps budget tops out at 0.19 bpp even if ACS spends every bit,
+   * so no encoder change and no rate fix can make that combination look sharp on
+   * a moving camera — the budget is the ceiling, and it has to move.
+   */
+  fun budgetCapsQuality(width: Int, height: Int, fps: Double, budgetBps: Int): Boolean {
+    if (budgetBps <= 0) return false
+    return budgetBps < neededBps(width, height, fps, HIGH_MOTION_BPP)
+  }
+
+  /**
+   * Whether ACS is actually spending what it was granted.
+   *
+   * The grant is a target, not a wall — a device run recorded `used=108%`, the wire
+   * at 1623 kbps against a 1.5 Mbps grant — so falling short of it is a choice the
+   * rate controller made rather than a limit it hit. That makes the shortfall
+   * diagnostic: something upstream of the ceiling is holding the bitrate down, and
+   * [hint] uses CPU to say which thing.
+   */
+  const val SPENDING_FRACTION = 0.85
+
+  /**
+   * Process CPU at which a software encoder is a plausible cap.
+   *
+   * The figure is a percentage of a *single* core, not of the device, so on an
+   * 8-core phone 88% means one core nearly full while seven sit idle. That still
+   * binds a single-threaded encoder, which is why the threshold sits near one core
+   * rather than near the machine.
+   */
+  const val ENCODER_BUSY_PERCENT = 90.0
+
+  fun spendingBudget(wireBitrateBps: Long?, budgetBps: Int): Boolean {
+    if (wireBitrateBps == null || budgetBps <= 0) return false
+    return wireBitrateBps >= budgetBps * SPENDING_FRACTION
+  }
+
+  fun hint(
+    band: Band,
+    budgetCapped: Boolean,
+    spendingBudget: Boolean,
+    encoderBusy: Boolean,
+  ): String = when {
+    band == Band.UNKNOWN -> "no wire report yet"
+    band == Band.GOOD -> "enough for high motion"
+    !spendingBudget && encoderBusy ->
+      "bits unspent with a core nearly full; encoder is the cap -- cut pixels, not the ceiling"
+    !spendingBudget ->
+      "bits unspent while CPU is idle; congestion control is holding the rate down, " +
+        "so neither a bigger ceiling nor fewer pixels addresses it -- check the network"
+    budgetCapped ->
+      "budget cannot reach high motion at this geometry; raise maxBitrateBps or drop resolution"
+    band == Band.BLOCKY -> "far below any usable bitrate; check for a rate-controller collapse"
+    band == Band.SOFT -> "only enough for a static scene; a head camera will smear"
+    else -> "fine for moderate motion, still short for a head-mounted camera"
+  }
+
+  /**
+   * One line per tick. Prints the derived figures and the bitrate that would be
+   * needed, because "0.17 bpp" alone does not tell anyone what to change.
+   */
+  fun line(
+    wireWidth: Int?,
+    wireHeight: Int?,
+    wireFps: Double?,
+    wireBitrateBps: Long?,
+    budgetBps: Int,
+    packetsPerSecond: Double?,
+    cpuPercent: Double?,
+    sendQuality: String,
+  ): String {
+    val bpp = bitsPerPixel(wireBitrateBps, wireWidth, wireHeight, wireFps)
+    val band = band(bpp)
+    val capped = if (wireWidth != null && wireHeight != null && wireFps != null) {
+      budgetCapsQuality(wireWidth, wireHeight, wireFps, budgetBps)
+    } else {
+      false
+    }
+    val bitsPerFrame = if (wireBitrateBps != null && wireFps != null && wireFps > 0) {
+      (wireBitrateBps / wireFps).roundToInt().toString()
+    } else {
+      "na"
+    }
+    val goodKbps = if (wireWidth != null && wireHeight != null && wireFps != null) {
+      (neededBps(wireWidth, wireHeight, wireFps, HIGH_MOTION_BPP) / 1000).toString()
+    } else {
+      "na"
+    }
+    val usedKbps = wireBitrateBps?.let { (it / 1000).toString() } ?: "na"
+    val usedPercent = if (wireBitrateBps != null && budgetBps > 0) {
+      ((wireBitrateBps * 100.0 / budgetBps).roundToInt()).toString()
+    } else {
+      "na"
+    }
+    return "P9 quality band=$band bpp=${bpp?.let { decimal(it) } ?: "na"} " +
+      "size=${wireWidth ?: 0}x${wireHeight ?: 0}@${wireFps?.let { PipelineStats.formatRate(it) } ?: "na"} " +
+      "bitsPerFrame=$bitsPerFrame kbps=$usedKbps budgetKbps=${budgetBps / 1000} used=$usedPercent% " +
+      "goodNeedsKbps=$goodKbps budgetCapped=$capped " +
+      "pps=${packetsPerSecond?.let { PipelineStats.formatRate(it) } ?: "na"} " +
+      "cpu=${cpuPercent?.let { PipelineStats.formatRate(it) } ?: "na"} " +
+      "sendQuality=${sendQuality.ifBlank { "na" }} -- " +
+      hint(
+        band = band,
+        budgetCapped = capped,
+        spendingBudget = spendingBudget(wireBitrateBps, budgetBps),
+        encoderBusy = cpuPercent != null && cpuPercent >= ENCODER_BUSY_PERCENT,
+      )
+  }
+
+  /** Three places, because bpp differences that matter show up in the third. */
+  private fun decimal(value: Double): String = ((value * 1000).roundToInt() / 1000.0).toString()
+}