LivLiv Player 0.3.0

The first version of LivLiv Player on npm. The interface settled first, so a page written for 0.2 needs a few changes. Format 4 is unchanged.

What to change from 0.2

0.2	0.3
import ... from '@livliv/player' and its subpaths	'@livliv-dev/player', the package's name on npm.
player.act('away')	player.setAway(true) and setAway(false). act('away') now throws: it was a switch among one-off moves.
player.puppet	No longer in the types. player.poke() and player.canvasToModel() are what pages used it for. The field still exists and can change in any version.
player.load(a); player.load(b) played a, then b	The new load replaces the one running, which rejects with an AbortError. If you catch errors, let this one through: if (e.name === 'AbortError') return.
dispose() on a load running rejected with an Error	It rejects with an AbortError, as load() on a disposed player does.
Errors told apart by their message	e.code, on a LivLivError. The messages can change.

Install

npm install @livliv-dev/player

The npm package is the player alone, without characters/. The featured characters are in this repository's characters/: copy the ones you use next to your page, with their licence. Kujira, Kujira Q and Pen come from other people's work; their sources, credits and terms are in characters/CREDITS.md.

Face tracking also needs @mediapipe/tasks-vision (1.1.1), and VRM characters need three and @pixiv/three-vrm. All three are optional peer dependencies.

New

• load(source, { signal, onProgress, poster }): call a load off, follow how far it has come, show a picture until the first frame.
• LivLivError, with a code for each reason, from @livliv-dev/player and @livliv-dev/player/body.
• player.contextLost and player.onContextLost: the page hears when the WebGL context is gone. See API.md.
• dispose({ release: true }): gives the WebGL context up, for a canvas leaving the page.
• player.setAway(), player.poke(), player.canvasToModel().
• example/react.html, which loads React from esm.sh.

Changed

• A model that breaks while it is built leaves the character before as it was. It used to leave an empty canvas.
• The pose stays in the ranges of PARAM_RANGES on Player too, as it did on BodyPlayer. A value that is not a number counts as the default.
• maxPixelRatio can be read and changed on a Player.
• snapshot() on a Player draws first, so it is the pose as it is now, on a paused player too.
• A BodyPlayer's Frame.time counts the frames before this one, as a Player's does. Its idle motion runs one frame later.
• Player and BodyPlayer now share their code. Nothing a Player draws changed in our frame-by-frame comparison.

Requirements

WebGL2 and ES2023: Chrome / Edge 97+, Firefox 104+, Safari 15.4+. Tested on current desktop Chromium, Firefox and WebKit; not yet on real phones or in in-app WebViews.

Known

Issue #1 is still open, and a fresh export from Blender hasn't been tested.

License

Code: Apache License 2.0. Featured characters, which are not in the npm package: characters/LICENSE.md and characters/CREDITS.md.

All changes: CHANGELOG.md and v0.2.1...v0.3.0

---

中文：这是第一个发布到 npm 的版本。接口先定了下来，所以为 0.2 写的页面要改几处：act('away')、player.puppet、连续调用 load()、靠错误信息判断错误，改法见上面的表。安装：npm install @livliv-dev/player。npm 包里只有播放器，不含 characters/；精选角色在这个仓库里，把要用的角色连同许可一起复制到你的页面旁边。Kujira、Kujira Q 和 Pen 来自别人的作品，来源和条款见 characters/CREDITS.md。目前在桌面的 Chromium、Firefox、WebKit 上测过，手机还没有测。issue #1 还开着，从 Blender 新导出的文件也没有测过。

日本語：npm で公開する最初のバージョンです。先に API を確定したため、0.2 向けのページは数か所の変更が必要です。act('away')、player.puppet、続けて呼ぶ load()、メッセージによるエラー判定が対象で、変更方法は上の表にあります。インストールは npm install @livliv-dev/player です。npm パッケージに入っているのはプレイヤーだけで、characters/ は含まれません。厳選キャラクターはこのリポジトリにあるので、使うキャラクターをライセンスと一緒にページの横にコピーしてください。Kujira、Kujira Q、Pen は他の方の作品がもとになっており、出典と利用条件は characters/CREDITS.md にあります。テストはデスクトップの Chromium、Firefox、WebKit のみで、スマートフォンではまだ行っていません。issue #1 は未解決で、Blender から新たに書き出したファイルもテストしていません。

LivLiv Player 0.2.1

This release corrects the sources and terms of three featured characters, and makes the player lighter and quicker. Format 4 is unchanged.

Character sources and terms, corrected

The characters/LICENSE.md in 0.2.0 said all 21 featured characters were made by the LivLiv team, and each character's meta.license pointed to that license. That was wrong for Kujira, Kujira Q and Pen, which come from other people's work. From this version:

• Kujira and Kujira Q are under CC BY-NC-SA 4.0, not the LivLiv Featured Characters License. They are based on the community "whale girl" (鲸鱼娘): original character 溟月 by 上善无形, maid design by ZipZipPipe. Credit: "Kujira: 上善无形, ZipZipPipe (CC BY-NC-SA 4.0); model by LivLiv".
• Pen is covered by neither the Apache License nor the LivLiv Featured Characters License. It is based on the fan character known as 咕咕嘎嘎 (Gugu Gaga penguin), made by 贱兔死顺盖 from the Administrator in Arknights: Endfield (Hypergryph), and on a photo of a figure marked "GUGA", maker unknown. LivLiv holds no rights in this character and grants none. If you hold rights in it, CREDITS.md says how to reach us.
• The other 18 keep their terms.

The art and models of the three are unchanged; only the author and license in their meta are different. If you took them from 0.2.0, follow characters/CREDITS.md, which has the sources and credit lines, and not the license in the 0.2.0 tag.

Lighter and quicker

• The core is about 30 KB gzipped, down from about 34. PNGTuber and VRM no longer pull in the renderer.
• Keyforms and a layer's images are fetched together, and keyforms decode 5-7 times faster. On the refined Nana, a load blocks the page less than half as long, and a frame takes about 25 % less time.
• Face tracking has a new option, maxFps, 'auto' by default: it looks for the face less often when that would take over half of the main thread.
• A refused camera stops the face model's download.
• dispose() frees every GPU buffer of a layer at once, and during a load or a start it leaves nothing behind.

VRM

• Fixed: arms and the nod were backwards on 0.x, and the eyes looked the wrong way up and down on every VRM. The head now turns without a neck bone. Framing follows the model's own units and shape, so a model in other units no longer leaves an empty picture.
• A file's own expressions are listed. One-sided blinks work, and so do mouths with only ih and oh.
• load() gives the file's author and terms in model.meta, in the same shape for 1.0 and 0.x. The player does not enforce them.
• A file is looked through before three.js parses it, and a refusal says what to do. One that names an outside URL is refused. A file compressed with Draco, Meshopt or KTX2 says it needs decoders, and configureLoader is where yours go.
• A .vrm opened on the wrong example page says where it belongs, and the examples site brings its own three.js.

Tested on three.js 0.170, 0.186 and 0.187 with three-vrm 3.5.5, in desktop Chromium, on these files:

• VRoid Studio: AvatarSample_A, Vita. UniVRM: AliciaSolid. VRM 1.0: Seed-san, Constraint_Twist.
• A Meebit made with the VRM add-on for Blender. It plays; it has no expressions or eye bones, so only the head and body move.
• The add-on's own 70 test files: 54 load and 16 are refused with an error. Many are tiny test scenes rather than characters, so this shows they load, not that they are framed well.

Not tested: a fresh export from Blender, real decoders through configureLoader, and real phones. Issue #1 is still open.

Changes that may refuse what worked before

• The format check now holds what a model's meshes would cost to a limit before anything is built, and checks every number the rig computes with. Every model we tested still loads; a damaged or hand-edited file that got through before may now be refused with a message.
• On the example pages, ?model= opens files on the same site only.

Also

• Player.isSupported() lets a page ask before it starts.
• A damaged file leaves the character on screen in place.
• Types work with node16 and nodenext.

Examples

• Every character has a cover.webp (512 x 768, about 50 KB). The pages show it at once and fade the character in over it.
• The examples site loads one file per character. A dropped download is tried again, then falls back to the character's folder.
• The camera button says what the camera is for before the browser asks. A refused or missing camera gets a short note and a demo motion.
• The gallery opens on the refined Nana and no longer switches characters by itself.

Requirements

WebGL2 and ES2023: Chrome / Edge 97+, Firefox 104+, Safari 15.4+. Tested on current desktop browsers, not yet on real phones. The notes for 0.2.0 first said "on desktop and mobile", which went further than our testing, and have been corrected.

Install

Not on npm yet: build from this repository (npm install && npm run build) and import dist/index.js.

License

Code: Apache License 2.0. Featured characters: characters/LICENSE.md and characters/CREDITS.md.

All changes: v0.2.0...v0.2.1

---

中文：这一版更正了三个精选角色的来源和条款，也让播放器更轻、更快。0.2.0 的角色许可写的是 21 个角色都由 LivLiv 团队制作，这对 Kujira、Kujira Q 和 Pen 不对，它们来自别人的作品。Kujira 和 Kujira Q 采用 CC BY-NC-SA 4.0；Apache 许可和 LivLiv 精选角色许可都不适用于 Pen，LivLiv 对这个角色不持有任何权利，也不授予任何权利。如果你用的是 0.2.0 里的这三个角色，请以 characters/CREDITS.md 为准。另外：核心约 30 KB（gzip），加载和每帧都更快，修了 VRM 的几处问题，格式检查更严，示例页先显示封面。目前只在桌面浏览器上测过，手机还没有测。还没有上 npm，请从仓库构建。

日本語：このバージョンでは、厳選キャラクター 3 体の出典と利用条件を訂正し、プレイヤーを軽く、速くしました。0.2.0 のキャラクターライセンスには 21 体すべてを LivLiv チームが制作したとありましたが、Kujira、Kujira Q、Pen については誤りで、この 3 体は他の方の作品がもとになっています。Kujira と Kujira Q は CC BY-NC-SA 4.0 です。Pen には Apache License も LivLiv Featured Characters License も適用されず、LivLiv はこのキャラクターについて権利を持たず、許諾もしません。0.2.0 のこの 3 体をお使いの場合は、characters/CREDITS.md に従ってください。そのほか、コアは gzip で約 30 KB になり、読み込みと毎フレームの処理が速くなりました。VRM の不具合をいくつか修正し、フォーマットの検査を厳しくし、サンプルページは最初にカバー画像を表示します。テストはデスクトップのブラウザのみで、スマートフォンではまだ行っていません。npm にはまだ公開していないので、リポジトリからビルドしてください。

LivLiv Player 0.2.0

The first public release of LivLiv Player: a lightweight 2.5D character player for the web, with lip sync and webcam face tracking. It comes with 21 featured characters, ready to use.

What's in it

• Player plays a LivLiv model (a .livliv file, or its folder) on a <canvas> with WebGL2: layered 2D art that turns its head with depth. No dependencies; about 34 KB gzipped for the core, idle motion included.
• Idle motion: breathing, blinking, and following the pointer with the eyes and head. setExpression(), act() (nod, shake, tilt, hop, shy, away), lookAt() and blink() on top.
• Lip sync (@livliv-dev/player/voice): from the microphone, a MediaStream, an <audio> or <video> element, or clips queued with speech.say().
• Face tracking (@livliv-dev/player/tracking): webcam tracking with MediaPipe, in the browser. Camera images stay on the device; API.md has the networking details.
• VRM and PNGTuber characters (@livliv-dev/player/body, /vrm, /png): the same API, lip sync and face tracking included. VRM 0.x and 1.0 need three and @pixiv/three-vrm, both optional.

(Corrected after release: the package name is @livliv-dev/player. These notes first used a name that is not ours on npm.)

• Format 4: .livliv and model.json v4, described in FORMAT.md with a JSON Schema in schema/. Packages exported before v4 still play.
• Untrusted files: sizes, layer counts, paths and ZIP entries are checked before anything reaches the GPU, and the readers are fuzz-tested. Limits are in API.md.
• Examples: example/demo.html (expressions, actions, microphone, camera), gallery.html (all 21 characters), png.html, vrm.html.

Featured characters

21 characters in characters/, each with four expressions (smile, shy, angry, sad). None of them are under the Apache License.

• 18 are LivLiv's own, carefully made with AI: free for personal, non-commercial use with credit ("Characters: LivLiv (livliv.ai)"); no selling or AI training. For commercial use, ask by email (admin@livliv.ai). They carry a small LivLiv mark in the bottom-right corner. Nana is LivLiv's mascot. Full terms: characters/LICENSE.md.
• Kujira, Kujira Q and Pen come from other people's work. That license doesn't cover them, and LivLiv can't grant commercial use for them. Their sources, credits and terms: characters/CREDITS.md.

Install

Not on npm yet: build from this repository (npm install && npm run build) and import dist/index.js.

Requirements

WebGL2 and ES2023: Chrome / Edge 97+, Firefox 104+, Safari 15.4+. Tested on current desktop browsers, not yet on real phones (corrected: this line first said "on desktop and mobile"). The tests need Node 22.18 or newer; CI draws every featured character in headless Chromium.

License

Code: Apache License 2.0. Featured characters: characters/LICENSE.md and characters/CREDITS.md. Neither covers the LivLiv name and logos.

---

中文：LivLiv Player 的第一个公开版本。超轻量的 2.5D 网页角色播放器，支持口型同步和摄像头面捕，VRM 和 PNGTuber 角色用同一套接口；附带 21 个精选角色，每个都有四种表情。其中 18 个是我们精心制作的（AI 参与制作），个人非商业使用免费，请署名；Kujira、Kujira Q、Pen 来自别人的作品，来源和条款见 characters/CREDITS.md。详见 README.zh-CN.md。

日本語：LivLiv Player の最初の公開バージョンです。リップシンクと Web カメラのフェイストラッキングに対応した軽量の Web 向けキャラクタープレイヤーで、VRM と PNGTuber も同じ API で再生できます。厳選キャラクター 21 体つき（表情は各 4 種）。うち 18 体は AI を使って丁寧に作ったもので、個人の非商用利用は無料、クレジット表記が必要です。Kujira、Kujira Q、Pen は他の方の作品がもとで、出典と条件は characters/CREDITS.md にあります。詳しくは README.ja.md へ。