react-native-ensys-camera-x 1.0.7

package/android/src/main/java/com/customcamera/NativeVideoViewManager.kt

@@ -0,0 +1,845 @@
+package com.customcamera
+
+import android.content.Context
+import android.graphics.Color
+import android.graphics.Matrix
+import android.graphics.SurfaceTexture
+import android.media.MediaMetadataRetriever
+import android.media.MediaPlayer
+import android.net.Uri
+import android.os.Build
+import android.os.Handler
+import android.os.Looper
+import android.view.Gravity
+import android.view.Surface
+import android.view.TextureView
+import android.view.View
+import android.widget.FrameLayout
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.ReactContext
+import com.facebook.react.bridge.ReadableArray
+import com.facebook.react.bridge.WritableMap
+import com.facebook.react.uimanager.SimpleViewManager
+import com.facebook.react.uimanager.ThemedReactContext
+import com.facebook.react.uimanager.UIManagerHelper
+import com.facebook.react.uimanager.annotations.ReactProp
+import com.facebook.react.uimanager.events.Event
+import kotlin.math.roundToInt
+
+/**
+ * ReactNative view manager for the full-screen media viewer's video cells.
+ *
+ * This is a rewrite that mirrors the proven [AspectRatioVideoView] used by the native
+ * auto-preview after recording. The previous implementation drove an
+ * [android.widget.VideoView] and computed its contain-box from `mp.videoWidth/videoHeight`
+ * — the clip's *coded* (pre-rotation) dimensions — with no rotation correction, so any
+ * portrait clip carrying 90/270 rotation metadata was laid out with a landscape aspect box
+ * and rendered cropped/stretched. It also never reset its cached dimensions when `src`
+ * changed on a recycled FlatList cell, so a reused view briefly laid out (and showed) the
+ * previous clip.
+ *
+ * The rewrite:
+ *  - Renders through a [TextureView] + [MediaPlayer] so MediaPlayer applies the clip's
+ *    rotation and hands us the fully-rotated frame.
+ *  - Derives the aspect box from ROTATION-CORRECTED display dimensions (extracted via
+ *    [MediaMetadataRetriever], swapping W/H for 90/270), never from the coded buffer.
+ *  - Fully resets cached dimensions and releases the player on every `src` change, with a
+ *    same-src guard so an unchanged rebind is a no-op — a recycled cell can never show or
+ *    lay out with the previous clip.
+ *  - Applies a deterministic aspect-fit (contain) transform and re-applies the caller's
+ *    paused state once the player is prepared.
+ */
+class NativeVideoViewManager : SimpleViewManager<AspectFitVideoContainer>() {
+  override fun getName() = "NativeCustomVideoView"
+
+  override fun createViewInstance(reactContext: ThemedReactContext): AspectFitVideoContainer {
+    return AspectFitVideoContainer(reactContext)
+  }
+
+  override fun onDropViewInstance(view: AspectFitVideoContainer) {
+    view.stopPlayback()
+    super.onDropViewInstance(view)
+  }
+
+  override fun getCommandsMap(): MutableMap<String, Int> = mutableMapOf("seekTo" to 1)
+
+  override fun receiveCommand(view: AspectFitVideoContainer, commandId: Int, args: ReadableArray?) {
+    when (commandId) {
+      1 -> view.seekTo(args?.getInt(0) ?: 0)
+    }
+  }
+
+  override fun getExportedCustomDirectEventTypeConstants(): MutableMap<String, Any> {
+    val constants: MutableMap<String, Any> =
+      super.getExportedCustomDirectEventTypeConstants() ?: mutableMapOf()
+    constants["topPlaybackProgress"] = mutableMapOf("registrationName" to "onPlaybackProgress")
+    constants["topPlaybackEnded"] = mutableMapOf("registrationName" to "onPlaybackEnded")
+    return constants
+  }
+
+  @ReactProp(name = "src")
+  fun setSrc(view: AspectFitVideoContainer, src: String?) {
+    view.setSource(src)
+  }
+
+  @ReactProp(name = "paused")
+  fun setPaused(view: AspectFitVideoContainer, paused: Boolean) {
+    view.setPaused(paused)
+  }
+
+  /**
+   * Whether this slide is the currently-visible page of the full-screen viewer. The paging
+   * host sets it per cell so exactly one clip is ever "active". Distinct from `paused` (the
+   * user's manual play/pause of the visible clip): deactivating a slide fully releases its
+   * player and resets it to 00:00, so returning to it replays from the start rather than
+   * resuming, and only the visible clip ever holds a decoder.
+   *
+   * Defaults to true so single-video consumers that never set it (e.g. the editing screen)
+   * keep their existing behaviour.
+   */
+  @ReactProp(name = "active", defaultBoolean = true)
+  fun setActive(view: AspectFitVideoContainer, active: Boolean) {
+    view.setActive(active)
+  }
+}
+
+private class VideoPlaybackEvent(
+  surfaceId: Int,
+  viewId: Int,
+  private val name: String,
+  private val payload: WritableMap
+) : Event<VideoPlaybackEvent>(surfaceId, viewId) {
+  override fun getEventName() = name
+  override fun getEventData(): WritableMap = payload
+  override fun canCoalesce(): Boolean = false
+}
+
+/**
+ * Container that renders the fitted video frame on a PURE BLACK (`#000000`) surface so the
+ * clip is clearly distinguishable from the viewer's dark background, which the video would
+ * otherwise blend into (both are near-identical dark colors).
+ *
+ * It hosts two children, both centred:
+ *  - a black [matte] View sized to the clip's exact aspect-fit rectangle, sitting behind the
+ *    video, and
+ *  - a non-opaque [AspectFitVideoView] (TextureView) filling the container, which draws the
+ *    rotation-corrected, aspect-fit frame.
+ *
+ * Because the TextureView is non-opaque and the container itself is transparent, everything
+ * OUTSIDE the fitted rectangle stays transparent — the surrounding viewer background shows
+ * through unchanged. Only the video's own rectangle is backed by black. The video is never
+ * cropped, stretched, distorted, or rescaled: the matte merely matches the fit box the video
+ * already computes, exactly mirroring the black-container treatment the native auto-preview
+ * uses. All playback, controls, gestures, and navigation are unaffected.
+ */
+class AspectFitVideoContainer(context: Context) : FrameLayout(context) {
+  // Backing matte sized to the video's fitted rectangle (stock: pure black). Hidden until
+  // the fit is known so nothing is drawn before the clip's dimensions are available.
+  private val matte = View(context).apply {
+    setBackgroundColor(
+      CameraTheme.get(context).componentColor("videoView", "matteBackground", Color.BLACK)
+    )
+    visibility = View.GONE
+  }
+
+  private val videoView = AspectFitVideoView(context).apply {
+    // Let the letterbox region stay transparent so the viewer background remains visible
+    // around the fitted video instead of painting the whole cell.
+    isOpaque = false
+    onFittedSizeChanged = { fittedW, fittedH -> updateMatte(fittedW, fittedH) }
+  }
+
+  fun seekTo(positionMs: Int) = videoView.seekTo(positionMs)
+
+  // Instant poster shown OVER the TextureView while the decoder prepares. The TextureView is
+  // deliberately masked (alpha 0) until MediaPlayer prepares and renders frame 0, which takes
+  // on the order of seconds — without a poster the slide is a blank rectangle for that whole
+  // time. The poster bitmap comes from the same background MediaMetadataRetriever pass that
+  // probes the clip's display dimensions (no extra file open), is FIT_CENTER like the video's
+  // own contain transform so it lands in the same rectangle, and is faded out only once a REAL
+  // decoded frame is flowing (onFirstFrame) — then re-shown whenever the surface is masked
+  // again (source swap / deactivation), so a blank frame is never visible.
+  private val poster = android.widget.ImageView(context).apply {
+    scaleType = android.widget.ImageView.ScaleType.FIT_CENTER
+    visibility = View.GONE
+  }
+
+  init {
+    // Matte first (behind), then the video, then the poster on top; all centred.
+    addView(
+      matte,
+      LayoutParams(0, 0, Gravity.CENTER)
+    )
+    addView(
+      videoView,
+      LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.MATCH_PARENT, Gravity.CENTER)
+    )
+    addView(
+      poster,
+      LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.MATCH_PARENT, Gravity.CENTER)
+    )
+    videoView.onPosterFrame = { bitmap ->
+      poster.setImageBitmap(bitmap)
+      // Only reveal if the decoder hasn't already beaten the probe to a real frame.
+      if (!videoView.hasRenderedFrame()) showPoster()
+    }
+    videoView.onFirstFrame = {
+      // A real decoded frame is on the surface — retire the poster with a short cross-fade.
+      poster.animate().alpha(0f).setDuration(120).withEndAction {
+        poster.visibility = View.GONE
+      }.start()
+    }
+    videoView.onMasked = {
+      // Surface hidden (source swap or slide deactivated): fall back to the poster instantly
+      // so the cell shows the clip's content, never a blank/black rectangle.
+      showPoster()
+    }
+    // The inner TextureView is an untagged child, so it can't dispatch events to JS itself.
+    // It hands progress/ended values here and this container dispatches them with ITS React tag
+    // (the one RN assigned in createViewInstance) — the only tag the JS <NativeCustomVideoView>
+    // actually listens on.
+    videoView.onProgress = { currentTimeMs, durationMs, isPlaying ->
+      dispatchProgress(currentTimeMs, durationMs, isPlaying)
+    }
+    videoView.onEnded = { durationMs ->
+      dispatchEnded(durationMs)
+    }
+  }
+
+  private fun dispatchProgress(currentTimeMs: Int, durationMs: Int, isPlaying: Boolean) {
+    val reactContext = context as? ReactContext ?: return
+    // `id` here is THIS container's React tag (set by RN after createViewInstance), so the event
+    // reaches the mounted <NativeCustomVideoView> and its onPlaybackProgress handler fires.
+    val dispatcher = UIManagerHelper.getEventDispatcherForReactTag(reactContext, id) ?: return
+    val payload = Arguments.createMap().apply {
+      putInt("currentTimeMs", currentTimeMs)
+      putInt("durationMs", durationMs)
+      putBoolean("isPlaying", isPlaying)
+    }
+    dispatcher.dispatchEvent(
+      VideoPlaybackEvent(UIManagerHelper.getSurfaceId(reactContext), id, "topPlaybackProgress", payload)
+    )
+  }
+
+  private fun dispatchEnded(durationMs: Int) {
+    val reactContext = context as? ReactContext ?: return
+    val dispatcher = UIManagerHelper.getEventDispatcherForReactTag(reactContext, id) ?: return
+    val payload = Arguments.createMap().apply {
+      putInt("durationMs", durationMs)
+    }
+    dispatcher.dispatchEvent(
+      VideoPlaybackEvent(UIManagerHelper.getSurfaceId(reactContext), id, "topPlaybackEnded", payload)
+    )
+  }
+
+  private fun showPoster() {
+    if (poster.drawable == null) return
+    poster.animate().cancel()
+    poster.alpha = 1f
+    poster.visibility = View.VISIBLE
+  }
+
+  /** Resize/centre the black matte to exactly cover the video's current aspect-fit rectangle. */
+  private fun updateMatte(fittedW: Int, fittedH: Int) {
+    if (fittedW <= 0 || fittedH <= 0) {
+      matte.visibility = View.GONE
+      return
+    }
+    val lp = matte.layoutParams as LayoutParams
+    if (lp.width != fittedW || lp.height != fittedH) {
+      lp.width = fittedW
+      lp.height = fittedH
+      lp.gravity = Gravity.CENTER
+      matte.layoutParams = lp
+    }
+    matte.visibility = View.VISIBLE
+  }
+
+  // Mirrors the video view's same-src guard: a FlatList rebind that didn't change the clip
+  // must not clear the poster (setSource below would no-op and never restore it).
+  private var lastSrc: String? = null
+
+  fun setSource(src: String?) {
+    if (src != lastSrc) {
+      lastSrc = src
+      // Clear the previous clip's poster before binding the new one so a recycled cell can
+      // never flash the old clip's frame. A cached poster for the new clip re-shows instantly
+      // from inside setSource's probe (or the cache hit below).
+      poster.animate().cancel()
+      poster.setImageBitmap(null)
+      poster.visibility = View.GONE
+    }
+    videoView.setSource(src)
+  }
+
+  fun setPaused(paused: Boolean) = videoView.setPaused(paused)
+
+  fun setActive(active: Boolean) = videoView.setActive(active)
+
+  fun stopPlayback() = videoView.stopPlayback()
+}
+
+/**
+ * A [TextureView] that renders one clip at a time with aspect-fit (contain) scaling and
+ * rotation-corrected dimensions. Self-contained so it can be driven purely by the `src` and
+ * `paused` props coming from ReactNative.
+ */
+class AspectFitVideoView(context: Context) : TextureView(context) {
+  private var mediaPlayer: MediaPlayer? = null
+  private var surface: Surface? = null
+  private val progressHandler = Handler(Looper.getMainLooper())
+  private var progressRunnable: Runnable? = null
+
+  // The clip currently bound to this view. Used as a same-src guard so re-binding the same
+  // uri (e.g. a FlatList rebind that didn't actually change the item) is a no-op.
+  private var currentUri: Uri? = null
+  private var pendingUri: Uri? = null
+  private var pendingSeekMs: Int? = null
+
+  // Rotation-corrected display dimensions of the current clip. Reset to 0 on every source
+  // change so a recycled view never lays out with the previous clip's aspect ratio.
+  private var displayW = 0
+  private var displayH = 0
+
+  // Desired playback state from the `paused` prop. Re-applied once the player is prepared,
+  // since start()/pause() are no-ops before then.
+  private var paused = true
+
+  // True once the clip has reached its end (natural completion or the progress monitor hitting
+  // the duration). While set, the underlying MediaPlayer is in (or effectively at) the
+  // PlaybackCompleted / paused-at-end state, where a plain start() is unreliable across OEMs
+  // (the exact symptom the JS replay tap hit: play at the end did nothing). start() consults this
+  // flag to restart deterministically by seeking first, then playing. Cleared whenever playback
+  // actually (re)starts or a fresh clip is opened.
+  private var completed = false
+
+  // Whether this slide is the currently-visible viewer page (the `active` prop). A player
+  // is created ONLY while active; deactivating releases it (freeing the decoder) and resets
+  // to 00:00, so re-activating replays from the start. Defaults to true so consumers that
+  // never set the prop (single-video editing screen) behave exactly as before.
+  private var active = true
+
+  private val mainHandler = Handler(Looper.getMainLooper())
+
+  // Monotonic token identifying the current source. A background dimension probe stamps the
+  // token it was launched for and only applies its result if the view still shows that clip.
+  private var sourceToken = 0
+
+  // Reports the video's current aspect-fit rectangle (in px, centred within this view) each
+  // time the transform is recomputed, so a host container can size a matching black backing.
+  var onFittedSizeChanged: ((Int, Int) -> Unit)? = null
+
+  // Poster pipeline (see AspectFitVideoContainer): a decoded frame of the CURRENT clip,
+  // delivered as soon as it is available (from cache: synchronously inside setSource).
+  var onPosterFrame: ((android.graphics.Bitmap) -> Unit)? = null
+
+  // Fired once per bound clip, the first time a REAL decoded frame reaches the surface.
+  var onFirstFrame: (() -> Unit)? = null
+
+  // Fired whenever the surface is masked (source swap / deactivation / player release), so
+  // the host can fall back to the poster instead of showing a blank rectangle.
+  var onMasked: (() -> Unit)? = null
+
+  // Whether the current clip has pushed at least one real frame to the surface.
+  private var renderedFrame = false
+  fun hasRenderedFrame(): Boolean = renderedFrame
+
+  // Last fitted size dispatched, so we only notify on an actual change.
+  private var lastFittedW = -1
+  private var lastFittedH = -1
+
+  init {
+    surfaceTextureListener = object : TextureView.SurfaceTextureListener {
+      override fun onSurfaceTextureAvailable(st: SurfaceTexture, width: Int, height: Int) {
+        surface = Surface(st)
+        updatePlaybackState()
+        applyAspectTransform()
+      }
+
+      override fun onSurfaceTextureSizeChanged(st: SurfaceTexture, width: Int, height: Int) {
+        applyAspectTransform()
+      }
+
+      override fun onSurfaceTextureDestroyed(st: SurfaceTexture): Boolean {
+        release()
+        surface?.release()
+        surface = null
+        // The surface's pixels are gone with it — restore the poster so re-attaching (e.g.
+        // returning to this screen) shows the clip's content instead of a blank rectangle.
+        renderedFrame = false
+        onMasked?.invoke()
+        return true
+      }
+
+      override fun onSurfaceTextureUpdated(st: SurfaceTexture) {
+        // Backup unmask: once real frames are flowing the view must be visible, even if the
+        // prepared/error callbacks were missed for any reason. Cheap and idempotent.
+        if (alpha != 1f) alpha = 1f
+        if (!renderedFrame) {
+          renderedFrame = true
+          onFirstFrame?.invoke()
+        }
+      }
+    }
+  }
+
+  /** Bind (or rebind) the clip to display. No-op when the uri is unchanged. */
+  fun setSource(src: String?) {
+    val uri = src?.let { Uri.parse(it) }
+    if (uri == currentUri) return
+
+    currentUri = uri
+    pendingUri = uri
+    pendingSeekMs = null
+
+    // Full reset: forget the previous clip's aspect box and tear down its player so nothing
+    // from the old clip can be shown or laid out while the new one loads.
+    displayW = 0
+    displayH = 0
+    renderedFrame = false
+    // Clear the fitted rectangle too so a recycled cell never shows the previous clip's black
+    // backing before the new clip's dimensions arrive.
+    lastFittedW = -1
+    lastFittedH = -1
+    onFittedSizeChanged?.invoke(0, 0)
+    sourceToken++
+    // Hide the surface across the swap so a recycled cell can never show the OLD clip's last
+    // frame while the new one loads (or, if this cell is inactive, indefinitely). The fresh
+    // player's onPreparedListener re-reveals it; an inactive cell simply stays masked.
+    alpha = 0f
+    release()
+
+    if (uri == null) {
+      // A cleared source can never have a live player; reconcile so any existing one is
+      // released and the frame is hidden.
+      updatePlaybackState()
+      return
+    }
+
+    // Poster fast path: a clip seen before shows its cached poster frame synchronously, so
+    // paging back to it is instant with no blank gap at all.
+    posterCache.get(uri.toString())?.let { cached ->
+      onPosterFrame?.invoke(cached)
+      onMasked?.invoke()
+    }
+
+    probeDisplayDimensions(uri, sourceToken)
+    // Reconcile: opens the player now if this slide is active and the surface is ready,
+    // otherwise onSurfaceTextureAvailable()/setActive() will when their preconditions are met.
+    updatePlaybackState()
+  }
+
+  fun setPaused(paused: Boolean) {
+    this.paused = paused
+    if (paused) {
+      stopProgressMonitoring()
+    }
+    updatePlaybackState()
+    if (!paused) {
+      startProgressMonitoring()
+    }
+  }
+
+  fun setActive(active: Boolean) {
+    if (this.active == active) return
+    this.active = active
+    if (!paused) {
+      startProgressMonitoring()
+    }
+    updatePlaybackState()
+  }
+
+  /**
+   * Single source of truth for the player lifecycle. Enforces the invariant:
+   *   a live MediaPlayer exists  ⇔  active && surface != null && pendingUri != null
+   *   and it plays               ⇔  the above AND !paused
+   *
+   * Because deactivating releases the player and re-activating creates a fresh one (prepared
+   * at position 0), a returned-to clip always replays from 00:00 rather than resuming, and at
+   * most one decoder is ever alive across all slides — the low-end win. Order-independent, so
+   * every trigger (src / paused / active / surface) can just call this.
+   */
+  private fun updatePlaybackState() {
+    val shouldHavePlayer = active && surface != null && pendingUri != null
+    if (shouldHavePlayer) {
+      if (mediaPlayer == null) {
+        // Create fresh (starts at 00:00). onPreparedListener auto-starts iff !paused.
+        openVideo()
+      } else {
+        // Player already live for this clip — just honour the manual paused state.
+        if (paused) pause() else start()
+      }
+    } else if (mediaPlayer != null) {
+      // Not the visible clip (or no surface/uri): free the decoder and reset to 00:00. Mask
+      // the frame so the next activation can't flash the last-shown frame before it reloads.
+      alpha = 0f
+      renderedFrame = false
+      onMasked?.invoke()
+      release()
+    }
+  }
+
+  // Playback events are dispatched to JS by the CONTAINER, not here. This inner TextureView is an
+  // untagged child (createViewInstance returns AspectFitVideoContainer, so RN only ever sets a
+  // React tag on the container). Dispatching from here used this view's `id`, which is
+  // View.NO_ID (-1) — a tag no mounted React view owns — so every progress/ended event was
+  // silently dropped and the JS seek bar / timer never advanced. Forward the values to the
+  // container via these callbacks and let it dispatch with its own (valid) tag.
+  var onProgress: ((currentTimeMs: Int, durationMs: Int, isPlaying: Boolean) -> Unit)? = null
+  var onEnded: ((durationMs: Int) -> Unit)? = null
+
+  private fun emitProgress(currentTimeMs: Int, durationMs: Int) {
+    onProgress?.invoke(currentTimeMs, durationMs, !paused && mediaPlayer?.isPlaying == true)
+  }
+
+  private fun emitEnded(durationMs: Int) {
+    onEnded?.invoke(durationMs)
+  }
+
+  private fun startProgressMonitoring() {
+    if (progressRunnable != null) return
+    progressRunnable = object : Runnable {
+      override fun run() {
+        val mp = mediaPlayer ?: run {
+          progressRunnable = null
+          return
+        }
+        if (!active || paused) {
+          progressRunnable = null
+          return
+        }
+        try {
+          val current = mp.currentPosition
+          val duration = mp.duration
+          if (duration > 0) {
+            emitProgress(current.coerceIn(0, duration), duration)
+            if (current >= duration) {
+              mp.pause()
+              paused = true
+              // Mark end-of-clip so the next play restarts from the beginning deterministically,
+              // and drop any stale pending seek so a plain replay tap lands at 0 (not a leftover
+              // target). A manual seek after the end re-sets pendingSeekMs and is honoured.
+              completed = true
+              pendingSeekMs = null
+              emitEnded(duration)
+              progressRunnable = null
+              return
+            }
+          }
+        } catch (_: IllegalStateException) {
+          // Player can be mid-release or unprepared — stop the loop until next state change.
+          progressRunnable = null
+          return
+        }
+        progressHandler.postDelayed(this, 200L)
+      }
+    }
+    progressHandler.post(progressRunnable!!)
+  }
+
+  private fun stopProgressMonitoring() {
+    progressRunnable?.let { progressHandler.removeCallbacks(it) }
+    progressRunnable = null
+  }
+
+  /**
+   * Extract rotation-corrected display dimensions AND a poster frame off the main thread in
+   * ONE retriever pass (mirrors `readDimensions`/`extractVideoMetadata`: swap W/H for 90/270
+   * rotation) and apply them if the view still shows this clip. The dimensions give a correct
+   * aspect box even before/independent of MediaPlayer's version-specific size reporting; the
+   * poster covers the seconds-long gap until the decoder renders its first real frame.
+   */
+  private fun probeDisplayDimensions(uri: Uri, token: Int) {
+    Thread {
+      var poster: android.graphics.Bitmap? = null
+      val (w, h) = runCatching {
+        val retriever = MediaMetadataRetriever()
+        try {
+          retriever.setDataSource(context, uri)
+          var w = retriever.extractMetadata(MediaMetadataRetriever.METADATA_KEY_VIDEO_WIDTH)?.toIntOrNull()
+          var h = retriever.extractMetadata(MediaMetadataRetriever.METADATA_KEY_VIDEO_HEIGHT)?.toIntOrNull()
+          val rotation = retriever.extractMetadata(MediaMetadataRetriever.METADATA_KEY_VIDEO_ROTATION)?.toIntOrNull() ?: 0
+          if (rotation == 90 || rotation == 270) {
+            val temp = w
+            w = h
+            h = temp
+          }
+          // Poster: best-effort ONLY (getFrameAtTime returns null for some clips/URIs — the
+          // decoder's own frame remains authoritative; see MEMORY video-preview-poster-decoder).
+          // Skip when a cached poster already fired from setSource.
+          if (posterCache.get(uri.toString()) == null) {
+            // Ask the decoder for a screen-sized frame where the platform supports it (API 27+)
+            // instead of taking the coded frame and shrinking it below: a 4K clip's coded frame is
+            // a ~33 MB allocation that exists only to be discarded, and posters are produced right
+            // after a recording, when the heap is already carrying the capture pipeline.
+            val target = context.resources.displayMetrics
+              .let { maxOf(it.widthPixels, it.heightPixels) }
+            poster = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O_MR1 && target > 0) {
+              runCatching {
+                retriever.getScaledFrameAtTime(
+                  0, MediaMetadataRetriever.OPTION_CLOSEST_SYNC, target, target
+                ) ?: retriever.getScaledFrameAtTime(
+                  1_000L, MediaMetadataRetriever.OPTION_CLOSEST, target, target
+                )
+              }.getOrNull()
+            } else {
+              retriever.getFrameAtTime(0, MediaMetadataRetriever.OPTION_CLOSEST_SYNC)
+                ?: retriever.getFrameAtTime(1_000L, MediaMetadataRetriever.OPTION_CLOSEST)
+            }
+          }
+          Pair(w, h)
+        } finally {
+          retriever.release()
+        }
+      }.getOrDefault(Pair(null, null))
+
+      // Frames come out at coded size; downscale to roughly the screen so a 4K clip's poster
+      // doesn't hold a ~33 MB bitmap in the cache. The ImageView scales it to the fit box.
+      val scaledPoster = poster?.let { raw ->
+        val target = context.resources.displayMetrics.let { maxOf(it.widthPixels, it.heightPixels) }
+        val maxDim = maxOf(raw.width, raw.height)
+        if (maxDim > target && maxDim > 0) {
+          val scale = target.toFloat() / maxDim
+          val scaled = android.graphics.Bitmap.createScaledBitmap(
+            raw,
+            (raw.width * scale).toInt().coerceAtLeast(1),
+            (raw.height * scale).toInt().coerceAtLeast(1),
+            true
+          )
+          if (scaled !== raw) raw.recycle()
+          scaled
+        } else raw
+      }
+
+      mainHandler.post {
+        // Ignore a stale probe whose clip has since been replaced.
+        if (token != sourceToken) {
+          scaledPoster?.recycle()
+          return@post
+        }
+        if (w != null && h != null && w > 0 && h > 0) {
+          displayW = w
+          displayH = h
+          applyAspectTransform()
+        }
+        if (scaledPoster != null) {
+          posterCache.put(uri.toString(), scaledPoster)
+          onPosterFrame?.invoke(scaledPoster)
+        }
+      }
+    }.start()
+  }
+
+  private fun openVideo() {
+    val uri = pendingUri ?: return
+    val surf = surface ?: return
+    release()
+    // A fresh player always begins at 00:00 and has not completed yet.
+    completed = false
+    // Hide the surface until the fresh player renders its first frame, so a recycled/returned
+    // cell can never briefly show the previous clip's last frame. The black matte shows
+    // through meanwhile, giving a clean freeze at 00:00.
+    alpha = 0f
+    mediaPlayer = MediaPlayer().apply {
+      setSurface(surf)
+      isLooping = false
+      setOnVideoSizeChangedListener { _, w, h ->
+        // Fall back to the player-reported size only when the metadata probe hasn't yet
+        // supplied rotation-corrected dimensions, so the transform still has an aspect.
+        if ((displayW <= 0 || displayH <= 0) && w > 0 && h > 0) {
+          displayW = w
+          displayH = h
+        }
+        applyAspectTransform()
+      }
+      setOnCompletionListener {
+        paused = true
+        // See the progress-monitor end branch: flag the completed state and forget any stale
+        // pending seek so the next play cleanly restarts from 0 (a manual post-end seek overrides).
+        completed = true
+        pendingSeekMs = null
+        stopProgressMonitoring()
+        val duration = try { duration } catch (_: IllegalStateException) { 0 }
+        if (duration > 0) {
+          emitProgress(duration, duration)
+          emitEnded(duration)
+        }
+      }
+      setOnPreparedListener { mp ->
+        mp.isLooping = false
+        applyAspectTransform()
+        // The player is prepared at 00:00 and ready to render — reveal the surface.
+        alpha = 1f
+        // Publish the real clip duration to JS the instant we're prepared, BEFORE the pending
+        // seek / auto-start below. The full-screen viewer opens every clip PAUSED on its poster,
+        // and progress is only emitted while PLAYING (startProgressMonitoring) — so without this
+        // the JS player never learned the clip length until the first play: the total-time
+        // readout sat at 0:00 and the seek bar had no scale to drag against (a paused scrub mapped
+        // to duration 0 → a no-op). A subsequent seekTo / progress tick refines the position.
+        val preparedDuration = try { mp.duration } catch (_: IllegalStateException) { 0 }
+        if (preparedDuration > 0) {
+          emitProgress(mp.currentPosition.coerceIn(0, preparedDuration), preparedDuration)
+        }
+        val targetSeek = pendingSeekMs
+        pendingSeekMs = null
+        if (targetSeek != null) {
+          seekTo(targetSeek)
+        }
+        // Re-apply the desired paused state now that start()/pause() will take effect.
+        if (!paused) {
+          try { mp.start(); startProgressMonitoring() } catch (e: IllegalStateException) {}
+        } else {
+          // Paused-at-open (poster mode): a prepared-but-never-started player renders
+          // NOTHING on many devices, leaving the slide on the black matte. Seeking to 0
+          // forces the decoder to push frame 0 to the surface — a true full-resolution
+          // poster, aspect-fitted by the same transform as playback, with no separate
+          // thumbnail pipeline. SEEK_CLOSEST (API 26+) decodes the exact frame instead
+          // of the nearest sync frame.
+          try {
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+              mp.seekTo(0L, MediaPlayer.SEEK_CLOSEST)
+            } else {
+              mp.seekTo(0)
+            }
+          } catch (e: IllegalStateException) {}
+        }
+      }
+      setOnErrorListener { _, _, _ ->
+        // Never leave the view stuck hidden if preparation failed.
+        alpha = 1f
+        true
+      }
+      try {
+        setDataSource(context, uri)
+        prepareAsync()
+      } catch (e: Exception) {
+        // Best effort — leave the view blank rather than crash the viewer.
+      }
+    }
+  }
+
+  /**
+   * Scale the (rotation-applied) frame MediaPlayer stretches across the whole SurfaceTexture
+   * back down to the clip's true display aspect ratio, centred and fitted inside the view.
+   * Aspect-preserving FIT (contain): the entire frame is always visible, never cropped,
+   * never stretched.
+   */
+  private fun applyAspectTransform() {
+    val vw = width
+    val vh = height
+    if (vw <= 0 || vh <= 0 || displayW <= 0 || displayH <= 0) return
+
+    val videoAspect = displayW.toFloat() / displayH.toFloat()
+    val viewAspect = vw.toFloat() / vh.toFloat()
+
+    val scaleX: Float
+    val scaleY: Float
+    if (videoAspect > viewAspect) {
+      // Clip is wider than the view: span the full width, shrink the height to fit.
+      scaleX = 1f
+      scaleY = viewAspect / videoAspect
+    } else {
+      // Clip is taller than (or equal to) the view: span the full height, shrink width.
+      scaleX = videoAspect / viewAspect
+      scaleY = 1f
+    }
+
+    val matrix = Matrix()
+    matrix.setScale(scaleX, scaleY, vw / 2f, vh / 2f)
+    setTransform(matrix)
+    invalidate()
+
+    // Publish the fitted rectangle (the visible video box) so a host can back it with a
+    // black surface sized exactly to the video — never larger, so surrounding background
+    // stays visible.
+    val fittedW = (vw * scaleX).roundToInt()
+    val fittedH = (vh * scaleY).roundToInt()
+    if (fittedW != lastFittedW || fittedH != lastFittedH) {
+      lastFittedW = fittedW
+      lastFittedH = fittedH
+      onFittedSizeChanged?.invoke(fittedW, fittedH)
+    }
+  }
+
+  fun seekTo(positionMs: Int) {
+    val clamped = positionMs.coerceAtLeast(0)
+    pendingSeekMs = clamped
+    val mp = mediaPlayer ?: return
+    try {
+      val duration = mp.duration
+      val target = if (duration > 0) clamped.coerceAtMost(duration) else clamped
+      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+        mp.seekTo(target.toLong(), MediaPlayer.SEEK_CLOSEST)
+      } else {
+        mp.seekTo(target)
+      }
+      emitProgress(mp.currentPosition.coerceAtMost(duration), duration)
+    } catch (_: IllegalStateException) {
+      // Player may be preparing or already released — will be re-applied from `pendingSeekMs`.
+    }
+  }
+
+  private fun start() {
+    val mp = mediaPlayer ?: return
+    try {
+      if (completed) {
+        // The clip is sitting at its end (PlaybackCompleted, or paused-at-duration). A plain
+        // start() from here is unreliable across devices — on some it does nothing, which is the
+        // exact "play at the end does nothing" bug. Restart deterministically: seek FIRST, then
+        // play. Honour a pending seek target (a manual seek made after the clip ended) over 0, so
+        // "seek then play" continues from that position instead of the beginning.
+        val duration = try { mp.duration } catch (_: IllegalStateException) { 0 }
+        val target = (pendingSeekMs ?: 0).let { if (duration > 0) it.coerceIn(0, duration) else it.coerceAtLeast(0) }
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+          mp.seekTo(target.toLong(), MediaPlayer.SEEK_CLOSEST)
+        } else {
+          mp.seekTo(target)
+        }
+        pendingSeekMs = null
+        // Reflect the restart position immediately so JS isn't briefly showing the end frame.
+        if (duration > 0) emitProgress(target.coerceIn(0, duration), duration)
+      }
+      mp.start()
+      completed = false
+      startProgressMonitoring()
+    } catch (e: IllegalStateException) {
+      // Player not ready / released — onPreparedListener re-applies playback.
+    }
+  }
+
+  private fun pause() {
+    try {
+      if (mediaPlayer?.isPlaying == true) mediaPlayer?.pause()
+    } catch (e: IllegalStateException) {
+      // Player not ready / released — nothing to pause.
+    }
+    stopProgressMonitoring()
+  }
+
+  fun stopPlayback() {
+    stopProgressMonitoring()
+    release()
+  }
+
+  private fun release() {
+    stopProgressMonitoring()
+    mediaPlayer?.let { mp ->
+      try { mp.stop() } catch (e: IllegalStateException) {}
+      try { mp.reset() } catch (e: Exception) {}
+      mp.release()
+    }
+    mediaPlayer = null
+  }
+
+  companion object {
+    // Small process-wide poster cache keyed by uri, shared across recycled viewer cells so
+    // paging back to a clip shows its poster synchronously. Screen-sized RGB bitmaps at
+    // ~4 slides' worth: bounded, and evicted purely by LRU.
+    private val posterCache = object : android.util.LruCache<String, android.graphics.Bitmap>(
+      (Runtime.getRuntime().maxMemory() / 1024L / 16L)
+        .coerceIn(4 * 1024L, 32 * 1024L).toInt()
+    ) {
+      override fun sizeOf(key: String, value: android.graphics.Bitmap): Int = value.byteCount / 1024
+    }
+  }
+}