Skip to content

Commit 005242c

Browse files
ukimsanovukimsanov
committed
docs: add the Studio section, workflow guides, and section hubs
Adds the pages the rebuilt navigation is organised around, and moves the sidebar onto that structure. Every entry points at a file that exists after this commit; nothing is rewritten or removed yet, and no redirect is claimed yet. - Studio (13 pages) — the editor had no section of its own - One guide per creation workflow, matching the shipped agent skills - Section hubs: Concepts, Catalog, Developers, Deploy, Workflows, Help, Go further, Product updates, 30 Days of HyperFrames Pages a later commit retires drop out of the sidebar here but still exist and still resolve, so the site stays navigable at this commit. Incidentally fixes a link to /concepts from the Lambda migration guide that is broken on main today — the destination did not exist.
1 parent 492952e commit 005242c

40 files changed

Lines changed: 3641 additions & 113 deletions

‎docs/catalog/index.mdx‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
title: "Catalog"
3+
description: "Browse reusable HyperFrames scenes, transitions, captions, overlays, effects, and components."
4+
---
5+
6+
The Catalog is a library of visuals you can add to a project instead of building each one from scratch.
7+
8+
Use a **block** when you want a larger scene or self-contained visual. Use a **component** when you want a smaller effect or behavior inside an existing scene.
9+
10+
## Start with the job
11+
12+
<CardGroup cols={2}>
13+
<Card title="Code animations" icon="code" href="/catalog/blocks/code-typing">
14+
Show code being typed, changed, highlighted, scrolled, or transformed.
15+
</Card>
16+
<Card title="Captions" icon="closed-captioning" href="/catalog/components/caption-highlight">
17+
Keep speech readable or emphasize selected words without designing a caption system from zero.
18+
</Card>
19+
<Card title="Transitions" icon="arrows-left-right" href="/catalog/blocks/cinematic-zoom">
20+
Move between scenes with a quiet cut treatment or a more expressive transition.
21+
</Card>
22+
<Card title="Social overlays" icon="share-nodes" href="/catalog/blocks/x-post">
23+
Show posts, follow prompts, notifications, names, roles, and platform-inspired cards.
24+
</Card>
25+
<Card title="Data and diagrams" icon="chart-column" href="/catalog/blocks/data-chart">
26+
Explain a number, comparison, trend, location, or geographic movement.
27+
</Card>
28+
<Card title="Complete scenes" icon="play" href="/catalog/blocks/app-showcase">
29+
Start from a larger scene that already combines design, media, and animation.
30+
</Card>
31+
</CardGroup>
32+
33+
## Use an item in a real project
34+
35+
1. Open an item and watch the motion preview.
36+
2. Check that its communication job matches the scene.
37+
3. Copy the plain-language request from the item page into your agent chat.
38+
4. Replace the example content with real project content.
39+
5. Match the project's type, color, spacing, and motion language.
40+
6. Review the item inside the complete video, not only in isolation.
41+
42+
The terminal command and source details remain available on each item page for people who need them.
43+
44+
## Before you keep it
45+
46+
<Note>
47+
A Catalog item is a starting point, not a finished design decision. Keep it only when it makes the scene clearer or faster to understand. Remove decorative motion that competes with the story.
48+
</Note>
49+
50+
Check:
51+
52+
- Can the viewer understand why the visual is present?
53+
- Is the real content readable at the final size?
54+
- Does its timing fit the scenes around it?
55+
- Does it feel like part of this project rather than a pasted demo?
56+
- Is a quieter alternative more effective?
57+
58+
## Related topics
59+
60+
- [Add Catalog items in Studio](/studio/assets-and-blocks)
61+
- [Build richer compositions](/go-further)
62+
- [Contribute a Catalog item](/contributing/catalog)

‎docs/concepts/index.mdx‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
---
2+
title: "How a HyperFrames project works"
3+
sidebarTitle: "Project model"
4+
description: "Understand the editable files, compositions, timing, and tools behind a HyperFrames video."
5+
---
6+
7+
A HyperFrames project is a folder your agent can create and you can keep
8+
editing. Its HTML is the video: it describes the scenes, timing, motion, media,
9+
and reusable parts that HyperFrames plays or renders.
10+
11+
## The source is the project
12+
13+
The agent, Studio, CLI, SDK, and Player do not create separate versions of the
14+
video. They work with the same project files.
15+
16+
| What you want to change | Best place to start |
17+
| ---------------------------------------------------- | ------------------- |
18+
| Story, structure, or several scenes | Ask the agent |
19+
| Text, layout, timing, or animation you can see | Studio |
20+
| Preview, checks, snapshots, rendering, or automation | CLI |
21+
| A composition inside your own product | SDK or Player |
22+
23+
<div style={{ maxWidth: "42rem", margin: "1.5rem auto" }}>
24+
<Frame caption="The same editable project open in Studio, with its source, canvas, controls, and timeline.">
25+
<img
26+
src="https://static.heygen.ai/hyperframes-oss/docs/images/studio/overview-v1.jpg"
27+
alt="A HyperFrames project open in Studio with the source tree, canvas, controls, and timeline"
28+
/>
29+
</Frame>
30+
</div>
31+
32+
Studio writes supported edits back into the source. An agent can continue from
33+
those files, Git can track them, and the renderer sees the same result.
34+
35+
## What the agent creates
36+
37+
A larger project often looks like this:
38+
39+
```text
40+
project/
41+
├── BRIEF.md what the video must communicate
42+
├── STORYBOARD.md the planned sequence and review state
43+
├── SCRIPT.md locked narration, when the video has it
44+
├── frame.md visual direction, when the project needs one
45+
├── index.html the main composition
46+
├── hyperframes.json project settings
47+
├── compositions/ scenes and reusable visual parts
48+
├── assets/ images, video, audio, and fonts
49+
└── renders/ finished files
50+
```
51+
52+
Only the project source is essential. Planning files exist to preserve decisions
53+
across reviews and agent sessions. A simple title card may need only
54+
`index.html` and an asset; a narrated launch film benefits from a brief,
55+
storyboard, script, and separate scenes.
56+
57+
## Compositions hold the video together
58+
59+
A **composition** is a finite, seekable piece of the project. The main
60+
composition is the complete sequence. Other compositions can be scenes,
61+
captions, title systems, or visuals reused more than once.
62+
63+
```text
64+
Main video
65+
├── Opening
66+
├── Product demo
67+
├── Customer proof
68+
└── Closing
69+
```
70+
71+
Each part is still HTML. A larger project stays manageable because a scene can
72+
be built and checked on its own, then placed on the main timeline.
73+
74+
```html
75+
<div
76+
data-composition-id="product-demo"
77+
data-composition-src="compositions/product-demo.html"
78+
data-start="4"
79+
data-duration="6"
80+
data-track-index="1"
81+
></div>
82+
```
83+
84+
Edit the nested composition when the scene itself should change everywhere it
85+
is used. Edit its placement in the main composition when only this appearance
86+
should start earlier, run longer, or move to another layer.
87+
88+
## Time is part of the source
89+
90+
Timed elements carry their start, duration, and track in HTML:
91+
92+
```html
93+
<img
94+
id="product-shot"
95+
class="clip"
96+
data-start="2"
97+
data-duration="3"
98+
data-track-index="1"
99+
src="./assets/product.png"
100+
/>
101+
```
102+
103+
This image starts at two seconds, remains for three seconds, and appears on
104+
track one. Animation timelines are paused and seekable, so Studio, the Player,
105+
and the renderer can request an exact moment without playing from the
106+
beginning.
107+
108+
## Variables keep approved parts changeable
109+
110+
A variable exposes something that is meant to change—such as a title, logo,
111+
color, price, or customer name—without rebuilding the layout. One composition
112+
can produce several approved versions while preserving its design and motion.
113+
114+
Use a variable when the structure should stay fixed. Use a normal edit when the
115+
structure itself needs to change.
116+
117+
## How a project moves forward
118+
119+
There is no required seven-step ceremony. The project records only the
120+
decisions its size and review process need.
121+
122+
| Decision | Where it usually lives |
123+
| ------------------------------ | ----------------------------------------------------------- |
124+
| What the video is for | Your request and, for a fuller project, `BRIEF.md` |
125+
| What happens and in what order | `STORYBOARD.md` and optional `SCRIPT.md` |
126+
| How it looks | `frame.md`, project assets, and the compositions themselves |
127+
| The editable result | `index.html`, `compositions/`, and `assets/` |
128+
| The approved delivery | checks plus the file in `renders/` |
129+
130+
Review the message and sequence before polishing individual frames. Once the
131+
project looks right, run the checks, render it, and watch the exported file.
132+
133+
## Why rendering can repeat the same moment
134+
135+
HyperFrames seeks the composition to an exact time, captures the frame, and
136+
advances. Media and audio follow the same timeline.
137+
138+
For the same source, media, and settings, an exact timestamp should resolve to
139+
the same project state. Compositions therefore avoid the current clock,
140+
unseeded randomness, and render-time network requests.
141+
142+
## Go deeper when you need it
143+
144+
<CardGroup cols={2}>
145+
<Card title="Reuse a design with variables" icon="sliders" href="/concepts/variables">
146+
Expose approved content without opening the layout.
147+
</Card>
148+
<Card title="Finish and share a video" icon="circle-check" href="/guides/export-and-share">
149+
Review, check, render, watch, and deliver the same project.
150+
</Card>
151+
<Card title="Composition structure" icon="layer-group" href="/concepts/compositions">
152+
Use nested compositions and exact source attributes.
153+
</Card>
154+
<Card title="HTML schema" icon="code" href="/reference/html-schema">
155+
Look up the complete technical composition contract.
156+
</Card>
157+
</CardGroup>
158+
159+
## Related topics
160+
161+
- [Take more control of an existing project](/go-further)
162+
- [Look up the complete HTML schema](/reference/html-schema)
163+
- [Choose a developer integration surface](/developers/overview)

‎docs/deploy/overview.mdx‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
---
2+
title: "Choose a rendering path"
3+
sidebarTitle: "Rendering overview"
4+
description: "Choose the smallest HyperFrames rendering surface for local work, an application backend, managed cloud, or infrastructure you operate."
5+
---
6+
7+
Every rendering path starts with the same HyperFrames project. The difference is
8+
who operates Chrome and FFmpeg, how the request is submitted, and how much of the
9+
pipeline your application needs to control.
10+
11+
| Need | Start with | You operate |
12+
| --- | --- | --- |
13+
| Render while creating or in CI | **CLI** | The machine running the command |
14+
| Render from a Node application | **Producer** | The Node service and its runtime |
15+
| Control exact frame capture | **Engine** | Capture, encoding, and orchestration |
16+
| Submit a render without managing infrastructure | **HyperFrames Cloud** | Nothing beyond the request and result |
17+
| Run distributed renders in your AWS account | **AWS Lambda** | The deployed AWS stack |
18+
| Run distributed renders in your Google Cloud account | **Cloud Run** | The deployed GCP resources |
19+
| Deploy a preview and render API from a template | **Hosted templates** | The selected hosting account |
20+
21+
## Local or CI: use the CLI
22+
23+
The CLI owns the complete normal pipeline: project loading, checks, browser
24+
capture, audio mixing, and encoding.
25+
26+
```bash
27+
npx hyperframes check
28+
npx hyperframes render --output video.mp4
29+
```
30+
31+
Start here unless an application—not a person or CI job—must initiate the
32+
render. See [Rendering](/guides/rendering) for the normal workflow and the
33+
[complete CLI reference](/packages/cli) for automation flags.
34+
35+
## A Node application: use Producer
36+
37+
`@hyperframes/producer` is the complete programmable render pipeline. It is the
38+
right layer for a backend that needs to provide project input, receive progress,
39+
cancel work, or control encoding without spawning the CLI.
40+
41+
```ts
42+
import { createRenderJob, executeRenderJob } from "@hyperframes/producer";
43+
44+
const job = createRenderJob({ fps: 30, quality: "standard" });
45+
await executeRenderJob(job, "./project", "./video.mp4");
46+
```
47+
48+
Use [Producer](/packages/producer) for its current configuration and exported
49+
API. Use Engine only when Producer performs work your application must replace.
50+
51+
## Exact frame capture: use Engine
52+
53+
`@hyperframes/engine` opens a seekable composition and captures exact frames.
54+
It does not replace the complete Producer pipeline.
55+
56+
Use it when building specialized capture, inspection, or rendering
57+
infrastructure. For an ordinary encoded video, stay with CLI or Producer. See
58+
[Engine](/packages/engine).
59+
60+
## No infrastructure: use HyperFrames Cloud
61+
62+
Managed cloud rendering accepts a project, runs the render, and returns the
63+
finished file without requiring local Chrome or FFmpeg.
64+
65+
```bash
66+
npx hyperframes cloud render ./project --output video.mp4
67+
```
68+
69+
Authentication, variables, webhooks, and job management are covered in
70+
[Cloud rendering](/deploy/cloud).
71+
72+
## Infrastructure you control
73+
74+
Use [AWS Lambda](/deploy/aws-lambda) or [Google Cloud Run](/deploy/gcp-cloud-run)
75+
when renders must run inside your own cloud account. Both paths distribute work
76+
across workers and store intermediate and final media in the corresponding
77+
cloud storage.
78+
79+
Use the [hosted templates](/guides/deploy) when the desired result is a small
80+
preview application plus a render API on Vercel, Cloudflare, or Modal—not a
81+
general distributed-rendering platform.
82+
83+
## The decision
84+
85+
Choose the highest-level surface that completes the job:
86+
87+
```text
88+
CLI → Producer → Engine
89+
```
90+
91+
Moving right gives an application more control and more pipeline responsibility.
92+
Managed Cloud, AWS Lambda, Cloud Run, and hosted templates decide where that
93+
pipeline runs.
94+
95+
## Related topics
96+
97+
- [Render with the CLI](/guides/rendering)
98+
- [Render with HyperFrames Cloud](/deploy/cloud)
99+
- [Use Producer from a Node application](/packages/producer)

‎docs/developers/cli.mdx‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
title: "CLI guide"
3+
description: "Find the HyperFrames command for creating, checking, rendering, publishing, and automating projects."
4+
---
5+
6+
Use this page to choose a command. The [CLI reference](/packages/cli) contains
7+
detailed flags, examples, and environment settings. The installed version
8+
remains authoritative: run `npx hyperframes <command> --help`.
9+
10+
## Everyday project loop
11+
12+
| Task | Command |
13+
| --- | --- |
14+
| Create a project | `npx hyperframes init my-video` |
15+
| Open Studio | `npx hyperframes preview` |
16+
| Check HTML structure | `npx hyperframes lint` |
17+
| Run browser, layout, motion, and contrast checks | `npx hyperframes check` |
18+
| Capture review frames | `npx hyperframes snapshot --at 0,2,5` |
19+
| Render a video | `npx hyperframes render --output output.mp4` |
20+
| Publish a browser link | `npx hyperframes publish` |
21+
| Diagnose the machine | `npx hyperframes doctor` |
22+
23+
## Work with media
24+
25+
| Task | Command |
26+
| --- | --- |
27+
| Inspect project metadata | `npx hyperframes info` |
28+
| Transcribe speech | `npx hyperframes transcribe <file>` |
29+
| Generate narration | `npx hyperframes tts <script>` |
30+
| Capture a website | `npx hyperframes capture <url>` |
31+
32+
## Reuse and inspect
33+
34+
| Task | Command |
35+
| --- | --- |
36+
| Add a Catalog item | `npx hyperframes add <name>` |
37+
| List compositions | `npx hyperframes compositions` |
38+
| Inspect keyframe behavior | `npx hyperframes keyframes` |
39+
| Compare outputs | `npx hyperframes compare` |
40+
41+
## Rendering and automation
42+
43+
The CLI also supports:
44+
45+
- batch and variable-driven output;
46+
- image sequences and several video formats;
47+
- managed cloud rendering;
48+
- AWS Lambda and Google Cloud Run workflows;
49+
- machine-readable JSON output;
50+
- publishing and shared spaces.
51+
52+
Start with the simple command, then open the [full reference](/packages/cli) for the exact options needed by automation or infrastructure.
53+
54+
<Tip>
55+
Run `npx hyperframes <command> --help` for the installed version’s exact syntax.
56+
</Tip>
57+
58+
## Related topics
59+
60+
- [Open the complete CLI reference](/packages/cli)
61+
- [Choose a rendering path](/deploy/overview)
62+
- [Diagnose a CLI or project problem](/guides/troubleshooting)

0 commit comments

Comments
 (0)