Repository navigation
Running "hyperframs render" on a Linux system, video compositing always fail. #566
Description
Describe the bug
below is the console log, It always gets stuck at 25% and then fails after a while.
root@5F-4gpu-45-01:/code/temp/req_html_test_0429_1735# hyperframes render
◆ Rendering req_html_test_0429_1735 → /code/temp/req_html_test_0429_1735/renders/req_html_test_0429_1735_2026-04-29_22-17-58.mp4
30fps · standard · auto workers (72 cores detected)
│
◇ Browser: cache
⚠ composition_file_too_large: This HTML composition file has 306 lines. Agents produce better results when large scenes are split into smaller sub-compositions.
Fix: Split coherent scenes or layers into separate .html files under compositions/, then mount them from the parent with data-composition-src so each file stays small enough to inspect, revise, and validate independently.
Continuing render despite lint issues. Use --strict to block.
█░░░░░░░░░░░░░░░░░░░░░░░░ 5% Compiling composition[Compiler] Inlined CDN script: https://digital-public.obs.cn-east-3.myhuaweicloud.com/hyperframes/gsap.min.js
[Compiler] Inlined CDN script: https://digital-public.obs.cn-east-3.myhuaweicloud.com/hyperframes/effects_bundle.js
[INFO] Compiled composition metadata {"entryFile":"index.html","staticDuration":329.888,"width":1920,"height":1080,"videoCount":7,"audioCount":8,"renderModeHints":{"recommendScreenshot":false,"reasons":[]}}
██░░░░░░░░░░░░░░░░░░░░░░░ 10% Extracting video frames[Compiler] WARNING: Video "elem_22_video" has sparse keyframes (max interval: 10s). This causes seek failures and frame freezing. Re-encode with: ffmpeg -i "ppt_video_slow_playback_23.mp4" -c:v libx264 -r 30 -g 30 -keyint_min 30 -movflags +faststart -c:a copy output.mp4
[Compiler] WARNING: Video "elem_21_video" has sparse keyframes (max interval: 10s). This causes seek failures and frame freezing. Re-encode with: ffmpeg -i "ppt_video_slow_playback_22.mp4" -c:v libx264 -r 30 -g 30 -keyint_min 30 -movflags +faststart -c:a copy output.mp4
[Compiler] WARNING: Video "elem_20_video" has sparse keyframes (max interval: 7.2s). This causes seek failures and frame freezing. Re-encode with: ffmpeg -i "ppt_video_slow_playback_21.mp4" -c:v libx264 -r 30 -g 30 -keyint_min 30 -movflags +faststart -c:a copy output.mp4
[INFO] [Render] No HDR sources detected — rendering SDR
██████░░░░░░░░░░░░░░░░░░░ 25% Starting frame capture
[WARN] [Render] Auto-worker calibration failed; using conservative worker budget. {"protocolTimeout":30000,"error":"Runtime.callFunctionOn timed out. Increase the 'protocolTimeout' setting in launch/connect calls for a higher timeout if needed."}
[WARN] [Render] Reduced auto worker count for high-cost capture workload to avoid Chrome compositor starvation. {"from":6,"to":3,"costMultiplier":8,"reasons":["calibration-failed","7 videos","8 audios"]}
[WARN] [Render] Parallel capture timed out; retrying missing frames. {"fromWorkers":3,"toWorkers":1,"missingFrames":9897,"error":"[Parallel] Capture failed: Worker 0: Runtime.callFunctionOn timed out. Increase the 'protocolTimeout' setting in launch/connect calls for a higher timeout if needed.; Worker 1: Runtime.callFunctionOn timed out. Increase the 'protocolTimeout' setting in launch/connect calls for a higher timeout if needed.; Worker 2: Runtime.callFunctionOn timed out. Increase the 'protocolTimeout' setting in launch/connect calls for a higher timeout if needed."}
██████░░░░░░░░░░░░░░░░░░░ 25% Failed: [Parallel] Capture failed: Worker 0: Runtime.callFunctionOn timed out. Increase the 'protocolTimeout' setting in launch/connect calls for a higher timeout if needed.
✗ Render failed
[Parallel] Capture failed: Worker 0: Runtime.callFunctionOn timed out. Increase the 'protocolTimeout' setting in launch/connect calls for a higher timeout if needed.
Try --docker for containerized rendering
Link to reproduction
Steps to reproduce
1
Expected behavior
1
Actual behavior
1
Environment
root@5F-4gpu-45-01:/code# hyperframes doctor
hyperframes doctor
✓ Version 0.4.34 (latest)
✓ Node.js v24.15.0 (linux x64)
✓ CPU 72 cores · Intel(R) Xeon(R) Gold 6154 CPU @ 3.00GHz @ 1200MHz
✓ Memory 251.5 GB total · 243.8 GB free
✓ Disk 6278.8 GB free
✓ /dev/shm 16384 MB
✓ Environment Docker
✓ FFmpeg ffmpeg version 6.1 Copyright (c) 2000-2023 the FFmpeg developers
✓ FFprobe ffprobe version 6.1 Copyright (c) 2007-2023 the FFmpeg developers
✓ Chrome cache: /root/.cache/hyperframes/chrome/chrome-headless-shell/linux-131.0.6778.85/chrome-headless-shell-linux64/chrome-headless-shell
/bin/sh: 1: docker: not found
✗ Docker Not found
https://docs.docker.com/get-docker/
✗ Docker running Not running
Start Docker Desktop or run: sudo systemctl start dockerAdditional context
No response
Activity
miguel-heygen commentedon Apr 29, 2026
Hi! The root cause has been identified and a fix is in PR #567. In the meantime, here are two workarounds to unblock your render:
Workaround 1: Force screenshot mode (recommended)
Set `PRODUCER_FORCE_SCREENSHOT=true` before running:
```bash
PRODUCER_FORCE_SCREENSHOT=true hyperframes render
```
This bypasses BeginFrame mode entirely and uses the standard screenshot capture path, which is more stable for compositions with many heavy videos.
Workaround 2: Set explicit worker count
Force a single worker to avoid multiple Chrome instances competing for resources:
```bash
hyperframes render --workers 1
```
What's happening
Your composition has 7 videos with sparse keyframes, which makes the page very expensive to initialize in Chrome's BeginFrame mode (deterministic rendering on Linux). The auto-worker calibration probe uses a 30-second timeout, and Chrome can't respond to CDP calls within that window while loading 7 video files simultaneously.
When calibration timed out, the engine was supposed to fall back to screenshot mode — but the fallback check was too narrow and didn't recognize
Runtime.callFunctionOn timed outas a BeginFrame-mode signal. Instead it stayed in BeginFrame mode, spawned 3 workers, and all 3 also timed out with 0 frames captured.The fix in #567 extends the fallback to cover this. Until that's released, either workaround above will get your render completing.
Separately: your videos have sparse keyframes (up to 10-second intervals). While this doesn't cause the crash above, it can cause frame-seek issues during rendering. You can re-encode them for better performance:
```bash
ffmpeg -i input.mp4 -c:v libx264 -r 30 -g 30 -keyint_min 30 -movflags +faststart -c:a copy output.mp4
```
fix: fall back to screenshot mode when any CDP call times out during …
fix: fall back to screenshot mode when any CDP call times out during …