Time Propagation

Timegroups use a single source of truth architecture: only the root timegroup's currentTime is written. All child times are derived from that root value. This eliminates the synchronization problems that arise when multiple elements maintain independent timeline state.

The problem with separate timeline states

When elements each hold their own time state:

• Race conditions. Multiple timelines updated independently can drift out of sync.
• Manual synchronization. Keeping all positions consistent requires coordination code that is error-prone.
• No single source of truth. Multiple places where time is stored make it difficult to reason about playback state or implement features like seeking consistently.

Root-only writes, computed child times

Every ef-timegroup has two time properties:

Property	Meaning
currentTime	Position in the root timeline (global coordinate). Writable only on the root.
ownCurrentTimeMs	Position in this element's local timeline (local coordinate, resets to 0 when this element starts). Read-only.

Setting the root's currentTime atomically updates every descendant:

const root = document.getElementById('my-video');
root.currentTime = 5.5; // All children update immediately

In sequence mode, each child computes ownCurrentTimeMs as currentTimeMs − startOffset, clamped to its duration. An element that hasn't started yet returns 0; one that has ended returns its duration.

Consequence for seeking: Always await tg.seek(timeMs) rather than setting currentTime directly when you need to read frame state immediately after — seek() resolves only after the frame is committed.

// currentTime is set but frame may not be committed yet
tg.currentTime = 5.5;

// seek() awaits frame commitment — safe to read state after
await tg.seek(5500);
console.log(tg.ownCurrentTimeMs); // guaranteed current

---