# SDK du visage

:::warning{title="Préversion"}

Le SDK est en préversion (0.x) : son interface peut encore évoluer. Pour la fenêtre de conversation complète (visage, voix, micro, suggestions), voir [Fenêtre de conversation](/fenetre).

:::

Le SDK affiche le visage d'un avatar dans votre page et anime sa bouche sur la voix : **sa voix Twimi** (formules Avatar Widget et Avatar Agent), ou **la vôtre** (formule Avatar SDK : votre voicebot, votre synthèse vocale, un enregistrement). Il s'occupe de la conversation, du jeton et des fichiers du visage.

**[Voir la démonstration](https://api-dev.atwimi.com/v1/sdk/demo/)**, avec Maude et Antoine.

## Installer

```html
<script src="https://api-dev.atwimi.com/v1/sdk/twimi.js"></script>
```

- `/v1/sdk/twimi.js` : la dernière version 0.x ;
- `/v1/sdk/0.5.0/twimi.js` : une version figée, qui ne change jamais (conseillé en production).

Tout vient de Twimi, y compris le moteur du modèle de bouche (ONNX Runtime) : aucun CDN tiers à autoriser.

## Afficher et faire parler

```html
<div id="zone"></div>
<button id="parler">Parler</button>
<script>
  const tw = await Twimi.init({ key: "pk_test_…", avatar: "maude" });
  const face = tw.face({ container: "#zone", size: 320 });

  document.getElementById("parler").onclick = () => face.say("Bonjour ! Je suis Maude.");
</script>
```

- `Twimi.init` vérifie la clé et la page en lisant la fiche de l'avatar. Utilisez la **clé publique** (`pk_…`), depuis une page déclarée pour votre déploiement : le SDK refuse une clé secrète.
- `tw.face()` affiche le visage tout de suite ; l'événement `ready` arrive quand la bouche est prête (quelques secondes au premier chargement).
- La conversation s'ouvre au premier `say()` ou `play()` (voir [Voix et décompte](/voix-et-decompte)), et son jeton est renouvelé tout seul.

## Sa voix ou la vôtre

| | Méthode | Formules |
| --- | --- | --- |
| La voix de l'avatar | `face.say(texte)` : découpé en phrases, la suivante se prépare pendant que la précédente est dite. Accepte aussi un flux de texte (un bot qui répond en streaming). | Avatar Widget, Avatar Agent |
| Votre voix | `face.play(son)` : `ArrayBuffer`, `Blob`, `AudioBuffer` ou adresse d'un fichier. Le son est analysé en entier avant d'être joué : envoyez une longue réponse **phrase par phrase**. | Avatar SDK (et les autres) |

`say()` et `play()` se résolvent à la fin de la parole.

## Contrôler

| | |
| --- | --- |
| `face.stop()` | arrête tout de suite ; ce qui restait à dire est abandonné, `end` est émis |
| `face.mute(true)` | coupe le son ; la bouche continue de bouger |
| `face.unlock()` | débloque le son (à appeler dans un clic) |
| `face.destroy()` | libère le visage et termine la conversation |
| `face.state` | `loading`, `idle`, `speaking` ou `error` |

## Événements

```js
face.on("ready", () => {});                         // la bouche est prête
face.on("start", ({ duration }) => {});            // une phrase commence
face.on("end", () => {});                           // elle est finie (ou arrêtée)
face.on("status", ({ state }) => {});
face.on("error", ({ code, message, reason }) => {});
```

Une erreur dans votre gestionnaire n'arrête jamais le SDK.

## Le son bloqué par le navigateur

Les navigateurs interdisent de jouer un son avant un geste du visiteur. Si `say()` ou `play()` part sans clic, le SDK émet `error` avec le code `audio_locked`, puis le son part au premier clic ou à la première touche. Pour l'éviter, déclenchez la parole depuis un clic, ou appelez `face.unlock()` dans un gestionnaire de clic.

## Erreurs

Les promesses sont rejetées avec une `Twimi.TwimiError` : `code` (celui de l'API, voir [Erreurs et limites](/erreurs), ou `audio_locked`, `audio_unreadable`, `destroyed`, `network`), `message`, `status`, `requestId` et, pour `voice_limit_reached`, `reason`.

## Sans écrire d'initialisation

```html
<twimi-face key="pk_test_…" avatar="maude" size="320"></twimi-face>
<script>
  document.querySelector("twimi-face").say("Bonjour !");
</script>
```

Le style de la balise est isolé : celui de votre site ne casse pas le visage, et inversement. Ses événements sont `twimi-ready`, `twimi-start`, `twimi-end`, `twimi-error` et `twimi-status` (contenu dans `event.detail`).

## Limites de la préversion

- Un déploiement correspond à un avatar : une autre clé pour un autre avatar.
- Pas de flux audio continu (voicebot en temps réel) : envoyez le son phrase par phrase.
- Le visage s'affiche en carré ; sa taille se règle avec `size` (en pixels).