Data Attributes

Core attributes for controlling element timing and behavior.

Hyperframes uses HTML data attributes to control timing, media playback, and composition structure. These are the declarative building blocks of every video.

Timing Attributes

Attribute	Example	Description
data-start	"0" or "intro"	Start time in seconds, or a clip ID reference for relative timing
data-duration	"5"	Duration in seconds. Required for images and sub-compositions. Optional for video/audio (defaults to source duration). On the root composition it sets the total render length (see Composition Attributes).
data-track-index	"0"	Timeline track number. Temporal ordering — groups clips into rows on the timeline. Clips on the same track cannot overlap. Does not control z-ordering (use CSS z-index for that).

Media Attributes

Attribute	Example	Description
data-media-start	"2"	Media playback offset / trim point in seconds. Default: 0
data-volume	"0.8"	Audio/video volume, 0 to 1
data-has-audio	"true"	Indicates video has an audio track

Composition Attributes

Attribute	Example	Description
data-composition-id	"root"	Unique ID for composition wrapper (required on every composition)
data-width	"1920"	Composition width in pixels
data-height	"1080"	Composition height in pixels
data-duration (root)	"30"	On the root composition, the total render length / frame count in seconds. Read once from the source HTML at compile time, like data-width / data-height, so a script or hyperframes render --variables cannot change it (author it directly, one value per output). If the root omits data-duration, and only then, the renderer derives the total length from the live DOM / timeline after scripts run.
data-composition-src	"./intro.html"	Path to external composition HTML file
data-variable-values	'{"title":"Hello"}'	JSON object of values passed to a nested composition. Inside the sub-composition, read them via window.__hyperframes.getVariables() — the runtime layers these over the sub-comp’s own data-composition-variables defaults and exposes the merged result on a per-instance basis (the same source can be embedded multiple times with different values).
data-composition-variables	'[{"id":"title","type":"string","label":"Title","default":"Hello"}]'	JSON array of declared variables (id, type, label, default). Drives Studio editing UI and provides defaults read by window.__hyperframes.getVariables(). The CLI flag hyperframes render --variables '<json>' overrides these defaults at top-level render time; host elements override them per-instance via data-variable-values.
data-var-src	"heroImage"	Binds the element’s src to a declared variable — the runtime substitutes the value (URL string or image {url}) in preview and render; the authored src stays as the fallback.
data-var-text	"title"	Binds the element’s own text to a scalar variable. Element children (nested clips, animated spans) are preserved. Scalar variables are also applied as --{id} CSS custom properties on the composition root, so color: var(--accent) responds to overrides.

Element Visibility

Add class="clip" to all timed elements so the runtime can manage their visibility lifecycle:

index.html

<h1 id="title" class="clip"
    data-start="0" data-duration="5" data-track-index="0">
  Hello World
</h1>

Relative Timing

Instead of calculating absolute start times, a clip can reference another clip’s id in its data-start attribute. This means “start when that clip ends”:

index.html

<video id="intro" data-start="0" data-duration="10" data-track-index="0" src="..."></video>
<video id="main" data-start="intro" data-duration="20" data-track-index="0" src="..."></video>
<video id="outro" data-start="main" data-duration="5" data-track-index="0" src="..."></video>

main resolves to second 10, outro resolves to second 30. If intro’s duration changes, downstream clips shift automatically.

Offsets (Gaps and Overlaps)

Add + N or - N after the ID to offset from the end of the referenced clip:

index.html

<!-- 2-second gap after intro -->
<video id="scene-a" data-start="intro + 2" data-duration="20"
       data-track-index="0" src="..."></video>

<!-- 0.5-second overlap with intro (crossfade) -->
<video id="scene-b" data-start="intro - 0.5" data-duration="20"
       data-track-index="1" src="..."></video>

Overlapping clips must be on different tracks — clips on the same track cannot overlap in time.

Relative timing rules and constraints

Same composition only — references resolve within the clip’s parent composition. You cannot reference a clip in a sibling or parent composition.

No circular references — A cannot start after B if B starts after A. The resolver detects cycles and throws an error.

Referenced clip must have a known duration — either an explicit data-duration or a duration inferred from source media. If the referenced clip has no known duration, the reference cannot resolve.

Parsing rules — if the value is a valid number, it is treated as absolute seconds. Otherwise it is parsed as one of:

• <id> — start when that clip ends
• <id> + <number> — start N seconds after that clip ends
• <id> - <number> — start N seconds before that clip ends

Chain length — references can chain (A -> B -> C), but deeply nested chains make the timeline harder to reason about. Keep chains under 3-4 levels for readability.

Next Steps

Compositions

How compositions use data attributes to define video structure

HTML Schema Reference

Complete attribute reference with per-element details

GSAP Animation

Animate elements alongside data-attribute-driven timing

Common Mistakes

Pitfalls to avoid when setting up timing and attributes