@pictor-sdk/video-android 0.1.5 → 0.1.6

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

@@ -212,6 +212,9 @@ internal object CompositionSpike {
         private set
 
     @Volatile var readinessTimeouts = 0L
+
+    /** How many resumes had to be re-primed because no frame could satisfy them. */
+    @Volatile var primedResumes = 0L
         private set
 
     /** How long a hold may wait before it is reported as a failure. */
@@ -408,19 +411,24 @@ internal object CompositionSpike {
         */
         if (seamHoldTargetUs >= 0) return pts >= seamHoldTargetUs
 
-        return pts >= epochTargetUs - FRAME_MATCH_BACK_US &&
-            pts <= epochTargetUs + FRAME_MATCH_AHEAD_US
+        return ResumeReadiness.matches(pts, epochTargetUs)
     }
 
     /**
-     * How far a frame may sit from the epoch's target and still be its first.
+     * The newest frame the pipeline actually has, or null if there is none.
      *
-     * 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.
+     * The same three checks the gate makes before it will look at a timestamp:
+     * latched rather than merely offered, pixels and timestamp from the same
+     * frame, and a usable project time. A caller deciding where to re-prime has
+     * to be reading the same frame the gate will be judging.
      */
-    private const val FRAME_MATCH_BACK_US = 40_000L
-    private const val FRAME_MATCH_AHEAD_US = 1_000_000L
+    private fun latchedFramePtsUs(): Long? {
+        val frame = FrameClock.latestSample() ?: return null
+        if (frame[FrameClock.Field.CONSUMED_NS] <= 0L) return null
+        if (frame[FrameClock.Field.ASSOCIATION] != 1L) return null
+        val pts = frame[FrameClock.Field.PTS_US]
+        return if (pts < 0L) null else pts
+    }
 
     /** Retained evidence, so an excursion can be looked at rather than inferred. */
     private const val RING = 8192
@@ -660,6 +668,7 @@ internal object CompositionSpike {
             .put("releases", releases)
             .put("readinessTimeouts", readinessTimeouts)
             .put("readinessFailure", readinessFailure ?: JSONObject.NULL)
+            .put("primedResumes", primedResumes)
             /*
               Hold durations, listed rather than summarised.
 
@@ -912,7 +921,38 @@ internal object CompositionSpike {
     fun play(): String = onPlayer {
         intentPlaying = true
         // Resume targets where the transport already is.
-        armRelease(it.currentPosition * 1000)
+        val clockUs = it.currentPosition * 1000
+        /*
+          Unless nothing can show that position.
+
+          Coming back from the background the renderer has stopped latching
+          while the transport kept counting, so the newest frame can sit a
+          frame or two behind the clock — past the gate's backward tolerance.
+          Arming there asks for a frame the decoder will never produce while it
+          is paused, and a seek to the position it already reports need not
+          produce one either, so the hold times out and every later press of
+          play repeats the same impossible wait.
+
+          Re-primed instead of relaxed: playback seeks to the timestamp of the
+          frame on screen, which is a real position and a different one, so the
+          decoder emits for it and the gate releases on a frame made for this
+          epoch. See `ResumeReadiness`.
+        */
+        val primeUs =
+            if (seamHoldTargetUs >= 0) null
+            else ResumeReadiness.primeTargetUs(clockUs, latchedFramePtsUs())
+        if (primeUs == null) {
+            armRelease(clockUs)
+            return@onPlayer
+        }
+        // A new epoch, for the same reason a seek opens one: what is in flight
+        // describes the position being left, not the one being asked for.
+        epoch += 1
+        epochAtNs = System.nanoTime()
+        FrameClock.bump()
+        primedResumes += 1
+        armRelease(primeUs)
+        it.seekTo(primeUs / 1000)
     }
 
     fun pause(): String = onPlayer {

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

@@ -0,0 +1,82 @@
+package dev.pictor.video
+
+/**
+ * Where a resume may be released, and where it has to be re-primed first.
+ *
+ * The readiness gate releases the transport only on a frame that shows the
+ * epoch's position. That is the right rule, and it is kept exactly: this is the
+ * arithmetic behind it, pulled out so it can be reasoned about and tested
+ * without a player.
+ *
+ * ## The failure it exists for
+ *
+ * A resume's target is the transport clock, and the clock can sit ahead of the
+ * newest frame that exists. When the app goes to the background the renderer
+ * stops latching before the transport stops counting, so the last frame on
+ * screen ends up a frame or two behind the position the player reports. Arming
+ * on the clock then asks for a frame that nothing will produce — the decoder is
+ * paused, and Media3 need not emit anything for a seek to the position it is
+ * already at — so the gate waits out its three seconds and the transport is
+ * left stopped. Pressing play again re-arms the same impossible wait.
+ *
+ * Measured on a Pixel 7, opening the system document picker from "Add music":
+ * targets 46,667 us and 53,334 us ahead of the newest frame against a 40,000 us
+ * backward tolerance, wedging two runs in five. The runs that recovered had
+ * gaps inside the tolerance.
+ *
+ * ## What is done about it
+ *
+ * Re-prime, rather than relax. When no frame can satisfy the hold, playback
+ * seeks to the timestamp of the frame already on screen — a real position that
+ * differs from the clock, so the decoder emits for it — and the gate then
+ * releases on a frame produced for this epoch. The tolerances are untouched,
+ * nothing starts on an unverified frame, and the distance moved is whatever the
+ * renderer fell behind rather than a nudge chosen to clear the comparison.
+ */
+internal object ResumeReadiness {
+
+    /**
+     * 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.
+     */
+    const val FRAME_MATCH_BACK_US = 40_000L
+    const val FRAME_MATCH_AHEAD_US = 1_000_000L
+
+    /** Whether a frame at [framePtsUs] shows the position [targetUs] asks for. */
+    fun matches(framePtsUs: Long, targetUs: Long): Boolean =
+        framePtsUs >= targetUs - FRAME_MATCH_BACK_US &&
+            framePtsUs <= targetUs + FRAME_MATCH_AHEAD_US
+
+    /**
+     * The position a stalled resume has to re-prime at, or null to wait as usual.
+     *
+     * [framePtsUs] is the newest latched, associated frame of the current
+     * generation, or null when there is none — after a seek, for instance, where
+     * `FrameClock.bump` has cleared it and the seek's own frame is on its way.
+     * With nothing latched there is nothing to re-prime at and nothing to
+     * conclude, so the ordinary wait applies.
+     *
+     * Returns null when the gate can already be satisfied, so an ordinary start
+     * or seek is completely unaffected: this only fires where playback would
+     * otherwise wait for a frame that cannot arrive.
+     *
+     * A frame further behind than [FRAME_MATCH_AHEAD_US] is not treated as the
+     * current picture at all. That is a stalled pipeline rather than a renderer
+     * that stopped a couple of frames early, and seeking a second backwards to
+     * meet it would be starting playback somewhere nobody asked for. It is left
+     * to time out and be reported, which is what that timeout is for.
+     */
+    fun primeTargetUs(clockUs: Long, framePtsUs: Long?): Long? {
+        if (framePtsUs == null) return null
+        if (matches(framePtsUs, clockUs)) return null
+        // Ahead of the clock is not this problem: a frame in front of the target
+        // is already covered by the forward tolerance, and seeking back to it
+        // would move playback the wrong way.
+        if (framePtsUs > clockUs) return null
+        if (framePtsUs < clockUs - FRAME_MATCH_AHEAD_US) return null
+        return framePtsUs
+    }
+}

package/dist/index.d.mts

@@ -1026,6 +1026,19 @@ interface CompositionPlaybackState {
     width: number;
     height: number;
     error: string | null;
+    /**
+     * Why the transport refused to start, or null.
+     *
+     * Playback is released on a frame that shows the position asked for, and if
+     * no such frame arrives the hold times out and the transport stays stopped
+     * rather than starting on an unverified picture. That used to be invisible:
+     * the control stayed enabled, the press was accepted, and nothing happened,
+     * with no way for a host to tell that apart from a person who had not pressed
+     * it yet. Pressing play again clears it and tries afresh.
+     *
+     * @experimental
+     */
+    readinessFailure: string | null;
 }
 /** @experimental */
 type CompositionPlayback = Omit<Media3Playback, 'state'> & {
@@ -2501,6 +2514,16 @@ interface CompositionSpikeState {
     releases?: number;
     readinessTimeouts?: number;
     readinessFailure?: string | null;
+    /**
+     * How many resumes had to be re-primed because no frame could satisfy them.
+     *
+     * A resume whose target sits past the newest frame cannot be released on
+     * anything that exists, so playback seeks to the frame on screen to make the
+     * decoder produce one. Counted because it is a recovery, not a normal path:
+     * a number that climbs steadily is the renderer falling behind the transport
+     * more often than it should.
+     */
+    primedResumes?: number;
     /** How long the last hold lasted before playback was released. */
     holdMs?: number;
     /**

package/dist/index.d.ts

@@ -1026,6 +1026,19 @@ interface CompositionPlaybackState {
     width: number;
     height: number;
     error: string | null;
+    /**
+     * Why the transport refused to start, or null.
+     *
+     * Playback is released on a frame that shows the position asked for, and if
+     * no such frame arrives the hold times out and the transport stays stopped
+     * rather than starting on an unverified picture. That used to be invisible:
+     * the control stayed enabled, the press was accepted, and nothing happened,
+     * with no way for a host to tell that apart from a person who had not pressed
+     * it yet. Pressing play again clears it and tries afresh.
+     *
+     * @experimental
+     */
+    readinessFailure: string | null;
 }
 /** @experimental */
 type CompositionPlayback = Omit<Media3Playback, 'state'> & {
@@ -2501,6 +2514,16 @@ interface CompositionSpikeState {
     releases?: number;
     readinessTimeouts?: number;
     readinessFailure?: string | null;
+    /**
+     * How many resumes had to be re-primed because no frame could satisfy them.
+     *
+     * A resume whose target sits past the newest frame cannot be released on
+     * anything that exists, so playback seeks to the frame on screen to make the
+     * decoder produce one. Counted because it is a recovery, not a normal path:
+     * a number that climbs steadily is the renderer falling behind the transport
+     * more often than it should.
+     */
+    primedResumes?: number;
     /** How long the last hold lasted before playback was released. */
     holdMs?: number;
     /**

package/dist/index.js

@@ -884,7 +884,8 @@ function composedState(snapshot) {
         */
     width: 0,
     height: 0,
-    error: snapshot.error ?? null
+    error: snapshot.error ?? null,
+    readinessFailure: snapshot.readinessFailure ?? null
   };
 }
 function useCompositionPlayback(options) {