Skip to content

Commit 1d8c3d1

Browse files
committed
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.
1 parent 1158d68 commit 1d8c3d1

5 files changed

Lines changed: 279 additions & 51 deletions

File tree

‎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-
Media files of 5 MB or more upload as HeyGen assets and are referenced by 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. Inspect what will upload 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. Inspect what will upload before starting a render:
6363

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

‎docs/packages/cli.mdx‎

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1797,20 +1797,22 @@ match. Those rules use gitignore syntax and apply to `hyperframes publish` too.
17971797
Keep them narrow — a dynamically selected asset may have no static reference to
17981798
protect it.
17991799

1800-
Media files of 5 MB or more go up as HeyGen assets before zipping, and the
1801-
zip's copy of each HTML, CSS, script and JSON file points at the asset URL
1802-
instead; your project files are not changed. Uploads are cached by content, so
1803-
a re-render uploads only what changed. Media the asset API does not take as is
1804-
is converted on your machine first, which needs ffmpeg: video (for example MKV,
1805-
or over 200 MB) and audio (for example FLAC or M4A) at visually lossless
1806-
quality, still images such as AVIF to PNG, and animated GIFs in the entry
1807-
composition to the same seekable video the renderer makes from them. A video or audio file that has to be re-encoded is first cut to the
1808-
parts the entry composition plays (plus half a second either side), and the
1809-
composition's media starts shift to match, so a long source fits. Media inside
1810-
sub-compositions, looping clips and files a script names keep their full
1811-
length. A file a
1812-
script reaches by building its path, rather than naming it in a plain string,
1813-
also stays in the zip, as do animated GIFs inside sub-compositions.
1800+
Media files of 5 MB or more that the project names by path go up as HeyGen
1801+
assets before zipping, and the zip's copy of each HTML, CSS, script and JSON
1802+
file points at the asset URL instead; your project files are not changed.
1803+
Asset URLs are public and unsigned: anyone who has one can fetch the
1804+
media. Uploads are cached by content, so a re-render uploads only what changed.
1805+
Media the asset API does not take as is is converted on your machine first,
1806+
which needs ffmpeg: video (for example MKV, or over 200 MB) and audio (for
1807+
example FLAC or M4A) at visually lossless quality, still images such as AVIF to
1808+
PNG, and animated GIFs of 5 MB or more in the entry composition to the same
1809+
seekable video the renderer makes from them. A video or audio file that has to
1810+
be re-encoded is first cut to the parts the entry composition plays (plus half
1811+
a second either side), and the composition's media starts shift to match, so a
1812+
long source fits. Media inside sub-compositions, looping clips, clips with
1813+
`data-var-src` and files a script names keep their full length. A file no
1814+
plain string names, such as one a script builds a path to or one picked through
1815+
`--variables`, stays in the zip, as do animated GIFs inside sub-compositions.
18141816

18151817
The zip has to come in under 200 MB — the direct-upload cap — or the command
18161818
stops before uploading it and names the largest files left. Use `--dry-run`

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

Lines changed: 198 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,10 @@ function fakeHead(status: number, size: number): typeof fetch {
4949
) as unknown as typeof fetch;
5050
}
5151

52+
// Encoders read a temp snapshot of the staged bytes, never the project file.
53+
const staged = (name: string) =>
54+
expect.stringMatching(new RegExp(`hf-offload-src-[^/\\\\]+[/\\\\]${name}$`));
55+
5256
const html = (body: string) => `<!doctype html><html><head></head><body>${body}</body></html>`;
5357

5458
describe("offloadHeavyMedia", () => {
@@ -58,7 +62,7 @@ describe("offloadHeavyMedia", () => {
5862
`<video src="media/clip.mp4" poster="media/bg.png"><source src="./media/clip.mp4" /></video>` +
5963
`<img srcset="media/bg.png 1x, media/small.png 2x" />` +
6064
`<div style="background-image: url(media/bg.png)"></div>` +
61-
`<audio src="/media/voice.mp3"></audio>` +
65+
`<audio src="/media/voice.mp3#t=2"></audio>` +
6266
`<div data-composition-src="compositions/scene.html"></div>`,
6367
);
6468
const dir = project({
@@ -94,7 +98,7 @@ describe("offloadHeavyMedia", () => {
9498
expect(index).toContain(`<source src="${url("media/clip.mp4")}"`);
9599
expect(index).toContain(`srcset="${url("media/bg.png")} 1x, media/small.png 2x"`);
96100
expect(index).toContain(`url(${url("media/bg.png")})`);
97-
expect(index).toContain(`<audio src="${url("media/voice.mp3")}"`);
101+
expect(index).toContain(`<audio src="${url("media/voice.mp3")}#t=2"`);
98102
const scene = fileMap.get("compositions/scene.html")!.toString();
99103
expect(scene).toContain(`<video src="${url("media/clip.mp4")}"`);
100104
expect(scene).toContain(`<img src="${url("media/bg.png")}"`);
@@ -135,6 +139,23 @@ describe("offloadHeavyMedia", () => {
135139
expect(second.get("index.html")!.toString()).toContain("https://assets.example/1/clip.mp4");
136140
});
137141

142+
it("treats a cache file holding null as empty", async () => {
143+
const dir = project({
144+
"index.html": html(`<video src="clip.mp4"></video>`),
145+
"clip.mp4": HEAVY,
146+
});
147+
const cache = cachePath();
148+
writeFileSync(cache, "null");
149+
150+
await expect(
151+
offloadHeavyMedia(dir, buildPublishFileMap(dir), {
152+
apiBaseUrl: "https://api.example",
153+
upload: fakeUpload(),
154+
cachePath: cache,
155+
}),
156+
).resolves.toHaveLength(1);
157+
});
158+
138159
it("uploads again when the cached asset URL no longer serves the file", async () => {
139160
const dir = project({
140161
"index.html": html(`<video src="clip.mp4"></video>`),
@@ -151,8 +172,13 @@ describe("offloadHeavyMedia", () => {
151172
...opts,
152173
fetchImpl: fakeHead(404, 0),
153174
});
175+
// Served, but not the size uploaded: the asset was replaced.
176+
await offloadHeavyMedia(dir, buildPublishFileMap(dir), {
177+
...opts,
178+
fetchImpl: fakeHead(200, HEAVY.byteLength - 1),
179+
});
154180

155-
expect(opts.upload).toHaveBeenCalledTimes(2);
181+
expect(opts.upload).toHaveBeenCalledTimes(3);
156182
expect(report[0]).toMatchObject({ action: "upload", url: "https://assets.example/2/clip.mp4" });
157183
});
158184

@@ -179,7 +205,7 @@ describe("offloadHeavyMedia", () => {
179205
cachePath: cachePath(),
180206
});
181207

182-
expect(reencoder.run).toHaveBeenCalledWith(join(dir, "take.mkv"), "video", undefined);
208+
expect(reencoder.run).toHaveBeenCalledWith(staged("take.mkv"), "video", undefined);
183209
expect(upload.mock.calls[0]![0]).toMatchObject({
184210
filename: "take.mp4",
185211
contentType: "video/mp4",
@@ -241,9 +267,7 @@ describe("offloadHeavyMedia", () => {
241267
expect(index).toContain(`video.src = \`${url("media/clip.mp4")}\``);
242268
expect(fileMap.get("main.js")!.toString()).toContain(`new Audio("${url("music.mp3")}")`);
243269
expect(fileMap.get("data/cues.json")!.toString()).toBe(`{"track": "${url("music.mp3")}"}`);
244-
expect(report.find((item) => item.path === "voice.mp3")).toMatchObject({
245-
kept_in_archive: true,
246-
});
270+
expect(report.find((item) => item.path === "voice.mp3")).toBeUndefined();
247271
expect(fileMap.has("voice.mp3")).toBe(true);
248272
expect(fileMap.has("music.mp3")).toBe(false);
249273
expect(fileMap.has("media/clip.mp4")).toBe(false);
@@ -324,6 +348,65 @@ describe("offloadHeavyMedia", () => {
324348
expect(fileMap.has("media/other.gif")).toBe(true);
325349
});
326350

351+
it("prepares a nested entry's GIF from the file next to it, as the renderer resolves it", async () => {
352+
const nested = Buffer.alloc(OFFLOAD_MIN_BYTES, 2);
353+
const dir = project({
354+
"index.html": html(""),
355+
"compositions/scene.html": html(`<img src="logo.gif" />`),
356+
"compositions/logo.gif": nested,
357+
"logo.gif": HEAVY,
358+
});
359+
let prepared: Buffer | undefined;
360+
const gifPrep = vi.fn<GifPrep>(async (input, options) => {
361+
prepared = readFileSync(options.sourceAssets!.get("logo.gif")!);
362+
const outputPath = join(options.outputDir, "hfgif-v1-abc.webm");
363+
writeFileSync(outputPath, HEAVY);
364+
return {
365+
html: input.replace(
366+
`<img src="logo.gif" />`,
367+
`<video src="../_animated_gif/hfgif-v1-abc.webm"></video>`,
368+
),
369+
preparedGifs: [{ sourceSrc: "logo.gif", outputPath }],
370+
};
371+
});
372+
const fileMap = buildPublishFileMap(dir);
373+
374+
await offloadHeavyMedia(dir, fileMap, {
375+
apiBaseUrl: "https://api.example",
376+
entryPath: "compositions/scene.html",
377+
upload: fakeUpload(),
378+
gifPrep,
379+
cachePath: cachePath(),
380+
});
381+
382+
expect(prepared?.equals(nested)).toBe(true);
383+
expect(fileMap.has("compositions/logo.gif")).toBe(false);
384+
expect(fileMap.has("logo.gif")).toBe(true);
385+
});
386+
387+
it("re-encodes the staged bytes, not a file saved on disk after staging", async () => {
388+
const dir = project({
389+
"index.html": html(`<audio src="voice.flac"></audio>`),
390+
"voice.flac": HEAVY,
391+
});
392+
const fileMap = buildPublishFileMap(dir);
393+
writeFileSync(join(dir, "voice.flac"), Buffer.alloc(OFFLOAD_MIN_BYTES, 9));
394+
let encoded: Buffer | undefined;
395+
const run = vi.fn(async (sourcePath: string) => {
396+
encoded = readFileSync(sourcePath);
397+
return { bytes: Buffer.from("wav"), filename: "voice.wav", contentType: "audio/wav" };
398+
});
399+
400+
await offloadHeavyMedia(dir, fileMap, {
401+
apiBaseUrl: "https://api.example",
402+
upload: fakeUpload(),
403+
reencoder: { choose: async () => "audio", run },
404+
cachePath: cachePath(),
405+
});
406+
407+
expect(encoded?.equals(HEAVY)).toBe(true);
408+
});
409+
327410
it("cuts a re-encoded video to the windows its clips play and shifts their starts to match", async () => {
328411
const dir = project({
329412
"index.html": html(
@@ -346,7 +429,7 @@ describe("offloadHeavyMedia", () => {
346429
cachePath: cachePath(),
347430
});
348431

349-
expect(run).toHaveBeenCalledWith(join(dir, "long.mkv"), "video", [
432+
expect(run).toHaveBeenCalledWith(staged("long.mkv"), "video", [
350433
{ start: 9.5, end: 12.5 },
351434
{ start: 100, end: 105 },
352435
]);
@@ -356,6 +439,38 @@ describe("offloadHeavyMedia", () => {
356439
expect(index).toMatch(/id="b"[^>]*data-media-start="3.5"/);
357440
});
358441

442+
it("cuts on the source's own frames at 29.97 fps and re-encodes when the cut changes", async () => {
443+
const clip = (start: number) =>
444+
html(`<video src="long.mkv" data-duration="2" data-media-start="${start}"></video>`);
445+
const dir = project({ "index.html": clip(10), "long.mkv": HEAVY });
446+
const fps = 30000 / 1001;
447+
const run = vi.fn(async () => ({
448+
bytes: Buffer.from("cut"),
449+
filename: "long.mp4",
450+
contentType: "video/mp4",
451+
}));
452+
const opts = {
453+
apiBaseUrl: "https://api.example",
454+
upload: fakeUpload(),
455+
reencoder: { choose: async () => "video" as const, trimGrid: async () => fps, run },
456+
// Any cached URL is still served, so only the key decides reuse.
457+
fetchImpl: fakeHead(200, 3),
458+
cachePath: cachePath(),
459+
};
460+
461+
await offloadHeavyMedia(dir, buildPublishFileMap(dir), opts);
462+
writeFileSync(join(dir, "index.html"), clip(20));
463+
await offloadHeavyMedia(dir, buildPublishFileMap(dir), opts);
464+
await offloadHeavyMedia(dir, buildPublishFileMap(dir), opts);
465+
466+
expect(run).toHaveBeenCalledTimes(2);
467+
const calls = run.mock.calls as unknown as Array<[string, string, Array<{ start: number }>]>;
468+
for (const [, , segments] of calls) {
469+
const frames = segments[0]!.start * fps;
470+
expect(Math.abs(frames - Math.round(frames))).toBeLessThan(1e-6);
471+
}
472+
});
473+
359474
it("keeps the whole file when a use is not a bounded clip or a script names it", async () => {
360475
const looped = project({
361476
"index.html": html(
@@ -368,7 +483,53 @@ describe("offloadHeavyMedia", () => {
368483
"main.js": "const name = `long.mkv`.replace('.mkv', '');",
369484
"long.mkv": HEAVY,
370485
});
371-
for (const dir of [looped, scripted]) {
486+
const variableBound = project({
487+
"index.html": html(
488+
`<video data-var-src="clip" src="long.mkv" data-duration="2" data-media-start="10"></video>`,
489+
),
490+
"long.mkv": HEAVY,
491+
});
492+
const fragment = project({
493+
"index.html": html(
494+
`<video src="long.mkv#t=10,12" data-duration="2" data-media-start="10"></video>`,
495+
),
496+
"long.mkv": HEAVY,
497+
});
498+
const automated = project({
499+
"index.html": html(
500+
`<video src="long.mkv" data-duration="2" data-media-start="10" data-automation="x"></video>`,
501+
),
502+
"long.mkv": HEAVY,
503+
});
504+
const offsetParent = project({
505+
"index.html": html(
506+
`<div data-media-start="3"><video src="long.mkv" data-duration="2" data-media-start="10"></video></div>`,
507+
),
508+
"long.mkv": HEAVY,
509+
});
510+
const nested = project({
511+
"index.html": html(
512+
`<div data-composition-id="root"><div data-composition-id="inner">` +
513+
`<video src="long.mkv" data-duration="2" data-media-start="10"></video></div></div>`,
514+
),
515+
"long.mkv": HEAVY,
516+
});
517+
const namedInPage = project({
518+
"index.html": html(
519+
`<video src="long.mkv" data-duration="2" data-media-start="10"></video><p data-note="long.mkv"></p>`,
520+
),
521+
"long.mkv": HEAVY,
522+
});
523+
for (const dir of [
524+
looped,
525+
scripted,
526+
variableBound,
527+
fragment,
528+
automated,
529+
offsetParent,
530+
nested,
531+
namedInPage,
532+
]) {
372533
const run = vi.fn(async () => ({
373534
bytes: Buffer.from("full"),
374535
filename: "long.mp4",
@@ -381,11 +542,31 @@ describe("offloadHeavyMedia", () => {
381542
reencoder: { choose: async () => "video", trimGrid: async () => 30, run },
382543
cachePath: cachePath(),
383544
});
384-
expect(run).toHaveBeenCalledWith(join(dir, "long.mkv"), "video", undefined);
545+
expect(run).toHaveBeenCalledWith(staged("long.mkv"), "video", undefined);
385546
expect(fileMap.get("index.html")!.toString()).toContain(`data-media-start="10"`);
386547
}
387548
});
388549

550+
it("keeps a heavy file no reference names in the zip, since --variables can pick it at render time", async () => {
551+
const dir = project({
552+
"index.html": html(`<video data-var-src="clip" src="media/a.mp4"></video>`),
553+
"media/a.mp4": HEAVY,
554+
"media/b.mp4": HEAVY,
555+
});
556+
const fileMap = buildPublishFileMap(dir);
557+
const upload = fakeUpload();
558+
559+
const report = await offloadHeavyMedia(dir, fileMap, {
560+
apiBaseUrl: "https://api.example",
561+
upload,
562+
cachePath: cachePath(),
563+
});
564+
565+
expect(report.map((item) => item.path)).toEqual(["media/a.mp4"]);
566+
expect(upload).toHaveBeenCalledTimes(1);
567+
expect(fileMap.has("media/b.mp4")).toBe(true);
568+
});
569+
389570
it("never decodes a media file as text, since one can exceed the longest string allowed", async () => {
390571
const dir = project({
391572
"index.html": html(`<video src="clip.mp4"></video>`),
@@ -409,20 +590,26 @@ describe("offloadHeavyMedia", () => {
409590

410591
it("leaves small media and remote URLs alone", async () => {
411592
const dir = project({
412-
"index.html": html(`<img src="logo.png" /><video src="https://cdn.example/a.mp4"></video>`),
593+
"index.html": html(
594+
`<img src="logo.png" /><img src="spin.gif" /><video src="https://cdn.example/a.mp4"></video>`,
595+
),
413596
"logo.png": "small",
597+
"spin.gif": "small",
414598
});
415599
const fileMap = buildPublishFileMap(dir);
416600
const upload = fakeUpload();
601+
const gifPrep = vi.fn<GifPrep>();
417602

418603
const report = await offloadHeavyMedia(dir, fileMap, {
419604
apiBaseUrl: "https://api.example",
420605
upload,
606+
gifPrep,
421607
cachePath: cachePath(),
422608
});
423609

424610
expect(report).toEqual([]);
425611
expect(upload).not.toHaveBeenCalled();
612+
expect(gifPrep).not.toHaveBeenCalled();
426613
expect(fileMap.has("logo.png")).toBe(true);
427614
});
428615
});

0 commit comments

Comments
 (0)