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. Optional for video/audio (defaults to source duration). Not used on compositions.
data-track-index	"0"	Timeline track number. Controls z-ordering (higher = in front) and groups clips into rows. Clips on the same track cannot overlap.

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-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.

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