Live2D

The Live2DRenderer renders a Live2D Cubism model in the browser using @live2d-loader/core with pluggable rendering backends. It supports automatic blink, pointer tracking, expression presets, both RMS-based and viseme-based lip-sync, and switchable WebGL / WebGPU rendering.

Usage

import { Live2DRenderer } from "avatarlayer/renderers";

const renderer = new Live2DRenderer({
  modelUrl: "/models/avatar/model.model3.json", // Cubism 5
  frameMode: "upperBodyFocus",
  autoBlink: true,
  renderer: "webgpu", // use WebGPU for Cubism 3/4/5 models
});

Constructor options

Frame modes

WebGL / WebGPU backends

The renderer automatically selects the appropriate backend based on the model type and renderer setting:

How it works

When mounted, the renderer:

1. Detects the Cubism version from the model URL extension
2. Loads the appropriate Cubism adapter (Cubism2Adapter or Cubism5Adapter)
3. Creates the rendering backend (WebGL or WebGPU) based on the model type and preference
4. Loads the model via @live2d-loader/core
5. Starts automatic blink and idle motion loops
6. Begins a render loop at screen refresh rate

Peer dependencies

The Live2D renderer requires these packages to be installed:

• @live2d-loader/core
• @live2d-loader/renderer-webgl
• @live2d-loader/adapter-cubism2 (for Cubism 2 models)
• @live2d-loader/adapter-cubism5 (for Cubism 3/4/5 models)

When speak(audio) is called:

1. The audio blob is played through an <audio> element
2. Audio is analyzed in realtime for lip-sync — either via RMS amplitude or viseme weights
3. The mouth parameters on the Live2D model are updated each frame
4. The promise resolves when the audio ends

Avatar control

The Live2D renderer responds to update() calls for expression and emotion control:

session.updateControl({
  avatar: {
    emotion: {
      label: "happy",
      intensity: 0.8,
      valence: 0.7,
      arousal: 0.5,
    },
  },
});

Supported expressions are mapped automatically: happy, sad, angry, surprised, relaxed, neutral. The renderer matches available model expressions to the requested emotion.

Cubism version parameter mapping

The renderer automatically uses the correct parameter IDs for each Cubism version: