Skip to main content
Go from zero to a rendered MP4 in four steps: scaffold a project, preview it live, customize the composition, and render.

​
What you’ll build

A 1920x1080 video with an animated title that fades in from above — rendered to MP4 on your local machine. The entire composition is a single HTML file.

​
Prerequisites

1

Install Node.js 20+

Hyperframes requires Node.js 20 or later. Check your version:
node --version
Expected output
v20.11.0   # or any version >= 20
2

Install FFmpeg

FFmpeg is required for local video rendering (encoding captured frames into MP4).
brew install ffmpeg
Verify the installation:
ffmpeg -version
Expected output
ffmpeg version 7.x ...

​
Create your first video

1

Scaffold the project

npx create-hyperframe my-video
cd my-video
Expected output
✔ Created my-video/
✔ index.html
✔ assets/
Done. Run `npx hyperframes dev` to preview.
This generates the following project structure:
my-video
index.html
compositions
.gitkeep
assets
.gitkeep
PathPurpose
index.htmlRoot composition — your video’s entry point
compositions/Sub-compositions loaded via data-composition-src
assets/Media files (video, audio, images)
2

Preview in the browser

npx hyperframes dev
Expected output
✔ Hyperframes dev server running
  → http://localhost:3000
Open http://localhost:3000 to see the live preview. Edits to index.html reload automatically.
The dev server supports hot reload — save your HTML file and the preview updates instantly, no manual refresh needed.
3

Edit the composition

Open index.html and replace it with this composition:
index.html
<div id="root" data-composition-id="my-video"
     data-start="0" data-width="1920" data-height="1080">

  <!-- 1. Define a timed text clip on track 0 -->
  <h1 id="title" class="clip"
      data-start="0" data-duration="5" data-track-index="0"
      style="font-size: 72px; color: white; text-align: center;
             position: absolute; top: 50%; left: 50%;
             transform: translate(-50%, -50%);">
    Hello, Hyperframes!
  </h1>

  <!-- 2. Load GSAP for animation -->
  <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>

  <!-- 3. Create a paused timeline and register it -->
  <script>
    const tl = gsap.timeline({ paused: true });
    tl.from("#title", { opacity: 0, y: -50, duration: 1 }, 0);
    window.__timelines = window.__timelines || {};
    window.__timelines["my-video"] = tl;
  </script>
</div>
Three rules to remember:
  • Root element must have data-composition-id, data-width, and data-height
  • Timed elements need data-start, data-duration, data-track-index, and class="clip"
  • GSAP timeline must be created with { paused: true } and registered on window.__timelines
4

Render to MP4

npx hyperframes render -o output.mp4
Expected output
✔ Capturing frames... 150/150
✔ Encoding MP4...
✔ output.mp4 (1920x1080, 5.0s, 30fps)
Your video is now at output.mp4. Open it with any media player.

​
Requirements summary

DependencyRequiredNotes
Node.js 20+YesRuntime for CLI and dev server
bun or npmYesPackage manager (bun recommended)
FFmpegYesVideo encoding for local renders
DockerNoOptional — for deterministic, reproducible renders

​
Next steps

Compositions

Learn how compositions, clips, and nested timelines work together

GSAP Animation

Add fade, slide, scale, and custom animations to your videos

Templates

Start from built-in templates like title-card and video-edit

Rendering

Explore render options: quality presets, Docker mode, and GPU encoding