Repository navigation
Description
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):
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.
Activity
fix(producer): degrade multi-worker disk capture to single-worker str…
fix(producer): degrade multi-worker disk capture to single-worker str…
fix(producer): degrade multi-worker disk capture to single-worker str…
miguel-heygen commentedon Oct 24, 2026
Thanks for the detailed report and for following up with #5334.
Where this stands on 0.8.193:
--workers 1.PNG and alpha captures are still estimated at full size, so a very tight disk can still refuse those.