|
1 | 1 | --- |
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." |
5 | 4 | --- |
6 | 5 |
|
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. |
8 | 8 |
|
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. |
22 | 12 |
|
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 |
26 | 14 |
|
27 | | -The main composition also defines the output frame and total duration. |
| 15 | +Here is a whole video: a logo, then a video clip. |
28 | 16 |
|
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 | +``` |
40 | 26 |
|
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. |
42 | 30 |
|
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: |
44 | 33 |
|
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 | +``` |
46 | 41 |
|
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> |
48 | 195 | <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" |
54 | 199 | data-track-index="1" |
55 | | - data-width="1920" |
56 | | - data-height="1080" |
| 200 | + data-variable-values='{"title":"Enterprise","color":"#22c55e"}' |
57 | 201 | ></div> |
58 | 202 | ``` |
59 | 203 |
|
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 | +``` |
65 | 231 |
|
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. |
67 | 236 |
|
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 |
71 | 238 |
|
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 | +``` |
73 | 242 |
|
74 | | -## Continue |
| 243 | +## Related topics |
75 | 244 |
|
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