Get unstuck

Start with what you can see, try the smallest useful fix, and get back to your HyperFrames task.

Find the symptom that looks like yours below — the contents list on the right jumps straight to it. You should not need to understand the rendering architecture to solve a normal problem.

Studio will not open

The browser never opens, the page is unreachable, or the project does not load.

1. Open a terminal in the HyperFrames project folder.
2. Run npx hyperframes preview.
3. Keep that process running while Studio is open.
4. Use the local URL printed in the terminal.

If the command cannot find a project, check that you are inside the project folder rather than its parent.

Preview is wrong or stale

A saved change is missing, playback looks old, or the preview is blank. Try these in order:

1. Save the changed file.
2. Reload Studio once.
3. Check the terminal for a build or runtime error.
4. Run the project checks:

npx hyperframes lint
npx hyperframes check

lint checks the composition structure. check opens the project in a browser gate and catches runtime, layout, motion, and contrast problems.

I cannot select or edit something

Selection, canvas controls, timing, or an Inspector field is unavailable.

• Open Layers and select the element there when clicking the canvas is difficult.
• Confirm you are in Preview, not Storyboard.
• Scrub to a time where the element is actually visible.
• Check whether the visual lives inside a nested composition.
• Ask the agent when the change affects source structure rather than one visible element.

Open Studio troubleshooting →

Media is missing or black

An image, video, font, or audio file is absent or does not render. Check that:

• the file still exists inside the project;
• the path and filename capitalisation match;
• the source is local and available during rendering;
• the browser can decode the format;
• the media is visible at the current time;
• the terminal reports no download, decode, or CORS error.

Never rely on a temporary signed URL or a render-time network request. Ask the agent to copy required media into the project.

Animation is wrong

Motion jumps, drifts, starts at the wrong time, or changes after seeking. First decide whether it happens:

• during normal playback;
• only after scrubbing;
• only in the final render.

That distinction separates a timeline mistake from non-deterministic animation. HyperFrames animation must be seekable: the same frame should look the same every time it is requested.

Run npx hyperframes check, then give your agent the smallest affected scene and the exact timestamp.

Render failed or differs from preview

Export stops, produces the wrong result, or disagrees with Studio.

1. Preserve the complete render error.
2. Run npx hyperframes check.
3. Confirm fonts and media are local and load before capture.
4. Check the affected timestamp in Studio.
5. Try the normal MP4 preset before changing codecs or advanced flags.

The complete troubleshooting guide covers codec, browser, FFmpeg, GPU, HDR, and deployment-specific failures.

Copy a useful diagnostic

If none of the above resolved it, send this to your agent with the visible facts filled in:

What I was trying to do:

What I clicked or ran:

What I expected:

What happened instead:

Exact error:

Where it happens: Studio / lint / check / render

Does it happen every time?

HyperFrames version:

Operating system:

Affected file or timestamp:

Add a screenshot or short recording when the failure is visual. Never paste access tokens, credentials, or private media into a public issue.

Still stuck

Common questions

Short answers to what usually comes up during first use.

Complete troubleshooting

Less common project, media, animation, rendering, and environment failures.

Share product feedback

Explain a confusing or broken experience with useful context.

Search GitHub issues

Find a known problem, or open a reproducible one.