mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 16:08:56 +00:00
* 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
1259 lines
46 KiB
TypeScript
1259 lines
46 KiB
TypeScript
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();
|
||
}
|
||
}
|