Skip to main content

Documentation Index

Fetch the complete documentation index at: https://hyperframes-split-cli-media-skills.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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

HyperFrames does not automatically bind data-var-* attributes into your composition DOM or CSS. The supported pattern is:
  1. Declare the variables once on the sub-comp’s <html> root with data-composition-variables (id + type + default).
  2. Pass per-instance values on each composition host with data-variable-values.
  3. Read the resolved values inside the composition with window.__hyperframes.getVariables(). The runtime layers the host’s data-variable-values over the declared defaults on a per-instance basis, so the same source can be embedded multiple times with different values.
index.html
<div
  data-composition-id="card-pro"
  data-composition-src="compositions/card.html"
  data-start="0"
  data-track-index="1"
  data-variable-values='{"title":"Pro","color":"#ff4d4f"}'
></div>
<div
  data-composition-id="card-enterprise"
  data-composition-src="compositions/card.html"
  data-start="card-pro"
  data-track-index="1"
  data-variable-values='{"title":"Enterprise","color":"#22c55e"}'
></div>
compositions/card.html
<html data-composition-variables='[
  {"id":"title","type":"string","label":"Title","default":"Fallback"},
  {"id":"color","type":"color","label":"Color","default":"#111827"}
]'>
  <body>
    <div data-composition-id="card" data-width="1920" data-height="1080">
      <h1 class="title"></h1>

      <style>
        [data-composition-id="card"] {
          --card-color: #111827;
        }

        [data-composition-id="card"] .title {
          color: var(--card-color);
        }
      </style>

      <script>
        // Inside a sub-comp script, getVariables() returns the per-instance
        // values: declared defaults < host data-variable-values overrides.
        const { title, color } = __hyperframes.getVariables();
        const root = document.querySelector('[data-composition-id="card"]');
        root.querySelector(".title").textContent = title;
        root.style.setProperty("--card-color", color);
      </script>
    </div>
  </body>
</html>
If you are building tooling on top of @hyperframes/core, the same data-composition-variables array is readable via extractCompositionMetadata() for Studio editing UI and analysis pipelines.

​
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

Examples

Start from built-in examples for common video patterns

HTML Schema Reference

Complete schema for authoring compositions