@voqalize/avatar 0.2.2 → 0.4.0

package/client/arjun.ts

@@ -0,0 +1,26 @@
+/** Professional Indian male interviewer, authored to read at call-tile size. */
+
+import { createCanvasAvatar } from './createCanvasAvatar.js';
+import type { CanvasAvatarOptions } from './createCanvasAvatar.js';
+import type { AvatarInstance } from './createAvatar.js';
+
+const RIG_URL = new URL('../src/canvas/data/interviewer-male.rig.json', import.meta.url);
+const IMAGES = {
+  'round-m3-hair-back.webp': new URL('../src/canvas/data/img/round-m3-hair-back.webp', import.meta.url),
+  'round-m3-top-body.webp': new URL('../src/canvas/data/img/round-m3-top-body.webp', import.meta.url),
+  'round-m3-hair-front.webp': new URL('../src/canvas/data/img/round-m3-hair-front.webp', import.meta.url),
+} as const;
+const FACE = () => import('../src/canvas/avatars/round/face.mjs');
+
+export type { CanvasAvatarOptions };
+// Same mixer, same clip library, so the same declaration (`supports.ts`).
+export { supports } from './supports.js';
+
+export function createAvatar(options: CanvasAvatarOptions): AvatarInstance {
+  return createCanvasAvatar(options, {
+    rigUrl: RIG_URL,
+    images: IMAGES,
+    face: FACE,
+    label: 'Arjun — professional male interviewer avatar',
+  });
+}

package/client/createAvatar.ts

@@ -0,0 +1,177 @@
+/**
+ * `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/createCanvasAvatar.ts

@@ -0,0 +1,72 @@
+/** Shared private constructor for the code-authored canvas avatars. */
+
+import type { PipecatClient } from '@pipecat-ai/client-js';
+import { createAvatar as createMixer, STATES } from '../src/avatar.js';
+import type { Gain } from '../src/avatar.js';
+import { createCanvasRig } from '../src/canvas/create-rig.js';
+import { AvatarClient } from './AvatarClient.js';
+import type { AvatarInstance, AvatarOptions } from './createAvatar.js';
+
+export interface CanvasAvatarOptions extends AvatarOptions {
+  /** Viseme amplitude, 0..2. `1` is as authored. */
+  readonly mouthGain?: Gain;
+  /** Gesture-clip amplitude, 0..2. */
+  readonly gestureGain?: Gain;
+  /** Idle/liveness amplitude, 0..2. */
+  readonly motionGain?: Gain;
+}
+
+/** @deprecated Use `CanvasAvatarOptions`; kept for the original entry points. */
+export type InterviewerAvatarOptions = CanvasAvatarOptions;
+
+interface CanvasAvatarConfig {
+  readonly rigUrl: URL;
+  readonly images: Readonly<Record<string, URL>>;
+  readonly face: () => Promise<unknown>;
+  readonly label: string;
+}
+
+const GAINS = ['mouthGain', 'gestureGain', 'motionGain'] as const;
+const PRESENCE_FILTERS: Readonly<Record<string, string>> = {
+  DEGRADED: String(STATES.DEGRADED.filter ?? ''),
+  OFFLINE: String(STATES.OFFLINE.filter ?? ''),
+};
+
+export function createCanvasAvatar(
+  options: CanvasAvatarOptions,
+  config: CanvasAvatarConfig,
+): AvatarInstance {
+  const { mount, client, ...gains } = options;
+  if (!mount) throw new TypeError('createAvatar: `mount` is required');
+  if (!client) throw new TypeError('createAvatar: `client` is required');
+  for (const key of GAINS) {
+    const gain = gains[key];
+    if (gain === undefined) continue;
+    if (!Number.isFinite(gain) || gain < 0 || gain > 2) {
+      throw new RangeError(`createAvatar: \`${key}\` must be 0..2, got ${String(gain)}`);
+    }
+  }
+
+  const canvas = createCanvasRig({
+    url: config.rigUrl,
+    images: config.images,
+    face: config.face,
+    label: config.label,
+  });
+  const widget = createMixer({ mount, rig: canvas.factory, ...gains });
+  const driver = new AvatarClient(widget, {
+    onPresenceChange: (state) => canvas.setPresenceFilter(PRESENCE_FILTERS[state] ?? ''),
+  });
+  const detach = driver.attach(client as PipecatClient);
+
+  let destroyed = false;
+  return {
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      detach();
+      driver.destroy();
+      widget.destroy();
+    },
+  };
+}

package/client/index.ts

@@ -0,0 +1,44 @@
+/**
+ * `@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

@@ -0,0 +1,108 @@
+/**
+ * `@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,
+  shapeFor,
+  normalizeCues,
+  textToCues,
+  ARPABET_TO_VISEME,
+  AZURE_VISEME_TO_LETTER,
+} from "../src/avatar.js";
+
+export type {
+  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/interviewer-female.ts

@@ -0,0 +1,4 @@
+/** @deprecated Renamed to `meera`; kept as an alias so existing imports keep working. */
+
+export { createAvatar } from './meera.js';
+export type { CanvasAvatarOptions, CanvasAvatarOptions as InterviewerAvatarOptions } from './createCanvasAvatar.js';

package/client/interviewer-male.ts

@@ -0,0 +1,4 @@
+/** @deprecated Renamed to `arjun`; kept as an alias so existing imports keep working. */
+
+export { createAvatar } from './arjun.js';
+export type { CanvasAvatarOptions, CanvasAvatarOptions as InterviewerAvatarOptions } from './createCanvasAvatar.js';

package/client/ishita.ts

@@ -0,0 +1,26 @@
+/** Polished professional female avatar, authored to read at call-tile size. */
+
+import { createCanvasAvatar } from './createCanvasAvatar.js';
+import type { CanvasAvatarOptions } from './createCanvasAvatar.js';
+import type { AvatarInstance } from './createAvatar.js';
+
+const RIG_URL = new URL('../src/canvas/data/professional-female-a.rig.json', import.meta.url);
+const IMAGES = {
+  'professional-female-a-top-body.webp': new URL('../src/canvas/data/img/professional-female-a-top-body.webp', import.meta.url),
+  'professional-female-a-hair-back.webp': new URL('../src/canvas/data/img/professional-female-a-hair-back.webp', import.meta.url),
+  'professional-female-a-hair-front.webp': new URL('../src/canvas/data/img/professional-female-a-hair-front.webp', import.meta.url),
+} as const;
+const FACE = () => import('../src/canvas/avatars/round/face.mjs');
+
+export type { CanvasAvatarOptions };
+// Same mixer, same clip library, so the same declaration (`supports.ts`).
+export { supports } from './supports.js';
+
+export function createAvatar(options: CanvasAvatarOptions): AvatarInstance {
+  return createCanvasAvatar(options, {
+    rigUrl: RIG_URL,
+    images: IMAGES,
+    face: FACE,
+    label: 'Ishita — polished professional female avatar',
+  });
+}

package/client/kabir.ts

@@ -0,0 +1,26 @@
+/** Relaxed professional male avatar, authored to read at call-tile size. */
+
+import { createCanvasAvatar } from './createCanvasAvatar.js';
+import type { CanvasAvatarOptions } from './createCanvasAvatar.js';
+import type { AvatarInstance } from './createAvatar.js';
+
+const RIG_URL = new URL('../src/canvas/data/professional-male-b.rig.json', import.meta.url);
+const IMAGES = {
+  'professional-male-b-top-body.webp': new URL('../src/canvas/data/img/professional-male-b-top-body.webp', import.meta.url),
+  'professional-male-b-hair-back.webp': new URL('../src/canvas/data/img/professional-male-b-hair-back.webp', import.meta.url),
+  'professional-male-b-hair-front.webp': new URL('../src/canvas/data/img/professional-male-b-hair-front.webp', import.meta.url),
+} as const;
+const FACE = () => import('../src/canvas/avatars/round/face.mjs');
+
+export type { CanvasAvatarOptions };
+// Same mixer, same clip library, so the same declaration (`supports.ts`).
+export { supports } from './supports.js';
+
+export function createAvatar(options: CanvasAvatarOptions): AvatarInstance {
+  return createCanvasAvatar(options, {
+    rigUrl: RIG_URL,
+    images: IMAGES,
+    face: FACE,
+    label: 'Kabir — relaxed professional male avatar',
+  });
+}

package/client/meera.ts

@@ -0,0 +1,26 @@
+/** Professional Indian female interviewer, authored to read at call-tile size. */
+
+import { createCanvasAvatar } from './createCanvasAvatar.js';
+import type { CanvasAvatarOptions } from './createCanvasAvatar.js';
+import type { AvatarInstance } from './createAvatar.js';
+
+const RIG_URL = new URL('../src/canvas/data/interviewer-female.rig.json', import.meta.url);
+const IMAGES = {
+  'round-w1-hair-back.webp': new URL('../src/canvas/data/img/round-w1-hair-back.webp', import.meta.url),
+  'round-w1-top-body.webp': new URL('../src/canvas/data/img/round-w1-top-body.webp', import.meta.url),
+  'round-w1-hair-front.webp': new URL('../src/canvas/data/img/round-w1-hair-front.webp', import.meta.url),
+} as const;
+const FACE = () => import('../src/canvas/avatars/round/face.mjs');
+
+export type { CanvasAvatarOptions };
+// Same mixer, same clip library, so the same declaration (`supports.ts`).
+export { supports } from './supports.js';
+
+export function createAvatar(options: CanvasAvatarOptions): AvatarInstance {
+  return createCanvasAvatar(options, {
+    rigUrl: RIG_URL,
+    images: IMAGES,
+    face: FACE,
+    label: 'Meera — professional female interviewer avatar',
+  });
+}

package/client/naina.ts

@@ -0,0 +1,26 @@
+/** Relaxed professional female avatar, authored to read at call-tile size. */
+
+import { createCanvasAvatar } from './createCanvasAvatar.js';
+import type { CanvasAvatarOptions } from './createCanvasAvatar.js';
+import type { AvatarInstance } from './createAvatar.js';
+
+const RIG_URL = new URL('../src/canvas/data/professional-female-b.rig.json', import.meta.url);
+const IMAGES = {
+  'professional-female-b-top-body.webp': new URL('../src/canvas/data/img/professional-female-b-top-body.webp', import.meta.url),
+  'professional-female-b-hair-back.webp': new URL('../src/canvas/data/img/professional-female-b-hair-back.webp', import.meta.url),
+  'professional-female-b-hair-front.webp': new URL('../src/canvas/data/img/professional-female-b-hair-front.webp', import.meta.url),
+} as const;
+const FACE = () => import('../src/canvas/avatars/round/face.mjs');
+
+export type { CanvasAvatarOptions };
+// Same mixer, same clip library, so the same declaration (`supports.ts`).
+export { supports } from './supports.js';
+
+export function createAvatar(options: CanvasAvatarOptions): AvatarInstance {
+  return createCanvasAvatar(options, {
+    rigUrl: RIG_URL,
+    images: IMAGES,
+    face: FACE,
+    label: 'Naina — relaxed professional female avatar',
+  });
+}

package/client/playout.ts

@@ -0,0 +1,95 @@
+/**
+ * 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/professional-female-a.ts

@@ -0,0 +1,4 @@
+/** @deprecated Renamed to `ishita`; kept as an alias so existing imports keep working. */
+
+export { createAvatar } from './ishita.js';
+export type { CanvasAvatarOptions } from './createCanvasAvatar.js';

package/client/professional-female-b.ts

@@ -0,0 +1,4 @@
+/** @deprecated Renamed to `naina`; kept as an alias so existing imports keep working. */
+
+export { createAvatar } from './naina.js';
+export type { CanvasAvatarOptions } from './createCanvasAvatar.js';

package/client/professional-male-a.ts

@@ -0,0 +1,4 @@
+/** @deprecated Renamed to `vikram`; kept as an alias so existing imports keep working. */
+
+export { createAvatar } from './vikram.js';
+export type { CanvasAvatarOptions } from './createCanvasAvatar.js';

package/client/professional-male-b.ts

@@ -0,0 +1,4 @@
+/** @deprecated Renamed to `kabir`; kept as an alias so existing imports keep working. */
+
+export { createAvatar } from './kabir.js';
+export type { CanvasAvatarOptions } from './createCanvasAvatar.js';