# bbot

> A circle, and two circles inside it that follow the pointer. An animated face
> for web UIs — 30 expressions, 9 one-shot reactions, spring-driven. The head is
> a sphere, so the eyes travel a curved path and foreshorten toward the rim.
> 3.7 kB gzipped, no dependencies, MIT.

From npm:

    npm i @bwnd/bbot

    import { createFace } from '@bwnd/bbot'        // no React needed
    import { Face } from '@bwnd/bbot/react'        // optional peer dep

Or with no install and no build step at all:

    import { createFace } from 'https://bbot.bwnd.app/face.js'
    createFace(document.querySelector('#bot'), { expression: 'curious' })

Either way styles inject themselves — there is no stylesheet to link. The host
element needs an explicit width and height, or nothing renders.

It lip-syncs: `face.talk(level)` takes 0-1 speech energy once a frame, opens the
mouth over the current mood and bobs the head. Needs `mouth: true`. You rarely
measure that energy yourself — `@bwnd/bbot/talk` exports `listen(source, face)`,
which drives it from an `<audio>`, a `MediaStream` or an `AudioNode`, and
`analyseVoice(buffer).at(time)` for rendering, which syncs to a frame's timestamp
rather than to playback. Both report the sound's colour as well as its loudness —
`talk(level, {wide, round})` picks a vowel shape, where level alone only opens
the jaw.

It also has a finish: `@bwnd/bbot/fx` exports `applyFx(svg, opts)` with ten
0-1 knobs — `gloss`, `rim`, `chrome`, `glass`, `bloom`, `halation`, `holo`,
`scan`, `scratch`, `hue` — composable, and built lazily so an unused one is
free. Both are separate entry points and cost nothing unless imported.

## Render API — a face without running anything

If you want a picture of a face rather than a live one, ask for it. No key, no
signup:

    curl -X POST https://bbot.bwnd.app/api/render \
      -H 'content-type: application/json' \
      -d '{"expression":"joy","ink":"#b6ff3d","format":"jpg"}'

Returns JSON: a `url` to a 1080×1080 file, and `snippet` — the embed code for
that same face, live. `format` is one of:

- `jpg` — a still card, captioned bbot.bwnd.app. Good for an avatar or a post.
- `mp4` — a 1–6 second clip (`seconds`), H.264. Uploads straight to TikTok,
  Instagram or X. By default the face pops in, sweeps its gaze, blinks, winks and
  bounces; pass a `script` to choreograph it instead — a list of cues like
  `{"at": 1.2, "expression": "surprised", "react": "pop"}`, each with `at` plus
  any of `expression`, `react` and `look`. Moods cross-fade, so space them ~0.5s.
  Pass `say` and the clip is narrated, lip-synced to the audio itself: the voice
  sets the length (so `seconds` is ignored) and a mouth is forced on. Narration
  is capped hard — `say` is max 200 characters (~30 words) and a narrated clip
  is max 10 seconds, because the speech is billed per character and recording
  runs in real time. Longer is rejected, not truncated silently; ask for several
  short clips instead. Two clips render at once, a third gets a 429. `voice`
  takes an ElevenLabs voice name or id; `GET /api/render/voices` lists them.
  Narration needs a key configured on the host — without one those calls say so
  and everything else still works.
- `snippet` — the embed code only. Nothing is rendered, so it returns instantly.

Colours are `#rrggbb`: `skin` is the head *and* the backdrop behind it, `ink` the
eyes and mouth, `ring` the hairline. `mouth` and `pupils` are booleans. An
unknown expression is rejected with the list of valid ones, so you can retry.

It is the real library that answers — the endpoint drives it in a headless
browser, so what you get back is what a person gets from the playground.

One gotcha: the edge in front of this domain 403s the `Python-urllib` default
User-Agent, on these docs as well as the API. Send any other agent string (or use
requests) and it is fine. Retrying will not help.

## MCP

Inside bwnd, the same actions are MCP tools on this incubator's own server
(`incu-sbx:8000/mcp` on the mesh — not exposed publicly; use the HTTP API above
from outside): `list_face_moods`, `list_face_voices`, `render_face`,
`record_face`, `face_embed_code`. To make a talking clip: `list_face_voices` to
pick who it sounds like, `list_face_moods` for what it can do, then
`record_face(say=..., voice=..., script=[...])`.

## Docs

- [SKILL.md](https://bbot.bwnd.app/SKILL.md): full agent-facing usage — API, options, expressions, reactions, theming, and the mistakes worth avoiding
- [expressions.json](https://bbot.bwnd.app/expressions.json): machine-readable manifest — every expression and reaction with its parameters, generated from source on each build
- [Library bundle](https://bbot.bwnd.app/face.js): ESM, styles injected at runtime
- [Stylesheet](https://bbot.bwnd.app/face.css): only needed if importing the raw source instead of the bundle

## Source

- [GitHub](https://github.com/bwndapp/bbot): source, README, runnable demo
- [CDN mirror](https://cdn.jsdelivr.net/gh/bwndapp/bbot@main/dist/face.js): jsDelivr, pinnable by tag