LivLiv Player: A Lightweight Web Avatar with Lip Sync and Face Tracking
LivLiv Player brings 2.5D, VRM, and PNGTuber characters to the browser with lip sync and optional webcam tracking—all through a small, dependency-free core.
Adding a responsive character to a website or stream often means choosing between a heavyweight runtime, a platform-specific tool, or a collection of custom animation code. LivLiv Player takes a more compact approach: it renders 2.5D characters in the browser and offers lip sync and webcam-driven face tracking as optional features.
The core uses WebGL2, has no dependencies, and is about 30 KB gzipped. One API can load LivLiv models, VRM avatars, and simple PNGTuber assets, making the project useful for interactive sites, desktop-style web apps, and stream overlays.
Get a character on screen
Install the npm package and attach a Player to a canvas:
npm install @livliv-dev/player
import { Player } from '@livliv-dev/player'
const canvas = document.querySelector('canvas')
const player = new Player(canvas)
await player.load('/characters/k01/')
player.setExpression('smile')
player.act('nod')
player.params.mouthOpen = 0.6 // value from 0 to 1
A LivLiv character can be loaded from a directory containing model.json and its textures/, or from a .livliv package. Expressions and action IDs are available on the player, so an application can expose them as buttons, bind them to conversational state, or trigger them from its own animation logic.
The project repository includes 21 featured characters ready to load. The npm package contains the player, not the character files; copy the characters you intend to use into your own project and follow each asset’s license.
Add speech and webcam tracking when needed
Voice and tracking are separate imports, so applications that do not need them can keep them out of the initial player setup. For speech playback with lip sync:
import { createSpeech } from '@livliv-dev/player/voice'
const speech = createSpeech(player)
button.onclick = () => {
speech.unlock() // call from a user gesture to satisfy browser audio policies
speech.say('/reply.mp3')
}
The player supports lip sync from microphone input, audio, and video. Webcam face tracking uses MediaPipe and is imported separately; it requires @mediapipe/tasks-vision:
import { startFaceTracking } from '@livliv-dev/player/tracking'
await startFaceTracking(player)
That separation is practical for both performance and consent. Camera access is an explicit capability rather than a hidden requirement, and the README says tracking runs in the browser, with camera images staying on the device. The player itself does not call an AI service: it renders the files supplied to it. As with any camera feature, an app should clearly explain why it requests access and provide a way to stop tracking.
One API for 2D-style and 3D avatars
LivLiv Player also supports PNGTuber images and VRM models through a body-player interface. These formats have different rendering needs, but can still fit into a shared application flow:
import { BodyPlayer } from '@livliv-dev/player/body'
import { PngBody } from '@livliv-dev/player/png'
import { VrmBody } from '@livliv-dev/player/vrm'
const png = new BodyPlayer(canvasA, new PngBody())
await png.load({ closed: '/me-closed.png', open: '/me-open.png' })
const vrm = new BodyPlayer(canvasB, new VrmBody())
await vrm.load('/avatars/me.vrm')
VRM support requires three and @pixiv/three-vrm; PNGTuber support uses image assets, typically a closed-mouth and open-mouth picture, with optional closed-eye variants. This lets a product start with a simple image avatar and later offer a more fully rigged model without replacing all of its character-facing code.
Choose between embedding and self-hosting
For a quick demo or OBS overlay, LivLiv provides an iframe endpoint with a transparent background:
<iframe
src="https://livliv.ai/live/k01"
width="480"
height="640"
allow="camera; microphone"
style="border: 0; background: transparent"
></iframe>
For more control, self-host the player and character assets. The examples can be built locally with npm install and npm run build, then served from any static server. The demo accepts a ?model= parameter to select another character, while separate examples demonstrate PNGTuber and VRM loading.
Featured characters include cover.webp posters at 512 × 768, around 50 KB each. Pass a poster with player.load(source, { poster }) to show it while the character’s first frame loads. For an immediate visual before JavaScript runs, place the poster beneath the canvas and fade the character in, as the repository’s loading example does.
Formats, compatibility, and project boundaries
The player supports the LivLiv package format (.livliv and model.json v4); packages exported before v4 are documented separately and remain playable. The format documentation and JSON Schema are included in the repository. The player is not a Live2D runtime: it does not use Live2D software or the Cubism SDK and cannot read .moc3 or .cmo3 files.
Browser requirements are WebGL2 and ES2023. The listed minimums are Chrome and Edge 97+, Firefox 104+, and Safari 15.4+. The project reports testing on current desktop browsers, but not yet on phones, so mobile performance and compatibility should be validated before shipping.
Treat character licensing as part of integration
The code is Apache-2.0, but the featured characters have their own terms and are not covered by that license. Most are available for personal, non-commercial projects with the credit “Characters: LivLiv (livliv.ai)”; the repository’s character license prohibits selling them, commercial use, and AI training. Kujira, Kujira Q, and Pen are based on other people’s work and have separate credits and terms. Keep package metadata such as meta.author and meta.license, and check the applicable license before publishing an avatar.
LivLiv’s character-creation service uses AI, and the project asks users who publicly show characters made with LivLiv to disclose that AI was used rather than presenting the work as hand-drawn or hand-rigged. Those distinctions matter when building a public-facing product, not just when choosing a renderer.
Try it in your own stack
The repository includes TypeScript source, API and format documentation, examples, and tests. A typical local workflow is:
git clone https://github.com/livliv-dev/player
cd player
npm install
npm run check
npm run build
npm test
Unit and fuzz tests run on Node 22.18 or newer without a browser. Browser tests render featured characters in headless Chromium; Firefox and WebKit engine tests are also available, with browser installation and WebGL requirements documented in the README.
LivLiv Player is a good fit when an application needs a lightweight web avatar with optional interaction features and a choice of character formats. Its small core keeps the basic renderer approachable, while separate voice and tracking modules let developers add richer behavior only when the experience calls for it.