@mentra/acs-meeting 3.2.0-dev.120

package/android/src/main/java/com/mentra/acsmeeting/video/AcsFrameSender.kt

@@ -0,0 +1,475 @@
+package com.mentra.acsmeeting.video
+
+import android.util.Log
+import com.azure.android.communication.calling.RawOutgoingVideoStream
+import com.azure.android.communication.calling.RawVideoFrameBuffer
+import com.azure.android.communication.calling.VideoStreamFormat
+import com.azure.android.communication.calling.VideoStreamFormatChangedListener
+import com.azure.android.communication.calling.VideoStreamPixelFormat
+import com.azure.android.communication.calling.VideoStreamResolution
+import com.azure.android.communication.calling.VideoStreamState
+import com.azure.android.communication.calling.VideoStreamStateChangedListener
+import com.azure.android.communication.calling.VirtualOutgoingVideoStream
+import com.mentra.acsmeeting.source.AcsInvestigation
+import com.mentra.acsmeeting.source.I420Planes
+import com.mentra.acsmeeting.source.PixelFormatArm
+import com.mentra.acsmeeting.source.TargetSize
+import com.mentra.acsmeeting.telemetry.ChromaProbe
+import com.mentra.acsmeeting.telemetry.PipelineStats
+import java.nio.ByteBuffer
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.ConcurrentLinkedQueue
+import java.util.concurrent.Executors
+import java.util.concurrent.RejectedExecutionException
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.TimeoutException
+import java.util.concurrent.atomic.AtomicBoolean
+import java.util.concurrent.atomic.AtomicInteger
+import java.util.concurrent.atomic.AtomicReference
+
+/**
+ * I420 to ACS: three independent direct planes (Y, U, V). No inter-arrival
+ * pacer — [SendGate] is the only backpressure. Size mismatch drops; the sink
+ * owns scaling to the negotiated size.
+ */
+class AcsFrameSender(
+  private val stats: PipelineStats = PipelineStats(),
+) {
+  private val running = AtomicBoolean(false)
+  private val stream = AtomicReference<RawOutgoingVideoStream?>(null)
+  private val format = AtomicReference<VideoStreamFormat?>(null)
+  private val sender = Executors.newSingleThreadExecutor { runnable ->
+    Thread(runnable, "acs-i420-send").apply { isDaemon = true }
+  }
+  private val gate = SendGate()
+  private val pool = ConcurrentHashMap<Int, ConcurrentLinkedQueue<ByteBuffer>>()
+  private val sendSeq = AtomicInteger(0)
+  private val lastTicks = AtomicReference(0L)
+  private val held = AtomicInteger(0)
+  private val cleanup = Executors.newSingleThreadScheduledExecutor { runnable ->
+    Thread(runnable, "acs-zc-release").apply { isDaemon = true }
+  }
+  // Set on the session thread, read from ACS state/format listener threads.
+  @Volatile private var onFormat: ((TargetSize) -> Unit)? = null
+  private var attachedStream: VirtualOutgoingVideoStream? = null
+  private var stateListener: VideoStreamStateChangedListener? = null
+  private var formatListener: VideoStreamFormatChangedListener? = null
+
+  fun attach(outgoing: VirtualOutgoingVideoStream, onFormat: ((TargetSize) -> Unit)? = null) {
+    detach()
+    this.onFormat = onFormat
+    stream.set(outgoing)
+    attachedStream = outgoing
+    val onState = VideoStreamStateChangedListener {
+      // Ignore late events from a previous call's stream so a stale STOPPED
+      // cannot freeze outgoing video for the current meeting.
+      if (stream.get() !== outgoing) return@VideoStreamStateChangedListener
+      val state = outgoing.state
+      Log.i(TAG, "raw video state=$state")
+      running.set(state == VideoStreamState.STARTED)
+      if (state == VideoStreamState.STARTED) {
+        format.set(outgoing.format)
+        logFormat(outgoing.format)
+        pushTarget(outgoing.format)
+      }
+    }
+    val onFormatChanged = VideoStreamFormatChangedListener { args ->
+      if (stream.get() !== outgoing) return@VideoStreamFormatChangedListener
+      format.set(args.format)
+      logFormat(args.format)
+      pushTarget(args.format)
+    }
+    stateListener = onState
+    formatListener = onFormatChanged
+    outgoing.addOnStateChangedListener(onState)
+    outgoing.addOnFormatChangedListener(onFormatChanged)
+  }
+
+  fun isReady(): Boolean = stream.get() != null && running.get() && format.get() != null
+
+  fun sendPlanes(planes: I420Planes) {
+    val out = stream.get()
+    if (out == null || !running.get()) {
+      stats.onDropNotStarted()
+      return
+    }
+    val negotiated = format.get()
+    if (negotiated == null) {
+      stats.onDropNotStarted()
+      return
+    }
+    if (negotiated.width != planes.width || negotiated.height != planes.height) {
+      stats.onDropSize()
+      return
+    }
+    if (!planes.planesReadable()) {
+      stats.onDropMalformed()
+      Log.w(
+        TAG,
+        "P5 send plane too small ${planes.width}x${planes.height} " +
+          "stride=${planes.strideY}/${planes.strideU}/${planes.strideV}",
+      )
+      return
+    }
+
+    val prepared = prepareSend(planes, negotiated)
+    stats.setChroma(prepared.chroma)
+
+    if (!gate.tryAcquire()) {
+      stats.onDropBusy()
+      releaseSendBuffers(prepared, planes)
+      return
+    }
+
+    val seq = sendSeq.incrementAndGet()
+    stats.onQueued()
+    if (seq <= TRACE_SENDS) {
+      Log.i(
+        TAG,
+        "P5 send-enter seq=$seq mode=${prepared.mode} buffers=${prepared.buffers.size} " +
+          "sizes=${prepared.buffers.joinToString("/") { it.remaining().toString() }} " +
+          "direct=${prepared.buffers.all { it.isDirect }} tight=${planes.isTight()} " +
+          "sinkThread=${Thread.currentThread().name}",
+      )
+    }
+
+    val submitted = try {
+      sender.execute {
+        var result = "ok"
+        // A timed-out future is NOT cancelled: ACS still reads these direct buffers.
+        var reclaimable = true
+        var frame: RawVideoFrameBuffer? = null
+        try {
+          val streamTicks = try {
+            out.timestampInTicks
+          } catch (_: Exception) {
+            0L
+          }
+          val ticks = AcsTimestamp.resolve(
+            streamTicks = streamTicks,
+            captureNs = if (planes.timestampNs > 0) planes.timestampNs else System.nanoTime(),
+            lastTicks = lastTicks.get(),
+          )
+          lastTicks.set(ticks)
+          frame = RawVideoFrameBuffer()
+          frame.buffers = prepared.buffers
+          frame.streamFormat = negotiated
+          frame.timestampInTicks = ticks
+          val sendStart = System.nanoTime()
+          out.sendRawVideoFrame(frame).get(SEND_TIMEOUT_MS, TimeUnit.MILLISECONDS)
+          stats.send.record(System.nanoTime() - sendStart)
+          stats.onSub()
+          if (seq <= TRACE_SENDS) {
+            Log.i(
+              TAG,
+              "P5 send-exit seq=$seq result=ok ticks=$ticks streamTicks=$streamTicks " +
+                "thread=${Thread.currentThread().name}",
+            )
+          }
+        } catch (error: TimeoutException) {
+          result = "timeout"
+          reclaimable = false
+          stats.onDropFail()
+          stats.onAbandoned()
+          if (prepared.zeroCopy) {
+            stats.onZcTimeout()
+            scheduleZeroCopyRelease(planes)
+          }
+          Log.w(TAG, "P5 send-exit seq=$seq result=timeout getMs>$SEND_TIMEOUT_MS buffers=abandoned")
+        } catch (error: Exception) {
+          result = "failed"
+          stats.onDropFail()
+          Log.w(TAG, "P5 send-exit seq=$seq result=failed ${describeAcs(error)}")
+        } finally {
+          if (reclaimable) {
+            try {
+              frame?.close()
+            } catch (_: Exception) {
+            }
+            releaseSendBuffers(prepared, planes)
+          }
+          gate.release()
+          if (seq == 1 && result != "ok") {
+            Log.w(TAG, "P5 send first frame did not complete result=$result mode=${prepared.mode}")
+          }
+        }
+      }
+      true
+    } catch (error: RejectedExecutionException) {
+      false
+    }
+    if (!submitted) {
+      stats.onDropFail()
+      gate.release()
+      releaseSendBuffers(prepared, planes)
+    }
+  }
+
+  private data class PreparedSend(
+    val buffers: List<ByteBuffer>,
+    val zeroCopy: Boolean,
+    val mode: String,
+    val chroma: ChromaProbe.Sample,
+  )
+
+  private fun prepareSend(planes: I420Planes, negotiated: VideoStreamFormat): PreparedSend {
+    if (negotiatedPixelIsNv12(negotiated)) {
+      return prepareNv12(planes)
+    }
+    val ySize = planes.width * planes.height
+    val uvSize = I420Packer.chromaStride(planes.width) * I420Packer.chromaStride(planes.height)
+    val zeroCopy = tryZeroCopy(planes)
+    val y: ByteBuffer
+    val u: ByteBuffer
+    val v: ByteBuffer
+    if (zeroCopy) {
+      planes.retain!!()
+      val nowHeld = held.incrementAndGet()
+      stats.onZcUsed(nowHeld)
+      y = planes.y.duplicate()
+      u = planes.u.duplicate()
+      v = planes.v.duplicate()
+    } else {
+      y = borrow(ySize)
+      u = borrow(uvSize)
+      v = borrow(uvSize)
+      val chromaW = I420Packer.chromaStride(planes.width)
+      val chromaH = I420Packer.chromaStride(planes.height)
+      val copyStart = System.nanoTime()
+      I420Packer.copyPlane(planes.y, planes.strideY, planes.width, planes.height, y)
+      I420Packer.copyPlane(planes.u, planes.strideU, chromaW, chromaH, u)
+      I420Packer.copyPlane(planes.v, planes.strideV, chromaW, chromaH, v)
+      y.flip()
+      u.flip()
+      v.flip()
+      stats.copy.record(System.nanoTime() - copyStart)
+    }
+    return PreparedSend(
+      buffers = listOf(y, u, v),
+      zeroCopy = zeroCopy,
+      mode = if (zeroCopy) "zerocopy" else "planes",
+      chroma = ChromaProbe.samplePlanes(y, u, v),
+    )
+  }
+
+  private fun prepareNv12(planes: I420Planes): PreparedSend {
+    val ySize = planes.width * planes.height
+    val uvSize = Nv12Packer.uvSize(planes.width, planes.height)
+    val y = borrow(ySize)
+    val uv = borrow(uvSize)
+    val chromaW = I420Packer.chromaStride(planes.width)
+    val chromaH = Nv12Packer.chromaHeight(planes.height)
+    val copyStart = System.nanoTime()
+    Nv12Packer.copyY(planes.y, planes.strideY, planes.width, planes.height, y)
+    Nv12Packer.interleaveUv(
+      planes.u, planes.strideU, planes.v, planes.strideV, chromaW, chromaH, uv,
+    )
+    y.flip()
+    uv.flip()
+    stats.copy.record(System.nanoTime() - copyStart)
+    return PreparedSend(
+      buffers = listOf(y, uv),
+      zeroCopy = false,
+      mode = "nv12",
+      chroma = ChromaProbe.sampleNv12(y, uv),
+    )
+  }
+
+  private fun negotiatedPixelIsNv12(negotiated: VideoStreamFormat): Boolean {
+    return try {
+      negotiated.pixelFormat == VideoStreamPixelFormat.NV12
+    } catch (_: Exception) {
+      AcsInvestigation.pixelFormat == PixelFormatArm.NV12
+    }
+  }
+
+  private fun tryZeroCopy(planes: I420Planes): Boolean {
+    if (!AcsInvestigation.zeroCopy) return false
+    if (planes.retain == null || planes.release == null) {
+      stats.onZcFell()
+      return false
+    }
+    if (!planes.isDirect()) {
+      stats.onZcFell()
+      return false
+    }
+    if (!planes.isTight()) {
+      stats.onZcPadded()
+      stats.onZcFell()
+      return false
+    }
+    if (held.get() >= MAX_HELD) {
+      stats.onZcFell()
+      return false
+    }
+    return true
+  }
+
+  private fun releaseSendBuffers(prepared: PreparedSend, planes: I420Planes) {
+    if (prepared.zeroCopy) {
+      try {
+        planes.release?.invoke()
+      } catch (_: Exception) {
+      }
+      held.decrementAndGet()
+    } else {
+      for (buffer in prepared.buffers) recycle(buffer)
+    }
+  }
+
+  private fun scheduleZeroCopyRelease(planes: I420Planes) {
+    cleanup.schedule({
+      try {
+        planes.release?.invoke()
+      } catch (_: Exception) {
+      } finally {
+        held.decrementAndGet()
+      }
+    }, ZC_GRACE_MS, TimeUnit.MILLISECONDS)
+  }
+
+  fun detach() {
+    running.set(false)
+    val previous = attachedStream
+    if (previous != null) {
+      stateListener?.let { previous.removeOnStateChangedListener(it) }
+      formatListener?.let { previous.removeOnFormatChangedListener(it) }
+    }
+    attachedStream = null
+    stateListener = null
+    formatListener = null
+    stream.set(null)
+    format.set(null)
+    sendSeq.set(0)
+    lastTicks.set(0L)
+    pool.clear()
+    onFormat = null
+  }
+
+  private fun pushTarget(fmt: VideoStreamFormat?) {
+    if (fmt == null || fmt.width <= 0 || fmt.height <= 0) return
+    onFormat?.invoke(TargetSize(fmt.width, fmt.height))
+  }
+
+  // Keyed by exact capacity: luma and chroma differ 4x, and a single queue made
+  // a luma borrow evict a chroma buffer it could not use.
+  private fun borrow(capacity: Int): ByteBuffer {
+    val existing = pool[capacity]?.poll()
+    if (existing != null) {
+      existing.clear()
+      return existing
+    }
+    stats.onPlaneAlloc()
+    return ByteBuffer.allocateDirect(capacity)
+  }
+
+  private fun recycle(buffer: ByteBuffer) {
+    val queue = pool.getOrPut(buffer.capacity()) { ConcurrentLinkedQueue() }
+    if (queue.size >= POOL_PER_SIZE) return
+    buffer.clear()
+    queue.offer(buffer)
+  }
+
+  private fun logFormat(fmt: VideoStreamFormat?) {
+    if (fmt == null) return
+    Log.i(
+      TAG,
+      "P5 negotiated format pixel=${fmt.pixelFormat} ${fmt.width}x${fmt.height} fps=${fmt.framesPerSecond} " +
+        "stride=${fmt.stride1}/${fmt.stride2}/${fmt.stride3}",
+    )
+  }
+
+  companion object {
+    private const val TAG = "ACS-SPIKE"
+    private const val SEND_TIMEOUT_MS = 200L
+    private const val TRACE_SENDS = 8
+    private const val POOL_PER_SIZE = 4
+    private const val MAX_HELD = 2
+    private const val ZC_GRACE_MS = 1_000L
+
+    fun outgoingFormat(profile: VideoProfile = VideoProfile.DEFAULT): VideoStreamFormat =
+      when (AcsInvestigation.pixelFormat) {
+        PixelFormatArm.NV12 -> nv12Format(profile)
+        PixelFormatArm.I420 -> i420Format(profile)
+      }
+
+    fun i420Format(profile: VideoProfile = VideoProfile.DEFAULT): VideoStreamFormat =
+      i420Format(profile.width, profile.height, profile.fps.toFloat())
+
+    fun nv12Format(profile: VideoProfile = VideoProfile.DEFAULT): VideoStreamFormat =
+      nv12Format(profile.width, profile.height, profile.fps.toFloat())
+
+    fun i420Format(width: Int, height: Int, fps: Float): VideoStreamFormat {
+      val spec = I420FormatSpec.of(width, height, fps)
+      val format = VideoStreamFormat()
+      format.pixelFormat = VideoStreamPixelFormat.I420
+      applyNamedSize(format, spec.width, spec.height)
+      format.framesPerSecond = spec.fps
+      format.stride1 = spec.strideY
+      format.stride2 = spec.strideU
+      format.stride3 = spec.strideV
+      return format
+    }
+
+    fun nv12Format(width: Int, height: Int, fps: Float): VideoStreamFormat {
+      val spec = Nv12FormatSpec.of(width, height, fps)
+      val format = VideoStreamFormat()
+      format.pixelFormat = VideoStreamPixelFormat.NV12
+      applyNamedSize(format, spec.width, spec.height)
+      format.framesPerSecond = spec.fps
+      format.stride1 = spec.strideY
+      format.stride2 = spec.strideUv
+      return format
+    }
+
+    private fun applyNamedSize(format: VideoStreamFormat, width: Int, height: Int) {
+      when (I420FormatSpec.of(width, height).namedResolution()) {
+        AcsNamedResolution.P1080 -> format.resolution = VideoStreamResolution.P1080
+        AcsNamedResolution.P720 -> format.resolution = VideoStreamResolution.P720
+        AcsNamedResolution.P540 -> format.resolution = VideoStreamResolution.P540
+        AcsNamedResolution.P480 -> format.resolution = VideoStreamResolution.P480
+        AcsNamedResolution.P360 -> format.resolution = VideoStreamResolution.P360
+        AcsNamedResolution.P270 -> format.resolution = VideoStreamResolution.P270
+        AcsNamedResolution.P240 -> format.resolution = VideoStreamResolution.P240
+        AcsNamedResolution.P180 -> format.resolution = VideoStreamResolution.P180
+        AcsNamedResolution.VGA -> format.resolution = VideoStreamResolution.VGA
+        AcsNamedResolution.QVGA -> format.resolution = VideoStreamResolution.QVGA
+        null -> {
+          Log.w(TAG, "ACS format ${width}x${height} is not a VideoStreamResolution; advertising raw size")
+          format.width = width
+          format.height = height
+        }
+      }
+    }
+
+    fun describeAcs(error: Throwable): String {
+      val parts = ArrayList<String>(4)
+      var current: Throwable? = error
+      var depth = 0
+      while (current != null && depth < 5) {
+        val code = errorCodeOf(current)
+        val message = current.message?.trim().orEmpty()
+        parts.add(
+          buildString {
+            append(current!!.javaClass.simpleName)
+            if (message.isNotEmpty()) append(':').append(message)
+            if (code != null) append(" code=").append(code)
+          },
+        )
+        current = current.cause
+        depth += 1
+      }
+      return parts.joinToString(" | ")
+    }
+
+    private fun errorCodeOf(error: Throwable): String? {
+      return try {
+        val method = error.javaClass.methods.firstOrNull { it.name == "getErrorCode" && it.parameterCount == 0 }
+          ?: return null
+        method.invoke(error)?.toString()
+      } catch (_: Exception) {
+        null
+      }
+    }
+  }
+}

package/android/src/main/java/com/mentra/acsmeeting/video/AcsTimestamp.kt

@@ -0,0 +1,26 @@
+package com.mentra.acsmeeting.video
+
+/**
+ * ACS [RawVideoFrame.setTimestampInTicks] uses Windows / .NET ticks:
+ * 100-nanosecond units. A frame with timestamp 0 is "no time", and a run of
+ * those makes the Teams jitter buffer hold the last picture until it decides
+ * the stream has moved — which looks like a random freeze.
+ *
+ * Prefer the stream clock when ACS is advancing it (Microsoft's sample does
+ * exactly that). Otherwise convert a capture timestamp. Always emit a tick
+ * strictly after [lastTicks] so two frames never share a presentation time.
+ */
+object AcsTimestamp {
+  const val NS_PER_TICK = 100L
+
+  fun resolve(streamTicks: Long, captureNs: Long, lastTicks: Long): Long {
+    val fromStream = streamTicks > 0
+    val fromCapture = captureNs > 0
+    val candidate = when {
+      fromStream && streamTicks > lastTicks -> streamTicks
+      fromCapture -> captureNs / NS_PER_TICK
+      else -> lastTicks + 1
+    }
+    return if (candidate <= lastTicks) lastTicks + 1 else candidate
+  }
+}

package/android/src/main/java/com/mentra/acsmeeting/video/FrameGeometry.kt

@@ -0,0 +1,22 @@
+package com.mentra.acsmeeting.video
+
+/**
+ * Pack I420 in the buffer's coordinate system, never [VideoFrame.rotatedWidth].
+ * cropAndScale and toI420 planes are un-rotated; mixing them with display size
+ * overruns the plane at rotation 90/270.
+ */
+object FrameGeometry {
+  data class PackSize(
+    val width: Int,
+    val height: Int,
+    val rotationNonZero: Boolean,
+  )
+
+  fun packSize(bufferWidth: Int, bufferHeight: Int, rotationDegrees: Int): PackSize {
+    return PackSize(
+      width = bufferWidth,
+      height = bufferHeight,
+      rotationNonZero = rotationDegrees % 360 != 0,
+    )
+  }
+}

package/android/src/main/java/com/mentra/acsmeeting/video/I420FormatSpec.kt

@@ -0,0 +1,90 @@
+package com.mentra.acsmeeting.video
+
+/**
+ * ACS Android [com.azure.android.communication.calling.VideoStreamResolution]
+ * names. The virtual outgoing stream wants these exact sizes. Near-matches
+ * fail even when WHEP preview works: P480 is 858×480, not 854×480. Portrait
+ * 540×960 is not a named size; ACS P540 is 960×540.
+ */
+enum class AcsNamedResolution {
+  P1080,
+  P720,
+  P540,
+  P480,
+  P360,
+  P270,
+  P240,
+  P180,
+  VGA,
+  QVGA,
+}
+
+/**
+ * The I420 format we advertise to ACS, as plain values.
+ *
+ * Split out from [AcsFrameSender.i420Format] because VideoStreamFormat is a
+ * native-backed ACS class that cannot initialize under a JVM unit test. The
+ * arithmetic is the part worth asserting; applying it to the SDK object is not.
+ *
+ * Strides must agree with [I420Packer], or ACS reads the chroma planes at the
+ * wrong offsets and the picture greens out.
+ */
+data class I420FormatSpec(
+  val width: Int,
+  val height: Int,
+  val fps: Float,
+  val strideY: Int,
+  val strideU: Int,
+  val strideV: Int,
+) {
+  companion object {
+    const val MIN_WIDTH = 240
+    const val MAX_WIDTH = 1920
+    const val MIN_HEIGHT = 180
+    const val MAX_HEIGHT = 1080
+    const val MIN_FPS = 1f
+    const val MAX_FPS = 30f
+
+    /** VirtualOutgoingVideoStream join allowlist. P540 is 960×540, never 540×960. */
+    private val ALLOWED_SIZES = setOf(1280 to 720, 960 to 540)
+
+    fun of(width: Int = 1280, height: Int = 720, fps: Float = 20f): I420FormatSpec {
+      val chroma = I420Packer.chromaStride(width)
+      return I420FormatSpec(
+        width = width,
+        height = height,
+        fps = fps,
+        strideY = width,
+        strideU = chroma,
+        strideV = chroma,
+      )
+    }
+
+    fun parseOrNull(width: Int, height: Int, fps: Float): I420FormatSpec? {
+      if (width to height !in ALLOWED_SIZES) return null
+      val spec = of(width, height, fps)
+      return if (spec.withinAcsBounds()) spec else null
+    }
+  }
+
+  fun withinAcsBounds(): Boolean =
+    width in MIN_WIDTH..MAX_WIDTH && height in MIN_HEIGHT..MAX_HEIGHT && fps in MIN_FPS..MAX_FPS
+
+  /** Named ACS resolution for this geometry, or null if we must advertise raw size. */
+  fun namedResolution(): AcsNamedResolution? = when (width to height) {
+    1920 to 1080 -> AcsNamedResolution.P1080
+    1280 to 720 -> AcsNamedResolution.P720
+    960 to 540 -> AcsNamedResolution.P540
+    858 to 480 -> AcsNamedResolution.P480
+    640 to 360 -> AcsNamedResolution.P360
+    480 to 270 -> AcsNamedResolution.P270
+    352 to 240 -> AcsNamedResolution.P240
+    320 to 180 -> AcsNamedResolution.P180
+    640 to 480 -> AcsNamedResolution.VGA
+    320 to 240 -> AcsNamedResolution.QVGA
+    else -> null
+  }
+
+  /** Bytes ACS will read given these strides; must equal what [I420Packer] writes. */
+  fun packedSize(): Int = strideY * height + 2 * (strideU * I420Packer.chromaStride(height))
+}

package/android/src/main/java/com/mentra/acsmeeting/video/I420Packer.kt

@@ -0,0 +1,72 @@
+package com.mentra.acsmeeting.video
+
+import java.nio.ByteBuffer
+import kotlin.math.roundToInt
+
+/** Tight I420 pack + stride math. No Android / ACS / WebRTC types so JVM tests stay cheap. */
+object I420Packer {
+  fun packedSize(width: Int, height: Int): Int {
+    val chromaW = (width + 1) / 2
+    val chromaH = (height + 1) / 2
+    return width * height + 2 * chromaW * chromaH
+  }
+
+  fun chromaStride(width: Int): Int = (width + 1) / 2
+
+  /**
+   * Bytes a reader must be able to see for a plane with [stride], starting at
+   * the buffer's current position. Last row is only [width] bytes, not a full
+   * stride, so this is `stride*(height-1)+width`.
+   */
+  fun planeMinBytes(stride: Int, width: Int, height: Int): Int {
+    if (width <= 0 || height <= 0 || stride < width) return 0
+    return stride * (height - 1) + width
+  }
+
+  /**
+   * Packs padded WebRTC planes into tight I420 (strideY=width, strideU=strideV=(width+1)/2).
+   */
+  fun pack(
+    dataY: ByteBuffer,
+    strideY: Int,
+    dataU: ByteBuffer,
+    strideU: Int,
+    dataV: ByteBuffer,
+    strideV: Int,
+    width: Int,
+    height: Int,
+    dest: ByteBuffer,
+  ) {
+    dest.clear()
+    val chromaW = chromaStride(width)
+    val chromaH = chromaStride(height)
+    copyPlane(dataY, strideY, width, height, dest)
+    copyPlane(dataU, strideU, chromaW, chromaH, dest)
+    copyPlane(dataV, strideV, chromaW, chromaH, dest)
+    dest.flip()
+  }
+
+  fun copyPlane(src: ByteBuffer, stride: Int, width: Int, height: Int, dest: ByteBuffer) {
+    val plane = src.duplicate()
+    val origin = plane.position()
+    if (stride == width && plane.remaining() >= width * height) {
+      plane.limit(origin + width * height)
+      dest.put(plane)
+      return
+    }
+    for (row in 0 until height) {
+      val start = origin + row * stride
+      plane.limit(start + width)
+      plane.position(start)
+      dest.put(plane)
+    }
+  }
+
+  fun percentileMs(samplesNs: LongArray, quantile: Double): String {
+    if (samplesNs.isEmpty()) return "na"
+    val sorted = samplesNs.copyOf()
+    sorted.sort()
+    val index = ((sorted.size - 1) * quantile).roundToInt().coerceIn(0, sorted.lastIndex)
+    return ((sorted[index] / 1_000_000.0) * 10).roundToInt().div(10.0).toString()
+  }
+}