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

​
Timing Attributes

AttributeExampleDescription
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

AttributeExampleDescription
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

AttributeExampleDescription
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

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