Files
hyperframes/docs/help.mdx
T
ukimsanov 60806271ba docs: apply the same de-duplication to the remaining journey pages
help: the eight symptom cards linked to anchors immediately below that repeated
their own descriptions. One accordion per symptom now holds the fix, so scanning
and expanding replaces scrolling past the same words twice. The diagnostic block
and the four real escalation links stay.

studio: dropped the decision flowchart that duplicated the table beneath it, and
added the existing Storyboard screenshot so the Storyboard-versus-Preview split
is shown rather than only described.

quickstart: removed the five-node diagram that restated the six numbered steps,
and pointed the request-writing advice at the prompting guide instead of growing
a third copy of it.
2026-07-29 13:36:54 -07:00

131 lines
4.8 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."
---
Open the symptom that looks most like yours. You should not need to understand the rendering architecture to solve a normal problem.
<AccordionGroup>
<Accordion title="Studio will not open" icon="window">
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.
</Accordion>
<Accordion title="Preview is wrong or stale" icon="rotate">
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.
</Accordion>
<Accordion title="I cannot select or edit something" icon="arrow-pointer">
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)
</Accordion>
<Accordion title="Media is missing or black" icon="photo-film">
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.
</Accordion>
<Accordion title="Animation is wrong" icon="wand-magic-sparkles">
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.
</Accordion>
<Accordion title="Render failed or differs from preview" icon="film">
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.
</Accordion>
</AccordionGroup>
## 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>