mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-15 22:08:03 +00:00
ukimsanov
f2bd52650d
Navigation: Start here now holds exactly the four entry points a person can be sent - what it is, make one, choose a workflow, and the Studio overview. The three pages that were sitting in it went where they belong: the project tour is conceptual so it moved to Learn, authentication is configuration so it moved to Developers, and the hosted AI-chat route is a creation surface so it moved to Create with an agent. Width: the theme capped the article shell at 72rem and reserved 28rem of every wide viewport for the contents rail, leaving the reading column at ~664px on a 1600px screen - narrower than the 16:9 video the pages are supposed to show. Raised the shell and returned 9rem from the gutter, taking the column to roughly 950px. Running prose is held near 80 characters because longer lines measurably hurt reading; tables, cards, code, and media use the full width. Added .hf-wide for visuals that should escape the measure entirely. Components: the quickstart source chooser is now Tabs, which is what parallel variants of one instruction want, and the help symptoms are visible sections with their own anchors so support can link a symptom directly instead of the hub. Wrote the doctrine into AGENTS.md - one component per job, cards never point at anchors on their own page, no diagram that restates adjacent prose, and the rules for custom React snippets (named exports, no third-party packages, no CDN).
129 lines
4.4 KiB
Plaintext
129 lines
4.4 KiB
Plaintext
---
|
|
title: "Get unstuck"
|
|
sidebarTitle: "Get unstuck"
|
|
description: "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:
|
|
|
|
```bash
|
|
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 →](/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](/guides/troubleshooting) 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:
|
|
|
|
```text
|
|
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
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Common questions" icon="circle-question" href="/guides/common-questions">
|
|
Short answers to what usually comes up during first use.
|
|
</Card>
|
|
<Card title="Complete troubleshooting" icon="wrench" href="/guides/troubleshooting">
|
|
Less common project, media, animation, rendering, and environment failures.
|
|
</Card>
|
|
<Card title="Share product feedback" icon="comment" href="/guides/feedback">
|
|
Explain a confusing or broken experience with useful context.
|
|
</Card>
|
|
<Card title="Search GitHub issues" icon="github" href="https://github.com/heygen-com/hyperframes/issues">
|
|
Find a known problem, or open a reproducible one.
|
|
</Card>
|
|
</CardGroup>
|