@voqalize/avatar 0.4.4 → 0.5.1

package/client/createAvatar.ts

@@ -1,177 +0,0 @@
-/**
- * `createAvatar` — the entire public surface of an avatar.
- *
- *     const avatar = createAvatar({ mount: el, client: pipecatClient });
- *     // …
- *     avatar.destroy();
- *
- * An avatar is an embodiment of a `PipecatClient`. You hand it a mount and a
- * live client; it subscribes and reacts. There is nothing else: no methods to
- * drive it, no callbacks to observe it, no state to read back. Everything it
- * needs to know is already on the wire — Pipecat's factual lifecycle events
- * plus the avatar server-message envelope (docs/contract-wire.md).
- *
- * ## This is also the extension point
- *
- * There is no registry, no loader and no plug-in system. **You add an avatar by
- * publishing a module that exports `createAvatar` with this signature**, and
- * importing yours instead of ours:
- *
- *     import { createAvatar } from "@acme/our-mascot";
- *
- * That is the whole mechanism, and it is deliberate. A registry would make us
- * own resolution, versioning and asset paths for code we have never seen; a
- * renderer interface would make us commit to a second public contract before we
- * know what the second renderer actually needs. An ES module export we get for
- * free from the platform.
- *
- * Everything past `mount` and `client` belongs to the implementation. Ours takes
- * `SvgAvatarOptions`; yours takes whatever it likes, and `AvatarFactory<O>` is
- * generic so the caller still gets your options checked.
- *
- * ## What an implementation owes the caller
- *
- * Only that `destroy()` leaves the mount as it found it and unsubscribes from
- * the client. Not returning to rest, not honouring every action, not even
- * having a mouth — a handless, mouthless avatar that only changes colour is a
- * conforming avatar. The obligations that *matter* are perceptual, not typed,
- * and they live in docs/contract-behavior.md.
- */
-
-import type { PipecatClient } from "@pipecat-ai/client-js";
-import { createAvatar as createSvgWidget } from "../src/avatar.js";
-import type { Face, FaceTheme, Gain, HandSide } from "../src/avatar.js";
-import type { BehaviorStateId } from "../src/behavior.js";
-import { peep } from "../src/face-peep.js";
-import { AvatarClient } from "./AvatarClient.js";
-
-export type { Face, FaceTheme, Gain, HandSide };
-
-/**
- * What every `createAvatar` takes. Implementations extend it with their own
- * options; the two named here are the only ones the caller can count on.
- */
-export interface AvatarOptions {
-  /** The element to render into. The implementation owns its contents. */
-  readonly mount: HTMLElement;
-  /**
-   * A live `PipecatClient`. Required, and not nullable: an avatar with nothing
-   * to embody has no reason to exist yet. React callers get the forgiving
-   * version — `<Avatar>` waits for a non-null client before mounting.
-   */
-  readonly client: PipecatClient;
-}
-
-/** What every `createAvatar` returns. */
-export interface AvatarInstance {
-  /** Unsubscribe from the client and remove everything from the mount. */
-  destroy(): void;
-}
-
-/**
- * The shape a third-party avatar module exports, parameterised by its own
- * options so a caller passing them gets them checked. `AvatarFactory` bare is
- * the common denominator — the two options everyone shares.
- */
-export type AvatarFactory<O extends AvatarOptions = AvatarOptions> =
-  (options: O) => AvatarInstance;
-
-/**
- * What a mounted avatar answers to — the one *optional* export beside
- * `createAvatar`.
- *
- * A page that drives an avatar has a problem an ordinary consumer does not.
- * The wire's action id is open and an unknown one is ignored in silence
- * (docs/contract-wire.md § Action), which is right for a protocol and useless
- * for a control surface: a button per name cannot tell "this face has no such
- * motion" from "nothing happened". This is the avatar answering that question
- * for a driving UI, and nothing else reads it — `createAvatar` does not take
- * it, the library never consults it, and an avatar that omits it is fully
- * conforming. It is a *declaration*: nobody verifies it, so a list that has
- * drifted from the drawing is a bug in the avatar and not something the
- * library can catch.
- */
-export interface AvatarSupport {
-  /**
-   * Every action id this avatar answers to, the two required ones included.
-   * An id absent from here is a documented no-op, never an error.
-   */
-  readonly actions: readonly string[];
-  /**
-   * Which of the nine states this avatar draws *distinguishably*.
-   *
-   * Every avatar must accept all nine; a renderer that draws `CANT_HEAR` as
-   * ordinary listening is conforming (docs/contract-behavior.md). So this is
-   * the narrower claim — which of them a reviewer can expect to tell apart on
-   * the face — and omitting it claims all nine, which is what every avatar in
-   * this repo does.
-   */
-  readonly states?: readonly BehaviorStateId[];
-}
-
-/** The bundled avatars' own `supports` value is in `supports.ts`, not here: it
- *  is a value, so this module's `peep` import would follow it into the bundle of
- *  anything that read it — including the canvas avatars, which draw no SVG face. */
-
-/**
- * Options for the bundled SVG avatars — ours alone; nothing outside this
- * package reads them.
- *
- * `face` is a value, not a name: a name needs a table, and a table needs every
- * face imported to answer any lookup. Import the one you want and the other two
- * never enter your bundle.
- *
- *     import { createAvatar } from "@voqalize/avatar";
- *     import { wren } from "@voqalize/avatar/faces/wren";
- *
- *     createAvatar({ mount, client, face: wren });
- */
-export interface SvgAvatarOptions extends AvatarOptions {
-  /** Defaults to `peep`, the face this entry point already carries. */
-  readonly face?: Face;
-  /** Palette for that face. Its keys are the face's own; see `THEME` in its
-   * module, and CLAUDE.md on why `peep` has exactly one. */
-  readonly theme?: FaceTheme;
-  /** Viseme amplitude, 0..2. `1` is as authored. */
-  readonly mouthGain?: Gain;
-  /** Gesture-clip amplitude, 0..2. */
-  readonly gestureGain?: Gain;
-  /** Idle/liveness amplitude, 0..2. Low by design — see CLAUDE.md. */
-  readonly motionGain?: Gain;
-  /** Render the frame-edge hand at all. Default true. */
-  readonly hand?: boolean;
-  /** `1` puts it on the viewer's right, `-1` the other side. */
-  readonly handSide?: HandSide;
-}
-
-const GAINS = ["mouthGain", "gestureGain", "motionGain"] as const;
-
-export function createAvatar(options: SvgAvatarOptions): AvatarInstance {
-  const { mount, client, face = peep, ...rest } = options;
-  if (!mount) throw new TypeError("createAvatar: `mount` is required");
-  if (!client) throw new TypeError("createAvatar: `client` is required");
-  // The one range TypeScript cannot state, checked where it is cheapest to fix:
-  // at construction, by the caller who typed the number.
-  for (const key of GAINS) {
-    const g = rest[key];
-    if (g === undefined) continue;
-    if (!Number.isFinite(g) || g < 0 || g > 2) {
-      throw new RangeError(`createAvatar: \`${key}\` must be 0..2, got ${String(g)}`);
-    }
-  }
-
-  const widget = createSvgWidget({ mount, face, ...rest });
-  const driver = new AvatarClient(widget);
-  const detach = driver.attach(client);
-
-  let destroyed = false;
-  return {
-    destroy() {
-      if (destroyed) return;
-      destroyed = true;
-      detach();
-      driver.destroy();
-      widget.destroy();
-    },
-  };
-}

package/client/index.ts

@@ -1,44 +0,0 @@
-/**
- * `@voqalize/avatar` — a talking head that embodies a `PipecatClient`.
- *
- *     import { createAvatar } from "@voqalize/avatar";
- *
- *     const avatar = createAvatar({ mount: el, client: pipecatClient });
- *
- * That is the whole public surface. Put an `AvatarProcessor` in the pipecat
- * pipeline (`pip install voqalize-avatar`), mount this in the bot's tile, and
- * the face listens, thinks, claims the floor and lipsyncs what the TTS says.
- *
- * Entry points, and the split is the design rather than packaging taste:
- *
- * - `@voqalize/avatar` — this one. Framework-free. `@pipecat-ai/client-js` is
- *   a type-only import, so even that peer is genuinely optional at runtime.
- *   It carries exactly one drawing: `peep`, the default face.
- * - `@voqalize/avatar/faces/{peep,wren,myna}` — one drawing each. Import the
- *   one you want and pass it as `face`; the others never enter your bundle.
- * - `@voqalize/avatar/react` — `<Avatar>`. Pulls React; nothing here does.
- * - `@voqalize/avatar/internal` — the SVG widget, the behavior catalog and the
- *   viseme clock. **No semver promise**: these move in any minor. They are
- *   exported because an avatar author building on our renderer needs them, not
- *   because they are an interface.
- *
- * To ship your own avatar, publish a module exporting `createAvatar` and import
- * that instead — see `createAvatar.ts` and docs/design-avatar-interface.md. A
- * module may also export `supports`, which is how a page that *drives* an
- * avatar learns which action ids this one answers to; every consumer that only
- * mounts a face can ignore it.
- */
-
-export { createAvatar } from "./createAvatar.js";
-export { supports } from "./supports.js";
-export type {
-  AvatarOptions,
-  AvatarInstance,
-  AvatarFactory,
-  AvatarSupport,
-  SvgAvatarOptions,
-  Face,
-  FaceTheme,
-  Gain,
-  HandSide,
-} from "./createAvatar.js";

package/client/internal.ts

@@ -1,132 +0,0 @@
-/**
- * `@voqalize/avatar/internal` — the parts of our own implementation that
- * another avatar can build on.
- *
- * **Nothing here is covered by semver.** Names, signatures and semantics move
- * in any minor release. It is exported because an avatar author who wants the
- * SVG mixer, the behavior catalog or — most usefully — the viseme clock should
- * not have to vendor a copy, not because any of it is an interface. The
- * interface is `createAvatar`, and it is one function.
- *
- * The one thing here worth reaching for on purpose is `VisemeTrack`: someone
- * has to turn a cue array plus a clock into "which mouth shape is on screen
- * right now", every renderer needs exactly that, and it is a solved problem.
- *
- *     const track = new VisemeTrack();
- *     track.start(cues, () => performance.now() - t0);
- *     // per frame:
- *     const s = track.sample();   // { letter: "D", intensity: 1, phone: "OW" } | null
- *
- * `docs/internal-rig.md` describes the pose-channel model the bundled SVG
- * renderer uses internally. It is *not* the seam to implement — see
- * docs/design-avatar-interface.md.
- */
-
-export {
-  // The bundled SVG widget. Not the faces: importing one from here would put
-  // all three in every bundle that wanted the viseme clock.
-  // `@voqalize/avatar/faces/<name>` is where a face comes from.
-  createAvatar as createSvgAvatar,
-  // The pose space a custom `rig` is handed on every frame, and the rests it is
-  // measured against.
-  REST,
-  CHANNELS,
-  RANGE,
-  STATES,
-  STATE_NAMES,
-  ACTIONS,
-  ACTION_IDS,
-  GAZE_NAMES,
-  GAZE_TARGETS,
-  EMOTION_NAMES,
-  // The viseme clock and its tables.
-  VisemeTrack,
-  VISEME_LETTERS,
-  VISEME_SHAPES,
-  SILENT,
-  LEAD_MS,
-  // The body's share of a held tilt, for a page driving a rig by hand.
-  SHOULDER_TILT,
-  // Stepping a gesture by hand: the catalogue, the player, and the smoothing
-  // law the mixer puts between a clip's keyframes and the face. A filmstrip
-  // instrument needs all three, and the one thing it must not do is fork the
-  // smoothing — that is the part a keyframe is authored against
-  // (docs/internal-mixer.md § Smoothing).
-  INTERNAL_CLIPS,
-  ClipPlayer,
-  TAU,
-  clamp,
-  approach,
-  // Posing a face directly, with no mixer, no clock and no client above it —
-  // what a pose sheet or a rig-conformance page does. `makeParams` fills the
-  // rests around a handful of overrides, `emotionPose` names a familiar set of
-  // them, `avatarFrame` wraps the result and `createSvgRig(face)` draws it.
-  makeParams,
-  emotionPose,
-  avatarFrame,
-  createSvgRig,
-  shapeFor,
-  // The one number that says how far the mandible falls for a given aperture.
-  // Anything composing a mouth pose without `shapeFor` — a retarget, a driver —
-  // needs it, and the amplitudes behind the lips are calibrated at it.
-  JAW_OF_OPEN,
-  normalizeCues,
-  textToCues,
-  ARPABET_TO_VISEME,
-  AZURE_VISEME_TO_LETTER,
-} from "../src/avatar.js";
-
-export type {
-  Clip,
-  ClipSample,
-  AvatarApi,
-  AvatarStateName,
-  AvatarActionId,
-  AvatarGazeName,
-  AvatarEmotionName,
-  AvatarAction,
-  AvatarMeta,
-  VisemeLetter,
-  Cue,
-  PoseChannel,
-  PoseOverrides,
-  CreateAvatarOptions as CreateSvgAvatarOptions,
-} from "../src/avatar.js";
-
-// The rig contract, for a renderer that implements `apply(frame)` directly
-// instead of wearing the SVG adapter. `docs/internal-rig.md` — and note that
-// this is the mixer's private seam, not the avatar interface.
-export type {
-  AvatarFrame,
-  AvatarRig,
-  AvatarRigFactory,
-  HandFrame,
-  RigPose,
-} from "../src/rig.js";
-
-export {
-  BEHAVIOR_STATE_IDS,
-  BEHAVIOR_ACTIONS,
-  BEHAVIOR_ACTION_IDS,
-  WIRE_ACTION_TO_BEHAVIOR,
-} from "../src/behavior.js";
-
-export type { BehaviorStateId, BehaviorActionId } from "../src/behavior.js";
-
-export { isAvatarMessage, CORE_ACTION_IDS } from "./types.js";
-// The optional driving-UI declaration, as a type only. The bundled avatar's own
-// `supports` value lives on the public entry point and importing it here would
-// drag `peep`'s drawing in behind it — the same reason the faces are not
-// exported from this module. Compose yours from `CORE_ACTION_IDS` and
-// `ACTION_IDS` above, which cost nothing.
-export type { AvatarSupport } from "./createAvatar.js";
-// A renderer may reuse the one lifecycle/precedence ladder without gaining a
-// second public avatar interface.
-export { AvatarClient } from "./AvatarClient.js";
-export type {
-  AvatarCommand,
-  AvatarCue,
-  AvatarCuesCmd,
-  CoreActionId,
-} from "./types.js";
-export type { AvatarClientOptions, AvatarDriver, AvatarPresenceState } from "./AvatarClient.js";

package/client/playout.ts

@@ -1,95 +0,0 @@
-/**
- * When the bot's audio actually begins, heard on the track the browser plays.
- *
- * `BotStartedSpeaking` and the audio reach the browser by different roads —
- * the event on the data channel, the sound over RTP and through a jitter
- * buffer — so the event is a statement about *which* audio is starting and
- * not about when anyone hears it. Measured on two stacks, the event arrived
- * 57 ms after the first sample on one and 160 ms before it on the other: the
- * mouth lagged the voice on the first and ran ahead of it on the second, and
- * no constant corrects both. So the turn clock is anchored to the sound.
- *
- * What makes "the sound began" observable is that between turns the decoded
- * track is exact digital zero — Opus decodes silence to silence — so onset is
- * the first sample off zero, not a speech detector's guess at a threshold. That
- * matters: cue `t: 0` is the first sample the TTS produced, lead-in included,
- * and a detector keyed to *speech* would anchor 20-50 ms into the lead-in.
- *
- * What this probe hears is the sound entering the page's audio graph, not
- * leaving the speaker. For a wired speaker the difference is about what the
- * compositor and display add to the picture, and the two cancel. A Bluetooth
- * headset adds 150-250 ms that nothing on the picture side matches, so the
- * probe also reports the device latency the browser admits to, and the
- * client delays the mouth by the excess (`AvatarClient.ts`).
- */
-
-export interface PlayoutProbe {
-  /**
-   * Where the bot's current sound began, on the caller's `now()` clock.
-   * `null`: the track is silent right now. `undefined`: this probe cannot say —
-   * the track has been sounding for longer than it can look back, or the
-   * audio graph is not running.
-   */
-  onset(): number | null | undefined;
-  /** The output device's latency as this context reports it, in ms; 0 when it
-   * will not say. The probe shares the device the call's audio plays on. */
-  outputLatencyMs?(): number;
-  /** Ask a suspended graph to run. A browser that needs a gesture for it
-   * ignores the request outside one, so this is safe to call at any time. */
-  resume?(): void;
-  dispose(): void;
-}
-
-/** 8192 samples is 170 ms at 48 kHz: past the 57 ms the sound has been seen to
- * lead the event by, with room for a slower network. */
-const WINDOW = 8192;
-/** -80 dBFS. The gaps between turns are exact zero; this only keeps a
- * denormal from reading as speech. */
-const FLOOR = 1e-4;
-
-export function createPlayoutProbe(track: MediaStreamTrack, now: () => number): PlayoutProbe | null {
-  const Ctx = globalThis.AudioContext;
-  if (!Ctx) return null;
-  let ctx: AudioContext;
-  let source: MediaStreamAudioSourceNode;
-  let analyser: AnalyserNode;
-  try {
-    ctx = new Ctx();
-    source = ctx.createMediaStreamSource(new MediaStream([track]));
-    analyser = ctx.createAnalyser();
-    analyser.fftSize = WINDOW;
-    source.connect(analyser);
-  } catch {
-    return null;
-  }
-  // A context made after the user's connect click is allowed to run; one that
-  // is not simply answers `undefined`, and the event anchors the turn.
-  ctx.resume().catch(() => {});
-  const buf = new Float32Array(WINDOW);
-
-  return {
-    onset() {
-      if (ctx.state !== "running") return undefined;
-      analyser.getFloatTimeDomainData(buf);
-      const t = now();
-      let first = -1;
-      for (let i = 0; i < buf.length; i++) {
-        if (Math.abs(buf[i]!) > FLOOR) { first = i; break; }
-      }
-      if (first < 0) return null;
-      if (first === 0) return undefined;
-      return t - ((buf.length - first) / ctx.sampleRate) * 1000;
-    },
-    outputLatencyMs() {
-      const s = ctx.outputLatency;
-      return typeof s === "number" && Number.isFinite(s) ? s * 1000 : 0;
-    },
-    resume() {
-      if (ctx.state === "suspended") ctx.resume().catch(() => {});
-    },
-    dispose() {
-      source.disconnect();
-      ctx.close().catch(() => {});
-    },
-  };
-}

package/client/react.ts

@@ -1,13 +0,0 @@
-/**
- * `@voqalize/avatar/react` — the avatar as one component.
- *
- *     import { Avatar } from "@voqalize/avatar/react";
- *
- *     <Avatar client={session.client} className="avatar-tile" />
- *
- * Separate from the main entry so that `createAvatar` costs nothing to a
- * caller who is not on React — React is an optional peer, and a barrel that
- * re-exported this would make it a hard one.
- */
-
-export { Avatar, type AvatarProps } from "./Avatar.js";

package/client/supports.ts

@@ -1,27 +0,0 @@
-/**
- * `supports` for every avatar this package ships.
- *
- * It is one constant and one file because they are one renderer: every avatar
- * mounts the same mixer with the same clip library, so a second list would be
- * the same list with a second chance to be wrong. It is not in
- * `createAvatar.ts`, where the type is documented, because a value is imported
- * for real — reading it from there would pull `peep`'s drawing into every
- * consumer's bundle.
- *
- * The two required ids first, then this renderer's own catalogue. `ACTION_IDS`
- * already carries `RESPONSE_INTERRUPTED` as this renderer's shape for it, so
- * the join dedupes rather than concatenating, and `ACKNOWLEDGE` is the one name
- * here with no clip behind it because `action()` resolves it on the floor
- * (docs/internal-mixer.md § Actions).
- */
-
-import { ACTION_IDS } from "../src/avatar.js";
-import type { AvatarSupport } from "./createAvatar.js";
-import { CORE_ACTION_IDS } from "./types.js";
-
-export const supports: AvatarSupport = Object.freeze({
-  actions: Object.freeze([
-    ...CORE_ACTION_IDS,
-    ...ACTION_IDS.filter((id) => !(CORE_ACTION_IDS as readonly string[]).includes(id)),
-  ]),
-});

package/client/three/assets.ts

@@ -1,26 +0,0 @@
-/**
- * Every compiled character as one table — for a page that enumerates them.
- *
- * Each URL lives in its own module (`tara-asset.ts` and its siblings) and this
- * file only gathers them, because a bundler emits assets per module: anything
- * importing *this* ships every GLB, which is right for a rig instrument that
- * switches between characters and wrong for a consumer who mounted one.
- * So the character modules never import this — they import their own — and the
- * only reader is `/internal/three`, a separate entry point that ships nothing.
- */
-import { TANYA_GLB } from "./tanya-asset.js";
-import { TANVI_GLB } from "./tanvi-asset.js";
-import { TESS_GLB } from "./tess-asset.js";
-import { TARA_GLB } from "./tara-asset.js";
-import { TUSHAR_GLB } from "./tushar-asset.js";
-
-export const ASSETS = Object.freeze({
-  tara: TARA_GLB,
-  tushar: TUSHAR_GLB,
-  tanya: TANYA_GLB,
-  tess: TESS_GLB,
-  tanvi: TANVI_GLB,
-});
-
-/** Every compiled character, in build order. */
-export type CharacterName = keyof typeof ASSETS;

package/client/three/budgets.ts

@@ -1,27 +0,0 @@
-/** Measurable limits for one 3-D avatar at its shipping surface. */
-export const SHIPPING_SURFACE = Object.freeze({
-  cssWidth: 400,
-  cssHeight: 300,
-  maxDevicePixelRatio: 2,
-});
-
-/** Keep the physical drawing buffer inside the shipping ceiling at any mount size. */
-export function pixelRatioFor(width: number, height: number, devicePixelRatio: number): number {
-  const maxWidth = SHIPPING_SURFACE.cssWidth * SHIPPING_SURFACE.maxDevicePixelRatio;
-  const maxHeight = SHIPPING_SURFACE.cssHeight * SHIPPING_SURFACE.maxDevicePixelRatio;
-  return Math.max(0.1, Math.min(
-    SHIPPING_SURFACE.maxDevicePixelRatio,
-    devicePixelRatio,
-    maxWidth / Math.max(1, width),
-    maxHeight / Math.max(1, height),
-  ));
-}
-
-/** Crossing one of these is a failed asset/runtime review, not a suggestion. */
-export const HARD_BUDGET = Object.freeze({
-  assetBytes: 6 * 1024 * 1024,
-  triangles: 60_000,
-  drawCalls: 30,
-  bones: 40,
-  morphTargets: 45,
-});