Why is my HyperFrames render black?

A black HyperFrames video means the renderer captured frames successfully and there was nothing visible in them. That narrows it a lot. Work down this list in order, because the first three are the most common and the cheapest to rule out.

1. You rendered the wrong file

The scaffold creates a top-level index.html. If your real composition lives somewhere else, for example compositions/index.html, then check, snapshot, render and Studio preview all open the empty scaffold, report success, and give you a black video. One reporter filed it as a GSAP seek bug before the maintainers found two entry files in the project. Current versions reject this case outright, but older ones do not.

Fix: render the entry file you actually authored.

2. A <video> has no timing of its own

Putting data-start and data-duration on the wrapping .clip div is not enough. The <video> element needs them too. Without its own timing, its schedule starts at composition zero, so a clip placed at 6 seconds is already past the end of a 4 second source and renders black.

Fix: give the video element its own timing.

3. The animation never ran

If the timeline is not registered under the composition ID, the renderer cannot seek it, and everything that starts hidden stays hidden. Check that the timeline is created with { paused: true } and registered at window.__timelines["your-id"], where the key matches data-composition-id exactly.

Fix: register the timeline correctly.

4. You nested paused timelines yourself

If you built two scene timelines and combined them with parent.add(child), the parent reports a duration of 0 and the children never advance. Every seek resolves to time zero. This is a GSAP behaviour, not a regression, and it is identical across every GSAP version from 3.11.5 to 3.15.0.

Fix: let HyperFrames nest the scenes.

5. A sub-composition file is empty or the slot outlived its timeline

An empty compositions/scene.html used to be skipped silently, dropping the scene from the video. Current versions refuse to render and name the file. Separately, a sub-composition whose timeline is shorter than its slot went black for the rest of the slot in older versions; that was fixed in May 2026.

Fix: check your sub-composition files.

6. Elements start hidden and nothing reveals them

A render worker seeks straight to a frame. It restores the authored hidden state, not whatever your preview showed a moment ago. An element that fades in with fromTo but never states opacity: 1 as its destination can stay invisible in the render while looking fine when you scrub.

Fix: state the visible end state explicitly.

7. Something in a specific feature path

Two reports are worth knowing, both closed:

• Transparent WebM compositing showed opaque black in version 0.7.106. The maintainers could not reproduce it on 0.8.41 and closed it; if you still see it on a current release, reopen with the exact command and input file.
• Colour grading on an element that also has a CSS entrance animation rendered solid white (MP4) or black (ProRes) in versions 0.7.109 and 0.8.2. The reporter's bisection pointed at the combination, not at grading alone.

Check it worked

npx hyperframes doctor
npx hyperframes lint
npx hyperframes check
npx hyperframes snapshot --at 0,3,8

doctor checks the machine, lint and check check the project, and snapshot shows you real frames. If the first frame is black but a later one is not, you have an animation or visibility problem. If every frame is black, suspect the entry file or the timeline registration. Run npx hyperframes compositions to confirm which composition and duration HyperFrames resolved.