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 use the timeline to scrub.

Create a file called videos/template.video.ts:

Use defaults for fallback values when no data is passed. The render function receives data from the context (merged from defaults 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.

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 -o output.mp4 --data '{"title": "Dynamic Video", "subtitle": "Rendered from CLI"}'

SuperImg will render every frame headlessly and encode it into a high-quality MP4.

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'
 
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.