@pictor-sdk/video-android 0.1.0 → 0.1.4

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

@@ -111,6 +111,72 @@ internal class ExportGate(private val context: Context) {
 
     private val main = Handler(Looper.getMainLooper())
 
+    /**
+     * The looper every Transformer is built, started and cancelled on.
+     *
+     * Not the main one, and that is the whole point. Media3 requires those
+     * three to happen on one thread with a Looper, and `Transformer.cancel()`
+     * blocks until it has joined its internal threads — on a wedged pipeline,
+     * the threads that are stuck. With the main looper as that thread, a
+     * cancelled-but-wedged export froze the app permanently: measured, the main
+     * looper ran nothing from the moment of the cancel onward, which is why the
+     * screen kept showing `Exporting… 98%` while React had already rendered the
+     * failure, and why nothing could read the app's accessibility tree.
+     *
+     * Releasing the export's waiter before calling `cancel()` was necessary and
+     * is not sufficient — it frees the *export*, not the thread. Moving the
+     * whole Transformer lifecycle here is what keeps a stuck join off the UI.
+     *
+     * One thread for the life of the gate: the contract is that build, start
+     * and cancel agree, not that each run gets its own.
+     */
+    /*
+      Replaceable, because `cancel()` is allowed not to come back.
+
+      It joins Media3's internal threads, and on a wedged pipeline those are the
+      stuck ones — so the cancel can occupy this looper indefinitely. Every
+      later run builds and starts its Transformer here too, which made one
+      unrecoverable wedge enough to hang the *next* export before it began.
+
+      So a cancel that has not returned within [CANCEL_SETTLE_MS] retires the
+      thread and the next job gets a fresh one. The retired thread is abandoned,
+      not killed: nothing can interrupt a blocked native join, and quitting its
+      looper would not either. That leaks one thread per unrecoverable wedge,
+      which is the trade — a leaked thread against an export that cannot start
+      — and [retiredTransformerThreads] counts them so it is observable rather
+      than assumed.
+    */
+    @Volatile private var transformerThread = newTransformerThread()
+
+    @Volatile private var onTransformerThread = Handler(transformerThread.looper)
+
+    private val retiredTransformerThreads = java.util.concurrent.atomic.AtomicInteger(0)
+
+    private fun newTransformerThread(): android.os.HandlerThread =
+        android.os.HandlerThread("pictor-export-transformer").apply { start() }
+
+    /**
+     * Give up on the current transformer looper and start another.
+     *
+     * Called only when a cancel posted to it has not answered in time. Idempotent
+     * against the thread it was asked to retire: a second caller that finds a
+     * different thread already in place does nothing.
+     */
+    private fun retireTransformerThread(stuck: android.os.HandlerThread) {
+        synchronized(this) {
+            if (transformerThread !== stuck) return
+            transformerThread = newTransformerThread()
+            onTransformerThread = Handler(transformerThread.looper)
+        }
+        retiredTransformerThreads.incrementAndGet()
+        android.util.Log.w(
+            "PictorExport",
+            "the transformer looper did not answer a cancel within " +
+                CANCEL_SETTLE_MS + " ms; abandoned it and started another " +
+                "(retired=" + retiredTransformerThreads.get() + ")",
+        )
+    }
+
     /**
      * Files this gate created, so a caller can prove it left none behind.
      *
@@ -141,17 +207,14 @@ internal class ExportGate(private val context: Context) {
     */
     @Volatile private var currentJob: String? = null
     @Volatile private var cancelled = false
-    @Volatile private var activeTransformer: Transformer? = null
-    /*
-      The run's latch, so a cancellation can end the wait.
-
-      `Transformer.cancel()` does not call the listener — traced: cancel entered
-      and exited on the main thread in 47 ms, and no `onCompleted` or `onError`
-      ever followed. The run's latch was therefore never counted down and the
-      export sat on `latch.await` until its timeout, which is where the seconds
-      came from once the cancel finally reached the Transformer at all.
-    */
-    @Volatile private var activeLatch: CountDownLatch? = null
+    /**
+     * The Transformer run in flight, and the latch whoever is waiting on it holds.
+     *
+     * The rules it enforces — one atomic decision, and release before stop —
+     * and what each one cost are in `RunRegistry`, where they can be tested
+     * without an Android runtime.
+     */
+    private val runs = RunRegistry<Transformer>()
 
     /**
      * Whether to hash every sample to prove the mux copied rather than encoded.
@@ -219,7 +282,35 @@ internal class ExportGate(private val context: Context) {
     fun beginJob(jobId: String): Boolean {
         synchronized(this) {
             if (currentJob != null) return false
+            /*
+              Media3's own logging, in a diagnostics build.
+
+              This package's counters stop at the edge of its own effects.
+              Whether the encoder drained, whether the muxer finalised and
+              whether the listener was ever called are Media3's to say, and
+              without this the only way to ask was to guess from a blocked
+              stack — which is how "the frame counter reached its total" got
+              mistaken for "the shard completed".
+
+              Compile-time, like every other diagnostic here: a shipped build
+              has no path to it. Built with `-PpictorDiagnostics=true`.
+            */
+            if (Diagnostics.ENABLED) {
+                androidx.media3.common.util.Log.setLogLevel(
+                    androidx.media3.common.util.Log.LOG_LEVEL_ALL,
+                )
+                startMainThreadWatch()
+            }
             currentJob = jobId
+            /*
+              At the start as well as the end.
+
+              A job that never settles never reaches `endJob`, so an end-only
+              reading is silent about exactly the runs worth counting — and
+              after a wedged export the runs that follow are the ones that do
+              not settle.
+            */
+            logResources(jobId, "begin")
             cancelled = pendingCancels.remove(jobId)
             resetHeartbeats()
             // Ownership starts here and ends in `endJob`: beats from the job
@@ -229,12 +320,46 @@ internal class ExportGate(private val context: Context) {
         }
     }
 
+    /**
+     * What this job left behind, counted at the moment it gives the job back.
+     *
+     * A responsive main thread proves the UI survived a wedged export; it says
+     * nothing about whether the export's codecs, temporary files and threads
+     * went with it. A pipeline that cannot be cancelled cleanly accumulates all
+     * three, and the symptom — the *next* export failing to get an encoder — is
+     * a long way from the cause.
+     *
+     * Thread names rather than a total: the interesting ones are Media3's own
+     * (`Transformer:Internal`, `ExoPlayer`) and this package's single
+     * `pictor-export-transformer`. A count that grows across a stall-and-retry
+     * cycle is a leak; a steady one is not.
+     *
+     * Diagnostics-only, and read-only — it allocates nothing the export needs.
+     */
+    private fun logResources(jobId: String?, at: String) {
+        if (!Diagnostics.ENABLED) return
+        val names = Thread.getAllStackTraces().keys.map { it.name }
+        fun count(prefix: String) = names.count { it.startsWith(prefix) }
+        val liveTemp = synchronized(created) { created.size }
+        android.util.Log.i(
+            "PictorResources",
+            at + " job=" + (jobId ?: "-") +
+                " codecsLive=" + CodecLedger.liveCount() +
+                " tempLive=" + liveTemp +
+                " threadsTotal=" + names.size +
+                " transformerInternal=" + count("Transformer:Internal") +
+                " exoPlayer=" + count("ExoPlayer") +
+                " pictorExport=" + count("pictor-export"),
+        )
+    }
+
     /** Give the job back, whatever happened to it. */
     fun endJob() {
+        logResources(currentJob, "end  ")
         synchronized(this) {
             currentJob = null
             cancelled = false
-            activeTransformer = null
+            runs.clear()
             ExportHeartbeat.detach()
             ExportProgress.end()
         }
@@ -256,16 +381,60 @@ internal class ExportGate(private val context: Context) {
             }
             cancelled = true
         }
-        val running = activeTransformer
-        if (running != null) {
-            // Transformer is main-thread only; cancelling from the export's own
-            // worker would be the same crash this gate wraps elsewhere.
-            main.post {
-                runCatching { running.cancel() }
-                // `cancel()` is silent, so the waiter is released here. Without
-                // this the run waits out its whole timeout after being stopped.
-                activeLatch?.countDown()
+        /*
+          The registry releases the waiter, then hands the Transformer back to
+          be stopped. Transformer is main-thread only, so stopping it is a post;
+          the release already happened and does not wait for it.
+
+          Counting down a latch whose run then completes normally is harmless:
+          the waiter reports from `result`, `failure` and `cancelledEarly`, and
+          `cancelled` is what makes this outcome a cancellation.
+        */
+        /*
+          Stopped on the main looper, and how long that blocks is measured.
+
+          Releasing the waiter first stops the *export* waiting on `cancel()`.
+          It does nothing about the thread `cancel()` runs on: Media3 requires
+          it on the thread the Transformer was built on, which here is main, and
+          it blocks until Media3 joins its internal threads. On a wedged
+          pipeline those are the stuck ones.
+
+          Moving it off main would break that contract, so it stays — and the
+          duration is logged instead, because "the UI freezes during a cancel"
+          is a claim that needs a number rather than an argument. The
+          architectural answer, if the number is bad, is to build the
+          Transformer on its own looper thread so `cancel()` blocks that one;
+          that is a larger change than a cancel path should make on its own.
+        */
+        runs.cancel { transformer ->
+            val thread = transformerThread
+            val returned = CountDownLatch(1)
+            onTransformerThread.post {
+                val startedNs = System.nanoTime()
+                runCatching { transformer.cancel() }
+                returned.countDown()
+                val ms = (System.nanoTime() - startedNs) / 1_000_000
+                if (ms > MAIN_BLOCK_WARN_MS) {
+                    android.util.Log.w(
+                        "PictorExportCancel",
+                        "Transformer.cancel() took " + ms + " ms — off the UI thread",
+                    )
+                }
             }
+            /*
+              Watched from a third thread, so neither the caller nor the looper
+              waits on it.
+
+              This method is called from the JavaScript thread. Blocking it for
+              seconds would be a frozen app, and blocking it for a cancel that
+              never returns would be a dead one — so the settle is somebody
+              else's job, and all the caller gets is the return.
+            */
+            Thread({
+                if (!returned.await(CANCEL_SETTLE_MS, TimeUnit.MILLISECONDS)) {
+                    retireTransformerThread(thread)
+                }
+            }, "pictor-cancel-settle").apply { isDaemon = true }.start()
         }
         return true
     }
@@ -382,6 +551,102 @@ internal class ExportGate(private val context: Context) {
      * without incrementing the counter is what made the ledger disagree with the
      * disk, so the three steps do not exist separately.
      */
+    /**
+     * Wait for a terminal signal, saying what is happening while it does not come.
+     *
+     * The wait itself is unchanged — the same deadline, the same answer. What is
+     * added is that a run which is going to take ten minutes to report a timeout
+     * says so on the way, with the counters that separate the two cases anyone
+     * cares about: **slow** and **stuck**.
+     *
+     * That distinction is not available anywhere else. The stall watchdog on the
+     * JavaScript side is keyed on *any* report, deliberately — a 0.1x shard
+     * spends minutes inside one frame budget and is healthy — so a stage that
+     * keeps emitting keeps the watchdog quiet however wrong the emission is.
+     * When that happens the only evidence that existed was a progress bar that
+     * stopped moving, which is equally consistent with a slow encoder.
+     *
+     * Deliberately not a second watchdog. It changes no outcome and cancels
+     * nothing; it is the log line that makes the difference visible.
+     */
+    private fun awaitWithReport(
+        latch: CountDownLatch,
+        timeoutSeconds: Long,
+        stage: String,
+        counters: () -> String,
+    ): BoundedWait.Outcome =
+        BoundedWait.await(
+            timeoutMs = timeoutSeconds * 1_000L,
+            sliceMs = REPORT_EVERY_MS,
+            nowMs = { System.nanoTime() / 1_000_000 },
+            awaitSlice = { ms -> latch.await(ms, TimeUnit.MILLISECONDS) },
+            /*
+              The flag, not only the latch.
+
+              A cancel releases the waiter when it finds a published run. When
+              it does not — the composition is still being built, or the run has
+              already been cleared — there is no latch to count down, and the
+              wait used to sit out its entire deadline with `cancelled` true
+              beside it, printing that flag every four seconds. Measured six
+              times: a stall reported in seven seconds, settled 600 010 ms
+              later.
+            */
+            cancelled = { cancelled },
+            onSlice = { waitedMs ->
+                android.util.Log.i(
+                    "PictorExportWait",
+                    "stage=" + stage + " waitedMs=" + waitedMs +
+                        " cancelled=" + cancelled + " " + counters(),
+                )
+            },
+        )
+
+    /**
+     * Whether the main looper is still running anything, watched from off it.
+     *
+     * The first version of this posted a runnable and logged how late it ran.
+     * That can only report a looper that is *slow*: a looper that is **blocked**
+     * runs nothing, so the check never executes and the log stays empty — and
+     * empty was read as healthy. It is the same mistake as reading a frame
+     * counter that reached its total as a finished shard.
+     *
+     * So the main thread only stamps a clock, and a plain daemon thread decides
+     * whether that stamp has gone stale. Silence from the looper now produces a
+     * line instead of the absence of one.
+     *
+     * Diagnostics-only, and bounded: it outlives the job because the interesting
+     * moment is after the export settles, but it does not outlive the run.
+     */
+    private fun startMainThreadWatch() {
+        val lastTickMs = java.util.concurrent.atomic.AtomicLong(System.currentTimeMillis())
+        val untilMs = System.currentTimeMillis() + WATCH_FOR_MS
+        val stamp = object : Runnable {
+            override fun run() {
+                lastTickMs.set(System.currentTimeMillis())
+                if (System.currentTimeMillis() < untilMs) main.postDelayed(this, 250)
+            }
+        }
+        main.post(stamp)
+
+        Thread({
+            var reported = false
+            while (System.currentTimeMillis() < untilMs) {
+                Thread.sleep(250)
+                val staleMs = System.currentTimeMillis() - lastTickMs.get()
+                if (staleMs > MAIN_BLOCK_WARN_MS && !reported) {
+                    reported = true
+                    android.util.Log.w(
+                        "PictorMainThread",
+                        "the main looper has run nothing for " + staleMs + " ms",
+                    )
+                } else if (staleMs <= MAIN_BLOCK_WARN_MS && reported) {
+                    reported = false
+                    android.util.Log.w("PictorMainThread", "the main looper is answering again")
+                }
+            }
+        }, "pictor-main-watch").apply { isDaemon = true }.start()
+    }
+
     private fun releaseTemp(file: File) {
         runCatching { file.delete() }
         synchronized(created) { if (created.remove(file)) tempFilesReleased.incrementAndGet() }
@@ -1354,6 +1619,7 @@ internal class ExportGate(private val context: Context) {
 
         val startedNs = System.nanoTime()
         val latch = CountDownLatch(1)
+        val handle = RunRegistry.Handle<Transformer>(latch)
         var result: ExportResult? = null
         var failure: ExportException? = null
         var buildFailure: Throwable? = null
@@ -1361,7 +1627,7 @@ internal class ExportGate(private val context: Context) {
         // not a failure either: `finishRun` reads this and the cancel flag.
         var cancelledEarly = false
 
-        main.post {
+        onTransformerThread.post {
             try {
             val builder = EditedMediaItemSequence.Builder()
             builder.experimentalSetForceAudioTrack(true)
@@ -1412,14 +1678,21 @@ internal class ExportGate(private val context: Context) {
             val composition = Composition.Builder(builder.build()).build()
             val transformer = Transformer.Builder(context)
                 .addListener(object : Transformer.Listener {
+                    /*
+                      Scoped to this run's handle, because a listener can arrive
+                      late. `Transformer.cancel()` never calls it, so a wedged
+                      run's listener may fire long after the export that owned
+                      it gave up — by which time a newer one has published
+                      itself. An unscoped clear forgot the *new* run, and the
+                      next cancel then found nothing to stop and nothing to
+                      release.
+                    */
                     override fun onCompleted(c: Composition, r: ExportResult) {
-                        activeTransformer = null
-                        activeLatch = null
+                        runs.clear(handle)
                         result = r; latch.countDown()
                     }
                     override fun onError(c: Composition, r: ExportResult, e: ExportException) {
-                        activeTransformer = null
-                        activeLatch = null
+                        runs.clear(handle)
                         result = r; failure = e; latch.countDown()
                     }
                 })
@@ -1434,15 +1707,23 @@ internal class ExportGate(private val context: Context) {
               cancel issued before any native work still took 4.7 s to settle,
               which is the whole of the first shard.
             */
-            if (cancelled) {
+            /*
+              Published under the lock a cancel takes, so the two cannot cross.
+
+              Checking `cancelled` and then assigning was two steps with a gap,
+              and a cancel arriving inside it found no transformer to stop and
+              no latch to release while the run it was meant to stop started
+              anyway.
+            */
+            if (cancelled) runs.refuse(handle)
+            val started = runs.publish(handle, transformer)
+            if (!started) {
                 // Not counted here. `finishRun` is the only place a run reaches
                 // a terminal outcome, so it cannot be counted twice.
                 cancelledEarly = true
                 latch.countDown()
                 return@post
             }
-            activeTransformer = transformer
-            activeLatch = latch
             transformer.start(composition, output.absolutePath)
             } catch (e: Throwable) {
                 /*
@@ -1457,9 +1738,13 @@ internal class ExportGate(private val context: Context) {
             }
         }
 
-        val finished = latch.await(timeoutSeconds, TimeUnit.SECONDS)
+        // Bounded the same way the shard wait is, and for the same reason: a
+        // cancel that finds no published run has no latch to release, and this
+        // one would otherwise sit out its whole deadline knowing it was over.
+        val waited = awaitWithReport(latch, timeoutSeconds, "mix") { "" }
         val elapsedMs = (System.nanoTime() - startedNs) / 1_000_000
-        val ok = finished && failure == null && buildFailure == null && !cancelledEarly
+        val ok = waited == BoundedWait.Outcome.Settled &&
+            failure == null && buildFailure == null && !cancelledEarly
         if (!ok) {
             releaseTemp(output)
         }
@@ -1471,7 +1756,9 @@ internal class ExportGate(private val context: Context) {
             error = when {
                 buildFailure != null -> "audio composition rejected: " +
                     buildFailure!!.javaClass.simpleName + ": " + buildFailure!!.message
-                !finished -> "audio timeline timed out after ${'$'}timeoutSeconds s"
+                waited == BoundedWait.Outcome.Cancelled -> "cancelled"
+                waited == BoundedWait.Outcome.TimedOut ->
+                    "audio timeline timed out after ${'$'}timeoutSeconds s"
                 failure != null -> "${'$'}{failure!!.errorCode}: ${'$'}{failure!!.message}"
                 else -> ""
             },
@@ -1562,6 +1849,7 @@ internal class ExportGate(private val context: Context) {
 
         val startedNs = System.nanoTime()
         val latch = CountDownLatch(1)
+        val handle = RunRegistry.Handle<Transformer>(latch)
         var result: ExportResult? = null
         var failure: ExportException? = null
         // A shard stopped before its Transformer started is neither a success
@@ -1576,7 +1864,7 @@ internal class ExportGate(private val context: Context) {
                 null
             }
 
-        main.post {
+        onTransformerThread.post {
             val effects: ImmutableList<Effect> =
                 if (probe == null) ImmutableList.of() else ImmutableList.of(probe as Effect)
             val builder = EditedMediaItemSequence.Builder()
@@ -1680,7 +1968,30 @@ internal class ExportGate(private val context: Context) {
                 val speedVideo: Effect? = null
                 if (item != null && item.speed != 1f) {
                     edited.setSpeed(ConstantSpeed(item.speed))
-                    if (item.speedMode != "resample") {
+                    /*
+                      Not on a track that is thrown away — and that track is
+                      what wedges the export.
+
+                      Measured with `GateLadder` at a configured 6.122448979591837
+                      on a Pixel 7: `speed + cadence + skia` completes in 644 ms
+                      with the contract's 29 frames. Add the channel mixer and it
+                      still completes, in 776 ms. Add *this* processor instead and
+                      the run never finishes — 90 s timeout, the rung's thread
+                      still alive afterwards, and a cadence trace reading
+                      `emitted=29 endIn=1 endOut=1 glCreated=1 glDeleted=0`:
+                      every frame delivered, end-of-stream seen at both ends, and
+                      the pipeline never shut down.
+
+                      It also bought nothing here. A shard's own audio is removed
+                      and a silent track forced in its place, purely so Media3's
+                      speed path has something to re-time; the final mux takes
+                      only this pipeline's *video*. What a person actually hears
+                      is stretched by `AudioMixer.stretch`, which runs Sonic over
+                      the real PCM and preserves pitch there. So the correction
+                      stays where it is audible and leaves the path where it is
+                      silent, discarded, and fatal.
+                    */
+                    if (item.speedMode != "resample" && !item.removeAudio) {
                         /*
                           Media3 re-times audio by **resampling** it, on both
                           public paths: `setSpeed` and
@@ -1781,9 +2092,14 @@ internal class ExportGate(private val context: Context) {
                     }
                 }
                 .addListener(object : Transformer.Listener {
+                    /*
+                      Scoped to this run's handle. See the same guard on the mix
+                      sequence: a wedged run's listener can arrive after a newer
+                      export has published itself here, and clearing that one
+                      would leave it uncancellable.
+                    */
                     override fun onCompleted(composition: Composition, exportResult: ExportResult) {
-                        activeTransformer = null
-                        activeLatch = null
+                        runs.clear(handle)
                         result = exportResult
                         latch.countDown()
                     }
@@ -1793,8 +2109,7 @@ internal class ExportGate(private val context: Context) {
                         exportResult: ExportResult,
                         exportException: ExportException,
                     ) {
-                        activeTransformer = null
-                        activeLatch = null
+                        runs.clear(handle)
                         failure = exportException
                         latch.countDown()
                     }
@@ -1812,13 +2127,14 @@ internal class ExportGate(private val context: Context) {
               and was caught by the next stage check, which is where the seconds
               came from.
             */
-            if (cancelled) {
+            // Published under the lock a cancel takes: see the sibling site above.
+            if (cancelled) runs.refuse(handle)
+            val started = runs.publish(handle, transformer)
+            if (!started) {
                 cancelledEarly = true
                 latch.countDown()
                 return@post
             }
-            activeTransformer = transformer
-            activeLatch = latch
             runCatching { transformer.start(composition, output.absolutePath) }
                 .onFailure {
                     failure = ExportException.createForUnexpected(RuntimeException(it))
@@ -1826,9 +2142,13 @@ internal class ExportGate(private val context: Context) {
                 }
         }
 
-        val finished = latch.await(timeoutSeconds, TimeUnit.SECONDS)
+        val waited = awaitWithReport(latch, timeoutSeconds, "shard") {
+            "cadence=" + (cadence?.trace() ?: "none") +
+                " skiaFrames=" + (probe?.framesSeen()?.toString() ?: "none")
+        }
         val elapsedMs = (System.nanoTime() - startedNs) / 1_000_000
-        val ok = finished && failure == null && result != null && !cancelledEarly
+        val ok = waited == BoundedWait.Outcome.Settled &&
+            failure == null && result != null && !cancelledEarly
 
         if (!ok) {
             // A failed gate leaves no partial file. Transformer writes as it
@@ -1840,7 +2160,21 @@ internal class ExportGate(private val context: Context) {
                 ok = false,
                 uri = "",
                 error = when {
-                    !finished -> "timeout after ${timeoutSeconds}s"
+                    /*
+                      A deadline that expired outranks a cancellation, and the
+                      order says so.
+
+                      A run that waited out its whole deadline has to report
+                      that, even if a cancel was also requested along the way —
+                      the two are different failures and only one of them means
+                      the platform stopped answering. What changed is that the
+                      wait now distinguishes them itself: `TimedOut` is only
+                      returned when the time genuinely ran out with no cancel,
+                      so a cancelled export no longer arrives here wearing a
+                      timeout it did not have.
+                    */
+                    waited == BoundedWait.Outcome.TimedOut ->
+                        "timeout after ${timeoutSeconds}s"
                     failure != null -> buildString {
                         append(failure!!.errorCode).append(": ").append(failure!!.message)
                         // The message alone says "Video frame processing error"
@@ -1855,6 +2189,16 @@ internal class ExportGate(private val context: Context) {
                             depth += 1
                         }
                     }
+                    /*
+                      Released by a cancel, with nothing to show for the run.
+
+                      Reported as the cancellation it is rather than as "no
+                      result": the waiter is now released *before* the
+                      Transformer is stopped, so reaching here with no result is
+                      the ordinary shape of a cancelled run, not an anomaly.
+                    */
+                    waited == BoundedWait.Outcome.Cancelled ||
+                        cancelledEarly || cancelled -> "cancelled"
                     else -> "no result"
                 },
                 elapsedMs = elapsedMs,
@@ -1969,6 +2313,39 @@ internal class ExportGate(private val context: Context) {
     }
 
     private companion object {
+        /**
+         * How often a wait that has not settled reports itself.
+         *
+         * Long enough that a healthy export logs a handful of lines, short
+         * enough that two consecutive lines show whether the counters moved —
+         * which is the whole question.
+         */
+        const val REPORT_EVERY_MS = 4_000L
+
+        /**
+         * A main-thread block worth naming.
+         *
+         * Well past a dropped frame and well under a platform ANR, so the log
+         * carries the cancels that a person would actually feel and stays quiet
+         * for the ones they would not.
+         */
+        const val MAIN_BLOCK_WARN_MS = 250L
+
+        /**
+         * How long a posted `Transformer.cancel()` gets before its looper is
+         * abandoned.
+         *
+         * Not a guess at how long a healthy cancel takes — a healthy one is
+         * milliseconds, and the measured unhealthy one never returns at all.
+         * This is how long the *next* export is willing to wait before it stops
+         * caring: three seconds is far past anything legitimate and far short of
+         * a person deciding the app is broken.
+         */
+        const val CANCEL_SETTLE_MS = 3_000L
+
+        /** How long the looper watch outlives the job that started it. */
+        const val WATCH_FOR_MS = 180_000L
+
         const val TEMP_PREFIX = "pictor-gate-"
     }
 }

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()