@pictor-sdk/video-android 0.1.0

package/src/exportProgressPump.ts

@@ -0,0 +1,190 @@
+import type { VideoExportProgress } from '@pictor-sdk/video-core'
+import type { ExportStage } from './exportJob'
+import {
+  STALL_GRACE_MS,
+  createProgressReporter,
+  createStallWatchdog,
+  type ProgressPlan,
+  type StallVerdict,
+} from './exportProgress'
+
+/**
+ * Reading native counters, and turning them into a progress stream.
+ *
+ * The native run is one call that resolves when the whole export is done, so
+ * there is nothing to subscribe to: progress has to be *read*. That is the whole
+ * reason this exists as a pump rather than an event stream, and it is also why
+ * the two signals stay separate on either side of the boundary.
+ *
+ * **Natively, nothing is throttled.** Every emitted frame, every block of mixed
+ * audio and every muxed sample batch increments a counter or beats, at whatever
+ * rate the encoder runs. Throttling there would be throttling the evidence.
+ *
+ * **Across the bridge, everything is throttled.** This polls at 8 Hz and the
+ * reporter emits at most that often, because nobody can read a progress bar
+ * faster and every update costs a crossing. A 0.1× export that beats a thousand
+ * times a second still produces eight callbacks.
+ *
+ * The watchdog reads the *beat total* rather than the progress fraction. A long
+ * mux moves the bar by almost nothing while beating steadily, and treating that
+ * as a stall would kill a healthy export — which is the failure mode the
+ * separation exists to prevent.
+ *
+ * @experimental
+ */
+
+/** What native reports about work completed so far. @experimental */
+export interface ProgressSnapshot {
+  /** Output frames written, per shard index. */
+  shards: readonly number[]
+  /** Mixed audio samples handed to the encoder. */
+  audioSamples: number
+  /** What `audioSamples` counts up to. Zero before the mix starts. */
+  audioPlanned: number
+  /** Concatenation and mux finished. */
+  muxed: boolean
+  /**
+   * Every heartbeat from every source, summed.
+   *
+   * Liveness only. It is deliberately not a work total — a mux batch and an
+   * output frame are not the same amount of anything — so it feeds the watchdog
+   * and never the bar.
+   */
+  beats: number
+}
+
+/** @experimental */
+export interface ProgressPumpOptions {
+  plan: ProgressPlan
+  durationUs: number
+  /** Read the native counters. Called on every tick. */
+  read(): ProgressSnapshot
+  onProgress?: (progress: VideoExportProgress) => void
+  /** Called once, when nothing has reported for the threshold. */
+  onStall(verdict: StallVerdict): void
+  /** Bridge delivery rate. 125 ms is 8 Hz. */
+  pollMs?: number
+  thresholdMs?: number
+  now?: () => number
+}
+
+/** @experimental */
+export interface ProgressPump {
+  /** Emit `{ progress: 0, time: 0 }`, once. */
+  begin(): void
+  /** Read native once and report what changed. */
+  tick(): void
+  /**
+   * The destination is closed and verified readable. Emits 1, once.
+   *
+   * Separate from the mux on purpose: a bar that fills when the encoder stops
+   * produces a "done" over a file that cannot yet be opened.
+   */
+  complete(): void
+  /** Deliver nothing further, whatever arrives. */
+  stop(): void
+  /** How often {@link tick} expects to be called. */
+  readonly pollMs: number
+}
+
+/**
+ * Where the export was when it went quiet.
+ *
+ * Derived from what has finished rather than from a native stage string, so a
+ * stall report cannot claim a stage the counters contradict.
+ */
+function stageOf(snapshot: ProgressSnapshot, plan: ProgressPlan): ExportStage {
+  if (snapshot.muxed) return 'publishing'
+  const shardsDone = plan.shardFrames.every(
+    (total, index) => (snapshot.shards[index] ?? 0) >= total,
+  )
+  if (!shardsDone) return 'shards'
+  if (snapshot.audioPlanned > 0 && snapshot.audioSamples < snapshot.audioPlanned) return 'audio'
+  return 'concatenating'
+}
+
+/** @experimental */
+export function createProgressPump(options: ProgressPumpOptions): ProgressPump {
+  const now = options.now ?? (() => Date.now())
+  const pollMs = options.pollMs ?? 125
+  const plan = options.plan
+  const reporter = createProgressReporter({
+    plan,
+    durationUs: options.durationUs,
+    onProgress: options.onProgress,
+    // The reporter's own throttle is the poll interval: a tick that finds
+    // nothing new should not be able to spend a crossing saying so.
+    throttleMs: pollMs,
+    now,
+  })
+  const watchdog = createStallWatchdog({ thresholdMs: options.thresholdMs ?? STALL_GRACE_MS })
+  let lastBeats = -1
+  let stopped = false
+  let stalled = false
+
+  return {
+    pollMs,
+
+    begin() {
+      reporter.begin()
+      // Seeded here rather than on the first tick. Without it the threshold
+      // would be measured from whenever polling happened to start, which for a
+      // slow first shard is a different moment from when work began.
+      watchdog.advanced('resolving', 0, now())
+    },
+
+    tick() {
+      if (stopped || stalled) return
+      const snapshot = options.read()
+      /*
+        One read of native state is one update to the bar.
+
+        Without the batch the first shard spends the throttle slot and the rest
+        — including the whole audio mix — are dropped until the next tick, so
+        the last thing to change before an export ends could never be delivered
+        at all.
+      */
+      reporter.batch(() => {
+        for (let i = 0; i < plan.shardFrames.length; i += 1) {
+          reporter.shard(i, snapshot.shards[i] ?? 0)
+        }
+        if (snapshot.audioPlanned > 0 && plan.audioSamples > 0) {
+          /*
+          Rescaled rather than counted twice.
+
+          Native counts interleaved samples at its own rate and channel count;
+          the plan counts what the compiler predicted. Passing native's number
+          straight through would weight audio by whichever of the two happened
+          to be larger, so what crosses is the fraction.
+        */
+          const fraction = Math.min(1, snapshot.audioSamples / snapshot.audioPlanned)
+          reporter.audio(plan.audioSamples * fraction)
+        }
+        if (snapshot.muxed) reporter.muxed()
+      })
+
+      const at = now()
+      if (snapshot.beats !== lastBeats) {
+        lastBeats = snapshot.beats
+        watchdog.advanced(stageOf(snapshot, plan), snapshot.beats, at)
+      }
+      const verdict = watchdog.stalledFor(at)
+      if (verdict) {
+        // Once. The export is torn down from here and there is nothing further
+        // to observe; continuing to poll a dead run would report it again.
+        stalled = true
+        options.onStall(verdict)
+      }
+    },
+
+    complete() {
+      if (stopped) return
+      reporter.complete()
+    },
+
+    stop() {
+      stopped = true
+      reporter.stop()
+    },
+  }
+}