@pictor-sdk/video-android 0.1.0

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

@@ -0,0 +1,978 @@
+package dev.pictor.video
+
+import android.content.Context
+import android.os.Handler
+import android.os.Looper
+import androidx.media3.common.MediaItem
+import androidx.media3.common.Player
+import androidx.media3.common.audio.SpeedProvider
+import androidx.media3.common.util.Size
+import androidx.media3.transformer.Composition
+import androidx.media3.transformer.CompositionPlayer
+import androidx.media3.transformer.EditedMediaItem
+import androidx.media3.transformer.EditedMediaItemSequence
+import androidx.media3.transformer.Effects
+import org.json.JSONArray
+import org.json.JSONObject
+
+/**
+ * One playback clock for the picture and the prepared mix.
+ *
+ * ## Why this exists
+ *
+ * The two-player preview cannot meet the 60 ms gate. Attribution said why, and
+ * none of it is tuneable: the two transports are compared through anchors
+ * polled at 50 ms, so a single observation carries up to ±56 ms of uncertainty
+ * against a 60 ms tolerance; the correction loop runs at 500 ms and each
+ * corrective seek costs 200-400 ms, so the loop's own latency exceeds what it
+ * is holding; and at a seam the project clock divides the local position by a
+ * speed the player has not applied for about 450 ms.
+ *
+ * ## The contract that makes this possible
+ *
+ * Verified against media3 1.9.4 as installed, not against a summary of it:
+ *
+ * - `Renderer.render(positionUs, ...)` takes **renderer time** — "a
+ *   continuously increasing value across all input sample streams" — so a
+ *   project-wide audio stream has a coherent axis to sit on.
+ * - `DefaultMediaClock` allows exactly one renderer to provide the clock
+ *   ("Multiple renderer media clocks enabled" is an error), and
+ *   `setPlaybackParameters` asks that clock first and takes back whatever it
+ *   accepts. So the clock owner really is authoritative, and a clip's speed
+ *   cannot be expressed as a global `PlaybackParameters` without dragging the
+ *   mix along with it.
+ * - Therefore the per-clip speed has to live in the *source* mapping, not in
+ *   the clock. `Effects.createExperimentalSpeedChangingEffect` returns exactly
+ *   that pair — an audio processor and a video timestamp adjustment — and
+ *   `CompositionPlayer` is documented to accept speed effects only from it.
+ *
+ * `CompositionPlayer` builds one `ExoPlayer` per sequence but hands them a
+ * single `Clock`, one playback thread, and one `PlaybackAudioGraphWrapper` that
+ * mixes every sequence into one sink. That is the difference from the current
+ * design: not "two clocks compared often" but one clock, with the picture timed
+ * against the audio that is actually being played.
+ *
+ * ## What this deliberately is not
+ *
+ * A spike, behind [Diagnostics]. It does not replace the preview, it does not
+ * touch preparation or export, and it claims nothing about live PCM gain or
+ * fades — those are a separate capability and the mix it plays is the same
+ * prepared file the current preview uses.
+ *
+ * Every timing value comes from the shared compiler: the host passes
+ * `playlistOf()`'s items verbatim and this maps them onto media items. There is
+ * no second interpretation of the project here, which is the invariant that
+ * made the relaxation in the first place tolerable.
+ */
+/*
+  The preview's transport, and no longer only a spike.
+
+  Built as one, measured as one, and accepted for v1 by watching it: the object
+  keeps its name because the native bridge method names are generated from the
+  TurboModule spec and renaming them is churn without a reader — the editor
+  reaches this through `useCompositionPlayback` and never sees the word. The
+  rename is a tracked follow-up.
+
+  Transport and ownership — `start`, `claim`, `play`, `pause`, `seek`,
+  `release` — are production paths and are no longer gated on diagnostics. The
+  measurement surface still is: `drain` returns nothing without diagnostics,
+  because a release build has no reason to retain per-frame samples.
+*/
+internal object CompositionSpike {
+
+    /** A constant speed for one clip. The compiler decided it; this carries it. */
+    private class ConstantSpeed(private val speed: Float) : SpeedProvider {
+        override fun getSpeed(timeUs: Long): Float = speed
+
+        /*
+          No further changes: a clip's speed is constant across the clip.
+
+          `C.TIME_UNSET` and not `Long.MIN_VALUE` — they differ by one and the
+          difference is not cosmetic. `SpeedProviderUtil` walks the speed
+          changes to compute the item's presentation duration, and
+          `Long.MIN_VALUE` failed its `checkState` with a bare
+          `IllegalStateException` naming nothing.
+        */
+        override fun getNextSpeedChangeTimeUs(timeUs: Long): Long =
+            androidx.media3.common.C.TIME_UNSET
+    }
+
+    private val main = Handler(Looper.getMainLooper())
+
+    @Volatile private var player: CompositionPlayer? = null
+    @Volatile private var lastError: String? = null
+    @Volatile private var startedAtNs = 0L
+    @Volatile private var readyAtNs = 0L
+    @Volatile private var seekStartedNs = 0L
+    @Volatile private var seekReadyNs = 0L
+
+    /**
+     * One reading of both clocks, taken together on the player's own thread.
+     *
+     * `CompositionPlayer` must be accessed from a single application thread —
+     * reading its position from the JS thread throws "Player is accessed on the
+     * wrong thread" — so the pairing is made here and published as a snapshot.
+     *
+     * This is polling, and it is not the polling the old design failed on.
+     * There, two independently-pumped anchors were subtracted, so the error was
+     * the sum of two staleness windows and could reach ±56 ms. Here both values
+     * are read in the same statement on the same thread, so the *pairing* is
+     * exact; the interval only affects how fresh the answer is, and the frame's
+     * own age is carried so a stale one can be excluded rather than averaged.
+     */
+    /**
+     * Which presentation boundary this measures.
+     *
+     * Three are observable in-process and they are not the same instant:
+     *
+     * - `METADATA_NS`  Media3 says a frame is about to be rendered.
+     * - `RELEASE_NS`   the time it *asks* the surface to present at. An
+     *                  intention, not an acknowledgement.
+     * - `CONSUMED_NS`  the consumer called `updateTexImage` and latched it.
+     *
+     * The offset is computed from `CONSUMED_NS`, because it is the latest
+     * boundary this process can witness rather than request. Actual scanout is
+     * one compositor pass later and is **not observed** here: there is no
+     * present fence or `onFrameCommit` in this path, so nothing in these
+     * numbers proves when the panel lit up. `RELEASE_NS` is retained beside it
+     * so the gap between intended and latched is visible rather than assumed
+     * to be zero.
+     */
+    private class Pairing(
+        val atNs: Long,
+        val positionUs: Long,
+        val playing: Boolean,
+        val playbackState: Int,
+        val durationUs: Long,
+        val presentedUs: Long,
+        val presentedAgeNs: Long,
+        /** How long the read itself took, which bounds the pairing error. */
+        val readSpanNs: Long,
+    )
+
+    @Volatile private var pairing: Pairing? = null
+
+    /**
+     * A transition epoch, bumped by start and every seek.
+     *
+     * A frame carried over from before a seek is not a late frame, it is a
+     * frame about a position nobody is at. Pairing one with the clock after the
+     * seek produces an excursion the size of the seek, and no amount of
+     * averaging tells that apart from a real one.
+     */
+    @Volatile private var epoch = 0L
+    @Volatile private var epochAtNs = 0L
+
+    /**
+     * The newest preparation anybody has claimed.
+     *
+     * A preparation that finishes after a newer one was asked for describes a
+     * document that no longer exists. Refusing it here, at the moment of
+     * attachment, is the only place that can be certain: the host cannot know
+     * whether a promise it is still holding was overtaken, and a mix that
+     * attaches for a beat before being replaced is a beat of the wrong sound.
+     */
+    private val claimed = java.util.concurrent.atomic.AtomicLong(0)
+
+    /** Claim the next request id. The host does this before it starts preparing. */
+    fun claim(): String {
+        return JSONObject().put("ok", true).put("requestId", claimed.incrementAndGet()).toString()
+    }
+
+    /** Attachments refused because a newer request had already been claimed. */
+    @Volatile var superseded = 0L
+        private set
+
+    /*
+      Playback readiness, as transport behaviour rather than as a label.
+
+      Marking an interval "preparing" in a report while the audio keeps playing
+      describes the defect instead of fixing it. So the transport is actually
+      held: `intentPlaying` is what the person asked for, and the player is only
+      started once a frame belonging to the current epoch has been latched.
+
+      The decoder still runs while the hold is on — the player is paused, not
+      stopped, and Media3 renders the first frame after a seek even when it is
+      not playing. That is what keeps this from deadlocking: the condition the
+      hold waits for is produced by work the hold does not prevent.
+    */
+    @Volatile var intentPlaying = false
+        private set
+
+    @Volatile private var releasePending = false
+    @Volatile private var releaseArmedNs = 0L
+    /** Where this epoch is meant to be, in composition time. */
+    @Volatile private var epochTargetUs = 0L
+    @Volatile private var releasedAtNs = 0L
+    @Volatile private var readinessFailure: String? = null
+
+    /** Holds that ended in a release, and holds that timed out. */
+    @Volatile var releases = 0L
+        private set
+
+    @Volatile var readinessTimeouts = 0L
+        private set
+
+    /** How long a hold may wait before it is reported as a failure. */
+    private const val READINESS_TIMEOUT_NS = 3_000_000_000L
+
+    /**
+     * The clip boundaries, in composition time, and the hold that covers them.
+     *
+     * ## Why a hold at all
+     *
+     * Measured on a Pixel 7: at each boundary the video decoder is released and
+     * a new one allocated and initialised — 126 ms from `videoDecoderReleased`
+     * at mediaPos 9.90 to `videoDecoderInitialized` at 10.02 — and nothing
+     * reaches the renderer's output for 119 to 168 ms. `videoPrewarmingEnabled`
+     * is on by default, `createSecondaryRenderer` is gated on it, the internal
+     * ExoPlayer enables dynamic scheduling, and two decoders are created at
+     * startup, so prewarming is configured and running. It still does not carry
+     * this boundary, and the boundary has no format excuse: the two clips are
+     * both H.264 High, 1080x1920, yuv420p, level 40, 30 fps.
+     *
+     * So the clock waits instead of the picture falling behind it. **This is a
+     * playback pause, not seamless playback**, and its wall-clock duration is
+     * reported separately from synchronisation for exactly that reason.
+     *
+     * ## Armed before the boundary, not after it
+     *
+     * Noticing the missing frame afterwards is the reactive delay this
+     * replaces. The hold arms when the position crosses `seam - SEAM_ARM_LEAD`,
+     * which pauses the shared clock while the player goes on preparing.
+     */
+    @Volatile private var seamTargetsUs: LongArray = LongArray(0)
+
+    /**
+     * Off, because the hold does not work on this player.
+     *
+     * Measured twice, at both arming positions. Pausing at `seam - 250 ms` and
+     * pausing exactly on the boundary both ran to the 2 s bound and reported a
+     * timeout: with `playWhenReady` false `CompositionPlayer` does not advance
+     * across an item boundary, so the incoming frame the hold waits for is
+     * never produced. Holding the clock and waiting for the new stream are
+     * mutually exclusive here.
+     *
+     * The mechanism is kept, disabled, with its bound and its cancellation
+     * intact — the negative result is worth more than the deleted code. Set
+     * `"seamHold": true` in the spec to run it.
+     *
+     * **Diagnostics only, and not a candidate for production.** Both variants
+     * were measured and neither meets the gate: pausing alone deadlocks, and
+     * the seek variant prepares but leaves the run worse than doing nothing.
+     * It is preserved as evidence of what was tried, not as an alternative
+     * waiting for a different player.
+     */
+    @Volatile private var seamHoldEnabled = false
+
+    /**
+     * Prepare the incoming item with an explicit seek, rather than only pausing.
+     *
+     * Pausing natural traversal and explicitly preparing a seek target are not
+     * the same operation. `CompositionPlayer.handleSeek` calls
+     * `CompositionPlayerInternal.startSeek`, then `ExoPlayer.seekTo` on each
+     * sequence, then resets the packet release control and releases the
+     * aggregator's frames before `endSeek` — and `ExoPlayer.seekTo` resets the
+     * renderers' positions, which is the path that makes a paused seek produce
+     * a frame. It is the same path the existing seek readiness already uses and
+     * passes on.
+     *
+     * So the seam is held by seeking to the incoming item's own compiled start,
+     * which is where the clock already is: no timeline time is skipped, and the
+     * retained picture keeps the outgoing frame on screen while it happens.
+     *
+     * It works, and it is worse. Measured over both boundaries: two holds of
+     * 241 ms and 180 ms, no timeouts, released on verified incoming frames — so
+     * paused preparation is real. But the boundary's output gap grew from 156
+     * and 119 ms to 330 and 262 ms, the seek itself triggering further decoder
+     * initialisations, and the submission gate went from one excursion at 67 ms
+     * to two at 208.6 ms. The hold covers less of the gap than it adds.
+     */
+    @Volatile private var seamSeekEnabled = false
+
+    /** Seams already held for, so a hold arms once per boundary per pass. */
+    private val seamsHeld = java.util.concurrent.ConcurrentHashMap<Long, Boolean>()
+
+    @Volatile private var seamHoldTargetUs = -1L
+    @Volatile private var seamHoldStartedNs = 0L
+
+    /**
+     * The boundary this pass has committed to holding at, before reaching it.
+     *
+     * Two phases, because one does not work. Pausing at `seam - lead` was tried
+     * and deadlocked: with the clock stopped short of the boundary the player
+     * never crosses it, so the frame the hold is waiting for is never produced,
+     * and the hold ran to its 2 s bound and reported a timeout — which is the
+     * bound doing its job, and a negative result.
+     *
+     * So the decision is made early and the pause lands on the boundary. The
+     * transition starts, the decoder is torn down and rebuilt, and what waits
+     * is the clock rather than the picture's place in it.
+     */
+    @Volatile private var seamArmedUs = -1L
+
+    /** Completed holds, as wall-clock milliseconds. Reported, never averaged in. */
+    private val seamHoldMs = java.util.concurrent.CopyOnWriteArrayList<Long>()
+
+    @Volatile var seamHoldTimeouts = 0L
+        private set
+
+    /**
+     * How far before a boundary the hold arms.
+     *
+     * Longer than the measured 168 ms worst gap, so the pause begins before the
+     * preparation it is covering rather than inside it.
+     */
+    private const val SEAM_ARM_LEAD_US = 250_000L
+
+    /** A hold that has not resolved by here is reported, never released blind. */
+    private const val SEAM_HOLD_TIMEOUT_NS = 2_000_000_000L
+
+    /** Declare the boundaries this composition will cross. */
+    fun setSeamTargets(targets: LongArray) {
+        seamTargetsUs = targets
+        seamsHeld.clear()
+        seamHoldTargetUs = -1
+        seamArmedUs = -1
+        seamHoldMs.clear()
+    }
+
+    /** Drop any hold in flight. Pause, seek, background and teardown all do. */
+    private fun cancelSeamHold() {
+        seamHoldTargetUs = -1
+        seamArmedUs = -1
+    }
+
+    /**
+     * Arm a hold for the epoch that just began.
+     *
+     * Start and seek both enter preparing. The intent is untouched: a hold is
+     * about *when* playback may run, never about whether the person asked for
+     * it.
+     */
+    private fun armRelease(targetUs: Long) {
+        // Preparing is not streaming: the first frame for this position has to
+        // be latched as soon as it exists, not paced against a schedule that
+        // belongs to the position being left.
+        FrameClock.setStreaming(false)
+        releasePending = true
+        epochTargetUs = targetUs
+        releaseArmedNs = System.nanoTime()
+        releasedAtNs = 0
+        readinessFailure = null
+    }
+
+    /**
+     * Whether a frame for the current epoch has actually been latched.
+     *
+     * Three things, not one. The frame must belong to this epoch — latched at
+     * or after the epoch began — it must carry a usable project timestamp, and
+     * it must have been latched rather than merely offered: `CONSUMED_NS` is
+     * set by the consumer after `updateTexImage` returned a new timestamp.
+     */
+    private fun firstFrameReady(): Boolean {
+        val frame = FrameClock.latestSample() ?: return false
+        // Latched, not merely offered: the consumer sets this after
+        // `updateTexImage` returned a new timestamp.
+        if (frame[FrameClock.Field.CONSUMED_NS] <= 0L) return false
+        /*
+          The pixels and the timestamp must be the same frame.
+
+          Readiness releases transport on the claim "this frame is the one we
+          asked for", and a fallback pairing cannot support it: the timestamp is
+          the claimed metadata and the pixels are whatever was latched. Starting
+          on one is how playback showed frame 7 at frame 2's instant.
+        */
+        if (frame[FrameClock.Field.ASSOCIATION] != 1L) return false
+        val pts = frame[FrameClock.Field.PTS_US]
+        if (pts < 0L) return false
+        /*
+          Matched by position, not by arrival order.
+
+          Requiring a frame latched *after* the button press deadlocked at
+          startup: the player renders its first frame when it becomes ready,
+          which is before anyone presses play, so the condition could never be
+          met and three of four transitions timed out at 3 s. What the gate
+          actually needs is a frame showing *this* epoch's position — the same
+          test for a start, a seek and a resume.
+        */
+        /*
+          A seam hold wants the frame *after* the boundary, exactly.
+
+          The ordinary backward tolerance exists because a seek lands on the
+          preceding sample. At a seam the target is an exact known boundary, and
+          the outgoing clip's last frame sits one interval before it — inside
+          that tolerance. Releasing on it would end the hold on the picture the
+          hold exists to move past.
+        */
+        if (seamHoldTargetUs >= 0) return pts >= seamHoldTargetUs
+
+        return pts >= epochTargetUs - FRAME_MATCH_BACK_US &&
+            pts <= epochTargetUs + FRAME_MATCH_AHEAD_US
+    }
+
+    /**
+     * How far a frame may sit from the epoch's target and still be its first.
+     *
+     * Backwards by about a frame, because a seek lands on the preceding
+     * keyframe-derived sample; forwards by a second, because the first frame
+     * after a seek into a long GOP can legitimately be later than asked for.
+     */
+    private const val FRAME_MATCH_BACK_US = 40_000L
+    private const val FRAME_MATCH_AHEAD_US = 1_000_000L
+
+    /** Retained evidence, so an excursion can be looked at rather than inferred. */
+    private const val RING = 8192
+    private val ring = arrayOfNulls<LongArray>(RING)
+    private val written = java.util.concurrent.atomic.AtomicLong(0)
+
+    /** One retained sample. Packed: a gate reads thousands of these. */
+    private fun record(p: Pairing, frame: LongArray?, pipeline: LongArray) {
+        val seq = written.getAndIncrement()
+        val row = LongArray(19)
+        row[0] = seq
+        row[1] = p.atNs
+        row[2] = p.positionUs
+        row[3] = (if (p.playing) 1L else 0L) or (if (p.playbackState == Player.STATE_READY) 2L else 0L)
+        row[4] = epoch
+        row[5] = p.atNs - epochAtNs
+        row[6] = frame?.get(FrameClock.Field.ID) ?: -1
+        row[7] = frame?.get(FrameClock.Field.GENERATION) ?: -1
+        row[8] = frame?.get(FrameClock.Field.WINDOW_INDEX) ?: -1
+        row[9] = frame?.get(FrameClock.Field.PTS_US) ?: -1
+        row[10] = frame?.get(FrameClock.Field.RELEASE_NS) ?: -1
+        row[11] = frame?.get(FrameClock.Field.CONSUMED_NS) ?: -1
+        row[12] = frame?.get(FrameClock.Field.AVAILABLE_NS) ?: -1
+        row[13] = frame?.get(FrameClock.Field.COALESCED) ?: -1
+        row[14] = pipeline[0]
+        row[15] = pipeline[1]
+        row[16] = pipeline[2]
+        row[17] = p.readSpanNs
+        /*
+          The earliest boundary, and the one that decides the seam.
+
+          `METADATA_NS` is when Media3's renderer said a frame was about to go
+          to the surface. A gap that ends here produced nothing at all — the
+          decoder or the item's preparation. A gap between here and
+          `AVAILABLE_NS` is the video graph queueing it. Between `AVAILABLE_NS`
+          and `CONSUMED_NS` is this consumer. Three different owners, and
+          without this stamp the first two are one interval.
+        */
+        row[18] = frame?.get(FrameClock.Field.METADATA_NS) ?: -1
+        ring[(seq % RING).toInt()] = row
+    }
+
+    /** Retained samples from [fromSeq]. @return `{ok, rows, nextSeq, total, dropped}` */
+    fun drain(fromSeq: Long, limit: Int): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        val total = written.get()
+        val oldest = maxOf(0L, total - RING)
+        // A gap is reported, never closed silently: a window that quietly lost
+        // its middle reads exactly like one that had nothing there.
+        val dropped = maxOf(0L, oldest - fromSeq)
+        var seq = maxOf(fromSeq, oldest)
+        val out = JSONArray()
+        while (seq < total && out.length() < limit) {
+            ring[(seq % RING).toInt()]?.let { row ->
+                if (row[0] == seq) out.put(JSONArray().also { a -> row.forEach { a.put(it) } })
+            }
+            seq += 1
+        }
+        return JSONObject()
+            .put("ok", true).put("rows", out).put("nextSeq", seq)
+            .put("total", total).put("dropped", dropped)
+            .toString()
+    }
+
+    private val pump = object : Runnable {
+        override fun run() {
+            val p = player ?: return
+            /*
+              The release decision runs here, on the player's own thread.
+
+              Same place the clocks are read, so the condition and the action
+              cannot be separated by a thread hop — and a newer seek that
+              re-arms between them would be acting on a hold that no longer
+              exists.
+            */
+            /*
+              Arm the seam hold before the boundary, on the player's own thread.
+
+              Same thread that reads the clock and issues the transport call, so
+              the crossing and the pause cannot be separated by a hop. A hold
+              already in flight, or a transport the person has paused, arms
+              nothing.
+            */
+            if (seamHoldEnabled && seamHoldTargetUs < 0 && releasePending.not() && intentPlaying && p.isPlaying) {
+                val positionUs = p.currentPosition * 1000
+                if (seamArmedUs < 0) {
+                    for (seam in seamTargetsUs) {
+                        if (seamsHeld.containsKey(seam)) continue
+                        if (positionUs < seam - SEAM_ARM_LEAD_US || positionUs >= seam) continue
+                        seamsHeld[seam] = true
+                        seamArmedUs = seam
+                        PreviewTrace.record("spike.seamArm") {
+                            JSONObject().put("seamUs", seam).put("atUs", positionUs)
+                        }
+                        break
+                    }
+                }
+                if (seamArmedUs >= 0 && positionUs >= seamArmedUs) {
+                    /*
+                      On the boundary, not before it. The clock stops here and
+                      the outgoing picture stays on screen because nothing
+                      replaces it; the transition is already under way.
+                    */
+                    seamHoldTargetUs = seamArmedUs
+                    seamHoldStartedNs = System.nanoTime()
+                    seamArmedUs = -1
+                    runCatching { p.pause() }
+                    armRelease(seamHoldTargetUs)
+                    if (seamSeekEnabled) {
+                        /*
+                          The same seek the readiness gate already survives, to
+                          the position the clock is already at. Frames in flight
+                          belong to the outgoing item, so the epoch moves with
+                          it; the picture on screen is the ring's retained one
+                          and is not disturbed.
+                        */
+                        epoch += 1
+                        epochAtNs = System.nanoTime()
+                        FrameClock.bump()
+                        runCatching { p.seekTo(seamHoldTargetUs / 1000) }
+                    }
+                    PreviewTrace.record("spike.seamHold") {
+                        JSONObject().put("seamUs", seamHoldTargetUs).put("atUs", positionUs)
+                    }
+                }
+            }
+            if (releasePending && intentPlaying) {
+                val waitedNs = System.nanoTime() - releaseArmedNs
+                val holding = seamHoldTargetUs >= 0
+                val limitNs = if (holding) SEAM_HOLD_TIMEOUT_NS else READINESS_TIMEOUT_NS
+                if (firstFrameReady()) {
+                    if (holding) {
+                        seamHoldMs.add((System.nanoTime() - seamHoldStartedNs) / 1_000_000)
+                        seamHoldTargetUs = -1
+                    }
+                    releasePending = false
+                    releasedAtNs = System.nanoTime()
+                    releases += 1
+                    // Playback is continuous from here, across seams included.
+                    FrameClock.setStreaming(true)
+                    // Retention makes enforcement affordable: the acquisition is
+                    // never deferred, so honouring the schedule no longer costs
+                    // a frame per wait.
+                    FrameClock.enforcePresentationSchedule = true
+                    PreviewTrace.record("spike.release") {
+                        JSONObject().put("waitedMs", waitedNs / 1_000_000)
+                    }
+                    runCatching { p.play() }
+                } else if (waitedNs > limitNs) {
+                    if (holding) {
+                        /*
+                          A hold that never resolves is a defect, and resuming
+                          blind would hide it behind the excursion it causes.
+                          Reported, and the transport is left for the person to
+                          restart rather than started on an unverified frame.
+                        */
+                        seamHoldTimeouts += 1
+                        seamHoldMs.add((System.nanoTime() - seamHoldStartedNs) / 1_000_000)
+                        seamHoldTargetUs = -1
+                    }
+                    // Bounded, and reported rather than released blind: a hold
+                    // that never resolves is a defect, and starting anyway
+                    // would hide it behind the excursion it causes.
+                    releasePending = false
+                    readinessTimeouts += 1
+                    readinessFailure = "no first frame within ${waitedNs / 1_000_000} ms"
+                    PreviewTrace.record("spike.readinessTimeout") {
+                        JSONObject().put("waitedMs", waitedNs / 1_000_000)
+                    }
+                }
+            }
+            val before = System.nanoTime()
+            val position = p.currentPosition * 1000
+            val playing = p.isPlaying
+            val playbackState = p.playbackState
+            val duration = p.duration * 1000
+            val frame = FrameClock.latestSample()
+            val pipeline = FrameClock.pipeline()
+            val after = System.nanoTime()
+            val paired = Pairing(
+                atNs = after,
+                positionUs = position,
+                playing = playing,
+                playbackState = playbackState,
+                durationUs = duration,
+                presentedUs = frame?.get(FrameClock.Field.PTS_US) ?: -1,
+                /*
+                  Aged from the *scheduled release*, not from the metadata callback.
+
+                  `offer` is recorded when Media3 says a frame is about to be
+                  rendered; the frame is actually presented at the release time
+                  it hands the surface, which was measured at about 40 ms later.
+                  Ageing from the callback overstates it by that much, and the
+                  overstatement lands directly on the offset as a constant bias.
+                */
+                /*
+                  Aged from the latch, the last boundary this process witnesses.
+
+                  Not from `RELEASE_NS`: that is the time Media3 *asked* the
+                  surface to present at, and an intended time is not an
+                  acknowledgement. Both are retained, so the difference between
+                  what was asked for and what was latched is measurable instead
+                  of assumed away.
+                */
+                presentedAgeNs =
+                    if (frame == null) -1 else after - frame[FrameClock.Field.CONSUMED_NS],
+                readSpanNs = after - before,
+            )
+            pairing = paired
+            record(paired, frame, pipeline)
+            // A frame's worth. Fine grained because it costs one main-thread
+            // read of already-computed values, and because the gate has to
+            // resolve a transient that lasts a second and a half.
+            main.postDelayed(this, 16)
+        }
+    }
+
+    /** Players built and released, so a teardown gate can bound them. */
+    @Volatile var built = 0L
+        private set
+
+    @Volatile var releasedCount = 0L
+        private set
+
+    fun state(): String {
+        val p = player
+        val json = JSONObject()
+            .put("ok", true)
+            .put("attached", p != null)
+            .put("built", built)
+            .put("released", releasedCount)
+            .put("superseded", superseded)
+            .put("claimed", claimed.get())
+            .put("intentPlaying", intentPlaying)
+            .put("releasePending", releasePending)
+            .put("releases", releases)
+            .put("readinessTimeouts", readinessTimeouts)
+            .put("readinessFailure", readinessFailure ?: JSONObject.NULL)
+            /*
+              Hold durations, listed rather than summarised.
+
+              Each is a wall-clock pause the person sees. An average would make
+              two 150 ms stalls read like steady playback, and none of this is
+              synchronisation — it is the price paid to keep synchronisation.
+            */
+            .put("seamHoldMs", org.json.JSONArray(seamHoldMs.toList()))
+            .put("seamHoldTimeouts", seamHoldTimeouts)
+            .put("seamHoldActive", seamHoldTargetUs >= 0)
+            .put("epochTargetUs", epochTargetUs)
+            .put(
+                "holdMs",
+                if (releasedAtNs > releaseArmedNs) (releasedAtNs - releaseArmedNs) / 1_000_000
+                else -1,
+            )
+            .put("error", lastError ?: JSONObject.NULL)
+            // Readiness is reported apart from synchronisation on purpose: a
+            // preparation pause is a latency figure, not an A/V error, and
+            // averaging one into the other is how a slow start reads as drift.
+            .put("startupMs", if (readyAtNs > startedAtNs) (readyAtNs - startedAtNs) / 1_000_000 else -1)
+            .put("seekMs", if (seekReadyNs > seekStartedNs) (seekReadyNs - seekStartedNs) / 1_000_000 else -1)
+        val snapshot = pairing
+        if (p == null || snapshot == null) return json.toString()
+        return json
+            /*
+              Both readings, taken here, in one call.
+
+              The position is the composition's own clock — driven by the audio
+              graph — and the presented frame is what the consumer actually
+              latched. Sampled together against one `System.nanoTime()`, the only
+              uncertainty left is the position's millisecond quantisation and the
+              frame's own age, and the age is reported so a sample taken during a
+              stall can be excluded rather than averaged in.
+            */
+            .put("atNs", snapshot.atNs)
+            .put("positionUs", snapshot.positionUs)
+            .put("playing", snapshot.playing)
+            .put("playbackState", snapshot.playbackState)
+            .put("durationUs", snapshot.durationUs)
+            .put("presentedUs", if (snapshot.presentedUs < 0) JSONObject.NULL else snapshot.presentedUs)
+            .put("presentedAgeNs", snapshot.presentedAgeNs)
+            .put("readSpanNs", snapshot.readSpanNs)
+            // How old this pairing is by the time it is read. Reported so a
+            // verdict is never taken from a snapshot the pump failed to refresh.
+            .put("pairingAgeNs", System.nanoTime() - snapshot.atNs)
+            .toString()
+    }
+
+    /**
+     * Build the composition and attach it to the surface the preview already owns.
+     *
+     * @param specJson `{items:[{uri,startUs,endUs,speed}], mixUri, width, height}`
+     *   exactly as `playlistOf()` produced it.
+     */
+    fun start(context: Context, specJson: String): String {
+        return try {
+            val spec = JSONObject(specJson)
+            val itemsJson = spec.getJSONArray("items")
+            val width = spec.getInt("width")
+            val height = spec.getInt("height")
+            val mixUri = spec.optString("mixUri", "")
+            // Required, not optional. `CompositionPlayer` computes each
+            // sequence's duration up front and an audio-only item cannot supply
+            // one on its own, so a missing value fails with a bare
+            // `IllegalStateException` carrying only `C.TIME_UNSET`.
+            val mixDurationUs = spec.optLong("mixDurationUs", 0L)
+            /*
+              Refused before anything is built.
+
+              Zero means the caller did not claim, which is allowed and treated
+              as "no supersession in play" — the spike is also used for runs
+              that never race.
+            */
+            val requestId = spec.optLong("requestId", 0L)
+            if (requestId != 0L && requestId < claimed.get()) {
+                superseded += 1
+                return JSONObject()
+                    .put("ok", false).put("superseded", true)
+                    .put("requestId", requestId).put("claimed", claimed.get())
+                    .toString()
+            }
+
+            val clips = ArrayList<EditedMediaItem>(itemsJson.length())
+            for (i in 0 until itemsJson.length()) {
+                clips.add(clipItem(itemsJson.getJSONObject(i)))
+            }
+            if (clips.isEmpty()) {
+                return JSONObject().put("ok", false).put("error", "no items").toString()
+            }
+
+            /*
+              The boundaries, from the same spec the composition is built from.
+
+              Each item occupies its trimmed source length divided by its speed,
+              and the seams are the running total. Taken from here rather than
+              asked of the player: the player reports where it *is*, and the
+              hold has to arm before it gets there.
+
+              The last boundary is the end of the composition and is not a seam;
+              nothing follows it to prepare.
+            */
+            val seams = ArrayList<Long>(itemsJson.length())
+            var at = 0L
+            for (i in 0 until itemsJson.length()) {
+                val item = itemsJson.getJSONObject(i)
+                val speed = item.optDouble("speed", 1.0).takeIf { it > 0 } ?: 1.0
+                at += ((item.optLong("endUs") - item.optLong("startUs")) / speed).toLong()
+                if (i < itemsJson.length() - 1) seams.add(at)
+            }
+            seamHoldEnabled = spec.optBoolean("seamHold", false)
+            seamSeekEnabled = spec.optBoolean("seamSeek", false)
+            setSeamTargets(seams.toLongArray())
+
+            val sequences = ArrayList<EditedMediaItemSequence>(2)
+            sequences.add(EditedMediaItemSequence.Builder(clips).build())
+            if (mixUri.isNotEmpty()) {
+                sequences.add(
+                    EditedMediaItemSequence.Builder(
+                        EditedMediaItem.Builder(MediaItem.fromUri(mixUri))
+                            // Audio only. The mix already covers the whole
+                            // project; a video track here would be a second
+                            // picture nobody asked for.
+                            .setRemoveVideo(true)
+                            .setDurationUs(mixDurationUs)
+                            .build(),
+                    ).build(),
+                )
+            }
+            val composition = Composition.Builder(sequences).build()
+
+            val surface = VideoSurface.currentSurface()
+                ?: return JSONObject().put("ok", false).put("error", "no surface").toString()
+
+            val done = java.util.concurrent.CountDownLatch(1)
+            main.post {
+                runCatching {
+                    releaseLocked()
+                    lastError = null
+                    startedAtNs = System.nanoTime()
+                    readyAtNs = 0
+                    val p = CompositionPlayer.Builder(context).build()
+                    p.setVideoSurface(surface, Size(width, height))
+                    // The same hook the two-player path uses, so the presented
+                    // frame is measured by the machinery already trusted.
+                    p.setVideoFrameMetadataListener { presentationTimeUs, releaseTimeNs, _, _ ->
+                        FrameClock.offer(presentationTimeUs, releaseTimeNs)
+                    }
+                    p.addListener(object : Player.Listener {
+                        override fun onPlaybackStateChanged(state: Int) {
+                            if (state == Player.STATE_READY) {
+                                if (readyAtNs == 0L) readyAtNs = System.nanoTime()
+                                if (seekStartedNs > seekReadyNs) seekReadyNs = System.nanoTime()
+                            }
+                        }
+
+                        override fun onPlayerError(error: androidx.media3.common.PlaybackException) {
+                            lastError = "${error.errorCodeName}: ${error.message}"
+                        }
+                    })
+                    // Checked again inside the post: the claim may have moved
+                    // while this request was queued behind another.
+                    if (requestId != 0L && requestId < claimed.get()) {
+                        superseded += 1
+                        runCatching { p.release() }
+                        lastError = null
+                        done.countDown()
+                        return@post
+                    }
+                    p.setComposition(composition)
+                    p.prepare()
+                    player = p
+                    built += 1
+                    pairing = null
+                    epoch += 1
+                    epochAtNs = System.nanoTime()
+                    intentPlaying = false
+                    releasePending = false
+                    epochTargetUs = 0
+                    main.removeCallbacks(pump)
+                    pump.run()
+                }.onFailure {
+                    // With the stack, because a spike's first failure is
+                    // usually a contract it is holding wrongly and the class
+                    // name alone names none of them.
+                    lastError = it.javaClass.simpleName + ": " + it.message
+                    android.util.Log.e("PictorSpike", "composition start failed", it)
+                }
+                done.countDown()
+            }
+            done.await(5, java.util.concurrent.TimeUnit.SECONDS)
+            JSONObject().put("ok", lastError == null)
+                .put("error", lastError ?: JSONObject.NULL)
+                .put("sequences", sequences.size)
+                .put("clips", clips.size)
+                .toString()
+        } catch (e: Exception) {
+            JSONObject().put("ok", false).put("error", e.javaClass.simpleName + ": " + e.message)
+                .toString()
+        }
+    }
+
+    private fun clipItem(o: JSONObject): EditedMediaItem {
+        val startUs = o.getLong("startUs")
+        val endUs = o.getLong("endUs")
+        val speed = o.getDouble("speed").toFloat()
+        val media = MediaItem.Builder()
+            .setUri(o.getString("uri"))
+            .setClippingConfiguration(
+                MediaItem.ClippingConfiguration.Builder()
+                    .setStartPositionMs(startUs / 1000)
+                    .setEndPositionMs(endUs / 1000)
+                    .build(),
+            )
+            .build()
+        val builder = EditedMediaItem.Builder(media)
+            /*
+              No clip audio, ever.
+
+              The prepared mix already contains it — that is what makes it a
+              mix — and letting the clip's own track through would play the
+              whole timeline twice. This is the same rule the two-player path
+              enforces by muting the source player.
+            */
+            .setRemoveAudio(true)
+            .setDurationUs(endUs - startUs)
+        if (speed != 1f) {
+            /*
+              Speed as a source mapping, not as a clock rate.
+
+              `CompositionPlayer` accepts speed effects only from this factory,
+              and the reason it has to is the clock contract: a global
+              `PlaybackParameters` speed would scale the one axis every sequence
+              shares, dragging the mix to 2x with the picture. The pair is an
+              audio processor and a video timestamp adjustment, which is exactly
+              "the clip's compiled source-time mapping" expressed where the
+              player can honour it.
+            */
+            val pair = Effects.createExperimentalSpeedChangingEffect(ConstantSpeed(speed))
+            builder.setEffects(Effects(listOf(pair.first), listOf(pair.second)))
+        }
+        return builder.build()
+    }
+
+    /**
+     * The person asked for playback.
+     *
+     * Recorded as intent and armed as a hold; the transport starts from the
+     * pump once a current-epoch frame exists. Starting here would be the very
+     * thing this gate exists to stop.
+     */
+    fun play(): String = onPlayer {
+        intentPlaying = true
+        // Resume targets where the transport already is.
+        armRelease(it.currentPosition * 1000)
+    }
+
+    fun pause(): String = onPlayer {
+        // Intent first: a pause must invalidate a release that is about to
+        // happen, not race it.
+        intentPlaying = false
+        releasePending = false
+        cancelSeamHold()
+        FrameClock.setStreaming(false)
+        it.pause()
+    }
+
+    fun seek(positionUs: Long): String = onPlayer {
+        // A seek supersedes any hold: the boundary it was covering is no longer
+        // where playback is going.
+        cancelSeamHold()
+        seekStartedNs = System.nanoTime()
+        seekReadyNs = 0
+        // A new epoch: frames still in flight belong to the position being left.
+        epoch += 1
+        epochAtNs = seekStartedNs
+        // Frames in flight describe the position being left; their release
+        // times must not pace the new one.
+        FrameClock.bump()
+        /*
+          Held across the seek, and the older pending release is invalidated by
+          the re-arm. The player is paused so the seek does not play through
+          the interval where the picture is still the old position.
+        */
+        it.pause()
+        armRelease(positionUs)
+        it.seekTo(positionUs / 1000)
+    }
+
+    fun release(): String {
+        val done = java.util.concurrent.CountDownLatch(1)
+        main.post { releaseLocked(); done.countDown() }
+        done.await(5, java.util.concurrent.TimeUnit.SECONDS)
+        return JSONObject().put("ok", true).put("released", releasedCount).toString()
+    }
+
+    /** Main-thread only: `CompositionPlayer` requires one application thread. */
+    private fun releaseLocked() {
+        main.removeCallbacks(pump)
+        pairing = null
+        // Unmount and background both come through here: a pending release must
+        // not survive the player it was about to start.
+        intentPlaying = false
+        releasePending = false
+        FrameClock.setStreaming(false)
+        player?.let {
+            runCatching { it.release() }
+            releasedCount += 1
+        }
+        player = null
+    }
+
+    private fun onPlayer(block: (CompositionPlayer) -> Unit): String {
+        val p = player ?: return JSONObject().put("ok", false).put("error", "not started").toString()
+        main.post { runCatching { block(p) }.onFailure { lastError = it.message } }
+        return JSONObject().put("ok", true).toString()
+    }
+}