# player (livliv-dev/player)

> A lightweight 2.5D character player for the web. It puts an animated character on a page, a stream overlay or an app, with lip sync and webcam face tracking.

- GitHub: https://github.com/livliv-dev/player
- GitHub.Locker page: https://github.locker/livliv-dev/player
- Stars: 1.6K
- Language: TypeScript
- License: Apache-2.0
- Last push: 2026-11-16

## Questions and answers

Written by GitHub.Locker from the README and the repository; check the README below for details.

**Is it a library I add to my site, or a finished app?**

It is a library: an npm package with the player alone, which you call from your own page. A ready /live/ page also exists for embedding without code.

**How do I get it running?**

Clone the repo, run 'npm install && npm run build', serve the folder with any static server, and open /example/demo.html to try expressions, actions, microphone and camera.

**Do I need anything special?**

Only a browser with WebGL2 and ES2023 (Chrome/Edge 97+, Firefox 104+, Safari 15.4+). The core has no dependencies and is about 30 KB gzipped; MediaPipe for face tracking loads only when you need it.

**Any catches?**

It has been tested on current desktop browsers only, not yet on phones. Also, the featured characters have their own licence, separate from Apache 2.0, so they cannot be sold or used commercially.

**Does it send my camera or voice anywhere?**

No. The player calls no AI service and reads only the files you point it at. Face tracking runs Google's MediaPipe in the browser, and camera images stay on the device.

**What is the difference between LivLiv, VRM and PNGTuber characters?**

All three play through the same API. A PNGTuber needs two pictures (mouth closed and open), a VRM comes from VRoid Studio or any tool exporting VRM 0.x or 1.0, and a LivLiv model is made from one picture on livliv.ai.

**Does it support full-body characters?**

Yes. Full-body characters are drawn head to feet and stand on the ground, swaying and crouching with their feet in place. You pick the shot with view.fit; four featured characters (f05 to f08) are full-body.

**Why did the authors open-source it?**

They want the art of creating characters to belong to everyone, so they released their AI character-creation tools, the player and its playback protocol, and a stage where characters can meet an audience.

**Was AI used to make the characters?**

Yes. The featured characters and characters made on livliv.ai were made with AI, so the README asks you to say so and not present them as hand-drawn or hand-rigged.


---

## README (checked against GitHub 2026-11-18)

Source: https://github.com/livliv-dev/player/blob/main/README.md

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="media/livliv-player-wordmark-white.svg">
    <img alt="LivLiv Player" src="media/livliv-player-wordmark-2000.png" width="360">
  </picture>
</p>

<p align="center">
  A lightweight 2.5D character player for the web, with lip sync and webcam face tracking. A few lines of code put a character in a page, a stream overlay or an app.<br>
  Comes with 25 featured characters in different styles, ready to use.
</p>

<p align="center"><b>English</b> · <a href="README.zh-CN.md">中文</a> · <a href="README.ja.md">日本語</a> · <a href="README.vi.md">Tiếng Việt</a></p>

<p align="center"><img src="media/demo.gif" alt="Featured characters breathing, blinking, turning their heads and talking" width="720"></p>

- WebGL2, no dependencies, about 30 KB gzipped for the core
- Lip sync (microphone, audio, video) and webcam face tracking (MediaPipe), both in the browser, imported only when you need them
- Plays LivLiv, VRM and PNGTuber characters through the same API
- Full-body characters stand on the ground: they sway, crouch and dip with their feet in place, in the shot you pick
- 25 featured characters in [`characters/`](characters/), ready to use

## Try it

- **Online**: the examples run on [livliv-dev.github.io/player](https://livliv-dev.github.io/player/).
- **Here**: `npm install && npm run build`, serve this folder with any static server and open `/example/demo.html`
  (expressions, actions, microphone, camera; `?model=../characters/<id>/` picks another character).
  `/example/png.html` and `/example/vrm.html` show a PNGTuber and a VRM.
- **On livliv.ai**: each character's page there plays it with the same renderer. Start at
  [livliv.ai/discover](https://livliv.ai/discover).

## Project LivLiv

We want the art of creating characters to belong to everyone.

We're open-sourcing our AI tools for character creation, [the player and its playback protocol](https://github.com/livliv-dev/player),
and [a stage where your characters can meet an audience](https://github.com/livliv-dev/stage).

Come say hello on [Discord](https://discord.gg/ac5qF36T2H) and follow us on [X (Twitter)](https://x.com/livliv_ai).

## Use it in your page

```sh
npm install @livliv-dev/player
```

```js
import { Player } from '@livliv-dev/player'

const player = new Player(document.querySelector('canvas'))
await player.load('characters/k01/')   // a folder with model.json and textures/, or a .livliv file

player.setExpression('smile')          // ids are in player.expressions
player.act('nod')
player.params.mouthOpen = 0.6          // 0..1
```

Lip sync and face tracking:

```js
import { createSpeech } from '@livliv-dev/player/voice'
import { startFaceTracking } from '@livliv-dev/player/tracking'   // needs @mediapipe/tasks-vision

const speech = createSpeech(player)
button.onclick = () => { speech.unlock(); speech.say('/reply.mp3') }

await startFaceTracking(player)
```

A VRM or a PNGTuber, on the same API:

```js
import { BodyPlayer } from '@livliv-dev/player/body'
import { VrmBody } from '@livliv-dev/player/vrm'    // needs three and @pixiv/three-vrm
import { PngBody } from '@livliv-dev/player/png'

const vrm = new BodyPlayer(canvasA, new VrmBody())
await vrm.load('/avatars/me.vrm')
const png = new BodyPlayer(canvasB, new PngBody())
await png.load({ closed: 'me-closed.png', open: 'me-open.png' })
```

The whole API is in [API.md](API.md): options, params, expressions and actions, drivers, recorded poses and attachment
points, VRM and PNGTuber characters, the limits on untrusted files, the model package and the format version. The LivLiv package format (`.livliv`,
`model.json` v4) is in [FORMAT.md](FORMAT.md), with a JSON Schema in [`schema/`](schema/); packages exported before v4
are described in [FORMAT-v3.md](FORMAT-v3.md) and still play.

> The npm package is the player alone. The featured characters are in this repository's [`characters/`](characters/): copy
> the ones you use next to your page, with their licence.

## Featured characters

`characters/` holds 25 characters, ready to `load()`. Most were made by LivLiv: use them free with credit
("Characters: LivLiv (livliv.ai)"), commercially too if you are an individual. Don't sell them or merchandise made from
them, and don't train AI models on them. They are **not** covered by the Apache License; the terms are in
[characters/LICENSE.md](characters/LICENSE.md). Kujira, Kujira Q and Pen come from other people's work, with their own
terms in [characters/CREDITS.md](characters/CREDITS.md).

**New in 0.5.0: full-body characters.** Drawn head to feet, they stand on the ground: they sway, crouch and dip while
their feet stay put. Four featured characters are full-body: Tsubaki, Neve, Juno and Viola (f05–f08). Pick the shot
with `player.view.fit`: `'frame'` (default), `'knee'` or `'whole'`; see
[Full-body characters](API.md#full-body-characters) in API.md.

Each character has a `cover.webp`, its first frame: `player.load(source, { poster })` shows it until the character is
ready, and [example/loading.js](example/loading.js) shows it before any script has run.

Each character is also one file to download, `<id>.livliv`, at `https://livliv-dev.github.io/player/characters/<id>.livliv`
(the names below link to them). They are served with CORS, so a page on another site can `load()` one straight from
there, and [`index.json`](https://livliv-dev.github.io/player/characters/index.json) lists them all.

| id | name | id | name | id | name |
|---|---|---|---|---|---|
| `k01` | [Sena](https://livliv-dev.github.io/player/characters/k01.livliv) | `d01` | [Yui](https://livliv-dev.github.io/player/characters/d01.livliv) | `v01` | [Aster](https://livliv-dev.github.io/player/characters/v01.livliv) |
| `k02` | [Elio](https://livliv-dev.github.io/player/characters/k02.livliv) | `d02` | [Leo](https://livliv-dev.github.io/player/characters/d02.livliv) | `v03` | [Mira](https://livliv-dev.github.io/player/characters/v03.livliv) |
| `char06` | [Aoi](https://livliv-dev.github.io/player/characters/char06.livliv) | `d03` | [Nana](https://livliv-dev.github.io/player/characters/d03.livliv) | `v04` | [Kai](https://livliv-dev.github.io/player/characters/v04.livliv) |
| `char07` | [Sora](https://livliv-dev.github.io/player/characters/char07.livliv) | `d03ft` | [Nana (refined)](https://livliv-dev.github.io/player/characters/d03ft.livliv) | `v05` | [Lilith](https://livliv-dev.github.io/player/characters/v05.livliv) |
| `s01` | [Hana](https://livliv-dev.github.io/player/characters/s01.livliv) | `p01` | [Kujira](https://livliv-dev.github.io/player/characters/p01.livliv) | `v06` | [Usa](https://livliv-dev.github.io/player/characters/v06.livliv) |
| `q02` | [Mochi](https://livliv-dev.github.io/player/characters/q02.livliv) | `p02` | [Kujira Q](https://livliv-dev.github.io/player/characters/p02.livliv) | `v07` | [Stella](https://livliv-dev.github.io/player/characters/v07.livliv) |
| `q03` | [Kotaro](https://livliv-dev.github.io/player/characters/q03.livliv) | `p03` | [Pen](https://livliv-dev.github.io/player/characters/p03.livliv) | `w01` | [Max](https://livliv-dev.github.io/player/characters/w01.livliv) |
| `f05` | [Tsubaki (full-body)](https://livliv-dev.github.io/player/characters/f05.livliv) | `f06` | [Neve (full-body)](https://livliv-dev.github.io/player/characters/f06.livliv) | `f07` | [Juno (full-body)](https://livliv-dev.github.io/player/characters/f07.livliv) |
| `f08` | [Viola (full-body)](https://livliv-dev.github.io/player/characters/f08.livliv) | | | | |

## Characters of your own

You can bring in a PNGTuber's pictures, or a VRM (drawn with three.js); or make a character of your own from one
picture on [livliv.ai](https://livliv.ai).

- **A PNGTuber**: two pictures (mouth closed, mouth open), and two more with the eyes closed if you have them.
- **A VRM**: from VRoid Studio or any tool that exports VRM 0.x or 1.0.
- **A LivLiv model**: make one from a picture on [livliv.ai](https://livliv.ai), then download its model package from
  the character's page (**Model package**): a `.livliv` file. Pass it to `load()` as it is (a URL, or the `File`
  someone picked), or unzipped as a folder. Full-body characters play too (from 0.5); livliv.ai does not offer their
  packages yet.

## About the player and the characters

LivLiv Player and the `.livliv` format are LivLiv's own work. They use no Live2D software or Cubism SDK and do not
read `.moc3` or `.cmo3` files. "Live2D" is a trademark of Live2D Inc.; LivLiv is not affiliated with it.

Making a character on livliv.ai uses AI. The player itself only plays: it calls no AI service and reads only the files
you point it at. Face tracking runs Google's MediaPipe in the browser, and camera images stay on the device; API.md has
the networking details.

The featured characters in this repository were made on LivLiv too, also with AI; Kujira, Kujira Q and Pen adapt other
people's characters ([credits](characters/CREDITS.md)). Refined Nana (`d03ft`) also has
swinging parts and head-turn keyforms added with LivLiv's own tools.

A package's `meta.author` and `meta.license` record who made it and on what terms: keep them and follow them. When you
show a character made with LivLiv in public, say that AI was used to make it, and don't present it as hand-drawn or
hand-rigged.

## Embed without code

```html
<iframe src="https://livliv.ai/live/k01" width="480" height="640" allow="camera; microphone"
  style="border:0;background:transparent"></iframe>
```

The same `/live/<id>` page has a transparent background and works as an OBS Browser Source.\
(Powered by [https://livliv.ai](https://livliv.ai))

## Develop

```sh
git clone https://github.com/livliv-dev/player
cd player
npm install
npm run check          # types
npm run build          # dist/: index.js, tracking.js, voice.js, body.js, png.js, vrm.js (ES modules), chunks/ and types/
npm test               # unit and fuzz tests (Node 22.18 or newer, no browser)
npm run test:browser   # every featured character drawn in headless Chromium; once: npx playwright-core install chromium-headless-shell
npm run test:engines   # a sample on Firefox and WebKit, where WebGL2 starts (a GPU or a software GL); once: npx playwright-core install firefox webkit
```

`src/runtime/` is the renderer and motion code livliv.ai runs; this repository is published from it. See
[CONTRIBUTING.md](CONTRIBUTING.md). Security reports: [SECURITY.md](SECURITY.md).

## Browser support

WebGL2 and ES2023: Chrome / Edge 97+, Firefox 104+, Safari 15.4+. Tested on current desktop browsers, not yet on phones.

## License

The code is under the [Apache License 2.0](LICENSE) (see also [NOTICE](NOTICE)). The featured characters have their
own licence, [characters/LICENSE.md](characters/LICENSE.md). You may keep the LivLiv name and logo in your own versions, as long as they don't claim to be the official one.

## Thanks

Thanks to 上善无形, ZipZipPipe and 贱兔死顺盖, whose characters Kujira, Kujira Q and Pen are based on: see [characters/CREDITS.md](characters/CREDITS.md).

