@pictor-sdk/video-android 0.1.3 → 0.1.5

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

@@ -0,0 +1,8 @@
+package dev.pictor.video
+
+import androidx.media3.common.Player
+
+/** Media3 seeks in milliseconds. A duplicate must not erase its latched frame. */
+internal fun isRedundantCompositionSeek(positionMs: Long, targetUs: Long, state: Int): Boolean =
+    (state == Player.STATE_READY || state == Player.STATE_BUFFERING) &&
+        positionMs == targetUs / 1000

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

@@ -145,6 +145,7 @@ internal object CompositionSpike {
         val playbackState: Int,
         val durationUs: Long,
         val presentedUs: Long,
+        val presentedWindowIndex: Int,
         val presentedAgeNs: Long,
         /** How long the read itself took, which bounds the pairing error. */
         val readSpanNs: Long,
@@ -606,6 +607,7 @@ internal object CompositionSpike {
                 playbackState = playbackState,
                 durationUs = duration,
                 presentedUs = frame?.get(FrameClock.Field.PTS_US) ?: -1,
+                presentedWindowIndex = frame?.get(FrameClock.Field.WINDOW_INDEX)?.toInt() ?: -1,
                 /*
                   Aged from the *scheduled release*, not from the metadata callback.
 
@@ -699,6 +701,7 @@ internal object CompositionSpike {
             .put("playbackState", snapshot.playbackState)
             .put("durationUs", snapshot.durationUs)
             .put("presentedUs", if (snapshot.presentedUs < 0) JSONObject.NULL else snapshot.presentedUs)
+            .put("presentedWindowIndex", snapshot.presentedWindowIndex)
             .put("presentedAgeNs", snapshot.presentedAgeNs)
             .put("readSpanNs", snapshot.readSpanNs)
             // How old this pairing is by the time it is read. Reported so a
@@ -761,11 +764,14 @@ internal object CompositionSpike {
               nothing follows it to prepare.
             */
             val seams = ArrayList<Long>(itemsJson.length())
+            val windowEndsUs = LongArray(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()
+                at = item.optLong("timelineEndUs",
+                    at + ((item.optLong("endUs") - item.optLong("startUs")) / speed).toLong())
+                windowEndsUs[i] = at
                 if (i < itemsJson.length() - 1) seams.add(at)
             }
             seamHoldEnabled = spec.optBoolean("seamHold", false)
@@ -804,7 +810,10 @@ internal object CompositionSpike {
                     // 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)
+                        FrameClock.offerForWindow(
+                            presentationTimeUs, releaseTimeNs,
+                            compositionWindowAt(presentationTimeUs, windowEndsUs),
+                        )
                     }
                     p.addListener(object : Player.Listener {
                         override fun onPlaybackStateChanged(state: Int) {
@@ -873,17 +882,8 @@ internal object CompositionSpike {
                     .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)
+        // The helper removes clip audio: the prepared mix already contains it.
+        val builder = compositionVideoItem(media, o.optLong("sourceDurationUs", endUs))
         if (speed != 1f) {
             /*
               Speed as a source mapping, not as a clock rate.
@@ -929,6 +929,16 @@ internal object CompositionSpike {
         // A seek supersedes any hold: the boundary it was covering is no longer
         // where playback is going.
         cancelSeamHold()
+        // Scrubbing sends the last position again on release. Media3 may not
+        // emit another frame for a no-op seek; bumping FrameClock here would
+        // erase the only frame that can satisfy the following Play readiness
+        // gate. Keep pause/hold semantics, but don't invalidate that frame or
+        // the metadata for a seek to this position already in flight.
+        if (isRedundantCompositionSeek(it.currentPosition, positionUs, it.playbackState)) {
+            it.pause()
+            armRelease(positionUs)
+            return@onPlayer
+        }
         seekStartedNs = System.nanoTime()
         seekReadyNs = 0
         // A new epoch: frames still in flight belong to the position being left.

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

@@ -0,0 +1,16 @@
+package dev.pictor.video
+
+import androidx.media3.common.MediaItem
+import androidx.media3.transformer.EditedMediaItem
+
+/**
+ * Media3 applies the MediaItem's trim itself. Its duration is the untrimmed
+ * source duration, NOT end - start: that would apply the trim twice and reject
+ * any end beyond that shortened duration. Speed is applied separately as well.
+ * Legacy callers without metadata supply endUs as the known source extent;
+ * with an explicit clipping end this gives the same presentation duration.
+ */
+internal fun compositionVideoItem(media: MediaItem, sourceDurationUs: Long): EditedMediaItem.Builder =
+    EditedMediaItem.Builder(media)
+        .setRemoveAudio(true)
+        .setDurationUs(sourceDurationUs)

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

@@ -0,0 +1,17 @@
+package dev.pictor.video
+
+/**
+ * CompositionPlayer emits project-time PTS, not playlist transition events.
+ * Tag the actual offered frame using compiled exclusive window ends, never
+ * the playhead: outgoing and incoming frames can be in flight at the seam.
+ */
+internal fun compositionWindowAt(presentationUs: Long, windowEndsUs: LongArray): Int {
+    if (presentationUs < 0 || windowEndsUs.isEmpty()) return -1
+    var low = 0
+    var high = windowEndsUs.size
+    while (low < high) {
+        val mid = (low + high) ushr 1
+        if (presentationUs < windowEndsUs[mid]) high = mid else low = mid + 1
+    }
+    return low.coerceAtMost(windowEndsUs.lastIndex)
+}

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

@@ -212,6 +212,11 @@ internal object FrameClock {
     /** From `VideoFrameMetadataListener`, before the frame is released. */
     @JvmStatic
     fun offer(ptsUs: Long, scheduledReleaseNs: Long) {
+        offerForWindow(ptsUs, scheduledReleaseNs, windowIndex)
+    }
+
+    /** Composition frames carry their own window, determined from their PTS. */
+    internal fun offerForWindow(ptsUs: Long, scheduledReleaseNs: Long, frameWindowIndex: Int) {
         val now = PlaybackAnchor.nowNs()
         /*
           How far ahead the renderer scheduled this frame.
@@ -239,7 +244,7 @@ internal object FrameClock {
         sample[Field.POSITION_AT_RELEASE_US] = PlaybackAnchor.positionAt(scheduledReleaseNs)
         sample[Field.FLAGS] = stateBits(anchor)
         sample[Field.ANCHOR_AGE_NS] = PlaybackAnchor.ageNs(scheduledReleaseNs)
-        sample[Field.WINDOW_INDEX] = windowIndex.toLong()
+        sample[Field.WINDOW_INDEX] = frameWindowIndex.toLong()
         synchronized(lock) {
             if (metadata.size >= CAPACITY) {
                 metadata.removeFirst()

package/dist/index.d.mts

@@ -2431,6 +2431,10 @@ interface CompositionSpikeItem {
     /** Clipping bounds in **source** time, which is where speed is applied. */
     startUs: number;
     endUs: number;
+    /** Full source duration, before trimming or speed. Omit only for legacy callers. */
+    sourceDurationUs?: number;
+    /** Exclusive project-time end from the playlist compiler, after trim and speed. */
+    timelineEndUs?: number;
     speed: number;
 }
 /** @experimental */
@@ -2517,6 +2521,8 @@ interface CompositionSpikeState {
     playbackState?: number;
     durationUs?: number;
     presentedUs?: number | null;
+    /** Playlist window belonging to the latched frame, not the current playhead. */
+    presentedWindowIndex?: number;
     /** How old the presented frame was when it was read, so a stalled sample can be excluded. */
     presentedAgeNs?: number;
     /** How long the paired read itself took. Bounds the pairing error. */

package/dist/index.d.ts

@@ -2431,6 +2431,10 @@ interface CompositionSpikeItem {
     /** Clipping bounds in **source** time, which is where speed is applied. */
     startUs: number;
     endUs: number;
+    /** Full source duration, before trimming or speed. Omit only for legacy callers. */
+    sourceDurationUs?: number;
+    /** Exclusive project-time end from the playlist compiler, after trim and speed. */
+    timelineEndUs?: number;
     speed: number;
 }
 /** @experimental */
@@ -2517,6 +2521,8 @@ interface CompositionSpikeState {
     playbackState?: number;
     durationUs?: number;
     presentedUs?: number | null;
+    /** Playlist window belonging to the latched frame, not the current playhead. */
+    presentedWindowIndex?: number;
     /** How old the presented frame was when it was read, so a stalled sample can be excluded. */
     presentedAgeNs?: number;
     /** How long the paired read itself took. Bounds the pairing error. */

package/dist/index.js

@@ -714,6 +714,7 @@ function useVideoSurface(options) {
 
 // src/useCompositionPlayback.ts
 var import_react2 = require("react");
+var import_react_native3 = require("react-native");
 var import_video_core2 = require("@pictor-sdk/video-core");
 
 // src/compositionSpike.ts
@@ -722,6 +723,7 @@ function compositionSpikeSpec(project, mix, resolve) {
   const playlist = (0, import_video_core.playlistOf)(project);
   const items = [];
   const unsupported = playlist.unsupported.map((u) => `${u.clipId}: ${u.reason}`);
+  const clips = new Map(project.clips.map((clip) => [clip.id, clip]));
   for (const item of playlist.items) {
     const uri = resolve(item.source);
     if (uri === null) {
@@ -732,6 +734,8 @@ function compositionSpikeSpec(project, mix, resolve) {
       uri,
       startUs: Number(item.startUs),
       endUs: Number(item.endUs),
+      sourceDurationUs: clips.get(item.clipId)?.metadata.duration,
+      timelineEndUs: Number(item.timelineEndUs),
       speed: item.speed
     });
   }
@@ -928,10 +932,26 @@ function useCompositionPlayback(options) {
     setUnsupported(
       refused.map((reason) => ({ clipId: reason.split(":")[0] ?? "", reason }))
     );
-    if (spec.items.length === 0) return;
+    if (spec.items.length === 0) {
+      spikePause();
+      return;
+    }
     const started = spikeStart(spec);
     if (started.ok === true) loaded.current = signature;
   }, [enabled, signature, surfaceGeneration, project, mix]);
+  (0, import_react2.useEffect)(() => {
+    const subscription = import_react_native3.AppState.addEventListener("change", (next) => {
+      if (next === "active") {
+        lifecycle.resume();
+        setLifecycleEpoch(lifecycle.epoch);
+        return;
+      }
+      lifecycle.suspend("background");
+      setLifecycleEpoch(lifecycle.epoch);
+      setPlaying(false);
+    });
+    return () => subscription.remove();
+  }, [lifecycle]);
   (0, import_react2.useEffect)(() => {
     return () => {
       lifecycle.teardown("unmount");
@@ -1016,7 +1036,7 @@ function useCompositionPlayback(options) {
 // src/useMedia3Playback.ts
 var import_video_core3 = require("@pictor-sdk/video-core");
 var import_react3 = require("react");
-var import_react_native3 = require("react-native");
+var import_react_native4 = require("react-native");
 
 // src/surfaceRecovery.ts
 var RECOVERY_GRACE_MS = 1500;
@@ -1108,7 +1128,7 @@ function useMedia3Playback(options) {
   const lifecycle = lifecycleRef.current;
   const [lifecycleEpoch, setLifecycleEpoch] = (0, import_react3.useState)(lifecycle.epoch);
   (0, import_react3.useEffect)(() => {
-    const subscription = import_react_native3.AppState.addEventListener("change", (next) => {
+    const subscription = import_react_native4.AppState.addEventListener("change", (next) => {
       if (next === "active") {
         lifecycle.resume();
         setLifecycleEpoch(lifecycle.epoch);