@pictor-sdk/video-android 0.1.0 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pictor-sdk/video-android",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "description": "Optional Android video playback and export adapter for Pictor. Requires Android API 29+.",
   "license": "MIT",
   "main": "./dist/index.js",
@@ -29,7 +29,7 @@
     "react": ">=18.0.0",
     "@expo/config-plugins": ">=54.0.0",
     "react-native-reanimated": ">=3.16.0",
-    "@pictor-sdk/video-core": "^0.1.0"
+    "@pictor-sdk/video-core": "^0.1.1"
   },
   "devDependencies": {
     "react-native": "^0.81.0",
@@ -40,7 +40,7 @@
     "@types/react": "^19.0.0",
     "@expo/config-plugins": "^54.0.5",
     "react-native-reanimated": "^4.1.0",
-    "@pictor-sdk/video-core": "0.1.0"
+    "@pictor-sdk/video-core": "0.1.1"
   },
   "codegenConfig": {
     "name": "PictorVideoSpec",

package/plugin/gradleProperties.js

@@ -11,14 +11,17 @@
  */
 
 /**
- * The oldest Android the adapter is known to run on.
+ * The oldest Android the adapter builds against.
  *
- * Conservative, and deliberately so: the surviving code path needs 24, and 29 is
- * held only because nothing older than the one device here has actually run it.
- * Installing this adapter raises a host's `minSdkVersion`; not installing it
- * leaves image-only consumers exactly where they were.
+ * 24, matching `android/build.gradle` — the two have to agree or a prebuild
+ * writes a floor the library then rejects. React Native needs 24 and Media3
+ * 1.9.4 declares 23, so nothing below this is reachable anyway.
+ *
+ * This is a *build* floor. Whether 24..28 actually works is a separate claim,
+ * and `docs/research/min-sdk-24.md` records how far it has been taken. A host
+ * that wants a higher floor passes one: this raises, never lowers.
  */
-const MIN_SDK_VERSION = 29
+const MIN_SDK_VERSION = 24
 
 const MIN_SDK_KEY = 'android.minSdkVersion'
 

package/src/NativePictorVideo.ts

@@ -469,6 +469,17 @@ export interface Spec extends TurboModule {
   exportGateHoldMediaCopy(enabled: boolean): string
   /** Gate-only: wedge the cadence program after N frames. -1 is off. @experimental */
   exportGateStallAfterFrames(frames: number): string
+  /**
+   * Gate-only: the smallest failing Media3 export, one stage at a time.
+   *
+   * Takes a JSON spec — uri, source span in microseconds, the configured speed
+   * and the emission plan `resampleClip` compiled — and runs a plain
+   * Transformer, then the same run with speed mapping, cadence and Skia added
+   * individually. Starts in the background and returns immediately; each rung
+   * and the whole ladder are reported to logcat under `PictorLadderRung` and
+   * `PictorLadder`. @experimental
+   */
+  exportGateLadder(specJson: string): string
   /**
    * Arm the gate-only controls. Everything gate-only is inert until this is
    * called, and the production exporter never calls it. @experimental

package/src/compositionSpike.ts

@@ -34,6 +34,10 @@ export interface CompositionSpikeItem {
   /** Clipping bounds in **source** time, which is where speed is applied. */
   startUs: number
   endUs: number
+  /** Full source duration, before trimming or speed. Omit only for legacy callers. */
+  sourceDurationUs?: number
+  /** Exclusive project-time end from the playlist compiler, after trim and speed. */
+  timelineEndUs?: number
   speed: number
 }
 
@@ -122,6 +126,8 @@ export interface CompositionSpikeState {
   playbackState?: number
   durationUs?: number
   presentedUs?: number | null
+  /** Playlist window belonging to the latched frame, not the current playhead. */
+  presentedWindowIndex?: number
   /** 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. */
@@ -148,6 +154,7 @@ export function compositionSpikeSpec(
   const playlist = playlistOf(project)
   const items: CompositionSpikeItem[] = []
   const unsupported = playlist.unsupported.map((u) => `${u.clipId}: ${u.reason}`)
+  const clips = new Map(project.clips.map((clip) => [clip.id, clip]))
   for (const item of playlist.items) {
     const uri = resolve(item.source as unknown as { kind: string; uri?: string })
     if (uri === null) {
@@ -158,6 +165,8 @@ export function compositionSpikeSpec(
       uri,
       startUs: Number(item.startUs),
       endUs: Number(item.endUs),
+      sourceDurationUs: clips.get(item.clipId)?.metadata.duration,
+      timelineEndUs: Number(item.timelineEndUs),
       speed: item.speed,
     })
   }

package/src/exporter.ts

@@ -169,6 +169,27 @@ export interface Media3ExporterOptions {
    * Native counting is unthrottled regardless; this is only the bridge rate.
    */
   progressPollMs?: number
+  /**
+   * Which mechanism re-times a clip's **video** when its speed is not 1.
+   *
+   * `'cadence'` (the default, and what has shipped) compiles an exact emit plan
+   * in `resampleClip` and a GL effect drops or repeats frames to match it. The
+   * plan's length is the clip's length by construction, so project time is
+   * exact — and above 1× the decoder still reads every source frame, which is
+   * what produces a burst of output followed immediately by end-of-stream.
+   *
+   * `'media3'` sends no plan, so no cadence effect is built and
+   * `EditedMediaItem.setSpeed` carries the video timing on its own.
+   *
+   * Exposed because the burst is implicated in a vendor encoder that drops its
+   * output end-of-stream at high rates — see
+   * `docs/research/export-speed-stall.md`. It is a comparison switch, not a
+   * recommendation: the two paths select different frames, and which one is
+   * correct is what the comparison is for.
+   *
+   * @experimental
+   */
+  videoSpeedVia?: 'cadence' | 'media3'
 }
 
 /** Why an export will not start. @experimental */
@@ -357,9 +378,18 @@ export function createMedia3VideoExporter(options: Media3ExporterOptions): Video
       }
       const resources = overlayPlan.resources
 
+      /*
+        Whether a re-timed clip gets an emit plan at all.
+
+        Omitting it is how the cadence effect is left out: native builds one
+        only when both arrays arrive, so there is no second switch to keep in
+        step. A clip at 1× has nothing to re-time either way.
+      */
+      const viaMedia3 = options.videoSpeedVia === 'media3'
       const shards = plan.map((shard, index) => {
         const clip = playable[index]!
-        const cadence = cadenceFor(shard.plan.frames)
+        const cadence =
+          viaMedia3 && clip.speed !== 1 ? null : cadenceFor(shard.plan.frames)
         return {
           uri: uris[index]!,
           startMs: Math.round(clip.sourceIn / 1000),
@@ -378,11 +408,19 @@ export function createMedia3VideoExporter(options: Media3ExporterOptions): Video
             What matters is that the *source's* audio never enters this pipeline:
             a per-shard audio track has to be re-encoded to concatenate, which is
             what put a second generation on everything the user hears.
+
+            `ExportGate` notes that `setRemoveAudio` beside a speed change is a
+            combination Media3 warns about, and that was tried as a candidate
+            fix for the high-rate export stall: giving the re-timing the real
+            stream instead of silence. It made no difference to the fault — the
+            encoder stopped at exactly the same place — so the change was
+            reverted rather than kept for a benefit that could not be shown.
+            See `docs/research/export-speed-stall.md`.
           */
           forceAudioTrack: true,
           removeAudio: true,
-          emitsPerInput: cadence.emitsPerInput,
-          outputPtsUs: cadence.outputPtsUs,
+          emitsPerInput: cadence?.emitsPerInput,
+          outputPtsUs: cadence?.outputPtsUs,
           spanUs: Math.round((shard.plan.frameCount * 1_000_000) / fps),
         }
       })