zeroweight-renderer

Universal avatar rendering engine. Framework-agnostic — use via CDN <script> tag or ES module import.

Installation

CDN (Script Tag)

<script src="https://unpkg.com/zeroweight-renderer/dist/zeroweight-renderer.umd.js"></script>

Or via jsDelivr:

<script src="https://cdn.jsdelivr.net/npm/zeroweight-renderer/dist/zeroweight-renderer.umd.js"></script>

npm / yarn

npm install zeroweight-renderer

Quick Start

Via <script> tag

<canvas id="avatar" width="640" height="480"></canvas>

<script src="https://unpkg.com/zeroweight-renderer/dist/zeroweight-renderer.umd.js"></script>
<script>
  const { ZeroWeightRenderer, ActionQueue, VoiceActivityDetector } = window.ZeroWeightRenderer;

  const renderer = new ZeroWeightRenderer();
  const canvas = document.getElementById('avatar');

  // Init with your avatar bundle payload
  await renderer.init(canvas, { payload: bundleData });

  // Play actions
  renderer.play('speaking');
  renderer.play('wave_hand', 'listening'); // oneshot with fallback

  // Clean up
  renderer.destroy();
</script>

Via ES module

import {
  ZeroWeightRenderer,
  ActionQueue,
  VoiceActivityDetector,
} from "zeroweight-renderer";

const renderer = new ZeroWeightRenderer();
await renderer.init(canvas, { payload: bundleData });

API

ZeroWeightRenderer

The core rendering engine. Handles WASM initialization, canvas setup, render loop, and action management.

const renderer = new ZeroWeightRenderer();

| Method | Description | | --------------------------- | -------------------------------------------------- | | init(canvas, config) | Initialize with a canvas element and bundle config | | play(actionId, fallback?) | Play an action (e.g. "speaking", "wave_hand") | | interrupt() | Interrupt the current action | | destroy() | Clean up all resources |

| Property | Description | | ------------ | ---------------------------------------------------------------- | | state | Current state: "idle" | "loading" | "ready" | "error" | | isReady | true when engine is ready | | dimensions | Avatar intrinsic { width, height } |

Events: ready, actionLoaded, allActionsLoaded, dimensions, error, stateChanged

renderer.on("ready", () => console.log("Engine ready!"));
renderer.on("dimensions", (w, h) => console.log(`Avatar: ${w}x${h}`));

ActionQueue

Centralized action dispatch with turn-based queuing for speech synchronization.

const queue = new ActionQueue((actionId, fallback) => {
  renderer.play(actionId, fallback);
});

queue.dispatch("wave_hand"); // Execute or queue
queue.setTurnActive(true); // Start speaking turn
queue.setSpeechState("speaking"); // Update speech state
queue.forceListening(); // Reset to listening

VoiceActivityDetector

Amplitude-based VAD using Web Audio API with hysteresis for lipsync.

const vad = new VoiceActivityDetector({
  threshold: 0.008,
  speechStartFrames: 1,
  speechPauseFrames: 30,
  turnEndFrames: 50,
});

vad.on("speechStart", () => queue.setTurnActive(true));
vad.on("turnEnd", () => queue.setTurnActive(false));

vad.start(mediaStreamTrack);

Usage Tiers

| Tier | What you get | Use case | | ------------------ | -------------------------------------------------------------------------------------- | ------------------------ | | Tier 1 (Raw) | ZeroWeightRenderer only | Custom engine control | | Tier 2 (Queue) | + ActionQueue + VoiceActivityDetector | Speech-synced avatars | | Tier 3 (React) | zeroweight-renderer-react | Drop-in React components |

Build from Source

git clone <repo-url>
cd zeroweight-renderer
npm install
npm run build

Output in dist/:

• zeroweight-renderer.umd.js — UMD bundle (script tag)
• zeroweight-renderer.es.js — ES module
• index.d.ts — TypeScript declarations

License

MIT