@mentra/acs-meeting 3.2.0-dev.120

package/android/src/main/java/com/mentra/acsmeeting/RemoteRoster.kt

@@ -0,0 +1,123 @@
+package com.mentra.acsmeeting
+
+import android.util.Log
+import com.azure.android.communication.calling.Call
+import com.azure.android.communication.calling.ParticipantState
+import com.azure.android.communication.calling.ParticipantsUpdatedListener
+import com.azure.android.communication.calling.PropertyChangedListener
+import com.azure.android.communication.calling.RemoteParticipant
+import java.util.concurrent.ConcurrentHashMap
+
+/**
+ * Tracks ACS remote participants so the host can show who is in the room.
+ * Listener callbacks arrive on ACS threads; [onChanged] must hop to the
+ * session executor before touching session state.
+ */
+class RemoteRoster(
+  private val onChanged: () -> Unit,
+) {
+  private class Tracked(
+    val participant: RemoteParticipant,
+    val listener: PropertyChangedListener,
+  )
+
+  private var call: Call? = null
+  private var updatedListener: ParticipantsUpdatedListener? = null
+  private val tracked = ConcurrentHashMap<String, Tracked>()
+
+  fun attach(joined: Call) {
+    detach()
+    call = joined
+    val listener = ParticipantsUpdatedListener { event ->
+      event.addedParticipants.forEach { track(it) }
+      event.removedParticipants.forEach { untrack(it) }
+      Log.i(TAG, "roster updated added=${event.addedParticipants.size} removed=${event.removedParticipants.size} size=${tracked.size}")
+      onChanged()
+    }
+    joined.addOnRemoteParticipantsUpdatedListener(listener)
+    updatedListener = listener
+    joined.remoteParticipants.forEach { track(it) }
+    Log.i(TAG, "roster attached size=${tracked.size}")
+  }
+
+  fun detach() {
+    val joined = call
+    val listener = updatedListener
+    call = null
+    updatedListener = null
+    if (joined != null && listener != null) {
+      try {
+        joined.removeOnRemoteParticipantsUpdatedListener(listener)
+      } catch (_: Exception) {
+      }
+    }
+    tracked.values.forEach { removeListeners(it) }
+    tracked.clear()
+  }
+
+  fun snapshot(): List<Map<String, Any?>> =
+    tracked.values
+      .map { describe(it.participant) }
+      .sortedBy { it["id"] as? String ?: "" }
+
+  private fun track(participant: RemoteParticipant) {
+    val id = idOf(participant)
+    if (tracked.containsKey(id)) return
+    val listener = PropertyChangedListener { onChanged() }
+    val entry = Tracked(participant, listener)
+    tracked[id] = entry
+    try {
+      participant.addOnStateChangedListener(listener)
+      participant.addOnIsMutedChangedListener(listener)
+      participant.addOnIsSpeakingChangedListener(listener)
+      participant.addOnDisplayNameChangedListener(listener)
+    } catch (error: Exception) {
+      Log.w(TAG, "roster listener attach failed", error)
+    }
+  }
+
+  private fun untrack(participant: RemoteParticipant) {
+    tracked.remove(idOf(participant))?.let { removeListeners(it) }
+  }
+
+  private fun removeListeners(entry: Tracked) {
+    try {
+      entry.participant.removeOnStateChangedListener(entry.listener)
+      entry.participant.removeOnIsMutedChangedListener(entry.listener)
+      entry.participant.removeOnIsSpeakingChangedListener(entry.listener)
+      entry.participant.removeOnDisplayNameChangedListener(entry.listener)
+    } catch (_: Exception) {
+    }
+  }
+
+  companion object {
+    private const val TAG = "ACS-SPIKE"
+
+    fun idOf(participant: RemoteParticipant): String =
+      try {
+        participant.identifier?.rawId ?: "participant-${System.identityHashCode(participant)}"
+      } catch (_: Exception) {
+        "participant-${System.identityHashCode(participant)}"
+      }
+
+    fun describe(participant: RemoteParticipant): Map<String, Any?> {
+      val state = try { participant.state } catch (_: Exception) { null }
+      return mapOf(
+        "id" to idOf(participant),
+        "displayName" to (try { participant.displayName } catch (_: Exception) { null }),
+        "state" to stateName(state),
+        "isMuted" to (try { participant.isMuted } catch (_: Exception) { false }),
+        "isSpeaking" to (try { participant.isSpeaking } catch (_: Exception) { false }),
+      )
+    }
+
+    fun stateName(state: ParticipantState?): String = when (state) {
+      ParticipantState.CONNECTED -> "connected"
+      ParticipantState.CONNECTING, ParticipantState.RINGING, ParticipantState.EARLY_MEDIA -> "connecting"
+      ParticipantState.IN_LOBBY -> "lobby"
+      ParticipantState.HOLD -> "hold"
+      ParticipantState.DISCONNECTED -> "disconnected"
+      ParticipantState.IDLE, null -> "idle"
+    }
+  }
+}

package/android/src/main/java/com/mentra/acsmeeting/audio/AcsAudioPolicy.kt

@@ -0,0 +1,90 @@
+package com.mentra.acsmeeting.audio
+
+enum class AudioSourceKind { GLASSES, PHONE }
+
+/** Mirrors (AudioStreamType, AudioStreamState). Attached-but-STOPPED reads as NONE. */
+enum class ActiveStreamKind { NONE, VIRTUAL, LOCAL }
+
+enum class PhysicalMuteAction { MUTE, UNMUTE, LEAVE_ALONE }
+
+enum class AudioSafety { SAFE, DEGRADED, UNSAFE }
+
+data class AudioPolicyDecision(
+  val glassesPcmEnabled: Boolean,
+  val phonePcmEnabled: Boolean,
+  val physicalMute: PhysicalMuteAction,
+)
+
+/** Transport mute is an ACS join concern, distinct from user intent. */
+data class JoinAudioPlan(
+  val armVirtual: Boolean,
+  val transportMuted: Boolean,
+)
+
+object AcsAudioPolicy {
+  fun decide(
+    desired: AudioSourceKind,
+    active: ActiveStreamKind,
+    userMuted: Boolean,
+  ): AudioPolicyDecision {
+    val glassesPcmEnabled =
+      active == ActiveStreamKind.VIRTUAL &&
+        desired == AudioSourceKind.GLASSES &&
+        !userMuted
+    val phonePcmEnabled =
+      active == ActiveStreamKind.VIRTUAL &&
+        desired == AudioSourceKind.PHONE &&
+        !userMuted
+    val physicalMute = when (active) {
+      ActiveStreamKind.VIRTUAL, ActiveStreamKind.NONE -> PhysicalMuteAction.LEAVE_ALONE
+      ActiveStreamKind.LOCAL ->
+        if (desired == AudioSourceKind.PHONE && !userMuted) {
+          PhysicalMuteAction.UNMUTE
+        } else {
+          PhysicalMuteAction.MUTE
+        }
+    }
+    return AudioPolicyDecision(glassesPcmEnabled, phonePcmEnabled, physicalMute)
+  }
+
+  fun planJoin(
+    desired: AudioSourceKind,
+    userMuted: Boolean,
+    glassesRequiresUnmutedTransport: Boolean,
+  ): JoinAudioPlan {
+    // Phone and glasses both feed RawOutgoingAudioStream. Mute is PCM/capturer
+    // gating, never a LocalOutgoingAudioStream (that path makes ACS own the route).
+    val armVirtual = true
+    val transportMuted =
+      if (desired == AudioSourceKind.GLASSES && glassesRequiresUnmutedTransport) {
+        false
+      } else if (desired == AudioSourceKind.PHONE) {
+        false
+      } else {
+        userMuted
+      }
+    return JoinAudioPlan(armVirtual = armVirtual, transportMuted = transportMuted)
+  }
+
+  @Suppress("UNUSED_PARAMETER")
+  fun expectedStream(desired: AudioSourceKind): ActiveStreamKind = ActiveStreamKind.VIRTUAL
+
+  fun parseSource(raw: String?): AudioSourceKind? =
+    when (raw) {
+      "glasses" -> AudioSourceKind.GLASSES
+      "phone" -> AudioSourceKind.PHONE
+      else -> null
+    }
+}
+
+/** Layer 1: what the glasses encoder captures for this WHIP session. Independent of ACS. */
+object CapturePolicy {
+  fun captureGlassesMic(source: AudioSourceKind): Boolean = source == AudioSourceKind.GLASSES
+}
+
+/** Null ACS call handles must fail, never report success via `call?.mute(); Unit`. */
+object CallGuard {
+  fun <T : Any> require(value: T?): Result<T> =
+    if (value == null) Result.failure(IllegalStateException("no call"))
+    else Result.success(value)
+}

package/android/src/main/java/com/mentra/acsmeeting/audio/AudioPolicyApplier.kt

@@ -0,0 +1,176 @@
+package com.mentra.acsmeeting.audio
+
+interface AudioStreamController {
+  fun readActive(): ActiveStreamKind
+  fun isPhysicallyMuted(): Boolean?
+  fun setGlassesPcmEnabled(enabled: Boolean)
+  fun setPhonePcmEnabled(enabled: Boolean)
+  fun mutePhysical(): Result<Unit>
+  fun unmutePhysical(): Result<Unit>
+  fun stopActive(): Result<Unit>
+}
+
+interface PolicyScheduler {
+  fun schedule(delayMs: Long, task: () -> Unit)
+  fun cancelPending()
+}
+
+class AudioPolicyApplier(
+  private val controller: AudioStreamController,
+  private val scheduler: PolicyScheduler,
+  private val log: (String) -> Unit = {},
+) {
+  private var generation = 0L
+  private var lastDecision: AudioPolicyDecision? = null
+  private var lastSafety: AudioSafety = AudioSafety.DEGRADED
+
+  fun lastSafety(): AudioSafety = lastSafety
+
+  fun apply(desired: AudioSourceKind, userMuted: Boolean, reason: String): AudioSafety {
+    generation += 1
+    scheduler.cancelPending()
+    return runApply(desired, userMuted, reason, generation, force = false, armConvergence = true)
+  }
+
+  fun reset() {
+    generation += 1
+    scheduler.cancelPending()
+    lastDecision = null
+    lastSafety = AudioSafety.DEGRADED
+  }
+
+  private fun runApply(
+    desired: AudioSourceKind,
+    userMuted: Boolean,
+    reason: String,
+    gen: Long,
+    force: Boolean,
+    armConvergence: Boolean,
+  ): AudioSafety {
+    if (gen != generation) return lastSafety
+    val active = controller.readActive()
+    val decision = AcsAudioPolicy.decide(desired, active, userMuted)
+    val outcome = applyDecision(decision, force)
+    if (gen != generation) return lastSafety
+
+    val after = controller.readActive()
+    val expected = AcsAudioPolicy.expectedStream(desired)
+    val safety = safetyOf(desired, after, outcome)
+    lastDecision = decision
+    lastSafety = safety
+    log(
+      "audio policy reason=$reason source=$desired userMuted=$userMuted " +
+        "active=$after expected=$expected glassesPcm=${decision.glassesPcmEnabled} " +
+        "phonePcm=${decision.phonePcmEnabled} mute=${decision.physicalMute} safety=$safety",
+    )
+
+    if (after == expected) {
+      scheduler.cancelPending()
+    } else if (armConvergence && gen == generation) {
+      armConvergence(desired, userMuted, gen, expected)
+    }
+    return lastSafety
+  }
+
+  private fun armConvergence(
+    desired: AudioSourceKind,
+    userMuted: Boolean,
+    gen: Long,
+    expected: ActiveStreamKind,
+  ) {
+    CONVERGE_DELAYS_MS.forEachIndexed { index, delayMs ->
+      scheduler.schedule(delayMs) {
+        if (gen != generation) return@schedule
+        val isLast = index == CONVERGE_DELAYS_MS.lastIndex
+        runApply(desired, userMuted, "converge-${delayMs}ms", gen, force = true, armConvergence = false)
+        if (isLast && gen == generation && controller.readActive() != expected) {
+          log("audio policy convergence timed out source=$desired expected=$expected holding silence")
+          lastSafety = AudioSafety.DEGRADED
+        }
+      }
+    }
+  }
+
+  private fun applyDecision(decision: AudioPolicyDecision, force: Boolean): EffectOutcome {
+    val previous = lastDecision
+    val skipGlassesPcm = !force && previous != null && previous.glassesPcmEnabled == decision.glassesPcmEnabled
+    val skipPhonePcm = !force && previous != null && previous.phonePcmEnabled == decision.phonePcmEnabled
+    val skipMute = !force && previous != null && previous.physicalMute == decision.physicalMute
+    if (!skipGlassesPcm) {
+      controller.setGlassesPcmEnabled(decision.glassesPcmEnabled)
+    }
+    if (!skipPhonePcm) {
+      controller.setPhonePcmEnabled(decision.phonePcmEnabled)
+    }
+    if (skipMute) return EffectOutcome.NONE
+
+    return when (decision.physicalMute) {
+      PhysicalMuteAction.LEAVE_ALONE -> EffectOutcome.NONE
+      PhysicalMuteAction.UNMUTE -> {
+        val result = controller.unmutePhysical()
+        val unmuted = controller.isPhysicallyMuted()
+        val failed = result.isFailure || unmuted == true
+        EffectOutcome(unmuteAttempted = true, unmuteFailed = failed)
+      }
+      PhysicalMuteAction.MUTE -> {
+        val result = controller.mutePhysical()
+        val muted = controller.isPhysicallyMuted()
+        val muteFailed = result.isFailure || muted == false
+        if (!muteFailed) return EffectOutcome(muteAttempted = true)
+        val stop = controller.stopActive()
+        val stopped = controller.readActive() == ActiveStreamKind.NONE
+        EffectOutcome(
+          muteAttempted = true,
+          muteFailed = true,
+          stopAttempted = true,
+          stopFailed = stop.isFailure || !stopped,
+        )
+      }
+    }
+  }
+
+  private fun safetyOf(
+    desired: AudioSourceKind,
+    active: ActiveStreamKind,
+    outcome: EffectOutcome,
+  ): AudioSafety {
+    if (outcome.stopFailed) return AudioSafety.UNSAFE
+    if (outcome.stopAttempted) return AudioSafety.SAFE
+    if (outcome.unmuteFailed) return AudioSafety.DEGRADED
+    val expected = AcsAudioPolicy.expectedStream(desired)
+    if (active != expected) return AudioSafety.DEGRADED
+    return AudioSafety.SAFE
+  }
+
+  private data class EffectOutcome(
+    val muteAttempted: Boolean = false,
+    val muteFailed: Boolean = false,
+    val unmuteAttempted: Boolean = false,
+    val unmuteFailed: Boolean = false,
+    val stopAttempted: Boolean = false,
+    val stopFailed: Boolean = false,
+  ) {
+    companion object {
+      val NONE = EffectOutcome()
+    }
+  }
+
+  companion object {
+    val CONVERGE_DELAYS_MS = longArrayOf(50, 100, 200, 400, 800, 1600)
+  }
+}
+
+class ExecutorPolicyScheduler(
+  private val executor: java.util.concurrent.ScheduledExecutorService,
+) : PolicyScheduler {
+  private val pending = java.util.concurrent.CopyOnWriteArrayList<java.util.concurrent.ScheduledFuture<*>>()
+
+  override fun schedule(delayMs: Long, task: () -> Unit) {
+    pending.add(executor.schedule(task, delayMs, java.util.concurrent.TimeUnit.MILLISECONDS))
+  }
+
+  override fun cancelPending() {
+    pending.forEach { it.cancel(false) }
+    pending.clear()
+  }
+}

package/android/src/main/java/com/mentra/acsmeeting/audio/IncomingAudioPump.kt

@@ -0,0 +1,112 @@
+package com.mentra.acsmeeting.audio
+
+import java.io.ByteArrayOutputStream
+
+/**
+ * ACS mixed-audio buffers → fixed-format chunks for the host PCM player.
+ *
+ * - Normalizes to [OUT_RATE] Hz mono regardless of what ACS actually
+ *   delivers. The requested RawIncomingAudioStreamProperties are a hint;
+ *   the event carries the real format, and playing 48 kHz data on a 16 kHz
+ *   AudioTrack is exactly the "slow, low-pitched" symptom.
+ * - Pre-rolls [prerollMs] before the first emit and then emits in
+ *   [batchMs] chunks, so the player always has headroom over bridge jitter
+ *   instead of underrunning between 20 ms callbacks.
+ *
+ * Not thread-safe: ACS delivers mixed audio from a single thread.
+ */
+class IncomingAudioPump(
+  private val prerollMs: Int = DEFAULT_PREROLL_MS,
+  private val batchMs: Int = DEFAULT_BATCH_MS,
+  private val emit: (pcm16Le: ByteArray) -> Unit,
+) {
+  data class Format(val sampleRate: Int, val channels: Int)
+
+  private val resampler = PcmResampler(OUT_RATE)
+  private val pending = ByteArrayOutputStream()
+  private var primed = false
+
+  var format: Format? = null
+    private set
+  var formatChanges = 0
+    private set
+  var eventsIn = 0L
+    private set
+  var bytesIn = 0L
+    private set
+  var bytesOut = 0L
+    private set
+
+  fun push(pcm16Le: ByteArray, sampleRate: Int, channels: Int) {
+    if (pcm16Le.isEmpty()) return
+    val next = Format(sampleRate, channels)
+    if (format != next) {
+      if (format != null) formatChanges += 1
+      format = next
+    }
+    eventsIn += 1
+    bytesIn += pcm16Le.size
+    val normalized = resampler.process(pcm16Le, sampleRate, channels)
+    pending.write(normalized)
+    drain(force = false)
+  }
+
+  /** Emit whatever is buffered (call on stop so the tail is not lost). */
+  fun flush() {
+    drain(force = true)
+    primed = false
+  }
+
+  fun reset() {
+    pending.reset()
+    primed = false
+    resampler.reset()
+    format = null
+  }
+
+  private fun drain(force: Boolean) {
+    val threshold = if (primed) bytesFor(batchMs) else bytesFor(prerollMs)
+    if (pending.size() == 0) return
+    if (!force && pending.size() < threshold) return
+    val all = pending.toByteArray()
+    pending.reset()
+    // Chunk on batch boundaries so the player queue sees a steady cadence;
+    // the remainder waits for the next callback unless flushing.
+    val batch = bytesFor(batchMs)
+    var offset = 0
+    while (all.size - offset >= batch) {
+      emitChunk(all.copyOfRange(offset, offset + batch))
+      offset += batch
+    }
+    if (offset < all.size) {
+      if (force) emitChunk(all.copyOfRange(offset, all.size)) else pending.write(all, offset, all.size - offset)
+    }
+    primed = true
+  }
+
+  private fun emitChunk(chunk: ByteArray) {
+    bytesOut += chunk.size
+    emit(chunk)
+  }
+
+  companion object {
+    const val OUT_RATE = 16_000
+    const val OUT_CHANNELS = 1
+
+    /**
+     * Downlink headroom, and the only knob for the downlink latency A/B.
+     *
+     * The remote path already stacks Teams/ACS network + ACS receive + RN
+     * bridge batching + this preroll + A2DP buffering, so more is not simply
+     * better: every millisecond here is conversational delay. Walk
+     * [PREROLL_LADDER_MS] on real S22 + Mentra Live hardware and ship the
+     * smallest value with no audible underruns. 120 ms underran on the
+     * reported jitter; 160 ms is one step up, not the top of the ladder.
+     */
+    const val DEFAULT_PREROLL_MS = 160
+    val PREROLL_LADDER_MS = listOf(120, 160, 200)
+    const val DEFAULT_BATCH_MS = 60
+
+    fun bytesFor(ms: Int): Int = OUT_RATE * OUT_CHANNELS * 2 * ms / 1000
+  }
+}

package/android/src/main/java/com/mentra/acsmeeting/audio/IncomingRateProbe.kt

@@ -0,0 +1,65 @@
+package com.mentra.acsmeeting.audio
+
+import kotlin.math.max
+
+/**
+ * Measures what ACS actually delivers on the incoming mixed-audio callback.
+ *
+ * Deriving a rate as `bytes / (2 * channels) * 50` only holds if ACS really
+ * fires exactly every 20 ms — which is the assumption being diagnosed. This
+ * accumulates samples against elapsed monotonic time instead, so a rate ACS
+ * mislabels shows up as `measuredRate` disagreeing with `declaredRate` and a
+ * cadence that is not 20 ms shows up in `callbackHz`.
+ */
+class IncomingRateProbe(private val windowNanos: Long = DEFAULT_WINDOW_NANOS) {
+  data class Reading(
+    val declaredRate: Int,
+    val channels: Int,
+    val samplesPerCallback: Int,
+    val callbackHz: Double,
+    val measuredRate: Double,
+    val events: Long,
+  )
+
+  private var windowStartNanos: Long? = null
+  private var events = 0L
+  private var samples = 0L
+
+  /** Returns a reading at most once per window; null in between. */
+  fun record(nowNanos: Long, bytes: Int, sampleRate: Int, channels: Int): Reading? {
+    val samplesPerCallback = bytes / (2 * max(1, channels))
+    val start = windowStartNanos
+    if (start == null) {
+      // This callback only opens the window; it arrived before it.
+      windowStartNanos = nowNanos
+      return null
+    }
+    events += 1
+    samples += samplesPerCallback
+    val elapsedNanos = nowNanos - start
+    if (elapsedNanos < windowNanos) return null
+    val seconds = elapsedNanos / 1_000_000_000.0
+    val reading = Reading(
+      declaredRate = sampleRate,
+      channels = channels,
+      samplesPerCallback = samplesPerCallback,
+      callbackHz = events / seconds,
+      measuredRate = samples / seconds,
+      events = events,
+    )
+    windowStartNanos = nowNanos
+    events = 0
+    samples = 0
+    return reading
+  }
+
+  fun reset() {
+    windowStartNanos = null
+    events = 0
+    samples = 0
+  }
+
+  companion object {
+    const val DEFAULT_WINDOW_NANOS = 1_000_000_000L
+  }
+}

package/android/src/main/java/com/mentra/acsmeeting/audio/PcmBridge.kt

@@ -0,0 +1,108 @@
+package com.mentra.acsmeeting.audio
+
+import android.util.Base64
+import android.util.Log
+import java.io.ByteArrayOutputStream
+import java.io.File
+import java.nio.ByteBuffer
+import java.nio.ByteOrder
+import kotlin.math.abs
+
+/** Downmix/resample PCM16 to 48 kHz mono ~20 ms blocks for ACS raw outgoing audio. */
+class PcmBridge(
+  private val dumpDir: File?,
+  private val dumpWav: Boolean,
+) {
+  private var dump: ByteArrayOutputStream? = if (dumpWav) ByteArrayOutputStream() else null
+  private var dumpRate = 0
+  private var dumpChannels = 0
+  private var dumped = false
+  private val outgoing = ByteArrayOutputStream()
+  private val resampler = PcmResampler(TARGET_RATE)
+  private var lastRmsLogMs = 0L
+
+  fun ingest(pcm16Le: ByteArray, sampleRate: Int, channels: Int): List<ByteArray> {
+    if (dump != null && !dumped) {
+      dump!!.write(pcm16Le)
+      dumpRate = sampleRate
+      dumpChannels = channels
+      val needed = 30 * sampleRate * channels * 2
+      if (dump!!.size() >= needed) finishDump()
+    }
+    logLevel(pcm16Le, sampleRate, channels)
+    // Stateful: filter history and fractional phase carry across WebRTC's
+    // 10 ms callbacks, so there is no seam every 480 samples.
+    val mono = resampler.process(pcm16Le, sampleRate, channels)
+    outgoing.write(mono)
+    val frameBytes = TARGET_RATE * 2 / 50 // 20 ms
+    val frames = mutableListOf<ByteArray>()
+    val buf = outgoing.toByteArray()
+    var offset = 0
+    while (buf.size - offset >= frameBytes) {
+      frames.add(buf.copyOfRange(offset, offset + frameBytes))
+      offset += frameBytes
+    }
+    outgoing.reset()
+    if (offset < buf.size) outgoing.write(buf, offset, buf.size - offset)
+    return frames
+  }
+
+  @Synchronized
+  fun finishDump() {
+    if (dumped) return
+    val data = dump?.toByteArray() ?: return
+    dumped = true
+    dump = null
+    val dir = dumpDir ?: return
+    val file = File(dir, "acs-whep-p4.wav")
+    file.writeBytes(wav(data, dumpRate, dumpChannels))
+    Log.i(TAG, "P4 wrote ${file.absolutePath} bytes=${data.size} rate=$dumpRate ch=$dumpChannels")
+  }
+
+  private fun logLevel(pcm: ByteArray, sampleRate: Int, channels: Int) {
+    val now = System.currentTimeMillis()
+    if (now - lastRmsLogMs < 1000) return
+    lastRmsLogMs = now
+    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
+    }
+    val mean = if (n == 0) 0 else acc / n
+    Log.i(TAG, "P4 pcm rate=$sampleRate ch=$channels meanAbs=$mean bytes=${pcm.size}")
+  }
+
+  companion object {
+    private const val TAG = "ACS-SPIKE"
+    const val TARGET_RATE = 48_000
+
+    /** One-shot convenience (fresh filter state). Streams must use a [PcmResampler] instance. */
+    fun toMono(pcm16Le: ByteArray, sampleRate: Int, channels: Int): ByteArray =
+      PcmResampler(TARGET_RATE).process(pcm16Le, sampleRate, channels)
+
+    fun wav(pcm: ByteArray, sampleRate: Int, channels: Int): ByteArray {
+      val header = ByteBuffer.allocate(44).order(ByteOrder.LITTLE_ENDIAN)
+      header.put("RIFF".toByteArray())
+      header.putInt(36 + pcm.size)
+      header.put("WAVE".toByteArray())
+      header.put("fmt ".toByteArray())
+      header.putInt(16)
+      header.putShort(1)
+      header.putShort(channels.toShort())
+      header.putInt(sampleRate)
+      header.putInt(sampleRate * channels * 2)
+      header.putShort((channels * 2).toShort())
+      header.putShort(16)
+      header.put("data".toByteArray())
+      header.putInt(pcm.size)
+      return header.array() + pcm
+    }
+
+    fun encodeBase64(pcm: ByteArray): String = Base64.encodeToString(pcm, Base64.NO_WRAP)
+  }
+}