Video Composition

Build video compositions with HTML web components (<ef-timegroup>, <ef-video>, etc.) or React (<Timegroup>, <Video>, etc.). Same composition model, same rendering pipeline — pick the syntax that fits your project.

Web component attributes use kebab-case (sourcein, auto-init). React props use camelCase (sourceIn, autoInit). Each element reference documents both.

Before opening any reference file, answer:

1. HTML or React?

• HTML/web components — kebab-case attributes, works in any HTML file
• React — camelCase props, requires TimelineRoot wrapper (see references/timeline-root.md)

2. What's the core structure? Every composition is a tree of ef-timegroup containers. Pick a mode:

• mode="sequence" — children play one after another (scenes)
• mode="fixed" — children play simultaneously for a set duration
• mode="contain" — expands to fit children

3. What does the user need?

Need	Reference
Arrange clips in sequence	timegroup, sequencing
Animate text	text, css-variables
Video/audio/image	video, audio, image
Per-frame canvas animation	scripting
Scene transitions	transitions
Captions/subtitles	captions
Export to MP4	render-to-video or use editframe-cli
Cloud rendering	render-api

The single gate: Does the composition have explicit dimensions (w-[1920px] h-[1080px] or equivalent) on the root timegroup? If not, the renderer has nothing to frame against — add them before anything else.

Quick Start

<ef-configuration api-host="..." media-engine="local">
  <ef-timegroup mode="sequence" overlap="1s">
    <ef-timegroup mode="fixed" duration="5s" class="absolute w-full h-full">
      <ef-video src="intro.mp4" class="size-full object-cover"></ef-video>
      <ef-text
        split="word"
        class="absolute top-8 left-8 text-white text-4xl font-bold"
        style="animation: 0.6s slide-up both; animation-delay: calc(var(--ef-word-index) * 80ms)"
      >Opening Title</ef-text>
    </ef-timegroup>
    <ef-timegroup mode="fixed" duration="5s" class="absolute w-full h-full">
      <ef-video src="main.mp4" sourcein="10s" sourceout="15s" class="size-full"></ef-video>
      <ef-audio src="music.mp3" volume="0.3"></ef-audio>
    </ef-timegroup>
  </ef-timegroup>
</ef-configuration>
<style>
  @keyframes slide-up {
    from { transform: translateY(24px); opacity: 0; }
    to   { transform: translateY(0);    opacity: 1; }
  }
</style>

import { Timegroup, Video, Text, Audio } from "@editframe/react";

export const MyVideo = () => (
  <Timegroup mode="sequence" overlap="1s" className="w-[1920px] h-[1080px]">
    <Timegroup mode="fixed" duration="5s" className="absolute w-full h-full">
      <Video src="intro.mp4" className="size-full object-cover" />
      <Text
        split="word"
        className="absolute top-8 left-8 text-white text-4xl font-bold"
        style={{ animation: "0.6s slide-up both", animationDelay: "calc(var(--ef-word-index) * 80ms)" }}
      >Opening Title</Text>
    </Timegroup>
    <Timegroup mode="fixed" duration="5s" className="absolute w-full h-full">
      <Video src="main.mp4" sourceIn="10s" sourceOut="15s" className="size-full" />
      <Audio src="music.mp3" volume={0.3} />
    </Timegroup>
  </Timegroup>
);

@keyframes slide-up {
  from { transform: translateY(24px); opacity: 0; }
  to   { transform: translateY(0);    opacity: 1; }
}

React requires a TimelineRoot wrapper — see references/timeline-root.md.

Duration Units

5s (seconds) | 1000ms (milliseconds) | 2m (minutes)

Getting Started

Create a project: npm create @editframe (see the editframe-create skill)

• references/getting-started.md — Your first composition

Motion

Motion is how compositions become video rather than presentations. These are the primary tools.

• references/text.md — Word/character splitting, stagger animations, --ef-stagger-offset
• references/css-variables.md — --ef-progress, --ef-duration, time-driven CSS
• references/scripting.md — addFrameTask for per-frame canvas and procedural animation
• references/transitions.md — Crossfades, slides, zoom transitions between scenes
• references/r3f.md — React Three Fiber 3D integration

Media Elements

• references/video.md — Video clips, trimming, effects
• references/audio.md — Audio, volume
• references/image.md — Static images
• references/captions.md — Subtitles with word highlighting
• references/waveform.md — Audio visualization

Layout & Timing

• references/timegroup.md — Container, sequencing, scenes
• references/sequencing.md — Sequential scene playback
• references/surface.md — Mirror another element
• references/time-model.md — How time propagates through the tree

Rendering

• references/render-to-video.md — Export to MP4 in the browser
• references/render-api.md — Render API and custom render data
• references/transcription.md — Generate captions with WhisperX

See the editframe-cli skill for CLI rendering.

React

• references/timeline-root.md — Required wrapper for React compositions
• references/hooks.md — useTimingInfo, usePanZoomTransform
• references/use-media-info.md — useMediaInfo hook

Advanced

• references/configuration.md — Media engine and API host
• references/server-rendering.md — SSR with Next.js/Remix
• references/entry-points.md — Package exports
• references/events.md — Custom event catalog
• references/css-parts.md — Shadow DOM styling

Styling

Elements use standard CSS/Tailwind. Position with absolute, size with w-full h-full or size-full.