@voqalize/avatar 0.2.2 → 0.4.0

package/src/interjections.js

@@ -26,9 +26,13 @@ const nod = (peak, at = 0.24, rebound = 0.56) => [
   [0, 0], [at, peak], [rebound, -peak * 0.24], [1, 0],
 ];
 
-export const INTERJECTIONS = {
+// This is the authoring library. It intentionally contains exploratory clips
+// as well as production ones; only the small `ACTIONS` export below is
+// part of the public action contract.
+const CLIPS = {
   // ---------------------------------------------------------------------
-  // Pure backchannel — no words, fired automatically while LISTENING.
+  // Wordless acknowledgement clips. Every one is an explicit backend or
+  // application decision; the client never fires them from VAD or a timer.
   // ---------------------------------------------------------------------
   // The nod peaks below are pre-compensated for the head's 160ms time constant.
   // Authored at their perceptual value (~0.3) they rendered at ~0.6x and read as
@@ -44,26 +48,27 @@ export const INTERJECTIONS = {
   // drops further than the trend — and everything stays under the 1.5 Hz line
   // where sustained attention turns into impatience.
   NOD_SMALL: {
-    id: 'NOD_SMALL', label: 'nod (continuer)', text: '', duration: 800,
+    id: 'NOD_SMALL', label: 'nod (continuer)', text: '', duration: 900,
     keys: {
-      // One cycle: single-cycle nods are 42% of the corpus, and the continuer
-      // is the quietest citizen of the family — "go on", not "I agree".
-      headPitch: nod(0.55, 0.22, 0.52),
-      browRaiseL: [[0, 0], [0.3, 0.14], [1, 0]],
-      browRaiseR: [[0, 0], [0.3, 0.14], [1, 0]],
+      // One readable stroke, not an ambient bob. The peak is deliberately
+      // authored above its desired rendered travel because the common head
+      // smoothing absorbs a fast impulse before it reaches the SVG.
+      headPitch: [[0, 0], [0.25, 0.74], [0.38, 0.70], [0.68, -0.12], [1, 0]],
+      browRaiseL: [[0, 0], [0.34, 0.16], [1, 0]],
+      browRaiseR: [[0, 0], [0.34, 0.16], [1, 0]],
     },
   },
   NOD_SLOW: {
-    id: 'NOD_SLOW', label: 'nod (assessment, two-beat)', text: '', duration: 1420,
+    id: 'NOD_SLOW', label: 'nod (assessment / receipt)', text: '', duration: 1200,
     keys: {
-      // Two cycles at ~1.4 Hz. The first beat is the deepest thing any nod
-      // does (anticipatory rising) and the second sits well below it —
-      // declination plus final lowering, which is what makes the gesture
-      // resolve instead of merely stopping. The lift between beats crosses
-      // slightly above rest so the cycles read as separate strokes.
-      headPitch: [[0, 0], [0.16, 0.85], [0.38, -0.10], [0.60, 0.55], [0.85, -0.06], [1, 0]],
-      mouthCornerL: [[0, 0], [0.45, 0.12], [1, 0]],
-      mouthCornerR: [[0, 0], [0.45, 0.12], [1, 0]],
+      // A receipt needs an arrival. The former two fast peaks registered as
+      // idle bobbing at call-tile size, so this is one deep downstroke with a
+      // short dwell and a slower recovery. The tiny torso commitment keeps the
+      // head from looking like it is sliding independently of the body.
+      headPitch: [[0, 0], [0.18, 0.18], [0.39, 1.06], [0.52, 1.02], [0.78, -0.16], [1, 0]],
+      torsoLean: [[0, 0], [0.40, 0.09], [0.58, 0.07], [1, 0]],
+      browRaiseL: [[0, 0], [0.23, 0.12], [0.62, 0.08], [1, 0]],
+      browRaiseR: [[0, 0], [0.23, 0.10], [0.62, 0.07], [1, 0]],
     },
   },
   // The "ah — I see" nod. What separates it from agreement is the upswing:
@@ -88,13 +93,126 @@ export const INTERJECTIONS = {
     keys: {
       browRaiseL: [[0, 0], [0.24, 0.30], [0.7, 0.06], [1, 0]],
       browRaiseR: [[0, 0], [0.24, 0.26], [0.7, 0.06], [1, 0]],
-      headPitch: [[0, 0], [0.3, 0.08], [1, 0]],
       mouthCornerL: [[0, 0], [0.35, 0.14], [1, 0]],
       mouthCornerR: [[0, 0], [0.35, 0.14], [1, 0]],
     },
     blinkAt: [0.22],
   },
-  // The disagree family follows the same three laws as the nods (§3.4): the
+  // ---------------------------------------------------------------------
+  // Understanding beats — eye/face/body composites, deliberately separate
+  // from nods. They are the shared low-authoring-cost alternative when a
+  // portrait's pitch geometry is too limited to carry acknowledgement alone.
+  // ---------------------------------------------------------------------
+  ACK_CONTINUE: {
+    id: 'ACK_CONTINUE', label: 'acknowledge: continue', text: '', duration: 620,
+    keys: {
+      // Eyes acknowledge first; nothing here claims agreement or closes the
+      // conversational floor while the user is still talking.
+      browRaiseL: [[0, 0], [0.18, 0.14], [0.48, 0.06], [1, 0]],
+      browRaiseR: [[0, 0], [0.18, 0.12], [0.48, 0.05], [1, 0]],
+      lidL: [[0, 0], [0.20, 0.035], [0.58, 0.01], [1, 0]],
+      lidR: [[0, 0], [0.20, 0.035], [0.58, 0.01], [1, 0]],
+    },
+  },
+  ACK_RECEIVE: {
+    id: 'ACK_RECEIVE', label: 'acknowledge: received', text: '', duration: 1120,
+    keys: {
+      // Recognition → take it in → settle. The face does not nod; it lands in
+      // a quiet, held receipt, leaving room for the user to see the response.
+      // Recognition is quick: everything arrives in the first ~150 ms and then
+      // holds. It used to build over the first third of the clip with the lids
+      // half-lowered and the trunk sinking, and a video reviewer read that as
+      // the head drifting down — "looks like losing consciousness". The lids
+      // are a flicker now, not a droop, and the lean is a small forward set.
+      browRaiseL: [[0, 0], [0.09, 0.17], [0.30, 0.06], [1, 0]],
+      browRaiseR: [[0, 0], [0.09, 0.14], [0.30, 0.05], [1, 0]],
+      lidL: [[0, 0], [0.10, 0.09], [0.30, 0.04], [0.70, 0.02], [1, 0]],
+      lidR: [[0, 0], [0.10, 0.09], [0.30, 0.04], [0.70, 0.02], [1, 0]],
+      mouthPress: [[0, 0], [0.13, 0.20], [0.60, 0.15], [1, 0]],
+      mouthCornerL: [[0, 0], [0.18, 0.09], [0.80, 0.055], [1, 0]],
+      mouthCornerR: [[0, 0], [0.18, 0.09], [0.80, 0.055], [1, 0]],
+      torsoLean: [[0, 0], [0.14, 0.07], [0.70, 0.05], [1, 0]],
+      shoulderL: [[0, 0], [0.16, 0.060], [0.70, 0.035], [1, 0]],
+      shoulderR: [[0, 0], [0.16, 0.060], [0.70, 0.035], [1, 0]],
+    },
+  },
+  ACK_REALIZE: {
+    id: 'ACK_REALIZE', label: 'acknowledge: realization', text: '', duration: 980,
+    keys: {
+      // The brows and widened lid lead: this means "the point connected", not
+      // the generic social smile which looks like agreement in a small tile.
+      browRaiseL: [[0, 0], [0.15, 0.36], [0.42, 0.20], [1, 0]],
+      browRaiseR: [[0, 0], [0.15, 0.32], [0.42, 0.18], [1, 0]],
+      lidL: [[0, 0], [0.16, -0.07], [0.48, -0.025], [1, 0]],
+      lidR: [[0, 0], [0.16, -0.07], [0.48, -0.025], [1, 0]],
+      mouthCornerL: [[0, 0], [0.35, 0.12], [0.80, 0.09], [1, 0]],
+      mouthCornerR: [[0, 0], [0.35, 0.12], [0.80, 0.09], [1, 0]],
+      torsoLean: [[0, 0], [0.38, 0.07], [0.72, 0.05], [1, 0]],
+    },
+  },
+  ACK_EMPATHIZE: {
+    id: 'ACK_EMPATHIZE', label: 'acknowledge: empathy', text: '', duration: 1180,
+    keys: {
+      // Inner brows and softened lids acknowledge the affect without signalling
+      // agreement. Keep the mouth nearly neutral for professional contexts.
+      browInnerL: [[0, 0], [0.22, 0.24], [0.68, 0.16], [1, 0]],
+      browInnerR: [[0, 0], [0.22, 0.20], [0.68, 0.13], [1, 0]],
+      browRaiseL: [[0, 0], [0.22, 0.07], [0.68, 0.05], [1, 0]],
+      browRaiseR: [[0, 0], [0.22, 0.06], [0.68, 0.04], [1, 0]],
+      lidL: [[0, 0], [0.25, 0.06], [0.72, 0.04], [1, 0]],
+      lidR: [[0, 0], [0.25, 0.06], [0.72, 0.04], [1, 0]],
+      mouthPress: [[0, 0], [0.34, 0.06], [0.72, 0.045], [1, 0]],
+      torsoLean: [[0, 0], [0.40, 0.065], [0.76, 0.045], [1, 0]],
+    },
+  },
+  // A comparison nod, not the director's default. Two quick decaying strokes
+  // with a barely-there listening tilt reflect the common conversational form
+  // the current single deep receipt does not show. It stays comparison-only:
+  // the host can decide whether this faster cadence fits its conversation.
+  // **Slower than it was, and that is what made it land.** This nod ran two
+  // down-beats 381 ms apart — 2.6 Hz, which is past the 1.5 Hz line CLAUDE.md
+  // and research-biomechanics.md § 3.4 both draw between "I'm with you" and
+  // "hurry up", and which the head's own 160 ms smoothing attenuates to about a
+  // third. Authoring it louder was the obvious fix and the wrong one: the
+  // gesture was not too small, it was too *fast* to survive the mass of the
+  // thing it was moving.
+  //
+  // At 780 ms between down-beats it is 1.28 Hz, attenuated to about 0.64
+  // instead of 0.36, and 1.5 s long — which is where the research puts this
+  // kind of nod anyway. § 3.3 separates a `short` continuer (0.83 s, small)
+  // from a `long` assessment nod (1.42 s, large range), and an acknowledgement
+  // of what someone just said is the second. § 3.4's two structural laws hold:
+  // the first cycle is the biggest, and each one decays.
+  //
+  // **No opening up-beat, and the corpus is why.** An earlier pass gave this a
+  // small preparatory lift on the theory that a nod winds up before it starts.
+  // § 3.3 separates `long` (large range, *no* swing-up) from `long_p` (large
+  // range *with* one, reading as a cognitive shift), so a lift here was quietly
+  // making agreement look like realisation. It also broke the rate: the beat
+  // sat 330 ms before the first peak, a 1.52 Hz opening half-cycle in a clip
+  // whose two down-beats are a comfortable 1.28 Hz apart.
+  ACK_NOD: {
+    id: 'ACK_NOD', label: 'acknowledge: nod', text: '', duration: 1500,
+    keys: {
+      // Down, up through neutral, down again, settle. The trailing −0.08 flourish
+      // that used to sit at 0.94 is gone: it put two *return* beats 570 ms apart,
+      // a 1.75 Hz oscillation inside a clip whose down-beats are a comfortable
+      // 1.28 Hz. A gesture's last move should be releasing, not one more beat.
+      // Each down is the stroke and each up the recovery, so the downs are
+      // fast and the ups take their time: a symmetric ramp on both sides read
+      // as "a very slow, linear dip" on video. The downs still sit 720 ms
+      // apart (1.39 Hz), and a short hold at the bottom is what gives the
+      // stroke its weight.
+      headPitch: [[0, 0], [0.16, 1.10], [0.24, 1.00], [0.52, -0.20], [0.64, 0.66], [0.72, 0.58], [1, 0]],
+      headRoll: [[0, 0], [0.18, -0.090], [0.70, -0.070], [1, 0]],
+      torsoLean: [[0, 0], [0.32, 0.130], [0.70, 0.085], [1, 0]],
+      shoulderL: [[0, 0], [0.44, 0.062], [0.76, 0.036], [1, 0]],
+      shoulderR: [[0, 0], [0.44, 0.062], [0.76, 0.036], [1, 0]],
+      lidL: [[0, 0], [0.30, 0.070], [0.68, 0.040], [1, 0]],
+      lidR: [[0, 0], [0.30, 0.070], [0.68, 0.040], [1, 0]],
+    },
+  },
+  // The disagree family follows the same three laws as explicit nods (§3.4): the
   // first swing is the biggest, every cycle decays, and the whole gesture
   // stays at or under ~1.5 Hz. Both are SERVER-SENT ONLY — an agent must
   // never disagree autonomously, so neither is in the listening engine's
@@ -211,6 +329,24 @@ export const INTERJECTIONS = {
     blinkAt: [0.1],
   },
 
+  /** Server-confirmed cut-off after playout stopped. This is not a state: the
+   * clip explains the abrupt transition, then lands in whatever factual pose
+   * Pipecat has resolved underneath it. */
+  RESPONSE_INTERRUPTED: {
+    id: 'RESPONSE_INTERRUPTED', label: 'response: interrupted', text: '', duration: 1550,
+    keys: {
+      mouthOpen: [[0, 0], [0.06, 0.36], [0.80, 0.36], [1, 0]],
+      jaw: [[0, 0], [0.08, 0.20], [0.80, 0.20], [1, 0]],
+      browRaiseL: [[0, 0], [0.12, 0.46], [0.72, 0.34], [1, 0]],
+      browRaiseR: [[0, 0], [0.12, 0.40], [0.72, 0.30], [1, 0]],
+      lidL: [[0, 0], [0.12, -0.18], [0.72, -0.12], [1, 0]],
+      lidR: [[0, 0], [0.12, -0.16], [0.72, -0.10], [1, 0]],
+      torsoLean: [[0, 0], [0.18, -0.16], [0.72, -0.10], [1, 0]],
+      shoulderL: [[0, 0], [0.18, -0.12], [0.72, -0.08], [1, 0]],
+      shoulderR: [[0, 0], [0.18, -0.12], [0.72, -0.08], [1, 0]],
+    },
+  },
+
   /**
    * "May I come in." This used to be a raised palm, and it is now the same
    * signal without one: the body claims a little space and the face asks. The
@@ -273,8 +409,8 @@ export const INTERJECTIONS = {
    * oscillation left to fill the time; a held smile past about a second stops
    * being a greeting and becomes an expression.
    */
-  WAVE: {
-    id: 'WAVE', label: 'greet (brow flash)', text: '', duration: 1300,
+  GESTURE_GREET: {
+    id: 'GESTURE_GREET', label: 'gesture: greet', text: '', duration: 1300,
     keys: {
       browRaiseL: [[0, 0], [0.11, 0.85], [0.4, 0.22], [0.75, 0.12], [1, 0]],
       browRaiseR: [[0, 0], [0.11, 0.80], [0.4, 0.20], [0.75, 0.10], [1, 0]],
@@ -304,8 +440,8 @@ export const INTERJECTIONS = {
    * Deep enough to be unmistakable: peak 0.62 against NOD_SMALL's 0.52, over
    * nearly three times the duration.
    */
-  THUMBS_UP: {
-    id: 'THUMBS_UP', label: 'approve', text: '', duration: 1500,
+  GESTURE_APPROVE: {
+    id: 'GESTURE_APPROVE', label: 'gesture: approve', text: '', duration: 1500,
     keys: {
       headPitch: [[0, 0], [0.3, 0.62], [0.58, 0.20], [0.78, 0.34], [1, 0]],
       mouthCornerL: [[0, 0], [0.36, 0.58], [0.8, 0.48], [1, 0]],
@@ -473,8 +609,8 @@ export const INTERJECTIONS = {
       torsoLean: [[0, 0], [0.25, 0.10], [0.7, 0.08], [1, 0]],
     },
   },
-  ONE_MOMENT: {
-    id: 'ONE_MOMENT', label: 'one moment', text: 'one moment', duration: 1350,
+  GESTURE_WAIT: {
+    id: 'GESTURE_WAIT', label: 'gesture: wait', text: 'one moment', duration: 1350,
     // w · ʌ · n  ·  m · oʊ · m · ə · n · t
     mouthCues: [
       { t: 0, v: 'F' }, { t: 110, v: 'C' }, { t: 210, v: 'A' }, { t: 320, v: 'F' },
@@ -557,19 +693,52 @@ export const INTERJECTIONS = {
   },
 };
 
-export const INTERJECTION_IDS = Object.keys(INTERJECTIONS);
+/** Full local authoring library. Not a server action vocabulary. */
+export const INTERNAL_CLIPS = CLIPS;
 
-/** Clips that carry words, vs. wordless backchannel. */
-export const SPOKEN_IDS = INTERJECTION_IDS.filter((k) => INTERJECTIONS[k].text);
+/**
+ * This renderer's own addressable actions — the bundled SVG faces' catalogue,
+ * not the wire's vocabulary, which is open and has only two required ids
+ * (`docs/contract-wire.md` § Action).
+ *
+ * Every one of these is a name a server may send *once it knows this renderer
+ * is mounted*, and nothing here is a name it may send blind. Two of them are
+ * what `ACKNOWLEDGE` resolves to on the floor — `ACK_NOD` while the user still
+ * has it, `ACK_RECEIVE` once they have stopped — and `RESPONSE_INTERRUPTED` is
+ * required of every avatar, so it appears here as this renderer's shape for it
+ * rather than as its own idea. The four `GESTURE_*` are things this body does
+ * and no protocol asks for.
+ *
+ * Naming is `CATEGORY_INTENT`, and the list doubles as the conformance sweep's
+ * roster: `ACKNOWLEDGE` is absent on purpose, because sweeping both shapes it
+ * resolves to covers strictly more.
+ */
+export const ACTION_IDS = Object.freeze([
+  'ACK_RECEIVE', 'ACK_NOD',
+  'RESPONSE_INTERRUPTED',
+  'GESTURE_GREET', 'GESTURE_GOODBYE', 'GESTURE_APPROVE', 'GESTURE_WAIT',
+]);
+
+/** Face-capable subset of the action contract. */
+export const ACTIONS = Object.freeze({
+  ...Object.fromEntries(ACTION_IDS.filter((id) => CLIPS[id]).map((id) => [id, CLIPS[id]])),
+  // The goodbye face intentionally reuses the greeting brow-flash while its
+  // hand owns the distinct, longer farewell motion. It still needs metadata so
+  // a client can enumerate every public action without knowing that detail.
+  GESTURE_GOODBYE: {
+    ...CLIPS.GESTURE_GREET,
+    id: 'GESTURE_GOODBYE', label: 'gesture: goodbye', duration: 1550,
+  },
+});
 
 /**
- * Attach audio to a clip. Call once at boot with your own TTS renders:
- *   attachAudio('OKAY', '/audio/agent-okay.mp3')
+ * Attach audio to an internal authoring clip. Production actions are silent
+ * sequences; response speech always belongs to Pipecat's audio/viseme track.
  * The baked viseme track is then scheduled against that file's clock instead of
  * the local timer, so any timing drift resolves in the audio's favour.
  */
 export function attachAudio(id, url) {
-  const clip = INTERJECTIONS[id];
+  const clip = CLIPS[id];
   if (!clip) throw new Error(`unknown interjection: ${id}`);
   const el = new Audio(url);
   el.preload = 'auto';

package/src/params.js

@@ -14,6 +14,8 @@
  *   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
@@ -21,8 +23,10 @@ export const REST = {
   mouthRound: 0.1, // pucker / lip protrusion
   mouthPress: 0.15, // lips thinned & pressed together
   mouthTuck: 0.0, // lower lip drawn under upper teeth (F/V)
-  mouthCornerL: 0.1, // -1 frown .. +1 smile
-  mouthCornerR: 0.1,
+  // 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
@@ -118,7 +122,7 @@ export const GROUPS = {
 export const TAU = (() => {
   const t = {};
   for (const c of CHANNELS) t[c] = 0.09;
-  for (const c of GROUPS.mouth) t[c] = 0.042;
+  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;
@@ -126,7 +130,7 @@ export const TAU = (() => {
   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 = 0.07; // the jaw lags the lips slightly
+  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;

package/src/perform.js

@@ -3,7 +3,7 @@
  *
  * 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, interjections, hand gestures. The vocabulary is deliberately
+ * 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.
@@ -14,25 +14,23 @@
  * 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 (CLAIM_FLOOR starts ~350ms before the first sample)
- * is authored into the times by the composer, not imposed here.
+ * 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', 'interject', 'gesture']);
-// The verbs addressed by `id` rather than `name`. Both id verbs name a clip the
-// widget already owns; both name-verbs name an enum value.
-const ID_VERBS = new Set(['interject', 'gesture']);
+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 (is "THINKING" a state? is "NOD_UP"
- * an interjection?) are checked when the verb fires, by the dispatcher in
+ * 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.