@pictor-sdk/video-android 0.1.0 → 0.1.4

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

@@ -1039,6 +1039,19 @@ class PictorVideoModule(reactContext: ReactApplicationContext) :
         return org.json.JSONObject().put("ok", true).put("stallAfterFrames", frames.toInt()).toString()
     }
 
+    /**
+     * Gate-only: the smallest failing Media3 export, located one stage at a time.
+     *
+     * Runs on the calling background thread and blocks it — each rung has its
+     * own bounded wait, so the whole ladder is bounded, and a rung that never
+     * completes is reported as a timeout rather than waited on.
+     */
+    @androidx.media3.common.util.UnstableApi
+    override fun exportGateLadder(specJson: String): String {
+        if (!Diagnostics.ENABLED) return Diagnostics.unavailable()
+        return GateLadder.start(reactApplicationContext, specJson)
+    }
+
     /**
      * Arm the gate-only controls.
      *

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

@@ -0,0 +1,108 @@
+package dev.pictor.video
+
+import java.util.concurrent.CountDownLatch
+
+/**
+ * Which run is in flight, so a cancellation can reach it — and release it.
+ *
+ * ## The two rules, and what each one cost
+ *
+ * **Publication and cancellation are one decision.** They used to be two steps
+ * apiece: a run checked a `cancelled` flag and then assigned itself to a field,
+ * while a cancel set that flag and then read that field. A cancel landing
+ * between the check and the assignment read nothing, cancelled nothing and
+ * released nothing, while the run it was meant to stop went on to start. The
+ * waiter then sat until its timeout — 600 s, on an export a person was watching.
+ * Here both sides take the same lock, so a cancel is either seen by the
+ * publication or finds the published run. Never neither.
+ *
+ * **The waiter is released before anything that can block.** Media3's
+ * `Transformer.cancel()` does not call the run's listener, so the cancelling
+ * side must count the latch down itself — and it must do that *first*. Measured
+ * on a wedged shard: the cancel found a live transformer and a live latch, and
+ * the waiter still sat for 288 seconds, because `cancel()` blocks joining the
+ * threads that are stuck and the countdown was the line after it. Stopping the
+ * work is best-effort; ending the wait is not.
+ *
+ * Generic in the thing being stopped so this holds no Android types and the
+ * rules above can be tested for real rather than re-stated in a test's own copy.
+ */
+internal class RunRegistry<T> {
+
+    /** One run's registration: its waiter, and what would stop it. */
+    class Handle<T>(val latch: CountDownLatch) {
+        @Volatile internal var target: T? = null
+        /** Set under the lock. True once a cancel has claimed this run. */
+        @Volatile var cancelled: Boolean = false
+            internal set
+    }
+
+    private val lock = Any()
+    private var active: Handle<T>? = null
+
+    /**
+     * Offer a built run. `false` means a cancel got here first, so do not start
+     * it — the caller releases its own latch and reports the run cancelled.
+     */
+    fun publish(handle: Handle<T>, target: T): Boolean = synchronized(lock) {
+        if (handle.cancelled) return false
+        handle.target = target
+        active = handle
+        true
+    }
+
+    /**
+     * Claim whatever is in flight, release its waiter, then try to stop it.
+     *
+     * Returns false when there was nothing published — the caller has already
+     * recorded the intent to cancel, and the run that has not published yet
+     * will see it and refuse.
+     *
+     * `stop` runs after the release and its outcome is nobody's business here:
+     * a stop that throws, blocks or never happens must not decide whether the
+     * export is still waiting.
+     */
+    fun cancel(stop: (T) -> Unit): Boolean {
+        val handle = synchronized(lock) {
+            val current = active
+            current?.cancelled = true
+            current
+        }
+        if (handle == null) return false
+        handle.latch.countDown()
+        val target = handle.target
+        if (target != null) stop(target)
+        return true
+    }
+
+    /**
+     * Mark the next publication refused, without needing one yet.
+     *
+     * A cancel that arrives while a composition is still being built has no run
+     * to claim. Recording it on the handle is what makes the publication refuse
+     * rather than start something nobody wants.
+     */
+    fun refuse(handle: Handle<T>) = synchronized(lock) { handle.cancelled = true }
+
+    /**
+     * Forget `handle`, if it is still the one in flight.
+     *
+     * Scoped, because the caller is a Media3 listener and a listener can arrive
+     * **late**. `Transformer.cancel()` does not invoke it, so a wedged run's
+     * listener may fire minutes later — by which time a newer export has
+     * published itself here. An unscoped clear then forgot the *new* run, and
+     * the next cancel found nothing to stop and nothing to release: the very
+     * failure this class exists to prevent, reintroduced from the other end.
+     *
+     * Returns false when the handle was not current, which is the caller's
+     * signal that its result belongs to an export nobody is waiting for.
+     */
+    fun clear(handle: Handle<T>): Boolean = synchronized(lock) {
+        if (active !== handle) return false
+        active = null
+        true
+    }
+
+    /** Forget whatever is in flight. For a job ending, not for a listener. */
+    fun clear() = synchronized(lock) { active = null }
+}

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

@@ -91,6 +91,10 @@ internal class SkiaPassThroughEffect(
     val overlayTexturesFreed = AtomicLong(0)
     private val shaderPrograms = AtomicLong(0)
     private val frames = AtomicLong(0)
+
+    /** Frames this effect has passed through. Read while a wait has not settled. */
+    fun framesSeen(): Long = frames.get()
+
     private val releases = AtomicLong(0)
     private val timestamps = StringBuilder()
     private val glErrorCodes = mutableSetOf<Int>()

package/dist/index.d.mts

@@ -1284,6 +1284,27 @@ interface Media3ExporterOptions {
      * Native counting is unthrottled regardless; this is only the bridge rate.
      */
     progressPollMs?: number;
+    /**
+     * Which mechanism re-times a clip's **video** when its speed is not 1.
+     *
+     * `'cadence'` (the default, and what has shipped) compiles an exact emit plan
+     * in `resampleClip` and a GL effect drops or repeats frames to match it. The
+     * plan's length is the clip's length by construction, so project time is
+     * exact — and above 1× the decoder still reads every source frame, which is
+     * what produces a burst of output followed immediately by end-of-stream.
+     *
+     * `'media3'` sends no plan, so no cadence effect is built and
+     * `EditedMediaItem.setSpeed` carries the video timing on its own.
+     *
+     * Exposed because the burst is implicated in a vendor encoder that drops its
+     * output end-of-stream at high rates — see
+     * `docs/research/export-speed-stall.md`. It is a comparison switch, not a
+     * recommendation: the two paths select different frames, and which one is
+     * correct is what the comparison is for.
+     *
+     * @experimental
+     */
+    videoSpeedVia?: 'cadence' | 'media3';
 }
 /** Why an export will not start. @experimental */
 declare class VideoExportRejected extends Error {
@@ -2410,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 */
@@ -2496,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

@@ -1284,6 +1284,27 @@ interface Media3ExporterOptions {
      * Native counting is unthrottled regardless; this is only the bridge rate.
      */
     progressPollMs?: number;
+    /**
+     * Which mechanism re-times a clip's **video** when its speed is not 1.
+     *
+     * `'cadence'` (the default, and what has shipped) compiles an exact emit plan
+     * in `resampleClip` and a GL effect drops or repeats frames to match it. The
+     * plan's length is the clip's length by construction, so project time is
+     * exact — and above 1× the decoder still reads every source frame, which is
+     * what produces a burst of output followed immediately by end-of-stream.
+     *
+     * `'media3'` sends no plan, so no cadence effect is built and
+     * `EditedMediaItem.setSpeed` carries the video timing on its own.
+     *
+     * Exposed because the burst is implicated in a vendor encoder that drops its
+     * output end-of-stream at high rates — see
+     * `docs/research/export-speed-stall.md`. It is a comparison switch, not a
+     * recommendation: the two paths select different frames, and which one is
+     * correct is what the comparison is for.
+     *
+     * @experimental
+     */
+    videoSpeedVia?: 'cadence' | 'media3';
 }
 /** Why an export will not start. @experimental */
 declare class VideoExportRejected extends Error {
@@ -2410,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 */
@@ -2496,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

@@ -722,6 +722,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 +733,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
     });
   }
@@ -1910,9 +1913,10 @@ function createMedia3VideoExporter(options) {
           );
         }
         const resources = overlayPlan.resources;
+        const viaMedia3 = options.videoSpeedVia === "media3";
         const shards = plan.map((shard, index) => {
           const clip = playable[index];
-          const cadence = cadenceFor(shard.plan.frames);
+          const cadence = viaMedia3 && clip.speed !== 1 ? null : cadenceFor(shard.plan.frames);
           return {
             uri: uris[index],
             startMs: Math.round(clip.sourceIn / 1e3),
@@ -1931,11 +1935,19 @@ function createMedia3VideoExporter(options) {
                         What matters is that the *source's* audio never enters this pipeline:
                         a per-shard audio track has to be re-encoded to concatenate, which is
                         what put a second generation on everything the user hears.
+            
+                        `ExportGate` notes that `setRemoveAudio` beside a speed change is a
+                        combination Media3 warns about, and that was tried as a candidate
+                        fix for the high-rate export stall: giving the re-timing the real
+                        stream instead of silence. It made no difference to the fault — the
+                        encoder stopped at exactly the same place — so the change was
+                        reverted rather than kept for a benefit that could not be shown.
+                        See `docs/research/export-speed-stall.md`.
                       */
             forceAudioTrack: true,
             removeAudio: true,
-            emitsPerInput: cadence.emitsPerInput,
-            outputPtsUs: cadence.outputPtsUs,
+            emitsPerInput: cadence?.emitsPerInput,
+            outputPtsUs: cadence?.outputPtsUs,
             spanUs: Math.round(shard.plan.frameCount * 1e6 / fps)
           };
         });