@pictor-sdk/video-android 0.1.0

package/src/exportJob.ts

@@ -0,0 +1,232 @@
+import { VideoExportCancelled } from '@pictor-sdk/video-core'
+
+/**
+ * One export at a time, settled exactly once, cancellable anywhere.
+ *
+ * The experimental exporter blocked the bridge for a whole encode and threw
+ * from `cancel()`. That was honest — a silent no-op behind a cancel button is
+ * worse than a refusal — but it is not something a host can ship, so this is the
+ * orchestration that makes cancellation real.
+ *
+ * ## Why cancellation cannot just reject the promise
+ *
+ * A Transformer nobody is listening to still encodes, still writes and still
+ * holds its codecs. Rejecting in JavaScript would hand the host a cancelled
+ * state over an export that is still running, still filling the cache and still
+ * about to produce a file nobody is waiting for. So `cancel` reaches native
+ * first and the promise settles from the job's own checkpoints.
+ *
+ * ## Checkpoints
+ *
+ * Cancellation is cooperative. The work is a sequence of stages, each of which
+ * calls {@link ExportJob.checkpoint} on the way past, and the first checkpoint
+ * after a cancel throws. That is why the stages are named: a cancellation
+ * carries where it stopped, which is the difference between a log that says
+ * "cancelled" and one that says which resources were live at the time.
+ *
+ * ## Settling once
+ *
+ * Every path — success, failure, cancellation — clears the active job, and
+ * nothing may be delivered afterwards. A progress callback that arrives after a
+ * host has shown a result is a UI that goes backwards from "done".
+ *
+ * @experimental
+ */
+
+/** The lifecycle points an export can be stopped at. @experimental */
+export const EXPORT_STAGES = [
+  'resolving',
+  'overlays',
+  'shards',
+  'cadence',
+  'audio',
+  'concatenating',
+  'finalising',
+  'publishing',
+] as const
+
+/** @experimental */
+export type ExportStage = (typeof EXPORT_STAGES)[number]
+
+/** @experimental */
+export interface ExportJob {
+  readonly id: string
+  /**
+   * Give cancellation a chance to take effect.
+   *
+   * Throws {@link VideoExportCancelled} if the job has been cancelled. Called
+   * between stages and inside long loops, because a cancel that can only be
+   * observed when the work finishes is not a cancel.
+   */
+  checkpoint(stage: ExportStage): void
+  /** Deliver progress, unless the job has settled. */
+  progress(value: number, deliver: (value: number) => void): void
+}
+
+/** @experimental */
+export interface ExportJobsOptions {
+  /**
+   * Stop the native side of a job.
+   *
+   * Given the job id so a late cancel cannot stop a *different* export that
+   * started in the meantime.
+   */
+  cancelNative(jobId: string): void
+  /** Injected in tests. */
+  now?: () => number
+}
+
+/**
+ * The job domain's ledger.
+ *
+ * Kept apart from the native run counters on purpose. One export job drives
+ * several Transformer runs, so adding a job total to a run total produces a
+ * number that reconciles with nothing — and reads like a reconciliation, which
+ * is worse than reporting neither.
+ *
+ * @experimental
+ */
+export interface ExportJobCounts {
+  /** Jobs that began. Refused starts are not accepted jobs. */
+  accepted: number
+  succeeded: number
+  cancelled: number
+  failed: number
+  /** Exactly 0 or 1: one job at a time. */
+  active: number
+}
+
+/** @experimental */
+export interface ExportJobs {
+  /** The running job's id, or `null`. */
+  readonly active: string | null
+  /**
+   * `accepted === succeeded + cancelled + failed + active`, always.
+   *
+   * Terminal outcomes are mutually exclusive: a cancelled job is not also a
+   * failed one, however it unwound.
+   */
+  readonly counts: ExportJobCounts
+  /** Run `body` as the one active job. */
+  run<T>(body: (job: ExportJob) => Promise<T>): Promise<T>
+  /** Ask the running job to stop. Idempotent; a no-op when none is running. */
+  cancel(): void
+}
+
+let counter = 0
+
+/** @experimental */
+export function createExportJobs(options: ExportJobsOptions): ExportJobs {
+  const now = options.now ?? (() => Date.now())
+  let active: string | null = null
+  let cancelledAt: ExportStage | null = null
+  let cancelRequested = false
+  let settled = false
+  let accepted = 0
+  let succeeded = 0
+  let cancelled = 0
+  let failed = 0
+
+  const clear = () => {
+    active = null
+    cancelRequested = false
+    cancelledAt = null
+    settled = true
+  }
+
+  return {
+    get active() {
+      return active
+    },
+
+    get counts() {
+      return {
+        accepted,
+        succeeded,
+        cancelled,
+        failed,
+        active: active === null ? 0 : 1,
+      }
+    },
+
+    async run<T>(body: (job: ExportJob) => Promise<T>): Promise<T> {
+      if (active !== null) {
+        /*
+          Refused, not queued.
+
+          The native module runs one export per process. Interleaving two would
+          have them share a Transformer, a muxer and a cache directory, and the
+          first symptom would be a corrupt file rather than an error.
+        */
+        throw new Error(
+          `createMedia3VideoExporter: an export is already running (${active}); ` +
+            'cancel it before starting another',
+        )
+      }
+
+      counter += 1
+      accepted += 1
+      const id = `export_${now().toString(36)}_${counter.toString(36)}`
+      active = id
+      cancelRequested = false
+      cancelledAt = null
+      settled = false
+
+      const job: ExportJob = {
+        id,
+        checkpoint(stage) {
+          if (cancelRequested) {
+            cancelledAt = stage
+            throw new VideoExportCancelled(id, stage)
+          }
+        },
+        progress(value, deliver) {
+          if (settled || cancelRequested) return
+          deliver(value)
+        },
+      }
+
+      try {
+        const result = await body(job)
+        /*
+          A cancel that arrived while the last stage was finishing still wins.
+
+          The alternative is resolving with a file the user asked us not to
+          make, which is the outcome a cancel button exists to prevent.
+        */
+        if (cancelRequested) {
+          throw new VideoExportCancelled(id, cancelledAt ?? 'finalising')
+        }
+        clear()
+        succeeded += 1
+        return result
+      } catch (error) {
+        const wasCancelled = cancelRequested
+        const stage = cancelledAt ?? 'finalising'
+        clear()
+        if (wasCancelled) cancelled += 1
+        else failed += 1
+        if (wasCancelled) {
+          /*
+            The cancellation is the outcome, whatever the body threw.
+
+            Tearing down a Transformer mid-encode raises its own errors, and
+            reporting one of those would tell a host the export failed when the
+            user had simply stopped it.
+          */
+          if (error instanceof VideoExportCancelled) throw error
+          throw new VideoExportCancelled(id, stage)
+        }
+        throw error
+      }
+    },
+
+    cancel() {
+      // No job, nothing to stop, nothing to say. Repeated presses reach native
+      // once, because a second stop for the same job is not a second request.
+      if (active === null || cancelRequested) return
+      cancelRequested = true
+      options.cancelNative(active)
+    },
+  }
+}

package/src/exportProgress.ts

@@ -0,0 +1,391 @@
+import type { VideoExportProgress } from '@pictor-sdk/video-core'
+import type { ExportStage } from './exportJob'
+
+/**
+ * How far an export has got, and how to tell slow from stuck.
+ *
+ * ## Weighting is derived, not decided
+ *
+ * Equal percentages per stage would be a lie the bar tells: a 0.1× shard writes
+ * three hundred frames while its neighbour writes sixty, and splitting them
+ * evenly makes the first appear stuck and the second appear instant. The weights
+ * come from the work the compiler already planned — output frames per shard,
+ * audio samples, the mux — so the bar moves at the rate the encoder does.
+ *
+ * Output frames, specifically. Cadence changes how many frames a shard *writes*
+ * for a given source, and writing is what the progress is measuring the passage
+ * of; counting source frames would make slow motion look fast and fast motion
+ * look stuck.
+ *
+ * ## What 1 means
+ *
+ * One is not "the encoder finished". It is "the destination is complete and
+ * readable", which is a later moment: there is still a mux, and after that a
+ * publication. Reporting 1 at the end of encoding produces a "done" that cannot
+ * yet be opened, which is worse than a bar that sits at 97 for a moment.
+ *
+ * ## Progress and heartbeat are different signals
+ *
+ * **Progress** is completed work shown to a person, throttled to a handful of
+ * updates a second because nobody can read more than that and every update
+ * costs a bridge crossing.
+ *
+ * **Heartbeat** is evidence that work is still happening. It is not throttled,
+ * it does not have to move the visible percentage, and it is counted natively:
+ * a single muxed sample batch or a block of copied destination bytes is a
+ * heartbeat even when the bar does not visibly change for a second.
+ *
+ * Conflating them is what makes a watchdog wrong in both directions. Keyed on
+ * visible progress, a long mux or a large destination copy looks stalled
+ * because its percentage barely moves; keyed on elapsed time per stage, a 0.1×
+ * shard that legitimately runs for minutes looks stalled too. What actually
+ * marks a wedge is **silence** — no heartbeat from any source at all.
+ *
+ * @experimental
+ */
+
+/** What a shard will write. @experimental */
+export interface ShardPlan {
+  /** Output frames, after cadence. */
+  frames: number
+}
+
+/** @experimental */
+export interface ProgressPlanInput {
+  shards: readonly ShardPlan[]
+  /** Mixed audio samples the timeline will produce. Zero when silent. */
+  audioSamples: number
+  durationUs: number
+}
+
+/** Fractions of the whole export, summing to 1. @experimental */
+export interface ProgressPlan {
+  shardWeights: number[]
+  audioWeight: number
+  /** Concatenation and mux: real work, and the last thing before publication. */
+  muxWeight: number
+  /**
+   * Publication: writing the destination and making it readable.
+   *
+   * Held back deliberately so the encoded-and-muxed state cannot reach 1. A bar
+   * that fills before the file exists produces a "done" that cannot be opened,
+   * which is a worse lie than sitting at 97 for a moment.
+   */
+  publishWeight: number
+  durationUs: number
+  /** The totals the fractions are measured against. */
+  shardFrames: number[]
+  audioSamples: number
+}
+
+/**
+ * How long without a heartbeat counts as wedged.
+ *
+ * Derived from the longest silence real work produces, not from how long the
+ * platform takes to notice a wedge. The first version had that backwards — it
+ * justified twelve seconds by sitting *past* Media3's observed 10.5 s stall
+ * detection, which makes a watchdog decorative: it can only ever be the second
+ * thing to notice.
+ *
+ * The maximum legitimate heartbeat gap, measured across **three passes of seven
+ * cases** on a Pixel 7 — short and long 1×, 0.1× and 10× cadence, mixed-speed
+ * multi-clip, muted, and project audio — is **2046 ms**, in the 0.1× case. Seven
+ * seconds is 3.4× that, and 3.5 s ahead of the platform's own 10.5 s stall
+ * detection. Both margins are the point: too close to the first and it fires on
+ * healthy work, too close to the second and it is not worth having.
+ *
+ * Three passes rather than one because a single pass is not a maximum. The same
+ * 0.1× case measured 1668, 1426 and 2046 ms in three different sessions, and a
+ * threshold frozen from the lowest of those would have been derived from a run
+ * that happened to go well.
+ *
+ * ## Two corrections this number carries
+ *
+ * The first series measured 1668 ms with gate provenance hashing running — every
+ * sample of both intermediates and the result read and digested, beating as it
+ * went. A threshold calibrated against work the user never pays for is
+ * calibrated against the wrong export, so the hashing moved behind a conformance
+ * flag. The second series missed the *per-shard* hashing, which was still
+ * running. With all of it gated the worst source moved from `muxBatch` to
+ * `audioBlock`: the mux beats on its own sample batches, and once the hashing
+ * that was reading them stopped, the audio mix became the quietest stage again.
+ *
+ * ## The headroom here is small, and that is the finding
+ *
+ * 3.4× the worst gap and 3.5 s before the platform leaves roughly one doubling
+ * of the worst legitimate silence before the two constraints meet. On a slower
+ * encoder there may be no gap between them at all, which is why
+ * `Media3ExporterOptions.stallGraceMs` exists.
+ *
+ * Any of this was only measurable after the silence was instrumented rather
+ * than tolerated. Before, the maximum gap was 5.4 s and no useful threshold
+ * existed between it and the platform's timeout; the gap turned out to be the
+ * Sonic time-stretch and AAC encode inside the audio mix, which at 0.1× turn one
+ * second of source into ten with nothing beating.
+ *
+ * @experimental
+ */
+export const STALL_GRACE_MS = 7_000
+
+/** The measured maximum, kept beside the threshold it justifies. @experimental */
+export const MAX_OBSERVED_HEARTBEAT_GAP_MS = 2_046
+
+/** A unit of work, in the same currency as the weights. */
+const AUDIO_UNIT = 1 / 512
+const MUX_UNITS = 24
+const PUBLISH_UNITS = 8
+
+/** @experimental */
+export function planProgressWeights(input: ProgressPlanInput): ProgressPlan {
+  const shardUnits = input.shards.map((s) => Math.max(0, s.frames))
+  const audioUnits = input.audioSamples > 0 ? input.audioSamples * AUDIO_UNIT : 0
+  const total =
+    shardUnits.reduce((a, b) => a + b, 0) + audioUnits + MUX_UNITS + PUBLISH_UNITS
+  // The fixed mux and publish units keep this above zero, so an empty timeline
+  // weighs its publication rather than dividing by nothing.
+  return {
+    shardWeights: shardUnits.map((u) => u / total),
+    audioWeight: audioUnits / total,
+    muxWeight: MUX_UNITS / total,
+    publishWeight: PUBLISH_UNITS / total,
+    durationUs: Math.max(0, input.durationUs),
+    shardFrames: shardUnits,
+    audioSamples: Math.max(0, input.audioSamples),
+  }
+}
+
+/** @experimental */
+export interface ProgressReporterOptions {
+  plan: ProgressPlan
+  durationUs: number
+  onProgress?: (progress: VideoExportProgress) => void
+  /** Bridge crossings are bounded to roughly this spacing. */
+  throttleMs?: number
+  now?: () => number
+}
+
+/** @experimental */
+export interface ProgressReporter {
+  /** Emit 0, once, when work begins. */
+  begin(): void
+  /** Report a shard's completed output frames. */
+  shard(index: number, framesDone: number): void
+  /** Report mixed audio samples. */
+  audio(samplesDone: number): void
+  /** Concatenation and mux finished. Not 1. */
+  muxed(): void
+  /** The destination is complete and readable. Emits 1, once. */
+  complete(): void
+  /**
+   * Apply several updates and emit at most once.
+   *
+   * A poll reads every shard, the audio and the mux together, and without this
+   * the first of those spends the throttle slot and the rest are dropped until
+   * the next tick — so the last shard's frames and the whole audio mix could
+   * arrive a tick late or, at the end of an export, never. One read of native
+   * state is one update to the bar.
+   */
+  batch(body: () => void): void
+  /** Deliver nothing further. */
+  stop(): void
+}
+
+/** @experimental */
+export function createProgressReporter(options: ProgressReporterOptions): ProgressReporter {
+  const now = options.now ?? (() => Date.now())
+  const throttleMs = options.throttleMs ?? 120
+  const plan = options.plan
+  const shardDone = plan.shardWeights.map(() => 0)
+  let audioDone = 0
+  let muxDone = 0
+  let publishDone = 0
+  let highest = 0
+  let began = false
+  let finished = false
+  let stopped = false
+  let lastEmitMs = Number.NEGATIVE_INFINITY
+  let batching = 0
+  let batchForce = false
+
+  const fraction = () => {
+    let sum = 0
+    for (let i = 0; i < shardDone.length; i += 1) {
+      sum += plan.shardWeights[i]! * shardDone[i]!
+    }
+    return sum + plan.audioWeight * audioDone + plan.muxWeight * muxDone + plan.publishWeight * publishDone
+  }
+
+  const emit = (value: number, force: boolean) => {
+    /*
+      Nothing crosses before the export is declared started.
+
+      Everything that can refuse an export runs before `begin`, and a bar that
+      appears and then vanishes because a photo clip was rejected claims work
+      that never happened.
+    */
+    if (stopped || !began) return
+    if (batching > 0) {
+      // Held until the batch closes. `force` survives, because a completion
+      // inside a batch is still a completion.
+      batchForce = batchForce || force
+      return
+    }
+    /*
+      Monotonic by construction.
+
+      A native counter that restarts — a retried shard, a stage re-entered —
+      must not drag the bar backwards, so what is reported is the high-water
+      mark rather than the latest computation.
+    */
+    const next = Math.max(highest, Math.min(1, value))
+    const at = now()
+    if (!force && at - lastEmitMs < throttleMs) return
+    /*
+      A repeat is not an update.
+
+      Polling reports the same fraction every tick while a shard encodes, and
+      delivering it is a bridge crossing that tells a host nothing — measured on
+      device, a one-second export spent three of its ten callbacks re-sending 0.
+      Liveness is the heartbeat's job, and it does not go through here.
+    */
+    if (!force && began && next === highest) return
+    highest = next
+    lastEmitMs = at
+    /*
+      A host's callback is not allowed to end the export.
+
+      It runs on the caller's side and can throw for reasons that have nothing
+      to do with encoding — a render error, a disposed component. Aborting a
+      working encode because a progress indicator failed would be the wrong
+      trade in every case.
+    */
+    try {
+      options.onProgress?.({
+        progress: highest,
+        time: Math.min(plan.durationUs, Math.round(plan.durationUs * highest)),
+      })
+    } catch {
+      // Deliberately swallowed; see above.
+    }
+  }
+
+  return {
+    begin() {
+      if (began || stopped) return
+      began = true
+      emit(0, true)
+    },
+    shard(index, framesDone) {
+      if (finished || stopped) return
+      if (index < 0 || index >= shardDone.length) return
+      const total = Math.max(1, plan.shardFrames[index] ?? 1)
+      shardDone[index] = Math.max(shardDone[index]!, Math.min(1, framesDone / total))
+      emit(fraction(), false)
+    },
+    audio(samplesDone) {
+      if (finished || stopped) return
+      const total = Math.max(1, plan.audioSamples)
+      audioDone = Math.max(audioDone, Math.min(1, samplesDone / total))
+      emit(fraction(), false)
+    },
+    muxed() {
+      if (finished || stopped) return
+      muxDone = 1
+      emit(fraction(), true)
+    },
+    complete() {
+      if (finished || stopped) return
+      finished = true
+      publishDone = 1
+      emit(1, true)
+    },
+    batch(body) {
+      batching += 1
+      try {
+        body()
+      } finally {
+        batching -= 1
+      }
+      const force = batchForce
+      batchForce = false
+      emit(finished ? 1 : fraction(), force)
+    },
+    stop() {
+      stopped = true
+    },
+  }
+}
+
+/** What a wedged export looked like when it was noticed. @experimental */
+export interface StallVerdict {
+  stage: ExportStage | string
+  units: number
+  idleMs: number
+}
+
+/** @experimental */
+export interface StallWatchdogOptions {
+  thresholdMs?: number
+}
+
+/** Where a heartbeat came from, so a gap can be attributed. @experimental */
+export const HEARTBEAT_SOURCES = [
+  'videoFrame',
+  'cadence',
+  'audioBlock',
+  'muxBatch',
+  'publishBytes',
+] as const
+
+/** @experimental */
+export type HeartbeatSource = (typeof HEARTBEAT_SOURCES)[number]
+
+/** @experimental */
+export interface StallWatchdog {
+  /**
+   * Record a heartbeat. Any beat counts, whether or not it moved the bar.
+   *
+   * `units` is carried for the report only — a repeated count is still a
+   * heartbeat, because the pipeline spoke.
+   */
+  advanced(stage: ExportStage | string, units: number, atMs: number): void
+  /** The verdict if nothing has reported for the threshold, else `null`. */
+  stalledFor(atMs: number): StallVerdict | null
+}
+
+/**
+ * Slow is not stuck.
+ *
+ * Keyed on *any* report rather than on elapsed time per stage: a 0.1× export
+ * spends minutes inside one shard and is perfectly healthy while doing it, and
+ * a stage timeout would either fire on that or be too long to catch anything.
+ * What distinguishes a wedge is silence.
+ *
+ * Fires once. A wedged export is one event, and the cleanup it triggers is the
+ * same path cancellation already proved.
+ *
+ * @experimental
+ */
+export function createStallWatchdog(options: StallWatchdogOptions = {}): StallWatchdog {
+  const thresholdMs = options.thresholdMs ?? STALL_GRACE_MS
+  let lastStage: ExportStage | string | null = null
+  let lastUnits = 0
+  let lastAtMs = 0
+  let fired = false
+
+  return {
+    advanced(stage, units, atMs) {
+      lastStage = stage
+      lastUnits = units
+      lastAtMs = atMs
+    },
+    stalledFor(atMs) {
+      // Nothing has started, so nothing is stalled.
+      if (fired || lastStage === null) return null
+      const idleMs = atMs - lastAtMs
+      if (idleMs < thresholdMs) return null
+      fired = true
+      return { stage: lastStage, units: lastUnits, idleMs }
+    },
+  }
+}