@pictor-sdk/video-android 0.1.6 → 0.2.0

package/android/src/main/java/dev/pictor/video/ExportGate.kt

@@ -1598,6 +1598,123 @@ internal class ExportGate(private val context: Context) {
         }
     }
 
+    /**
+     * Export a single still photograph with animated overlays.
+     *
+     * The still is encoded directly from the PNG through the same image path
+     * `runStill` proves, and the overlays are the same compiled scene program a
+     * video project uses. There is no audio and no mux: a photo story gets a
+     * silent MP4 whose duration is the story duration.
+     *
+     * Publication is the same staged rename as `runProject`, because the failure
+     * that matters is identical — a half-written file replacing a good one.
+     */
+    fun runPhotoProject(
+        pngBytes: ByteArray,
+        programJson: String,
+        overlaysJson: String,
+        durationUs: Long,
+        timeoutSeconds: Long = 180,
+        destinationJson: String = "",
+    ): Outcome {
+        val target = if (destinationJson.isEmpty()) null else GateDestination.parse(destinationJson)
+        if (target != null) {
+            GateDestination.validate(target)?.let {
+                refusals.incrementAndGet()
+                return failed(it, 0, Thread.currentThread().name)
+            }
+        }
+        if (durationUs <= 0) {
+            refusals.incrementAndGet()
+            return failed("photo duration must be positive", 0, Thread.currentThread().name)
+        }
+        val (compiled, invalid) = SceneProgramNative.parse(programJson)
+        if (compiled == null) {
+            refusals.incrementAndGet()
+            return failed("program rejected: " + (invalid?.reason ?: "unknown"), 0, Thread.currentThread().name)
+        }
+        val (resources, badResource) = OverlayResources.parse(context, overlaysJson)
+        if (resources == null) {
+            refusals.incrementAndGet()
+            return failed(
+                "overlay resources rejected: " + (badResource?.reason ?: "unknown"),
+                0, Thread.currentThread().name,
+            )
+        }
+        for (id in compiled.requiredResourceIds()) {
+            if (!resources.entries.containsKey(id)) {
+                refusals.incrementAndGet()
+                return failed(
+                    "overlay resource '" + id + "' is referenced by the program but not supplied",
+                    0, Thread.currentThread().name,
+                )
+            }
+        }
+        val still = File.createTempFile(TEMP_PREFIX + "photo-", ".png", context.cacheDir)
+        synchronized(created) { tempFilesCreated.incrementAndGet(); created.add(still) }
+        var videoUri: String? = null
+        try {
+            still.writeBytes(pngBytes)
+            val video = runSequence(
+                listOf(still.absolutePath), timeoutSeconds, compiled,
+                withSkia = true, stillDurationUs = durationUs, overlays = resources,
+            )
+            if (!video.ok) return video
+            videoUri = video.uri
+            if (target == null) return video.copy(hasAudio = false)
+            if (cancelled) {
+                return failed("cancelled during publishing", 0, Thread.currentThread().name)
+            }
+            val output = File(video.uri)
+            val sweptStaging = GateDestination.sweepStaging(target)
+            val staging = GateDestination.stagingFor(target, System.nanoTime())
+            synchronized(created) { tempFilesCreated.incrementAndGet(); created.add(staging) }
+            val stageError = GateDestination.stage(
+                output, staging, keepGoing = { !cancelled },
+                beatEpoch = ExportHeartbeat.currentEpoch(),
+            )
+            if (stageError != null) {
+                releaseTemp(staging)
+                return failed(
+                    if (stageError == "cancelled") "cancelled during publishing" else stageError,
+                    0, Thread.currentThread().name,
+                )
+            }
+            val stagedProbe = GateDestination.probe(staging.absolutePath)
+            if (!stagedProbe.optBoolean("readable", false)) {
+                releaseTemp(staging)
+                return failed(
+                    "the staged file could not be read back: " + stagedProbe.optString("error", "no video track"),
+                    0, Thread.currentThread().name,
+                )
+            }
+            GateDestination.publish(staging, target)?.let {
+                releaseTemp(staging)
+                return failed(it, 0, Thread.currentThread().name)
+            }
+            synchronized(created) {
+                if (created.remove(staging)) tempFilesReleased.incrementAndGet()
+            }
+            return video.copy(
+                uri = target.path,
+                fileBytes = File(target.path).length(),
+                hasAudio = false,
+                boundary = if (sweptStaging > 0) "sweptStaging=" + sweptStaging else video.boundary,
+            )
+        } finally {
+            releaseTemp(still)
+            /*
+              A temporary belongs to the caller.
+
+              The adapter probes the returned uri before it reports success, so
+              releasing it here deletes the file out from under that probe —
+              which is exactly an unopenable "success". Only a published file
+              leaves a temp of ours to clean up.
+            */
+            if (target != null) videoUri?.let { releaseTemp(File(it)) }
+        }
+    }
+
     /**
      * One audio-only pass over the whole timeline.
      *

package/android/src/main/java/dev/pictor/video/PictorVideoModule.kt

@@ -369,6 +369,50 @@ class PictorVideoModule(reactContext: ReactApplicationContext) :
         return GateFrames.framePng(reactApplicationContext, uri, timeUs.toLong())
     }
 
+    /**
+     * Export a photo story: one still, animated overlays, no audio.
+     *
+     * The base is PNG bytes because a photo story has no video source. Animated
+     * overlays are the same resource list the video exporter prepares, so the
+     * still path cannot drift into a second renderer.
+     */
+    @androidx.media3.common.util.UnstableApi
+    override fun exportRunPhotoProjectAsync(
+        jobId: String,
+        pngPath: String,
+        programJson: String,
+        overlaysJson: String,
+        durationUs: Double,
+        timeoutSeconds: Double,
+        destinationJson: String,
+        promise: com.facebook.react.bridge.Promise,
+    ) {
+        val running = gate ?: ExportGate(reactApplicationContext).also { gate = it }
+        if (!running.beginJob(jobId)) {
+            promise.resolve(
+                org.json.JSONObject().put("ok", false)
+                    .put("error", "an export is already running").toString(),
+            )
+            return
+        }
+        exportExecutor.execute {
+            val outcome = try {
+                val bytes = java.io.File(pngPath).readBytes()
+                val result = running.runPhotoProject(
+                    bytes, programJson, overlaysJson, durationUs.toLong(),
+                    timeoutSeconds.toLong(), destinationJson,
+                )
+                report(result, running)
+            } catch (e: Throwable) {
+                org.json.JSONObject().put("ok", false)
+                    .put("error", e.javaClass.simpleName + ": " + e.message).toString()
+            } finally {
+                running.endJob()
+            }
+            promise.resolve(outcome)
+        }
+    }
+
     /**
      * Run an export off the bridge, so it can be cancelled while it runs.
      *

package/dist/index.d.mts

@@ -1318,6 +1318,18 @@ interface Media3ExporterOptions {
      * @experimental
      */
     videoSpeedVia?: 'cadence' | 'media3';
+    /**
+     * Render one photo clip to the PNG a photo-story export encodes.
+     *
+     * A photo project has no video source for the base frame, so the host renders
+     * it through the same document renderer the preview uses and returns a local
+     * PNG path. Without this a photo project is refused exactly as before.
+     *
+     * Only a project consisting of exactly one photo is accepted: a sequence of
+     * stills is a slideshow with its own timeline rules, and silently treating it
+     * as one long still would be a different composition.
+     */
+    renderPhotoBase?(source: MediaSource, clipId: string): Promise<string>;
 }
 /** Why an export will not start. @experimental */
 declare class VideoExportRejected extends Error {

package/dist/index.d.ts

@@ -1318,6 +1318,18 @@ interface Media3ExporterOptions {
      * @experimental
      */
     videoSpeedVia?: 'cadence' | 'media3';
+    /**
+     * Render one photo clip to the PNG a photo-story export encodes.
+     *
+     * A photo project has no video source for the base frame, so the host renders
+     * it through the same document renderer the preview uses and returns a local
+     * PNG path. Without this a photo project is refused exactly as before.
+     *
+     * Only a project consisting of exactly one photo is accepted: a sequence of
+     * stills is a slideshow with its own timeline rules, and silently treating it
+     * as one long still would be a different composition.
+     */
+    renderPhotoBase?(source: MediaSource, clipId: string): Promise<string>;
 }
 /** Why an export will not start. @experimental */
 declare class VideoExportRejected extends Error {

package/dist/index.js

@@ -1825,11 +1825,26 @@ var VideoExportRejected = class extends Error {
   }
 };
 var DEFAULT_FPS = 30;
-function describeUnsupported(project, spec) {
+function animatedSchedulesFor(project) {
+  const schedules = {};
+  for (const overlay of project.overlays) {
+    if (overlay.type !== "sticker") continue;
+    const data = overlay.data;
+    if (data && data.animation) schedules[overlay.id] = data.animation;
+  }
+  return schedules;
+}
+function describeUnsupported(project, spec, options) {
   const reasons = [];
   for (const clip of project.clips) {
     if (clip.kind === "photo") {
-      reasons.push(`clip '${clip.id}' is a photo, which this exporter does not encode yet`);
+      if (!options.renderPhotoBase) {
+        reasons.push(`clip '${clip.id}' is a photo, and no photo renderer was supplied`);
+      } else if (project.clips.length !== 1) {
+        reasons.push(
+          `clip '${clip.id}' is a photo in a project of ${project.clips.length} clips; only a single-photo story is supported`
+        );
+      }
       continue;
     }
   }
@@ -1861,11 +1876,107 @@ function createMedia3VideoExporter(options) {
         if (issues.length > 0) {
           throw new VideoExportRejected(issues.map((issue) => issue.message));
         }
-        const unsupported = describeUnsupported(project, spec);
+        const unsupported = describeUnsupported(project, spec, options);
         if (unsupported.length > 0) throw new VideoExportRejected(unsupported);
         const decision = resolveDestination(spec.destination);
         if (decision.destination === null) throw new VideoExportRejected(decision.reasons);
         const destination = decision.destination;
+        const photoOnly = project.clips.length === 1 && project.clips[0].kind === "photo";
+        if (photoOnly) {
+          const clip = project.clips[0];
+          if (!options.renderPhotoBase) {
+            throw new VideoExportRejected([`clip '${clip.id}' is a photo, and no photo renderer was supplied`]);
+          }
+          const pngPath = await options.renderPhotoBase(clip.source, clip.id);
+          job.checkpoint("resolving");
+          const photoProgram = (0, import_video_core6.compileVideoSceneProgram)(project, {
+            animatedSchedules: animatedSchedulesFor(project)
+          });
+          if (photoProgram.segments.length === 0) {
+            throw new VideoExportRejected(["the compiled program has no segments"]);
+          }
+          const named2 = /* @__PURE__ */ new Set();
+          for (const segment of photoProgram.segments) {
+            for (const command of segment.commands) {
+              if (command.op === "overlay") named2.add(command.overlayId);
+            }
+          }
+          const overlayPlan2 = options.prepareOverlays ? options.prepareOverlays(photoProgram, project.size, 1) : {
+            resources: [],
+            pending: [],
+            invalid: [...named2].map((overlayId) => ({
+              overlayId,
+              kind: "unknown",
+              reason: "no prepareOverlays was supplied, so this overlay has no portable form"
+            }))
+          };
+          const stagedNow2 = overlayPlan2.resources.map((resource) => resource.file);
+          if (overlayPlan2.pending.length > 0) {
+            options.releaseResources?.(stagedNow2);
+            throw new VideoExportRejected(
+              overlayPlan2.pending.map(
+                (id) => `overlay '${id}' is still preparing; export would omit it`
+              )
+            );
+          }
+          if (overlayPlan2.invalid.length > 0) {
+            options.releaseResources?.(stagedNow2);
+            throw new VideoExportRejected(
+              overlayPlan2.invalid.map(
+                (bad) => `overlay '${bad.overlayId}' (${bad.kind}): ${bad.reason}`
+              )
+            );
+          }
+          job.checkpoint("overlays");
+          let outcome2;
+          try {
+            outcome2 = JSON.parse(
+              await nativeModule().exportRunPhotoProjectAsync(
+                job.id,
+                pngPath,
+                JSON.stringify({
+                  version: import_video_core6.VIDEO_SCENE_PROGRAM_VERSION,
+                  projectSize: { width: project.size.width, height: project.size.height },
+                  durationUs: photoProgram.durationUs,
+                  segments: photoProgram.segments
+                }),
+                JSON.stringify(overlayPlan2.resources),
+                (0, import_video_core6.projectDuration)(project),
+                180,
+                destination.kind === "file" ? JSON.stringify({
+                  kind: "file",
+                  path: destination.path,
+                  overwrite: destination.overwrite
+                }) : ""
+              )
+            );
+          } finally {
+            options.releaseResources?.(stagedNow2);
+          }
+          if (!outcome2.ok) {
+            const error = outcome2.error || "the export failed";
+            if (isRefusal(error)) throw new VideoExportRejected([error]);
+            throw new import_video_core6.VideoExportFailed(job.id, "encoding", error);
+          }
+          const probe2 = JSON.parse(nativeModule().exportProbeOutput(outcome2.uri));
+          if (!probe2.readable) {
+            throw new import_video_core6.VideoExportFailed(
+              job.id,
+              "publishing",
+              `${describeTarget(outcome2.uri)} could not be read back: ${probe2.error ?? "no video track"}`
+            );
+          }
+          if (destination.kind === "file") return { kind: "file", uri: outcome2.uri };
+          const temporaryUri2 = outcome2.uri;
+          return {
+            kind: "temporary",
+            uri: temporaryUri2,
+            release: async () => {
+              await Promise.resolve();
+              nativeModule().exportReleaseTemporaryOutput(temporaryUri2);
+            }
+          };
+        }
         const playable = project.clips.filter((clip) => (0, import_video_core6.isPlayableWindow)(clip));
         if (playable.length === 0) throw new VideoExportRejected(["the project has no playable clips"]);
         if (!((0, import_video_core6.projectDuration)(project) > 0)) {
@@ -1892,7 +2003,9 @@ function createMedia3VideoExporter(options) {
           targetFps: fps
         }));
         const plan = (0, import_video_core6.planClipShards)(requests, fps);
-        const program = (0, import_video_core6.compileVideoSceneProgram)(project);
+        const program = (0, import_video_core6.compileVideoSceneProgram)(project, {
+          animatedSchedules: animatedSchedulesFor(project)
+        });
         if (program.segments.length === 0) {
           throw new VideoExportRejected(["the compiled program has no segments"]);
         }