Get the Wireface SDK

What is in the SDK#

The Wireface SDK is the face engine for your own pages and apps, as ES modules with no dependencies. It runs in any browser with WebGL2 and ES modules: Chrome, Edge, Firefox, and Safari 15 and later. It is the same engine Wireface Desktop, Wireface Chat and this site run on. One package, @wireface/sdk, has everything:

• The 3D faceSkins, expressions, teeth, lip sync from clips or live audio, and characters made from a photo on the device.Developer guide
• Wireface 2DAny picture of a face, a photo, a painting, anime or pixel art, that talks.Wireface 2D
• Wireface for three.jsThe face as a mesh or a live texture on characters and objects in your scenes.Wireface for three.js
• Wireface ImagesOne script tag animates the pictures already on a page. Free, with its own public repository.Wireface Images
• The embeddable faceNo code to install: one iframe, set up with URL parameters and driven with postMessage.Embedding

Character creation, expressions, rendering and audio-driven lip sync are free and need no account, key or network. The detection API, for drawn and stylised faces that need AI to find, is optional and free too.

Download it#

It's free to build with. Sign in, or make a free account, and download it from your account. You'll find the runnable examples there too, and a free key for the optional detection API. The licences say what needs a licence.

Download the free SDK

Add it to your project#

Install the archive you downloaded with npm. Its file name carries the version, so use the name of your file:

npm install ./wireface-sdk-<version>.tgz

import { createFace } from '@wireface/sdk';

No bundler? Unpack the archive next to your pages and import its dist/wireface.js directly.

Pages must be served over http(s): browsers don't load ES modules from file://. Using Vite or another bundler? Tell the face where its assets are: see Bundlers and assets.

Run the examples#

Choose Download runnable examples in your account. This separate archive includes the compiled SDK, assets, example pages and a local server. You need Node.js 18 or later and npm. Replace <version> below with the version in the downloaded filename. Run the commands from the folder containing the download:

mkdir wireface-examples
tar -xzf wireface-browser-<version>.tgz -C wireface-examples
cd wireface-examples
npm install
npm start

Open http://localhost:5173/examples/. Start with Create a character on the device, choose a photo, switch between 3D and 2D, then export your character. Portable character playback loads that saved file and can lip-sync to an audio file. These work without an account, key or external network after installation.

The installable npm archive contains the runtime, declarations and guides. Run npm start in the extracted runnable examples folder. Hosted detection needs WIREFACE_SDK_KEY in the server's environment; Gemini Live conversations use a separate GEMINI_API_KEY. Set PORT if 5173 is already in use.

Your first face with Vite#

In a new app folder, install your downloaded SDK archive using its actual path, then install Vite. Use a Node version supported by your Vite release. Copy the SDK's assets with the included command:

npm init -y
npm install ./wireface-sdk-<version>.tgz
npm install --save-dev vite
npx --no-install wireface-assets public/wireface

Create index.html:

<!doctype html>
<html lang="en">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>My first Wireface</title>
<canvas id="face" style="width:320px;height:400px"></canvas>
<script type="module" src="/main.js"></script>
</html>

Create main.js:

import { createFace } from '@wireface/sdk';
const face = createFace(document.querySelector('#face'), { assets: '/wireface/' });
await face.useCharacter('sarah');
face.express('happy');

Create vite.config.mjs, then run npx vite and open the address it prints:

import { defineConfig } from 'vite';
export default defineConfig({
  optimizeDeps: { exclude: ['@wireface/sdk'] },
});

For local photo creation, add the explicit MediaPipe paths from Bundlers and assets. Install three separately to use @wireface/sdk/three. Call face.destroy() when your component is removed.

Where to go next#

• Want to see it first? Play with the face on Try it, the picture version on Try 2D, or the three.js Theatre.
• Read the developer guide for characters, the detection API and offline playback, then the guide for 2D or three.js.
• The JSON schemas for config files and characters are published at /schema/ on this site, and the package includes TypeScript types for every entry point.