HyperFrames errors, black frames and slow renders, answered
HyperFrames turns an HTML document with timing attributes and a seekable animation into a deterministic MP4. When it goes wrong it usually goes wrong quietly: the check passes, the render exits 0, and the video is black or still. These answers are built from the project's issue tracker, its docs and its changelog, with the cause traced rather than guessed.
Errors and things that look wrong
What does 'Composition HTML is empty or could not be parsed' mean in HyperFrames?
A data-composition-src that points at an empty, partial or missing file was the most common HyperFrames render failure in the project's own telemetry. Here is what the error means, what older versions did, and the fix.
Why do my fonts look wrong in a HyperFrames render, and what is FONT_FETCH_FAILED?
A font that looks right in preview can fall back, change weight or fail the render outright. Embed the font with @font-face, understand what the compiler does with a named Google Font, and know why Arial and Segoe UI behave differently from Helvetica.
Why does a HyperFrames render go black when I nest paused GSAP timelines?
Combining paused scene timelines with parent.add(child) makes the parent report a duration of 0 and leaves the children frozen at time zero. It is GSAP behaviour, not a regression, and lint and check do not catch it.
Why does every HyperFrames render take 45 seconds longer than it should?
A composition that never registers a GSAP timeline still makes the renderer wait for one, and gives up after a fixed 45 seconds. The cost is flat on every render. One attribute removes it.
Why does HyperFrames render my empty scaffold instead of my composition?
If check, snapshot and render all succeed but show a blank black video, you may have two entry files. HyperFrames opens the top-level index.html by default, and that may not be the one you wrote.
Why does my HyperFrames render look different from the preview?
Preview and render run the same runtime, so a real difference has a specific cause: fonts, remote media, a cold-seek state problem, the wrong entry file, or a variable that never arrived. Here is how to find which.
Why does my HyperFrames video clip render black or freeze?
A video clip that plays in preview but renders black usually needs its own data-start and data-duration, not just a timed wrapper. Also covers clips shorter than their slot and videos that freeze while their box animates.
Why is an element invisible in my HyperFrames render but fine in preview?
A render worker seeks straight to a frame and restores the authored state, not whatever the preview last showed. Elements that start hidden need their visible end state stated explicitly, and a fromTo shows its from-state before it starts.
Why is my first HyperFrames video a still image?
A composition script that throws leaves the timeline unbuilt, and older HyperFrames versions waited 45 seconds, wrote the MP4 anyway and exited 0. Here is why that happens and how current versions fail instead.
Why is my HyperFrames animation static?
If the render shows your elements frozen in their start state, HyperFrames almost certainly cannot find or seek your timeline. The timeline has to be paused and registered under the exact composition ID.
Why is my HyperFrames render black?
A black HyperFrames video almost always has one of seven causes, from rendering the wrong entry file to a video clip with no timing of its own. Here is how to tell which one you have in a few minutes.
Why is my HyperFrames render slow, and what actually speeds it up?
Separate a slow preview from a slow render, find the fixed 45 second tax, then work through source video, filters, encoding and resolution. Real fixes from HyperFrames' own performance guide.
How to do it
How do I add a voiceover and captions to a HyperFrames video?
Generate narration locally or ask your agent for it, transcribe it into word-level timestamps, turn the transcript into readable captions, and mix music under the voice without cutting words.
How do I install HyperFrames, and why did npx skills add fail?
The current install routes for Claude Code, Codex, Cursor and others, plus the three real failures people hit: a 60 second clone timeout, a missing git-lfs, and a Codex marketplace error. What each means and how to get past it.
How to create a product launch video with HyperFrames
Build a 12 second, four scene product launch video from an empty folder with HyperFrames: the project layout, every file, the check and snapshot commands, a real render, and the mistakes the linter catches. Tested on HyperFrames 0.8.134.
How it works
What are the HyperFrames determinism rules, in one checklist?
Same composition, same video, every time, as long as nothing in a frame reads the clock, an unseeded random number or the network. The rules, the reason for each, and the lint codes that enforce them.
Why did HyperFrames check pass and render exit 0 when my video is wrong?
HyperFrames can produce a valid-looking MP4 from a composition that is structurally fine and visually wrong. Here is the class of bug, what has been fixed to fail loudly, and what to verify yourself.