hanzoai/frames
2
0
Fork 0
mirror of https://github.com/hanzoai/frames.git synced 2026-09-24 00:08:03 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(concepts): note that media data-duration can be variable-driven

Browse Source
This commit is contained in:
James
2026-05-19 20:47:46 -04:00
committed by James Russo
parent b3154969f1
commit deba69b725
1 changed files with 32 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/concepts/variables.mdx
+32 -6
View File
@@ -78,19 +78,45 @@ The same pattern covers the three media element types:
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.
### Swapping media: do you need to vary duration too?
A common follow-up: if a variable swaps a `<video>` to a different clip, does `data-duration` need to change too? Usually no. `data-duration` is optional on `<video>` and `<audio>` — leave it off and the renderer ffprobes the source and uses its natural length:
```html compositions/hero.html
<video id="hero" data-start="0" data-track-index="0"></video>
<script>
document.getElementById("hero").src = __hyperframes.getVariables().heroVideo;
</script>
```
If you need to clamp or pin the clip to a specific length per render — for example, to keep downstream timing stable across clips of different source lengths — expose duration as its own `number` variable and apply it via the same script:
```html compositions/hero.html
<video id="hero" data-start="0" data-track-index="0"></video>
<script>
const { heroVideo, heroDuration } = __hyperframes.getVariables();
const el = document.getElementById("hero");
el.src = heroVideo;
if (heroDuration !== undefined) {
el.setAttribute("data-duration", String(heroDuration));
}
</script>
```
The probe phase reads `data-duration` from the live DOM after your script runs, so an attribute written programmatically behaves identically to one baked into the source HTML.
## What can't be a variable
Some inputs look variable-shaped but are configured elsewhere. The right mechanism for each:
A small set of inputs are read once from the source HTML or from the CLI / SDK, with no live-DOM re-read — no script (and therefore no variable) can change them:
| What | Mechanism (not a variable) |
|------|----------------------------|
| Composition duration | `data-duration` attribute on the composition element |
| Composition dimensions | `data-width` / `data-height` attributes |
| Frame rate | `--fps` flag on `hyperframes render` |
| Output format / codec / quality | `--format` / `--codec` / `--quality` flags |
| Composition dimensions | `data-width` / `data-height` on the composition element — parsed from the source HTML at compile time, not from the live DOM |
| Frame rate | `--fps` flag on `hyperframes render`, or `config.fps` in the SDK |
| Output format / codec / quality | `--format` / `--codec` / `--quality` flags, or the SDK equivalents |
| A sibling or parent composition's variables | Variables are per-composition; use [`data-variable-values`](#per-instance-overrides-sub-compositions) on each sub-comp host element to pass overrides |
The deeper rule: variables are runtime values, not authoring inputs. A variable can toggle DOM state, swap text, change a color — anything your composition script does with the resolved value. It can't change the composition's structural identity. Two compositions with different `data-composition-id` or different layout markup remain different compositions, even when their variable values are identical.
The deeper rule: variables are runtime values your script applies to the DOM. They can drive anything the renderer reads from the live DOM after that script runs — text, colors, media `src`, even clip `data-duration` as shown above. They can't change inputs the renderer reads once at compile time (dimensions) or that live entirely outside the composition (CLI flags, encoder settings).
## Reading Variables at Runtime