Skip to content

Commit ca35227

Browse files
vanceingallsVia
andcommitted
feat(cli): surface extract-cache dir in doctor + add --frames-cache-dir sugar
Windows users with the OS temp dir on a small system drive have hit C: exhaustion mid-render (Slack ts=1784219488 · CLI v0.7.58 · win32 15 GB / 8-core, ~5500 frames). The engine already honors HYPERFRAMES_EXTRACT_CACHE_DIR for relocation, but the knob was undocumented and invisible in diagnostics — the reporter had to piece together a 4-flag compound workaround including EXTRACT_CACHE_DIR=off. Changes: - Extract the env-var resolver into a public engine API (resolveExtractCacheDir, defaultExtractCacheDir, EXTRACT_CACHE_DIR_DISABLED_ALIASES) with a typed resolution shape distinguishing "disabled by user" vs "default" vs "env override". - Add a Frames-cache check to `hyperframes doctor` that reports the effective directory, its free space, source (env or default), and fails with a relocation hint when <2 GB free at that mount. - Add `hyperframes render --frames-cache-dir <path>` as discoverable CLI sugar for the env var, including the opt-out aliases (off/none/false/0) and CWD-safe absolute-path resolution. - Document the flag in docs/packages/cli.mdx with the field-signal citation, and add a render example row for the Windows workflow. - Cover both surfaces with unit tests (6 doctor cases + 4 engine cases including all disabled-alias variants). Refs Slack #hyperframes-cli-feedback ts=1784219488 (win32 v0.7.58). Co-authored-by: Via <via-heygen[bot]@users.noreply.github.com>
1 parent 3bb26b0 commit ca35227

7 files changed

Lines changed: 289 additions & 19 deletions

File tree

‎docs/packages/cli.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -720,6 +720,7 @@ Word-level transcripts (whisper output) are grouped into readable caption cues o
720720
| `--strict-variables` | — | off | Fail render if any `--variables` key is undeclared or has a wrong type vs the composition's `data-composition-variables`. Without this flag, mismatches print as warnings and the render continues. |
721721
| `--browser-timeout` | seconds (0.001–86400) | 60 | Puppeteer page-navigation timeout for the entry HTML. Increase when heavy compositions (many videos, fonts, or asset requests) cannot reach `domcontentloaded` within the default 60 s. The flag takes **seconds**; the env fallback `PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS` takes **milliseconds**. This controls `page.goto` only — very heavy compositions may also need `PRODUCER_PUPPETEER_PROTOCOL_TIMEOUT_MS` and/or `PRODUCER_PLAYER_READY_TIMEOUT_MS` bumped (post-navigation `window.__hf` readiness has its own 45 s budget). |
722722
| `--protocol-timeout` | milliseconds (≥ 1000) | 300000 (5 min) | Puppeteer CDP protocol timeout — the per-call budget for `Runtime.callFunctionOn` seek/paint, `Page.captureScreenshot`, and other CDP round-trips. Raise on RAM-pressured hosts (≤ 8 GB), heavy-asset compositions (many videos + images), or when the render fails with `Runtime.callFunctionOn timed out` / `Target closed`. The default is auto-scaled per composition by output pixel area (a 4K comp bumps the ceiling proportionally, capped at 30 min); an explicit override sets the floor and disables scaling below it. Env fallback `PRODUCER_PUPPETEER_PROTOCOL_TIMEOUT_MS` (also **milliseconds**). |
723+
| `--frames-cache-dir` | path or `off` / `none` / `false` / `0` | `<tmpdir>/hyperframes-extract-cache-<uid>` | Directory for the content-addressed extracted-frame cache. Relocate it off the system drive when the OS temp directory lives on a small partition — long renders can accumulate multi-GB of frames, and on Windows `%TEMP%` defaults to `C:` (reporter `ts=1784219488`, CLI 0.7.58, 15 GB laptop: extract cache exhausted C: mid-render). Pass an opt-out alias (`off`, `none`, `false`, `0`) to disable caching entirely; frames then extract into the render's `workDir` and are cleaned up when the render ends. Env fallback `HYPERFRAMES_EXTRACT_CACHE_DIR`. `hyperframes doctor` reports the effective directory + free space at that location. |
723724

724725
CRF and target bitrate default to the `--quality` preset. Use `--crf` or `--video-bitrate` for fine-grained overrides; `RenderConfig.crf` and `RenderConfig.videoBitrate` accept the same overrides programmatically. Use `--video-frame-format png` when source videos are UI recordings, screen captures, or other color-sensitive clips that should avoid JPEG frame extraction.
725726

‎packages/cli/src/commands/doctor.test.ts‎

Lines changed: 78 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
import { describe, it, expect, beforeEach, afterEach } from "vitest";
2-
import { buildDoctorReport, redactHome, parseToolVersion, type CheckOutcome } from "./doctor.js";
2+
import {
3+
buildDoctorReport,
4+
checkFramesCache,
5+
redactHome,
6+
parseToolVersion,
7+
type CheckOutcome,
8+
} from "./doctor.js";
39

410
// ── Fixtures ────────────────────────────────────────────────────────────────
511

@@ -195,3 +201,74 @@ describe("buildDoctorReport", () => {
195201
});
196202
});
197203
});
204+
205+
describe("checkFramesCache", () => {
206+
it("reports disabled state with the raw env value when the user opts out", () => {
207+
const result = checkFramesCache(
208+
{ HYPERFRAMES_EXTRACT_CACHE_DIR: "off" },
209+
() => 100_000,
210+
() => true,
211+
);
212+
expect(result.ok).toBe(true);
213+
expect(result.detail).toContain("Disabled (off)");
214+
expect(result.detail).toContain("per-render workDir");
215+
});
216+
217+
it("reports the effective directory + free space + default source when env is unset", () => {
218+
const result = checkFramesCache(
219+
{},
220+
() => 50_000, // ~48.8 GB
221+
() => true,
222+
);
223+
expect(result.ok).toBe(true);
224+
expect(result.detail).toContain("48.8 GB free");
225+
expect(result.detail).toContain("default");
226+
});
227+
228+
it("reports a positive env override with source: HYPERFRAMES_EXTRACT_CACHE_DIR", () => {
229+
const result = checkFramesCache(
230+
{ HYPERFRAMES_EXTRACT_CACHE_DIR: "/mnt/scratch/hf" },
231+
() => 10_000,
232+
() => true,
233+
);
234+
expect(result.ok).toBe(true);
235+
expect(result.detail).toContain("/mnt/scratch/hf");
236+
expect(result.detail).toContain("HYPERFRAMES_EXTRACT_CACHE_DIR");
237+
});
238+
239+
it("fails with a relocation hint when free space at the cache location is <2 GB", () => {
240+
const result = checkFramesCache(
241+
{ HYPERFRAMES_EXTRACT_CACHE_DIR: "/tmp/hf" },
242+
() => 512, // 0.5 GB
243+
() => true,
244+
);
245+
expect(result.ok).toBe(false);
246+
expect(result.hint).toContain("--frames-cache-dir");
247+
expect(result.hint).toContain("HYPERFRAMES_EXTRACT_CACHE_DIR");
248+
});
249+
250+
it("falls back to the first existing ancestor when the cache dir does not exist yet", () => {
251+
const seen: string[] = [];
252+
const result = checkFramesCache(
253+
{ HYPERFRAMES_EXTRACT_CACHE_DIR: "/mnt/scratch/newly/created/subdir" },
254+
(path) => {
255+
seen.push(path);
256+
return 20_000;
257+
},
258+
(path) => path === "/mnt/scratch",
259+
);
260+
expect(result.ok).toBe(true);
261+
// statfs was called against the walked-up ancestor, not the raw dir.
262+
expect(seen).toContain("/mnt/scratch");
263+
});
264+
265+
it("handles a null free-space reading without failing the check", () => {
266+
const result = checkFramesCache(
267+
{ HYPERFRAMES_EXTRACT_CACHE_DIR: "/mnt/scratch" },
268+
() => null,
269+
() => true,
270+
);
271+
expect(result.ok).toBe(true);
272+
expect(result.detail).toContain("free space unknown");
273+
});
274+
});

‎packages/cli/src/commands/doctor.ts‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,10 @@
11
// fallow-ignore-file complexity
22
import { defineCommand } from "citty";
33
import { execFileSync, execSync } from "node:child_process";
4+
import { existsSync } from "node:fs";
45
import { platform } from "node:os";
6+
import { dirname } from "node:path";
7+
import { resolveExtractCacheDir } from "@hyperframes/engine";
58
import type { Example } from "./_examples.js";
69
import { c } from "../ui/colors.js";
710
import { parseToolVersion, runEnvironmentChecks } from "../browser/preflight.js";
@@ -133,6 +136,70 @@ function checkDisk(): CheckResult {
133136
return { ok: true, detail: `${freeGb} GB free` };
134137
}
135138

139+
/**
140+
* Report the effective extracted-frame cache directory. Long renders can
141+
* accumulate multi-GB of extracted video frames here; on Windows the OS
142+
* `%TEMP%` default lives on C:, so users with output on a data drive but the
143+
* OS on a small SSD have hit disk-exhaustion mid-render (field signal
144+
* `ts=1784219488` · CLI 0.7.58 · 15GB/8-core). Surfacing the effective path
145+
* + free space at that path lets `hyperframes doctor` catch the mismatch
146+
* before the render, and reminds users the relocation knob exists.
147+
*
148+
* `statfsSync` requires the path to exist. When the configured cache dir has
149+
* not been created yet, walk up to the nearest existing ancestor and report
150+
* the free space there (which is the same filesystem in practice — free space
151+
* is per-mount, not per-directory).
152+
*/
153+
export function checkFramesCache(
154+
env: Record<string, string | undefined> = process.env,
155+
freeDiskMb: (path: string) => number | null = getFreeDiskMb,
156+
fileExists: (path: string) => boolean = existsSync,
157+
): CheckResult {
158+
const resolution = resolveExtractCacheDir(env);
159+
if (resolution.disabled) {
160+
return {
161+
ok: true,
162+
detail: `Disabled (${resolution.rawValue}) — frames extract into per-render workDir`,
163+
};
164+
}
165+
const dir = resolution.dir;
166+
const probePath = firstExistingAncestor(dir, fileExists) ?? dir;
167+
const freeMb = freeDiskMb(probePath);
168+
if (freeMb === null) {
169+
return {
170+
ok: true,
171+
detail: `${dir} (free space unknown; ${sourceLabel(resolution.source)})`,
172+
};
173+
}
174+
const freeGb = (freeMb / 1024).toFixed(1);
175+
const suffix = `${freeGb} GB free at ${probePath} · ${sourceLabel(resolution.source)}`;
176+
if (freeMb < 2048) {
177+
return {
178+
ok: false,
179+
detail: `${dir} · ${suffix}`,
180+
hint:
181+
"Low free space at the extract cache location — long renders can exhaust the drive. " +
182+
"Relocate via HYPERFRAMES_EXTRACT_CACHE_DIR=<path> or `hyperframes render --frames-cache-dir <path>`.",
183+
};
184+
}
185+
return { ok: true, detail: `${dir} · ${suffix}` };
186+
}
187+
188+
function firstExistingAncestor(path: string, fileExists: (p: string) => boolean): string | null {
189+
let current = path;
190+
for (let i = 0; i < 64; i += 1) {
191+
if (fileExists(current)) return current;
192+
const parent = dirname(current);
193+
if (parent === current) return null;
194+
current = parent;
195+
}
196+
return null;
197+
}
198+
199+
function sourceLabel(source: "env" | "default"): string {
200+
return source === "env" ? "HYPERFRAMES_EXTRACT_CACHE_DIR" : "default";
201+
}
202+
136203
function commandExists(command: string): boolean {
137204
try {
138205
execFileSync("which", [command], { stdio: "ignore", timeout: 5000 });
@@ -269,6 +336,7 @@ export default defineCommand({
269336
{ name: "CPU", run: checkCPU },
270337
{ name: "Memory", run: checkMemory },
271338
{ name: "Disk", run: checkDisk },
339+
{ name: "Frames cache", run: () => checkFramesCache() },
272340
{ name: "Archive extractor", run: checkArchiveExtractor },
273341
];
274342

‎packages/cli/src/commands/render.ts‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,10 @@ export const examples: Example[] = [
3535
["Deterministic render via Docker", "hyperframes render --docker --output deterministic.mp4"],
3636
["Parallel rendering with 6 workers", "hyperframes render --workers 6 --output fast.mp4"],
3737
["Opt out of browser GPU render", "hyperframes render --no-browser-gpu --output cpu.mp4"],
38+
[
39+
"Relocate frame cache off C: (Windows) or another small partition",
40+
"hyperframes render --frames-cache-dir D:/hf-cache --output out.mp4",
41+
],
3842
["HDR output (auto-detected)", "hyperframes render --output hdr-output.mp4"],
3943
[
4044
"Override composition variables (parametrized render)",
@@ -396,6 +400,18 @@ export default defineCommand({
396400
// guard below leaves PRODUCER_EXPERIMENTAL_FAST_CAPTURE untouched and the
397401
// env fallback survives (matches the --low-memory-mode idiom).
398402
},
403+
"frames-cache-dir": {
404+
type: "string",
405+
description:
406+
"Directory for the content-addressed extracted-frame cache. " +
407+
"Use to relocate the cache off the system drive when the OS temp " +
408+
"directory lives on a small partition (e.g. Windows C: exhaustion " +
409+
'during long renders). Pass "off" / "none" / "false" / "0" to ' +
410+
"disable caching entirely (frames extract into the render's workDir " +
411+
"and are cleaned up when the render ends). Default: " +
412+
"<tmpdir>/hyperframes-extract-cache-<uid>. " +
413+
"Env: HYPERFRAMES_EXTRACT_CACHE_DIR.",
414+
},
399415
},
400416
// `run` is the citty handler for `hyperframes render` — sequential flag
401417
// validation + render dispatch. Inherited CRITICAL on main (CRAP 1290);
@@ -579,6 +595,19 @@ export default defineCommand({
579595
: "false";
580596
}
581597

598+
// ── Override: extracted-frame cache directory ────────────────────────
599+
// Sugar for HYPERFRAMES_EXTRACT_CACHE_DIR. Set BEFORE resolveConfig() so
600+
// the env resolver picks up the CLI-supplied value. Disabling aliases
601+
// (off/none/false/0) pass through verbatim — the engine helper canonicalizes.
602+
// Positive paths are resolved to absolute so CWD changes downstream can't
603+
// stale them.
604+
if (typeof args["frames-cache-dir"] === "string" && args["frames-cache-dir"].trim() !== "") {
605+
const raw = args["frames-cache-dir"].trim();
606+
const normalized = raw.toLowerCase();
607+
const isDisableAlias = ["off", "none", "false", "0"].includes(normalized);
608+
process.env.HYPERFRAMES_EXTRACT_CACHE_DIR = isDisableAlias ? raw : resolve(raw);
609+
}
610+
582611
// ── Validate max-concurrent-renders ─────────────────────────────────
583612
if (args["max-concurrent-renders"] != null) {
584613
const parsed = parseInt(args["max-concurrent-renders"], 10);

‎packages/engine/src/config.test.ts‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,9 @@ import {
88
shouldClampToScreenshotForConcreteGpu,
99
applyConcreteGpuScreenshotClamp,
1010
shouldAutoDisableStreamingEncodeOnWin32Compound,
11+
resolveExtractCacheDir,
12+
defaultExtractCacheDir,
13+
EXTRACT_CACHE_DIR_DISABLED_ALIASES,
1114
} from "./config.js";
1215
import type { EngineConfig } from "./config.js";
1316
import { isLowMemorySystem } from "./services/systemMemory.js";
@@ -798,3 +801,45 @@ describe("scaleProtocolTimeoutForComposition", () => {
798801
);
799802
});
800803
});
804+
805+
describe("resolveExtractCacheDir", () => {
806+
it("returns the OS-default cache dir when the env var is unset", () => {
807+
const res = resolveExtractCacheDir({});
808+
expect(res.disabled).toBe(false);
809+
expect(res.source).toBe("default");
810+
if (!res.disabled) {
811+
expect(res.dir).toBe(defaultExtractCacheDir());
812+
}
813+
});
814+
815+
it("threads a positive env value through verbatim (source: env)", () => {
816+
const res = resolveExtractCacheDir({
817+
HYPERFRAMES_EXTRACT_CACHE_DIR: "D:/hf-cache",
818+
});
819+
expect(res.disabled).toBe(false);
820+
expect(res.source).toBe("env");
821+
if (!res.disabled) {
822+
expect(res.dir).toBe("D:/hf-cache");
823+
expect(res.rawValue).toBe("D:/hf-cache");
824+
}
825+
});
826+
827+
it.each(EXTRACT_CACHE_DIR_DISABLED_ALIASES.flatMap((v) => [v, v.toUpperCase(), ` ${v} `]))(
828+
"reports disabled for opt-out alias %s",
829+
(value) => {
830+
const res = resolveExtractCacheDir({ HYPERFRAMES_EXTRACT_CACHE_DIR: value });
831+
expect(res.disabled).toBe(true);
832+
if (res.disabled) {
833+
expect(res.dir).toBeUndefined();
834+
expect(res.rawValue).toBe(value);
835+
}
836+
},
837+
);
838+
839+
it("defaults to process.env when no env argument is passed", () => {
840+
// Signal-only smoke test — the previous callers rely on this default and
841+
// both engine.resolveConfig() and doctor's checkFramesCache() would break
842+
// silently if the signature drifted to require an env argument.
843+
expect(() => resolveExtractCacheDir()).not.toThrow();
844+
});
845+
});

‎packages/engine/src/config.ts‎

Lines changed: 64 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -420,6 +420,69 @@ export function shouldAutoDisableStreamingEncodeOnWin32Compound(opts: {
420420
return true;
421421
}
422422

423+
/**
424+
* Result of resolving the extract cache directory from the env, decoupled from
425+
* the wider {@link resolveConfig} pipeline so `hyperframes doctor` (and any
426+
* other diagnostic surface) can report the exact same effective value the
427+
* renderer will use — including whether the user has explicitly disabled the
428+
* cache via `off`/`none`/`false`/`0`.
429+
*
430+
* - `dir: string` + `disabled: false` → renderer will use this directory.
431+
* `source` reports whether the value came from the env or the OS default.
432+
* - `dir: undefined` + `disabled: true` → user explicitly turned caching off;
433+
* frames extract into the per-render workDir (auto-cleaned when the render
434+
* ends). `rawValue` carries the exact string the user set.
435+
*/
436+
export type ExtractCacheDirResolution =
437+
| { dir: string; disabled: false; source: "env" | "default"; rawValue?: string }
438+
| { dir: undefined; disabled: true; source: "env"; rawValue: string };
439+
440+
/**
441+
* Env-var values that disable the extract cache entirely. Case-insensitive;
442+
* whitespace-trimmed. Kept as an exported constant so the CLI can echo the
443+
* accepted alias set in `--frames-cache-dir` help text without drift.
444+
*/
445+
export const EXTRACT_CACHE_DIR_DISABLED_ALIASES: readonly string[] = ["off", "none", "false", "0"];
446+
447+
/**
448+
* Compute the default extract-cache directory when the user has NOT set
449+
* `HYPERFRAMES_EXTRACT_CACHE_DIR`. Exported so downstream tests can reproduce
450+
* the exact path without duplicating the uid-suffix idiom.
451+
*/
452+
export function defaultExtractCacheDir(): string {
453+
return join(tmpdir(), `hyperframes-extract-cache-${process.getuid?.() ?? "u"}`);
454+
}
455+
456+
/**
457+
* Resolve the extract-cache directory from an environment (defaults to
458+
* `process.env`). Mirrors the internal helper used by {@link resolveConfig},
459+
* but returns a rich resolution object so callers can distinguish "disabled by
460+
* user" from "default location" without re-parsing the env value.
461+
*
462+
* See {@link ExtractCacheDirResolution} for the shape and its two states.
463+
*/
464+
export function resolveExtractCacheDir(
465+
env: Record<string, string | undefined> = process.env,
466+
): ExtractCacheDirResolution {
467+
const raw = env["HYPERFRAMES_EXTRACT_CACHE_DIR"];
468+
if (raw === undefined) {
469+
return { dir: defaultExtractCacheDir(), disabled: false, source: "default" };
470+
}
471+
const normalized = raw.trim().toLowerCase();
472+
if (EXTRACT_CACHE_DIR_DISABLED_ALIASES.includes(normalized)) {
473+
return { dir: undefined, disabled: true, source: "env", rawValue: raw };
474+
}
475+
return { dir: raw, disabled: false, source: "env", rawValue: raw };
476+
}
477+
478+
function resolveExtractCacheDirFromEnv(
479+
env: (key: string) => string | undefined,
480+
): string | undefined {
481+
const raw = env("HYPERFRAMES_EXTRACT_CACHE_DIR");
482+
return resolveExtractCacheDir(raw === undefined ? {} : { HYPERFRAMES_EXTRACT_CACHE_DIR: raw })
483+
.dir;
484+
}
485+
423486
function memoryAdaptiveCacheLimit(): number {
424487
const total = getSystemTotalMb();
425488
if (total < 4096) return 32;
@@ -474,23 +537,6 @@ export function resolveConfig(overrides?: Partial<EngineConfig>): EngineConfig {
474537
const raw = env("HF_STATIC_DEDUP")?.trim().toLowerCase();
475538
return !(raw === "false" || raw === "off" || raw === "0");
476539
};
477-
const resolveExtractCacheDir = (): string | undefined => {
478-
const raw = env("HYPERFRAMES_EXTRACT_CACHE_DIR");
479-
if (raw === undefined) {
480-
return join(tmpdir(), `hyperframes-extract-cache-${process.getuid?.() ?? "u"}`);
481-
}
482-
const trimmed = raw.trim();
483-
const normalized = trimmed.toLowerCase();
484-
if (
485-
normalized === "off" ||
486-
normalized === "none" ||
487-
normalized === "false" ||
488-
normalized === "0"
489-
) {
490-
return undefined;
491-
}
492-
return raw;
493-
};
494540

495541
// Env-var layer (backward compat)
496542
const fromEnv: Partial<EngineConfig> = {
@@ -589,7 +635,7 @@ export function resolveConfig(overrides?: Partial<EngineConfig>): EngineConfig {
589635
verifyRuntime: env("PRODUCER_VERIFY_HYPERFRAME_RUNTIME") !== "false",
590636
runtimeManifestPath: env("PRODUCER_HYPERFRAME_MANIFEST_PATH"),
591637

592-
extractCacheDir: resolveExtractCacheDir(),
638+
extractCacheDir: resolveExtractCacheDirFromEnv(env),
593639
extractCacheMaxBytes:
594640
envNum("HYPERFRAMES_EXTRACT_CACHE_MAX_MB", DEFAULT_CONFIG.extractCacheMaxBytes / 1024 ** 2) *
595641
1024 ** 2,

0 commit comments

Comments
 (0)