@mentra/acs-meeting 3.3.0-dev.487 → 3.3.0-dev.489

package/README.md

@@ -34,8 +34,10 @@ differences are collected in [iOS](#ios).
 ## Mental model
 
 **The phone is a relay, not a capture device.** It receives what the glasses already
-encoded, decodes it, and re-publishes it into ACS. Production never generates pixels on
-the phone, and no video frame ever crosses the JavaScript bridge.
+encoded, decodes it, and re-publishes it into ACS. Live video is not drawn on the phone,
+and a live frame does not cross the JavaScript bridge. A photo shutter is the exception:
+the phone draws a "Taking a photo" card, then a still, and feeds those pixels through the
+same sender. See [Photo hold](#photo-hold).
 
 ```
 glasses ──H.264 over WHIP──▶ [SoftAP listener | Cloudflare] ──▶ phone decode ──▶ ACS ──▶ Teams
@@ -533,6 +535,32 @@ The actual submit runs on the `acs-i420-send` thread with a 200 ms timeout. Two
   prefers the stream clock when ACS is advancing it, falls back to capture time, and always
   emits a tick strictly after the last one.
 
+### Photo hold
+
+A high-resolution photo cannot ride the live camera. The host pauses only the glasses
+publisher (`start_stream` on Direct link; Call's own stream on Cloudflare), keeps the
+meeting, the hotspot, and the ACS sender up, and replaces the tile with three pictures
+in order:
+
+1. A full-frame card, "Taking a photo", from the button press until the still is ready.
+2. The still, for a few seconds counted by the caller from `shownAt`.
+3. Live video again.
+
+The card and the still are generated on the phone (`OutgoingVideoHold` on Android,
+`outgoingHoldPixelBuffer` on iOS) and pumped about every 100 ms through the existing
+frame sender. Each frame carries a fresh timestamp. A gap, or a timestamp of zero, makes
+Teams hold a random freeze. The last live frame is not repeated.
+
+While the hold is active, glasses frames are dropped (`forwardGlassesPlanes` /
+`holdingOutgoing`). `holdOutgoingVideo` resolves only after one replacement frame has
+been handed to the sender. Leave, End, and a new join stop the hold and cancel the
+pause without starting the publisher again. A pause the caller never resumes expires
+after 30 seconds, the publisher starts, and the host emits `miniapp_meeting_video_publisher`
+with `status: "expired"`. A resume that names a stale pause id does nothing.
+
+Direct link must not use the ordinary camera-loss recovery for this pause. That path
+rebuilds the hotspot. `PhotoPauseController` suppresses it until the pause ends.
+
 ## Audio uplink path
 
 ### Choosing the microphone

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

@@ -7,6 +7,7 @@ import com.mentra.glassesmedia.network.InternetHold
 import com.mentra.glassesmedia.network.ScopedNetworkChangeDetector
 import com.mentra.glassesmedia.network.ScopedNetworkError
 import com.mentra.glassesmedia.network.ScopedSoftApNetwork
+import com.mentra.glassesmedia.source.StillPhotoInbox
 import com.mentra.acsmeeting.source.MeetingVideoSourceSpec
 import com.mentra.glassesmedia.trace.SoftApTrace
 import com.mentra.acsmeeting.video.VideoProfile
@@ -17,6 +18,11 @@ import expo.modules.kotlin.Promise
 class AcsMeetingModule : Module() {
   private var session: AcsMeetingSession? = null
 
+  /** Still timeouts and the decode into the outgoing hold, off the ingest connection thread. */
+  private val stillTimer = java.util.concurrent.Executors.newSingleThreadScheduledExecutor { runnable ->
+    Thread(runnable, "acs-glasses-still").apply { isDaemon = true }
+  }
+
   /**
    * Wrap one `AsyncFunction` body in an entry/exit trace.
    *
@@ -429,6 +435,91 @@ class AcsMeetingModule : Module() {
       session?.setMuted(muted) ?: mapOf("state" to "idle", "muted" to muted)
     }
 
+    AsyncFunction("holdOutgoingVideo") { kind: String, imageBase64: String?, promise: Promise ->
+      val meeting = session
+      if (meeting == null) {
+        promise.reject("NO_MEETING", "No active meeting", null)
+      } else {
+        val bytes = imageBase64?.let { android.util.Base64.decode(it, android.util.Base64.DEFAULT) }
+        meeting.setOutgoingHold(kind, bytes) { handed ->
+          if (handed) promise.resolve(null) else promise.reject("HOLD_FAILED", "The outgoing card was not sent", null)
+        }
+      }
+    }
+
+    /**
+     * Register a full-size still the glasses will upload during a Direct-link call, and return the
+     * URL they must POST it to. Must resolve before the glasses are asked to shoot, so the upload
+     * can never arrive for an id the listener does not know.
+     */
+    AsyncFunction("prepareGlassesStill") { requestId: String ->
+      traced("prepare_glasses_still", "requestId" to requestId) {
+        val meeting = session ?: throw IllegalStateException("No active meeting")
+        val uploadUrl = meeting.softApStillUrl(requestId)
+          ?: throw IllegalStateException("This call has no Direct link receiver")
+        StillPhotoInbox.expect(requestId)
+        mapOf("uploadUrl" to uploadUrl)
+      }
+    }
+
+    /**
+     * Wait for the prepared still, then hold it on the outgoing tile. The JPEG stays native: it is
+     * decoded straight into the hold rather than crossing the bridge. Resolves once the first still
+     * frame is handed to the Teams sender.
+     */
+    AsyncFunction("awaitGlassesStill") { requestId: String, timeoutMs: Int, promise: Promise ->
+      val pending = StillPhotoInbox.lookup(requestId)
+      if (pending == null) {
+        promise.reject("STILL_NOT_PREPARED", "No still is pending for $requestId", null)
+        return@AsyncFunction
+      }
+      val timeout = stillTimer.schedule({
+        pending.completeExceptionally(java.util.concurrent.TimeoutException("still_timeout"))
+      }, timeoutMs.toLong().coerceAtLeast(1L), java.util.concurrent.TimeUnit.MILLISECONDS)
+      pending.whenCompleteAsync({ bytes, error ->
+        timeout.cancel(false)
+        StillPhotoInbox.cancel(requestId)
+        val cause = (error as? java.util.concurrent.CompletionException)?.cause ?: error
+        when {
+          cause is java.util.concurrent.CancellationException ->
+            promise.reject("STILL_CANCELLED", "The still was cancelled", null)
+          cause is java.util.concurrent.TimeoutException ->
+            promise.reject("STILL_TIMEOUT", "The glasses did not upload the still in ${timeoutMs}ms", null)
+          cause != null -> promise.reject("STILL_FAILED", cause.message ?: "Still upload failed", cause)
+          else -> {
+            val meeting = session
+            if (meeting == null) {
+              promise.reject("NO_MEETING", "The meeting ended before the still arrived", null)
+            } else {
+              val holdStartedAt = android.os.SystemClock.elapsedRealtime()
+              SoftApTrace.stage("glasses_still_hold", "requestId" to requestId, "bytes" to bytes.size)
+              meeting.setOutgoingHold("image", bytes) { handed ->
+                val holdMs = android.os.SystemClock.elapsedRealtime() - holdStartedAt
+                SoftApTrace.stage(
+                  "glasses_still_handed",
+                  "requestId" to requestId,
+                  "bytes" to bytes.size,
+                  "handed" to handed,
+                  "holdMs" to holdMs,
+                )
+                if (handed) {
+                  meeting.noteStillHeld(bytes.size)
+                  promise.resolve(mapOf("bytes" to bytes.size, "shownAt" to System.currentTimeMillis()))
+                } else {
+                  promise.reject("HOLD_FAILED", "The still was not sent to the meeting", null)
+                }
+              }
+            }
+          }
+        }
+      }, stillTimer)
+    }
+
+    /** Drop one pending still, or every pending still when [requestId] is null. Idempotent. */
+    AsyncFunction("cancelGlassesStill") { requestId: String? ->
+      if (requestId == null) StillPhotoInbox.cancelAll() else StillPhotoInbox.cancel(requestId)
+    }
+
     AsyncFunction("setVideoEnabled") { enabled: Boolean, promise: Promise ->
       val meeting = session
       if (meeting == null) {

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

@@ -79,6 +79,8 @@ import com.mentra.glassesmedia.source.GlassesMediaSourceFactory
 import com.mentra.glassesmedia.source.LocalWhipIngestSource
 import com.mentra.acsmeeting.source.MeetingVideoSourceSpec
 import com.mentra.glassesmedia.source.SourceConfig
+import com.mentra.glassesmedia.source.StillPhotoInbox
+import com.mentra.glassesmedia.source.WhipIngestProtocol
 import com.mentra.glassesmedia.source.SourceKind
 import com.mentra.glassesmedia.source.SourceState
 import com.mentra.glassesmedia.source.SyntheticI420Source
@@ -89,6 +91,8 @@ import com.mentra.glassesmedia.telemetry.PipelineStats
 import com.mentra.glassesmedia.telemetry.PipelineTicker
 import com.mentra.glassesmedia.trace.SoftApTrace
 import com.mentra.acsmeeting.video.AcsFrameSender
+import com.mentra.acsmeeting.video.OutgoingVideoHold
+import com.mentra.glassesmedia.source.I420Planes
 import com.mentra.acsmeeting.video.VideoProfile
 import java.util.concurrent.CountDownLatch
 import java.util.concurrent.Executors
@@ -134,6 +138,13 @@ class AcsMeetingSession(
   private val outgoingReady = AtomicBoolean(false)
   private val muted = AtomicBoolean(false)
   private val frameSender = AcsFrameSender(stats, avSync)
+  private val outgoingHold = OutgoingVideoHold(
+    send = { planes -> frameSender.sendPlanes(planes) },
+    // The negotiated size, not the profile ceiling: ACS renegotiates below the ceiling under load,
+    // and sendPlanes drops any hold frame whose dimensions differ from the negotiated format.
+    width = { frameSender.negotiatedSize()?.width ?: profile.width },
+    height = { frameSender.negotiatedSize()?.height ?: profile.height },
+  )
   private var profile = VideoProfile.DEFAULT
   private val resolvedFactory = mediaSourceFactory ?: GlassesMediaSourceFactory { video, pcm, config ->
     // The synthetic diagnostic arm overrides everything; otherwise the requested kind decides.
@@ -222,6 +233,9 @@ class AcsMeetingSession(
   // Health of the glasses WHEP feed, reported alongside the ACS phase so the host
   // can tell "call is up, glasses video is dead" from a healthy call.
   @Volatile private var mediaSource = SourceState.IDLE
+  /** Elapsed realtime when the last full-size still was handed to the Teams sender. 0 if none. */
+  @Volatile private var lastStillHeldAtMs = 0L
+  @Volatile private var lastStillBytes = 0
   // The transport of the active call. A SoftAP source must not be auto-rebuilt: its URL is an
   // output of binding, so a rebuild rebinds a new port and strands the glasses on the old one.
   @Volatile private var currentSourceKind = SourceKind.WHEP
@@ -644,12 +658,7 @@ class AcsMeetingSession(
           // The pin is back on by the time the Teams join below runs.
           bindIngestUnpinned {
             media.attach(
-              video = { planes ->
-                // Preview first, deliberately: the tap must see frames ACS's pacing and
-                // readiness gates would otherwise hide, and it cannot delay or break this call.
-                DecodedFrameTap.offer(planes)
-                if (frameSender.sendPlanes(planes)) DecodedFrameTap.recordAcsSend()
-              },
+              video = { planes -> forwardGlassesPlanes(planes) },
               pcm = { pcm, rate, channels -> feedOutgoingPcm(pcm, rate, channels) },
               config = videoSource.toConfig(),
             )
@@ -674,10 +683,7 @@ class AcsMeetingSession(
 
         if (videoSource !is MeetingVideoSourceSpec.SoftAp) {
           media.attach(
-            video = { planes ->
-              DecodedFrameTap.offer(planes)
-              if (frameSender.sendPlanes(planes)) DecodedFrameTap.recordAcsSend()
-            },
+            video = { planes -> forwardGlassesPlanes(planes) },
             pcm = { pcm, rate, channels -> feedOutgoingPcm(pcm, rate, channels) },
             config = if (synthetic) SourceConfig("", SourceKind.DIRECT) else videoSource.toConfig(),
           )
@@ -773,6 +779,17 @@ class AcsMeetingSession(
    */
   fun softApIngestUrl(): String? = media.ingestUrl
 
+  /**
+   * Where the glasses upload a full-size still for [requestId] during this SoftAP call: the same
+   * listener, host and port as the WHIP endpoint. Null for other transports or before the bind.
+   */
+  fun softApStillUrl(requestId: String): String? {
+    if (!WhipIngestProtocol.isValidStillRequestId(requestId)) return null
+    val ingest = media.ingestUrl ?: return null
+    if (!ingest.endsWith(WhipIngestProtocol.BASE_PATH)) return null
+    return ingest.removeSuffix(WhipIngestProtocol.BASE_PATH) + WhipIngestProtocol.STILL_PATH + "/" + requestId
+  }
+
   /**
    * Destroy the current SoftAP listener generation and bind a new one on the address the
    * scoped network reports *now* — the caller rejoins first, then asks for this.
@@ -893,6 +910,34 @@ class AcsMeetingSession(
     mediaRestartAttempts = 0
   }
 
+  /** Remember a still that reached the Teams sender, so a later disconnect can be correlated with it. */
+  fun noteStillHeld(bytes: Int) {
+    lastStillHeldAtMs = SystemClock.elapsedRealtime()
+    lastStillBytes = bytes
+  }
+
+  /**
+   * Ignore glasses frames and send a card or still instead. Reports through [onResult] once one
+   * replacement frame has been handed to the sender, so the caller can stop the camera after that.
+   *
+   * Asynchronous: the hold does its own off-thread wait for the first frame rather than blocking
+   * the caller, so the RN module thread never stalls (and risks an ANR) inside this call.
+   */
+  fun setOutgoingHold(kind: String, imageBytes: ByteArray?, onResult: (Boolean) -> Unit) {
+    if (kind == "live") {
+      outgoingHold.stop()
+      onResult(true)
+      return
+    }
+    outgoingHold.start(kind, imageBytes, onResult)
+  }
+
+  private fun forwardGlassesPlanes(planes: I420Planes) {
+    if (outgoingHold.isActive()) return
+    DecodedFrameTap.offer(planes)
+    if (frameSender.sendPlanes(planes)) DecodedFrameTap.recordAcsSend()
+  }
+
   fun setMuted(next: Boolean): Map<String, Any> {
     if (MediaDiagnostics.videoArm == VideoSourceArm.SYNTHETIC) {
       muted.set(true)
@@ -958,6 +1003,8 @@ class AcsMeetingSession(
   }
 
   fun leave() {
+    outgoingHold.stop()
+    StillPhotoInbox.cancelAll()
     val submittedAt = SystemClock.elapsedRealtime()
     // Invalidate before queueing: leaveLocked cannot run until the executor finishes the current
     // join/hang-up, and without this bump a Cancel sits behind an unbounded ACS Future.
@@ -1235,10 +1282,36 @@ class AcsMeetingSession(
     val end = describeEndReason(call)
     // A failed connection is recoverable; do not tell the wearer the remote meeting ended.
     // Wait for DISCONNECTED because DISCONNECTING may not yet carry the final reason.
-    if (state == CallState.DISCONNECTED && (end["code"] as? Number)?.toInt()?.let { it != 0 } == true) {
+    val endCode = (end["code"] as? Number)?.toInt()
+    if (state == CallState.DISCONNECTED && endCode != null && endCode != 0) {
       phase = "error"
       lastError = "ACS_CONNECTION_LOST: The Teams connection was lost. Check mobile data and rejoin. " +
         "(code=${end["code"]}, subcode=${end["subcode"]})"
+      val sinceStillMs = if (lastStillHeldAtMs == 0L) -1L else SystemClock.elapsedRealtime() - lastStillHeldAtMs
+      val sinceConnectedMs = if (connectedAtMs == 0L) -1L else SystemClock.elapsedRealtime() - connectedAtMs
+      // 430/10065 has arrived with the glasses stream still live. These fields say whether a still
+      // was on the tile at that moment, so the next capture can separate a Teams network drop
+      // from the photo path.
+      Log.w(
+        TAG,
+        "ACS disconnect context code=$endCode subcode=${end["subcode"]} sinceConnectedMs=$sinceConnectedMs " +
+          "sinceStillMs=$sinceStillMs stillBytes=$lastStillBytes holdActive=${outgoingHold.isActive()} " +
+          "mediaSource=$mediaSource videoEnabled=$videoEnabled source=$currentSourceKind",
+      )
+      SoftApTrace.stage(
+        "acs_disconnect_context",
+        *diag(
+          "endCode" to endCode,
+          "endSubcode" to (end["subcode"] ?: -1),
+          "sinceConnectedMs" to sinceConnectedMs,
+          "sinceStillMs" to sinceStillMs,
+          "stillBytes" to lastStillBytes,
+          "holdActive" to outgoingHold.isActive(),
+          "mediaSource" to mediaSource.name.lowercase(),
+          "videoEnabled" to videoEnabled,
+          "source" to currentSourceKind.name.lowercase(),
+        ),
+      )
     }
     Log.i(TAG, "ACS call state=$state phase=$phase previous=$previous end=$end")
     if (callId.isEmpty()) callId = readCallId()
@@ -1943,6 +2016,8 @@ class AcsMeetingSession(
     keepAgent: Boolean = false,
     failures: AtomicReference<Exception?>? = null,
   ) {
+    outgoingHold.stop()
+    StillPhotoInbox.cancelAll()
     // Invalidate first: a bounded ACS operation still in flight has to find a stale generation
     // rather than attach an agent to a session that is being torn down.
     joinGeneration.incrementAndGet()

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

@@ -103,6 +103,18 @@ class AcsFrameSender(
 
   fun isReady(): Boolean = stream.get() != null && running.get() && format.get() != null
 
+  /**
+   * The size ACS currently expects, or null before the first negotiated format arrives.
+   *
+   * [sendPlanes] drops any frame whose dimensions differ from this, so a hold that renders to the
+   * profile ceiling instead of this size is dropped whenever ACS negotiates below it.
+   */
+  fun negotiatedSize(): TargetSize? {
+    val fmt = format.get() ?: return null
+    if (fmt.width <= 0 || fmt.height <= 0) return null
+    return TargetSize(fmt.width, fmt.height)
+  }
+
   /** True when the frame was submitted to ACS; false when a readiness, size, pacing or busy gate dropped it. */
   fun sendPlanes(planes: I420Planes): Boolean {
     val out = stream.get()

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

@@ -0,0 +1,198 @@
+package com.mentra.acsmeeting.video
+
+import android.graphics.Bitmap
+import android.graphics.Canvas
+import android.graphics.Color
+import android.graphics.Matrix
+import android.graphics.Paint
+import android.graphics.RectF
+import android.graphics.BitmapFactory
+import android.media.ExifInterface
+import com.mentra.glassesmedia.source.I420Planes
+import java.io.ByteArrayInputStream
+import java.nio.ByteBuffer
+import java.util.concurrent.Executors
+import java.util.concurrent.ScheduledFuture
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicBoolean
+
+/**
+ * Replaces glasses frames on the outgoing Teams tile.
+ *
+ * A gap, or a timestamp of zero, makes Teams hold a random freeze. This pump
+ * keeps handing the existing frame sender a full-frame card or still, and the
+ * sender's own clock keeps the timestamps moving.
+ */
+class OutgoingVideoHold(
+  private val send: (I420Planes) -> Boolean,
+  private val width: () -> Int,
+  private val height: () -> Int,
+) {
+  private val running = AtomicBoolean(false)
+  private val scheduler = Executors.newSingleThreadScheduledExecutor { runnable ->
+    Thread(runnable, "acs-photo-hold").apply { isDaemon = true }
+  }
+  private var task: ScheduledFuture<*>? = null
+  private var planes: HeldPlanes? = null
+
+  fun isActive(): Boolean = running.get()
+
+  /**
+   * Begin the hold and report through [onResult] once one card or still frame has been handed to
+   * the sender, or `false` if none lands within [HANDED_TIMEOUT_MS].
+   *
+   * Non-blocking: the wait runs on the hold scheduler, never on the caller's thread, so the RN
+   * module thread cannot stall (and risk an ANR) waiting for ACS to accept the first frame.
+   */
+  fun start(kind: String, imageBytes: ByteArray?, onResult: (Boolean) -> Unit) {
+    stop()
+    val w = width()
+    val h = height()
+    val frame = when (kind) {
+      "image" -> imageBytes?.let { decode(it, w, h) } ?: card(w, h)
+      else -> card(w, h)
+    }
+    planes = frame
+    running.set(true)
+    val settled = AtomicBoolean(false)
+    task = scheduler.scheduleAtFixedRate({
+      val current = planes ?: return@scheduleAtFixedRate
+      if (!running.get()) return@scheduleAtFixedRate
+      if (send(current.frame()) && settled.compareAndSet(false, true)) onResult(true)
+    }, 0, 100, TimeUnit.MILLISECONDS)
+    // Fail the hold if no frame lands in the window, without blocking the caller.
+    scheduler.schedule({
+      if (settled.compareAndSet(false, true)) onResult(false)
+    }, HANDED_TIMEOUT_MS, TimeUnit.MILLISECONDS)
+  }
+
+  fun stop() {
+    running.set(false)
+    task?.cancel(false)
+    task = null
+    planes = null
+  }
+
+  private fun card(width: Int, height: Int): HeldPlanes {
+    val w = width.coerceAtLeast(16)
+    val h = height.coerceAtLeast(16)
+    val bitmap = Bitmap.createBitmap(w, h, Bitmap.Config.ARGB_8888)
+    val canvas = Canvas(bitmap)
+    canvas.drawColor(Color.rgb(18, 18, 22))
+    val paint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
+      color = Color.WHITE
+      textAlign = Paint.Align.CENTER
+      textSize = (h / 12f).coerceAtLeast(24f)
+    }
+    canvas.drawText("Taking a photo", w / 2f, h / 2f, paint)
+    return HeldPlanes(bitmap)
+  }
+
+  /**
+   * Decode the still and letterbox it onto a [width]x[height] frame. The frame must match the
+   * negotiated size the caller passed, or [send] drops it for a dimension mismatch.
+   */
+  private fun decode(bytes: ByteArray, width: Int, height: Int): HeldPlanes? {
+    val w = width.coerceAtLeast(16)
+    val h = height.coerceAtLeast(16)
+    val decoded = decodeUpright(bytes, w, h) ?: return null
+    val canvasBitmap = Bitmap.createBitmap(w, h, Bitmap.Config.ARGB_8888)
+    val canvas = Canvas(canvasBitmap)
+    canvas.drawColor(Color.rgb(18, 18, 22))
+    val scale = minOf(w.toFloat() / decoded.width, h.toFloat() / decoded.height)
+    val drawWidth = decoded.width * scale
+    val drawHeight = decoded.height * scale
+    val dst = RectF(
+      (w - drawWidth) / 2f,
+      (h - drawHeight) / 2f,
+      (w + drawWidth) / 2f,
+      (h + drawHeight) / 2f,
+    )
+    canvas.drawBitmap(decoded, null, dst, Paint(Paint.FILTER_BITMAP_FLAG))
+    decoded.recycle()
+    return HeldPlanes(canvasBitmap)
+  }
+
+  /**
+   * Decode at no more than twice the frame size, with the EXIF orientation applied. Glasses JPEGs
+   * carry their rotation in EXIF rather than in the pixels, and a full 12 MP decode would allocate
+   * ~48 MB for a frame that is shown at 1280x720.
+   */
+  private fun decodeUpright(bytes: ByteArray, frameWidth: Int, frameHeight: Int): Bitmap? {
+    val bounds = BitmapFactory.Options().apply { inJustDecodeBounds = true }
+    BitmapFactory.decodeByteArray(bytes, 0, bytes.size, bounds)
+    if (bounds.outWidth <= 0 || bounds.outHeight <= 0) return null
+    val longEdge = maxOf(bounds.outWidth, bounds.outHeight)
+    val target = maxOf(frameWidth, frameHeight) * 2
+    var sample = 1
+    while (longEdge / (sample * 2) >= target) sample *= 2
+    val decoded = BitmapFactory.decodeByteArray(
+      bytes,
+      0,
+      bytes.size,
+      BitmapFactory.Options().apply { inSampleSize = sample },
+    ) ?: return null
+    val orientation = runCatching {
+      ExifInterface(ByteArrayInputStream(bytes))
+        .getAttributeInt(ExifInterface.TAG_ORIENTATION, ExifInterface.ORIENTATION_NORMAL)
+    }.getOrDefault(ExifInterface.ORIENTATION_NORMAL)
+    val matrix = Matrix()
+    when (orientation) {
+      ExifInterface.ORIENTATION_ROTATE_90 -> matrix.postRotate(90f)
+      ExifInterface.ORIENTATION_ROTATE_180 -> matrix.postRotate(180f)
+      ExifInterface.ORIENTATION_ROTATE_270 -> matrix.postRotate(270f)
+      ExifInterface.ORIENTATION_FLIP_HORIZONTAL -> matrix.postScale(-1f, 1f)
+      ExifInterface.ORIENTATION_FLIP_VERTICAL -> matrix.postScale(1f, -1f)
+      ExifInterface.ORIENTATION_TRANSPOSE -> { matrix.postRotate(90f); matrix.postScale(-1f, 1f) }
+      ExifInterface.ORIENTATION_TRANSVERSE -> { matrix.postRotate(270f); matrix.postScale(-1f, 1f) }
+      else -> return decoded
+    }
+    val upright = Bitmap.createBitmap(decoded, 0, 0, decoded.width, decoded.height, matrix, true)
+    if (upright !== decoded) decoded.recycle()
+    return upright
+  }
+
+  companion object {
+    private const val HANDED_TIMEOUT_MS = 2_000L
+  }
+}
+
+private class HeldPlanes(bitmap: Bitmap) {
+  private val y: ByteBuffer
+  private val u: ByteBuffer
+  private val v: ByteBuffer
+  private val width = bitmap.width
+  private val height = bitmap.height
+  private val chromaWidth = (width + 1) / 2
+  private val chromaHeight = (height + 1) / 2
+
+  init {
+    val pixels = IntArray(width * height)
+    bitmap.getPixels(pixels, 0, width, 0, 0, width, height)
+    bitmap.recycle()
+    y = ByteBuffer.allocateDirect(width * height)
+    u = ByteBuffer.allocateDirect(chromaWidth * chromaHeight)
+    v = ByteBuffer.allocateDirect(chromaWidth * chromaHeight)
+    for (row in 0 until height) {
+      for (col in 0 until width) {
+        val color = pixels[row * width + col]
+        val r = (color shr 16) and 0xff
+        val g = (color shr 8) and 0xff
+        val b = color and 0xff
+        y.put(row * width + col, (((66 * r + 129 * g + 25 * b + 128) shr 8) + 16).toByte())
+        if (row % 2 == 0 && col % 2 == 0) {
+          val index = (row / 2) * chromaWidth + (col / 2)
+          u.put(index, (((-38 * r - 74 * g + 112 * b + 128) shr 8) + 128).toByte())
+          v.put(index, (((112 * r - 94 * g - 18 * b + 128) shr 8) + 128).toByte())
+        }
+      }
+    }
+  }
+
+  fun frame(): I420Planes {
+    y.position(0)
+    u.position(0)
+    v.position(0)
+    return I420Planes(y, width, u, chromaWidth, v, chromaWidth, width, height, System.nanoTime())
+  }
+}

package/ios/AcsFrameSender.swift

@@ -53,6 +53,18 @@ final class AcsFrameSender: NSObject {
         return true
     }
 
+    /// The size ACS currently expects. A hold frame built at any other size is tagged with the
+    /// negotiated format and dropped for a dimension mismatch, so callers render to this.
+    func negotiatedSize() -> (width: Int, height: Int)? {
+        stateLock.lock()
+        defer { stateLock.unlock() }
+        guard let stream else { return nil }
+        let width = Int(stream.format.width)
+        let height = Int(stream.format.height)
+        guard width > 0, height > 0 else { return nil }
+        return (width, height)
+    }
+
     func detach() {
         stateLock.lock()
         running = false

package/ios/AcsMeetingModule.swift

@@ -1,9 +1,12 @@
 import AVFoundation
 import AzureCommunicationCalling
 import AzureCommunicationCommon
+import CoreGraphics
+import CoreText
 import ExpoModulesCore
 import Foundation
 import GlassesMedia
+import ImageIO
 
 public class AcsMeetingModule: Module {
     private var session: AcsMeetingSession?
@@ -173,6 +176,18 @@ public class AcsMeetingModule: Module {
             session.setMuted(muted) { promise.resolve($0) }
         }
 
+        AsyncFunction("holdOutgoingVideo") { (kind: String, imageBase64: String?, promise: Promise) in
+            guard let session = self.session else {
+                promise.reject(AcsMeetingError("No active meeting"))
+                return
+            }
+            if session.setOutgoingHold(kind: kind, imageBase64: imageBase64) {
+                promise.resolve(nil)
+            } else {
+                promise.reject(AcsMeetingError("The outgoing card was not sent"))
+            }
+        }
+
         AsyncFunction("setVideoEnabled") { (enabled: Bool, promise: Promise) in
             guard let session = self.session else {
                 promise.reject(AcsMeetingError("No active meeting"))
@@ -620,11 +635,12 @@ final class AcsMeetingSession {
             self?.feedOutgoingPcm(pcm, sampleRate: rate, channels: channels, generation: generation)
         }
         let source: DecodedGlassesMediaSource = sourceConfig.kind == .softap ? LocalWhipIngestSource() : WhepVideoSource()
-        source.onFrame = { [frameSender] buffer in
-            // Preview first, deliberately: the tap must see frames the ACS sender's pacing and
-            // readiness gates would otherwise hide, and it cannot delay or break this call.
+        source.onFrame = { [weak self] buffer in
+            guard let self else { return }
+            // A photo card or still owns the tile. Glasses frames stay off it until that hold ends.
+            if self.holdingOutgoing { return }
             DecodedFrameTap.shared.offer(buffer)
-            if frameSender.send(buffer) { DecodedFrameTap.shared.recordAcsSend() }
+            if self.frameSender.send(buffer) { DecodedFrameTap.shared.recordAcsSend() }
         }
         source.onPcm = { [weak self] pcm, rate, channels in
             self?.feedOutgoingPcm(pcm, sampleRate: rate, channels: channels, generation: generation)
@@ -812,8 +828,48 @@ final class AcsMeetingSession {
         }
     }
 
+    private var holdingOutgoing = false
+    private var holdTimer: DispatchSourceTimer?
+    private var holdBuffer: CVPixelBuffer?
+
+    /// Drop glasses frames and keep sending a full-frame card so Teams does not freeze the last picture.
+    func setOutgoingHold(kind: String, imageBase64: String?) -> Bool {
+        if kind == "live" {
+            stopOutgoingHold()
+            return true
+        }
+        stopOutgoingHold()
+        // Render at the size ACS negotiated, not the profile ceiling: ACS renegotiates below the
+        // ceiling under load, and a hold frame built at 1280x720 would be dropped for a mismatch.
+        let size = frameSender.negotiatedSize() ?? (width: AcsOutgoingVideo.hd.width, height: AcsOutgoingVideo.hd.height)
+        guard let buffer = outgoingHoldPixelBuffer(kind: kind, imageBase64: imageBase64, width: size.width, height: size.height) else {
+            return false
+        }
+        holdBuffer = buffer
+        holdingOutgoing = true
+        let timer = DispatchSource.makeTimerSource(queue: queue)
+        timer.schedule(deadline: .now(), repeating: .milliseconds(100))
+        timer.setEventHandler { [weak self] in
+            guard let self, let buffer = self.holdBuffer, self.holdingOutgoing else { return }
+            _ = self.frameSender.send(buffer)
+        }
+        holdTimer = timer
+        timer.resume()
+        return frameSender.send(buffer)
+    }
+
+    private func stopOutgoingHold() {
+        holdingOutgoing = false
+        holdTimer?.cancel()
+        holdTimer = nil
+        holdBuffer = nil
+    }
+
     func leave() {
-        queue.async { self.leaveLocked() }
+        queue.async {
+            self.stopOutgoingHold()
+            self.leaveLocked()
+        }
     }
 
     func leaveAndAwait(timeout: TimeInterval, completion: @escaping (Bool) -> Void) {
@@ -1023,6 +1079,7 @@ final class AcsMeetingSession {
 
     private func leaveLocked(emitIdle: Bool = true) {
         dispatchPrecondition(condition: .onQueue(queue))
+        stopOutgoingHold()
         audioDiagnostics?.finish()
         audioDiagnostics = nil
         joinGeneration &+= 1
@@ -1483,3 +1540,153 @@ private func joinMeeting(agent: CommonCallAgent, locator: TeamsMeetingLinkLocato
         completion(nil, AcsMeetingError("Unsupported meeting agent"))
     }
 }
+
+/// Card or still for the outgoing tile. A missing still falls back to the card, never the last live frame.
+func outgoingHoldPixelBuffer(kind: String, imageBase64: String?, width: Int, height: Int) -> CVPixelBuffer? {
+    let w = max(16, width)
+    let h = max(16, height)
+    if kind == "image",
+       let imageBase64,
+       let data = Data(base64Encoded: imageBase64),
+       let source = CGImageSourceCreateWithData(data as CFData, nil),
+       let image = CGImageSourceCreateImageAtIndex(source, 0, nil),
+       let buffer = nv12PixelBuffer(image: image, width: w, height: h) {
+        return buffer
+    }
+    return takingPhotoCardPixelBuffer(width: w, height: h) ?? takingPhotoPixelBuffer(width: w, height: h)
+}
+
+func takingPhotoCardPixelBuffer(width: Int, height: Int) -> CVPixelBuffer? {
+    let colorSpace = CGColorSpaceCreateDeviceRGB()
+    guard let context = CGContext(
+        data: nil,
+        width: width,
+        height: height,
+        bitsPerComponent: 8,
+        bytesPerRow: width * 4,
+        space: colorSpace,
+        bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue
+    ) else { return nil }
+    context.setFillColor(red: 18 / 255, green: 18 / 255, blue: 22 / 255, alpha: 1)
+    context.fill(CGRect(x: 0, y: 0, width: width, height: height))
+    let font = CTFontCreateWithName("Helvetica" as CFString, CGFloat(max(24, height / 12)), nil)
+    let attrs = [
+        kCTFontAttributeName: font,
+        kCTForegroundColorAttributeName: CGColor(gray: 1, alpha: 1),
+    ] as CFDictionary
+    guard let attributed = CFAttributedStringCreate(nil, "Taking a photo" as CFString, attrs) else { return nil }
+    let line = CTLineCreateWithAttributedString(attributed)
+    var ascent: CGFloat = 0
+    let lineWidth = CGFloat(CTLineGetTypographicBounds(line, &ascent, nil, nil))
+    context.textPosition = CGPoint(x: (CGFloat(width) - lineWidth) / 2, y: (CGFloat(height) - ascent) / 2)
+    CTLineDraw(line, context)
+    guard let image = context.makeImage() else { return nil }
+    return nv12PixelBuffer(image: image, width: width, height: height)
+}
+
+func nv12PixelBuffer(image: CGImage, width: Int, height: Int) -> CVPixelBuffer? {
+    var rgba = [UInt8](repeating: 0, count: width * height * 4)
+    let drew = rgba.withUnsafeMutableBytes { raw -> Bool in
+        guard let base = raw.baseAddress else { return false }
+        guard let context = CGContext(
+            data: base,
+            width: width,
+            height: height,
+            bitsPerComponent: 8,
+            bytesPerRow: width * 4,
+            space: CGColorSpaceCreateDeviceRGB(),
+            bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue
+        ) else { return false }
+        context.setFillColor(red: 18 / 255, green: 18 / 255, blue: 22 / 255, alpha: 1)
+        context.fill(CGRect(x: 0, y: 0, width: width, height: height))
+        let scale = min(CGFloat(width) / CGFloat(image.width), CGFloat(height) / CGFloat(image.height))
+        let drawWidth = CGFloat(image.width) * scale
+        let drawHeight = CGFloat(image.height) * scale
+        context.interpolationQuality = .high
+        context.draw(
+            image,
+            in: CGRect(
+                x: (CGFloat(width) - drawWidth) / 2,
+                y: (CGFloat(height) - drawHeight) / 2,
+                width: drawWidth,
+                height: drawHeight
+            )
+        )
+        return true
+    }
+    guard drew else { return nil }
+    let attrs = [kCVPixelBufferIOSurfacePropertiesKey: [:]] as CFDictionary
+    var buffer: CVPixelBuffer?
+    let status = CVPixelBufferCreate(
+        kCFAllocatorDefault,
+        width,
+        height,
+        kCVPixelFormatType_420YpCbCr8BiPlanarFullRange,
+        attrs,
+        &buffer
+    )
+    guard status == kCVReturnSuccess, let buffer else { return nil }
+    CVPixelBufferLockBaseAddress(buffer, [])
+    defer { CVPixelBufferUnlockBaseAddress(buffer, []) }
+    guard let yPlane = CVPixelBufferGetBaseAddressOfPlane(buffer, 0),
+          let uvPlane = CVPixelBufferGetBaseAddressOfPlane(buffer, 1) else { return nil }
+    let yRow = CVPixelBufferGetBytesPerRowOfPlane(buffer, 0)
+    let uvRow = CVPixelBufferGetBytesPerRowOfPlane(buffer, 1)
+    let y = yPlane.assumingMemoryBound(to: UInt8.self)
+    let uv = uvPlane.assumingMemoryBound(to: UInt8.self)
+    for row in 0..<height {
+        for col in 0..<width {
+            let pixel = (row * width + col) * 4
+            let alpha = Int(rgba[pixel + 3])
+            var r = Int(rgba[pixel])
+            var g = Int(rgba[pixel + 1])
+            var b = Int(rgba[pixel + 2])
+            if alpha != 0 && alpha != 255 {
+                r = min(255, r * 255 / alpha)
+                g = min(255, g * 255 / alpha)
+                b = min(255, b * 255 / alpha)
+            }
+            y[row * yRow + col] = UInt8(clamping: ((66 * r + 129 * g + 25 * b + 128) >> 8) + 16)
+            if row % 2 == 0 && col % 2 == 0 {
+                let index = (row / 2) * uvRow + col
+                uv[index] = UInt8(clamping: ((-38 * r - 74 * g + 112 * b + 128) >> 8) + 128)
+                uv[index + 1] = UInt8(clamping: ((112 * r - 94 * g - 18 * b + 128) >> 8) + 128)
+            }
+        }
+    }
+    return buffer
+}
+
+/// Full-frame card sent while the glasses camera is busy with a photo. Dark, not the last live picture.
+func takingPhotoPixelBuffer(width: Int, height: Int) -> CVPixelBuffer? {
+    let attrs = [kCVPixelBufferIOSurfacePropertiesKey: [:]] as CFDictionary
+    var buffer: CVPixelBuffer?
+    let status = CVPixelBufferCreate(
+        kCFAllocatorDefault,
+        width,
+        height,
+        kCVPixelFormatType_420YpCbCr8BiPlanarFullRange,
+        attrs,
+        &buffer
+    )
+    guard status == kCVReturnSuccess, let buffer else { return nil }
+    CVPixelBufferLockBaseAddress(buffer, [])
+    defer { CVPixelBufferUnlockBaseAddress(buffer, []) }
+    if let yPlane = CVPixelBufferGetBaseAddressOfPlane(buffer, 0) {
+        let rowBytes = CVPixelBufferGetBytesPerRowOfPlane(buffer, 0)
+        let yHeight = CVPixelBufferGetHeightOfPlane(buffer, 0)
+        memset(yPlane, 18, rowBytes * yHeight)
+        let band = yHeight / 5
+        let bandY = (yHeight - band) / 2
+        let y = yPlane.assumingMemoryBound(to: UInt8.self)
+        for row in bandY..<(bandY + band) {
+            memset(y.advanced(by: row * rowBytes), 235, rowBytes)
+        }
+    }
+    if let uvPlane = CVPixelBufferGetBaseAddressOfPlane(buffer, 1) {
+        let rowBytes = CVPixelBufferGetBytesPerRowOfPlane(buffer, 1)
+        let uvHeight = CVPixelBufferGetHeightOfPlane(buffer, 1)
+        memset(uvPlane, 128, rowBytes * uvHeight)
+    }
+    return buffer
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentra/acs-meeting",
-  "version": "3.3.0-dev.487",
+  "version": "3.3.0-dev.489",
   "description": "MentraOS native ACS Teams meeting module (WHEP decode → ACS raw media)",
   "main": "build/index.js",
   "react-native": "src/index.ts",
@@ -32,7 +32,7 @@
   },
   "dependencies": {
     "@expo/config-plugins": "~55.0.10",
-    "@mentra/glasses-media": "3.3.0-dev.487"
+    "@mentra/glasses-media": "3.3.0-dev.489"
   },
   "devDependencies": {
     "expo-module-scripts": "^55.0.2",