editframe-composition

name	editframe-composition
title	Video Composition
description	Create video compositions with Editframe using HTML web components or React. Supports video, audio, images, text, captions, transitions, and cloud rendering.
order	10
license	MIT
metadata	{"author":"editframe","version":"2.0"}

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.