Timegroup

The timegroup element is the fundamental organizing unit of an Editframe video.

The timegroup element is used to declare several kinds of video timelines. Timegroups can be nested to create rich timelines.

The outer-most timegroup is the root timegroup. It is the parent of all other timegroups. The pixel dimensions of the root timegroup are used to determine the aspect ratio of the video. And the computed duration of the root timegroup is used to determine the duration of the video.

Examples

Mode: fixed

The most simple timegroup is a fixed duration timegroup. While it doesn't make for a very compelling video, we can use the fixed time group to create static content.

Mode: sequence

The sequence timegroup plays its children in sequence. Here we have three items that each play for a fixed duration of 5, 8, and 3 seconds. The duration of the sequence timegroup is the sum of the durations of its children. It's kind of like flexbox, but for time.

Mode: contain

The contain timegroup plays its children simultaneously. The duration of the contain timegroup is the maximum duration of its children. Here, we have three items that each play for a fixed duration of 5, 8, and 3 seconds. The duration of the contain timegroup is the maximum duration of its children, which is 8 seconds. As you scrub the timeline, you'll see that the last item plays for the entire duration of the timegroup.

These three timegroup modes can be combined to create rich timelines of all kinds.

Mode: fit

Fit timegroups expand their duration to fit the duration of their parent timegroup. This can be used create background elements that play for the duration of the video.

In this example, you can change the duration of the sequence items to see how the fit element will maintain the duration of the timegroup containing it.

CSS Variable: --ef-duration

The timegroup element supports animation control. This is useful for creating complex animations that are timed to the video.

In this example, we have specified a fade-in and fade-out animation that will run on the titlecard and subtitle.

To apply the animation, we use the style attribute to set the animation on the titlecard and subtitle.

<p
  class="text-3xl"
  style="
    animation: fade-in 2s ease-in-out paused,
               fade-out 2s ease-in-out calc(var(--ef-duration) - 2s) paused
  "
>
  Five Second Titlecard
</p>

The var(--ef-duration) variable is a special variable that is set by the timegroup element. It is the duration of the nearest parent timegroup. By using this variable we can ensure that the fadeout will always start at the same time relative to the end of the timegroup.

This is great for creating templates where you don't know exactly how long the final media will be. Either because it might change during production, or because it will be filled with dynamic during templated rendering.

CSS Variable: --ef-progress

The timegroup element also supports progress control. This is useful for creating interactive media.

In this example, we have specified a progress animation that will run on the titlecard and subtitle. The progress animation is a simple scale animation that will run from 0 to 100% based on the progress of the timegroup.

<!-- We can use the --ef-progress variable to create a scale animation that runs from 0 to 100% based on the progress of the timegroup. -->
<p class="text-3xl" style="scale(var(--ef-progress))">Five Second Titlecard</p>

<!-- We can also use the --ef-progress variable to create a progress bar that fills up from 0 to 100% based on the progress of the timegroup. -->
<div class="h-2 w-1/2 bg-slate-400">
  <div class="bg-blue-400 h-full" style={{width: `var(--ef-progress)`}}></div>
</div>

Mode: sequence with overlap and transitions

CSS Variables: --ef-transition-duration and --ef-transition-out-start

When using an overlap, the timegroup element will automatically calculate the --ef-transition-duration and --ef-transition-out-start variables. These variables are useful for creating transitions between sequence items. Again, they help us create templates that are dynamic and can be reused with different content.

Repeating the same example, we can see the --ef-transition-duration and --ef-transition-out-start variables in action.

Controlling transitions with CSS is a powerful way to create complex animations and interactive media. You might be surprised how much you can do with just a few lines of CSS and SVG. Checkout the CSS Animation Control section for more examples.

Frame Rate and Time Quantization

To ensure that animations and media playback are perfectly synchronized, ef-timegroup quantizes all time updates to a consistent frame grid. This is controlled by the fps (frames per second) attribute.

When you set the currentTime on a timegroup, the value is automatically rounded to the nearest frame boundary based on the configured fps. This process, known as time quantization, is crucial for preventing timing inconsistencies and producing predictable, smooth output, especially in a rendering environment.

Attributes