Why does my HyperFrames render look different from the preview?

The design goal is that they match, and the docs say why they should: preview and render run the same runtime, and capture waits until the composition is fully loaded. So when they differ, one of a short list of things is different. Check in this order.

1. Fonts

The most common visible difference. Fonts and Chrome versions differ between computers, so a local render can shift by a pixel from one machine to the next, and a font that your machine resolves may not resolve the same way elsewhere. Embed the font with @font-face rather than relying on a system font. See the fonts answer.

2. Remote media

Remote media can fail because of permissions, expiring URLs or cross-origin restrictions. Prefer a local project asset. Confirm the path, the filename capitalisation, and whether the file was moved or renamed.

3. An element that only exists in sequence

If something is hidden and revealed by a tween, a render worker that seeks directly to a later frame restores the authored hidden state instead of what the preview showed. Elements stay invisible, or appear early. See the cold-seek answer.

4. You are not looking at the same file

If check, snapshot and render all look blank or wrong, you may be rendering the scaffold instead of your composition. See the wrong entry file answer.

5. A value that arrives in preview and not in render

One confirmed case: data-variable-values passed to a sub-composition were injected by preview and snapshot, but render left the variables empty and painted the JavaScript defaults, silently and with exit code 0. It was reported against 0.7.42 and closed on July 8, 2026. If your composition uses variables on sub-compositions and an old version, compare a rendered frame, not a snapshot.

6. Browser-specific effects

The docs' own checklist for this symptom is fonts, remote media, browser-specific effects and the actual exported file. If an effect such as a blur or a filter looks different in the render, rule out your machine first with a Docker render, which pins the Chromium version.

What is not a difference

Speed. Preview plays in real time and can stutter. Render never drops a frame. Do not "fix" a stuttering preview by degrading the composition, because the render will be perfect regardless.

Tiny pixel noise between parallel workers. A default multi-worker render can produce a handful of plus or minus one pixel level differences at worker chunk boundaries. If you need bit-exact output, use --workers 1.

Check it worked

npx hyperframes render --docker --output output.mp4

If the Docker render matches your preview, the difference was your machine. If it does not, the difference is in the composition: go back to causes 3 to 5. For a wider view of the principle behind this, see why a render looks different from the preview, for any tool.