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.

Basic Usage

<!--
  This timegroup will be as long in duration as the video within it.
  It represents a 500px by 500px video.
-->
<ef-timegroup class="h-[500px] w-[500px]">
  <ef-video assetId="c71f4e73-5e80-4bfd-a2ab-c69a0f5e0e83"></ef-video>
</ef-timegroup>

Nested Structure

<ef-timegroup> elements can be nested to create complex timing structures:

<!--
  This time group will play in sequence.
  It contains two child time groups.
  The will play one after the other, and the duration of the parent timegroup
  will be the sum of the durations of its children.
-->
<ef-timegroup mode="sequence">
  <ef-timegroup mode="contain">
    <!-- Temporal elements will play simultaneously in this time group.
     This time group will play until the longest child temporal element finishes. -->
  </ef-timegroup>
  <ef-timegroup mode="fixed" duration="5s">
    <!-- This time group will play for 5 seconds.
     Any media within this time group will be limited to 5 seconds. -->
  </ef-timegroup>
</ef-timegroup>

Working with Media

The <ef-timegroup> element is designed to work seamlessly with custom media elements like <ef-video>, <ef-audio>, and <ef-image>:

<ef-timegroup mode="sequence">
  <!-- This example would play the video and audio one after the other. -->
  <ef-video assetId="c71f4e73-5e80-4bfd-a2ab-c69a0f5e0e83"></ef-video>
  <ef-audio assetId="17a4c803-785f-475b-bed8-81d892fe941e"></ef-audio>
</ef-timegroup>

Styling

<ef-timegroup> elements can be styled using standard CSS techniques.

<ef-timegroup class="relative h-[500px] w-[500px] overflow-hidden bg-slate-500">
  <!-- Content -->
</ef-timegroup>

In this example, we're using utility classes (from Tailwind CSS) to set the dimensions, positioning, and background color of the timegroup. But any approach to CSS styling can be used.

Attributes

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.

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.