@run-cloud/sdk 0.21.0 → 0.22.1

package/dist/remotion.d.ts

@@ -1,4 +1,4 @@
-import type { CreateSandboxOptions, ExecOptions, ExecResult, Sandbox } from "./index.js";
+import type { CreateSandboxOptions, ExecOptions, ExecResult, Sandbox, Snapshot } from "./index.js";
 export declare const REMOTION_IMAGE_REGISTRY = "us-docker.pkg.dev/remotion-dev/production/render";
 export type RemotionCodec = "h264" | "h265" | "vp8" | "vp9" | "gif" | "prores" | "mp3" | "aac" | "wav";
 export type RemotionRenderStage = "starting" | "selecting-composition" | "rendering" | "downloading" | "combining" | "uploading" | "done" | "error" | "expired";
@@ -13,7 +13,7 @@ export interface RemotionS3Output {
     contentType?: string;
 }
 export interface RemotionS3ChunkOutput extends Omit<RemotionS3Output, "downloadUrl"> {
-    /** Presigned GET URL used by the coordinator sandbox after this chunk is uploaded. */
+    /** Presigned GET URL used to retrieve this chunk after it is uploaded. */
     downloadUrl: string;
     /** Optional headers required by the signed GET. */
     downloadHeaders?: Record<string, string>;
@@ -37,7 +37,7 @@ export interface RemotionDistributedOptions {
     framesPerSandbox?: number;
     /** Called once per planned chunk so the customer can presign temporary objects in their own S3. */
     createChunkOutput(plan: RemotionDistributedChunkPlan): RemotionDistributedChunkOutput | Promise<RemotionDistributedChunkOutput>;
-    /** How long the coordinator waits for each temporary chunk to become readable. */
+    /** How long to wait for each temporary chunk to become readable. */
     downloadTimeoutSeconds?: number;
 }
 export interface RemotionRenderOptions {
@@ -46,10 +46,12 @@ export interface RemotionRenderOptions {
     inputProps?: Record<string, unknown>;
     codec?: RemotionCodec;
     output: RemotionS3Output;
-    /** Exact Remotion version used to select Remotion's public renderer image. */
+    /** Exact Remotion version installed into Remotion's matching public runtime image. */
     remotionVersion?: string;
     /** Custom image containing @remotion/renderer, Chrome, and FFmpeg. */
     image?: string;
+    /** Organization-owned runtime snapshot returned by createRuntimeSnapshot(). */
+    snapshotId?: string;
     cpu?: number;
     memory?: number;
     disk?: number;
@@ -67,12 +69,24 @@ export interface RemotionRenderOptions {
     muted?: boolean;
     audioCodec?: string;
     metadata?: Record<string, string>;
-    /** Split one video across multiple run.cloud sandboxes and combine it in the first sandbox. */
+    /** Split one video across multiple run.cloud sandboxes and combine the frame ranges. */
     distributed?: RemotionDistributedOptions;
 }
+export interface CreateRemotionRuntimeSnapshotOptions {
+    /** Exact Remotion version installed into the organization-owned snapshot. */
+    remotionVersion: string;
+    cpu?: number;
+    memory?: number;
+    disk?: number;
+    startupTimeoutSeconds?: number;
+    timeoutSeconds?: number;
+    region?: string;
+    name?: string;
+    label?: string;
+}
 export interface RemotionRenderHandle {
     renderId: string;
-    /** Coordinator sandbox. Kept for compatibility with single-sandbox callers. */
+    /** Primary sandbox. Kept for compatibility with single-sandbox callers. */
     sandboxId: string;
     /** Every sandbox allocated to this render. */
     sandboxIds: string[];
@@ -106,16 +120,40 @@ export interface RemotionSandboxApi {
     writeFile(id: string, path: string, content: Uint8Array, options?: {
         mode?: number;
     }): Promise<void>;
+    snapshot?(id: string, options?: {
+        label?: string;
+        timeoutSeconds?: number;
+        pollIntervalMs?: number;
+    }): Promise<Snapshot>;
     destroy(id: string): Promise<void>;
 }
+export interface RemotionSnapshotApi {
+    restore(id: string, options?: {
+        name?: string;
+        region?: string;
+        cpu?: number;
+        memory?: number;
+        disk?: number;
+        idlePauseSeconds?: number;
+        timeoutSeconds?: number;
+        idempotencyKey?: string;
+    }): Promise<Sandbox>;
+}
 export declare class RemotionClient {
     private readonly sandboxes;
-    constructor(sandboxes: RemotionSandboxApi);
+    private readonly snapshots?;
+    constructor(sandboxes: RemotionSandboxApi, snapshots?: RemotionSnapshotApi | undefined);
+    /**
+     * Install a version-pinned renderer once and preserve it as an
+     * organization-owned snapshot for subsequent render workers.
+     */
+    createRuntimeSnapshot(options: CreateRemotionRuntimeSnapshotOptions): Promise<Snapshot>;
     /**
      * Start a detached render. The caller owns every returned sandbox until it
      * calls cancel(), or until the finite sandbox timeouts expire.
      */
     start(options: RemotionRenderOptions): Promise<RemotionRenderHandle>;
+    private startWithSignal;
     private createSandbox;
     private startDistributed;
     getProgress(render: string | RemotionRenderHandle): Promise<RemotionRenderProgress>;
@@ -130,8 +168,9 @@ export declare class RemotionRenderFailedError extends Error {
     constructor(progress: RemotionRenderProgress);
 }
 /**
- * Self-contained guest runner written into the sandbox by the SDK. The image
- * supplies @remotion/renderer and its native browser/FFmpeg dependencies.
+ * Self-contained guest runner written into the sandbox by the SDK. The SDK
+ * installs @remotion/renderer into the public image, while custom images may
+ * supply it from one of the conventional application roots below.
  */
 export declare const REMOTION_PLANNER_SOURCE: string;
 export declare const REMOTION_RUNNER_SOURCE: string;

package/dist/remotion.js

@@ -1,3 +1,4 @@
+import { Buffer } from "node:buffer";
 import { createHash } from "node:crypto";
 export const REMOTION_IMAGE_REGISTRY = "us-docker.pkg.dev/remotion-dev/production/render";
 const REMOTION_DIR = "/tmp/runcloud-remotion";
@@ -8,34 +9,118 @@ const MANIFEST_PATH = `${REMOTION_DIR}/manifest.json`;
 const PROGRESS_PATH = `${REMOTION_DIR}/progress.json`;
 const STARTED_PATH = `${REMOTION_DIR}/started`;
 const LOG_PATH = `${REMOTION_DIR}/render.log`;
+const REMOTION_RUNTIME_ROOT = "/opt/remotion";
+const REMOTION_IMAGE_BROWSER_CACHE = "/usr/app/node_modules/.remotion";
 export class RemotionClient {
     sandboxes;
-    constructor(sandboxes) {
+    snapshots;
+    constructor(sandboxes, snapshots) {
         this.sandboxes = sandboxes;
+        this.snapshots = snapshots;
+    }
+    /**
+     * Install a version-pinned renderer once and preserve it as an
+     * organization-owned snapshot for subsequent render workers.
+     */
+    async createRuntimeSnapshot(options) {
+        if (!this.sandboxes.snapshot) {
+            throw new Error("createRuntimeSnapshot requires a sandbox API with snapshot support");
+        }
+        const image = remotionImageForVersion(options.remotionVersion);
+        const sandbox = await this.sandboxes.create({
+            image,
+            cpu: options.cpu ?? 2,
+            memory: options.memory ?? 4_096,
+            disk: options.disk ?? 20,
+            idlePauseSeconds: 0,
+            timeoutSeconds: options.timeoutSeconds ?? 15 * 60,
+            region: options.region,
+            name: options.name,
+        });
+        let result;
+        let operationError;
+        try {
+            await prepareSandbox(this.sandboxes, sandbox, options.startupTimeoutSeconds ?? 15 * 60, options.remotionVersion);
+            const flush = await this.sandboxes.exec(sandbox.id, ["sync"]);
+            if (flush.exitCode !== 0) {
+                throw new Error(`failed to flush the Remotion runtime before snapshotting: ${flush.stderr || `exit ${flush.exitCode}`}`);
+            }
+            result = await this.sandboxes.snapshot(sandbox.id, {
+                label: options.label ?? `runcloud-remotion-${options.remotionVersion}`,
+                timeoutSeconds: options.startupTimeoutSeconds ?? 15 * 60,
+            });
+        }
+        catch (error) {
+            operationError = error;
+        }
+        try {
+            await this.sandboxes.destroy(sandbox.id);
+        }
+        catch (cleanupError) {
+            if (operationError) {
+                throw new AggregateError([operationError, cleanupError], "Remotion runtime snapshot failed and its bootstrap sandbox could not be destroyed");
+            }
+            throw cleanupError;
+        }
+        if (operationError)
+            throw operationError;
+        return result;
     }
     /**
      * Start a detached render. The caller owns every returned sandbox until it
      * calls cancel(), or until the finite sandbox timeouts expire.
      */
     async start(options) {
+        return this.startWithSignal(options);
+    }
+    async startWithSignal(options, signal) {
         const job = renderJob(options);
         const image = resolveRemotionImage(options);
+        const runtimeVersion = options.image || options.snapshotId
+            ? undefined
+            : options.remotionVersion;
+        throwIfAborted(signal);
         if (options.distributed) {
-            return this.startDistributed(options, job, image);
+            return this.startDistributed(options, job, image, signal);
         }
-        const sandbox = await this.createSandbox(options, image);
-        const handle = handleForSandboxes([sandbox.id]);
+        const created = [];
         try {
-            await prepareSandbox(this.sandboxes, sandbox, options.startupTimeoutSeconds ?? 15 * 60);
-            await startGuestJob(this.sandboxes, sandbox.id, job, REMOTION_RUNNER_SOURCE);
+            const sandbox = await this.createSandbox(options, image);
+            created.push(sandbox);
+            throwIfAborted(signal);
+            const handle = handleForSandboxes([sandbox.id]);
+            await prepareSandbox(this.sandboxes, sandbox, options.startupTimeoutSeconds ?? 15 * 60, runtimeVersion, signal);
+            await startGuestJob(this.sandboxes, sandbox.id, job, REMOTION_RUNNER_SOURCE, signal);
             return handle;
         }
         catch (error) {
-            return destroyAfterFailure(this.sandboxes, [sandbox.id], error, "Remotion render setup");
+            return destroyAfterFailure(this.sandboxes, created.map((sandbox) => sandbox.id), error, "Remotion render setup");
         }
     }
     createSandbox(options, image, index) {
         const suffix = index === undefined ? undefined : `chunk-${index}`;
+        const name = options.name && suffix ? `${options.name}-${suffix}` : options.name;
+        if (options.snapshotId) {
+            if (!this.snapshots) {
+                throw new Error("snapshotId requires a RemotionClient configured with snapshots");
+            }
+            return this.snapshots.restore(options.snapshotId, {
+                cpu: options.cpu ?? 8,
+                memory: options.memory ?? 16_384,
+                disk: options.disk ?? 40,
+                idlePauseSeconds: 0,
+                timeoutSeconds: options.timeoutSeconds ?? 3_600,
+                ...(options.idempotencyKey
+                    ? {
+                        idempotencyKey: suffix
+                            ? `${options.idempotencyKey}:${suffix}`
+                            : options.idempotencyKey,
+                    }
+                    : {}),
+                region: options.region,
+                name,
+            });
+        }
         return this.sandboxes.create({
             image,
             cpu: options.cpu ?? 8,
@@ -44,38 +129,45 @@ export class RemotionClient {
             idlePauseSeconds: 0,
             timeoutSeconds: options.timeoutSeconds ?? 3_600,
             region: options.region,
-            name: options.name && suffix ? `${options.name}-${suffix}` : options.name,
+            name,
             idempotencyKey: options.idempotencyKey && suffix
                 ? `${options.idempotencyKey}:${suffix}`
                 : options.idempotencyKey,
         });
     }
-    async startDistributed(options, baseJob, image) {
+    async startDistributed(options, baseJob, image, signal) {
         const distributed = validateDistributedOptions(options.distributed);
         const created = [];
         try {
+            throwIfAborted(signal);
             const coordinator = await this.createSandbox(options, image, 0);
             created.push(coordinator);
-            await prepareSandbox(this.sandboxes, coordinator, options.startupTimeoutSeconds ?? 15 * 60);
-            const plan = await planComposition(this.sandboxes, coordinator.id, baseJob);
+            throwIfAborted(signal);
+            await prepareSandbox(this.sandboxes, coordinator, options.startupTimeoutSeconds ?? 15 * 60, options.image || options.snapshotId ? undefined : options.remotionVersion, signal);
+            const plan = await planComposition(this.sandboxes, coordinator.id, baseJob, signal);
             const chunkRanges = distributeFrames(plan.durationInFrames, distributed);
-            const storageRenderId = handleForSandboxes([coordinator.id]).renderId;
+            for (let index = 1; index < chunkRanges.length; index += 1) {
+                throwIfAborted(signal);
+                created.push(await this.createSandbox(options, image, index));
+                throwIfAborted(signal);
+            }
+            await Promise.all(created.slice(1).map((sandbox) => prepareSandbox(this.sandboxes, sandbox, options.startupTimeoutSeconds ?? 15 * 60, options.image || options.snapshotId ? undefined : options.remotionVersion, signal)));
+            const handle = handleForSandboxes(created.map((sandbox) => sandbox.id));
             const chunkOutputs = await Promise.all(chunkRanges.map(async (frameRange, index) => {
+                throwIfAborted(signal);
                 const output = await distributed.createChunkOutput({
-                    renderId: storageRenderId,
+                    renderId: handle.renderId,
                     index,
                     frameRange,
                     sandboxCount: chunkRanges.length,
                 });
+                throwIfAborted(signal);
                 validateChunkOutput(output, baseJob.codec, baseJob.renderOptions.muted === true, index);
                 return output;
             }));
-            for (let index = 1; index < chunkRanges.length; index += 1) {
-                created.push(await this.createSandbox(options, image, index));
-            }
-            await Promise.all(created.slice(1).map((sandbox) => prepareSandbox(this.sandboxes, sandbox, options.startupTimeoutSeconds ?? 15 * 60)));
-            const handle = handleForSandboxes(created.map((sandbox) => sandbox.id));
+            throwIfAborted(signal);
             await this.sandboxes.writeFile(coordinator.id, MANIFEST_PATH, new TextEncoder().encode(JSON.stringify({ sandboxIds: handle.sandboxIds })), { mode: 0o600 });
+            throwIfAborted(signal);
             const framesPerChunk = chunkRanges[0][1] - chunkRanges[0][0] + 1;
             const chunkJobs = chunkRanges.map((frameRange, index) => {
                 const media = chunkMediaPlan(baseJob.codec, baseJob.renderOptions.audioCodec, baseJob.renderOptions.muted === true, framesPerChunk);
@@ -112,9 +204,9 @@ export class RemotionClient {
                     } : {}),
                 };
             });
-            await Promise.all(created.map((sandbox, index) => writeGuestJob(this.sandboxes, sandbox.id, chunkJobs[index], REMOTION_DISTRIBUTED_RUNNER_SOURCE)));
-            await Promise.all(created.slice(1).map((sandbox, offset) => launchGuestJob(this.sandboxes, sandbox.id, chunkJobs[offset + 1])));
-            await launchGuestJob(this.sandboxes, coordinator.id, chunkJobs[0]);
+            await Promise.all(created.map((sandbox, index) => writeGuestJob(this.sandboxes, sandbox.id, chunkJobs[index], REMOTION_DISTRIBUTED_RUNNER_SOURCE, signal)));
+            await Promise.all(created.slice(1).map((sandbox, offset) => launchGuestJob(this.sandboxes, sandbox.id, chunkJobs[offset + 1], signal)));
+            await launchGuestJob(this.sandboxes, coordinator.id, chunkJobs[0], signal);
             return handle;
         }
         catch (error) {
@@ -173,7 +265,7 @@ export class RemotionClient {
     }
     /** Wait for a render and always stop billing when it reaches a terminal state. */
     async render(options, waitOptions = {}) {
-        const handle = await this.start(options);
+        const handle = await this.startWithSignal(options, waitOptions.signal);
         let renderError;
         try {
             for (;;) {
@@ -221,29 +313,74 @@ export function remotionImageForVersion(version) {
     return `${REMOTION_IMAGE_REGISTRY}:${version}`;
 }
 function resolveRemotionImage(options) {
+    if (options.snapshotId !== undefined) {
+        if (!options.snapshotId.trim()) {
+            throw new TypeError("snapshotId must not be empty");
+        }
+        if (options.image) {
+            throw new TypeError("set either snapshotId or image, not both");
+        }
+        if (options.remotionVersion) {
+            throw new TypeError("snapshotId already pins the runtime; omit remotionVersion");
+        }
+        return undefined;
+    }
     if (options.image)
         return options.image;
     if (!options.remotionVersion) {
-        throw new TypeError("remotionVersion is required unless a custom image is supplied");
+        throw new TypeError("remotionVersion is required unless a custom image or runtime snapshot is supplied");
     }
     return remotionImageForVersion(options.remotionVersion);
 }
-async function prepareSandbox(sandboxes, sandbox, startupTimeoutSeconds) {
-    await waitForSandboxReady(sandboxes, sandbox, startupTimeoutSeconds);
-    const prepare = await sandboxes.exec(sandbox.id, ["/bin/mkdir", "-p", REMOTION_DIR]);
+async function prepareSandbox(sandboxes, sandbox, startupTimeoutSeconds, remotionVersion, signal) {
+    await waitForSandboxReady(sandboxes, sandbox, startupTimeoutSeconds, signal);
+    throwIfAborted(signal);
+    const prepare = await sandboxes.exec(sandbox.id, ["/bin/mkdir", "-p", REMOTION_DIR], { signal });
+    throwIfAborted(signal);
     if (prepare.exitCode !== 0) {
         throw new Error(`failed to prepare Remotion render: ${prepare.stderr || `exit ${prepare.exitCode}`}`);
     }
+    if (!remotionVersion)
+        return;
+    const install = await sandboxes.exec(sandbox.id, [
+        "npm",
+        "install",
+        "--prefix",
+        REMOTION_RUNTIME_ROOT,
+        "--no-audit",
+        "--no-fund",
+        "--no-package-lock",
+        "--omit=dev",
+        `@remotion/renderer@${remotionVersion}`,
+    ], { signal, timeoutSeconds: startupTimeoutSeconds });
+    throwIfAborted(signal);
+    if (install.exitCode !== 0) {
+        throw new Error(`failed to install Remotion renderer ${remotionVersion}: ${install.stderr || `exit ${install.exitCode}`}`);
+    }
+    const browserCache = await sandboxes.exec(sandbox.id, [
+        "/bin/ln",
+        "-sfn",
+        REMOTION_IMAGE_BROWSER_CACHE,
+        `${REMOTION_RUNTIME_ROOT}/node_modules/.remotion`,
+    ], { signal });
+    throwIfAborted(signal);
+    if (browserCache.exitCode !== 0) {
+        throw new Error(`failed to expose the Remotion browser cache: ${browserCache.stderr || `exit ${browserCache.exitCode}`}`);
+    }
 }
-async function writeGuestJob(sandboxes, sandboxId, job, runnerSource) {
+async function writeGuestJob(sandboxes, sandboxId, job, runnerSource, signal) {
+    throwIfAborted(signal);
     const encodedJob = new TextEncoder().encode(JSON.stringify(job));
     const jobHash = createHash("sha256").update(encodedJob).digest("hex");
     const jobPath = `${REMOTION_DIR}/job-${jobHash}.json`;
     await sandboxes.writeFile(sandboxId, RUNNER_PATH, new TextEncoder().encode(runnerSource), { mode: 0o700 });
+    throwIfAborted(signal);
     await sandboxes.writeFile(sandboxId, jobPath, encodedJob, { mode: 0o600 });
+    throwIfAborted(signal);
     return jobPath;
 }
-async function launchGuestJob(sandboxes, sandboxId, job) {
+async function launchGuestJob(sandboxes, sandboxId, job, signal) {
+    throwIfAborted(signal);
     const encodedJob = new TextEncoder().encode(JSON.stringify(job));
     const jobHash = createHash("sha256").update(encodedJob).digest("hex");
     const jobPath = `${REMOTION_DIR}/job-${jobHash}.json`;
@@ -251,17 +388,20 @@ async function launchGuestJob(sandboxes, sandboxId, job) {
         "/bin/sh",
         "-c",
         `mkdir -p ${REMOTION_DIR} && if (set -C; : > ${STARTED_PATH}) 2>/dev/null; then nohup node ${RUNNER_PATH} ${jobPath} >${LOG_PATH} 2>&1 </dev/null & fi`,
-    ]);
+    ], { signal });
+    throwIfAborted(signal);
     if (start.exitCode !== 0) {
         throw new Error(`failed to start Remotion render: ${start.stderr || `exit ${start.exitCode}`}`);
     }
 }
-async function startGuestJob(sandboxes, sandboxId, job, runnerSource) {
-    await writeGuestJob(sandboxes, sandboxId, job, runnerSource);
-    await launchGuestJob(sandboxes, sandboxId, job);
+async function startGuestJob(sandboxes, sandboxId, job, runnerSource, signal) {
+    await writeGuestJob(sandboxes, sandboxId, job, runnerSource, signal);
+    await launchGuestJob(sandboxes, sandboxId, job, signal);
 }
-async function planComposition(sandboxes, sandboxId, job) {
+async function planComposition(sandboxes, sandboxId, job, signal) {
+    throwIfAborted(signal);
     await sandboxes.writeFile(sandboxId, PLANNER_PATH, new TextEncoder().encode(REMOTION_PLANNER_SOURCE), { mode: 0o700 });
+    throwIfAborted(signal);
     const planJob = new TextEncoder().encode(JSON.stringify({
         serveUrl: job.serveUrl,
         composition: job.composition,
@@ -270,11 +410,14 @@ async function planComposition(sandboxes, sandboxId, job) {
         planPath: PLAN_PATH,
     }));
     await sandboxes.writeFile(sandboxId, `${REMOTION_DIR}/plan-job.json`, planJob, { mode: 0o600 });
-    const result = await sandboxes.exec(sandboxId, ["node", PLANNER_PATH, `${REMOTION_DIR}/plan-job.json`]);
+    throwIfAborted(signal);
+    const result = await sandboxes.exec(sandboxId, ["node", PLANNER_PATH, `${REMOTION_DIR}/plan-job.json`], { signal });
     if (result.exitCode !== 0) {
         throw new Error(`failed to plan Remotion render: ${result.stderr || `exit ${result.exitCode}`}`);
     }
+    throwIfAborted(signal);
     const raw = JSON.parse(new TextDecoder().decode(await sandboxes.readFile(sandboxId, PLAN_PATH)));
+    throwIfAborted(signal);
     if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
         throw new Error("Remotion composition plan is invalid");
     }
@@ -338,7 +481,7 @@ export function distributeFrames(durationInFrames, options) {
 }
 function validateChunkOutput(output, codec, muted, index) {
     const hasVideo = !isAudioCodec(codec);
-    const hasAudio = !muted && codec !== "gif";
+    const hasAudio = hasAudioOutput(codec, muted);
     if (hasVideo)
         validateChunkLocation(output?.video, `distributed chunk ${index} video`);
     if (hasAudio)
@@ -353,9 +496,12 @@ function validateChunkLocation(output, name) {
 function isAudioCodec(codec) {
     return codec === "mp3" || codec === "aac" || codec === "wav";
 }
+function hasAudioOutput(codec, muted) {
+    return isAudioCodec(codec) || (!muted && codec !== "gif");
+}
 function chunkMediaPlan(codec, requestedAudioCodec, muted, framesPerChunk) {
     const hasVideo = !isAudioCodec(codec);
-    const hasAudio = !muted && codec !== "gif";
+    const hasAudio = hasAudioOutput(codec, muted);
     if (!hasVideo) {
         return {
             hasVideo: false,
@@ -404,7 +550,7 @@ async function destroyAfterFailure(sandboxes, sandboxIds, error, context) {
     }
     throw error;
 }
-async function waitForSandboxReady(sandboxes, initial, timeoutSeconds) {
+async function waitForSandboxReady(sandboxes, initial, timeoutSeconds, signal) {
     if (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0) {
         throw new RangeError("startupTimeoutSeconds must be a positive number");
     }
@@ -412,6 +558,7 @@ async function waitForSandboxReady(sandboxes, initial, timeoutSeconds) {
     let sandbox = initial;
     let hasPolled = false;
     for (;;) {
+        throwIfAborted(signal);
         if (sandbox.state === "running")
             return;
         if (["interrupted", "destroying", "destroyed", "stopped"].includes(sandbox.state)) {
@@ -424,8 +571,9 @@ async function waitForSandboxReady(sandboxes, initial, timeoutSeconds) {
             throw new Error(`Remotion sandbox did not become ready within ${timeoutSeconds} seconds`);
         }
         if (hasPolled)
-            await abortableDelay(1_000);
+            await abortableDelay(1_000, signal);
         sandbox = await sandboxes.get(sandbox.id);
+        throwIfAborted(signal);
         hasPolled = true;
     }
 }
@@ -448,6 +596,9 @@ function renderJob(options) {
     assertJson(options.envVariables ?? {}, "envVariables");
     validateHeaders(options.output.headers ?? {});
     const codec = options.codec ?? "h264";
+    if (isAudioCodec(codec) && options.muted === true) {
+        throw new TypeError("muted cannot be true for audio-only codecs");
+    }
     const contentType = options.output.contentType ?? contentTypeForCodec(codec);
     return {
         serveUrl: options.serveUrl,
@@ -535,13 +686,34 @@ function handleForSandboxes(sandboxIds) {
     if (!sandboxId)
         throw new TypeError("at least one Remotion sandbox is required");
     return {
-        renderId: `render_${sandboxId}`,
+        renderId: sandboxIds.length === 1
+            ? `render_${sandboxId}`
+            : `render_group_${Buffer.from(JSON.stringify(sandboxIds)).toString("base64url")}`,
         sandboxId,
         sandboxIds,
         sandboxCount: sandboxIds.length,
     };
 }
 function handleForRenderId(renderId) {
+    if (renderId.startsWith("render_group_")) {
+        try {
+            const encoded = renderId.slice("render_group_".length);
+            const sandboxIds = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+            if (!Array.isArray(sandboxIds) ||
+                sandboxIds.length < 2 ||
+                sandboxIds.length > 200 ||
+                sandboxIds.some((id) => typeof id !== "string" || id.length === 0) ||
+                new Set(sandboxIds).size !== sandboxIds.length) {
+                throw new TypeError("invalid run.cloud distributed Remotion renderId");
+            }
+            return handleForSandboxes(sandboxIds);
+        }
+        catch (error) {
+            if (error instanceof TypeError && error.message.startsWith("invalid run.cloud"))
+                throw error;
+            throw new TypeError("invalid run.cloud distributed Remotion renderId");
+        }
+    }
     if (!renderId.startsWith("render_") || renderId.length === "render_".length) {
         throw new TypeError("invalid run.cloud Remotion renderId");
     }
@@ -557,6 +729,8 @@ async function resolveRenderHandle(sandboxes, render) {
             sandboxIds: render.sandboxIds ?? [render.sandboxId],
             sandboxCount: render.sandboxCount ?? render.sandboxIds?.length ?? 1,
         };
+    if (handle.sandboxIds.length > 1)
+        return handle;
     try {
         const raw = JSON.parse(new TextDecoder().decode(await sandboxes.readFile(handle.sandboxId, MANIFEST_PATH)));
         if (!raw || typeof raw !== "object" || Array.isArray(raw))
@@ -645,8 +819,7 @@ function progressPayload(handle, raw) {
     };
 }
 async function abortableDelay(milliseconds, signal) {
-    if (signal?.aborted)
-        throw signal.reason ?? new Error("render aborted");
+    throwIfAborted(signal);
     await new Promise((resolve, reject) => {
         const onAbort = () => {
             clearTimeout(timeout);
@@ -659,9 +832,14 @@ async function abortableDelay(milliseconds, signal) {
         signal?.addEventListener("abort", onAbort, { once: true });
     });
 }
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw signal.reason ?? new Error("render aborted");
+}
 /**
- * Self-contained guest runner written into the sandbox by the SDK. The image
- * supplies @remotion/renderer and its native browser/FFmpeg dependencies.
+ * Self-contained guest runner written into the sandbox by the SDK. The SDK
+ * installs @remotion/renderer into the public image, while custom images may
+ * supply it from one of the conventional application roots below.
  */
 export const REMOTION_PLANNER_SOURCE = String.raw `
 import {readFile, writeFile} from 'node:fs/promises';
@@ -671,10 +849,14 @@ const loadRenderer = async () => {
   try {
     return await import('@remotion/renderer');
   } catch (initialError) {
-    for (const root of ['/usr/app', '/app', '/workspace']) {
+    for (const root of ['/opt/remotion', '/usr/app', '/app', '/workspace']) {
       try {
         return createRequire(root + '/package.json')('@remotion/renderer');
-      } catch {}
+      } catch (error) {
+        if (error?.code !== 'MODULE_NOT_FOUND' || !String(error.message).includes('@remotion/renderer')) {
+          throw error;
+        }
+      }
     }
     throw initialError;
   }
@@ -708,17 +890,19 @@ const loadRenderer = async () => {
   try {
     return await import('@remotion/renderer');
   } catch (initialError) {
-    for (const root of ['/usr/app', '/app', '/workspace']) {
+    for (const root of ['/opt/remotion', '/usr/app', '/app', '/workspace']) {
       try {
         return createRequire(root + '/package.json')('@remotion/renderer');
-      } catch {}
+      } catch (error) {
+        if (error?.code !== 'MODULE_NOT_FOUND' || !String(error.message).includes('@remotion/renderer')) {
+          throw error;
+        }
+      }
     }
     throw initialError;
   }
 };
 
-const {selectComposition, renderMedia} = await loadRenderer();
-
 const jobPath = process.argv[2];
 if (!jobPath) throw new Error('render job path is required');
 const job = JSON.parse(await readFile(jobPath, 'utf8'));
@@ -746,6 +930,7 @@ const persist = async (patch) => {
 
 try {
   await persist({stage: 'selecting-composition'});
+  const {selectComposition, renderMedia} = await loadRenderer();
   const composition = await selectComposition({
     serveUrl: job.serveUrl,
     id: job.composition,
@@ -811,16 +996,19 @@ const loadRenderer = async () => {
   try {
     return await import('@remotion/renderer');
   } catch (initialError) {
-    for (const root of ['/usr/app', '/app', '/workspace']) {
+    for (const root of ['/opt/remotion', '/usr/app', '/app', '/workspace']) {
       try {
         return createRequire(root + '/package.json')('@remotion/renderer');
-      } catch {}
+      } catch (error) {
+        if (error?.code !== 'MODULE_NOT_FOUND' || !String(error.message).includes('@remotion/renderer')) {
+          throw error;
+        }
+      }
     }
     throw initialError;
   }
 };
 
-const {selectComposition, renderMedia, combineChunks} = await loadRenderer();
 const jobPath = process.argv[2];
 if (!jobPath) throw new Error('distributed render job path is required');
 const job = JSON.parse(await readFile(jobPath, 'utf8'));
@@ -885,6 +1073,7 @@ const download = async (source, destination, deadline) => {
 
 try {
   await persist({stage: 'selecting-composition'});
+  const {selectComposition, renderMedia, combineChunks} = await loadRenderer();
   const composition = await selectComposition({
     serveUrl: job.serveUrl,
     id: job.composition,