Describe the bug
On Windows (and any host with modest free disk), ordinary renders were rejected by the disk-capture headroom gate with a message like:
Disk capture may need ~16331.7 MB of temporary frame storage, but only 18092.4 MB is free at
C:\Users\...\AppData\Local\Temp\hf-render-xxxx\captured-frames. Re-run with --low-memory-mode ...
A few seconds of video "requiring 16 GB" looks alarming — and in our field case the machine had 18 GB free yet a ~1-minute 1080p30 export was refused only because the estimate crossed the 90% gate by 48 MB. Two compounding problems:
1. The estimate is an uncompressed RGBA ceiling, while disk frames are written compressed.
estimateDiskCaptureBytes bills totalFrames × width × height × 4 (raw RGBA), but the capture stage writes jpg (or png for alpha). Measured 1080p JPEG captures land at ~150–400 KB/frame — roughly 1/20–1/30 of the estimate. A 44 s 1080p30 composition estimated at ~11 GB against 11.4 GB free failed, with an actual JPEG footprint of a few hundred MB.
2. When the gate rejects, the render fails outright even when streaming was possible.
Auto-parallel renders always take the disk path (ordered streaming would stall later workers), and shouldUseStreamingEncode requires workerCount === 1 — so the only reason a render landed on the disk path was parallelism. The gate then runs as a hard error at capture time instead of a replan trigger. Long renders past the streaming duration cap (240 s) had no escape at all: 5 minutes of 1080p30 estimated at ~60 GB under the RGBA ceiling, rejecting effectively every machine.
Expected behavior
- The estimate should reflect the actual (compressed) capture format with a safety margin, not a raw RGBA ceiling.
- When disk headroom is insufficient but single-worker streaming is eligible for the render, the orchestrator should degrade the plan to single-worker streaming instead of failing.
Environment
- Windows 11 x64, HyperFrames producer ~v0.8.40 (observed in an Electron integration; applies to CLI renders too)
- C: drive with ~18 GB free; capture temp dir on the system drive (
hf-render-*)
Proposed fix
Two-part (PR to follow):
estimateDiskCaptureBytes bills by capture format: JPEG 0.5 B/px (keeps a ~5× safety margin, shrinks the estimate 8×) and PNG 2 B/px (lossless, half the RGBA ceiling). Gate message updated to the compressed-frame estimate basis.executeRenderJob checks the gate right after the initial capture plan is built; when headroom is insufficient and shouldUseStreamingEncode(cfg, format, 1, duration) is true, the plan degrades to single-worker streaming via a shouldDegradeDiskCaptureToStreaming predicate — before capture and telemetry observe it, so the degraded plan is indistinguishable from one the streaming gate chose up front.
Describe the bug
On Windows (and any host with modest free disk), ordinary renders were rejected by the disk-capture headroom gate with a message like:
A few seconds of video "requiring 16 GB" looks alarming — and in our field case the machine had 18 GB free yet a ~1-minute 1080p30 export was refused only because the estimate crossed the 90% gate by 48 MB. Two compounding problems:
1. The estimate is an uncompressed RGBA ceiling, while disk frames are written compressed.
estimateDiskCaptureBytesbillstotalFrames × width × height × 4(raw RGBA), but the capture stage writesjpg(orpngfor alpha). Measured 1080p JPEG captures land at ~150–400 KB/frame — roughly 1/20–1/30 of the estimate. A 44 s 1080p30 composition estimated at ~11 GB against 11.4 GB free failed, with an actual JPEG footprint of a few hundred MB.2. When the gate rejects, the render fails outright even when streaming was possible.
Auto-parallel renders always take the disk path (ordered streaming would stall later workers), and
shouldUseStreamingEncoderequiresworkerCount === 1— so the only reason a render landed on the disk path was parallelism. The gate then runs as a hard error at capture time instead of a replan trigger. Long renders past the streaming duration cap (240 s) had no escape at all: 5 minutes of 1080p30 estimated at ~60 GB under the RGBA ceiling, rejecting effectively every machine.Expected behavior
Environment
hf-render-*)Proposed fix
Two-part (PR to follow):
estimateDiskCaptureBytesbills by capture format: JPEG 0.5 B/px (keeps a ~5× safety margin, shrinks the estimate 8×) and PNG 2 B/px (lossless, half the RGBA ceiling). Gate message updated to the compressed-frame estimate basis.executeRenderJobchecks the gate right after the initial capture plan is built; when headroom is insufficient andshouldUseStreamingEncode(cfg, format, 1, duration)is true, the plan degrades to single-worker streaming via ashouldDegradeDiskCaptureToStreamingpredicate — before capture and telemetry observe it, so the degraded plan is indistinguishable from one the streaming gate chose up front.