Files
hyperframes/packages/cli/src/commands/cloud/render.ts
T
Miguel Ángel d317abcdba fix(cli): cloud render --json reports re-encode progress and times out a stalled cache check (#7755)
* fix(cli): cloud render --json reports re-encode progress and times out a stalled cache check

* refactor(parsers): share the ffmpeg progress reader from ff-binaries

The reader lived in a new studio-server entry point, which pushed its packed size over budget and left package.json out of step with package-subpaths.json. Both callers already depend on parsers. The re-encode now gets a progress callback only when someone listens.

* style(cli): format the offload test
2026-11-17 10:30:43 +00:00

1259 lines
46 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import { failCommand, failUsage } 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 "../../utils/defineCommand.js";
import {
ASPECT_RATIO_MATCH_TOLERANCE,
detectAspectRatioFromHtml,
type AspectRatioDetection,
type SupportedAspectRatio,
} from "../../cloud/detectAspectRatio.js";
import {
CANVAS_DIMENSIONS,
checkOutputResolutionCompatibility,
type CanvasResolution,
} from "@hyperframes/core";
import { c } from "../../ui/colors.js";
import { errorBox, formatBytes, formatDuration } from "../../ui/format.js";
import { describeUnresolvedFontUse } from "../../cloud/fontFailure.js";
import { resolveDefaultFpsArg } from "../../utils/renderArgs.js";
import { resolveProject, type ProjectDir } from "../../utils/project.js";
import { readProjectConfig } from "../../utils/projectConfig.js";
import { normalizeErrorMessage } from "../../utils/errorMessage.js";
import {
archiveKey,
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 LeftOutReference,
type OnLeftOut,
type OnOutsideFile,
type OutsideFileReference,
outsideFilesNotice,
} from "../../utils/leftOutReference.js";
import { trackUploadLeftOut } from "../../telemetry/uploadLeftOut.js";
import { isUnattended } from "../../utils/attendedTerminal.js";
import {
confirmOutsideFiles,
stageWithOutsideFileApproval,
} from "../../utils/outsideFileApproval.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 { describeSwappedFonts, embedSystemFonts } from "../../cloud/fontPreflight.js";
import { parseEnumFlag, parseIntFlag, parseNumericFlag } from "../../cloud/parsing.js";
import {
uploadAssetViaDirectUpload,
uploadZipViaDirectUpload,
type UploadProgressEvent,
} 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 { statSync } from "node:fs";
import {
compositionEntryErrorMessage,
parseCompositionEntryArg,
} from "../../utils/compositionEntry.js";
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 ZIP_BUDGET_BYTES_WITH_ROOM_FOR_ZIP_RECORDS = Math.floor(DIRECT_UPLOAD_LIMIT_BYTES * 0.95);
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: the composition's root data-fps, else 30.",
},
quality: { type: "string", description: "draft | standard | high (default: standard)" },
format: { type: "string", description: "mp4 | webm | mov (default: mp4)" },
resolution: {
type: "string",
description: "Resolution tier: 1080p | 4k (default: 1080p; 4k is billed at 1.5x)",
},
"aspect-ratio": {
type: "string",
description:
"W:H; detected from the composition, so rarely needed. The render keeps the composition's own size; 4k needs 16:9, 9:16 or 1:1",
},
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. 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,
},
"include-outside-files": {
type: "boolean",
description:
"Upload the files the project uses from outside its folder without asking. Otherwise they are left out unless you approve them.",
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 quality = parseEnumFlag(args.quality, VALID_QUALITY, { flag: "--quality" });
const format = parseEnumFlag(args.format, VALID_FORMAT, { flag: "--format" });
const resolution = parseEnumFlag(args.resolution, VALID_RESOLUTION, {
flag: "--resolution",
});
const explicitAspectRatio = parseAspectRatioFlag(args["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);
const fps = parseIntFlag(resolveCloudFpsArg(project, args.fps, args.composition), {
flag: "--fps",
min: 1,
max: 240,
});
// 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,
resolution,
);
const includeOutsideFiles = args["include-outside-files"] === true;
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, includeOutsideFiles),
asJson,
);
return;
}
const variables = resolveVariablesAndValidateIfLocal(
args.variables,
args["variables-file"],
args["strict-variables"] ?? false,
project,
args.composition,
);
const client = await createCloudClient();
const preparedArchive =
project.kind === "dir"
? await prepareLocalArchive(
project,
args.composition,
asJson,
includeOutsideFiles,
(file) =>
uploadAssetViaDirectUpload({
client,
...file,
onProgress: reportUploadProgress(file.filename, asJson),
}),
variables && JSON.stringify(variables),
)
: undefined;
const upload = await maybeUploadProject(
client,
project,
preparedArchive,
asJson,
args["idempotency-key"],
);
const submitted = await submitRender(client, {
projectInput: upload.projectInput,
fps,
quality,
format,
resolution,
aspectRatio,
composition: args.composition,
variables,
title: args.title,
callbackUrl: args["callback-url"],
callbackId: args["callback-id"],
idempotencyKey: args["idempotency-key"],
reverseSessionId: reverseSessionIdOf(project),
});
const renderId = submitted.render_id;
if (!args.wait) {
if (asJson) {
console.log(
JSON.stringify(
withMeta({
render: { render_id: renderId, status: "queued" as const },
swapped_fonts: preparedArchive?.swappedFonts ?? [],
left_out: preparedArchive?.leftOut ?? [],
outside_files: preparedArchive?.outsideFiles ?? [],
}),
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, project.kind === "dir" ? (project.dir ?? ".") : undefined);
}
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,
swapped_fonts: preparedArchive?.swappedFonts ?? [],
left_out: preparedArchive?.leftOut ?? [],
outside_files: preparedArchive?.outsideFiles ?? [],
}),
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_:.-]`);
failUsage();
}
}
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.",
);
failUsage();
}
// ---------------------------------------------------------------------------
// 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.");
failUsage();
}
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 a render knob: at 1080p the
* cloud renders at the composition's own size whatever `aspect_ratio` says, and a 4k render scales it up to a 16:9,
* 9:16 or 1:1 preset, the only values the API accepts. So:
*
* - a detected 16:9 / 9:16 / 1:1 is sent;
* - any other ratio (2:1, 4:5, …) is not sent at 1080p, where the output keeps the composition's size, and is
* refused before upload at 4k, where no preset fits it;
* - an explicit `--aspect-ratio W:H` that contradicts the composition is refused before upload.
*
* 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: string | undefined,
asJson: boolean,
resolution: "1080p" | "4k" = "1080p",
): SupportedAspectRatio | undefined {
if (project.kind !== "dir") {
if (explicit && isSupportedAspectRatio(explicit)) return explicit;
if (explicit) refuseUnsupportedAt4k(resolution, `--aspect-ratio ${explicit}`);
const reason = project.kind === "asset_id" ? "--asset-id" : "--url";
logDetection(asJson, `Auto-detect skipped (project is ${reason}); ${KEEPS_OWN_SIZE}`);
return undefined;
}
const dir = project.dir ?? ".";
const entry = parseCompositionEntryArg(compositionArg ?? "index.html", dir, statSync);
if (!entry.ok) {
const { title, message, hint } = compositionEntryErrorMessage(entry.error);
errorBox(title, message, hint);
failCommand();
}
const entryRelative = entry.value ?? "index.html";
const detection = detectAspectRatioFromHtml(resolvePath(dir, entryRelative));
const dims = detection.kind === "matched" || detection.kind === "no-match" ? detection : null;
if (explicit && dims && !sameRatio(explicit, dims.width / dims.height)) {
errorBox(
"Aspect ratio mismatch",
`--aspect-ratio ${explicit} doesn't match the composition (${dims.width}×${dims.height}, ${ratioLabel(dims.width, dims.height)}).`,
"The renderer keeps 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();
}
if (detection.kind === "matched") {
if (resolution === "4k") refuseUnfit4kPreset(detection);
logDetection(asJson, summarizeDetection(detection, entryRelative));
return detection.aspectRatio;
}
if (detection.kind === "no-match") {
refuseUnsupportedAt4k(
resolution,
`This composition (${detection.width}×${detection.height}, ${ratioLabel(detection.width, detection.height)})`,
`Render it at 1080p, which keeps ${detection.width}×${detection.height}, or re-author it at a supported ratio.`,
);
logDetection(asJson, summarizeDetection(detection, entryRelative));
return undefined;
}
if (explicit && isSupportedAspectRatio(explicit)) return explicit;
if (explicit) refuseUnsupportedAt4k(resolution, `--aspect-ratio ${explicit}`);
logDetection(asJson, `${summarizeDetection(detection, entryRelative)}; ${KEEPS_OWN_SIZE}`);
return undefined;
}
const KEEPS_OWN_SIZE = "the render keeps the composition's own size.";
const isSupportedAspectRatio = (value: string): value is SupportedAspectRatio =>
(VALID_ASPECT_RATIO as readonly string[]).includes(value);
function sameRatio(aspect: string, ratio: number): boolean {
const [w, h] = aspect.split(":").map(Number);
return Math.abs(w! / h! - ratio) <= ASPECT_RATIO_MATCH_TOLERANCE;
}
function ratioLabel(width: number, height: number): string {
if (!Number.isInteger(width) || !Number.isInteger(height)) return (width / height).toFixed(2);
const gcd = (a: number, b: number): number => (b === 0 ? a : gcd(b, a % b));
const d = gcd(width, height);
return `${width / d}:${height / d}`;
}
const PRESET_4K: Record<SupportedAspectRatio, CanvasResolution> = {
"16:9": "landscape-4k",
"9:16": "portrait-4k",
"1:1": "square-4k",
};
/** The detector matches a ratio within a tolerance; the renderer's 4K preset has to fit the exact size. */
function refuseUnfit4kPreset(detection: {
aspectRatio: SupportedAspectRatio;
width: number;
height: number;
}): void {
const preset = PRESET_4K[detection.aspectRatio];
const compat = checkOutputResolutionCompatibility({
compositionWidth: detection.width,
compositionHeight: detection.height,
outputResolution: preset,
});
if (compat.ok) return;
const exact = CANVAS_DIMENSIONS[preset];
errorBox(
"No 4K preset fits this composition",
`${detection.width}×${detection.height} cannot render at 4K as ${detection.aspectRatio}: ${compat.message}`,
`Render it at 1080p, which keeps ${detection.width}×${detection.height}, or re-author it at ${exact.width / 2}×${exact.height / 2}.`,
);
failCommand();
}
function refuseUnsupportedAt4k(
resolution: "1080p" | "4k",
subject: string,
fix = "Render at 1080p, which keeps the composition's own size.",
): void {
if (resolution !== "4k") return;
errorBox(
"No 4K preset for this aspect ratio",
`${subject} is not 16:9, 9:16 or 1:1, the only ratios a 4K cloud render can scale to.`,
fix,
);
failCommand();
}
/** `--aspect-ratio` takes any `W:H`; only 16:9, 9:16 and 1:1 are sent, the rest are checked against the composition. */
export function parseAspectRatioFlag(raw: string | undefined): string | undefined {
if (raw === undefined) return undefined;
const match = /^([1-9]\d*):([1-9]\d*)$/.exec(raw.trim());
if (match) return `${match[1]}:${match[2]}`;
errorBox("Invalid --aspect-ratio", `Got "${raw}". Use W:H, such as 16:9, 9:16, 1:1 or 2:1.`);
failUsage();
}
function logDetection(asJson: boolean, message: string): void {
if (asJson) return;
console.log(c.dim(` ${message}`));
}
// 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 `Detected aspect ratio: ${ratioLabel(detection.width, detection.height)} (from ${entryRelative} dims ${detection.width}×${detection.height}); the cloud render keeps that size`;
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,
composition: string | undefined,
): 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;
const project = resolveProject(source.dir);
const entryPath = resolvePath(project.dir, composition ?? "index.html");
const issues = validateVariablesAgainstProject(entryPath, 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[];
swappedFonts: string[];
leftOut: LeftOutReference[];
outsideFiles: OutsideFileReference[];
}
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,
includeOutsideFiles: boolean,
upload?: OffloadOptions["upload"],
variablesText?: string,
): Promise<PreparedLocalArchive> {
const project = resolveProject(source.dir);
if (!asJson) {
console.log("");
console.log(`${c.accent("◆")} Zipping ${c.accent(project.name)}`);
}
const { fileMap, entryPath, leftOut, outsideFiles } = await stageAndReport(project, composition, {
asJson,
dryRun: !upload,
includeOutsideFiles,
});
const swappedFonts = await embedSystemFonts({
dir: project.dir,
entryFile: composition,
entryPath,
fileMap,
});
if (swappedFonts.length > 0 && !asJson) console.log(c.dim(describeSwappedFonts(swappedFonts)));
const offloaded = await offloadMedia(project, fileMap, entryPath, asJson, upload, variablesText);
const { archive, sizeBytes } = zipWithinUploadLimit(fileMap);
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,
swappedFonts,
leftOut,
outsideFiles,
};
if (upload) assertArchiveFits(sizeBytes, largestFiles);
if (!asJson && sizeBytes >= ARCHIVE_DIAGNOSTIC_THRESHOLD_BYTES) {
reportLargestFiles(prepared);
}
return prepared;
}
// Media left on disk barely compresses: past the limit, its size is the report and nothing is read.
function zipWithinUploadLimit(fileMap: Map<string, StagedFile>) {
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)])));
return { archive, sizeBytes: archive?.buffer.byteLength ?? onDiskBytes };
}
function reportLeftOut(warning: string, reference: LeftOutReference, asJson: boolean): void {
if (!asJson) return console.log(c.warn(` ${warning}`));
console.error(c.warn(` ${warning}`));
console.error(JSON.stringify({ event: "left_out", ...reference }));
}
/** Asks about unapproved outside files only on a real upload a person watches; otherwise they stay out. */
async function stageAndReport(
project: ProjectDir,
composition: string | undefined,
options: { asJson: boolean; dryRun: boolean; includeOutsideFiles: boolean },
) {
const { asJson, dryRun } = options;
const { staged, outsideFiles } = await stageWithOutsideFileApproval(
project.dir,
{
includeAll: options.includeOutsideFiles,
ask: asJson || dryRun || isUnattended() ? undefined : confirmOutsideFiles,
},
(onOutsideFile) => {
const warnings: { warning: string; reference: LeftOutReference }[] = [];
const onLeftOut: OnLeftOut = (warning, reference) => warnings.push({ warning, reference });
return { ...stageProjectFiles(project, composition, onLeftOut, onOutsideFile), warnings };
},
);
for (const { warning, reference } of staged.warnings) reportLeftOut(warning, reference, asJson);
const leftOut = staged.warnings.map(({ reference }) => reference);
trackUploadLeftOut("cloud_render", leftOut, dryRun);
listOutsideFiles(outsideFiles, asJson);
return { fileMap: staged.fileMap, entryPath: staged.entryPath, leftOut, outsideFiles };
}
function listOutsideFiles(outsideFiles: OutsideFileReference[], asJson: boolean): void {
if (outsideFiles.length === 0) return;
if (!asJson) return console.log(c.dim(indentLines(outsideFilesNotice(outsideFiles))));
for (const reference of outsideFiles) {
console.error(JSON.stringify({ event: "outside_file", ...reference }));
}
}
const indentLines = (text: string) => text.replace(/^/gm, " ");
function stageProjectFiles(
project: ProjectDir,
composition: string | undefined,
onLeftOut: OnLeftOut,
onOutsideFile: OnOutsideFile,
): { fileMap: Map<string, StagedFile>; entryPath: string } {
try {
const entryPath = archiveKey(
relative(project.dir, resolvePath(project.dir, composition ?? "index.html")).replaceAll(
"\\",
"/",
),
);
const fileMap = stagePublishFiles(
project.dir,
OFFLOAD_MIN_BYTES,
onLeftOut,
onOutsideFile,
entryPath,
);
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"],
variablesText?: string,
): Promise<OffloadedMedia[]> {
let offloaded: OffloadedMedia[];
try {
offloaded = await offloadHeavyMedia(project.dir, fileMap, {
apiBaseUrl: resolveCloudBaseUrl(),
upload,
entryPath,
variablesText,
zipBudgetBytes: ZIP_BUDGET_BYTES_WITH_ROOM_FOR_ZIP_RECORDS,
onFile: (item) =>
(asJson ? console.error : console.log)(c.dim(` ${describeOffload(item, !upload)}`)),
onReencodeProgress: asJson ? reencodeProgressLines() : undefined,
});
} 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;
}
/** --fps, else the entry's root data-fps (the owner local render uses), else the server default. */
export function resolveCloudFpsArg(
source: ProjectInputSource,
fps: string | undefined,
composition: string | undefined,
): string | undefined {
if (source.kind !== "dir") return fps;
const { dir } = resolveProject(source.dir);
const resolved = resolveDefaultFpsArg(fps, dir, resolvePath(dir, "index.html"), composition);
// The cloud API takes whole frame rates; a fractional data-fps (29.97) leaves it to the server.
return resolved !== undefined && /^\d+$/.test(resolved) ? resolved : fps;
}
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();
}
/** Under --json, a line on stderr per whole percent a re-encode makes (per second when its length is unknown),
* so a caller can tell a long encode from a dead one. */
export function reencodeProgressLines(
now: () => number = Date.now,
): NonNullable<OffloadOptions["onReencodeProgress"]> {
let last = { path: "", percent: -1, at: 0 };
return ({ path, doneSeconds, totalSeconds }) => {
const percent = totalSeconds
? Math.min(100, Math.floor((doneSeconds / totalSeconds) * 100))
: null;
const at = now();
const same = path === last.path;
if (same && (percent === null ? at - last.at < 1000 : percent === last.percent)) return;
last = { path, percent: percent ?? -1, at };
console.error(
JSON.stringify({
event: "reencode_progress",
file: path,
percent,
done_seconds: Math.round(doneSeconds * 10) / 10,
total_seconds: totalSeconds === null ? null : Math.round(totalSeconds * 10) / 10,
}),
);
};
}
/** A line per PUT progress event: JSON on stderr under --json, so a caller can tell a slow upload from a dead one. */
function reportUploadProgress(name: string, asJson: boolean): (event: UploadProgressEvent) => void {
return (event) => {
if (event.phase !== "upload" || event.sentBytes === undefined) return;
const { percent, sentBytes, totalBytes, attempt = 1 } = event;
if (asJson) {
console.error(
JSON.stringify({
event: "upload_progress",
file: name,
attempt,
percent,
sent_bytes: sentBytes,
total_bytes: totalBytes,
}),
);
} else {
const retry = attempt > 1 ? ` (try ${attempt}, from the first byte)` : "";
console.log(
c.dim(
` ${name}: ${percent}% · ${formatBytes(sentBytes)} of ${formatBytes(totalBytes ?? 0)}${retry}`,
),
);
}
};
}
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,
swapped_fonts: prepared.swappedFonts,
left_out: prepared.leftOut,
outside_files: prepared.outsideFiles,
},
}),
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: (ev) => {
reportUploadProgress(`${project.name}.zip`, asJson)(ev);
if (asJson) return;
if (ev.phase === "initialize") {
console.log(c.dim(` initializing…`));
} else if (ev.phase === "upload" && ev.percent === 0 && ev.attempt === undefined) {
console.log(c.dim(` uploading to S3…`));
} else if (ev.phase === "complete") {
console.log(c.dim(` finalizing…`));
}
},
});
} 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;
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;
reverseSessionId: string | undefined;
}
type RenderRequestBody = CreateHyperframesRenderRequest & { reverse_session_id?: string };
function reverseSessionIdOf(project: ProjectInputSource): string | undefined {
return project.kind === "dir"
? readProjectConfig(project.dir ?? ".")?.reverseSessionId
: 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): RenderRequestBody {
const body: RenderRequestBody = { 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.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;
if (opts.reverseSessionId !== undefined) body.reverse_session_id = opts.reverseSessionId;
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 = "";
let logged = { status: "", at: 0 };
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 (logsTick(detail.status, elapsedMs, logged)) {
// Non-TTY: a line per status change and one a minute while it holds, no carriage returns.
console.log(` ${formatTickLine(detail, elapsedMs)}`);
lastStatus = detail.status;
logged = { status: detail.status, at: elapsedMs };
}
},
});
} 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");
}
}
const STILL_RUNNING_EVERY_MS = 60_000;
export function logsTick(
status: string,
elapsedMs: number,
logged: { status: string; at: number },
): boolean {
return status !== logged.status || elapsedMs - logged.at >= STILL_RUNNING_EVERY_MS;
}
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,
projectDir?: string,
): never {
if (asJson) {
console.log(JSON.stringify(withMeta({ render: detail }), null, 2));
failCommand();
}
const fontUse =
projectDir && detail.failure_message
? describeUnresolvedFontUse(detail.failure_message, projectDir)
: undefined;
errorBox(
"Render failed",
[detail.failure_message ?? "(no failure_message returned)", fontUse].filter(Boolean).join("\n"),
`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();
}
}