Skip to content

Commit eb199bd

Browse files
committed
docs: make the two hardest-reading pages readable, and draw the two core concepts
**Prompting.** These were the only two pages that stayed hard to read once the sentence counter was corrected for bullet lists. Capstone went from 46% of sentences over 28 words to 20%, and 53 semicolons to 42. Motion went from 37% to 15%, 26 semicolons to 4, and lost six table rows that were prose in a grid. Both keep every technique and every worked example — the length barely moved, the sentences did. **Concepts.** Compositions and Determinism explain how the whole thing works and showed the reader nothing. Each has one mermaid diagram now: how an HTML file with data-* timing becomes a numbered sequence of frames, and why frame 90 always comes out the same — what is locked before frame 0, and the three things that break it. Mermaid renders natively in Mintlify, so these cost no asset, no CDN upload and no regeneration. Verified in the browser rather than assumed; the pattern is the one proven on concepts/frame-adapters.
1 parent 8762887 commit eb199bd

4 files changed

Lines changed: 524 additions & 283 deletions

File tree

‎docs/concepts/compositions.mdx‎

Lines changed: 229 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,76 +1,250 @@
11
---
2-
title: "Understand compositions"
3-
sidebarTitle: "Compositions"
4-
description: "See how a HyperFrames project divides a video into timed, reusable parts."
2+
title: Compositions
3+
description: "The fundamental building block of a Hyperframes video."
54
---
65

7-
A composition is a piece of a HyperFrames project with its own size and timeline. The main composition is the finished sequence. Other compositions can be scenes, captions, title systems, or reusable visual parts inside it.
6+
A composition is an HTML file that describes a video. You write elements, give
7+
them `data-*` timing attributes, and the framework turns them into frames.
88

9-
```text
10-
Main video
11-
├── Opening
12-
├── Product demo
13-
├── Customer quote
14-
└── Closing
15-
```
16-
17-
Each part is still HTML. Studio, the agent, and normal code tools all work on the same files.
18-
19-
## What a composition controls
20-
21-
A composition brings three things together:
9+
`index.html` is the top-level composition. It can hold other compositions
10+
inside it. There is no special "root" type — any composition can be imported
11+
into any other.
2212

23-
- **content** — text, shapes, images, video, audio, or another composition;
24-
- **time** — when each part starts and how long it remains;
25-
- **motion** — seekable animation tied to the same playhead.
13+
## How an HTML file becomes frames
2614

27-
The main composition also defines the output frame and total duration.
15+
Here is a whole video: a logo, then a video clip.
2816

29-
## When to create another composition
30-
31-
Separate a part when it has a clear job and can be understood on its own.
32-
33-
Good boundaries include:
34-
35-
- a complete scene;
36-
- a repeated title or caption treatment;
37-
- a product-demo sequence;
38-
- a visual reused in several places;
39-
- a complex section that is easier to review separately.
17+
```html index.html
18+
<div id="root" data-composition-id="root"
19+
data-start="0" data-width="1920" data-height="1080">
20+
<img class="clip" src="assets/logo.png"
21+
data-start="0" data-duration="2" data-track-index="0" />
22+
<video class="clip" src="assets/video.mp4"
23+
data-start="2" data-duration="3" data-track-index="0"></video>
24+
</div>
25+
```
4026

41-
Do not split every small element into its own file. Extra nesting makes a simple project harder to follow.
27+
Two rules make that work. The outer element needs `data-composition-id`, and
28+
every timed element needs `class="clip"` so the runtime can hide it outside its
29+
own window of time.
4230

43-
## How nesting works
31+
The clips add up to five seconds. At 30 frames per second — the default — that
32+
is 150 frames, numbered 0 to 149:
4433

45-
The main composition gives each nested composition a place on its timeline:
34+
```mermaid
35+
flowchart TD
36+
A["index.html<br/>img: start 0, duration 2<br/>video: start 2, duration 3"]
37+
A --> B["One timeline, 5 seconds<br/>30 fps = 150 frames"]
38+
B --> C["frames 0-59<br/>image on screen"]
39+
B --> D["frames 60-149<br/>video on screen, playing<br/>from its own second 0"]
40+
```
4641

47-
```html
42+
Nothing plays in real time during a render. The renderer asks for frame 0, then
43+
frame 1, and each answer is a single still picture. That is what makes
44+
[rendering deterministic](/concepts/determinism).
45+
46+
## What can go on the timeline
47+
48+
A clip is any element with timing attributes on it:
49+
50+
- `<video>` — video clips, B-roll, A-roll
51+
- `<img>` — stills and overlays
52+
- `<audio>` — music and sound effects
53+
- `<div data-composition-id="...">` — another composition nested inside this one
54+
55+
The [Data attributes](/concepts/data-attributes) page lists every timing
56+
attribute. The [HTML schema](/reference/html-schema) has the full contract.
57+
58+
## Put one composition inside another
59+
60+
You can either point at a separate file or write the nested composition inline.
61+
Use a separate file when you want to reuse it.
62+
63+
<Tabs>
64+
<Tab title="External file">
65+
`data-composition-src` names the file. The framework fetches it, pulls the
66+
content out of its `<template>` tag, mounts it, runs its scripts, and
67+
registers its timeline.
68+
69+
Paths resolve from the **project root**, not from the file doing the
70+
referencing. So a composition nested one level deep still writes
71+
`compositions/foo.html`, never `../compositions/foo.html`.
72+
73+
```html index.html
74+
<div
75+
id="el-5"
76+
data-composition-id="intro-anim"
77+
data-composition-src="compositions/intro-anim.html"
78+
data-start="0"
79+
data-duration="4"
80+
data-playback-start="0"
81+
data-track-index="3"
82+
></div>
83+
```
84+
85+
The file it points at wraps everything in a `<template>`:
86+
87+
```html compositions/intro-anim.html
88+
<template id="intro-anim-template">
89+
<div data-composition-id="intro-anim" data-width="1920" data-height="1080">
90+
<div class="title">Welcome!</div>
91+
92+
<style>
93+
[data-composition-id="intro-anim"] .title {
94+
font-size: 72px; color: white; text-align: center;
95+
}
96+
</style>
97+
98+
<script>
99+
const tl = gsap.timeline({ paused: true });
100+
tl.from(".title", { opacity: 0, y: -50, duration: 1 });
101+
window.__timelines["intro-anim"] = tl;
102+
</script>
103+
</div>
104+
</template>
105+
```
106+
107+
`data-playback-start` picks which moment of the child timeline shows first.
108+
It defaults to `0`. Trimming or splitting from the left pushes this offset
109+
forward by the time elapsed multiplied by `data-playback-rate`, so the
110+
nested animation keeps going instead of jumping back to its beginning.
111+
</Tab>
112+
<Tab title="Inline">
113+
Write the nested composition straight into the parent. Simpler for
114+
something you only use once.
115+
116+
```html index.html
117+
<div id="root" data-composition-id="root"
118+
data-start="0" data-width="1920" data-height="1080">
119+
120+
<!-- Inline nested composition -->
121+
<div id="el-5" data-composition-id="intro-anim"
122+
data-start="0" data-track-index="3"
123+
data-width="1920" data-height="1080">
124+
<div class="title">Welcome!</div>
125+
</div>
126+
127+
<script>
128+
// Timeline for the inline composition
129+
const introTl = gsap.timeline({ paused: true });
130+
introTl.from(".title", { opacity: 0, y: -50, duration: 1 });
131+
window.__timelines["intro-anim"] = introTl;
132+
</script>
133+
</div>
134+
```
135+
136+
No `<template>` tag and no `data-composition-src` here.
137+
</Tab>
138+
</Tabs>
139+
140+
### Where the files live
141+
142+
<Tree>
143+
<Tree.Folder name="project" defaultOpen>
144+
<Tree.File name="index.html" />
145+
<Tree.Folder name="compositions" defaultOpen>
146+
<Tree.File name="intro-anim.html" />
147+
<Tree.File name="caption-overlay.html" />
148+
<Tree.File name="outro-title.html" />
149+
</Tree.Folder>
150+
<Tree.Folder name="assets">
151+
<Tree.File name="video.mp4" />
152+
<Tree.File name="music.mp3" />
153+
<Tree.File name="logo.png" />
154+
</Tree.Folder>
155+
</Tree.Folder>
156+
</Tree>
157+
158+
## HTML sets the timing, scripts do the motion
159+
160+
Your HTML says what plays, when, and on which track, all through
161+
[data attributes](/concepts/data-attributes). Your scripts handle the creative
162+
part: effects, transitions, canvas, SVG, [GSAP](/guides/gsap-animation)
163+
animation.
164+
165+
<Warning>
166+
Never use a script to play, pause, or seek a media element, and never use one
167+
to show or hide a clip based on time. The framework already does that from the
168+
data attributes, and a script doing it too will fight the framework. See
169+
[Common Mistakes](/guides/common-mistakes) for what that looks like.
170+
</Warning>
171+
172+
## Reuse one composition with different content
173+
174+
One source file can appear several times in the same video, each copy carrying
175+
its own text and colors. HyperFrames does not wire `data-var-*` attributes into
176+
your DOM or CSS for you — you do it in three steps:
177+
178+
1. Declare each variable — id, type, default — on the sub-composition's root
179+
with `data-composition-variables`. That root is the `<html>` element in a
180+
full-document composition, or the `[data-composition-id]` element in a
181+
template or fragment.
182+
2. Pass each copy's values on its host element with `data-variable-values`.
183+
3. Read them inside the composition with
184+
`window.__hyperframes.getVariables()`, which layers the host's values over
185+
the declared defaults, one copy at a time.
186+
187+
```html index.html
188+
<div
189+
data-composition-id="card-pro"
190+
data-composition-src="compositions/card.html"
191+
data-start="0"
192+
data-track-index="1"
193+
data-variable-values='{"title":"Pro","color":"#ff4d4f"}'
194+
></div>
48195
<div
49-
id="product-demo-host"
50-
data-composition-id="product-demo"
51-
data-composition-src="compositions/product-demo.html"
52-
data-start="4"
53-
data-duration="6"
196+
data-composition-id="card-enterprise"
197+
data-composition-src="compositions/card.html"
198+
data-start="card-pro"
54199
data-track-index="1"
55-
data-width="1920"
56-
data-height="1080"
200+
data-variable-values='{"title":"Enterprise","color":"#22c55e"}'
57201
></div>
58202
```
59203

60-
`data-composition-src` paths resolve from the project root, even when the referencing composition is inside another folder.
61-
62-
This tells HyperFrames to mount `product-demo.html` at four seconds and show a six-second window of it. The nested source keeps its own content and animation.
63-
64-
If the same source is mounted more than once, each instance can start at a different time or receive different [variables](/concepts/variables).
204+
The second card's `data-start="card-pro"` means "start when that one ends".
205+
206+
And the source file both cards share:
207+
208+
```html compositions/card.html
209+
<html data-composition-variables='[
210+
{"id":"title","type":"string","label":"Title","default":"Fallback"},
211+
{"id":"color","type":"color","label":"Color","default":"#111827"}
212+
]'>
213+
<body>
214+
<div data-composition-id="card" data-width="1920" data-height="1080">
215+
<h1 class="title"></h1>
216+
217+
<style>
218+
[data-composition-id="card"] .title { color: var(--card-color, #111827); }
219+
</style>
220+
221+
<script>
222+
const { title, color } = __hyperframes.getVariables();
223+
const root = document.querySelector('[data-composition-id="card"]');
224+
root.querySelector(".title").textContent = title;
225+
root.style.setProperty("--card-color", color);
226+
</script>
227+
</div>
228+
</body>
229+
</html>
230+
```
65231

66-
## Decide where to make a change
232+
[Variables](/concepts/variables) covers the types, the bindings that need no
233+
script, CLI overrides, and which value wins. If you are building tooling on
234+
`@hyperframes/core`, `extractCompositionMetadata()` reads the same
235+
`data-composition-variables` array — that is how Studio builds its editing UI.
67236

68-
- Edit the **nested composition** when the scene itself should change everywhere it is used.
69-
- Edit the **main composition** when only its placement, duration, or relationship to other scenes should change.
70-
- Ask the **agent** when a revision changes the story or crosses several compositions.
237+
## See every composition in a project
71238

72-
In Studio, open or expand a nested scene when you need to work inside it, then use the breadcrumb to return to the parent sequence.
239+
```bash
240+
npx hyperframes compositions
241+
```
73242

74-
## Continue
243+
## Related topics
75244

76-
Use [Variables](/concepts/variables) when the design should stay fixed while approved content changes. Use the [HTML schema](/reference/html-schema) when you need exact element and attribute rules.
245+
- [Data attributes](/concepts/data-attributes)
246+
- [Deterministic rendering](/concepts/determinism)
247+
- [Variables](/concepts/variables)
248+
- [Animate with GSAP](/guides/gsap-animation)
249+
- [HTML schema reference](/reference/html-schema)
250+
- [Start from an example](/examples)

0 commit comments

Comments
 (0)