@convai/embody 1.0.1 → 1.1.0-beta.0

package/dist/rig/resolve.d.ts

@@ -27,7 +27,13 @@ export interface ResolvedRig {
  * them — validating those is the upload pipeline's job, not embody's.
  */
 export declare const REQUIRED_BONES: readonly BoneRole[];
-/** Apply a profile to a loaded root. Call once, at load — never per frame. */
-export declare function resolveRig(root: THREE.Object3D, profile: RigProfile): ResolvedRig;
+/**
+ * Apply a profile to a loaded root. Call once, at load — never per frame.
+ * `quiet` leaves missing bones to the caller to report (createCharacter's
+ * report says it, with the fix).
+ */
+export declare function resolveRig(root: THREE.Object3D, profile: RigProfile, opts?: {
+    quiet?: boolean;
+}): ResolvedRig;
 /** Write a value to every mesh carrying a role. Absent roles are a no-op. */
 export declare function writeMorph(rig: ResolvedRig, role: MorphRole, value: number): void;

package/dist/rig/resolve.js

@@ -14,8 +14,12 @@ function findFirst(root, aliases) {
     }
     return null;
 }
-/** Apply a profile to a loaded root. Call once, at load — never per frame. */
-export function resolveRig(root, profile) {
+/**
+ * Apply a profile to a loaded root. Call once, at load — never per frame.
+ * `quiet` leaves missing bones to the caller to report (createCharacter's
+ * report says it, with the fix).
+ */
+export function resolveRig(root, profile, opts = {}) {
     const bones = {};
     const restPose = {};
     const missing = [];
@@ -33,7 +37,7 @@ export function resolveRig(root, profile) {
         if (!bones[role])
             missing.push(role);
     }
-    if (missing.length) {
+    if (missing.length && !opts.quiet) {
         const detail = missing.map((r) => {
             const aliases = profile.bones[r] ?? [];
             const desc = aliases.length > 0 ? aliases.join('|') : 'no aliases declared in profile';

package/dist/rig/units.d.ts

@@ -1,27 +1,46 @@
 /**
- * Unit normalisation for character models.
+ * Unit normalisation and grounding for character models.
  *
- * Assets disagree about export scale (sofia.glb: raw centimetres;
+ * SCALE. Assets disagree about export scale (sofia.glb: raw centimetres;
  * japanese-f.glb: centimetre geometry under a baked 0.01 root), and every
  * static measure of a SkinnedMesh lies about rendered size — Box3 and
  * computeBoundingBox read bind-pose geometry, bone spans miss bind scaling.
+ * The assumption-free answer is to measure the head→ankle bone span in WORLD
+ * space and multiply the scale by the error until it converges.
  *
- * The assumption-free answer (proven in the playhouse's CharacterPreview):
- * measure the head→ankle bone span actually in world space every frame and
- * multiply the scale by the error until it converges. Costs two
- * getWorldPosition calls; settles in a frame or two; cannot be wrong about
- * units because it never assumes any.
+ * That measurement is only meaningful in an upright pose, so it is taken
+ * ONCE, at construction, in the bind pose (nothing has animated the skeleton
+ * yet), and never again. Re-measuring every frame — what this module used to
+ * do — reads any pose that is not standing straight as "too small" and blows
+ * the character up: kneeling 1.5x, crouched 2.1x, bending to pick something up
+ * 2.7x (measured with Mixamo clips on a convai-mha-1 body).
  *
- * This is consumer-side insurance. The character spec gains a units mandate
- * and the processing pipeline will normalise export scale; this stays as the
- * belt to that suspenders.
+ * GROUND. The soles go on the ground, not the ankle bone: pinning `foot_l`
+ * put the soles ~10 cm under the floor. At construction the lowest skinned
+ * vertices under each foot and ball bone are captured in that bone's local
+ * frame; every frame they are carried by the bone (so a rolled foot, a lifted
+ * heel or tiptoes are followed) and the lowest of them, across both feet, is
+ * placed on `groundY`. A body without skinned feet falls back to the ankle
+ * bones.
+ *
+ * `grounding: 'clip'` places the body once and then leaves vertical motion to
+ * the clip — for jumps and anything else that should leave the floor.
  */
 import * as THREE from 'three';
-export interface UnitNormalizer {
-    /** Run every frame until it reports true (converged). Cheap either way. */
-    update(): boolean;
-}
-export declare function createUnitNormalizer(root: THREE.Object3D, opts?: {
+export type Grounding = 'feet' | 'clip';
+export interface UnitNormalizerOptions {
     targetHeight?: number;
     groundY?: number;
-}): UnitNormalizer;
+    /**
+     * `feet` (default): every frame, the lowest sole point rests on `groundY`.
+     * `clip`: grounded once at load; the clip's own root motion decides height.
+     */
+    grounding?: Grounding;
+}
+export interface UnitNormalizer {
+    /** Root scale after the one-time measurement. */
+    readonly scale: number;
+    /** Put the current pose on the ground. Call after the pose is final for the frame. */
+    ground(): void;
+}
+export declare function createUnitNormalizer(root: THREE.Object3D, opts?: UnitNormalizerOptions): UnitNormalizer;

package/dist/rig/units.js

@@ -1,61 +1,162 @@
 /**
- * Unit normalisation for character models.
+ * Unit normalisation and grounding for character models.
  *
- * Assets disagree about export scale (sofia.glb: raw centimetres;
+ * SCALE. Assets disagree about export scale (sofia.glb: raw centimetres;
  * japanese-f.glb: centimetre geometry under a baked 0.01 root), and every
  * static measure of a SkinnedMesh lies about rendered size — Box3 and
  * computeBoundingBox read bind-pose geometry, bone spans miss bind scaling.
+ * The assumption-free answer is to measure the head→ankle bone span in WORLD
+ * space and multiply the scale by the error until it converges.
  *
- * The assumption-free answer (proven in the playhouse's CharacterPreview):
- * measure the head→ankle bone span actually in world space every frame and
- * multiply the scale by the error until it converges. Costs two
- * getWorldPosition calls; settles in a frame or two; cannot be wrong about
- * units because it never assumes any.
+ * That measurement is only meaningful in an upright pose, so it is taken
+ * ONCE, at construction, in the bind pose (nothing has animated the skeleton
+ * yet), and never again. Re-measuring every frame — what this module used to
+ * do — reads any pose that is not standing straight as "too small" and blows
+ * the character up: kneeling 1.5x, crouched 2.1x, bending to pick something up
+ * 2.7x (measured with Mixamo clips on a convai-mha-1 body).
  *
- * This is consumer-side insurance. The character spec gains a units mandate
- * and the processing pipeline will normalise export scale; this stays as the
- * belt to that suspenders.
+ * GROUND. The soles go on the ground, not the ankle bone: pinning `foot_l`
+ * put the soles ~10 cm under the floor. At construction the lowest skinned
+ * vertices under each foot and ball bone are captured in that bone's local
+ * frame; every frame they are carried by the bone (so a rolled foot, a lifted
+ * heel or tiptoes are followed) and the lowest of them, across both feet, is
+ * placed on `groundY`. A body without skinned feet falls back to the ankle
+ * bones.
+ *
+ * `grounding: 'clip'` places the body once and then leaves vertical motion to
+ * the clip — for jumps and anything else that should leave the floor.
  */
 import * as THREE from 'three';
 /** Head→ankle joint span as a fraction of full stature (calibrated on Sofia). */
 const BONE_SPAN_RATIO = 0.837;
+/** Bones whose skinned vertices can touch the floor when standing. */
+const CONTACT_BONES = ['foot_l', 'foot_r', 'ball_l', 'ball_r'];
+/** A vertex within this of a bone region's lowest point is part of its sole, m. */
+const SOLE_BAND = 0.01;
+/** At most this many sole points are kept per bone (spread over the sole). */
+const POINTS_PER_BONE = 12;
+function findBone(root, name) {
+    let hit = null;
+    root.traverse((o) => {
+        if (!hit && o.name.trim().toLowerCase() === name)
+            hit = o;
+    });
+    return hit;
+}
+function worldY(o, tmp) {
+    o.updateWorldMatrix(true, false);
+    return o.getWorldPosition(tmp).y;
+}
+/**
+ * The lowest skinned vertices of each contact bone, in that bone's local frame.
+ * A vertex belongs to the bone carrying most of its weight. Read in the bind
+ * pose, once.
+ */
+function captureSoles(root, bones) {
+    const regions = new Map();
+    const v = new THREE.Vector3();
+    // updateMatrixWorld, not updateWorldMatrix: only the former runs
+    // SkinnedMesh's override that refreshes bindMatrixInverse, which
+    // getVertexPosition reads.
+    root.updateMatrixWorld(true);
+    root.traverse((o) => {
+        const mesh = o;
+        if (!mesh.isSkinnedMesh)
+            return;
+        const si = mesh.geometry.attributes.skinIndex;
+        const sw = mesh.geometry.attributes.skinWeight;
+        if (!si || !sw)
+            return;
+        for (let i = 0; i < si.count; i++) {
+            let best = -1;
+            let bone = -1;
+            for (let c = 0; c < 4; c++) {
+                const w = sw.getComponent(i, c);
+                if (w > best) {
+                    best = w;
+                    bone = si.getComponent(i, c);
+                }
+            }
+            const b = mesh.skeleton.bones[bone];
+            if (!b || !bones.has(b.name.trim().toLowerCase()))
+                continue;
+            mesh.getVertexPosition(i, v).applyMatrix4(mesh.matrixWorld);
+            let list = regions.get(b);
+            if (!list)
+                regions.set(b, (list = []));
+            list.push(v.clone());
+        }
+    });
+    const points = [];
+    for (const [bone, verts] of regions) {
+        const low = Math.min(...verts.map((p) => p.y));
+        const sole = verts.filter((p) => p.y <= low + SOLE_BAND);
+        const step = Math.max(1, Math.floor(sole.length / POINTS_PER_BONE));
+        bone.updateWorldMatrix(true, false);
+        for (let i = 0; i < sole.length; i += step) {
+            points.push({ bone, local: bone.worldToLocal(sole[i].clone()) });
+        }
+    }
+    return points;
+}
 export function createUnitNormalizer(root, opts = {}) {
     const target = (opts.targetHeight ?? 1.7) * BONE_SPAN_RATIO;
     const groundY = opts.groundY ?? 0;
-    let head = null;
-    let foot = null;
-    root.traverse((o) => {
-        const n = o.name.trim().toLowerCase();
-        if (!head && n === 'head')
-            head = o;
-        if (!foot && n === 'foot_l')
-            foot = o;
-    });
-    const a = new THREE.Vector3();
-    const b = new THREE.Vector3();
-    let settled = 0;
-    return {
-        update() {
-            if (!head || !foot)
-                return true;
-            head.updateWorldMatrix(true, false);
-            foot.updateWorldMatrix(true, false);
-            const span = head.getWorldPosition(a).y - foot.getWorldPosition(b).y;
+    const head = findBone(root, 'head');
+    const ankle = findBone(root, 'foot_l');
+    const tmp = new THREE.Vector3();
+    // Scale, once. Uniform scale makes the span linear in the root scale, so
+    // this converges in one or two passes; the bound is only insurance.
+    if (head && ankle) {
+        for (let i = 0; i < 8; i++) {
+            const span = worldY(head, tmp) - worldY(ankle, tmp);
             if (!(span > 1e-9))
-                return false;
+                break;
             const err = target / span;
-            if (Math.abs(err - 1) > 0.005) {
-                root.scale.multiplyScalar(err);
-                root.updateWorldMatrix(true, true);
-                settled = 0;
-            }
-            else
-                settled++;
-            // feet on the floor, every pass, so scale correction never leaves the
-            // character hovering or sunk
-            foot.updateWorldMatrix(true, false);
-            root.position.y += groundY - foot.getWorldPosition(b).y;
-            return settled > 2;
+            if (Math.abs(err - 1) < 1e-6)
+                break;
+            root.scale.multiplyScalar(err);
+            root.updateWorldMatrix(true, true);
+        }
+    }
+    const contactBones = new Map();
+    for (const name of CONTACT_BONES) {
+        const b = findBone(root, name);
+        if (b)
+            contactBones.set(name, b);
+    }
+    const soles = captureSoles(root, contactBones);
+    // Without skinned feet, the ankle bones themselves are the contact points.
+    const contacts = soles.length
+        ? soles
+        : [...contactBones.values()].map((bone) => ({ bone, local: new THREE.Vector3() }));
+    const lowest = () => {
+        let low = Infinity;
+        for (const c of contacts) {
+            c.bone.updateWorldMatrix(true, false);
+            const y = tmp.copy(c.local).applyMatrix4(c.bone.matrixWorld).y;
+            if (y < low)
+                low = y;
+        }
+        return low;
+    };
+    const place = () => {
+        if (!contacts.length)
+            return;
+        const low = lowest();
+        if (!Number.isFinite(low))
+            return;
+        root.position.y += groundY - low;
+        root.updateWorldMatrix(false, false);
+    };
+    // Grounded at load in either mode, so 'clip' starts on the floor too.
+    place();
+    return {
+        scale: root.scale.x,
+        ground() {
+            if (opts.grounding === 'clip')
+                return;
+            place();
         },
     };
 }

package/dist/speech/expression.d.ts

@@ -0,0 +1,20 @@
+export type Mood = 'warm' | 'neutral' | 'curious' | 'focused' | 'steady';
+export declare class Expression {
+    /** How much of the warm expression the face wears. Cross-fades over ~1 s. */
+    mood: Mood;
+    private readonly mouth;
+    private readonly eyes;
+    private readonly rounding;
+    private readonly closure;
+    private readonly depress;
+    private readonly brow;
+    private readonly browSlow;
+    private warmMouth;
+    private warmEyes;
+    private quiet;
+    private t;
+    private readonly m;
+    constructor(mood?: Mood);
+    /** Apply to `out` in place. `speaking`: the character's voice is playing. */
+    apply(out: Float32Array, dt: number, speaking: boolean): void;
+}

package/dist/speech/expression.js

@@ -0,0 +1,118 @@
+/**
+ * Expression over the lipsync stream: a face that keeps its warmth between
+ * sentences, applied to the shaped frame (MHA channel order) before it is
+ * written to the face.
+ *
+ * Speech is fast and mouth-only; emotion is slow and face-wide. So each
+ * channel has an owner:
+ *  · Speech owns articulation (jaw, lip press, purse, funnel, raise, depress,
+ *    stretch): never written here.
+ *  · Shared channels (mouth corners, dimples) are split into a slow part and
+ *    the stream's fast motion; the smile is screened onto the slow part only,
+ *    gated off by lip rounding and closure (a smile flattening an "oo" or a
+ *    "p" reads worse than a missing smile).
+ *  · Emotion (cheek raise, upper lid): a weak Duchenne smile, eased to ~45%
+ *    of the mouth's and ~35% of the eyes' rest level while speaking. The
+ *    stream's own cheek raise and inner squint are capped: it sends up to
+ *    ~0.45 on stressed words, which closed the eyes to slits mid-sentence.
+ *  · Sad shapes the stream sends are remapped, not deleted: an inner-only brow
+ *    raise becomes a full raise (interest), brow-down halves under a raised
+ *    inner brow, and corner depress is cancelled by the smile.
+ *
+ * Timing: back to the rest expression only after 0.7 s of silence (pauses
+ * between sentences don't pop it), held 2.5 s, then relaxed to a lighter idle
+ * level; a slow few-percent drift so it is never frozen. The mood sets how
+ * much of it there is. Values are the coffee-shop studio's.
+ */
+import { MHA_PROFILE } from '@convai/web-sdk/lipsync-helpers';
+const MOODS = {
+    warm: { mouth: 1, eyes: 1, browDown: 0, browOuter: 0 },
+    neutral: { mouth: 0.2, eyes: 0.15, browDown: 0, browOuter: 0 },
+    curious: { mouth: 0.6, eyes: 0.5, browDown: 0, browOuter: 0.12 },
+    focused: { mouth: 0.25, eyes: 0.1, browDown: 0.14, browOuter: 0 },
+    // Present without the smile, brows a touch down: the default on a male
+    // record, where the light smile of `neutral` read soft.
+    steady: { mouth: 0.08, eyes: 0.05, browDown: 0.12, browOuter: 0 },
+};
+/** The smile at full warmth, per channel (base names; both sides). */
+const MOUTH = { mouthCornerPull: 0.3, mouthCornerUp: 0.2, mouthDimple: 0.06 };
+const EYES = { eyeCheekRaise: 0.15, eyeUpperLidUp: 0.04, eyeSquintInner: 0 };
+const STREAM_EYE_CAP = { eyeCheekRaise: 0.08, eyeSquintInner: 0.04, eyeUpperLidUp: 1 };
+const ROUNDING = /^(mouthFunnel|mouthLipsPurse|mouthLipsTowards)/;
+const CLOSURE = /^(mouthLipsPress|mouthPress|mouthLipsTogether)/;
+const SPEAK_MOUTH = 0.45;
+const SPEAK_EYES = 0.35;
+const REST_AFTER = 0.7;
+const HOLD = 2.5;
+const IDLE_SHARE = 0.35;
+const RELAX = 2.5;
+const NAMES = MHA_PROFILE.channelNames.map((n) => n.replace(/^CTRL_expressions_/, ''));
+const where = (test) => NAMES.map((n, i) => (test(n) ? i : -1)).filter((i) => i >= 0);
+const screen = (a, b) => a + b - a * b;
+const clamp01 = (v) => Math.min(1, Math.max(0, v));
+export class Expression {
+    constructor(mood = 'neutral') {
+        this.mouth = where((n) => MOUTH[n.replace(/[LR]$/, '')] !== undefined)
+            .map((i) => ({ i, amount: MOUTH[NAMES[i].replace(/[LR]$/, '')], slow: 0 }));
+        this.eyes = where((n) => EYES[n.replace(/[LR]$/, '')] !== undefined)
+            .map((i) => ({ i, amount: EYES[NAMES[i].replace(/[LR]$/, '')], cap: STREAM_EYE_CAP[NAMES[i].replace(/[LR]$/, '')] ?? 1 }));
+        this.rounding = where((n) => ROUNDING.test(n));
+        this.closure = where((n) => CLOSURE.test(n));
+        this.depress = where((n) => /^mouthCornerDepress[LR]$/.test(n));
+        this.brow = (name) => NAMES.indexOf(name);
+        this.browSlow = new Float32Array(NAMES.length);
+        this.warmMouth = 1;
+        this.warmEyes = 1;
+        this.quiet = Infinity;
+        this.t = 0;
+        this.mood = mood;
+        this.m = { ...MOODS[mood] };
+    }
+    /** Apply to `out` in place. `speaking`: the character's voice is playing. */
+    apply(out, dt, speaking) {
+        if (dt <= 0)
+            return;
+        this.t += dt;
+        this.quiet = speaking ? 0 : this.quiet + dt;
+        const atRest = this.quiet >= REST_AFTER;
+        const idle = this.quiet >= REST_AFTER + HOLD;
+        const restLevel = idle ? IDLE_SHARE : 1;
+        const ease = (v, to) => v + (to - v) * (1 - Math.exp(-dt / (idle && to < v ? RELAX : to < v ? 0.45 : 1.0)));
+        this.warmMouth = ease(this.warmMouth, atRest ? restLevel : SPEAK_MOUTH);
+        this.warmEyes = ease(this.warmEyes, atRest ? restLevel : SPEAK_EYES);
+        const km = 1 - Math.exp(-dt / 1.0);
+        const target = MOODS[this.mood] ?? MOODS.neutral;
+        for (const k of Object.keys(this.m))
+            this.m[k] += (target[k] - this.m[k]) * km;
+        // Never frozen: a slow drift of a few percent.
+        const drift = 1 + 0.05 * Math.sin(this.t * 0.83) + 0.03 * Math.sin(this.t * 0.37 + 1.3);
+        const peak = (list) => list.reduce((m, i) => Math.max(m, out[i]), 0);
+        const gate = Math.max(0, 1 - 0.9 * Math.min(1, peak(this.rounding) * 2) - 0.5 * Math.min(1, peak(this.closure) * 2));
+        const kSlow = 1 - Math.exp(-dt / 0.25);
+        for (const c of this.mouth) {
+            const v = out[c.i];
+            c.slow += (v - c.slow) * kSlow;
+            out[c.i] = clamp01(v - c.slow + screen(c.slow, c.amount * this.warmMouth * this.m.mouth * drift * gate));
+        }
+        for (const c of this.eyes)
+            out[c.i] = clamp01(screen(Math.min(out[c.i], c.cap), c.amount * this.warmEyes * this.m.eyes * drift));
+        // Brows: smoothed (~100 ms) and remapped, per side.
+        const kBrow = 1 - Math.exp(-dt / 0.1);
+        for (const side of ['L', 'R']) {
+            const inner = this.brow(`browRaiseIn${side}`), outer = this.brow(`browRaiseOuter${side}`), down = this.brow(`browDown${side}`);
+            for (const i of [inner, outer, down])
+                if (i >= 0)
+                    this.browSlow[i] += (out[i] - this.browSlow[i]) * kBrow;
+            const innerSlow = inner >= 0 ? this.browSlow[inner] : 0;
+            if (inner >= 0)
+                out[inner] = innerSlow;
+            if (outer >= 0)
+                out[outer] = clamp01(screen(Math.max(this.browSlow[outer], 0.8 * innerSlow), this.m.browOuter));
+            if (down >= 0)
+                out[down] = clamp01(screen(this.browSlow[down] * (innerSlow > 0.1 ? 0.5 : 1), this.m.browDown));
+        }
+        const pull = MOUTH.mouthCornerPull * this.warmMouth * this.m.mouth;
+        for (const i of this.depress)
+            out[i] = clamp01(out[i] - pull);
+    }
+}

package/dist/speech/lipsync.d.ts

@@ -16,6 +16,8 @@
 import type * as THREE from 'three';
 import type { BlendshapeQueue } from '@convai/web-sdk/core';
 import { type CorrectiveMap } from './correctiveMap.js';
+import type { VoiceClock } from './voiceClock.js';
+import { Expression, type Mood } from './expression.js';
 /** Tier-1 customization: the mouth knobs, per character. Defaults = pagoda-act's tuned values. */
 export interface MouthTuning {
     /** Hard cap on jawOpen; peak excursions read exaggerated on camera. */
@@ -50,8 +52,28 @@ export interface MouthTuning {
     teethLowerTuck?: number;
     /** Gain multipliers by MHA channel name, forwarded to the processor. */
     gainOverrides?: Record<string, number>;
-    /** Seconds of visual lead granted at speech start. */
+    /** Seconds of visual lead granted at speech start (wall-clock path only). */
     visualLeadSeconds?: number;
+    /**
+     * How far the mouth leads the voice, s, when it follows the voice's own
+     * clock. The anchor pairs the first audible sound with the first frame that
+     * opens the jaw, which comes ~150 ms into the syllable; the rest is the
+     * small natural lead of a mouth over its sound, plus the finishing's ~33 ms
+     * of smoothing. Default 0.2.
+     */
+    voiceLeadSeconds?: number;
+    /**
+     * Mouth finishing (bilabial closures, rest in the voice's breaks, stall
+     * cover, a soft knee on over-wide openings, light smoothing, range). See
+     * MouthFinish. Default `true`.
+     */
+    finish?: boolean;
+    /**
+     * The face's resting expression between and under speech (see Expression):
+     * a mood, or `false` to play the stream's face as sent. Change it live
+     * through `lipsync.expression.mood`. Default `'neutral'` (a light smile).
+     */
+    expression?: Mood | false;
     /**
      * Seconds without a fresh frame, while the bot still reads as speaking,
      * after which the mouth relaxes instead of holding its last shape: a stream
@@ -59,8 +81,9 @@ export interface MouthTuning {
      */
     staleReleaseSeconds?: number;
 }
-type Tuning = Required<Omit<MouthTuning, 'gainOverrides' | 'teethLowerTuck'>> & {
+type Tuning = Required<Omit<MouthTuning, 'gainOverrides' | 'teethLowerTuck' | 'expression'>> & {
     gainOverrides: Record<string, number>;
+    expression: Mood | false;
 };
 export declare class LipsyncSystem {
     readonly t: Tuning;
@@ -85,11 +108,54 @@ export declare class LipsyncSystem {
     correctiveMap: CorrectiveMap | null;
     private mapped;
     private unpinned;
+    /**
+     * The voice's own clock, when the received audio can be read. Set by
+     * createCharacter from the session; null keeps the wall-clock path.
+     */
+    voice: VoiceClock | null;
+    /** Frames consumed this turn, and the turn frame where speech starts. */
+    private turnFrame;
+    private anchor;
+    /** Frames waiting when the voice's packets stopped, or null while they flow. */
+    private holdWaiting;
+    /** The queue ran dry after the anchor: the next frames are a new start. */
+    private dry;
+    /** Since it ran dry: whether the voice went quiet, and how long frames have waited. */
+    private gapSeen;
+    private lateFor;
+    /**
+     * Where the stream's motion starts: the first frame that moves the mouth,
+     * any mouth channel away from its rest in the first frame, within the
+     * lead-in. Keyed on the jaw alone, a reply opening on rounded or closed
+     * lips ("Who knew the moon", "Peter") matched a second into the stream
+     * (63 and 80 frames measured), the whole reply ran that far early, and its
+     * last words had no frames left.
+     */
+    private leadIn;
+    private blend;
+    private readonly finisher;
+    /** The resting expression, or null when switched off. Set `.mood` to change it. */
+    readonly expression: Expression | null;
     private readonly ch;
     constructor(tuning?: MouthTuning, correctiveMap?: CorrectiveMap | null);
     /** Bind every morph-bearing mesh under root. Returns matched channel count. */
     bind(root: THREE.Object3D): number;
     private correct;
+    private wasSpeakingClock;
+    /**
+     * Consume the queue up to where the voice is, and return the stream at that
+     * exact time: the last whole frame blended toward the next by the fraction
+     * left over. Embody draws once per render tick, so at ~46 fps against a
+     * 60 fps stream whole frames stepped 1, 2 or 3 at a time, an uneven speed
+     * that read as jitter. Null until the voice is audible, or when nothing new
+     * is due.
+     */
+    private followVoice;
+    /** The last whole frame consumed on the voice clock, uncorrected. */
+    private rawHeld;
+    private zeros;
+    /** A rest frame in the stream's layout, for the finisher to add to. */
+    private zero;
     /** Tick each frame. Pass the queue only if this character owns the turn. */
     update(delta: number, q: BlendshapeQueue | undefined): void;
 }