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": []
}