Skip to content

Commit b306438

Browse files
feat(cli): cloud render uploads heavy media as HeyGen assets (#5931)
* feat(cli): cloud render uploads heavy media as HeyGen assets Media of 5 MB or more leaves the project zip: it uploads through the direct-upload flow as a HeyGen asset and the zip's HTML and CSS point at the asset URL. Uploads are cached by content hash and re-checked before reuse. Media the asset API refuses or caps is re-encoded at visually lossless quality first. The zip must end under 200 MB or the command stops and names the largest files left. * feat(cli): cloud render offloads GIFs, still images and script-referenced media Animated GIFs in the entry composition go through the renderer's own GIF preparation and upload as the resulting video. Still AVIF, GIF, BMP and TIFF images convert to PNG. Plain string literals in scripts and JSON that name offloaded media point at the asset URL. ffprobe calls end their options with "--", and two comment lines are trimmed for the ratchet. * feat(cli): cloud render uploads only the parts of long media a composition plays A video or audio file that has to be re-encoded is cut to the union of the windows its clips play, with half a second of margin on the source's frame grid, and the staged composition's media starts shift to match. Clips in sub-compositions, looping clips, speed ramps and files a script names keep the full file. * fix(cli): cloud render no longer decodes media files as text when rewriting references * fix(cli): cloud render keeps media chosen at render time and encodes the staged bytes Only media a reference points at is offloaded, so a file picked through --variables or built by a script stays in the zip. Variable-bound clips and clips with a media fragment keep their full length. Entry GIFs resolve the way the renderer rebases a nested entry and are prepared only from 5 MB, and every encode reads the staged bytes its cache key hashes. Query strings and media fragments survive the rewrite, a null cache file reads as empty, and the docs say asset URLs are public and unsigned. * fix(cli): cloud render comments cite only what this repo holds * fix(cli): cloud render handles media over 2 GiB and explains a too-large upload Media of 5 MB or more stays on disk until it is used: it is hashed and uploaded as a stream, and a file edited after staging stops the run instead of caching the wrong upload. Files left in the zip are sized before any is read, so a 4 GB file reports "too large" instead of crashing. The asset API rejects an over-limit upload as invalid_parameter with "File too large"; that now gets the dry-run hint instead of the --help one. * fix(cli): cloud render checks and reads each staged file through one handle Staging, the on-disk staged read and the re-encoded output read each opened the path twice: once to stat, once to read. A file swapped or edited between the two could be read without the size or change check seeing it. Each now opens once, checks the open file's stat before and after the read, and reads from it. * test(cli): a heavy file a script builds from split strings stays in the cloud render zip * fix(cli): cloud render keeps media scripts may reach and never trims clips scripts retime - An offloaded file keeps its zip copy when script code holds both its stem and extension, so a path joined at runtime still loads. - Entry GIFs are prepared from a private copy checked against the staged file, so the GIF cache never stores a later edit. - No cut when any script can write a clip's timing attributes, dataset, currentTime, playbackRate, src or loop.
1 parent eec3c51 commit b306438

15 files changed

Lines changed: 2432 additions & 94 deletions

File tree

‎.fallowrc.jsonc‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
"packages/studio/src/components/ui/index.ts",
66
"packages/producer/src/**/*.test.ts",
77
// Studio's browser-journey helpers are plain .mjs under tests/e2e; their unit tests live beside them.
8-
"packages/studio/tests/e2e/*.test.mjs",
8+
"packages/studio/tests/e2e/**/*.test.mjs",
99
"packages/aws-lambda/src/**/*.test.ts",
1010
"packages/gcp-cloud-run/src/**/*.test.ts",
1111
"packages/gcp-cloud-run/terraform/*.test.ts",
@@ -67,7 +67,7 @@
6767
// Test fixture worker, spawned by path via the pools' workerEntryPath
6868
// option from the crash-recovery tests; has no import-graph referrer.
6969
"packages/producer/src/services/__fixtures__/crashOnMessageWorker.mjs",
70-
"scripts/*.{ts,mjs,js}",
70+
"scripts/**/*.{ts,mjs,js}",
7171
"scripts/*/run.mjs",
7272
// Keyframe UI components — wired dynamically via EaseCurveSection/MotionPanel.
7373
"packages/studio/src/components/editor/KeyframeDiamond.tsx",
@@ -255,7 +255,7 @@
255255
// CLI command files: every command exports a const `examples` per the
256256
// convention documented in CLAUDE.md. This is a namespace barrel, not a
257257
// collision.
258-
{ "file": "packages/cli/src/commands/*.ts", "exports": ["examples"] },
258+
{ "file": "packages/cli/src/commands/**/*.ts", "exports": ["examples"] },
259259
// Options type for the render-queue hook's public startRender callback —
260260
// consumed structurally by callers (StudioRightPanels), not by import.
261261
{

‎docs/deploy/cloud.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ hyperframes cloud render --resolution 4k
5959

6060
## Check what will upload
6161

62-
Cloud project archives have a 200 MB limit. Inspect the archive before starting a render:
62+
Media files of 5 MB or more that the project names by path upload as HeyGen assets and are referenced by public, unsigned URL, so large footage and audio do not count against the 200 MB project archive limit. Uploads are cached, so re-rendering uploads only new or changed media. Media is streamed from disk as it uploads, so a large file never has to fit in memory; editing one while the command is preparing it stops the run. Inspect what will upload before starting a render:
6363

6464
```bash
6565
hyperframes cloud render --dry-run

‎docs/packages/cli.mdx‎

Lines changed: 21 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1803,11 +1803,28 @@ match. Those rules use gitignore syntax and apply to `hyperframes publish` too.
18031803
Keep them narrow — a dynamically selected asset may have no static reference to
18041804
protect it.
18051805

1806-
The zip has to come in under 200 MB — the direct-upload cap. Use `--dry-run`
1807-
first to see the compressed size and the largest included files, without
1806+
Media files of 5 MB or more that the project names by path go up as HeyGen
1807+
assets before zipping, and the zip's copy of each HTML, CSS, script and JSON
1808+
file points at the asset URL instead; your project files are not changed.
1809+
Asset URLs are public and unsigned: anyone who has one can fetch the
1810+
media. Uploads are cached by content, so a re-render uploads only what changed.
1811+
Media the asset API does not take as is is converted on your machine first,
1812+
which needs ffmpeg: video (for example MKV, or over 200 MB) and audio (for
1813+
example FLAC or M4A) at visually lossless quality, still images such as AVIF to
1814+
PNG, and animated GIFs of 5 MB or more in the entry composition to the same
1815+
seekable video the renderer makes from them. A video or audio file that has to
1816+
be re-encoded is first cut to the parts the entry composition plays (plus half
1817+
a second either side), and the composition's media starts shift to match, so a
1818+
long source fits. Media inside sub-compositions, looping clips, clips with
1819+
`data-var-src` and files a script names keep their full length. A file no
1820+
plain string names, such as one a script builds a path to or one picked through
1821+
`--variables`, stays in the zip, as do animated GIFs inside sub-compositions.
1822+
1823+
The zip has to come in under 200 MB — the direct-upload cap — or the command
1824+
stops before uploading it and names the largest files left. Use `--dry-run`
1825+
first to see which media would upload and the compressed size, without
18081826
authenticating, uploading, or starting anything. If you are over, add only
1809-
paths you have verified are unneeded to `.hyperframesignore`, or pre-host the
1810-
large media and reference it by URL.
1827+
paths you have verified are unneeded to `.hyperframesignore`.
18111828

18121829
Render parameters mirror local `hyperframes render` where they overlap:
18131830

‎packages/cli/src/cloud/errors.test.ts‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,21 @@ describe("cloud/errors reportApiError", () => {
4949
expect(errorBox).toHaveBeenCalledWith(
5050
"Upload failed (HTTP 413)",
5151
"project too large",
52-
"The zip exceeded the 200 MB limit. Run `hyperframes cloud render --dry-run`, then add only verified-unneeded paths to `.hyperframesignore` or pre-host required large media.",
52+
"The zip exceeded the 200 MB limit. Run `hyperframes cloud render --dry-run` to see what stays in it, then add only verified-unneeded paths to `.hyperframesignore`.",
53+
);
54+
});
55+
56+
it("points an upload the server refuses as too large to dry-run, not to --help", () => {
57+
const err = new HyperframesApiError({
58+
status: 400,
59+
message: "File too large. Maximum is 200 MiB.",
60+
code: "invalid_parameter",
61+
});
62+
expect(() => reportApiError("Upload failed", err)).toThrow(CliRuntimeError);
63+
expect(errorBox).toHaveBeenCalledWith(
64+
"Upload failed (HTTP 400)",
65+
"File too large. Maximum is 200 MiB.",
66+
expect.stringContaining("hyperframes cloud render --dry-run"),
5367
);
5468
});
5569

‎packages/cli/src/cloud/errors.ts‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ import { HyperframesApiError } from "./_gen/client.js";
2020
*/
2121
const ERROR_CODE_HINTS: Record<string, string> = {
2222
hyperframes_project_too_large:
23-
"The zip exceeded the 200 MB limit. Run `hyperframes cloud render --dry-run`, then add only verified-unneeded paths to `.hyperframesignore` or pre-host required large media.",
23+
"The zip exceeded the 200 MB limit. Run `hyperframes cloud render --dry-run` to see what stays in it, then add only verified-unneeded paths to `.hyperframesignore`.",
2424
hyperframes_render_not_found:
2525
"The render_id no longer exists — either soft-deleted or never created.",
2626
invalid_parameter:
@@ -30,6 +30,14 @@ const ERROR_CODE_HINTS: Record<string, string> = {
3030
rate_limit_exceeded: "Retry after the duration in the Retry-After header.",
3131
};
3232

33+
// The asset upload API reports an over-limit file as invalid_parameter; only its message says why.
34+
function hintCode(err: HyperframesApiError): string | undefined {
35+
if (err.code === "invalid_parameter" && /^File too large\b/.test(err.message)) {
36+
return "hyperframes_project_too_large";
37+
}
38+
return err.code;
39+
}
40+
3341
/**
3442
* Print an errorBox and `process.exit(1)` for any unknown error from
3543
* the cloud subverbs. The `stage` is the human-readable name of the
@@ -64,7 +72,8 @@ export function reportApiError(
6472
errorBox("Not found", options.notFound);
6573
failCommand();
6674
}
67-
const hint = err.code ? hints[err.code] : undefined;
75+
const code = hintCode(err);
76+
const hint = code ? hints[code] : undefined;
6877
const title = `${stage} (HTTP ${err.status})`;
6978
// Priority: code-specific hint > caller suggestion > bare code
7079
// label > no third line. Code-specific hints win because they

0 commit comments

Comments
 (0)