ALLPERSONAS / DEVELOPERS

Face API

Create a face, update its state, and clean up when your view unmounts.

Preview

Live SDK@allpersonas/core

Ruby

MAKE IT YOURS

CharacterExpressionReady when you are

Use this face in your app

Your selected face — assistant.ts

import { createFace } from '@allpersonas/core';

export function mountAssistant(host: HTMLElement) {
  Object.assign(host.style, { width: '280px', height: '340px' });
  const face = createFace(host, {
    avatar: "ruby",
    expression: "attentive",
  });
  // Update when your agent's state changes.
  // face.update({ thinking: true });
  return () => face.destroy();
}

Create, update, destroy

Example.tsx

import { createFace } from '@allpersonas/core';

export function mountAssistant(host: HTMLElement) {
  host.style.width = '280px';
  host.style.height = '340px';
  const face = createFace(host, {
    avatar: 'ruby',
    expression: 'attentive',
  });

  face.update({ thinking: true });
  // When your agent responds:
  face.update({ thinking: false, expression: 'joyful' });

  // Call the returned function when your view unmounts.
  return () => face.destroy();
}

API	Result	Purpose
`createFace(host, options?)`	FaceController	Mount in an HTMLElement or ShadowRoot; owns its contents.
`face.update(options)`	void	Merge a FaceOptions patch; undefined restores an optional value’s default.
`face.element`	HTMLDivElement	The rendered face element. Set surrounding layout on the host.
`face.destroy()`	void	Remove the face and release animation frames and event listeners.

Character IDs: leo, ruby, finn, iris, theo, noah.

FaceOptions

Option	Type / default	What it does
`avatar`	AvatarId \| Avatar · ruby	Choose one of the six characters.
`expression`	Expression · attentive	Set the current emotional cue.
`thinking`	boolean · false	Use the reflective pose while your agent is working.
`speaking`	boolean · false	Whether speech is actually playing.
`animated`	boolean · true	Enable movement, subject to reduced-motion preferences.
`boundary`	{ readonly current: WordBoundary \| null }	Real word timing, normally from AvatarSpeech.boundary.
`getLevel`	() => number \| null	Read the RMS level of your own playing audio.
`mouthOpen`	number · optional	Manual 0–1 mouth openness. Overrides measured motion.
`label`	string · character + expression	A meaningful accessible name for the image.
`decorative`	boolean · false	Hide the image from assistive technology when text already labels it.
`artworkSrc`	string · bundled artwork	Override the character sheet while retaining its geometry.

Setting speaking alone does not create a talking loop. Supply real word boundaries, measured audio levels, or a mouthOpen value to drive the mouth. Put size, classes, and layout styles on the host.