Quickstart

Create, preview, and render your first Hyperframes video in under two minutes.

Go from zero to a rendered MP4: scaffold a project, edit with your AI agent, preview live, 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 22+

   Hyperframes requires Node.js 22 or later. Check your version:

   node --version
   

   Expected output

   v22.0.0   # or any version >= 22
   
2. Install FFmpeg

   FFmpeg is required for local video rendering (encoding captured frames into MP4).

   macOS

   brew install ffmpeg
   

   Verify the installation:

   ffmpeg -version
   

   Expected output

   ffmpeg version 7.x ...
   

Create your first video

1. Scaffold the project

   npx hyperframes init my-video
   cd my-video
   

   This starts an interactive wizard that walks you through template selection and media import. To skip prompts (e.g. in CI or from an agent), use --non-interactive:

   npx hyperframes init my-video --non-interactive --template blank
   

   See Templates for all available templates.

   This generates a project structure like:

   my-video

   meta.json

   index.html

   compositions

   intro.html

   captions.html

   assets

   video.mp4

   Path	Purpose
   meta.json	Project metadata (name, ID, creation date)
   index.html	Root composition — your video’s entry point
   compositions/	Sub-compositions loaded via data-composition-src
   assets/	Media files (video, audio, images)

   If you have a source video, pass it with --video for automatic transcription and captions:

   npx hyperframes init my-video --template warm-grain --video ./intro.mp4
   
2. Preview in the browser

   npx hyperframes preview
   

   This starts the Hyperframes Studio and opens your composition in the browser. 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 the project with your AI coding agent (Claude Code, Cursor, etc.) — HyperFrames skills are installed automatically and your agent knows how to create and edit compositions.

   Or edit index.html directly — here’s a minimal 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 --output 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

Dependency	Required	Notes
Node.js 22+	Yes	Runtime for CLI and dev server
npm or bun	Yes	Package manager
FFmpeg	Yes	Video encoding for local renders
Docker	No	Optional — 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 Warm Grain and Swiss Grid

Rendering

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