mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 16:08:56 +00:00
* docs(variables): say what can be a variable, including a video or sound per account * docs(variables): render the per-account example from index.html and keep the outline
279 lines
9.9 KiB
Plaintext
279 lines
9.9 KiB
Plaintext
---
|
||
title: "Reuse a design with variables"
|
||
sidebarTitle: "Variables"
|
||
description: "Change approved text, colors, media, and choices without rebuilding the composition."
|
||
---
|
||
|
||
Variables expose the parts of a composition that are meant to change. One
|
||
customer card can accept a different name, logo, color, and plan while keeping
|
||
the same layout and motion.
|
||
|
||
Use a variable when the design should remain stable across versions. Make a
|
||
normal source edit when the structure itself needs to change.
|
||
|
||
<div className="not-prose my-7 grid grid-cols-2 gap-3">
|
||
<div className="overflow-hidden rounded-xl border border-zinc-200 bg-zinc-950 dark:border-zinc-800">
|
||
<video
|
||
className="aspect-video w-full object-cover"
|
||
src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/validate-variables-default.mp4#t=0.1"
|
||
autoPlay
|
||
muted
|
||
loop
|
||
playsInline
|
||
preload="metadata"
|
||
/>
|
||
<div className="px-3 py-2 text-sm text-zinc-600 dark:text-zinc-400">Default values</div>
|
||
</div>
|
||
<div className="overflow-hidden rounded-xl border border-zinc-200 bg-zinc-950 dark:border-zinc-800">
|
||
<video
|
||
className="aspect-video w-full object-cover"
|
||
src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/validate-variables-variant.mp4#t=0.1"
|
||
autoPlay
|
||
muted
|
||
loop
|
||
playsInline
|
||
preload="metadata"
|
||
/>
|
||
<div className="px-3 py-2 text-sm text-zinc-600 dark:text-zinc-400">
|
||
The same design with different values
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
## Use variables in the browser editor
|
||
|
||
The browser editor can create and bind variables, preview overrides, and copy the reviewed
|
||
values into a render command. Follow [Use variables and templates](/studio/assets-and-blocks#use-variables)
|
||
for that complete workflow.
|
||
|
||
## Advanced: declare the approved inputs
|
||
|
||
Variables live on the composition declaration:
|
||
|
||
```html compositions/card.html
|
||
<html
|
||
data-composition-variables='[
|
||
{"id":"title","type":"string","label":"Title","default":"Pro"},
|
||
{"id":"accent","type":"color","label":"Accent color","default":"#6c5ce7"},
|
||
{"id":"logo","type":"string","label":"Logo","default":"assets/logo.svg"}
|
||
]'
|
||
></html>
|
||
```
|
||
|
||
### What can be a variable
|
||
|
||
A variable has one of seven kinds. The kind sets the control the browser editor
|
||
shows and what a render accepts for it.
|
||
|
||
| Kind | What it holds | Example |
|
||
| --------- | ---------------------------------------------- | -------------------------------- |
|
||
| `string` | Text, or a link to a file | A customer name, a video link |
|
||
| `number` | A count, position, size, or strength | Seats on a plan, a speed |
|
||
| `color` | One approved color | A brand accent |
|
||
| `boolean` | On or off | Show the badge |
|
||
| `enum` | One value from a list you approved | `light` or `dark` |
|
||
| `font` | A font family | The headline typeface |
|
||
| `image` | A link to a picture | A customer logo |
|
||
|
||
Video and sound have no kind of their own. Declare the link as a `string`, then
|
||
bind it to a `<video>` or `<audio>` element, as in [Swap in a video or a sound](#swap-in-a-video-or-a-sound).
|
||
|
||
### Say what a slot means, not where it sits
|
||
|
||
`label` and `description` are read by people and by agents. A description that
|
||
only gives a position ("small credit in the corner of every banner") leaves the
|
||
slot's meaning to be guessed; one that gives the meaning ("name of the brand this
|
||
video promotes") can be filled correctly without opening the HTML.
|
||
|
||
For a template that will be remixed against someone else's brand, add
|
||
`portrays` — a list naming what the slot stands for. It is optional metadata,
|
||
ignored by rendering, and it tells an editing agent which slots carry identity
|
||
and must not be filled with invented copy:
|
||
|
||
```html compositions/card.html
|
||
{"id":"appName","type":"string","label":"App name",
|
||
"description":"Name of the brand this video promotes, credited in the corner of every banner.",
|
||
"portrays":["subject_name"],"default":"HyperFrames"}
|
||
```
|
||
|
||
| Value | The slot stands for |
|
||
| ---------------------- | -------------------------------------------------------------------------- |
|
||
| `subject_name` | The promoted brand's own name |
|
||
| `subject_domain` | Its domain, URL, or handle |
|
||
| `subject_tagline` | Its own positioning line |
|
||
| `subject_logo` | Its mark or wordmark |
|
||
| `recommended_position` | The winning or featured slot in a ranking, so the promoted brand goes there |
|
||
| `competitor_name` | A real product other than the promoted brand |
|
||
| `authority_badge` | A claim of endorsement, ranking authority, rating, or source |
|
||
| `host_identity` | The depicted application's own identity, which a remix leaves alone |
|
||
|
||
`portrays` is orthogonal to `role`: `role` says which aspect of the composition a
|
||
knob affects (`content`, `style`, `timing`, `motion`, `layout`), while `portrays`
|
||
says what the value means to a viewer.
|
||
|
||
## Bind common values without a script
|
||
|
||
Use direct bindings for the normal cases:
|
||
|
||
```html
|
||
<h1 data-var-text="title">Pro</h1>
|
||
|
||
<img data-var-src="logo" src="assets/logo.svg" alt="" />
|
||
|
||
<style>
|
||
.card-title {
|
||
color: var(--accent);
|
||
}
|
||
</style>
|
||
```
|
||
|
||
- `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
|
||
const { featured = false } = window.__hyperframes.getVariables();
|
||
document.querySelector(".badge").hidden = !featured;
|
||
```
|
||
|
||
## Swap in a video or a sound
|
||
|
||
Bind a link to a media element with `data-var-src`. Keep a `src` on the element
|
||
as the placeholder:
|
||
|
||
```html index.html
|
||
<html
|
||
data-composition-variables='[
|
||
{"id":"welcomeClip","type":"string","label":"Welcome clip","default":"assets/placeholder.mp4"}
|
||
]'
|
||
>
|
||
<video
|
||
data-var-src="welcomeClip"
|
||
src="assets/placeholder.mp4"
|
||
data-start="0"
|
||
data-track-index="0"
|
||
playsinline
|
||
></video>
|
||
</html>
|
||
```
|
||
|
||
Render the same saved project once per account by passing each account's clip:
|
||
|
||
```bash
|
||
npx hyperframes render \
|
||
--variables '{"welcomeClip":"https://example.com/clips/northstar.mp4"}' \
|
||
--output northstar.mp4
|
||
```
|
||
|
||
The film takes the length and the sound of the clip you pass, not the
|
||
placeholder's. A 3 second placeholder swapped for a 5 second clip renders 5
|
||
seconds, and that clip's sound is mixed once.
|
||
|
||
Limits:
|
||
|
||
- `data-var-src` works on `<video>`, `<audio>`, `<img>`, and `<source>`. On any
|
||
other element it is ignored.
|
||
- The link must be a path or an `http`, `https`, or `blob` URL. Any
|
||
other value, including a `data:` video, is dropped and the placeholder
|
||
renders instead, with a warning.
|
||
- A clip inside a nested composition that receives its own `data-variable-values`
|
||
is resolved by the browser during the render, not before it.
|
||
- The root composition's length follows the clips it plays. It is not a variable.
|
||
|
||
## Give each nested composition different values
|
||
|
||
A parent can reuse the same composition several times:
|
||
|
||
```html index.html
|
||
<div
|
||
data-composition-id="card-pro"
|
||
data-composition-src="compositions/card.html"
|
||
data-start="0"
|
||
data-duration="3"
|
||
data-track-index="1"
|
||
data-variable-values='{"title":"Pro","accent":"#ff4d4f"}'
|
||
></div>
|
||
|
||
<div
|
||
data-composition-id="card-enterprise"
|
||
data-composition-src="compositions/card.html"
|
||
data-start="card-pro"
|
||
data-duration="3"
|
||
data-track-index="1"
|
||
data-variable-values='{"title":"Enterprise","accent":"#22c55e"}'
|
||
></div>
|
||
```
|
||
|
||
Both instances keep the same source and receive different content.
|
||
|
||
## Advanced: render a version from data
|
||
|
||
Override top-level values from the CLI:
|
||
|
||
```bash
|
||
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. Batch files can use UTF-8, with or without a byte order
|
||
mark (BOM), or UTF-16LE with a BOM.
|
||
|
||
```json rows.json
|
||
[
|
||
{ "name": "acme", "title": "Acme Pro" },
|
||
{ "name": "northstar", "title": "Northstar Pro" }
|
||
]
|
||
```
|
||
|
||
```bash
|
||
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
|
||
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.
|