Skip to content

docs: rewrite the guides and landing pages #2979

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ukimsanov merged 5 commits into from
Aug 4, 2026
Merged

docs: rewrite the guides and landing pages #2979

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
e60bef3
docs: rewrite the guides and landing pages
ukimsanov Aug 3, 2026
ac94869
docs: make the Reference Project links read as links
ukimsanov Aug 4, 2026
3d8db3f
docs: drop the Source group to two columns
ukimsanov Aug 4, 2026
b36f69a
docs: drop the live embed from the introduction
ukimsanov Aug 4, 2026
f720eb7
docs: lead the Quickstart with a paste-to-agent block, cut the Exampl…
ukimsanov Aug 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
347 changes: 90 additions & 257 deletions docs/examples.mdx
View file
Open in desktop

Large diffs are not rendered by default.

185 changes: 44 additions & 141 deletions docs/guides/4k-rendering.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,167 +1,70 @@
---
title: 4K Rendering
description: "Render any composition to 4K (3840×2160) without rewriting it — the CLI supersamples a 1080p composition via Chrome's device scale factor."
title: Render in 4K
description: Author at 4K or supersample an existing composition at render time.
---

Hyperframes renders to 4K (3840×2160) two ways. Both produce a true 4K MP4; pick the one that matches your project.

<CardGroup cols={2}>
<Card title="Author at 4K" icon="ruler">
Scaffold the project at 4K so the composition is laid out at 4K natively. Best when you want crisp 4K-native typography and assets.
```bash
npx hyperframes init my-video --resolution 4k
```
</Card>
<Card title="Supersample at render" icon="up-right-and-down-left-from-center">
Keep your existing 1080p composition. Pass `--resolution 4k` at render time and Chrome renders at 2× DPR so the screenshot lands at 4K.
```bash
npx hyperframes render --resolution 4k --output 4k.mp4
```
</Card>
</CardGroup>

## Quickstart

<Steps>
<Step title="Render an existing project at 4K">
```bash Terminal
npx hyperframes render --resolution 4k --output my-video-4k.mp4
```

The composition's `data-width` / `data-height` are unchanged. Chrome's `deviceScaleFactor` is set to `2`, so the captured screenshot for each frame is 3840×2160. ffmpeg auto-detects the dimensions from the screenshot stream and encodes at 4K.
</Step>
<Step title="Or scaffold a new project at 4K">
```bash Terminal
npx hyperframes init my-video --resolution 4k
```

Every scaffolded HTML file is patched in place: `data-width="3840"`, `data-height="2160"`, `data-resolution="landscape-4k"`, `#stage` CSS dimensions, and the `<meta viewport>` tag.
</Step>
<Step title="Verify the output is 4K">
```bash Terminal
ffprobe -v error -select_streams v:0 -show_entries stream=width,height my-video-4k.mp4
```

Expected:
```
width=3840
height=2160
```
</Step>
</Steps>

## Resolution presets

`--resolution` accepts these values on both `init` and `render`:

| Preset | Dimensions | Aliases |
|--------|-----------|---------|
| `landscape` | 1920×1080 | `1080p`, `hd` |
| `portrait` | 1080×1920 | `1080p-portrait` |
| `square` | 1080×1080 | `1080p-square`, `square-1080p` |
| `landscape-4k` | 3840×2160 | `4k`, `uhd` |
| `portrait-4k` | 2160×3840 | `4k-portrait` |
| `square-4k` | 2160×2160 | `4k-square` |

Examples:

```bash Terminal
npx hyperframes render --resolution 4k # landscape 4K
npx hyperframes render --resolution portrait-4k # vertical 4K (TikTok / Reels at max quality)
npx hyperframes render --resolution 1080p # explicit 1080p (no-op on 1080p compositions)
```

## How `--resolution` works (supersampling)

The composition stays at its authored dimensions. Hyperframes computes a `deviceScaleFactor` from the ratio of output to composition dimensions and passes it to Chrome:

| Composition | `--resolution` | `deviceScaleFactor` | Output |
|-------------|---------------|--------------------|--------|
| 1920×1080 | `4k` | 2 | 3840×2160 |
| 1080×1920 | `portrait-4k` | 2 | 2160×3840 |
| 3840×2160 | `4k` | 1 (no-op) | 3840×2160 |

Chrome then renders the page at the higher DPR — effectively rendering each CSS pixel as 2×2 device pixels — so the captured screenshot is at the requested resolution.
## Render an existing project in 4K

<Tip>
This approach is intentionally simple — no composition edits, no second authoring pass. The tradeoff: 4K renders take roughly 4× as long per frame because there are 4× the pixels to capture and encode.
</Tip>

## What scales, what doesn't

Supersampling re-renders the page at higher DPR. That genuinely helps anything the browser rasterizes from a vector or high-resolution source, and does nothing for content already locked to a fixed pixel grid. Knowing which is which sets correct expectations before a 4K render:
```bash
npx hyperframes render --resolution 4k --output final-4k.mp4
```

| Asset type | Behavior at `--resolution 4k` |
|------------|------------------------------|
| Text (HTML, SVG `<text>`, web fonts) | ✅ **Re-rasterized at 4K.** Glyphs are vector and the browser shapes/rasterizes them at the new DPR. Crisp at any scale. |
| SVG / vector graphics | ✅ **Re-rasterized at 4K.** Same story as text — paths are vector. |
| CSS shapes, gradients, borders, shadows | ✅ **Re-rasterized at 4K.** Browser-generated raster. |
| Images with intrinsic dimensions ≥ 4K | ✅ **Full benefit.** A 3840×2160 source serves all the detail. |
| Images smaller than 4K (e.g. a 1920×1080 PNG) | ⚠️ **No new detail.** Browser upscales the source bitmap; output is no sharper than rendering at 1080p and upscaling externally — but no worse either. |
| `<video>` elements | ❌ **Locked to source resolution.** A 1080p MP4 stays 1080p; the supersample only helps the surrounding DOM. Encode source video at the target resolution if you need 4K throughout. |
| `<canvas>` (2D and WebGL) | ❌ **Locked to canvas's intrinsic dimensions.** `<canvas width="1920" height="1080">` is a 1080p bitmap regardless of DPR. To render canvas content at 4K, multiply `canvas.width` / `canvas.height` by your target DPR and scale the drawing context (`ctx.scale(2, 2)` for a 2× canvas with the same logical layout). |
| Pre-rendered video frames injected by the engine | ❌ **Locked to extraction resolution.** When the producer pre-extracts `<video>` frames via ffmpeg, they're decoded at the source video's dimensions. |
HyperFrames keeps the composition's layout unchanged and captures it at a higher device-pixel ratio. A 1920×1080 composition becomes a 3840×2160 file.

**Rule of thumb**: if the asset is *vector or generated by the browser*, supersampling helps. If it's a *bitmap with fixed pixel dimensions* (video, canvas, low-res PNG), it doesn't — author it at the target resolution instead.
Use the matching preset for portrait or square work:

## Constraints
| Preset | Output |
| --- | --- |
| `4k` or `landscape-4k` | 3840×2160 |
| `portrait-4k` | 2160×3840 |
| `square-4k` | 2160×2160 |

`--resolution` enforces three guards before any frames are captured. If any fail, the render exits before doing work.
## Author a project at 4K

### Aspect ratio must match
If the project should use a 4K canvas from the start:

```bash
# OK — both landscape
hyperframes render --resolution 4k # composition is 1920×1080

# Error — composition is landscape, target is portrait
hyperframes render --resolution portrait-4k # composition is 1920×1080
# → outputResolution portrait-4k (2160×3840) does not match the aspect ratio
# of the composition (1920×1080). Pick a preset whose orientation matches.
npx hyperframes init my-video --resolution 4k
```

### The scale must be an integer

The width ratio (output ÷ composition) must be a positive integer. 1080p → 4K is exactly `2×`. 720p → 4K would be `3×` and works. Non-integer scales like 900p → 4K (`2.4×`) introduce aliasing on subpixel-positioned text — Hyperframes refuses rather than producing a blurry render.

### Downsampling is not supported

`--resolution` only supersamples. A 4K composition cannot be downsampled to 1080p with this flag — render at the composition's native resolution and downscale separately with ffmpeg if needed.

### Not yet supported with `--hdr`
Choose this when canvas or WebGL code, fixed-resolution media, or layout decisions need to know the final pixel dimensions while you author.

The HDR layered compositor processes pixel buffers at composition dimensions; supersample + HDR would need parallel scaling for those buffers. The combination is rejected with a clear error message. Render in two passes if you need both: HDR at composition resolution, then upscale separately.
## What gets sharper

## Performance
| Content | Result when supersampled |
| --- | --- |
| HTML text, SVG, CSS shapes, gradients | Re-rasterized at 4K |
| High-resolution images | Use their available source detail |
| 1080p images and video | Scaled up; no new source detail |
| `<canvas>` and WebGL | Limited by the canvas's intrinsic dimensions |

A 1080p → 4K supersample is roughly 4× more pixels to capture, encode, and write. Expect:
For a fully sharp 4K result, use 4K source media and size canvas/WebGL buffers for the target resolution.

- **Per-frame capture**: 3–4× slower (Chrome paints 4× the pixels and the screenshot transfer is 4× larger)
- **Encoding**: 2–3× slower (depends on codec; H.264 scales sublinearly with resolution)
- **Memory**: bounded — the engine's frame data-URI cache is byte-budgeted (default 1500 MB per worker, configurable via `PRODUCER_FRAME_DATA_URI_CACHE_BYTES_MB`)
- **Output file size**: at the default CRF, expect 3–5× the file size of the 1080p render. Pass `--video-bitrate 25M` (or higher) for predictable file sizes.

For a 4K render of a 30-second composition, plan on a few minutes of wall time on a modern laptop. Add `--workers 4` (or more) on a render box for parallel capture.
## Constraints

## Studio support
`--resolution` only works when:

The Renders panel in Studio includes a resolution dropdown next to the format and quality selectors. Pick `4K` (or `4K ↕` for portrait) and hit **Export** — the same supersampling path runs as the CLI flag, no composition edits required.
- the preset has the same aspect ratio as the composition;
- the target is an integer multiple of the authored dimensions;
- the target is not smaller than the composition;
- the output is MP4 rather than an alpha format;
- HDR is not forced for the same render.

The dropdown defaults to `Auto` (render at the composition's authored size). Available presets:
HyperFrames checks these conditions before opening the browser. Render at the composition's native size and resize separately when a combination is unsupported.

- **Auto** — composition's native dimensions
- **1080p ↔** / **1080p ↕** — 1920×1080 / 1080×1920
- **4K ↔** / **4K ↕** — 3840×2160 / 2160×3840
## Verify the file

The resolution applies per render, not per project — your composition files are unchanged. The same [constraints](#constraints) apply; when the producer rejects a combination, the failure surfaces in the Studio render queue.
```bash
ffprobe -v error -select_streams v:0 \
-show_entries stream=width,height final-4k.mp4
```

You can also drive resolution from the CLI:
For landscape 4K, the output should report `3840` by `2160`.

- **New project**: `hyperframes init my-video --resolution 4k`
- **Existing project**: `hyperframes render --resolution 4k --output 4k.mp4`
4K captures four times as many pixels as 1080p, so expect more render time, memory use, and output data. Start with `--quality draft` for review, then render the approved version at the quality you need.

## See also
## Related topics

- [`render` CLI reference](/packages/cli#render) — every render flag including `--video-bitrate` and `--crf`
- [`init` CLI reference](/packages/cli#init) — the `--resolution` flag at scaffold time
- [HDR Rendering](/guides/hdr) — color pipeline guide; HDR + 4K is not yet a supported combination
- [Render from the command line](/guides/rendering)
- [Improve render performance](/guides/performance)
- [Deliver an HDR project](/guides/hdr)
58 changes: 46 additions & 12 deletions docs/guides/authentication.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,12 @@
---
title: Authentication & API keys
description: "Sign in to HeyGen, and how the keys for voice, music, and capture resolve across the CLI and skills — including the priority order and the fully local fallback."
description: "Sign in to HeyGen and understand how agent workflows choose voice, music, sound, and optional capture-description providers."
---

HyperFrames uses a HeyGen credential for premium voiceover (TTS) and the music / sound-effects library. Other providers are optional, and **everything runs without any key** — voice and music fall back to fully local engines. This page covers signing in, the keys each capability uses, and the order they resolve.
You can create and render locally without an account. Voice and music can fall
back to local engines when no provider key is available. Sign in when you want
HeyGen voice and music, managed cloud rendering, hosted MCP, or ownership of a
published project that you can update later.

## Sign in

Expand Down Expand Up @@ -37,41 +40,68 @@ Signing in is the same OAuth step as creating an account — new users land on t
The credential lives in `~/.heygen/credentials` (mode `0600`) — no per-repo `.env` to manage. Browser OAuth is a `hyperframes auth login` feature. The separate [`heygen` CLI](https://github.com/heygen-com/heygen-cli) (its own install — there's no `npx heygen`) is API-key-only, so `heygen auth login` just stores a key you paste. Both read the same `~/.heygen/credentials`, so signing in with one carries to the other.

<Tip>
No account needed to try HyperFrames. With no credential, voice uses **Kokoro** and music uses **MusicGen**, both fully local and offline — see [Working offline](#working-offline).
No account is needed to try HyperFrames locally. With no credential, voice can
use **Kokoro** and music can use **MusicGen** — see [Working
offline](#working-offline).
</Tip>

## How credentials resolve
## How the HeyGen credential resolves

The HeyGen credential drives TTS and music / SFX **retrieval**. It resolves first-match-wins:
Bundled media workflows use the HeyGen credential for hosted TTS and music /
sound retrieval. It resolves first-match-wins:

1. `HEYGEN_API_KEY` — environment variable
2. `HYPERFRAMES_API_KEY` — alias, for parity with other tools
3. `~/.heygen/credentials` — written by `hyperframes auth login` (or `heygen auth login`)

Point at a different config directory with `HEYGEN_CONFIG_DIR`, or a different backend with `HEYGEN_API_URL`.

## Keys by capability
## Providers used by agent workflows

Each capability picks the **first available provider** in order; the last is always a local engine that needs no key. Cloud providers below the HeyGen line need their own key *and* a local Python dependency.
After the workflow's sign-in preflight, each media capability uses the first
available provider in its order. Voice, music, and sound have offline
fallbacks; capture descriptions are optional and are skipped when no supported
vision key is available.

| Capability | Provider order | Key(s) — first match wins | Local dependency |
|------------|----------------|---------------------------|------------------|
| **Voice (TTS)** | HeyGen → ElevenLabs → Kokoro | `HEYGEN_API_KEY` → `HYPERFRAMES_API_KEY` → `~/.heygen` · then `ELEVENLABS_API_KEY` | Kokoro: `pip install kokoro-onnx soundfile` |
| **Music (BGM)** | HeyGen library → Lyria → MusicGen | HeyGen credential (above) · then `GEMINI_API_KEY` → `GOOGLE_API_KEY` | MusicGen: `pip install transformers torch soundfile numpy` |
| **Sound effects** | HeyGen library → bundled library | HeyGen credential (above) | bundled — no deps |
| **Capture descriptions** | OpenRouter → Gemini | `OPENROUTER_API_KEY` → `GEMINI_API_KEY` | — (optional; for [website capture](/guides/website-to-video)) |
| **Capture descriptions** | OpenRouter → Gemini | `OPENROUTER_API_KEY` → `GEMINI_API_KEY` | None; optional for [website capture](/guides/product-launch-video) |

Run `npx hyperframes doctor` to check which local dependencies are installed. The media skills also run `hyperframes auth status` as a preflight before generating, so you always know whether a run will use HeyGen or a local engine before it starts.
Run `npx hyperframes doctor` to check which local dependencies are installed.
The media workflows run `hyperframes auth status` before generation and tell
you which path they will use.

<Note>
`npx hyperframes tts` itself is the local Kokoro CLI. Hosted HeyGen and
ElevenLabs voices are selected by the bundled media workflow helpers, not by
that command.
</Note>

## Working offline

No key configured is a normal state, not an error. The workflow runs entirely on local models:
No key configured is a normal state for local work. After their dependencies
and model files are installed, these fallbacks run locally:

- **Voice** — Kokoro-82M (54 voices), with Whisper for word-level caption alignment.
- **Music** — MusicGen (`facebook/musicgen-small`).
- **Sound effects** — a bundled library.

Local engines are free and offline; HeyGen gives higher-quality voices and a professionally produced music library. Sign in any time to switch a project from local to HeyGen.
Local engines do not call a hosted generation API after setup. Their first use
may download model files. HeyGen provides managed voices and a produced music
library; sign in when you want those services or cloud rendering.

## Publishing without an account

`npx hyperframes publish` works while signed out. It uploads the project and
prints a URL containing a claim token. Open that URL and authenticate in the web
app to claim the project.

Sign in with `npx hyperframes auth login` before publishing when you want the CLI
to own the project immediately, update the same URL with `--update`, or publish
to a shared space with `--space`.

## Environment variables

Expand All @@ -85,4 +115,8 @@ Local engines are free and offline; HeyGen gives higher-quality voices and a pro
| `GEMINI_API_KEY` / `GOOGLE_API_KEY` | Lyria music generation (and capture descriptions). |
| `OPENROUTER_API_KEY` | Capture descriptions; takes priority over Gemini for that step. |

See the [`hyperframes auth`](/packages/cli#hyperframes-auth) command reference for subcommand details, and [Cloud rendering](/deploy/cloud) for using the same credential to render in HeyGen's cloud.
## Related topics

- [Open the authentication command reference](/packages/cli#hyperframes-auth)
- [Render with HyperFrames Cloud](/deploy/cloud)
- [Choose where to create](/guides/choose-creation-path)
10 changes: 5 additions & 5 deletions docs/guides/claude-design-hyperframes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -523,7 +523,7 @@ composition with `-c` rather than as a bare path.
npx hyperframes render -o output.mp4
```

1920x1080 / 30fps by default. Use `--fps 60` or `--resolution 3840x2160` to override.
1920x1080 / 30fps by default. Use `--fps 60` or `--resolution 4k` to override.
````

### Skeleton A -- Social Reel (1080x1920, 15s, 6 scenes)
Expand Down Expand Up @@ -1231,8 +1231,8 @@ tl.to("#s5-headline", { backgroundSize: "100% 30%", duration: 0.6, ease: "power2
Everything critical is inlined above. These are for edge cases:

- Core composition contract (data attributes, sub-comp wiring): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes/SKILL.md
- Motion theory (easing as emotion, direction rules): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes/references/motion-principles.md
- Typography (full banned list, weight contrast, OpenType): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes/references/typography.md
- Transitions (shader catalog, CSS transition patterns): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes/references/transitions.md
- Captions synced to audio: https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes/references/captions.md
- Motion theory (easing as emotion, direction rules): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes-creative/references/motion-principles.md
- Typography (full banned list, weight contrast, OpenType): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes-creative/references/typography.md
- Transitions (shader catalog, CSS transition patterns): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes-animation/transitions/overview.md
- Captions synced to audio: https://github.com/heygen-com/hyperframes/blob/main/skills/embedded-captions/SKILL.md
- Full docs: https://hyperframes.heygen.com/
Loading
Loading