heygen-com--hyperframes/skills/hyperframes-core/references/tracks-and-clips.md

Tracks and Clips

Clips are timed children of the composition root. Tracks are a temporal-overlap concept, not a visual-stacking concept.

What is a Clip

A clip is any DOM element with data-start, data-duration (where required), and data-track-index. Common kinds:

• Visual <div> clips — scenes, cards, overlays. Always require data-duration.
• Sub-composition hosts — <div> with data-composition-src. Always require data-duration.
• Video clips — <video> with muted and playsinline. Duration can default to media length.
• Audio clips — <audio>. Duration can default to media length.
• Image clips — <img>. Always require data-duration.

Add class="clip" to authored visual clips so tooling and examples can find them.

Tracks Are Temporal, Not Visual

data-track-index controls temporal overlap, not paint order:

• Two clips on the same data-track-index must NOT overlap in time. hyperframes lint flags this.
• Visual layering (front/back) is controlled by CSS z-index, not by track index.

A clip on track 5 is not "above" a clip on track 1 — it's just on a different audio/visual lane in time. Use CSS for layering, tracks for sequencing.

Picking a Track Index

There's no fixed convention, but common patterns:

• Track 0 — base video (e.g. an A-roll).
• Track 1+ — visual scenes, overlays, captions.
• Higher tracks (e.g. 10+) — audio clips, separated from visual tracks to keep linting clear.

When adding a new clip to an existing composition:

1. Find an existing track that has no overlap with your new clip's [data-start, data-start + data-duration) range.
2. Or pick a fresh track index.
3. Never overlap two clips on the same track — the linter will fail and the render is undefined.

Clip Time Inside the Composition

data-start is in seconds, measured from the start of the composition. For sub-compositions, the sub-composition's internal timeline (its own data-duration and child clips) runs from data-start to data-start + data-duration of the host.

data-media-start (on <video>/<audio>) is an offset into the source media. Use it to skip the first few seconds of a media file without trimming the file itself.

Relative Timing

data-start accepts a clip ID instead of a number, meaning "start when that clip ends". Add + N / - N to offset; negative produces overlap (useful for crossfades).

<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="scene-a"
  data-start="intro + 2"
  data-duration="20"
  data-track-index="0"
  src="..."
></video>
<video
  id="scene-b"
  data-start="intro - 0.5"
  data-duration="20"
  data-track-index="1"
  src="..."
></video>

Rules:

• References resolve inside the same composition only — cannot reach into a parent or sibling sub-composition.
• The referenced clip must have a known duration (explicit data-duration or inferred from media). Otherwise the reference cannot resolve.
• No circular references — A → B → A is rejected. Cycles are detected and error out.
• A value that parses as a number is always treated as absolute seconds. Otherwise the resolver expects <id>, <id> + <number>, or <id> - <number> (whitespace optional).
• References can chain (A → B → C). Keep chains under 3-4 levels for readability.
• Negative offsets create overlap; overlapping clips must be on different tracks, same-track overlap is rejected.