@pictor-sdk/video-android 0.1.0

package/src/previewMix.ts

@@ -0,0 +1,212 @@
+import { requireNative } from './player'
+
+/**
+ * The audio a preview plays.
+ *
+ * ## Preparation, not playback
+ *
+ * A preview mix is produced by the same code an export runs: every contributing
+ * source is decoded, re-timed by its clip's speed, ramped, summed and saturated
+ * once, then encoded. That takes real time proportional to the project, and no
+ * amount of naming it "preview" makes it realtime. A caller has to show that it
+ * is preparing and must not pretend otherwise.
+ *
+ * ## Why not mix in the player
+ *
+ * Because then there would be two definitions of what a project sounds like,
+ * and the one a person hears while editing would be the one that was never
+ * tested against an export. Gain, fades, trims, speed and overlap are decided
+ * by `compileAudioMixProgram` and executed by `AudioMixer` — here and in the
+ * exporter, from the same plan.
+ *
+ * ## Superseding
+ *
+ * One job at a time. A newer request cancels the one in flight, which unwinds
+ * at its next checkpoint, deletes its partial and reports `superseded`. A
+ * superseded result is not a failure and must never be published: it is the
+ * answer to a question nobody is asking any more.
+ *
+ * @experimental
+ */
+
+/** A prepared mix. @experimental */
+export interface PreparedMix {
+  ok: true
+  /** A `file://` URI in app-private storage. */
+  uri: string
+  /** The content key: mix program, sources and mixer configuration. */
+  key: string
+  /** True when nothing had to be encoded — the file was already there. */
+  cached: boolean
+  byteLength: number
+  /**
+   * Where the time went, when it was actually prepared.
+   *
+   * Milliseconds per stage and frames per source. Absent for a cached mix,
+   * which did no work to attribute.
+   */
+  profile?: {
+    stageMs: Record<string, number>
+    counts: Record<string, number>
+    sources: Record<string, Record<string, number>>
+  }
+}
+
+/** @experimental */
+export type PreviewMixResult =
+  | PreparedMix
+  /** A newer request replaced this one. Not a failure; never publish it. */
+  | { ok: false; superseded: true; key: string }
+  /** It ran and failed. The reason is diagnostic and may name a path. */
+  | { ok: false; superseded?: false; key?: string; reason: string }
+
+/**
+ * Prepare the mix for a compiled program, or hand back the one already
+ * prepared.
+ *
+ * `urisJson` maps span id to a resolved, durable source URI — the same
+ * resolution an export performs, so the two agree about which file a span
+ * means.
+ *
+ * Never rejects: a mix that cannot be produced is an outcome.
+ *
+ * @experimental
+ */
+export async function preparePreviewMix(
+  jobId: string,
+  programJson: string,
+  urisJson: string,
+): Promise<PreviewMixResult> {
+  let raw: string
+  try {
+    raw = await requireNative().previewMixPrepare(jobId, programJson, urisJson)
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) }
+  }
+
+  let value: Record<string, unknown>
+  try {
+    value = JSON.parse(raw) as Record<string, unknown>
+  } catch {
+    return { ok: false, reason: 'native returned unparseable JSON' }
+  }
+
+  if (value.ok === true) {
+    return {
+      ok: true,
+      uri: String(value.uri ?? ''),
+      key: String(value.key ?? ''),
+      cached: value.cached === true,
+      byteLength: Number(value.byteLength ?? 0),
+      ...(value.profile ? { profile: value.profile as PreparedMix['profile'] } : {}),
+    }
+  }
+  if (value.superseded === true) {
+    return { ok: false, superseded: true, key: String(value.key ?? '') }
+  }
+  return {
+    ok: false,
+    ...(typeof value.key === 'string' ? { key: value.key } : {}),
+    reason: typeof value.error === 'string' ? value.error : 'the mix could not be prepared',
+  }
+}
+
+/**
+ * Stop whatever is preparing.
+ *
+ * Safe to call when nothing is: cancelling twice, or cancelling after a job
+ * already finished, is how a caller's teardown paths overlap on purpose.
+ *
+ * @experimental
+ */
+export function cancelPreviewMix(): void {
+  try {
+    requireNative().previewMixCancel()
+  } catch {
+    // Nothing to stop, or no adapter. Neither is worth raising during teardown.
+  }
+}
+
+/**
+ * The key a program would produce, without preparing it.
+ *
+ * Lets a caller ask "is this the mix I am already playing?" before starting a
+ * job — which is what stops a selection change, or any edit that does not
+ * change the sound, from rebuilding anything.
+ *
+ * @experimental
+ */
+export function previewMixKey(programJson: string, urisJson: string): string {
+  try {
+    return requireNative().previewMixKey(programJson, urisJson)
+  } catch {
+    return ''
+  }
+}
+
+/** Drop one prepared mix. @experimental */
+export function releasePreviewMix(key: string): boolean {
+  try {
+    const value = JSON.parse(requireNative().previewMixRelease(key)) as { removed?: boolean }
+    return value.removed === true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Keep only these mixes; remove the rest and every partial.
+ *
+ * The bound on the cache. A sweep that cannot read its own result removes
+ * nothing, rather than assuming the directory should be empty.
+ *
+ * @experimental
+ */
+export function sweepPreviewMixes(keepKeys: readonly string[]): {
+  removed: number
+  kept: number
+  partials: number
+  skipped: number
+} {
+  const none = { removed: 0, kept: 0, partials: 0, skipped: 0 }
+  try {
+    const value = JSON.parse(requireNative().previewMixSweep(JSON.stringify([...keepKeys]))) as {
+      ok?: boolean
+      removed?: number
+      kept?: number
+      partials?: number
+      skipped?: number
+    }
+    if (value.ok !== true) return none
+    return {
+      removed: Number(value.removed ?? 0),
+      kept: Number(value.kept ?? 0),
+      partials: Number(value.partials ?? 0),
+      skipped: Number(value.skipped ?? 0),
+    }
+  } catch {
+    return none
+  }
+}
+
+/** What is prepared, for assertions. @experimental */
+export function previewMixLedger(): {
+  count: number
+  bytes: number
+  items: { name: string; byteLength: number }[]
+} {
+  try {
+    const value = JSON.parse(requireNative().previewMixLedger()) as {
+      count?: number
+      bytes?: number
+      items?: { name: string; byteLength: number }[]
+    }
+    return {
+      count: Number(value.count ?? 0),
+      bytes: Number(value.bytes ?? 0),
+      items: value.items ?? [],
+    }
+  } catch {
+    return { count: 0, bytes: 0, items: [] }
+  }
+}

package/src/previewTrace.ts

@@ -0,0 +1,348 @@
+import { requireNative } from './player'
+
+/**
+ * The paired player trace.
+ *
+ * Both players sampled on one monotonic clock, buffered natively and drained
+ * afterwards. It exists because the question — do the picture and the sound
+ * agree — needs samples closer together than a bridge hop, and far closer than
+ * `uiautomator` can time.
+ *
+ * Diagnostics-only in native: a build without them refuses, and even with them
+ * it does nothing until armed.
+ *
+ * @experimental
+ */
+
+/** One sample or event. @experimental */
+export interface TraceEvent {
+  seq: number
+  /** `System.nanoTime()`, the clock both players publish on. */
+  atNs: number
+  type: string
+  v: Record<string, unknown>
+}
+
+/** @experimental */
+export interface TracePage {
+  ok: boolean
+  /**
+   * Whether the *run* is trustworthy.
+   *
+   * False when the sampler threw. The events before the fault are real and the
+   * silence after it is not evidence of anything — a summary computed over a
+   * truncated run reads exactly like one computed over a complete one.
+   */
+  valid: boolean
+  /** Why it stopped being trustworthy, or null. */
+  fault: string | null
+  events: TraceEvent[]
+  nextSeq: number
+  total: number
+  /** Events overwritten before they could be read. Non-zero means a hole. */
+  dropped: number
+}
+
+const EMPTY: TracePage = {
+  ok: false,
+  valid: false,
+  fault: 'trace unavailable',
+  events: [],
+  nextSeq: 0,
+  total: 0,
+  dropped: 0,
+}
+
+/** Arm the trace and start sampling. @experimental */
+export function armPreviewTrace(on: boolean, intervalMs = 25): boolean {
+  try {
+    const value = JSON.parse(requireNative().previewTraceArm(on, intervalMs)) as { ok?: boolean }
+    return value.ok === true
+  } catch {
+    return false
+  }
+}
+
+/** Label the trace, so a harness can find its own cases. @experimental */
+export function markPreviewTrace(label: string): void {
+  try {
+    requireNative().previewTraceMark(label)
+  } catch {
+    // Unarmed or unavailable; a mark that lands nowhere is not worth raising.
+  }
+}
+
+/**
+ * Drain a page of events.
+ *
+ * Paged rather than whole: a full trace is far past what a single log line
+ * survives, and truncation in the middle is the failure this is meant to
+ * detect rather than cause.
+ *
+ * @experimental
+ */
+export function drainPreviewTrace(fromSeq: number, limit = 200): TracePage {
+  try {
+    const value = JSON.parse(requireNative().previewTraceDrain(fromSeq, limit)) as TracePage
+    return value.ok ? value : EMPTY
+  } catch {
+    return EMPTY
+  }
+}
+
+/**
+ * Every event, drained in pages until the buffer is exhausted.
+ *
+ * @experimental
+ */
+export function drainAllPreviewTrace(limit = 200): TracePage {
+  const events: TraceEvent[] = []
+  let seq = 0
+  let dropped = 0
+  let total = 0
+  let valid = true
+  let fault: string | null = null
+  // Bounded: the ring is finite, so this cannot page forever even if the
+  // sampler is still running while it drains.
+  for (let guard = 0; guard < 200; guard += 1) {
+    const page = drainPreviewTrace(seq, limit)
+    // Carried from every page: a fault recorded mid-drain still invalidates
+    // the run, and the last page is not special.
+    if (page.fault) {
+      valid = false
+      fault = page.fault
+    }
+    if (!page.ok || page.events.length === 0) {
+      total = page.total || total
+      break
+    }
+    events.push(...page.events)
+    dropped += page.dropped
+    total = page.total
+    if (page.nextSeq === seq) break
+    seq = page.nextSeq
+  }
+  return { ok: true, valid, fault, events, nextSeq: seq, total, dropped }
+}
+
+/**
+ * The offset between the players, summarised over the samples that mattered.
+ *
+ * Only samples where **both** players were playing are counted: a paused
+ * player's position does not advance, so including it would average in a
+ * divergence that is not drift.
+ *
+ * @experimental
+ */
+export function summariseOffsets(events: readonly TraceEvent[]): {
+  samples: number
+  playingSamples: number
+  /** Samples whose presented frame was the same one as the tick before. */
+  staleFrameSamples: number
+  /**
+   * Samples with no presented frame at all.
+   *
+   * `FrameClock.latest` is null until the renderer consumes something, and
+   * again after a generation bump. Counting these as "stale" hid them: a run
+   * reported 56 stale of 506 while every sampled point in the same run had no
+   * record whatsoever, because an absent field is not a false one.
+   */
+  absentFrameSamples: number
+  /** Samples with a frame that had advanced since the previous tick. */
+  freshFrameSamples: number
+  /** The longest run of consecutive stale samples. */
+  longestStaleRun: number
+  minUs: number
+  maxUs: number
+  meanUs: number
+  worstAbsUs: number
+} {
+  let n = 0
+  let stale = 0
+  let absent = 0
+  let fresh = 0
+  let staleRun = 0
+  let longestStaleRun = 0
+  let min = Number.POSITIVE_INFINITY
+  let max = Number.NEGATIVE_INFINITY
+  let sum = 0
+  let samples = 0
+  for (const e of events) {
+    if (e.type !== 'sample') continue
+    samples += 1
+    /*
+      Stale frames are counted, never filtered.
+
+      A presented time that has not moved since the last tick describes a frame
+      the renderer already showed. Dropping those samples and reporting the
+      percentage that remain would be reporting a pass over the interval where
+      the picture was least trustworthy.
+    */
+    if (e.v.pfFresh === undefined) {
+      absent += 1
+      staleRun += 1
+      if (staleRun > longestStaleRun) longestStaleRun = staleRun
+    } else if (e.v.pfFresh === false) {
+      stale += 1
+      staleRun += 1
+      if (staleRun > longestStaleRun) longestStaleRun = staleRun
+    } else {
+      fresh += 1
+      staleRun = 0
+    }
+    if (e.v.videoPlaying !== true || e.v.audioPlaying !== true) continue
+    const offset = Number(e.v.offsetUs)
+    if (!Number.isFinite(offset)) continue
+    n += 1
+    sum += offset
+    if (offset < min) min = offset
+    if (offset > max) max = offset
+  }
+  return {
+    samples,
+    playingSamples: n,
+    staleFrameSamples: stale,
+    absentFrameSamples: absent,
+    freshFrameSamples: fresh,
+    longestStaleRun,
+    minUs: n > 0 ? min : 0,
+    maxUs: n > 0 ? max : 0,
+    meanUs: n > 0 ? Math.round(sum / n) : 0,
+    worstAbsUs: n > 0 ? Math.max(Math.abs(min), Math.abs(max)) : 0,
+  }
+}
+
+/**
+ * What the stall coordinator has done.
+ *
+ * Holds, releases and realigning seeks. A gate asserts that seams produced
+ * holds and that every hold resolved — a coordinator that never engaged and one
+ * that engaged and never released look identical in an offset summary.
+ *
+ * @experimental
+ */
+export function previewSyncCounters(): Record<string, unknown> {
+  try {
+    return JSON.parse(requireNative().previewSyncCounters()) as Record<string, unknown>
+  } catch {
+    return { ok: false }
+  }
+}
+
+/**
+ * Stop playback for a host reason — background, picker, unmount.
+ *
+ * Overrides a resume the coordinator is holding, so playback cannot restart at
+ * a moment nobody asked for.
+ *
+ * @experimental
+ */
+export function stopPreviewForHost(reason: string): void {
+  try {
+    requireNative().previewSyncStop(reason)
+  } catch {
+    // No adapter, or nothing playing. Neither is worth raising in teardown.
+  }
+}
+
+/**
+ * Frames offered, queued and drawn.
+ *
+ * The instrument-disruption check reads this with tracing off and again with it
+ * on: if the drawn count advances at the same rate either way, the trace is not
+ * changing what it measures. Three defects in this area were the measurement
+ * rather than the product, so that check comes before the numbers do.
+ *
+ * @experimental
+ */
+export function previewFramePipeline(): Record<string, number> {
+  try {
+    return JSON.parse(requireNative().previewFramePipeline()) as Record<string, number>
+  } catch {
+    return {}
+  }
+}
+
+/** Which parts of the music preview exist. All true in production. @experimental */
+export interface PreviewParts {
+  /** Whether the drift check may act. Off measures without correcting. */
+  driftCorrection: boolean
+  loadPlayer: boolean
+  startMix: boolean
+  positionPump: boolean
+  coordinator: boolean
+}
+
+/**
+ * Turn parts of the music preview off, to bisect a failure.
+ *
+ * Gate-only in native. Guessing between a second player, its position pump, the
+ * stall coordinator and the mix actually playing is how the previous attempts
+ * in this area became tuning; this is how one of them gets ruled out at a time.
+ *
+ * @experimental
+ */
+export function setPreviewParts(parts: Partial<PreviewParts>): PreviewParts | null {
+  try {
+    const v = JSON.parse(requireNative().previewConfigSet(JSON.stringify(parts))) as
+      PreviewParts & { ok?: boolean }
+    return v.ok ? v : null
+  } catch {
+    return null
+  }
+}
+
+/** @experimental */
+export function previewParts(): PreviewParts | null {
+  try {
+    return JSON.parse(requireNative().previewConfigGet()) as PreviewParts
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Silence the video player's own audio.
+ *
+ * Exposed because a bisect control needs the *same* mute in every
+ * configuration: without it, the video-only row would be the only one with
+ * audible clip audio, and any difference against the others would be
+ * confounded by a whole track the rest do not have.
+ *
+ * @experimental
+ */
+export function muteSourceAudio(muted: boolean): void {
+  try {
+    requireNative().previewMuteSourceAudio(muted)
+  } catch {
+    // No adapter. The caller's other work still stands.
+  }
+}
+
+/**
+ * Every codec mix preparation owns, and what became of it.
+ *
+ * A `release()` that was called is not a release that finished, so both ends
+ * are recorded along with the exception path. The preview video decoder is not
+ * here: it belongs to the player and outlives any job, and counting it would
+ * make "live after publication" always true.
+ *
+ * @experimental
+ */
+export function previewCodecLedger(): {
+  live: number
+  peakLive: number
+  total: number
+  entries: Record<string, unknown>[]
+} {
+  try {
+    return JSON.parse(requireNative().previewCodecLedger()) as {
+      live: number
+      peakLive: number
+      total: number
+      entries: Record<string, unknown>[]
+    }
+  } catch {
+    return { live: -1, peakLive: -1, total: 0, entries: [] }
+  }
+}