@voqalize/avatar 0.0.1

package/src/clips.js

@@ -0,0 +1,144 @@
+/**
+ * Gesture clip player.
+ *
+ * A clip is a short, multi-channel keyframed timeline. Clip channels are
+ * *additive deltas*, not absolute poses — a nod adds pitch to whatever the head
+ * is already doing, which is what makes "nod while speaking" work without any
+ * special-casing.
+ *
+ * Two behaviours matter more here than the curves themselves:
+ *   · clips are interruptible (barge-in must kill an in-flight nod), and
+ *   · the queue collapses duplicates — three stacked nods reads as a fault.
+ */
+
+import { clamp } from './params.js';
+import { VisemeTrack } from './visemes.js';
+
+const smoothstep = (t) => t * t * (3 - 2 * t);
+
+function sampleTrack(keys, u) {
+  if (!keys.length) return 0;
+  if (u <= keys[0][0]) return keys[0][1];
+  const last = keys[keys.length - 1];
+  if (u >= last[0]) return last[1];
+  for (let i = 1; i < keys.length; i++) {
+    if (u <= keys[i][0]) {
+      const [t0, v0] = keys[i - 1];
+      const [t1, v1] = keys[i];
+      const k = t1 === t0 ? 1 : smoothstep((u - t0) / (t1 - t0));
+      return v0 + (v1 - v0) * k;
+    }
+  }
+  return last[1];
+}
+
+const RAMP_IN = 70;
+const RAMP_OUT = 150;
+
+export class ClipPlayer {
+  /**
+   * @param {object} hooks
+   * @param {(name:string|null)=>void} hooks.onGaze  clip-scoped gaze override
+   * @param {()=>void}                 hooks.onBlink
+   */
+  constructor(hooks = {}) {
+    this.hooks = hooks;
+    this.clip = null;
+    this.t = 0;
+    this.fading = false;
+    this.fadeT = 0;
+    this.mouth = new VisemeTrack();
+    this._blinksDone = 0;
+    this.onEnd = null;
+  }
+
+  get playing() { return !!this.clip; }
+  get id() { return this.clip ? this.clip.id : null; }
+
+  /**
+   * @param {object} clip
+   * @param {HTMLAudioElement} [audio] if given, the clip's mouth track is
+   *        scheduled against the audio clock instead of the local timer
+   */
+  play(clip, audio) {
+    if (!clip) return;
+    // Collapse a repeat of the clip already running.
+    if (this.clip && this.clip.id === clip.id && !this.fading) return;
+
+    this.clip = clip;
+    this.t = 0;
+    this.fading = false;
+    this.fadeT = 0;
+    this._blinksDone = 0;
+    this.audio = audio || null;
+
+    if (clip.mouthCues && clip.mouthCues.length) {
+      const clock = audio
+        ? () => audio.currentTime * 1000
+        : () => this.t;
+      this.mouth.tailMs = 60;
+      this.mouth.start(clip.mouthCues, clock);
+    } else {
+      this.mouth.stop();
+    }
+    if (clip.gaze && this.hooks.onGaze) this.hooks.onGaze(clip.gaze);
+    if (audio) { audio.currentTime = 0; audio.play().catch(() => {}); }
+  }
+
+  /** Barge-in. Fades rather than cutting, so the head doesn't snap. */
+  stop(immediate = false) {
+    if (!this.clip) return;
+    if (immediate) return this._end();
+    this.fading = true;
+    this.fadeT = 0;
+  }
+
+  _end() {
+    const had = this.clip;
+    this.clip = null;
+    this.fading = false;
+    this.mouth.stop();
+    if (this.audio) { this.audio.pause(); this.audio = null; }
+    if (had && had.gaze && this.hooks.onGaze) this.hooks.onGaze(null);
+    if (this.onEnd) this.onEnd(had);
+  }
+
+  /**
+   * @returns {{delta: object, weight: number, mouth: object|null, ownsMouth: boolean}}
+   */
+  update(dtMs) {
+    if (!this.clip) return { delta: null, weight: 0, mouth: null, ownsMouth: false };
+    this.t += dtMs;
+    const c = this.clip;
+    const u = clamp(this.t / c.duration);
+
+    let w = Math.min(1, this.t / RAMP_IN) * Math.min(1, (c.duration - this.t) / RAMP_OUT);
+    if (this.fading) {
+      this.fadeT += dtMs;
+      w *= Math.max(0, 1 - this.fadeT / 110);
+      if (this.fadeT >= 110) { this._end(); return { delta: null, weight: 0, mouth: null, ownsMouth: false }; }
+    }
+    w = clamp(w);
+
+    if (c.blinkAt && this.hooks.onBlink) {
+      while (this._blinksDone < c.blinkAt.length && u >= c.blinkAt[this._blinksDone]) {
+        this._blinksDone++;
+        this.hooks.onBlink();
+      }
+    }
+
+    const delta = {};
+    for (const ch in c.keys) delta[ch] = sampleTrack(c.keys[ch], u) * w;
+
+    let mouth = null;
+    const ownsMouth = !!(c.mouthCues && c.mouthCues.length);
+    if (ownsMouth) mouth = this.mouth.sample();
+
+    if (this.t >= c.duration && !this.fading) {
+      // Let the mouth track finish its tail before tearing down.
+      if (!ownsMouth || !this.mouth.playing) this._end();
+    }
+
+    return { delta, weight: w, mouth, ownsMouth };
+  }
+}

package/src/emotions.js

@@ -0,0 +1,55 @@
+/**
+ * Affect is a separate axis from state.
+ *
+ * If emotion were folded into the state enum you'd need SPEAKING_WARM,
+ * SPEAKING_CONCERNED, LISTENING_WARM ... and the table would be unmaintainable
+ * within a week. Instead: `setState('LISTENING', { emotion: 'curious' })`. The
+ * emotion contributes a base pose that every other layer builds on top of.
+ */
+
+export const EMOTIONS = {
+  neutral: {
+    mouthCornerL: 0.10, mouthCornerR: 0.10,
+  },
+  warm: {
+    mouthCornerL: 0.48, mouthCornerR: 0.48,
+    // A real smile squints. Without this it reads as a mask.
+    squintL: 0.30, squintR: 0.30, lidL: 0.04, lidR: 0.04,
+    browRaiseL: 0.10, browRaiseR: 0.10,
+  },
+  curious: {
+    browRaiseL: 0.34, browRaiseR: 0.12,
+    browAngleL: 0.10,
+    headRoll: 0.07,
+    mouthCornerL: 0.18, mouthCornerR: 0.14,
+    lidL: -0.10, lidR: -0.10,
+  },
+  concerned: {
+    browInnerL: 0.55, browInnerR: 0.55,
+    browRaiseL: -0.08, browRaiseR: -0.08,
+    mouthCornerL: -0.22, mouthCornerR: -0.22,
+    lidL: 0.06, lidR: 0.06,
+  },
+  encouraging: {
+    mouthCornerL: 0.58, mouthCornerR: 0.58,
+    browRaiseL: 0.26, browRaiseR: 0.26,
+    squintL: 0.22, squintR: 0.22,
+    headPitch: 0.05,
+  },
+  thoughtful: {
+    browRaiseL: -0.14, browRaiseR: -0.06,
+    browInnerL: 0.18, browInnerR: 0.10,
+    mouthPress: 0.45, mouthCornerL: -0.05, mouthCornerR: 0.02,
+    lidL: 0.10, lidR: 0.10,
+  },
+};
+
+export const EMOTION_NAMES = Object.keys(EMOTIONS);
+
+/** Blend an emotion toward neutral by `intensity`. */
+export function emotionPose(name, intensity = 1) {
+  const src = EMOTIONS[name] || EMOTIONS.neutral;
+  const out = {};
+  for (const k in src) out[k] = src[k] * intensity;
+  return out;
+}

package/src/face-core.js

@@ -0,0 +1,154 @@
+// ---------------------------------------------------------------------------
+// face-core — the part of a face module that is not the face.
+//
+// Three avatars were built independently before this module existed, and their
+// renderers converged on the same shape: an element table, a memoized attribute
+// writer, and an apply() that runs torso lean → shoulders → parallax → eyes →
+// brows → mouth → teeth → tongue. The geometry differs per character; the
+// plumbing and the pose mechanics do not. This module absorbs the proven-
+// identical parts, so a face module supplies art and feature geometry and gets
+// the body mechanics for free.
+//
+// What lives here is exactly what those faces shared line-for-line, or differed
+// in only by a named scalar. Anything a character has an opinion about — what
+// an eye is, how a mouth is drawn — stays in the face module. Two of the three
+// have since been retired; what they proved about the seam is why this file
+// looks the way it does, and helpers only they used went with them.
+// ---------------------------------------------------------------------------
+
+import { clamp } from './params.js';
+
+/** Attribute-value number formatter: 2 decimal places, no trailing zeros. */
+export const f = (n) => (Math.round(n * 100) / 100).toString();
+
+// Constants every rig agreed on. Named here so a new avatar inherits the
+// agreement instead of re-deriving it.
+export const LEAN_SCALE = 0.055; // scale gain at torsoLean = 1
+export const ROLL_TORSO = 1.5;   // degrees of roll the torso follows…
+export const ROLL_HEAD = 5.5;    // …versus what the head itself takes.
+
+/**
+ * Mount the static markup and return the per-instance tools: the svg root, an
+ * id-scoped selector for building the element table, and the memoized `set`.
+ * SVG attribute setting is the hot path; `set` skips redundant DOM writes.
+ */
+export function createFaceShell(mount, id, markupHtml) {
+  mount.innerHTML = markupHtml;
+  const svg = mount.querySelector(`#${id}`);
+  const $ = (n) => svg.querySelector(`#${id}-${n}`);
+  const prev = new Map();
+  const set = (node, attr, val) => {
+    const k = node.id + attr;
+    if (prev.get(k) === val) return;
+    prev.set(k, val);
+    node.setAttribute(attr, val);
+  };
+  return { svg, $, set };
+}
+
+/** The one return shape every face honours: { svg, apply, theme, destroy }. */
+export function faceApi(mount, svg, apply, theme) {
+  return { svg, apply, theme, destroy: () => { mount.innerHTML = ''; } };
+}
+
+/**
+ * Blocks A–C of every apply(): torso lean, shoulders, and the layer parallax
+ * loop. `spec` is a module-level constant in the face module:
+ *
+ *   leanTravel   px of downward travel at torsoLean = 1
+ *   leanPivot    {x, y} the scale pivot — behind the head, not the frame base:
+ *                scaling about the bottom makes the head rise as it grows,
+ *                which reads as standing up instead of leaning in
+ *   shrugLift    px of shoulder lift at shrug = 1
+ *   shrugTiltDeg degrees of one-sided-shrug rotation at tilt = 1 — a per-rig
+ *                judgement about how much the collar can cover, not taste
+ *   shrugPivot   {x, y} the sternum
+ *   yawPx        px of head travel at headYaw = 1
+ *   pitchPx      px at headPitch = 1
+ *   pivot        {x, y} roll pivot — the base of the neck, not the chin:
+ *                rotating about the chin swings the whole cranium sideways
+ *                and reads as a puppet on a stick
+ *   breathSwell  fractional scale of the torso layers at breath = 1, about
+ *                `swellPivot`. Required. It replaced a rigid vertical bob of
+ *                the whole shirt, which moved the hem — and the hem is the one
+ *                part of a seated torso that does not move, so the result read
+ *                as the figure being nudged up and down rather than as breath.
+ *                A scale about the hem raises the shoulder line and widens the
+ *                chest, which is what an inbreath does and is the only breath
+ *                cue a head-and-shoulders crop can actually show.
+ *   swellPivot   {x, y} the hem — bottom of the frame, on the midline
+ *   turnPx       px of lateral trunk travel at torsoTurn = 1 (0 if the rig
+ *                does not declare it)
+ *   layers       draw-order list of layer names in the element table
+ *   parallax     {layer: multiplier} — follows the art, not a standard
+ *   torsoLayers  the subset of `layers` that moves at torso speed
+ *   units        the rig's linear scale factor relative to the numbers above
+ *                (1 where travels are already in the rig's own units). Kept as
+ *                a separate factor, applied last, so a rig built by scaling
+ *                another's numbers states that lineage — and so evaluation
+ *                order matches code that wrote `travel * 9 * S` longhand.
+ *                Degrees never take it: degrees are degrees at any scale.
+ *
+ * In a webcam frame a lean is read almost entirely as a change of scale, so
+ * that is how it is drawn.
+ */
+export function poseTransforms(p, set, el, spec) {
+  const u = spec.units;
+  const lean = p.torsoLean;
+  const leanT = lean
+    ? `translate(0 ${f(lean * spec.leanTravel * u)}) `
+      + `translate(${f(spec.leanPivot.x)} ${f(spec.leanPivot.y)}) `
+      + `scale(${f(1 + lean * LEAN_SCALE)}) `
+      + `translate(${f(-spec.leanPivot.x)} ${f(-spec.leanPivot.y)}) `
+    : '';
+
+  // One shoulder cannot rise without the other when the shirt is a single
+  // path. A small rotation about the sternum is what a one-sided shrug looks
+  // like anyway, and it needs no new geometry.
+  const shrug = (p.shoulderL + p.shoulderR) * 0.5;
+  const tilt = (p.shoulderR - p.shoulderL) * 0.5;
+
+  // Breath as chest expansion. The swell scales the torso layers about the
+  // hem, so the shoulder line rises and the chest widens while the bottom of
+  // the shirt stays put. The head then has to ride whatever the shoulders did
+  // or the neck telescopes — and that lift is not a tuned constant, it is
+  // arithmetic: the swell's vertical displacement at the neck pivot. One
+  // number to author, and the two layers cannot drift out of agreement.
+  const swell = spec.breathSwell ? p.breath * spec.breathSwell : 0;
+  const neckLift = swell ? swell * (spec.swellPivot.y - spec.pivot.y) : 0;
+  const swellT = swell
+    ? `translate(${f(spec.swellPivot.x)} ${f(spec.swellPivot.y)}) `
+      + `scale(${f(1 + swell)}) `
+      + `translate(${f(-spec.swellPivot.x)} ${f(-spec.swellPivot.y)}) `
+    : '';
+
+  const torsoT = `translate(${f(p.torsoTurn * (spec.turnPx || 0) * u)} ${f(-shrug * spec.shrugLift * u)}) `
+    + `rotate(${f(-tilt * spec.shrugTiltDeg)} ${f(spec.shrugPivot.x)} ${f(spec.shrugPivot.y)}) `
+    + swellT;
+
+  const yx = p.headYaw * spec.yawPx;
+  const py = p.headPitch * spec.pitchPx;
+  for (const key of spec.layers) {
+    const k = spec.parallax[key];
+    const torso = spec.torsoLayers.includes(key);
+    const roll = torso ? p.headRoll * ROLL_TORSO : p.headRoll * ROLL_HEAD;
+    // Torso layers get their breath from the swell inside torsoT; head layers
+    // get the matching lift, which is derived from the swell rather than tuned
+    // separately — the neck rides on the chest it sits on.
+    const bob = torso ? 0 : -neckLift;
+    set(el[key], 'transform',
+      leanT + (torso ? torsoT : '')
+      + `translate(${f(yx * k)} ${f(py * k + bob)}) rotate(${f(roll)} ${f(spec.pivot.x)} ${f(spec.pivot.y)})`);
+  }
+}
+
+/**
+ * Upper-and-lower teeth pair (peep, wren). Lower teeth appear only once
+ * the mouth is genuinely open: below that the lower lip is over them and
+ * drawing them turns every mid-open viseme into a grin; above it, their
+ * absence is what made viseme D read as a cave.
+ */
+export function pairedTeeth(p, set, el, teethPath, m) {
+  set(el.teeth, 'd', teethPath(m, clamp(p.teethUpper), false));
+  set(el.teethLo, 'd', teethPath(m, clamp(p.teethUpper) * clamp((m.open - 0.45) / 0.4), true));
+}