How To: Avoid Common Mistakes

Wrong: Writing to a child's currentTime directly, or expecting currentTime = 1 on a child in a sequence.

Right: Write only to the root timegroup. Read ownCurrentTimeMs for element-relative time.

// Wrong
childTimegroup.currentTime = 5;

// Right — set root, children compute their own local time
rootTimegroup.currentTime = 5;

// Read local time
console.log(childTimegroup.ownCurrentTimeMs);

Wrong: Setting currentTime and immediately reading frame state.

Right: Use await timegroup.seek(timeMs) which resolves only when the frame is ready.

// Wrong — state may not be committed yet
tg.currentTime = 5.5;
console.log(tg.ownCurrentTimeMs); // potentially stale

// Right
await tg.seek(5500);
console.log(tg.ownCurrentTimeMs); // guaranteed current

Mode and attribute confusion

Wrong: fit="contain" expecting duration to change.

Right: mode="fit" controls duration inheritance; fit="contain" (an unrelated CSS attribute) controls visual scaling.

Wrong: Expecting overlap="2s" alone to create a visual crossfade.

Right: overlap shifts timing so two scenes share 2s, but the visual blend requires CSS animations using --ef-transition-duration and --ef-transition-out-start.

Animation timing mistakes

Wrong:

animation-delay: 3s; /* hard-coded, breaks when duration changes */

Right:

animation-delay: var(--ef-transition-out-start);
/* or */
animation-delay: calc(var(--ef-duration) - 2s);

FPS configuration

Wrong: Setting fps on nested child timegroups.

Right: Set fps once on the root timegroup. Mixed FPS values inside a tree cause quantization mismatches.

<!-- Right -->
<ef-timegroup mode="sequence" fps="30">
  <ef-timegroup mode="fixed" duration="3s"><!-- no fps here --></ef-timegroup>
</ef-timegroup>