Forem: 老船长PZ_Jack

easy-live2d v0.4.0: A Milestone Release for Live2D on the Web

老船长PZ_Jack — Sat, 04 Apr 2026 15:21:27 +0000

easy-live2d v0.4.0: A Milestone Release for Live2D on the Web

After months of work, easy-live2d v0.4.0 is finally here.

This is a milestone release for the project. The goal of this update was clear from the beginning: strengthen the core capabilities, support more model formats, and refactor the overall architecture. In short, while keeping the external API largely unchanged, the internals were almost completely rewritten.

If you build with Live2D on the web, this release is meant to remove a lot of the friction that usually comes with it.

What is easy-live2d?

easy-live2d is a Pixi.js-oriented wrapper around Live2D. It is designed to make Live2D models feel like normal Pixi.js objects, so you can load, render, animate, and interact with them without fighting low-level integration details.

The project focuses on a compact API centered around Live2DSprite, with built-in support for common use cases such as:

model loading
hit detection
dragging
motion playback
expression switching
voice playback
lip sync

The idea is simple: make Live2D easier to use in real web projects.

A major refactor without breaking the API

The biggest change in v0.4.0 is not just a new feature. It is the architectural rewrite underneath.

This version was built to improve the core of the library while preserving the external developer experience as much as possible. For users already integrating easy-live2d, that means you can keep working with a familiar API while benefiting from a much stronger internal foundation.

That foundation matters, because it unlocks better compatibility, cleaner integration, and more room for future features.

Unified support for Cubism 3, 4, and 5

One of the most important improvements in v0.4.0 is broader model compatibility.

Previous versions could run into problems depending on the Cubism version used by a model. In v0.4.0, that gap has been addressed. The library now supports Cubism 3, 4, and 5 models through the same loading flow.

That means older assets and newer models can be handled in a much more consistent way:

const sprite = new Live2DSprite({
  modelPath: '/Resources/YourModel/model.model3.json',
  ticker: Ticker.shared,
})

app.stage.addChild(sprite)

You pass in the model path, and the library takes care of the rest.

Voice playback and lip sync in one line

Another major addition in this release is voice lip sync.

With v0.4.0, you can play a voice file and have the model's mouth animate automatically:

await sprite.playVoice({
  voicePath: '/sounds/hello.mp3',
})

This is especially useful for AI characters, virtual presenters, educational demos, desktop assistants, and interactive storytelling experiences.

The API supports common audio formats such as mp3, wav, and ogg, and it can also work with remote audio URLs. That makes it straightforward to connect Live2D characters to TTS pipelines or other dynamic voice sources.

Better Pixi.js integration

A common pain point when embedding Live2D into a Pixi.js project is rendering conflict. In practice, this often shows up as flickering, layer issues, or scene instability when Live2D content needs to coexist with UI, backgrounds, and other sprites.

v0.4.0 specifically improves this part of the experience.

A Live2D model behaves like a normal Pixi.js sprite, so you can position, scale, and compose it inside a regular scene graph:

sprite.width = 400
sprite.x = 100
sprite.y = 200

const container = new Container()
container.addChild(background)
container.addChild(sprite)
container.addChild(uiLayer)

That sounds small, but in real projects it makes a big difference. Live2D becomes easier to treat as part of the scene, rather than a special case that constantly needs workarounds.

Built-in interaction features

v0.4.0 also expands the out-of-the-box interaction layer.

You can enable mouse follow:

Config.MouseFollow = true

Respond to hit areas:

sprite.onLive2D('hit', ({ hitAreaName }) => {
  if (hitAreaName === 'Head') {
    sprite.setExpression({ expressionId: 'smile' })
  }
})

Make the model draggable:

const sprite = new Live2DSprite({
  modelPath: '/Resources/Hiyori/Hiyori.model3.json',
  draggable: true,
})

And control motions and expressions directly:

await sprite.startMotion({
  group: 'TapBody',
  no: 0,
  priority: Priority.Normal,
})

sprite.setExpression({ expressionId: 'smile' })

These are the kinds of features that many Live2D projects end up building anyway. Having them integrated into the library reduces setup time and keeps application code simpler.

Built for real-world web workflows

The release is also more practical from an engineering perspective.

easy-live2d can be used in plain HTML projects, modern frontend stacks such as Vue or React with Vite, and now also in Tauri desktop applications.

There is also a StackBlitz playground for quick testing directly in the browser.

Installation remains minimal:

pnpm add easy-live2d pixi.js

For model assets hosted on a CDN or another server, v0.4.0 also includes path redirection support, which helps avoid editing model files manually when asset paths need to be remapped.

Documentation and playground

This release is backed by a refreshed documentation site with both Chinese and English content, covering getting started guides as well as API details.

If you want to try it right away:

Docs: https://panzer-jack.github.io/easy-live2d
Playground: https://stackblitz.com/~/github.com/Panzer-Jack/easy-live2d-playground
GitHub: https://github.com/Panzer-Jack/easy-live2d

Closing

easy-live2d v0.4.0 is not just a feature update. It is a structural step forward for the project.

The external API stays familiar, but the internals have been heavily rebuilt to support more models, improve integration quality, and make Live2D easier to use in actual web applications.

If you are building virtual characters, AI companions, interactive sites, or desktop experiences with Live2D, this version is worth a look.

easy-live2d - Making Live2D integration easier!

老船长PZ_Jack — Tue, 03 Jun 2025 16:59:18 +0000

easy-live2d

Making Live2D integration easier! A lightweight, developer-friendly Live2D Web SDK wrapper library based on Pixi.js.

Make your Live2D as easy to control as a pixi sprite!

You can directly experience the charm of easy-live2d in your browser using this cloud IDE StackBlitz! 😋

📖 Documentation

👉 easy-live2d Official Documentation

TODO

(✅) Transfer Core capabilities to Sprite
(✅) Read model paths
(✅) Configuration file migration
(✅) Direct control of expressions and actions
(✅) Expose various event functions
(✅) Voice functionality
(✅ -) Mouth synchronization - Currently only supports wav format
WebGL rendering mounting issues (tentative)

✨ Features

⚡️ Support for Pixi.js v8 and Cubism 5 (both latest versions)
🌟 Ultra-lightweight, removing redundant features
🚀 Simpler API interface
🛠️ Compatible with official Live2D Web SDK
📦 Adaptable to modern frontend frameworks (like Vue, React)

⛵️ Developers

Due to Live2D policy, you need to download Live2D Cubism SDK for Web from the Live2D Cubism official website
and place its Core directory in the /packages/cubism directory

📦 Installation

pnpm add easy-live2d
# or
npm install easy-live2d
# or
yarn add easy-live2d

🛠️ Quick Start

You can also refer to the code in the StackBlitz cloud IDE

Make sure to include Cubism Core in your index.html:
Download it directly from the Live2D Cubism official website: Live2D Cubism SDK for Web

Native HTML

<!doctype html>
<html lang="">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" href="/favicon.ico" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vite App</title>
    <style>
      html,
      body {
        overflow: hidden;
        margin: 0;
      }
    </style>
  </head>

  <body>
    <div id="app"></div>
    <script src="/Core/live2dcubismcore.js"></script>
    <script type="module">
      import { Application, Ticker } from 'pixi.js';
      import { Live2DSprite, Config, Priority, LogLevel } from 'easy-live2d';

      // Configure basic settings
      Config.MotionGroupIdle = 'Idle'; // Set default idle motion group
      Config.MouseFollow = false; // Disable mouse following
      Config.CubismLoggingLevel = LogLevel.LogLevel_Off // Set logging level

      // Create Live2D sprite and initialize
      const live2DSprite = new Live2DSprite();
      live2DSprite.init({
        modelPath: '/Resources/Huusya/Huusya.model3.json',
        ticker: Ticker.shared
      });

      // Listen for click events
      live2DSprite.onLive2D('hit', ({ hitAreaName, x, y }) => {
        console.log('hit', hitAreaName, x, y);
      })

      // You can also initialize directly like this
      // const live2DSprite = new Live2DSprite({
      //   modelPath: '/Resources/Huusya/Huusya.model3.json',
      //   ticker: Ticker.shared
      // })

      // Create application
      const init = async () => {
        // You can also initialize directly like this
        // const model2Json = await (await fetch(path)).json()
        // const modelSetting = new CubismSetting({
        //   prefixPath: '/Resources/Hiyori/',
        //   modelJSON: model2Json,
        // })
        // live2DSprite.init({
        //   modelSetting,
        //   ticker: Ticker.shared,
        // })
        const app = new Application();
        await app.init({
          view: document.getElementById('live2d'),
          backgroundAlpha: 0, // Set alpha to 0 for transparency if needed
        });
        // Live2D sprite size and position settings
        live2DSprite.x = -300
        live2DSprite.y = -300
        live2DSprite.width = canvasRef.value.clientWidth * window.devicePixelRatio
        live2DSprite.height = canvasRef.value.clientHeight * window.devicePixelRatio
        app.stage.addChild(live2dSprite);

        // Set expression
        live2DSprite.setExpression({
          expressionId: 'normal',
        })

        // Play voice
        live2DSprite.playVoice({
          // Current mouth synchronization only supports wav format
          voicePath: '/Resources/Huusya/voice/test.wav',
        })

        // Stop voice
        // live2DSprite.stopVoice()

        setTimeout(() => {
          // Play voice
          live2DSprite.playVoice({
            voicePath: '/Resources/Huusya/voice/test.wav',
            immediate: true // Whether to play immediately: default is true, will stop current playing voice and play new voice immediately
          })
        }, 10000)

        // Set motion
        live2DSprite.startMotion({
          group: 'test',
          no: 0,
          priority: 3,
        })
      }
      init()
    </script>
  </body>
</html>

Vue3 Demo: (Note: make sure to include Cubism Core in your index.html entry file)

<script setup lang="ts">
import { onMounted, onUnmounted, ref } from 'vue'
import { Config, Live2DSprite, LogLevel, Priority } from 'easy-live2d'
import { Application, Ticker } from 'pixi.js'
import { initDevtools } from '@pixi/devtools'

const canvasRef = ref<HTMLCanvasElement>()
const app = new Application()

// Set default Config configuration
Config.MotionGroupIdle = 'Idle' // Set default idle motion group
Config.MouseFollow = false // Disable mouse following
Config.CubismLoggingLevel = LogLevel.LogLevel_Off // Set logging level


// Create Live2D sprite and initialize
const live2DSprite = new Live2DSprite()
live2DSprite.init({
  modelPath: '/Resources/Hiyori/Hiyori.model3.json',
  ticker: Ticker.shared
});

// Listen for click events
live2DSprite.onLive2D('hit', ({ hitAreaName, x, y }) => {
  console.log('hit', hitAreaName, x, y);
})

// You can also initialize directly like this
// const live2DSprite = new Live2DSprite({
//   modelPath: '/Resources/Huusya/Huusya.model3.json',
//   ticker: Ticker.shared
// })

onMounted(async () => {
  // You can also initialize directly like this
  // const model2Json = await (await fetch(path)).json()
  // const modelSetting = new CubismSetting({
  //   prefixPath: '/Resources/Hiyori/',
  //   modelJSON: model2Json,
  // })
  // live2DSprite.init({
  //   modelSetting,
  //   ticker: Ticker.shared,
  // })
  await app.init({
    view: canvasRef.value,
    backgroundAlpha: 0, // Set alpha to 0 for transparency if needed
  })
  if (canvasRef.value) {

    // Live2D sprite size and position settings
    live2DSprite.x = -300
    live2DSprite.y = -300
    live2DSprite.width = canvasRef.value.clientWidth * window.devicePixelRatio
    live2DSprite.height = canvasRef.value.clientHeight * window.devicePixelRatio
    app.stage.addChild(live2DSprite);

    // Set expression
    live2DSprite.setExpression({
      expressionId: 'normal',
    })

    // Play voice
    live2DSprite.playVoice({
      // Current mouth synchronization only supports wav format
      voicePath: '/Resources/Huusya/voice/test.wav',
    })

    // Stop voice
    // live2DSprite.stopVoice()

    setTimeout(() => {
      // Play voice
      live2DSprite.playVoice({
        voicePath: '/Resources/Huusya/voice/test.wav',
        immediate: true // Whether to play immediately: default is true, will stop current playing voice and play new voice immediately
      })
    }, 10000)

    // Set motion
    live2DSprite.startMotion({
      group: 'test',
      no: 0,
      priority: 3,
    })
  }
})

onUnmounted(() => {
  // Release instance
  live2DSprite.destroy()
})

</script>

<template>
  <div class="test">
  </div>
  <canvas
    ref="canvasRef"
    id="live2d"
  />
</template>

<style>
#live2d {
  position: absolute;
  top: 0%;
  right: 0%;
  width: 100%;
  height: 100%;
}

.test {
  display: inline-block;
  position: absolute;
  width: 100%;
  height: 70%;
  background-color: pink;
}
</style>

Voice Lip-Sync

Method 1:

Enable lip-sync by setting MouthMovement in the Live2D model editor.

You can refer to the official documentation for this method.

Method 2:
In the model's xx.model3.json file, find the "Groups" section with "Name": "LipSync", and add: "Ids":"ParamMouthOpenY". See example below:

{
    "Version": 3,
    "FileReferences": {
        "Moc": "xx.moc3",
        "Textures": [
            "xx.2048/texture_00.png"
        ],
        "Physics": "xx.physics3.json",
        "DisplayInfo": "xx.cdi3.json",
        "Motions": {
            "test": [],
            "idle": []
        },
        "Expressions": []
    },
    "Groups": [
        {
            "Target": "Parameter",
            "Name": "EyeBlink",
            "Ids": []
        },
        {
            "Target": "Parameter",
            "Name": "LipSync",
            "Ids": [
                "ParamMouthOpenY"
            ]
        }
    ],
    "HitAreas": []
}