@pictor-sdk/video-android 0.1.0

package/src/NativePictorVideo.ts

@@ -0,0 +1,574 @@
+/* eslint-disable @typescript-eslint/no-wrapper-object-types --
+ * React Native's codegen recognises the upper-cased `Object` as its
+ * `UnsafeObject` type and rejects the primitive `object`. This file is a
+ * codegen spec before it is TypeScript, so the generator's spelling wins.
+ */
+import { TurboModuleRegistry, type TurboModule } from 'react-native'
+
+/**
+ * The native surface. **Internal** until the API stabilises.
+ *
+ * Numbers, strings and plain objects only. `ExoPlayer`, `MediaItem`, `Surface`
+ * and every other Android or Media3 type stops at the Kotlin side of this
+ * boundary and never appears in a Pictor signature.
+ *
+ * Nothing here is per frame. Frames reach the renderer through the
+ * `__pictorVideoSurface` host object on the UI runtime, so the JS thread is not
+ * in the picture's path at all; these calls are controls and a throttled
+ * snapshot.
+ */
+export interface Spec extends TurboModule {
+  /** Publishes `__pictorVideoSurface` on the JS runtime. */
+  installVideoSurface(): boolean
+  /**
+   * Publishes `__pictorOverlayStaging` on the JS runtime.
+   *
+   * Native chooses the directory; JS never supplies a destination.
+   */
+  installOverlayStaging(): boolean
+
+  /** Open a source — local `android.resource:`/`file:` or remote — and render it. */
+  media3Prepare(uri: string): boolean
+  /** Diagnostics: a player with no video output, for heap attribution. */
+  media3PrepareNoSurface(uri: string): boolean
+  /** Diagnostics: point the existing player at another source. */
+  media3Rebind(uri: string): boolean
+  /** Diagnostics: end the source, keep the player. */
+  media3StopKeepingPlayer(): void
+  /**
+   * Replace the playlist. Two parallel arrays: sources, then four numbers per
+   * entry — clipping start and end in microseconds, speed in milli-units, and
+   * muted as 0 or 1.
+   */
+  media3SetPlaylist(
+    uris: string[],
+    bounds: number[],
+    startWindow: number,
+    startPositionUs: number,
+  ): boolean
+  /** Seek in the player's coordinates: window index plus offset. */
+  media3SeekToWindow(windowIndex: number, positionUs: number): void
+  /**
+   * **V3.3 gate only.** Encode one source through Transformer, once.
+   *
+   * Not an exporter and not reachable from `VideoExporter`: it takes a single
+   * URI rather than a project, writes to an adapter-private temporary, and
+   * exists to answer whether Skia can draw inside Transformer's frame processor
+   * without changing the picture. `withSkia` selects the effect chain — false is
+   * the vanilla run that establishes what the codec alone costs.
+   *
+   * Returns a JSON string rather than a shaped object because the shape is a
+   * gate's report, not an API, and freezing it here would be pretending
+   * otherwise.
+   *
+   * @experimental
+   */
+  exportGateRun(uri: string, withSkia: boolean, timeoutSeconds: number): string
+  /**
+   * **V3.3 gate only.** Execute one serialized, versioned `VideoScene`.
+   *
+   * Native receives a scene, never a project: ids, indices and numbers that
+   * `resolveVideoScene` already settled. It validates the schema version, the
+   * command order and every identity before Transformer starts, and refuses
+   * anything it cannot execute faithfully rather than skipping it.
+   *
+   * @experimental
+   */
+  exportGateRunScene(
+    uri: string,
+    sceneJson: string,
+    timeoutSeconds: number,
+    /** `-1` never fails; `0` fails after GL init before the first frame; `n` after n frames. */
+    failAfterFrames: number,
+  ): string
+  /**
+   * **V3.3 gate only.** Execute a compiled scene *program* over a sequence.
+   *
+   * One document for the whole export: sorted, contiguous, half-open segments
+   * compiled from the project's clip placements and overlay spans. Native
+   * validates coverage, then selects a segment per frame by binary search — a
+   * lookup, not an interpretation.
+   *
+   * @experimental
+   */
+  exportGateRunProgram(uris: string[], programJson: string, timeoutSeconds: number): string
+  /** **V3.3 gate only.** Delete every temporary the gate created. @experimental */
+  /**
+   * **V3.3 gate only.** A sequence whose clipping and speed TypeScript chose.
+   *
+   * `itemsJson` is `{ uri, startMs, endMs, speed, durationUs?, forceAudioTrack? }[]`.
+   * Native hands these to Media3 and computes none of them: which part of a
+   * source plays, and how fast, is timeline interpretation and belongs to the
+   * compiler.
+   *
+   * `forceAudioTrack` is sequence-level and honoured if any item sets it. A
+   * source with no audio track fails outright at any rate other than 1 without
+   * it — Media3 drives its speed path through audio.
+   *
+   * @experimental
+   */
+  exportGateRunItems(itemsJson: string, programJson: string, timeoutSeconds: number): string
+  exportGateReleaseTemporary(): number
+  /**
+   * **V3.3 gate only.** Compare two files in **display space**.
+   *
+   * Display space is the only space the question means anything in: a file
+   * storing 1080×1920 with a rotation flag and one storing 1920×1080 with the
+   * orientation baked in display identically, and comparing stored dimensions
+   * would call that a difference.
+   *
+   * Returns a JSON report of per-timestamp statistics. It states no verdict —
+   * the threshold is frozen by the caller, from the control, before the thing
+   * being tested is looked at.
+   *
+   * @experimental
+   */
+  exportGateCompare(leftUri: string, rightUri: string, timestampsUs: number[]): string
+  /**
+   * **V3.3 gate only.** Mean colour of a central region, per timestamp.
+   *
+   * Reports numbers and draws no conclusion. Which source a colour implies, and
+   * which frame of it, is arithmetic the TypeScript oracle owns.
+   *
+   * @experimental
+   */
+  exportGateSample(uri: string, timestampsUs: number[]): string
+  /**
+   * **V3.3 gate only.** Muxed sample timestamps and per-track durations.
+   *
+   * A frame count and a whole-file duration cannot tell a held tail frame from a
+   * correctly-timed one, or a gap from a slow rate. The written timestamps can.
+   * Reports them; judges nothing.
+   *
+   * @experimental
+   */
+  /**
+   * **V3.4 gate only.** Mean and extremes over caller-chosen rectangles.
+   *
+   * `probesJson` is `{ timeUs, x, y, w, h }[]`. The fixed centre region
+   * {@link exportGateSample} uses straddles a transformed clip's edge and
+   * averages source pixels with cleared ones; the caller has the corner oracle
+   * and passes rectangles it has confirmed are covered.
+   *
+   * @experimental
+   */
+  /**
+   * **V3.5 gate only.** Decoded audio: loudness and spectrum per window.
+   *
+   * A pitch-shifting speed change and a pitch-preserving one produce files whose
+   * duration and sample count are identical, so counting cannot tell them apart.
+   * Also reports AAC encoder delay, padding and the first presentation time,
+   * which a seam alignment check needs.
+   *
+   * @experimental
+   */
+  exportGateAudio(uri: string, windowsJson: string): string
+  exportGateProbe(uri: string, probesJson: string): string
+  exportGateTracks(uri: string): string
+  /**
+   * **V3.4 gate only.** One decoded frame as base64 PNG, in display space.
+   *
+   * @experimental
+   */
+  exportGateFramePng(uri: string, timeUs: number): string
+  /**
+   * **V3.4 gate only.** Encode a still through the treatment's encoder.
+   *
+   * A comparison between two renderers is only about the renderers if
+   * everything after them is the same, so the reference is encoded and decoded
+   * exactly as the treatment is.
+   *
+   * @experimental
+   */
+  exportGateEncodeStill(pngBase64: string, frames: number): string
+  /**
+   * **V3.4 gate only.** Geometry and interior colour, measured separately.
+   *
+   * A maximum channel delta is near-useless at a transformed edge: one row of
+   * pixels on the far side of a bright/black boundary reads 255 while the
+   * picture is right. Returns mask overlap, edge displacement and interior
+   * colour error, and draws no conclusion about any of them.
+   *
+   * @experimental
+   */
+  exportGateGeometry(
+    leftUri: string,
+    leftUs: number,
+    rightUri: string,
+    rightUs: number,
+    maskThreshold: number,
+  ): string
+  /**
+   * **V3.3 gate only.** Per-sample checksums of the compressed video payload.
+   *
+   * Transmuxing must move encoded bytes and change only timestamps and container
+   * metadata. Decoded pixels cannot show that — a re-encode that happens to look
+   * identical would pass — so the payload itself is checksummed.
+   *
+   * @experimental
+   */
+  exportGateSampleHashes(uri: string): string
+  /**
+   * **V3.3 gate only.** One Transformer job per clip, then a transmux concat.
+   *
+   * `shardsJson` is `{ uri, startMs, endMs, speed, timelineOffsetUs,
+   * forceAudioTrack, frameDropFps?, encoderRepeatUs?, emitsPerInput?,
+   * outputPtsUs?, cadenceFailAfterEmits? }[]`. The cadence arrays come straight
+   * from `resampleClip`; native walks them and computes no grid arithmetic. Native adds `timelineOffsetUs` to each local
+   * presentation timestamp and does segment lookup; it computes no placement,
+   * duration or rate. Intermediates are deleted on every path.
+   *
+   * @experimental
+   */
+  exportGateRunShards(
+    shardsJson: string,
+    programJson: string,
+    timeoutSeconds: number,
+    overlaysJson: string,
+  ): string
+  /**
+   * **V3.4 gate only.** Write raw RGBA bytes to a sidecar and checksum them.
+   *
+   * Pixels never travel in scene JSON. This stages them beside it and returns
+   * the path, length and CRC32 a descriptor must declare.
+   *
+   * @experimental
+   */
+  /**
+   * **V3.5 gate only.** Video shards, an audio timeline, then a muxer copy.
+   *
+   * The two pipelines never meet until the last step, and that step decodes
+   * nothing: `MediaMuxer` writes both sets of encoded samples unchanged, so
+   * neither takes a second generation.
+   *
+   * @experimental
+   */
+  /**
+   * Run an export off the bridge so it can be cancelled while it runs.
+   *
+   * Resolves with the same JSON outcome the blocking call returns. @experimental
+   */
+  exportRunProjectAsync(
+    jobId: string,
+    shardsJson: string,
+    programJson: string,
+    overlaysJson: string,
+    mixProgramJson: string,
+    mixUrisJson: string,
+    timeoutSeconds: number,
+    /** `""` for a temporary, or `{kind:'file',path,overwrite}`. @experimental */
+    destinationJson: string,
+  ): Promise<string>
+  /**
+   * Save a finished export into the device's video collection.
+   *
+   * Inserts pending, streams, verifies, then publishes. Settles once: the
+   * published `content:` uri, or an error with the pending row already
+   * deleted. @experimental
+   */
+  mediaSaveAsync(jobId: string, sourceUri: string): Promise<string>
+  /**
+   * Offer a saved video to the system share sheet.
+   *
+   * The durable `content:` uri only, with a read grant and nothing else.
+   * Returns what the intent carried, so a gate can inspect it. @experimental
+   */
+  mediaShare(uri: string): string
+  /** Ask a running save to stop. Idempotent. @experimental */
+  mediaSaveCancel(jobId: string): string
+  /** Delete this app's own stale pending rows. Never a published item. @experimental */
+  mediaSaveSweepPending(): string
+  /** Confirm a saved item still opens. @experimental */
+  mediaSaveReadable(uri: string): string
+  /**
+   * Release one temporary output this module produced. Idempotent.
+   *
+   * Refuses any path it did not create, so it cannot delete a caller's file.
+   * @experimental
+   */
+  exportReleaseTemporaryOutput(uri: string): string
+  /**
+   * Remove `.pictor-staging-*.tmp` orphans a killed process left behind.
+   *
+   * Positively identified by prefix and suffix; never a wildcard. @experimental
+   */
+  exportSweepStagingOrphans(directory: string): string
+  /** Counted work plus the beat total, for the progress pump. @experimental */
+  exportProgressSnapshot(): string
+  /**
+   * What a picked audio file actually contains.
+   *
+   * Duration, audio-track presence, seekability and MIME, read by opening the
+   * file. The host asks this before a sound may enter a project: the mix
+   * compiler has no decoder and believes whatever the document declares, and a
+   * document that claimed audio a file lacked cost a whole export. Returns
+   * `{ok, durationUs, hasAudioTrack, seekable, mimeType}` or `{ok:false,
+   * reason}` — never throws, because an unreadable pick is an answer.
+   * @experimental
+   */
+  /**
+   * Prepare the audio a preview plays, off the JS thread.
+   *
+   * The same mixer an export runs, over the same compiled program. Resolves
+   * `{ok, uri, key, cached, byteLength}`, or `{ok:false, superseded}` when a
+   * newer request replaced it — which a caller must never publish.
+   * @experimental
+   */
+  previewMixPrepare(
+    jobId: string,
+    programJson: string,
+    urisJson: string,
+  ): Promise<string>
+  /**
+   * Load a prepared mix into the mixed-audio player, stamped with an epoch.
+   *
+   * The epoch is how a start or a seek proves it belongs to the mix currently
+   * playing; one carrying an older epoch is dropped. @experimental
+   */
+  previewAudioLoad(uri: string, epoch: number): string
+  /** Start, if the epoch still matches. @experimental */
+  previewAudioPlay(epoch: number): string
+  /** @experimental */
+  previewAudioPause(): string
+  /** Seek to a global timeline position, if the epoch still matches. @experimental */
+  previewAudioSeek(positionUs: number, epoch: number): string
+  /** Preview rate. Clip speed is already compiled into the mix. @experimental */
+  previewAudioSetRate(rate: number): string
+  /** Position and the wall clock it was sampled at, for drift. @experimental */
+  previewAudioState(): string
+  /**
+   * Silence the video player's own audio while a mixed preview plays.
+   *
+   * The mix contains the clips' audio too, so both audible plays the timeline
+   * twice. @experimental
+   */
+  previewMuteSourceAudio(muted: boolean): string
+  /** @experimental */
+  previewAudioRelease(): string
+  /**
+   * Gate-only: encode a fixed, natively generated PCM fixture and describe the
+   * result — access units, timestamps, CSD, payload hashes and decoded metrics.
+   *
+   * The inputs are formulas rather than files, so a baseline taken before a
+   * change to the encoder loop is comparable with one taken after it.
+   * @experimental
+   */
+  encoderGateRun(fixture: string, maxInputSize: number): string
+  /** Gate-only: where samples go, stage by stage, for one marker source. @experimental */
+  primingAttribution(): string
+  /** Gate-only: the file-measurable Music gates, in one run. @experimental */
+  musicGates(): string
+
+  /**
+   * Gate-only: mix the marker fixture at a chosen timeline start, decode the
+   * result and report where the markers actually landed. @experimental
+   */
+  previewAlignmentGate(startUs: number): string
+
+  /** Gate-only: arm the paired player trace and sample every `intervalMs`. @experimental */
+  previewTraceArm(on: boolean, intervalMs: number): string
+  /** Gate-only: label the trace so a harness can find its own cases. @experimental */
+  previewTraceMark(label: string): string
+  /** Gate-only: drain trace events from a sequence number, paged. @experimental */
+  previewTraceDrain(fromSeq: number, limit: number): string
+  /**
+   * Compare both players on one clock and correct the mix past a tolerance.
+   *
+   * Native because that is where both anchors are published; measuring across
+   * the bridge would carry the hop's own jitter into the answer. @experimental
+   */
+  previewDriftCheck(toleranceUs: number): string
+  /**
+   * Stop playback for a host reason — background, picker, unmount.
+   *
+   * Overrides any automatic resume the stall coordinator is holding, so
+   * playback cannot restart at a moment nobody asked for. @experimental
+   */
+  previewSyncStop(reason: string): string
+  /** What the stall coordinator has done, for assertions. @experimental */
+  previewSyncCounters(): string
+  /**
+   * Frames offered, queued and drawn.
+   *
+   * Read-only accounting, available in release, so the question "is the trace
+   * disturbing the picture?" can be asked without the trace. @experimental
+   */
+  previewFramePipeline(): string
+  /**
+   * Gate-only: the shared-clock playback spike.
+   *
+   * `spikeStart` takes `{items:[{uri,startUs,endUs,speed}], mixUri, width,
+   * height}` straight from `playlistOf()`, so the compiler decides the timing
+   * and native maps it onto media items without interpreting the project.
+   */
+  spikeStart(specJson: string): string
+  spikePlay(): string
+  spikePause(): string
+  spikeSeek(positionUs: number): string
+  spikeClaim(): string
+  spikeState(): string
+  spikeDrain(fromSeq: number, limit: number): string
+  spikeRelease(): string
+  /**
+   * Gate-only: turn parts of the music preview off, to bisect a failure.
+   *
+   * `{loadPlayer, startMix, positionPump, coordinator}`, all true in
+   * production. @experimental
+   */
+  previewConfigSet(json: string): string
+  /** What the configuration currently is. @experimental */
+  previewConfigGet(): string
+  /** Every codec mix preparation owns, and what became of it. @experimental */
+  previewCodecLedger(): string
+  /** Stop whatever is preparing. @experimental */
+  previewMixCancel(): string
+  /** The cache key for a program, without preparing it. @experimental */
+  previewMixKey(programJson: string, urisJson: string): string
+  /** Drop one prepared mix. @experimental */
+  previewMixRelease(key: string): string
+  /** Keep only these keys; remove the rest and every partial. @experimental */
+  previewMixSweep(keepKeysJson: string): string
+  /** What is prepared, for assertions. @experimental */
+  previewMixLedger(): string
+  /**
+   * Copy a picked source into app-owned durable storage.
+   *
+   * A picker returns a reference, not a file: a `content://` grant dies with
+   * the activity result and a cache copy dies whenever Android wants storage
+   * back. The project persists what this returns, never what a picker did.
+   * Content-addressed, so the same song added twice is stored once. Returns
+   * `{ok, uri, token, byteLength, sha256, created}` or `{ok:false, reason}`.
+   * @experimental
+   */
+  ingestManagedSource(uri: string): string
+  /** Drop one managed source by token. @experimental */
+  releaseManagedSource(token: string): string
+  /**
+   * Remove every managed source not named in `keepTokensJson`, and every
+   * partial a killed process left. The only thing that deletes media.
+   * @experimental
+   */
+  sweepManagedSources(keepTokensJson: string): string
+  /**
+   * Every filename in the managed directory, including partials and strays.
+   *
+   * Read-only accounting. `managedSourceLedger` reports only well-formed
+   * sources, which cannot show what a sweep left behind. @experimental
+   */
+  managedSourceList(): string
+  /** Gate-only: sweep with an unparsed keep list. @experimental */
+  managedSourceGateSweepRaw(rawKeep: string): string
+  /** Gate-only: seed a file with an exact name, to exercise the sweep. @experimental */
+  managedSourceGateSeed(name: string, bytes: number): string
+  /** Tokens and sizes of what is stored, for assertions. @experimental */
+  managedSourceLedger(): string
+  probeAudioSource(uri: string): string
+  /** Confirm the destination is closed and parseable. @experimental */
+  exportProbeOutput(uri: string): string
+  /** Gate-only: hold inside the media copy, so a kill can land there. @experimental */
+  exportGateHoldMediaCopy(enabled: boolean): string
+  /** Gate-only: wedge the cadence program after N frames. -1 is off. @experimental */
+  exportGateStallAfterFrames(frames: number): string
+  /**
+   * Arm the gate-only controls. Everything gate-only is inert until this is
+   * called, and the production exporter never calls it. @experimental
+   */
+  exportGateEnableDiagnostics(enabled: boolean): string
+  /** Gate-only: fail publication at a chosen point. @experimental */
+  exportGatePublishFault(mode: string): string
+  /** Gate-only: does this directory's filesystem have an atomic no-replace? @experimental */
+  exportGateProbeNoReplace(directory: string): string
+  /** Gate-only: size and CRC32, to prove a file did or did not change. @experimental */
+  exportGateFileDigest(path: string): string
+  /** Gate-only: which temporaries are still registered, by name. @experimental */
+  exportGateLiveTemporaries(): string
+  /** Gate-only: remove a file, so a case can start from a known state. @experimental */
+  exportGateDeleteFile(path: string): string
+  /** Gate-only: a writable directory that is not the gallery. @experimental */
+  exportGateExternalFilesDir(): string
+  /** Gate-only: the current heartbeat epoch. @experimental */
+  exportGateBeatEpoch(): string
+  /** Gate-only: offer a beat for `epoch`; reports acceptance. @experimental */
+  exportGateTestBeat(source: string, epoch: number): string
+  /** Gate-only: enable sample hashing for conformance checks. @experimental */
+  exportGateProvenance(enabled: boolean): string
+  /** Heartbeat counts and the maximum gap per source. @experimental */
+  exportGateHeartbeats(): string
+  /** Gate-only: started/completed/failed/released accounting. @experimental */
+  exportGateAccounting(): string
+  /** Stop `jobId` if it is the one running. Idempotent. @experimental */
+  exportCancelJob(jobId: string): string
+  exportGateRunProject(
+    shardsJson: string,
+    programJson: string,
+    overlaysJson: string,
+    mixProgramJson: string,
+    mixUrisJson: string,
+    timeoutSeconds: number,
+    destinationJson: string,
+  ): string
+  /**
+   * **V3.5 gate only.** Mix a compiled `AudioMixProgram` and encode it once.
+   *
+   * `urisJson` maps span id to a host-resolved URI. Native reads only the plan:
+   * no audio kinds, no duration policy, no project.
+   *
+   * @experimental
+   */
+  exportGateMixAudio(programJson: string, urisJson: string): string
+  /**
+   * **V3.5 gate only.** Decode one window and report every stage.
+   *
+   * Running the identical window at 1x and another rate settles which stage is
+   * responsible: matching cropped counts with differing stretched counts point
+   * at the stretch, differing cropped counts at the decode.
+   *
+   * @experimental
+   */
+  exportGateDecodeProbe(uri: string, fromUs: number, toUs: number, speed: number): string
+  /** Per-window dominant-frequency trajectory and harmonic band energies. @experimental */
+  exportGateTrajectory(uri: string, spec: string): string
+  /** Copy a gate output to external files, for the human gates. @experimental */
+  exportGateStage(uri: string, name: string): string
+  /** Measure this encoder configuration's priming from a burst at `at`. @experimental */
+  exportGatePrimingProbe(rate: number, channels: number, bitrate: number, at: number): string
+  /** Decode a window under a simulated decoder warm-up requirement. @experimental */
+  exportGatePrerollProbe(uri: string, fromUs: number, toUs: number, warmupUs: number): string
+  /**
+   * **V3.5 gate only.** Run the time-stretch alone on synthetic PCM.
+   *
+   * @experimental
+   */
+  exportGateStretchProbe(rate: number, channels: number, frames: number, speed: number): string
+  exportGateStageResource(base64: string, width: number, height: number): string
+  media3Play(): void
+  media3Pause(): void
+  /** Microseconds, like every other time in Pictor. */
+  media3Seek(positionUs: number): void
+  media3SetRate(rate: number): void
+  /** Media3's own recovery after a source failure: prepare again. */
+  media3Retry(): void
+  media3Release(): void
+  /** A throttled snapshot: position, size, counters and any source error. */
+  media3State(): Object
+
+  /**
+   * Start decoding one still frame. Returns a token to poll or cancel with.
+   *
+   * Not a Promise: a strip issues and abandons requests in bursts, and a
+   * rejected Promise per abandoned request is noisy and hard to cancel. A
+   * token the caller owns makes "stop this one" expressible.
+   */
+  thumbnailRequest(uri: string, sourceTimeUs: number, widthPx: number): number
+  thumbnailCancel(token: number): void
+  /** Base64 JPEG, or null while it is still decoding. Consumes the result. */
+  thumbnailTake(token: number): string | null
+  thumbnailError(token: number): string | null
+  thumbnailRunning(token: number): boolean
+  thumbnailReleaseSource(uri: string): void
+  thumbnailReleaseAll(): void
+  /** `{ decoded, cancelled, failed, running, retrievers }`. */
+  thumbnailCounters(): Object
+}
+
+export default TurboModuleRegistry.get<Spec>('PictorVideo')

package/src/audioProbe.ts

@@ -0,0 +1,72 @@
+import type { AudioProbe } from '@pictor-sdk/video-core'
+import { requireNative } from './player'
+
+/**
+ * Reading what a picked audio file actually contains.
+ *
+ * The structural half of {@link AudioProbe} lives in `@pictor-sdk/video-core`,
+ * which has no decoder and never will; this is the adapter that can answer it.
+ * A host calls this once, before adding, and passes the result to
+ * `acceptAudioSource`.
+ *
+ * Nothing here identifies the file. The display name is the host's to carry —
+ * a picker URI embeds an id and sometimes a user's own folder names.
+ *
+ * @experimental
+ */
+
+/** A probe that failed, with a reason fit for a log rather than a person. @experimental */
+export interface AudioProbeFailure {
+  ok: false
+  /** Why the file could not be read. Diagnostic, not a user-facing sentence. */
+  reason: string
+}
+
+/** What native learned, minus the display name only the host knows. @experimental */
+export type AudioProbeResult = ({ ok: true } & Omit<AudioProbe, 'displayName'>) | AudioProbeFailure
+
+/**
+ * Open `uri` and report its audio.
+ *
+ * Never throws for an unreadable file: a pick that cannot be read is an answer,
+ * and a host that had to wrap this in a `try` would be handling a normal
+ * outcome as an exception. It throws only if the adapter is not installed,
+ * which is a wiring mistake rather than a file.
+ *
+ * @experimental
+ */
+export function probeAudioSource(uri: string): AudioProbeResult {
+  let raw: string
+  try {
+    raw = requireNative().probeAudioSource(uri)
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) }
+  }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return { ok: false, reason: 'probe returned unparseable JSON' }
+  }
+
+  const value = parsed as Partial<AudioProbe> & { ok?: boolean; reason?: string }
+  if (value.ok !== true) {
+    return { ok: false, reason: typeof value.reason === 'string' ? value.reason : 'probe failed' }
+  }
+
+  /*
+    Normalised here, not trusted as-is.
+
+    Everything downstream treats these as decided facts — `hasAudioTrack` ends
+    up in `metadata.hasAudio`, which is what the encoder is told. A missing or
+    malformed field must not arrive as `undefined` and read as permission.
+  */
+  return {
+    ok: true,
+    durationUs: Number.isFinite(value.durationUs) ? Number(value.durationUs) : 0,
+    hasAudioTrack: value.hasAudioTrack === true,
+    seekable: value.seekable === true,
+    mimeType: typeof value.mimeType === 'string' ? value.mimeType : '',
+  }
+}