Developers
Embedding the face
Put a talking face on any web page with one iframe. Set it up with URL parameters, and drive it from your page with postMessage.
On this page
The quickest way
Open Try it, set up a face, and go to its Embed tab. Pick a Size (Small 240x280, Medium 360x400 or Large 480x540), a Background (Transparent or Dark), and a Voice if you want a play button that says that voice's line. Copy the code and paste it into your page; Open it shows the frame on its own.
The code
<iframe src="https://wireface.dev/embed/?skin=mei&talk=mei" width="360" height="400" title="Wireface"
allow="autoplay; microphone" style="border: 0"></iframe>The face fills the frame and the frame is transparent, so it sits on your page's own background. If your site's
Content Security Policy doesn't allow style attributes, drop style="border: 0" and set
border: 0 on the iframe in your stylesheet. The frame also needs to be allowed by your policy's
frame-src, if you set one.
A live one
This frame is /embed/?skin=mei&skin_amount=0.6&talk=mei: Mei, 60% of the way from the
wireframe to her skin, so the wireframe's lines show faintly over her whole face. Press the play button to hear her
line.
URL parameters
Everything is set by the query string. A value that isn't valid is left out, and the default used.
| Parameter | Values | What it does |
|---|---|---|
skin | mei, marcus, amara, walter, lucia, arjun, omar, ruth, robot, monster, dracula | The skin to wear: Mei if none is given. For the bare wireframe, add skin_amount=0. |
skin_amount | 0 to 1 (default 1) | Wireframe (0) to skin (1): a cross-fade over the whole face, the wireframe's lines and glow fading as the skin comes in |
preset | cyan, ember, green, amber, violet, rose, ice | A colour preset (colours) |
primary, secondary, iris | a colour as six hex digits, without #: ff4d6d | The wireframe and its glow, the rim light, and the eye colour |
bg | transparent (default), dark, or six hex digits | The frame's background. dark is #060b18. |
talk | mei, marcus, amara, walter, lucia, robot, monster, dracula | Shows a play button that says that voice's line, lip-synced |
captions | 0 | Hides the caption shown while it talks |
teeth_style | normal, braces, vampire, goofy, sharp, turkey | Other teeth than the skin's own |
eyes, follow_mouse | 1 or true; anything else is off | Eyeballs (or hollow eyes), and following the pointer |
| any other face setting | its usual range | glow, wire, fill, scanlines, points, edge_fade, teeth_width, teeth_size, motion, expressiveness, mouth_gain, sync_offset_ms and zoom: see the face settings |
style | hologram, sculpt | For older links: style=hologram means skin_amount=0 (unless skin_amount is given too), and style=sculpt the whole skin |
For example, Dracula on a dark background, mostly wireframe, glowing violet:
https://wireface.dev/embed/?skin=dracula&skin_amount=0.35&preset=violet&glow=1.2&bg=darkControlling it from your page
Send the frame a message with postMessage, naming the command in wireface:
const face = document.querySelector('iframe').contentWindow;
const to = 'https://wireface.dev';
face.postMessage({ wireface: 'say', clip: 'mei' }, to);
face.postMessage({ wireface: 'express', name: 'surprised' }, to);
face.postMessage({ wireface: 'skin', id: 'dracula' }, to);
face.postMessage({ wireface: 'set', config: { preset: 'violet', skin_amount: 0.5 } }, to);| Command | With | What it does |
|---|---|---|
say | clip: a voice id | Says that voice's line, lip-synced, with its expressions |
hush | Stops it talking | |
express | name, seconds (default 4) | Shows an expression: happy, excited, amused, surprised, curious, thinking, concerned, sad, afraid, frustrated, calm, content, bored, glum or neutral, or an everyday word for one (angry, worried...) |
mood | name (or none), intensity (default 0.6) | A standing mood; without a name, none |
state | name | idle, thinking, busy, error, muted or asleep |
skin | id (or null), sweep (default 1.2) | Sweeps on a skin from the catalogue, after sweeping the old one off; null sweeps it off, leaving the bare wireframe |
set | config: any face settings | Changes settings, such as skin_amount, colours or glow |
appear, disappear | Brings the face back, or burns it away |
Events from the face
The frame posts messages to its parent page, with the event's type in wireface:
| Message | When |
|---|---|
{ wireface: 'ready' } | The face is set up and listening for commands |
{ wireface: 'speaking', text } | It starts talking (with the line's text) or stops (text: null) |
{ wireface: 'caption', text } | The sentence it's saying now |
{ wireface: 'error', message, command } | Something failed, such as an unknown skin or voice, or a bad setting |
addEventListener('message', e => {
if (e.origin !== 'https://wireface.dev') return;
if (e.data.wireface === 'ready') console.log('the face is ready');
});Sound
Browsers only allow sound after someone has clicked. The play button counts. Until then, say mimes:
the mouth moves, but there's no sound. Keep allow="autoplay" on the iframe.
What it can't do
- Your own photo. On Try it, your photo stays in your browser, so an embed of it shows the wireframe instead.
- Your own voices, or lip sync to your own audio. The embed says the eight included lines.
For those, or a face without an iframe, use wireface-core in your own page.
Licence
The embed is free on personal and non-commercial sites. For a business, see licence and pricing.