mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-14 13:27:13 +00:00
ukimsanov
f595a7d683
Rendering, Performance, Deploy, Figma and Bring in a design. **Figma is the one worth reading about.** The first attempt failed honestly — no token, no file key, so it refused to fake an import and built a generic design handoff instead, where both panels looked identical and nothing was demonstrated. A real token and file key were sitting in bug-bash-figma-hf. With genuine access it makes the actual point: the same cursor and the same clicks land on a PNG export and on the imported HTML, and only the HTML responds — the field takes text, the button runs through its states. One side is pixels, the other is a component. It replaces the placeholder comment on Bring in a design too. **Performance is measured, not asserted.** 25.0s against 9.8s as the median of three runs at 1920x1080 over 300 frames, one CSS declaration responsible for the whole gap, and a pixel comparison at 43.7 dB PSNR confirming the picture did not change. Real numbers from real runs on this machine. **Rendering** shows the loop end to end. **Deploy** shows the four places a render can run and labels anything not executed live. All four carry their own audio at about -19 dB. Each was checked on a contact sheet and for dead frames before publishing. Guides with nothing to look at: 15 at the start of this work, 5 now. The five left are pages where a video would be decoration — authentication, feedback, a decision table, a comparison that carries code, and 4K, which is a paragraph about a flag.
77 lines
3.3 KiB
Plaintext
77 lines
3.3 KiB
Plaintext
---
|
||
title: Fix a slow preview or render
|
||
description: Find the expensive part of a composition and make it cheaper.
|
||
---
|
||
|
||
import { DocsVideo } from "/snippets/docs-video.jsx";
|
||
|
||
A finished render can be smooth even when preview stutters. Preview must draw each frame in real time; render can take as long as it needs to capture the same frames.
|
||
|
||
<DocsVideo
|
||
title="The same composition built two ways, timed on this machine"
|
||
src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/render-performance-demo-v1.mp4"
|
||
poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/render-performance-demo-v1.jpg"
|
||
/>
|
||
|
||
Real numbers, not estimates: 25.0s against 9.8s, taken as the median of three
|
||
runs at 1920x1080 over 300 frames. One CSS declaration is the whole difference,
|
||
and a pixel comparison confirms the picture did not change.
|
||
|
||
## Start with the symptom
|
||
|
||
| What you see | Check first |
|
||
| --- | --- |
|
||
| Preview stutters in one scene | Large blurs, masks, shadows, or many animated layers in that scene |
|
||
| Preview pauses the first time an image appears | Oversized source images or image decoding |
|
||
| The whole page becomes slow | Script work, layout thrashing, or too many DOM nodes |
|
||
| Render is slow but the result is correct | Source-video extraction, frame capture, or encoding |
|
||
| WebM takes much longer than MP4 | VP9 encoding; transparent WebM is CPU-heavy |
|
||
|
||
## Reduce expensive browser work
|
||
|
||
- Use fewer large `backdrop-filter` and `filter: blur()` layers.
|
||
- Avoid animating dozens of shadowed elements at once.
|
||
- Replace a static blur or texture stack with a pre-rendered image.
|
||
- Size images near their actual delivery dimensions. A very large JPEG still decodes into a very large bitmap.
|
||
- Keep work inside animation callbacks small. Do not repeatedly read layout and write styles in the same frame.
|
||
|
||
For a 1920×1080 composition, a 3840×2160 source already provides enough detail for a 2× display. Larger sources usually add memory and decode work without improving the frame.
|
||
|
||
## Measure instead of guessing
|
||
|
||
1. Run `npx hyperframes preview`.
|
||
2. Open Chrome DevTools and select **Performance**.
|
||
3. Record the part that stutters.
|
||
4. Inspect the longest tasks:
|
||
- **Paint** or **Composite Layers** points to filters, shadows, masks, or large layers.
|
||
- **Layout** or **Recalculate Style** points to layout work.
|
||
- **Script** points to author code.
|
||
|
||
Change one expensive feature, record again, and keep the version that moves the bottleneck.
|
||
|
||
## Make a fast review render
|
||
|
||
If the composition is intentionally too heavy for real-time playback, review an encoded file:
|
||
|
||
```bash
|
||
npx hyperframes render --quality draft --output review.mp4
|
||
```
|
||
|
||
Use `standard` or `high` for delivery. Draft changes capture and encoder quality; it does not change the composition's timing.
|
||
|
||
## Tune transparent WebM only when needed
|
||
|
||
WebM uses the CPU-heavy VP9 encoder. The default is suitable for most work. To trade more encoding time for compression quality:
|
||
|
||
```bash
|
||
npx hyperframes render --format webm --vp9-cpu-used 2 --output overlay.webm
|
||
```
|
||
|
||
`--vp9-cpu-used` accepts integers from `-8` to `8`; higher values are faster with a larger quality/size tradeoff.
|
||
|
||
## Related topics
|
||
|
||
- [Diagnose a failed or stalled render](/guides/troubleshooting)
|
||
- [Render from the command line](/guides/rendering)
|
||
- [Render at 4K](/guides/4k-rendering)
|