@convai/web-sdk 0.3.1-beta.3 → 0.3.2-beta.1

package/dist/lipsync-helpers/index.cjs

@@ -1,1195 +0,0 @@
-'use strict';
-
-/**
- * ARKit 61-Element Custom Order Mapper
- * Maps the custom 61-element ARKit blendshape array to standard ARKit indices
- *
- * This ordering includes:
- * - 52 standard ARKit facial blendshapes (in custom order)
- * - 9 additional values for head and eye rotations
- */
-/**
- * Custom ARKit 61-element ordering
- * This is the order in which blendshapes are received from the server
- */
-const ARKIT_ORDER_61 = [
-    "EyeBlinkLeft", // 0
-    "EyeLookDownLeft", // 1
-    "EyeLookInLeft", // 2
-    "EyeLookOutLeft", // 3
-    "EyeLookUpLeft", // 4
-    "EyeSquintLeft", // 5
-    "EyeWideLeft", // 6
-    "EyeBlinkRight", // 7
-    "EyeLookDownRight", // 8
-    "EyeLookInRight", // 9
-    "EyeLookOutRight", // 10
-    "EyeLookUpRight", // 11
-    "EyeSquintRight", // 12
-    "EyeWideRight", // 13
-    "JawForward", // 14
-    "JawRight", // 15
-    "JawLeft", // 16
-    "JawOpen", // 17 🔑 KEY for mouth opening
-    "MouthClose", // 18 🔑 KEY for mouth closing
-    "MouthFunnel", // 19 🔑 KEY for "O" sounds
-    "MouthPucker", // 20 🔑 KEY for "U" sounds
-    "MouthRight", // 21
-    "MouthLeft", // 22
-    "MouthSmileLeft", // 23 🔑 KEY for "ee" sounds
-    "MouthSmileRight", // 24 🔑 KEY for "ee" sounds
-    "MouthFrownLeft", // 25
-    "MouthFrownRight", // 26
-    "MouthDimpleLeft", // 27
-    "MouthDimpleRight", // 28
-    "MouthStretchLeft", // 29 🔑 KEY for wide mouth
-    "MouthStretchRight", // 30 🔑 KEY for wide mouth
-    "MouthRollLower", // 31
-    "MouthRollUpper", // 32
-    "MouthShrugLower", // 33
-    "MouthShrugUpper", // 34
-    "MouthPressLeft", // 35
-    "MouthPressRight", // 36
-    "MouthLowerDownLeft", // 37
-    "MouthLowerDownRight", // 38
-    "MouthUpperUpLeft", // 39
-    "MouthUpperUpRight", // 40
-    "BrowDownLeft", // 41
-    "BrowDownRight", // 42
-    "BrowInnerUp", // 43
-    "BrowOuterUpLeft", // 44
-    "BrowOuterUpRight", // 45
-    "CheekPuff", // 46
-    "CheekSquintLeft", // 47
-    "CheekSquintRight", // 48
-    "NoseSneerLeft", // 49
-    "NoseSneerRight", // 50
-    "TongueOut", // 51 🔑 KEY for "th" sounds
-    "HeadYaw", // 52 - Head rotation left/right
-    "HeadPitch", // 53 - Head rotation up/down
-    "HeadRoll", // 54 - Head rotation tilt
-    "LeftEyeYaw", // 55 - Left eye rotation left/right
-    "LeftEyePitch", // 56 - Left eye rotation up/down
-    "LeftEyeRoll", // 57 - Left eye rotation roll
-    "RightEyeYaw", // 58 - Right eye rotation left/right
-    "RightEyePitch", // 59 - Right eye rotation up/down
-    "RightEyeRoll", // 60 - Right eye rotation roll
-];
-/**
- * Standard ARKit blendshape order (52 elements)
- * This is Apple's official ordering
- */
-const STANDARD_ARKIT_ORDER = [
-    "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
-    "JawRight", // 25
-    "MouthClose", // 26
-    "MouthDimpleLeft", // 27
-    "MouthDimpleRight", // 28
-    "MouthFrownLeft", // 29
-    "MouthFrownRight", // 30
-    "MouthFunnel", // 31
-    "MouthLeft", // 32
-    "MouthLowerDownLeft", // 33
-    "MouthLowerDownRight", // 34
-    "MouthPressLeft", // 35
-    "MouthPressRight", // 36
-    "MouthPucker", // 37
-    "MouthRight", // 38
-    "MouthRollLower", // 39
-    "MouthRollUpper", // 40
-    "MouthShrugLower", // 41
-    "MouthShrugUpper", // 42
-    "MouthSmileLeft", // 43
-    "MouthSmileRight", // 44
-    "MouthStretchLeft", // 45
-    "MouthStretchRight", // 46
-    "MouthUpperUpLeft", // 47
-    "MouthUpperUpRight", // 48
-    "NoseSneerLeft", // 49
-    "NoseSneerRight", // 50
-    "TongueOut", // 51
-];
-/**
- * Mapping from custom 61-order indices to standard ARKit indices
- * Maps ARKIT_ORDER_61[i] -> STANDARD_ARKIT_ORDER[j]
- */
-const ORDER_61_TO_STANDARD_MAP = new Map();
-// Build the mapping at module initialization
-for (let i = 0; i < ARKIT_ORDER_61.length; i++) {
-    const name = ARKIT_ORDER_61[i];
-    // Only map the first 52 (standard ARKit blendshapes)
-    if (i < 52) {
-        const standardIndex = STANDARD_ARKIT_ORDER.indexOf(name);
-        if (standardIndex !== -1) {
-            ORDER_61_TO_STANDARD_MAP.set(i, standardIndex);
-        }
-    }
-}
-/**
- * Convert 61-element custom order array to standard 52-element ARKit array
- * @param values61 - 61-element array in custom order
- * @returns 52-element array in standard ARKit order
- */
-function convertOrder61ToStandard(values61) {
-    const standardArray = new Array(52).fill(0);
-    for (let i = 0; i < Math.min(52, values61.length); i++) {
-        const standardIndex = ORDER_61_TO_STANDARD_MAP.get(i);
-        if (standardIndex !== undefined) {
-            standardArray[standardIndex] = values61[i];
-        }
-    }
-    return standardArray;
-}
-/**
- * Map 61-element array to named object (all 61 values)
- * @param values61 - 61-element array in custom order
- * @returns Object with blendshape/rotation names as keys
- */
-function mapOrder61ToNames(values61) {
-    const mapped = {};
-    for (let i = 0; i < Math.min(values61.length, ARKIT_ORDER_61.length); i++) {
-        // Convert to camelCase (lowercase first letter)
-        const name = ARKIT_ORDER_61[i];
-        const camelCaseName = name.charAt(0).toLowerCase() + name.slice(1);
-        mapped[camelCaseName] = values61[i];
-    }
-    return mapped;
-}
-/**
- * Get specific blendshape value by name from 61-element array
- * @param values61 - 61-element array in custom order
- * @param name - Name of the blendshape (case-insensitive)
- * @returns The value, or 0 if not found
- */
-function getBlendshapeValueFromOrder61(values61, name) {
-    const upperName = name.charAt(0).toUpperCase() + name.slice(1);
-    const index = ARKIT_ORDER_61.indexOf(upperName);
-    if (index !== -1 && index < values61.length) {
-        return values61[index];
-    }
-    return 0;
-}
-/**
- * Extract head rotation values from 61-element array
- * @param values61 - 61-element array in custom order
- * @returns Object with head rotation values (yaw, pitch, roll)
- */
-function getHeadRotation(values61) {
-    return {
-        yaw: values61[52] || 0,
-        pitch: values61[53] || 0,
-        roll: values61[54] || 0,
-    };
-}
-/**
- * Extract eye rotation values from 61-element array
- * @param values61 - 61-element array in custom order
- * @returns Object with left and right eye rotation values
- */
-function getEyeRotations(values61) {
-    return {
-        left: {
-            yaw: values61[55] || 0,
-            pitch: values61[56] || 0,
-            roll: values61[57] || 0,
-        },
-        right: {
-            yaw: values61[58] || 0,
-            pitch: values61[59] || 0,
-            roll: values61[60] || 0,
-        },
-    };
-}
-/**
- * Get key lip-sync blendshapes from 61-element array
- * These are the most important values for facial animation
- */
-function getLipSyncValuesFromOrder61(values61) {
-    return {
-        jawOpen: values61[17] || 0,
-        mouthClose: values61[18] || 0,
-        mouthFunnel: values61[19] || 0,
-        mouthPucker: values61[20] || 0,
-        mouthSmileLeft: values61[23] || 0,
-        mouthSmileRight: values61[24] || 0,
-        mouthStretchLeft: values61[29] || 0,
-        mouthStretchRight: values61[30] || 0,
-        mouthRollLower: values61[31] || 0,
-        mouthRollUpper: values61[32] || 0,
-        tongueOut: values61[51] || 0,
-    };
-}
-/**
- * Get active blendshapes from 61-element array (above threshold)
- * @param values61 - 61-element array in custom order
- * @param threshold - Minimum value to consider "active" (default: 0.01)
- * @returns Sorted array of active blendshapes
- */
-function getActiveBlendshapesFromOrder61(values61, threshold = 0.01) {
-    const active = [];
-    for (let i = 0; i < Math.min(values61.length, ARKIT_ORDER_61.length); i++) {
-        if (Math.abs(values61[i]) > threshold) {
-            const name = ARKIT_ORDER_61[i];
-            const camelCaseName = name.charAt(0).toLowerCase() + name.slice(1);
-            active.push({
-                name: camelCaseName,
-                value: values61[i],
-                index: i,
-            });
-        }
-    }
-    // Sort by absolute value (descending)
-    return active.sort((a, b) => Math.abs(b.value) - Math.abs(a.value));
-}
-/**
- * Format 61-element array for logging
- * @param values61 - 61-element array in custom order
- * @param threshold - Only show values above this (default: 0.01)
- * @param maxEntries - Maximum entries to show (default: 20)
- */
-function formatOrder61ForLogging(values61, threshold = 0.01, maxEntries = 20) {
-    const active = getActiveBlendshapesFromOrder61(values61, threshold)
-        .slice(0, maxEntries)
-        .reduce((acc, item) => {
-        acc[item.name] = Number(item.value.toFixed(4));
-        return acc;
-    }, {});
-    return {
-        active,
-        total: values61.length,
-        activeCount: Object.keys(active).length,
-        headRotation: getHeadRotation(values61),
-        eyeRotations: getEyeRotations(values61),
-    };
-}
-
-/**
- * ARKit Blendshape Helpers
- * Utilities for working with ARKit blendshape arrays (52-60 elements)
- *
- * ARKit Standard: 52 blendshapes (indices 0-51)
- * ARKit Extended: Up to 60 blendshapes with additional facial features
- */
-/**
- * ARKit Standard Blendshape Names (indices 0-51)
- */
-const ARKIT_BLENDSHAPE_NAMES = [
-    "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" sounds
-    "mouthLeft", // 32
-    "mouthLowerDownLeft", // 33
-    "mouthLowerDownRight", // 34
-    "mouthPressLeft", // 35
-    "mouthPressRight", // 36
-    "mouthPucker", // 37 🔑 KEY for "U" 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
-    "mouthStretchRight", // 46 🔑 KEY for wide mouth
-    "mouthUpperUpLeft", // 47
-    "mouthUpperUpRight", // 48
-    "noseSneerLeft", // 49
-    "noseSneerRight", // 50
-    "tongueOut", // 51 🔑 KEY for "th" sounds
-];
-/**
- * Extended blendshapes (indices 52-59) - if provided
- * These are optional extensions beyond standard ARKit
- */
-const ARKIT_EXTENDED_NAMES = [
-    "eyeDilation", // 52 - Pupil dilation
-    "eyeConstriction", // 53 - Pupil constriction
-    "mouthShrug", // 54 - Combined mouth shrug
-    "lipSuckUpper", // 55 - Upper lip suck
-    "lipSuckLower", // 56 - Lower lip suck
-    "lipFunnel", // 57 - Lip funnel position
-    "lipPress", // 58 - Lip press together
-    "reserved", // 59 - Reserved for future use
-];
-/**
- * Map ARKit blendshape array to named object (ARKit standard only: 0-51)
- * @param values - Array of blendshape values (length 52-60)
- * @returns Object with blendshape names as keys
- */
-function mapARKitBlendshapesToNames(values) {
-    const mapped = {};
-    // Map standard ARKit blendshapes (0-51)
-    for (let i = 0; i < Math.min(values.length, ARKIT_BLENDSHAPE_NAMES.length); i++) {
-        mapped[ARKIT_BLENDSHAPE_NAMES[i]] = values[i];
-    }
-    // Map extended blendshapes if available (52+)
-    if (values.length > 52) {
-        const extendedStart = 52;
-        for (let i = 0; i < Math.min(values.length - extendedStart, ARKIT_EXTENDED_NAMES.length); i++) {
-            mapped[ARKIT_EXTENDED_NAMES[i]] = values[extendedStart + i];
-        }
-    }
-    return mapped;
-}
-/**
- * Get only active blendshapes (above threshold)
- * @param values - Array of blendshape values
- * @param threshold - Minimum value to consider "active" (default: 0.01)
- * @returns Sorted array of active blendshapes
- */
-function getActiveARKitBlendshapes(values, threshold = 0.01) {
-    const active = [];
-    // Check standard ARKit blendshapes
-    for (let i = 0; i < Math.min(values.length, ARKIT_BLENDSHAPE_NAMES.length); i++) {
-        if (Math.abs(values[i]) > threshold) {
-            active.push({
-                name: ARKIT_BLENDSHAPE_NAMES[i],
-                value: values[i],
-                index: i,
-            });
-        }
-    }
-    // Check extended blendshapes
-    if (values.length > 52) {
-        for (let i = 52; i < Math.min(values.length, 52 + ARKIT_EXTENDED_NAMES.length); i++) {
-            if (Math.abs(values[i]) > threshold) {
-                active.push({
-                    name: ARKIT_EXTENDED_NAMES[i - 52],
-                    value: values[i],
-                    index: i,
-                });
-            }
-        }
-    }
-    // Sort by absolute value (descending)
-    return active.sort((a, b) => Math.abs(b.value) - Math.abs(a.value));
-}
-/**
- * Get specific blendshape value by name
- * @param values - Array of blendshape values
- * @param name - Name of the blendshape
- * @returns The value, or 0 if not found
- */
-function getARKitBlendshapeValue(values, name) {
-    const index = ARKIT_BLENDSHAPE_NAMES.indexOf(name);
-    if (index !== -1 && index < values.length) {
-        return values[index];
-    }
-    const extendedIndex = ARKIT_EXTENDED_NAMES.indexOf(name);
-    if (extendedIndex !== -1) {
-        const actualIndex = 52 + extendedIndex;
-        if (actualIndex < values.length) {
-            return values[actualIndex];
-        }
-    }
-    return 0;
-}
-/**
- * Format ARKit blendshapes for logging
- * @param values - Array of blendshape values
- * @param threshold - Only show values above this (default: 0.01)
- * @param maxEntries - Maximum entries to show (default: 20)
- */
-function formatARKitBlendshapesForLogging(values, threshold = 0.01, maxEntries = 20) {
-    const active = getActiveARKitBlendshapes(values, threshold)
-        .slice(0, maxEntries)
-        .reduce((acc, item) => {
-        acc[item.name] = Number(item.value.toFixed(4));
-        return acc;
-    }, {});
-    return {
-        active,
-        total: values.length,
-        activeCount: Object.keys(active).length,
-    };
-}
-/**
- * Get the most important facial features for speech
- * These are the key blendshapes for lip-sync
- */
-const KEY_LIPSYNC_BLENDSHAPES = {
-    jaw: [24], // jawOpen
-    lips: [26, 31, 37, 39, 40], // mouthClose, mouthFunnel, mouthPucker, mouthRollLower, mouthRollUpper
-    smile: [43, 44, 45, 46], // mouthSmile*, mouthStretch*
-    tongue: [51], // tongueOut
-};
-/**
- * Extract only lip-sync relevant blendshapes
- * @param values - Full blendshape array
- * @returns Object with categorized lip-sync blendshapes
- */
-function getLipSyncBlendshapes(values) {
-    return {
-        jaw: values[24] || 0,
-        mouthClose: values[26] || 0,
-        mouthFunnel: values[31] || 0,
-        mouthPucker: values[37] || 0,
-        mouthRollLower: values[39] || 0,
-        mouthRollUpper: values[40] || 0,
-        mouthSmileLeft: values[43] || 0,
-        mouthSmileRight: values[44] || 0,
-        mouthStretchLeft: values[45] || 0,
-        mouthStretchRight: values[46] || 0,
-        tongueOut: values[51] || 0,
-    };
-}
-
-/**
- * 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
- */
-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
- */
-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
- */
-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
- */
-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
- */
-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
- */
-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'],
-};
-
-/**
- * Neurosync Meta Human Blendshape Mapper
- * Maps 251 blendshape indices to their corresponding names
- * Based on Neurosync Meta Human specification
- */
-const NEUROSYNC_BLENDSHAPE_NAMES = [
-    // 0-51: ARKit Standard Blendshapes
-    "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
-    "jawRight", // 25
-    "mouthClose", // 26
-    "mouthDimpleLeft", // 27
-    "mouthDimpleRight", // 28
-    "mouthFrownLeft", // 29
-    "mouthFrownRight", // 30
-    "mouthFunnel", // 31
-    "mouthLeft", // 32
-    "mouthLowerDownLeft", // 33
-    "mouthLowerDownRight", // 34
-    "mouthPressLeft", // 35
-    "mouthPressRight", // 36
-    "mouthPucker", // 37
-    "mouthRight", // 38
-    "mouthRollLower", // 39
-    "mouthRollUpper", // 40
-    "mouthShrugLower", // 41
-    "mouthShrugUpper", // 42
-    "mouthSmileLeft", // 43
-    "mouthSmileRight", // 44
-    "mouthStretchLeft", // 45
-    "mouthStretchRight", // 46
-    "mouthUpperUpLeft", // 47
-    "mouthUpperUpRight", // 48
-    "noseSneerLeft", // 49
-    "noseSneerRight", // 50
-    "tongueOut", // 51
-    // 52-250: Meta Human Extended Blendshapes
-    "head_forward", // 52
-    "head_upDown", // 53
-    "head_tilt", // 54
-    "head_turn", // 55
-    "neck_stretch", // 56
-    "neck_tilt", // 57
-    "eyebrow_raiseInner_L", // 58
-    "eyebrow_raiseInner_R", // 59
-    "eyebrow_raiseOuter_L", // 60
-    "eyebrow_raiseOuter_R", // 61
-    "eyebrow_down_L", // 62
-    "eyebrow_down_R", // 63
-    "eye_blink_L", // 64
-    "eye_blink_R", // 65
-    "eye_wide_L", // 66
-    "eye_wide_R", // 67
-    "eye_squint_L", // 68
-    "eye_squint_R", // 69
-    "eye_look_up_L", // 70
-    "eye_look_up_R", // 71
-    "eye_look_down_L", // 72
-    "eye_look_down_R", // 73
-    "eye_look_in_L", // 74
-    "eye_look_in_R", // 75
-    "eye_look_out_L", // 76
-    "eye_look_out_R", // 77
-    "pupil_dilate_L", // 78
-    "pupil_dilate_R", // 79
-    "cheek_puff_L", // 80
-    "cheek_puff_R", // 81
-    "cheek_squint_L", // 82
-    "cheek_squint_R", // 83
-    "cheek_raiser_L", // 84
-    "cheek_raiser_R", // 85
-    "nose_wrinkle_L", // 86
-    "nose_wrinkle_R", // 87
-    "nose_nostril_raise_L", // 88
-    "nose_nostril_raise_R", // 89
-    "nose_nostril_compress_L", // 90
-    "nose_nostril_compress_R", // 91
-    "nose_nostril_dilate_L", // 92
-    "nose_nostril_dilate_R", // 93
-    "lip_upper_raise_L", // 94
-    "lip_upper_raise_R", // 95
-    "lip_upper_raiseInner_L", // 96
-    "lip_upper_raiseInner_R", // 97
-    "lip_upper_close", // 98
-    "lip_lower_close", // 99
-    "lip_lower_down_L", // 100
-    "lip_lower_down_R", // 101
-    "lip_lower_downInner_L", // 102
-    "lip_lower_downInner_R", // 103
-    "lip_corner_puller_L", // 104
-    "lip_corner_puller_R", // 105
-    "lip_corner_depressor_L", // 106
-    "lip_corner_depressor_R", // 107
-    "lip_stretcher_L", // 108
-    "lip_stretcher_R", // 109
-    "lip_funneler_LT", // 110
-    "lip_funneler_RT", // 111
-    "lip_funneler_LB", // 112
-    "lip_funneler_RB", // 113
-    "lip_pucker_L", // 114
-    "lip_pucker_R", // 115
-    "lip_press_L", // 116
-    "lip_press_R", // 117
-    "lip_tightener_L", // 118
-    "lip_tightener_R", // 119
-    "lip_suck_LT", // 120
-    "lip_suck_RT", // 121
-    "lip_suck_LB", // 122
-    "lip_suck_RB", // 123
-    "mouth_left", // 124
-    "mouth_right", // 125
-    "mouth_smile_L", // 126
-    "mouth_smile_R", // 127
-    "mouth_frown_L", // 128
-    "mouth_frown_R", // 129
-    "mouth_dimpler_L", // 130
-    "mouth_dimpler_R", // 131
-    "mouth_stretch_L", // 132
-    "mouth_stretch_R", // 133
-    "mouth_shrug_upper", // 134
-    "mouth_shrug_lower", // 135
-    "mouth_roll_upper_L", // 136
-    "mouth_roll_upper_R", // 137
-    "mouth_roll_lower_L", // 138
-    "mouth_roll_lower_R", // 139
-    "jaw_open", // 140
-    "jaw_forward", // 141
-    "jaw_left", // 142
-    "jaw_right", // 143
-    "jaw_clench", // 144
-    "jaw_thrust", // 145
-    "tongue_out", // 146
-    "tongue_up", // 147
-    "tongue_down", // 148
-    "tongue_wide", // 149
-    "tongue_narrow", // 150
-    "tongue_curl_up", // 151
-    "tongue_roll", // 152
-    "tongue_bulge_L", // 153
-    "tongue_bulge_R", // 154
-    "tongue_press", // 155
-    "midLipLowerDown_L", // 156
-    "midLipLowerDown_R", // 157
-    "midLipUpperUp_L", // 158
-    "midLipUpperUp_R", // 159
-    "midNostrilSharpener_L", // 160
-    "midNostrilSharpener_R", // 161
-    "viseme_sil", // 162
-    "viseme_PP", // 163
-    "viseme_FF", // 164
-    "viseme_TH", // 165
-    "viseme_DD", // 166
-    "viseme_kk", // 167
-    "viseme_CH", // 168
-    "viseme_SS", // 169
-    "viseme_nn", // 170
-    "viseme_RR", // 171
-    "viseme_aa", // 172
-    "viseme_E", // 173
-    "viseme_I", // 174
-    "viseme_O", // 175
-    "viseme_U", // 176
-    "lid_tightener_L", // 177
-    "lid_tightener_R", // 178
-    "eyelid_upper_raise_L", // 179
-    "eyelid_upper_raise_R", // 180
-    "eyelid_lower_down_L", // 181
-    "eyelid_lower_down_R", // 182
-    "eye_parallel_look_down", // 183
-    "eye_parallel_look_up", // 184
-    "innerBrow_raiser_L", // 185
-    "innerBrow_raiser_R", // 186
-    "outerBrow_raiser_L", // 187
-    "outerBrow_raiser_R", // 188
-    "lipCorner_down_L", // 189
-    "lipCorner_down_R", // 190
-    "lipCorner_wide_L", // 191
-    "lipCorner_wide_R", // 192
-    "lipLower_down_L", // 193
-    "lipLower_down_R", // 194
-    "lipUpper_up_L", // 195
-    "lipUpper_up_R", // 196
-    "wrinkler", // 197
-    "chin_raiser", // 198
-    "chin_raiser_T", // 199
-    "chin_raiser_B", // 200
-    "lips_toward", // 201
-    "lips_blow", // 202
-    "puff_suck_lower", // 203
-    "puff_suck_upper", // 204
-    "puff_suck_upper_L", // 205
-    "puff_suck_upper_R", // 206
-    "puff_suck_lower_L", // 207
-    "puff_suck_lower_R", // 208
-    "phone_aa", // 209
-    "phone_ow", // 210
-    "phone_ee", // 211
-    "phone_er", // 212
-    "phone_uw", // 213
-    "phone_l", // 214
-    "phone_w", // 215
-    "phone_m", // 216
-    "phone_f", // 217
-    "phone_th", // 218
-    "phone_s", // 219
-    "phone_sh", // 220
-    "phone_t", // 221
-    "phone_k", // 222
-    "phone_b", // 223
-    "phone_d", // 224
-    "phone_g", // 225
-    "phone_n", // 226
-    "phone_r", // 227
-    "phone_y", // 228
-    "expression_neutral", // 229
-    "expression_happy", // 230
-    "expression_sad", // 231
-    "expression_angry", // 232
-    "expression_surprised", // 233
-    "expression_disgusted", // 234
-    "expression_afraid", // 235
-    "expression_contempt", // 236
-    "occlusion_upper", // 237
-    "occlusion_lower", // 238
-    "teeth_upper", // 239
-    "teeth_lower", // 240
-    "teeth_fwdBack_upper", // 241
-    "teeth_fwdBack_lower", // 242
-    "teeth_width_upper", // 243
-    "teeth_width_lower", // 244
-    "gums_upper", // 245
-    "gums_lower", // 246
-    "tongue_tip", // 247
-    "tongue_thickness", // 248
-    "soft_palate", // 249
-    "emotion_intensity", // 250
-];
-/**
- * Maps blendshape values to their names
- */
-function mapBlendshapesToNames(values) {
-    const mapped = {};
-    values.forEach((value, index) => {
-        if (index < NEUROSYNC_BLENDSHAPE_NAMES.length) {
-            const name = NEUROSYNC_BLENDSHAPE_NAMES[index];
-            mapped[name] = value;
-        }
-        else {
-            // Handle any indices beyond our known names
-            mapped[`unknown_${index}`] = value;
-        }
-    });
-    return mapped;
-}
-/**
- * Formats blendshapes for logging with filtering
- * @param values - Array of 251 blendshape values
- * @param threshold - Only log values above this threshold (default: 0.01)
- * @param maxEntries - Maximum number of entries to log (default: 20)
- */
-function formatBlendshapesForLogging(values, threshold = 0.01, maxEntries = 20) {
-    const mapped = mapBlendshapesToNames(values);
-    // Filter values above threshold and sort by value (descending)
-    const activeBlendshapes = Object.entries(mapped)
-        .filter(([_, value]) => Math.abs(value) > threshold)
-        .sort(([, a], [, b]) => Math.abs(b) - Math.abs(a))
-        .slice(0, maxEntries)
-        .reduce((acc, [name, value]) => {
-        acc[name] = Number(value.toFixed(4));
-        return acc;
-    }, {});
-    return {
-        active: activeBlendshapes,
-        total: values.length,
-        activeCount: Object.keys(activeBlendshapes).length,
-    };
-}
-/**
- * Gets the most significant blendshapes
- */
-function getTopBlendshapes(values, count = 10) {
-    return values
-        .map((value, index) => ({
-        name: NEUROSYNC_BLENDSHAPE_NAMES[index] || `unknown_${index}`,
-        value,
-        index,
-    }))
-        .filter((item) => Math.abs(item.value) > 0.001)
-        .sort((a, b) => Math.abs(b.value) - Math.abs(a.value))
-        .slice(0, count);
-}
-
-exports.ARKIT_BLENDSHAPE_INDICES = ARKIT_BLENDSHAPE_INDICES;
-exports.ARKIT_BLENDSHAPE_NAMES = ARKIT_BLENDSHAPE_NAMES;
-exports.ARKIT_EXTENDED_NAMES = ARKIT_EXTENDED_NAMES;
-exports.ARKIT_ORDER_61 = ARKIT_ORDER_61;
-exports.ARKIT_PHONEME_REFERENCE_VALUES = ARKIT_PHONEME_REFERENCE_VALUES;
-exports.BLENDSHAPE_QUICK_GUIDE = BLENDSHAPE_QUICK_GUIDE;
-exports.KEY_LIPSYNC_BLENDSHAPES = KEY_LIPSYNC_BLENDSHAPES;
-exports.NEUROSYNC_BLENDSHAPE_NAMES = NEUROSYNC_BLENDSHAPE_NAMES;
-exports.SAMPLE_PHONEME_TESTS = SAMPLE_PHONEME_TESTS;
-exports.STANDARD_ARKIT_ORDER = STANDARD_ARKIT_ORDER;
-exports.convertOrder61ToStandard = convertOrder61ToStandard;
-exports.formatARKitBlendshapesForLogging = formatARKitBlendshapesForLogging;
-exports.formatBlendshapesForLogging = formatBlendshapesForLogging;
-exports.formatOrder61ForLogging = formatOrder61ForLogging;
-exports.generatePhonemeBlendshapes = generatePhonemeBlendshapes;
-exports.getARKitBlendshapeValue = getARKitBlendshapeValue;
-exports.getActiveARKitBlendshapes = getActiveARKitBlendshapes;
-exports.getActiveBlendshapesFromOrder61 = getActiveBlendshapesFromOrder61;
-exports.getBlendshapeValueFromOrder61 = getBlendshapeValueFromOrder61;
-exports.getEyeRotations = getEyeRotations;
-exports.getHeadRotation = getHeadRotation;
-exports.getLipSyncBlendshapes = getLipSyncBlendshapes;
-exports.getLipSyncValuesFromOrder61 = getLipSyncValuesFromOrder61;
-exports.getPhonemeDescription = getPhonemeDescription;
-exports.getTopBlendshapes = getTopBlendshapes;
-exports.mapARKitBlendshapesToNames = mapARKitBlendshapesToNames;
-exports.mapBlendshapesToNames = mapBlendshapesToNames;
-exports.mapOrder61ToNames = mapOrder61ToNames;