@pictor-sdk/video-android 0.1.0

package/android/src/main/java/dev/pictor/video/Media3Player.kt

@@ -0,0 +1,934 @@
+package dev.pictor.video
+
+import android.content.Context
+import android.net.Uri
+import android.os.Handler
+import android.os.Looper
+import androidx.media3.common.AudioAttributes
+import androidx.media3.common.C
+import androidx.media3.common.MediaItem
+import androidx.media3.common.PlaybackException
+import androidx.media3.common.PlaybackParameters
+import androidx.media3.common.Player
+import androidx.media3.exoplayer.ExoPlayer
+import androidx.media3.exoplayer.video.VideoFrameMetadataListener
+
+/**
+ * Playback, by Media3.
+ *
+ * ExoPlayer owns decoding, buffering, audio focus, A/V synchronisation, seeking,
+ * speed and lifecycle. Pictor owns the document, the timeline and the Skia
+ * composition, and this class is only the translation between them.
+ *
+ * That division is the point of the change. The custom `MediaCodec`/`AudioTrack`
+ * backend reached one-frame synchronisation, and cost several slices on codec
+ * pacing, buffer ownership, async-flush races and a GL memory leak — none of
+ * which is Pictor's problem, and none of which accumulates the per-device
+ * workarounds ExoPlayer already carries.
+ *
+ * Video goes to the persistent `SurfaceTexture` from [VideoSurface], so the
+ * renderer keeps one external texture and one `SkImage` for the whole session.
+ *
+ * **No Media3 type leaves this class.** The module exposes numbers and strings;
+ * `ExoPlayer`, `MediaItem` and the rest stop here.
+ */
+internal class Media3Player private constructor(
+    private val player: ExoPlayer,
+    val widthHint: Int,
+    val heightHint: Int,
+) {
+    @Volatile
+    private var released = false
+
+    /** Everything ExoPlayer is touched from is its own application thread. */
+    private val main = Handler(Looper.getMainLooper())
+
+    /**
+     * Publishes the position anchor, on the player's thread.
+     *
+     * One re-posted Runnable, never a fresh lambda. 50 ms is far coarser than a
+     * frame and that is fine: consumers extrapolate between anchors rather than
+     * asking the player, which is what keeps the render path free of a thread
+     * hop.
+     */
+    private val anchorPump = object : Runnable {
+        override fun run() {
+            if (released) return
+            PlaybackAnchor.publish(
+                PlaybackAnchor.Sample(
+                    positionUs = player.currentPosition * 1000,
+                    monotonicNs = System.nanoTime(),
+                    rate = player.playbackParameters.speed,
+                    playing = player.isPlaying,
+                    buffering = player.playbackState == Player.STATE_BUFFERING,
+                    discontinuity = false,
+                    generation = FrameClock.generation,
+                    windowIndex = player.currentMediaItemIndex,
+                ),
+            )
+            // The coordinator runs from here rather than from a timer of its
+            // own: this pump already exists, already runs on the player's
+            // thread, and is the cadence everything else about position uses.
+            PreviewSync.tick(::holdTransport)
+            durationUs = if (player.duration == C.TIME_UNSET) 0L else player.duration * 1000
+            ended = player.playbackState == Player.STATE_ENDED
+            ready = player.playbackState == Player.STATE_READY
+            videoWidth = player.videoSize.width
+            videoHeight = player.videoSize.height
+            // Cached here, on the player's own thread. Reading it from state()
+            // throws "Player is accessed on the wrong thread" — state() is
+            // called from JS and must touch nothing but volatiles.
+            playbackState = player.playbackState
+            // The active format, for fault classification. Reported here rather
+            // than from state(): touching the player off its own thread throws.
+            val format = player.videoFormat
+            videoFormat = if (format == null) {
+                ""
+            } else {
+                "${format.sampleMimeType} ${format.width}x${format.height}" +
+                    " rot${format.rotationDegrees} @${format.frameRate}"
+            }
+            currentWindow = player.currentMediaItemIndex
+            FrameClock.windowIndex = currentWindow
+            windowPositionUs = player.currentPosition * 1000
+            windowCount = player.mediaItemCount
+            main.postDelayed(this, ANCHOR_INTERVAL_MS)
+        }
+    }
+
+    /** Called from the analytics listener on the player's thread. */
+    private fun decoderInitialised(name: String) {
+        decoderName = name
+        surfaceGeneration += 1
+    }
+
+    private fun startAnchor() {
+        main.post(anchorPump)
+    }
+
+    /**
+     * Report source failures. Registered on the player's thread after
+     * construction, because it writes this instance's fields.
+     *
+     * Without it a failed source is invisible: the player simply stops, and the
+     * state reads exactly like an idle player nobody asked to do anything. That
+     * is how a dead endpoint looked in the remote gate — behaviour that was
+     * correct and entirely unreported.
+     */
+    /**
+     * Take responsibility for attaching, for as long as this player exists.
+     *
+     * Registered when the player is built and cleared when it is released, so a
+     * surface created at any point — before this player, after it, or after a
+     * screen remount — reaches it without the host being involved.
+     */
+    private fun ownSurfaceAttachment() {
+        VideoSurface.onSurfaceLive = { attachSurface() }
+        attachSurface()
+    }
+
+    private fun attachErrorListener() {
+        main.post {
+            if (released) return@post
+            // Which decoder Media3 chose. Registered here, on the player's own
+            // thread and after construction, because it writes instance state —
+            // the companion cannot reach it.
+            player.addAnalyticsListener(
+                object : androidx.media3.exoplayer.analytics.AnalyticsListener {
+                    override fun onVideoDecoderInitialized(
+                        eventTime: androidx.media3.exoplayer.analytics.AnalyticsListener.EventTime,
+                        name: String,
+                        initializedTimestampMs: Long,
+                        initializationDurationMs: Long,
+                    ) {
+                        decoderInitialised(name)
+                    }
+
+                    /*
+                      The format the decoder is actually configured for, and the
+                      size it actually produces.
+
+                      Recorded from the player rather than inferred from the
+                      device: "a Pixel 7 uses the Exynos decoder" is a guess
+                      that happens to be checkable, and a guess that survives
+                      because nobody checked it is how the last three
+                      attributions in this area went wrong. A mixed-resolution
+                      seam is also the one moment these two can disagree.
+                    */
+                    override fun onVideoInputFormatChanged(
+                        eventTime: androidx.media3.exoplayer.analytics.AnalyticsListener.EventTime,
+                        format: androidx.media3.common.Format,
+                        decoderReuseEvaluation:
+                            androidx.media3.exoplayer.DecoderReuseEvaluation?,
+                    ) {
+                        inputFormats += 1
+                        inputWidth = format.width
+                        inputHeight = format.height
+                        inputRotation = format.rotationDegrees
+                        // Whether Media3 kept the codec across the seam or built
+                        // a new one. A reused codec that stops delivering and a
+                        // replaced one that never starts are different faults.
+                        decoderReuse = decoderReuseEvaluation?.result ?: -1
+                    }
+
+                    override fun onVideoSizeChanged(
+                        eventTime: androidx.media3.exoplayer.analytics.AnalyticsListener.EventTime,
+                        size: androidx.media3.common.VideoSize,
+                    ) {
+                        outputSizes += 1
+                        outputWidth = size.width
+                        outputHeight = size.height
+                    }
+                },
+            )
+            player.addListener(
+                object : Player.Listener {
+                    /**
+                     * A window change is a discontinuity for the frame clock.
+                     *
+                     * Frames queued for the outgoing clip must not be paired
+                     * with a position in the incoming one — that is a seam that
+                     * reports the wrong time for a few frames, which looks like
+                     * clock drift and is not.
+                     */
+                    /**
+                     * The picture and the mix are held together through a
+                     * stall, and released together when they agree.
+                     *
+                     * See [PreviewSync]. Pausing only the mix was tried first
+                     * and left a seam transient of about 200 ms, because the
+                     * picture resumed the moment its decoder was ready while
+                     * the mix was still moving.
+                     */
+                    override fun onPlaybackStateChanged(state: Int) {
+                        val buffering = state == Player.STATE_BUFFERING
+                        if (buffering == lastBufferingSeen) return
+                        lastBufferingSeen = buffering
+                        PreviewTrace.record("source.buffering") {
+                            org.json.JSONObject()
+                                .put("buffering", buffering)
+                                .put("presentedUs", PreviewSync.presentedUs() ?: -1)
+                                .put("decodedUs", PreviewSync.decodedUs(System.nanoTime()))
+                        }
+                        PreviewSync.onVideoBuffering(buffering, ::holdTransport)
+                    }
+
+                    override fun onMediaItemTransition(item: MediaItem?, reason: Int) {
+                        currentWindow = player.currentMediaItemIndex
+                        // Published for the frame clock in the same callback the
+                        // window actually changes in, so a frame offered after
+                        // the seam is tagged with the window it belongs to.
+                        FrameClock.windowIndex = currentWindow
+                        applyWindowSpeed(currentWindow)
+                        applyWindowMute(currentWindow)
+                        transitions += 1
+                    }
+
+                    /** Which decoder Media3 chose, and when it changed. */
+                    override fun onVideoSizeChanged(size: androidx.media3.common.VideoSize) {
+                        videoWidth = size.width
+                        videoHeight = size.height
+                    }
+
+                    override fun onPlayerError(error: PlaybackException) {
+                        errorCount += 1
+                        errorCode = error.errorCode
+                        errorMessage = "${error.errorCodeName}: ${error.message ?: ""}"
+                        // Media3's own classification, which is the only honest
+                        // basis for retrying: a network drop recovers, a
+                        // malformed container will fail identically forever.
+                        errorRecoverable =
+                            error.errorCode == PlaybackException.ERROR_CODE_IO_NETWORK_CONNECTION_FAILED ||
+                            error.errorCode == PlaybackException.ERROR_CODE_IO_NETWORK_CONNECTION_TIMEOUT ||
+                            error.errorCode == PlaybackException.ERROR_CODE_IO_BAD_HTTP_STATUS
+                    }
+                },
+            )
+        }
+    }
+
+    private fun onPlayer(block: ExoPlayer.() -> Unit) {
+        if (released) return
+        if (Looper.myLooper() == Looper.getMainLooper()) {
+            player.block()
+        } else {
+            main.post { if (!released) player.block() }
+        }
+    }
+
+    fun play() {
+        PreviewSync.onUserPlay()
+        // The dual-player preview shares the consumer, so it owns the same
+        // streaming flag: without it every frame would be paced against a
+        // schedule nobody set, or none would be paced at all.
+        FrameClock.setStreaming(true)
+        onPlayer {
+            // A hold may have taken the transport away; starting has to give it
+            // back or the press would do nothing.
+            transportHeld = false
+            play()
+        }
+    }
+
+    fun pause() {
+        PreviewSync.onUserStop("pause")
+        FrameClock.setStreaming(false)
+        onPlayer { pause() }
+    }
+
+    fun seekTo(positionUs: Long) {
+        // Before the seek, not after: frames already queued belong to the
+        // position being left, and pairing one with the new clip time would
+        // publish a position that never existed.
+        FrameClock.bump()
+        onPlayer { seekTo(positionUs / 1000) }
+    }
+
+    /**
+     * The user's preview rate, composed with whatever speed the clip carries.
+     *
+     * A 2x clip previewed at 0.5x plays at 1x. Overwriting the player's speed
+     * outright would silently discard the clip's own, which is part of the
+     * document and not a preview setting.
+     */
+    fun setRate(rate: Float) {
+        userRate = if (rate > 0f) rate else 1f
+        onPlayer {
+            applyWindowSpeed(currentMediaItemIndex)
+            applyWindowMute(currentMediaItemIndex)
+        }
+    }
+
+    /**
+     * A snapshot, for a throttled read. Never called per frame.
+     *
+     * Positions are microseconds, because that is Pictor's unit; Media3 works
+     * in milliseconds and the conversion belongs here rather than in JS.
+     */
+    /**
+     * A snapshot for a throttled read. **Never blocks.**
+     *
+     * Reads the anchor the player's own thread publishes rather than posting
+     * and waiting. The old version held a latch, which put a thread hop inside
+     * anything that called it — including the synchronisation measurement.
+     */
+    /**
+     * Every floating-point value the state carries, as a bridge-safe `Double`.
+     *
+     * `Map<String, Any>` boxes whatever it is given, and a Kotlin `Float` boxes
+     * to `java.lang.Float` — which the bridge does not convert. The field then
+     * arrives as `undefined` rather than as a wrong number, so a consumer that
+     * spreads defaults underneath still sees `undefined`, and the first
+     * `.toFixed` on it is fatal.
+     *
+     * Named so the conversion is a decision at the boundary rather than a
+     * `.toDouble()` remembered per call site — the two that were missing had one
+     * and did not survive, which is exactly the kind of thing an audit misses
+     * and a single funnel cannot.
+     */
+    private fun bridgeDouble(value: Float): Double = value.toDouble()
+
+    fun state(): Map<String, Any> {
+        if (released) return mapOf("released" to true)
+        val anchor = PlaybackAnchor.latest()
+        val counters = FrameClock.counters()
+        val granularity = PlaybackAnchor.granularity()
+        return mapOf(
+            "positionUs" to PlaybackAnchor.positionAt(System.nanoTime()),
+            "anchorPositionUs" to anchor.positionUs,
+            "durationUs" to durationUs,
+            "playing" to anchor.playing,
+            "buffering" to anchor.buffering,
+            "ended" to ended,
+            "ready" to ready,
+            "rate" to bridgeDouble(anchor.rate),
+            "width" to videoWidth,
+            "height" to videoHeight,
+            "generation" to counters[4],
+            "queueDepth" to FrameClock.depth(),
+            "overflowed" to counters[0],
+            "unpaired" to counters[1],
+            "stale" to counters[2],
+            "queueHighWater" to counters[3],
+            "threads" to threadCount(),
+            "nativeHeapBytes" to android.os.Debug.getNativeHeapAllocatedSize(),
+            "coalesced" to counters[5],
+            "anchorPublications" to granularity.publications,
+            "anchorChanges" to granularity.changes,
+            "anchorMaxStepUs" to granularity.maxStepUs,
+            "anchorMeanStepUs" to
+                (if (granularity.changes > 0) granularity.totalStepUs / granularity.changes else 0L),
+            "anchorMaxStaleNs" to granularity.maxStaleNs,
+            "windowIndex" to currentWindow,
+            "windowCount" to windowCount,
+            "windowPositionUs" to windowPositionUs,
+            "transitions" to transitions,
+            "missedLatches" to VideoSurface.missedLatches,
+            "updatesAttempted" to VideoSurface.updatesAttempted,
+            "updatesSucceeded" to VideoSurface.updatesSucceeded,
+            "updatesSkipped" to VideoSurface.updatesSkipped,
+            "updatesFailed" to VideoSurface.updatesFailed,
+            "framesOffered" to FrameClock.offered,
+            "framesAvailable" to FrameClock.available,
+            // The level, not the edge. `pendingDepth` is what a consumer that
+            // was disarmed when the frame arrived can still see.
+            "pendingDepth" to VideoSurface.pendingDepth,
+            "framesRejected" to VideoSurface.framesRejected,
+            "pendingGeneration" to VideoSurface.pendingGeneration,
+            "controllerId" to VideoSurface.controllerId.toLong(),
+            "pendingId" to VideoSurface.pendingId.toLong(),
+            "orphaned" to FrameClock.orphaned,
+            "seeksRequested" to seeksRequested,
+            "seeksAccepted" to seeksAccepted,
+            "pendingSeek" to pendingSeek,
+            "playbackState" to playbackState,
+            "videoFormat" to videoFormat,
+            "decoderName" to decoderName,
+            "inputFormats" to inputFormats,
+            "inputWidth" to inputWidth,
+            "inputHeight" to inputHeight,
+            "inputRotation" to inputRotation,
+            "decoderReuse" to decoderReuse,
+            "outputSizes" to outputSizes,
+            "outputWidth" to outputWidth,
+            "outputHeight" to outputHeight,
+            "surfaceGeneration" to surfaceGeneration,
+            "rateConstrained" to rateConstrained,
+            "requestedRate" to bridgeDouble(requestedRate),
+            "staleWindowSpeeds" to staleWindowSpeeds,
+            "windowSpeedCount" to (windowSpeeds?.size ?: 0).toLong(),
+            "effectiveRate" to bridgeDouble(
+                windowSpeeds?.getOrNull(currentWindow)?.times(userRate) ?: 1f,
+            ),
+            "surfaceAttachments" to VideoSurface.attachment.attachments.toLong(),
+            "attachedSurfaceGeneration" to VideoSurface.attachment.attached,
+            "liveSurfaceGeneration" to VideoSurface.attachment.live,
+            "lastPairedPtsUs" to (FrameClock.latestSample()?.get(FrameClock.Field.PTS_US) ?: -1L),
+            "errorCount" to errorCount,
+            "errorCode" to errorCode,
+            "errorMessage" to errorMessage,
+            "errorRecoverable" to errorRecoverable,
+            "released" to false,
+        )
+    }
+
+    /**
+     * Ask the player to try the source again.
+     *
+     * `prepare()` after an error is Media3's documented recovery: it re-resolves
+     * the source and resumes from the current position, so a network source that
+     * went away and came back needs nothing else. Recoverable errors are the
+     * only ones worth retrying — a malformed container will fail identically
+     * however many times it is asked — so callers decide, using [errorRecoverable].
+     */
+    fun retry() {
+        onPlayer {
+            clearError()
+            prepare()
+        }
+    }
+
+    /** A new attempt owns its own outcome; the previous failure is not it. */
+    private fun clearError() {
+        errorCode = 0
+        errorMessage = ""
+        errorRecoverable = false
+    }
+
+    // Written on the player's thread, read anywhere. Cheap fields the anchor
+    // does not carry.
+    @Volatile private var durationUs: Long = 0
+    @Volatile private var errorCode = 0
+    @Volatile private var errorMessage = ""
+    @Volatile private var errorRecoverable = false
+    @Volatile private var errorCount = 0L
+    @Volatile private var ended = false
+    @Volatile private var ready = false
+    @Volatile private var videoWidth = 0
+    @Volatile private var videoHeight = 0
+    @Volatile private var windowSpeeds: FloatArray? = null
+    /** The rate the user asked for, separate from the clip's own speed. */
+    @Volatile private var userRate = 1f
+    @Volatile private var currentWindow = 0
+    @Volatile private var windowPositionUs = 0L
+    @Volatile private var windowCount = 0
+    @Volatile private var transitions = 0L
+    private val mutedWindows = java.util.Collections.synchronizedSet(HashSet<Int>())
+
+    /**
+     * Silence every window, whatever the document says.
+     *
+     * Set while a mixed-audio preview is playing. The mix already contains the
+     * clips' own audio — it is compiled from the same program an export uses —
+     * so leaving the player audible would play the whole timeline twice, once
+     * mixed and once raw.
+     */
+    @Volatile private var sourceAudioMuted = false
+
+    /**
+     * Apply the mute for a window.
+     *
+     * `mutedWindows` was populated by [setPlaylist] and read by nothing, which
+     * meant a muted clip was silent in an export and audible in preview — the
+     * two disagreeing about the document, quietly. Applied here beside the
+     * speed, at the same three moments a window becomes current.
+     */
+    private fun applyWindowMute(windowIndex: Int) {
+        val silent = sourceAudioMuted || mutedWindows.contains(windowIndex)
+        val wanted = if (silent) 0f else 1f
+        if (player.volume != wanted) player.volume = wanted
+        publishedVolume = player.volume
+    }
+
+    /** Silence, or restore, the player's own audio. */
+    fun setSourceAudioMuted(muted: Boolean) {
+        sourceAudioMuted = muted
+        PreviewTrace.record("source.mute") { org.json.JSONObject().put("muted", muted) }
+        onPlayer { applyWindowMute(currentMediaItemIndex) }
+    }
+
+    /**
+     * The volume the source player is actually at.
+     *
+     * Published on every mute application rather than read on demand, because
+     * reading it needs the player's own thread and the trace samples from
+     * another one. A flag says what was asked for; this says what happened.
+     */
+    @Volatile private var publishedVolume: Float = 1f
+
+    /** Where each window begins on the project timeline. */
+    @Volatile private var windowTimelineStartUs: LongArray = LongArray(0)
+
+    /** The last buffering state seen, so a repeat is not acted on twice. */
+    @Volatile private var lastBufferingSeen = false
+
+    /**
+     * Whether the picture is held for a coordinated resume.
+     *
+     * `playWhenReady` is the transport, and a hold takes it away without
+     * touching what the person asked for — [PreviewSync] keeps that.
+     */
+    @Volatile private var transportHeld = false
+
+    /** Hold or release the picture's transport, on the player's own thread. */
+    private fun holdTransport(hold: Boolean) {
+        if (transportHeld == hold) return
+        transportHeld = hold
+        onPlayer { playWhenReady = !hold }
+    }
+
+    /** Window-local media time to project time, as `windowToProjectTime` does. */
+    internal fun speedFor(windowIndex: Int): Float {
+        val speeds = windowSpeeds ?: return -1f
+        return speeds.getOrNull(windowIndex)?.takeIf { it > 0f } ?: -1f
+    }
+
+    private fun globalFor(windowIndex: Int, localUs: Long): Long {
+        val starts = windowTimelineStartUs
+        val speeds = windowSpeeds
+        if (windowIndex < 0 || windowIndex >= starts.size) return localUs
+        val speed = speeds?.getOrNull(windowIndex)?.takeIf { it > 0f } ?: 1f
+        return starts[windowIndex] + Math.round(localUs / speed.toDouble())
+    }
+
+    /**
+     * Point the existing player at another source, without rebuilding it.
+     *
+     * `stop` + `clearMediaItems` + `setMediaItem` + `prepare` is the documented
+     * reuse path. Whether it actually resets session state, or accumulates,
+     * is the question heap attribution answers — so it exists to be measured,
+     * not because reuse is assumed better.
+     */
+    fun rebind(uriString: String) {
+        FrameClock.bump()
+        clearError()
+        val done = java.util.concurrent.CountDownLatch(1)
+        main.post {
+            runCatching {
+                player.stop()
+                player.clearMediaItems()
+                player.setMediaItem(MediaItem.fromUri(Uri.parse(uriString)))
+                player.prepare()
+            }
+            done.countDown()
+        }
+        done.await(RELEASE_TIMEOUT_MS, java.util.concurrent.TimeUnit.MILLISECONDS)
+    }
+
+    /**
+     * Replace the whole playlist, keeping the player, surface and texture.
+     *
+     * Two parallel arrays: the sources, and four numbers per entry — clipping
+     * start and end in microseconds, speed in milli-units, muted as 0/1. Flat,
+     * because this crosses the bridge and a map per clip would allocate a
+     * native-backed object per entry on every edit; the timeline can change on
+     * every frame of a trim drag.
+     *
+     * **The texture and the `SkImage` are untouched.** That is the whole point
+     * of a process-scoped presentation surface: reordering clips or deleting one
+     * is a playlist operation, not a reason to rebuild the GL objects the
+     * renderer holds.
+     *
+     * The generation bumps first, so frames already queued for the old playlist
+     * are rejected on arrival rather than paired with a time in the new one.
+     */
+    fun setPlaylist(
+        uris: List<String>,
+        bounds: DoubleArray,
+        startWindow: Int,
+        startPositionUs: Long,
+    ) {
+        FrameClock.bump()
+        clearError()
+        // Defensive only. Attachment happens when a surface becomes live; this
+        // is here so a playlist can never be loaded against a stale surface if
+        // that path is ever bypassed, not as the mechanism itself.
+        attachSurface()
+        val done = java.util.concurrent.CountDownLatch(1)
+        main.post {
+            runCatching {
+                val media = ArrayList<MediaItem>(uris.size)
+                val speeds = ArrayList<Float>(uris.size)
+                for ((index, uri) in uris.withIndex()) {
+                    val base = index * FIELDS_PER_ITEM
+                    val startUs = bounds[base].toLong()
+                    val endUs = bounds[base + 1].toLong()
+                    val speed = (bounds[base + 2] / 1000.0).toFloat()
+                    val muted = bounds[base + 3] != 0.0
+                    media.add(
+                        MediaItem.Builder()
+                            .setUri(Uri.parse(uri))
+                            .setClippingConfiguration(
+                                MediaItem.ClippingConfiguration.Builder()
+                                    // Media3 clips in milliseconds. The timeline is
+                                    // microseconds, so this is the one place the two
+                                    // units meet, and it rounds rather than truncates:
+                                    // truncation biases every trim earlier.
+                                    .setStartPositionMs((startUs + 500) / 1000)
+                                    .setEndPositionMs((endUs + 500) / 1000)
+                                    .build(),
+                            )
+                            .build(),
+                    )
+                    speeds.add(if (speed > 0f) speed else 1f)
+                    if (muted) mutedWindows.add(index) else mutedWindows.remove(index)
+                }
+                windowSpeeds = speeds.toFloatArray()
+                /*
+                  Where each window begins on the project timeline.
+
+                  `player.currentPosition` is position *within the current
+                  window*, so a consumer comparing it against a global time sees
+                  it reset at every seam — measured as a 9.8 s apparent offset
+                  when the trace first read it. The same cumulative sum
+                  `windowToProjectTime` performs in `@pictor-sdk/video-core`, kept
+                  here so a reader on another thread can convert without the
+                  project.
+                */
+                val starts = LongArray(speeds.size)
+                var at = 0L
+                for (i in speeds.indices) {
+                    starts[i] = at
+                    val base = i * 4
+                    val startUs = bounds[base].toLong()
+                    val endUs = bounds[base + 1].toLong()
+                    val speed = speeds[i]
+                    at += Math.round((endUs - startUs) / speed.toDouble())
+                }
+                windowTimelineStartUs = starts
+                player.setMediaItems(media, startWindow, startPositionUs / 1000)
+                applyWindowSpeed(startWindow)
+                applyWindowMute(startWindow)
+                player.prepare()
+            }
+            done.countDown()
+        }
+        done.await(RELEASE_TIMEOUT_MS, java.util.concurrent.TimeUnit.MILLISECONDS)
+    }
+
+    /**
+     * Per-window playback speed.
+     *
+     * ExoPlayer's speed is a property of the player, not of an item, so a
+     * timeline whose clips differ in speed has to change it as windows change.
+     * Applied on transition rather than continuously — setting it every tick
+     * would fight the user's own rate control.
+     */
+    private fun applyWindowSpeed(windowIndex: Int) {
+        val speeds = windowSpeeds
+        // No playlist, or an index the playlist does not have.
+        //
+        // Both used to `return`, which leaves `playbackParameters` at whatever
+        // was last set. A cleared playlist therefore kept the rate of the
+        // playlist before it, and an index past the end kept the rate of a
+        // window that no longer exists — a stale value that outlives the thing
+        // that justified it. Unity is the only honest rate for a player with
+        // nothing to play, and it is a value rather than an absence, so it
+        // cannot be confused with "leave it alone".
+        if (speeds == null || speeds.isEmpty()) {
+            resetRate()
+            return
+        }
+        val speed = speeds.getOrNull(windowIndex)
+        if (speed == null) {
+            staleWindowSpeeds += 1
+            resetRate()
+            return
+        }
+        val requested = speed * userRate
+        // Clamped to the same range `composeRate` uses in @pictor-sdk/video-core.
+        // The two must agree: if the player quietly refused a rate the timeline
+        // still counted at, the picture would advance at one speed while the
+        // playhead moved at another — a drift that reads as a broken clock and
+        // is really an unreported refusal. Counted so it is visible rather than
+        // inferred.
+        requestedRate = requested
+        val effective = requested.coerceIn(MIN_RATE, MAX_RATE)
+        if (effective != requested) rateConstrained += 1
+        if (player.playbackParameters.speed != effective) {
+            player.playbackParameters = PlaybackParameters(effective)
+        }
+    }
+
+    /**
+     * Put the player back to unity.
+     *
+     * Separate from `applyWindowSpeed` so "there is no rate to apply" is an
+     * action rather than a missing one. Never clamps, so it can never be the
+     * path that selects a ceiling.
+     */
+    private fun resetRate() {
+        if (player.playbackParameters.speed != 1f) {
+            player.playbackParameters = PlaybackParameters(1f)
+        }
+    }
+
+    /** Times a requested rate had to be clamped. Should stay zero in the UI. */
+    @Volatile private var rateConstrained = 0L
+
+    /**
+     * Times a window index had no speed.
+     *
+     * A playlist and a window index that disagree. Should stay zero; a non-zero
+     * value means the two were read at different moments.
+     */
+    @Volatile private var staleWindowSpeeds = 0L
+
+    /** The rate asked for before clamping, so a ceiling is distinguishable. */
+    @Volatile private var requestedRate = 1f
+
+    /**
+     * Point the player at the surface that is live now.
+     *
+     * Called by [VideoSurface] the instant a surface becomes live, so a host
+     * never has to remember it. Idempotent by generation: re-attaching an
+     * unchanged surface makes Media3 drop and rebuild its output, which costs
+     * frames at exactly the wrong moment.
+     */
+    private fun attachSurface() {
+        if (released || !VideoSurface.attachment.needsAttach()) return
+        val surface = VideoSurface.currentSurface() ?: return
+        val done = java.util.concurrent.CountDownLatch(1)
+        main.post {
+            runCatching {
+                if (!released && VideoSurface.attachment.attach()) {
+                    player.setVideoSurface(surface)
+                }
+            }
+            done.countDown()
+        }
+        done.await(RELEASE_TIMEOUT_MS, java.util.concurrent.TimeUnit.MILLISECONDS)
+    }
+
+    /** Seek by window and offset, the player's own coordinates. */
+    fun seekToWindow(windowIndex: Int, positionUs: Long) {
+        FrameClock.bump()
+        seeksRequested += 1
+        pendingSeek = true
+        onPlayer {
+            seekTo(windowIndex, positionUs / 1000)
+            // Cleared on the player's thread once the seek has been accepted,
+            // so a `pendingSeek` that stays true is a seek the player never
+            // acted on — which is what a freeze would look like from here.
+            pendingSeek = false
+            seeksAccepted += 1
+        }
+    }
+
+    /**
+     * Counters for the cross-window freeze soak.
+     *
+     * Deliberately cheap: three longs and a boolean, incremented on paths that
+     * already exist. A freeze that never reproduces still leaves these behind,
+     * so the next occurrence is diagnosable instead of anecdotal.
+     */
+    @Volatile private var seeksRequested = 0L
+    @Volatile private var seeksAccepted = 0L
+    @Volatile private var pendingSeek = false
+    @Volatile private var playbackState = 0
+    @Volatile private var videoFormat = ""
+    @Volatile private var decoderName = ""
+    @Volatile private var inputFormats = 0
+    @Volatile private var inputWidth = 0
+    @Volatile private var inputHeight = 0
+    @Volatile private var inputRotation = 0
+    @Volatile private var decoderReuse = -1
+    @Volatile private var outputSizes = 0
+    @Volatile private var outputWidth = 0
+    @Volatile private var outputHeight = 0
+    /** Bumped whenever a surface is attached, so re-attachment is visible. */
+    @Volatile private var surfaceGeneration = 0
+
+    /** End the source but keep the player, for the reuse configurations. */
+    fun stopKeepingPlayer() {
+        FrameClock.bump()
+        val done = java.util.concurrent.CountDownLatch(1)
+        main.post {
+            runCatching {
+                player.stop()
+                player.clearMediaItems()
+            }
+            done.countDown()
+        }
+        done.await(RELEASE_TIMEOUT_MS, java.util.concurrent.TimeUnit.MILLISECONDS)
+    }
+
+    /** Live thread count, for leak attribution. Diagnostics only. */
+    fun threadCount(): Int = Thread.getAllStackTraces().size
+
+    /** Explicit, on the player's own thread. Never from a finalizer. */
+    fun release() {
+        if (live === this) live = null
+        if (released) return
+        released = true
+        val latch = java.util.concurrent.CountDownLatch(1)
+        main.post {
+            // Listener off before the surface, surface before the player.
+            // Media3 takes a non-null listener, so a no-op replaces ours
+            // rather than clearing it — the player is about to go anyway, and
+            // this stops FrameClock being fed during teardown.
+            runCatching {
+                player.setVideoFrameMetadataListener { _, _, _, _ -> }
+            }
+            VideoSurface.onSurfaceLive = null
+            runCatching { player.setVideoSurface(null) }
+            runCatching { player.release() }
+            main.removeCallbacks(anchorPump)
+            FrameClock.bump()
+            PlaybackAnchor.reset()
+            latch.countDown()
+        }
+        latch.await(RELEASE_TIMEOUT_MS, java.util.concurrent.TimeUnit.MILLISECONDS)
+    }
+
+    companion object {
+        /**
+         * The live player's volume, or null when there is none.
+         *
+         * For the trace, which needs to prove that source audio is silent
+         * while a mix is playing — a mute flag says what was intended, and
+         * this says what the player is at.
+         */
+        fun currentVolumeOrNull(): Double? = live?.publishedVolume?.toDouble()
+
+        /**
+         * The project-timeline position for a window-local one.
+         *
+         * Returns the input unchanged when there is no playlist to convert
+         * against, which is the honest answer for a single-item player.
+         */
+        fun globalPositionUs(windowIndex: Int, localUs: Long): Long =
+            live?.globalFor(windowIndex, localUs) ?: localUs
+
+        /**
+         * The speed the local-to-global conversion is dividing by.
+         *
+         * Exposed for the trace: the conversion has two factors — the rate the
+         * player is running at and the speed this window is declared with — and
+         * a project clock advancing at the wrong rate cannot be attributed to
+         * one of them without seeing both.
+         */
+        fun windowSpeedFor(windowIndex: Int): Float = live?.speedFor(windowIndex) ?: -1f
+
+        /** The player the module is holding, for read-only diagnostics. */
+        @Volatile internal var live: Media3Player? = null
+
+        private const val RELEASE_TIMEOUT_MS = 2_000L
+
+        /** Clipping start, clipping end, speed, muted — per playlist entry. */
+        private const val FIELDS_PER_ITEM = 4
+
+        /** Mirrors MIN/MAX_PLAYBACK_RATE in @pictor-sdk/video-core. */
+        private const val MIN_RATE = 0.1f
+        private const val MAX_RATE = 10f
+
+        /**
+         * How often the position anchor is refreshed.
+         *
+         * Coarser than a frame on purpose: consumers extrapolate between
+         * anchors, so this only bounds drift, and a tighter interval would buy
+         * nothing but wake-ups.
+         */
+        private const val ANCHOR_INTERVAL_MS = 50L
+
+        /**
+         * Build a player rendering into the registered presentation surface.
+         *
+         * The surface has to exist first: it is created on the UI runtime,
+         * where Skia's GL context lives, and only then handed here.
+         */
+        fun create(
+            context: Context,
+            uriString: String,
+            /** Configuration 1 of heap attribution: a player with no output. */
+            attachSurface: Boolean = true,
+        ): Media3Player {
+            val surface = if (attachSurface) {
+                VideoSurface.currentSurface()
+                    ?: throw IllegalStateException(
+                        "no presentation surface: create the external texture before preparing",
+                    )
+            } else {
+                null
+            }
+            // A new source invalidates every queued frame.
+            FrameClock.bump()
+            val built = java.util.concurrent.CompletableFuture<ExoPlayer>()
+            Handler(Looper.getMainLooper()).post {
+                val player = ExoPlayer.Builder(context).build()
+                player.setAudioAttributes(
+                    AudioAttributes.Builder()
+                        .setUsage(C.USAGE_MEDIA)
+                        .setContentType(C.AUDIO_CONTENT_TYPE_MOVIE)
+                        .build(),
+                    // Media3 handles audio focus, which the custom backend
+                    // never did.
+                    true,
+                )
+                // The clip's presentation time only exists here. It is paired
+                // with the renderer's frames positionally, which holds because
+                // this fires immediately before each frame is released to the
+                // surface and `onFrameAvailable` follows in the same order.
+                player.setVideoFrameMetadataListener(
+                    VideoFrameMetadataListener { presentationTimeUs, releaseTimeNs, _, _ ->
+                        FrameClock.offer(presentationTimeUs, releaseTimeNs)
+                    },
+                )
+                if (surface != null) player.setVideoSurface(surface)
+                player.setMediaItem(MediaItem.fromUri(Uri.parse(uriString)))
+                player.prepare()
+                built.complete(player)
+            }
+            val player = built.get(5, java.util.concurrent.TimeUnit.SECONDS)
+            return Media3Player(player, 0, 0).also {
+                it.startAnchor()
+                it.attachErrorListener()
+                it.ownSurfaceAttachment()
+                // Held for read-only diagnostics: the trace has to be able to
+                // ask what volume the source player is actually at, and it
+                // samples from a thread that has no reference to it.
+                live = it
+            }
+        }
+    }
+}