commotion-engine

Rust-powered animation engine compiled to WebAssembly. Create, validate, and render animated scenes from JSON descriptions.

Install

npm install commotion-engine

Usage

import init, { Commotion } from 'commotion-engine';

await init();

const engine = new Commotion();

// Validate a scene
const diagnostics = engine.validate(JSON.stringify({
  width: 960,
  height: 540,
  background: "#1a1a2e",
  layers: [
    { type: "text", content: "Hello", position: ["50%", "50%"], size: 48, fill: "#ffffff", align: "center" },
    { type: "circle", center: [480, 400], radius: 60, fill: "#3b82f6" }
  ]
}));

// Load and render
const handle = engine.load_scene(sceneJson);
const info = JSON.parse(engine.sceneInfo(handle));
const rgba = engine.render_frame_rgba(handle, 0.0); // Uint8Array of RGBA pixels

// Draw to canvas
const canvas = document.getElementById('canvas');
canvas.width = info.width;
canvas.height = info.height;
const ctx = canvas.getContext('2d');
const imageData = new ImageData(new Uint8ClampedArray(rgba), info.width, info.height);
ctx.putImageData(imageData, 0, 0);

API

new Commotion()

Create an engine instance.

.validate(json: string): string

Validate a scene JSON string. Returns JSON with { errors: [...] }.

.load_scene(json: string): number

Load a scene and return a handle for rendering.

.sceneInfo(handle: number): string

Get scene metadata (width, height, fps, duration, layer IDs).

.duration(handle: number): number

Get the total animation duration in seconds.

.render_frame_rgba(handle: number, t: number): Uint8Array

Render a frame at time t (seconds). Returns raw RGBA pixel data.

Commotion.schema(): string

Get the full JSON Schema for the scene format.

Commotion.compactSchema(): string

Get a compact schema reference (useful as LLM context).

Commotion.generateSpeechTrack(script: string, wpm: number): string

Generate timed speech segments from a script.

Commotion.buildSubtitleTrack(speechJson: string, maxWordsPerCue: number): string

Build subtitle cues from a speech track.

Scene Format

Scenes are JSON objects with layers, animations, and sequences:

{
  "width": 960,
  "height": 540,
  "fps": 30,
  "background": "#0a0a1a",
  "layers": [
    {
      "type": "text",
      "content": "NEON",
      "position": ["50%", "50%"],
      "size": 72,
      "fill": "#00e5ff",
      "align": "center",
      "text_style": { "neon": { "glow_color": "#00e5ff" } }
    }
  ],
  "sequences": [
    {
      "name": "intro",
      "animations": [
        { "target": "layer_0", "effect": "fade_in", "duration": 1.0 }
      ]
    }
  ]
}

Supports: shapes, text (with neon glow), charts, paths, groups, blend modes, masks, spring physics, stagger animations, and more.

License

MIT