@voqalize/avatar 0.4.4 → 0.5.0

package/src/line-art.js

@@ -1,137 +0,0 @@
-/**
- * line-art — the variable-width stroke engine peep was built with.
- *
- * The construction idiom of the Open Peeps style is that NOTHING IS A STROKE:
- * every line is a filled outline whose width varies along its length, which is
- * what lets a mark swell in the middle and come to a point at the ends. A
- * uniform `stroke-width` with round caps is a rope with a blob at each end,
- * and it is the whole difference between "vector illustration" and "someone
- * drew this". Extracted from face-peep.js verbatim so the next line-art
- * character starts from the kit, not from a copy of peep.
- *
- * A curve is a flat list of points in polybezier form — [p0, c1, c2, p1, c3,
- * c4, p2, ...]. `widths` is a PROFILE across the whole mark, sampled at even
- * intervals: [3, 11, 3] means thin-fat-thin whether the curve has one Bézier
- * segment or six. Indexing per node instead is a trap — a one-segment curve
- * has only two nodes, so a third entry is never read and the mark comes out
- * blunt at one end.
- */
-
-import { f } from './face-core.js';
-
-export function toSegs(flat) {
-  // Loud, because the failure is otherwise silent: a point count that is not
-  // 3n+1 simply drops the trailing points and the mark comes out short with no
-  // error anywhere.
-  if (flat.length < 4 || (flat.length - 1) % 3 !== 0) {
-    throw new Error(`curve needs 3n+1 points, got ${flat.length}`);
-  }
-  const out = [];
-  for (let i = 0; i + 3 < flat.length; i += 3) out.push(flat.slice(i, i + 4));
-  return out;
-}
-
-export const bezPt = (P, t) => {
-  const u = 1 - t;
-  return [0, 1].map(
-    (i) => u * u * u * P[0][i] + 3 * u * u * t * P[1][i] + 3 * u * t * t * P[2][i] + t * t * t * P[3][i]
-  );
-};
-export const bezTan = (P, t) => {
-  const u = 1 - t;
-  return [0, 1].map(
-    (i) => 3 * (u * u * (P[1][i] - P[0][i]) + 2 * u * t * (P[2][i] - P[1][i]) + t * t * (P[3][i] - P[2][i]))
-  );
-};
-
-export function widthAt(ws, s) {
-  const u = s * (ws.length - 1);
-  const i = Math.min(Math.floor(u), ws.length - 2);
-  return ws[i] + (ws[i + 1] - ws[i]) * (u - i);
-}
-
-/** Sample a polybezier: point, unit normal, and normalized position along it. */
-export function walk(segs, per) {
-  const out = [];
-  segs.forEach((P, i) => {
-    for (let k = i === 0 ? 0 : 1; k <= per; k++) {
-      const t = k / per;
-      const d = bezTan(P, t);
-      const L = Math.hypot(d[0], d[1]) || 1;
-      out.push({ p: bezPt(P, t), n: [-d[1] / L, d[0] / L], s: (i + t) / segs.length });
-    }
-  });
-  return out;
-}
-
-export const polyD = (pts, cmd) =>
-  pts.map(([x, y], i) => `${i ? 'L' : cmd}${f(x)} ${f(y)}`).join('');
-
-/** An open tapered mark: offset ±w/2 along the normal and close the polygon. */
-export function taper(flat, widths, per = 8) {
-  const s = walk(toSegs(flat), per);
-  const a = [], b = [];
-  for (const { p, n, s: u } of s) {
-    const h = widthAt(widths, u) / 2;
-    a.push([p[0] + n[0] * h, p[1] + n[1] * h]);
-    b.push([p[0] - n[0] * h, p[1] - n[1] * h]);
-  }
-  return polyD(a, 'M') + polyD(b.reverse(), 'L') + 'Z';
-}
-
-/**
- * A closed tapered outline — an annulus of varying width around a contour.
- * Two subpaths of opposite winding, so the inside is a hole under nonzero fill.
- */
-export function taperRing(flat, widths, per = 8) {
-  const s = walk(toSegs(flat), per);
-  const a = [], b = [];
-  for (const { p, n, s: u } of s) {
-    const h = widthAt(widths, u) / 2;
-    a.push([p[0] + n[0] * h, p[1] + n[1] * h]);
-    b.push([p[0] - n[0] * h, p[1] - n[1] * h]);
-  }
-  return polyD(a, 'M') + 'Z' + polyD(b.reverse(), 'M') + 'Z';
-}
-
-/** The plain region a curve encloses — the white "background" path of a part. */
-export function region(flat) {
-  const segs = toSegs(flat);
-  let d = `M${f(segs[0][0][0])} ${f(segs[0][0][1])}`;
-  for (const P of segs) {
-    d += `C${f(P[1][0])} ${f(P[1][1])} ${f(P[2][0])} ${f(P[2][1])} ${f(P[3][0])} ${f(P[3][1])}`;
-  }
-  return d + 'Z';
-}
-
-/**
- * On-curve points -> the polybezier form above, Catmull-Rom at the standard 1/6
- * tension. The house idiom for a FACE is hand-authored control points: a brow or
- * a lip contour is tuned a handle at a time and interpolation would fight that.
- * This is for marks whose geometry is easier to read as a list of places the
- * line goes through than as three-in-four control points — the hand's contours,
- * where the authoring question is "how far does the thumb clear the knuckles"
- * and every point is measured against another point. Curve control is worth
- * less there than a shape whose numbers can be argued about.
- */
-export function smooth(pts) {
-  const out = [pts[0]];
-  for (let i = 0; i < pts.length - 1; i++) {
-    const p0 = pts[i - 1] || pts[i];
-    const p1 = pts[i];
-    const p2 = pts[i + 1];
-    const p3 = pts[i + 2] || p2;
-    out.push(
-      [p1[0] + (p2[0] - p0[0]) / 6, p1[1] + (p2[1] - p0[1]) / 6],
-      [p2[0] - (p3[0] - p1[0]) / 6, p2[1] - (p3[1] - p1[1]) / 6],
-      p2
-    );
-  }
-  return out;
-}
-
-/** Deterministic jitter, so a drawing is the same every load. */
-export function rng(seed) {
-  let s = seed >>> 0;
-  return () => ((s = (s * 1664525 + 1013904223) >>> 0) / 4294967296);
-}

package/src/params.js

@@ -1,180 +0,0 @@
-/**
- * The rig parameter space.
- *
- * Everything the face can do is a point in this ~30-dimensional space. Visemes,
- * emotions, gaze poses and gesture keyframes are all just named vectors here, so
- * blending them is plain arithmetic rather than SVG path surgery.
- *
- * Sign conventions (viewer's perspective):
- *   headYaw   +  turns toward viewer's right
- *   headPitch +  chin down
- *   headRoll  +  tilts toward viewer's right
- *   pupilX    +  right,  pupilY + down
- *   browRaise +  up,  browAngle + outer end up,  browInner + inner end up
- *   mouthCornerL/R + up (smile)
- */
-
-import { JAW_RESPONSE_TAU_S, MOUTH_RESPONSE_TAU_S } from './speech-timing.js';
-
-export const REST = {
-  // --- mouth -------------------------------------------------------------
-  mouthOpen: 0.02, // vertical aperture, 0..1
-  mouthWidth: 0.42, // 0 narrow .. 1 wide (0.42 is neutral)
-  mouthRound: 0.1, // pucker / lip protrusion
-  mouthPress: 0.15, // lips thinned & pressed together
-  mouthTuck: 0.0, // lower lip drawn under upper teeth (F/V)
-  // Availability is not a permanent smile. Warmth and encouragement are
-  // explicit behavioral choices layered above this neutral resting shape.
-  mouthCornerL: 0.0, // -1 frown .. +1 smile
-  mouthCornerR: 0.0,
-  teethUpper: 0.0, // how far the upper teeth show, 0..1
-  tongue: 0.0, // tongue raised into the aperture, 0..1
-  jaw: 0.0, // extra chin drop, follows mouthOpen but slower
-
-  // --- eyes --------------------------------------------------------------
-  // A fully-open lid shows an unnatural ring of sclera; real neutral eyes sit
-  // with the upper lid already grazing the iris.
-  lidL: 0.12, // 0 wide open .. 1 fully closed
-  lidR: 0.12,
-  squintL: 0.0, // lower lid raised (smile / suspicion)
-  squintR: 0.0,
-  pupilX: 0.0,
-  pupilY: 0.05,
-
-  // --- brows -------------------------------------------------------------
-  browRaiseL: 0.0,
-  browRaiseR: 0.0,
-  browAngleL: 0.0,
-  browAngleR: 0.0,
-  browInnerL: 0.0, // inner-end lift, the "concern" muscle (AU1)
-  browInnerR: 0.0,
-
-  // --- head & body -------------------------------------------------------
-  headYaw: 0.0,
-  headPitch: 0.0,
-  headRoll: 0.0,
-  breath: 0.0, // driven by the idle layer, 0..1 through the cycle
-
-  // --- shoulders & torso -------------------------------------------------
-  // Shoulders are a floor-management channel as much as an affective one. The
-  // single most legible "I would like to come in" signal a person gives is the
-  // shoulders rising with an inbreath, and the face alone cannot say it.
-  shoulderL: 0.0, // -1 dropped .. +1 raised
-  shoulderR: 0.0,
-  // Leaning in is engagement and leaning back is withdrawal, and in a webcam
-  // frame both are read almost entirely as a change of scale.
-  torsoLean: 0.0, // -1 back .. +1 forward
-  // The trunk's own lateral axis, and the last body degree of freedom the rig
-  // was missing. Before it, everything below the collar could do was rise,
-  // fall and scale: a motion map over a 24-second listening run showed the
-  // outer edge of the body travelling exactly zero pixels. A seated person's
-  // trunk shifts sideways constantly — settling, re-settling, and lagging
-  // after a head turn — and none of that was expressible.
-  //
-  // It carries the head's turn on a much slower time constant (below), which
-  // is what buys follow-through for free: the mixer retargets it to headYaw
-  // every frame and the difference in TAU does the rest.
-  torsoTurn: 0.0, // -1 trunk toward viewer's left .. +1 right
-};
-
-// There are deliberately no arm or hand channels. The rig carried a full
-// forearm/hand chain — raise, spread, wrist rotation, splay, thumb, index — and
-// it was removed rather than fixed. Two reasons, both worth knowing before
-// anyone re-adds it. The framing is a head-and-shoulders portrait, so a hand
-// only exists at the bottom edge of the crop and every pose is a compromise
-// between "large enough to read" and "not covering the face"; and gesture is a
-// fraction of a percent of what this widget is for, against which the arm chain
-// was the single largest and most defect-prone body of geometry in the rig.
-// What the arms used to say — assent, deference, wanting the floor, apology —
-// is said by the head, brows, shoulders and torso lean instead, which is where
-// a viewer looking at a face on a video call is already looking.
-
-export const CHANNELS = Object.keys(REST);
-
-/**
- * Channel groups. Gesture clips declare which groups they own so that, say, a
- * nod during speech moves the head without stealing the mouth from the viseme
- * stream.
- */
-export const GROUPS = {
-  mouth: [
-    'mouthOpen', 'mouthWidth', 'mouthRound', 'mouthPress', 'mouthTuck',
-    'teethUpper', 'tongue', 'jaw',
-  ],
-  smile: ['mouthCornerL', 'mouthCornerR'],
-  eyes: ['lidL', 'lidR', 'squintL', 'squintR'],
-  gaze: ['pupilX', 'pupilY'],
-  brows: [
-    'browRaiseL', 'browRaiseR', 'browAngleL', 'browAngleR',
-    'browInnerL', 'browInnerR',
-  ],
-  head: ['headYaw', 'headPitch', 'headRoll'],
-  body: ['breath', 'torsoLean', 'torsoTurn'],
-  shoulders: ['shoulderL', 'shoulderR'],
-};
-
-/**
- * Per-channel smoothing time constants, in seconds. This is where the face gets
- * its sense of mass: the mouth snaps, the head drifts. It also does all the
- * viseme co-articulation for free — we never blend shapes explicitly, we just
- * retarget and let the mouth channels chase at ~40ms.
- */
-export const TAU = (() => {
-  const t = {};
-  for (const c of CHANNELS) t[c] = 0.09;
-  for (const c of GROUPS.mouth) t[c] = MOUTH_RESPONSE_TAU_S;
-  for (const c of GROUPS.smile) t[c] = 0.13;
-  t.lidL = t.lidR = 0.018; // blinks must be crisp
-  t.squintL = t.squintR = 0.12;
-  t.pupilX = t.pupilY = 0.032; // saccades are ballistic and fast
-  for (const c of GROUPS.brows) t[c] = 0.08;
-  for (const c of GROUPS.head) t[c] = 0.16; // the head has real mass
-  t.breath = 0.25;
-  t.jaw = JAW_RESPONSE_TAU_S; // the jaw lags the lips slightly
-  // The torso has more mass than the head and reads wrong when it hasn't.
-  t.shoulderL = t.shoulderR = 0.19;
-  t.torsoLean = 0.24;
-  // Nearly 3x the head's, and that ratio is the whole point rather than a
-  // taste call. The mixer feeds torsoTurn the *same* target as headYaw, so
-  // every head turn is chased by a trunk that arrives late and settles late —
-  // follow-through out of the smoothing mechanism the rig already had, with no
-  // second animation system to keep in sync. Shorten this toward the head's
-  // 0.16 and the two move as one rigid piece, which is the puppet read.
-  t.torsoTurn = 0.44;
-  return t;
-})();
-
-/**
- * Per-channel clamp bounds, applied after the layers mix and before smoothing.
- *
- * The head, mouth corners and brow angles are deliberately allowed past 1: they
- * are the channels a gesture clip adds to on top of an already-posed face, and
- * clipping them at 1 flattens the peak of every nod fired during an emotion.
- */
-export const RANGE = (() => {
-  const r = {};
-  for (const c of CHANNELS) r[c] = [0, 1];
-  for (const c of GROUPS.head) r[c] = [-1.4, 1.4];
-  r.mouthCornerL = r.mouthCornerR = [-1.4, 1.4];
-  r.browAngleL = r.browAngleR = [-1.4, 1.4];
-  r.browRaiseL = r.browRaiseR = [-1, 1];
-  r.browInnerL = r.browInnerR = [-1, 1];
-  r.pupilX = r.pupilY = [-1, 1];
-  r.shoulderL = r.shoulderR = [-1, 1];
-  r.torsoLean = [-1, 1];
-  r.torsoTurn = [-1, 1];
-  return r;
-})();
-
-export const clamp = (v, lo = 0, hi = 1) => (v < lo ? lo : v > hi ? hi : v);
-export const lerp = (a, b, t) => a + (b - a) * t;
-
-export function makeParams(overrides) {
-  return Object.assign({}, REST, overrides);
-}
-
-/** Frame-rate independent exponential approach toward a target. */
-export function approach(cur, target, tau, dt) {
-  if (tau <= 0) return target;
-  return cur + (target - cur) * (1 - Math.exp(-dt / tau));
-}

package/src/perform.js

@@ -1,107 +0,0 @@
-/**
- * Perform — the composable action timeline.
- *
- * A performance is the server's choreography: timed verbs `{t, do, ...}` fired
- * against a clock, where every verb resolves to one of the widget's own enums —
- * states, emotions, gaze targets, and semantic actions. The vocabulary is deliberately
- * closed: the backend sequences what the rig already does well, it cannot
- * invent motion. That constraint is what makes the wire format assemblable by
- * a dialogue manager and reviewable by a human.
- *
- * The clock discipline is VisemeTrack's (visemes.js): ride the audio clock
- * whenever there is audio, because a gesture that drifts out of its own
- * sentence is worse than no gesture at all, and a timer drifts the moment the
- * tab is backgrounded. One deliberate difference: beat times fire *verbatim*,
- * with no LEAD_MS. Visemes lead the sound because phoneme sync is
- * frame-critical; a gesture arrives through its channels' own smoothing lag,
- * and any deliberate lead is authored into the times by the composer, not
- * imposed here.
- *
- * Seeking the audio backward does not re-fire earlier actions: verbs have side
- * effects, and replaying a nod is worse than missing one.
- */
-
-const VERBS = new Set(['state', 'emotion', 'gaze', 'action']);
-// `action` is addressed by id; the remaining verbs name an enum value.
-const ID_VERBS = new Set(['action']);
-
-/**
- * Shape hygiene for action arrays, in the spirit of normalizeCues: sort by
- * time, drop what cannot possibly fire — no finite `t`, an unknown verb, a
- * missing `name`/`id` — each with a console warning, never a throw.
- *
- * This checks *shape* only. Enum values are checked when the verb fires, by the dispatcher in
- * avatar.js — deliberately, and not just because importing the enums here
- * would be a dependency cycle: a track half-composed against a newer widget
- * should lose the verbs the widget doesn't know, not the whole performance.
- */
-export function normalizeActions(actions) {
-  const out = [];
-  for (const a of actions || []) {
-    if (!a || typeof a.t !== 'number' || !Number.isFinite(a.t)) {
-      console.warn('perform: dropped action without a time', a);
-      continue;
-    }
-    if (!VERBS.has(a.do)) {
-      console.warn(`perform: dropped unknown verb "${a && a.do}"`, a);
-      continue;
-    }
-    const idVerb = ID_VERBS.has(a.do);
-    if ((idVerb ? a.id : a.name) == null) {
-      console.warn(`perform: dropped ${a.do} with no ${idVerb ? 'id' : 'name'}`, a);
-      continue;
-    }
-    out.push(a);
-  }
-  return out.sort((x, y) => x.t - y.t);
-}
-
-/**
- * Schedules an action track against a clock. Sampled by the mixer once per
- * frame, so firing granularity is one frame — gestures cannot tell.
- */
-export class PerformTrack {
-  constructor() {
-    this.actions = [];
-    this.clock = null;
-    this.playing = false;
-    this._idx = 0;
-    /** @type {(a: object) => void} fired per action, in time order */
-    this.onAction = null;
-    /** Fired when the last action has fired — not when its effects finish. */
-    this.onEnd = null;
-  }
-
-  /** @param {() => number} clock elapsed ms of whatever the track rides on */
-  start(actions, clock) {
-    this.actions = normalizeActions(actions);
-    this.clock = clock;
-    this._idx = 0;
-    this.playing = true;
-    if (!this.actions.length) this._finish();
-  }
-
-  /** Cancels future actions. Does not fire onEnd: a stopped performance did
-   *  not complete, and nothing downstream should be told it did. */
-  stop() {
-    this.playing = false;
-    this.actions = [];
-    this.clock = null;
-    this._idx = 0;
-  }
-
-  update() {
-    if (!this.playing || !this.clock) return;
-    const now = this.clock();
-    while (this._idx < this.actions.length && this.actions[this._idx].t <= now) {
-      const a = this.actions[this._idx++];
-      if (this.onAction) this.onAction(a);
-    }
-    if (this._idx >= this.actions.length) this._finish();
-  }
-
-  _finish() {
-    this.playing = false;
-    if (this.onEnd) this.onEnd();
-  }
-}