@convai/web-sdk 0.2.4 → 0.3.0-beta.0

package/dist/lipsync-helpers/arkitPhonemeReference.js

@@ -0,0 +1,362 @@
+/**
+ * ARKit Blendshape Reference Values for Phonemes/Visemes
+ *
+ * This file provides reference values for ARKit's 52 standard facial blendshapes
+ * when forming different phonemes (speech sounds). These values are based on
+ * industry standards from systems like OVR LipSync, Oculus Audio, and ARKit face tracking.
+ *
+ * All blendshape values range from 0.0 (no activation) to 1.0 (full activation)
+ *
+ * ARKit Blendshapes: Indices 0-51
+ * Meta Human Extended: Indices 52-250
+ */
+/**
+ * Reference values for common phonemes
+ * Based on International Phonetic Alphabet (IPA) and Arpabet standards
+ */
+export const ARKIT_PHONEME_REFERENCE_VALUES = {
+    // ============================================
+    // SILENCE / NEUTRAL
+    // ============================================
+    sil: {
+        jawOpen: 0.0,
+        mouthClose: 1.0,
+        description: "Silence - mouth closed, neutral expression"
+    },
+    // ============================================
+    // VOWELS
+    // ============================================
+    aa: {
+        jawOpen: 0.7,
+        mouthFunnel: 0.0,
+        mouthPucker: 0.0,
+        tongueOut: 0.1,
+        description: "Open back vowel - 'ah' (father, hot)"
+    },
+    ae: {
+        jawOpen: 0.5,
+        mouthStretchLeft: 0.4,
+        mouthStretchRight: 0.4,
+        description: "Near-open front vowel - 'a' (cat, bat)"
+    },
+    E: {
+        jawOpen: 0.4,
+        mouthStretchLeft: 0.3,
+        mouthStretchRight: 0.3,
+        mouthSmileLeft: 0.2,
+        mouthSmileRight: 0.2,
+        description: "Open-mid front vowel - 'eh' (bed, get)"
+    },
+    I: {
+        jawOpen: 0.1,
+        mouthStretchLeft: 0.6,
+        mouthStretchRight: 0.6,
+        mouthSmileLeft: 0.5,
+        mouthSmileRight: 0.5,
+        mouthClose: 0.3,
+        description: "Close front vowel - 'ee' (see, feet)"
+    },
+    ih: {
+        jawOpen: 0.2,
+        mouthStretchLeft: 0.4,
+        mouthStretchRight: 0.4,
+        mouthSmileLeft: 0.3,
+        mouthSmileRight: 0.3,
+        description: "Near-close front vowel - 'i' (sit, bit)"
+    },
+    O: {
+        jawOpen: 0.5,
+        mouthFunnel: 0.6,
+        mouthPucker: 0.3,
+        description: "Close-mid back rounded vowel - 'oh' (go, boat)"
+    },
+    aw: {
+        jawOpen: 0.6,
+        mouthFunnel: 0.4,
+        mouthPucker: 0.2,
+        description: "Open-mid back rounded vowel - 'aw' (thought, caught)"
+    },
+    U: {
+        jawOpen: 0.2,
+        mouthFunnel: 0.8,
+        mouthPucker: 0.9,
+        description: "Close back rounded vowel - 'oo' (food, boot)"
+    },
+    uh: {
+        jawOpen: 0.25,
+        mouthFunnel: 0.5,
+        mouthPucker: 0.6,
+        description: "Near-close back rounded vowel - 'u' (book, foot)"
+    },
+    er: {
+        jawOpen: 0.35,
+        mouthFunnel: 0.3,
+        mouthPucker: 0.1,
+        description: "R-colored mid-central vowel - 'er' (her, bird)"
+    },
+    ah: {
+        jawOpen: 0.4,
+        mouthFunnel: 0.1,
+        description: "Open-mid back vowel - 'uh' (but, cup)"
+    },
+    // ============================================
+    // DIPHTHONGS
+    // ============================================
+    ow: {
+        jawOpen: 0.6,
+        mouthFunnel: 0.3,
+        mouthPucker: 0.2,
+        description: "Diphthong - 'ow' (cow, house)"
+    },
+    ay: {
+        jawOpen: 0.5,
+        mouthStretchLeft: 0.3,
+        mouthStretchRight: 0.3,
+        description: "Diphthong - 'ai' (eye, my)"
+    },
+    oy: {
+        jawOpen: 0.5,
+        mouthFunnel: 0.4,
+        mouthPucker: 0.3,
+        description: "Diphthong - 'oy' (boy, coin)"
+    },
+    // ============================================
+    // CONSONANTS - BILABIALS (both lips)
+    // ============================================
+    PP: {
+        jawOpen: 0.0,
+        mouthClose: 1.0,
+        mouthPressLeft: 0.5,
+        mouthPressRight: 0.5,
+        description: "Bilabial stops/nasal - 'p', 'b', 'm' (pat, bat, mat)"
+    },
+    // ============================================
+    // CONSONANTS - LABIODENTAL (teeth on lip)
+    // ============================================
+    FF: {
+        jawOpen: 0.15,
+        mouthRollLower: 0.6,
+        mouthUpperUpLeft: 0.3,
+        mouthUpperUpRight: 0.3,
+        description: "Labiodental fricatives - 'f', 'v' (fat, vat)"
+    },
+    // ============================================
+    // CONSONANTS - DENTAL/INTERDENTAL
+    // ============================================
+    TH: {
+        jawOpen: 0.2,
+        tongueOut: 0.4,
+        mouthUpperUpLeft: 0.2,
+        mouthUpperUpRight: 0.2,
+        mouthRollLower: 0.2,
+        description: "Dental fricatives - 'th' (think, this)"
+    },
+    // ============================================
+    // CONSONANTS - ALVEOLAR (tongue to ridge)
+    // ============================================
+    DD: {
+        jawOpen: 0.3,
+        mouthClose: 0.2,
+        description: "Alveolar stops - 't', 'd' (tap, dap)"
+    },
+    SS: {
+        jawOpen: 0.15,
+        mouthStretchLeft: 0.4,
+        mouthStretchRight: 0.4,
+        mouthClose: 0.4,
+        description: "Alveolar sibilants - 's', 'z' (sap, zap)"
+    },
+    nn: {
+        jawOpen: 0.2,
+        mouthClose: 0.3,
+        description: "Alveolar nasal - 'n' (nap)"
+    },
+    l: {
+        jawOpen: 0.25,
+        tongueOut: 0.2,
+        description: "Alveolar lateral approximant - 'l' (lap)"
+    },
+    // ============================================
+    // CONSONANTS - POSTALVEOLAR (behind ridge)
+    // ============================================
+    CH: {
+        jawOpen: 0.2,
+        mouthFunnel: 0.3,
+        mouthPucker: 0.2,
+        description: "Postalveolar affricates - 'ch', 'j' (church, judge)"
+    },
+    sh: {
+        jawOpen: 0.2,
+        mouthFunnel: 0.4,
+        mouthPucker: 0.3,
+        description: "Postalveolar fricatives - 'sh', 'zh' (shoe, measure)"
+    },
+    // ============================================
+    // CONSONANTS - RETROFLEX
+    // ============================================
+    RR: {
+        jawOpen: 0.3,
+        mouthFunnel: 0.2,
+        mouthPucker: 0.15,
+        tongueOut: 0.1,
+        description: "Alveolar approximant - 'r' (red)"
+    },
+    // ============================================
+    // CONSONANTS - PALATAL
+    // ============================================
+    y: {
+        jawOpen: 0.2,
+        mouthStretchLeft: 0.35,
+        mouthStretchRight: 0.35,
+        mouthSmileLeft: 0.2,
+        mouthSmileRight: 0.2,
+        description: "Palatal approximant - 'y' (yes)"
+    },
+    // ============================================
+    // CONSONANTS - VELAR (back of tongue)
+    // ============================================
+    kk: {
+        jawOpen: 0.35,
+        description: "Velar stops/nasal - 'k', 'g', 'ng' (kite, go, sing)"
+    },
+    // ============================================
+    // CONSONANTS - GLOTTAL
+    // ============================================
+    hh: {
+        jawOpen: 0.3,
+        description: "Glottal fricative - 'h' (hat)"
+    },
+    // ============================================
+    // CONSONANTS - LABIO-VELAR
+    // ============================================
+    w: {
+        jawOpen: 0.15,
+        mouthPucker: 0.8,
+        mouthFunnel: 0.6,
+        description: "Labio-velar approximant - 'w' (wet)"
+    },
+};
+/**
+ * ARKit Blendshape Indices (0-51)
+ * These are Apple's standard 52 facial blendshapes
+ */
+export const ARKIT_BLENDSHAPE_INDICES = {
+    browDownLeft: 0,
+    browDownRight: 1,
+    browInnerUp: 2,
+    browOuterUpLeft: 3,
+    browOuterUpRight: 4,
+    cheekPuff: 5,
+    cheekSquintLeft: 6,
+    cheekSquintRight: 7,
+    eyeBlinkLeft: 8,
+    eyeBlinkRight: 9,
+    eyeLookDownLeft: 10,
+    eyeLookDownRight: 11,
+    eyeLookInLeft: 12,
+    eyeLookInRight: 13,
+    eyeLookOutLeft: 14,
+    eyeLookOutRight: 15,
+    eyeLookUpLeft: 16,
+    eyeLookUpRight: 17,
+    eyeSquintLeft: 18,
+    eyeSquintRight: 19,
+    eyeWideLeft: 20,
+    eyeWideRight: 21,
+    jawForward: 22,
+    jawLeft: 23,
+    jawOpen: 24, // 🔑 KEY for mouth opening
+    jawRight: 25,
+    mouthClose: 26, // 🔑 KEY for mouth closing
+    mouthDimpleLeft: 27,
+    mouthDimpleRight: 28,
+    mouthFrownLeft: 29,
+    mouthFrownRight: 30,
+    mouthFunnel: 31, // 🔑 KEY for "O" and "oo" sounds
+    mouthLeft: 32,
+    mouthLowerDownLeft: 33,
+    mouthLowerDownRight: 34,
+    mouthPressLeft: 35,
+    mouthPressRight: 36,
+    mouthPucker: 37, // 🔑 KEY for "U" and "w" sounds
+    mouthRight: 38,
+    mouthRollLower: 39,
+    mouthRollUpper: 40,
+    mouthShrugLower: 41,
+    mouthShrugUpper: 42,
+    mouthSmileLeft: 43, // 🔑 KEY for "ee" sounds
+    mouthSmileRight: 44, // 🔑 KEY for "ee" sounds
+    mouthStretchLeft: 45, // 🔑 KEY for wide mouth shapes
+    mouthStretchRight: 46, // 🔑 KEY for wide mouth shapes
+    mouthUpperUpLeft: 47,
+    mouthUpperUpRight: 48,
+    noseSneerLeft: 49,
+    noseSneerRight: 50,
+    tongueOut: 51 // 🔑 KEY for "th" and "l" sounds
+};
+/**
+ * Generate a complete 251-length blendshape array for a specific phoneme
+ * @param phoneme - The phoneme key from ARKIT_PHONEME_REFERENCE_VALUES
+ * @returns Array of 251 blendshape values
+ */
+export function generatePhonemeBlendshapes(phoneme) {
+    const blendshapes = new Array(251).fill(0);
+    const values = ARKIT_PHONEME_REFERENCE_VALUES[phoneme];
+    // Map phoneme values to ARKit indices (0-51)
+    for (const [key, value] of Object.entries(values)) {
+        if (key !== 'description' && key in ARKIT_BLENDSHAPE_INDICES) {
+            const index = ARKIT_BLENDSHAPE_INDICES[key];
+            blendshapes[index] = value;
+        }
+    }
+    return blendshapes;
+}
+/**
+ * Pre-generated sample blendshapes for testing and visualization
+ * Use these to test your visualization system
+ */
+export const SAMPLE_PHONEME_TESTS = {
+    'Silence': generatePhonemeBlendshapes('sil'),
+    'A (ah - father)': generatePhonemeBlendshapes('aa'),
+    'E (eh - bed)': generatePhonemeBlendshapes('E'),
+    'I (ee - see)': generatePhonemeBlendshapes('I'),
+    'O (oh - go)': generatePhonemeBlendshapes('O'),
+    'U (oo - food)': generatePhonemeBlendshapes('U'),
+    'P/B/M': generatePhonemeBlendshapes('PP'),
+    'F/V': generatePhonemeBlendshapes('FF'),
+    'TH (think)': generatePhonemeBlendshapes('TH'),
+    'S/Z': generatePhonemeBlendshapes('SS'),
+    'SH (shoe)': generatePhonemeBlendshapes('sh'),
+    'CH (church)': generatePhonemeBlendshapes('CH'),
+    'W (wet)': generatePhonemeBlendshapes('w'),
+    'R (red)': generatePhonemeBlendshapes('RR'),
+    'L (lap)': generatePhonemeBlendshapes('l'),
+    'K/G': generatePhonemeBlendshapes('kk'),
+};
+/**
+ * Get a formatted string showing active blendshapes for a phoneme
+ * Useful for debugging and documentation
+ */
+export function getPhonemeDescription(phoneme) {
+    const data = ARKIT_PHONEME_REFERENCE_VALUES[phoneme];
+    const lines = [data.description, ''];
+    for (const [key, value] of Object.entries(data)) {
+        if (key !== 'description') {
+            lines.push(`  ${key}: ${value}`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Quick reference guide for key blendshapes
+ */
+export const BLENDSHAPE_QUICK_GUIDE = {
+    'Open mouth': ['jawOpen'],
+    'Close mouth': ['mouthClose'],
+    'Round lips (O, oo)': ['mouthFunnel', 'mouthPucker'],
+    'Smile (ee)': ['mouthSmileLeft', 'mouthSmileRight', 'mouthStretchLeft', 'mouthStretchRight'],
+    'Lips pressed (p, b, m)': ['mouthPressLeft', 'mouthPressRight', 'mouthClose'],
+    'Teeth on lip (f, v)': ['mouthRollLower', 'mouthUpperUpLeft', 'mouthUpperUpRight'],
+    'Tongue visible (th, l)': ['tongueOut'],
+};
+//# sourceMappingURL=arkitPhonemeReference.js.map

package/dist/lipsync-helpers/arkitPhonemeReference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arkitPhonemeReference.js","sourceRoot":"","sources":["../../src/lipsync-helpers/arkitPhonemeReference.ts"],"names":[],"mappings":"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"}

package/dist/lipsync-helpers/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Lipsync Helpers
+ * Utilities for processing and mapping lipsync/blendshape data
+ */
+export { ARKIT_ORDER_61, STANDARD_ARKIT_ORDER, convertOrder61ToStandard, mapOrder61ToNames, getBlendshapeValueFromOrder61, getHeadRotation, getEyeRotations, getLipSyncValuesFromOrder61, getActiveBlendshapesFromOrder61, formatOrder61ForLogging, } from "./arkitOrder61";
+export { ARKIT_BLENDSHAPE_NAMES, ARKIT_EXTENDED_NAMES, mapARKitBlendshapesToNames, getActiveARKitBlendshapes, getARKitBlendshapeValue, formatARKitBlendshapesForLogging, KEY_LIPSYNC_BLENDSHAPES, getLipSyncBlendshapes, } from "./arkitBlendshapeHelpers";
+export { ARKIT_PHONEME_REFERENCE_VALUES, ARKIT_BLENDSHAPE_INDICES, SAMPLE_PHONEME_TESTS, BLENDSHAPE_QUICK_GUIDE, generatePhonemeBlendshapes, getPhonemeDescription, type PhonemeBlendshapes, } from "./arkitPhonemeReference";
+export { METAHUMAN_ORDER_251, METAHUMAN_CATEGORIES, KEY_METAHUMAN_LIPSYNC, getMetaHumanBlendshapeName, getMetaHumanBlendshapeIndex, getMetaHumanBlendshapesByCategory, formatMetaHumanBlendshapesForLogging, } from "./metahumanOrder251";
+export { NEUROSYNC_BLENDSHAPE_NAMES, mapBlendshapesToNames, formatBlendshapesForLogging, getTopBlendshapes, } from "./neurosyncBlendshapeMapper";
+//# sourceMappingURL=index.d.ts.map

package/dist/lipsync-helpers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lipsync-helpers/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,wBAAwB,EACxB,iBAAiB,EACjB,6BAA6B,EAC7B,eAAe,EACf,eAAe,EACf,2BAA2B,EAC3B,+BAA+B,EAC/B,uBAAuB,GACxB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,EACzB,uBAAuB,EACvB,gCAAgC,EAChC,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EACL,8BAA8B,EAC9B,wBAAwB,EACxB,oBAAoB,EACpB,sBAAsB,EACtB,0BAA0B,EAC1B,qBAAqB,EACrB,KAAK,kBAAkB,GACxB,MAAM,yBAAyB,CAAC;AAOjC,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,0BAA0B,EAC1B,2BAA2B,EAC3B,iCAAiC,EACjC,oCAAoC,GACrC,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,0BAA0B,EAC1B,qBAAqB,EACrB,2BAA2B,EAC3B,iBAAiB,GAClB,MAAM,6BAA6B,CAAC"}

package/dist/lipsync-helpers/index.js

@@ -0,0 +1,21 @@
+/**
+ * Lipsync Helpers
+ * Utilities for processing and mapping lipsync/blendshape data
+ */
+// ============================================================================
+// ARKIT FORMAT (52 blendshapes + 9 rotation values = 61 total)
+// ============================================================================
+// ARKit 61-Element Custom Order (RECOMMENDED - for direct server data)
+export { ARKIT_ORDER_61, STANDARD_ARKIT_ORDER, convertOrder61ToStandard, mapOrder61ToNames, getBlendshapeValueFromOrder61, getHeadRotation, getEyeRotations, getLipSyncValuesFromOrder61, getActiveBlendshapesFromOrder61, formatOrder61ForLogging, } from "./arkitOrder61";
+// ARKit Blendshape Helpers (for standard ARKit 52-element format)
+export { ARKIT_BLENDSHAPE_NAMES, ARKIT_EXTENDED_NAMES, mapARKitBlendshapesToNames, getActiveARKitBlendshapes, getARKitBlendshapeValue, formatARKitBlendshapesForLogging, KEY_LIPSYNC_BLENDSHAPES, getLipSyncBlendshapes, } from "./arkitBlendshapeHelpers";
+// ARKit Phoneme Reference Values
+export { ARKIT_PHONEME_REFERENCE_VALUES, ARKIT_BLENDSHAPE_INDICES, SAMPLE_PHONEME_TESTS, BLENDSHAPE_QUICK_GUIDE, generatePhonemeBlendshapes, getPhonemeDescription, } from "./arkitPhonemeReference";
+// ============================================================================
+// METAHUMAN FORMAT (251 CTRL_expressions_* blendshapes)
+// ============================================================================
+// MetaHuman 251-Element Order (for MetaHuman Control Rig data)
+export { METAHUMAN_ORDER_251, METAHUMAN_CATEGORIES, KEY_METAHUMAN_LIPSYNC, getMetaHumanBlendshapeName, getMetaHumanBlendshapeIndex, getMetaHumanBlendshapesByCategory, formatMetaHumanBlendshapesForLogging, } from "./metahumanOrder251";
+// Neurosync Blendshape Mapper (Legacy - for compatibility)
+export { NEUROSYNC_BLENDSHAPE_NAMES, mapBlendshapesToNames, formatBlendshapesForLogging, getTopBlendshapes, } from "./neurosyncBlendshapeMapper";
+//# sourceMappingURL=index.js.map

package/dist/lipsync-helpers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/lipsync-helpers/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,+EAA+E;AAC/E,+DAA+D;AAC/D,+EAA+E;AAE/E,uEAAuE;AACvE,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,wBAAwB,EACxB,iBAAiB,EACjB,6BAA6B,EAC7B,eAAe,EACf,eAAe,EACf,2BAA2B,EAC3B,+BAA+B,EAC/B,uBAAuB,GACxB,MAAM,gBAAgB,CAAC;AAExB,kEAAkE;AAClE,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,EACzB,uBAAuB,EACvB,gCAAgC,EAChC,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,0BAA0B,CAAC;AAElC,iCAAiC;AACjC,OAAO,EACL,8BAA8B,EAC9B,wBAAwB,EACxB,oBAAoB,EACpB,sBAAsB,EACtB,0BAA0B,EAC1B,qBAAqB,GAEtB,MAAM,yBAAyB,CAAC;AAEjC,+EAA+E;AAC/E,wDAAwD;AACxD,+EAA+E;AAE/E,+DAA+D;AAC/D,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,0BAA0B,EAC1B,2BAA2B,EAC3B,iCAAiC,EACjC,oCAAoC,GACrC,MAAM,qBAAqB,CAAC;AAE7B,2DAA2D;AAC3D,OAAO,EACL,0BAA0B,EAC1B,qBAAqB,EACrB,2BAA2B,EAC3B,iBAAiB,GAClB,MAAM,6BAA6B,CAAC"}

package/dist/lipsync-helpers/metahumanOrder251.d.ts

@@ -0,0 +1,115 @@
+/**
+ * MetaHuman 251-Element Blendshape Order
+ *
+ * This is the standard format sent by Convai's MetaHuman blendshape provider.
+ * The server sends 251 CTRL_expressions_* values in this specific order.
+ *
+ * Based on Unreal Engine MetaHuman Control Rig specification.
+ *
+ * Source: UConvaiNeuroSyncComponent::CtrlExpressionNames[251]
+ */
+/**
+ * MetaHuman 251-element blendshape names (CTRL_expressions_*)
+ * This is the order in which blendshapes are received from the server
+ */
+export declare const METAHUMAN_ORDER_251: readonly string[];
+/**
+ * Category breakdown for MetaHuman blendshapes
+ */
+export declare const METAHUMAN_CATEGORIES: {
+    brows: {
+        start: number;
+        end: number;
+        count: number;
+    };
+    ears: {
+        start: number;
+        end: number;
+        count: number;
+    };
+    eyes: {
+        start: number;
+        end: number;
+        count: number;
+    };
+    eyelashes: {
+        start: number;
+        end: number;
+        count: number;
+    };
+    jaw: {
+        start: number;
+        end: number;
+        count: number;
+    };
+    mouth: {
+        start: number;
+        end: number;
+        count: number;
+    };
+    neck: {
+        start: number;
+        end: number;
+        count: number;
+    };
+    nose: {
+        start: number;
+        end: number;
+        count: number;
+    };
+    teeth: {
+        start: number;
+        end: number;
+        count: number;
+    };
+    tongue: {
+        start: number;
+        end: number;
+        count: number;
+    };
+};
+/**
+ * Key blendshapes for lip-sync (most important for speech animation)
+ */
+export declare const KEY_METAHUMAN_LIPSYNC: {
+    EYE_BLINK_L: number;
+    EYE_BLINK_R: number;
+    JAW_FORWARD: number;
+    JAW_LEFT: number;
+    JAW_OPEN: number;
+    JAW_RIGHT: number;
+    MOUTH_FUNNEL_DL: number;
+    MOUTH_FUNNEL_DR: number;
+    MOUTH_FUNNEL_UL: number;
+    MOUTH_FUNNEL_UR: number;
+    MOUTH_LEFT: number;
+    MOUTH_RIGHT: number;
+    MOUTH_STRETCH_L: number;
+    MOUTH_STRETCH_R: number;
+    MOUTH_LIPS_TOGETHER_DL: number;
+    MOUTH_LIPS_TOGETHER_DR: number;
+    MOUTH_LIPS_TOGETHER_UL: number;
+    MOUTH_LIPS_TOGETHER_UR: number;
+    TONGUE_OUT: number;
+};
+/**
+ * Get blendshape name by index
+ */
+export declare function getMetaHumanBlendshapeName(index: number): string | undefined;
+/**
+ * Get blendshape index by name
+ */
+export declare function getMetaHumanBlendshapeIndex(name: string): number;
+/**
+ * Get blendshapes by category
+ */
+export declare function getMetaHumanBlendshapesByCategory(category: keyof typeof METAHUMAN_CATEGORIES): readonly string[];
+/**
+ * Format MetaHuman blendshapes for logging
+ */
+export declare function formatMetaHumanBlendshapesForLogging(values: number[] | Float32Array, threshold?: number, maxEntries?: number): {
+    active: Record<string, number>;
+    total: number;
+    activeCount: number;
+};
+//# sourceMappingURL=metahumanOrder251.d.ts.map

package/dist/lipsync-helpers/metahumanOrder251.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metahumanOrder251.d.ts","sourceRoot":"","sources":["../../src/lipsync-helpers/metahumanOrder251.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAmSvC,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmDhC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;CAiCjC,CAAC;AAEF;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE5E;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED;;GAEG;AACH,wBAAgB,iCAAiC,CAAC,QAAQ,EAAE,MAAM,OAAO,oBAAoB,GAAG,SAAS,MAAM,EAAE,CAGhH;AAED;;GAEG;AACH,wBAAgB,oCAAoC,CAClD,MAAM,EAAE,MAAM,EAAE,GAAG,YAAY,EAC/B,SAAS,GAAE,MAAa,EACxB,UAAU,GAAE,MAAW,GACtB;IACD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB,CA4BA"}