Player

Embed SuperImg templates directly in web apps. The Player renders templates in the browser using real HTML/CSS in a sandboxed iframe — no video file needed for preview.

Installation

npm install superimg

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

Basic Usage

Vanilla JavaScript

import { Player } from 'superimg/browser';
import template from './my-video.media';
 
const player = new Player({ container: '#video', format: 'horizontal' });
await player.load(template);
player.play();

React

import { Player } from 'superimg/react/player';
import template from './my-video.media';
 
function App() {
  return (
    <Player
      template={template}
      format="horizontal"
      playbackMode="loop"
      controls
      style={{ width: '100%', maxWidth: 640, aspectRatio: '16/9' }}
    />
  );
}

Playback Controls

player.play();
player.pause();
 
player.isPlaying;
player.isReady;
player.currentFrame;
player.totalFrames;
player.fps;

Seeking

player.seekFrame(50);
player.seekTimeSeconds(2.5);
player.seekProgress(0.5);

Dynamic Data

await player.load(template, { data: { title: 'Hello' } });
player.update({ data: { title: 'Updated Title' } });

Format Options

const player = new Player({ container: '#video', format: 'horizontal' });
player.update({ format: 'vertical' });
player.update({ width: 800, height: 600 });

Playback Modes

const player = new Player({
  container: '#video',
  playbackMode: 'loop',  // or 'once'
});

Store (vanilla UI)

const store = player.store;
store.subscribe(() => {
  const { isPlaying, currentFrame, isScrubbing } = store.getState();
});
store.getState().togglePlayPause();
store.getState().setFrame(30);

Use createTimelineController from superimg/browser for scrubbing UI.

Events

player.on('play', () => {});
player.on('pause', () => {});
player.on('ended', () => {});
player.on('ready', () => {});
player.on('frame', (frame, totalFrames) => {});
player.on('rendered', (payload) => {}); // payload.compositeHtml for inspector/debug
player.on('scenechange', (scene) => {});
player.on('error', (err) => {});

Composed Templates

import { compose } from 'superimg';
 
const composed = compose([intro, content, outro]);
await player.load(composed);
 
player.seekScene('intro');
player.seekScene(0);
player.nextScene();
player.previousScene();

Checkpoints

player.goToCheckpoint('chorus');
player.nextCheckpoint();
player.prevCheckpoint();
player.addCheckpoint('chorus', 120, { label: 'Chorus' });
player.removeCheckpoint('chorus');

Player Options

const player = new Player({
  container: '#video',
  format: 'horizontal',
  playbackMode: 'once',
  loadMode: 'eager',
  hoverBehavior: 'none',
  hoverDelayMs: 200,
});

React Props

<Player
  template={template}
  data={{ title: 'Dynamic' }}
  format="horizontal"
  playbackMode="loop"
  autoPlay
  controls="full"
  onStore={(store) => {}}
  onPlay={() => {}}
  onPause={() => {}}
  onFrame={(frame) => {}}
/>

Browser Export

Preview (Player) and export (exportToVideo) are separate paths:

import { CanvasRenderer, exportToVideo, downloadBlob } from 'superimg/browser';

See the docs playground or usePlaygroundExport for a complete export example.