@pictor-sdk/video-android 0.1.0

package/src/index.ts

@@ -0,0 +1,276 @@
+/**
+ * `@pictor-sdk/video-android` — optional Android video playback adapter.
+ *
+ * Playback is Media3's ExoPlayer rendering into a persistent external-OES
+ * `SurfaceTexture`; the renderer keeps one texture and one `SkImage` for the
+ * whole session and composes them with the rest of the document in Skia. No
+ * frame crosses the JS thread.
+ *
+ * **Requires Android API 29 or higher**, which is conservative: the surviving
+ * path needs 24, and 29 is held only until something older than the one device
+ * here can actually run it. Installing this package raises a host's
+ * `minSdkVersion`; not installing it leaves image-only consumers exactly where
+ * they were.
+ *
+ * The surface here is **internal** until the Pixel 7 measurements validate it.
+ * Nothing is re-exported from a package a consumer installs by default.
+ *
+ * @experimental
+ */
+export {
+  createMemoryGuard,
+  describeTrip,
+  observeMemory,
+  DEFAULT_CEILING_BYTES,
+  DEFAULT_RISE_BYTES,
+  DEFAULT_WINDOW_SAMPLES,
+  type MemoryGuard,
+} from './memoryGuard'
+
+export {
+  createSyncTrace,
+  distribution,
+  expectedPtsAt,
+  record as recordTick,
+  syncReport,
+  type Distribution,
+  type SyncReport,
+  type SyncTrace,
+  type TickSample,
+} from './syncTrace'
+
+export { AndroidVideoPlayer } from './player'
+
+export { Media3, type Media3State } from './media3'
+
+export {
+  NO_SURFACE,
+  afterPrepare,
+  idlePlaylistSession,
+  isCurrentGeneration,
+  retireSurface,
+  shouldPrepare,
+  type PlaylistIntent,
+  type PlaylistSession,
+} from './playlistSession'
+
+export {
+  createSurfaceOwner,
+  nextOwnerToken,
+  resetSurfaceOwnerForTests,
+  surfaceOwner,
+  type SurfaceCreateResult,
+  type SurfaceOwner,
+  type SurfaceOwnerEffects,
+  type SurfaceReadiness,
+} from './surfaceOwner'
+
+export {
+  useVideoSurface,
+  videoSurfaceSlot,
+  type VideoSurface,
+  type VideoSurfaceHandle,
+  type VideoSurfaceOptions,
+} from './useVideoSurface'
+
+export {
+  useCompositionPlayback,
+  type CompositionPlayback,
+  type CompositionPlaybackState,
+  type UseCompositionPlaybackOptions,
+} from './useCompositionPlayback'
+
+export {
+  useMedia3Playback,
+  type Media3Playback,
+  type UseMedia3PlaybackOptions,
+} from './useMedia3Playback'
+
+export {
+  createAndroidThumbnailProvider,
+  thumbnailCounters,
+  type AndroidThumbnailOptions,
+} from './thumbnailProvider'
+
+export {
+  beginPhase,
+  observe,
+  recoveryFrames,
+  CONVERGED_RUN,
+  MAX_RECOVERY_SAMPLES,
+  type Phase,
+  type PhaseState,
+} from './convergence'
+
+export {
+  createMedia3VideoExporter,
+  VideoExportRejected,
+  type Media3ExporterOptions,
+  type OverlayPreparationResult,
+  type OverlayResourceDescriptor,
+} from './exporter'
+
+export {
+  createPlaybackLifecycle,
+  type PlaybackLifecycle,
+  type PlaybackLifecycleEffects,
+  type PlaybackStopReason,
+} from './playbackLifecycle'
+export {
+  RECOVERY_GRACE_MS,
+  classifyStall,
+  shouldRecover,
+  type RecoverySample,
+  type StallKind,
+} from './surfaceRecovery'
+
+export {
+  EXPORT_STAGES,
+  createExportJobs,
+  type ExportJob,
+  type ExportJobs,
+  type ExportJobsOptions,
+  type ExportStage,
+} from './exportJob'
+
+export {
+  MAX_OBSERVED_HEARTBEAT_GAP_MS,
+  STALL_GRACE_MS,
+  createProgressReporter,
+  createStallWatchdog,
+  planProgressWeights,
+  type ProgressPlan,
+  type ProgressPlanInput,
+  type ProgressReporter,
+  type ProgressReporterOptions,
+  type ShardPlan,
+  type StallVerdict,
+  type StallWatchdog,
+  type StallWatchdogOptions,
+} from './exportProgress'
+
+export {
+  createMediaStoreSaver,
+  shareSavedMedia,
+  sweepPendingMediaSaves,
+  MediaSaveCancelled,
+  MediaSaveFailed,
+} from './mediaStore'
+
+export {
+  createOverlayStagingSink,
+  installOverlayStaging,
+  measureStagingStall,
+  sweepOverlayStaging,
+  type OverlayStagingSink,
+  type StagedRaster,
+} from './overlayStaging'
+export { probeAudioSource } from './audioProbe'
+export type { AudioProbeFailure, AudioProbeResult } from './audioProbe'
+export {
+  ingestManagedSource,
+  managedSourceLedger,
+  managedSourceList,
+  seedManagedSourceForGate,
+  sweepManagedSourcesRawForGate,
+  managedSourceToken,
+  releaseManagedSource,
+  sweepManagedSources,
+} from './managedSources'
+export type { IngestResult, ManagedSource, ManagedSourceFailure } from './managedSources'
+export {
+  cancelPreviewMix,
+  preparePreviewMix,
+  previewMixKey,
+  previewMixLedger,
+  releasePreviewMix,
+  sweepPreviewMixes,
+} from './previewMix'
+export type { PreparedMix, PreviewMixResult } from './previewMix'
+export {
+  PREVIEW_DRIFT_TOLERANCE_US,
+  decidePreviewAudio,
+  previewAudioNeeded,
+  previewProgramJson,
+} from './previewAudioSession'
+export type {
+  PreviewAudioDecision,
+  PreviewAudioInputs,
+  PreviewAudioStatus,
+} from './previewAudioSession'
+export {
+  PHASE_MARK_PREFIX,
+  summarisePhases,
+  type PhaseReport,
+  type PhaseSummary,
+} from './tracePhases'
+export {
+  compositionSpikeSpec,
+  spikePause,
+  spikePlay,
+  spikeRelease,
+  spikeSeek,
+  spikeClaim,
+  spikeDrain,
+  spikeStart,
+  spikeState,
+  type CompositionSpikeItem,
+  type CompositionSpikeSpec,
+  type CompositionSpikeState,
+  type SpikeSample,
+} from './compositionSpike'
+export {
+  classifyExcursions,
+  offsetAt,
+  windowAround,
+  SPIKE_TOLERANCE_US,
+  type Excursion,
+  type ExcursionCause,
+  type ExcursionReport,
+} from './spikeExcursions'
+export {
+  PREVIEW_OUTPUT_FPS,
+  PREVIEW_TOLERANCE_US,
+  checkCadence,
+  type CadenceClip,
+  type CadenceResult,
+  type Verdict,
+} from './previewCadence'
+export {
+  scoreSubmissions,
+  traceSeam,
+  traceStartup,
+  traceSubmission,
+  type ScoredSubmission,
+  type SubmissionRecord,
+  type SubmissionReport,
+  type SeamStage,
+  type StartupRow,
+  type StartupTrace,
+  type SeamTrace,
+  type SubmissionTrace,
+  type TraceRow,
+} from './submissionScoring'
+export { usePreviewAudio } from './usePreviewAudio'
+export { previewAudioDiagnostics } from './previewAudioDiagnostics'
+export type { PreviewAudioDiagnostics } from './previewAudioDiagnostics'
+export type { PreviewAudioBinding, UsePreviewAudioOptions } from './usePreviewAudio'
+export { mixSpanContext, resolveMixSources } from './mixSources'
+export type { ResolvedMixSources } from './mixSources'
+export { ENCODER_GATE_FIXTURES, runEncoderGate } from './encoderGate'
+export type { EncoderGateResult } from './encoderGate'
+export {
+  armPreviewTrace,
+  drainAllPreviewTrace,
+  drainPreviewTrace,
+  markPreviewTrace,
+  muteSourceAudio,
+  previewCodecLedger,
+  previewFramePipeline,
+  previewParts,
+  setPreviewParts,
+  previewSyncCounters,
+  stopPreviewForHost,
+  summariseOffsets,
+} from './previewTrace'
+export type { PreviewParts, TraceEvent, TracePage } from './previewTrace'

package/src/managedSources.ts

@@ -0,0 +1,252 @@
+import { requireNative } from './player'
+
+/**
+ * Media the app owns, copied out of wherever it was picked from.
+ *
+ * A picker returns a reference, not a file. A `content://` grant is scoped to
+ * the activity result that produced it; `copyToCacheDirectory` improves on that
+ * by writing into **cache**, which Android reclaims whenever it wants storage
+ * back. Either way a project persisted with a picker URI reopens with media
+ * that has quietly gone, and nothing says so until an export fails.
+ *
+ * So ingestion copies into `filesDir` and the project stores that. See
+ * `ManagedSources.kt` for why the name is the content hash and why nothing is
+ * ever deleted implicitly.
+ *
+ * @experimental
+ */
+
+/** Where a managed source lives, and what it is. @experimental */
+export interface ManagedSource {
+  /** A `file://` URI in app-owned durable storage. Safe to persist. */
+  uri: string
+  /** The content hash. Names the file; never derived from the user's filename. */
+  token: string
+  byteLength: number
+  sha256: string
+  /**
+   * Whether this call brought the file into existence.
+   *
+   * False means the bytes were already stored and something else may be
+   * pointing at them — a caller unwinding its own work must not release a
+   * source it did not create.
+   */
+  created: boolean
+}
+
+/** @experimental */
+export interface ManagedSourceFailure {
+  ok: false
+  /** Diagnostic. Never shown to a person: it may name a path. */
+  reason: string
+}
+
+/** @experimental */
+export type IngestResult = ({ ok: true } & ManagedSource) | ManagedSourceFailure
+
+/**
+ * Copy a picked source into durable, app-owned storage.
+ *
+ * Never throws for an unreadable source: a pick that cannot be copied is an
+ * answer. It throws only if the adapter is not installed.
+ *
+ * @experimental
+ */
+export function ingestManagedSource(uri: string): IngestResult {
+  return parse<IngestResult>(
+    () => requireNative().ingestManagedSource(uri),
+    (value) => ({
+      ok: true,
+      uri: String(value.uri ?? ''),
+      token: String(value.token ?? ''),
+      byteLength: Number(value.byteLength ?? 0),
+      sha256: String(value.sha256 ?? ''),
+      created: value.created === true,
+    }),
+  )
+}
+
+/**
+ * Drop one managed source.
+ *
+ * For unwinding an ingestion whose item was never created. Not for Undo: an
+ * Undo that deleted the source would leave Redo restoring an item that points
+ * at nothing.
+ *
+ * @experimental
+ */
+export function releaseManagedSource(token: string): boolean {
+  try {
+    const value = JSON.parse(requireNative().releaseManagedSource(token)) as { removed?: boolean }
+    return value.removed === true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Remove every managed source not named in `keepTokens`.
+ *
+ * The only thing that deletes media, and it is always given the full set of
+ * what the project still references. Also removes partials a killed process
+ * left behind.
+ *
+ * @experimental
+ */
+export function sweepManagedSources(keepTokens: readonly string[]): {
+  removed: number
+  kept: number
+  partials: number
+  /** Files that are not ours, counted so the accounting matches a listing. */
+  skipped: number
+} {
+  try {
+    const value = JSON.parse(
+      requireNative().sweepManagedSources(JSON.stringify([...keepTokens])),
+    ) as { ok?: boolean; removed?: number; kept?: number; partials?: number; skipped?: number }
+    if (value.ok !== true) return { removed: 0, kept: 0, partials: 0, skipped: 0 }
+    return {
+      removed: Number(value.removed ?? 0),
+      kept: Number(value.kept ?? 0),
+      partials: Number(value.partials ?? 0),
+      skipped: Number(value.skipped ?? 0),
+    }
+  } catch {
+    // A sweep that cannot be understood removes nothing. The opposite default
+    // would delete a project's media on a parse error.
+    return { removed: 0, kept: 0, partials: 0, skipped: 0 }
+  }
+}
+
+/**
+ * Every filename in the managed directory, including partials and strays.
+ *
+ * Read-only accounting, so it is available in release for the same reason the
+ * ledgers are: it is how a sweep is proven rather than asserted.
+ * {@link managedSourceLedger} reports only well-formed sources, which cannot
+ * show what a sweep left behind.
+ *
+ * @experimental
+ */
+export function managedSourceList(): { name: string; byteLength: number }[] {
+  try {
+    const value = JSON.parse(requireNative().managedSourceList()) as {
+      items?: { name: string; byteLength: number }[]
+    }
+    return value.items ?? []
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Gate-only: put a file in the managed directory with an exact name.
+ *
+ * Ingestion only ever produces well-formed, referenced sources, so the cases a
+ * sweep exists to handle — an orphan, a stale partial, a file that is not ours
+ * — cannot be reached through the normal API. Refused in a release build built
+ * without diagnostics.
+ *
+ * @experimental
+ */
+export function seedManagedSourceForGate(name: string, bytes: number): boolean {
+  try {
+    const value = JSON.parse(requireNative().managedSourceGateSeed(name, bytes)) as { ok?: boolean }
+    return value.ok === true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Gate-only: sweep with a keep list handed over exactly as written.
+ *
+ * The production path serialises its own list, so an unparseable one can never
+ * reach native — which makes "an unreadable keep list deletes nothing"
+ * unprovable through it. Returns what native reported.
+ *
+ * @experimental
+ */
+export function sweepManagedSourcesRawForGate(rawKeep: string): {
+  ok: boolean
+  removed: number
+  kept: number
+  partials: number
+  skipped: number
+} {
+  try {
+    const value = JSON.parse(requireNative().managedSourceGateSweepRaw(rawKeep)) as {
+      ok?: boolean
+      removed?: number
+      kept?: number
+      partials?: number
+      skipped?: number
+    }
+    return {
+      ok: value.ok === true,
+      removed: Number(value.removed ?? 0),
+      kept: Number(value.kept ?? 0),
+      partials: Number(value.partials ?? 0),
+      skipped: Number(value.skipped ?? 0),
+    }
+  } catch {
+    return { ok: false, removed: 0, kept: 0, partials: 0, skipped: 0 }
+  }
+}
+
+/** What is stored, for assertions. Tokens and sizes, never names. @experimental */
+export function managedSourceLedger(): {
+  count: number
+  bytes: number
+  items: { token: string; byteLength: number }[]
+} {
+  try {
+    const value = JSON.parse(requireNative().managedSourceLedger()) as {
+      count?: number
+      bytes?: number
+      items?: { token: string; byteLength: number }[]
+    }
+    return {
+      count: Number(value.count ?? 0),
+      bytes: Number(value.bytes ?? 0),
+      items: value.items ?? [],
+    }
+  } catch {
+    return { count: 0, bytes: 0, items: [] }
+  }
+}
+
+/**
+ * The token a managed URI names, or null if it is not one of ours.
+ *
+ * Lets a host collect the keep list for {@link sweepManagedSources} straight
+ * from a project's sources without storing a second index that could drift.
+ *
+ * @experimental
+ */
+export function managedSourceToken(uri: string): string | null {
+  const match = /\/([0-9a-f]{64})\.bin$/.exec(uri)
+  return match ? match[1]! : null
+}
+
+function parse<T>(
+  call: () => string,
+  build: (value: Record<string, unknown>) => T,
+): T | ManagedSourceFailure {
+  let raw: string
+  try {
+    raw = call()
+  } 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: false, reason: typeof value.reason === 'string' ? value.reason : 'failed' }
+  }
+  return build(value)
+}