Setting the file. One moment.
Subchapter 21.9
references/tracks-and-clips.mdMarkdown5 KBView on GitHub
Clips are timed elements inside a composition. Tracks are a Studio display concept: the render never reads them.
A clip is any DOM element with data-start and, where required, data-duration. data-track-index is optional. Common kinds:
<div> clips — scenes, cards, overlays. Always require data-duration.<div> with data-composition-src. Always require data-duration.<video> with muted and playsinline. Duration can default to media length.<audio>. Duration can default to media length.<img>. data-duration is optional and defaults to 3 seconds; write it only for another length.Add class="clip" to authored visual clips. The runtime does not read it, but the scaffold’s shared .clip { position: absolute; inset: 0 } rule is what gives a scene its full-frame box, Studio treats it as an edit hint, and lint warns without it.
data-track-index is the row a clip occupies in Studio’s timeline. It is not read by the render, and it constrains nothing:
z-index, not by track index.A clip on track 5 is not “above” a clip on track 1. Use CSS for layering, data-start/data-duration for sequencing.
The one place the value carries meaning: two <audio> elements that share a track index and overlap in time raise a lint warning (duplicate_audio_track), which is a useful nudge that you are about to double up a bed.
Purely a readability choice for whoever opens the file in Studio. Common patterns, owned by /hyperframes-studio (one caption track, one element kind per track).
When adding a clip to an existing composition, set its data-start/data-duration against the clips around it. You do not need to hunt for a free lane, and you never need to renumber tracks after a retime.
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.
For a hard cut, trim, splice, or reorder, duplicate the same video source into
multiple clip elements. Each copy selects its source range with
data-media-start plus data-duration, and places that range on the authored
timeline with data-start. Change the source offsets and placement order; do
not try to keyframe source cutting.
Separately authored audio gives each audio copy the identical source range and
timing as its matching video clip (data-media-start, data-duration, and
data-start). Video stays muted; the separate audio elements carry sound.
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, and three ways this fails silently. Nothing in lint checks any of them, so read them before you use a reference:
data-start="intro - 0.5" means “0.5s before intro ends”. data-start="intro-0.5" (no spaces) is parsed as a reference to an element whose id is literally intro-0.5; that element does not exist, so the clip silently starts at 0.data-start="hero" where hero has no data-duration and no known media length silently means “same time as hero“ rather than “after hero“.A → B → A puts one of them at 0.getElementById, then [data-composition-id]). A reference can therefore reach a target in another composition on the assembled page. Keep referenced ids unique and keep the reference and its target in the same file, or the result depends on assembly order.<id>, <id> + <number>, or <id> - <number>.A → B → C). Keep chains under 3-4 levels for readability.Because every failure mode above is a silent 0, snapshot a reference-timed composition and check the clip actually starts where you meant.