hyperframes/docs/guides/templates.mdx

---
title: Templates
description: "Built-in templates for common video patterns."
---

Hyperframes includes starter templates to help you scaffold compositions quickly. Each template gives you a working project with the correct [composition structure](/concepts/compositions), [data attributes](/concepts/data-attributes), and a [GSAP timeline](/guides/gsap-animation) already wired up.

## Using Templates

```bash Terminal
npx hyperframes init --template <name>
```

This creates a new project directory with an `index.html` composition, sub-compositions, and any required assets.

You can also run `npx hyperframes init` without `--template` to choose interactively.

## Available Templates

<Tabs>
  <Tab title="blank">
    ### blank

    An empty composition with just the scaffolding — a video element, audio track, captions sub-composition, and an empty GSAP timeline. Start from scratch.

    **What it produces:** A minimal project with a single video clip and audio, ready for you to customize. The timeline is registered and ready for you to add tweens.

    **When to use it:** You have a specific design in mind and want full control. Good for AI agent workflows that will generate the composition programmatically, or when starting from a source video.

    ```bash Terminal
    npx hyperframes init my-video --template blank
    ```

    **What you get:**
    ```
    my-video/
    ├── meta.json
    ├── index.html
    └── compositions/
        └── captions.html
    ```
  </Tab>
  <Tab title="warm-grain">
    ### warm-grain

    A cream-toned aesthetic with grain texture overlay. Warm, organic feel suited for lifestyle and branding videos.

    **What it produces:** A composition with warm color grading, textured grain, and smooth transitions. Includes an intro sub-composition and captions support.

    **When to use it:** You want an organic, stylized look for branding, lifestyle, or editorial content.

    ```bash Terminal
    npx hyperframes init my-video --template warm-grain
    ```

    **What you get:**
    ```
    my-video/
    ├── meta.json
    ├── index.html
    ├── compositions/
    │   ├── intro.html
    │   ├── graphics.html
    │   └── captions.html
    └── assets/
    ```
  </Tab>
  <Tab title="play-mode">
    ### play-mode

    Playful elastic animations with bold, energetic motion.

    **What it produces:** A composition with bouncy, elastic animation curves and dynamic layout transitions. Includes intro, stats, and captions sub-compositions.

    **When to use it:** You want a fun, high-energy feel — great for social media, product launches, or explainer videos.

    ```bash Terminal
    npx hyperframes init my-video --template play-mode
    ```

    **What you get:**
    ```
    my-video/
    ├── meta.json
    ├── index.html
    ├── compositions/
    │   ├── intro.html
    │   ├── stats.html
    │   └── captions.html
    └── assets/
    ```
  </Tab>
  <Tab title="swiss-grid">
    ### swiss-grid

    Structured grid layout inspired by Swiss/International Typographic Style.

    **What it produces:** A clean, grid-based composition with precise typography and structured layouts. Includes intro, graphics, and captions sub-compositions.

    **When to use it:** You want a clean, professional, information-dense layout — ideal for corporate videos, data presentations, or technical content.

    ```bash Terminal
    npx hyperframes init my-video --template swiss-grid
    ```

    **What you get:**
    ```
    my-video/
    ├── meta.json
    ├── index.html
    ├── compositions/
    │   ├── intro.html
    │   ├── graphics.html
    │   └── captions.html
    └── assets/
    ```
  </Tab>
  <Tab title="vignelli">
    ### vignelli

    Bold typography with red accents, inspired by Massimo Vignelli's design philosophy.

    **What it produces:** A striking composition with strong typographic hierarchy, red accent colors, and confident transitions. Includes overlays and captions sub-compositions.

    **When to use it:** You want a bold, authoritative visual style — great for headlines, announcements, or editorial content.

    ```bash Terminal
    npx hyperframes init my-video --template vignelli
    ```

    **What you get:**
    ```
    my-video/
    ├── meta.json
    ├── index.html
    ├── compositions/
    │   ├── overlays.html
    │   └── captions.html
    └── assets/
    ```
  </Tab>
</Tabs>

## Choosing a Template

| Template | Style | Best for |
|----------|-------|----------|
| `blank` | Minimal scaffolding | Full control, agent-generated, starting from video |
| `warm-grain` | Organic, textured | Lifestyle, branding, editorial |
| `play-mode` | Energetic, elastic | Social media, product launches |
| `swiss-grid` | Clean, structured | Corporate, data, technical |
| `vignelli` | Bold, typographic | Headlines, announcements |

<Tip>
  If you are new to Hyperframes, start with `warm-grain` or `play-mode` to see working animations and sub-compositions in action. Use `blank` when you want minimal scaffolding and full control. Run `npx hyperframes init` without `--template` to preview all options interactively.
</Tip>

## Passing a Source Video

You can initialize a project with your own video file using the `--video` flag:

```bash Terminal
npx hyperframes init my-video --template warm-grain --video ./my-clip.mp4
```

The CLI will probe the video for duration, resolution, and codec. If the video uses an incompatible codec (not H.264, VP8/9, AV1, or Theora), it will be automatically transcoded to H.264 MP4 if FFmpeg is available.

## Custom Templates

Any directory with an `index.html` can serve as a template. You can copy a directory manually or build your own init workflow.

Your custom template needs:

1. An `index.html` with a [`data-composition-id`](/concepts/data-attributes#composition-attributes) root element
2. A [GSAP timeline](/guides/gsap-animation) registered in `window.__timelines`
3. Any assets in the same directory or a subdirectory

```html index.html
<div id="root" data-composition-id="my-template"
     data-start="0" data-width="1920" data-height="1080">

  <!-- Your elements here -->

  <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
  <script>
    const tl = gsap.timeline({ paused: true });
    // Add your animations...
    window.__timelines = window.__timelines || {};
    window.__timelines["my-template"] = tl;
  </script>
</div>
```

After creating a custom template, validate it with the [linter](/packages/cli#lint):

```bash Terminal
npx hyperframes lint
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Create, preview, and render your first video
  </Card>
  <Card title="GSAP Animation" icon="wand-magic-sparkles" href="/guides/gsap-animation">
    Add animations to your template
  </Card>
  <Card title="Compositions" icon="layer-group" href="/concepts/compositions">
    Understand the composition data model
  </Card>
  <Card title="Rendering" icon="film" href="/guides/rendering">
    Render your composition to MP4
  </Card>
</CardGroup>