@pictor-sdk/video-android 0.1.0

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

@@ -0,0 +1,72 @@
+package dev.pictor.video
+
+import java.util.concurrent.atomic.AtomicLong
+
+/**
+ * Evidence that an export is still working, as distinct from how far it has got.
+ *
+ * Progress is what a person sees, throttled to a few updates a second because
+ * that is all anyone can read. A heartbeat is not throttled and does not have to
+ * move the visible percentage: one muxed sample batch, one repeated cadence
+ * copy, one block of copied bytes. Keeping the two apart is what stops a long
+ * mux from looking stalled because its percentage barely moves, and a 0.1x shard
+ * from looking stalled because it legitimately runs for minutes.
+ *
+ * ## Beats are owned
+ *
+ * A process-wide sink with no identity is a hazard: a decoder thread from a run
+ * that has already been released can still be unwinding, and its beat would land
+ * on whatever job happens to be current — keeping a genuinely stalled export
+ * alive with the dying breaths of the previous one. That is the exact failure a
+ * watchdog exists to catch, so beats carry the epoch of the work that produced
+ * them and a beat from any other epoch is discarded.
+ *
+ * Producers capture the epoch once, when they start, and hand it back with every
+ * beat. They never read the current epoch at beat time — that would defeat the
+ * check by construction.
+ *
+ * ## No fabricated liveness
+ *
+ * Nothing here beats on a timer. A "still alive" tick from a scheduler would
+ * keep the watchdog quiet precisely when a worker is blocked, which is the one
+ * situation it is meant to report. Every beat is a piece of work that happened
+ * or a blocking step that completed.
+ */
+internal object ExportHeartbeat {
+    private val epoch = AtomicLong(0)
+
+    @Volatile private var sink: ((String) -> Unit)? = null
+
+    /**
+     * Take ownership for a new job.
+     *
+     * Returns the epoch producers must carry. Bumped rather than reused so beats
+     * already in flight from the previous job cannot be mistaken for this one's.
+     */
+    fun attach(to: (String) -> Unit): Long {
+        val next = epoch.incrementAndGet()
+        sink = to
+        return next
+    }
+
+    /** Give it up. Beats afterwards are ignored until the next `attach`. */
+    fun detach() {
+        epoch.incrementAndGet()
+        sink = null
+    }
+
+    /** The epoch a producer should capture when it starts. */
+    fun currentEpoch(): Long = epoch.get()
+
+    /**
+     * Record a beat from `source`, on behalf of `atEpoch`.
+     *
+     * Ignored when nothing is exporting, and ignored when the epoch is not the
+     * current one — a late beat from a released run proves nothing about the job
+     * running now.
+     */
+    fun beat(source: String, atEpoch: Long) {
+        if (atEpoch != epoch.get()) return
+        sink?.invoke(source)
+    }
+}

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

@@ -0,0 +1,103 @@
+package dev.pictor.video
+
+import org.json.JSONArray
+import org.json.JSONObject
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.atomic.AtomicLong
+
+/**
+ * Completed work, counted where it happens.
+ *
+ * The sibling of [ExportHeartbeat], and deliberately not the same thing. A beat
+ * says the pipeline is alive; these counters say how much of the export exists.
+ * A long mux beats hundreds of times and completes one unit of work, so a bar
+ * driven by beats would race, and a watchdog driven by these counters would kill
+ * a healthy 0.1× shard.
+ *
+ * Owned by the same epoch as the heartbeat, for the same reason: the export
+ * before this one may still have a shader program running on a thread Media3
+ * has not finished with, and a frame it emits must not be credited to the job
+ * that is running now. Ownership is taken in `ExportGate.beginJob` and given
+ * back in `endJob`; anything arriving on an older epoch is dropped.
+ *
+ * Read across the bridge by polling rather than pushed, because the native run
+ * is one call that resolves at the end. Counting here is unthrottled; the
+ * throttle belongs on the JavaScript side, where the crossings are.
+ */
+internal object ExportProgress {
+    /** The epoch these counters belong to, or -1 when no job owns them. */
+    @Volatile private var activeEpoch: Long = -1L
+
+    private val shardFrames = ConcurrentHashMap<Int, AtomicLong>()
+    @Volatile private var currentShard: Int = -1
+    private val audioSamples = AtomicLong(0)
+    private val audioPlanned = AtomicLong(0)
+    @Volatile private var muxed: Boolean = false
+
+    fun begin(epoch: Long) {
+        synchronized(this) {
+            shardFrames.clear()
+            currentShard = -1
+            audioSamples.set(0)
+            audioPlanned.set(0)
+            muxed = false
+            activeEpoch = epoch
+        }
+    }
+
+    fun end() {
+        synchronized(this) { activeEpoch = -1L }
+    }
+
+    private fun owned(atEpoch: Long): Boolean = atEpoch == activeEpoch
+
+    /**
+     * Which shard the frames arriving now belong to.
+     *
+     * Shards run one at a time, so the producer does not have to know its own
+     * index — which is just as well, because a `GlShaderProgram` is constructed
+     * by Media3 and told nothing about the timeline.
+     */
+    fun enterShard(index: Int, atEpoch: Long) {
+        if (!owned(atEpoch)) return
+        currentShard = index
+    }
+
+    fun frame(atEpoch: Long) {
+        if (!owned(atEpoch)) return
+        val shard = currentShard
+        if (shard < 0) return
+        shardFrames.getOrPut(shard) { AtomicLong(0) }.incrementAndGet()
+    }
+
+    /** Mixed samples handed to the encoder, and what they count up to. */
+    fun audio(done: Long, planned: Long, atEpoch: Long) {
+        if (!owned(atEpoch)) return
+        audioPlanned.set(planned)
+        // Monotonic here as well as in the reporter: the encoder's input offset
+        // is already monotonic, but a retried mix would restart it.
+        while (true) {
+            val seen = audioSamples.get()
+            if (done <= seen || audioSamples.compareAndSet(seen, done)) break
+        }
+    }
+
+    fun muxed(atEpoch: Long) {
+        if (!owned(atEpoch)) return
+        muxed = true
+    }
+
+    /** `shards` is dense from 0, so a shard that has emitted nothing reads 0. */
+    fun snapshotJson(beats: Long): String {
+        val highest = shardFrames.keys.maxOrNull() ?: -1
+        val shards = JSONArray()
+        for (i in 0..highest) shards.put(shardFrames[i]?.get() ?: 0L)
+        return JSONObject()
+            .put("shards", shards)
+            .put("audioSamples", audioSamples.get())
+            .put("audioPlanned", audioPlanned.get())
+            .put("muxed", muxed)
+            .put("beats", beats)
+            .toString()
+    }
+}