Skip to main content
A composition is an HTML document that defines a video timeline. Every clip — video, image, audio — lives inside a composition.

​
Structure

Every composition needs a root element with data-composition-id:
index.html
<div id="root" data-composition-id="root"
     data-start="0" data-width="1920" data-height="1080">
  <!-- Elements go here -->
</div>
The index.html file is the top-level composition. It can contain nested compositions within it. Any composition can be imported into another — there is no special “root” type.

​
Clip Types

A clip is any discrete block on the timeline, represented as an HTML element with data attributes:
  • <video> — Video clips, B-roll, A-roll
  • <img> — Static images, overlays
  • <audio> — Music, sound effects
  • <div data-composition-id="..."> — Nested compositions (animations, grouped sequences)
See the HTML Schema Reference for the full list of attributes on each clip type.

​
Nested Compositions

You can embed one composition inside another in two ways: loading from an external file or defining it inline. External files are the recommended approach for reusable compositions.
Reference another HTML file with data-composition-src. The framework automatically fetches the file, extracts the <template> content, mounts it, executes scripts, and registers the timeline.
index.html
<div
  id="el-5"
  data-composition-id="intro-anim"
  data-composition-src="compositions/intro-anim.html"
  data-start="0"
  data-track-index="3"
></div>
Each external composition file wraps its content in a <template> tag:
compositions/intro-anim.html
<template id="intro-anim-template">
  <div data-composition-id="intro-anim" data-width="1920" data-height="1080">
    <div class="title">Welcome!</div>

    <style>
      [data-composition-id="intro-anim"] .title {
        font-size: 72px; color: white; text-align: center;
      }
    </style>

    <script>
      const tl = gsap.timeline({ paused: true });
      tl.from(".title", { opacity: 0, y: -50, duration: 1 });
      window.__timelines["intro-anim"] = tl;
    </script>
  </div>
</template>

​
Project Structure

project
index.html
compositions
intro-anim.html
caption-overlay.html
outro-title.html

​
Two Layers: Primitives and Scripts

Every composition has two layers:
  • HTML — primitive clips (video, img, audio, nested compositions). The declarative structure: what plays, when, and on which track. Controlled by data attributes.
  • Script — effects, transitions, dynamic DOM, canvas, SVG — creative animation via GSAP. Scripts do not control media playback or clip visibility.
Never use scripts to play/pause/seek media elements or to show/hide clips based on timing. The framework handles this automatically from data attributes. Scripts that duplicate this behavior will conflict with the framework. See Common Mistakes for examples.

​
Variables

Compositions can expose variables for dynamic content:
compositions/card.html
<div data-composition-id="card" data-var-title="string" data-var-color="color">
Variables make compositions reusable as templates — the same composition can render different content by injecting variable values at render time.

​
Listing Compositions

Use the CLI to see all compositions in a project: 
npx hyperframes compositions

​
Next Steps

Data Attributes

Full reference for timing, media, and composition attributes

GSAP Animation

Add animations to your compositions with GSAP timelines

Templates

Start from built-in templates for common video patterns

HTML Schema Reference

Complete schema for authoring compositions