Advanced Usage

Advanced Usage

Use @zeroweight/react when you want renderer lifecycle management and LiveKit wiring, but still need full UI control.

Custom UI with useAvatarSession

import { LiveKitRoom } from "@livekit/components-react";
import { LiveKitAvatarProvider, useAvatarSession } from "@zeroweight/react";
 
export function CustomAvatar() {
  const session = useAvatarSession({
    avatarId: "your-avatar-id",
    apiKey: "optional-api-key"
  });
 
  return (
    <div>
      <div ref={session.containerRef} style={{ width: 640, height: 480 }} />
 
      <button onClick={session.connect}>Connect</button>
      <button onClick={session.disconnect}>Disconnect</button>
      <button onClick={() => session.runAction("wave_hand")}>Wave</button>
 
      {session.token && (
        <LiveKitRoom
          serverUrl={session.livekitUrl}
          token={session.token}
          connect
          audio
          onConnected={session.markConnected}
          onDisconnected={session.disconnect}
        >
          <LiveKitAvatarProvider session={session} />
        </LiveKitRoom>
      )}
    </div>
  );
}

Renderer-only flow

If you do not want the React package, use the core renderer library directly. This is ideal for non-React frameworks or plain JavaScript projects.

Source: @zeroweight/renderer (opens in a new tab)

Installation

Add the library via unpkg:

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

Sample Usage

<canvas id="avatar" width="640" height="480"></canvas>
 
<script src="https://unpkg.com/@zeroweight/renderer/dist/zeroweight-renderer.umd.js"></script>
<script>
  (async () => {
    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 a simple action
    renderer.play("wave_hand");
 
    // Play an action with a fallback (e.g. oneshot -> loop)
    // This plays 'greeting' then automatically transitions to 'listening'
    renderer.play("greeting", "listening");
  })();
</script>
Quick StartSecurity