hyperframes/docs/quickstart.mdx

---
title: Quickstart
description: "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

- **Node.js 22+** — runtime for the CLI and dev server
- **FFmpeg** — video encoding for local renders

<Accordion title="Install instructions">
  <Steps>
    <Step title="Install Node.js 22+">
      Hyperframes requires Node.js 22 or later. Check your version:

      ```bash
      node --version
      ```

      ```bash Expected output
      v22.0.0   # or any version >= 22
      ```
    </Step>

    <Step title="Install FFmpeg">
      FFmpeg is required for local video rendering (encoding captured frames into MP4).

      <CodeGroup>
      ```bash macOS
      brew install ffmpeg
      ```
      ```bash Ubuntu / Debian
      sudo apt install ffmpeg
      ```
      ```bash Windows
      # Download from https://ffmpeg.org/download.html
      # or install via winget:
      winget install ffmpeg
      ```
      </CodeGroup>

      Verify the installation:

      ```bash
      ffmpeg -version
      ```

      ```bash Expected output
      ffmpeg version 7.x ...
      ```
    </Step>
  </Steps>
</Accordion>

## Create your first video

<Steps>
  <Step title="Scaffold the project">
    ```bash
    npx hyperframes init my-video
    cd my-video
    ```

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

    ```bash
    npx hyperframes init my-video --non-interactive --example blank
    ```

    See [Examples](/examples) for all available examples.

    This generates a project structure like:

    <Tree>
      <Tree.Folder name="my-video" defaultOpen>
        <Tree.File name="meta.json" />
        <Tree.File name="index.html" />
        <Tree.Folder name="compositions" defaultOpen>
          <Tree.File name="intro.html" />
          <Tree.File name="captions.html" />
        </Tree.Folder>
        <Tree.Folder name="assets" defaultOpen>
          <Tree.File name="video.mp4" />
        </Tree.Folder>
      </Tree.Folder>
    </Tree>

    | 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:

    ```bash
    npx hyperframes init my-video --example warm-grain --video ./intro.mp4
    ```
  </Step>

  <Step title="Preview in the browser">
    ```bash
    npx hyperframes preview
    ```

    This starts the Hyperframes Studio and opens your composition in the browser. Edits to `index.html` reload automatically.

    <Tip>
      The dev server supports hot reload — save your HTML file and the preview updates instantly, no manual refresh needed.
    </Tip>
  </Step>

  <Step title="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:

    ```html 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`
  </Step>

  <Step title="Render to MP4">
    ```bash
    npx hyperframes render --output output.mp4
    ```

    ```bash 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.
  </Step>
</Steps>

## 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

<CardGroup cols={2}>
  <Card title="Compositions" icon="layer-group" href="/concepts/compositions">
    Learn how compositions, clips, and nested timelines work together
  </Card>
  <Card title="GSAP Animation" icon="wand-magic-sparkles" href="/guides/gsap-animation">
    Add fade, slide, scale, and custom animations to your videos
  </Card>
  <Card title="Examples" icon="grid-2" href="/examples">
    Start from built-in examples like Warm Grain and Swiss Grid
  </Card>
  <Card title="Rendering" icon="film" href="/guides/rendering">
    Explore render options: quality presets, Docker mode, and GPU encoding
  </Card>
</CardGroup>