@pictor-sdk/video-android 0.1.0

package/src/compositionSpike.ts

@@ -0,0 +1,305 @@
+import { playlistOf, type VideoProject } from '@pictor-sdk/video-core'
+import { requireNative } from './player'
+
+/**
+ * The shared-clock playback spike, from the host's side.
+ *
+ * ## What it is testing
+ *
+ * Whether one playback-clock authority can drive the picture and a prepared,
+ * project-wide mix at once. The two-player preview cannot meet the 60 ms gate
+ * and the reasons are structural: anchors polled at 50 ms make a single
+ * comparison uncertain by up to ±56 ms against a 60 ms tolerance, the
+ * correction loop runs at 500 ms while each corrective seek costs 200-400 ms,
+ * and at a seam the project clock divides by a speed the player applies about
+ * 450 ms later.
+ *
+ * ## Why the spec is built here
+ *
+ * `playlistOf` is the shared compiler, and it already decides every number this
+ * needs: the source bounds a clip plays between, its speed, and where the
+ * window sits on the project timeline. Passing its output through verbatim is
+ * what keeps the adapter free of a second interpretation of the document —
+ * native maps items onto media items and nothing else.
+ *
+ * Diagnostics-only, and it says nothing about live PCM gain or fades: it plays
+ * the same prepared mix file the current preview plays.
+ *
+ * @experimental
+ */
+
+/** One clip, as the compiler described it. @experimental */
+export interface CompositionSpikeItem {
+  uri: string
+  /** Clipping bounds in **source** time, which is where speed is applied. */
+  startUs: number
+  endUs: number
+  speed: number
+}
+
+/** @experimental */
+export interface CompositionSpikeSpec {
+  /**
+   * Hold the shared clock at each clip boundary.
+   *
+   * Off, and measured off for a reason: with `playWhenReady` false
+   * `CompositionPlayer` does not advance across an item boundary, so the
+   * incoming frame the hold waits for is never produced and the hold runs to
+   * its bound. Holding the clock and preparing the next stream are mutually
+   * exclusive on this player.
+   */
+  seamHold?: boolean
+  /**
+   * Prepare the incoming item with an explicit seek while the clock is held.
+   *
+   * Only meaningful with `seamHold`. Pausing natural traversal and seeking to a
+   * target are different operations: the seek path resets the renderers, which
+   * is what makes a paused player produce a frame, and is the same path the
+   * existing seek readiness already passes on.
+   */
+  seamSeek?: boolean
+  items: CompositionSpikeItem[]
+  /** The prepared mix. Empty plays the picture with no sound at all. */
+  mixUri: string
+  /**
+   * The mix's duration.
+   *
+   * Required whenever `mixUri` is set: the player computes each sequence's
+   * duration before playing, and an audio-only item cannot report one itself.
+   */
+  mixDurationUs: number
+  width: number
+  height: number
+  /**
+   * The request this attachment belongs to.
+   *
+   * Claimed before preparation starts. Native refuses an attachment whose id is
+   * older than the newest claim, so a preparation that finishes late cannot put
+   * a stale mix on screen for even one frame. Omit for runs with no race.
+   */
+  requestId?: number
+}
+
+/** @experimental */
+export interface CompositionSpikeState {
+  ok: boolean
+  attached: boolean
+  built: number
+  released: number
+  error: string | null
+  /**
+   * Readiness latency, reported apart from synchronisation.
+   *
+   * A preparation pause is a latency figure and an A/V offset is an error;
+   * averaging one into the other is how a slow start reads as drift.
+   */
+  startupMs: number
+  seekMs: number
+  /** What the person asked for, independent of whether the transport is running. */
+  intentPlaying?: boolean
+  /** A hold waiting for the first frame of the current epoch. */
+  releasePending?: boolean
+  releases?: number
+  readinessTimeouts?: number
+  readinessFailure?: string | null
+  /** How long the last hold lasted before playback was released. */
+  holdMs?: number
+  /**
+   * Wall-clock milliseconds spent holding the clock at each clip boundary.
+   *
+   * Listed, never averaged. Each entry is a pause the person sees: the decoder
+   * is torn down and rebuilt at a boundary and the clock waits rather than the
+   * picture falling behind it. **This is not seamless playback**, which is why
+   * it is reported apart from every synchronisation figure.
+   */
+  seamHoldMs?: number[]
+  /** Holds that reached their bound without a correctly associated frame. */
+  seamHoldTimeouts?: number
+  seamHoldActive?: boolean
+  atNs?: number
+  positionUs?: number
+  playing?: boolean
+  playbackState?: number
+  durationUs?: number
+  presentedUs?: number | null
+  /** How old the presented frame was when it was read, so a stalled sample can be excluded. */
+  presentedAgeNs?: number
+  /** How long the paired read itself took. Bounds the pairing error. */
+  readSpanNs?: number
+  /** How stale the pairing was when it was read out. */
+  pairingAgeNs?: number
+}
+
+/**
+ * Build the spike's spec from a project and a prepared mix.
+ *
+ * Unsupported clips are not silently dropped: `playlistOf` reports them, and a
+ * spec built from a playlist missing a window would put every later seam in the
+ * wrong place — which is exactly the class of error this spike exists to
+ * measure.
+ *
+ * @experimental
+ */
+export function compositionSpikeSpec(
+  project: VideoProject,
+  mix: { uri: string; durationUs: number },
+  resolve: (source: { kind: string; uri?: string }) => string | null,
+): { spec: CompositionSpikeSpec; unsupported: string[] } {
+  const playlist = playlistOf(project)
+  const items: CompositionSpikeItem[] = []
+  const unsupported = playlist.unsupported.map((u) => `${u.clipId}: ${u.reason}`)
+  for (const item of playlist.items) {
+    const uri = resolve(item.source as unknown as { kind: string; uri?: string })
+    if (uri === null) {
+      unsupported.push(`${item.clipId}: unresolved`)
+      continue
+    }
+    items.push({
+      uri,
+      startUs: Number(item.startUs),
+      endUs: Number(item.endUs),
+      speed: item.speed,
+    })
+  }
+  return {
+    spec: {
+      items,
+      mixUri: mix.uri,
+      mixDurationUs: mix.durationUs,
+      width: project.size.width,
+      height: project.size.height,
+    },
+    unsupported,
+  }
+}
+
+function call(fn: () => string, label: string): Record<string, unknown> {
+  try {
+    return JSON.parse(fn()) as Record<string, unknown>
+  } catch (error) {
+    return { ok: false, error: `${label}: ${String(error)}` }
+  }
+}
+
+/** Claim the next request id, before preparing. @experimental */
+export function spikeClaim(): number {
+  const result = call(() => requireNative().spikeClaim(), 'spikeClaim')
+  return typeof result.requestId === 'number' ? result.requestId : 0
+}
+
+/** @experimental */
+export function spikeStart(spec: CompositionSpikeSpec): Record<string, unknown> {
+  return call(() => requireNative().spikeStart(JSON.stringify(spec)), 'spikeStart')
+}
+
+/** @experimental */
+export function spikePlay(): Record<string, unknown> {
+  return call(() => requireNative().spikePlay(), 'spikePlay')
+}
+
+/** @experimental */
+export function spikePause(): Record<string, unknown> {
+  return call(() => requireNative().spikePause(), 'spikePause')
+}
+
+/** @experimental */
+export function spikeSeek(positionUs: number): Record<string, unknown> {
+  return call(() => requireNative().spikeSeek(positionUs), 'spikeSeek')
+}
+
+/** @experimental */
+export function spikeState(): CompositionSpikeState {
+  return call(() => requireNative().spikeState(), 'spikeState') as unknown as CompositionSpikeState
+}
+
+/**
+ * One retained sample, unpacked.
+ *
+ * Packed across the boundary because a gate reads thousands of these, and named
+ * here because a gate that indexes into an array of eighteen longs is one
+ * transposition away from a confident wrong answer.
+ *
+ * @experimental
+ */
+export interface SpikeSample {
+  seq: number
+  atNs: number
+  positionUs: number
+  playing: boolean
+  ready: boolean
+  epoch: number
+  sinceEpochNs: number
+  frameId: number
+  frameGeneration: number
+  frameWindow: number
+  framePtsUs: number
+  /**
+   * When Media3's renderer said this frame was about to go to the surface.
+   *
+   * The earliest boundary observable here, and the one that separates the
+   * owners of a gap: nothing before this is the decoder or the item's
+   * preparation, this to {@link SpikeSample.frameAvailableNs} is the video
+   * graph, and that to {@link SpikeSample.frameConsumedNs} is this consumer.
+   */
+  frameMetadataNs: number
+  /** The time Media3 *asked* the surface to present at. An intention. */
+  frameReleaseNs: number
+  /** The time the consumer latched it. The last boundary observable here. */
+  frameConsumedNs: number
+  frameAvailableNs: number
+  coalesced: number
+  offered: number
+  available: number
+  taken: number
+  readSpanNs: number
+}
+
+/** @experimental */
+export function spikeDrain(fromSeq: number, limit = 400): {
+  ok: boolean
+  rows: SpikeSample[]
+  nextSeq: number
+  total: number
+  dropped: number
+} {
+  const page = call(() => requireNative().spikeDrain(fromSeq, limit), 'spikeDrain') as {
+    ok?: boolean
+    rows?: number[][]
+    nextSeq?: number
+    total?: number
+    dropped?: number
+  }
+  return {
+    ok: page.ok === true,
+    rows: (page.rows ?? []).map((r) => ({
+      seq: r[0]!,
+      atNs: r[1]!,
+      positionUs: r[2]!,
+      playing: (r[3]! & 1) === 1,
+      ready: (r[3]! & 2) === 2,
+      epoch: r[4]!,
+      sinceEpochNs: r[5]!,
+      frameId: r[6]!,
+      frameGeneration: r[7]!,
+      frameWindow: r[8]!,
+      framePtsUs: r[9]!,
+      frameReleaseNs: r[10]!,
+      frameConsumedNs: r[11]!,
+      frameAvailableNs: r[12]!,
+      coalesced: r[13]!,
+      offered: r[14]!,
+      available: r[15]!,
+      taken: r[16]!,
+      readSpanNs: r[17]!,
+      frameMetadataNs: r[18] ?? -1,
+    })),
+    nextSeq: page.nextSeq ?? fromSeq,
+    total: page.total ?? 0,
+    dropped: page.dropped ?? 0,
+  }
+}
+
+/** @experimental */
+export function spikeRelease(): Record<string, unknown> {
+  return call(() => requireNative().spikeRelease(), 'spikeRelease')
+}

package/src/convergence.ts

@@ -0,0 +1,112 @@
+/**
+ * Deciding when playback has settled, instead of assuming it after a timeout.
+ *
+ * The first attempt excluded a fixed 1.5 s after every transition. That is a
+ * guess in both directions: too short for a seek, whose tail leaked into the
+ * steady figures, and too long for a rate change that settles immediately. It
+ * also hides the thing worth knowing — how long recovery actually took.
+ *
+ * So a transition opens a phase, and the phase closes when the offsets say so:
+ * [CONVERGED_RUN] consecutive samples inside the expected bound. The recovery
+ * duration and the worst offset seen on the way are kept, because a transient
+ * that is excluded but not reported is a failure nobody can see.
+ *
+ * [MAX_RECOVERY_SAMPLES] is a safety net, not a policy. A phase that never
+ * converges is closed anyway and marked, so a permanent failure surfaces as a
+ * failure instead of an ever-growing exclusion window.
+ *
+ * Pure, so the rule is tested rather than trusted.
+ *
+ * @experimental
+ */
+
+/** What kind of transition opened a phase. Steady is the absence of one. */
+export type Phase =
+  | 'steady'
+  | 'startup'
+  | 'seek'
+  | 'source'
+  | 'pauseResume'
+  | 'rateChange'
+
+/**
+ * Consecutive in-bound samples that end a transient.
+ *
+ * Eight at 30 fps is about a quarter second of agreement — long enough that a
+ * single lucky frame cannot close a phase, short enough to measure recovery
+ * rather than round it up.
+ */
+export const CONVERGED_RUN = 8
+
+/** A phase is closed after this many samples whatever they say. */
+export const MAX_RECOVERY_SAMPLES = 600
+
+export interface PhaseState {
+  phase: Phase
+  /** Offsets collected while this phase was open. */
+  samples: number[]
+  /** Consecutive in-bound samples so far. */
+  run: number
+  /** Worst absolute offset seen during the transient, in microseconds. */
+  worstUs: number
+  /** Samples taken before it converged. */
+  recoverySamples: number
+  /** True once converged; further samples belong to steady state. */
+  converged: boolean
+  /** True when the safety net closed it instead of convergence. */
+  timedOut: boolean
+}
+
+export function beginPhase(phase: Phase): PhaseState {
+  return {
+    phase,
+    samples: [],
+    run: 0,
+    worstUs: 0,
+    recoverySamples: 0,
+    converged: phase === 'steady',
+    timedOut: false,
+  }
+}
+
+/**
+ * Feed one offset. Returns the updated phase and where the sample belongs.
+ *
+ * A sample taken while a transient is open belongs to that transient, never to
+ * steady state — merging them would report the transitions as if they were
+ * playback.
+ */
+export function observe(
+  state: PhaseState,
+  offsetUs: number,
+  boundUs: number,
+): { state: PhaseState; bucket: Phase } {
+  if (state.converged) {
+    return { state, bucket: 'steady' }
+  }
+
+  const magnitude = Math.abs(offsetUs)
+  const next: PhaseState = {
+    ...state,
+    samples: [...state.samples, offsetUs],
+    recoverySamples: state.recoverySamples + 1,
+    worstUs: Math.max(state.worstUs, magnitude),
+    run: magnitude <= boundUs ? state.run + 1 : 0,
+  }
+
+  if (next.run >= CONVERGED_RUN) {
+    next.converged = true
+  } else if (next.recoverySamples >= MAX_RECOVERY_SAMPLES) {
+    // Closed by the safety net. Marked, so it reads as a failure to converge
+    // rather than quietly becoming steady state.
+    next.converged = true
+    next.timedOut = true
+  }
+
+  return { state: next, bucket: state.phase }
+}
+
+/** How long recovery took, in frames, or null while still recovering. */
+export function recoveryFrames(state: PhaseState): number | null {
+  return state.converged ? state.recoverySamples : null
+}

package/src/encoderGate.ts

@@ -0,0 +1,66 @@
+import { requireNative } from './player'
+
+/**
+ * The AAC encoder's frozen behaviour, re-measurable on demand.
+ *
+ * The encode loop is 16% of a preview preparation and was 89% of it before it
+ * was rewritten. That rewrite was checked against a baseline of natively
+ * generated PCM fixtures — inputs that are formulas rather than files, so the
+ * two halves of the comparison cannot drift apart — and the check was exact:
+ * access-unit count, payload bytes, payload hash, CSD, timestamps, decoded
+ * frame count, RMS and transient positions all matched.
+ *
+ * This is the door to that. Diagnostics-gated in native, so a release build
+ * without them refuses.
+ *
+ * @experimental
+ */
+
+/** @experimental */
+export interface EncoderGateResult {
+  ok: boolean
+  fixture?: string
+  /** Compressed shape. */
+  units?: number
+  payloadBytes?: number
+  payloadHash?: number
+  csd0?: number
+  firstUs?: number
+  lastUs?: number
+  headTimestamps?: number[]
+  /** Decoded result. */
+  decodedFrames?: number
+  decodedRms?: number
+  peak?: number
+  markerPositionsMs?: number[]
+  expectedMarkersMs?: number[]
+  /** What it cost. */
+  encodeMs?: number
+  inputFrames?: number
+  fileBytes?: number
+  error?: string
+}
+
+/** The fixtures the gate can run. @experimental */
+export const ENCODER_GATE_FIXTURES = [
+  'short',
+  'acceptance',
+  'silence',
+  'saturated',
+  'markers',
+] as const
+
+/**
+ * Encode one fixture and describe the result completely.
+ *
+ * Never throws: a gate that is unavailable is an answer.
+ *
+ * @experimental
+ */
+export function runEncoderGate(fixture: string, maxInputSize = 65536): EncoderGateResult {
+  try {
+    return JSON.parse(requireNative().encoderGateRun(fixture, maxInputSize)) as EncoderGateResult
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) }
+  }
+}

package/src/exportDestination.ts

@@ -0,0 +1,149 @@
+import type { VideoExportDestination } from '@pictor-sdk/video-core'
+
+/**
+ * Where the file goes, and what is refused before anything is encoded.
+ *
+ * ## Refusal, never fallback
+ *
+ * A destination that cannot be honoured fails the export naming the reason. The
+ * tempting alternative — write to the cache and return that instead — produces
+ * an export that reports success while the file is nowhere the caller asked for,
+ * and nothing downstream can tell that apart from having worked. A host that
+ * wants a temporary can ask for one.
+ *
+ * ## `file:` only, for now
+ *
+ * A `content:` uri is not a path. A document provider need not be a filesystem,
+ * so there is no directory to stage in and no rename to be atomic about;
+ * publishing would have to be a copy into an opaque stream, with no way to leave
+ * the previous contents intact if it failed halfway. That is a different design,
+ * not a missing branch, so it is refused by name.
+ *
+ * ## Paths do not appear in errors
+ *
+ * A message that quotes `/data/user/0/com.host.app/files/private/...` puts an
+ * app-private path into a log, a crash report and whatever the host displays.
+ * Every reason here names the file and nothing above it.
+ *
+ * @experimental
+ */
+
+/** A destination this adapter can honour. @experimental */
+export type ResolvedDestination =
+  | { kind: 'temporary' }
+  | { kind: 'file'; path: string; overwrite: boolean }
+
+/** @experimental */
+export interface DestinationDecision {
+  destination: ResolvedDestination | null
+  /** Empty when `destination` is set. Never contains a full path. */
+  reasons: string[]
+}
+
+/**
+ * The last segment, for a message that has to name something.
+ *
+ * Directories are the private part. A filename the caller chose is already
+ * theirs, and without it a refusal cannot say which destination it refused.
+ */
+export function describeTarget(path: string): string {
+  const trimmed = path.replace(/\/+$/, '')
+  const name = trimmed.slice(trimmed.lastIndexOf('/') + 1)
+  return name.length > 0 ? name : '(unnamed)'
+}
+
+const KNOWN_SCHEMES: Record<string, string> = {
+  'content:': 'a content uri is not a filesystem path, so it cannot be published atomically',
+  'http:': 'a remote destination cannot be written to directly',
+  'https:': 'a remote destination cannot be written to directly',
+  'android.resource:': 'app resources are read-only',
+  'asset:': 'bundled assets are read-only',
+}
+
+/** @experimental */
+export function resolveDestination(destination?: VideoExportDestination): DestinationDecision {
+  if (destination === undefined) return { destination: { kind: 'temporary' }, reasons: [] }
+  if (destination.kind === 'temporary') return { destination: { kind: 'temporary' }, reasons: [] }
+  if (destination.kind !== 'file') {
+    return {
+      destination: null,
+      reasons: [`destination kind '${String((destination as { kind: string }).kind)}' is not supported`],
+    }
+  }
+
+  const uri = destination.uri
+  if (typeof uri !== 'string' || uri.trim().length === 0) {
+    return { destination: null, reasons: ['the file destination has no uri'] }
+  }
+
+  const scheme = /^[a-zA-Z][a-zA-Z0-9+.-]*:/.exec(uri)?.[0]?.toLowerCase()
+  if (scheme !== undefined && scheme !== 'file:') {
+    const known = KNOWN_SCHEMES[scheme]
+    return {
+      destination: null,
+      reasons: [
+        known !== undefined
+          ? `destination scheme '${scheme}' is not supported: ${known}`
+          : `destination scheme '${scheme}' is not supported; only file: is`,
+      ],
+    }
+  }
+  if (scheme === undefined) {
+    // A bare path is ambiguous — relative to what? — and accepting it would
+    // silently resolve against a working directory nobody set.
+    return { destination: null, reasons: ['the file destination must be a file: uri'] }
+  }
+
+  let path: string
+  try {
+    // `file:///a/b` and `file:/a/b` both name an absolute path; `file://host/a`
+    // names another machine's, which is not something to guess at.
+    const withoutScheme = uri.slice('file:'.length)
+    const rest = withoutScheme.startsWith('//') ? withoutScheme.slice(2) : withoutScheme
+    if (withoutScheme.startsWith('//') && !rest.startsWith('/')) {
+      return {
+        destination: null,
+        reasons: ['the file destination names a remote host, which is not supported'],
+      }
+    }
+    path = decodeURIComponent(rest)
+  } catch {
+    return { destination: null, reasons: ['the file destination uri is malformed'] }
+  }
+
+  if (!path.startsWith('/')) {
+    return { destination: null, reasons: ['the file destination must be an absolute path'] }
+  }
+  if (path.endsWith('/')) {
+    return {
+      destination: null,
+      reasons: ['the file destination is a directory; it must name the file to write'],
+    }
+  }
+  if (path.includes('\0')) {
+    return { destination: null, reasons: ['the file destination uri is malformed'] }
+  }
+  /*
+    `..` is refused rather than normalised.
+
+    Resolving it would mean a destination that names one directory and writes to
+    another, and the staging file — which must live beside the target for the
+    publication to be a same-filesystem rename — would be placed by arithmetic
+    the caller did not do.
+  */
+  if (path.split('/').some((segment) => segment === '..')) {
+    return { destination: null, reasons: ['the file destination must not contain ".."'] }
+  }
+  const name = describeTarget(path)
+  if (name === '.' || name === '(unnamed)') {
+    return {
+      destination: null,
+      reasons: ['the file destination is a directory; it must name the file to write'],
+    }
+  }
+
+  return {
+    destination: { kind: 'file', path, overwrite: destination.overwrite === true },
+    reasons: [],
+  }
+}