Workspace
A
Official VS Code built-in theme
Dark 2026
Typing `functional_toolkit.py` with workbench colors from 2026-dark.json.
◇ functional_toolkit.py
README.md
TerminalProblemsOutput
functional-toolkit % python -m pytest
collected 3 items
tests/test_toolkit.py ... passed
```
This image starts at two seconds, remains for three seconds, and appears on
track one. Animation timelines are paused and seekable, so Studio, the Player,
and the renderer can request an exact moment without playing from the
beginning.
## Variables keep approved parts changeable
A variable exposes something that is meant to change—such as a title, logo,
color, price, or customer name—without rebuilding the layout. One composition
can produce several approved versions while preserving its design and motion.
Use a variable when the structure should stay fixed. Use a normal edit when the
structure itself needs to change.
## How a project moves forward
There is no required seven-step ceremony. The project records only the
decisions its size and review process need.
| Decision | Where it usually lives |
| ------------------------------ | ----------------------------------------------------------- |
| What the video is for | Your request and, for a fuller project, `BRIEF.md` |
| What happens and in what order | `STORYBOARD.md` and optional `SCRIPT.md` |
| How it looks | `frame.md`, project assets, and the compositions themselves |
| The editable result | `index.html`, `compositions/`, and `assets/` |
| The approved delivery | checks plus the file in `renders/` |
Review the message and sequence before polishing individual frames. Once the
project looks right, run the checks, render it, and watch the exported file.
## Why rendering can repeat the same moment
HyperFrames seeks the composition to an exact time, captures the frame, and
advances. Media and audio follow the same timeline.
For the same source, media, and settings, an exact timestamp should resolve to
the same project state. Compositions therefore avoid the current clock,
unseeded randomness, and render-time network requests.
## Go deeper when you need it
```
* `data-var-text` replaces the element’s own text.
* `data-var-src` replaces an image, video, audio, or source URL.
* Scalar variables are available as CSS custom properties such as
`var(--accent)`.
Use `window.__hyperframes.getVariables()` only when the result needs conditions,
loops, or derived values:
```js theme={null}
const { featured = false } = window.__hyperframes.getVariables();
document.querySelector(".badge").hidden = !featured;
```
## Give each nested composition different values
A parent can reuse the same composition several times:
```html index.html theme={null}
```
Both instances keep the same source and receive different content.
## Advanced: render a version from data
Override top-level values from the CLI:
```bash theme={null}
npx hyperframes render \
--variables '{"title":"Enterprise","accent":"#22c55e"}' \
--strict-variables \
--output enterprise.mp4
```
Use `--variables-file` for a JSON file and `--batch` when the same composition
must render once per data row. The [CLI reference](/packages/cli) covers batch
output, validation, and automation.
### Batch renders
Put one variable object per row in a JSON array, then use placeholders from the
row to name each output:
```json rows.json theme={null}
[
{ "name": "acme", "title": "Acme Pro" },
{ "name": "northstar", "title": "Northstar Pro" }
]
```
```bash theme={null}
npx hyperframes render \
--batch rows.json \
--strict-variables \
--output "renders/{name}.mp4"
```
Start with the default single-row concurrency. Increase `--batch-concurrency`
only after one real render is stable and the machine has enough memory for
several renders at once.
## What can't be a variable
Variables change content inside a composition. They do not change:
* the composition viewport;
* the root composition’s total render duration;
* frame rate;
* output format, codec, or quality;
* a parent or sibling composition unless values are passed to it explicitly.
Those choices are read from source or render settings before composition logic
runs.
## Check the contract
Run:
```bash theme={null}
npx hyperframes lint
```
The linter catches malformed declarations, missing fields, wrong default types,
and invalid enum choices. `--strict-variables` turns undeclared or mistyped
render values into errors.
Continue to [Compositions](/concepts/compositions) for nesting or the
[HTML schema](/reference/html-schema) for the complete attribute contract.
# Contribute to HyperFrames
Source: https://hyperframes.heygen.com/contributing
Set up the repository, make a focused change, and open a pull request.
## Set up the repository
```bash theme={null}
git clone https://github.com/YOUR_USERNAME/hyperframes.git
cd hyperframes
bun install
bun run build
```
HyperFrames uses Bun for workspace operations. Do not add a `pnpm-lock.yaml` or replace `bun.lock`.
Start Studio while working on UI or composition behavior:
```bash theme={null}
bun run dev
```
Studio listens on `http://localhost:5190` when run from the monorepo.
## Check your change
Run the smallest relevant test while iterating, then the repository gates before opening a pull request:
```bash theme={null}
bun run lint
bun run format:check
bun run --filter '*' typecheck
bun run test
```
For a composition, run the gates from the project directory, or pass it:
```bash theme={null}
npx hyperframes lint ./my-video
npx hyperframes check ./my-video
```
Registry items need a different command. They ship as `