mesh-avatar

A WebGL runtime for 2D mesh avatars created with Mesh Avatar Studio. Load a .mavatar archive or an avatar folder into a canvas, then control its motion, voice level and expressions.

For React and Next.js, use mesh-avatar-react.

To move an avatar with your own face and voice without installing anything, open the Player in Chrome or Edge.

To embed an avatar with HTML, use mesh-avatar-element. It provides a <mesh-avatar> custom element and a standalone CDN script.

Install

npm install mesh-avatar

The package is ESM and includes TypeScript declarations. Rendering requires a browser with WebGL. It has no React dependency; the animation loop starts automatically after loading.

Get a .mavatar file

Open your project in Mesh Avatar Studio and choose Export .mavatar in the editor header. The file holds the rig, the built layers, any drawn eye and mouth variants and a manifest, so it is all the runtime needs. You can also pack a project folder from the command line with npm run pack-avatar -- projects/<name> in the Studio repository.

Load an avatar

Place an exported .mavatar file in your app's public assets and provide a canvas:

<canvas id="avatar" width="720" height="960"></canvas>

import { loadMeshAvatar } from 'mesh-avatar';

const canvas = document.querySelector('#avatar');
const avatar = await loadMeshAvatar(canvas, '/avatars/character.mavatar');

To load the unpacked folder instead, serve its rig.json, built/ assets and optional avatar.json under a folder URL:

import { loadMeshAvatar } from 'mesh-avatar';

const canvas = document.querySelector('#avatar');
const avatar = await loadMeshAvatar(canvas, '/avatars/character/');

Use one loading example per canvas. Asset URLs must be reachable by the browser; cross-origin hosting needs the appropriate CORS headers. You can also pass a URL, Blob, ArrayBuffer or Uint8Array to loadMeshAvatar for an archive.

Drive the avatar

// Idle motion and blinking are enabled by default.
avatar.setAutoIdle(true);

// While your app plays voice audio, feed its normalized loudness (0–1).
avatar.setSpeaking(true);
avatar.setVoiceLevel(0.6);

// Set an emotion for the spoken line, or a persistent expression overlay.
avatar.setEmotion('happy', { playMotion: false });
avatar.setExpression('smile');

// Show optional overlay layers (such as glasses) by name; [] hides them all.
avatar.setOverlays(['glasses']);

// Apply tracked or posed parameters. Each call replaces the supplied overrides.
avatar.setParameters({ angleX: 10, gazeX: 0.25 }, 1);

// When the line finishes, return to idle and clear overrides.
avatar.setVoiceLevel(0);
avatar.setSpeaking(false);
avatar.setEmotion(null);
avatar.setExpression('neutral');
avatar.setParameters({});

// When removing the canvas or replacing the avatar:
avatar.destroy();

Emotion tags are happy, sad, angry, surprised, relaxed and neutral (or null to reset). Expressions are neutral, smile, shy, surprise, halfLidded, angry, sad and wink; LIVE_EXPRESSIONS exports that list. PARAMS exports the parameter IDs, ranges and defaults. Overlay names come from the avatar's optional built/overlays/overlays.json; unknown names are ignored. Voice methods animate the avatar; your app handles audio playback.

loadMeshAvatar releases archives it opens on destroy() or load failure; when passed an existing AvatarPackage from openAvatar, the caller owns it and must call release() after its last user is destroyed.

For custom loading or tooling, the package also exports createMeshAvatar, openAvatar, packAvatar, unpackAvatar, validateAvatarFiles, parseManifest, parseRig, validateRig and lighting settings. See the avatar format reference for archive contents, validation and compatibility rules.

Mouth movement

Three optional settings control audio loudness lip sync and kana previews. granularity changes how readily the mouth separates syllables, openness changes the opening amount, and closeSpeed changes how quickly it closes. Each accepts a finite value from 0 to 1; 0.5 preserves the existing behavior.

The Studio's five styles use these values:

| Style | granularity | openness | closeSpeed | | --- | --- | --- | --- | | Relaxed | 0 | 0.5 | 0 | | Standard | 0.5 | 0.5 | 0.5 | | Snappy | 1 | 0.5 | 1 | | Subtle | 0.5 | 0 | 0.5 | | Expressive | 0.5 | 1 | 0.5 |

If your app already supplies a rig and built assets, pass lipSync when creating the avatar:

import { createMeshAvatar, type LipSyncSettings } from 'mesh-avatar';

const lipSync: LipSyncSettings = { granularity: 0, openness: 0.5, closeSpeed: 0 };
const avatar = await createMeshAvatar(canvas, { rig, assets, lipSync });
avatar.setLipSync({ openness: 0.75 }); // Other settings keep their current values.

Avatars saved or exported in Studio carry these settings in avatar.json.lipSync. loadMeshAvatar applies them automatically; explicit options.lipSync fields override the saved values. setLipSync is a partial update and works during playback. The optional preset field records the editor selection only; playback uses the three numbers.

License

The runtime is MIT licensed; see LICENSE. The browser bundle includes fflate, with its MIT notice retained in the bundle.

Avatar artwork has its own license. Miko images and other sample artwork are not included in this npm package, and the runtime license does not grant rights to that artwork.