Composition

Time Model

How ef-timegroup controls timing, duration, and sequencing in a composition.

ef-timegroup is the core timing primitive. Every composition has at least one — the root group that defines the total video duration. Groups nest to build complex timelines.

duration

HTML timing attributes accept time strings such as 5s, 500ms, and 2m; a bare number such as "2.5" means seconds. JavaScript timing APIs such as currentTime, duration, offset, and seek() use seconds. React's duration and offset props also accept numeric seconds. Fields explicitly suffixed Ms use milliseconds.

Media speed and source time

For ef-video and ef-audio, sourcein, sourceout, trimstart, and trimend refer to seconds in the original media file. playback-rate specifies source seconds per composition second and preserves audio pitch; it accepts finite values from 0.25 to 4, with a default of 1.

Without an explicit duration, the clip's duration is its selected source span divided by the rate. For example, sourcein="2s" sourceout="10s" playback-rate="2" produces a four-second clip. At one composition second into that clip, the source is at four seconds.

An explicit duration stays in composition seconds and takes precedence over sourceout: sourcein="2s" duration="3s" playback-rate="2" uses source seconds 2 through 8. The end is clamped to the known file length, which can shorten the resulting clip.

mode="sequence"

Children play one after another. Without overlap, the group's total duration is the sum of its children's durations. Inactive scenes are hidden; seeking to the end holds the last scene's final frame.

Interactive example

Sequence with overlapping transitions

Set overlap on a mode="sequence" to start each scene before the previous one ends. Both scenes are active during the shared window. Overlap shortens the total duration: the 2s, 3s, and 2s scenes below make a 5s sequence with 1s overlap.

In order to use the overlap window for a transition, add CSS animations that reference the special timing variables --ef-transition-duration and --ef-transition-out-start.

To animate a transition into a scene, use --ef-transition-duration as the animation duration and start at local 0s. To animate a scene out, use the same duration but start at --ef-transition-out-start, which is that scene's duration minus the overlap.

Interactive example

mode="fixed"

Children share a timeline whose length is the group's explicit duration. Each child's local clock starts at its optional offset within the group.

Unlike sequence scenes, children in fixed, contain, and fit groups remain visible outside their own playback interval: visuals hold their first frame before the offset and their last frame after the clip ends. Audio is silent outside the interval. Use a sequence or timeline-driven visibility when an overlay must disappear.

Interactive example

offset shifts when an element begins within its parent fixed group.

mode="contain"

The group's duration reaches the furthest child end: the maximum of each child's offset + duration. Below, Scene B starts at 2s and lasts 6s, so the group lasts 8s.

Interactive example

mode="fit"

The group's duration matches its parent's duration. Use it for a layer whose timeline should span the parent composition.

fit does not change a media file's playback rate, loop it, or extend its sound past the available source. Set playback-rate explicitly when you want to retime media.

This can be combined with a sequence to give a background audio layer the full composition's timeline:

Interactive example

Timegroups vs Temporal Elements

Timegroups are the typical element to use to structure the timing of your composition, but they aren't the only temporal elements.

  • <ef-video>
  • <ef-audio>
  • <ef-image>
  • <ef-text>

These can be direct children of a timegroup to simplify your composition structure.

Wrap them in a timegroup when a scene also needs ordinary HTML content, graphics, or shared layout.

loop

Add loop to the root ef-timegroup to loop the composition in the browser preview:

html
<ef-timegroup duration="5s" loop class="w-[1920px] h-[1080px] bg-black">
  ...
</ef-timegroup>

loop has no effect during rendering — the renderer plays through exactly once.

fps

fps controls the frame rate used when scrubbing and rendering. It defaults to 30. Drag the slider to see how frame rate affects animation smoothness:

Interactive example