@run-cloud/sdk 0.20.0 → 0.22.0

package/README.md

@@ -263,6 +263,7 @@ Provider-shaped migration adapters ship in this same package:
 | Cloudflare Sandbox | `@run-cloud/sdk/compat/cloudflare` |
 | CodeSandbox | `@run-cloud/sdk/compat/codesandbox` |
 | Fly Machines | `@run-cloud/sdk/compat/fly` |
+| Remotion Lambda | `@run-cloud/sdk/compat/remotion-lambda` |
 
 ```ts
 // import { Sandbox } from "@vercel/sandbox";
@@ -280,6 +281,117 @@ Provider-specific features that do not have a public run.cloud equivalent throw
 `UnsupportedCompatibilityFeatureError` with a migration hint. In particular,
 public port capabilities and filesystem mutation are not silently emulated.
 
+## Remotion renders with customer-owned S3
+
+run.cloud can replace the Lambda compute used for a Remotion render without
+owning the output bucket. Supply a presigned S3-compatible PUT URL; the sandbox
+renders the video, uploads it directly to that URL, and is destroyed when
+`render()` returns.
+
+```ts
+import { Client } from "@run-cloud/sdk";
+
+const cloud = new Client();
+const result = await cloud.remotion.render({
+  serveUrl: "https://example.com/remotion-bundle",
+  composition: "ProductDemo",
+  remotionVersion: "4.0.507",
+  inputProps: { customer: "Acme" },
+  codec: "h264",
+  output: {
+    uploadUrl: presignedPutUrl,
+    downloadUrl: finalObjectUrl,
+    contentType: "video/mp4",
+  },
+});
+
+console.log(result.outputFile);
+```
+
+`remotionVersion` selects Remotion's matching public, versioned renderer image;
+all Remotion packages in a project should use that exact version. You can pass
+`image` instead to use a custom compatible runtime. Signed URLs are written to
+a private guest file and are not included in command logs.
+
+For a smaller migration from `@remotion/lambda/client`, switch the import and
+add `s3Output`; existing `region` and `functionName` fields may remain while
+compute moves to run.cloud:
+
+```ts
+import {
+  getRenderProgress,
+  renderMediaOnLambda,
+} from "@run-cloud/sdk/compat/remotion-lambda";
+
+const render = await renderMediaOnLambda({
+  region: "us-east-1",
+  functionName: "remotion-render-4-0-507-mem2048mb-disk2048mb-240sec",
+  serveUrl: "https://example.com/remotion-bundle",
+  composition: "ProductDemo",
+  codec: "h264",
+  s3Output: {
+    bucketName: "customer-video-output",
+    uploadUrl: presignedPutUrl,
+    downloadUrl: finalObjectUrl,
+  },
+});
+
+const progress = await getRenderProgress({ renderId: render.renderId });
+```
+
+The adapter derives the exact Remotion image version from the standard Lambda
+function name. By default, `concurrencyPerLambda` controls Remotion workers
+inside one sandbox.
+
+To split one video across multiple sandboxes, add a customer-owned temporary
+chunk location. `concurrency` chooses the target maximum sandbox count, while
+`framesPerLambda` can derive it after the SDK selects the composition. Each
+allocated sandbox renders one frame range. For a sufficiently long video,
+`concurrency: 8` creates up to eight sandboxes:
+
+```ts
+const render = await renderMediaOnLambda({
+  functionName: "remotion-render-4-0-507-mem2048mb-disk2048mb-240sec",
+  serveUrl: "https://example.com/remotion-bundle",
+  composition: "ProductDemo",
+  codec: "h264",
+  concurrency: 8,
+  concurrencyPerLambda: 1,
+  s3Output: {
+    bucketName: "customer-video-output",
+    uploadUrl: finalPresignedPutUrl,
+    downloadUrl: finalObjectUrl,
+  },
+  runCloud: {
+    distributed: {
+      createChunkOutput: async ({ renderId, index }) => {
+        const prefix = `remotion-chunks/${renderId}/${index}`;
+        return {
+          video: await presignTemporaryObject(`${prefix}.ts`),
+          audio: await presignTemporaryObject(`${prefix}.aac`),
+        };
+      },
+    },
+  },
+});
+
+console.log(render.sandboxCount); // exact number actually allocated
+```
+
+`presignTemporaryObject()` returns `{uploadUrl, downloadUrl, headers?,
+contentType?}`. Both URLs point to the same temporary object. Signed URLs stay
+out of shell commands, and the temporary objects are used to produce the final
+artifact in customer S3. Configure an S3 lifecycle rule for the temporary
+prefix.
+
+Chunks must be equal-sized except for the last one, so very short or awkwardly
+divisible compositions can use fewer sandboxes than the target. run.cloud still
+does not create or host an S3 bucket, deploy the Remotion site,
+store render metadata, or add a queue/webhook layer. `render.sandboxCount` and
+`progress.runCloud.sandboxCount` report the exact fan-out. `deleteRender()` or
+`cloud.remotion.cancel()` destroys every sandbox associated with the render;
+finite sandbox timeouts remain the cleanup backstop.
+
 `cloud.assets.upload(blob, options)` verifies the uploaded size and MD5 before
 returning a ready asset. Re-uploading the same bytes reuses the verified object.
 For multipart archives, `cloud.assets.uploadBatch(parts, { uploadBatchId,

package/dist/compat/remotion-lambda.d.ts

@@ -0,0 +1,82 @@
+import type { RemotionCodec, RemotionDistributedOptions, RemotionRenderOptions, RemotionRenderProgress, RemotionS3Output } from "../remotion.js";
+import { type CompatibilityClientOptions } from "./common.js";
+export interface LambdaCompatibleS3Output extends Omit<RemotionS3Output, "downloadUrl"> {
+    /** Returned as bucketName for code that persists the Lambda render handle. */
+    bucketName: string;
+    downloadUrl: string;
+}
+export interface RenderMediaOnLambdaInput extends CompatibilityClientOptions {
+    /** Accepted for source compatibility. Compute runs in run.cloud, not this AWS region. */
+    region?: string;
+    /** Accepted for source compatibility. No Lambda function is invoked. */
+    functionName?: string;
+    serveUrl: string;
+    composition: string;
+    inputProps?: Record<string, unknown>;
+    codec: RemotionCodec;
+    /** Target maximum run.cloud sandbox count when runCloud.distributed is configured. */
+    concurrency?: number;
+    /** Frames rendered by each sandbox when runCloud.distributed is configured. */
+    framesPerLambda?: number;
+    /** Maps to @remotion/renderer concurrency inside the run.cloud sandbox. */
+    concurrencyPerLambda?: number | `${number}%`;
+    /** The signed S3 output determines object privacy instead. */
+    privacy?: "public" | "private" | "no-acl";
+    /** Accepted for source compatibility; this thin adapter does not orchestrate retries. */
+    maxRetries?: number;
+    envVariables?: Record<string, string>;
+    crf?: number;
+    imageFormat?: "png" | "jpeg" | "none";
+    pixelFormat?: string;
+    scale?: number;
+    muted?: boolean;
+    audioCodec?: string;
+    metadata?: Record<string, string>;
+    /**
+     * The only required migration addition: customer-owned S3-compatible signed
+     * upload and download locations. run.cloud never owns the bucket.
+     */
+    s3Output: LambdaCompatibleS3Output;
+    runCloud?: Pick<RemotionRenderOptions, "image" | "remotionVersion" | "cpu" | "memory" | "disk" | "timeoutSeconds" | "startupTimeoutSeconds" | "region" | "name" | "idempotencyKey"> & {
+        /**
+         * Enables multi-sandbox rendering. createChunkOutput presigns temporary
+         * video/audio objects in the customer's own S3 bucket.
+         */
+        distributed?: Omit<RemotionDistributedOptions, "sandboxCount" | "framesPerSandbox"> & {
+            sandboxCount?: number;
+            framesPerSandbox?: number;
+        };
+    };
+}
+export interface RenderMediaOnLambdaOutput {
+    renderId: string;
+    bucketName: string;
+    sandboxCount: number;
+}
+export declare function renderMediaOnLambda(input: RenderMediaOnLambdaInput): Promise<RenderMediaOnLambdaOutput>;
+export interface GetRenderProgressInput extends CompatibilityClientOptions {
+    renderId: string;
+    /** Retained because existing Lambda integrations commonly persist this alongside renderId. */
+    bucketName?: string;
+    region?: string;
+    functionName?: string;
+}
+export interface LambdaCompatibleRenderProgress {
+    done: boolean;
+    overallProgress: number;
+    outputFile: string | null;
+    outputSizeInBytes: number | null;
+    errors: RemotionRenderProgress["errors"];
+    fatalErrorEncountered: boolean;
+    currentTime: number;
+    renderSize: number;
+    runCloud: RemotionRenderProgress;
+}
+export declare function getRenderProgress(input: GetRenderProgressInput): Promise<LambdaCompatibleRenderProgress>;
+export interface DeleteRenderInput extends CompatibilityClientOptions {
+    renderId: string;
+    bucketName?: string;
+    region?: string;
+}
+export declare function deleteRender(input: DeleteRenderInput): Promise<void>;
+export declare function remotionVersionFromFunctionName(functionName: string | undefined): string;

package/dist/compat/remotion-lambda.js

@@ -0,0 +1,68 @@
+import { compatibilityClient, } from "./common.js";
+export async function renderMediaOnLambda(input) {
+    if (!input.s3Output?.downloadUrl) {
+        throw new TypeError("s3Output.downloadUrl is required");
+    }
+    const client = compatibilityClient(input);
+    const runCloud = input.runCloud ?? {};
+    const distributed = runCloud.distributed
+        ? {
+            ...runCloud.distributed,
+            sandboxCount: runCloud.distributed.sandboxCount ?? input.concurrency,
+            framesPerSandbox: runCloud.distributed.framesPerSandbox ??
+                (runCloud.distributed.sandboxCount === undefined && input.concurrency === undefined
+                    ? input.framesPerLambda
+                    : undefined),
+        }
+        : undefined;
+    const handle = await client.remotion.start({
+        serveUrl: input.serveUrl,
+        composition: input.composition,
+        inputProps: input.inputProps,
+        codec: input.codec,
+        output: input.s3Output,
+        concurrency: input.concurrencyPerLambda,
+        envVariables: input.envVariables,
+        crf: input.crf,
+        imageFormat: input.imageFormat,
+        pixelFormat: input.pixelFormat,
+        scale: input.scale,
+        muted: input.muted,
+        audioCodec: input.audioCodec,
+        metadata: input.metadata,
+        ...runCloud,
+        distributed,
+        remotionVersion: runCloud.remotionVersion ??
+            (runCloud.image ? undefined : remotionVersionFromFunctionName(input.functionName)),
+    });
+    return {
+        renderId: handle.renderId,
+        bucketName: input.s3Output.bucketName,
+        sandboxCount: handle.sandboxCount,
+    };
+}
+export async function getRenderProgress(input) {
+    const progress = await compatibilityClient(input).remotion.getProgress(input.renderId);
+    return {
+        done: progress.done,
+        overallProgress: progress.progress,
+        outputFile: progress.outputFile,
+        outputSizeInBytes: progress.outputSizeInBytes,
+        errors: progress.errors,
+        fatalErrorEncountered: progress.fatalErrorEncountered,
+        currentTime: Date.parse(progress.updatedAt),
+        renderSize: progress.outputSizeInBytes ?? 0,
+        runCloud: progress,
+    };
+}
+export async function deleteRender(input) {
+    await compatibilityClient(input).remotion.cancel(input.renderId);
+}
+export function remotionVersionFromFunctionName(functionName) {
+    const match = functionName?.match(/^remotion-render-(\d+)-(\d+)-(\d+)(?:-|$)/);
+    if (!match) {
+        throw new TypeError("functionName must use Remotion's naming convention, or runCloud.remotionVersion/image must be supplied");
+    }
+    return `${match[1]}.${match[2]}.${match[3]}`;
+}
+//# sourceMappingURL=remotion-lambda.js.map

package/dist/compat/remotion-lambda.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remotion-lambda.js","sourceRoot":"","sources":["../../src/compat/remotion-lambda.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 import WebSocket from "ws";
+import { RemotionClient } from "./remotion.js";
+export * from "./remotion.js";
 export type SimulatorPlatform = "ios" | "android";
 export interface SimulatorPoint {
     /** Normalized display-space coordinate, inclusive from 0 (left) to 1 (right). */
@@ -813,6 +815,7 @@ export declare class Client {
     readonly secrets: SecretsClient;
     readonly ci: CiClient;
     readonly images: ImageClient;
+    readonly remotion: RemotionClient;
     private readonly apiKey;
     private readonly apiUrl;
     private readonly fetchImpl;
@@ -1268,4 +1271,3 @@ export declare class AssetsClient {
         deleted: boolean;
     }>;
 }
-export {};

package/dist/index.js

@@ -1,5 +1,7 @@
 import WebSocket from "ws";
 import { createHash, randomUUID } from "node:crypto";
+import { RemotionClient } from "./remotion.js";
+export * from "./remotion.js";
 export const SIMULATOR_KEYS = [
     "a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m",
     "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z",
@@ -699,6 +701,7 @@ export class Client {
     secrets;
     ci;
     images;
+    remotion;
     apiKey;
     apiUrl;
     fetchImpl;
@@ -724,6 +727,7 @@ export class Client {
         this.secrets = new SecretsClient(this);
         this.ci = new CiClient(this);
         this.images = new ImageClient(this);
+        this.remotion = new RemotionClient(this.sandboxes);
     }
     async usage(options = {}) {
         const query = options.orgId ? `?orgId=${encodeURIComponent(options.orgId)}` : "";