mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-14 18:01:20 +08:00
ukimsanov
84 lines
4.0 KiB
Plaintext
84 lines
4.0 KiB
Plaintext
---
|
|
title: "How a HyperFrames project works"
|
|
sidebarTitle: "Overview"
|
|
description: "Understand the project, composition, timing, variables, and rendering model behind every HyperFrames video."
|
|
---
|
|
|
|
A HyperFrames project is a normal folder of HTML compositions, media, fonts,
|
|
and settings. The agent writes it, Studio or the SDK can edit it, and
|
|
HyperFrames can play or render it frame by frame.
|
|
|
|
## Project, composition, element
|
|
|
|
The **project** is the complete working folder. It can contain several compositions, media files, narration, music, fonts, and rendered versions.
|
|
|
|
A **composition** is one finite, seekable HTML page. It might be the complete video, one scene, a caption layer, or a reusable element nested inside another composition.
|
|
|
|
An **element** is something inside a composition: text, a shape, an image, video, audio, or another composition.
|
|
|
|
```text
|
|
project
|
|
├── BRIEF.md agreed goal and direction, when useful
|
|
├── STORYBOARD.md planned sequence, when useful
|
|
├── SCRIPT.md narration or planned copy, when useful
|
|
├── index.html main composition
|
|
├── hyperframes.json project settings
|
|
├── compositions/ scenes and reusable compositions
|
|
├── assets/ video, images, audio, and fonts
|
|
└── renders/ finished files
|
|
```
|
|
|
|
Small projects may contain only `index.html` and a few assets. The planning
|
|
files are checkpoints for larger or collaborative work, not required ceremony.
|
|
|
|
Studio edits supported changes back into these files. It does not create a
|
|
separate proprietary project document, so an agent, Git, validation, and
|
|
rendering all see the same source.
|
|
|
|
## Time is written into the project
|
|
|
|
Clips carry their start, duration, and track in HTML. That is why Studio, the Player, the SDK, and the renderer can all agree on what should exist at an exact moment.
|
|
|
|
```html
|
|
<img
|
|
id="product-shot"
|
|
class="clip"
|
|
data-start="2"
|
|
data-duration="3"
|
|
data-track-index="1"
|
|
src="./assets/product.png"
|
|
/>
|
|
```
|
|
|
|
This image appears at two seconds, remains for three seconds, and sits on track one. Animation timelines are paused and seekable, so HyperFrames can request any frame without playing from the beginning.
|
|
|
|
## Compositions make larger projects manageable
|
|
|
|
A complete video can be one composition, but larger work is easier to understand when scenes or systems are separated. A title sequence, product demo, caption layer, and outro can each be built and checked independently, then assembled into the master composition.
|
|
|
|
Nested compositions also make useful parts reusable. Change the source once and every place using that composition receives the update.
|
|
|
|
## Variables separate content from design
|
|
|
|
Variables expose values such as a title, color, image, price, or customer name without requiring someone to rewrite the layout. One authored composition can then produce several versions while preserving its design and motion.
|
|
|
|
Use variables when the same structure should accept different approved inputs. Use a normal edit when the structure itself needs to change.
|
|
|
|
## A render is a repeatable playback
|
|
|
|
During rendering, HyperFrames seeks the project to an exact time, captures the frame, advances, and repeats. Media and audio follow the same timeline.
|
|
|
|
For the same inputs and settings, the same timestamp should produce the same result. That is why compositions avoid the current clock, unseeded randomness, and render-time network requests.
|
|
|
|
## Where each tool fits
|
|
|
|
| Need | Surface |
|
|
| ---------------------------------------- | ------- |
|
|
| Change the story or several source files | Agent |
|
|
| Make a visible or timing edit | Studio |
|
|
| Query or edit a composition in code | SDK |
|
|
| Embed and seek a live composition | Player |
|
|
| Validate, preview, or render | CLI |
|
|
|
|
Go deeper only when the task requires it: [compositions](/concepts/compositions), [variables](/concepts/variables), [timing attributes](/concepts/data-attributes), or [deterministic rendering](/concepts/determinism).
|