Recording and packages

Recording happens entirely inside a perform or edit_and_perform session. Add a source image before recording. Smore validates the take, normalizes it to MP4/H.264 when necessary, and creates a reference package before notifying the parent page.

Receive the package ID

The iframe emits an at-least-once message:

{
  "v": 1,
  "type": "smore:reference-package",
  "referencePackageId": "reference-package-id"
}

Forward only the package ID to an authenticated endpoint on your own origin. That endpoint must authorize the partner scene, load its expected Smore scene ID from your database, and durably enqueue both IDs.

await enqueueVideoGeneration({
  deduplicationKey: `${expectedSmoreSceneId}:${referencePackageId}`,
  expectedSmoreSceneId,
  referencePackageId,
});

Do not call the package API from browser code and do not place the Smore secret key in the iframe host.

Retrieve when work starts

const packageResponse = await smoreFetch(
  `/v1/reference-packages/${referencePackageId}`,
  { method: "GET", signal: AbortSignal.timeout(15_000) },
);

if (!packageResponse.ok) throw await packageResponse.json();
const referencePackage = await packageResponse.json();

if (referencePackage.sceneId !== expectedSmoreSceneId) {
  throw new Error("Reference package scene mismatch");
}

The response pairs:

• The scene’s validated original source image
• The exact scene version recorded by the user
• A normalized MP4/H.264 camera-reference clip

Media URLs expire after 15 minutes. Store the package ID—not the signed URLs—and retrieve fresh URLs when the job actually starts.

Acknowledge durable receipt

After validating the scene binding and durably recording or queueing the package:

const ackResponse = await smoreFetch(
  `/v1/reference-packages/${referencePackageId}/ack`,
  { method: "POST", signal: AbortSignal.timeout(15_000) },
);

if (ackResponse.status !== 204) throw await ackResponse.json();

Acknowledgment is idempotent. It stops repeated notifications but does not delete the package or prevent later signed-URL refreshes.

Recover missed notifications

On worker startup and reconnect, read:

GET /v1/scenes/{sceneId}/pending-reference-packages

Queue each returned ID using the same scene-and-package deduplication key. Continue after acknowledgment until the endpoint returns an empty array.