Editframe logoEditframe

Understanding Temporal Elements

In Editframe, temporal elements are elements that exist in time. They have a duration, a current playback position, and playback state (playing or paused).

What Makes an Element Temporal?

These elements are temporal:

  • <ef-video> - Video elements
  • <ef-audio> - Audio elements
  • <ef-timegroup> - Compositions that organize other temporals

All temporal elements share these properties:

  • duration - How long they play
  • currentTime - Where in the timeline you are
  • playback state - Playing or paused

The Key Concept: Root vs Nested

Only the root temporal element can be controlled. This is the most important concept to understand.

Standalone Temporal Elements

A video or audio element by itself is a root temporal and can be controlled directly:

<!-- This video is a root temporal -->
<ef-video id="my-video" src="/video.mp4"></ef-video>

<!-- You can control it -->
<ef-toggle-play target="my-video">
  <button slot="play">Play</button>
  <button slot="pause">Pause</button>
</ef-toggle-play>

Nested Temporal Elements

When you nest temporal elements inside a timegroup, only the timegroup can be controlled:

<ef-timegroup id="composition" mode="sequence">
  <ef-video id="video-1" src="/intro.mp4"></ef-video>
  <ef-video id="video-2" src="/main.mp4"></ef-video>
</ef-timegroup>

In this example:

  • The <ef-timegroup> is the root temporal - you can play/pause it
  • The videos inside are nested temporals - they follow the root's timeline automatically
  • You cannot independently control the individual videos

This is why you build compositions with timegroups - the timegroup becomes the controllable unit, and everything inside follows its timeline.

When you play the root timegroup, it automatically manages the playback of all nested temporal elements according to the timeline structure you've defined.

Connecting Controls

Control elements need to connect to a temporal element using the target attribute:

<!-- A temporal element -->
<ef-video id="my-video" src="/video.mp4"></ef-video>

<!-- Controls that target it -->
<ef-toggle-play target="my-video">
  <button slot="play">▶ Play</button>
  <button slot="pause">⏸ Pause</button>
</ef-toggle-play>

The same works for timegroups:

<!-- A timegroup composition -->
<ef-timegroup id="my-composition" mode="sequence">
  <ef-video src="/intro.mp4"></ef-video>
  <ef-video src="/main.mp4"></ef-video>
</ef-timegroup>

<!-- Controls that target it -->
<ef-toggle-play target="my-composition">
  <button slot="play">▶ Play</button>
  <button slot="pause">⏸ Pause</button>
</ef-toggle-play>

The target attribute lets you place controls anywhere in your layout, separate from the temporal element itself.

Key Takeaways

Temporal elements are elements that exist in time:

  • <ef-video> - Video elements
  • <ef-audio> - Audio elements
  • <ef-timegroup> - Compositions that organize temporals

The root temporal concept is essential: Only root temporal elements can be controlled. When you nest temporals inside a timegroup, the timegroup becomes the root and controls all nested elements.

Controls connect to temporals using the target attribute to reference the temporal element's id.

This abstraction lets you build complex video compositions where a single timeline controls many synchronized elements.

Next Steps