mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
* fix(cli): batch render outputs stay inside the --output folder A row value may still name a subfolder of the folder written before the template's first placeholder, but a value that resolves outside it stops the batch before any folder is made or file is written. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli): project text shows control characters as visible escapes compositions, lint, snapshot and info --media print composition ids, sources, element ids, lint messages and media paths through one helper that writes C0, DEL and C1 control characters out as \xNN, so they reach the terminal as text. The CLI's own colors are unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(studio-server): waveform and peaks key one cache entry per file and refuse other sites Both caches are keyed on the resolved project-relative path, so another spelling of the same file (a doubled or trailing slash) reads the cached peaks instead of decoding again. Waveform and peaks requests that another site makes are refused the way thumbnail requests already are; the Studio page asks for both as itself. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(studio-server): preview stills run at most four at a time A video's stand-in still is made through a small job queue: four at once, 32 more waiting, and a 503 with Retry-After beyond that. A waiting request whose client goes away leaves the queue without starting ffmpeg. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli): batch output folder check keeps backslash names and row-named paths A trailing backslash counts as a separator only where it is one, and the check compares path segments. A template that starts with a placeholder names no folder, so each row's value is the whole output path as before. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli): lint header shows control characters in file names as escapes Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(studio-server): a finished or in-progress still never waits for a still slot Only a still that is neither on disk nor already being made takes one of the four slots, through a hook resolveStill gives the route. Waiters queue without a cap and nothing answers 503, since a poster is never asked for again. A waiter whose client leaves still never starts ffmpeg; a request that shared that waiter's still tries again on its own. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore: raise the studio-server packed budget to 172000 main already packs about 170 KB against a 168500 budget; the request guards, still slots and cache-key change here add about 550 bytes. * fix(core,studio-server): a preview served to another site offers no editing port When the Studio server answers a preview document to another site's request, it now marks the document, and the runtime's editing agent ignores every connect in a marked document. The Studio's own frames, which load the preview from the same origin, keep the editing port. The marked copy carries no ETag, so it is never revalidated in place of the unmarked one. * fix(studio-server): a media still stops when no request waits on it Each still job now counts the requests waiting on it. A request whose connection closes leaves the job, and when the last one leaves, the job's ffmpeg is killed and the job is forgotten, so the next request starts afresh. A caller that passes no signal keeps the job running, and a request that has already closed starts nothing. * test(studio-server): group the still cancellation tests after the real-ffmpeg still test * fix(studio-server): a preview framed by another site is never revalidated A frame load of a preview from another site now drops If-None-Match and If-Modified-Since before the route answers, so it always gets a fresh, marked document instead of a 304 that could reuse the unmarked copy a browser cached for the Studio's own page on the same site. Subresource loads keep their validators. * fix(cli): check findings and keyframes headers show control characters as escapes check prints each finding's message, source file, selector and fix hint, and keyframes prints each composition's name and source, through terminalText. * test(studio-server): a request sharing an abandoned still waiter gets its still * chore(studio-server): raise the unpacked size budget for the still job slots and cross-site guards * fix(cli): layout and contrast lines in check show control characters as escapes --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
286 lines
10 KiB
Plaintext
286 lines
10 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"
|
||
```
|
||
|
||
Every output stays inside the folder written before the first placeholder
|
||
(`renders/` here). A row value may name a subfolder of it, but a value that
|
||
leads outside it, such as `../other`, stops the batch before anything renders.
|
||
A template that starts with a placeholder, such as `--output "{path}"`, names
|
||
no folder, so each row's value is used as the whole output path, absolute
|
||
paths included.
|
||
|
||
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.
|