Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { failCommand } from "../../utils/commandResult.js";
/**
* `hyperframes cloud render` — orchestrate a cloud-rendered HyperFrames
* composition end-to-end:
*
* 1. Resolve the project (or reuse a pre-uploaded `--asset-id` /
* `--url`).
* 2. Zip the project (reuses `createPublishArchive` so the
* file-ignore set matches the existing `publish` command exactly).
* 3. Upload the zip via the direct-to-S3 flow: `POST /v3/assets/
* direct-uploads` returns a presigned URL, we PUT the zip bytes
* to it, then `POST /v3/assets/{asset_id}/complete` finalizes.
* Cap: 200 MB. See `../../cloud/upload.ts` for the three-step
* contract. (The legacy `POST /v3/assets` proxy path was 32 MB.)
* 4. Submit the render via `POST /v3/hyperframes/renders` with a
* `project: {type:"asset_id", asset_id}` shape.
* 5. If `--no-wait`: print the `render_id` and exit immediately.
* Otherwise poll `GET /v3/hyperframes/renders/{id}` every
* `--poll-interval` (default 2s, max 60min). `--callback-url`
* can be combined with either mode: the webhook always fires when
* the server-side render terminates, independent of whether the
* CLI is still polling.
* 6. On `completed`: stream the signed `video_url` to disk.
* 7. On `failed`: print `failure_message` and exit 1.
*
* Auth comes from the existing `cli/src/auth/` chain via `cloud/auth.ts`.
* The cloud HTTP client (`cloud/_gen/client.ts`) is generated from
* HeyGen's external API OpenAPI spec; never hand-edit it.
*/
import { defineCommand } from "citty";
import {
detectAspectRatioFromHtml,
type AspectRatioDetection,
} from "../../cloud/detectAspectRatio.js";
import { c } from "../../ui/colors.js";
import { errorBox, formatBytes, formatDuration } from "../../ui/format.js";
import { resolveProject, type ProjectDir } from "../../utils/project.js";
import { normalizeErrorMessage } from "../../utils/errorMessage.js";
import {
readStaged,
type StagedFile,
stagedSize,
stagePublishFiles,
type PublishArchiveResult,
zipPublishFileMap,
} from "../../utils/publishProject.js";
import {
reportVariableIssues,
resolveVariablesArg,
validateVariablesAgainstProject,
} from "../../utils/variables.js";
import { withMeta } from "../../utils/updateCheck.js";
import type { Example } from "../_examples.js";
import {
DEFAULT_MAX_WAIT_MS,
DEFAULT_POLL_INTERVAL_MS,
PollTimeoutError,
createCloudClient,
downloadToFile,
pollUntilTerminal,
} from "../../cloud/index.js";
import { reportApiError } from "../../cloud/errors.js";
import { parseEnumFlag, parseIntFlag, parseNumericFlag } from "../../cloud/parsing.js";
import { uploadAssetViaDirectUpload, uploadZipViaDirectUpload } from "../../cloud/upload.js";
import {
OFFLOAD_MIN_BYTES,
offloadHeavyMedia,
type OffloadedMedia,
type OffloadOptions,
} from "../../cloud/offload.js";
import { resolveCloudBaseUrl } from "../../cloud/auth.js";
import { colorStatus } from "../../cloud/statusColor.js";
import type {
CreateHyperframesRenderRequest,
HyperframesCloudClient,
HyperframesRenderDetail,
} from "../../cloud/index.js";
import { isAbsolute, relative, resolve as resolvePath } from "node:path";
import { existsSync } from "node:fs";
const VALID_QUALITY = ["draft", "standard", "high"] as const;
const VALID_FORMAT = ["mp4", "webm", "mov"] as const;
const VALID_RESOLUTION = ["1080p", "4k"] as const;
const VALID_ASPECT_RATIO = ["16:9", "9:16", "1:1"] as const;
// Mirrors the binary-byte max_bytes contract used by direct asset uploads.
const DIRECT_UPLOAD_LIMIT_BYTES = 200 * 1024 * 1024;
const ARCHIVE_DIAGNOSTIC_THRESHOLD_BYTES = 150 * 1024 * 1024;
const LARGEST_FILE_COUNT = 10;
const FORMAT_EXT: Record<string, string> = { mp4: ".mp4", webm: ".webm", mov: ".mov" };
export const examples: Example[] = [
["Render the current directory in the cloud", "hyperframes cloud render"],
["Inspect archive size without uploading", "hyperframes cloud render --dry-run"],
[
"Pick a specific composition + output path",
"hyperframes cloud render . --composition compositions/intro.html -o ./renders/intro.mp4",
],
["Higher quality, 60fps", "hyperframes cloud render --quality high --fps 60"],
[
"Submit and exit; webhook fires when the render terminates",
"hyperframes cloud render --callback-url https://example.com/hook --no-wait",
],
[
"Override variables (parametrized render)",
'hyperframes cloud render --variables \'{"title":"Q4 Recap","theme":"dark"}\'',
],
["Re-render an already-uploaded zip", "hyperframes cloud render --asset-id asst_abc123"],
];
export default defineCommand({
meta: { name: "render", description: "Render a HyperFrames composition in the cloud" },
args: {
dir: { type: "positional", required: false, description: "Project directory (default: .)" },
fps: { type: "string", description: "Frames per second (1-240). Default: 30." },
quality: { type: "string", description: "draft | standard | high (default: standard)" },
format: { type: "string", description: "mp4 | webm | mov (default: mp4)" },
"page-motion-blur": {
type: "string",
description:
"Set off to disable authored page motion blur. Omit to keep the current cloud behavior.",
},
resolution: {
type: "string",
description: "Resolution tier: 1080p | 4k (default: 1080p; 4k is billed at 1.5x)",
},
"aspect-ratio": {
type: "string",
description: "Aspect ratio: 16:9 | 9:16 | 1:1 (default: 16:9)",
},
composition: {
type: "string",
alias: "c",
description: "Entry HTML file inside the zip (default: index.html)",
},
variables: {
type: "string",
description:
'Inline JSON object overriding data-composition-variables. Example: --variables \'{"title":"X"}\'',
},
"variables-file": {
type: "string",
description: "Path to a JSON file with variable values (alternative to --variables)",
},
"strict-variables": {
type: "boolean",
description: "Fail when --variables keys are undeclared or have the wrong type",
default: false,
},
title: {
type: "string",
description: "Free-text label echoed back in detail responses",
},
"callback-url": {
type: "string",
description:
"HTTPS webhook fired when the render terminates. Fires regardless of whether the CLI is still polling — combine with --no-wait for true fire-and-forget.",
},
"callback-id": {
type: "string",
description: "Opaque tracking ID echoed in webhook payloads",
},
"asset-id": {
type: "string",
description:
"Skip zip+upload and submit an already-uploaded composition. Mutually exclusive with --url and the project dir.",
},
url: {
type: "string",
description:
"Public HTTPS URL of a composition zip. Mutually exclusive with --asset-id and the project dir.",
},
// Citty parses `--no-FOO` as `--FOO=false`. A flag literally named
// "no-wait" gets routed as `args.wait=false`, leaving
// `args["no-wait"]` undefined and the early-return for
// fire-and-forget mode unreachable. Named the arg `wait` so the
// user-facing `--no-wait` flag works via citty's negation; the
// run() body checks `if (!args.wait)`.
wait: {
type: "boolean",
description:
"Poll until completion and download the video (default: true). Pass `--no-wait` for fire-and-forget — submits and exits with the render_id.",
default: true,
},
output: {
type: "string",
alias: "o",
description: "Destination path for the downloaded video (default: renders/<render_id>.<ext>)",
},
"poll-interval": {
type: "string",
description: `Poll cadence in seconds (default: ${DEFAULT_POLL_INTERVAL_MS / 1000})`,
},
"max-wait": {
type: "string",
description: `Max poll duration in minutes (default: ${DEFAULT_MAX_WAIT_MS / 60_000})`,
},
json: {
type: "boolean",
description: "Emit machine-readable JSON instead of human-friendly progress",
default: false,
},
"dry-run": {
type: "boolean",
description: "Build and inspect the project zip without authenticating or uploading",
default: false,
},
"idempotency-key": {
type: "string",
description: "Optional Idempotency-Key for safe retries (1-255 chars from [A-Za-z0-9_:.-])",
},
},
// fallow-ignore-next-line complexity
async run({ args }) {
const asJson = Boolean(args.json);
const fps = parseIntFlag(args.fps, { flag: "--fps", min: 1, max: 240 });
const quality = parseEnumFlag(args.quality, VALID_QUALITY, { flag: "--quality" });
const format = parseEnumFlag(args.format, VALID_FORMAT, { flag: "--format" });
const pageMotionBlur = parseEnumFlag(args["page-motion-blur"], ["off"] as const, {
flag: "--page-motion-blur",
});
const resolution = parseEnumFlag(args.resolution, VALID_RESOLUTION, {
flag: "--resolution",
});
const explicitAspectRatio = parseEnumFlag(args["aspect-ratio"], VALID_ASPECT_RATIO, {
flag: "--aspect-ratio",
});
const pollIntervalMs = parsePollIntervalMs(args["poll-interval"]);
const maxWaitMs = parseMaxWaitMs(args["max-wait"]);
validateIdempotencyKey(args["idempotency-key"]);
// Project resolution runs BEFORE variables resolution so a user
// passing conflicting inputs (`dir + --asset-id`) sees the
// structural error before any variable parsing errors.
const project = resolveProjectInput({
dir: args.dir,
assetId: args["asset-id"],
url: args.url,
});
validateDryRunSource(project, args["dry-run"] ?? false);
// Aspect ratio is derived from the composition's authored dimensions: for
// a local dir we parse the entry HTML and auto-detect, so the user rarely
// needs --aspect-ratio at all. When they DO pass it, we validate it
// matches the composition (the renderer can't reshape, only supersample to
// a matching ratio) and fail fast on a mismatch. This also fails fast when
// the --composition entry file is missing, rather than uploading a zip the
// render rejects with a generic server-side error.
const aspectRatio = resolveAspectRatioForSubmit(
project,
args.composition,
explicitAspectRatio,
asJson,
);
if (args["dry-run"]) {
if (project.kind !== "dir") throw new Error("Dry-run project must be a local directory");
reportDryRun(await prepareLocalArchive(project, args.composition, asJson), asJson);
return;
}
const variables = resolveVariablesAndValidateIfLocal(
args.variables,
args["variables-file"],
args["strict-variables"] ?? false,
project,
);
const client = await createCloudClient();
const preparedArchive =
project.kind === "dir"
? await prepareLocalArchive(project, args.composition, asJson, (file) =>
uploadAssetViaDirectUpload({ client, ...file }),
)
: undefined;
const upload = await maybeUploadProject(
client,
project,
preparedArchive,
asJson,
args["idempotency-key"],
);
const submitted = await submitRender(client, {
projectInput: upload.projectInput,
fps,
quality,
format,
resolution,
pageMotionBlur,
aspectRatio,
composition: args.composition,
variables,
title: args.title,
callbackUrl: args["callback-url"],
callbackId: args["callback-id"],
idempotencyKey: args["idempotency-key"],
});
const renderId = submitted.render_id;
if (!args.wait) {
if (asJson) {
console.log(
JSON.stringify(
withMeta({ render: { render_id: renderId, status: "queued" as const } }),
null,
2,
),
);
} else {
console.log("");
console.log(`${c.success("✓")} Submitted ${c.accent(renderId)}`);
console.log(c.dim(` Poll with: hyperframes cloud get ${renderId}`));
}
return;
}
if (!asJson) {
console.log("");
console.log(c.dim(` Polling ${renderId} every ${pollIntervalMs / 1000}s …`));
}
const detail = await pollWithProgress(client, renderId, asJson, {
intervalMs: pollIntervalMs,
maxWaitMs,
});
if (detail.status === "failed") {
handleFailedRender(detail, asJson);
}
if (!detail.video_url) {
errorBox(
"Render completed but returned no video_url",
`render_id: ${renderId}. Try \`hyperframes cloud get ${renderId}\` to inspect raw fields.`,
);
failCommand();
}
const outputPath = resolveOutputPath(args.output, renderId, detail.format);
const downloadResult = await streamVideo(detail.video_url, outputPath, asJson);
if (asJson) {
console.log(
JSON.stringify(
withMeta({
render: detail,
output_path: outputPath,
bytes_written: downloadResult.bytes,
}),
null,
2,
),
);
}
},
});
// ---------------------------------------------------------------------------
// Argument parsing — defers to cloud/parsing.ts for strict validators
// ---------------------------------------------------------------------------
function parsePollIntervalMs(raw: string | undefined): number {
const n = parseNumericFlag(raw, { flag: "--poll-interval", min: 1 });
return n === undefined ? DEFAULT_POLL_INTERVAL_MS : Math.round(n * 1000);
}
function parseMaxWaitMs(raw: string | undefined): number {
const n = parseNumericFlag(raw, { flag: "--max-wait", min: 0.0001 });
return n === undefined ? DEFAULT_MAX_WAIT_MS : Math.round(n * 60_000);
}
const IDEMPOTENCY_KEY_RE = /^[A-Za-z0-9_:.-]{1,255}$/;
function validateIdempotencyKey(key: string | undefined): void {
if (key === undefined) return;
if (!IDEMPOTENCY_KEY_RE.test(key)) {
errorBox("Invalid --idempotency-key", `Got "${key}". Must be 1-255 chars from [A-Za-z0-9_:.-]`);
failCommand();
}
}
export function validateDryRunSource(source: ProjectInputSource, dryRun: boolean): void {
if (!dryRun || source.kind === "dir") return;
errorBox(
"Invalid --dry-run input",
"--dry-run inspects a local project directory and cannot be combined with --asset-id or --url.",
);
failCommand();
}
// ---------------------------------------------------------------------------
// Project resolution (dir | asset-id | url) — exactly one source
// ---------------------------------------------------------------------------
export interface ProjectInputSource {
kind: "dir" | "asset_id" | "url";
dir?: string;
assetId?: string;
url?: string;
}
// fallow-ignore-next-line complexity
function resolveProjectInput(opts: {
dir: string | undefined;
assetId: string | undefined;
url: string | undefined;
}): ProjectInputSource {
// Count every source the user explicitly supplied. The positional
// `dir` defaults to `undefined` when omitted (not to "."), so we
// can detect "user actually typed something" vs. "default to cwd".
const explicit = {
dir: opts.dir !== undefined && opts.dir !== "",
assetId: opts.assetId !== undefined && opts.assetId !== "",
url: opts.url !== undefined && opts.url !== "",
};
const count = Number(explicit.dir) + Number(explicit.assetId) + Number(explicit.url);
if (count > 1) {
errorBox("Conflicting inputs", "Pass only one of: project dir, --asset-id, --url.");
failCommand();
}
if (explicit.assetId) return { kind: "asset_id", assetId: opts.assetId };
if (explicit.url) return { kind: "url", url: opts.url };
return { kind: "dir", dir: opts.dir ?? "." };
}
/**
* Resolve the aspect ratio for the submit body, validating local inputs.
*
* Aspect ratio is a property of the composition (its `data-width`/
* `data-height`), not an independent render knob — the pipeline supersamples
* to a *matching* ratio and can't reshape. So for a local dir we auto-detect
* from the entry HTML and the user rarely needs `--aspect-ratio`. Behaviour:
*
* - Local dir, no explicit flag → auto-detect and log the result.
* - Local dir, explicit flag that conflicts with the detected dims → hard
* error (the render would otherwise fail or silently ignore the request).
* - Local dir with a missing `--composition` entry → hard error before
* upload, instead of a generic server-side render failure.
* - `--asset-id` / `--url` → the zip isn't on disk; trust an explicit flag,
* otherwise let the server default (16:9) apply.
*
* Logs are suppressed in `--json` mode so machine output stays clean.
*/
// fallow-ignore-next-line complexity
export function resolveAspectRatioForSubmit(
project: ProjectInputSource,
compositionArg: string | undefined,
explicit: "16:9" | "9:16" | "1:1" | undefined,
asJson: boolean,
): "16:9" | "9:16" | "1:1" | undefined {
if (project.kind !== "dir") {
if (!explicit) {
const reason = project.kind === "asset_id" ? "--asset-id" : "--url";
logDetection(asJson, `Auto-detect skipped (project is ${reason})`);
}
return explicit;
}
const dir = project.dir ?? ".";
const entryRelative = compositionArg ?? "index.html";
const entryPath = resolvePath(dir, entryRelative);
if (!existsSync(entryPath)) {
errorBox(
"Composition not found",
`Entry file "${entryRelative}" does not exist in ${dir}.`,
"Pass --composition with a path that exists inside the project, or omit it to use index.html.",
);
failCommand();
}
const detection = detectAspectRatioFromHtml(entryPath);
if (explicit) {
// The renderer matches the composition's authored aspect ratio — it can't
// reshape. Both a `matched` ratio that differs from `explicit` AND a
// `no-match` (dims are known but the ratio isn't 16:9/9:16/1:1, so it can
// never equal the requested supported ratio) are definite conflicts.
// Other kinds (no-dims / no-root-div / invalid-dims / read-error) leave the
// ratio unknown, so we can't prove a conflict and forward the explicit value.
const conflictDetail =
detection.kind === "matched" && detection.aspectRatio !== explicit
? `${detection.width}×${detection.height} → ${detection.aspectRatio}`
: detection.kind === "no-match"
? `${detection.width}×${detection.height}, ratio ${detection.ratio.toFixed(2)} — not a supported ratio`
: undefined;
if (conflictDetail) {
errorBox(
"Aspect ratio mismatch",
`--aspect-ratio ${explicit} doesn't match the composition (${conflictDetail}).`,
"The renderer matches the composition's authored aspect ratio — it can't reshape it. Drop --aspect-ratio (it's auto-detected) or re-author the composition at the target ratio.",
);
failCommand();
}
return explicit;
}
logDetection(asJson, summarizeDetection(detection, entryRelative));
return detection.kind === "matched" ? detection.aspectRatio : undefined;
}
const ASPECT_FALLBACK_HINT =
"server will default aspect_ratio to 16:9. Pass --aspect-ratio to override.";
function logDetection(asJson: boolean, message: string): void {
if (asJson) return;
// `matched` is the only branch with its own affirmative phrasing; the
// rest share the fallback hint to keep the user oriented after a miss.
const suffix = message.startsWith("Detected aspect ratio") ? "" : `; ${ASPECT_FALLBACK_HINT}`;
console.log(c.dim(` ${message}${suffix}`));
}
// fallow-ignore-next-line complexity
function summarizeDetection(detection: AspectRatioDetection, entryRelative: string): string {
switch (detection.kind) {
case "matched":
return `Detected aspect ratio: ${detection.aspectRatio} (from ${entryRelative} dims ${detection.width}×${detection.height})`;
case "no-root-div":
return `No <div data-composition-id> found in ${entryRelative}`;
case "no-dims":
return `${entryRelative} root composition has no data-width / data-height`;
case "invalid-dims":
return `${entryRelative} root has invalid dims (${detection.width}×${detection.height})`;
case "no-match":
return `${entryRelative} dims ${detection.width}×${detection.height} (ratio ${detection.ratio.toFixed(2)}) don't match 16:9, 9:16, or 1:1`;
case "read-error":
return `Couldn't read ${entryRelative} for aspect-ratio detection (${detection.error})`;
}
}
function resolveVariablesAndValidateIfLocal(
inline: string | undefined,
filePath: string | undefined,
strict: boolean,
source: ProjectInputSource,
): Record<string, unknown> | undefined {
const variables = resolveVariablesArg(inline, filePath);
if (!variables || Object.keys(variables).length === 0) return variables;
// Only validate against the local composition when we actually have
// a local project on disk. For --asset-id / --url paths the schema
// lives on the server side, so we send the variables as-is and let
// the API surface any mismatch via `hyperframes_project_invalid`.
if (source.kind !== "dir") return variables;
// `resolveProject` calls process.exit on a missing/invalid dir, so
// there's no need to wrap this in try/catch — if it returns, the
// index.html is present. The earlier impl had a dead try/catch.
const { indexPath } = resolveProject(source.dir);
const issues = validateVariablesAgainstProject(indexPath, variables);
reportVariableIssues(issues, { strict, quiet: false });
return variables;
}
// ---------------------------------------------------------------------------
// Upload step (only when project is a local dir)
// ---------------------------------------------------------------------------
interface UploadResult {
projectInput: CreateHyperframesRenderRequest["project"];
}
export interface ArchiveFileSummary {
path: string;
size_bytes: number;
}
interface PreparedLocalArchive {
project: ProjectDir;
/** Absent when the files left on disk alone are over the upload limit: they are never read. */
archive?: PublishArchiveResult;
sizeBytes: number;
fileCount: number;
largestFiles: ArchiveFileSummary[];
offloaded: OffloadedMedia[];
}
function summarizeLargestFiles(fileMap: Map<string, StagedFile>): ArchiveFileSummary[] {
return [...fileMap.entries()]
.map(([path, content]) => ({ path, size_bytes: stagedSize(content) }))
.sort((a, b) => b.size_bytes - a.size_bytes || a.path.localeCompare(b.path))
.slice(0, LARGEST_FILE_COUNT);
}
async function prepareLocalArchive(
source: ProjectInputSource,
composition: string | undefined,
asJson: boolean,
upload?: OffloadOptions["upload"],
): Promise<PreparedLocalArchive> {
const project = resolveProject(source.dir);
if (!asJson) {
console.log("");
console.log(`${c.accent("◆")} Zipping ${c.accent(project.name)}`);
}
const { fileMap, entryPath } = stageProjectFiles(project, composition);
const offloaded = await offloadMedia(project, fileMap, entryPath, asJson, upload);
// Media left on disk barely compresses: past the limit, its size is the report and nothing is read.
const onDiskBytes = [...fileMap.values()]
.filter((file) => !Buffer.isBuffer(file))
.reduce((sum, file) => sum + stagedSize(file), 0);
const archive =
onDiskBytes > DIRECT_UPLOAD_LIMIT_BYTES
? undefined
: zipPublishFileMap(new Map([...fileMap].map(([path, file]) => [path, readStaged(file)])));
const sizeBytes = archive?.buffer.byteLength ?? onDiskBytes;
if (!asJson) {
console.log(c.dim(` ${fileMap.size} files · ${formatBytes(sizeBytes)}`));
}
const largestFiles = summarizeLargestFiles(fileMap);
const prepared = {
project,
archive,
sizeBytes,
fileCount: fileMap.size,
largestFiles,
offloaded,
};
if (upload) assertArchiveFits(sizeBytes, largestFiles);
if (!asJson && sizeBytes >= ARCHIVE_DIAGNOSTIC_THRESHOLD_BYTES) {
reportLargestFiles(prepared);
}
return prepared;
}
function stageProjectFiles(
project: ProjectDir,
composition: string | undefined,
): { fileMap: Map<string, StagedFile>; entryPath: string } {
try {
const fileMap = stagePublishFiles(project.dir, OFFLOAD_MIN_BYTES);
const entryPath = relative(
project.dir,
resolvePath(project.dir, composition ?? "index.html"),
).replaceAll("\\", "/");
if (!fileMap.has(entryPath)) {
throw new Error(
`Composition "${composition ?? "index.html"}" is excluded from the archive. Check .hyperframesignore.`,
);
}
return { fileMap, entryPath };
} catch (err) {
const msg = normalizeErrorMessage(err);
errorBox("Zip failed", msg, "Check the project and .hyperframesignore for missing files.");
failCommand();
}
}
async function offloadMedia(
project: ProjectDir,
fileMap: Map<string, StagedFile>,
entryPath: string,
asJson: boolean,
upload: OffloadOptions["upload"],
): Promise<OffloadedMedia[]> {
let offloaded: OffloadedMedia[];
try {
offloaded = await offloadHeavyMedia(project.dir, fileMap, {
apiBaseUrl: resolveCloudBaseUrl(),
upload,
entryPath,
onFile: asJson
? undefined
: (item) => console.log(c.dim(` ${describeOffload(item, !upload)}`)),
});
} catch (err) {
reportApiError("Media upload failed", err);
}
if (!asJson) {
for (const item of offloaded.filter((entry) => entry.kept_in_archive)) {
console.log(
c.dim(
` ${item.path} also stays in the zip: a script builds its path in a way that cannot be rewritten`,
),
);
}
}
return offloaded;
}
export function assertArchiveFits(sizeBytes: number, largestFiles: ArchiveFileSummary[]): void {
if (sizeBytes <= DIRECT_UPLOAD_LIMIT_BYTES) return;
errorBox(
"Project too large for cloud render",
`The zip is ${formatBytes(sizeBytes)} after moving media to HeyGen assets, over the ${formatBytes(DIRECT_UPLOAD_LIMIT_BYTES)} upload limit. Largest files left in it:\n${largestFiles
.map((file) => ` ${formatBytes(file.size_bytes).padStart(9)} ${file.path}`)
.join("\n")}`,
"Exclude files the render does not need with .hyperframesignore.",
);
failCommand();
}
function describeOffload(item: OffloadedMedia, dryRun: boolean): string {
const verb =
item.action === "cached"
? "already uploaded"
: item.action === "reencode"
? dryRun
? "would re-encode and upload"
: "re-encoded and uploaded"
: dryRun
? "would upload"
: "uploaded";
return `${formatBytes(item.size_bytes).padStart(9)} ${item.path} · ${verb}`;
}
function reportLargestFiles(prepared: PreparedLocalArchive): void {
console.log(c.dim(" Largest included files:"));
for (const file of prepared.largestFiles) {
console.log(c.dim(` ${formatBytes(file.size_bytes).padStart(9)} ${file.path}`));
}
console.log(c.dim(" Exclude verified-unneeded files with .hyperframesignore."));
}
function reportDryRun(prepared: PreparedLocalArchive, asJson: boolean): void {
const { sizeBytes } = prepared;
if (asJson) {
console.log(
JSON.stringify(
withMeta({
archive: {
project: prepared.project.name,
file_count: prepared.fileCount,
size_bytes: sizeBytes,
upload_limit_bytes: DIRECT_UPLOAD_LIMIT_BYTES,
exceeds_upload_limit: sizeBytes > DIRECT_UPLOAD_LIMIT_BYTES,
largest_files: prepared.largestFiles,
offloaded_media: prepared.offloaded,
},
}),
null,
2,
),
);
return;
}
if (sizeBytes < ARCHIVE_DIAGNOSTIC_THRESHOLD_BYTES) reportLargestFiles(prepared);
console.log("");
console.log(`${c.success("✓")} Dry run complete — nothing uploaded`);
if (sizeBytes > DIRECT_UPLOAD_LIMIT_BYTES) {
console.log(c.warn(` Archive exceeds the 200 MB direct-upload limit.`));
}
}
// fallow-ignore-next-line complexity
async function maybeUploadProject(
client: HyperframesCloudClient,
source: ProjectInputSource,
preparedArchive: PreparedLocalArchive | undefined,
asJson: boolean,
idempotencyKey: string | undefined,
): Promise<UploadResult> {
if (source.kind === "asset_id") {
return { projectInput: { type: "asset_id", asset_id: source.assetId! } };
}
if (source.kind === "url") {
return { projectInput: { type: "url", url: source.url! } };
}
if (!preparedArchive) throw new Error("Local project archive was not prepared");
const { project, archive } = preparedArchive;
if (!archive) throw new Error("Local project archive is over the upload limit");
if (!asJson) {
console.log("");
console.log(`${c.accent("◆")} Uploading (direct-to-S3)`);
}
const uploadStart = Date.now();
let uploaded;
try {
uploaded = await uploadZipViaDirectUpload({
client,
bytes: archive.buffer,
filename: `${project.name}.zip`,
idempotencyKey,
onProgress: !asJson
? (ev) => {
if (ev.phase === "initialize") {
console.log(c.dim(` initializing…`));
} else if (ev.phase === "upload" && ev.percent === 0) {
console.log(c.dim(` uploading to S3…`));
} else if (ev.phase === "complete") {
console.log(c.dim(` finalizing…`));
}
}
: undefined,
});
} catch (err) {
reportApiError("Upload failed", err);
}
if (!asJson) {
console.log(
c.dim(
` asset_id: ${c.accent(uploaded.asset_id)} · ${formatDuration(Date.now() - uploadStart)}`,
),
);
}
return { projectInput: { type: "asset_id", asset_id: uploaded.asset_id } };
}
// ---------------------------------------------------------------------------
// Submit step
// ---------------------------------------------------------------------------
interface SubmitOptions {
projectInput: CreateHyperframesRenderRequest["project"];
fps: number | undefined;
quality: "draft" | "standard" | "high" | undefined;
format: "mp4" | "webm" | "mov" | undefined;
pageMotionBlur: NonNullable<CreateHyperframesRenderRequest["page_motion_blur"]> | undefined;
resolution: CreateHyperframesRenderRequest["resolution"] | undefined;
aspectRatio: CreateHyperframesRenderRequest["aspect_ratio"] | undefined;
composition: string | undefined;
variables: Record<string, unknown> | undefined;
title: string | undefined;
callbackUrl: string | undefined;
callbackId: string | undefined;
idempotencyKey: string | undefined;
}
async function submitRender(
client: HyperframesCloudClient,
opts: SubmitOptions,
): Promise<{ render_id: string }> {
const body = buildRenderBody(opts);
try {
return await client.createRender({ body, idempotencyKey: opts.idempotencyKey });
} catch (err) {
reportApiError("Submit failed", err);
}
}
// fallow-ignore-next-line complexity
function buildRenderBody(opts: SubmitOptions): CreateHyperframesRenderRequest {
const body: CreateHyperframesRenderRequest = { project: opts.projectInput };
if (opts.fps !== undefined) body.fps = opts.fps;
if (opts.quality !== undefined) body.quality = opts.quality;
if (opts.format !== undefined) body.format = opts.format;
if (opts.pageMotionBlur !== undefined) body.page_motion_blur = opts.pageMotionBlur;
if (opts.resolution !== undefined) body.resolution = opts.resolution;
if (opts.aspectRatio !== undefined) body.aspect_ratio = opts.aspectRatio;
if (opts.composition !== undefined) body.composition = opts.composition;
if (opts.variables !== undefined) body.variables = opts.variables;
if (opts.title !== undefined) body.title = opts.title;
if (opts.callbackUrl !== undefined) body.callback_url = opts.callbackUrl;
if (opts.callbackId !== undefined) body.callback_id = opts.callbackId;
return body;
}
// ---------------------------------------------------------------------------
// Poll + progress
// ---------------------------------------------------------------------------
// fallow-ignore-next-line complexity
async function pollWithProgress(
client: HyperframesCloudClient,
renderId: string,
asJson: boolean,
poll: { intervalMs: number; maxWaitMs: number },
): Promise<HyperframesRenderDetail> {
// ANSI carriage-return redraws only make sense on a TTY. CI logs and
// file redirects get one append per status change instead, and JSON
// mode stays silent altogether.
const interactive = !asJson && process.stdout.isTTY === true;
let lastStatus = "";
try {
return await pollUntilTerminal(client, renderId, {
intervalMs: poll.intervalMs,
maxWaitMs: poll.maxWaitMs,
// fallow-ignore-next-line complexity
onTick: (detail, elapsedMs) => {
if (asJson) return;
if (interactive) {
if (detail.status === lastStatus) {
process.stdout.write(`\r\x1b[2K ${formatTickLine(detail, elapsedMs)}`);
} else {
if (lastStatus) process.stdout.write("\n");
process.stdout.write(` ${formatTickLine(detail, elapsedMs)}`);
lastStatus = detail.status;
}
} else if (detail.status !== lastStatus) {
// Non-TTY: one line per status transition, no carriage returns.
console.log(` ${formatTickLine(detail, elapsedMs)}`);
lastStatus = detail.status;
}
},
});
} catch (err) {
if (!asJson && lastStatus && interactive) process.stdout.write("\n");
if (err instanceof PollTimeoutError) {
errorBox(
"Poll timed out",
err.message,
`The render may still complete. Resume with: hyperframes cloud get ${renderId}`,
);
failCommand();
}
return reportApiError("API error during poll", err, {
suggestion: `The render may still be running. Resume with: hyperframes cloud get ${renderId}`,
});
} finally {
if (!asJson && lastStatus && interactive) process.stdout.write("\n");
}
}
function formatTickLine(detail: HyperframesRenderDetail, elapsedMs: number): string {
const status = colorStatus(detail.status);
return `${status} ${c.dim(formatDuration(elapsedMs))}`;
}
// ---------------------------------------------------------------------------
// Terminal handlers
// ---------------------------------------------------------------------------
function handleFailedRender(detail: HyperframesRenderDetail, asJson: boolean): never {
if (asJson) {
console.log(JSON.stringify(withMeta({ render: detail }), null, 2));
failCommand();
}
errorBox(
"Render failed",
detail.failure_message ?? "(no failure_message returned)",
`Inspect: hyperframes cloud get ${detail.render_id}`,
);
failCommand();
}
function resolveOutputPath(output: string | undefined, renderId: string, format: string): string {
if (output) {
return isAbsolute(output) ? output : resolvePath(process.cwd(), output);
}
const ext = FORMAT_EXT[format] ?? `.${format}`;
return resolvePath(process.cwd(), "renders", `${renderId}${ext}`);
}
// fallow-ignore-next-line complexity
async function streamVideo(
url: string,
destPath: string,
asJson: boolean,
): Promise<{ bytes: number }> {
// `downloadToFile` creates the parent directory and preserves existing output on failure.
if (!asJson) {
console.log("");
console.log(`${c.accent("◆")} Downloading to ${c.accent(destPath)}`);
}
try {
const result = await downloadToFile(url, destPath);
if (!asJson) {
console.log(c.dim(` ${formatBytes(result.bytes)} written`));
}
return { bytes: result.bytes };
} catch (err) {
const message = normalizeErrorMessage(err);
errorBox(
"Download failed",
message,
"The presigned URL is short-lived; re-fetch with `hyperframes cloud get`.",
);
failCommand();
}
}