> ## Documentation Index
> Fetch the complete documentation index at: https://hyperframes.heygen.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Variables
> Parameterize compositions so the same source can render different content.
Variables let you declare named, typed slots in a composition and fill them at render time — from a parent composition, from the CLI, or from an API call. A card composition that takes `title` and `color` can be embedded a hundred times with a hundred different values without duplicating any HTML.
## Declaring Variables
Add `data-composition-variables` to the `` root of any composition. Its value is a JSON array of variable declarations — one object per variable:
```html compositions/card.html theme={null}
```
Every declaration requires four fields: `id`, `type`, `label`, and `default`. `id` must be unique within the composition.
## Variable Types
| Type | `default` value | Extra options |
| --------- | ------------------------ | ---------------------------------------------------------------- |
| `string` | `"some text"` | `placeholder?: string`, `maxLength?: number` |
| `number` | `0` | `min?: number`, `max?: number`, `step?: number`, `unit?: string` |
| `color` | `"#rrggbb"` | — |
| `boolean` | `true` / `false` | — |
| `enum` | one of the option values | `options: [{value: string, label: string}]` |
The Studio editing UI uses `label`, `type`, and the type-specific options to render the right input widget for each variable.
## What can be a variable
Variables come in two layers. The five [declared types](#variable-types) above cover typed primitive data — strings, numbers, colors, booleans, enums. For everything else, a `string` variable holding a URL is the escape hatch: your composition reads the URL and assigns it to whatever DOM element needs it.
### Parameterizing media assets
The same composition can render different images, video clips, or audio tracks just by swapping URLs through a string variable:
```html compositions/product-card.html theme={null}
```
The runtime probes the DOM after your composition script runs, so a `` or `` `src` assigned at runtime from a variable is discovered and pre-extracted for the render. No extra wiring required — just set the `src` from your variable.
The same pattern covers the three media element types:
* **``** — assign from a string variable, but keep the timing attributes (`data-start`, `data-duration`, `data-track-index`, `data-has-audio`) on the element itself. The probe phase scans `video[data-start]` elements after your script runs and reads the resolved `src` for pre-extraction.
* **``** — same as video. The audio is decoded during capture and mixed into the final output.
Pass assets as URL references your composition resolves at render time; don't inline base64. URL-shaped assets travel cleanly through both the local renderer and the Lambda surface — see [Templates on Lambda](/deploy/templates-on-lambda#working-with-large-variables) for the 256 KiB execution-input cap on distributed renders.
### Parameterizing media color grading
Media color grading can also read exact variable references inside
`data-color-grading`. Use `$name` or `${name}` as the entire value for a field;
the runtime resolves it from the current composition's variables before applying
the shader grading:
```html compositions/hero.html theme={null}
```
When the same composition is embedded multiple times, each host's
`data-variable-values` can produce different grading without copying or rewriting
the media element's `data-color-grading` JSON.
### Swapping media: do you need to vary duration too?
A common follow-up: if a variable swaps a `` to a different clip, does `data-duration` need to change too? Usually no. `data-duration` is optional on `` and `` — leave it off and the renderer ffprobes the source and uses its natural length:
```html compositions/hero.html theme={null}
>` — use destructuring with defaults matching the declared `default` values:
```html compositions/card.html theme={null}
```
Both host elements point to the same `card.html` source, but each instance receives different values. The runtime merges the host's `data-variable-values` over the sub-comp's declared defaults on a per-instance basis — the same sub-composition can run with completely different content simultaneously.
## CLI Overrides (Top-level Renders)
Pass variable values at render time with `--variables` or `--variables-file`. These override the declared defaults for the top-level composition:
```bash Terminal theme={null}
# Inline JSON
npx hyperframes render --variables '{"title":"Q4 Report","color":"#1d4ed8"}' --output q4.mp4
# JSON file
npx hyperframes render --variables-file ./vars.json --output out.mp4
# Fail on undeclared or mistyped variables
npx hyperframes render --variables '{"title":"Q4 Report"}' --strict-variables --output out.mp4
```
`--strict-variables` turns variable warnings into errors. Any variable in `--variables` that is not declared in `data-composition-variables`, or whose value does not match the declared type, causes the render to exit non-zero. Useful in CI pipelines where an undeclared variable key likely indicates a typo or a schema mismatch.
CLI overrides apply only to the top-level composition. Sub-composition variables are controlled by `data-variable-values` on each host element.
## Batch Renders
Use `--batch` when the same composition should render once per data row:
```json rows.json theme={null}
[
{ "name": "Alice", "title": "Q4 Report" },
{ "name": "Bob", "title": "Renewal Plan" }
]
```
```bash Terminal theme={null}
npx hyperframes render --batch rows.json --output "renders/{name}.mp4" --strict-variables
```
Each row is treated like a `--variables` object and merged over the composition defaults. Output paths support `{key}` placeholders from the row plus `{index}`. Hyperframes validates missing placeholders, output collisions, and `--strict-variables` issues before the first row starts rendering, then writes `manifest.json` next to the outputs with one status row per render.
For small compositions, `--batch-concurrency 2` can run rows in parallel. The default is `1` because each individual render already parallelizes across render workers.
## Layering and Precedence
Variable values are resolved by merging three sources, lowest to highest precedence:
| Source | Precedence | Where declared |
| --------------------------- | ---------- | --------------------------------------------------- |
| Declared defaults | Lowest | `data-composition-variables` on `` |
| Per-instance host overrides | Middle | `data-variable-values` on the sub-comp host element |
| CLI `--variables` flag | Highest | `hyperframes render --variables '{...}'` |
A missing key at any layer falls through to the next lower layer. If no layer provides a value, the declared `default` is used.
## Validation
The linter checks variable declarations statically:
```bash Terminal theme={null}
npx hyperframes lint
```
It catches malformed JSON, missing required fields (`id`, `type`, `label`, `default`), and type mismatches between `type` and the `default` value. Fix lint errors before rendering — they indicate the runtime will be unable to resolve variables correctly.
At render time, the CLI validates `--variables` against the schema and reports issues as warnings (or errors with `--strict-variables`):
* **undeclared** — a key in `--variables` has no matching `id` in `data-composition-variables`
* **type-mismatch** — the value's JavaScript type does not match the declared `type` (e.g. a string where a number is expected)
* **enum-out-of-range** — an enum value is not in the declared `options` list
## Inspecting Variables Programmatically
If you are building tooling on top of `@hyperframes/core`, the variable declarations are readable without rendering:
```typescript theme={null}
import { extractCompositionMetadata } from "@hyperframes/core";
import { readFileSync } from "node:fs";
const html = readFileSync("compositions/card.html", "utf8");
const { variables } = extractCompositionMetadata(html);
// variables is CompositionVariable[]
```
This is the same API the Studio editing UI uses to build the variables panel for each composition.
## Next Steps
Full reference for data-composition-variables and data-variable-values attributes
How nested compositions use variables for reuse
CLI flags for passing variables at render time
All CLI commands and flags