@hyperframes/gcp-cloud-run

Google Cloud Run and Workflows adapter for distributed HyperFrames rendering.

The GCP Cloud Run package runs HyperFrames’ distributed render primitives on Google Cloud. It ships a Cloud Run HTTP service, a Node client SDK, and a Terraform module for provisioning the bucket, service, workflow, and service accounts.

npm install @hyperframes/gcp-cloud-run

When to Use

Use @hyperframes/gcp-cloud-run when you need to:

• Render large compositions on Google Cloud infrastructure
• Orchestrate plan, renderChunk, and assemble through Cloud Workflows
• Store project archives, chunk outputs, and final videos in GCS
• Deploy the renderer as a Cloud Run service with a pinned Chrome runtime
• Drive renders from CI, a backend service, or custom internal tooling

Use a different package if you want to:

• Render locally or inside a single Node process - use the CLI or producer
• Run the same distributed model on AWS - use aws-lambda
• Build or edit composition HTML - use studio, sdk, or core

Cloud Run uses a container image, so it avoids Lambda ZIP-size pressure and can install the same pinned chrome-headless-shell runtime used by the standard renderer.

Package Exports

Import	Description
@hyperframes/gcp-cloud-run	Server handler, event types, GCS transport, and client SDK exports
@hyperframes/gcp-cloud-run/server	Cloud Run HTTP service entry point
@hyperframes/gcp-cloud-run/sdk	Lightweight Node SDK for deploying sites, starting renders, polling progress, and estimating cost

The published package also includes terraform/ and a Dockerfile for deployment.

Architecture

Cloud Workflows invokes one Cloud Run service with different Action values:

1. Plan

   Downloads the project archive from GCS, runs the producer planner, and uploads the plan directory.

2. Render chunks

   Cloud Workflows runs parallel renderChunk calls against the Cloud Run service. Each request renders one chunk and uploads it to GCS.

3. Assemble

   Downloads all chunks and audio assets, assembles the deliverable, and uploads the final file.

The service is intentionally close to the AWS Lambda adapter: thin cloud transport around the same @hyperframes/producer/distributed primitives.

Deploying

Build and push the container, then apply the Terraform module:

gcloud builds submit . \
  --tag REGION-docker.pkg.dev/PROJECT/REPO/hyperframes-render:TAG

terraform -chdir=node_modules/@hyperframes/gcp-cloud-run/terraform init
terraform -chdir=node_modules/@hyperframes/gcp-cloud-run/terraform apply \
  -var project_id=PROJECT \
  -var region=us-central1 \
  -var image=REGION-docker.pkg.dev/PROJECT/REPO/hyperframes-render:TAG

Terraform outputs the bucket name, service URL, workflow name, and region needed by the SDK.

Using the SDK

import { getRenderProgress, renderToCloudRun } from "@hyperframes/gcp-cloud-run/sdk";

const handle = await renderToCloudRun({
  projectDir: "./my-composition",
  config: { fps: 30, width: 1920, height: 1080, format: "mp4" },
  bucketName: "hyperframes-render-my-project",
  projectId: "my-project",
  location: "us-central1",
  workflowId: "hyperframes-render",
  serviceUrl: "https://hyperframes-render-abc.us-central1.run.app",
});

let progress = await getRenderProgress({ executionName: handle.executionName });
while (progress.status === "running") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  progress = await getRenderProgress({ executionName: handle.executionName });
}

console.log(progress.status, progress.outputFile, progress.costs.displayCost);

Pass projectDir for one-shot uploads, or call deploySite() separately and reuse the returned site handle across many renders.

Related Guides

GCP Cloud Run Deployment

End-to-end deployment details and smoke-test notes.

@hyperframes/producer

The distributed primitives that the Cloud Run service executes.