react-native-ensys-camera-x 1.0.7

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

@@ -0,0 +1,1992 @@
+package com.customcamera
+
+import android.content.Context
+import android.graphics.SurfaceTexture
+import android.media.MediaCodec
+import android.media.MediaCodecInfo
+import android.media.MediaExtractor
+import android.media.MediaFormat
+import android.media.MediaMuxer
+import android.net.Uri
+import android.opengl.EGL14
+import android.opengl.EGLConfig
+import android.opengl.EGLContext
+import android.opengl.EGLDisplay
+import android.opengl.EGLExt
+import android.opengl.EGLSurface
+import android.opengl.GLES11Ext
+import android.opengl.GLES20
+import android.opengl.Matrix
+import android.os.SystemClock
+import android.util.Log
+import android.view.Surface
+import java.io.File
+import java.nio.ByteBuffer
+import java.nio.ByteOrder
+import java.nio.FloatBuffer
+
+/**
+ * Physically rotates every frame of a captured video so the recorded scene is stored
+ * UPRIGHT in the pixels themselves — not via a display transform or an orientation
+ * metadata flag. This is the video counterpart to the still-photo pixel rotation done in
+ * [CustomCameraActivity.normalizeCapturedPhotoOrientation]: the encoded frames are
+ * decoded, rotated on the GPU, and re-encoded, and the container's rotation metadata is
+ * reset to 0 so no downstream consumer double-rotates. The single re-encoded file is then
+ * used everywhere (editing preview, full-screen viewer, final review, export/send), so
+ * every stage shows the identical upright video.
+ *
+ * Pipeline (the classic decode → OpenGL → encode → mux transcode, no third-party lib):
+ *   MediaExtractor → MediaCodec decoder → SurfaceTexture (external texture)
+ *     → OpenGL ES rotation → MediaCodec encoder input Surface → MediaCodec encoder
+ *     → MediaMuxer (rotated video track + the ORIGINAL audio track copied through
+ *       sample-for-sample so audio, its timestamps, and A/V sync are bit-exact).
+ *
+ * Quality is preserved: resolution is carried over exactly (only width/height are swapped
+ * for a 90°/270° rotation), the source frame rate and bit rate are reused, every frame is
+ * rendered (none dropped), presentation timestamps are copied verbatim (so duration and
+ * sync are unchanged), and there is no cropping, scaling, or stretching — the rotation is
+ * a pure 90°-multiple remap onto an equally sized surface.
+ *
+ * The description above is [rotate]'s contract. [compress] reuses the same pipeline for a very
+ * different job and is deliberately ORIENTATION-NEUTRAL: it scales the frame in its coded
+ * orientation and copies the source's rotation metadata onto the output, so a compressed clip is
+ * displayed exactly like the clip it came from. Captured video stores its orientation as
+ * metadata rather than in the pixels, so compression must not be the one operation that changes
+ * that — see [compress] for why baking it there mis-shaped the compressed preview.
+ */
+object VideoRotationTranscoder {
+  private const val TAG = "VideoRotationTranscoder"
+  private const val TIMEOUT_US = 10_000L
+  private const val DEFAULT_FRAME_RATE = 30
+  private const val DEFAULT_I_FRAME_INTERVAL = 1
+  // The HEVC encode target a profile may prefer over the source codec. A literal (not
+  // MediaFormat.MIMETYPE_VIDEO_HEVC) so this file compiles identically on any compileSdk; the
+  // resolver only sets [VideoCompressionPlan.preferHevc] when the device actually has this encoder.
+  private const val MIME_VIDEO_HEVC = "video/hevc"
+  // Reasonable bit-rate floor so a source that does not advertise one is still encoded at
+  // high quality (≈ 0.25 bits per pixel per frame at 30fps for 1080p ≈ 15 Mbps).
+  private const val FALLBACK_BPP = 0.25
+  // Smallest edge any encoded output may have. Applied to the SCALE (see compress), never to a
+  // single edge, so honouring it can never change the frame's aspect ratio.
+  private const val MIN_ENCODED_EDGE = 160
+
+  // ── Compression targets ─────────────────────────────────────────────────────────────────
+  // The band [compress] clamps its encoder bit rate into, and the lowest quality ratio it
+  // honours. Named rather than left inline in [compress] because the size a menu quotes for a
+  // level has to be computed from the SAME numbers the encoder is configured with (see
+  // [estimateCompressedBytes]); a prediction built on a hand-copied second set of limits drifts
+  // away from the encoder the moment either one is touched.
+  private const val MIN_COMPRESSED_BIT_RATE = 200_000
+  private const val MAX_COMPRESSED_BIT_RATE = 25_000_000
+  // Quality floor. Keep the 99% menu level representable instead of collapsing the 80%..99%
+  // ladder onto one ratio. The independent encoder bitrate floor still prevents an invalid target
+  // on low-bitrate clips. Shared verbatim with the size estimate ([qualityRatioForPercent] /
+  // [estimateCompressedBytes]) so the number the menu quotes always matches the encode that runs.
+  private const val MIN_QUALITY_RATIO = 0.01f
+
+  // ── The quality floor: what a reduction may never cost ──────────────────────────────────
+  // A percentage is a request for a SIZE, and taken literally it will ask a full-size frame to
+  // survive on a rate no encoder can make look like the source: 1% of a 17 Mbps 1080p capture is
+  // 170 kbps, which is blocking and mud. So the percent-derived rate is a TARGET, and this is the
+  // floor underneath it — the fewest bits per pixel per frame an encode will accept before it stops
+  // honouring the requested reduction. Past that point the file simply stops getting smaller; that
+  // is the honest trade, and it is the one the user asked for.
+  //
+  // Expressed in bits per pixel per frame rather than as an absolute rate because that is the unit
+  // quality lives in: the same 4 Mbps is generous for 720p, adequate for 1080p and hopeless for 4K,
+  // so a fixed-rate floor would protect one resolution and abandon the others. Both figures are the
+  // low end of the "visually close to the source" range for their codec on camera-style content,
+  // which is what a compression of a capture is.
+  //
+  // Not a CQ/CRF encode, deliberately: MediaCodec's constant-quality mode is optional, unevenly
+  // implemented across vendors, and — being quality- rather than rate-targeted — makes the output
+  // size unpredictable, which every size a menu row quotes depends on. Rate-targeted VBR with a
+  // quality floor gets the same protection from a knob every device actually implements.
+  private const val MIN_BITS_PER_PIXEL_AVC = 0.065
+  // HEVC carries the same picture in roughly two thirds the bits, so its floor sits proportionately
+  // lower: equal protection, lower cost.
+  private const val MIN_BITS_PER_PIXEL_HEVC = 0.045
+  //
+  // The floor's own limit. A clip can arrive ALREADY below it — a re-shared social video, a screen
+  // recording of static content — and for such a clip the floor would say "no reduction is available
+  // at all", which is not an answer a Compress menu can give. So the floor is never allowed above
+  // this share of the source's own rate: quality is protected wherever there is fat to trim, and a
+  // real reduction is always on offer. Half, so the guarantee is easy to state — every clip can
+  // always be made at least about twice as small, and past that point the pipeline protects the
+  // picture rather than the percentage.
+  private const val MAX_FLOOR_SOURCE_SHARE = 0.5
+
+  // ── How wide a prediction can honestly be ───────────────────────────────────────────────
+  // [compress] hands the encoder a TARGET bit rate (KEY_BIT_RATE) and no bitrate mode, which on
+  // Android means VBR on virtually every device: the encoder tracks the target over the clip but
+  // spends fewer bits than asked on easy content (static scenes, low motion, letterboxing) and a
+  // few more on hard content. So the video half of an output's size is a band around the target,
+  // not a single number — which is why a level is quoted as a RANGE and the band is expressed
+  // here, next to the clamps it shares, rather than guessed at by the caller.
+  //
+  // The bounds are deliberately asymmetric: undershoot is both more common and much larger than
+  // overshoot, because a rate-limited encoder is free to spend LESS than its budget but is actively
+  // driven not to spend more.
+  /** Lowest share of the target bit rate the video half is expected to actually spend. */
+  private const val ESTIMATE_RATE_UNDERSHOOT = 0.75
+  /** Highest share of it, for content the encoder cannot hold to the target. */
+  private const val ESTIMATE_RATE_OVERSHOOT = 1.10
+
+  // ── Progress reporting ──────────────────────────────────────────────────────────────────
+  // [compress] reports how far through the pass it is so the caller's overlay can show a REAL
+  // remaining time instead of counting a prediction down. The measure is the encoder's own output
+  // timestamps against the source duration: it is the position of the work actually written to the
+  // muxer, so it advances at exactly the rate the transcode does — on a slow device it crawls, on
+  // a fast one it races, and either way the caller's arithmetic lands on the truth.
+  /** Smallest gap between two progress callbacks. Enough to animate; far too coarse to cost. */
+  private const val PROGRESS_MIN_INTERVAL_MS = 150L
+  /** …unless the fraction has moved this much, which forces a callback however recent the last. */
+  private const val PROGRESS_MIN_DELTA = 0.01f
+  /**
+   * Ceiling while the loop is running. The last steps of the pass — flushing the encoder, copying
+   * the audio track, stopping the muxer — happen after the final video sample, so reporting 1.0
+   * from inside the loop would announce a finished file that is still being written. 1.0 is sent
+   * by [compress] itself, once there really is nothing left to do.
+   */
+  private const val PROGRESS_TRANSCODE_CEILING = 0.99f
+
+  // The conversion's tail ([convertContainer]). Its loop stops well short of the ceiling above
+  // because what follows it is NOT a moment: the audio elementary stream is copied through
+  // sample-for-sample and the muxer then writes the container's index. On a long clip that is
+  // seconds of real work, and reporting the loop's end as ~1.0 told the caller the export was
+  // finished while all of it was still to come — which is exactly what left the countdown at zero
+  // watching an overlay that would not go away.
+  /** Ceiling while the conversion's transcode loop is running. */
+  private const val PROGRESS_CONVERT_LOOP_CEILING = 0.88f
+  /** Fraction complete once the audio track has been copied into the output. */
+  private const val PROGRESS_CONVERT_AFTER_AUDIO = 0.95f
+  /**
+   * Reported before the muxer is stopped — the one step of the pass with no measurable length.
+   * Deliberately above the caller's "finalizing" threshold, so the countdown hands over to a static
+   * line for it instead of quoting a second count it cannot justify.
+   */
+  private const val PROGRESS_CONVERT_TAIL = 0.99f
+
+  /**
+   * Round [value] to the nearest even pixel count (encoders reject odd dimensions), never
+   * below 2. Applied to both axes of an already aspect-correct size, so the ≤1px adjustment
+   * is the only difference from the exact scaled dimension.
+   */
+  private fun evenDimension(value: Float): Int {
+    val rounded = (value + 0.5f).toInt().coerceAtLeast(2)
+    return (rounded / 2) * 2
+  }
+
+  /** The encoder's frame size for a compression — see [encodedFrameSize]. */
+  data class EncodedFrameSize(val width: Int, val height: Int)
+
+  /**
+   * The frame a compression encodes, from the source's CODED size and the profile's resolution cap.
+   *
+   * FULL RESOLUTION IS PRESERVED. Compression lowers the bit rate; it does NOT shrink the frame.
+   * The old quality-derived downscale (sqrt(ratio) for the heavier levels) is gone: it was the
+   * single largest source of visible degradation, trading sharpness away on exactly the clips the
+   * user most wanted to keep. Nothing here reads the quality level at all, so resolution is a
+   * function of the DEVICE, never of the compression strength.
+   *
+   * Two things may still move the frame, and only these two:
+   * - [maxEncodedEdge] — the profile's device-safety ceiling. Size is bitrate × duration, so this
+   *   buys no reduction whatsoever; it is a pure stability knob that lightens decode/encode work and
+   *   holds peak memory down on small devices. 0 means "no cap" (the HIGH tier), and the caps that
+   *   remain sit at or above 1080p so an ordinary capture is never touched.
+   * - [MIN_ENCODED_EDGE] — the encoder minimum, which takes priority over the cap so an extreme
+   *   aspect can never land below it.
+   *
+   * Both apply as ONE factor to BOTH axes, so the aspect ratio is untouched; clamping each edge
+   * separately (the original behaviour) stretches a frame whenever only one of them is out of
+   * range. Coded orientation is preserved as well — no width/height swap — because it is the
+   * container's rotation metadata, re-stamped on the output, that orients the clip.
+   *
+   * Shared with [estimateCompressedByteRange] so a quoted size and the encode it predicts are
+   * always derived from the same frame.
+   */
+  internal fun encodedFrameSize(
+    codedWidth: Int,
+    codedHeight: Int,
+    maxEncodedEdge: Int
+  ): EncodedFrameSize {
+    val longestEdge = maxOf(codedWidth, codedHeight)
+    val cappedScale = if (maxEncodedEdge > 0 && longestEdge > maxEncodedEdge) {
+      maxEncodedEdge.toFloat() / longestEdge
+    } else {
+      1.0f
+    }
+    val smallestEdge = minOf(codedWidth, codedHeight)
+    val scale = if (smallestEdge > 0 && smallestEdge * cappedScale < MIN_ENCODED_EDGE) {
+      (MIN_ENCODED_EDGE.toFloat() / smallestEdge).coerceAtMost(1.0f)
+    } else {
+      cappedScale
+    }
+    return EncodedFrameSize(
+      evenDimension(codedWidth * scale),
+      evenDimension(codedHeight * scale)
+    )
+  }
+
+  /**
+   * The centre-crop needed to reduce a frame shown at [displayW]×[displayH] to [targetAspect]
+   * (width / height). This is the pure arithmetic behind cropping a captured clip to the selected
+   * aspect ratio: it keeps the FULL shorter display axis and trims only the longer display axis,
+   * symmetrically about the centre — exactly the region the live viewfinder (PreviewView
+   * FILL_CENTER) showed when the box already matched the selected ratio.
+   *
+   * @param displayW display (rotation-corrected) width in pixels.
+   * @param displayH display (rotation-corrected) height in pixels.
+   * @param targetAspect requested width/height ratio (≤ 0 → no crop).
+   * @param swapsAxes true when the source's rotation (90/270) swaps which coded axis is the display
+   *   width, i.e. coded V instead of coded U carries the trimmed display-width band.
+   * @return the cropped DISPLAY dimensions and the fraction of each CODED axis (u, v) that remains
+   *   (1.0 = untouched). The sampled band — (1.0, scaleV) or (scaleU, 1.0) — always has aspect
+   *   [targetAspect], so mapping it onto a [AspectCropPlan.outDisplayW]×[outDisplayH] surface never
+   *   distorts.
+   */
+  internal fun computeAspectCropPlan(
+    displayW: Int,
+    displayH: Int,
+    targetAspect: Float,
+    swapsAxes: Boolean
+  ): AspectCropPlan {
+    var outDisplayW = displayW
+    var outDisplayH = displayH
+    var cropScaleU = 1f
+    var cropScaleV = 1f
+    if (targetAspect > 0f && displayW > 0 && displayH > 0) {
+      val srcDisplayAspect = displayW.toFloat() / displayH.toFloat()
+      if (kotlin.math.abs(srcDisplayAspect - targetAspect) > 0.0001f) {
+        if (srcDisplayAspect > targetAspect) {
+          // Source frame is WIDER than the target → trim width, keep full height.
+          outDisplayH = displayH
+          outDisplayW = evenDimension(displayH.toFloat() * targetAspect)
+          val frac = outDisplayW.toFloat() / displayW.toFloat()
+          // Display width is coded V when the axes are swapped, else coded U.
+          if (swapsAxes) cropScaleV = frac else cropScaleU = frac
+        } else {
+          // Source frame is TALLER than the target → trim height, keep full width.
+          outDisplayW = displayW
+          outDisplayH = evenDimension(displayW.toFloat() / targetAspect)
+          val frac = outDisplayH.toFloat() / displayH.toFloat()
+          if (swapsAxes) cropScaleU = frac else cropScaleV = frac
+        }
+      }
+    }
+    return AspectCropPlan(outDisplayW, outDisplayH, cropScaleU, cropScaleV)
+  }
+
+  /** Result of [computeAspectCropPlan]. See it for the meaning of each field. */
+  data class AspectCropPlan(
+    val outDisplayW: Int,
+    val outDisplayH: Int,
+    val cropScaleU: Float,
+    val cropScaleV: Float
+  )
+
+  /**
+   * Re-encodes [input] into [output] with every frame rotated [rotationDegrees] clockwise
+   * (a multiple of 90) so the pixels are stored upright, writing rotation metadata of 0.
+   * The audio track, frame rate, bit rate, resolution, and every presentation timestamp
+   * are preserved.
+   *
+   * @return true only if [output] was produced successfully; on any failure the caller
+   *   must keep using the untouched [input] (capture must never fail because of this).
+   */
+  fun rotate(input: File, output: File, rotationDegrees: Int): Boolean {
+    val degrees = ((rotationDegrees % 360) + 360) % 360
+    if (degrees % 90 != 0) {
+      Log.w(TAG, "Unsupported rotation $rotationDegrees; skipping")
+      return false
+    }
+
+    var extractor: MediaExtractor? = null
+    var decoder: MediaCodec? = null
+    var encoder: MediaCodec? = null
+    var muxer: MediaMuxer? = null
+    var inputSurface: InputSurface? = null
+    var outputSurface: OutputSurface? = null
+    var audioInfo: AudioPassthrough? = null
+    try {
+      extractor = MediaExtractor()
+      extractor.setDataSource(input.absolutePath)
+
+      val videoTrack = firstTrack(extractor, "video/") ?: run {
+        Log.w(TAG, "No video track found")
+        return false
+      }
+      val sourceFormat = extractor.getTrackFormat(videoTrack)
+      val codedWidth = sourceFormat.getInteger(MediaFormat.KEY_WIDTH)
+      val codedHeight = sourceFormat.getInteger(MediaFormat.KEY_HEIGHT)
+
+      // A 90°/270° rotation swaps the frame's width and height; 0°/180° keeps them.
+      val swapsAxes = degrees == 90 || degrees == 270
+      val outWidth = if (swapsAxes) codedHeight else codedWidth
+      val outHeight = if (swapsAxes) codedWidth else codedHeight
+
+      val frameRate = readFrameRate(sourceFormat)
+      val bitRate = readBitRate(sourceFormat, codedWidth, codedHeight, frameRate)
+      val sourceMime = sourceFormat.getString(MediaFormat.KEY_MIME) ?: "video/avc"
+      val encodeMime = if (isEncodableVideoMime(sourceMime)) sourceMime else "video/avc"
+
+      // Configure the encoder first so we can obtain its input Surface for the GL output.
+      val encoderFormat = MediaFormat.createVideoFormat(encodeMime, outWidth, outHeight).apply {
+        setInteger(
+          MediaFormat.KEY_COLOR_FORMAT,
+          MediaCodecInfo.CodecCapabilities.COLOR_FormatSurface
+        )
+        setInteger(MediaFormat.KEY_BIT_RATE, bitRate)
+        setInteger(MediaFormat.KEY_FRAME_RATE, frameRate)
+        setInteger(MediaFormat.KEY_I_FRAME_INTERVAL, DEFAULT_I_FRAME_INTERVAL)
+      }
+      encoder = MediaCodec.createEncoderByType(encodeMime)
+      encoder.configure(encoderFormat, null, null, MediaCodec.CONFIGURE_FLAG_ENCODE)
+      inputSurface = InputSurface(encoder.createInputSurface())
+      inputSurface.makeCurrent()
+      encoder.start()
+
+      // The decoder renders decoded frames into a SurfaceTexture we own; the GL renderer
+      // then draws that texture — rotated — into the encoder's input Surface.
+      outputSurface = OutputSurface(degrees)
+      decoder = MediaCodec.createDecoderByType(sourceMime)
+      decoder.configure(sourceFormat, outputSurface.surface, null, 0)
+      decoder.start()
+      extractor.selectTrack(videoTrack)
+
+      muxer = MediaMuxer(output.absolutePath, MediaMuxer.OutputFormat.MUXER_OUTPUT_MPEG_4)
+      // Pixels are physically upright now, so the container must advertise no rotation.
+      muxer.setOrientationHint(0)
+
+      audioInfo = AudioPassthrough.open(input)
+
+      val ok = runVideoTranscode(
+        extractor, decoder, encoder, inputSurface, outputSurface, muxer, audioInfo
+      )
+      if (!ok) return false
+
+      // Copy the untouched audio track after the video track is written; timestamps are
+      // preserved verbatim so audio stays perfectly in sync and the duration is unchanged.
+      audioInfo?.copyTo(muxer)
+      return true
+    } catch (e: Exception) {
+      Log.e(TAG, "Video rotation transcode failed", e)
+      return false
+    } catch (e: OutOfMemoryError) {
+      Log.e(TAG, "Video rotation transcode ran out of memory", e)
+      return false
+    } finally {
+      try { decoder?.stop() } catch (_: Exception) {}
+      try { decoder?.release() } catch (_: Exception) {}
+      try { encoder?.stop() } catch (_: Exception) {}
+      try { encoder?.release() } catch (_: Exception) {}
+      try { muxer?.stop() } catch (_: Exception) {}
+      try { muxer?.release() } catch (_: Exception) {}
+      try { outputSurface?.release() } catch (_: Exception) {}
+      try { inputSurface?.release() } catch (_: Exception) {}
+      try { audioInfo?.release() } catch (_: Exception) {}
+      try { extractor?.release() } catch (_: Exception) {}
+    }
+  }
+
+  /**
+   * Re-encodes [input] into a new [output] file at a reduced bit rate specified by [qualityRatio],
+   * at the source's FULL resolution. The source file [input] is never overwritten, modified, or
+   * deleted.
+   *
+   * QUALITY IS PROTECTED, NOT TRADED AWAY. Compression here is a bit-rate change and nothing more:
+   *
+   *  - **Resolution** keeps its full pixel dimensions at every level (the old quality-derived
+   *    downscale is gone). The only thing that may reduce it is the profile's device-safety cap
+   *    ([VideoCompressionPlan.maxEncodedEdge]) — a per-device memory ceiling applied equally to every
+   *    level, set above what the camera records, never the compression strength.
+   *  - **Frame rate, duration and A/V sync** are the source's own: presentation timestamps are copied
+   *    verbatim, no frames are dropped, and the audio track is copied sample-for-sample rather than
+   *    re-encoded.
+   *  - **Orientation and aspect ratio** are carried through untouched (see below).
+   *  - **The rate has a QUALITY FLOOR under it** ([qualityFloorBitRate], measured in bits per pixel
+   *    per frame on the frame and codec actually being encoded), so no level can starve a full-size
+   *    frame into blocking. A percentage is a request, and beyond the floor the answer is "the file
+   *    stops getting smaller" rather than "the picture stops being watchable". The clamp on the ratio
+   *    itself ([MIN_QUALITY_RATIO]) remains only as the outer bound on the requested target.
+   *  - **The encoder is asked for its high-quality profile** (AVC High / HEVC Main) and VBR, so the
+   *    budget it does have is spent where the eye notices.
+   *
+   * The file still shrinks; it just does so with far less visible degradation.
+   *
+   * ORIENTATION-NEUTRAL BY CONSTRUCTION. Compression is a size change and nothing else: the
+   * frames are re-encoded in their CODED orientation (no axis swap, no GPU rotation) and the
+   * source's rotation metadata is copied verbatim onto the output container. The compressed
+   * clip therefore has the SAME rotation-corrected display width/height as the source — scaled
+   * by the same factor on both axes — so its aspect ratio, and the preview box every consumer
+   * derives from it, are identical to the original's.
+   *
+   * This matters because captured clips store their orientation as container metadata and keep
+   * their pixels in the sensor's coded orientation (see
+   * CustomCameraActivity.normalizeCapturedVideoOrientation). Baking that rotation into the
+   * pixels here — the previous behaviour, which swapped the output dimensions, rotated in GL and
+   * wrote an orientation hint of 0 — re-oriented the clip relative to its own original: the
+   * decoder ALSO applies the container rotation to its output Surface (MediaCodec honours
+   * MediaFormat.KEY_ROTATION, which MediaExtractor reports, and a SurfaceTexture surfaces it
+   * through getTransformMatrix), so the frame was rotated twice and re-encoded into a buffer
+   * shaped for the un-rotated frame. The result was a compressed clip whose stored geometry no
+   * longer matched the original's — which is what made the preview shrink in height and render
+   * the frame squashed/sideways after compressing.
+   *
+  * @param qualityRatio Target quality level, clamped into [[MIN_QUALITY_RATIO], 1.0]: the share of
+  *   the source bit rate to keep. Values below the floor are raised to it so the 99% menu level
+  *   remains a small but valid target.
+   * @param rotationDegrees Rotation metadata (a multiple of 90) to stamp on [output]. The
+   *   default 0 means "carry the source's own rotation through unchanged", which is what every
+   *   caller wants; a non-zero value overrides it for a source whose tag is known to be wrong.
+   * @param onProgress Called on the CALLING (worker) thread with how much of the pass is done,
+   *   0.0..1.0, as the encoder writes frames — see [PROGRESS_MIN_INTERVAL_MS]. It is the measured
+   *   position of the transcode, not a prediction, which is what lets a caller display a remaining
+   *   time that tracks the real work instead of a clock. Values are monotonic, start at 0.0 and
+   *   end at exactly 1.0 on success (nothing further is reported on failure). A source whose
+   *   duration cannot be read reports only the 0.0 and the final 1.0, so a caller must treat a
+   *   silent transcode as "progress unknown" rather than "stalled".
+   * @return true only if [output] was produced successfully.
+   */
+  fun compress(
+    input: File,
+    output: File,
+    qualityRatio: Float,
+    rotationDegrees: Int = 0,
+    // The active compression profile resolved to concrete encoder knobs (bitrate multiplier,
+    // resolution cap, codec, GOP, threading). The default leaves every historical value in place,
+    // so a caller that passes nothing gets exactly the pre-profile behaviour.
+    plan: VideoCompressionPlan = VideoCompressionPlan(),
+    onProgress: ((Float) -> Unit)? = null
+  ): Boolean {
+    val ratio = qualityRatio.coerceIn(MIN_QUALITY_RATIO, 1.0f)
+    val degrees = ((rotationDegrees % 360) + 360) % 360
+    if (degrees % 90 != 0) {
+      Log.w(TAG, "Unsupported rotation $rotationDegrees; skipping compression")
+      return false
+    }
+
+    var extractor: MediaExtractor? = null
+    var decoder: MediaCodec? = null
+    var encoder: MediaCodec? = null
+    var muxer: MediaMuxer? = null
+    var inputSurface: InputSurface? = null
+    var outputSurface: OutputSurface? = null
+    var audioInfo: AudioPassthrough? = null
+    try {
+      onProgress?.invoke(0f)
+      extractor = MediaExtractor()
+      extractor.setDataSource(input.absolutePath)
+
+      val videoTrack = firstTrack(extractor, "video/") ?: run {
+        Log.w(TAG, "No video track found for compression")
+        return false
+      }
+      val sourceFormat = extractor.getTrackFormat(videoTrack)
+      val codedWidth = sourceFormat.getInteger(MediaFormat.KEY_WIDTH)
+      val codedHeight = sourceFormat.getInteger(MediaFormat.KEY_HEIGHT)
+
+      // Read (but do not apply) the source's orientation: it is re-stamped on the output
+      // container below so the compressed clip is displayed exactly like the original.
+      val sourceRotation = if (rotationDegrees != 0) degrees else readRotation(input)
+
+      // FULL RESOLUTION IS PRESERVED — see [encodedFrameSize], which owns this arithmetic and is
+      // read by the size estimate too, so a quote can never describe a different frame from the one
+      // that is encoded. Compression lowers the bit rate; it does NOT shrink the frame. Coded
+      // orientation is preserved as well (no width/height swap): the container's rotation metadata,
+      // re-stamped below, is what orients the clip — exactly as it does for the source file.
+      val frame = encodedFrameSize(codedWidth, codedHeight, plan.maxEncodedEdge)
+      val outWidth = frame.width
+      val outHeight = frame.height
+
+      val sourceMime = sourceFormat.getString(MediaFormat.KEY_MIME) ?: "video/avc"
+      // Codec choice: honour the profile's HEVC preference (already gated on "device has an HEVC
+      // encoder AND is not a LOW tier" by the resolver) for more reduction at equal quality, else
+      // keep the source's own codec when it is re-encodable, else fall back to AVC. The DECODER
+      // always uses [sourceMime]; only the ENCODE target moves, and the MP4 muxer carries both.
+      //
+      // Resolved BEFORE the bit rate because the quality floor is codec-aware — HEVC carries the
+      // same picture in fewer bits, so it is allowed a proportionately lower floor.
+      val encodeMime = when {
+        plan.preferHevc -> MIME_VIDEO_HEVC
+        isEncodableVideoMime(sourceMime) -> sourceMime
+        else -> "video/avc"
+      }
+
+      val frameRate = readFrameRate(sourceFormat)
+      // The yardstick every progress fraction is measured against, and the length the size the
+      // menu quoted for this level was predicted over — read once, used by both.
+      val durationUs = readDurationUs(sourceFormat)
+      val origBitRate = compressionSourceBitRate(
+        sourceFormat, input.length(), codedWidth, codedHeight, frameRate, durationUs
+      )
+      // FRAME RATE IS PRESERVED TOO: [frameRate] is the source's own, handed to the encoder
+      // unchanged, so the floor below is quoted against the real frame cost. Dropping frames would
+      // be another way to buy size, and it is not taken — the request is for a smaller file, not a
+      // choppier clip.
+      //
+      // The floor is measured on the ENCODED frame (not the coded source) because that is what the
+      // encoder actually has to carry, and it is capped at the source's own rate inside the helper
+      // so an already-thin clip is never inflated past its original.
+      val floorBitRate = qualityFloorBitRate(
+        outWidth, outHeight, frameRate, encodeMime == MIME_VIDEO_HEVC, origBitRate
+      )
+      val targetBitRate =
+        targetCompressedBitRate(origBitRate, ratio, plan.bitrateScale, floorBitRate)
+
+      val encoderFormat = MediaFormat.createVideoFormat(encodeMime, outWidth, outHeight).apply {
+        setInteger(
+          MediaFormat.KEY_COLOR_FORMAT,
+          MediaCodecInfo.CodecCapabilities.COLOR_FormatSurface
+        )
+        setInteger(MediaFormat.KEY_BIT_RATE, targetBitRate)
+        setInteger(MediaFormat.KEY_FRAME_RATE, frameRate)
+        setInteger(
+          MediaFormat.KEY_I_FRAME_INTERVAL,
+          plan.keyFrameIntervalSeconds.coerceAtLeast(1)
+        )
+        // Spend the bit budget where it is needed. VBR lets the encoder move bits from easy frames
+        // (static scenes, letterboxing) to hard ones (motion, detail) while still tracking the
+        // target over the clip, so the same average rate buys a visibly cleaner picture than CBR.
+        // It also matches the assumption the size estimate is built on (see [ESTIMATE_RATE_*]).
+        setInteger(
+          MediaFormat.KEY_BITRATE_MODE,
+          MediaCodecInfo.EncoderCapabilities.BITRATE_MODE_VBR
+        )
+        applyEncoderThreadingHints(this, plan)
+      }
+      // Ask for the encoder's high-quality profile (AVC High / HEVC Main) so it uses the more
+      // efficient coding tools — the same bit rate then carries a sharper image. Only a profile the
+      // encoder actually advertises is requested, and if it still rejects the pairing at configure
+      // time the encoder is recreated with the profile stripped, so the compression always runs.
+      encoder = configureWithHighQualityProfile(
+        MediaCodec.createEncoderByType(encodeMime), encoderFormat, encodeMime
+      )
+      inputSurface = InputSurface(encoder.createInputSurface())
+      inputSurface.makeCurrent()
+      encoder.start()
+
+      // Identity render: the frame is copied through at its coded orientation, so the encoder's
+      // buffer holds exactly the pixels the source track holds (only smaller).
+      outputSurface = OutputSurface(0)
+      decoder = MediaCodec.createDecoderByType(sourceMime)
+      // Neutralise the rotation the DECODER would otherwise apply for us. MediaExtractor reports
+      // the container's rotation as KEY_ROTATION, and MediaCodec honours it by setting a
+      // transform on its output Surface — which a SurfaceTexture hands back through
+      // getTransformMatrix(). Left in place, frames would arrive pre-rotated and be re-encoded
+      // into a buffer sized for the un-rotated frame: a squashed, sideways clip whose stored
+      // geometry no longer matches the original's. Decoding in the coded orientation keeps the
+      // re-encode a pure size change.
+      sourceFormat.setInteger(MediaFormat.KEY_ROTATION, 0)
+      decoder.configure(sourceFormat, outputSurface.surface, null, 0)
+      decoder.start()
+      extractor.selectTrack(videoTrack)
+
+      muxer = MediaMuxer(output.absolutePath, MediaMuxer.OutputFormat.MUXER_OUTPUT_MPEG_4)
+      // Carry the SOURCE's orientation onto the copy. Together with the un-swapped, un-rotated
+      // pixels above this makes the compressed clip's rotation-corrected display dimensions the
+      // original's, scaled — so both files preview at the identical aspect ratio.
+      muxer.setOrientationHint(sourceRotation)
+
+      audioInfo = AudioPassthrough.open(input)
+
+      val ok = runVideoTranscode(
+        extractor, decoder, encoder, inputSurface, outputSurface, muxer, audioInfo,
+        // Read from the SOURCE track (the pass copies presentation timestamps through verbatim, so
+        // the output's timeline is the same one) and 0 when the container does not declare it —
+        // which reports no progress rather than a fraction of a guessed length.
+        durationUs = durationUs,
+        onProgress = onProgress
+      )
+      if (!ok) return false
+
+      audioInfo?.copyTo(muxer)
+      // Only now is there a complete, muxed file: the encoder is flushed and the audio track is
+      // written. Reporting 1.0 any earlier would tell the caller the copy was ready while the
+      // muxer was still finishing it.
+      onProgress?.invoke(1f)
+      return true
+    } catch (e: Exception) {
+      Log.e(TAG, "Video compression transcode failed", e)
+      return false
+    } catch (e: OutOfMemoryError) {
+      Log.e(TAG, "Video compression transcode ran out of memory", e)
+      return false
+    } finally {
+      try { decoder?.stop() } catch (_: Exception) {}
+      try { decoder?.release() } catch (_: Exception) {}
+      try { encoder?.stop() } catch (_: Exception) {}
+      try { encoder?.release() } catch (_: Exception) {}
+      try { muxer?.stop() } catch (_: Exception) {}
+      try { muxer?.release() } catch (_: Exception) {}
+      try { outputSurface?.release() } catch (_: Exception) {}
+      try { inputSurface?.release() } catch (_: Exception) {}
+      try { audioInfo?.release() } catch (_: Exception) {}
+      try { extractor?.release() } catch (_: Exception) {}
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────────────────
+  // Predicting a compression's size — what a menu can quote before anything is encoded
+  // ─────────────────────────────────────────────────────────────────────────────────────────
+
+  /**
+   * The quality ratio a "smaller by [percent]%" request maps onto.
+   *
+   * The one definition of that mapping. [compress] is handed this and [estimateCompressedBytes]
+   * predicts from this, so a level's quoted size and the encode it describes can never be derived
+   * from two different readings of the same percentage.
+   */
+  fun qualityRatioForPercent(percent: Int): Float =
+    ((100 - percent) / 100f).coerceIn(MIN_QUALITY_RATIO, 1.0f)
+
+  /**
+   * The bit rate [compress] configures its encoder with, for a source at [sourceBitRate] and a
+   * quality ratio of [ratio].
+   *
+   * A function rather than a multiplication repeated at each call site because of the CLAMP and the
+   * FLOOR: on a low-bitrate clip every heavy level lands on the same floor, so a prediction that
+   * scaled without clamping would promise files the encoder is never going to write.
+   */
+  private fun targetCompressedBitRate(
+    sourceBitRate: Int,
+    ratio: Float,
+    // The active profile's bitrate multiplier, folded in BEFORE the clamp so the estimate and the
+    // encoder read one number — a profile that halves the rate quotes half the size and writes it.
+    bitrateScale: Float = 1f,
+    // The quality floor from [qualityFloorBitRate] (0 = none/unknown). Raising the rate TO the floor
+    // rather than clamping down to it is the whole point: past this rate the file stops getting
+    // smaller instead of getting uglier. Applied before the absolute clamp so the hard device
+    // limits still have the last word.
+    floorBitRate: Int = 0
+  ): Int =
+    maxOf((sourceBitRate * ratio * bitrateScale).toInt(), floorBitRate)
+      .coerceIn(MIN_COMPRESSED_BIT_RATE, MAX_COMPRESSED_BIT_RATE)
+
+  /**
+   * The lowest rate an encode of a [width]×[height] frame at [frameRate] fps is allowed to run at —
+   * the quality floor described on [MIN_BITS_PER_PIXEL_AVC], turned into a bit rate for one specific
+   * frame.
+   *
+   * `bits-per-pixel × pixels × frames-per-second`, which is simply the definition of the unit read
+   * forwards. [hevc] picks the codec's floor, so an HEVC encode is allowed the lower rate its extra
+   * efficiency earns rather than being held to AVC's.
+   *
+   * Capped at [MAX_FLOOR_SOURCE_SHARE] of [sourceBitRate] because a floor must never INFLATE, and
+   * must never leave a menu with nothing to offer: a clip that already sits below the floor is
+   * honestly cheap rather than under-encoded, and re-encoding it upwards would spend bits to add
+   * nothing and hand back a copy larger than the original. Returns 0 — no floor — when the frame or
+   * rate is unreadable, leaving the percentage to be honoured literally as before.
+   */
+  internal fun qualityFloorBitRate(
+    width: Int,
+    height: Int,
+    frameRate: Int,
+    hevc: Boolean,
+    sourceBitRate: Int
+  ): Int {
+    if (width <= 0 || height <= 0 || frameRate <= 0) return 0
+    val bitsPerPixel = if (hevc) MIN_BITS_PER_PIXEL_HEVC else MIN_BITS_PER_PIXEL_AVC
+    val floor = (bitsPerPixel * width.toDouble() * height.toDouble() * frameRate.toDouble())
+      .coerceAtMost(Int.MAX_VALUE.toDouble())
+      .toInt()
+    if (sourceBitRate <= 0) return floor
+    return floor.coerceAtMost((sourceBitRate * MAX_FLOOR_SOURCE_SHARE).toInt())
+  }
+
+  /**
+   * The source bit rate [compress] scales: the video track's own declared rate, capped by the rate
+   * the FILE actually sustains ([sourceBytes] over [durationUs]).
+   *
+   * The cap is what keeps "smaller by N%" meaning anything. [readBitRate] reports the track's
+   * declared rate and — for the many MP4s whose extractor track format carries no `bitrate` key at
+   * all — falls back to a high-quality rate derived from pixel throughput (≈15 Mbps for 1080p30).
+   * Either figure can sit far above what the clip really spends: an already-compressed 1080p clip
+   * at 2 Mbps probes as 15 Mbps, and scaling THAT by 0.7 asks the encoder for several times the
+   * source's own rate, so the "compressed" copy comes out larger than the file it came from. A
+   * file cannot hold more video than it holds bytes, so its measured average rate is a ceiling
+   * that never takes away bits the source actually spent.
+   *
+   * Only [compress] uses it. [rotate] and [convertContainer] re-encode to PRESERVE what is there
+   * and keep reading the declared rate, whose headroom over the average is the point for them.
+   */
+  private fun compressionSourceBitRate(
+    format: MediaFormat,
+    sourceBytes: Long,
+    width: Int,
+    height: Int,
+    frameRate: Int,
+    durationUs: Long
+  ): Int {
+    val declared = readBitRate(format, width, height, frameRate)
+    val durationSeconds = durationUs / 1_000_000.0
+    if (sourceBytes <= 0L || durationSeconds <= 0.0) return declared
+    val measured = (sourceBytes * 8.0 / durationSeconds)
+      .coerceAtMost(Int.MAX_VALUE.toDouble())
+      .toInt()
+    return if (measured > 0) minOf(declared, measured) else declared
+  }
+
+  /**
+   * Everything about a source clip that determines how large a compression of it comes out — read
+   * once from the file, then good for every level in a ladder.
+   */
+  data class CompressionSizeModel(
+    /** Length of the file the encoder would read, in bytes. */
+    val sourceBytes: Long,
+    /** The rate [compress] would scale for this source — see [compressionSourceBitRate]. */
+    val sourceVideoBitRate: Int,
+    /** The source's duration in seconds, or 0 when its container declares none. */
+    val durationSeconds: Double,
+    /**
+     * The video track's CODED width/height and frame rate — what the quality floor is measured
+     * against, so a prediction can apply the same floor the encode will. 0 when unreadable, which
+     * simply leaves the prediction floor-free (the percentage is then honoured literally).
+     */
+    val codedWidth: Int = 0,
+    val codedHeight: Int = 0,
+    val frameRate: Int = 0
+  ) {
+    /** Whether there is enough here to predict a size at all. */
+    val isUsable: Boolean
+      get() = sourceBytes > 0L && sourceVideoBitRate > 0 && durationSeconds > 0.0
+  }
+
+  /**
+   * Read the [CompressionSizeModel] for a local file, or null when it holds no readable video
+   * track. Call from a background thread: it opens the file.
+   */
+  fun readCompressionSizeModel(input: File): CompressionSizeModel? {
+    val bytes = runCatching { input.takeIf { it.isFile }?.length() ?: 0L }.getOrDefault(0L)
+    if (bytes <= 0L) return null
+    return readCompressionSizeModel(bytes) { it.setDataSource(input.absolutePath) }
+  }
+
+  /**
+   * The [readCompressionSizeModel] above for a clip that only exists behind a `content://` URI.
+   * [sourceBytes] is its real length (the descriptor's, not a MediaStore column's), which a URI
+   * cannot be asked for here. Call from a background thread.
+   */
+  fun readCompressionSizeModel(
+    context: Context,
+    uri: Uri,
+    sourceBytes: Long
+  ): CompressionSizeModel? {
+    if (sourceBytes <= 0L) return null
+    return readCompressionSizeModel(sourceBytes) { it.setDataSource(context, uri, null) }
+  }
+
+  private fun readCompressionSizeModel(
+    sourceBytes: Long,
+    configure: (MediaExtractor) -> Unit
+  ): CompressionSizeModel? {
+    var extractor: MediaExtractor? = null
+    return try {
+      extractor = MediaExtractor()
+      configure(extractor)
+      val track = firstTrack(extractor, "video/") ?: return null
+      val format = extractor.getTrackFormat(track)
+      val durationUs = readDurationUs(format)
+      val codedWidth = readDimension(format, MediaFormat.KEY_WIDTH)
+      val codedHeight = readDimension(format, MediaFormat.KEY_HEIGHT)
+      val frameRate = readFrameRate(format)
+      CompressionSizeModel(
+        sourceBytes = sourceBytes,
+        sourceVideoBitRate = compressionSourceBitRate(
+          format,
+          sourceBytes,
+          codedWidth,
+          codedHeight,
+          frameRate,
+          durationUs
+        ),
+        durationSeconds = durationUs / 1_000_000.0,
+        codedWidth = codedWidth,
+        codedHeight = codedHeight,
+        frameRate = frameRate
+      )
+    } catch (e: Exception) {
+      Log.w(TAG, "Could not read a compression size model", e)
+      null
+    } finally {
+      try { extractor?.release() } catch (_: Exception) {}
+    }
+  }
+
+  /**
+   * The descriptive facts about a clip the compression cache records for a source or an output:
+   * rotation-corrected display dimensions, duration, frame rate, declared/estimated bit rate and
+   * the video codec's MIME. Purely informational — nothing about the encode depends on it — so
+   * every field is nullable and a partial read is still worth keeping.
+   */
+  data class VideoMediaInfo(
+    /** Duration in milliseconds, or null when the container declares none. */
+    val durationMs: Long?,
+    /** Display width in px (already swapped for a 90/270 rotation), or null when unreadable. */
+    val width: Int?,
+    /** Display height in px (already swapped for a 90/270 rotation), or null when unreadable. */
+    val height: Int?,
+    /** Frame rate in fps, or null when the track declares none. */
+    val frameRate: Int?,
+    /** Declared (or pixel-estimated) video bit rate in bits/sec, or null when unreadable. */
+    val bitRate: Int?,
+    /** Video track MIME, e.g. "video/avc" / "video/hevc", or null when unreadable. */
+    val mimeType: String?
+  )
+
+  /**
+   * Read a [VideoMediaInfo] for a local file, or null when it holds no readable video track. Reuses
+   * the same private track readers the size model and the transcode use, so the numbers recorded in
+   * the cache match the ones the encode saw. Rotation is corrected via [readRotation] so width/height
+   * are display dimensions (what a preview lays out with), not the coded ones. Call from a background
+   * thread: it opens the file.
+   */
+  fun readMediaInfo(file: File): VideoMediaInfo? {
+    if (!file.isFile || file.length() <= 0L) return null
+    var extractor: MediaExtractor? = null
+    return try {
+      extractor = MediaExtractor()
+      extractor.setDataSource(file.absolutePath)
+      val track = firstTrack(extractor, "video/") ?: return null
+      val format = extractor.getTrackFormat(track)
+      val codedWidth = readDimension(format, MediaFormat.KEY_WIDTH)
+      val codedHeight = readDimension(format, MediaFormat.KEY_HEIGHT)
+      val frameRate = readFrameRate(format)
+      val durationUs = readDurationUs(format)
+      // Display dims: a 90/270 recording stores its frame landscape and carries a rotation the
+      // player applies, so swap here to describe the clip as it is actually shown.
+      val rotation = readRotation(file)
+      val swap = rotation == 90 || rotation == 270
+      VideoMediaInfo(
+        durationMs = (durationUs / 1000L).takeIf { it > 0L },
+        width = (if (swap) codedHeight else codedWidth).takeIf { it > 0 },
+        height = (if (swap) codedWidth else codedHeight).takeIf { it > 0 },
+        frameRate = frameRate.takeIf { it > 0 },
+        bitRate = readBitRate(format, codedWidth, codedHeight, frameRate).takeIf { it > 0 },
+        mimeType = format.getString(MediaFormat.KEY_MIME)
+      )
+    } catch (e: Exception) {
+      Log.w(TAG, "Could not read media info for ${file.name}", e)
+      null
+    } finally {
+      try { extractor?.release() } catch (_: Exception) {}
+    }
+  }
+
+  /**
+   * The band of output sizes a compression of this source at [percent] is expected to land in —
+   * what a dropdown row quotes ("~5.8 – 7.1 MB") — or null when the model holds too little to
+   * predict anything.
+   *
+   * [expected] is the arithmetic the encoder's own configuration implies; [low] and [high] are that
+   * figure with the encoder's rate-tracking tolerance applied to the part of the file it re-encodes
+   * (see [ESTIMATE_RATE_UNDERSHOOT] / [ESTIMATE_RATE_OVERSHOOT]). Every bound is clamped the same
+   * way, so `low <= expected <= high` always holds and no bound can exceed the original.
+   */
+  data class CompressedSizeEstimate(val low: Long, val expected: Long, val high: Long)
+
+  /**
+   *
+   * The band predicts the ACTUAL file the encoder will write, so it is computed entirely from
+   * [model] — the source the pass actually reads and re-encodes ([CompressionSizeModel.sourceBytes]).
+   * [originalBytes] is the length the caller presents as the clip's "original" (0 = unknown); for a
+   * just-recorded clip that is the RECORDED length shown on the "Original video" row, which is LARGER
+   * than the smaller aspect-cropped file the encoder actually reads. It no longer anchors the
+   * arithmetic — doing so inflated every rung by the crop delta, so a level read high against the
+   * file that really lands on disk — and is kept only as a defensive upper bound, so a quote can
+   * never read larger than the figure the caller is showing as the original.
+   *
+   * The arithmetic follows what [compress] actually does, which is precisely why a flat
+   * `original × (1 - percent/100)` does not:
+   *
+   *  - **Only the video track is re-encoded.** The audio elementary stream is copied through
+   *    sample-for-sample by [AudioPassthrough], and the container's own overhead (index tables
+   *    sized by a sample count this pass does not change) rides along with it. Those bytes are the
+   *    same in the copy as in the source, so they are held OUT of the scaling and added back
+   *    whole — and out of the tolerance band too, since a copied byte is not a predicted one. On a
+   *    short clip with a full-rate audio track they are a large share of the file, and scaling them
+   *    away was most of the old error: "smaller by 70%" quoted 30% of a file whose audio alone
+   *    accounts for 25% of it.
+   *  - **The encoder is given a BIT RATE, so the video half scales with time, not with the file.**
+   *    Its size is the target rate over the source's duration — and that target is clamped
+   *    ([targetCompressedBitRate]), so on a low-bitrate clip the heavy levels all land on the same
+   *    floor and quote the same size, which is exactly what the encoder will produce.
+   *  - **Resolution does not enter into it.** The frame keeps its full size at every level, and even
+   *    the profile's device-safety cap changes only how many pixels are encoded, not the target
+   *    rate — so it does not change the size the rate-over-duration arithmetic predicts.
+   *
+   * Still an estimate, and shown as one: an encoder targets a rate rather than guaranteeing it, so
+   * easy content undershoots. That is what the range is for — the width comes from the encoder's
+   * documented behaviour, not from padding a guess. What it no longer does is describe a different
+   * calculation from the one the encoder runs.
+   */
+  fun estimateCompressedByteRange(
+    model: CompressionSizeModel,
+    originalBytes: Long,
+    percent: Int,
+    // Must match the [VideoCompressionPlan] the encode will use, so the quoted size and the produced
+    // file stay in lockstep across every profile. The whole plan rather than just its bitrate scale
+    // because the quality floor is measured on the ENCODED frame and the ENCODE codec, both of which
+    // the plan decides ([VideoCompressionPlan.maxEncodedEdge], [VideoCompressionPlan.preferHevc]).
+    plan: VideoCompressionPlan = VideoCompressionPlan()
+  ): CompressedSizeEstimate? {
+    if (!model.isUsable) return null
+    // Predict the ACTUAL output: everything rests on the file the encoder actually reads and
+    // re-encodes ([model.sourceBytes]), NOT on [originalBytes]. For a background-aspect-cropped
+    // recording the two differ — the "Original video" row shows the larger RECORDED length while the
+    // encoder reads the smaller cropped file — and anchoring passthrough/ceiling to the recorded
+    // figure inflated every rung by that crop delta, quoting sizes the encode never produces. Basing
+    // them on the real source makes each rung equal the file that will actually land on disk.
+    val encodedSourceBytes = model.sourceBytes
+    val sourceVideoBytes = model.sourceVideoBitRate / 8.0 * model.durationSeconds
+    // Everything the pass copies rather than re-encodes, as a residual: the encoded source minus what
+    // its video track spends. Derived rather than probed so it needs no second pass over the audio
+    // track, and so the ladder's lightest rung lands on the source's own size rather than near it.
+    val passthroughBytes = (encodedSourceBytes - sourceVideoBytes).coerceAtLeast(0.0)
+    // The same floor [compress] will apply, computed from the same frame and codec it will encode
+    // with. Without this the heavy rungs would quote sizes the encoder no longer produces, and the
+    // dropdown would promise a reduction the pipeline now (deliberately) refuses to make.
+    val frame = encodedFrameSize(model.codedWidth, model.codedHeight, plan.maxEncodedEdge)
+    val floorBitRate = qualityFloorBitRate(
+      frame.width, frame.height, model.frameRate, plan.preferHevc, model.sourceVideoBitRate
+    )
+    val targetBitRate = targetCompressedBitRate(
+      model.sourceVideoBitRate, qualityRatioForPercent(percent), plan.bitrateScale, floorBitRate
+    )
+    val compressedVideoBytes = targetBitRate / 8.0 * model.durationSeconds
+    // Never quote a "smaller" level as bigger than the file it comes from: the video half rests on a
+    // DECLARED rate, and a clip that over-declares its own would otherwise be shown growing. The cap
+    // is the encoded source (the output cannot exceed what it was re-encoded from at these rates),
+    // and never above the caller's presented original either. The floor keeps a sub-byte prediction
+    // from reading as an empty file.
+    val ceiling = if (originalBytes > 0L) minOf(encodedSourceBytes, originalBytes) else encodedSourceBytes
+    fun bytes(videoBytes: Double): Long =
+      Math.round(videoBytes + passthroughBytes).coerceIn(1L, ceiling)
+    return CompressedSizeEstimate(
+      low = bytes(compressedVideoBytes * ESTIMATE_RATE_UNDERSHOOT),
+      expected = bytes(compressedVideoBytes),
+      high = bytes(compressedVideoBytes * ESTIMATE_RATE_OVERSHOOT)
+    )
+  }
+
+  /**
+   * The single most likely output size for [percent] — [estimateCompressedByteRange]'s
+   * [CompressedSizeEstimate.expected], and 0 when the model cannot predict at all.
+   *
+   * Kept for callers that need one number rather than a band (the compression cache's recorded
+   * expectation, the seed arithmetic behind the countdown); the dropdown quotes the range.
+   */
+  fun estimateCompressedBytes(
+    model: CompressionSizeModel,
+    originalBytes: Long,
+    percent: Int,
+    plan: VideoCompressionPlan = VideoCompressionPlan()
+  ): Long =
+    estimateCompressedByteRange(model, originalBytes, percent, plan)?.expected ?: 0L
+
+  /**
+   * The smallest a compression of [model] can honestly come out — the quality floor expressed as a
+   * FILE SIZE rather than a rate, for the menus that quote a proportional band instead of predicting
+   * from the bit rate.
+   *
+   * `floor-rate × duration + everything the pass copies` (the audio residual, which no video setting
+   * can shrink). A row whose proportional figure lands below this is quoting a file the pipeline will
+   * not write, so the quoting side raises it to this number and the two agree again.
+   *
+   * 0 when the model cannot say — an unreadable frame or duration leaves the proportional band
+   * exactly as it was.
+   */
+  fun qualityFloorVideoBytes(
+    model: CompressionSizeModel,
+    plan: VideoCompressionPlan = VideoCompressionPlan()
+  ): Long {
+    if (!model.isUsable) return 0L
+    val frame = encodedFrameSize(model.codedWidth, model.codedHeight, plan.maxEncodedEdge)
+    val floorBitRate = qualityFloorBitRate(
+      frame.width, frame.height, model.frameRate, plan.preferHevc, model.sourceVideoBitRate
+    )
+    if (floorBitRate <= 0) return 0L
+    val sourceVideoBytes = model.sourceVideoBitRate / 8.0 * model.durationSeconds
+    val passthroughBytes = (model.sourceBytes - sourceVideoBytes).coerceAtLeast(0.0)
+    val floorBytes = floorBitRate / 8.0 * model.durationSeconds + passthroughBytes
+    return Math.round(floorBytes).coerceIn(0L, model.sourceBytes)
+  }
+
+  /** Outcome of a container conversion: whether it worked, and what it cost. */
+  data class ConversionResult(val success: Boolean, val audioDropped: Boolean = false)
+
+  /**
+   * Re-encodes [input] into [output] using [container]'s codec and container format — the video
+   * half of the preview editor's "Export By" menu. [input] is never overwritten, modified, or
+   * deleted.
+   *
+   * Everything that describes the clip is carried across:
+   *
+   *  - **Resolution.** The frame is re-encoded at its exact coded size (only rounded to even
+   *    pixels, which every encoder requires); nothing is scaled, cropped or stretched.
+   *  - **Quality.** The source track's own bit rate is reused, so the conversion targets the
+   *    quality the clip already had rather than a fixed ladder.
+   *  - **Timing.** Presentation timestamps are copied verbatim by [runVideoTranscode], so
+   *    duration, frame rate and A/V sync are unchanged.
+   *  - **Orientation.** Handled two different ways on purpose. MP4 and 3GP store rotation as
+   *    container metadata, so the frames go through in their CODED orientation and the source's
+   *    rotation is re-stamped on the copy — identical to [compress], and for the same reason
+   *    (rotating pixels that the container already rotates displays the clip twice-turned).
+   *    WebM has no rotation field, so for it the rotation is instead baked into the pixels and
+   *    the axes are swapped. Either way the exported clip DISPLAYS at the original's dimensions,
+   *    aspect ratio and orientation.
+   *  - **Audio**, when the target container can carry the source's audio codec — the elementary
+   *    stream is copied sample-for-sample, never re-encoded. WebM accepts only Vorbis/Opus, so an
+   *    AAC track cannot go with it; that is reported through [ConversionResult.audioDropped]
+   *    rather than failing the whole export, so the caller can say so out loud.
+   *
+   * @param dropAudio omit the audio track deliberately (the clip was muted in the editor). This
+   *   is how a muted export is silenced: remuxing the finished copy afterwards is not an option,
+   *   because [VideoEditUtils.mute] always writes an MP4 and would put MP4 bytes inside a `.webm`
+   *   or `.3gp` name.
+   * @param onProgress Called on the CALLING (worker) thread with how much of the pass is done,
+   *   0.0..1.0, as the encoder writes frames — the same decode → GL → encode → mux loop [compress]
+   *   runs, measured the same way, but carried on through the tail this conversion has to pay for:
+   *   the loop stops at [PROGRESS_CONVERT_LOOP_CEILING], the audio copy runs to
+   *   [PROGRESS_CONVERT_AFTER_AUDIO] and the muxer's own close-out is reported as
+   *   [PROGRESS_CONVERT_TAIL]. Monotonic, starts at 0.0 and ends at exactly 1.0 on success (nothing
+   *   further is reported on failure). A source whose duration cannot be read reports only the 0.0,
+   *   the tail and the final 1.0, so a caller must treat a silent conversion as "progress unknown"
+   *   rather than "stalled".
+   */
+  fun convertContainer(
+    input: File,
+    output: File,
+    container: MediaExportFormats.VideoContainer,
+    dropAudio: Boolean = false,
+    onProgress: ((Float) -> Unit)? = null,
+    /** Optional target aspect ratio (width/height) to center-crop the frames to. */
+    cropAspect: Float? = null,
+    // The active profile resolved to encoder knobs. Only the bitrate multiplier, the resolution cap
+    // and the threading/GOP hints apply here — the CODEC is fixed by [container], never the profile,
+    // so an "Export By WebM" stays VP8 whatever profile is chosen. The default preserves the exact
+    // pre-profile conversion (declared source rate, coded resolution, 1s GOP).
+    plan: VideoCompressionPlan = VideoCompressionPlan()
+  ): ConversionResult {
+    var extractor: MediaExtractor? = null
+    var decoder: MediaCodec? = null
+    var encoder: MediaCodec? = null
+    var muxer: MediaMuxer? = null
+    var inputSurface: InputSurface? = null
+    var outputSurface: OutputSurface? = null
+    var audioInfo: AudioPassthrough? = null
+    // The muxer is stopped explicitly below so its close-out is inside the reported pass rather
+    // than in the finally, where the caller would already have been told the export was finished.
+    var muxerStopped = false
+    try {
+      onProgress?.invoke(0f)
+      extractor = MediaExtractor()
+      extractor.setDataSource(input.absolutePath)
+
+      val videoTrack = firstTrack(extractor, "video/") ?: run {
+        Log.w(TAG, "No video track found for conversion")
+        return ConversionResult(false)
+      }
+      val sourceFormat = extractor.getTrackFormat(videoTrack)
+      val codedWidth = sourceFormat.getInteger(MediaFormat.KEY_WIDTH)
+      val codedHeight = sourceFormat.getInteger(MediaFormat.KEY_HEIGHT)
+      val sourceRotation = readRotation(input)
+
+      // Containers that carry a rotation field keep the pixels exactly as coded (renderDegrees
+      // 0) and re-stamp the hint below; the rest have the rotation drawn into the frames here.
+      val renderDegrees = if (container.supportsOrientationHint) 0 else sourceRotation
+
+      // The source's own rotation metadata ALWAYS defines how a coded pixel maps to the upright
+      // DISPLAY frame (the hint MP4/3GP re-stamp for playback, and the same value WebM bakes into
+      // the pixels). A 90°/270° rotation swaps which coded axis becomes the display width.
+      val displaySwapsAxes = sourceRotation % 180 != 0
+      val displayW = if (displaySwapsAxes) codedHeight else codedWidth
+      val displayH = if (displaySwapsAxes) codedWidth else codedHeight
+
+      // Target-cropped DISPLAY dimensions plus the centre-crop texture scales needed to reproduce
+      // the selected aspect ratio in the re-encoded pixels. When a capture aspect ratio is active
+      // the clip must be genuinely centre-cropped to it — keeping only the same frame the viewfinder
+      // showed — not merely zoomed (see [computeAspectCropPlan]).
+      val cropPlan = computeAspectCropPlan(displayW, displayH, cropAspect ?: 0f, displaySwapsAxes)
+      var outDisplayW = cropPlan.outDisplayW
+      var outDisplayH = cropPlan.outDisplayH
+      val cropScaleU = cropPlan.cropScaleU
+      val cropScaleV = cropPlan.cropScaleV
+
+      // Profile resolution cap, applied to the DISPLAY dimensions (aspect + orientation preserved by
+      // scaling both by one factor). The crop texture scales above are normalised, so lowering the
+      // encode resolution just fills the smaller surface — the framing is unchanged. 0 = no cap,
+      // which is the RECOMMENDED case on medium/high devices, leaving the export at coded size.
+      if (plan.maxEncodedEdge > 0) {
+        val longest = maxOf(outDisplayW, outDisplayH)
+        if (longest > plan.maxEncodedEdge) {
+          val s = plan.maxEncodedEdge.toFloat() / longest
+          outDisplayW = (outDisplayW * s).toInt().coerceAtLeast(1)
+          outDisplayH = (outDisplayH * s).toInt().coerceAtLeast(1)
+        }
+      }
+
+      // STORED (encoded) dimensions depend on how the container handles rotation:
+      //  • MP4/3GP store pixels in CODED orientation and rotate them at playback, so the stored
+      //    size mirrors the source's coded↔display axis mapping.
+      //  • WebM bakes the rotation into the pixels (renderDegrees above), so stored == display.
+      val outWRaw: Int
+      val outHRaw: Int
+      if (container.supportsOrientationHint) {
+        outWRaw = if (displaySwapsAxes) outDisplayH else outDisplayW
+        outHRaw = if (displaySwapsAxes) outDisplayW else outDisplayH
+      } else {
+        outWRaw = outDisplayW
+        outHRaw = outDisplayH
+      }
+      val outWidth = evenDimension(outWRaw.toFloat())
+      val outHeight = evenDimension(outHRaw.toFloat())
+
+      val frameRate = readFrameRate(sourceFormat)
+      // Bit rate. RECOMMENDED (scale 1.0) keeps the historical behaviour exactly — the declared
+      // source rate, whose headroom is the point of a quality-preserving conversion. A profile that
+      // moves the rate anchors instead to what the file ACTUALLY sustains (declared can be wildly
+      // over-stated for MP4s carrying no bitrate key) before scaling, so a "High Compression" export
+      // is genuinely smaller and a "Maximum Quality" export adds real headroom, not a guess.
+      val bitRate = if (plan.bitrateScale != 1f) {
+        val durationUs = readDurationUs(sourceFormat)
+        val anchor = compressionSourceBitRate(
+          sourceFormat, input.length(), codedWidth, codedHeight, frameRate, durationUs
+        )
+        (anchor * plan.bitrateScale).toInt()
+          .coerceIn(MIN_COMPRESSED_BIT_RATE, MAX_COMPRESSED_BIT_RATE)
+      } else {
+        readBitRate(sourceFormat, codedWidth, codedHeight, frameRate)
+      }
+      val encodeMime = container.videoMimeType
+
+      val encoderFormat = MediaFormat.createVideoFormat(encodeMime, outWidth, outHeight).apply {
+        setInteger(
+          MediaFormat.KEY_COLOR_FORMAT,
+          MediaCodecInfo.CodecCapabilities.COLOR_FormatSurface
+        )
+        setInteger(MediaFormat.KEY_BIT_RATE, bitRate)
+        setInteger(MediaFormat.KEY_FRAME_RATE, frameRate)
+        setInteger(
+          MediaFormat.KEY_I_FRAME_INTERVAL,
+          plan.keyFrameIntervalSeconds.coerceAtLeast(1)
+        )
+        applyEncoderThreadingHints(this, plan)
+      }
+      encoder = MediaCodec.createEncoderByType(encodeMime)
+      encoder.configure(encoderFormat, null, null, MediaCodec.CONFIGURE_FLAG_ENCODE)
+      inputSurface = InputSurface(encoder.createInputSurface())
+      inputSurface.makeCurrent()
+      encoder.start()
+
+      outputSurface = OutputSurface(renderDegrees, cropScaleU, cropScaleV)
+      val sourceMime = sourceFormat.getString(MediaFormat.KEY_MIME) ?: "video/avc"
+      decoder = MediaCodec.createDecoderByType(sourceMime)
+      // Decode in the CODED orientation. MediaCodec otherwise honours the container rotation
+      // MediaExtractor reports as KEY_ROTATION and hands back pre-rotated frames, which would
+      // either double-rotate the baked path or silently rotate the metadata path. See [compress].
+      sourceFormat.setInteger(MediaFormat.KEY_ROTATION, 0)
+      decoder.configure(sourceFormat, outputSurface.surface, null, 0)
+      decoder.start()
+      extractor.selectTrack(videoTrack)
+
+      muxer = MediaMuxer(output.absolutePath, container.muxerOutputFormat)
+      if (container.supportsOrientationHint) {
+        // Un-rotated pixels + the source's own hint = a copy displayed exactly like the original.
+        muxer.setOrientationHint(sourceRotation)
+      }
+
+      audioInfo = if (dropAudio) null else AudioPassthrough.open(input)
+      // Only an audio track the user still WANTS but the container cannot hold counts as dropped;
+      // a deliberately muted export is not something to warn about.
+      val audioDropped = audioInfo != null && !container.carriesAudio(audioInfo.mimeType)
+      val audioToMux = if (audioDropped) null else audioInfo
+
+      val ok = runVideoTranscode(
+        extractor, decoder, encoder, inputSurface, outputSurface, muxer, audioToMux,
+        // The yardstick every progress fraction is measured against, read from the SOURCE track
+        // exactly as [compress] reads it: this pass copies presentation timestamps through
+        // verbatim, so the output rides the same timeline. 0 when the container does not declare a
+        // duration, which reports no progress rather than a fraction of a guessed length.
+        durationUs = readDurationUs(sourceFormat),
+        onProgress = onProgress,
+        progressCeiling = PROGRESS_CONVERT_LOOP_CEILING
+      )
+      if (!ok) return ConversionResult(false)
+
+      // The audio copy is a full pass over the source's audio track, so it reports its own
+      // position rather than being folded into the step above it.
+      val audioSpan = PROGRESS_CONVERT_AFTER_AUDIO - PROGRESS_CONVERT_LOOP_CEILING
+      audioToMux?.copyTo(muxer) { copied ->
+        onProgress?.invoke(PROGRESS_CONVERT_LOOP_CEILING + audioSpan * copied)
+      }
+      onProgress?.invoke(PROGRESS_CONVERT_AFTER_AUDIO)
+
+      // Stopping the muxer is what writes the container's index, and on a long clip it is not
+      // instant. Reported BEFORE it runs, so the caller's overlay describes the step it is
+      // actually waiting on; the finally below then has nothing left to stop.
+      onProgress?.invoke(PROGRESS_CONVERT_TAIL)
+      runCatching { muxer.stop() }.onFailure {
+        Log.w(TAG, "Muxer did not stop cleanly after conversion", it)
+      }
+      muxerStopped = true
+
+      // Only now is there a complete, muxed file: the encoder is flushed, the audio track is
+      // written and the container is closed. Reporting 1.0 any earlier would tell the caller the
+      // copy was ready while the muxer was still finishing it.
+      onProgress?.invoke(1f)
+      return ConversionResult(true, audioDropped)
+    } catch (e: Exception) {
+      Log.e(TAG, "Video container conversion to ${container.extension} failed", e)
+      return ConversionResult(false)
+    } catch (e: OutOfMemoryError) {
+      Log.e(TAG, "Video container conversion ran out of memory", e)
+      return ConversionResult(false)
+    } finally {
+      try { decoder?.stop() } catch (_: Exception) {}
+      try { decoder?.release() } catch (_: Exception) {}
+      try { encoder?.stop() } catch (_: Exception) {}
+      try { encoder?.release() } catch (_: Exception) {}
+      // Only if the success path did not already stop it — stopping a stopped muxer throws.
+      if (!muxerStopped) {
+        try { muxer?.stop() } catch (_: Exception) {}
+      }
+      try { muxer?.release() } catch (_: Exception) {}
+      try { outputSurface?.release() } catch (_: Exception) {}
+      try { inputSurface?.release() } catch (_: Exception) {}
+      try { audioInfo?.release() } catch (_: Exception) {}
+      try { extractor?.release() } catch (_: Exception) {}
+    }
+  }
+
+  /**
+   * Drives the decode → rotate → encode loop until the encoder signals end-of-stream,
+   * writing each encoded frame to [muxer]. Returns false if the muxer could not be started
+   * (e.g. the encoder never produced an output format).
+   *
+   * @param durationUs the source's length in microseconds, which is what [onProgress]'s fraction
+   *   is measured against. 0 (the default) means "unknown", and reports nothing at all rather than
+   *   inventing a denominator.
+   * @param onProgress how far through the pass this is, 0.0..[progressCeiling], called on this
+   *   thread as encoded frames are muxed. Never called twice with the same value and never called
+   *   with a smaller one than the last.
+   * @param progressCeiling the highest fraction this loop may report, which is how much of the
+   *   caller's 0..1 range belongs to the loop as opposed to the steps that follow it. A caller with
+   *   an expensive tail of its own (an audio copy, a muxer close-out) hands over a lower ceiling
+   *   and reports the rest itself.
+   */
+  private fun runVideoTranscode(
+    extractor: MediaExtractor,
+    decoder: MediaCodec,
+    encoder: MediaCodec,
+    inputSurface: InputSurface,
+    outputSurface: OutputSurface,
+    muxer: MediaMuxer,
+    audioInfo: AudioPassthrough?,
+    durationUs: Long = 0L,
+    onProgress: ((Float) -> Unit)? = null,
+    progressCeiling: Float = PROGRESS_TRANSCODE_CEILING
+  ): Boolean {
+    val bufferInfo = MediaCodec.BufferInfo()
+    var videoTrackIndex = -1
+    var muxerStarted = false
+
+    var inputDone = false
+    var decoderDone = false
+    var encoderDone = false
+
+    // Last fraction handed to [onProgress] and when, so the callback is throttled by BOTH time and
+    // movement: a 4K frame can take longer than the interval (movement wins) and a 60fps clip
+    // produces frames far faster than it (time wins).
+    var lastReportedProgress = 0f
+    var lastReportedAtMs = 0L
+
+    while (!encoderDone) {
+      // 1) Feed compressed samples into the decoder.
+      if (!inputDone) {
+        val inIndex = decoder.dequeueInputBuffer(TIMEOUT_US)
+        if (inIndex >= 0) {
+          val inputBuffer = decoder.getInputBuffer(inIndex)!!
+          val sampleSize = extractor.readSampleData(inputBuffer, 0)
+          if (sampleSize < 0) {
+            decoder.queueInputBuffer(
+              inIndex, 0, 0, 0, MediaCodec.BUFFER_FLAG_END_OF_STREAM
+            )
+            inputDone = true
+          } else {
+            decoder.queueInputBuffer(
+              inIndex, 0, sampleSize, extractor.sampleTime, 0
+            )
+            extractor.advance()
+          }
+        }
+      }
+
+      // 2) Pull decoded frames, render them rotated into the encoder's input Surface.
+      if (!decoderDone) {
+        val outIndex = decoder.dequeueOutputBuffer(bufferInfo, TIMEOUT_US)
+        if (outIndex >= 0) {
+          val eos = bufferInfo.flags and MediaCodec.BUFFER_FLAG_END_OF_STREAM != 0
+          val render = bufferInfo.size != 0
+          decoder.releaseOutputBuffer(outIndex, render)
+          if (render) {
+            outputSurface.awaitNewImage()
+            outputSurface.drawImage()
+            // Carry the source presentation timestamp forward so duration and A/V sync
+            // are preserved exactly.
+            inputSurface.setPresentationTime(bufferInfo.presentationTimeUs * 1000L)
+            inputSurface.swapBuffers()
+          }
+          if (eos) {
+            decoderDone = true
+            encoder.signalEndOfInputStream()
+          }
+        }
+      }
+
+      // 3) Drain the encoder, starting the muxer once its real output format is known.
+      var encoderOutputAvailable = true
+      while (encoderOutputAvailable) {
+        val outIndex = encoder.dequeueOutputBuffer(bufferInfo, TIMEOUT_US)
+        when {
+          outIndex == MediaCodec.INFO_TRY_AGAIN_LATER -> encoderOutputAvailable = false
+          outIndex == MediaCodec.INFO_OUTPUT_FORMAT_CHANGED -> {
+            if (muxerStarted) throw RuntimeException("Encoder format changed twice")
+            videoTrackIndex = muxer.addTrack(encoder.outputFormat)
+            audioInfo?.addTrack(muxer)
+            muxer.start()
+            muxerStarted = true
+          }
+          outIndex >= 0 -> {
+            val encoded = encoder.getOutputBuffer(outIndex)!!
+            if (bufferInfo.flags and MediaCodec.BUFFER_FLAG_CODEC_CONFIG != 0) {
+              // Codec config is folded into the track format by the muxer; drop it.
+              bufferInfo.size = 0
+            }
+            if (bufferInfo.size != 0) {
+              if (!muxerStarted) throw RuntimeException("Muxer not started before data")
+              encoded.position(bufferInfo.offset)
+              encoded.limit(bufferInfo.offset + bufferInfo.size)
+              muxer.writeSampleData(videoTrackIndex, encoded, bufferInfo)
+              // Progress is reported for the sample just WRITTEN, so the fraction only ever
+              // describes work that is already in the output file.
+              if (onProgress != null && durationUs > 0L && bufferInfo.presentationTimeUs > 0L) {
+                val fraction = (bufferInfo.presentationTimeUs.toFloat() / durationUs.toFloat())
+                  .coerceIn(0f, progressCeiling)
+                val now = SystemClock.elapsedRealtime()
+                val moved = fraction - lastReportedProgress
+                if (moved > 0f &&
+                  (moved >= PROGRESS_MIN_DELTA || now - lastReportedAtMs >= PROGRESS_MIN_INTERVAL_MS)
+                ) {
+                  lastReportedProgress = fraction
+                  lastReportedAtMs = now
+                  onProgress(fraction)
+                }
+              }
+            }
+            encoder.releaseOutputBuffer(outIndex, false)
+            if (bufferInfo.flags and MediaCodec.BUFFER_FLAG_END_OF_STREAM != 0) {
+              encoderDone = true
+              encoderOutputAvailable = false
+            }
+          }
+        }
+      }
+    }
+    return muxerStarted
+  }
+
+  private fun firstTrack(extractor: MediaExtractor, mimePrefix: String): Int? {
+    for (i in 0 until extractor.trackCount) {
+      val mime = extractor.getTrackFormat(i).getString(MediaFormat.KEY_MIME) ?: continue
+      if (mime.startsWith(mimePrefix)) return i
+    }
+    return null
+  }
+
+  /**
+   * The track's length in microseconds, or 0 when the container does not declare one.
+   *
+   * 0 is not a failure: it is the honest "there is no denominator here", and every caller treats
+   * it as "report no progress" rather than dividing by a guess. Nothing about the transcode
+   * depends on it — only the progress fraction does.
+   */
+  private fun readDurationUs(format: MediaFormat): Long {
+    if (!format.containsKey(MediaFormat.KEY_DURATION)) return 0L
+    return try {
+      format.getLong(MediaFormat.KEY_DURATION).coerceAtLeast(0L)
+    } catch (_: Exception) {
+      0L
+    }
+  }
+
+  /**
+   * A dimension key off a track format, or 0 when the format does not carry it. [compress] reads
+   * width/height directly because an extractor's video format always declares them; the size-model
+   * probe goes through here instead, because a model is worth reading even off a format that is
+   * missing one — a declared bit rate makes the pixel fallback moot.
+   */
+  private fun readDimension(format: MediaFormat, key: String): Int =
+    if (!format.containsKey(key)) 0 else runCatching { format.getInteger(key) }.getOrDefault(0)
+
+  private fun readFrameRate(format: MediaFormat): Int {
+    if (!format.containsKey(MediaFormat.KEY_FRAME_RATE)) return DEFAULT_FRAME_RATE
+    // KEY_FRAME_RATE is usually stored as an Int in an extractor track format; on the rare
+    // source that stores it as a Float, getInteger throws and we fall back to the default
+    // (MediaFormat.getFloat is API 29+, so it is not used here — minSdk is 24).
+    return try {
+      val fr = format.getInteger(MediaFormat.KEY_FRAME_RATE)
+      if (fr > 0) fr else DEFAULT_FRAME_RATE
+    } catch (_: Exception) {
+      DEFAULT_FRAME_RATE
+    }
+  }
+
+  /**
+   * A track's declared bit rate, or a high-quality rate derived from its pixel throughput when the
+   * container declares none. Deliberately generous, because [rotate] and [convertContainer] re-encode
+   * to PRESERVE the source — [compressionSourceBitRate] is what caps it for a size-targeted pass.
+   */
+  private fun readBitRate(
+    format: MediaFormat,
+    width: Int,
+    height: Int,
+    frameRate: Int
+  ): Int {
+    // Prefer the source video track's declared bit rate so re-encoding preserves quality.
+    if (format.containsKey(MediaFormat.KEY_BIT_RATE)) {
+      val br = try { format.getInteger(MediaFormat.KEY_BIT_RATE) } catch (_: Exception) { 0 }
+      if (br > 0) return br
+    }
+    // Otherwise estimate a high-quality bit rate from the pixel throughput.
+    val estimated = (width.toDouble() * height.toDouble() * frameRate.toDouble() * FALLBACK_BPP)
+    return estimated.toInt().coerceAtLeast(2_000_000)
+  }
+
+  private fun isEncodableVideoMime(mime: String): Boolean {
+    return mime == "video/avc" || mime == "video/hevc" ||
+      mime == "video/x-vnd.on2.vp8" || mime == "video/x-vnd.on2.vp9" ||
+      mime == "video/mp4v-es"
+  }
+
+  /**
+   * Stamp the profile's threading hints onto an encoder [format]. KEY_PRIORITY tells the codec
+   * whether this is a realtime job (0, push the hardware) or a best-effort background one (1,
+   * gentler — the low/medium-tier default that keeps a small device responsive). KEY_OPERATING_RATE
+   * asks a capable device to run the transcode faster than realtime; it is left unset (0) on tiers
+   * that should not be pushed. Both keys exist from API 23 and are advisory — a codec that ignores
+   * them still produces a correct file. Applied to [compress] and [convertContainer] alike so the
+   * profile's speed/stability trade-off is identical on both paths.
+   */
+  private fun applyEncoderThreadingHints(format: MediaFormat, plan: VideoCompressionPlan) {
+    runCatching {
+      format.setInteger(MediaFormat.KEY_PRIORITY, plan.encoderPriority.coerceIn(0, 1))
+      if (plan.operatingRate > 0) {
+        format.setInteger(MediaFormat.KEY_OPERATING_RATE, plan.operatingRate)
+      }
+    }
+  }
+
+  /**
+   * Requests the encoder's high-quality profile on [format] and configures [encoder] with it. The
+   * profile (AVC High / HEVC Main) selects the codec's more efficient coding tools, so the SAME
+   * target bit rate carries a visibly sharper picture — the point of the "best quality per size"
+   * behaviour. Only a (profile, level) pair the encoder actually ADVERTISES in its capabilities is
+   * requested, so a configure failure is not expected; if one happens anyway the profile is dropped
+   * and the encoder is reconfigured at its default, so a compression never fails just for asking for
+   * more quality. Returns the successfully-configured encoder (the original, or its replacement).
+   */
+  private fun configureWithHighQualityProfile(
+    encoder: MediaCodec,
+    format: MediaFormat,
+    encodeMime: String
+  ): MediaCodec {
+    val profileLevel = preferredProfileLevel(encoder.codecInfo, encodeMime)
+    if (profileLevel != null) {
+      format.setInteger(MediaFormat.KEY_PROFILE, profileLevel.first)
+      format.setInteger(MediaFormat.KEY_LEVEL, profileLevel.second)
+    }
+    return try {
+      encoder.configure(format, null, null, MediaCodec.CONFIGURE_FLAG_ENCODE)
+      encoder
+    } catch (e: Exception) {
+      Log.w(TAG, "Encoder rejected high-quality profile for $encodeMime; encoding at default", e)
+      runCatching { encoder.release() }
+      // removeKey is API 29+; on 24-28 the advertised pair is authoritative, so a reconfigure would
+      // reproduce the same rejection and the outer catch turns it into a clean "couldn't compress".
+      if (profileLevel != null && android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.Q) {
+        format.removeKey(MediaFormat.KEY_PROFILE)
+        format.removeKey(MediaFormat.KEY_LEVEL)
+      }
+      val retry = MediaCodec.createEncoderByType(encodeMime)
+      try {
+        retry.configure(format, null, null, MediaCodec.CONFIGURE_FLAG_ENCODE)
+      } catch (e2: Exception) {
+        runCatching { retry.release() }
+        throw e2
+      }
+      retry
+    }
+  }
+
+  /**
+   * The best profile the encoder for [mime] advertises, paired with the highest level it lists for
+   * that profile — a combination the codec has declared it can encode, so it is safe to request. AVC
+   * favours High, HEVC favours Main; returns null when neither the capabilities nor the desired
+   * profile can be read, in which case the caller leaves the profile unset (encoder default).
+   */
+  private fun preferredProfileLevel(codecInfo: MediaCodecInfo, mime: String): Pair<Int, Int>? {
+    val caps = runCatching { codecInfo.getCapabilitiesForType(mime) }.getOrNull() ?: return null
+    val wanted = when (mime) {
+      MIME_VIDEO_HEVC -> MediaCodecInfo.CodecProfileLevel.HEVCProfileMain
+      else -> MediaCodecInfo.CodecProfileLevel.AVCProfileHigh
+    }
+    val best = caps.profileLevels
+      ?.filter { it.profile == wanted }
+      ?.maxByOrNull { it.level }
+      ?: return null
+    return wanted to best.level
+  }
+
+  // ---------------------------------------------------------------------------------------
+  // Audio passthrough: copies the original audio elementary stream sample-for-sample, so
+  // audio content, its presentation timestamps, and A/V sync are preserved bit-exact.
+  // ---------------------------------------------------------------------------------------
+  private class AudioPassthrough private constructor(
+    private val extractor: MediaExtractor,
+    private val trackIndex: Int,
+    private val format: MediaFormat
+  ) {
+    private var muxerTrackIndex = -1
+
+    /**
+     * The source audio track's codec, so a caller can ask whether a target container is able to
+     * carry it BEFORE adding the track — [MediaMuxer.addTrack] throws for a codec the container
+     * does not support, which would fail the whole conversion instead of just its audio.
+     */
+    val mimeType: String? get() = format.getString(MediaFormat.KEY_MIME)
+
+    fun addTrack(muxer: MediaMuxer) {
+      muxerTrackIndex = muxer.addTrack(format)
+    }
+
+    /**
+     * @param onProgress how much of the track has been copied, 0.0..1.0, called on this thread as
+     *   samples are written. A whole audio track is a real pass over the file — seconds of it on a
+     *   long clip — so it is reported rather than left as a silent gap at the end of a conversion.
+     *   Nothing is reported when the track declares no duration; there is no denominator to divide
+     *   by, and inventing one is worse than saying nothing.
+     */
+    fun copyTo(muxer: MediaMuxer, onProgress: ((Float) -> Unit)? = null) {
+      if (muxerTrackIndex < 0) return
+      val maxInputSize = if (format.containsKey(MediaFormat.KEY_MAX_INPUT_SIZE)) {
+        format.getInteger(MediaFormat.KEY_MAX_INPUT_SIZE).coerceAtLeast(64 * 1024)
+      } else {
+        256 * 1024
+      }
+      val durationUs = if (format.containsKey(MediaFormat.KEY_DURATION)) {
+        runCatching { format.getLong(MediaFormat.KEY_DURATION) }.getOrDefault(0L)
+      } else {
+        0L
+      }
+      var lastReportedAtMs = 0L
+      val buffer = ByteBuffer.allocate(maxInputSize)
+      val info = MediaCodec.BufferInfo()
+      extractor.selectTrack(trackIndex)
+      extractor.seekTo(0, MediaExtractor.SEEK_TO_CLOSEST_SYNC)
+      while (true) {
+        buffer.clear()
+        val size = extractor.readSampleData(buffer, 0)
+        if (size < 0) break
+        info.offset = 0
+        info.size = size
+        info.presentationTimeUs = extractor.sampleTime
+        info.flags = extractorFlagsToBufferFlags(extractor.sampleFlags)
+        muxer.writeSampleData(muxerTrackIndex, buffer, info)
+        // Audio samples are tiny and there are thousands of them, so this is throttled by time
+        // alone — the fraction moves far too little between two of them to be worth a callback.
+        if (onProgress != null && durationUs > 0L && info.presentationTimeUs > 0L) {
+          val now = SystemClock.elapsedRealtime()
+          if (now - lastReportedAtMs >= PROGRESS_MIN_INTERVAL_MS) {
+            lastReportedAtMs = now
+            onProgress(
+              (info.presentationTimeUs.toFloat() / durationUs.toFloat()).coerceIn(0f, 1f)
+            )
+          }
+        }
+        extractor.advance()
+      }
+    }
+
+    fun release() {
+      try { extractor.release() } catch (_: Exception) {}
+    }
+
+    private fun extractorFlagsToBufferFlags(sampleFlags: Int): Int {
+      var flags = 0
+      if (sampleFlags and MediaExtractor.SAMPLE_FLAG_SYNC != 0) {
+        flags = flags or MediaCodec.BUFFER_FLAG_KEY_FRAME
+      }
+      return flags
+    }
+
+    companion object {
+      fun open(input: File): AudioPassthrough? {
+        return try {
+          val extractor = MediaExtractor()
+          extractor.setDataSource(input.absolutePath)
+          var audioTrack = -1
+          for (i in 0 until extractor.trackCount) {
+            val mime = extractor.getTrackFormat(i).getString(MediaFormat.KEY_MIME) ?: continue
+            if (mime.startsWith("audio/")) { audioTrack = i; break }
+          }
+          if (audioTrack < 0) {
+            extractor.release()
+            null
+          } else {
+            AudioPassthrough(extractor, audioTrack, extractor.getTrackFormat(audioTrack))
+          }
+        } catch (e: Exception) {
+          Log.w(TAG, "No audio track to copy", e)
+          null
+        }
+      }
+    }
+  }
+
+  private fun readRotation(input: File): Int {
+    var retriever: android.media.MediaMetadataRetriever? = null
+    return try {
+      retriever = android.media.MediaMetadataRetriever()
+      retriever.setDataSource(input.absolutePath)
+      retriever.extractMetadata(android.media.MediaMetadataRetriever.METADATA_KEY_VIDEO_ROTATION)?.toIntOrNull() ?: 0
+    } catch (e: Exception) {
+      0
+    } finally {
+      runCatching { retriever?.release() }
+    }
+  }
+
+  // ---------------------------------------------------------------------------------------
+  // EGL / OpenGL helpers (adapted from the well-known Android "bigflake" decode-edit-encode
+  // pattern) used to draw the decoded frame, rotated, into the encoder's input Surface.
+  // ---------------------------------------------------------------------------------------
+
+  /** Wraps the encoder's input [Surface] in an EGL window surface + context. */
+  private class InputSurface(private val surface: Surface) {
+    private var eglDisplay: EGLDisplay = EGL14.EGL_NO_DISPLAY
+    private var eglContext: EGLContext = EGL14.EGL_NO_CONTEXT
+    private var eglSurface: EGLSurface = EGL14.EGL_NO_SURFACE
+
+    // EGL_RECORDABLE_ANDROID — marks the config as usable by a MediaCodec input surface.
+    private val eglRecordableAndroid = 0x3142
+
+    init {
+      eglDisplay = EGL14.eglGetDisplay(EGL14.EGL_DEFAULT_DISPLAY)
+      if (eglDisplay === EGL14.EGL_NO_DISPLAY) throw RuntimeException("no EGL display")
+      val version = IntArray(2)
+      if (!EGL14.eglInitialize(eglDisplay, version, 0, version, 1)) {
+        throw RuntimeException("eglInitialize failed")
+      }
+      val configAttribs = intArrayOf(
+        EGL14.EGL_RED_SIZE, 8,
+        EGL14.EGL_GREEN_SIZE, 8,
+        EGL14.EGL_BLUE_SIZE, 8,
+        EGL14.EGL_ALPHA_SIZE, 8,
+        EGL14.EGL_RENDERABLE_TYPE, EGL14.EGL_OPENGL_ES2_BIT,
+        eglRecordableAndroid, 1,
+        EGL14.EGL_NONE
+      )
+      val configs = arrayOfNulls<EGLConfig>(1)
+      val numConfigs = IntArray(1)
+      if (!EGL14.eglChooseConfig(
+          eglDisplay, configAttribs, 0, configs, 0, configs.size, numConfigs, 0
+        )
+      ) {
+        throw RuntimeException("eglChooseConfig failed")
+      }
+      val contextAttribs = intArrayOf(EGL14.EGL_CONTEXT_CLIENT_VERSION, 2, EGL14.EGL_NONE)
+      eglContext = EGL14.eglCreateContext(
+        eglDisplay, configs[0], EGL14.EGL_NO_CONTEXT, contextAttribs, 0
+      )
+      val surfaceAttribs = intArrayOf(EGL14.EGL_NONE)
+      eglSurface = EGL14.eglCreateWindowSurface(
+        eglDisplay, configs[0], surface, surfaceAttribs, 0
+      )
+      if (eglSurface === EGL14.EGL_NO_SURFACE) throw RuntimeException("eglCreateWindowSurface failed")
+    }
+
+    fun makeCurrent() {
+      if (!EGL14.eglMakeCurrent(eglDisplay, eglSurface, eglSurface, eglContext)) {
+        throw RuntimeException("eglMakeCurrent failed")
+      }
+    }
+
+    fun swapBuffers(): Boolean = EGL14.eglSwapBuffers(eglDisplay, eglSurface)
+
+    fun setPresentationTime(nsecs: Long) {
+      EGLExt.eglPresentationTimeANDROID(eglDisplay, eglSurface, nsecs)
+    }
+
+    fun release() {
+      if (eglDisplay !== EGL14.EGL_NO_DISPLAY) {
+        EGL14.eglMakeCurrent(
+          eglDisplay, EGL14.EGL_NO_SURFACE, EGL14.EGL_NO_SURFACE, EGL14.EGL_NO_CONTEXT
+        )
+        EGL14.eglDestroySurface(eglDisplay, eglSurface)
+        EGL14.eglDestroyContext(eglDisplay, eglContext)
+        EGL14.eglReleaseThread()
+        EGL14.eglTerminate(eglDisplay)
+      }
+      eglDisplay = EGL14.EGL_NO_DISPLAY
+      eglContext = EGL14.EGL_NO_CONTEXT
+      eglSurface = EGL14.EGL_NO_SURFACE
+      surface.release()
+    }
+  }
+
+  /**
+   * Owns the [Surface] the decoder renders into (backed by a [SurfaceTexture] mapped to an
+   * external GL texture), plus the [TextureRender] that redraws that texture rotated into
+   * the current EGL surface (the encoder input).
+   */
+  private class OutputSurface(
+    rotationDegrees: Int,
+    private val cropScaleX: Float = 1f,
+    private val cropScaleY: Float = 1f
+  ) : SurfaceTexture.OnFrameAvailableListener {
+    private val textureRender = TextureRender(rotationDegrees, cropScaleX, cropScaleY)
+    private val surfaceTexture: SurfaceTexture
+    val surface: Surface
+
+    // java.lang.Object (not kotlin.Any) so wait()/notifyAll() are available for the
+    // cross-thread frame handshake between onFrameAvailable and awaitNewImage.
+    private val frameSyncObject = java.lang.Object()
+    private var frameAvailable = false
+
+    init {
+      textureRender.surfaceCreated()
+      surfaceTexture = SurfaceTexture(textureRender.textureId)
+      surfaceTexture.setOnFrameAvailableListener(this)
+      surface = Surface(surfaceTexture)
+    }
+
+    fun awaitNewImage() {
+      val timeoutMs = 2500L
+      synchronized(frameSyncObject) {
+        while (!frameAvailable) {
+          frameSyncObject.wait(timeoutMs)
+          if (!frameAvailable) throw RuntimeException("Surface frame wait timed out")
+        }
+        frameAvailable = false
+      }
+      surfaceTexture.updateTexImage()
+    }
+
+    fun drawImage() {
+      textureRender.drawFrame(surfaceTexture)
+    }
+
+    override fun onFrameAvailable(st: SurfaceTexture) {
+      synchronized(frameSyncObject) {
+        frameAvailable = true
+        frameSyncObject.notifyAll()
+      }
+    }
+
+    fun release() {
+      surface.release()
+      surfaceTexture.release()
+    }
+  }
+
+  /**
+   * Draws an external OES texture (the decoded frame) onto a full-screen quad, applying a
+   * 90°-multiple rotation. The quad fills normalized device coordinates, so rotating the
+   * geometry by a multiple of 90° maps the source onto the (equally sized, axis-swapped)
+   * destination surface with no cropping, scaling, or stretching.
+   */
+  private class TextureRender(rotationDegrees: Int, private val cropScaleX: Float = 1f, private val cropScaleY: Float = 1f) {
+    var textureId = -1
+      private set
+
+    private val triangleVerticesData = floatArrayOf(
+      // X,   Y,  Z,    U, V
+      -1.0f, -1.0f, 0f, 0f, 0f,
+      1.0f, -1.0f, 0f, 1f, 0f,
+      -1.0f, 1.0f, 0f, 0f, 1f,
+      1.0f, 1.0f, 0f, 1f, 1f
+    )
+    private val triangleVertices: FloatBuffer
+
+    private val mvpMatrix = FloatArray(16)
+    private val stMatrix = FloatArray(16)
+    // Video rotation metadata is clockwise; a clockwise image rotation is a negative
+    // (clockwise) rotation about +Z in the y-up GL/NDC space used here.
+    private val rotation = (((-rotationDegrees) % 360) + 360) % 360
+
+    private var program = 0
+    private var uMVPMatrixHandle = 0
+    private var uSTMatrixHandle = 0
+    private var aPositionHandle = 0
+    private var aTextureHandle = 0
+
+    private val vertexShader = """
+      uniform mat4 uMVPMatrix;
+      uniform mat4 uSTMatrix;
+      attribute vec4 aPosition;
+      attribute vec4 aTextureCoord;
+      varying vec2 vTextureCoord;
+      void main() {
+        gl_Position = uMVPMatrix * aPosition;
+        vTextureCoord = (uSTMatrix * aTextureCoord).xy;
+      }
+    """.trimIndent()
+
+    private val fragmentShader = """
+      #extension GL_OES_EGL_image_external : require
+      precision mediump float;
+      varying vec2 vTextureCoord;
+      uniform samplerExternalOES sTexture;
+      void main() {
+        gl_FragColor = texture2D(sTexture, vTextureCoord);
+      }
+    """.trimIndent()
+
+    init {
+      triangleVertices = ByteBuffer
+        .allocateDirect(triangleVerticesData.size * FLOAT_SIZE_BYTES)
+        .order(ByteOrder.nativeOrder())
+        .asFloatBuffer()
+      triangleVertices.put(triangleVerticesData).position(0)
+      Matrix.setIdentityM(stMatrix, 0)
+    }
+
+    fun surfaceCreated() {
+      program = createProgram(vertexShader, fragmentShader)
+      if (program == 0) throw RuntimeException("failed to create GL program")
+      aPositionHandle = GLES20.glGetAttribLocation(program, "aPosition")
+      aTextureHandle = GLES20.glGetAttribLocation(program, "aTextureCoord")
+      uMVPMatrixHandle = GLES20.glGetUniformLocation(program, "uMVPMatrix")
+      uSTMatrixHandle = GLES20.glGetUniformLocation(program, "uSTMatrix")
+
+      val textures = IntArray(1)
+      GLES20.glGenTextures(1, textures, 0)
+      textureId = textures[0]
+      GLES20.glBindTexture(GLES11Ext.GL_TEXTURE_EXTERNAL_OES, textureId)
+      GLES20.glTexParameterf(
+        GLES11Ext.GL_TEXTURE_EXTERNAL_OES,
+        GLES20.GL_TEXTURE_MIN_FILTER, GLES20.GL_LINEAR.toFloat()
+      )
+      GLES20.glTexParameterf(
+        GLES11Ext.GL_TEXTURE_EXTERNAL_OES,
+        GLES20.GL_TEXTURE_MAG_FILTER, GLES20.GL_LINEAR.toFloat()
+      )
+      GLES20.glTexParameteri(
+        GLES11Ext.GL_TEXTURE_EXTERNAL_OES,
+        GLES20.GL_TEXTURE_WRAP_S, GLES20.GL_CLAMP_TO_EDGE
+      )
+      GLES20.glTexParameteri(
+        GLES11Ext.GL_TEXTURE_EXTERNAL_OES,
+        GLES20.GL_TEXTURE_WRAP_T, GLES20.GL_CLAMP_TO_EDGE
+      )
+    }
+
+    fun drawFrame(st: SurfaceTexture) {
+      st.getTransformMatrix(stMatrix)
+      Matrix.setIdentityM(mvpMatrix, 0)
+      if (rotation != 0) {
+        Matrix.rotateM(mvpMatrix, 0, rotation.toFloat(), 0f, 0f, 1f)
+      }
+
+      // Apply the requested aspect-ratio crop as a NORMALISED-texture (u/v) scale on top of the
+      // SurfaceTexture's own orientation transform — NOT an MVP scale. Scaling only the longer
+      // axis about the centre trims exactly that axis, so the re-encoded frame is genuinely
+      // centre-cropped to the target aspect (a uniform MVP scale would magnify both axes equally
+      // and leave the frame's aspect unchanged). cropScaleX/cropScaleY are the fraction of the
+      // coded width/height axis that remains (the trimmed axis < 1, the untouched axis == 1).
+      if (cropScaleX < 1f || cropScaleY < 1f) {
+        val crop = FloatArray(16)
+        Matrix.setIdentityM(crop, 0)
+        // Centre the kept band: offset by half the trimmed margin on each trimmed axis, then
+        // scale about that offset (translate-then-scale → u' = 0.5 + (u - 0.5) * scaleX).
+        Matrix.translateM(crop, 0, 0.5f * (1f - cropScaleX), 0.5f * (1f - cropScaleY), 0f)
+        if (cropScaleX < 1f) Matrix.scaleM(crop, 0, cropScaleX, 1f, 1f)
+        if (cropScaleY < 1f) Matrix.scaleM(crop, 0, 1f, cropScaleY, 1f)
+        val combined = FloatArray(16)
+        // st * crop → the crop selects the central band first, then the SurfaceTexture's own
+        // transform maps that band to the buffer. Safe against aliasing via a temp array.
+        Matrix.multiplyMM(combined, 0, stMatrix, 0, crop, 0)
+        System.arraycopy(combined, 0, stMatrix, 0, 16)
+      }
+
+      GLES20.glClearColor(0f, 0f, 0f, 1f)
+      GLES20.glClear(GLES20.GL_COLOR_BUFFER_BIT)
+
+      GLES20.glUseProgram(program)
+
+      GLES20.glActiveTexture(GLES20.GL_TEXTURE0)
+      GLES20.glBindTexture(GLES11Ext.GL_TEXTURE_EXTERNAL_OES, textureId)
+
+      triangleVertices.position(TRIANGLE_VERTICES_DATA_POS_OFFSET)
+      GLES20.glVertexAttribPointer(
+        aPositionHandle, 3, GLES20.GL_FLOAT, false,
+        TRIANGLE_VERTICES_DATA_STRIDE_BYTES, triangleVertices
+      )
+      GLES20.glEnableVertexAttribArray(aPositionHandle)
+
+      triangleVertices.position(TRIANGLE_VERTICES_DATA_UV_OFFSET)
+      GLES20.glVertexAttribPointer(
+        aTextureHandle, 2, GLES20.GL_FLOAT, false,
+        TRIANGLE_VERTICES_DATA_STRIDE_BYTES, triangleVertices
+      )
+      GLES20.glEnableVertexAttribArray(aTextureHandle)
+
+      GLES20.glUniformMatrix4fv(uMVPMatrixHandle, 1, false, mvpMatrix, 0)
+      GLES20.glUniformMatrix4fv(uSTMatrixHandle, 1, false, stMatrix, 0)
+
+      GLES20.glDrawArrays(GLES20.GL_TRIANGLE_STRIP, 0, 4)
+      GLES20.glFinish()
+    }
+
+    private fun createProgram(vertexSource: String, fragmentSource: String): Int {
+      val vertex = loadShader(GLES20.GL_VERTEX_SHADER, vertexSource)
+      if (vertex == 0) return 0
+      val fragment = loadShader(GLES20.GL_FRAGMENT_SHADER, fragmentSource)
+      if (fragment == 0) return 0
+      var prog = GLES20.glCreateProgram()
+      if (prog == 0) return 0
+      GLES20.glAttachShader(prog, vertex)
+      GLES20.glAttachShader(prog, fragment)
+      GLES20.glLinkProgram(prog)
+      val linkStatus = IntArray(1)
+      GLES20.glGetProgramiv(prog, GLES20.GL_LINK_STATUS, linkStatus, 0)
+      if (linkStatus[0] != GLES20.GL_TRUE) {
+        GLES20.glDeleteProgram(prog)
+        prog = 0
+      }
+      return prog
+    }
+
+    private fun loadShader(shaderType: Int, source: String): Int {
+      var shader = GLES20.glCreateShader(shaderType)
+      if (shader == 0) return 0
+      GLES20.glShaderSource(shader, source)
+      GLES20.glCompileShader(shader)
+      val compiled = IntArray(1)
+      GLES20.glGetShaderiv(shader, GLES20.GL_COMPILE_STATUS, compiled, 0)
+      if (compiled[0] == 0) {
+        GLES20.glDeleteShader(shader)
+        shader = 0
+      }
+      return shader
+    }
+
+    companion object {
+      private const val FLOAT_SIZE_BYTES = 4
+      private const val TRIANGLE_VERTICES_DATA_STRIDE_BYTES = 5 * FLOAT_SIZE_BYTES
+      private const val TRIANGLE_VERTICES_DATA_POS_OFFSET = 0
+      private const val TRIANGLE_VERTICES_DATA_UV_OFFSET = 3
+    }
+  }
+}