# Get the Wireface SDK

Everything for putting a talking face in your own app, game or page: what is in the package, where to get it, and which guide to read next.

1. [What is in the SDK](/docs/sdk/#what)
2. [Download it](/docs/sdk/#download)
3. [Add it to your project](/docs/sdk/#project)
4. [Run the examples](/docs/sdk/#examples)
5. [Your first face with Vite](/docs/sdk/#first-face)
6. [Where to go next](/docs/sdk/#next)

## 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 face** Skins, expressions, teeth, lip sync from clips or live audio, and characters made from a photo on the device. Developer guide](/docs/engine/)
- [**Wireface 2D** Any picture of a face, a photo, a painting, anime or pixel art, that talks. Wireface 2D](/docs/2d/)
- [**Wireface for three.js** The face as a mesh or a live texture on characters and objects in your scenes. Wireface for three.js](/docs/three/)
- [**Wireface Images** One script tag animates the pictures already on a page. Free, with its own public repository. Wireface Images](/docs/images/)
- [**The embeddable face** No code to install: one iframe, set up with URL parameters and driven with postMessage. Embedding](/docs/embed/)

Character creation, expressions, rendering and audio-driven lip sync are free and need no account, key or network. The [detection API](/docs/engine/#the-detection-api-optional), 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](/license/) say what needs a licence.

[Download the free SDK](/account/#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](/docs/engine/#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](/docs/engine/#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](/try/), the picture version on [Try 2D](/2d/try/), or the three.js [Theatre](/threejs/).
- Read the [developer guide](/docs/engine/) for characters, the detection API and offline playback, then the guide for [2D](/docs/2d/) or [three.js](/docs/three/).
- 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.

[NextDeveloper guide](/docs/engine/)