Getting Started

The fastest way to start building with SuperImg is to use the CLI to scaffold a new project.

Quick Start

Run the init command to create a new SuperImg project:

npx superimg init my-video-project
cd my-video-project

This sets up a fresh directory with the SuperImg CLI, the standard library, and a starter template.

Manual Installation

If you prefer to add SuperImg to an existing project:

npm install superimg

For React projects, the <Player> component is included in the same package — no extra install needed.

Your First Template

A SuperImg template is a function that takes time and data, and returns HTML. Create a template that accepts a dynamic title and subtitle. The demo below shows the code and a live preview — click the video to play or pause, or scrub through frames.

Create a file called template.media.ts:

Use sample for fallback values when no data is passed. The render function receives data from the context (merged from sample and any input you pass at render time).

Live Preview

To see your template in action, start the local development server:

npx superimg dev template

This opens a live preview in your browser. Edit your code, and the video updates instantly at 60fps.

Note on Browser Support: The live playground and in-browser compilation require a browser that supports cross-origin isolation. If your browser does not support this (or if the required headers are not set by the host), you will see an "unsupported browser" message.

Render to MP4

When you are ready to export, use the render command.

Rendering requires a Chromium browser. If you skipped the download during init, run this once first:

npx superimg setup

Because our template accepts data, we can pass a JSON string to generate a personalized video:

npx superimg render template --data '{"title": "Dynamic Video", "subtitle": "Rendered from CLI"}'

Output is written to output/template.mp4 next to your template file. SuperImg renders every frame headlessly and encodes it into a high-quality MP4.

Other output formats

# Animated GIF
npx superimg render template --format gif
 
# Single-frame still (PNG)
npx superimg render template --frame 45 --format png
 
# Static image template (no fps/duration in config)
npx superimg render og-card.media.ts

Use in React

If you are building a web app, you can embed your templates directly in the browser using the <Player> component.

Just like the CLI, you can pass data to the player to update the video dynamically:

import { Player } from 'superimg/react/player'
import myTemplate from './template.media'
 
function App() {
  return (
    <Player
      template={myTemplate}
      data={{ 
        title: "React Player", 
        subtitle: "Interactive video" 
      }}
      format="horizontal"
      playbackMode="loop"
      style={{ width: '100%', maxWidth: 640, aspectRatio: '16/9' }}
    />
  )
}

Next Steps

• Read the Introduction for the core concepts and mental model.
• Explore the RenderContext and template config options.
• Check the standard library for easing, math, and color helpers.